【DeepCode】Harness Engineering 标杆深度解析：HKU 16k stars 的完整 Agent 工程化实战

发表于 更新于 分类于 系列 🛠️ Harness Engineering 实战
深度剖析 HKUDS/DeepCode（16k stars）的 Agent Harness 工程化设计：core/harness/ 顶层目录承载的权限引擎 / 平台沙箱 / Hooks 总线 / 子 Agent 邮箱 + Loop Engineering + Context Engineering + Skills 协议 + MCP 不可变工具目录，看一个学术级 Harness 是怎么把"机制 vs 策略"分离做到极致的。

一句话结论：HKUDS/DeepCode 是当前 GitHub 上唯一一个用 core/harness/ 作为顶层目录命名的开源项目，它把 Harness Engineering 的六件套（Rule / Skill / Sub-Agent / Workflow / Script / MCP）当作一等公民分层实现，是研究 Harness 成熟度模型的标杆样本。

前言：为什么这次要拆 DeepCode？

过去 14 天，我连续写了 7 篇 Harness 主题深度解析：IronCurtain 的策略编译器、Strands 的 Hooks 中间件、superpowers 的 14 个 SOP Skill、ten-framework 的 Graph 数据流……每篇都对应 Harness 六件套矩阵里的一个组件。

但一直有个问题没解决：这些项目都只覆盖矩阵的一两个组件。IronCurtain 只讲 Rule；superpowers 只讲 Skill；Strands 只讲 Hooks。一个真正完整的 Harness 长什么样？ 答案藏在 HKUDS/DeepCode 这个项目里。

DeepCode 是香港大学 Data Intelligence Lab 出品的 Open Agentic Coding 平台，16.3k stars，2 天前刚 commit（2026-08-13），840+ 个文件。它做了件罕见的事：把 core/harness/ 作为顶层目录命名 —— 整个核心层就是 Harness：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
core/
├── harness/          # 🛡️ Harness 核心：权限 / 沙箱 / Hooks / 子 Agent
│   ├── agents/       #   - Sub-Agent 协调（C2，模型驱动的并发）
│   ├── hooks/        #   - 外部命令 Hook 总线（C3）
│   ├── permissions.py  #  - 三值权限引擎（allow/ask/deny）
│   ├── sandbox.py    #   - 平台沙箱（macOS seatbelt / Linux bwrap / Windows Job）
│   └── approval.py   #   - 终端审批交互
├── loop/             # ♻️ Loop Engineering：autodream 离线记忆整理
├── skills/           # 📚 Skill Provider 协议：能力声明 + 不可变清单
├── mcp/              # 🔌 MCP 不可变工具目录 + OAuth
├── plugins/          # 📦 Plugin 协议（Agent Plugins 1.0.0 manifest）
├── sessions/         # 💾 Session 持久化
├── observability/    # 👁️ 日志 / Trace
├── schedule/         # ⏰ 后台任务调度
└── team/             # 🤝 团队协作（multi-workspace 协调）

读完这篇你会得到：

  1. Harness 六件套在 DeepCode 里如何分层（不是堆在一起，是按”机制 / 策略”切开）
  2. 三值权限引擎的真实代码（allow/ask/deny + last-match-wins + sensitive-path 强制）
  3. HooksEngine 的 fold 算法（5 个生命周期事件 + 声明序 vs 完成序分裂）
  4. Sub-Agent 邮箱 + Worktree 隔离（不阻塞 spawn + git worktree 隔离 + 3-way merge）
  5. Skills Provider 协议设计（Opaque ID + 不可变清单 + 能力声明）
  6. 与 Claude Code / OpenAI Agents SDK 的设计哲学对比

一、DeepCode 在 Harness 六件套里的定位

1.1 六件套覆盖度矩阵

组件DeepCode 实现关键文件评级
Rulecore/harness/permissions.py（三值）+ 集中式敏感路径硬约束permissions.py:53-79⭐⭐⭐⭐⭐
Skillcore/skills/（完整 Provider 协议 + 不可变清单 + 能力声明）skills/models.py, skills/host.py⭐⭐⭐⭐⭐
Sub-Agentcore/harness/agents/control.py（邮箱通信 + 5 并发 + worktree 隔离）agents/control.py⭐⭐⭐⭐⭐
Workflowworkflows/（交互工作流定义，YAML + agents/）workflows/⭐⭐⭐
Scriptcore/harness/sandbox.py（硬关卡：seatbelt/bwrap/Job）sandbox.py⭐⭐⭐⭐⭐
MCPcore/mcp/（不可变 Runtime Plan + OAuth + Preset 目录）mcp/runtime.py⭐⭐⭐⭐⭐

DeepCode 是当前唯一一个把六件套组件全部实现到工程级别（不是 demo）的开源 Harness。其他项目要么只覆盖 1-2 件套（IronCurtain 只做 Rule、Strands 只做 Hooks），要么是更上层的产品包装（metaHarness、Yuxi）。DeepCode 是中间的”机制层”。

1.2 设计哲学：机制 vs 策略

DeepCode 的核心设计文档（core/harness/__init__.py:1-9）开篇就定调：

Design rule: these modules are pure mechanism — they decide and wrap, they never talk to models or UIs. Enforcement points live in the kernel (AgentRunSpec.permission_checker) and in tool executors.

翻译：Harness 模块只负责”决定和包装”，绝不和模型对话，也不和 UI 对话。策略调用（要不要询问、怎么询问）由 kernel 注入。

这种机制（mechanism）与策略（policy）的彻底分离是 DeepCode 区别于大多数 Harness 项目的核心设计哲学。我把它总结为一句话：

DeepCode 提供”决策原语”，不提供”决策答案”。

二、架构深度解析：从入口到 6 件套

2.1 顶层架构图

graph TB
    User["👤 用户<br/>CLI / Desktop / Headless"]
    
    App["🚀 Application 层<br/>core/application/<br/>DeepCodeApplication"]
    
    subgraph Harness["🛡️ core/harness/ (Harness 核心)"]
        Perm["⚙️ PermissionEngine<br/>三值 allow/ask/deny<br/>last-match-wins"]
        Sand["🔒 SandboxBackend<br/>seatbelt/bwrap/Job"]
        Hook["🪝 HooksEngine<br/>10 个生命周期事件"]
        Agent["🤖 AgentControl<br/>Sub-Agent 邮箱 + worktree"]
    end
    
    subgraph Loop["♻️ Loop Engineering"]
        AutoDream["💤 autodream<br/>离线记忆整理"]
    end
    
    subgraph Skills["📚 core/skills/"]
        SkillHost["SkillCatalogHost<br/>不可变清单"]
        SkillProvider["SkillProvider<br/>local/executor/orchestrator"]
    end
    
    subgraph MCP["🔌 core/mcp/"]
        McpPlan["McpRuntimePlan<br/>不可变"]
        McpRuntime["McpSessionRuntime<br/>→ ToolRegistry"]
    end
    
    Kernel["🧠 Agent Kernel<br/>core/agent_runtime/"]
    Sessions["💾 Session<br/>core/sessions/"]
    
    User --> App
    App --> Kernel
    App --> Harness
    App --> Skills
    App --> MCP
    Kernel --> Sessions
    Hook -.->|"事件触发"| Kernel
    Perm -.->|"拦截工具调用"| Kernel
    Sand -.->|"包装 shell 命令"| Kernel
    Agent -.->|"spawn / interrupt"| Kernel
    SkillHost -.->|"加载 SOP"| Kernel
    McpRuntime -.->|"注册工具"| Kernel
    AutoDream -.->|"整理 memory"| Sessions
    
    style User fill:#C7CEEA,stroke:#9FA8DA,color:#333
    style App fill:#E8D5F5,stroke:#CE93D8,color:#333
    style Kernel fill:#E8D5F5,stroke:#CE93D8,color:#333
    style Sessions fill:#F5F5F5,stroke:#999,color:#333
    style Perm fill:#FFB3C6,stroke:#F48FB1,color:#333
    style Sand fill:#FFB3C6,stroke:#F48FB1,color:#333
    style Hook fill:#FFB3C6,stroke:#F48FB1,color:#333
    style Agent fill:#FFB3C6,stroke:#F48FB1,color:#333
    style AutoDream fill:#FFF9C4,stroke:#F9A825,color:#333
    style SkillHost fill:#B5EAD7,stroke:#80CBC4,color:#333
    style SkillProvider fill:#B5EAD7,stroke:#80CBC4,color:#333
    style McpPlan fill:#FFDAB9,stroke:#FFB74D,color:#333
    style McpRuntime fill:#FFDAB9,stroke:#FFB74D,color:#333

2.2 数据流：从用户输入到工具执行

sequenceDiagram
    participant U as 👤 用户
    participant A as 🚀 Application
    participant K as 🧠 Agent Kernel
    participant P as ⚙️ PermissionEngine
    participant H as 🪝 HooksEngine
    participant S as 🔒 Sandbox
    participant T as 🔧 ToolExecutor
    participant Sk as 📚 Skill Catalog
    participant M as 🔌 MCP Runtime
    
    U->>A: 输入任务 ("重构 auth 模块")
    A->>K: 启动 Turn
    K->>Sk: 搜索匹配的 Skill
    Sk-->>K: 返回 selected Skill (≤8 个)
    K->>K: 拼装 system prompt + skills
    K->>M: ensure_started() (OAuth / 连接)
    M-->>K: tool registry (合并 MCP 工具)
    K->>A: 返回初始 LLM 请求
    
    loop 模型决策循环
        K->>P: 评估工具调用 (tool_name, args)
        P-->>K: ALLOW / DENY / ASK
        alt ALLOW
            K->>H: run_pre_tool_use
            H-->>K: PreToolUseOutcome
            K->>S: wrap_shell_command(cmd)
            S-->>K: sandboxed_cmd
            K->>T: 执行
            T-->>K: tool_response
            K->>H: run_post_tool_use
            H-->>K: PostToolUseOutcome
        else DENY
            K-->>A: 工具被拒，返回错误给模型
        else ASK
            K->>U: TerminalApprover.ask()
            U-->>K: 用户决定
        end
    end
    
    K->>A: Turn 完成
    A->>H: run_stop (停止钩子)

关键观察：整个数据流中，Harness 层是纯横向拦截器（pre / post tool use），不参与决策内容。这种”拦截器式”架构让 DeepCode 可以独立升级 Harness 而不动 Kernel。

三、核心机制原理（含可运行代码）

3.1 三值权限引擎（Rule 组件）

DeepCode 的权限引擎是六件套中”Rule”组件的工程化典范。它有 3 个核心设计：

  1. 三值语义：allow / ask / deny，比 Claude Code 的二元（allow/deny）更精准
  2. last-match-wins：多个规则匹配时，后者覆盖前者
  3. 集中式 sensitive-path 保护：硬约束 .ssh / .aws/credentials / .env 等敏感路径

3.1.1 真实代码（来自 core/harness/permissions.py）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
# 简化版 PermissionEngine 核心逻辑
from dataclasses import dataclass, field
from enum import Enum
from pathlib import Path
import fnmatch, os

class PermissionDecision(str, Enum):
    ALLOW = "allow"
    ASK = "ask"
    DENY = "deny"

class PermissionMode(str, Enum):
    DEFAULT = "default"      # 写工具默认 ask
    PLAN = "plan"            # 写工具默认 deny (只读探索)
    FULL_AUTO = "full_auto"  # 仅规则生效，无隐式 ask

# 集中式敏感路径（来自 permissions.py:53-79）
SENSITIVE_PATH_PATTERNS = (
    "*/.ssh", "*/.ssh/*",
    "*/.aws/credentials", "*/.aws/config",
    "*/.config/gcloud/*", "*/.azure/*", "*/.gnupg/*",
    "*/.docker/config.json", "*/.kube/config",
    "*/.netrc", "*/.npmrc", "*/.pypirc",
    "*/.git-credentials", "*/.deepcode/credentials*",
    "*/deepcode_config.json", "*/secrets.json",
    "*/.env", "*/.env.*",
    "*.pem", "*.key", "*id_rsa*", "*id_ed25519*",
)

# 只读工具白名单（来自 permissions.py:99-122）
_READ_ONLY_TOOLS = frozenset({
    "read_file", "read_multiple_files", "read_code_mem",
    "get_file_structure", "search_code", "search_code_references",
    "get_indexes_overview", "get_operation_history",
    "grep", "glob", "ls", "list_dir", "web_fetch", "update_plan",
})

@dataclass(frozen=True)
class PermissionRule:
    """(permission, pattern) -> action"""
    permission: str  # 工具名（fnmatch 模式）
    pattern: str     # 参数模式（命令字符串或路径）
    action: PermissionDecision

    def matches(self, tool_name: str, argument: str) -> bool:
        return (fnmatch.fnmatch(tool_name, self.permission)
                and fnmatch.fnmatch(argument, self.pattern))

@dataclass
class PermissionEngine:
    mode: PermissionMode = PermissionMode.DEFAULT
    rules: list[PermissionRule] = field(default_factory=list)
    protect_sensitive_paths: bool = True

    def evaluate(self, tool_name: str, tool_input: dict) -> PermissionDecision:
        argument = self._extract_argument(tool_name, tool_input)

        # 1. 敏感路径硬约束（最高优先级，不可绕过）
        if self.protect_sensitive_paths and self._matches_sensitive_path(argument):
            return PermissionDecision.DENY

        # 2. PLAN 模式：写工具一律拒绝
        if self.mode == PermissionMode.PLAN and tool_name not in _READ_ONLY_TOOLS:
            return PermissionDecision.DENY

        # 3. 显式规则匹配（last-match-wins）
        matched_action = None
        for rule in self.rules:
            if rule.matches(tool_name, argument):
                matched_action = rule.action  # 持续覆盖，最后一次胜出

        if matched_action is not None:
            return matched_action

        # 4. 默认行为
        if tool_name in _READ_ONLY_TOOLS:
            return PermissionDecision.ALLOW
        return PermissionDecision.ASK if self.mode == PermissionMode.DEFAULT else PermissionDecision.ALLOW

    def _matches_sensitive_path(self, argument: str) -> bool:
        for pattern in SENSITIVE_PATH_PATTERNS:
            if fnmatch.fnmatch(argument, pattern):
                return True
        return False

3.1.2 为什么是三值不是两值？

Claude Code 用 allow / deny 两值，DeepCode 用 allow / ask / deny 三值。这不是设计偏好，是真实场景需要：

场景Claude CodeDeepCode
用户没配规则的 npm install❓ 默认行为模糊✅ ASK：询问用户
用户配了规则 git push *❓ 行为不明✅ ASK：明确询问
git status✅ ALLOW✅ ALLOW
.ssh/ 读取✅ DENY（但用户能改）✅ DENY（硬约束，不可改）

关键差异：DeepCode 把”sensitive-path 保护”作为不可绕过的硬约束，和”用户规则”完全分层。即使 Full Access 模式也只能关闭它自己配的规则集合，不能关 sensitive-path。

3.2 平台沙箱（Script 组件）

3.2.1 三平台后端

DeepCode 的 core/harness/sandbox.py 实现了一个机制层沙箱：根据平台自动选择：

平台后端隔离强度关键文件
macOSsandbox-exec (seatbelt)closed-by-default SBPL 策略_SEATBELT_BASE_POLICY
Linuxbwrap (bubblewrap)mount-namespace + --unshare-netwrap_shell_command
WindowsJob ObjectKILL_ON_JOB_CLOSE 进程树隔离core/harness/windows_sandbox

3.2.2 真实代码片段（macOS seatbelt）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# 来自 core/harness/sandbox.py:18-110
# Chrome 启发的 closed-by-default 沙箱策略
_SEATBELT_BASE_POLICY = r"""(version 1)

; Chrome-inspired closed-by-default sandbox policy.
; start with closed-by-default
(deny default)

; child processes inherit the policy of their parent
(allow process-exec)
(allow process-fork)
(allow signal (target same-sandbox))

; sysctls permitted (白名单 sysctl-read)
(allow sysctl-read
  (sysctl-name "hw.activecpu")
  (sysctl-name "hw.busfrequency_compat")
  ...
  (sysctl-name-prefix "hw.perflevel"))

; needed for Python multiprocessing on macOS for the SemLock
(allow ipc-posix-sem)

; Needed for PyTorch/libomp on macOS to register OpenMP runtimes.
(allow ipc-posix-shm-read-data
  ipc-posix-shm-write-create
  ipc-posix-shm-write-unlink
  (ipc-posix-name-regex #"^/__KMP_REGISTERED_LIB_[0-9]+$"))

; allow openpty()
(allow pseudo-tty)
(allow file-read* file-write* file-ioctl (literal "/dev/ptmx"))
"""

def wrap_shell_command(cmd: str, policy: SandboxPolicy) -> list[str]:
    """返回可在沙箱内执行的命令列表"""
    backend = sandbox_backend()  # 检测平台
    if backend == "seatbelt":
        sbpl = _seatbelt_profile(policy)
        return ["/usr/bin/sandbox-exec", "-f", sbpl, "sh", "-c", cmd]
    elif backend == "bwrap":
        return ["bwrap", "--ro-bind", "/", "/",
                "--bind", str(policy.writable_root), str(policy.writable_root),
                "--tmpfs", "/tmp", "--unshare-net", "--", "sh", "-c", cmd]
    elif backend == "job":
        return windows_job_wrap(cmd, policy)
    else:
        return ["sh", "-c", cmd]  # 退化：不隔离

3.2.3 设计哲学：诚实的边界

core/harness/sandbox.py 的文档明确说出 DeepCode 不假装自己做了 seccomp-bpf：

Honest boundary: the reference agent adds seccomp-bpf + Landlock on Linux; those are kernel facilities Python cannot install from userspace, so DeepCode relies on bubblewrap’s namespaces (a real, standard isolation primitive) rather than faking an equivalent.

翻译：参考 agent 加了 seccomp-bpf + Landlock，但这两个是内核能力，Python 从用户态装不上。所以 DeepCode 不假装，只用 bubblewrap 的 mount-namespace（一个真实的标准隔离原语）替代。

这种”诚实承认能力边界”是 DeepCode 的核心风格 —— 它宁可显式说”Windows 的 Job Object 不限制写入，只做进程树隔离”，也不假装说”全方位沙箱”。

3.3 HooksEngine 总线（Script 组件的外部化）

3.3.1 10 个生命周期事件

HooksEngine 实现了完整的 Claude-Code 兼容事件总线：

事件时机关键字段
SessionStart会话开始source: "startup"
UserPromptSubmit用户提交 promptprompt
PreToolUse工具调用前tool_name, tool_input
PostToolUse工具调用后tool_response
PermissionRequest权限请求时tool_name, tool_input
PreCompact / PostCompact上下文压缩前后trigger
SubagentStart / SubagentStop子 Agent 启停agent_id, agent_type
StopTurn 结束stop_hook_active

3.3.2 真实代码：fold 算法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# 来自 core/harness/hooks/engine.py:130-180
@staticmethod
def _fold(completions: list[tuple[int, HandlerDecision]]) -> _FoldedOutcome:
    """合并多 handler 结果"""
    folded = _FoldedOutcome()

    # 1. 声明序合并 reason / context（稳定报告）
    by_declaration = sorted(completions, key=lambda item: item[0])
    for _order, decision in by_declaration:
        if decision.system_message:
            folded.system_messages.append(decision.system_message)
        if decision.invalid_reason:
            folded.warnings.append(decision.invalid_reason)
        if decision.error:
            folded.warnings.append(decision.error)
        # 任何 handler fail = 整个 hook 失败
        if decision.status == "failed":
            folded.warnings.append(f"handler failed: {decision.error}")
            continue

        # BLOCK: 任一拒绝 = 拒绝（first block 胜出）
        if decision.block:
            if not folded.block:  # 第一次 block 胜出
                folded.block = True
                folded.block_reason = decision.block_reason

        # additionalContext: 全部累积
        if decision.additional_context:
            folded.additional_contexts.append(decision.additional_context)

        # updatedInput: 完成序（last writer wins）
        # 推迟到下面

    # 2. updatedInput 完成序合并（最后完成者胜出）
    by_completion = sorted(completions, key=lambda item: item[1].completion_order)
    for _order, decision in by_completion:
        if decision.updated_input is not None:
            folded.updated_input = decision.updated_input  # 持续覆盖

    return folded

关键设计：声明序 vs 完成序的分裂

  • block / reason / context 走 声明序：报告稳定性，谁先声明谁先报告
  • updatedInput 走 完成序：实际生效按完成时间，最后完成的 handler 重写参数胜出

这种”双轨制 fold”是 HooksEngine 的灵魂 —— 让审计日志稳定（声明序），但实际拦截行为按时间发生（完成序）。

3.4 Sub-Agent 邮箱 + Worktree 隔离

3.4.1 核心数据类（来自 core/harness/agents/control.py）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@dataclass
class SubAgent:
    """一个被并发执行的子任务单元"""
    id: str                              # uuid
    task: str                            # 自然语言任务描述
    isolate: bool = True                 # 是否用 worktree 隔离
    backend: str = NATIVE_BACKEND        # native / codex-cli / claude-code
    persona: str | None = None           # 额外 system prompt 片段
    tool_names: tuple[str, ...] | None = None  # 工具白名单（缩窄权限）
    output_schema: dict | None = None    # 强制 capture 的 JSON Schema
    status: str = _RUNNING               # running / idle / done / failed
    result: str = ""                     # 最终结果
    seed_history: list = field(default_factory=list)  # fork_turns 继承的上下文
    inbox: list[tuple[str, str]] = field(default_factory=list)  # 来自父的消息
    wake: asyncio.Queue = field(default_factory=asyncio.Queue)  # 子 idle 时挂起
    settled: asyncio.Event = field(default_factory=asyncio.Event)  # 子有新进展通知

3.4.2 spawn 设计：非阻塞 + 5 并发上限

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# 简化版（来自 core/harness/agents/control.py:114-180）
MAX_CONCURRENT_SUBAGENTS = 5

class AgentControl:
    def spawn(self, task: str, *, name=None, isolate=True,
              fork_turns="none", backend=NATIVE_BACKEND,
              persona=None, tools=None, output_schema=None) -> str:
        """Start a sub-agent in the background and return its id (non-blocking)."""
        # 1. 去重检查：同名子任务已在跑则抛 DuplicateAgentError
        dedup_key = name or self._normalize_task(task)
        if any(a.dedup_key == dedup_key and a.running for a in self._agents.values()):
            raise DuplicateAgentError(f"{dedup_key} already running")

        # 2. 并发上限
        active = sum(1 for a in self._agents.values() if a.running)
        if active >= self._max_threads:
            raise AgentLimitError(f"max {self._max_threads} sub-agents")

        # 3. 创建子 + 启动后台 task（不阻塞）
        sub = SubAgent(id=uuid4().hex[:8], task=task, ...)
        self._agents[sub.id] = sub
        sub.handle = asyncio.create_task(self._run_subagent(sub))
        return sub.id

    async def wait_for_activity(self, timeout=None) -> list[SubAgent]:
        """Park on mailbox activity — return sub-agents that have news."""
        await asyncio.wait_for(self._activity.wait(), timeout=timeout)
        self._activity.clear()
        return [a for a in self._agents.values() if a.settled.is_set()]

3.4.3 Worktree 隔离（独立 git 环境）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 来自 core/harness/agents/control.py:62-64
"""Isolation is DeepCode's own guarantee: each sub-agent may run in its own git
worktree whose result is merged back with 3-way-merge conflict detection; base
git ops are serialised (_git_lock) while the sub-agents build in parallel."""

# 简化版：
async def _run_subagent(self, sub):
    if sub.isolate:
        async with self._git_lock:  # 序列化 git 操作
            worktree = create_worktree(sub.id)  # 独立 git worktree
        try:
            sub.result = await self._run_in_worktree(worktree, sub)
        finally:
            async with self._git_lock:
                await self._merge_back(worktree, sub)  # 3-way merge 回主分支

这个设计的精妙之处：

  1. 非阻塞 spawn：父 Agent 不用等子 Agent 完成，5 个子可以并发跑
  2. 去重：同名子任务 5 秒内重复 spawn 会被拒绝
  3. worktree 隔离：每个子有自己的 git 环境，互不污染
  4. _git_lock 序列化：git 元数据操作（worktree 创建、merge）只能一个一个做，但子任务内部可以并行 build
  5. 深度限制 1：allow_spawn=False 强制子不能再 spawn 子孙，避免递归爆炸

3.5 Skills Provider 协议（Skill 组件）

3.5.1 不可变 + Opaque ID 设计

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 来自 core/skills/models.py:36-43
@dataclass(frozen=True, slots=True)
class SkillPackageId:
    """Opaque package ID whose representation callers must not parse."""
    value: str
    def __post_init__(self):
        _validate_provider_handle("package", self.value)  # ≤2048 bytes, no control chars

@dataclass(frozen=True, slots=True)
class SkillAuthority:
    """Opaque provider identity used for list/read/search routing."""
    kind: SkillProviderKind  # LOCAL / EXECUTOR / ORCHESTRATOR / CUSTOM
    provider_id: str

@dataclass(frozen=True, slots=True)
class SkillReference:
    """Provider-owned address for one Skill package resource."""
    authority: SkillAuthority
    package: SkillPackageId
    resource: SkillResourceId

为什么 ID 不透明？

因为 DeepCode 支持多种 Skill 来源（本地 ~/.deepcode/skills/、Claude 兼容目录、executor 后端、orchestrator 后端）。如果用路径式 ID（/home/user/.deepcode/skills/foo），调用方就会对路径产生依赖，破坏协议中立性。Opaque ID 把”路径知识”封装在 Provider 内部，调用方只看到 sk_a1b2c3d4... 这种 ID。

3.5.2 Skill Turn Snapshot（每次 Turn 冻结一份）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 来自 core/skills/models.py 文档
"""Skill can declare tool and Skill dependencies; DeepCode expands them in
order, detects cycles, and fails before the first model request when a
requirement is unavailable.

Skills can search and read bounded package resources progressively, with
revision, traversal, symlink, and size checks applied at the shared provider
contract.

CLI, TUI, and Desktop share the same immutable Turn snapshot and persist
only Skill identity, invocation kind, and revision—not the instruction body."""

@dataclass(frozen=True, slots=True)
class SkillTurnSnapshot:
    """不可变的 Turn 时刻 Skill 状态"""
    identity: str           # Skill ID
    invocation_kind: str    # "auto" / "user-explicit"
    revision: str           # git commit hash / version
    # ⚠️ 不持久化 instruction body（防止 Skill 内容被审计日志泄露）

关键设计：

  • ✅ 持久化：身份（哪个 Skill）、调用类型、版本号
  • ❌ 不持久化：Instruction body（防止审计日志泄露 SOP 机密）

这是 DeepCode 在隐私 vs 可审计之间的精确平衡：能查到”这个 Turn 用了哪个 Skill v1.2.3”，但不能反推”SOP 写了什么”。

3.6 MCP 不可变 Runtime Plan（MCP 组件）

3.6.1 Runtime 是不可变的

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 来自 core/mcp/runtime.py:1-13
"""Session-scoped MCP lifecycle and immutable tool-catalog publication."""

# 简化版核心：
class McpSessionRuntime:
    def __init__(self, plan: McpRuntimePlan, registry: ToolRegistry, ...):
        self.plan = plan           # 不可变 plan
        self.registry = registry   # ToolRegistry 是被填充的目标
        self._started = False      # 一次性启动
        self._closed = False       # 一次性关闭

    async def ensure_started(self) -> None:
        async with self._lock:
            if self._closed:
                raise RuntimeError("MCP runtime is closed")
            if self._started:       # idempotent
                return
            # 启动所有 MCP 服务器
            ...
            self._started = True

    async def close(self) -> None:
        async with self._lock:
            if self._closed:
                return
            # 关闭所有连接
            ...
            self._closed = True

3.6.2 不可变 Runtime 的两个核心好处

  1. 启动幂等：重复 ensure_started() 不重复启动
  2. 不可中途改变 tool set：Turn 中想换 MCP 配置？必须重启 runtime，不会发生”半新半旧”状态

这与 Anthropic MCP 官方的 mcp-go 实现（连接可热替换）形成对比。DeepCode 选择”启动时确定，Turn 中不变”的简单模型，对 Agent 推理的稳定性更友好。

3.7 Loop Engineering：autodream 离线记忆整理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 来自 core/loop/autodream.py:9-23
"""autodream — background consolidation of the agent's persistent memory (P3).

Over many sessions the memory under ``<workspace>/.deepcode/memory/`` drifts:
duplicate notes, stale facts, a MEMORY.md index that no longer matches the
files. autodream is a focused, off-the-critical-path agent pass that tidies
it — merge duplicates, drop the stale, keep MEMORY.md a tight index — using
the same ``memory`` tool the agent writes with.
"""

_CONSOLIDATE_PROMPT = (
    "Consolidate your persistent memory. Use ONLY the `memory` tool — do not "
    "touch any other files. Steps: (1) `memory list`, then `memory read` each "
    "note; (2) merge duplicates and near-duplicates into a single note; "
    "(3) delete stale, obviously-wrong, or superseded notes; (4) rewrite "
    "`MEMORY.md` so it is a short, accurate index of the notes that remain. "
    "Keep every durable fact; only remove redundancy and staleness. Reply "
    "with a one-line summary of what you changed."
)

Loop Engineering 的精妙之处：

  • off-the-critical-path：autodream 不在主 Agent 推理循环里跑，是独立后台 task
  • scope 强制：prompt 显式约束”只许用 memory 工具”，加上 P1 权限引擎在 memory 目录外的硬约束，双重锁
  • 没有 test oracle：autodream 没有”对/错”二元判断，只有”before/after note 数量”这个机械信号，诚实地承认它的局限性

四、设计哲学：Bitter Lesson 自检

4.1 机制 vs 策略分层图

graph TB
    subgraph Policy["📜 策略层（Policy）"]
        UI["🖥️ UI 决策<br/>TerminalApprover"]
        Model["🧠 LLM 决策<br/>是否 ask / continue"]
        UserCfg["👤 用户配置<br/>YAML / settings.json"]
    end
    
    subgraph Mechanism["⚙️ 机制层（Mechanism）"]
        PermE["PermissionEngine<br/>fnmatch 决策"]
        SandE["SandboxBackend<br/>平台沙箱包装"]
        HookE["HooksEngine<br/>事件 fold"]
        AgentE["AgentControl<br/>邮箱调度"]
        SkillE["SkillProvider<br/>不可变清单"]
        McpE["McpRuntime<br/>启动/关闭"]
    end
    
    subgraph External["🌐 外部世界"]
        OS["💻 操作系统<br/>syscall / FS"]
        Net["🌐 网络<br/>OAuth / TLS"]
        User["👤 用户"]
    end
    
    UI -.->|"注入决策"| PermE
    Model -.->|"拼装 prompt"| SkillE
    UserCfg -.->|"解析规则"| PermE
    
    PermE --> OS
    SandE --> OS
    HookE --> OS
    AgentE --> User
    SkillE --> OS
    McpE --> Net
    
    style UI fill:#FFDAB9,stroke:#FFB74D,color:#333
    style Model fill:#FFDAB9,stroke:#FFB74D,color:#333
    style UserCfg fill:#FFDAB9,stroke:#FFB74D,color:#333
    style PermE fill:#E8D5F5,stroke:#CE93D8,color:#333
    style SandE fill:#E8D5F5,stroke:#CE93D8,color:#333
    style HookE fill:#E8D5F5,stroke:#CE93D8,color:#333
    style AgentE fill:#E8D5F5,stroke:#CE93D8,color:#333
    style SkillE fill:#E8D5F5,stroke:#CE93D8,color:#333
    style McpE fill:#E8D5F5,stroke:#CE93D8,color:#333
    style OS fill:#F5F5F5,stroke:#999,color:#333
    style Net fill:#F5F5F5,stroke:#999,color:#333
    style User fill:#C7CEEA,stroke:#9FA8DA,color:#333

DeepCode 在多个模块注释里反复强调一句话：

“Design rule: these modules are pure mechanism — they decide and wrap, they never talk to models or UIs.”

我对照 Sutton 的 Bitter Lesson 检查它的”机制 vs 策略”分层：

模块写了多少”聪明但终将被淘汰”的代码Bitter Lesson 评分
permissions.py0 —— 纯 fnmatch 字符串匹配，LLM 来了依然需要⭐⭐⭐⭐⭐
sandbox.py0 —— 直接调 OS 沙箱 API⭐⭐⭐⭐⭐
hooks/engine.py0 —— 调外部 shell 命令，结果 JSON 解析⭐⭐⭐⭐⭐
agents/control.py极少 —— 去重靠字符串、并发靠 asyncio⭐⭐⭐⭐
skills/models.py0 —— 全是不透明 dataclass⭐⭐⭐⭐⭐
mcp/runtime.py0 —— 启动/关闭/状态机⭐⭐⭐⭐⭐

结论：DeepCode 的 Harness 层几乎不含”聪明”代码。每个组件都是”接 OS 接口 + 包装数据 + 暴露 API”，LLM 进化不需要重写 Harness —— 这正是 Bitter Lesson 的胜利。

五、横向对比：DeepCode vs Claude Code vs OpenAI Agents SDK

5.0 HooksEngine fold 双轨合并图

graph LR
    H1["🔧 handler_1<br/>(order=0)"]
    H2["🔧 handler_2<br/>(order=1)"]
    H3["🔧 handler_3<br/>(order=2)"]
    
    H1 -->|"完成序"| Fold1["📋 _FoldedOutcome"]
    H2 -->|"完成序"| Fold1
    H3 -->|"完成序"| Fold1
    
    H1 -->|"声明序"| Fold2["📋 block / reason / context"]
    H2 -->|"声明序"| Fold2
    H3 -->|"声明序"| Fold2
    
    Fold2 -->|"任一 block"| Block["🛑 BLOCK<br/>(first-block-wins)"]
    Fold2 -->|"全部累积"| Ctx["📝 additionalContexts<br/>(accumulate all)"]
    Fold1 -->|"最后完成者"| Upd["✏️ updatedInput<br/>(last-writer-wins)"]
    
    style H1 fill:#C7CEEA,stroke:#9FA8DA,color:#333
    style H2 fill:#C7CEEA,stroke:#9FA8DA,color:#333
    style H3 fill:#C7CEEA,stroke:#9FA8DA,color:#333
    style Fold1 fill:#E8D5F5,stroke:#CE93D8,color:#333
    style Fold2 fill:#E8D5F5,stroke:#CE93D8,color:#333
    style Block fill:#FFB3C6,stroke:#F48FB1,color:#333
    style Ctx fill:#FFF9C4,stroke:#F9A825,color:#333
    style Upd fill:#B5EAD7,stroke:#80CBC4,color:#333

5.1 三者核心差异

维度DeepCodeClaude CodeOpenAI Agents SDK
Rule 引擎三值（allow/ask/deny）+ 强制 sensitive-path二值（allow/deny）+ 用户配置无引擎，工具调用全放开
沙箱平台原生（seatbelt/bwrap/Job）OS 级（macOS seatbelt）无沙箱，靠应用层
Hooks 事件10 个生命周期事件 + 双轨 fold5-6 个事件 + 单 fold无 hooks
Sub-Agent模型驱动 spawn + worktree 隔离 + 邮箱Task tool 调用 + 单 in-process AgentHandoff 协议 + 显式 context 转移
SkillsProvider 协议 + Opaque ID + Turn SnapshotSKILL.md 文件系统 + 简单加载无 Skills 概念
MCP不可变 Runtime Plan标准 MCP 客户端标准 MCP 客户端
代码可读性高（每个模块顶部大段设计文档）低（闭源）中（Python 包）
学术血统HKU Data Intelligence Lab + arXiv 2512.07921Anthropic（闭源）OpenAI（半开源）

5.2 关键设计哲学对比

5.2.1 Sub-Agent 通信模型

graph LR
    subgraph Claude["Claude Code (Task tool)"]
        P1["父 Agent"] -->|"Task 调用"| C1["子 Agent"]
        C1 -->|"result 返回"| P1
    end
    
    subgraph DeepCode["DeepCode (AgentControl)"]
        P2["父 Agent"] -->|"spawn (非阻塞)"| C2["子 Agent 1"]
        P2 -->|"spawn"| C3["子 Agent 2"]
        C2 -.->|"settled event"| M["📬 共享邮箱"]
        C3 -.->|"settled event"| M
        M -.->|"activity wait"| P2
        P2 -->|"send_message"| C2
    end
    
    subgraph OpenAI["OpenAI Agents SDK (Handoff)"]
        P3["Agent A"] -->|"handoff 协议"| P4["Agent B"]
        P4 -->|"handoff"| P5["Agent C"]
    end
    
    style P1 fill:#E8D5F5,stroke:#CE93D8,color:#333
    style P2 fill:#E8D5F5,stroke:#CE93D8,color:#333
    style P3 fill:#E8D5F5,stroke:#CE93D8,color:#333
    style P4 fill:#E8D5F5,stroke:#CE93D8,color:#333
    style P5 fill:#E8D5F5,stroke:#CE93D8,color:#333
    style C1 fill:#B5EAD7,stroke:#80CBC4,color:#333
    style C2 fill:#B5EAD7,stroke:#80CBC4,color:#333
    style C3 fill:#B5EAD7,stroke:#80CBC4,color:#333
    style M fill:#FFDAB9,stroke:#FFB74D,color:#333

核心差异：

  • Claude Code：父子严格串行，父等子完成才继续
  • DeepCode：父子可并发，父能继续工作等子回信（wait_for_activity）
  • OpenAI Agents SDK：无父子概念，handoff 是 Agent 间的对等交接（每个 Agent 是”专业领域专家”，用户提问触发 handoff 链）

5.2.2 Permission 决策模型

系统决策粒度配置载体不可绕过的硬约束
DeepCode(tool_name, arg_pattern) → actionYAML + 代码✅ sensitive-path 强制
Claude Code(tool_name) → actionsettings.json❌ 用户可改
OpenAI Agents SDK无无❌

5.2.3 Hooks 协议设计

DeepCode 直接 port 了 Claude Code 的 Hooks 协议（注释里说”Ports the reference agent’s registry.rs + engine/mod.rs + dispatcher.rs”）。这意味着 DeepCode 的 hooks 配置文件可以和 Claude Code 完全兼容，用户的 hook 脚本可以平滑迁移。

这是非常聪明的设计选择：不发明新标准，复用已存在的标准。从 Hooks 生态的复用性角度看，这是降维打击。

六、优缺点分析（按维度对比）

6.1 架构简洁性 / 扩展性 / 易用性（左侧维度）

维度DeepCode评级
架构简洁性✅ 顶层 core/harness/ 命名直观，每个模块顶部都有 5-10 行设计文档，新人能 5 分钟理解模块职责⭐⭐⭐⭐⭐
扩展性✅ Skills 是 Provider 协议（可插拔 LOCAL/EXECUTOR/ORCHESTRATOR），Sub-Agent 支持 native/external CLI 后端⭐⭐⭐⭐⭐
易用性⚠️ CLI/TUI/Desktop 三入口 + Headless 自动化，但 学习曲线陡峭：840+ 文件，需要读 DEEPCODE_V2_MASTER_PLAN.md 才懂全貌⭐⭐⭐
配置可读性✅ YAML 优先，所有决策文件都是文本（hooks.json, permissions.yaml, mcp.json）⭐⭐⭐⭐⭐

6.2 性能 / 复杂度 / 维护性（右侧维度）

维度DeepCode评级
性能✅ fnmatch + dataclass + 无 I/O 的 PermissionEngine，纳秒级决策；Sub-Agent 用 asyncio 并发⭐⭐⭐⭐
复杂度⚠️ 16.3k stars + 840 文件，二阶复杂度高：每个模块都要考虑和 sessions/observability/plugins 的交互⭐⭐⭐
维护性✅ 每个模块顶部大段设计文档 + 引用其他模块的 §4.3 等章节；模块间解耦好，改 PermissionEngine 不影响 HooksEngine⭐⭐⭐⭐⭐
学术严谨性✅ 注释里明确说”Honest boundary” —— 承认 sandbox 不假装 seccomp-bpf，不假装 Windows 写保护⭐⭐⭐⭐⭐

6.3 最适合 / 最不适合的使用场景

场景适合度
大型企业内部 Coding Agent 平台⭐⭐⭐⭐⭐（多租户 + 权限 + 沙箱 + Hooks 全套）
学术研究 / Agent 论文实现⭐⭐⭐⭐⭐（设计文档齐全 + 协议中立）
个人开发者玩具项目⭐⭐（学习曲线过陡，单人项目不需要 Harness 6 件套）
快速原型 / Demo⭐⭐（840 文件规模太大，建议从 OpenAI Agents SDK 开始）
跨平台分发（Win/Mac/Linux）⭐⭐⭐⭐⭐（沙箱三平台原生实现）

七、从零搭建启示：我自己复刻时怎么做？

7.0 6 件套 MVP 实施路线图

graph TB
    Start["🚀 开始：明确目标"]
    
    P0["📦 P0 阶段（2 周）<br/>Rule + Script + MCP"]
    P1["📦 P1 阶段（3 周）<br/>Skill + Sub-Agent + Hooks"]
    P2["📦 P2 阶段（按需）<br/>Loop + Plugin + Multi-Sandbox"]
    
    P0_R["⚙️ PermissionEngine<br/>fnmatch + 三值"]
    P0_S["🔒 Sandbox<br/>Linux bwrap 优先"]
    P0_M["🔌 MCP Runtime<br/>connect + 注册"]
    
    P1_Sk["📚 SkillProvider<br/>SKILL.md + 不透明 ID"]
    P1_Sub["🤖 AgentControl<br/>asyncio + Mailbox"]
    P1_H["🪝 HooksEngine<br/>5 事件 + JSON"]
    
    P2_L["♻️ autodream<br/>off-line"]
    P2_P["📦 Plugin<br/>1.0.0 manifest"]
    P2_W["🖥️ macOS/Windows<br/>sandbox"]
    
    Test["🧪 集成测试<br/>E2E Harness"]
    Done["✅ 完整 Harness"]
    
    Start --> P0
    Start --> P1
    Start --> P2
    
    P0 --> P0_R
    P0 --> P0_S
    P0 --> P0_M
    
    P1 --> P1_Sk
    P1 --> P1_Sub
    P1 --> P1_H
    
    P2 --> P2_L
    P2 --> P2_P
    P2 --> P2_W
    
    P0_R --> Test
    P0_S --> Test
    P0_M --> Test
    P1_Sk --> Test
    P1_Sub --> Test
    P1_H --> Test
    
    Test --> Done
    
    style Start fill:#C7CEEA,stroke:#9FA8DA,color:#333
    style P0 fill:#FFF9C4,stroke:#F9A825,color:#333
    style P1 fill:#FFDAB9,stroke:#FFB74D,color:#333
    style P2 fill:#F5F5F5,stroke:#999,color:#333
    style P0_R fill:#FFB3C6,stroke:#F48FB1,color:#333
    style P0_S fill:#FFB3C6,stroke:#F48FB1,color:#333
    style P0_M fill:#FFB3C6,stroke:#F48FB1,color:#333
    style P1_Sk fill:#E8D5F5,stroke:#CE93D8,color:#333
    style P1_Sub fill:#E8D5F5,stroke:#CE93D8,color:#333
    style P1_H fill:#E8D5F5,stroke:#CE93D8,color:#333
    style P2_L fill:#B5EAD7,stroke:#80CBC4,color:#333
    style P2_P fill:#B5EAD7,stroke:#80CBC4,color:#333
    style P2_W fill:#B5EAD7,stroke:#80CBC4,color:#333
    style Test fill:#FFDAB9,stroke:#FFB74D,color:#333
    style Done fill:#B5EAD7,stroke:#80CBC4,color:#333

读完 DeepCode 源码后，我重新设计了一套”Harness 6 件套 MVP 落地清单”。如果你想自己复刻一个 DeepCode 风格的 Harness，按这个优先级做：

7.1 必须实现的 3 件套（P0，2 周可交付）

组件最简实现代码量关键文件
Rule三值 PermissionEngine + fnmatch150 行core/harness/permissions.py
Script单一平台 sandbox（建议先做 Linux bwrap）100 行core/harness/sandbox.py
MCP简单 connect/disconnect + tool 注册200 行core/mcp/runtime.py

MVP 复刻清单（精简版代码）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# mvp_permission.py —— 150 行实现 DeepCode 三值权限引擎核心
from dataclasses import dataclass, field
from enum import Enum
import fnmatch

class PermDecision(str, Enum):
    ALLOW = "allow"; ASK = "ask"; DENY = "deny"

SENSITIVE = ("*/.ssh/*", "*/.aws/credentials", "*/.env", "*/.env.*",
             "*.pem", "*.key", "*id_rsa*", "*id_ed25519*")
READ_ONLY = {"read_file", "grep", "glob", "ls", "list_dir"}

@dataclass(frozen=True)
class PermRule:
    tool: str; pattern: str; action: PermDecision
    def match(self, t: str, a: str) -> bool:
        return fnmatch.fnmatch(t, self.tool) and fnmatch.fnmatch(a, self.pattern)

@dataclass
class PermEngine:
    rules: list[PermRule] = field(default_factory=list)
    sensitive_lock: bool = True  # 默认开 sensitive-path 保护

    def check(self, tool: str, arg: str) -> PermDecision:
        # 1. 硬约束
        if self.sensitive_lock and any(fnmatch.fnmatch(arg, p) for p in SENSITIVE):
            return PermDecision.DENY
        # 2. last-match-wins
        matched = next((r.action for r in reversed(self.rules)
                        if r.match(tool, arg)), None)
        if matched: return matched
        # 3. 默认
        return PermDecision.ALLOW if tool in READ_ONLY else PermDecision.ASK

# 用法
engine = PermEngine(rules=[
    PermRule("bash", "git push *", PermDecision.ASK),
    PermRule("bash", "*", PermDecision.ASK),
    PermRule("read_file", "*", PermDecision.ALLOW),
])
print(engine.check("bash", "git push origin main"))  # ASK
print(engine.check("read_file", "/tmp/foo.py"))      # ALLOW
print(engine.check("read_file", "/home/me/.ssh/id_rsa"))  # DENY (硬约束)

7.2 第二阶段做的 3 件套（P1，3 周可交付）

组件实现要点
SkillProvider 协议 + SKILL.md 解析器 + 能力声明
Sub-Agentasyncio.create_task + Mailbox + 单 worktree 隔离（先别做 3-way）
Hooks5 个核心事件（PreToolUse / PostToolUse / SessionStart / UserPromptSubmit / Stop）+ JSON 输出协议

7.3 可省略 / 暂缓的组件（P2，看需求）

  • Loop Engineering（autodream）：单 Agent 不需要，离线记忆整理是 10+ 用户场景才需要
  • Plugin 协议：Skills + MCP 已经覆盖 80% 用例，Plugin 主要是企业级多团队分发
  • 多平台 Sandbox：先做 Linux 一个平台，macOS/Windows 后加

7.4 踩坑预警（实测总结）

坑现象解决方案
cli 包名冲突from cli.tui import ... 解析到 site-packages 的第三方 cli 包DeepCode 在 deepcode.py 顶部显式 evict sys.modules 缓存
路径解析~/projects/foo 在 PermissionEngine 里被解析成绝对路径才匹配 denylist先 os.path.expanduser 再 Path.resolve 再 normpath
fnmatch 匹配深度*/.ssh 不会匹配 ~/.ssh/，因为 * 不跨 /用 fnmatch 时显式加 /* 模式覆盖子文件
Sandbox 退化bwrap 未装时 wrap_shell_command 默默退化成无沙箱加日志告警，显式告诉用户”当前无沙箱”
Sub-Agent 死循环子 Agent spawn 子，子 spawn 子孙DeepCode 强制 allow_spawn=False 在子 Agent 的 AgentRunSpec 里

八、关键 takeaway

如果你只读一段话，记下这些：

  1. core/harness/ 命名即态度：把 Harness 当作一等公民而不是工具集合，DeepCode 是少数做到这一点的项目
  2. 机制 vs 策略的彻底分层：6 个组件全部遵循”pure mechanism”原则，Harness 不和模型对话，不和 UI 对话
  3. 三值权限引擎：allow / ask / deny 比 Claude Code 的二值更精准，且 sensitive-path 是硬约束不可绕过
  4. 双轨 fold：HooksEngine 用声明序合并 reason/context，用完成序合并 updatedInput —— 审计稳定 + 实际生效
  5. Sub-Agent 邮箱通信：父 Agent 不用阻塞等子，可以继续工作等子回信（wait_for_activity）
  6. Skill Opaque ID：调用方只看到 sk_xxx 不透明 ID，路径知识封装在 Provider 内 —— 协议中立性
  7. 不可变 MCP Runtime Plan：Turn 中不能热替换工具，避免”半新半旧”状态
  8. 诚实的边界声明：DeepCode 在 sandbox 模块注释里明确说“不假装有 seccomp-bpf” —— 这种诚实是稀缺品质

九、行动建议

如果你是 Harness 架构师：

  • 把 DeepCode 的 core/harness/ 目录结构当模板：6 件套组件分目录而不是混在一起
  • 三值权限引擎 + fnmatch + last-match-wins 是 Rule 组件的最简工程化范式
  • HooksEngine 的”声明序 vs 完成序”分裂思想值得抄

如果你是 Agent 应用开发者：

  • 不要从 DeepCode 开始学。先用 OpenAI Agents SDK 跑通一个 demo，理解 Agent 是什么
  • 之后读 DeepCode 的 core/harness/permissions.py，把三值权限引擎集成进你的项目
  • 沙箱：先用 OS 级别的（macOS seatbelt / Linux bwrap），不要自己实现

如果你是研究人员：

  • DeepCode 的注释风格（每个模块顶部 5-10 行设计文档 + 引用其他模块 §章节）是学术级代码规范
  • 它的设计哲学文档（”Honest boundary”）值得抄到论文 Related Work
  • arXiv 2512.07921 是它的论文，值得对照源码读

收藏清单：

十、下一篇预告

Harness 六件套矩阵中，DeepCode 已经完整覆盖了 6 件套本体。下一篇将进入”单组件深度对比”阶段：

候选 1：Rule 组件横评 —— DeepCode 三值 vs Claude Code 二值 vs OpenAI Agents SDK 无引擎

候选 2：Sub-Agent 通信协议横评 —— DeepCode 邮箱模式 vs OpenAI Handoff 链式 vs AGT Saga 失败恢复

候选 3：Hook 总线协议横评 —— DeepCode 声明序 fold vs Strands Middleware Stack vs AGT Pre-Tool Hook 拦截

你想看哪个？评论区告诉我。

本文信息密度：12800 字 / 7 个 Mermaid 图 / 11 段可运行代码 / 3 个对比矩阵 / 1 个 8 组件定位表。完整源码引用已嵌入代码块，所有路径均可在 HKUDS/DeepCode 仓库验证。

作者立场：DeepCode 是当前 Harness Engineering 学术 + 工程化的标杆项目。它的”机制 vs 策略”分层思想应该成为所有 Harness 项目的设计基线。但它的学习成本（840 文件 + 全英文注释 + 设计文档要求高）不适合初学者直接上手。

下期预告：Sub-Agent 通信协议横评 —— 3 个开源项目对比，看谁的”父子模型”架构能撑住 100 个并发子任务。