Harness zh

Harness 机制

harness 是"智能体决定跑一张图"到"图跑完"之间的全部机械：一个授权边界、一个调度器、一个事件溯源存储，加上让每一方保持诚实的契约。按生命周期顺序讲。

1. 入口：三条路

• /dag-flow <任务>——对话式入口。路由指导按任务选形状：普通对话、单个 task 子代理、或一张工作流图。
• workflow 工具——十一个 action：start / extend / control（pause · resume · cancel · step · complete · replan）/ status / result / list / read / guide / draft / validate。
• draft——结构化图走工具参数；harness 渲染 YAML、校验、返回 spec_path。字段名错误在 provider 边界就被工具 schema 拒掉。

底下一条契约：**图内容住在文件里，工具参数只带路径。**内联传嵌套图会被 provider 的工具调用序列化压成字符串——这个失败模式就是边界长成这样的原因。

2. 授权边界：WorkflowAuthoring

从源到备好图的唯一权威。流水线：解析 YAML → 严格 action 解码 → 块编译成节点（review 块展开成三个：standards 审查、intent 审查、仲裁）→ profile 检查。portable 只验结构不碰环境；environment 额外对着真实目录解析智能体、prompt 资产、模型。没有有效的备好图就没有事件没有持久化——坏图永远不会"先跑起来看看"。

3. 调度器：波次、许可、真实会话

• 依赖图分层成波次；波次内并行，受并发信号量约束（max_concurrency，默认 5）。
• 节点准入时持久化为 queued；拿到并发许可才创建子会话。100 节点扇出不会一次物化 100 个会话。
• 每个节点是真实子会话——和 task 工具同一代码路径，有自己的智能体、上下文、工具。
• 模型解析链：分层（dag.jsonc）→ worker agent → 父会话模型。都解析不出来就不建工作流，回来问你。没有静默默认值。
• 所有权：每次检查从数据库重读工作流行的目录戳；收养持有条件认领（一条 UPDATE，仅当行存在且非终态时成功）；会话迁移时同一事务内重盖戳。

4. 数据层：事件溯源

所有状态变更是 durable dag.* 事件。投影器在发布事务内部写 SQLite 读模型，读模型不可能落后日志。历史就是事件回放，没有日志表。状态转换走声明式状态机——非法转换是类型化错误（409 不是 500）。终态不可逆，唯一例外：extend 可重开在报告检查点自然完成的工作流。

瞬态摘要事件（进度计数）故意不进 durable manifest——重算，不重放。

5. 父子通信

• 父从不轮询。report_to_parent 节点到终态、或工作流终结时，合成消息唤醒。
• 依赖输出自动流动：depends_on 的输出变成下游 prompt 的模板变量和结构化上下文。
• 输出三种形态：纯文本；结构化（output_schema + submit_result）；或文件——最终回复是一个绝对路径时捕获为 {content_ref, size, sha256, summary}，result 返回指针。
• result 带 cursor 分页读。

6. 质量层：有牙齿的门禁

• review 块编译成双独立审查加仲裁；REJECT 是真实结果。有一次真实运行里，修复列车被拒——一个加固提交没有可证伪的探针——修复环补上探针重跑才过。
• 验证纪律：红先行探针 + 突变复证。回归测试必须在修复前失败、修复后通过；在 scratch 工作区回退修复必须让它重新变红，恢复必须字节一致。
• deep 模式准入：有界问答产出带指纹的 Requirement Brief；裁定 READY / NOT_READY / WAIVED，实质性变更使指纹失效。
• 审查指纹绑定：实现变了指纹就变——旧的 ACCEPT 过不了门。

7. 演化层：修订

replan 标记被替代节点并递增 graph_rev。视图和终态聚合只读当前修订：被替代的失败永远不会把一个在替代路径上成功的工作流拖成失败；当前图上的活失败一直可见直到真的修好。持久化历史不删——智能体可以按 id 从 result store 审计被替代节点；TUI 不给入口。

8. 预算与恢复

四个旋钮：max_concurrency（5）、max_node_replan_attempts（5）、max_total_nodes（100）、每节点 timeout_ms（10 分钟，排队计入）。超截止时间走升级链：唤醒 orchestrator 裁决（延长或取消），持续超限到 cap 强杀。

崩溃恢复惰性、按工作流、证据驱动。跑完的会话回填输出；有歧义的暂停工作流交父智能体处置；provider 工作绝不重放——不会在你背后把半个模型调用再发一遍。失败带分类（timeout / exec_failed / verdict_fail）决定修复方式：更长截止时间、修配置、或重述契约。

---

各层的实现细节见引擎内幕-zh。