B Beaver Agent Sandbox产品 PRD · 模块路线图 · 测试场景
Product Requirement Document

Beaver：从聊天到可验收工作的产品 PRD

这页把 Beaver 当前代码里的能力，整理成产品团队、研发团队、测试团队都能对齐的 PRD。重点不是列功能，而是说明每个模块为什么要做、要做成什么样、怎么验收。

看模块拆解 看测试场景 看代码依据
Create PRD

产品 PRD

按 create-prd 的 8 段结构组织：摘要、联系人、背景、目标、市场、价值主张、方案、发布范围。

1. Summary

一句话定义

Beaver 是一个可私有部署的企业 Agent 工作台。它把普通聊天升级为可追踪任务，让用户能上传文件、调用工具、查看证据、验收结果，并把成功过程沉淀为技能和记忆。

2. Contacts

关键角色

  • 产品负责人：定义首批场景、验收指标和模块优先级。
  • 工程负责人：保证实例、任务、工具、技能和连接器架构可落地。
  • 设计负责人：保证工作台、任务详情、技能审核和配置体验可理解。
  • 运维负责人：保证部署、路由、日志、备份和故障恢复可执行。
  • 安全负责人：定义工具、连接器、文件、记忆和技能发布边界。
3. Background

为什么现在做

企业已经从“试一下 AI 聊天”进入“让 AI 完成真实工作”的阶段。真实工作需要任务状态、文件、工具、证据、验收、复盘和可复用经验。Beaver 当前代码已经具备 Chat、Task、Files、Skills、MCP、Cron、Agents、Connectors、Status、Logs 等基础产品面，可以进入产品化梳理。

4. Objective

产品目标

让试点团队在私有实例中完成可验收、可追踪、可复用的 Agent 工作，并让运营者能控制模型、工具、连接器和实例状态。

  • 首个用户会话内完成一次可验收任务。
  • 30 天内形成 30 个被接受的任务结果。
  • 核心任务 90% 具备可读证据。
  • 至少 5 个技能候选进入草稿，至少 3 个技能被复用。
5. Market Segments

目标用户

第一批不是泛用户，而是有重复知识工作、文件输入、工具调用、结果验收和流程复用需求的团队。

  • 项目交付团队：报告、纪要、跟进、复盘。
  • 运营团队：周期汇总、监控、通知、异常处理。
  • 技术支持团队：排查、日志、知识库、回复草稿。
  • AI 平台团队：私有部署、工具治理、技能沉淀。
6. Value Props

价值主张

  • 给终端用户：少反复解释，能看到任务进度和结果证据。
  • 给团队负责人：知道 AI 交付是否可靠，能沉淀好的方法。
  • 给平台管理员：模型、工具、连接器、实例状态都可管理。
  • 给安全负责人：高风险动作可以通过策略、证据和审核控制。
7. Solution

方案结构

产品由 8 个模块组成：控制面与实例、Chat/Task、文件产物、工具/MCP、技能学习、Agent Team、连接器/计划任务、运营治理。它们共同服务同一条闭环：请求、执行、证据、验收、复用。

Outcome Roadmap

模块路线图：先说明需要什么模块

按 outcome-roadmap 的方式，把“要做的功能”改写成“用户和业务要达成的结果”。

阶段 模块 当前代码依据 Outcome Statement 关键指标 依赖
Phase 1
完成核心闭环		 控制面与实例 auth-portal、authz-service、deploy-control、router-proxy、app-instance 让试点用户可以稳定进入自己的私有 Beaver 实例，从而减少环境配置和部署阻塞。 新实例可用率、部署耗时、登录成功率、配置恢复率 Docker、路由、实例健康检查、Provider 配置
Phase 1
完成核心闭环		 Chat/Task 工作台 /、/tasks、/tasks/[taskId]、AgentService、TaskService 让用户能把一次自然语言请求推进到可验收任务，从而证明 Beaver 不是聊天框，而是工作系统。 首个可验收任务耗时、任务完成率、接受率、修订次数 WebSocket、任务分类、时间线、反馈与验收
Phase 1
完成核心闭环		 文件与产物 /files、UserFileService、workspace APIs、文件工具 让用户和 Agent 能围绕同一份文件工作，从而让任务结果有上下文、有产物、可下载。 上传成功率、预览成功率、任务引用文件比例、文件错误率 文件存储、路径安全、预览、下载、删除
Phase 2
增强执行能力		 工具与 MCP /mcp、ToolRegistry、MCPConnectionManager、/api/mcp/tools 让管理员能接入、测试和治理工具，从而让 Agent 可以完成真实系统动作。 工具测试成功率、工具调用证据覆盖率、失败可诊断率 MCP server 配置、AuthZ scopes、工具策略
Phase 2
增强复用能力		 技能学习与市场 /skills、/marketplace、SkillLearningWorker、候选/草稿/审核/发布 API 让被接受的好任务变成可复用技能，从而降低重复任务成本并形成团队能力库。 候选数、草稿通过率、发布数、复用次数、回滚次数 运行记忆、安全检查、评测报告、人审流程
Phase 2
增强复杂任务		 Agent Team /agents、coordinator、ExecutionGraph、TaskExecutionPlanner 让复杂任务可以拆分给多个子 Agent 执行，从而提升多步骤工作质量和可解释性。 复杂任务完成率、子任务失败可见率、最终合成满意度 计划器、子 Agent 配置、执行图、证据汇总
Phase 3
主动工作		 连接器、渠道、计划任务 /outlook、/notifications、/cron、ChannelRuntime、CronService 让 Beaver 能在合适时间或外部事件触发工作，从而从被动问答变成主动运营助手。 计划任务成功率、通知参与率、连接器恢复率、外部动作误触发数 渠道配置、连接器凭证、去重、回调路由、外部写入策略
Phase 3
上线治理		 设置、状态、日志、运维 /settings、/status、/logs、/api/status、/api/runtime/restart 让管理员能发现并恢复模型、工具、渠道和运行时问题，从而降低试点支持成本。 故障定位时间、配置成功率、重启成功率、日志可用率 Provider 配置、通道配置、健康检查、日志投影
Job Stories + WWA

模块怎么做，以及为什么这么做

每个模块用 Job Story 说明用户情境，用 WWA 说明 Why / What / Acceptance，用测试场景说明怎么验收。

模块 01

控制面与私有实例

覆盖注册、登录、实例创建、Provider 配置、路由、实例健康。现有代码和部署结构包括 auth portal、authz service、deploy-control、router-proxy、app-instance。

核心页面：登录、注册、handoff、状态 核心接口：/api/auth/*、/api/status 关键风险：实例不可达、配置错误、控制面暴露

Job Story

当我第一次试用 Beaver 时，我想注册后直接进入自己的工作实例，所以我能在不理解底层部署的情况下开始第一项 Agent 工作。

WWA

Why：私有实例是 Beaver 的信任基础。用户必须先进入稳定、隔离、可恢复的环境。

What：提供注册、登录、handoff、Provider 配置、实例状态展示和失败恢复提示。

  • 用户能完成注册并进入实例。
  • Provider 未配置时有清晰提示。
  • 实例健康状态能被用户或管理员看到。
  • 控制面服务不作为公共产品入口暴露。

测试场景

  • 新用户注册后得到 token 和 handoff URL。
  • 实例没有 Provider 时，发送任务前出现可理解错误。
  • 访问 /api/ping 和 /api/status 返回健康数据。
  • 错误 token 访问受保护接口返回 401。
模块 02

Chat / Task 工作台

这是产品主线：用户发起请求，系统判断是否进入任务模式，Agent 执行，用户查看时间线、证据、产物，并选择接受、修订或放弃。

核心页面：/、/tasks、/tasks/[taskId] 核心服务：AgentService、TaskService 关键测试：active task、websocket、task feedback

Job Story

当我给 Agent 一个需要持续完成的工作时，我想看到它变成一个有状态的任务，所以我能知道它做到哪一步、产出了什么、是否值得接受。

WWA

Why：聊天只能回答，任务才能交付。Beaver 必须把“会话”升级为“工作单”。

What：支持发送消息和附件、任务识别、实时进度、任务列表、任务详情、验收与修订。

  • 任务可从聊天、列表、详情页互相跳转。
  • 用户能接受、要求修订或放弃结果。
  • 修订保留原任务上下文。
  • 任务状态和时间线在桌面和移动端可读。

测试场景

  • 发送任务型请求后创建 active task。
  • WebSocket 推送思考、工具、产物和完成事件。
  • 点击接受后任务状态持久化。
  • 输入修订意见后同一任务追加新 run。
模块 03

文件与产物工作区

支持用户上传、浏览、预览、下载、删除文件，也支持 Agent 在受控工作区中读取和生成产物。

核心页面：/files 核心服务：UserFileService、workspace files API 关键测试：user file service、web files API、filesystem tools

Job Story

当我的任务依赖文档、图片或数据文件时，我想把文件放进 Beaver，并在结果里看到它如何被使用，所以我能信任任务产出。

WWA

Why：企业知识工作通常围绕文件展开。没有文件边界，Agent 工作就难以落地。

What：提供目录、上传、预览、下载、删除和新建文件夹能力；Agent 工具只能在允许路径内操作。

  • 根目录和多级目录可浏览。
  • Markdown、文本、图片可预览。
  • 上传失败有可理解错误。
  • 非法路径不能逃逸工作区。

测试场景

  • 上传文件后列表立即出现。
  • 打开 Markdown 文件显示预览。
  • 下载文件内容与上传内容一致。
  • 删除目录或文件后刷新仍不存在。
  • 路径穿越请求被拒绝。
模块 04

工具与 MCP 管理

Beaver 通过内置工具和 MCP 工具让 Agent 具备真实动作能力。产品上需要让管理员看懂工具来源、连接状态、权限和测试结果。

核心页面：/mcp 核心接口：/api/mcp/servers、/api/mcp/tools 关键测试：marketplace and mcp、mcp tools server、tool assembler

Job Story

当我准备让 Agent 调用外部工具时，我想先测试连接并看清权限范围，所以我能避免把不可靠或高风险工具交给 Agent。

WWA

Why：工具是 Agent 的行动边界，也是最大的安全风险。

What：支持 MCP server 的新增、编辑、删除、测试、工具发现、AuthZ scope 预览和本地/远程分类。

  • 管理员能添加 stdio 或 remote server。
  • 测试失败返回具体原因。
  • 工具列表显示 server 来源。
  • 需要授权的工具显示权限预览。

测试场景

  • 新增 server 后出现在 MCP 列表。
  • 测试可用 server 返回 ok。
  • 删除 server 后工具列表同步减少。
  • 无效 JSON 配置在前端被拦截。
模块 05

技能学习、审核与市场

Beaver 的复用壁垒来自技能。已接受任务可以形成候选，候选生成草稿，草稿经过安全、评测、人审后发布，后续任务再调用。

核心页面：/skills、/marketplace 核心服务：SkillLearningWorker、SkillSpecStore 关键测试：skill learning pipeline、safety、eval、web api

Job Story

当一个任务结果被证明有用时，我想把它转成可审核的技能，所以团队以后不用从零开始重复同样方法。

WWA

Why：没有技能复用，Beaver 只是一次性执行工具；有技能复用，Beaver 才能积累团队能力。

What：提供已发布技能、候选、草稿、安全报告、评测报告、提交、批准、拒绝、发布、禁用、回滚、上传和市场安装。

  • 候选能基于运行证据生成。
  • 高风险草稿不能直接发布。
  • 发布需要人审状态。
  • 技能版本可查看、下载、回滚。

测试场景

  • 运行学习任务后产生候选或明确说明无候选。
  • 候选生成草稿后出现在草稿区。
  • 安全检查失败时提交按钮不可用。
  • 批准并发布后技能进入已发布列表。
  • 回滚后当前版本发生变化。
模块 06

Agent Team 与复杂任务执行

复杂任务需要拆分为 sequence、parallel 或 DAG。Beaver 当前有 coordinator、planner、registry、execution graph 和 subagent 管理能力。

核心页面：/agents 核心模块：coordinator、TaskExecutionPlanner 关键测试：agent team、task execution planner、agent registry resolver

Job Story

当一个任务需要调研、分析、生成和审核多步协作时，我想让 Beaver 自动拆分并展示每个子任务结果，所以我能判断最终答案是否可靠。

WWA

Why：复杂工作无法靠单轮问答稳定完成。多 Agent 执行能提高分工质量，但必须可解释。

What：支持 agent/subagent 管理、任务计划、执行图、子任务结果、失败状态和最终合成。

  • 管理员能创建和编辑本地 subagent。
  • 任务可生成可读执行计划。
  • 子任务失败不会丢失部分证据。
  • 最终答案能引用或总结子任务输出。

测试场景

  • 创建 subagent 后刷新仍存在。
  • 复杂任务生成 sequence/parallel/DAG 计划。
  • 某节点失败时任务时间线显示失败节点。
  • 最终合成包含子任务摘要。
模块 07

连接器、渠道、计划任务与通知

这一组能力让 Beaver 从“用户问了才做”变成“到时间或有外部事件时主动做”。现有页面覆盖 Outlook、Status 渠道配置、Notifications、Cron。

核心页面：/outlook、/notifications、/tasks?tab=scheduled 核心服务：CronService、ChannelRuntime 关键测试：cron service、channel runtime、connector APIs

Job Story

当我有固定周期的汇总或外部消息触发的工作时，我想让 Beaver 自动运行并通知我审核，所以我不用每天手动发起同样任务。

WWA

Why：企业工作有大量周期任务和外部事件。主动触发是 Agent 从助手变成运营系统的关键。

What：支持计划任务创建、开关、删除、立即运行，通知列表和详情，Outlook 连接、邮箱、日历、消息详情，渠道连接和验证。

  • 计划任务可以被暂停和恢复。
  • 计划输出可以进入正常任务验收流。
  • 连接器失败显示可恢复错误。
  • 外部写入必须受策略控制。

测试场景

  • 创建 every/cron/at 三类计划任务。
  • 点击 run now 产生一次 scheduled run。
  • 通知详情页能 engage 到任务上下文。
  • Outlook 配置测试失败时显示错误。
  • 重复外部消息被 dedupe store 去重。
模块 08

设置、状态、日志与运维治理

上线前必须让运营者知道系统是不是健康、模型是否可用、渠道是否正常、日志是否能解释问题，并能安全重启运行时。

核心页面：/settings、/status、/logs 核心接口：/api/status、/api/runtime/restart 关键测试：config loader、debug chat logs、process projection

Job Story

当 Agent 任务失败或连接器不可用时，我想快速看到配置、运行状态和日志，所以我能恢复服务而不是猜问题在哪里。

WWA

Why：私有部署产品的体验不只在用户界面，也在故障恢复速度。

What：提供 Provider 配置、Agent 参数、渠道配置、连接器状态、运行时重启、系统状态、聊天日志、事件投影。

  • Provider 保存后状态刷新。
  • 运行时重启需要确认。
  • 日志能按 session/run 展开。
  • 错误状态能给出下一步处理提示。

测试场景

  • 保存 Provider 配置后 /api/status 反映新状态。
  • 重启按钮触发 /api/runtime/restart 并显示进行中。
  • 日志页展示最近 run 和事件。
  • 长配置值不撑破页面。
Test Scenarios

测试矩阵：每个模块怎么证明满足需求

这里按 test-scenarios 的结构组织：测试目标、初始条件、用户角色、动作、预期结果。

模块 测试目标 初始条件 用户角色 关键步骤 预期结果 现有测试依据
控制面与实例 验证用户能进入私有实例并看到健康状态。 部署完成；实例容器运行；无或有 Provider 配置。 新用户、管理员 注册、登录、consume handoff、打开 status、调用 ping。 登录成功；错误 token 被拒绝；Provider 缺失时提示清楚；健康接口返回正常。 test_config_loader.py、web auth routes
Chat/Task 验证用户请求能转为可验收任务。 用户已登录；Provider 可用；WebSocket 可连接。 普通用户 发送任务请求、等待 run、打开任务详情、接受或修订。 任务生成；时间线有事件；接受状态持久化；修订继续同一任务。 test_active_task_api.py、test_task_mode_feedback.py、test_websocket_chat.py
文件与产物 验证用户文件能安全进入工作区并被预览。 用户已登录；工作区为空或有样例文件。 普通用户、Agent 上传、浏览、预览、下载、删除、尝试非法路径。 文件操作成功；内容一致；非法路径失败；二进制/大文件有保护。 test_user_file_service.py、test_web_files_api.py、test_filesystem_tools.py
工具与 MCP 验证工具接入可配置、可测试、可发现。 至少一个本地或远程 MCP server 配置。 管理员 新增 server、测试连接、查看工具、编辑、删除。 server 状态正确；工具列表更新；失败原因可读；AuthZ 预览正确。 test_marketplace_and_mcp.py、test_mcp_tools_server.py、test_tool_assembler.py
技能学习 验证接受任务能进入技能学习闭环。 有已接受 run；skill learning worker 可运行。 技能维护者 运行学习、查看候选、生成草稿、安全检查、提交、批准、发布、回滚。 候选有证据；草稿有报告；高风险被阻断；发布后可被后续任务选择。 test_skill_learning_pipeline.py、test_skill_learning_safety.py、test_skill_learning_web_api.py
Agent Team 验证复杂任务能被拆分执行并保留证据。 配置至少一个 subagent；任务需要多步骤处理。 高级用户、管理员 创建 subagent、发起复杂任务、查看节点结果、模拟节点失败。 执行图可读；子任务结果可见；失败节点不隐藏；最终答案可解释。 test_agent_team_v1.py、test_task_execution_planner.py
连接器与计划任务 验证主动任务可以创建、触发、通知和进入验收。 Cron 服务运行；连接器配置可用或模拟可用。 运营用户、管理员 创建计划任务、立即运行、查看通知、engage 通知、测试 Outlook 或渠道连接。 计划 run 被记录；通知可打开；engage 后进入任务流；失败连接器可恢复。 test_cron_service.py、test_channel_runtime.py、test_channel_connection_api.py
设置、状态、日志 验证管理员能定位和恢复运行问题。 存在至少一次聊天 run；Provider 和 channel 配置可编辑。 管理员、支持人员 修改配置、刷新状态、查看日志、重启运行时。 配置保存成功；状态反映变化；日志按 run 展开；重启有确认和结果反馈。 test_debug_chat_logs_api.py、test_process_projection.py
Release

发布范围：先完成产品需要的模块

这里不是精确排期，而是定义从产品完整性角度必须完成的版本边界。

MVP

可演示闭环

  • 登录进入实例。
  • Chat 变成 Task。
  • 文件上传和预览。
  • 任务详情、证据、接受、修订。
  • 状态和日志可看。
Pilot

可试点闭环

  • 工具/MCP 可接入和测试。
  • 技能候选、草稿、安全、评测、审核、发布。
  • Agent Team 可解释。
  • 计划任务和通知可用。
  • 部署和恢复文档完整。
Governance

可治理闭环

  • 工具策略分级。
  • 外部写入控制。
  • 技能质量指标。
  • 记忆可查看、编辑、冻结、删除。
  • 审计导出。
Scale

可规模化闭环

  • 实例备份和恢复。
  • 多团队工作区。
  • 更多连接器。
  • 跨实例指标。
  • 运维自动化。
Code Evidence

代码依据

本页不是纯产品想象，模块来自当前仓库已存在的前端页面、后端接口、服务模块和测试文件。

前端页面

  • app-instance/frontend/app/(app)/page.tsx：Chat 工作台。
  • app-instance/frontend/app/(app)/tasks：任务列表和详情。
  • app-instance/frontend/app/(app)/files：文件工作区。
  • app-instance/frontend/app/(app)/skills、/marketplace：技能和市场。
  • app-instance/frontend/app/(app)/mcp：MCP 工具管理。
  • app-instance/frontend/app/(app)/agents：Agent 和 Subagent。
  • app-instance/frontend/app/(app)/outlook、/notifications：连接器与通知。
  • app-instance/frontend/app/(app)/status、/logs：配置、状态、日志。

后端模块

  • beaver.services.agent_service：Agent 执行、任务模式、验收、计划任务。
  • beaver.tasks：任务记录、事件、证据、计划。
  • beaver.skills、beaver.memory.skills：技能装载、候选、草稿、审核、发布。
  • beaver.tools、beaver.integrations.mcp：工具和 MCP。
  • beaver.coordinator：多 Agent 执行。
  • beaver.services.user_files：用户文件存储。
  • beaver.services.cron_service：计划任务。
  • beaver.interfaces.channels、beaver.integrations.outlook：渠道和连接器。
产品模块 核心 API / 路由 测试文件线索
Chat/Task/api/sessions、/api/tasks、/ws/{session_id}test_active_task_api.py、test_task_mode_feedback.py、test_websocket_chat.py
Files/api/user-files/*、/api/workspace/*、/api/files/*test_user_file_service.py、test_web_files_api.py
Skills/api/skills、/api/skills/candidates、/api/skills/draftstest_skill_learning_pipeline.py、test_skill_learning_web_api.py
MCP/Tools/api/mcp/servers、/api/mcp/toolstest_marketplace_and_mcp.py、test_mcp_tools_server.py
Agents/api/agents、/api/subagentstest_agent_team_v1.py、test_agent_registry_resolver.py
Cron/Notifications/api/cron/jobs、/api/notificationstest_cron_service.py
Connectors/api/channel-connections、/api/integrations/outlook/*test_channel_connection_api.py、test_external_connector_bridge_api.py
Operations/api/status、/api/runtime/restart、/api/debug/chat-logstest_debug_chat_logs_api.py、test_process_projection.py