Deputy Agent 设计理念

根节点

设计目标：1 小时 ~ 2 天 无人值守 × 白领（非 Coding）任务的 Agent 框架。

这一句里有两个独立属性，分别推导出两组需求；另有一支正交的经济性约束，以及一项外部约束（生态/语言选择）。

根
├── 外部约束：依赖 CC / Codex 内核 → 选 TypeScript（生态绑定，非自由推导）
├── 属性 A：长时间无人值守
├── 属性 B：白领任务（非 Coding）
└── 属性 C：经济性（与 A、B 正交）

属性 A：长时间无人值守 → 5 个一阶需求

A. 无人值守长任务
├── A1. 单 session/单 Agent 撑不住 → 必须分段
├── A2. 长 context 下 LLM 会懒/忘/作弊 → 必须独立审查
├── A3. 不能停下问用户 → 必须自决
├── A4. 进程会崩 → 必须可持久化恢复
└── A5. 中途要能改方法 → 必须可运行期纠偏

A1. 分段

选项
├── (a) 单 session + 自动 context 压缩（CC 原生）  ❌ 压缩损失不可控
├── (b) 多 session 时间维度接力                    ✅ 选
└── (c) 空间维度并行（subagent fan-out）           ✅ 选（与 b 互补）

落地
├── filesystem 是唯一跨 session state（progress.md / streams/ / artifacts/）
├── 每个 session 进来先读 progress.md 重建上下文
├── 4 种显式退出信号：declare_done / blocked / handoff / continue
└── 强制把工作切成 phase——任一 phase 边界都是安全退出点

A2. 独立审查

选项
├── (a) 单 Agent 自审            ❌ 单 context 流自我审过度自信
├── (b) 对等 Multi-Agent          ❌ 通讯/仲裁成本高，LLM 不会现场生成合理组织
└── (c) Master-Worker             ✅ 选

落地（4 角色分工）
├── Meta：长寿命策略权威 + harness 设计者
├── Worker：短 session 执行者
├── Watcher：实时把 worker stream 压缩成"事实+引文"喂 Meta
│           （只有建议权，不能直接对 Worker 说话）
└── Reviewer：bootstrap 前 + final 前两个 stage 转换硬 gate（host 强制）

并附两条独立性纪律
├── Meta 触发 Reviewer 时不带初判 framing
└── "Meta 自己改 harness 自己 review = 等同没 review"

A3. 自决

选项
├── (a) 阈值触发就停下来问用户   ❌ 用户体验差、违背"无人值守"
└── (b) fail-soft 自决            ✅ 选

落地
├── Meta 先用工具解决（重启 Worker / 改 harness / 发消息），实在不行才 awaiting_user
├── 默认不引入"≤N 次工具调用"上限——明文写"容易被 AI 当偷工借口"
└── 跟用户必须沟通时优先"可编辑选项"而非"白框"——降心智成本

A4. 持久化

选项
├── (a) 进程内 state          ❌ 崩就丢
├── (b) 数据库                ❌ 重，与 LLM/agent 语义不对齐
└── (c) 纯文件系统             ✅ 选（天然就是 Memory）

落地
├── workspace/ + control/manifest.yaml（CAS 守卫的 stage 转换）
├── events.jsonl 追加 + state.jsonl 折叠
└── 启动恢复路径会接住未仲裁的 worker_session_end

A5. 运行期纠偏

选项
├── (a) harness 启动后冻结      ❌ 首版不可能预判一切
└── (b) 运行期 Meta 可改         ✅ 选

落地
├── 改 harness 只能走 sh_harness__write_*（写 audit 事件）
├── PreToolUse hook 拒绝 Edit/Write 改 workspace/harness/**（防绕过）
├── 改完必须配套 send_to_worker 告知（写文件 ≠ 调度）
├── 大改后触发 harness_revision_review
└── 兜底：watchdog 5 类阈值（no_progress 30min / tool_loop 5 次 / 等），
    触发后仍交 Meta 仲裁——host 从不擅自重启 worker

属性 B：白领任务 → 4 个一阶需求

B. 白领任务
├── B1. 没有客观判据（无 build/test pass）→ 完成判定要靠语义
├── B2. 输入形态多样且有 silent failure（xlsx/pdf 等）
├── B3. 不同白领任务方法论差异大 → 一套通用 harness 必污染
└── B4. 用户是非技术读者 → 沟通去框架术语

B1. 完成判定

选项
├── (a) 纯结构 check               ❌ 白领产出语义判不了真伪
├── (b) 纯语义判断                  ❌ 太贵且无下限
└── (c) 结构 sanity + 多层语义复核   ✅ 选

落地（反偷工三层）
├── done_criteria：6 类结构 check（file_exists / min_lines / 等），
│                  明确反对做成"语义裁决器"
├── Worker 自评：declare_done 硬 gate，逐条+实证引用+provenance 标签
├── Reviewer：fabrication 默认 critical，final_review 可 WebFetch 抽查
└── Meta 终审：必须主动 Read 真实产出做语义复核，不依赖 self-report

B2. 输入 silent failure

选项
├── (a) 堆一堆 Office MCP          ❌ LLM 根本意识不到该用
└── (b) 把"该 inventory"写进方法论  ✅ 选

落地
├── Meta / Worker / Reviewer 三个角色 prompt 各重复写一遍
│   office=zip / pdf=pdfimages 的 inventory SOP
└── 强制留 audit 证据（worker 做完 inventory 必须 notify_meta）

B3. 任务级定制

选项
├── (a) 一套大 harness 覆盖所有任务   ❌ 无关 prompt 污染
│                                       + 与模型版本耦合
│                                       + 提升 worker 能力门槛
├── (b) 一组任务类型的固定模板          ❌ 仍有污染，类型边界难划
└── (c) 按需现场生成 task harness      ✅ 选——这就是"造 harness 的 harness"

落地
├── framework harness（src/host + 角色 prompt）保持任务无关
├── Meta 在 bootstrapping 阶段写
│   methodology.md / sop/*.md / done_criteria.yaml /
│   worker_prompt_taskpart.md / tools/*
├── 写入路径有严格白名单，超出即拒
└── 强制把 raw_task 翻译成 6 类显式约束
    （受众/形态/时间窗/必含/排除/品质），每条冗余 ≥3 处落点

并附一条"不允许凭印象"纪律
└── harness 约束必须能追溯到 raw_task / clarify 原文；
    领域常识 / 训练记忆作为派生来源被显式禁止

B4. 用户沟通

落地
├── 给用户的文本零框架术语
├── intent 三分：question / delivery_report / notification
├── 澄清阶段优先"可编辑选项"，避免白框
└── trade-off 必须主动说明 silent failure 形态
    ——不让用户当错误巡查员

属性 C：经济性 → 多模型异构

C. 长任务的成本约束
└── C1. 角色对模型能力要求不同 → 分层选型

选项
├── (a) 全用顶配模型（Opus 全栈）          ❌ 长任务 token 成本爆炸
├── (b) 全用便宜模型                        ❌ Meta 策略层撑不住
└── (c) 异构：Meta/Reviewer 强 + Worker 便宜  ✅ 选

落地（典型分层）
├── Meta：长寿命 + 策略判断 + harness 设计 → 强模型（如 Opus）
├── Reviewer：独立高质量审 → 强模型
├── Worker：执行类工作 → 中档（如 Sonnet 或更便宜）
├── Watcher：流式压缩 + 模式识别 → 可用更便宜模型
└── Agent SDK 可分别指定 —— 不绑死单一 provider

第三层：明确"不做"的特性（取舍的另一半）

这部分往往比"做了什么"更能说明设计哲学。

不做
├── 跨任务 Memory                  作者明说"Hermes 只管杀不管埋"，
│                                   有效性辨别/淘汰比新增难得多；0.1.0 不实装
├── 跨任务自主迭代/AutoResearch    LLM 不擅长自我优化 MultiAgent 配置，
│                                   开发途中被迫推翻
├── 按需生成多 Agent Team           同上，LLM 不会现场生成合理的多 agent 组织
├── Coding 场景特化                 已经有够多人做了，刻意让出
├── 完整对等 Multi-Agent            通讯+仲裁成本高于收益（《人月神话》）
├── 大量内置花哨功能                明确选择"平衡 / 真正有用 / 经得起时间检验"
└── 一套覆盖所有模型的 harness      harness 与模型小版本绑定，没意义

把整棵树压成一句话

附：作者声明但未实装的能力

路线图（0.1.0 未实装，作者已公开规划）
├── 跨任务级 Memory ——
│   harness 生成阶段从历史 task 提取相关经验注入新任务；
│   每个任务完成后总结成简略经验文档
├── 外部 know-how 注入 ——
│   框架预制 + 用户/开发者上传 + 历史经验挖掘的 know-how / tool / MCP
│   与跨任务 Memory 强耦合
└── 时窗预算 ——
    clarifying 阶段目标 ≤ 5 min；
    harness 生成阶段有更多预算（可在该阶段做历史经验分析）