Skip to content

Harness engineering beginner tutorial, from 0 to 1

Attribute VILA Lab versioned claims; polish zh-TW harness-designs (#74)

Alec Chenc9773c6b581d
diff --git a/docs/en/harness-designs/claude-code/index.md b/docs/en/harness-designs/claude-code/index.md
index 000854d..1b5ad95 100644
--- a/docs/en/harness-designs/claude-code/index.md
+++ b/docs/en/harness-designs/claude-code/index.md
@@ -28,7 +28,7 @@ These four scopes form an **instruction hierarchy**: the official documentation
## Context Subsystem: A Five-Layer Compaction Pipeline
-Claude Code manages context through a **five-layer compaction pipeline**, not simply by "summarizing when it gets full." This architectural detail comes from VILA Lab's source-level analysis, [Dive into Claude Code](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). Lecture 5 explains how long-running tasks lose continuity; Claude Code's answer is a multi-stage funnel: first apply lossless pruning (removing redundant tool results), then perform structured distillation, and only then use lossy LLM summaries, with circuit breakers to prevent excessive compaction.
+According to VILA Lab's source-level analysis of Claude Code v2.1.88, [Dive into Claude Code](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf), the system used a **five-layer compaction pipeline** at that time, not simply by "summarizing when it gets full." Lecture 5 explains how long-running tasks lose continuity; Claude Code's answer is a multi-stage funnel: first apply lossless pruning (removing redundant tool results), then perform structured distillation, and only then use lossy LLM summaries, with circuit breakers to prevent excessive compaction.
This is paired with the design of session storage: **append-oriented storage**. All history is appended to `history.jsonl`, with `/resume` recovery and fork branches. This ensures that "every session leaves a good handoff before ending"—not because the system has a good memory, but because the storage layer is append-oriented and replayable.
@@ -47,7 +47,7 @@ The key design is **separation of responsibilities**: CLAUDE.md manages "what,"
Lecture 10 explains that "verification only counts when the complete flow works." Claude Code implements this through two tracks:
-**1. Permission system (deterministic constraints).** Claude Code's permissions do not simply "ask about everything." They combine seven modes with an ML-based classifier: low-risk operations are allowed, while high-risk operations are either confirmed or denied according to policy (for architectural details, see the [VILA Lab analysis](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). This turns "setting clear task boundaries for the agent" (Lecture 7) into runtime enforcement instead of a plea in a prompt.
+**1. Permission system (deterministic constraints).** Claude Code's permissions do not simply "ask about everything." According to VILA Lab's analysis of v2.1.88, the system combined seven modes with an ML-based classifier at that time: low-risk operations are allowed, while high-risk operations are either confirmed or denied according to policy (for architectural details, see the [VILA Lab analysis](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Note that permission-mode naming has changed since v2.1.88: current Anthropic docs ([permission modes](https://code.claude.com/docs/en/permission-modes)) list Manual (formerly "default", relabeled in v2.1.200+), Plan, acceptEdits, Auto, and bypassPermissions. This turns "setting clear task boundaries for the agent" (Lecture 7) into runtime enforcement instead of a plea in a prompt.
**2. Hooks (preventing premature declarations of completion).** `PostToolUse` hooks can force checks to run after tool execution and write the results back into the context; `Stop` hooks intervene when the agent declares completion. This separates "the one doing the work" from "the one checking the work." [Anthropic explicitly observed in its harness article](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) that agents "confidently praised their work," so hooks inject **deterministic** checks instead of trusting the model's self-evaluation.
@@ -64,7 +64,7 @@ Claude Code's logs are complete append-oriented records (history.jsonl). Togethe
| Instructions | Layered scopes (organization/user/project/local) + auto memory | Layered memory is the benchmark implementation |
| Tools | Four extension types: Skills + MCP + hooks + subagents | Clear separation of responsibilities is a core strength |
| Environment | In-project settings + settings.json | Relies on users to describe the environment in CLAUDE.md |
-| State | Append-oriented session storage + five-layer compaction + resume/fork | Extremely strong; a reference implementation for long-running task continuity |
+| State | Append-oriented session storage + five-layer compaction (per VILA v2.1.88 analysis) + resume/fork | Extremely strong; a reference implementation for long-running task continuity |
| Feedback | Permission classifier + mandatory checks through PostToolUse hooks | Turns "prevent premature declarations of completion" into a deterministic mechanism |
## Designs Worth Adopting
@@ -75,14 +75,22 @@ Claude Code's logs are complete append-oriented records (history.jsonl). Togethe
4. **Isolate subagent context**: split the context when splitting a task so subtask results do not pollute the main loop.
5. **Make session storage append-oriented and replayable**: handoffs depend on the storage layer, not memory.
-## References (Original Sources / Source Code)
+## References
-Every claim can be traced back to the original sources or source code below, avoiding secondhand recollections:
+Every claim can be traced back to the sources below, avoiding secondhand recollections.
+
+### Official Anthropic documentation
- **Claude Code · Memory**: A fresh context for every session, the four CLAUDE.md scopes, on-demand loading by subdirectory, auto memory (200 lines / 25KB), and `/init` generation of CLAUDE.md.<br/>https://code.claude.com/docs/en/memory
-- **Claude Code · Skills / MCP / Hooks / Sub-agents**: Definitions of the four extension mechanisms and their events (PreToolUse / PostToolUse / Stop).<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents
-- **VILA Lab, Dive into Claude Code** (source-level analysis): The five-layer compaction pipeline, seven permission modes + ML classifier, sidechain subagents, and append-oriented session storage in history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf
+- **Claude Code · Skills / MCP / Hooks / Sub-agents**: Definitions of the four extension mechanisms and their events (PreToolUse / PostToolUse / Stop).<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents
+- **Claude Code · Permission modes**: Current mode names Manual (formerly "default", relabeled in v2.1.200+), Plan, acceptEdits, Auto, and bypassPermissions.<br/>https://code.claude.com/docs/en/permission-modes
- **Anthropic, Effective harnesses for long-running agents**: The source for the claims that "reliability comes from the harness rather than the model," that agents "confidently praised their work," and that hooks should be used for verification.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
+
+### Independent/community research
+
+The sources in this group reflect a specific historical version (Claude Code v2.1.88 at the time of the VILA Lab analysis) and may not match current behavior.
+
+- **VILA Lab, Dive into Claude Code** (source-level analysis of v2.1.88): The five-layer compaction pipeline, seven permission modes + ML classifier, sidechain subagents, and append-oriented session storage in history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf
- **Claude Code Full Stack Guide** (community guide to the CLAUDE.md / Skills / MCP / Subagents / Hooks layers): Supplementary reading on the separation of responsibilities among extension mechanisms.<br/>https://jsmanifest.com/claude-code-full-stack-guide
Related lectures: [Lecture 3 · Why the Repository Must Become the System of Record](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Lecture 9 · Why Agents Declare Victory Too Early](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [Lecture 10 · Why End-to-End Testing Changes Results](../lectures/lecture-10-why-end-to-end-testing-changes-results/)
diff --git a/docs/zh-TW/harness-designs/claude-code/index.md b/docs/zh-TW/harness-designs/claude-code/index.md
index a126ff3..770a868 100644
--- a/docs/zh-TW/harness-designs/claude-code/index.md
+++ b/docs/zh-TW/harness-designs/claude-code/index.md
@@ -1,16 +1,16 @@
# 拆解 Claude Code 的 harness 設計
-Anthropic 在《[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)》中明確提出:可靠性來自 harness 而不是模型,agent 需要在「模型之外」受到約束。Claude Code 就是這個思路的產品化範例,Anthropic 官方也直接把它歸入 **agentic harness** 的範疇。這不是行銷話術——Claude Code 可能是目前公開拆解得最透徹的 harness:原始碼公開、社群研究報告詳盡,而且它把課程講義裡幾乎所有核心機制(分層記憶、上下文壓縮、permissions、hooks、subagent、session 持久化)都做成完整的產品化實作。
+Anthropic 在《[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)》中明確提出:可靠性來自 harness 而不是模型,agent 需要在「模型之外」受到約束。Claude Code 就是這個思路的產品化範例,Anthropic 官方也直接把它歸入 **agentic harness** 的範疇。這不是行銷話術,Claude Code 可能是目前公開拆解得最透徹的 harness:原始碼公開、社群研究報告詳盡,而且它把課程講義裡幾乎所有核心機制(分層記憶、上下文壓縮、permissions、hooks、subagent、session 持久化)都做成完整的產品化實作。
這一篇我們用課程五子系統框架拆解 Claude Code,重點看它如何落實「上下文管理」「防止提前宣告完成」「確定性約束」這些 harness 的原教旨概念。
## 一句話定位
-Claude Code 的核心是一個簡單的 while 循環:呼叫模型、執行工具、觀察結果、再次呼叫模型。但**絕大部分程式碼不在這個循環裡,而是在圍繞循環的系統中**——permissions 系統、上下文壓縮管線、擴充機制、subagent 編排、session 儲存。這就是 harness 的本質:循環是骨架,骨架以外的一切才是決定可靠性的部分。
+Claude Code 的核心是一個簡單的 while 循環:呼叫模型、執行工具、觀察結果、再次呼叫模型。但**絕大部分程式碼不在這個循環裡,而是在圍繞循環的系統中**,permissions 系統、上下文壓縮管線、擴充機制、subagent 編排、session 儲存。這就是 harness 的本質:循環是骨架,骨架以外的一切才是決定可靠性的部分。
## 指令子系統:分層記憶體系
-Claude Code 的記憶系統是它對 harness 理論最直接的貢獻,對應課程中的「儲存庫即事實來源」和「跨 session 上下文連續」兩講。[官方文件《How Claude remembers your project》](https://code.claude.com/docs/en/memory)明確說明:每次 session 都從全新的上下文視窗開始,透過兩類機制跨 session 攜帶知識——CLAUDE.md 檔案(你寫的指令)和 auto memory(Claude 自己寫的筆記)。
+Claude Code 的記憶系統是它對 harness 理論最直接的貢獻,對應課程中的「儲存庫即事實來源」和「跨 session 上下文連續」兩講。[官方文件《How Claude remembers your project》](https://code.claude.com/docs/en/memory)明確說明:每次 session 都從全新的上下文視窗開始,透過兩類機制跨 session 攜帶知識,CLAUDE.md 檔案(你寫的指令)和 auto memory(Claude 自己寫的筆記)。
就作用範圍而言,官方把 CLAUDE.md 檔案分成四類(依載入順序由廣到窄):
@@ -28,15 +28,15 @@ Claude Code 的記憶系統是它對 harness 理論最直接的貢獻,對應
## 上下文子系統:五層壓縮管線
-Claude Code 對上下文的管理是一套**五層 compaction 管線**(five-layer compaction pipeline),不是「滿了就摘要」這麼簡單——這項架構細節來自 [VILA Lab 的《Dive into Claude Code》](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)原始碼層級拆解。課程第五講談「長任務會失去連續性」,Claude Code 的解法是多級漏斗:先進行無損修剪(移除冗餘工具結果),再進行結構化提煉,最後才使用有損的 LLM 摘要,並搭配熔斷機制避免過度壓縮。
+根據 VILA Lab 對 Claude Code v2.1.88 的原始碼層級拆解《[Dive into Claude Code](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)》,當時的系統採用一套**五層 compaction 管線**(five-layer compaction pipeline),不是「滿了就摘要」這麼簡單。課程第五講談「長任務會失去連續性」,Claude Code 的解法是多級漏斗:先進行無損修剪(移除冗餘工具結果),再進行結構化提煉,最後才使用有損的 LLM 摘要,並搭配熔斷機制避免過度壓縮。
-與它搭配的是 session 儲存設計:**附加導向的 session 儲存(append-oriented storage)**,所有歷史都附加寫入 `history.jsonl`,支援 `/resume` 復原和 fork 分支。這保證了「每次 session 結束前都做好交接」——不是因為記性好,而是因為儲存層採用附加方式,並且可以重播。
+與它搭配的是 session 儲存設計:**附加導向的 session 儲存(append-oriented storage)**,所有歷史都附加寫入 `history.jsonl`,支援 `/resume` 復原和 fork 分支。這保證了「每次 session 結束前都做好交接」,不是因為記性好,而是因為儲存層採用附加方式,並且可以重播。
## 工具子系統:四種擴充機制
Claude Code 把擴充介面分成四類,每一類解決一種問題,這是它的設計中最值得借鑑的部分:
-- **技能(Skills)**:[官方文件](https://code.claude.com/docs/en/skills)定義——由 `SKILL.md` 描述的程序性知識,依觸發詞自動載入,採漸進式揭露。適合「如何做某件事」的領域知識。
+- **技能(Skills)**:[官方文件](https://code.claude.com/docs/en/skills)定義,由 `SKILL.md` 描述的程序性知識,依觸發詞自動載入,採漸進式揭露。適合「如何做某件事」的領域知識。
- **MCP**:[官方文件](https://code.claude.com/docs/en/mcp)中的 JSON-RPC 協定會連接外部系統,是「讓模型的手能伸到外部世界」的標準介面。
- **hooks(Hooks)**:[官方文件](https://code.claude.com/docs/en/hooks)掛在 `PreToolUse`、`PostToolUse`、`Stop` 等生命週期事件上的確定性腳本。
- **plugin / subagent(Subagents)**:[官方文件](https://code.claude.com/docs/en/sub-agents)把複雜任務拆給專門化的 agent 執行。
@@ -47,42 +47,50 @@ Claude Code 把擴充介面分成四類,每一類解決一種問題,這是
課程第十講談「跑通完整流程才算真正驗證」,Claude Code 對應的機制是雙軌制:
-**1. permissions 系統(確定性約束)。** Claude Code 的 permissions 不是「全部都詢問一遍」,而是七種模式 + 一個基於 ML 的分類器:低風險操作放行,高風險操作則依原則詢問或拒絕(架構細節請參閱 [VILA Lab 拆解](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf))。這是把「為 agent 劃清邊界」(第七講)做成執行時期的強制機制,而不是靠提示詞懇求。
+**1. permissions 系統(確定性約束)。** Claude Code 的 permissions 不是「全部都詢問一遍」,根據 VILA Lab 對 v2.1.88 的拆解,當時的系統採用七種模式 + 一個基於 ML 的分類器:低風險操作放行,高風險操作則依原則詢問或拒絕(架構細節請參閱 [VILA Lab 拆解](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf))。注意 v2.1.88 之後 permissions 模式命名已有變動:目前官方文件([permission modes](https://code.claude.com/docs/en/permission-modes))列出 Manual(原 "default",v2.1.200+ 起改名)、Plan、acceptEdits、Auto 與 bypassPermissions。這是把「為 agent 劃清邊界」(第七講)做成執行時期的強制機制,而不是靠提示詞懇求。
-**2. hooks(防止提前宣告完成)。** `PostToolUse` hooks 可以在工具執行後強制進行檢查、把結果寫回上下文;`Stop` hooks 則在 agent 宣告完成時介入。這就是「做事的人和檢查的人分開」——[Anthropic 在 harness 文章裡明確觀察到](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents),agent 會自信地稱讚自己的工作("confidently praised their work"),因此用 hooks 注入**確定性**檢查,而不是信任模型的自我評估。
+**2. hooks(防止提前宣告完成)。** `PostToolUse` hooks 可以在工具執行後強制檢查、把結果寫回上下文;`Stop` hooks 則在 agent 宣告完成時介入。這就是「做事的人和檢查的人分開」,[Anthropic 在 harness 文章裡明確觀察到](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents),agent 會自信地稱讚自己的工作("confidently praised their work"),因此用 hooks 注入**確定性**檢查,而不是信任模型的自我評估。
**3. subagent(隔離上下文)。** 每個 subagent 的對話記錄都存在獨立的 sidechain 檔案裡,**不會膨脹父 agent 的上下文**(請參閱 [VILA Lab 拆解](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf))。這是「任務邊界」和「上下文隔離」的結合:拆分任務的同時,也隔離上下文污染。
## 可觀測性與 session 持久化
-Claude Code 的日誌是完整的附加式記錄(history.jsonl),加上 `/compact`、`/clear`、`/init` 這些明確指令,讓你能主動管理上下文狀態,而不是被動等它滿。`/init` 更是把「讓 agent 每次工作前先初始化」(第六講)做成一條指令——[官方文件](https://code.claude.com/docs/en/memory)指出,它會自動分析程式碼庫並產生初始 CLAUDE.md(包括建置指令、測試說明、工程慣例)。
+Claude Code 的日誌是完整的附加式記錄(history.jsonl),加上 `/compact`、`/clear`、`/init` 這些明確指令,可主動管理上下文狀態,而不是被動等它滿。`/init` 更是把「讓 agent 每次工作前先初始化」(第六講)做成一條指令,[官方文件](https://code.claude.com/docs/en/memory)指出,它會自動分析程式碼庫並產生初始 CLAUDE.md(包括建置指令、測試說明、工程慣例)。
## 對應到課程框架
-| 子系统 | Claude Code 的实现 | 评价 |
+| 子系統 | Claude Code 的實現 | 評價 |
| --- | --- | --- |
-| 指令 | 作用域分层(组织/用户/项目/本地)+ 自动记忆 | 分层记忆是标杆实现 |
-| 工具 | 技能 + MCP + 钩子 + 子智能体四类扩展 | 职责划分清晰,是核心亮点 |
-| 环境 | 项目内设置 + settings.json | 靠用户在 CLAUDE.md 里自描述 |
-| 状态 | 追加式会话存储 + 五层压缩 + resume/fork | 极强,长任务连续性的参考实现 |
-| 反馈 | 权限分类器 + PostToolUse 钩子强制检查 | 把"防提前宣告完成"变成确定性机制 |
+| 指令 | 作用域分層(組織/用戶/項目/本地)+ 自動記憶 | 分層記憶是標桿實現 |
+| 工具 | 技能 + MCP + 鉤子 + 子代理四類擴充 | 職責劃分清晰,是核心亮點 |
+| 環境 | 項目內設置 + settings.json | 靠用戶在 CLAUDE.md 裡自描述 |
+| 狀態 | 追加式會話儲存 + 五層壓縮(依 VILA v2.1.88 拆解) + resume/fork | 極強,長任務連續性的參考實現 |
+| 回饋 | 權限分類器 + PostToolUse 鉤子強制檢查 | 把"防提前宣告完成"變成確定性機制 |
## 值得借鑑的設計
1. **指令依作用範圍分層**,而不是堆在單一檔案裡。目錄層級的 CLAUDE.md 是「就近載入」的漂亮實作。
2. **compaction 是分級漏斗**:先無損、後有損,不要一開始就做全文摘要。
-3. **用 hooks 進行確定性檢查**:防止提前宣告完成,靠的是執行時期強制,而不是提示詞懇求。
+3. **用 hooks 做確定性檢查**:防止提前宣告完成,靠的是執行時期強制,而不是提示詞懇求。
4. **subagent 上下文隔離**:拆任務的同時也拆上下文,不要讓子任務的結果污染主循環。
5. **session 儲存採附加式 + 可重播**:交接不是靠記憶,而是由儲存層保證。
-## 參考來源(原文 / 原始碼)
+## 參考來源
-每一項論述都能追溯到以下原文或原始碼,避免憑印象轉述:
+每一項論述都能追溯到以下來源,避免憑印象轉述:
-- **Claude Code 官方文档 · Memory**:每次 session 使用全新上下文、CLAUDE.md 四種作用範圍、子目錄隨選載入、auto memory(200 行 / 25KB)、`/init` 產生 CLAUDE.md。<br/>https://code.claude.com/docs/en/memory
-- **Claude Code 官方文档 · Skills / MCP / Hooks / Sub-agents**:四種擴充機制的定義與事件(PreToolUse / PostToolUse / Stop)。<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents
-- **VILA Lab《Dive into Claude Code》**(原始碼層級拆解報告):五層 compaction 管線、permissions 七種模式 + ML 分類器、sidechain subagent、附加式 session 儲存 history.jsonl。<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf
+### Anthropic 官方文件
+
+- **Claude Code 官方文件 · Memory**:每次 session 使用全新上下文、CLAUDE.md 四種作用範圍、子目錄隨選載入、auto memory(200 行 / 25KB)、`/init` 產生 CLAUDE.md。<br/>https://code.claude.com/docs/en/memory
+- **Claude Code 官方文件 · Skills / MCP / Hooks / Sub-agents**:四種擴充機制的定義與事件(PreToolUse / PostToolUse / Stop)。<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents
+- **Claude Code 官方文件 · Permission modes**:目前的模式名稱 Manual(原 "default",v2.1.200+ 起改名)、Plan、acceptEdits、Auto 與 bypassPermissions。<br/>https://code.claude.com/docs/en/permission-modes
- **Anthropic《Effective harnesses for long-running agents》**:「可靠性來自 harness 而非模型」、agent 會自信地稱讚自己的工作、用 hooks 進行驗證等觀點的出處。<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
-- **Claude Code Full Stack 导读**(社群,CLAUDE.md / Skills / MCP / Subagents / Hooks 分層):作為擴充機制職責分離的補充閱讀。<br/>https://jsmanifest.com/claude-code-full-stack-guide
+
+### 獨立研究 / 社群資源
+
+這類來源反映的是特定歷史版本(VILA Lab 拆解時為 Claude Code v2.1.88),可能與目前行為不符。
+
+- **VILA Lab《Dive into Claude Code》**(v2.1.88 原始碼層級拆解報告):五層 compaction 管線、permissions 七種模式 + ML 分類器、sidechain subagent、附加式 session 儲存 history.jsonl。<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf
+- **Claude Code Full Stack 導讀**(社群,CLAUDE.md / Skills / MCP / Subagents / Hooks 分層):作為擴充機制職責分離的補充閱讀。<br/>https://jsmanifest.com/claude-code-full-stack-guide
相關講義:[第三講 · 讓程式碼儲存庫成為唯一的事實來源](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [第九講 · 防止 agent 提前宣告完成](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [第十講 · 跑通完整流程才算真正驗證](../lectures/lecture-10-why-end-to-end-testing-changes-results/)
diff --git a/docs/zh-TW/harness-designs/codex/index.md b/docs/zh-TW/harness-designs/codex/index.md
index d387aa6..aa3d589 100644
--- a/docs/zh-TW/harness-designs/codex/index.md
+++ b/docs/zh-TW/harness-designs/codex/index.md
@@ -1,6 +1,6 @@
# 拆解 Codex 的 harness 設計
-OpenAI 的 [Codex](https://openai.com/index/harness-engineering/) 可能是四款產品裡與「harness 原教旨」連結最深的一個——那篇定義整個領域名稱的《Harness Engineering》文章,本身就是 OpenAI 團隊使用 Codex 開發產品時的經驗總結。因此,拆解 Codex 的 harness 設計,很大程度上就是拆解那篇文章背後的工程實務。
+OpenAI 的 [Codex](https://openai.com/index/harness-engineering/) 可能是四款產品裡與「harness 原教旨」連結最深的一個,那篇定義整個領域名稱的《Harness Engineering》文章,本身就是 OpenAI 團隊使用 Codex 開發產品時的經驗總結。因此,拆解 Codex 的 harness 設計,很大程度上就是拆解那篇文章背後的工程實務。
Codex 的哲學可以濃縮成一句話:**儲存庫即事實來源(repository as the system of record),AGENTS.md 只是目錄頁,工程的價值在於設計環境、表達意圖、建構回饋循環。**
@@ -24,10 +24,10 @@ OpenAI 團隊使用 Codex,在幾週內交付了一個最後達到上百萬行
Codex 的上下文工程可概括為四種策略。這是社群在 "context engineering" 成為獨立學科後,總結並對應回 Codex 的框架(框架出處請參閱 [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)):
-- **Write(寫出去)**:把上下文持久化到視窗之外——把結論寫入文件、把狀態寫入檔案,而不是留在對話裡。對應「儲存庫即事實來源」。
-- **Select(選進來)**:只把需要的 token 拉進視窗——由 AGENTS.md 指路、隨選讀取檔案,而不是把整個儲存庫塞進去。
-- **Compress(壓縮)**:保留真正重要的內容——Codex 有自動 compaction 和手動 `/compact`,可以自訂 `compact_prompt`(請參閱 [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/))。
-- **Isolate(隔離)**:把上下文切分到不同邊界——使用 subagent 隔離不同任務的上下文,前端 subagent 永遠看不到後端的資料庫 schema。
+- **Write(寫出去)**:把上下文持久化到視窗之外,把結論寫入文件、把狀態寫入檔案,而不是留在對話裡。對應「儲存庫即事實來源」。
+- **Select(選進來)**:只把需要的 token 拉進視窗,由 AGENTS.md 指路、隨選讀取檔案,而不是把整個儲存庫塞進去。
+- **Compress(壓縮)**:保留真正重要的內容,Codex 有自動 compaction 和手動 `/compact`,可以自訂 `compact_prompt`(請參閱 [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/))。
+- **Isolate(隔離)**:把上下文切分到不同邊界,使用 subagent 隔離不同任務的上下文,前端 subagent 永遠看不到後端的資料庫 schema。
Codex 還有一項很細緻的環境上下文設計:社群對 [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) 的原始碼分析顯示,`build_environment_update_item` 只在環境變更時輸出**有變動的欄位**(CWD、git 分支、檔案系統),而不是每一輪都貼上一遍完整的系統上下文。這是「不要在上下文裡保留重複 token」的工程細節。
@@ -35,33 +35,33 @@ Codex 還有一項很細緻的環境上下文設計:社群對 [codex-harness-i
Codex 有兩項核心 harness 機制:
-**1. git worktree 隔離環境。** [《Harness Engineering》原文](https://openai.com/index/harness-engineering/) 的 "Environment" 一節明確指出:每個任務都在獨立的 git worktree 裡執行,搭配本機可觀測性堆疊(日誌、指標、追蹤),讓每項變更都在獨立環境中驗證。這就是課程第七講「為 agent 劃清每次任務的邊界」的實體實作——邊界不是靠指令懇求,而是由環境隔離強制執行。環境(environment)子系統在此成為硬隔離。
+**1. git worktree 隔離環境。** [《Harness Engineering》原文](https://openai.com/index/harness-engineering/) 的 "Environment" 一節明確指出:每個任務都在獨立的 git worktree 裡執行,搭配本機可觀測性堆疊(日誌、指標、追蹤),讓每項變更都在獨立環境中驗證。這就是課程第七講「為 agent 劃清每次任務的邊界」的實體實作,邊界不是靠指令懇求,而是由環境隔離強制執行。環境(environment)子系統在此成為硬隔離。
-**2. 核心層級 subagent。** Codex 的 `spawn_agent` / `wait_agent` 是核心層級工具:模型明確建立 subagent、給它獨立的 session 歷史和工具集,並等待結果。subagent 會繼承父層的 AGENTS.md 指令,但在**自己的上下文**裡執行。設定放在 `.codex/agents/*.toml`,可指定不同模型和指令(細節請參閱 [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/) 的 Sub-agents 一節)。這是「上下文隔離」的直接實作——也體現了課程第十二講的「交接」精神:每個 subagent 都是邊界清楚的工作單元。
+**2. 核心層級 subagent。** Codex 的 `spawn_agent` / `wait_agent` 是核心層級工具:模型明確建立 subagent、給它獨立的 session 歷史和工具集,並等待結果。subagent 會繼承父層的 AGENTS.md 指令,但在**自己的上下文**裡執行。設定放在 `.codex/agents/*.toml`,可指定不同模型和指令(細節請參閱 [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/) 的 Sub-agents 一節)。這是「上下文隔離」的直接實作,也體現了課程第十二講的「交接」精神:每個 subagent 都是邊界清楚的工作單元。
## 回饋子系統:把驗證指令寫進規範
-OpenAI 的實務最強調的一點是:在 AGENTS.md 裡明確列出驗證指令,把「如何確認做對了」變成儲存庫的一部分。Codex 的工程流程中,測試、CI、文件、可觀測性設定——全都由 Codex 產生,而且全都是「可執行的驗證路徑」。模型能力強卻不可靠的解法,不是祈禱模型自律,而是讓**驗證路徑成為 harness 的預設元件**。
+OpenAI 的實務最強調的一點是:在 AGENTS.md 裡明確列出驗證指令,把「如何確認做對了」變成儲存庫的一部分。Codex 的工程流程中,測試、CI、文件、可觀測性設定,全都由 Codex 產生,而且全都是「可執行的驗證路徑」。模型能力強卻不可靠的解法,不是祈禱模型自律,而是讓**驗證路徑成為 harness 的預設元件**。
核准原則(approval policies)和計畫模式(plan mode)則是另一個回饋方向:執行高風險操作前先提出計畫、先取得核准,把「任務邊界」和「人類決策權」做成執行時期控制。
## 對應到課程框架
-| 子系统 | Codex 的实现 | 评价 |
+| 子系統 | Codex 的實現 | 評價 |
| --- | --- | --- |
-| 指令 | AGENTS.md 目录页 + docs/ 拆分 + 执行不变量 | 教科书级,定义了"给地图不给说明书" |
-| 工具 | worktree 隔离 + spawn_agent 子智能体 | 边界靠环境硬隔离,很强 |
-| 环境 | 独立 worktree + 可观测性栈 | worktree 隔离是其招牌 |
-| 状态 | Write 策略(状态写进文件/文档) | 依赖约定而非内建记忆 |
-| 反馈 | 验证命令入规范 + 审批策略 + plan mode | 反馈路径默认化,值得抄 |
+| 指令 | AGENTS.md 目錄頁 + docs/ 拆分 + 執行不變量 | 教科書級,定義了"給地圖不給說明書" |
+| 工具 | worktree 隔離 + spawn_agent 子代理 | 邊界靠環境硬隔離,很強 |
+| 環境 | 獨立 worktree + 可觀測性堆疊 | worktree 隔離是其招牌 |
+| 狀態 | Write 策略(狀態寫進檔案/文件) | 依賴約定而非內建記憶 |
+| 回饋 | 驗證命令入規範 + 審批策略 + plan mode | 回饋路徑預設化,值得抄 |
-Codex 和 Claude Code 的對比很有意思:Claude Code 是「加法」——把記憶、permissions、subagent 全都做到核心裡;Codex 是「減法」——核心盡量保持克制,把更多責任放在儲存庫慣例和上下文工程上。這也是為什麼社群常說「Codex 的 harness 哲學比它的程式碼更有價值」。
+Codex 和 Claude Code 的對比很有意思:Claude Code 是「加法」,把記憶、permissions、subagent 全都做到核心裡;Codex 是「減法」,核心盡量保持克制,把更多責任放在儲存庫慣例和上下文工程上。這也是為什麼社群常說「Codex 的 harness 哲學比它的程式碼更有價值」。
## 值得借鑑的設計
-1. **把 AGENTS.md 當成目錄頁來寫**:控制在 100 行左右,指向 docs/ 裡的細節,並可進行機械化檢查。
+1. **把 AGENTS.md 當成目錄頁來寫**:控制在 100 行左右,指向 docs/ 裡的細節,並可做機械化檢查。
2. **只寫不變量,不微觀管理實作**:硬性約束 + 驗證指令,其餘交給模型。
-3. **用 worktree 進行環境隔離**:任務邊界由環境強制執行,不靠指令懇求。
+3. **用 worktree 隔離環境**:任務邊界由環境強制執行,不靠指令懇求。
4. **環境上下文只傳增量**:每輪只輸出變動的欄位,不要重複貼上完整的系統上下文。
5. **用 subagent 隔離上下文**:拆任務的同時也拆上下文,不要讓子任務污染主循環。
@@ -70,8 +70,8 @@ Codex 和 Claude Code 的對比很有意思:Claude Code 是「加法」——
每一項論述都能追溯到以下原文或原始碼,避免憑印象轉述:
- **OpenAI《Harness Engineering》**:AGENTS.md 目錄頁和約 100 行的建議、executive invariants / don't micromanage、worktree 隔離 + 可觀測性堆疊、把驗證指令寫入規範、上百萬行產品案例、核准原則與 plan mode。本篇所有核心論述的主要出處。<br/>https://openai.com/index/harness-engineering/
-- **OpenAI 官方《AGENTS.md》规范**(AGENTS.md 作為跨工具慣例的標準):<br/>https://openai.com/index/agents-md/
-- **Codex CLI 开源仓库**(以 Rust 實作的單體二進位檔):<br/>https://github.com/openai/codex
+- **OpenAI 官方《AGENTS.md》規範**(AGENTS.md 作為跨工具慣例的標準):<br/>https://openai.com/index/agents-md/
+- **Codex CLI 開源儲存庫**(以 Rust 實作的單體二進位檔):<br/>https://github.com/openai/codex
- **Context Engineering for Codex CLI**(社群):Write-Select-Compress-Isolate 框架、`/compact` 與 `compact_prompt`、`spawn_agent` / `wait_agent` subagent 與 `.codex/agents/*.toml` 設定。<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/
- **codex-harness-internals**(社群原始碼分析):`build_environment_update_item` 增量環境上下文等實作細節。<br/>https://github.com/AlexKenbo/codex-harness-internals
diff --git a/docs/zh-TW/harness-designs/deepseek/index.md b/docs/zh-TW/harness-designs/deepseek/index.md
index 767de22..c915c97 100644
--- a/docs/zh-TW/harness-designs/deepseek/index.md
+++ b/docs/zh-TW/harness-designs/deepseek/index.md
@@ -1,32 +1,32 @@
# 拆解 DeepSeek Harness 的設計
-[DeepSeek Harness](https://deepseek.com/harness)(指令名稱 `dsh`,儲存庫 `deepseek-ai/deepseek-harness`)於 2026 年 8 月以 Developer Preview 形式發佈,官方給出的定義很直接:**Agent = Model + Environment + Tools + State**——模型、環境、工具、狀態,四件套。
+[DeepSeek Harness](https://deepseek.com/harness)(指令名稱 `dsh`,儲存庫 `deepseek-ai/deepseek-harness`)於 2026 年 8 月以 Developer Preview 形式發佈,官方給出的定義很直接:**Agent = Model + Environment + Tools + State**,模型、環境、工具、狀態,四件套。
-如果前三個產品的拆解是在問「harness 應該如何設計」,DeepSeek Harness 問的是更激進的問題:**harness 能不能脫離特定模型,成為一種獨立的執行時期?** 它的答案是可以,而且把這件事做到了極致——[架構文件](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)的原文是:*Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself*(產品的每一部分都是 plugin,包括模型轉接器、工具登錄檔、session 日誌,甚至 agent 循環本身)。
+如果前三個產品的拆解是在問「harness 應該如何設計」,DeepSeek Harness 問的是更激進的問題:**harness 能不能脫離特定模型,成為一種獨立的執行時期?** 它的答案是可以,而且把這件事做到了極致,[架構文件](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)的原文是:*Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself*(產品的每一部分都是 plugin,包括模型轉接器、工具登錄檔、session 日誌,甚至 agent 循環本身)。
這一篇我們拆解它,重點看三件事:plugin 化的核心、能力接縫(capability seam)、事件管線,以及那項最強的工程約束 "Model-visible means logged"。
## 一句話定位
-傳統 coding agent 的結構是「LLM + 固定的 agent 循環 + 固定的工具集」。DeepSeek Harness 的結構是「模型 + 一個 plugin 核心(Cordis)」,核心只負責 plugin 的載入、卸載、相依關係和事件機制,**不擁有任何 agent 的具體能力**——[架構文件](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)的原文是 "There is no privileged core to patch"(不存在需要修補的特權核心),"you extend dsh by mounting a plugin beside the others"(只要在一旁掛載一個 plugin 即可擴充,不必修改核心)。這表示連 agent 循環本身都不是神聖不可修改的——你可以使用 DeepSeek 的模型、接上 Claude Code 的 subagent、採用遠端沙箱、編寫自訂記憶、替換自訂循環、替換自訂 UI,組成一個全新的 agent。
+傳統 coding agent 的結構是「LLM + 固定的 agent 循環 + 固定的工具集」。DeepSeek Harness 的結構是「模型 + 一個 plugin 核心(Cordis)」,核心只負責 plugin 的載入、卸載、相依關係和事件機制,**不擁有任何 agent 的具體能力**,[架構文件](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)的原文是 "There is no privileged core to patch"(不存在需要修補的特權核心),"you extend dsh by mounting a plugin beside the others"(只要在一旁掛載一個 plugin 即可擴充,不必修改核心)。這表示連 agent 循環本身都不是神聖不可修改的,你可以使用 DeepSeek 的模型、接上 Claude Code 的 subagent、採用遠端沙箱、編寫自訂記憶、替換自訂循環、替換自訂 UI,組成一個全新的 agent。
這是對課程「模型權重以外的一切都是 harness」這句話最徹底的貫徹:既然 harness 是獨立的,就讓它獨立成為一個作業系統。
## 架構核心 1:能力接縫(Capability Seam)
-DeepSeek Harness 使用 Service 表示「能力」,幾乎每項能力都拆成三層:
+DeepSeek Harness 使用 Service 表示「能力」,並將幾乎每項能力拆分為三層:
```
-Service Definition(能力定义)
+Service Definition(服務定義)
↓
-Service Provider(能力提供者)
+Service Provider(服務提供者)
↓
-Consumer(能力消费者)
+Consumer(服務使用者)
```
-以檔案系統為例:`FS Service` 下面有 Local FS、E2B FS、Remote FS 等多個 Provider,向上統一公開為 file tools。Shell、Subprocess、Sandbox、Web、LLM、SubAgent 都採用同一套結構。這套三層結構不是我們總結的——[架構文件 · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)原文就是:*a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool*(能力接縫 = 可替換的能力,包含三種角色:宣告介面的 Service Definition、實作它的 Service Provider,以及使用它的 Consumer;後者通常是面向模型的工具)。
+以檔案系統為例:`FS Service` 下面有 Local FS、E2B FS、Remote FS 等多個 Provider,向上統一公開為 file tools。Shell、Subprocess、Sandbox、Web、LLM、SubAgent 都採用同一套結構。這套三層結構不是我們總結的,[架構文件 · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)原文就是:*a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool*(能力接縫 = 可替換的能力,包含三種角色:宣告介面的 Service Definition、實作它的 Service Provider,以及使用它的 Consumer;後者通常是面向模型的工具)。
-這解決了 harness 工程裡長期存在的問題:**agent 究竟應該依賴「具體工具」,還是依賴「能力介面」?** DeepSeek Harness 選擇後者。對課程而言,這表示「工具子系統」被標準化為介面——更換 Provider 後,工具對模型公開的樣貌不變,但環境徹底改變。
+這解決了 harness 工程裡長期存在的問題:**agent 究竟應該依賴「具體工具」,還是依賴「能力介面」?** DeepSeek Harness 選擇後者。對課程而言,這表示「工具子系統」被標準化為介面,更換 Provider 後,工具對模型公開的樣貌不變,但環境徹底改變。
## 架構核心 2:事件管線(Event Pipeline)
@@ -37,12 +37,12 @@ turn/start → claim input → assemble(system prompt / context / tools)
→ agent/pre-step → step/start → LLM request(agent/request)→ llm/stream
→ assistant/message → tool/call
→ tools/pre-execute(permission / guard / policy / hook)
- → tools/execute → tools/post-execute → tool/result → step/end → 下一轮
+ → tools/execute → tools/post-execute → tool/result → step/end → 下一輪
```
(上面的管線轉寫自 [架構文件 · Turn flow](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) 一節:`turn/*`、`step/*`、`user/message`、`assistant/*`、`tool/*` 是持久化的 session 事件,`agent/pre-step`、`agent/request`、`llm/stream`、`tools/*` 則是 plugin 可以監聽的擴充點。)
-這項設計最大的好處是:**大量功能根本不必修改 agent 循環本身**。想在工具執行前進行安全檢查?監聽 `tools/pre-execute`。想加入記憶?在 `agent/pre-step` 注入。想記錄行為?訂閱 session 事件。想修改模型請求?掛接 `agent/request`。想決定是否繼續推理?監聽 `agent/turn-stopping`。
+這項設計最大的好處是:**大量功能根本不必修改 agent 循環本身**。想在工具執行前做安全檢查?監聽 `tools/pre-execute`。想加入記憶?在 `agent/pre-step` 注入。想記錄行為?訂閱 session 事件。想修改模型請求?掛接 `agent/request`。想決定是否繼續推理?監聽 `agent/turn-stopping`。
對照課程第十一講「讓 agent 的執行過程可觀測」,DeepSeek Harness 走得更遠:它不是「加入日誌」,而是讓**循環的每一步都成為事件點**,使可觀測性、permissions、記憶、原則全部以監聽器的身分掛在循環上,而不是寫死在循環裡。
@@ -54,19 +54,19 @@ DeepSeek Harness 有一個 **append-only 的 Session Event Log(僅附加的 se
(凡是模型能看到的,都必須記錄。任何進入模型請求的內容都必須能從日誌重建,而且有一項執行時期不變量會強制檢查這一點。)
-換句話說,可觀測性不是事後補上的日誌,而是 harness 的第一性約束:任何進入模型上下文的內容,預設都應該留下日誌。這直接呼應收官之夜的「可觀測性屬於 harness 內部」,並把 "append-only" 這項儲存設計化為原則——日誌只附加、不覆寫,session 狀態可以重播。
+換句話說,可觀測性不是事後補上的日誌,而是 harness 的第一性約束:任何進入模型上下文的內容,預設都應該留下日誌。這直接呼應收官之夜的「可觀測性屬於 harness 內部」,並把 "append-only" 這項儲存設計化為原則,日誌只附加、不覆寫,session 狀態可以重播。
## 對應到課程框架
-| 子系统 | DeepSeek Harness 的实现 | 评价 |
+| 子系統 | DeepSeek Harness 的實現 | 評價 |
| --- | --- | --- |
-| 指令 | 插件化;规则/技能均以插件形态注入 | 极自由,但没有内置的"CLAUDE.md"式惯例 |
-| 工具 | Service Definition → Provider → Consumer 能力接缝 | 工具子系统标准化的极致 |
-| 环境 | 沙箱/FS/Shell 全部可换 Provider(含远程 E2B) | 环境彻底可插拔 |
-| 状态 | append-only Session Event Log + Model-visible means logged | 可观测性是第一性约束 |
-| 反馈 | tools/pre-execute 上的 permission / guard / policy / hook | 反馈机制事件化 |
+| 指令 | 插件化;規則/技能均以插件形態注入 | 極自由,但沒有內建的"CLAUDE.md"式慣例 |
+| 工具 | Service Definition → Provider → Consumer 能力接縫 | 工具子系統標準化的極致 |
+| 環境 | 沙箱/FS/Shell 全部可換 Provider(含遠端 E2B) | 環境徹底可插拔 |
+| 狀態 | append-only Session Event Log + Model-visible means logged | 可觀測性是第一性約束 |
+| 回饋 | tools/pre-execute 上的 permission / guard / policy / hook | 回饋機制事件化 |
-DeepSeek Harness 和其他三款產品的根本差異在於:Pi、Claude Code、Codex 都是在「一個具體的 agent」內部最佳化 harness;DeepSeek Harness 則把 harness 定義成**獨立於模型的作業系統**,agent 本身只是這套 OS 上的可替換應用程式。代價也很明顯——自由度高表示設定成本也高,這是「harness 即 OS」這套設計固有的另一面(開發者預覽階段的定位也是「搶先體驗、機制仍在演進」)。
+DeepSeek Harness 和其他三款產品的根本差異在於:Pi、Claude Code、Codex 都是在「一個具體的 agent」內部最佳化 harness;DeepSeek Harness 則把 harness 定義成**獨立於模型的作業系統**,agent 本身只是這套 OS 上的可替換應用程式。代價也很明顯,自由度高表示設定成本也高,這是「harness 即 OS」這套設計固有的另一面(開發者預覽階段的定位也是「搶先體驗、機制仍在演進」)。
## 值得借鑑的設計
@@ -79,9 +79,9 @@ DeepSeek Harness 和其他三款產品的根本差異在於:Pi、Claude Code
每一項論述都能追溯到以下原文或原始碼,避免憑印象轉述:
-- **DeepSeek Harness 官网**:產品定義 "Agent = Model + Environment + Tools + State"、Developer Preview 定位與 `dsh` 指令。<br/>https://deepseek.com/harness
-- **deepseek-ai/deepseek-harness 仓库**(指令 `dsh`,MIT 授權條款):<br/>https://github.com/deepseek-ai/deepseek-harness
-- **架构文档 architecture.md**:本篇最核心的出處——"Every part of the product is a plugin"、"There is no privileged core to patch"、Turn flow 事件管線、Capability seams 三層角色、"Model-visible means logged" 與執行時期不變量、append-only Session Event Log、fs/tools/telemetry 等能力接縫與 `ctx.*` 子系統。<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md
-- **架构文档 · 配套子文档**:Cordis 核心簡介(plugins contribute services, typed events, reversible effects)、能力接縫細節、Session 子系統。<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md
+- **DeepSeek Harness 官網**:產品定義 "Agent = Model + Environment + Tools + State"、Developer Preview 定位與 `dsh` 指令。<br/>https://deepseek.com/harness
+- **deepseek-ai/deepseek-harness 儲存庫**(指令 `dsh`,MIT 授權條款):<br/>https://github.com/deepseek-ai/deepseek-harness
+- **架構文件 architecture.md**:本篇最核心的出處,"Every part of the product is a plugin"、"There is no privileged core to patch"、Turn flow 事件管線、Capability seams 三層角色、"Model-visible means logged" 與執行時期不變量、append-only Session Event Log、fs/tools/telemetry 等能力接縫與 `ctx.*` 子系統。<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md
+- **架構文件 · 配套子文件**:Cordis 核心簡介(plugins contribute services, typed events, reversible effects)、能力接縫細節、Session 子系統。<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md
相關講義:[第十一講 · 讓 agent 的執行過程可觀測](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [第十二講 · 每次 session 結束前都做好交接](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [第二講 · Harness 到底是什麼](../lectures/lecture-02-what-a-harness-actually-is/)
diff --git a/docs/zh-TW/harness-designs/index.md b/docs/zh-TW/harness-designs/index.md
index 874acaf..03b5e79 100644
--- a/docs/zh-TW/harness-designs/index.md
+++ b/docs/zh-TW/harness-designs/index.md
@@ -1,8 +1,8 @@
# 前沿 Harness 拆解
-這個專欄把課程講義提到的 harness 理論,逐一對照目前最前沿的真實產品。每個產品我們只關心一件事:**它的 harness 是怎麼設計的**——也就是模型周圍的那一層工程基礎設施:指令、工具、環境、狀態、回饋這五個子系統,以及上下文連續性、初始化、驗證、可觀測性、交接、循環這些核心機制。
+這個專欄把課程講義提到的 harness 理論,逐一對照目前最前沿的真實產品。每個產品我們只關心一件事:**它的 harness 是怎麼設計的**,也就是模型周圍的那一層工程基礎設施:指令、工具、環境、狀態、回饋這五個子系統,以及上下文連續性、初始化、驗證、可觀測性、交接、循環這些核心機制。
-我們刻意不談模型的推理能力強不強、不談某次跑分高不高,也不籠統介紹「這個 agent 能做什麼」。那些是模型層和產品層的問題。這裡只拆解 harness——模型權重以外的一切。
+我們刻意不談模型的推理能力強不強、不談某次跑分高不高,也不籠統介紹「這個 agent 能做什麼」。那些是模型層和產品層的問題。這裡只拆解 harness,模型權重以外的一切。
## 為什麼值得拆解
@@ -10,7 +10,7 @@
每個產品都是一組獨立的設計決策。把它們放在一起對照,你會看到相同的核心機制,被不同團隊以截然不同的方式實作:
-- **Pi** 把 harness 做成極簡核心 + 可程式化擴充,靠「最小系統提示 + 隨選載入」進行上下文工程。
+- **Pi** 把 harness 做成極簡核心 + 可程式化擴充,靠「最小系統提示 + 隨選載入」做上下文工程。
- **Claude Code** 把 harness 做成完整的執行環境:分層記憶、五級壓縮、permissions、hooks、subagent。
- **Codex** 把 harness 的哲學推到極致:儲存庫即事實來源,AGENTS.md 只是目錄頁,使用 worktree 隔離環境。
- **DeepSeek Harness** 乾脆把 harness 本身定義成一種獨立於模型的執行時期:Everything is a Plugin。
diff --git a/docs/zh-TW/harness-designs/pi/index.md b/docs/zh-TW/harness-designs/pi/index.md
index a3f5ff6..39eac5f 100644
--- a/docs/zh-TW/harness-designs/pi/index.md
+++ b/docs/zh-TW/harness-designs/pi/index.md
@@ -1,12 +1,12 @@
# 拆解 Pi 的 harness 設計
-[Pi](https://pi.dev/)(npm 套件 `@earendil-works/pi-coding-agent`)自稱 "minimal agent harness"——極簡的 agent harness。這句話值得拆開來看:它沒有自稱「最強的 coding agent」,也沒有自稱「最好用的 AI 程式設計工具」,而是把自己的定位牢牢釘在 **harness** 這個詞上。
+[Pi](https://pi.dev/)(npm 套件 `@earendil-works/pi-coding-agent`)自稱 "minimal agent harness",極簡的 agent harness。這句話值得拆開來看:它沒有自稱「最強的 coding agent」,也沒有自稱「最好用的 AI 程式設計工具」,而是把自己的定位牢牢釘在 **harness** 這個詞上。
這一篇我們用課程的五子系統框架(指令、工具、環境、狀態、回饋)拆解 Pi,看看它的設計哲學和 Claude Code、Codex 有什麼根本差異。答案先說:**Pi 的哲學是「核心最小化 + 擴充可程式化」,把上下文工程做到系統提示之外,讓使用者(甚至 Pi 自己)修改 harness,而不是讓 Pi 替你決定 harness。**
## 一句話定位
-Pi 是極簡核心:官方刻意把核心做小、把決定權交還給你——[pi.dev 首頁](https://pi.dev/)的原文是 "Ask Pi to build what you want, or install a package that does it your way"。它把 harness 拆成四層可自訂項目:
+Pi 是極簡核心:官方刻意把核心做小、把決定權交還給你,[pi.dev 首頁](https://pi.dev/)的原文是 "Ask Pi to build what you want, or install a package that does it your way"。它把 harness 拆成四層可自訂項目:
- **擴充(Extensions)**:掛在 Pi 生命週期事件上的 TypeScript hooks,執行時期(runtime)層級的可程式化介面。
- **技能(Skills)**:隨選載入的能力套件,包含指令和工具,漸進式揭露(progressive disclosure)。
@@ -19,59 +19,59 @@ Pi 是極簡核心:官方刻意把核心做小、把決定權交還給你—
Pi 和所有 coding agent 一樣,本質上是「推理 → 工具執行 → 觀察 → 再推理」的 while 循環。值得注意的不是循環本身,而是 Pi 對循環外層的處理:它把上下文管理這件事,從循環內部的「壓縮」擴展到循環外部的「控制」。
-Pi 的執行時期對外公開可程式化介面——[原始碼 README 的 Programmatic Usage](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) 裡,除了互動式 TUI,還支援腳本化的列印/JSON 模式、RPC 協定與 SDK 嵌入。這決定了同一個 harness 既能由人逐條驅動,也能由 CI/CD 或其他程式自動驅動。它對應課程第十三講「循環工程」中「從手動驅動到自動循環」的前提:一個 harness 如果只能由人類互動驅動,就永遠無法進入自動循環。
+Pi 的執行時期對外公開可程式化介面,[原始碼 README 的 Programmatic Usage](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) 裡,除了互動式 TUI,還支援腳本化的列印/JSON 模式、RPC 協定與 SDK 嵌入。這決定了同一個 harness 既能由人逐條驅動,也能由 CI/CD 或其他程式自動驅動。它對應課程第十三講「循環工程」中「從手動驅動到自動循環」的前提:一個 harness 如果只能由人類互動驅動,就永遠無法進入自動循環。
## 指令子系統:AGENTS.md 與 SYSTEM.md
Pi 對「指令」的處理很克制,但層級清楚:
-- **AGENTS.md**:[原始碼 README 的 Project Context Files](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) 清楚列出載入順序——全域 `~/.pi/agent/AGENTS.md` → 逐層向上走訪父目錄 → 目前目錄 `./AGENTS.md`(也相容 CLAUDE.md)。這就是「儲存庫即事實來源」的貫徹——指令是檔案,不是聊天框裡的叮嚀。
+- **AGENTS.md**:[原始碼 README 的 Project Context Files](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) 清楚列出載入順序,全域 `~/.pi/agent/AGENTS.md` → 逐層向上走訪父目錄 → 目前目錄 `./AGENTS.md`(也相容 CLAUDE.md)。這就是「儲存庫即事實來源」的貫徹,指令是檔案,不是聊天框裡的叮嚀。
- **SYSTEM.md**:[pi.dev 官方文件](https://pi.dev/docs/usage/project-context) 說明可依專案取代(replace)或附加(append)預設系統提示。這是 Pi 允許你修改「系統提示」的唯一正式入口,也是它的「環境自我描述」層。
-Pi 官方強調它的系統提示本身**極簡**。背後是一個明確的取捨:核心不塞入「如果……那麼……」的冗長規則,而是保留擴充點,讓規則以技能和擴充的形式在需要時才出現。這直接呼應課程第四講「為什麼單一巨型指令檔案會失敗」——Pi 以「核心極簡 + 檔案拆分 + 隨選載入」自然避開巨型指令的問題。
+Pi 官方強調它的系統提示本身**極簡**。背後是一個明確的取捨:核心不塞入「如果……那麼……」的冗長規則,而是保留擴充點,讓規則以技能和擴充的形式在需要時才出現。這直接呼應課程第四講「為什麼單一巨型指令檔案會失敗」,Pi 以「核心極簡 + 檔案拆分 + 隨選載入」自然避開巨型指令的問題。
## 狀態與上下文:Pi 拆得最細的地方
Pi 的上下文工程值得重點拆解,因為它把課程裡「上下文連續性」「防止上下文腐化」這些概念落實為具體機制:
-**1. compaction 可程式化。** 接近上下文上限時,自動將舊訊息摘要化——[pi.dev 官方文件](https://pi.dev/docs/usage/sessions)說明 compaction 策略本身**可以自訂**:你可以用擴充實作基於主題的壓縮、能理解程式碼的摘要,甚至改用不同的模型來產生摘要。原始碼 README 也列出預設機制的細節:自動 compaction 會在兩種情況下觸發(上下文溢位復原 / 超過保留門檻),切割點會保留最近約 2 萬個 token,之前的訊息則摘要成 "context handoff" 並逐級鏈式壓縮。換句話說,Pi 不把「怎麼壓縮」視為不可修改的常數,而是視為 harness 的一部分。
+**1. compaction 可程式化。** 接近上下文上限時,自動將舊訊息摘要化,[pi.dev 官方文件](https://pi.dev/docs/usage/sessions)說明 compaction 策略本身**可以自訂**:你可以用擴充實作基於主題的壓縮、能理解程式碼的摘要,甚至改用不同的模型來產生摘要。原始碼 README 也列出預設機制的細節:自動 compaction 會在兩種情況下觸發(上下文溢位復原 / 超過保留門檻),切割點會保留最近約 2 萬個 token,之前的訊息則摘要成 "context handoff" 並逐級鏈式壓縮。換句話說,Pi 不把「怎麼壓縮」視為不可修改的常數,而是視為 harness 的一部分。
**2. 動態上下文(Dynamic context)。** [pi.dev 官方文件](https://pi.dev/docs/usage/extensions)說明擴充可以在每一輪推理前注入訊息、過濾訊息歷史、實作 RAG、建構長期記憶。這比「上下文滿了再壓縮」更進一步:它讓你在上下文進入視窗前,就決定要放什麼、不放什麼。對應課程中的「讓 agent 的執行過程可觀測、可偵錯」和「保持上下文連續性」,Pi 把這兩件事下沉到擴充介面。
-**3. session 樹(Session tree)。** [pi.dev 首頁](https://pi.dev/)明確寫著「session 以樹狀結構儲存(sessions are stored as trees),`/tree` 可以回到任意歷史節點繼續,所有分支都儲存在同一個檔案裡」。這解決了課程一再強調的「跨 session 上下文斷裂」問題——不是靠摘要硬接,而是靠結構化的歷史重播。分支可以匯出為 HTML,或上傳為 gist 分享,可觀測性也一併解決了。
+**3. session 樹(Session tree)。** [pi.dev 首頁](https://pi.dev/)明確寫著「session 以樹狀結構儲存(sessions are stored as trees),`/tree` 可以回到任意歷史節點繼續,所有分支都儲存在同一個檔案裡」。這解決了課程一再強調的「跨 session 上下文斷裂」問題,不是靠摘要硬接,而是靠結構化的歷史重播。分支可以匯出為 HTML,或上傳為 gist 分享,可觀測性也一併解決了。
## 工具子系統:技能與擴充
Pi 的「工具」分成兩層:
-- **技能(Skills)**:[原始碼 README 的 Skills 一節](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)定義得很清楚——"self-contained capability packages that the agent loads on-demand",也就是隨選載入的能力套件,包含指令和工具,遵循 Agent Skills 標準。漸進式揭露讓技能細節只在觸發時才進入上下文,**不會塞爆提示快取(prompt cache)**。這是成本角度的 harness 設計:上下文每多一個 token,每次推理都要為它付費;把技能做成隨選載入,就是「給地圖,不給說明書」的另一種表達。
-- **擴充(Extensions)**:掛在內建生命週期事件上的 TypeScript hooks——[原始碼 README 的 Hooks 一節](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)列出四種官方範例用途:攔截危險指令(permissions 閘門)、切換任務時為程式碼建立 checkpoint、保護路徑(禁止寫入 `.env` 等)、修改工具輸出後再交給模型,以及從外部(檔案監看/Webhook/CI)注入訊息喚醒 agent。這些 hooks API 也在 `@mariozechner/pi-coding-agent/hooks` 裡匯出。社群 harness([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness))則進一步把 hooks 介面封裝成 skill-router、session-summary、extract-patterns、telemetry 等現成擴充。
+- **技能(Skills)**:[原始碼 README 的 Skills 一節](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)定義得很清楚,"self-contained capability packages that the agent loads on-demand",也就是隨選載入的能力套件,包含指令和工具,遵循 Agent Skills 標準。漸進式揭露讓技能細節只在觸發時才進入上下文,**不會塞爆提示快取(prompt cache)**。這是成本角度的 harness 設計:上下文每多一個 token,每次推理都要為它付費;把技能做成隨選載入,就是「給地圖,不給說明書」的另一種表達。
+- **擴充(Extensions)**:掛在內建生命週期事件上的 TypeScript hooks,[原始碼 README 的 Hooks 一節](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)列出四種官方範例用途:攔截危險指令(permissions 閘門)、切換任務時為程式碼建立 checkpoint、保護路徑(禁止寫入 `.env` 等)、修改工具輸出後再交給模型,以及從外部(檔案監看/Webhook/CI)注入訊息喚醒 agent。這些 hooks API 也在 `@mariozechner/pi-coding-agent/hooks` 裡匯出。社群 harness([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness))則進一步把 hooks 介面封裝成 skill-router、session-summary、extract-patterns、telemetry 等現成擴充。
-擴充是 Pi 最重要的設計決策:**它不是「提供使用者幾個開關」,而是把執行時期內部的事件介面全部公開。** 想加記憶?在 `agent/pre-step` 注入。想記錄行為?訂閱 session 事件。想修改模型請求?掛接 `agent/request`。你可以讓 Pi 自己修改自己的 harness——這比任何「設定項目」都更接近「可程式化 harness」的定義。
+擴充是 Pi 最重要的設計決策:**它不是「提供使用者幾個開關」,而是把執行時期內部的事件介面全部公開。** 想加記憶?在 `agent/pre-step` 注入。想記錄行為?訂閱 session 事件。想修改模型請求?掛接 `agent/request`。你可以讓 Pi 自己修改自己的 harness,這比任何「設定項目」都更接近「可程式化 harness」的定義。
## 回饋與驗證:把「學習」也做成 harness
Pi 本身沒有內建強制測試閘門(那是使用者要在 AGENTS.md 裡寫的驗證指令),但社群 harness([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness))透過擴充把「回饋迴路」結構化了,官方 README 的 Hooks 一節也提供了相似的機制基礎:
-- **session-summary**(pi-agent-harness 擴充):維護滾動更新的 `PROGRESS.md` 項目——這就是課程裡的狀態子系統,用於追蹤長任務進度。
-- **extract-patterns**(pi-agent-harness 擴充):從 session 中收集經驗教訓候選項,沉澱到 `LESSONS.md`——把「每次 session 結束前做好交接」從約定變成機制。
-- **telemetry**(pi-agent-harness 擴充):記錄 token 用量、成本等——可觀測性。
+- **session-summary**(pi-agent-harness 擴充):維護滾動更新的 `PROGRESS.md` 項目,這就是課程裡的狀態子系統,用於追蹤長任務進度。
+- **extract-patterns**(pi-agent-harness 擴充):從 session 中收集經驗教訓候選項,沉澱到 `LESSONS.md`,把「每次 session 結束前做好交接」從約定變成機制。
+- **telemetry**(pi-agent-harness 擴充):記錄 token 用量、成本等,可觀測性。
同一個社群儲存庫進一步驗證了這個模式:`VISION.md`(目標)、`PROGRESS.md`(進度)、`LESSONS.md`(經驗)、`STANDARDS.md`(標準),全都是 Markdown 檔案,可跨 session 持久化。這與課程建議的「儲存庫即事實來源 + 進度檔案 + 交接機制」完全是同一套做法,只是透過 Pi 的擴充機制成為開箱即用的一層。
## 對應到課程框架
-用課程五子系統為 Pi 評分(主觀,僅供對照):
+用課程五子系統為 Pi 評分:
-| 子系统 | Pi 的实现 | 评价 |
+| 子系統 | Pi 的實現 | 評價 |
| --- | --- | --- |
-| 指令 | AGENTS.md 分级加载 + SYSTEM.md | 层级清晰,但规则本身要靠用户写 |
-| 工具 | 技能按需加载 + 扩展全生命周期钩子 | 极强,把工具系统做成了可编程面 |
-| 环境 | SYSTEM.md 做环境自描述;运行时环境靠用户在 AGENTS.md 里声明 | 机制是开放的,但可复现性依赖用户自述 |
-| 状态 | 会话树 + 压缩可定制 + PROGRESS.md | 极强,跨会话与可恢复性是其核心 |
-| 反馈 | 验证命令靠用户定义;session-summary / extract-patterns 机制化 | 机制提供,内容靠用户 |
+| 指令 | AGENTS.md 分級載入 + SYSTEM.md | 層級清晰,但规则本身要靠用戶写 |
+| 工具 | 技能按需載入 + 擴充全生命週期鉤子 | 極強,把工具系統做成了可程式化介面 |
+| 環境 | SYSTEM.md 做環境自描述;運行時環境靠用戶在 AGENTS.md 裡聲明 | 機制是開放的,但可復現性依賴用戶自述 |
+| 狀態 | 會話樹 + 壓縮可自訂 + PROGRESS.md | 極強,跨會話與可恢復性是其核心 |
+| 回饋 | 驗證命令靠用戶定義;session-summary / extract-patterns 機制化 | 機制提供,內容靠用戶 |
-Pi 的取捨和 Claude Code / Codex 形成鮮明對比:Claude Code 把「記憶、permissions、subagent」全都做到核心裡,開箱即用;Codex 把「儲存庫規範、環境隔離」設為預設;Pi 選擇**什麼都不替你決定**——它把決定權做成擴充點。代價是你要嘛自己寫擴充,要嘛安裝別人寫好的套件。
+Pi 的取捨和 Claude Code / Codex 形成鮮明對比:Claude Code 把「記憶、permissions、subagent」全都做到核心裡,開箱即用;Codex 把「儲存庫規範、環境隔離」設為預設;Pi 選擇**什麼都不替你決定**,它把決定權做成擴充點。代價是你要嘛自己寫擴充,要嘛安裝別人寫好的套件。
## 值得借鑑的設計
@@ -84,11 +84,11 @@ Pi 的取捨和 Claude Code / Codex 形成鮮明對比:Claude Code 把「記
每一項論述都能追溯到以下原文或原始碼,避免憑印象轉述:
-- **pi.dev 官网**:定位原文 "Ask Pi to build what you want, or install a package that does it your way"、四層可自訂項目、session 樹("sessions are stored as trees"、`/tree`、單一檔案儲存、匯出 HTML / 分享 gist)。<br/>https://pi.dev/
-- **pi.dev 官方文档 · Sessions**:compaction 可插拔(topic-based / code-aware / 更換摘要模型)、自動 compaction 與動態上下文注入的機制說明。<br/>https://pi.dev/docs/usage/sessions
-- **pi.dev 官方文档 · Extensions**:擴充可在每輪推理前注入訊息、過濾歷史、執行 RAG、建構長期記憶。<br/>https://pi.dev/docs/usage/extensions
-- **pi.dev 官方文档 · Project Context**:SYSTEM.md 的 replace / append 語意。<br/>https://pi.dev/docs/usage/project-context
-- **Pi Coding Agent 源码 README**(badlogic/pi-mono):AGENTS.md 三級載入順序(全域 → 父目錄 → 目前目錄)、`/compact` 與自動 compaction 的觸發條件及 2 萬個 token 切割點、Skills 隨選載入與 Agent Skills 標準、Hooks 生命週期與四種官方範例用途、Programmatic Usage(JSON / RPC / SDK)。<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md
-- **pi-agent-harness 社区仓库**:skill-router / session-summary / extract-patterns / telemetry 擴充,VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md 檔案體系。<br/>https://github.com/LabidySabidy/pi-agent-harness
+- **pi.dev 官網**:定位原文 "Ask Pi to build what you want, or install a package that does it your way"、四層可自訂項目、session 樹("sessions are stored as trees"、`/tree`、單一檔案儲存、匯出 HTML / 分享 gist)。<br/>https://pi.dev/
+- **pi.dev 官方文件 · Sessions**:compaction 可插拔(topic-based / code-aware / 更換摘要模型)、自動 compaction 與動態上下文注入的機制說明。<br/>https://pi.dev/docs/usage/sessions
+- **pi.dev 官方文件 · Extensions**:擴充可在每輪推理前注入訊息、過濾歷史、執行 RAG、建構長期記憶。<br/>https://pi.dev/docs/usage/extensions
+- **pi.dev 官方文件 · Project Context**:SYSTEM.md 的 replace / append 語意。<br/>https://pi.dev/docs/usage/project-context
+- **Pi Coding Agent 原始碼 README**(badlogic/pi-mono):AGENTS.md 三級載入順序(全域 → 父目錄 → 目前目錄)、`/compact` 與自動 compaction 的觸發條件及 2 萬個 token 切割點、Skills 隨選載入與 Agent Skills 標準、Hooks 生命週期與四種官方範例用途、Programmatic Usage(JSON / RPC / SDK)。<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md
+- **pi-agent-harness 社群儲存庫**:skill-router / session-summary / extract-patterns / telemetry 擴充,VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md 檔案體系。<br/>https://github.com/LabidySabidy/pi-agent-harness
相關講義:[第二講 · Harness 到底是什麼](../lectures/lecture-02-what-a-harness-actually-is/) | [第五講 · 讓跨 session 的任務保持上下文連續](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [第十三講 · 從手動驅動到自動循環](../lectures/lecture-13-loop-engineering/)