|
|
@@ -0,0 +1,99 @@
|
|
|
+# V1 任务执行与独立验证
|
|
|
+
|
|
|
+V1 提供一套与具体业务无关的显式任务闭环：主 Agent 负责规划和决策，Worker 只执行，Validator 只评估。Worker 或 Validator 的 Trace 结束都不等于 Task 完成。
|
|
|
+
|
|
|
+```text
|
|
|
+Planner -> Task -> Worker Attempt -> Artifact Snapshot
|
|
|
+ -> independent Validator -> Planner Decision
|
|
|
+```
|
|
|
+
|
|
|
+## 两种完成策略
|
|
|
+
|
|
|
+- `legacy_auto`：默认值。保留原有 `agent`、`evaluate`、`goal` 和 Goal 父节点级联语义。
|
|
|
+- `explicit_validation`：启用 V1。只能配合带 `planner`、`worker`、`validator` role 的 preset 使用，且必须先装配 `TaskCoordinator`。
|
|
|
+
|
|
|
+显式模式的状态由 `TaskLedger` 决定。`GoalTree` 只用于兼容展示；二者不一致时可调用 `TaskCoordinator.reconcile_goal_tree()` 修复 Goal 投影。
|
|
|
+
|
|
|
+## 最小装配
|
|
|
+
|
|
|
+```python
|
|
|
+from agent import (
|
|
|
+ AgentRunner,
|
|
|
+ FileSystemTraceStore,
|
|
|
+ FileSystemTaskStore,
|
|
|
+ FileSystemArtifactStore,
|
|
|
+ OrchestrationConfig,
|
|
|
+ wire_orchestration,
|
|
|
+)
|
|
|
+
|
|
|
+trace_store = FileSystemTraceStore(".trace")
|
|
|
+runner = AgentRunner(trace_store=trace_store, llm_call=my_llm_call)
|
|
|
+
|
|
|
+coordinator = wire_orchestration(
|
|
|
+ runner,
|
|
|
+ FileSystemTaskStore(".trace"),
|
|
|
+ FileSystemArtifactStore(".trace"),
|
|
|
+ OrchestrationConfig(max_parallel_tasks=4),
|
|
|
+)
|
|
|
+```
|
|
|
+
|
|
|
+主 Agent 使用：
|
|
|
+
|
|
|
+```python
|
|
|
+from agent import CompletionPolicy, RunConfig
|
|
|
+
|
|
|
+config = RunConfig(
|
|
|
+ agent_type="planner",
|
|
|
+ completion_policy=CompletionPolicy.EXPLICIT_VALIDATION,
|
|
|
+ tool_groups=None,
|
|
|
+)
|
|
|
+
|
|
|
+result = await runner.run_result(
|
|
|
+ [{"role": "user", "content": "根据目标制定任务树并执行；每个任务必须独立验证。"}],
|
|
|
+ config,
|
|
|
+)
|
|
|
+```
|
|
|
+
|
|
|
+通过 `invoke_agent()` 启动本地项目时，如果项目 `RUN_CONFIG` 使用 `explicit_validation`，SDK 会用项目的 `TRACE_STORE_PATH` 自动装配文件 Store。项目可以在 `config.py` 暴露 `ORCHESTRATION_CONFIG` 覆盖并行度和 preset 名称。
|
|
|
+
|
|
|
+## Agent 工具
|
|
|
+
|
|
|
+Planner：
|
|
|
+
|
|
|
+- `task_plan`：创建顶层/子 Task、插入同级 Task、切换焦点。
|
|
|
+- `dispatch_tasks`：运行一个或多个互相隔离的 Worker→Validator 闭环。
|
|
|
+- `task_decide`：执行 accept、repair、retry、revise、split、block、unblock、cancel、supersede。
|
|
|
+- `validate_attempt`：仅在 Validator error、stopped、expired 后，对未变化的 Snapshot 发起新 Validator Trace。
|
|
|
+
|
|
|
+Worker 只能使用 `submit_attempt` 正式交付。Validator 只能使用 `submit_validation` 正式提交结构化报告。二者都是 terminal tool：结果会先写入 Trace，然后结束当前 Agent Loop。
|
|
|
+
|
|
|
+## 关键不变量
|
|
|
+
|
|
|
+- Planner 是唯一可以改变任务树和作出完成决策的角色。
|
|
|
+- Worker 看不到且不能执行 `agent`、`evaluate`、`goal` 或 Planner/Validator 工具。
|
|
|
+- Validator 使用独立 Trace，只能访问 preset 明确允许的只读工具。
|
|
|
+- Worker 未调用 `submit_attempt`，Attempt 失败，Task 进入 `needs_replan`。
|
|
|
+- Validator 未调用 `submit_validation`，Validation 状态为 `error`，不是业务 `failed`。
|
|
|
+- `passed` 只让 Task 进入 `awaiting_decision`；只有 Planner 对当前版本、当前 Attempt、当前 Snapshot 执行 `accept` 才完成。
|
|
|
+- `failed`、`inconclusive` 没有 override 接受入口。
|
|
|
+- 同一 TaskSpec 最多 repair 一次；repair 产生新 Attempt 和 Snapshot，但续用原 Worker Trace。retry、revise 使用新 Worker Trace。
|
|
|
+- 子 Task 全部完成后，父 Task 进入 `needs_replan`，不会自动完成。
|
|
|
+
|
|
|
+## 存储与扩展点
|
|
|
+
|
|
|
+默认目录：
|
|
|
+
|
|
|
+```text
|
|
|
+.trace/{root_trace_id}/orchestration/
|
|
|
+├── ledger.json
|
|
|
+├── artifacts/{snapshot_id}.json
|
|
|
+└── events.jsonl
|
|
|
+```
|
|
|
+
|
|
|
+`TaskStore`、`ArtifactStore`、`AgentExecutor`、`ToolPolicy`、`EventSink` 都是端口。V2 可增加远程执行器和公开 API，V3 可增加队列与分布式 Store，而不改变 Task 状态机和 Coordinator 决策语义。
|
|
|
+
|
|
|
+## V1 限制
|
|
|
+
|
|
|
+- 显式闭环只支持本地 Sub-Trace；远程 Agent 继续使用 `legacy_auto`。
|
|
|
+- 没有 Task/Attempt/Validation HTTP API。
|
|
|
+- 默认 Store 只保证单进程内并发安全；跨进程/分布式调度不在 V1 范围。
|
SamLee