diff --git a/README.md b/README.md index 901f9b4..a7a201a 100644 --- a/README.md +++ b/README.md @@ -442,6 +442,8 @@ Override with environment variables: `SUPERVISOR_SURFACE_TYPE`, `SUPERVISOR_SURF ## Design Philosophy +> **Foundational stance**: see [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) — why thin-supervisor watches but does not orchestrate. + Inspired by [Anthropic's Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents): 1. **The system's memory lives in SessionRun, not in the model's context.** Crashes don't lose history. Everything is in `session_log.jsonl`. diff --git a/docs/PHILOSOPHY.md b/docs/PHILOSOPHY.md new file mode 100644 index 0000000..6f71905 --- /dev/null +++ b/docs/PHILOSOPHY.md @@ -0,0 +1,95 @@ +# thin-supervisor 的哲学 + +## 核心公理 + +**Worker 足够强。** + +我们不是在构建一个"让弱 agent 变强"的脚手架,而是在构建一个"让强 agent 可被信任"的见证人。 + +这是一个赌。赌的是 coding agent 的能力在持续变强,不是停滞。过去两年每一次模型升级,agent 自己的规划、拆分、排序能力都在压过外部脚手架。我们选站在趋势这边。 + +所有试图"替 agent 规划"的层,迟早会变成冗余——它们的决策质量早晚低于 agent 本身。 + +## 三件事,仅此而已 + +Worker 够强,意味着它能自己规划、自己决定下一步、自己写代码。这些**我们不介入**。我们只在三个时刻在场: + +1. **该停的时候让它停** — 当它要做不可逆或越权的事 +2. **该走的时候让它走** — 当它在问"要不要继续"但答案显然是 yes +3. **说交付时替它判一下** — 因为"我做完了"是它结构性有偏的唯一判断 + +这三件事有一个共同点:**它们都是 worker 结构性做不好的事,不是能力问题,是位置问题。** + +## 为什么只 gate,不 orchestrate + +Agent 的**能力**和**偏差**是两件不同的东西。能力随模型进步而长,偏差不会。 + +- 规划、拆分、排序、选库——这些是**能力题**。Agent 越强做得越好,我们掺一脚只会拖后腿。 +- "我能做这个吗?""我做完了吗?""这是安全的吗?"——这些是**位置题**。它站在自己的位置上,永远有把答案说成 yes 的结构性压力。 + +**编排是对能力题的外包;gate 是对位置题的纠偏。** + +前者会被能力增长蚕食,后者不会。模型再强,**它也没法同时当裁判和选手**——这是结构决定的,不是水平决定的。 + +这就是为什么我们不做 plan 拆分、不做多 agent 编排、不做 context 管理。那些都是能力题,**agent 自己做只会越做越好**。而 gate 和 acceptance,agent 永远替代不了自己。 + +## "薄"不是代码少,是信任密度高 + +"thin" 真正的意思是**信任密度**。 + +- **Fat supervisor** = 不信任 worker,每一步都要我过一遍。它假设 worker 是需要监工的实习生。 +- **Thin supervisor** = 信任 worker 的执行,但不信任它的自我评价。它假设 worker 是需要审计的专家。 + +这两者对能力增长的响应完全相反: + +- Worker 变强 → **fat supervisor 价值下降**(实习生长大了,监工就多余了) +- Worker 变强 → **thin supervisor 价值不变甚至上升**(专家水平越高,交付验收越重要——你越没法凭"看起来对"来判断它做对没做对) + +Fat 是在对冲 agent 的弱,强到一定程度就没对冲对象了。Thin 是在对冲 agent 的结构性偏差,agent 再强这个偏差也还在。 + +## Gate vs. Drive:两种根本不同的东西 + +| Orchestrator | Supervisor | +|---|---| +| 主动推动 | 被动制动 | +| Happy path 里一直在 | Happy path 里近乎透明 | +| 输出计划 | 输出证据 | +| 决策驱动 | 契约驱动 | +| 和 agent 同构(都在做 LLM 推理) | 和 agent 异构(做确定性验证) | + +一个好的 supervisor 在 90% 的时间里什么都不做。它像车上的 ABS——平时意识不到它存在,只在需要紧急制动时才显形。 + +**推的东西会越来越像 agent 本身**,所以推的东西注定被 agent 淘汰。**制动的东西永远是外部的**,所以它不会被 agent 淘汰。 + +## 我们不是什么(via negativa) + +克制的难处在于**每一个诱惑看起来都合理**。这些事我们明确**不做**: + +- 不当 coach(不教 agent 怎么做) +- 不当 planner(不替它排顺序) +- 不当 editor(不改它的 prompt) +- 不当 PM(不跟踪里程碑) +- 不当 context engineer(不管它 context 怎么用) + +我们只是一个**闸门 + 黑匣子**: + +- 闸门在边界上断路 +- 黑匣子 durable、append-only、可审计 + +**飞机的黑匣子不会告诉飞行员怎么飞。**它只在事后告诉你发生过什么。这是一个特性,不是缺陷。 + +## 克制是这个项目最难的工程 + +能做的功能总是容易的。**不做是难的。** + +每次看到漂亮的"协作"或"编排"功能,都会有"我们也搞一个"的冲动。**抵抗这个冲动是这个项目的核心工程能力**,不是写代码的能力。 + +理由很冷酷:**每加一层都是一次 LLM 调用,每一次 LLM 调用都可能出错。** 你为了修 LLM 的错而加的层,本身也是 LLM。加层的边际收益递减,边际成本不减。 + +唯一打破这个递减规律的层是**确定性验证层**:跑测试、查文件、看 git 状态、hash 比对。这一层的可靠性不依赖 LLM。 + +**这是我们唯一愿意往里加东西的地方。** + +## 一句话 + +> 强 worker 需要的不是更好的教练,是更严格的裁判。