feat(beaver): 完成Task Team功能v1实现，重构后端架构支持统一内核

新增内部Task系统，包括验证、反馈门控机制，实现自动质量验证 (通过率>=0.75)和用户反馈闭环(satisfied/revise/abandon)。实现Agent Team v1协调器，支持sequence/parallel/dag执行策略， sub-agent复用主AgentLoop，每个run使用独立memory snapshot。建立Skill学习pipeline，包含draft/审核/发布/回滚完整生命周期，通过Task验证通过且用户满意才生成学习候选。重构目录结构，移除third_party依赖，建立统一engine内核，所有agent共享运行时基础组件。更新ContextBuilder清理provider消息字段，增强SkillContext版本管理，集成TaskExecutionPlanner和TaskSkillResolver实现技能解析机制。
2026-05-08 17:14:14 +08:00
parent 5ba5c7e4c1
commit 8a12c30141
93 changed files with 16724 additions and 1247 deletions
--- a/app-instance/backend/change.md
+++ b/app-instance/backend/change.md
@ -12,6 +12,25 @@
 2. `nanobot` 只作为迁移期遗留路径存在，最终应逐步退出目录、模块和文档命名。
 3. 新增目录、新增模块、新增文档都应优先使用 `beaver` 命名，而不是继续扩散 `nanobot`。

+## 文档分工
+
+三份核心文档从现在开始按下面的边界维护：
+
+1. `flow.md`
+   - 只保留树形运行结构
+   - 只描述“运行时怎么连起来”
+   - 不再承载蓝图解释、阶段判断、参考项目分析
+2. `施工指南.md`
+   - 保留施工顺序、阶段边界、完成标准、落地步骤
+3. `change.md`
+   - 保留长期蓝图、设计动机、参考项目借鉴边界、架构取舍
+
+这样做的目的很简单：
+
+1. `flow.md` 必须像运行时接线图，而不是混合说明文
+2. 施工时看 `施工指南.md`
+3. 讨论为什么这样设计时看 `change.md`
+
 ## 1. 这次重构到底要解决什么

 当前后端已经不是“功能不够”，而是“能力已经长出来了，但结构还停留在早期阶段”。
@ -29,6 +48,60 @@

 所以这次重构不是简单“整理目录”，而是把项目从“围绕一个 CLI 主 agent 生长出来的系统”升级成“所有 agent 共享同一内核的自有 agent harness 平台”。

+### 1.1 当前落地状态（2026-05-07）
+
+截至当前实现，新 `app-instance/backend/beaver` 已经把主链推进到：
+
+1. Main Agent 自动 Task 化与反馈门控。
+   - 简单问题直接走 `AgentLoop` 单轮回答。
+   - 复杂任务自动进入内部 Task。
+   - 产品面仍只暴露聊天入口，不暴露显式 Task 创建/管理 API。
+2. skill 生命周期与学习闭环第一层。
+   - runtime 记录 `SkillActivationReceipt / RunRecord / SkillEffectRecord`。
+   - Task run 自动验证并失败重试一次。
+   - learning candidates 默认不在 run 完成时生成。
+   - 只有“自动验证通过 + 用户满意反馈”才生成成功学习候选。
+   - `abandon` 写 Failure Memory，不生成成功 Skill draft。
+3. Agent Team v1 轻量 coordinator。
+   - 已有 Beaver 自己的 `AgentDescriptor / DelegationEnvelope / ExecutionNode / ExecutionGraph / TeamRunResult`。
+   - `TeamService.run_team(...)` 是内部服务入口，不新增产品级 Task API。
+   - `LocalAgentRunner` 让 sub-agent 复用主 `AgentLoop.process_direct()` / `submit_direct()`。
+   - 已支持 `sequence / parallel / dag`。
+   - `parallel` 和 DAG 同层节点保持真并发。
+   - 每个 run 使用独立 memory snapshot，避免并发 prompt 串记忆。
+   - 支持 pinned skill 继承、open skill assembly、per-node provider factory。
+   - sub-agent run 归入父 Task，失败节点归一成 `NodeRunResult`。
+4. Agent Team 已融入 Task mode 内部执行策略。
+   - `TaskExecutionPlanner` 先用 LLM JSON 规划 `single / team`。
+   - team node 只声明 `skill_query / required_capabilities`，不声明固定 specialist 人设。
+   - `TaskSkillResolver` 为每个 generic sub-agent 选择 published skill；未命中时生成 draft-only skill，并作为本次 run 的 ephemeral pinned instruction 使用。
+   - team 模式调用 `TeamService.run_team(...)` 产生 sub-agent runs。
+   - Team 输出只作为主 Agent synthesis run 的内部上下文。
+   - 用户可见最终回答仍由主 Agent 生成，并继续走验证、反馈和学习门控。
+   - planner 失败或 graph 非法时降级 `single`。
+
+当前仍未落地的部分：
+
+1. Agent Team 不暴露产品级聊天路由或显式 Task API；当前作为 Task 内部 sub-agent 执行策略。
+2. `moa / hierarchy / heavy / group_chat / forest / maker / router` 仍是策略预留，不是 v1 完整行为。
+3. 自动验证目前是 LLM validator，不是 replay sandbox。
+4. Skill draft synthesis / review / publish 安全链已有基础服务，但还没有做成完整后台学习 pipeline。
+5. `/api/agents` 和 agent registry 可作为未来外部 agent/A2A 管理面保留，但不参与 Task sub-agent 选择。
+6. 不允许在线直接改 published skill，这条约束保持不变。
+
+### 1.2 参考项目核对说明
+
+这版蓝图不是只根据印象在写。`2026-05-06` 我们已经重新核对过下面三个参考项目的公开入口文档：
+
+1. `OpenHarness`
+   - <https://github.com/HKUDS/OpenHarness>
+2. `hermes-agent`
+   - <https://github.com/NousResearch/hermes-agent>
+3. `swarms`
+   - <https://github.com/kyegomez/swarms>
+
+这一步的目的不是“照着抄目录”，而是把“到底借什么、不借什么”明确写死，避免后续施工时又把第三方项目的实现细节直接揉回 Beaver。
+
 ## 2. 我是怎么想的

 我的核心判断是：我们不能继续把第三方库、业务流程、执行控制、UI/API 接口揉在一起，而是应该先定义我们自己的稳定边界，再让第三方能力挂进来。
@ -40,6 +113,21 @@
 3. 用 `OpenHarness` 的强项来解决“工程边界、模块职责、可维护性”。
 4. 最终收口成我们自己的抽象和目录，而不是长期让第三方结构反向塑造我们。

+这里把三者的借鉴边界再说得更具体一点：
+
+1. `OpenHarness`
+   - 借它的 harness 分层方式：`engine / tools / skills / permissions / memory / coordinator / prompts / config`
+   - 借它“一条统一 loop + 明确 tool registry / permission / hook 边界”的工程组织方式
+   - 不直接照搬它的 CLI/TUI、commands、plugin 生态，也不要求 Beaver 长成它的目录镜像
+2. `hermes-agent`
+   - 借它的 memory / session / session_search / skills 运行时关系
+   - 借它对 FTS5 transcript 搜索、长期记忆、显式 skill 注入、session lineage 的处理方向
+   - 不把“自动学习闭环、完整渠道网关、全部终端后端、Honcho 用户建模”当成当前阶段必须同步迁入的范围
+3. `swarms`
+   - 借它已经验证过的多智能体执行形态，例如 sequential / hierarchy / rearrange / router 这类 orchestration 结构
+   - 借它作为 team execution backend 的角色，而不是借它来定义 Beaver 的主 runtime、session、tool、provider 契约
+   - 不再允许 Beaver 上层直接感知 `third_party/swarms`、`SwarmRouter` 参数细节或 import 副作用
+
 这意味着后续所有设计都应遵守四条原则：

 ### 2.1 我们要有自己的抽象
@ -296,9 +384,9 @@

 ## 4.2 彻底去掉 `third_party/`，把 `swarms` 改造成可替换 backend

-### 当前状态
+### 旧实现状态

-现在的 `agent_team` 已经接通：
+旧 `agent_team` 曾经接通：

 - `GroupChat`
 - `SequentialWorkflow`
@ -307,13 +395,41 @@
 - `MixtureOfAgents`
 - `HierarchicalSwarm`

-但这些能力还不是“平台正式能力集合”，而是“当前 bridge 恰好能跑通的一部分 swarms 类型”。
+但这些能力还不是 Beaver 的正式能力集合，而是“旧 bridge 恰好能跑通的一部分 swarms 类型”。

 更重要的是，当前它们依赖 `third_party/swarms` 这个 vendored 目录，这是后续必须去掉的。

+### 当前 Beaver 状态
+
+新后端已经先落地了不依赖 `third_party/swarms` 的 Agent Team v1：
+
+1. 自有核心模型：
+   - `AgentDescriptor`
+   - `DelegationEnvelope`
+   - `ExecutionNode`
+   - `ExecutionGraph`
+   - `NodeRunResult`
+   - `TeamRunResult`
+2. 内部服务入口：
+   - `TeamService.run_team(...)`
+3. 本地 delegated runner：
+   - `LocalAgentRunner`
+   - sub-agent 复用主 `AgentLoop.process_direct()` / `submit_direct()`
+4. 已实现策略：
+   - `sequence`
+   - `parallel`
+   - `dag`
+5. 已固定的安全语义：
+   - parent Task 必须存在且 session 匹配
+   - sub-agent run_ids 回填父 Task
+   - team/sub-agent 默认只写 receipts/effects，不生成 learning candidates
+   - learning candidates 仍只由 Task feedback gate 触发
+   - 节点级异常归一成 `NodeRunResult`
+   - summary 只聚合成功输出并列出失败节点
+
 ### 目标状态

-后续应该先定义我们自己的团队执行抽象：
+后续应该继续沿用我们自己的团队执行抽象：

 ```text
 TeamSpec
@ -325,31 +441,20 @@ TeamSpec

 然后：

-1. `SwarmsBackend` 只是 `StrategyBackend` 的一个实现。
+1. `SwarmsBackend` 如果以后存在，也只能是 `StrategyBackend` 的一个实现。
 2. 平台对外暴露的是自己的策略名和能力矩阵。
-3. `swarms` 只负责执行，不再负责定义平台边界。
+3. `swarms` 只提供可选执行或策略参考，不再负责定义平台边界。
 4. 仓库内不再保留 `third_party/`。
-5. `swarms` 要么作为外部依赖安装，要么把真正需要的最小能力内聚到我们自己的 backend 模块中。
+5. 高级策略可以先编译成 Beaver `ExecutionGraph` 或 step loop，而不是直接暴露 swarms runtime。

 ### 具体改法

-1. 抽出 `coordinator/backends/base.py`
-   - 定义统一 backend 接口
-2. 抽出 `coordinator/backends/swarms/`
-   - 把 `swarms_adapter.py`
-   - `swarms_bridge.py`
-   - `swarms_policy.py`
-   - `swarms_planner.py` 中 swarms 相关逻辑收进去
-3. 在平台层定义正式支持的 strategy
-   - `group_chat`
-   - `sequential`
-   - `concurrent`
-   - `rearrange`
-   - `mixture`
-   - `hierarchical`
-   - 后续预留 `graph`
-   - 后续预留 `heavy`
-4. 所有 strategy 的输入输出都转成我们的统一模型
+1. 保留当前 `coordinator/models.py / local.py / execution/scheduler.py` 作为 v1 core。
+2. 在平台层继续扩展正式支持的 strategy。
+   - 已实现：`sequence / parallel / dag`
+   - 预留：`moa / hierarchy / heavy / group_chat / forest / maker / router`
+3. 高级 strategy preset 先转成 `ExecutionGraph` 或 step loop。
+4. 如果后续接外部 swarms，单独放进 `coordinator/backends/swarms/`，并统一输入输出为 Beaver models。

 ### 结果

@ -357,7 +462,7 @@ TeamSpec

 1. `third_party/` 目录消失。
 2. 上层不再知道 `third_party/swarms` 这个路径。
-3. 对上层透明的是 `SwarmsBackend`，不是 vendored 源码目录。
+3. 对上层透明的是 Beaver 自有 team model 和 `TeamService`，不是 vendored 源码目录。

 ## 4.3 把 `skills` 从静态文档升级成能力生命周期系统

@ -557,23 +662,26 @@ CLI 不是“单 agent 专用模式”。

 ### 现在

-`spawn_agent_team -> DelegationManager -> AgentTeamOrchestrator -> SwarmsPlanner/Bridge -> SwarmRouter`
+`TeamService.run_team -> TeamGraphScheduler -> LocalAgentRunner -> AgentLoop.process_direct / submit_direct`
+
+Task mode 内部已经变成：
+
+`AgentService._run_task_mode -> TaskExecutionPlanner -> optional TeamService.run_team -> 主 Agent synthesis run -> ValidationService`

 ### 之后

-`spawn_agent_team`
-`-> DelegationService`
-`-> TeamApplicationService`
-`-> TeamPlanner`
-`-> ExecutionPlan`
-`-> StrategyBackendRegistry`
-`-> SwarmsBackend`
+`TeamService`
+`-> strategy preset`
+`-> ExecutionGraph`
+`-> TeamGraphScheduler`
+`-> LocalAgentRunner / optional StrategyBackend`
 `-> NormalizedTeamResult`

 结果是：

 1. 团队能力不再绑定某个第三方 runtime 结构。
-2. 可以逐步增加第二种 backend，而不推翻平台层。
+2. v1 已经支持 `sequence / parallel / dag`。
+3. 可以逐步增加高级 preset 或第二种 backend，而不推翻平台层。
 3. `swarms` 只是其中一个可插拔执行器。

 ## 5.3 skill 场景
@ -636,13 +744,13 @@ CLI 不是“单 agent 专用模式”。

 1. 把入口装配统一掉
 2. 把 `web/server.py` 开始拆分
-3. 把 swarms 相关代码聚到单独 backend 目录
+3. 先落地 Beaver 自有 Agent Team v1 core，避免继续依赖 vendored swarms

 交付物：

 - 统一 app factory / service wiring
 - 初步拆分 web routes
- `orchestration/backends/swarms/`
+- `coordinator/models.py / local.py / execution/scheduler.py`

 ### 第二期：平台抽象固化

@ -653,7 +761,7 @@ CLI 不是“单 agent 专用模式”。

 交付物：

- `TeamSpec`
+- `AgentDescriptor / ExecutionGraph / TeamRunResult`
 - `SkillSpec`
 - `ExecutionPlan`
 - `MemoryEntry`
@ -746,14 +854,11 @@ app-instance/backend/
 │   │   ├── guards/                  # 执行前检查
 │   │   └── profiles/                # 不同 agent 运行权限画像
 │   ├── coordinator/                 # 多 agent 协调层，参考 OpenHarness 的 coordinator 风格
-│   │   ├── delegation/              # 委派与任务分发
-│   │   ├── registry/                # agent registry 与 agent descriptor
-│   │   ├── planner/                 # 团队 planning 与 execution plan 生成
-│   │   ├── execution/               # 执行控制、fallback、聚合
-│   │   ├── backends/                # 可替换的多 agent backend
-│   │   │   ├── base.py              # backend 抽象接口
-│   │   │   └── swarms/              # swarms backend 封装，不再直接暴露第三方目录
-│   │   └── team/                    # team 级模型与编排对象
+│   │   ├── models.py                # AgentDescriptor / ExecutionGraph / TeamRunResult
+│   │   ├── local.py                 # LocalAgentRunner：复用主 AgentLoop
+│   │   ├── execution/               # sequence / parallel / dag 调度与聚合
+│   │   ├── backends/                # 后续可替换多 agent backend
+│   │   └── team/                    # team 级模型 re-export / 后续高级编排对象
 │   ├── services/                    # application services，对外提供统一能力入口
 │   │   ├── agent_service.py         # 统一 agent 运行入口
 │   │   ├── team_service.py          # 多 agent 执行入口
@ -797,3 +902,35 @@ app-instance/backend/
 3. 把 `skills` 从“静态 Markdown 包”升级成“可学习、可审核、可发布、可回滚的能力系统”。

 如果这三件事做成了，后面再扩多智能体架构、自动学习、插件生态、外部接入，代码就不会继续失控。
+
+---
+
+## 9. 最新落地状态：Task Team 后三件套
+
+本轮已经把 Task Team 融合后的三个缺口推进到 v1 可用状态：
+
+1. **Task Sub-agent Skill Resolver**
+   - 新增 `beaver/tasks/skill_resolver.py`。
+   - sub-agent 是临时 generic worker，不承载固定角色人设。
+   - `TaskExecutionPlanner` 的 team node 输出 `skill_query / required_capabilities / expected_output`。
+   - `TaskSkillResolver` 从 published skill catalog 中选择合适 skill，并写入 node pinned skills。
+   - 如果没有命中 published skill，会创建 draft-only skill，并把 draft 内容作为本次 sub-agent 的 ephemeral pinned skill context 使用。
+   - draft 不自动 approve/publish，不进入 runtime catalog；后续仍走 review/publish。
+   - agent registry / target resolver 不参与 Task sub-agent strategy，可作为未来外部 agent/A2A 管理面保留。
+
+2. **Task Team Process Projection**
+   - Task attempt 隐藏事件增加 `skill_queries / selected_skill_names / generated_skill_draft_ids / skill_resolution_report / node_results / task_synthesis_completed`。
+   - 新增 `GET /api/sessions/{session_id}/process`。
+   - 前端 `ChatWorkbench` 已接入 `ProcessLane` 和移动端 `Process` tab。
+   - 展示规划、skill selection、draft-only ephemeral guidance、team node、main synthesis、validation/retry，不把 team summary 直接当最终回答。
+
+3. **Learning Pipeline 闭环**
+   - 新增 `SkillLearningPipelineService`。
+   - Web API 覆盖 candidates、drafts、submit、approve、reject、publish、disable、rollback。
+   - `/skills` 页面增加 Published / Candidates / Drafts tabs。
+   - publish 仍要求 approved draft；rejected draft 不可 publish；draft 不进入 runtime catalog。
+
+验证状态：
+
+- 后端：`76 passed`。
+- 前端：`npm run typecheck` 通过，`npm test` 通过，`npm run lint` 通过但仍有既有 warnings。