我的最大启发是：

> **Coding agent harness 不应该被设计成“流程编排器”，而应该被设计成一个面向不完全确定智能体的“分层反馈控制系统”。**  
> Agent 是主控制器，harness 是观测器、约束器、安全联锁和人机协同外环；人是慢速高价值反馈源，而不是每一步的按钮审批员。

下面把钱学森《工程控制论》的思想映射到 coding agent harness。

---

## 1. 把 coding agent 看成控制系统

可以这样建模：

| 控制论概念 | Coding agent harness 中的对应物 |
|---|---|
| 参考输入 `r` | 用户任务、issue、acceptance criteria |
| 被控对象 `P` | 代码库、sandbox、测试环境、CI、依赖系统 |
| 控制器 `C` | Agent kernel，自主决定 workflow |
| 执行器 | edit、patch、bash、test、git、PR 等工具 |
| 输出 `y` | diff、测试结果、lint、typecheck、CI、PR 状态 |
| 误差 `e` | 当前实现与目标之间的差距 |
| 反馈 | 测试结果、编译错误、review comment、CI failure |
| 扰动 `d` | 需求不清、隐藏依赖、flaky test、LLM 幻觉、环境不一致 |
| 观测器 | run state、trajectory log、failure ledger、risk estimator |
| 人类外环 | reviewer、approver、product/architecture decision maker |

所以 agent harness 的本质不是：

```text
step1 -> step2 -> step3 -> step4
```

而是：

```text
目标 -> agent 决策 -> 工具动作 -> 环境反馈 -> 状态估计 -> 自修复/升级/继续
```

也就是一个闭环系统。

---

## 2. “稳定性第一”：自治必须有边界

钱学森强调控制系统首先要稳定。对应到 coding agent，稳定性不是数学上不发散，而是：

- 不无限循环；
- 不越改越大；
- 不为了修一个测试破坏更多模块；
- 不绕过测试；
- 不修改敏感路径；
- 不擅自 merge / deploy；
- 不把不确定性伪装成完成。

因此 harness 里应该有一个 **Progress / Stability Monitor**。

可以定义一个类似 Lyapunov 函数的风险-误差度量：

```text
V = 
  w1 * 未满足验收条件数量
+ w2 * failing checks 数量
+ w3 * diff 范围复杂度
+ w4 * 风险路径修改程度
+ w5 * 未验证假设数量
+ w6 * retry 消耗
+ w7 * agent 自信度不足
```

每轮 agent 动作之后，harness 评估：

```text
V 是否下降？
风险是否扩大？
是否触碰 hard constraint？
是否进入重复失败模式？
```

如果 `V` 连续几轮不下降，就不应该继续让 agent 盲目修，而应进入：

1. 缩小问题；
2. 回滚到 checkpoint；
3. 重新计划；
4. 请求 human review。

这就是控制论里的稳定性约束。

---

## 3. “反馈是灵魂”：测试、CI、review 都是反馈信号

Coding agent 最大的错误设计，是把 LLM 当成一次性生成器。

控制论视角下，它必须是反馈驱动的：

```mermaid
flowchart LR
  Goal[Task / Acceptance Criteria] --> Agent[Agent Controller]
  Agent --> Action[Tool Action / Patch]
  Action --> Env[Repo / Sandbox / CI]
  Env --> Feedback[Test / Lint / Diff / Error]
  Feedback --> Observer[State Estimator]
  Observer --> Agent
```

因此 harness 应该强制 agent 不断回答：

- 当前目标是什么？
- 现在观察到了什么？
- 哪个假设被证实？
- 哪个假设被推翻？
- 下一步实验是什么？
- 当前风险是否变大？
- 是否需要人类判断？

这就是我之前提到的 **Self-Reflection Ledger**。它不是让模型暴露完整思维链，而是保存工程化状态摘要：

```ts
type ReflectionLedger = {
  current_goal: string;
  observed_facts: string[];
  assumptions: {
    text: string;
    confidence: "low" | "medium" | "high";
    evidence?: string;
  }[];
  failed_attempts: {
    action: string;
    result: string;
    suspected_cause: string;
  }[];
  next_experiment: string;
  risk_change: "lower" | "same" | "higher";
  need_human?: {
    reason: string;
    decision_needed: string;
  };
};
```

这相当于 agent 的“状态估计器”。

---

## 4. “不完全确定系统”：LLM agent 天然就是不确定控制对象

钱学森特别关注不完全确定系统，这一点对 agent harness 极其关键。

Coding agent 面临的不确定性包括：

| 不确定性 | 表现 |
|---|---|
| 需求不确定 | issue 写得模糊，验收标准缺失 |
| 环境不确定 | 本地测试和 CI 不一致 |
| 代码库不确定 | 隐藏约定、文档过期、历史 debt |
| 模型不确定 | hallucination、过度自信、上下文遗漏 |
| 工具不确定 | flaky test、package install 失败 |
| 人类偏好不确定 | reviewer 风格、架构偏好、产品取舍 |

所以 harness 要走 **鲁棒控制** 思路：

- 默认不信单一信号；
- 测试、静态分析、diff review 多重验证；
- 对高风险动作加安全裕度；
- 对不确定需求要求 human clarification；
- 对失败修复设置 retry budget；
- 对 agent confidence 低的地方自动升级；
- 对敏感路径使用更严格 policy。

核心不是让 agent 永远正确，而是让系统在 agent 不完全可靠时仍然整体可靠。

---

## 5. “可观测性”：看不见就无法控制

如果 harness 不能观察 agent 的状态，就无法安全放权。

所以每个 run 至少要观测：

- agent 看过哪些文件；
- 为什么认为这些文件相关；
- 改了哪些文件；
- diff 范围多大；
- 跑了哪些测试；
- 哪些测试失败；
- 是否新增测试；
- 是否触碰 protected path；
- 是否出现循环行为；
- 是否修改了任务目标；
- 是否有未验证假设。

一个很重要的判断：

> 如果 acceptance criteria 没有对应的可观测验证方式，这个任务对 agent 来说就是“不可观测系统”。

此时 agent 不应该强行完成，而应该：

1. 先补测试；
2. 生成验证计划；
3. 请求人类确认验收标准；
4. 或把 PR 标记为需要人工重点 review。

---

## 6. “可控性”：agent 不是万能控制器

控制论里，系统可控才谈得上控制。

对应到 coding agent：

- 如果工具权限不够，agent 不可控；
- 如果没有测试命令，质量不可控；
- 如果依赖服务无法启动，验证不可控；
- 如果任务涉及产品决策，agent 不可控；
- 如果需要线上数据但无安全访问方式，agent 不可控；
- 如果修改范围超出 policy，agent 不可控。

所以 harness 应该有一个 **controllability check**：

```text
这个任务是否能在当前 sandbox + 当前工具 + 当前权限 + 当前验证手段下完成？
```

如果不能，agent 应该升级，而不是乱试。

---

## 7. “采样控制”：不是每一步都让人看，而是在关键采样点介入

采样控制思想非常适合 human-in-the-loop。

人不应该连续介入，因为人类反馈成本高、速度慢。应该采用 **事件触发式采样**：

### 自动运行的采样点

- 每次工具调用后记录 observation；
- 每次 patch 后更新 diff summary；
- 每次测试后更新 failure ledger；
- 每次 commit 后记录 checkpoint。

### 需要人类采样的关键点

- 修改 protected path；
- 新增依赖；
- 修改数据库 schema；
- 修改 auth/payment/security；
- 扩大 scope；
- 多次 auto-repair 失败；
- 需要产品/架构取舍；
- 准备从 draft PR 转 ready；
- 最终 merge。

这就符合你的要求：

> 人在 loop，但主要是 review，不是所有步骤都审批。

---

## 8. “分层控制”：agent 主导 workflow，harness 控制边界，人类控制方向

我建议采用三层控制结构。

```mermaid
flowchart TD
  Human[Human Supervisor<br/>目标/取舍/最终 review] --> Harness[Harness Supervisor<br/>policy/risk/checkpoint]
  Harness --> Agent[Agent Controller<br/>自主 workflow]
  Agent --> Tools[Tools / Actuators]
  Tools --> Repo[Repo / Sandbox / CI]
  Repo --> Observer[Observer / Feedback]
  Observer --> Agent
  Observer --> Harness
  Harness --> Human
```

### 第一层：agent 内环

高频、自动、自主。

负责：

- 查代码；
- 制定计划；
- 修改代码；
- 运行测试；
- 修复失败；
- 写 PR summary。

### 第二层：harness 监督环

中频、规则化、确定性。

负责：

- policy gate；
- risk scoring；
- checkpoint；
- retry budget；
- sandbox isolation；
- allowed/ask/deny；
- trajectory logging。

### 第三层：human 外环

低频、高价值。

负责：

- 需求澄清；
- 架构选择；
- 风险确认；
- review；
- merge；
- 事后调整 policy。

这样 agent 仍然是 workflow 的主导者，但系统整体不会失控。

---

## 9. “模型即对象”：agent 操作的不是代码，而是代码系统的模型

钱学森强调数学建模。对 coding agent harness 来说，不能只给 agent raw repo。

应该维护多个模型：

```text
Task Model       任务目标、验收条件、非目标
Repo Model       模块、依赖、owner、protected path
Risk Model       哪些改动危险，哪些需要审批
Progress Model   当前完成度、失败点、剩余 gap
Context Model    相关文件、相关 symbol、调用链
Human Model      reviewer 偏好、项目规范、历史反馈
```

Agent 每一步不是“凭感觉写代码”，而是在这些模型上做决策。

这也解释了为什么 `AGENTS.md` 很重要。它相当于这个控制系统的局部参数配置：

```md
# AGENTS.md

## Build
pnpm test
pnpm typecheck

## Protected areas
Ask before editing:
- auth/**
- payments/**
- infra/**
- migrations/**

## Review expectations
- Add tests for bug fixes
- Keep PR small
- Do not introduce new dependency without approval
```

---

## 10. “从特殊到一般，再回到特殊”：harness 要沉淀通用控制规律

钱学森的技术科学路径对 harness 设计很有启发：

1. 从具体 repo、具体 bug、具体 PR 中观察 agent 失败模式；
2. 抽象出通用策略；
3. 写入 harness policy、eval、tool design；
4. 再回到具体 repo 中应用。

例如：

| 具体失败 | 抽象规律 | harness 改进 |
|---|---|---|
| agent 改太多文件 | scope 失控 | diff budget + risk escalation |
| agent 反复修同一测试 | 闭环振荡 | retry cap + replan gate |
| agent 绕过测试 | 目标函数错误 | forbid disabling tests |
| agent 不理解 repo 惯例 | 模型不完整 | AGENTS.md + repo memory |
| agent 看不到 CI 差异 | 观测不足 | CI feedback ingestion |
| reviewer 总提同类意见 | 人类反馈未沉淀 | review comment classifier |

这样 harness 会越用越强，而不是每次从零开始。

---

## 11. “最优控制”：优化目标不是只让 agent 完成任务

Agent harness 的目标函数不应该是：

```text
maximize task completion
```

而应该是多目标优化：

```text
maximize correctness
minimize risk
minimize unnecessary human interruption
minimize diff size
minimize time
minimize cost
maximize maintainability
maximize reviewer trust
```

也就是说，agent 不是“尽快写完代码”，而是要在约束下找到最优控制策略。

例如：

- 低风险文档修改：agent 可以直接改、测试、开 draft PR；
- 中风险 bug fix：agent 自动修，但必须跑测试；
- 高风险 auth 修改：先生成方案，请人 review，再动手；
- 需求不清：不要写代码，先 ask human；
- CI 多次失败：不要继续乱修，生成 failure report。

---

## 12. 可以把 harness 重构成这几个控制论模块

我会在原架构上增加这些模块：

```text
1. Reference Manager
   管理任务目标、验收标准、非目标。

2. Observer / State Estimator
   从工具输出、diff、测试、CI 中估计当前状态。

3. Agent Controller
   由 agent 自主决定下一步 workflow。

4. Supervisory Controller
   harness 的确定性控制层：allow / ask / deny。

5. Stability Monitor
   检测循环、发散、scope creep、风险上升。

6. Repair Controller
   管理自动修复、retry budget、rollback。

7. Human Feedback Interface
   在关键节点请求 review、approval、clarification。

8. Learning / Identification Loop
   从历史 run 中更新 policy、AGENTS.md、eval。
```

核心循环可以是：

```python
while not done:
    y = observe_workspace()
    x = estimate_state(y)
    e = compare_with_acceptance_criteria(x, task)
    V = compute_progress_risk_score(x, e)

    if violates_hard_constraints(x):
        rollback_or_stop()
        ask_human()

    if not observable(task, x):
        agent.add_tests_or_request_clarification()

    if not controllable(task, tools, policy):
        escalate_to_human()

    action = agent.decide_next_action(
        task=task,
        state=x,
        error=e,
        risk=V,
        available_tools=tools,
    )

    gate = supervisor.evaluate(action, state=x, risk=V)

    if gate == "allow":
        result = execute(action)
    elif gate == "ask":
        result = ask_human_with_evidence_pack(action, x)
    else:
        result = deny_and_return_reason(action)

    update_state(result)

    if progress_not_improving_for_n_steps():
        replan_or_revert_or_escalate()
```

---

## 13. 最重要的架构启发

我会把这句话作为设计原则：

> **让 agent 自主，不等于让系统无控制；真正的自治来自闭环反馈、状态观测、稳定性约束和分层监督。**

所以，最好的 coding agent harness 不是一个强行规定 agent 每一步怎么做的 workflow engine。

它应该是：

```text
一个面向不完全确定智能体的工程控制系统。
```

其中：

- agent 决定 workflow；
- harness 提供可观测性、可控性、稳定性；
- tests/CI/review 提供反馈；
- human 是外环监督者；
- policy 是安全边界；
- checkpoint/rollback 是稳定机制；
- failure ledger 是系统自省；
- eval 和历史轨迹是系统学习。

一句话总结：

> **用钱学森控制论思想看，coding agent harness 的核心不是“编排 agent”，而是“控制 agent 所在的工程闭环”：让 agent 在反馈中自主决策，在约束中自动修复，在关键节点接受人的高价值校正。**