AI 编程 Harness：架构、安全与 Pi
模型负责提出下一步动作，而 Harness（控制层）负责让这个动作可执行、有边界、可观测且可恢复。它既不是模型本身，也不仅仅是聊天界面，而是连接模型、代码仓库、终端、权限体系与验证流程的控制中枢。
最小职责集
如果一个 Agent 只是循环直到模型说“完成”，那它只有编排能力，缺乏可靠的控制层。
证据边界
上述架构职责是综合总结。Pi 的行为依据文档与源码核验；DeepSeek Harness 的比较仍归因于正文链接的视频。这些来源能说明设计和已记录的功能，不能证明哪种 Harness 更可靠或更实用。
本文偏向终端编程场景，对 IDE 协作、浏览器/计算机使用 Agent、非英语工作、组织治理和非编码自动化涉及较少。阅读主张时请结合证据与偏差；当前产品选择则统一查看带日期的编码 Agent 评测。
内部控制系统
三个设计要点使控制层具体化：
- 代理循环模式 区分短会话回合、新鲜上下文循环、实现-验证周期及评估器-优化器工作流。每个循环都需要外部成功谓词和硬性预算。
- 上下文工程 将模型窗口视为变化的工作集，而计划、证据和检查点则持久保存在转录记录之外。
- 工具契约 明确副作用、重试、审批和部分失败，而不是让模型从函数名中推断。
这些层级对小规模本地模型尤为重要：缩短迭代周期、缩小工具集、返回有界输出，并让确定性检查决定是否需要下一轮交互。
Pi：可编程的最小 Harness
Pi 自称是一个最小终端编程 Harness。它将模型调用、代理循环、工具执行、可分支会话及终端界面保留在核心中，而将特定工作流行为留给可组合的资源。默认情况下，模型仅接收 read、write、edit 和 bash。grep、find 和 ls 也是内置工具，但必须显式选择或通过配置启用。
除了交互式 TUI，Pi 还支持单次 -p 输出、JSON 事件流、stdin/stdout RPC 以及用于在 Node.js 应用中嵌入代理的 SDK。提供商可切换。会话存储为可分支的 JSONL 树；/tree、/fork、/clone 和 /compact 涵盖文件内探索、独立会话及上下文压缩。
以下 Pi 细节基于 2026-08-28 对照本地安装的 Pi 0.84.3 文档核实。它们是版本化的产品事实，而非永久兼容性承诺。
各定制层级的所有权
全局资源通常位于 ~/.pi/agent/；项目资源位于 .pi/ 或 .agents/skills/。提示扩展文本。技能使用渐进式披露，默认上下文中仅保留其名称和描述。扩展直接更改 Harness 行为。当缺失的是方法时优先选择技能，当是复用输入时选择提示，仅在确实需要新工具、事件钩子或 UI 时才使用扩展。
Pi 已核验的请求准备、Steering、Follow-up、压缩与会话流程集中在有界 Agent 循环中。会话分支只改变模型看到的对话，不会恢复磁盘文件；本页后面的命令仅作为操作参考。
扩展：Pi 的插件层
扩展是由 Pi 直接加载的 TypeScript 模块。它可以：
- 注册模型可调用的工具和用户斜杠命令；
- 挂钩模型回合、工具调用及结果、模型变更和会话生命周期事件；
- 阻止或重写危险调用，并添加受保护路径或审批 UI；
- 自定义压缩、会话状态、终端组件和渲染；
- 注册提供商，或实现 MCP、子代理、计划模式和沙箱集成。
最后一点很重要：示例或第三方包可以实现这些功能，但它们不是核心默认值。较小的核心允许竞争设计，同时让安装者负责其策略、维护和恢复行为。
自动发现的扩展位于 ~/.pi/agent/extensions/ 或受信任项目的 .pi/extensions/；更改后运行 /reload。使用 pi -e ./extension.ts 进行临时实验而无需安装。Pi 包可以一起分发扩展、技能、提示和主题：
pi install npm:@scope/package@1.2.3 # 固定版本
pi install ./local-package -l # 项目范围
pi list
pi config # 启用或禁用单个资源
pi update --extensions
扩展以当前用户的权限执行任意代码，技能可能指示模型运行捆绑脚本。因此，包是分发单元，而非安全边界。安装前阅读源代码和依赖项，必要时固定版本，并仅启用工作流所需的资源。
日常使用
普通项目第一天不需要大型控制平面：
小项目可能只使用所需文件：
AGENTS.md用于规则和验收命令；.pi/prompts/review.md用于可选的简短重复提示；.agents/skills/release/SKILL.md用于可选的可复用程序；.pi/extensions/policy.ts仅在主机级策略需要代码时使用。
常见启动模式：
cd my-project
pi --name "parser repair" # 交互式会话
pi -c # 继续最新会话
pi --no-session -p "Summarize this repository" # 临时单次调用
# 仅暴露只读工具进行审查
pi --no-session --tools read,grep,find,ls -p "Review the change"
# 跳过发现并仅加载待测资源
pi --no-extensions -e ./.pi/extensions/policy.ts
pi --no-skills --skill ./.agents/skills/release/SKILL.md
值得记住的首个交互式命令：
安全基线
Pi 的项目信任决定是否加载项目 .pi 设置、资源和可执行扩展。它不是文件系统或网络沙箱。非交互模式不显示内置的项目信任提示，因此自动化必须做出明确的 --approve 决策，而不是默认永久信任任意仓库。
保守的起点是：
- 在信任项目资源之前，检查 Git 状态、
AGENTS.md和允许的写入范围； - 审查工作时使用
--tools read,grep,find,ls，仅在需要写入时扩大工具集； - 在容器或 VM 中运行不熟悉的仓库或危险命令，将凭据、Docker 套接字和不相关目录留在外部；
- 使用
--no-extensions、--no-skills及相关标志构建可复现的最小资源集； - 审查并固定第三方包，将每个扩展视为具有完全用户权限的代码；
- 通过测试、Lint、差异和最终进程状态判断完成，而非模型的“已完成”声明。
这是 Pi 与更产品化 Harness 的核心交换：核心更小且更易变形，但安全策略和工作流质量不会自动出现。
Pi 和 DeepSeek Harness：谁承担复杂度
Pi 介绍视频 与 DeepSeek Harness 视频里的系统乍看很像：都能换模型、接工具、加插件。真正值得比较的不是功能多少，而是复杂度什么时候出现、由谁处理。
Pi 从小核心开始。需要计划模式、子 Agent、MCP 或特殊界面时，使用者再把对应能力组装进来。默认状态因此容易理解，但兼容、权限和维护也由使用者负责。
DeepSeek Harness 视频则从 “Everything is a plugin” 出发，让模型、工具、界面和工作流共享一个组合面。这有利于团队复用反复出现的流程，同时也把依赖、版本和排错工作提前放进插件平台。
两种方式都没有消灭复杂度。Pi 推迟复杂度，并把它交给搭建工作流的人；视频展示的 DeepSeek Harness 则把更多复杂度集中到平台。对我现在的工作流，Pi 应该继续保持小而清楚。只有反复出现、已经稳定的能力，才值得固化成统一组件。等到这些组件多到难以分别维护时，插件工作台才真正有意义。
产品比较归 Frontier
本页只把 Pi 和视频中的 DeepSeek Harness 当作设计案例。带日期的跨产品矩阵、选型建议与复测协议统一放在如何选择 AI 编程 Agent，这样更新产品事实时不会改动 Harness 的持久模型。
实用设计顺序
- 定义结果和外部成功检查。
- 暴露最小的有用工具集。
- 将只读操作与写入和不可逆操作分开。
- 在对话记录之外保存产物和证据。
- 添加时间、Token、重试和并发限制。
- 在保护敏感数据的前提下追踪模型回合与工具调用。
- 更改默认模型、Harness 或推理级别前，先重放有代表性的任务。
质量门属于 Harness 和工作流，模型可以替换。更强的模型也许能减少重试，但不能取代证据、权限和端到端检查。变化较快的模型与定价信息放在模型与 API 雷达，公开测试结果和工具故障模式则记录在编码智能体评估。