Pi 的 CodeMode 对比 DeepSeek Harness 的 PTC 模式

在构建代码智能体（Coding Agent）的运行时架构时，传统的单步工具调用（Tool-Calling Loop）正在遭遇工程瓶颈：面对多文件重构与跨模块分析，单步 JSON RPC 往返导致交互轮次爆炸与上下文急剧膨胀，且无法高效表达工具间的异步依赖。为了突破这一调度天花板，Pi Coding Agent 的 CodeMode 与 DeepSeek Harness（CLI: dsh）的 PTC（Programmatic Tool Calling，编程式工具调用）模式给出了两条截然不同的代码执行路线。

早期的单步调用模式下，模型每执行一个操作（如读取文件或正则检索）都必须经历一次完整的序列化、反序列化以及模型推理往返。在《https://blog.baifan.site/claude-code-tool-system-design/》中讨论过工具系统渐进式披露的代价：当工程规模扩大，单步调用的通信时延和上下文消耗会呈指数级上升。

Pi 与 DeepSeek Harness 均选择将“编写程序”作为主要交互手段，但在类型边界、运行时抽象与执行协议的工程取舍上，走向了不同的演进路径。

两套架构的交互界面解构
#

1. Pi 的 CodeMode：以系统解释器为核心的环境透传
#

在《https://blog.baifan.site/pi-coding-agent-complete-guide/》中解析过 Pi 的设计哲学：它倾向于提供极致透明的底层接入。在 CodeMode 下，工具不再以显式的多参数 RPC 规范呈现给模型，而是作为宿主系统内可直接导入、调用的脚本逻辑。

自由度优先：模型直接编写临时脚本（Ad-hoc Script），调用系统标准库（如 os、re、subprocess）与文本处理管道。
沙箱内消解熵增：当需要从成百上千个源文件中检索特定模式时，模型自行在沙箱本地跑完过滤逻辑，仅向标准输出打印最终匹配的精简行。大量非结构化的中间日志和错误被阻隔在上下文之外。
Unix 哲学透传：文件系统即共享内存，标准输入输出（stdout/stderr）即协议总线。运行时抛弃了上层虚幻的 SDK 封装，直接让模型面对真实的 Linux 操作空间。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# Pi CodeMode：利用系统原生 Python 与管道在沙箱本地过滤，控制台仅输出收敛后的关键数据
python3 -c '
import os, re
pattern = re.compile(r"export\s+const\s+(\w+Action)")
for root, _, files in os.walk("src"):
    for f in files:
        if f.endswith(".ts"):
            path = os.path.join(root, f)
            with open(path, "r", encoding="utf-8", errors="ignore") as fp:
                for idx, line in enumerate(fp, 1):
                    m = pattern.search(line)
                    if m:
                        print(f"{path}:{idx} -> {m.group(1)}")
' | head -n 10

2. DSH 的 PTC 模式：基于具名 Typed SDK 的代码编排
#

在 DeepSeek Harness（基于 Cordis 插件微内核架构）中，DSH 预置了 Standard、Minimal、Creator 和 PTC 等运行模式。其中 PTC（Programmatic Tool Calling）模式是一项针对工具调用爆炸优化的运行协议：

单入口收敛（run_code）：在 PTC 模式下，DSH 不向模型暴露数十个独立的工具 JSON Schema，仅暴露唯一的底层调用入口——run_code。
动态生成 Typed SDK：运行时动态扫描当前挂载的插件服务（文件读写、搜索、Git、构建等），实时为模型生成一套具名类型化的 ambient declaration（例如以 TypeScript 的 ToolArgsMap 接口呈现）。
程序即编排：模型在单个交互步骤内编写一段包含并发请求、依赖串行调用与数据提炼的异步程序，最终仅将 return 的结构化结果返还给主循环。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// DSH 注入的上下文类型声明（将数十个冗长的 JSON Schema 压缩为紧凑的 TypeScript 接口）
declare namespace tools {
  function readFile(args: { path: string; offset?: number; limit?: number }): Promise<{ content: string }>;
  function search(args: { query: string; pattern?: string }): Promise<Array<{ file: string; line: number }>>;
  function batchEdit(args: { edits: Array<{ path: string; diff: string }> }): Promise<{ success: boolean; modified: number }>;
}

// 模型在单个 Step 中执行的编排代码块（单入口 run_code）
const matches = await tools.search({ query: "handleDeprecatedApi" });
const targetFiles = [...new Set(matches.map(m => m.file))];

const results = await Promise.allSettled(
  targetFiles.map(async (file) => {
    const data = await tools.readFile({ path: file });
    return { file, hasFallback: data.content.includes("fallbackHandler") };
  })
);

return results
  .filter((r): r is PromiseFulfilledResult<{ file: string; hasFallback: boolean }> => r.status === "fulfilled")
  .map(r => r.value)
  .filter(item => !item.hasFallback);

核心工程维度深度对比
#

维度	Pi CodeMode	DSH 的 PTC 模式 (Programmatic Tool Calling)
运行时视角	通用操作系统脚本沙箱（Shell / Python 环境）	Harness 层注入的微型 JS/TS 沙箱（QuickJS / Node VM）
工具暴露协议	本地可执行命令、CLI 管道或文件系统操作	运行时动态编译生成的静态类型声明（`d.ts`）
Schema 开销	极低（模型仅需感知基础环境定义与 CLI 工具）	极低（将数十个冗长的 JSON Schema 压缩为一个类型声明块）
并发与依赖表达	依赖 Bash 后台任务、xargs 或 Python 多线程，较重	原生利用事件循环（`Promise.allSettled` 等）表达高效并发
可观测性与审计粒度	偏粗，通常只能捕获整个脚本的 stdout/stderr	细粒度追踪：Runtime 在内部拦截 Proxy 的每个子调用，保持独立 Trace
错误隔离边界	运行时报错直接在 REPL 堆栈中暴露，易导致整段退出	类型断言与 Promise rejection 均被 Harness 沙箱守卫捕获并分类
IPC 数据搬运损耗	零 / 极低（直接通过管道和操作系统缓冲区传递）	存在 IPC 瓶颈（宿主与微沙箱间需频繁序列化传输数据）

1. 上下文信噪比与 Prompt Caching 的物理命中
#

在挂载 20 个以上工具时，嵌套复杂的 JSON Schema 会占用数千 Token。更严峻的是，只要任意一个工具的参数描述发生变动，整个系统提示词（System Prompt）的 Prefix Cache 就会彻底失效。

DSH 利用 TypeScript 类型定义替换 JSON Schema，提升了 Token 密度，扁平纯文本更利于维持前缀缓存的物理命中。同时，原本需要 5 轮“问-答-再调用”的网络往返（RTT）被收敛为 1 次代码执行，显著压低了端到端推理成本与交互延迟。

Pi 绕过了中间 SDK 层，贴近真实终端。代价在于模型必须通过 awk、grep、jq 或正则自行保证输出结果的纯净度。若模型在脚本中写错重定向或遗漏管道过滤，成千上万行非结构化日志将直接倾泻至上下文，导致窗口瞬间被噪音挤占。

2. 系统可观测性与权限管控的断层
#

可观测性与权限控制是两套设计在生产落地上最大的分水岭。我们在《https://blog.baifan.site/ai-agent-runtime-dynamic-intervention/》中分析过 Harness 编排层对 Agent 动作进行动态干预与权限拦截的必要性。

CodeMode 的盲盒风险：模型在 Python 脚本中通过循环批量改写本地文件时，外部 Harness 除非挂载 eBPF 探针或监听系统调用文件描述符，否则在进程层面只能观察到宽泛的 python execute.py。宿主无法在写入第 3 个文件时精细弹出确认授权提示，面临全盘放行或全盘拒绝的二元抉择。
PTC 的受控代理机制：在 DSH 模式下，代码看似由模型自主编写，但执行上下文中的 tools 本质是 Harness 注入的 Proxy 代理对象。当脚本执行至 await tools.write(...) 时，底层同步触发 Cordis 插件体系的生命周期钩子（Action Middleware），执行权限审批拦截（Approval Policy）并写入独立 Trace。这既保留了高级语言编排的灵活性，又将底层控制权收拢在宿主手中。

3. 运行时的隐藏损耗：IPC 传输与内存穿透
#

PTC 的整洁结构伴随着不可忽视的系统开销：

在 PTC 模式下，宿主（Harness）与代码执行环境（微沙箱）通常处于独立隔离状态。模型在一个步骤中调用 tools.read() 读取数十个大文件并在 JS 堆内计算时，所有数据必须在宿主与沙箱之间经过 IPC 序列化与反序列化传输。一旦微沙箱的内存配额设置保守，高并发大对象交换极易触发 OOM 崩溃。

Pi 的 CodeMode 依托本地原生进程，内核管道和页缓存直接承担了数据吞吐。在大文件检索与高吞吐数据流场景下，原生进程直接消解了中间序列化损耗。

架构选型与工程权衡
#

从单步工具调用向编程式执行演进，是代码智能体提升吞吐效率与推理经济性的必然路径。

Pi 的 CodeMode 走极简透传路线：依托成熟的解释器和命令行工具做减法。它的能力上限取决于模型本身的 Shell 与脚本编写水平，适用于个人本地开发、CLI 辅助等轻量、高自由度、无强风控约束的场景。

DeepSeek Harness 的 PTC 模式走微内核结构化抽象路线：将工具封装为安全代理沙箱中的 Typed SDK，在单轮请求内释放模型的并发与逻辑控制力，同时维系了 Harness 对单步调用追踪、审批流和安全隔离的控制力。

若系统要求严格的审计 Trace、需要接入企业级审批链并最大化利用 Prompt Cache，PTC 模式展现出更优的工程收敛性；若追求原生执行性能、零中间层封装的透明度以及对复杂本地工具链的无缝调用，CodeMode 依然是最纯粹的实现路线。

作者

ByF (BaiFan)

ByF，即 BaiFan（白帆）。系统后端工程师，专注 AI 底层原理与智能体架构。主站 baifan.site。

两套架构的交互界面解构 #

1. Pi 的 CodeMode：以系统解释器为核心的环境透传 #

2. DSH 的 PTC 模式：基于具名 Typed SDK 的代码编排 #

核心工程维度深度对比 #

1. 上下文信噪比与 Prompt Caching 的物理命中 #

2. 系统可观测性与权限管控的断层 #

3. 运行时的隐藏损耗：IPC 传输与内存穿透 #

架构选型与工程权衡 #