# Agent Harness 深度指南

> 以 OpenAI Codex、DeepSeek Harness 與 Pi 三套完整開源 case study，對稱理解 Agent Harness 的 Runtime、Model、Loop、Tools、State、Security、Extensions、Integration、Labs 與 Production。

繁體中文 Agent Harness 教材，以 OpenAI Codex、DeepSeek Harness 與 Pi 三套開源實作做對稱 case study，系統化介紹 Model/Loop、Context、Tools、State、Security、Extensions、Integration、Labs、Production 與原始碼閱讀。

Sidebar navigation（網站的 canonical reading order）：
- [導論：Model 不等於 Agent](/docs/intro.md)
- [學習地圖：用同一組問題讀三套 Harness](/docs/learning-map.md)
- [完整教材目錄](/docs/catalog.md)
- [AI / LLM 資源](/docs/reference/llm-resources.md)
- 一、Agent Harness｜共同基礎
  - [什麼是 Harness？](/docs/foundations/what-is-harness.md)
  - [Agent Loop：一次任務到底怎麼跑](/docs/foundations/agent-loop.md)
  - [Context、Instructions、Caching 與 Compaction](/docs/foundations/context-and-caching.md)
  - [State Models 與 Lifecycle：三套 Harness 怎麼記住工作](/docs/foundations/state-models-and-lifecycle.md)
- 二、Codex｜Productized Runtime 完整導讀
  - 架構與 Runtime
    - [系統架構總覽](/docs/architecture/system-map.md)
    - [官方視角：Codex 介面與 App Server](/docs/architecture/official-visuals.md)
    - [codex-core：Agent Runtime 的中心](/docs/architecture/codex-core.md)
    - [Model Provider、Responses API 與 Streaming](/docs/architecture/model-provider-and-streaming.md)
    - [Tool Execution：從模型意圖到真實副作用](/docs/architecture/tool-execution.md)
    - [State、History、Rollout 與 Persistence](/docs/architecture/state-and-persistence.md)
    - [App Server 與 Protocol](/docs/architecture/app-server-and-protocol.md)
    - [Client Surfaces：CLI、Exec、SDK、App Server 怎麼選](/docs/architecture/client-surfaces.md)
  - 安全、權限與信任邊界
    - [Sandbox 與 Approvals](/docs/security/sandbox-and-approvals.md)
    - [Permission Profiles、Rules 與 Network Policy](/docs/security/permissions-rules-network.md)
    - [Trust Boundaries 與常見安全誤區](/docs/security/trust-boundaries.md)
  - 客製化與擴充
    - [config.toml 與設定優先序](/docs/customization/config.md)
    - [AGENTS.md：Repository Instructions](/docs/customization/agents-md.md)
    - [Skills 與 Plugins：Progressive Disclosure](/docs/customization/skills-and-plugins.md)
    - [MCP：把外部能力接進 Harness](/docs/customization/mcp.md)
    - [Hooks：觀察、阻擋、改寫與整合](/docs/customization/hooks.md)
    - [Subagents 與 Git Worktrees](/docs/customization/subagents-and-worktrees.md)
  - 使用與整合
    - [Codex CLI：Interactive Harness](/docs/usage/cli.md)
    - [codex exec：非互動與 CI](/docs/usage/noninteractive-ci.md)
    - [Codex SDK：程式化使用 Harness](/docs/usage/sdk.md)
    - [App Server：建立自己的 Codex Client](/docs/usage/app-server.md)
    - [GitHub Actions 與 Codex](/docs/usage/github-actions.md)
- 三、DeepSeek Harness｜Composable Runtime 完整導讀
  - [DeepSeek Harness：Composable Runtime 完整導讀](/docs/deepseek/overview.md)
  - 架構與 Runtime
    - [官方視角：DeepSeek Harness Lifecycle 與 Tool Pipeline](/docs/deepseek/official-visuals.md)
    - [Cordis 與 Everything-is-a-Plugin 架構](/docs/deepseek/architecture.md)
    - [Model Adapter 與 Agent Loop](/docs/deepseek/model-and-agent-loop.md)
    - [Tool Execution：Registry、Guard、Sandbox 與 Result Pipeline](/docs/deepseek/tool-execution.md)
    - [Context、System Prompt 與 Compaction](/docs/deepseek/context-and-compaction.md)
    - [Session、Events 與可追溯狀態](/docs/deepseek/session-and-events.md)
    - [使用方式：Profiles、Bundles 與啟動組合](/docs/deepseek/usage-and-profiles.md)
  - 擴充與 Orchestration
    - [Models、Skills、Subagents、Hooks 與 Extensions](/docs/deepseek/models-skills-and-extensions.md)
    - [Skills、Subagents、Workflows 與長生命週期工作](/docs/deepseek/subagents-workflows-and-jobs.md)
    - [Code Mode、Capability 與 Runtime 組合](/docs/deepseek/code-mode-and-plugins.md)
  - 安全與 Execution World
    - [安全模型：Sandbox、Approval 與 Permission Presets](/docs/deepseek/security-and-approvals.md)
    - [Permission、Credentials 與 Execution Worlds](/docs/deepseek/execution-worlds-and-credentials.md)
  - 使用、整合與 Production
    - [CLI、Headless 與 Automation](/docs/deepseek/headless-and-automation.md)
    - [整合介面：Web、SDK、JSON-RPC、ACP 與自製 Client](/docs/deepseek/integration-surfaces.md)
    - [Production、測試、Invariant 與成熟度](/docs/deepseek/production-and-testing.md)
- 四、Pi｜Minimal Runtime 完整導讀
  - [Pi Agent Harness：Minimal Runtime 完整導讀](/docs/pi/overview.md)
  - 架構、Model、Loop 與 State
    - [官方視角：Pi TUI 與 Session Tree](/docs/pi/official-visuals.md)
    - [Pi 架構：從 pi-ai 到 AgentSession](/docs/pi/architecture.md)
    - [Model Providers：pi-ai 與多模型 Runtime](/docs/pi/model-providers.md)
    - [Agent Loop 與 Tools：Minimal Core 怎麼工作](/docs/pi/agent-loop-and-tools.md)
    - [Context、Compaction 與 Branching](/docs/pi/context-compaction-and-branching.md)
    - [Pi Session、Compaction 與 Extensions](/docs/pi/session-and-extensions.md)
  - Resources、Extensions 與 UI
    - [Resources、Skills、Prompts 與 Pi Packages](/docs/pi/resources-skills-and-packages.md)
    - [Extensions 與自訂 TUI](/docs/pi/extensions-and-ui.md)
  - 安全、使用、整合與 Production
    - [Project Trust 與 Containerization](/docs/pi/project-trust-and-isolation.md)
    - [CLI 與日常使用](/docs/pi/cli-and-usage.md)
    - [SDK 與 RPC：把 Pi 嵌入自己的產品](/docs/pi/sdk-and-rpc.md)
    - [Production 與 Governance：Minimal Harness 的責任清單](/docs/pi/production-and-governance.md)
- 五、三套 Harness｜實戰 Labs
  - Codex Labs
    - [Lab 1：完整追蹤一次 Turn](/docs/labs/trace-a-turn.md)
    - [Lab 2：做一套 Guardrails](/docs/labs/guardrails.md)
    - [Lab 3：寫一個最小 App Server Client](/docs/labs/embed-app-server.md)
  - DeepSeek Harness Labs
    - [Lab：Trace 一次 DeepSeek Turn / Step](/docs/deepseek/labs/trace-turn-step.md)
    - [Lab：加入一個 DeepSeek Capability](/docs/deepseek/labs/capability-plugin.md)
    - [Lab：Replay、Invariant 與 Session Correctness](/docs/deepseek/labs/replay-invariant.md)
  - Pi Labs
    - [Lab：Trace Pi Session 與 AgentSession](/docs/pi/labs/session-tree.md)
    - [Lab：寫一個 Pi Extension](/docs/pi/labs/extension.md)
    - [Lab：Branch、Tree 與 Compaction](/docs/pi/labs/branch-compaction.md)
- 六、三種 Harness｜比較、選型與採用
  - [比較框架：如何比較 Agent Harness](/docs/comparison/overview.md)
  - [架構維度逐項比較：Codex、DeepSeek Harness、Pi](/docs/comparison/architecture-comparison.md)
  - [情境式選型：什麼時候選 Codex、DeepSeek Harness 或 Pi？](/docs/comparison/scenario-selection.md)
  - [PoC、採用與混用策略](/docs/comparison/adoption-playbook.md)
- 七、Harness｜真實系統與實務
  - [實務工作流：把 Agent Loop 變成可驗證工程流程](/docs/applications/workflows.md)
  - [行為到底該放在哪一層？](/docs/applications/where-should-behavior-live.md)
  - [從零設計自己的 Agent Harness](/docs/applications/build-your-own-harness.md)
  - [Production Harness Checklist](/docs/applications/production-checklist.md)
- 八、參考資料、官方來源與原始碼
  - [Glossary：Agent Harness 三方名詞速查](/docs/reference/glossary.md)
  - [三套 Harness 原始碼導讀入口](/docs/reference/source-reading.md)
  - [openai/codex 原始碼導讀地圖](/docs/reference/source-map.md)
  - [deepseek-ai/deepseek-harness 原始碼導讀地圖](/docs/reference/deepseek-source-map.md)
  - [earendil-works/pi 原始碼導讀地圖](/docs/reference/pi-source-map.md)
  - [官方閱讀清單與版本策略](/docs/reference/reading-list.md)

## Table of Contents

- [導論：Model 不等於 Agent](https://harness-book.ycnets.com/docs/intro.md): > 最後核對：2026-08-24。Codex、DeepSeek Harness 與 Pi 都快速演進；本教材把穩定的 architecture responsibilities 與版本敏感的 API / Plugin / Extension 分開說明。
- [學習地圖：用同一組問題讀三套 Harness](https://harness-book.ycnets.com/docs/learning-map.md): 如果第一次接觸 Agent Harness，不需要先懂 Rust、TypeScript、Responses API、Cordis、MCP 或 Pi Extensions。
- [完整教材目錄](https://harness-book.ycnets.com/docs/catalog.md): 這一頁是《Agent Harness 深度指南》的完整索引。Sidebar 與 `llms.txt` / `llms-full.txt` 會使用同一份 canonical reading order。
- [AI / LLM 資源](https://harness-book.ycnets.com/docs/reference/llm-resources.md): 本站提供專門給大型語言模型使用的純文字與 Markdown 版本。
- [什麼是 Harness？](https://harness-book.ycnets.com/docs/foundations/what-is-harness.md): 如果只記一句話：
- [Agent Loop：一次任務到底怎麼跑](https://harness-book.ycnets.com/docs/foundations/agent-loop.md): 如果 Harness 是控制中心，**Agent Loop 就是控制中心反覆執行的主流程**。
- [Context、Instructions、Caching 與 Compaction](https://harness-book.ycnets.com/docs/foundations/context-and-caching.md): 如果 Model 是大腦，**Context 就是它這一次 inference 真正看得到的工作桌**。
- [State Models 與 Lifecycle：三套 Harness 怎麼記住工作](https://harness-book.ycnets.com/docs/foundations/state-models-and-lifecycle.md): Agent 如果只能完成一次無狀態 function call，就很難稱為完整工作系統。
- [系統架構總覽](https://harness-book.ycnets.com/docs/architecture/system-map.md): 前面已經知道：
- [官方視角：Codex 介面與 App Server](https://harness-book.ycnets.com/docs/architecture/official-visuals.md): 本頁刻意把教材自己的抽象圖，和 **OpenAI 官方 repo / 官方工程文章**放在一起看。目的不是用官方素材取代教材，而是讓你能確認：前面談到的 Client、Runtime、Thread、App Server，確實對應到 Codex 官方公開的產品與架構語彙。
- [codex-core：Agent Runtime 的中心](https://harness-book.ycnets.com/docs/architecture/codex-core.md): `codex-core` 是理解 harness runtime 最值得看的 crate。它不是 UI，也不是 protocol schema；它負責「一個 Codex thread 如何真正活起來」。
- [Model Provider、Responses API 與 Streaming](https://harness-book.ycnets.com/docs/architecture/model-provider-and-streaming.md): Harness 必須把「agent runtime」與「某個固定 endpoint」分開。Codex 可以依登入與設定走不同 model provider，而 core 仍維持同一套 turn/tool semantics。
- [Tool Execution：從模型意圖到真實副作用](https://harness-book.ycnets.com/docs/architecture/tool-execution.md): Model 只會產生「我要呼叫某工具」的結構化意圖。真正的副作用發生在 harness。
- [State、History、Rollout 與 Persistence](https://harness-book.ycnets.com/docs/architecture/state-and-persistence.md): LLM API 通常是 stateless 的；coding agent 卻必須表現得有狀態。這個落差由 harness 補上。
- [App Server 與 Protocol](https://harness-book.ycnets.com/docs/architecture/app-server-and-protocol.md): App Server 解決的是一個典型架構問題：**如何讓完整 Codex harness 不被某個 UI 綁死？**
- [Client Surfaces：CLI、Exec、SDK、App Server 怎麼選](https://harness-book.ycnets.com/docs/architecture/client-surfaces.md): Codex 的不同「使用方式」其實代表不同 integration depth。選錯 surface，常會讓架構過重或能力不足。
- [Sandbox 與 Approvals](https://harness-book.ycnets.com/docs/security/sandbox-and-approvals.md): Coding agent 的安全不能只靠一句：
- [Permission Profiles、Rules 與 Network Policy](https://harness-book.ycnets.com/docs/security/permissions-rules-network.md): Sandbox 模式回答的是粗粒度 capability；現代 agent runtime 還需要更細的「哪些路徑、哪些 command、哪些 network domain、什麼條件下允許」。
- [Trust Boundaries 與常見安全誤區](https://harness-book.ycnets.com/docs/security/trust-boundaries.md): 安全設計最實用的方法不是背設定，而是畫 trust boundary。Codex harness 至少同時接觸 user、repository、model、local machine、MCP servers、network services、CI secrets。
- [config.toml 與設定優先序](https://harness-book.ycnets.com/docs/customization/config.md): 如果你第一次看 Codex 設定，不要先背幾十個 key。
- [AGENTS.md：Repository Instructions](https://harness-book.ycnets.com/docs/customization/agents-md.md): `AGENTS.md` 最適合放「這個 repository 的 agent 必須知道，但不容易光靠讀 code 推斷」的規則。
- [Skills 與 Plugins：Progressive Disclosure](https://harness-book.ycnets.com/docs/customization/skills-and-plugins.md): Skill 的核心不是「再寫一份 prompt」，而是 **讓專門知識按需進 context**。
- [MCP：把外部能力接進 Harness](https://harness-book.ycnets.com/docs/customization/mcp.md): MCP（Model Context Protocol）讓 Codex 能連接外部 tool/resource server，而不必把每個 SaaS/API integration 寫死在 core。
- [Hooks：觀察、阻擋、改寫與整合](https://harness-book.ycnets.com/docs/customization/hooks.md): Hooks 是在 agent lifecycle 的特定事件插入 deterministic 程式邏輯。它非常適合把組織流程接進 harness，但不要把它誤認為唯一安全 boundary。
- [Subagents 與 Git Worktrees](https://harness-book.ycnets.com/docs/customization/subagents-and-worktrees.md): Subagent 解的是「把問題分解並平行化」，worktree 解的是「讓多個寫入工作彼此隔離」。兩者結合，才真正適合 parallel coding。
- [Codex CLI：Interactive Harness](https://harness-book.ycnets.com/docs/usage/cli.md): Codex CLI 不只是「在終端機輸入 Prompt」。
- [codex exec：非互動與 CI](https://harness-book.ycnets.com/docs/usage/noninteractive-ci.md): `codex exec` 是把完整 agent loop 放入 script/CI 的最低摩擦方式。
- [Codex SDK：程式化使用 Harness](https://harness-book.ycnets.com/docs/usage/sdk.md): SDK 適合在應用程式內啟動與延續 Codex task，又不想直接處理 App Server 的完整 protocol。
- [App Server：建立自己的 Codex Client](https://harness-book.ycnets.com/docs/usage/app-server.md): 若你要做「自己的 Codex UI」，最核心的整合點就是 App Server。
- [GitHub Actions 與 Codex](https://harness-book.ycnets.com/docs/usage/github-actions.md): OpenAI 提供 `openai/codex-action@v1`，讓 GitHub Actions workflow 安裝/執行 Codex，適合把 agent 放進 PR、release、maintenance automation。
- [DeepSeek Harness：Composable Runtime 完整導讀](https://harness-book.ycnets.com/docs/deepseek/overview.md): > 最後核對：2026-08-24。DeepSeek Harness 專案整體仍屬快速演進階段；教材把 architecture principles、package contracts 與產品成熟度分開看。
- [官方視角：DeepSeek Harness Lifecycle 與 Tool Pipeline](https://harness-book.ycnets.com/docs/deepseek/official-visuals.md): DeepSeek Harness 的官方 repo 和 Codex 不太一樣：它很少用產品宣傳截圖解釋架構，反而把大量「正式架構圖」直接寫成 Mermaid 放在文件裡，而且由 repo scripts 維護與驗證。
- [Cordis 與 Everything-is-a-Plugin 架構](https://harness-book.ycnets.com/docs/deepseek/architecture.md): DeepSeek Harness 最關鍵的架構選擇不是某個 Tool，而是：
- [Model Adapter 與 Agent Loop](https://harness-book.ycnets.com/docs/deepseek/model-and-agent-loop.md): DeepSeek Harness 的一個核心設計是：**Model 連線與 Agent Loop 是兩個不同 capability seam。**
- [Tool Execution：Registry、Guard、Sandbox 與 Result Pipeline](https://harness-book.ycnets.com/docs/deepseek/tool-execution.md): DeepSeek Harness 的 Tool 並不是「Agent Loop 裡的一個 switch-case」。Tool Registry、policy interception、executor、sandbox、result finalization 都有各自的 boundary。
- [Context、System Prompt 與 Compaction](https://harness-book.ycnets.com/docs/deepseek/context-and-compaction.md): DeepSeek Harness 把「Model 這一輪看到什麼」拆成幾個可獨立理解的責任：
- [Session、Events 與可追溯狀態](https://harness-book.ycnets.com/docs/deepseek/session-and-events.md): DeepSeek Harness 把 **append-only SessionEvent log** 放在 Runtime 的中心。這不是「把聊天存起來」，而是把會影響 trajectory 的 durable facts 記成可重建事件流。
- [使用方式：Profiles、Bundles 與啟動組合](https://harness-book.ycnets.com/docs/deepseek/usage-and-profiles.md): 這一章回答一個最實際的問題：
- [Models、Skills、Subagents、Hooks 與 Extensions](https://harness-book.ycnets.com/docs/deepseek/models-skills-and-extensions.md): DeepSeek Harness 雖然以「Everything is a Plugin」為底層哲學，但對 Agent 使用者來說，仍有清楚的高階 capability families。
- [Skills、Subagents、Workflows 與長生命週期工作](https://harness-book.ycnets.com/docs/deepseek/subagents-workflows-and-jobs.md): DeepSeek Harness 的擴充不只是一個泛稱「Plugin」。對 Model 可見的工作能力已經被拆成多個不同語意的 subsystem：
- [Code Mode、Capability 與 Runtime 組合](https://harness-book.ycnets.com/docs/deepseek/code-mode-and-plugins.md): DeepSeek Harness 的 Code Mode 很容易被看成「比較花俏的 Tool Calling」，但真正值得學的是：
- [安全模型：Sandbox、Approval 與 Permission Presets](https://harness-book.ycnets.com/docs/deepseek/security-and-approvals.md): DeepSeek Harness 將安全責任拆成多個相對獨立 capability：
- [Permission、Credentials 與 Execution Worlds](https://harness-book.ycnets.com/docs/deepseek/execution-worlds-and-credentials.md): DeepSeek Harness 的安全模型不只是一個 `sandboxMode`。真正的 execution boundary 由多個 responsibility 一起形成：
- [CLI、Headless 與 Automation](https://harness-book.ycnets.com/docs/deepseek/headless-and-automation.md): 理解 DeepSeek Harness 不能只看 Cordis source。真正使用時，最重要的是知道：**你啟動的是哪一個 Profile，以及這次 process 會組出什麼 Runtime。**
- [整合介面：Web、SDK、JSON-RPC、ACP 與自製 Client](https://harness-book.ycnets.com/docs/deepseek/integration-surfaces.md): DeepSeek Harness 沒有把所有 client integration 收斂成單一 protocol 名稱，而是提供多個用途不同的 surface：
- [Production、測試、Invariant 與成熟度](https://harness-book.ycnets.com/docs/deepseek/production-and-testing.md): DeepSeek Harness 的 production 評估要同時看兩層：
- [Pi Agent Harness：Minimal Runtime 完整導讀](https://harness-book.ycnets.com/docs/pi/overview.md): > 最後核對：2026-08-24。Pi 官方直接把自己稱為 **Agent Harness**；目前主要 repository 是 [`earendil-works/pi`](https://github.com/earendil-works/pi)。
- [官方視角：Pi TUI 與 Session Tree](https://harness-book.ycnets.com/docs/pi/official-visuals.md): Pi 很適合直接看官方截圖，因為它的產品哲學和架構哲學高度一致：**介面保持輕量，功能透過 Extensions / Skills / Packages 擴充；Session 則直接把 branch 做進資料模型。**
- [Pi 架構：從 pi-ai 到 AgentSession](https://harness-book.ycnets.com/docs/pi/architecture.md): Pi 的架構最好分成三層讀，而不是把 `pi-coding-agent` 當成唯一核心：
- [Model Providers：pi-ai 與多模型 Runtime](https://harness-book.ycnets.com/docs/pi/model-providers.md): Pi 從底層就把 Model Provider 做成獨立 package：`pi-ai`。
- [Agent Loop 與 Tools：Minimal Core 怎麼工作](https://harness-book.ycnets.com/docs/pi/agent-loop-and-tools.md): Pi 的 minimal philosophy 最容易從 `pi-agent-core` 與預設 Tools 看懂。
- [Context、Compaction 與 Branching](https://harness-book.ycnets.com/docs/pi/context-compaction-and-branching.md): Pi 的 Context 設計必須和它的 Tree Session 一起看。
- [Pi Session、Compaction 與 Extensions](https://harness-book.ycnets.com/docs/pi/session-and-extensions.md): Pi 最有辨識度的兩個 architectural choice 是：
- [Resources、Skills、Prompts 與 Pi Packages](https://harness-book.ycnets.com/docs/pi/resources-skills-and-packages.md): Pi 維持 minimal core 的關鍵，不只是 Extension API，而是一整套 **Resource discovery + distribution** 模型。
- [Extensions 與自訂 TUI](https://harness-book.ycnets.com/docs/pi/extensions-and-ui.md): Pi 的 TypeScript Extension 是它最寬的一個 customization surface。
- [Project Trust 與 Containerization](https://harness-book.ycnets.com/docs/pi/project-trust-and-isolation.md): Pi 的安全模型必須先記住一句官方原則：
- [CLI 與日常使用](https://harness-book.ycnets.com/docs/pi/cli-and-usage.md): Pi 的 terminal experience 是它最直接的產品入口。理解 CLI 不只是背 flags，而是看 **Model、Session、Tools、Resources、Trust** 怎麼在一個 AgentSession 裡組合。
- [SDK 與 RPC：把 Pi 嵌入自己的產品](https://harness-book.ycnets.com/docs/pi/sdk-and-rpc.md): Pi 不只是一個 TUI。官方提供兩條很不一樣的 embedding 路線：
- [Production 與 Governance：Minimal Harness 的責任清單](https://harness-book.ycnets.com/docs/pi/production-and-governance.md): Pi 可以很快被改造成高度客製的 Coding Agent，但 production 使用真正要問的是：
- [Lab 1：完整追蹤一次 Turn](https://harness-book.ycnets.com/docs/labs/trace-a-turn.md): 目標：把抽象的 agent loop 變成你可以觀察的事件。
- [Lab 2：做一套 Guardrails](https://harness-book.ycnets.com/docs/labs/guardrails.md): 目標：把「請不要做危險操作」改造成 deterministic control。
- [Lab 3：寫一個最小 App Server Client](https://harness-book.ycnets.com/docs/labs/embed-app-server.md): 目標：不透過 TUI，直接理解 App Server 的雙向 lifecycle。
- [Lab：Trace 一次 DeepSeek Turn / Step](https://harness-book.ycnets.com/docs/deepseek/labs/trace-turn-step.md): 這個 Lab 的目標不是只「跑起 dsh」，而是把一次工作拆成：
- [Lab：加入一個 DeepSeek Capability](https://harness-book.ycnets.com/docs/deepseek/labs/capability-plugin.md): 這個 Lab 練的是 DeepSeek Harness 最核心的設計語言：
- [Lab：Replay、Invariant 與 Session Correctness](https://harness-book.ycnets.com/docs/deepseek/labs/replay-invariant.md): DeepSeek Harness 的 event-sourced Session 最有價值的地方，是 correctness 可以被直接測試，而不只靠 UI 看起來正常。
- [Lab：Trace Pi Session 與 AgentSession](https://harness-book.ycnets.com/docs/pi/labs/session-tree.md): 這個 Lab 要把 Pi 的兩個 state boundary 分開看：
- [Lab：寫一個 Pi Extension](https://harness-book.ycnets.com/docs/pi/labs/extension.md): 這個 Lab 用最小 Extension 同時練三件事：
- [Lab：Branch、Tree 與 Compaction](https://harness-book.ycnets.com/docs/pi/labs/branch-compaction.md): 這個 Lab 專門驗證 Pi 最有辨識度的 state model：**同一個 Session 是一棵可操作的 JSONL Tree。**
- [比較框架：如何比較 Agent Harness](https://harness-book.ycnets.com/docs/comparison/overview.md): > 最後核對：2026-08-24。本章比較的是 Harness architecture 與 adoption trade-off，不是 GPT、DeepSeek 或其他模型本身的能力。
- [架構維度逐項比較：Codex、DeepSeek Harness、Pi](https://harness-book.ycnets.com/docs/comparison/architecture-comparison.md): 這一頁只做一件事：用同一組 architecture dimensions，逐項比較三套 Harness。
- [情境式選型：什麼時候選 Codex、DeepSeek Harness 或 Pi？](https://harness-book.ycnets.com/docs/comparison/scenario-selection.md): 前一頁已經把三套 Harness 放進同一組架構維度；這一頁不再重複那些定義，而是把它們放進實際產品情境。
- [PoC、採用與混用策略](https://harness-book.ycnets.com/docs/comparison/adoption-playbook.md): 做到這裡，選型不應再停在「我覺得哪套比較適合」。真正要做的是把判斷變成可驗證的 PoC。
- [實務工作流：把 Agent Loop 變成可驗證工程流程](https://harness-book.ycnets.com/docs/applications/workflows.md): 真正有效的 Agent Harness 應用，不是把需求改寫成「請 AI 幫我做」，而是把工程目標拆成可觀察、可執行、可限制、可驗證的閉環。
- [行為到底該放在哪一層？](https://harness-book.ycnets.com/docs/applications/where-should-behavior-live.md): 客製 Agent Harness 最常見的錯誤，不是功能做不出來，而是**把 behavior 放錯責任層**。
- [從零設計自己的 Agent Harness](https://harness-book.ycnets.com/docs/applications/build-your-own-harness.md): 如果已經理解 Codex、DeepSeek Harness 與 Pi，設計自己的 Harness 時最重要的不是複製其中一套，而是知道：
- [Production Harness Checklist](https://harness-book.ycnets.com/docs/applications/production-checklist.md): 把 Agent 放到 production 前，不要只問「模型夠不夠強」。真正需要驗證的是 Harness 是否能在模型判斷錯誤時，仍把 damage、cost 與 operational risk 限制在可接受範圍。
- [Glossary：Agent Harness 三方名詞速查](https://harness-book.ycnets.com/docs/reference/glossary.md): 這份 Glossary 先放**通用概念**，再分 Codex、DeepSeek Harness、Pi。目的不是把三套名詞硬翻成同一套，而是知道它們各自在回答哪一種 responsibility。
- [三套 Harness 原始碼導讀入口](https://harness-book.ycnets.com/docs/reference/source-reading.md): 本教材現在把 Codex、DeepSeek Harness 與 Pi 當成三套完整 architecture case study，因此 source reading 也用同一組 responsibility 來並讀。
- [openai/codex 原始碼導讀地圖](https://harness-book.ycnets.com/docs/reference/source-map.md): 本頁不是完整 crate catalog，而是用「你想理解什麼」來決定去哪裡看。
- [deepseek-ai/deepseek-harness 原始碼導讀地圖](https://harness-book.ycnets.com/docs/reference/deepseek-source-map.md): 本頁和 [`openai/codex` 原始碼導讀地圖](./source-map.md)採取相同原則：**不是列出所有 package，而是從「我想理解什麼」反推該從哪裡讀。**
- [earendil-works/pi 原始碼導讀地圖](https://harness-book.ycnets.com/docs/reference/pi-source-map.md): > 最後核對：2026-08-24。Pi repo 目前主線 package 名稱使用 `@earendil-works/*`。
- [官方閱讀清單與版本策略](https://harness-book.ycnets.com/docs/reference/reading-list.md): Codex、DeepSeek Harness 與 Pi 都演進很快。這份清單按「架構價值」排序，並盡量讓三套都覆蓋：