pi-dev-rules

Pi 开发规则

Pi 是一个极简终端编码工具：核心轻量，并通过 TypeScript 自定义项扩展。包：@earendil-works/pi-coding-agent。由 Earendil Inc.（MIT）维护。本技能对应官方文档 https://pi.dev/docs/latest，让你无需重新获取文档，也能回答 Pi 相关问题并构建 Pi 自定义项。另有五个资料包，介绍 pi.dev 文档网站未涵盖的内容：内部单体仓库架构（Chord 类型化宿主运行时、带有 Pico5 规范的持久化 Agent 工具框架、Agent 核心、遥测）、根据 2026-10-01 Earendil 博客文章整理的 Pi Durable 概览（实验性工具框架是什么、版本时间线，以及 1.2.0 中移除了哪些博客演示），以及仓库自身的开发／贡献规则。

何时使用此技能

• 安装、验证身份或启动 Pi；说明 CLI 标志／斜杠命令。
• 配置提供方、API 密钥、自定义模型（models.json）或代理。
• 编辑 settings.json、键绑定、主题；了解会话和压缩。
• 了解项目信任安全模型，以及如何在容器／沙箱中运行 Pi。
• 扩展 Pi：编写扩展、技能、提示词模板、程序包、自定义提供方、TUI 界面；启用 codemode 或编写其脚本。
• 查询 Pi 的版本历史／近期版本的变更内容。
• 通过 SDK、RPC 模式或 JSON 事件流模式，以编程方式驱动 Pi。
• 在 Windows／Termux／tmux／特定终端上设置 Pi，或从源代码构建 Pi。
• 了解Pi 的设计理念：创建者的理念（极简核心、4 个工具、默认 YOLO；2025-11-30 的宣言将 MCP、计划模式、待办事项和子 Agent 列为刻意不实现的功能，而内置 MCP 后来于 2026-09-29 加入），以及如何顺应这些理念配置或扩展 Pi，而不是与之背道而驰。
• 在 pi 单体仓库内部开展工作：@earendil-works/chord 类型化宿主运行时（契约、宿主和链接、热重载、增量／复制状态）、持久化工具框架（@earendil-works/pi-durable、Pico5）、Agent 核心和遥测。实验性的 server／client／protocol 程序包已在 1.2.0 中移除。
• 基于或询问有关 Pi Durable（@earendil-works/pi-durable）的问题：该工具框架是什么、各版本包含哪些内容、可运行示例位于何处，或为何博客文章中的演示路径已不存在。

参考索引：加载所需文件

文件	涵盖内容
references/cli-and-usage.md	安装、身份验证、启动、Pi 的工作方式（Agent 循环、上下文组装、会话树）、完整 CLI 参考（命令、标志、模式）、斜杠命令、消息队列、上下文文件、环境变量（包括 bash-tool 的 PI_SESSION_*/PI_MODEL）、会话、键绑定
references/providers-and-models.md	订阅和 API 密钥提供商（30 多个）、llama.cpp 本地路由器、NVIDIA RTX 配方预设、auth.json（以及作用域 env）、云提供商（Azure/Bedrock/Vertex/Cloudflare）、在 models.json 中配置自定义模型、compat、自定义提供商扩展
references/settings-and-compaction.md	配置布局（Agent 目录与项目 .pi/、上下文文件）、settings.json 架构及示例、信任/分析/重试/传输键、上下文压缩（自动/手动）和分支摘要
references/extending-pi.md	扩展 API（事件、工具、命令、UI）、技能（SKILL.md）、提示词模板、主题、包、虚拟模型（pi.registerVirtualModel）
references/mcp.md	内置 MCP 支持（2026-09-29）：全局和项目级 mcp.json 服务、stdio 与可流式 HTTP、pi mcp add/remove/list、OAuth 登录、暴露模式（codemode、codemode-deferred、deferred、direct、hidden）及 toolExposure、codemode/tool_search 工具、资源、权限、来自扩展的服务、SDK 接线，以及 --no-mcp / mcp__* 工具模式
references/codemode.md	codemode 工具：脚本输入和 // @options: 行、全局对象（tools.<name>()、text()、image()、console.log()、store()/load()、searchTools()、describeTool()）、工具调用的解析结果、分类器和图像模型、命名空间和内联预算、限制
references/tui-components.md	用于自定义扩展/工具 UI 的 TUI 组件系统（组件、叠加层、主题、自定义编辑器）
references/security-and-containerization.md	项目受信任模型（trust.json、defaultProjectTrust）、无内置沙箱、Gondolin 微型 VM、Docker、OpenShell、Docker Sandboxes
references/session-format.md	会话 JSONL 架构：版本、内容块、条目类型、树/上下文构建、SessionManager API，以及面向模型的消息类型
references/programmatic.md	SDK、CLI 集成（交互/打印/JSON/RPC 模式选择、RpcClient、分叉并重新打造品牌）、JSON 事件流模式、RPC 协议、RPC 命令参考、RPC 扩展 UI
references/platform-setup.md	Windows、Termux、tmux、按终端配置改造后的 Enter 键、Shell 别名
references/development.md	Monorepo 包列表、从源代码构建和独立二进制文件构建、供应链规则、AGENTS.md 开发规则、CONTRIBUTING.md 关卡
references/philosophy-and-design.md	创建者 Mario Zechner 的设计宣言（博客，2025-11-30；人工整理，非自动生成）：少于 1000 个 token 的极简提示词、4 个工具、默认 YOLO、其中列出的非功能（MCP/计划模式/待办事项/子 Agent/后台 bash）及其预期替代方案，并注明 MCP 条目自 2026-09-29 起已被取代、多提供商架构、Terminal-Bench 2.0 结果
references/chord.md	@earendil-works/chord：类型化主机运行时（契约、声明、注册表、主体、句柄、热重载）、主机和链接（memoryLinkPair、ipcLink、webSocketLink），以及 chord/delta 复制式最新值状态。内容取自 packages/chord/{README.md,docs/{guide,spec,tutorial}.md,src/delta/README.md}；Pi Durable 使用 Chord，但 Pi 编码 Agent 不使用；规范描述的是当前运行时
references/durable.md	Pi Durable 概览，整理自 2026-10-01 的 Earendil 博客文章和 v1.3.0 代码树：harness/conversation/agent/task/execution-environment 术语、产品定位（用于构建 Agent 应用的 harness，而非 Pi CLI）、版本时间线（从 Pi 1.0 的 1.0.0 到 1.3.0、版本同步、破坏性变更）、安装和代码结构、包布局及其 32 个可运行示例，以及在 1.2.0 中删除的博客演示。状态与路由信息请从此处开始
references/agent-harness.md	内部运行时包：@earendil-works/pi-durable（持久化对话/任务/文档 harness，实验性 API，先存储后展示）、@earendil-works/pi-agent-core（工具调用和状态）、@earendil-works/pi-telemetry（厂商中立的遥测契约、适配器、类型化架构）。内容取自三个包的 README；这不是面向用户的文档，入口请看 durable.md
references/durable-spec.md	pi-durable 背后的规范性 Pico5 规范（5352 行）：记录和生命周期、文档和变更所有权、任务和 effect sandwich、提交和收件箱、扩展/钩子/工具、遥测。这是实验性包的设计文档，并非冻结的 API；随附文本为 v1.3.0 规范
references/changelog.md	发布历史：最近 25 个版本及其主要变更，摘自 packages/coding-agent/CHANGELOG.md（共 289 个发布章节；完整内容请查看检出目录中的文件）

Pi 1.3.0 更新说明

• sessionShareDestination 可为 /share 选择 auto、gist 或 radius。
• 恢复会话时会还原活动工具。--tools +name/-name 可调整这组工具。
• --model 匹配不明确时，优先选择已配置凭据的提供商。否则，请指定 --provider。
• Kimi Code 现使用 Chat Completions。自定义基础 URL 必须包含 /v1。
• 每个 Pi 进程最多允许两个运行中的工作器；已取消的工作器在退出前也计入数量。
• Pi Durable 支持 SQLite 表前缀和共享的 Cloudflare 适配器队列。

入门插件

每位 Pi 用户都应安装这三个插件（作者相同，经过实战检验）：

pi install npm:pi-subagents       # subagents / loop / chain / parallel
pi install npm:pi-lens            # real-time LSP diagnostics
pi install npm:pi-web-access      # web search, URL fetch, YouTube, PDF

然后运行 pi list 进行验证，并重启 Pi。MCP 无需安装软件包：自 2026-09-29 起已内置（参见 references/mcp.md）。像 pi-mcp-adapter 这样注册 /mcp 的扩展，会取代内置支持，而非在其基础上扩展。

速查表

curl -fsSL https://pi.dev/install.sh | sh                         # install (pins dependencies)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent   # npm alternative (no pinned transitive deps)
export ANTHROPIC_API_KEY=sk-ant-...                               # or run /login in-session
cd /path/to/project && pi                                          # start interactive (may prompt to trust the project)

pi update                                 # update Pi itself (pi update self / pi update --self are aliases)
pi list                                   # list installed packages
pi -c                       # continue most recent session
pi -r                       # browse/resume sessions
pi --session <path|id>      # open specific session
pi --fork <path|id>         # fork a session
pi --no-session             # ephemeral (no save)
pi -a / -na                 # trust / don't trust project-local files for this run

pi -p "Summarize this codebase"                 # print mode (non-interactive)
pi @README.md "Summarize this"                  # attach files/images with @
cat file | pi -p "..."                          # pipe stdin
pi --provider openai --model gpt-4o "..."       # pick provider/model
pi --model sonnet:high "..."                    # model:thinkingLevel
pi --tools read,grep,find,ls -p "..."           # allowlist tools (-xt excludes; +name/-name adjusts defaults)
pi --mode json "..." | jq -c 'select(.type=="message_end")'   # JSON stream
pi --mode rpc                                   # JSON-RPC over stdin/stdout

# In-editor: @file (fuzzy), !cmd (run+send), !!cmd (run, hidden), /command, Ctrl+L model, Shift+Tab thinking, Ctrl+X copy
# While the agent runs: Enter queues a steering msg, Alt+Enter a follow-up, Esc aborts + restores

关键位置（全局 ~/.pi/agent/、项目 .pi/）： settings.json、auth.json、models.json、keybindings.json、trust.json、AGENTS.md、 SYSTEM.md、extensions/、skills/、prompts/、themes/、sessions/。

硬性规则

• 安装包名称必须准确为 @earendil-works/pi-coding-agent。pi.dev 安装程序 （curl -fsSL https://pi.dev/install.sh | sh）会固定依赖版本，也是文档指定的安装 路径；全局 npm 安装需要添加 --ignore-scripts，且不会固定任何依赖版本。
• 项目上下文文件是 AGENTS.md（Pi 也会读取 CLAUDE.md）；请将其放在项目根目录。
• 扩展以完整系统权限运行：应将其视为可信代码；对于危险操作（rm、sudo、敏感路径）， 使用 ctx.ui.confirm 或 tool_call 阻止处理程序进行管控。
• 项目信任是输入加载防护，不是沙箱。 Pi 没有内置沙箱；项目只有在决定是否加载其 .pi/ 资源（设置/扩展/技能/提示词/主题）时才被视为“可信”；相关决策记录在 ~/.pi/agent/trust.json 中，由 defaultProjectTrust（ask/always/never）控制， 每次运行时可通过 --approve/--no-approve 覆盖。对于不可信仓库或无人值守运行，请使用容器/虚拟机 （Gondolin/Docker/OpenShell）进行隔离；除非沙箱需要访问主机凭据，否则不要挂载主机的 ~/.pi/agent。
• 自 2026-09-29 起，MCP 已内置，可在 ~/.pi/agent/mcp.json 或项目的 .pi/ mcp.json 中配置；只有在项目受信任后才会读取项目文件，因为 stdio 服务会运行命令。 MCP 调用会经过工具流水线，因此 tool_call 处理程序和权限管控同样适用（codemode 调用会携带 parentToolCallId）。安装注册 /mcp 的扩展（pi-mcp-adapter）会禁用内置支持；如需禁用， 可使用 "extensions": ["-builtin:mcp"]、pi config，或在单次运行中使用 --no-mcp。
• 在扩展/SDK 工具中：出错时抛出异常，绝不要返回错误标志。 Pi 会将抛出的异常封装为错误工具结果 （isError: true）；具体约定请参阅文档中的 ToolDefinition，位于 packages/coding-agent/src/core/extensions/types.ts。工具输出限制在约 50KB / 2000 行以内 （DEFAULT_MAX_BYTES = 50 * 1024）。面向大模型的枚举请使用 @earendil-works/pi-ai 中的 StringEnum。
• 技能 name：长度为 1–64 个字符，只能包含小写 a-z 0-9 -，不得以连字符开头或结尾，也不得包含连续连字符； description 不超过 1024 个字符，且必须说明何时加载该技能（没有 description 的技能不会加载）。
• chord.md、durable.md、agent-harness.md 和 durable-spec.md 描述的是内部实现，不是 稳定约定。 Chord 与应用无关，供 Pi Durable 使用，不供 Pi CLI 使用。 pi-durable 仍处于实验阶段（2026-10-01 随 Pi 1.0 发布 1.0.0，2026-10-15 发布 1.3.0）。 版本号与 monorepo 保持同步，早期版本包含不兼容变更。Pico5 规范是一份设计文档。请引用 源代码树状态（pi@71023aec1），不要将其描述为承诺提供的 API。
• Pi Durable 博客文章是截至 2026-10-01 的快照。 其中的“试用”演示 （packages/coding-agent/src/experimental/{durable,vacation}/）已在 1.2.0 中由提交 7472cda0d 删除；durable harness 本身不受影响。请改为从 packages/durable/test/examples/（00–31）运行示例，并阅读 durable.md 了解版本时间线。
• auth.json 保存 API 密钥和 OAuth 令牌：Pi 会以 0600 权限写入该文件，请妥善保管，勿将其纳入 版本控制。凭据优先级：CLI --api-key → auth.json → 环境变量 → models.json 中自定义 provider 的密钥。
• 项目设置优先于 Agent 目录设置，资源列表会合并而非替换（模型查找前，会合并压缩阈值等逐模型对象）。 使用 pi install -l 将包声明写入 .pi/settings.json；Pi 只有在项目受信任后才会读取该文件。