|
|
@@ -0,0 +1,1235 @@
|
|
|
+# Agent框架任务规划与独立验证技术方案
|
|
|
+
|
|
|
+> 文档定位：通用 Agent 框架演进方案，不属于任何具体业务项目的技术方案
|
|
|
+> 适用范围：当前仓库 `agent/agent` 框架内核
|
|
|
+> 分析日期：2026-07-18
|
|
|
+> 写作原则：基于真实代码说明保留什么、修改什么、如何分阶段落地；不展开业务表结构和具体业务字段
|
|
|
+
|
|
|
+## 一、结论
|
|
|
+
|
|
|
+现有 Agent 框架可以直接演进为一套支持“主 Agent 统一规划、Worker 执行、Validator 独立评估、主 Agent 重新决策”的通用框架，不需要整体更换成其他编排框架。
|
|
|
+
|
|
|
+需要保留的核心能力包括：
|
|
|
+
|
|
|
+- `AgentRunner` 的模型调用和工具执行循环；
|
|
|
+- GoalTree 的动态任务树；
|
|
|
+- 主 Trace 与 Sub-Trace；
|
|
|
+- Worker 的独立上下文；
|
|
|
+- `continue_from` 的上下文续用能力；
|
|
|
+- 多 Worker 并行；
|
|
|
+- TraceStore、事件和可视化基础；
|
|
|
+- ToolRegistry、RunConfig 和 AgentPreset。
|
|
|
+
|
|
|
+真正缺少的不是 Agent 执行能力，而是下面四层语义没有分开：
|
|
|
+
|
|
|
+```text
|
|
|
+Task：一个业务无关的任务是否真正解决
|
|
|
+Attempt：某个 Worker 做过的一次执行尝试
|
|
|
+Validation：Validator 对某次尝试的独立评估
|
|
|
+Decision：主 Agent 对评估结果做出的最终决定
|
|
|
+```
|
|
|
+
|
|
|
+框架演进后的关键规则是：
|
|
|
+
|
|
|
+> Worker 运行结束不等于 Task 完成；Validator 评估通过也不等于 Task 完成；只有主 Agent 明确接受以后，Task 才能完成。
|
|
|
+
|
|
|
+本次只迭代框架能力，不改造任何具体业务项目，也不把任何具体业务的对象、Prompt、数据库、验收规则、成果格式或页面放进框架。
|
|
|
+
|
|
|
+## 二、框架边界
|
|
|
+
|
|
|
+### 2.1 框架负责什么
|
|
|
+
|
|
|
+框架负责提供所有业务都可以复用的运行能力：
|
|
|
+
|
|
|
+- 一个主 Agent 负责目标理解、任务规划和重新规划；
|
|
|
+- 动态创建、修订、拆分、阻塞、替代和取消 Task；
|
|
|
+- 派发 Worker 执行 Task；
|
|
|
+- 每次执行形成独立 Attempt；
|
|
|
+- 派发 Validator 对固定 Attempt 进行独立评估；
|
|
|
+- 把评估报告交还主 Agent；
|
|
|
+- 支持主 Agent 接受、返修、换人、改题、拆题或阻塞；
|
|
|
+- 控制 Planner、Worker、Validator 的工具权限；
|
|
|
+- 管理 Agent 会话生命周期和上下文隔离；
|
|
|
+- 保存 Task、Attempt、Validation、Decision 和 Trace；
|
|
|
+- 提供通用事件、API、SDK、恢复和观测能力。
|
|
|
+
|
|
|
+### 2.2 框架不负责什么
|
|
|
+
|
|
|
+框架不理解、不内置以下内容：
|
|
|
+
|
|
|
+- 某个行业或项目的业务对象；
|
|
|
+- 某个项目的任务拆分方法；
|
|
|
+- 某个项目的专用 Prompt 和 Skill；
|
|
|
+- 某个项目的验收标准；
|
|
|
+- 某个项目的数据库表、业务 API 和存储格式；
|
|
|
+- 某种成果的内部结构和发布流程；
|
|
|
+- 某个项目的产品页面；
|
|
|
+- 某个项目的固定 Workflow。
|
|
|
+
|
|
|
+### 2.3 正确的依赖方向
|
|
|
+
|
|
|
+依赖关系必须始终是业务项目调用框架，框架不能反向依赖业务项目。
|
|
|
+
|
|
|
+```text
|
|
|
+业务项目 A ─┐
|
|
|
+业务项目 B ─┼──> Agent Framework
|
|
|
+业务项目 C ─┘
|
|
|
+
|
|
|
+Agent Framework 不 import、不读取、不假设任何业务项目的内部代码和数据结构
|
|
|
+```
|
|
|
+
|
|
|
+业务项目通过配置和接口向框架注入：
|
|
|
+
|
|
|
+- 总目标和任务上下文；
|
|
|
+- Planner、Worker、Validator 的 Prompt；
|
|
|
+- 允许使用的工具；
|
|
|
+- 业务侧证据查询能力；
|
|
|
+- 成果的保存和读取能力；
|
|
|
+- 业务侧的验收条件；
|
|
|
+- 人工审批和发布动作。
|
|
|
+
|
|
|
+当前代码与这个目标边界还有一处历史偏差：`trace/run_api.py` 会动态加载 `examples.{project_name}.run`。这属于旧的项目启动兼容入口，不应继续留在通用 orchestration 内核。V1 应把它迁移到 Host bootstrap 或 legacy adapter；框架内核不得 import `examples` 或任何业务包。
|
|
|
+
|
|
|
+## 三、当前框架真实能力
|
|
|
+
|
|
|
+### 3.1 AgentRunner 可以继续作为统一执行引擎
|
|
|
+
|
|
|
+`agent/agent/core/runner.py` 已经实现模型调用、工具调用、消息循环、Trace 写入、停止和恢复等能力。
|
|
|
+
|
|
|
+Planner、Worker 和 Validator 可以继续使用同一个 AgentRunner，但必须拥有不同的：
|
|
|
+
|
|
|
+- 角色身份；
|
|
|
+- System Prompt；
|
|
|
+- 工具权限；
|
|
|
+- 上下文来源；
|
|
|
+- 最大运行轮次；
|
|
|
+- 结果协议；
|
|
|
+- 任务完成权限。
|
|
|
+
|
|
|
+不需要为 Validator 再开发另一套 Agent 执行器。
|
|
|
+
|
|
|
+### 3.2 Trace 已经支持父子 Agent 关系
|
|
|
+
|
|
|
+`agent/agent/trace/models.py` 中的 Trace 已经保存：
|
|
|
+
|
|
|
+- `agent_type`；
|
|
|
+- `parent_trace_id`；
|
|
|
+- `parent_goal_id`；
|
|
|
+- 运行状态；
|
|
|
+- 消息、工具调用、成本和耗时；
|
|
|
+- 可扩展的 context。
|
|
|
+
|
|
|
+因此可以继续使用：
|
|
|
+
|
|
|
+```text
|
|
|
+主 Agent = 主 Trace
|
|
|
+Worker = Worker Sub-Trace
|
|
|
+Validator = Validator Sub-Trace
|
|
|
+```
|
|
|
+
|
|
|
+不需要另造会话系统，但需要在 Trace context 中增加稳定的任务身份和角色身份，用于权限校验和恢复。
|
|
|
+
|
|
|
+### 3.3 GoalTree 已经具备动态规划基础
|
|
|
+
|
|
|
+`agent/agent/trace/goal_models.py` 和 `goal_tool.py` 已支持：
|
|
|
+
|
|
|
+- 创建顶层 Goal；
|
|
|
+- 创建子 Goal；
|
|
|
+- 切换当前 Goal；
|
|
|
+- 完成或放弃 Goal；
|
|
|
+- 使用父子关系表达任务树。
|
|
|
+
|
|
|
+主 Agent 可以在执行期间重新规划和拆分任务，不需要预先生成一张固定流程图。
|
|
|
+
|
|
|
+### 3.4 Worker 已经支持新建和有限续用上下文
|
|
|
+
|
|
|
+`agent/agent/tools/builtin/subagent.py` 默认会为 Worker 创建新 Sub-Trace，也支持使用 `continue_from` 恢复已有 Trace。
|
|
|
+
|
|
|
+这可以继续承担：
|
|
|
+
|
|
|
+- 新 Attempt 默认使用新 Worker 上下文；
|
|
|
+- 同一个 Task、同一个版本的局部返修有限续用原 Worker；
|
|
|
+- 换人、改题、拆题时创建新 Worker。
|
|
|
+
|
|
|
+### 3.5 框架已经支持多 Worker 并行
|
|
|
+
|
|
|
+当前 `agent()` 工具能够同时运行多个 Sub-Trace。
|
|
|
+
|
|
|
+新框架继续允许没有依赖关系的 Task 并行，但不把“并行”理解成“所有 Task 都可以同时跑”。存在先后依赖的 Task 仍由主 Agent 和 Coordinator 顺序推进。
|
|
|
+
|
|
|
+不过，当前代码只具备“同时启动多个 Sub-Trace”的并发能力，还不具备可靠的并行任务调度语义：
|
|
|
+
|
|
|
+- 多 Worker 聚合采用“任一分支成功，整体就算完成”的规则；
|
|
|
+- Worker 并行开关没有与 RunConfig 的实际配置正确连接；
|
|
|
+- `_get_allowed_tools(single, ...)` 没有真正根据 single 区分权限，多任务只读约束没有生效；
|
|
|
+- 分支结果会继续回写同一个父 Goal，无法分别验证和决策。
|
|
|
+
|
|
|
+新 Coordinator 必须把每个并行 Task 建成独立 Attempt 和 Validation，按依赖关系和聚合策略汇总。任何单个分支都不能直接完成父 Task，并行度也必须由 Coordinator 显式控制。
|
|
|
+
|
|
|
+### 3.6 已有扩展接口可以继续演进
|
|
|
+
|
|
|
+当前代码已经具备：
|
|
|
+
|
|
|
+- `TraceStore Protocol`：允许替换存储实现；
|
|
|
+- `ToolRegistry`：允许业务注册自己的工具；
|
|
|
+- `RunConfig`：允许每次运行传入配置；
|
|
|
+- `AgentPreset`：允许定义不同 Agent 角色；
|
|
|
+- `ToolContext Protocol`：允许工具获得运行上下文。
|
|
|
+
|
|
|
+新能力应沿着这些扩展点增加，不应另建一套平行框架。
|
|
|
+
|
|
|
+## 四、当前代码必须解决的问题
|
|
|
+
|
|
|
+### 4.1 Worker 运行结束会直接完成 Goal
|
|
|
+
|
|
|
+当前 `subagent.py` 在 Worker 返回后，会把 Worker 的运行状态写入父 Goal。
|
|
|
+
|
|
|
+但 Worker 的 `completed` 只说明 Agent 循环正常结束，不说明输出满足 Task 要求。
|
|
|
+
|
|
|
+新模式必须改为：
|
|
|
+
|
|
|
+```text
|
|
|
+Worker Trace completed
|
|
|
+→ Attempt submitted
|
|
|
+→ Task awaiting_validation
|
|
|
+```
|
|
|
+
|
|
|
+Worker 不再拥有完成 Task 或 Goal 的权限。
|
|
|
+
|
|
|
+### 4.2 旧 evaluate 不能直接承担正式 Validator
|
|
|
+
|
|
|
+当前 evaluate 主要返回自由文本，且存在以下问题：
|
|
|
+
|
|
|
+- 不能稳定解析通过、不通过和无法判断；
|
|
|
+- 评估运行结束可能错误完成当前 Goal；
|
|
|
+- 指定其他 Goal 时可能把状态更新到当前 Goal；
|
|
|
+- 没有绑定 Task 版本和 Attempt 快照；
|
|
|
+- 无法区分“产物不通过”和“Validator 自己运行异常”。
|
|
|
+
|
|
|
+建议保留旧 evaluate 兼容历史调用，新增正式的 `validator` 能力，不在原接口上强行改变全部旧语义。
|
|
|
+
|
|
|
+### 4.3 Preset 还不是可靠的权限边界
|
|
|
+
|
|
|
+当前 Runner 获取工具时会把 tool groups 和显式 tools 取并集。结果是角色本来只应该得到少量工具，却可能同时得到默认 core 工具。
|
|
|
+
|
|
|
+新规则必须是：
|
|
|
+
|
|
|
+```text
|
|
|
+Preset 定义角色最大权限
|
|
|
+RunConfig 只能在最大权限内缩小
|
|
|
+denied_tools 永远扣除
|
|
|
+执行工具时再次校验当前角色
|
|
|
+```
|
|
|
+
|
|
|
+权限控制不能只体现在模型看到的 Tool Schema 中，还要在工具真正执行前进行第二次校验。
|
|
|
+
|
|
|
+### 4.4 父 Goal 会自动级联完成
|
|
|
+
|
|
|
+当前 GoalTree 和 FileSystemTraceStore 都有“子 Goal 全部完成后自动完成父 Goal”的逻辑。
|
|
|
+
|
|
|
+显式验证模式下必须关闭这种行为。子 Task 全部完成后，父 Task只能进入“等待主 Agent 决策”，由主 Agent重新判断父问题是否真的解决。
|
|
|
+
|
|
|
+### 4.5 运行状态和业务状态混在一起
|
|
|
+
|
|
|
+当前 Trace、Goal 和 Agent 结果都可能使用 `completed`，但它们表达的是不同含义。
|
|
|
+
|
|
|
+必须明确：
|
|
|
+
|
|
|
+```text
|
|
|
+Trace completed：某个 Agent 停止运行
|
|
|
+Attempt submitted：Worker 交付了一次输出
|
|
|
+Validation Run Status=completed 且 Verdict=passed：Validator 正常完成并建议接受
|
|
|
+Task completed：主 Agent 已明确接受
|
|
|
+```
|
|
|
+
|
|
|
+### 4.6 continue_from 缺少身份校验
|
|
|
+
|
|
|
+当前续用主要检查 Trace 是否存在，没有严格确认：
|
|
|
+
|
|
|
+- 是否属于同一个主 Trace；
|
|
|
+- 是否属于同一个 Task；
|
|
|
+- Task 版本是否一致；
|
|
|
+- 原 Trace 是否是 Worker；
|
|
|
+- 是否仍允许继续返修；
|
|
|
+- 是否已经超过上下文或次数限制。
|
|
|
+
|
|
|
+新框架必须在 Coordinator 中统一校验，不允许调用方绕过。
|
|
|
+
|
|
|
+### 4.7 当前缺少针对核心语义的系统测试
|
|
|
+
|
|
|
+当前仓库没有完整覆盖 Goal、Subagent、Preset、Validator、状态转换的测试体系。
|
|
|
+
|
|
|
+这次框架升级必须同步建立测试，否则很容易出现“模型正文说未通过，但 Goal 状态已经完成”一类问题。
|
|
|
+
|
|
|
+## 五、目标架构
|
|
|
+
|
|
|
+```mermaid
|
|
|
+flowchart TD
|
|
|
+ Host[业务项目] --> SDK[Framework API / SDK]
|
|
|
+ SDK --> Coordinator[Task Coordinator]
|
|
|
+
|
|
|
+ Coordinator --> Planner[Main Agent / Planner]
|
|
|
+ Planner --> GoalTree[Dynamic GoalTree]
|
|
|
+ Planner --> Ledger[Task Ledger]
|
|
|
+
|
|
|
+ Ledger --> Attempt[Task Attempt]
|
|
|
+ Attempt --> Worker[Worker AgentRunner]
|
|
|
+ Worker --> Output[Attempt Output Snapshot]
|
|
|
+
|
|
|
+ Output --> Checks[Deterministic Checks]
|
|
|
+ Checks --> Validator[Validator AgentRunner]
|
|
|
+ Validator --> Report[Validation Report]
|
|
|
+
|
|
|
+ Report --> Planner
|
|
|
+ Planner --> Decision[Planner Decision]
|
|
|
+ Decision --> Ledger
|
|
|
+ Decision --> GoalTree
|
|
|
+
|
|
|
+ Coordinator --> TraceStore[TraceStore]
|
|
|
+ Coordinator --> EventBus[Framework Events]
|
|
|
+
|
|
|
+ Host -.注入.-> Tools[Business Tools]
|
|
|
+ Host -.注入.-> ArtifactPort[Artifact Port]
|
|
|
+ Host -.注入.-> EvidencePort[Evidence Port]
|
|
|
+```
|
|
|
+
|
|
|
+这套架构中：
|
|
|
+
|
|
|
+- GoalTree 表达任务之间的父子关系；
|
|
|
+- Task Ledger 表达每个任务当前运行到哪一步；
|
|
|
+- Trace 记录某个 Agent 实际做过什么；
|
|
|
+- Coordinator 用确定性程序推进状态；
|
|
|
+- Validator 只产生报告；
|
|
|
+- 主 Agent 的 Decision 才能完成、修订或拆分 Task；
|
|
|
+- 业务能力通过工具和接口注入。
|
|
|
+
|
|
|
+## 六、为什么保留 GoalTree，再增加 Task Ledger
|
|
|
+
|
|
|
+GoalTree 已经能够表达任务拓扑，不需要重写。
|
|
|
+
|
|
|
+但是 Goal 不应该同时承担以下所有职责：
|
|
|
+
|
|
|
+- 任务定义；
|
|
|
+- 任务版本；
|
|
|
+- Worker 运行；
|
|
|
+- Validator 评估；
|
|
|
+- 重试历史；
|
|
|
+- 主 Agent 决策；
|
|
|
+- 输出版本；
|
|
|
+- 业务完成状态。
|
|
|
+
|
|
|
+因此增加一个薄的 Task Ledger，用于记录：
|
|
|
+
|
|
|
+- 当前 Task 版本；
|
|
|
+- Task 当前阶段；
|
|
|
+- 关联的 Attempt；
|
|
|
+- 关联的 Validation；
|
|
|
+- 最近一次 Planner Decision；
|
|
|
+- 是否等待子任务；
|
|
|
+- 是否被新版本替代；
|
|
|
+- 当前输出引用和证据引用。
|
|
|
+
|
|
|
+Task Ledger 不是第二棵任务树，而是 GoalTree 的运行台账。
|
|
|
+
|
|
|
+### 6.1 Task Ledger 是显式验证模式的唯一事实来源
|
|
|
+
|
|
|
+在 `explicit_validation` 模式下，Task Ledger 是任务生命周期状态的唯一事实来源。
|
|
|
+
|
|
|
+GoalTree 只负责保存任务拓扑、焦点和展示所需摘要。现有 `Goal.status` 仅作为旧界面和旧接口的兼容投影，不允许被 Worker、Validator 或 Goal 工具独立写入。
|
|
|
+
|
|
|
+所有 `goal(done)`、Worker 回写、Validator 回写和父节点完成动作，都必须转换为 Coordinator Command。Coordinator 先原子更新 Task Ledger，再更新 Goal 的兼容投影。
|
|
|
+
|
|
|
+如果两者出现不一致：
|
|
|
+
|
|
|
+- Task Ledger 的状态用于调度、恢复和权限判断；
|
|
|
+- Goal.status 不能反向覆盖 Task Ledger；
|
|
|
+- Reconciliation 根据 Task Ledger 修复 Goal 投影并记录异常事件。
|
|
|
+
|
|
|
+详细状态一律从 Task Ledger 读取，避免 Task 与 Goal 双写后各自成为“真相”。
|
|
|
+
|
|
|
+## 七、核心角色及责任
|
|
|
+
|
|
|
+### 7.1 Host Application
|
|
|
+
|
|
|
+Host Application 是使用框架的业务项目。
|
|
|
+
|
|
|
+它负责：
|
|
|
+
|
|
|
+- 提供总目标和业务上下文；
|
|
|
+- 注册业务工具；
|
|
|
+- 提供业务 Prompt 和 Skill；
|
|
|
+- 提供输出和证据的保存方式；
|
|
|
+- 提供业务验收条件；
|
|
|
+- 决定是否需要人工审批；
|
|
|
+- 消费框架事件并构建自己的产品界面。
|
|
|
+
|
|
|
+框架不读取 Host Application 的内部模块。
|
|
|
+
|
|
|
+### 7.2 Task Coordinator
|
|
|
+
|
|
|
+Coordinator 不是 Agent，而是一层确定性程序。
|
|
|
+
|
|
|
+它负责：
|
|
|
+
|
|
|
+- 创建和更新 Task Ledger；
|
|
|
+- 校验当前状态是否允许执行某个动作；
|
|
|
+- 创建 Attempt 和 Validation；
|
|
|
+- 绑定 Task 版本和固定输出快照；
|
|
|
+- 在 Worker、Validator 和主 Agent 之间传递正确上下文；
|
|
|
+- 防止重复请求产生重复执行；
|
|
|
+- 管理超时、停止、恢复和错误状态；
|
|
|
+- 保证只有主 Agent Decision 能完成 Task。
|
|
|
+
|
|
|
+Agent 负责判断，Coordinator 负责守规则。
|
|
|
+
|
|
|
+### 7.3 Main Agent / Planner
|
|
|
+
|
|
|
+主 Agent 是唯一负责 Planning 的 Agent。
|
|
|
+
|
|
|
+它可以：
|
|
|
+
|
|
|
+- 理解总目标；
|
|
|
+- 创建和调整任务树；
|
|
|
+- 定义 Task 目标和验收条件；
|
|
|
+- 选择 Worker 类型和工具范围；
|
|
|
+- 读取 Validation Report；
|
|
|
+- 接受、返修、换人、改题、拆题、阻塞或取消；
|
|
|
+- 在子 Task 完成后重新判断父 Task。
|
|
|
+
|
|
|
+主 Agent 不直接修改 Task Ledger 文件，而是调用经过状态校验的规划工具。
|
|
|
+
|
|
|
+### 7.4 Worker
|
|
|
+
|
|
|
+Worker 负责执行一次 Task Attempt。
|
|
|
+
|
|
|
+它可以：
|
|
|
+
|
|
|
+- 读取本次任务上下文；
|
|
|
+- 调用本次任务允许的工具；
|
|
|
+- 生成 Attempt Output；
|
|
|
+- 提交证据引用和执行说明；
|
|
|
+- 报告新发现的问题。
|
|
|
+
|
|
|
+它不能：
|
|
|
+
|
|
|
+- 创建孙 Agent；
|
|
|
+- 修改任务树；
|
|
|
+- 修改验收条件；
|
|
|
+- 接受自己的结果；
|
|
|
+- 完成 Task；
|
|
|
+- 把 Attempt Output直接声明为最终结果。
|
|
|
+
|
|
|
+### 7.5 Validator
|
|
|
+
|
|
|
+Validator 使用独立 Trace 和独立上下文进行评估。
|
|
|
+
|
|
|
+它可以拥有和主 Agent 同等级的推理能力，也可以调用文件、数据库、API、网页和测试工具，但这些工具必须是只读或安全检查型工具。
|
|
|
+
|
|
|
+它负责：
|
|
|
+
|
|
|
+- 读取固定的 Task 版本；
|
|
|
+- 读取固定的 Attempt Output Snapshot；
|
|
|
+- 逐条检查验收条件；
|
|
|
+- 查询真实证据；
|
|
|
+- 输出结构化结论；
|
|
|
+- 指出失败位置、未验证事实和处理建议。
|
|
|
+
|
|
|
+它不能：
|
|
|
+
|
|
|
+- 修改 Attempt Output；
|
|
|
+- 修改 Task 或 GoalTree；
|
|
|
+- 创建 Agent；
|
|
|
+- 写业务数据；
|
|
|
+- 发布输出；
|
|
|
+- 完成 Task。
|
|
|
+
|
|
|
+## 八、核心对象
|
|
|
+
|
|
|
+### 8.1 Task
|
|
|
+
|
|
|
+Task 是业务无关的任务定义，表达“需要解决什么”。
|
|
|
+
|
|
|
+框架只关心：
|
|
|
+
|
|
|
+- 目标；
|
|
|
+- 验收条件；
|
|
|
+- 父子关系；
|
|
|
+- 版本；
|
|
|
+- 当前状态；
|
|
|
+- 业务自定义上下文引用。
|
|
|
+
|
|
|
+框架不理解目标正文中的业务含义。
|
|
|
+
|
|
|
+### 8.2 Attempt
|
|
|
+
|
|
|
+Attempt 表示一个 Worker 对某个 Task 版本做过的一次执行。
|
|
|
+
|
|
|
+同一个 Task 可以有多个 Attempt，例如：
|
|
|
+
|
|
|
+- 原 Worker 局部返修；
|
|
|
+- 换新 Worker 重做；
|
|
|
+- 使用不同模型重做；
|
|
|
+- 使用不同工具组合重做。
|
|
|
+
|
|
|
+每个 Attempt 都绑定自己的 Worker Trace 和输出快照。
|
|
|
+
|
|
|
+### 8.3 Validation
|
|
|
+
|
|
|
+Validation 表示 Validator 对某个 Attempt 固定快照做过的一次独立评估。
|
|
|
+
|
|
|
+输出发生变化后，旧 Validation 仍然保留，但不能作为新输出版本的通过依据。
|
|
|
+
|
|
|
+### 8.4 Planner Decision
|
|
|
+
|
|
|
+Decision 表示主 Agent 在读取评估后做出的明确决定。
|
|
|
+
|
|
|
+它必须被长期保存，便于解释：
|
|
|
+
|
|
|
+- 为什么接受；
|
|
|
+- 为什么重做；
|
|
|
+- 为什么换 Worker；
|
|
|
+- 为什么修改 Task；
|
|
|
+- 为什么拆分；
|
|
|
+- 为什么阻塞或取消。
|
|
|
+
|
|
|
+### 8.5 Artifact Reference
|
|
|
+
|
|
|
+框架不能假设输出是文本、图片、代码、知识条目还是其他内容。
|
|
|
+
|
|
|
+框架只保存通用引用，例如：
|
|
|
+
|
|
|
+- 输出标识；
|
|
|
+- 输出版本；
|
|
|
+- 存储位置；
|
|
|
+- 内容摘要；
|
|
|
+- 内容哈希；
|
|
|
+- 业务自定义 metadata。
|
|
|
+
|
|
|
+具体内容由 Host Application 的 Artifact Port 保存和读取。
|
|
|
+
|
|
|
+### 8.6 Evidence Reference
|
|
|
+
|
|
|
+框架只记录 Validator 使用过哪些证据引用，不理解证据的业务结构。
|
|
|
+
|
|
|
+证据可能来自：
|
|
|
+
|
|
|
+- 文件；
|
|
|
+- 数据库只读查询；
|
|
|
+- API 返回；
|
|
|
+- 网页；
|
|
|
+- 测试结果；
|
|
|
+- Trace；
|
|
|
+- 人工复核。
|
|
|
+
|
|
|
+## 九、状态模型
|
|
|
+
|
|
|
+### 9.1 Task 状态
|
|
|
+
|
|
|
+```text
|
|
|
+pending 等待执行
|
|
|
+running Worker 正在执行
|
|
|
+awaiting_validation Worker 已提交，等待评估
|
|
|
+validating Validator 正在评估
|
|
|
+awaiting_decision 评估完成，等待主 Agent 决策
|
|
|
+needs_replan 需要主 Agent重新规划
|
|
|
+waiting_children 等待子 Task
|
|
|
+completed 主 Agent 已接受
|
|
|
+superseded 已被另一个新 Task替代
|
|
|
+blocked 等待用户或外部条件
|
|
|
+cancelled 已取消
|
|
|
+```
|
|
|
+
|
|
|
+### 9.2 Attempt 状态
|
|
|
+
|
|
|
+```text
|
|
|
+running Worker 正在运行
|
|
|
+submitted Worker 已提交输出
|
|
|
+failed Worker 执行失败
|
|
|
+stopped 被停止
|
|
|
+expired 超时失效
|
|
|
+```
|
|
|
+
|
|
|
+### 9.3 Validation 运行状态与评审结论
|
|
|
+
|
|
|
+Validation 的运行状态和评审结论必须使用两个独立维度，不能再次混用。
|
|
|
+
|
|
|
+Validation Run Status：
|
|
|
+
|
|
|
+```text
|
|
|
+pending 等待运行
|
|
|
+running Validator 正在运行
|
|
|
+completed Validator 正常形成报告
|
|
|
+error Validator 自己运行异常
|
|
|
+stopped 被停止
|
|
|
+expired 超时失效
|
|
|
+```
|
|
|
+
|
|
|
+Validation Verdict：
|
|
|
+
|
|
|
+```text
|
|
|
+passed 建议通过
|
|
|
+failed 评审不通过
|
|
|
+inconclusive 无法判断或证据不足
|
|
|
+```
|
|
|
+
|
|
|
+只有 Run Status 为 completed 时才允许存在 Verdict。`error` 表示 Validator 没有正常完成评审，不能写成 failed；failed 只表示 Validator 正常完成后给出的评审结论。
|
|
|
+
|
|
|
+### 9.4 必须保持的状态不变量
|
|
|
+
|
|
|
+框架必须用程序保证：
|
|
|
+
|
|
|
+1. 一个 Validation 只能评估一个固定 Attempt Snapshot；
|
|
|
+2. Worker 不能把 Task 写成 completed；
|
|
|
+3. Validator 不能把 Task 写成 completed；
|
|
|
+4. Validation Run Status=completed 后，无论 Verdict 是什么，都进入 awaiting_decision；
|
|
|
+5. 普通 accept 只允许绑定当前 Task Version、当前 Attempt Snapshot，以及 Run Status=completed 且 Verdict=passed 的 Validation；
|
|
|
+6. 只有主 Agent 的有效 accept Decision 能把 Task 写成 completed；
|
|
|
+7. 子 Task 全部完成后，父 Task 只能进入 awaiting_decision 或 needs_replan；
|
|
|
+8. 旧 Task 版本的 Validation 不能用于新版本；
|
|
|
+9. 执行失败和评估异常不能伪装成业务不通过；
|
|
|
+10. 重复请求不能重复创建 Attempt 或重复接受输出。
|
|
|
+
|
|
|
+### 9.5 失败路径和决策边界
|
|
|
+
|
|
|
+状态机必须同时定义成功路径和失败路径：
|
|
|
+
|
|
|
+```text
|
|
|
+Attempt submitted
|
|
|
+→ Task awaiting_validation
|
|
|
+
|
|
|
+Attempt failed / stopped / expired
|
|
|
+→ Task needs_replan
|
|
|
+
|
|
|
+Validation completed + verdict
|
|
|
+→ Task awaiting_decision
|
|
|
+
|
|
|
+Validation error / stopped / expired
|
|
|
+→ Task needs_replan
|
|
|
+```
|
|
|
+
|
|
|
+`awaiting_decision` 专指“已有有效评审结论，等待主 Agent 决策”。
|
|
|
+
|
|
|
+`needs_replan` 专指“执行或评审链路没有形成有效结论，需要主 Agent决定重新执行、重新验证、修改任务或阻塞”。
|
|
|
+
|
|
|
+普通 accept 不能推翻 failed 或 inconclusive。如果某些业务允许主 Agent在特殊情况下越过评审结论，框架应提供独立的 `accept_override`，并要求 Host Policy 明确允许、记录理由和审批信息。它不能伪装成普通 accept。
|
|
|
+
|
|
|
+## 十、标准运行流程
|
|
|
+
|
|
|
+```mermaid
|
|
|
+sequenceDiagram
|
|
|
+ participant H as Host Application
|
|
|
+ participant M as Main Agent
|
|
|
+ participant C as Coordinator
|
|
|
+ participant W as Worker
|
|
|
+ participant V as Validator
|
|
|
+
|
|
|
+ H->>M: 提交总目标和上下文
|
|
|
+ M->>C: 创建或更新 Task
|
|
|
+ C->>W: 创建 Attempt 并启动 Worker
|
|
|
+ W-->>C: 提交输出、证据和 Trace
|
|
|
+ C->>C: 冻结 Attempt Snapshot
|
|
|
+ C->>V: 创建 Validation
|
|
|
+ V-->>C: 返回结构化评估报告
|
|
|
+ C-->>M: 报告、历史和当前任务树
|
|
|
+ M->>C: accept / repair / retry / revise / split / block
|
|
|
+ C->>C: 校验并执行状态转换
|
|
|
+ C-->>M: 返回更新后的 Task Ledger
|
|
|
+```
|
|
|
+
|
|
|
+这是一条通用运行协议，不规定主 Agent 创建什么业务任务。
|
|
|
+
|
|
|
+## 十一、Validator 设计
|
|
|
+
|
|
|
+### 11.1 先做确定性检查，再做 Agent 判断
|
|
|
+
|
|
|
+验证建议分三层：
|
|
|
+
|
|
|
+1. 确定性检查：格式、必填、文件存在、哈希、接口状态、测试结果等；
|
|
|
+2. Validator 判断：需要推理、比较、归因和综合判断的标准；
|
|
|
+3. 高风险复核：由第二模型、人工或业务侧审批完成。
|
|
|
+
|
|
|
+能够由程序确定的内容，不应全部交给模型猜测。
|
|
|
+
|
|
|
+### 11.2 Validator 必须评估固定快照
|
|
|
+
|
|
|
+Validator 启动时必须绑定：
|
|
|
+
|
|
|
+- Task ID 和 Task Version；
|
|
|
+- Attempt ID；
|
|
|
+- Output Snapshot；
|
|
|
+- 验收条件版本；
|
|
|
+- 允许使用的证据工具。
|
|
|
+
|
|
|
+评估过程中即使出现新输出，也不能替换 Validator 正在评估的版本。
|
|
|
+
|
|
|
+### 11.3 能力同级不等于权限同级
|
|
|
+
|
|
|
+Validator 可以使用高能力模型和丰富查询工具，但不能获得写权限。
|
|
|
+
|
|
|
+只读不能只靠 Prompt 保证，应通过：
|
|
|
+
|
|
|
+- 只读工具组；
|
|
|
+- 只读数据库账号；
|
|
|
+- 只读 API；
|
|
|
+- ToolRegistry 执行前角色校验；
|
|
|
+- 禁止 Agent、Goal 写入、文件写入和发布工具；
|
|
|
+- 独立运行环境或沙箱。
|
|
|
+
|
|
|
+### 11.4 报告必须结构化
|
|
|
+
|
|
|
+Validator 报告至少要能让程序稳定识别：
|
|
|
+
|
|
|
+- 总体结论：passed、failed、inconclusive；
|
|
|
+- 每条验收条件的结论；
|
|
|
+- 对应证据引用；
|
|
|
+- 未验证事实；
|
|
|
+- 失败位置；
|
|
|
+- 风险等级；
|
|
|
+- 给主 Agent 的处理建议。
|
|
|
+
|
|
|
+Validator 可以附带自然语言分析，但不能只返回一段无法解析的自由文本。
|
|
|
+
|
|
|
+## 十二、主 Agent重新规划
|
|
|
+
|
|
|
+框架需要向主 Agent提供以下通用 Decision：
|
|
|
+
|
|
|
+| Decision | 框架动作 |
|
|
|
+|---|---|
|
|
|
+| accept | 在有效 passed Validation 基础上接受本次输出，Task 完成 |
|
|
|
+| accept_override | Host Policy 特批后越过 failed/inconclusive，必须记录理由和审批 |
|
|
|
+| repair | 同 Task、同版本创建新 Attempt，可有限续用原 Worker Trace 上下文 |
|
|
|
+| retry | 创建新 Attempt，并创建新 Worker Trace |
|
|
|
+| revalidate | 对当前未变化的 Attempt Snapshot 创建新 Validation |
|
|
|
+| revise | 同一个 task_id 下创建新的不可变 spec_version，旧版本失效但 Task 不进入 superseded |
|
|
|
+| split | 创建子 Task，父 Task 进入 waiting_children |
|
|
|
+| request_evidence | 创建补证据 Task 或补充验证步骤 |
|
|
|
+| block | 等待用户、权限、资源或外部系统 |
|
|
|
+| cancel | 停止当前 Task 后续执行 |
|
|
|
+| supersede | 创建新的 task_id 替代旧 Task，旧 Task 进入 superseded |
|
|
|
+
|
|
|
+Coordinator 必须检查 Decision 是否适用于当前状态。例如已经 superseded 的 Task 不能再次 accept，已经修改验收条件的 Task 不能继续使用旧 Validation。
|
|
|
+
|
|
|
+`repair` 和 `retry` 都必须创建新 Attempt 和新 Output Snapshot。区别仅在于：repair 可以在满足上下文校验时通过 `continue_from` 续用上一 Worker Trace；retry 使用全新的 Worker Trace。旧 Attempt、旧 Snapshot 和旧 Validation 永远不修改。
|
|
|
+
|
|
|
+Validation 必须始终绑定 `task_id + spec_version + attempt_id + snapshot`。revise 只产生同一 Task 的新 spec_version；supersede 才会产生新的 task_id。
|
|
|
+
|
|
|
+## 十三、Agent 生命周期和上下文隔离
|
|
|
+
|
|
|
+### 13.1 Agent 定义与 Agent 会话分开
|
|
|
+
|
|
|
+以下内容可以长期复用：
|
|
|
+
|
|
|
+- 模型类型；
|
|
|
+- 角色 Prompt；
|
|
|
+- Tool Policy；
|
|
|
+- Skill 配置；
|
|
|
+- Preset。
|
|
|
+
|
|
|
+以下内容默认短生命周期：
|
|
|
+
|
|
|
+- 某次 Attempt 的消息上下文；
|
|
|
+- 某次 Validation 的消息上下文；
|
|
|
+- 临时工具结果；
|
|
|
+- 临时推理过程。
|
|
|
+
|
|
|
+Trace、输出、证据、报告和 Decision 长期保存。
|
|
|
+
|
|
|
+### 13.2 Worker 默认使用新上下文
|
|
|
+
|
|
|
+默认规则：
|
|
|
+
|
|
|
+```text
|
|
|
+New Attempt → New Worker Sub-Trace
|
|
|
+```
|
|
|
+
|
|
|
+这样可以减少：
|
|
|
+
|
|
|
+- 上一个任务的错误假设；
|
|
|
+- 无关上下文；
|
|
|
+- 已失效验收条件；
|
|
|
+- 越来越长的消息历史；
|
|
|
+- 多轮失败造成的路径依赖。
|
|
|
+
|
|
|
+### 13.3 continue_from 的允许条件
|
|
|
+
|
|
|
+只有以下条件全部满足才允许续用：
|
|
|
+
|
|
|
+- 同一个主 Trace；
|
|
|
+- 同一个 Task；
|
|
|
+- 同一个 Task Version；
|
|
|
+- 原 Trace 的角色是 Worker；
|
|
|
+- Decision 是 repair；
|
|
|
+- 修改范围明确且局部；
|
|
|
+- 未超过连续返修次数；
|
|
|
+- 未超过上下文长度和成本限制。
|
|
|
+
|
|
|
+改题、拆题、换路线或换 Worker 时必须新建 Trace。
|
|
|
+
|
|
|
+即使 repair 续用了原 Worker Trace，它仍然是一笔新的 Attempt，并生成新的 Output Snapshot。续用的是会话上下文，不是修改旧 Attempt。
|
|
|
+
|
|
|
+### 13.4 Validator 默认每次新建上下文
|
|
|
+
|
|
|
+每次 Validation 默认使用新 Trace，避免上一轮结论影响新一轮证据判断。
|
|
|
+
|
|
|
+框架可以复用 Validator Preset，但不复用其评估聊天历史。
|
|
|
+
|
|
|
+## 十四、工具权限模型
|
|
|
+
|
|
|
+### 14.1 Planner 权限
|
|
|
+
|
|
|
+Planner 可以：
|
|
|
+
|
|
|
+- 读取任务树和运行历史；
|
|
|
+- 创建、修订、拆分和阻塞 Task；
|
|
|
+- 启动 Worker 和 Validator；
|
|
|
+- 读取评估报告；
|
|
|
+- 提交 Planner Decision。
|
|
|
+
|
|
|
+Planner 是否拥有业务写工具，由 Host Application 配置，但框架自身的状态修改必须经过 Coordinator。
|
|
|
+
|
|
|
+默认情况下，Planner 只拥有编排写权限和业务只读权限。业务写工具需要 Host Application 显式授权并留下审计记录，避免“唯一 Planner”退化为主 Agent绕过 Worker 直接执行全部工作。
|
|
|
+
|
|
|
+### 14.2 Worker 权限
|
|
|
+
|
|
|
+Worker 可以使用当前 Attempt 明确允许的业务工具。
|
|
|
+
|
|
|
+框架默认禁止 Worker 使用：
|
|
|
+
|
|
|
+- `agent`；
|
|
|
+- `validator`；
|
|
|
+- Task/Goal 写入；
|
|
|
+- Planner Decision；
|
|
|
+- 发布和接受工具。
|
|
|
+
|
|
|
+### 14.3 Validator 权限
|
|
|
+
|
|
|
+Validator 可以使用只读查询和安全检查工具。
|
|
|
+
|
|
|
+框架默认禁止 Validator 使用：
|
|
|
+
|
|
|
+- 文件写入；
|
|
|
+- 数据库写入；
|
|
|
+- 外发消息；
|
|
|
+- 发布和部署；
|
|
|
+- `agent`；
|
|
|
+- Task/Goal 写入；
|
|
|
+- Planner Decision。
|
|
|
+
|
|
|
+### 14.4 权限计算规则
|
|
|
+
|
|
|
+工具权限不能再使用简单并集，建议采用：
|
|
|
+
|
|
|
+```text
|
|
|
+effective_tools
|
|
|
+= preset.allowed_tools
|
|
|
+∩ run_config.requested_tools
|
|
|
+∩ host_policy.allowed_tools
|
|
|
+− preset.denied_tools
|
|
|
+− host_policy.denied_tools
|
|
|
+```
|
|
|
+
|
|
|
+当某层没有显式 requested tools 时，表示“不进一步缩小”，不是“允许全部”。
|
|
|
+
|
|
|
+## 十五、通用扩展接口
|
|
|
+
|
|
|
+### 15.1 Task Store
|
|
|
+
|
|
|
+保存 Task、Attempt、Validation 和 Decision。
|
|
|
+
|
|
|
+框架可以提供文件系统默认实现，业务可以替换为关系数据库、文档数据库或其他共享存储。
|
|
|
+
|
|
|
+### 15.2 Artifact Port
|
|
|
+
|
|
|
+负责保存和读取 Attempt Output Snapshot。
|
|
|
+
|
|
|
+框架只认识 Artifact Reference，不认识具体内容结构。
|
|
|
+
|
|
|
+### 15.3 Evidence Port
|
|
|
+
|
|
|
+负责向 Validator 提供业务证据查询能力。
|
|
|
+
|
|
|
+实际实现可以是 ToolRegistry 中注册的只读工具，也可以是业务提供的适配器。
|
|
|
+
|
|
|
+### 15.4 Validation Policy
|
|
|
+
|
|
|
+用于定义：
|
|
|
+
|
|
|
+- 哪些 Task 只需确定性检查；
|
|
|
+- 哪些 Task 必须运行完整 Validator；
|
|
|
+- 哪些 Task 需要第二模型；
|
|
|
+- 哪些 Task 需要人工复核；
|
|
|
+- 最大验证次数和成本。
|
|
|
+
|
|
|
+框架提供机制，业务通过配置选择策略。
|
|
|
+
|
|
|
+### 15.5 Tool Policy
|
|
|
+
|
|
|
+Tool Policy 负责角色到工具权限的映射，并在工具执行前进行二次授权。
|
|
|
+
|
|
|
+业务可以注册工具，但不能绕过框架的角色上限。
|
|
|
+
|
|
|
+### 15.6 Event Sink
|
|
|
+
|
|
|
+框架输出通用事件，例如：
|
|
|
+
|
|
|
+```text
|
|
|
+task_created
|
|
|
+attempt_started
|
|
|
+attempt_submitted
|
|
|
+validation_started
|
|
|
+validation_completed
|
|
|
+planner_decision_recorded
|
|
|
+task_completed
|
|
|
+task_replanned
|
|
|
+task_blocked
|
|
|
+```
|
|
|
+
|
|
|
+业务系统可以订阅事件构建自己的页面、通知和监控。
|
|
|
+
|
|
|
+## 十六、存储、恢复和可观测性
|
|
|
+
|
|
|
+### 16.1 长期保存的内容
|
|
|
+
|
|
|
+至少需要保存：
|
|
|
+
|
|
|
+- 总目标；
|
|
|
+- GoalTree；
|
|
|
+- Task 和版本历史；
|
|
|
+- Attempt 和 Worker Trace；
|
|
|
+- Output Snapshot 引用；
|
|
|
+- Validation Report 和证据引用；
|
|
|
+- Planner Decision；
|
|
|
+- 角色、模型、工具策略和成本；
|
|
|
+- 状态变更事件。
|
|
|
+
|
|
|
+### 16.2 V1 可以继续使用文件存储
|
|
|
+
|
|
|
+第一版可以在现有 FileSystemTraceStore 基础上增加 Task Ledger 文件存储，先验证状态语义和运行闭环。
|
|
|
+
|
|
|
+但新的 Task Store 应先定义 Protocol，避免业务直接依赖文件目录结构。
|
|
|
+
|
|
|
+### 16.3 生产化使用共享存储
|
|
|
+
|
|
|
+多进程、多实例或跨机器运行时，需要共享持久化能力，否则会出现：
|
|
|
+
|
|
|
+- 一个实例看不到另一个实例创建的 Task；
|
|
|
+- 进程重启后无法恢复运行状态；
|
|
|
+- stop、continue 和 validation 找不到正确执行者；
|
|
|
+- 重复调度同一个 Attempt；
|
|
|
+- 多个主 Agent同时接受同一个输出。
|
|
|
+
|
|
|
+### 16.4 每一步必须可追踪
|
|
|
+
|
|
|
+一次完整闭环应能追踪：
|
|
|
+
|
|
|
+```text
|
|
|
+Task
|
|
|
+→ Attempt
|
|
|
+→ Worker Trace
|
|
|
+→ Output Snapshot
|
|
|
+→ Validation
|
|
|
+→ Validator Trace
|
|
|
+→ Planner Decision
|
|
|
+→ 下一 Task 状态
|
|
|
+```
|
|
|
+
|
|
|
+## 十七、并行和异步边界
|
|
|
+
|
|
|
+### 17.1 V1 使用现有同步闭环
|
|
|
+
|
|
|
+同一个 Task 的顺序固定为：
|
|
|
+
|
|
|
+```text
|
|
|
+Worker → Validator → Planner Decision
|
|
|
+```
|
|
|
+
|
|
|
+第一版可以继续使用现有 `await` 模式，不需要立即引入分布式队列。
|
|
|
+
|
|
|
+多个互不依赖的 Task 可以继续使用现有并行 Sub-Trace 能力。
|
|
|
+
|
|
|
+### 17.2 后续增加后台任务接口
|
|
|
+
|
|
|
+当主 Agent需要在 Worker 或 Validator 运行期间继续规划其他 Task 时，再提供：
|
|
|
+
|
|
|
+- start：启动后台 Attempt 或 Validation；
|
|
|
+- poll：查询状态；
|
|
|
+- event：完成后通知主 Agent；
|
|
|
+- stop：停止运行；
|
|
|
+- resume：恢复允许继续的运行。
|
|
|
+
|
|
|
+### 17.3 分布式调度放在 V3
|
|
|
+
|
|
|
+任务队列、租约、分布式锁、心跳和孤儿任务恢复属于生产治理，不是 V1 核心闭环的前置条件。
|
|
|
+
|
|
|
+## 十八、兼容策略
|
|
|
+
|
|
|
+为了不破坏现有调用，框架提供两种完成策略：
|
|
|
+
|
|
|
+```text
|
|
|
+legacy_auto
|
|
|
+保持旧行为，Worker 结束后可沿用旧 Goal 完成逻辑
|
|
|
+
|
|
|
+explicit_validation
|
|
|
+使用 Task、Attempt、Validation、Decision 的显式完成协议
|
|
|
+```
|
|
|
+
|
|
|
+新项目默认使用 `explicit_validation`。
|
|
|
+
|
|
|
+旧 evaluate 暂时保留，新 Validator 使用独立工具名、独立 Trace 类型和独立结构化结果。等旧调用完成迁移后，再决定是否废弃 evaluate。
|
|
|
+
|
|
|
+## 十九、代码改造范围
|
|
|
+
|
|
|
+### 19.1 保留不动或少动
|
|
|
+
|
|
|
+- `agent/agent/core/runner.py` 的核心模型循环；
|
|
|
+- Trace 和 Message 主体结构；
|
|
|
+- ToolRegistry 注册和调用框架；
|
|
|
+- GoalTree 的父子拓扑能力；
|
|
|
+- Sub-Trace 创建机制；
|
|
|
+- `continue_from` 的消息恢复基础；
|
|
|
+- WebSocket 和 Trace 可视化基础。
|
|
|
+
|
|
|
+### 19.2 修改现有模块
|
|
|
+
|
|
|
+| 模块 | 改造内容 |
|
|
|
+|---|---|
|
|
|
+| `tools/builtin/subagent.py` | Worker 完成改为 Attempt 提交；禁止 Worker 创建孙 Agent；增加续用身份校验入口 |
|
|
|
+| `trace/goal_models.py` | 增加完成策略；显式验证模式关闭父 Goal 自动完成 |
|
|
|
+| `trace/goal_tool.py` | Goal 完成动作改为经过 Coordinator 校验 |
|
|
|
+| `trace/store.py` | 保存新事件；显式验证模式关闭级联；避免非法状态 |
|
|
|
+| `core/presets.py` | 增加 Planner、Worker、Validator 角色策略 |
|
|
|
+| `core/runner.py` | 正确应用 Preset、轮次和工具权限；执行工具前进行角色校验 |
|
|
|
+| `trace/models.py` | Trace context 增加通用角色和 Task 身份 |
|
|
|
+| `trace/run_api.py` | 把动态加载 examples 的历史入口迁移到 Host bootstrap/legacy adapter；V2 再增加通用 API |
|
|
|
+| `tools/builtin/__init__.py` | 注册 Validator 和 Planner Decision 工具 |
|
|
|
+
|
|
|
+### 19.3 新增通用模块
|
|
|
+
|
|
|
+建议增加：
|
|
|
+
|
|
|
+```text
|
|
|
+agent/agent/orchestration/
|
|
|
+├── models.py
|
|
|
+├── protocols.py
|
|
|
+├── coordinator.py
|
|
|
+├── store.py
|
|
|
+├── policies.py
|
|
|
+└── events.py
|
|
|
+
|
|
|
+agent/agent/tools/builtin/
|
|
|
+├── validator.py
|
|
|
+└── task_planning.py
|
|
|
+```
|
|
|
+
|
|
|
+具体业务适配器不放在这些模块里。
|
|
|
+
|
|
|
+## 二十、三个框架版本
|
|
|
+
|
|
|
+### 20.1 Framework V1：任务执行与独立验证闭环
|
|
|
+
|
|
|
+目标：把最核心的语义和权限做正确。
|
|
|
+
|
|
|
+包括：
|
|
|
+
|
|
|
+- 主 Agent是唯一 Planner；
|
|
|
+- Worker 不能创建孙 Agent；
|
|
|
+- Task、Attempt、Validation、Decision 分离；
|
|
|
+- Worker 结束后进入 awaiting_validation；
|
|
|
+- 独立 Validator Trace；
|
|
|
+- 结构化 Validation Report；
|
|
|
+- 主 Agent支持 accept、repair、retry、revise、split、block；
|
|
|
+- 父 Task 不自动完成；
|
|
|
+- Worker 默认新 Trace；
|
|
|
+- Validator 默认新 Trace；
|
|
|
+- Planner、Worker、Validator 工具权限隔离；
|
|
|
+- 定义最小 TaskStore Protocol，并提供文件系统默认实现；
|
|
|
+- 定义最小 ArtifactSnapshot、EvidenceReader 和 ToolPolicy 协议及默认实现；
|
|
|
+- 使用不可变 Output Snapshot；
|
|
|
+- 提供单进程幂等键，防止同一请求重复创建 Attempt、Validation 或 Decision；
|
|
|
+- orchestration 内核不再动态 import examples 或业务包；
|
|
|
+- `legacy_auto` 与 `explicit_validation` 双模式；
|
|
|
+- 建立核心状态测试。
|
|
|
+
|
|
|
+以下改动量是基于当前代码和测试缺口的粗估，不是排期承诺：
|
|
|
+
|
|
|
+- 修改现有文件 8～12 个；
|
|
|
+- 新增文件 5～8 个；
|
|
|
+- 业务无关的框架代码和测试合计约 1,600～2,800 行。
|
|
|
+
|
|
|
+### 20.2 Framework V2：通用扩展接口与可靠恢复
|
|
|
+
|
|
|
+目标：让不同业务能够稳定接入框架。
|
|
|
+
|
|
|
+包括：
|
|
|
+
|
|
|
+- TaskStore、Artifact、Evidence 和 ToolPolicy 的生产级可插拔实现与业务适配器；
|
|
|
+- Validation Policy；
|
|
|
+- 通用 API 和 Python SDK；
|
|
|
+- 通用事件协议；
|
|
|
+- 跨进程、可持久化的幂等和防重复执行；
|
|
|
+- 超时和重试限制；
|
|
|
+- 进程重启后的状态恢复；
|
|
|
+- start、poll、event、stop、resume；
|
|
|
+- 统一成本、耗时、模型和失败原因统计。
|
|
|
+
|
|
|
+以下改动量是基于当前范围的粗估，不是排期承诺：
|
|
|
+
|
|
|
+- 修改和新增文件 10～15 个；
|
|
|
+- 框架代码和测试约 1,500～3,000 行。
|
|
|
+
|
|
|
+### 20.3 Framework V3：分布式生产治理
|
|
|
+
|
|
|
+目标：支持多业务、多实例和长时间运行。
|
|
|
+
|
|
|
+包括：
|
|
|
+
|
|
|
+- 后台任务队列；
|
|
|
+- Worker 和 Validator 独立进程；
|
|
|
+- 多实例协调；
|
|
|
+- Task Lease 和分布式锁；
|
|
|
+- 心跳和孤儿任务恢复；
|
|
|
+- 共享 TraceStore 和 TaskStore；
|
|
|
+- 多租户隔离；
|
|
|
+- 权限审计；
|
|
|
+- 配额和成本预算；
|
|
|
+- 多模型 Validator 策略；
|
|
|
+- 人工复核扩展点；
|
|
|
+- 完整监控和告警。
|
|
|
+
|
|
|
+预计在 V2 基础上新增：
|
|
|
+
|
|
|
+- 修改和新增文件 15～25 个；
|
|
|
+- 框架代码和测试约 2,000～4,000 行。
|
|
|
+
|
|
|
+## 二十一、V1 验收用例
|
|
|
+
|
|
|
+### 21.1 完成语义
|
|
|
+
|
|
|
+- Worker 正常结束后，Task 必须是 awaiting_validation，不能 completed；
|
|
|
+- Validator Run Status=completed 且 Verdict=failed 时，Task 不能完成；
|
|
|
+- Validator Run Status=completed 且 Verdict=passed 时，Task 必须进入 awaiting_decision；
|
|
|
+- 只有主 Agent accept 后，Task 才能 completed；
|
|
|
+- Validator Run Status=error 与 Verdict=failed 必须分开；
|
|
|
+- 普通 accept 必须绑定当前版本的 passed Validation；
|
|
|
+- accept_override 必须经过 Host Policy 并记录理由。
|
|
|
+
|
|
|
+### 21.2 重新规划
|
|
|
+
|
|
|
+- 同一个 Task 换 Worker 后产生新 Attempt；
|
|
|
+- 修改目标或验收条件后形成新 Task Version；
|
|
|
+- Task 被拆分后，子 Task分别执行和验证；
|
|
|
+- 子 Task全部完成后，父 Task 不自动完成；
|
|
|
+- 被 superseded 的 Task 不能再次 accept。
|
|
|
+
|
|
|
+### 21.3 上下文隔离
|
|
|
+
|
|
|
+- 不同 Task 默认不能复用 Worker Trace；
|
|
|
+- 同 Task、同版本的局部 repair 可以续用 Worker Trace，但必须创建新 Attempt 和 Snapshot；
|
|
|
+- revise、split 和 retry 默认创建新 Trace；
|
|
|
+- 改题后继续旧 Trace 必须被拒绝；
|
|
|
+- Validator 每次使用干净 Trace。
|
|
|
+
|
|
|
+### 21.4 权限
|
|
|
+
|
|
|
+- Worker 不能调用 agent、validator 和 Planner Decision；
|
|
|
+- Validator 可以读取允许的证据；
|
|
|
+- Validator 不能修改文件、业务数据、GoalTree 和 Task；
|
|
|
+- 仅隐藏 Tool Schema 不足以绕过执行层权限检查；
|
|
|
+- 主 Agent的每个 Decision 都留下记录。
|
|
|
+
|
|
|
+### 21.5 异常和恢复
|
|
|
+
|
|
|
+- Worker 失败只影响 Attempt，不直接完成或取消 Task；
|
|
|
+- Validator 崩溃记录为 error，可以重新验证；
|
|
|
+- 证据不足记录为 inconclusive；
|
|
|
+- 重复请求不会创建重复 Attempt；
|
|
|
+- 输出变化后旧 Validation 自动失效；
|
|
|
+- 达到次数、成本或上下文上限后进入 block 或 needs_replan。
|
|
|
+
|
|
|
+### 21.6 并行任务
|
|
|
+
|
|
|
+- 每个并行 Task 都有独立 Attempt 和 Validation；
|
|
|
+- 单个分支成功不能直接完成整体或父 Task；
|
|
|
+- 并行度由 Coordinator 配置，而不是读取不存在的 Runner 配置；
|
|
|
+- 聚合策略必须明确区分全部成功、部分成功和全部失败；
|
|
|
+- 并行 Worker 仍受各自 Tool Policy 约束。
|
|
|
+
|
|
|
+### 21.7 解耦检查
|
|
|
+
|
|
|
+- 框架内核不引用任何业务项目模块；
|
|
|
+- 框架模型中不出现具体业务对象；
|
|
|
+- 测试使用通用任务和通用输出；
|
|
|
+- 业务工具通过 ToolRegistry 注册；
|
|
|
+- 业务存储通过 Protocol 或 Port 注入；
|
|
|
+- 框架在没有任何具体业务项目代码时可以独立运行测试。
|
|
|
+
|
|
|
+## 二十二、主要风险和控制方式
|
|
|
+
|
|
|
+### 22.1 状态模型变复杂
|
|
|
+
|
|
|
+控制方式：所有状态转换集中到 Coordinator，不允许 Agent 或工具任意修改底层状态。
|
|
|
+
|
|
|
+### 22.2 Validator 与 Worker 可能有共同偏差
|
|
|
+
|
|
|
+控制方式：先做确定性检查；高风险任务支持第二模型和人工复核；框架记录评估历史，供业务统计漏检和误拒。
|
|
|
+
|
|
|
+### 22.3 Validator 增加成本和延迟
|
|
|
+
|
|
|
+控制方式：使用 Validation Policy 按风险选择规则检查、完整 Validator 或高级复核，而不是所有 Task 使用同一成本配置。
|
|
|
+
|
|
|
+### 22.4 主 Agent上下文越来越长
|
|
|
+
|
|
|
+控制方式：只把结构化报告和高价值摘要交给主 Agent；完整 Trace、输出和证据保存在外部存储，需要时读取。
|
|
|
+
|
|
|
+### 22.5 无限失败循环
|
|
|
+
|
|
|
+控制方式：限制同一 Task Version 的 Attempt 数、连续 repair 次数、拆分深度、Validation 次数、总 Token 和总成本。
|
|
|
+
|
|
|
+### 22.6 Prompt 不能保证权限
|
|
|
+
|
|
|
+控制方式：Preset 最大权限、RunConfig 缩小权限、Host Policy、工具执行层校验和基础设施只读账号共同生效。
|
|
|
+
|
|
|
+### 22.7 兼容旧调用可能拖累新语义
|
|
|
+
|
|
|
+控制方式：用 completion policy 明确隔离 legacy 和 explicit validation；新功能不复用含义不清的旧 evaluate 返回协议。
|
|
|
+
|
|
|
+### 22.8 通用框架可能被业务需求反向污染
|
|
|
+
|
|
|
+控制方式：坚持依赖倒置；任何业务能力必须通过 Tool、Port、Policy 或 Event 接入；框架内核不接受业务模型和业务流程。
|
|
|
+
|
|
|
+## 二十三、最终判断
|
|
|
+
|
|
|
+最适合当前框架的演进方向是：
|
|
|
+
|
|
|
+```text
|
|
|
+Central Main Planner
|
|
|
++ Dynamic GoalTree
|
|
|
++ Task Ledger
|
|
|
++ Ephemeral Worker per Attempt
|
|
|
++ Independent Tool-using Validator
|
|
|
++ Explicit Planner Decision
|
|
|
++ Business Capability Injection
|
|
|
+```
|
|
|
+
|
|
|
+不建议：
|
|
|
+
|
|
|
+- 让 Worker 自己评估自己；
|
|
|
+- 让 Validator 直接完成 Task；
|
|
|
+- 让 Worker 创建孙 Agent；
|
|
|
+- 让所有角色拥有相同写权限；
|
|
|
+- 把运行结束当成业务完成；
|
|
|
+- 为任务树层级引入多层 Agent 递归；
|
|
|
+- 把任何具体业务的 Workflow、数据结构或 Prompt 放进框架内核；
|
|
|
+- 在 V1 阶段整体更换框架或直接引入分布式调度。
|
|
|
+
|
|
|
+建议先完成 Framework V1，验证以下最小闭环：
|
|
|
+
|
|
|
+```text
|
|
|
+Main Agent Planning
|
|
|
+→ Worker Attempt
|
|
|
+→ Independent Validation
|
|
|
+→ Main Agent Decision
|
|
|
+→ Replan or Complete
|
|
|
+```
|
|
|
+
|
|
|
+框架只负责保证这个协议正确、可恢复、可扩展。业务项目负责告诉框架“做什么、用什么工具、如何验收、输出保存在哪里”。
|
SamLee