[Idea] 将稳定的 Agent 执行编译为可复用 Harness

[ARE404]

背景

一个值得引入 Maka 的能力是：把一次或多次已经跑通的 Agent 执行，固化成可复用、可验证、可版本化的 Harness。

这里的“编译”不是读取或保存模型的隐藏思维链，而是从可观察执行事实中提取稳定结构：用户目标、工具调用、输入输出、依赖顺序、状态、权限、错误处理和验收条件。

可以概括为：

让模型先解决“不确定该怎么做”的问题；当做法稳定后，把确定性部分交给程序，只把必要的语义判断留给 LLM，高风险决定留给人。

典型场景包括日报、信息聚合、日志分析、PR 检查、数据清洗、固定浏览器流程和项目发布流程。

它与现有 AHE 的区别

AHE 和 Harness Compiler 可以共享证据与评估基础设施，但优化对象不同：

维度	AHE	Harness Compiler
优化对象	Maka 自身：system prompt、工具契约、上下文和权限策略等	用户的某个具体工作流程
输入	多次任务的成功/失败证据与评测结果	一次或多次具体执行轨迹、用户规则和样例
输出	Change Manifest、候选 patch、新 target snapshot	HarnessSpec、Skill、脚本或 Rive Workflow
目标	让未来的 Agent 更可靠	让重复任务不再需要 Agent 全程重新推理
验证	baseline/candidate 独立评测与回归检查	fixtures 回放、shadow run、断言和人工发布

一句话：

AHE 把经验编译成新版 Agent；Harness Compiler 把经验编译成可重复执行的工作程序。

二者应该是独立模块，共用 Execution Evidence、lineage、snapshot、candidate/stable、回放和 rollback 等 primitives。AHE 不应静默修改用户已经发布的 Harness，Harness Compiler 也不应获得修改 Maka 自身的 authority。

为什么 Maka 适合做

当前架构已经具备主要地基：

• Runtime Events 记录用户输入、工具调用与结果、错误、权限决定和 durable tool dispatch；
• Execution Evidence Spine 能把结论绑定到具体 Session、AgentRun、Runtime Event coverage 和 Workspace revision；
• AHE 已建立 evidence → candidate → independent evaluation → keep/discard 的外循环；
• Rive 已被定位为显式步骤、恢复、重试和分布式 workflow 的 authority；
• Automation 可以负责定时触发，但不需要变成 workflow engine；
• Skill 可以承载仍需 Agent 主导的轻量流程。

因此不需要再造 Runtime 或 Task Ledger。缺少的是中间的 Harness Compiler 与发布生命周期。

建议的核心抽象

先定义与执行目标无关的 HarnessSpec，再通过 adapter 降低到 Skill、Script、Rive 或 Automation binding。

id: twitter-tech-daily
version: 1

inputs:
  date: date
  account: string

steps:
  - id: fetch_likes
    kind: deterministic
    tool: twitter.list_likes
    pagination: until_anchor

  - id: classify
    kind: llm
    input: ${fetch_likes.items}
    output_schema: TechClassification

  - id: update_state
    kind: deterministic
    operation: atomic_replace

approvals:
  - before: publish_external

assertions:
  - links_are_valid
  - report_date_matches_input
  - review_item_count == 3

建议的目标 adapter：

• Skill：主要是提示词、规则和人工步骤；
• Script：完全确定的数据处理，运行时可以零 Token；
• Rive：包含显式依赖、并行、重试、恢复或多个 worker；
• Automation binding：定义何时触发已发布 Harness；
• Hybrid：程序控制流中只保留少量 LLM 节点和人工批准节点。

发布生命周期

单次成功执行不足以证明流程稳定，因此建议分级：

1. observed：只观察到一次成功轨迹；
2. candidate：完成参数化并生成测试；
3. verified：通过历史数据回放；
4. shadowed：在真实输入上以只读或 dry-run 方式验证；
5. published：允许日常或定时执行；
6. stale：工具、模型、schema、权限或依赖发生变化，需要重新验证。

编译和发布必须保持分离。生成候选的模型不能单独宣布候选已经通过验证。

建议的第一个 vertical slice

第一版不追求“任意对话一键生成任意程序”，只实现一条窄而完整的路径：

1. 用户在一个已完成 Turn 上选择“固化为 Harness”；
2. Maka 从 Runtime Events 生成经过脱敏的 execution projection；
3. 模型生成 HarnessSpec Draft，并明确标出固定值、输入变量、确定性步骤、LLM 步骤、人工批准和未确认假设；
4. 默认生成可审查的 Workspace-local Skill、TypeScript 脚本与 fixtures；
5. 使用历史工具结果离线回放；
6. 用户确认后发布；
7. 后续增加 Rive target 和 Automation binding。

首批建议只支持低风险、可回放任务，例如信息收集、报告生成、文件扫描、数据清洗、日志分类和 PR 检查。会发消息、删除数据、付款或修改生产系统的 Harness 不应自动发布。

建议的模块 seam

可以新增独立的 @maka/harness，保持一个小 interface：

draftHarness(evidence, intent): HarnessCandidate
verifyHarness(candidate, corpus): HarnessVerification
publishHarness(candidate, target): PublishedHarness

内部包含 trace projection、参数化、HarnessSpec validation、目标 adapter、回放、版本与发布逻辑。Task Ledger 继续保持 advisory task state；Rive 继续拥有 workflow state；Runtime Events 继续拥有执行事实。

希望讨论的问题

1. HarnessSpec 应该是 Maka 自有 IR，还是直接以 Rive workflow package 为主格式？
2. 第一个输出目标应优先选择 Skill + TypeScript，还是直接落到 Rive？
3. 一次成功轨迹是否只允许生成 observed Draft？进入 verified 至少需要多少独立样例？
4. replay corpus 应保存完整工具结果、脱敏 fixture，还是仅保存 digest-bound artifact refs？
5. 工具 schema、模型或权限变化后，哪些变化应自动把 Harness 标记为 stale？
6. Workspace-local Harness 的默认存储和版本管理位置应该在哪里？

如果方向认可，下一步可以先写一个 ADR 和 HarnessSpec v0，再实现“completed Turn → reviewable Draft → offline replay report”的最小闭环。

[Astro-Han]

Thanks for writing this up in such detail — the goal is right, and it's the same one behind how we measure the product: a task you run a hundred times shouldn't make the model reason it out a hundred times. That's cost.

I think Skill already covers most of it, though. A Skill carries allowed-tools and required-tools for the permission boundary, sourceVersion and contentSha256 for versioning and content identity, and its body carries the steps, ordering, error recovery, and acceptance conditions. The deterministic part becomes a script, and the Skill tells the model when to run it — one dispatch, no re-derivation of the workflow.

Three things in the "existing foundation" section don't match what's on main, and I think they make the proposal look larger than it needs to be:

• Execution Evidence Spine — no match anywhere in the source or docs. What exists is narrower: memory-extraction-evidence.ts, bounded-evidence.ts.
• AHE — the only occurrence in the repository is one RFC under docs/local/, which describes "AHE-style" and "AHE-inspired" observability. It is a reference concept we borrowed, not a loop we built.
• Rive — in docs/agent-swarm.md:122 it appears in the table of things Maka deliberately does not own: Explicit workflow steps, arbitrary workflow resume, or distributed execution | Rive | Workflow state and recovery need a dedicated workflow authority. It is a designated future authority, not existing ground to build on.

So as written, this adds a HarnessSpec language, a compiler, a release lifecycle, and four adapters on top of three systems that don't exist yet.

What I think is genuinely missing is much smaller: generating a Skill draft from an execution trace. The Runtime Event log already holds the tool calls, ordering, results, and permission decisions; turning a successful run into a Skill body plus a script is a feature, not a subsystem. It also gives you something to measure — if the generated Skill doesn't actually reduce cost on a repeat run, the larger design wouldn't have either.

Would you be interested in starting there?

简体中文

谢谢你写得这么详细 —— 目标是对的，而且它和我们衡量产品的方式是同一件事：一个跑一百次的任务，不该让模型推理一百次。这就是成本。

不过我认为 Skill 已经覆盖了其中大部分。Skill 带 allowed-tools 和 required-tools 作为权限边界，带 sourceVersion 和 contentSha256 做版本和内容标识，正文承载步骤、顺序、错误恢复和验收条件。确定性部分写成脚本，Skill 负责告诉模型什么时候跑它 —— 一次分发，不需要重新推导整个流程。

「现有地基」那一节里有三处和 main 上的情况不符，我觉得正是它们让这个提案显得比实际需要的大：

• Execution Evidence Spine —— 源码和文档里零命中。实际存在的要窄得多：memory-extraction-evidence.ts、bounded-evidence.ts。
• AHE —— 全仓唯一一处出现在 docs/local/ 的一份 RFC 里，写的是 "AHE-style"、"AHE-inspired" 的可观测性。它是我们借鉴的外部概念，不是我们建成的外循环。
• Rive —— 在 docs/agent-swarm.md:122，它出现在「Maka 刻意不拥有」的那张表里：Explicit workflow steps, arbitrary workflow resume, or distributed execution | Rive | Workflow state and recovery need a dedicated workflow authority. 它是被指定的未来 authority，不是可以往上盖的现成地基。

所以照现在的写法，这是在三个还不存在的系统之上，再加一套 HarnessSpec 语言、一个编译器、一套发布生命周期和四个 adapter。

我认为真正缺的东西小得多：从执行轨迹生成 Skill 草稿。Runtime Event 日志里已经有工具调用、顺序、结果和权限决定；把一次成功的执行变成一份 Skill 正文加一个脚本，这是一个功能，不是一个子系统。而且它立刻可衡量 —— 如果生成出来的 Skill 在重复执行时并没有降低成本，那更大的那套设计也不会。

有兴趣从这里开始吗？

[jiengup]

This is an interesting proposal, and I have also thought about similar issues before. After all, before the emergence of large models, we entered the information age relying solely on deterministic automation programs, so in most scenarios, repetitive work is valuable.

However, the difficulty here lies in defining the boundary between model decision-making and the固化 harness. If the goal is just to "repeat" certain processes, is it enough for an agent to dump a script? And if it's a process with many decision points, that also means different decisions at different points can lead to completely different branches, and I don't think this can be solidified. Although Maka has very fine-grained event logs, they are just a single execution path after all.

If the functionality we want is between the two, perhaps as @Astro-Han suggested, dumping a skill and solidifying the decision-making process of the agent may be enough, although this is not an elegant behavior from an engineering perspective, but it may be a solution for scenarios involving probabilistic

中文

这是一个很有趣的提案，我之前也思考过类似的问题，毕竟在大模型出来之前，我们仅靠着确定性的自动化程序进入了信息时代，因此大部分场景下， 重复的工作是有价值的。

但是这里的难点在于，要如何定义模型决策和固化的harness之间的边界，如果只是希望能“重复“某些流程，是否由 agent dump 一个脚本就够了呢？而如果是一个有很多决策点的流程，那也代表不同决策点的决策会导致截然不同的分支，我不认为这是可以固化的。尽管 maka 有非常精细的 event log，但那也只是一次执行轨迹而已。

如果我们要的功能处于两者之间，或许像 @Astro-Han 所说的，dump 一个 skill，固化住 agent 的决策过程可能就足够了，虽然这在工程角度看来不是一个优雅的行为，但可能是概率性推理的场景下的解法了。