Product Requirement Document

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

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

看模块拆解 看测试场景 看代码依据
产品主线任务从请求到验收
用户价值证据知道 Agent 做了什么
增长杠杆技能把好方法复用
上线前提治理私有实例和可控工具
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/drafts` | `test_skill_learning_pipeline.py`、`test_skill_learning_web_api.py`
MCP/Tools | `/api/mcp/servers`、`/api/mcp/tools` | `test_marketplace_and_mcp.py`、`test_mcp_tools_server.py`
Agents | `/api/agents`、`/api/subagents` | `test_agent_team_v1.py`、`test_agent_registry_resolver.py`
Cron/Notifications | `/api/cron/jobs`、`/api/notifications` | `test_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-logs` | `test_debug_chat_logs_api.py`、`test_process_projection.py`