Pi Harness：架构与扩展边界
本案例沿用下文记录的 Pi 版本与观察日期。共同职责见 Harness 总览，这里具体讨论一个实现怎样划分这些职责。
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 应该继续保持小而清楚。只有反复出现、已经稳定的能力，才值得固化成统一组件。等到这些组件多到难以分别维护时，插件工作台才真正有意义。