my-pi/AGENTS.md

仓库说明

本仓库用于维护可通过一次 pi install 部署的个人 Pi 扩展组合包。根 package.json 是唯一的组合包安装入口；根 install.sh、update.sh 和 uninstall.sh 只是对 pi install / pi update / pi remove 的便捷包装，不形成第二套部署机制。依赖、默认行为和必要配置必须由组合包自身声明或部署，不把安装后的手工配置作为默认流程。每个自维护扩展使用独立的顶层目录，扩展源码、测试和说明应保留在各自目录内。

当前扩展

• pi-rtk-optimizer/：默认只负责非搜索工具输出压缩；RTK 命令改写为可选能力。
• 上游来源：https://github.com/MasuRii/pi-rtk-optimizer
• 初始导入快照：d155d253cb2f1358e34e717d47a82ebccb08cb8e（2026-07-03，0.9.0）。
• 该目录已纳入本仓库直接维护，不是 submodule，也不保留嵌套 .git。
• pi-ssh/：从上游源码导入并由根组合包加载的纯 ssh2 远程操作扩展，通过受权限链复核的 ssh_connect 建立 Agent 控制的持久连接，以 ssh_cd 显式维护远端工作区，并以 SFTP 与有界自适应搜索提供独立的远端工具；运行时不调用 OpenSSH 或 sshpass。
• 上游来源：https://github.com/pansapiens/pi-ssh
• 初始导入快照：e9a1059a0f37ab14b6a73ee608cb203edf803f31（2026-06-23，0.7.0）。
• 该目录已纳入本仓库直接维护，不是 submodule，也不保留嵌套 .git、node_modules 或构建产物；纯 ssh2 设计参考 99percentpeople/pi-extensions 的明确 commit，来源记录保留在 pi-ssh/UPSTREAM.md。
• pi-permission-system/：统一提供工具、路径、MCP、Skill、子代理转发、独立 JSONC 硬防御、普通策略、内置 Codex Guardian 风格 AutoReview 与人工 defer 兜底。
• 权限系统上游来源：https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system；初始导入快照：ec4fdb11343dc94f7185b113e559a4cf9f8dc035（pi-permission-system-v26.2.1）。
• AutoReview 上游来源：https://github.com/mzwing/pi-packages/tree/main/packages/pi-permission-auto-review；初始导入快照：8d196e4ef0884cac8326c366191dad3f585d470a（@mzwing/pi-permission-auto-review@0.2.0）。
• 原 AutoReview 源码已整合进 pi-permission-system/src/auto-review/，不再保留或加载第二个顶层扩展；其 MIT 许可与来源记录保留在 pi-permission-system/LICENSES/ 和 pi-permission-system/docs/auto-review/。该目录从明确 tag/commit 的上游源码导入并由本仓库直接维护，不使用 npm 预编译产物，不是 submodule，也不保留嵌套 .git。
• pi-subagents/：提供 Claude Code 风格的隔离子 Agent、后台执行、steering、resume、嵌套代理与自定义 Agent。
• 上游来源：https://github.com/tintinweb/pi-subagents
• 初始导入快照：3f9d35cd078d18a141eb5a6d8f4fc5010d756280（v0.18.0）。
• 该目录从明确 tag 导入并由本仓库直接维护，不使用 npm 预编译产物，不是 submodule，也不保留上游 .pi 状态；源码、测试、wrapper 与权限集成实现继续保留，但当前不属于根组合包运行时依赖，extensions/subagents.ts 也不在默认扩展加载列表中。
• extensions/fff-override.ts：强制使用 FFF 官方 override 模式，统一接管 find、grep、multi_grep 和 FFF 的 @ 补全；显式 CLI flag 仍遵循 FFF 官方优先级。
• pi-web-search/：完全自维护的统一在线搜索扩展。对模型只暴露 web_search / web_fetch，schema 与提示词不含厂商名；web_search 由当前主模型（ctx.model + ctx.modelRegistry.complete）按内置路由规则在 Tavily / Exa / Keenable 间选择并经统一参数翻译调用，details 记录实际 provider 与路由方式，决策按会话内 LRU 缓存，路由失败或被选厂商报错按可用性顺序降级；web_fetch 固定走 Exa web_fetch_exa，失败时静默降级 Keenable → Tavily。clients/ 为纯 fetch 直连：Tavily 走 api.tavily.com（必须有 key），Keenable 复刻上游 client 保留 keyless /public 端点与 SSRF 防护，Exa 直接对 mcp.exa.ai/mcp 发 JSON-RPC（缓存 mcp-session-id，404 自动重建会话，key 只走 x-api-key 头），不使用 pi-mcp-adapter 或任何上游扩展包。
• configure.sh search 与 scripts/search-auth.mjs：以交互或参数方式把 tavily / exa / keenable 三条 api_key 凭据写入 Pi 的 auth.json（$PI_CODING_AGENT_DIR/auth.json，默认 ~/.pi/agent/auth.json）；加锁后原子写、权限 600、保留全部其他条目，支持 --migrate 从旧 search.env 导入。pi-web-search/auth.ts 每次调用读取并复刻上游解析语义（!command 执行、$VAR/${VAR} 插值、credential env 优先于进程 env、$$/$! 转义）；显式进程环境变量不再直接读取，env 注入通过 "key": "$VAR" 表达。
• extensions/codegraph.ts：注册原生 codegraph_explore 工具，以 execFile argv 形式调用机器级 codegraph CLI（每次调用为短命进程，无常驻 server/daemon）；未初始化项目先经 ctx.ui.confirm 确认再 codegraph init 并自动重试，拒绝或失败则把结果打回让模型改用 find/grep/read/LSP；结果按 codegraph.db mtime 做有界缓存，索引一变即失效。
• extensions/plugin-init.ts：已移除；原 /plugin_init 的 CodeGraph 初始化职责由 extensions/codegraph.ts 在首次 codegraph_explore 调用内按需确认完成。
• context-mode：加载上游 Pi adapter 与 skills，提供 ctx_* 工具、隔离式大输出处理和会话连续性。
• extensions/hashline.ts：部署组合包权威 config/pi-hashline-edit.json 后加载 pi-hashline-edit，以行哈希锚点覆盖内置 read / edit；Hashline 自带 grep 强制关闭。
• extensions/permission-system.ts：直接加载仓库内 pi-permission-system/src/index.ts，自身不部署、不播种、不迁移任何配置。扩展运行时直接读取已安装组合包内的 config/pi-permission-policy.jsonc / config/pi-permission-hard-guards.jsonc；日志保留在 <agentDir>/my-pi/permission-system/logs/。旧 extensions/pi-permission-system/ 位置的残留文件被忽略，不迁移也不清理。项目级 policy 不读取。
• extensions/lsp.ts：把组合包内 TypeScript Language Server CLI 物化为绝对命令路径，部署 TypeScript/Kotlin/JDT LS 全局配置并加载 pi-lsp。
• extensions/tool-routing.ts：保留 Pi 默认系统提示词，在每轮开始前按激活工具追加简短路由规则，并提供 /dump-system-prompt 将扩展所见的有效提示词写入 .pi-debug/effective-system-prompt.md。
• extensions/system-prompt-cover.ts：把 Pi 默认系统提示词的开头替换为组合包权威 config/system-prompt-cover.md（扩展运行时直接读取已安装组合包内文件，不部署到 agent 目录），并用文本拼接保留其余全部分区及其原始顺序。必须注册在 tool-routing.ts 之前：tool-routing 会以 forceSystemPrompt 压平提示词，在其后改 systemPromptOptions 将不再影响本轮请求。封面文件缺失或空白时不干预。
• pi-chrome/：从上游源码导入并由本仓库直接维护，通过用户安装的 unpacked MV3 扩展与 127.0.0.1:17318 loopback bridge 接管当前已登录 Chrome；控制默认锁定，每个 Pi session 必须显式 /chrome authorize。
• 上游来源：https://github.com/tianrendong/pi-chrome
• 初始导入快照：017ff4b9a639f0b8b213e58a3f30613fc38edcc8（0.15.46，该 commit 无对应 tag）。
• 该目录从明确 commit 导入并由本仓库直接维护，不使用 npm 预编译产物，不是 submodule，也不保留嵌套 .git、node_modules 或构建产物。
• pi-tool-search/：从上游 v0.3.6 源码导入并由本仓库直接维护；从完整工具定义生成并缓存经过校验的 Tool Cards/工作流分组，通过固定工具 + 有界动态组 LRU 加载当前 Pi 的原始 schema。
• 上游来源：https://github.com/tuansondinh/pi-tool-search
• 初始导入快照：ddfb23646fd3957b791214de278e23aa393c9b13（v0.3.6）。
• 该目录不是 submodule，不保留嵌套 .git、上游 .pi 状态、node_modules 或构建产物。
• pi-ask-user/：把 Pi 上游 question.ts 与 questionnaire.ts 示例整合为模型主动调用的 ask_user_question 工具，统一支持单题、多题、选择、自由文本、自定义回答与复核；不加载 /qna。
• 上游来源：https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions
• 初始参考快照：dcd461925db2edf69a43c8135db1180d418afd54（2026-08-24）。
• 该目录由本仓库直接维护，保留上游 MIT 许可证与来源说明；根组合包直接加载源码并通过本地 file: 依赖打包。
• pi-worktree/：完全自维护（无上游）的斜杠命令 git worktree 管理扩展，提供 /wt（别名 /worktree）的 new / merge / switch / list / remove / prune 子命令，实现「一键拆分」与「一键合并」；不注册模型可调用工具。
• 状态登记位于 <agentDir>/pi-worktree/state.json（目录 700、文件 600、原子写入），不放 <agentDir>/my-pi/ 下；Pi 不能修改进程 cwd，会话切换通过 SessionManager.forkFrom（或为空会话写入最小 header）生成 cwd 指向目标目录的新会话文件再 ctx.switchSession 重建运行时，切换后的收尾只能在新 ctx 的 withSession 回调中执行。
• 合并流程固定为先确认、再 rebase 到来源分支、最后默认 --ff-only 合并（--squash 可选压缩），冲突时可选择中止或保留后用 /wt merge --continue / --abort 处理，来源改动用 stash 兜底，永远不会 push；登记文件写入走 state.json.lock 锁文件串行化；worktree 根目录与分支前缀由组合包 config/pi-worktree.json 的 root / branchPrefix 配置。
• 来源 checkout 的 .pi/worktree.json（version: 1）声明环境复刻：copy 只复制未跟踪文件、link 只软链 gitignore 目标、env 渲染为 600 权限环境文件、postCreate 仅在 ctx.isProjectTrusted() 时以 argv 形式 execFile（绝不走 shell），任一失败即停并可用 /wt reopen 增量重跑；未被 .gitignore 覆盖的软链/环境文件写入 .git/info/exclude（仓库各 worktree 共享），保证 /wt merge 不会提交它们。
• pi-lsp@0.1.7：提供声明式 LSP 接入；组合包内置 typescript-language-server@5.3.0 + typescript@6.0.3，并配置机器级 kotlin-lsp --stdio 与 jdtls。
• pi-hermes-memory/：从官方 pi-hermes-memory 仓库导入并由本仓库直接维护的 Hermes 风格持久记忆扩展；提供全局/项目/用户/失败四类记忆、SQLite FTS5 trigram 会话与记忆检索、SKILL.md 过程记忆、correction 检测、自动 consolidation、STANDING.md 常驻指令和 6 个记忆工具。
• 上游来源：https://github.com/chandra447/pi-hermes-memory
• 初始导入快照：df624056a2e8c68bc89ba0a81e1c120856ec9665（v0.9.10）。
• 该目录从明确 tag 导入并由本仓库直接维护，不使用 npm 预编译产物，不是 submodule，也不保留嵌套 .git、上游 .github 工作流或构建产物。
• pi-minimal-footer/：基于上游紧凑 footer，保留上下文仪表、订阅用量条和扩展状态。
• 上游来源：https://github.com/ogulcancelik/pi-extensions/tree/main/packages/pi-minimal-footer
• 初始导入快照：77bd1e175003cd08e6d05d9e7fed695f86ae87b7（@ogulcancelik/pi-minimal-footer@0.1.10）。
• 该目录从明确 commit 的上游源码导入并由本仓库直接维护，不使用 npm 预编译产物，不是 submodule，也不保留嵌套 .git。
• pi-notify/：基于 @smoose/pi-notify 的 Kitty 优先通知扩展，使用 OSC 99 精确聚焦来源 window/pane，在 Pi 完全 settled 后发送完成通知，并在 permissions:ui_prompt 表示即将请求人工权限确认时立即通知。
• 上游来源：https://github.com/smoosex/pi-notify
• 初始导入快照：3a3691ab690b4bc37a4412ab0dcbd35ef14adcbf（@smoose/pi-notify@0.1.1）。
• 该目录从 npm 对应明确 commit 的源码导入并由本仓库直接维护，不使用 npm 预编译产物，不是 submodule，也不保留嵌套 .git。
• pi-compaction/：统一管理增量 Session segment、确定性工具结果压缩、后台语义摘要、effective token 口径、context_tree_query、portable checkpoint 与 Codex native compaction；普通 Provider、native compaction、footer 和本地 context observer 必须消费同一个不可变 projection snapshot。
• 上游参考一：https://github.com/jjuraszek/pi-condense，快照 59c95110aacd8131db71e21296765dd80b72fae8（v2.9.1）。
• 上游来源二：https://github.com/ogulcancelik/pi-extensions/tree/main/packages/pi-codex-compaction，导入快照 c4d6ca8fb484ba51684296ba8b4715f8c7b3ac91（0.1.4）。
• pi-compaction 采用全新的 pi-compaction version 1 Session 记录和组合包 config/pi-compaction.json 配置，不读取或迁移旧 context-prune-*、contextPrune 或 openai-codex-native-compaction 状态；切换后应使用新 Session。两份上游 MIT 许可证及来源差异保留在包内。
• 根包还固定安装 pi-hashline-edit@0.8.3、typescript-language-server@5.3.0 和 typescript@6.0.3；@gotgenes/pi-permission-system、@smoose/pi-notify、pi-ask-user、pi-chrome、pi-compaction、pi-hermes-memory、pi-minimal-footer、pi-ssh、pi-tool-search、pi-web-search 与 pi-worktree 分别指向仓库内对应目录的本地 file: 依赖；pi-subagents/ 仅保留源码，不作为根运行时依赖。
• install.sh：先安装根组合包（组合包配置即随包内的 config/ 就位，不做额外部署），然后交互检查 Kitty/Solarized Dark、Oh My Zsh/Powerlevel10k/Zsh 插件、CodeGraph、Kotlin LSP、Java 21+ 和 JDT LS；缺失项目只在用户明确选择 Y 后安装或配置。Powerlevel10k 默认配置来自仓库内置的 config/p10k.zsh（当前 Rainbow/ASCII 单行紧凑主题）。
• update.sh：先通过 pi update 升级根组合包，成功升级后把默认 git 来源的已安装组合包 checkout git reset --hard 还原到已发布版本（本地路径来源不 reset，不做 git clean 以保留 node_modules），再只升级当前已安装的终端环境和机器级依赖；未安装项直接跳过。不得在 pi update 前预清理安装缓存；pi update 失败时 fail-fast 停止——Pi 1.3.0 会在下一次 pi update 时依据其 .pi-update-incomplete 标记自行重跑 git clean -fdx 与依赖安装完成自愈，本脚本不做人工恢复。其他组件升级前先查询并比较本地与远端版本，只有版本不同时才下载或替换；Powerlevel10k 配置优先从 pi update 后的已安装组合包读取，并与 .zshrc 受管块一起按内容比较后增量同步。
• uninstall.sh：先移除根组合包，其他共享终端环境和机器工具不卸载。不得删除 .pi/agent/pi-hermes-memory/、projects-memory/、.hippo/ 或任何用户记忆数据。

当前职责与默认行为

• FFF 独占本地字面搜索；远端服务器由独立的 ssh_find / ssh_grep 结构化工具在已授权调用内自适应使用现有命令。RTK 不得处理本地或远端搜索工具的调用/结果，也不得通过默认命令改写接管 rg、grep、find、fd。
• RTK 默认只压缩非搜索输出，包括本地 bash 与远端 ssh_bash 的 ANSI 清理、测试聚合、构建过滤、Git 压缩、Lint 聚合和兜底截断；ssh_bash 只复用输出处理，远端命令不得进入 RTK rewrite。
• commandRewritingEnabled 默认 false。默认安装不依赖系统 rtk CLI；只有用户主动开启命令改写时才需要 rtk rewrite。
• readCompaction.enabled、sourceCodeFilteringEnabled 和 smartTruncate.enabled 当前均默认 false，源码读取保持原样。未经用户明确决定，不因节省上下文而改变这些默认值。
• 若以后开启 read 压缩，优先考虑 readCompaction + smartTruncate，源码过滤仍独立评估；必须保留精确 offset/limit 读取、短文件和行锚点的完整性。
• Context Mode 负责避免批量读取、命令研究和网页原始内容直接撑大上下文；FFF 仍负责精确字面搜索，RTK 仍处理未走 Context Mode 的普通输出。
• chrome_snapshot、chrome_find 以及带 includeSnapshot=true 的交互工具必须把完整结构化快照写入当前项目 .pi/chrome-context/ 下的 Session 临时文件，工具结果只返回相对路径与有界摘要；模型必须立即用 ctx_execute_file 提取下一步所需信息，不得用 read / cat 把原始 JSON 重新塞入上下文。每个 Session/目标只保留最新快照，页面交互后旧快照视为失效，Session shutdown、撤销或授权过期时清理。
• Hashline 默认以 2 字符行哈希覆盖内置 read / edit，grep 和 replaceText 均关闭；它保证锚定编辑而不负责压缩，大文件上下文节省必须来自先定位/隔离分析、再做最小范围 offset/limit 读取。
• 工具路由规则不得替换 Pi 默认系统提示词：代码结构、调用关系和待修改 symbol 优先 CodeGraph，定义/引用/类型/诊断优先 LSP；工作区内大文件探索、分析和总结优先 ctx_execute_file，日志、构建与不可预测命令输出优先 Context Mode；字面搜索先用 FFF find 收敛文件位置，再在收敛路径内用 grep/multi_grep 获取行号；真正修改前才用小范围 Hashline read 获取新鲜锚点并用锚定 edit。在线搜索由 pi-web-search 内部路由，模型不感知厂商：路由规则为广泛发现、新闻和候选来源偏 Tavily，官方/技术/论文和高确定性来源偏 Exa，中文、站点限定和日期筛选偏 Keenable；路由决策由当前主模型做出，确定性逻辑只处理可用性与失败兜底，不得改写成启发式断路。遇到大量结果、截断或上限时继续缩小范围，不得靠提高 limit 或倾倒全部结果解决。
• ask_user_question 只用于模型继续任务所必需的用户决定、偏好、确认或澄清；不得重复询问直接用户消息中已有的信息。工具支持交互式 TUI 与具备 Pi extension UI bridge 的 RPC 客户端、顺序执行和最多 8 题；RPC 必须使用标准 select / input 对话框逐题收集，JSON/print 等无 UI 模式保持拒绝。取消或 abort 必须返回 cancelled: true，不得伪造答案，且 /qna 不属于该扩展。其成功 details.answers 必须保留 question / answer 字段，以匹配 AutoReview 已有的可信结构化用户交互边界。
• Tool Search 默认常驻核心 read / write / edit / bash / grep / find、codegraph_explore、lsp_diagnostics、ctx_execute / ctx_execute_file / ctx_batch_execute、六个记忆工具与 context_tree_query，以及 tool_search；Windows 上内置 powershell 必须与 bash 同属固定本地 Shell 核心工具，非 Windows 平台必须从目录中过滤。配置从已安装组合包内的 config/tool-search.json 直接读取，文件缺失或无效时回退 BUNDLE_TOOL_SEARCH_DEFAULTS；扩展自身不播种、不迁移，也不再读写 settings.json 的 toolSearch 段。其余组合包工具必须优先使用 pi-tool-search/extensions/bundle-groups.ts 中提交的权威工作流分组；精确已有分组必须直接激活，不得等待无关未知工具的模型增强。默认最多 5 个动态组、模型组最多 8 个工具、动态工具总数最多 28；groups 可原子激活最多 5 个精确组，完整请求超限时不得改变当前状态；加载或组内调用更新 LRU，超限先移除最久未用的非请求组。自然语言查询必须优先精确工具名和已提交 workflow alias，弱匹配或近似同分只能返回候选，不得任意激活；/tool-search-status 必须显示当前容量、LRU 顺序与最近淘汰原因。
• pi-chrome 在未授权时不注册 Chrome 工具；显式授权后出现的 21 个 chrome_* 工具必须由 Tool Search 分入 chrome-navigation、chrome-interaction、chrome-debugging，不得落入 unknown-tools 模型增强路径。授权撤销或过期时必须停用全部 21 个工具，包括 chrome_find / chrome_inspect；Tool Search 重新激活 schema 不能替代每次执行时的授权校验。
• 标准组合包工具全部命中预置目录时 Tool Search 不得调用模型、创建用户缓存或发送隐藏 schema。只有存在未识别第三方工具时才允许惰性模型增强；生成结果必须保留全部预置 assignment，模型元数据不得替代真实名称、参数或 schema。缓存必须位于 agent 目录且权限 600；模型失败必须继续使用预置目录 + 确定性未知工具分组。groupOverrides 优先级高于预置分组。
• Tool Search 必须直接使用当前 @earendil-works/pi-coding-agent、typebox、ModelRegistry.complete() 和 setActiveTools()；首次纯增加载使用当前 Pi 的增量结果传播，LRU 替换允许走宿主安全 fallback。不得安装或映射旧 @mariozechner runtime，不得恢复 provider payload 改写、代理分发或隐藏 sendMessage steer/retry 兼容循环。Tool Search 是唯一可调用 getActiveTools() / setActiveTools() 管理工具显隐的组合包扩展；pi-permission-system 只能在调用时裁决，不能读写 active tool 列表。
• pi-worktree 只注册 /wt / /worktree 斜杠命令，不暴露任何模型可调用工具；其 git 操作由用户显式触发，经 execFile argv 直接调用（带超时、不经 shell），按设计绕过 Bash 工具权限策略，不新增权限审批层。
• .pi-debug/ 是 /dump-system-prompt 生成的本地诊断目录，不提交到仓库，也不作为组合包运行时配置源。
• CodeGraph 是机器级依赖：install.sh/update.sh 经官方安装器管理 codegraph CLI，组合包不内置其运行时。安装、升级和普通启动流程不得执行 codegraph init；只有 codegraph_explore 在未初始化项目上被调用、且用户在 ctx.ui.confirm 中明确确认后，扩展才可以 codegraph init 当前目录。init 失败必须如实报告并让模型回退内置工具；不得改动 CodeGraph 更新或遥测设置。
• codegraph_explore 为原生 Pi 工具而非 MCP 工具：每次调用通过 execFile/pi.exec 以 argv 形式运行 codegraph explore（带超时、不经 shell），结果按 .codegraph/codegraph.db mtime 缓存；CLI 缺失、init 被拒绝或执行失败都不得抛出或阻止其他工具，必须以文本结果打回并引导模型改用 find/grep/read/LSP。
• 组合包不加载任何 MCP adapter；Exa 由 pi-web-search/clients/exa.ts 以纯 fetch JSON-RPC 直连托管端点 https://mcp.exa.ai/mcp：initialize 一次并缓存 mcp-session-id，随后 tools/call，HTTP 404 视为会话失效自动重建并重试一次。exa 凭据通过 x-api-key 请求头发送，不得放入 URL、仓库文件或日志。
• 在线搜索对模型只暴露 web_search / web_fetch 两个统一工具名，不得重新引入按厂商命名的工具；web_search 必须经 router.ts 的主模型分类选择 provider，web_fetch 固定优先 Exa。Exa 搜索统一走 web_search_advanced_exa 并显式约束 numResults 与 textMaxCharacters；Tavily 默认 search_depth: basic 且必须在 auth.json 存在 tavily api_key 凭据才参与路由；Keenable keyless 可用，keenable 凭据仅提高速率限制。
• 搜索 key 统一保存在 Pi 的 auth.json（tavily/exa/keenable 各一条 api_key 凭据，文件权限 600 且不得提交）；key 支持 !command 与 $VAR 间接寻址，configure.sh search / search-auth.mjs 只输出配置状态，禁止回显 key。旧的 search.env 不再被读取，仅由 --migrate 一次性导入。
• extensions/context-view.ts 是只读的本地 effective-context observer，只读取 pi-compaction/src/service.ts 发布的 projection metrics，不注册生产 context writer；pi-minimal-footer 优先显示同一 effective usage，snapshot 尚未建立时才回退宿主原始 usage。
• pi-compaction 负责已经进入 Session 的历史投影，与 Context Mode 的输入隔离职责互补。首次 Session hydration 允许一次完整扫描；后续普通 context hot path 必须复用不可变 snapshot 或只处理 delta，不得调用 summarizer、写 Session 或重新构建完整 branch。
• 已闭合工具结果先同步生成保留工具名、参数、状态、首尾证据和 source key 的有界确定性 stub；大于 semantic.minInputChars 的结果再进入单 Session 有界后台语义 worker。后台结果只在安全事件边界提交，陈旧 hash 必须丢弃，Provider 请求不得等待后台摘要。
• effective token 默认使用 Provider usage-backed baseline 加 projected delta；无可靠 baseline 时使用带上下界的估算。Pi Core raw threshold 只负责唤醒，只有 effective lower bound 达到 hardRatio 才执行 threshold compaction；manual 与 overflow 不得被阻断。
• Codex native compaction 必须直接消费当前 projection 生成的 ResponseItems，不得从 raw branch 重建输入；native checkpoint 同时保存有界 portable summary 供模型或 Provider 切换。配置只从组合包 config/pi-compaction.json 读取且不写回 settings.json，默认 soft/hard/target 比例为 72%/90%/55%。
• Kitty 完成通知只在 TUI 模式的 agent_settled 后发送；自动重试、自动 compaction 和 follow-up 期间不得提前通知或重置总耗时。权限通知只订阅 permissions:ui_prompt，在人类确认界面即将出现时立即发送，不得为策略或 AutoReview 已直接决定的请求通知，也不受完成通知时长门槛影响。默认 o=always、a=focus，每个 Pi Session 使用独立稳定 ID，标题和正文必须 Base64 编码。
• /notify on|off 只覆盖当前 Session；持久默认来自 PI_NOTIFY_* 环境变量。PI_NOTIFY_MESSAGE_SOURCE=none 必须继续提供不泄露回复正文、权限值或请求者细节的隐私模式，非 TUI 模式不得写入 OSC 序列。
• 权限策略默认允许常规工具，允许 FFF 工具，并放行 ls、LSP 查询（lsp_definition/lsp_references/lsp_hover/lsp_symbols）、ctx_search/ctx_index/ctx_stats/ctx_doctor、web_search 与 Chrome 只读检查工具；web_fetch、ctx_fetch_and_index 与 skill_manage 保持 ask（模型自选的 URL 可能外传数据，skill_manage 写入的 skill 会进入所有后续会话）；拒绝 Bash 直搜，硬防御默认只保留确定性的破坏性 Shell 命令；Git 只读管道命令（blame/describe/rev-list/merge-base/ls-tree/cat-file/name-rev/shortlog/stash list/worktree list/tag -l|--list/config --get|--list）放行，其余非只读操作、包管理、文件/系统/网络高风险操作与内置 MCP 的 mcp__<server>__<tool> 调用按唯一全局 policy 判定。项目外路径不再产生独立 external_directory 判断，只走配置中的工具、path 与 Bash pattern。
• SSH 权限沿用同一条 pi-permission-system gate 与 auto-review authorizer chain：ssh_connect、ssh_cd、ssh_read、ssh_write、ssh_edit、ssh_find、ssh_grep 默认 ask；连接前的证据解析已导入 host ID 为非秘密 target、port 与请求/default cwd，AutoReview 只可依据用户直接消息中的明确目标授权连接。ssh_bash 通过 shellTools 映射到完整 Bash 策略并设置 decisionFloor: "ask"，把普通 Bash allow 提升为复核请求，同时保留原有 ask 与硬 deny。全部远端路径不得送入基于本机 cwd 的默认 input.path 归一化。
• auto-review 是 pi-permission-system 内置 authorizer，不是独立扩展或第二个 tool_call gate；只复核普通策略产生的 ask，不会重复处理普通策略已 allow / deny 或硬防御已 deny 的请求。
• reviewer 是对话式 Codex Guardian 风格审查：以独立请求（不写入主会话）把有界 active-branch 对话记录与权限请求交给模型，模型只能通过 approve / reject 两个工具给出带 reason 的结论，不强制 toolChoice。approve 自动批准（包括 path）；reject 以及配置、模型、超时、Provider 错误、截断、未调用工具、多次调用或参数无效等一切异常都必须 defer 到人工提示，并在弹窗中显示原因（模型理由标注为模型生成）。正文文本即使是合法 JSON 也不得作为结论；只有用户按 Esc 中止当前操作时才直接拒绝。不得在 authorizer chain 外增加第二层内置授权范围限制，也不得恢复 annotator 机制。唯一例外是 protectedWrites：硬防御文件里配置的确定性 human-only 写路径——它不经 authorizer chain（含 AutoReview）、yolo 或 Session grant，无确认界面时直接拒绝，本身不产生裁决，只是永远把人拉进回路。
• reviewer 默认跟随会话当前主模型（每次审查实时读取 ctx.model），经 modelRegistry.streamSimple(...).result() 调用；autoReview.provider / autoReview.model 必须同时设置（固定审查模型）或同时留空，只设其一视为配置错误并 defer。默认 reasoning: "low"（仅对支持推理的模型生效）、总超时 30 秒、最多 2 次尝试（仅 Provider 错误重试）、maxOutputTokens 4000。只把 active branch 中的直接用户消息与已识别、未取消的结构化问答作为授权证据，assistant/tool/compaction 内容不能自行授权；工具结果可替换为更短的 pi-compaction 摘要，但仍属不可信证据。同一条用户消息内完全相同的请求只缓存 approve 结论。
• config/pi-permission-policy.jsonc 必须显式配置 authorizerChain: ["auto-review"]，普通未匹配请求和需要自动复核的 Git 非只读、包管理等类别声明为 ask；普通 pattern 必须按具体度优先（精确匹配、字面字符更多、通配符更少、pattern 更长，最后才以声明顺序破同级）；autoReview 段只保留 enabled，不设 provider/model 种子值，使审查默认跟随主模型；config/pi-permission-hard-guards.jsonc 独立保存可由用户调整但不能被普通策略、Session grant、per-agent 规则或 reviewer 覆盖的高危 deny，以及 protectedWrites 人工写保护清单。
• protectedWrites（config/pi-permission-hard-guards.jsonc）是确定性的 human-only 写路径，不属于普通策略也不是第二个授权范围：命中目标的 write/edit 与本地 bash 写入（redirect-out、写操作程序参数、bash -c/eval 等包装载荷中的受保护路径）一律弹出人工确认，跳过 AutoReview、yolo 与既有 Session grant，弹窗不提供「本会话允许」选项；没有可用确认界面（无 UI、子代理转发终端）时直接拒绝。读取不受影响；ssh_bash 等远端 shell 工具不参与本机路径保护。
• pi-lsp 的 TypeScript/JavaScript 后端由根包固定依赖提供，extensions/lsp.ts 使用当前 Node 可执行文件直接启动包内 typescript-language-server CLI，不得依赖或调用 VS Code GUI；Kotlin/JDT LS 仍使用组合包部署的 kotlin-lsp --stdio 与 jdtls 配置，根包不安装这两个系统可执行文件，便捷脚本可在用户逐项明确确认后通过 Homebrew 安装 Kotlin LSP、Java 21 和 JDT LS。
• 终端环境配置只属于便捷脚本：Kitty 可选安装后可通过官方 kitten 启用 Solarized Dark；Oh My Zsh 使用不切换 shell 的 unattended 安装；Powerlevel10k 将仓库内置的 config/p10k.zsh（Rainbow/ASCII 单行紧凑主题）部署到 ~/.config/my-pi/p10k.zsh（遵循 XDG_CONFIG_HOME），不得覆盖用户自己的 ~/.p10k.zsh。.zshrc 中脚本拥有的内容必须使用 # >>> my-pi:<id> >>> / # <<< my-pi:<id> <<< 受管块，更新时只替换块内内容；标记不完整或重复时拒绝修改。实际修改前必须创建带时间戳的备份。git、zsh-autosuggestions、zsh-syntax-highlighting 在安装流程中逐项询问后才安装或启用。
• 原生远程压缩限定为 openai-codex + openai-codex-responses 与 sub-api + openai-responses，默认在 turn boundary 达到 effective 下界 90% 时触发。pi-compaction/src/native-provider.ts 统一资格与传输选择：Codex 保留原 endpoint/JWT/account ID；SubAPI 从显式 baseUrl 解析公共 /responses，使用配置的 API key 和请求头，不解析 ChatGPT account ID、不硬编码网关域名，也不调用独立 /responses/compact。两者复用 projection、compaction_trigger、SSE 结果、native checkpoint 恢复和 portable 模型切换摘要；SubAPI 部署须支持原生 compaction v2。普通聊天支持不代表压缩支持，失败回退 Pi，不自动改写用户模型配置。
• SubAPI 原生压缩认证必须保留非空显式 Authorization（大小写不敏感）的优先级；没有该头时才使用非空 API key 生成 Bearer，均缺失时可接受非空 cf-aig-authorization 代理认证头。不得要求 header-only 配置额外提供假 API key，也不得生成 Bearer undefined；空白或缺失凭据在网络请求前拒绝并回退 Pi。Codex 仍必须提供有效 JWT，不能用请求头绕过。
• 记忆由 pi-hermes-memory 统一负责：默认 policy-only 模式只注入 <memory-policy> 指令而不注入记忆正文，因此它不改变 system prompt 前缀、对 DeepSeek 前缀缓存友好；模型需要历史上下文时主动调用 memory_search / session_search，写入用 memory_add / memory_replace / memory_remove，过程记忆用 skill_manage。
• 六个记忆工具与 context_tree_query 必须由 pi-tool-search 的 alwaysEnabled 常驻，不得放入动态组：注入的 policy 会在普通工作中指示模型调用记忆工具，而恢复被投影的工具证据也不能依赖 tool_search 激活；常驻同时保持请求前缀稳定。它们只写扩展自己的 agent 目录数据或只读本地索引，不触碰工作区，因此在权限策略中默认 allow，避免每轮 AutoReview 往返。
• pi-hermes-memory 必须注册在 pi-compaction 之前。ExtensionRunner.emit() 在第一个返回 { cancel: true } 的 session_before_compact handler 处立即停止，而 pi-compaction 在判定无需压缩时正是这样返回；注册在其后的 handler 会被跳过，从而静默禁用 flushOnCompact。
• pi-hermes-memory 依赖 better-sqlite3@13，运行时实际 dlopen 的是包内 N-API 预编译二进制 prebuilds/<platform>.node，不依赖 node-gyp 编译产物。npm 会因该包存在 binding.gyp 而推断出隐式 node-gyp rebuild，该步骤既无必要也不得批准；根 allowScripts 必须保持不新增条目，同时保留既有的 better-sqlite3@12.11.1 放行。
• skill_manage 是 pi-hermes-memory 提供的能力，不是 Pi 宿主能力：Pi 只发现并加载 skill 目录（~/.pi/agent/skills/ 加扩展通过 resources_discover 注册的目录），没有创建 skill 的工具。该扩展同时承担 skill 写入与目录注册；不加载它，projects-memory/<项目>/skills/ 下的既有 skill 也不会被 Pi 发现。
• install.sh 默认从 git:git@bitbucket.org:siakitem/my-pi.git 安装，并允许用 PI_PACKAGE_SOURCE 覆盖来源；组合包安装失败时立即停止，机器级依赖安装失败时继续检查其余依赖并最终返回非零状态。
• CodeGraph 的可选安装使用官方远程安装脚本；macOS Kitty 使用 Homebrew cask，其他系统使用 Kitty 官方安装器；Kotlin LSP、Java 21 和 JDT LS 使用 Homebrew；Oh My Zsh 使用官方安装器，Powerlevel10k 与两个第三方 Zsh 插件从各自官方 Git 仓库克隆。升级时 Git checkout、Homebrew 包、Kitty 官方安装和 CodeGraph 都必须先比较本地与远端版本，版本一致时不得重新下载安装；无法可靠比较时保留现状并报告。缺少 Homebrew、curl 或 git 时保留已经完成的组合包安装并报告失败。
• install.sh 不检查默认不需要的 rtk CLI；update.sh 和 uninstall.sh 使用同一个 PI_PACKAGE_SOURCE 规则分别调用 pi update 和 pi remove。运行 update.sh 视为明确授权升级已安装组件；单独的 pi update 只在新版本存在时整体覆盖已安装副本（含 config/），update.sh 每次成功升级后都会把受管 checkout 还原到已发布版本，两者都不逐字段迁移或合并本机对已安装副本的改动；需要长期保留的自定义必须改仓库 config/ 源文件。不得安装缺失组件或改写受管块之外的用户配置；卸载不得删除用户记忆数据，其他共享机器级工具保持不变。
• <agentDir>/my-pi/ 只存放可随时丢弃的运行时状态（日志、缓存），不存放配置；组合包配置一律以仓库 config/ 为唯一来源并由扩展直接读取。用户数据（记忆、会话、auth.json、models.json、settings.json、search.env 等）不得放入该目录。外部 npm 扩展固定路径的 hashline.json、lsp.json 位于 agent 根目录，是唯一例外（扩展加载时从 config/ 覆盖写入）；旧位置（extensions/pi-permission-system/、settings.json 的 toolSearch 段、agent 根 SYSTEM_COVER.md）的残留不迁移也不清理。

组合包配置原则

• 本组合包是私有组合包，所有机器上的组合包配置必须一致。组合包自有扩展的全部配置只以仓库 config/ 为唯一来源，扩展运行时直接读取已安装组合包内的 config/ 文件，不复制、不播种、不迁移到 agent 目录。
• 配置变更一律修改仓库 config/ 并随组合包发布；pi install / pi update 即完成部署，便捷脚本不得再承担配置部署。某台机器上对已安装副本的临时修改（包括扩展设置界面的保存）不做保护、合并或提示：单独运行 pi update 只在有新版本时覆盖，update.sh 每次成功升级后都会把受管 checkout 还原到已发布版本。
• 新增或导入扩展时，其可配置项必须放进 config/ 下的独立文件；不得读写 Pi settings.json 的自定义段、agent 目录下的独立配置文件，也不得以环境变量作为持久默认值。只有外部 npm 扩展固定读取 agent 目录路径时（当前为 hashline.json、lsp.json），才允许在扩展加载时从 config/ 覆盖写入该路径。
• config/ 只放与机器无关的值；依赖本机路径的默认值（home 下的目录、可执行文件绝对路径等）保留在代码中运行时计算。
• <agentDir>/my-pi/ 只存放可随时丢弃的运行时状态（日志、缓存），不得存放配置。用户数据（记忆、会话、auth.json、models.json、凭据库）不属于组合包配置，不受本节约束，也不得放进 config/。

修改边界

• 优先在目标扩展目录内完成改动；不要让一个扩展依赖另一个扩展的未公开内部实现。
• 保留原项目的 LICENSE、版权信息和必要的来源说明。
• agent 目录下扩展运行时产生的数据——<agentDir>/my-pi/ 可丢弃运行时目录、旧 extensions/pi-permission-system/ 残留、日志、构建产物、覆盖率目录和依赖目录——属于本地状态，不应提交；config/ 下的全部文件（pi-permission-policy.jsonc、pi-permission-hard-guards.jsonc、tool-search.json、rtk-optimizer.json、pi-compaction.json、pi-worktree.json、pi-hermes-memory.json、system-prompt-cover.md、pi-hashline-edit.json、lsp.json、p10k.zsh 等）是组合包权威源配置，必须提交并维护。
• 外部 Pi 扩展依赖必须在根 package.json 中使用精确版本，自维护扩展必须使用本地 file: 依赖，并更新根 package-lock.json；不要用仓库级 .pi/settings.json 代替组合包依赖。
• 需要原生构建的依赖只按锁定版本加入根 allowScripts；当前 better-sqlite3@12.11.1 仍由 Context Mode 使用并保持精确放行。pi-hermes-memory 的 better-sqlite3@13 运行时使用包内 N-API 预编译二进制，npm 因 binding.gyp 推断出的 node-gyp rebuild 无需执行，不得为此新增放行条目。
• Pi 核心包只作为宿主 peer dependencies，不得在组合包内再安装或打包一套 Pi runtime；保留根 .npmrc 的 peer 安装策略。
• pi-tool-search/ 的根依赖必须保持 file:./pi-tool-search，组合包直接加载 pi-tool-search/extensions/index.ts；同步上游时先核对本地增量动态工具改造，禁止用旧 npm 入口或上游旧宿主实现直接覆盖。
• 新引入或同步自维护扩展时，必须先联网确认其官方源码仓库地址，再从官方 Git 仓库的明确 tag/commit 拉取源码快照；禁止以 npm tarball、npm 缓存、node_modules、dist/ 或其他预编译发布产物作为导入源。npm registry 只能用于核对包名、版本和发布元数据，不能替代源码仓库。
• 源码导入必须保留上游源码、测试、必要文档、许可证和来源记录，移除嵌套 .git、上游本地 .pi 状态、node_modules、覆盖率与构建产物，并在本文件和扩展来源说明中记录官方仓库、tag、commit 与版本。
• 每个自维护扩展目录必须保留 UPSTREAM.md 来源记录，并且必须用中文维护：记录官方仓库、tag/commit、导入版本、导入日期、许可证归属、本地改动清单，以及同步上游时的约束。UPSTREAM.md 是仓库自有的维护文档，不是上游产物；上游自带的源码、测试、文档、README、CHANGELOG 与 LICENSE 一律保持上游原文，不翻译、不改写。新增扩展或同步上游导致来源信息变化时，必须同步更新该文件。
• pi-notify/ 的根依赖必须保持 file:./pi-notify，组合包直接加载 pi-notify/src/index.ts；不得同时安装或加载 npm 预编译入口，否则会重复通知。
• 上游仅作为参考来源。同步上游改动时先核对本仓库已有修改，再按明确范围移植；不要直接覆盖本地实现。
• install.sh、update.sh、uninstall.sh、configure.sh 和 scripts/lib.sh 必须保持 POSIX sh 兼容，前者包含在根 package.json 的 files 中；修改脚本行为时同步更新 README 和本文件。
• 安装流程中的机器级依赖和用户终端配置必须保持逐项询问且默认拒绝，不得在没有用户明确确认的情况下自动安装或改写。用户主动运行 update.sh 只授权升级已安装项；缺失项仍必须跳过。.zshrc 修改必须局限于受管块并保留备份，卸载不得顺带删除或还原共享工具和用户终端配置。
• 未经明确要求，不执行发布、提交、推送、运行安装/卸载脚本或安装到用户 Pi 运行目录等外部写操作。

根目录 TypeScript 与 LSP 验证约定

• 根目录当前有意不安装 Pi runtime，也没有根级 tsconfig.json、devDependencies 或 @types/node；@earendil-works/pi-* 只作为 optional host peer dependencies。TypeScript LSP 因而会把根目录 .ts 文件放入 inferred project，不能把宿主 Pi 的运行时解析能力等同于仓库内静态类型环境。
• 每个任务首次对相关根目录 TypeScript 文件调用 lsp_diagnostics 时先建立并记录基线；后续只关注相对基线新增、消失或位置变化的诊断。文件和类型环境都未变化时不得重复调用 LSP 并重复报告同一组结果。
• 当前可预期的基线包括：宿主 peer 缺失导致的 TS2307（例如找不到 @earendil-works/pi-coding-agent），Node 类型缺失导致的 node:* / node:test / node:assert TS2591，以及由这些上游类型缺失级联产生的 TS7006、TS18048、TS2722 等。遇到级联错误时先确认其是否随缺失类型而产生，不要把它们直接归因于本次实现。
• 已知基线不等于忽略所有诊断：凡是无法由上述缺失依赖解释的新语法错误、结构类型错误、错误属性访问或本次修改所在代码的新诊断，必须修复并重新验证。交付时应把“已知类型环境基线”和“本次新增诊断”分开说明。
• 不得为了消除 LSP 基线而在根包安装第二套 Pi runtime、加入机器相关的宿主绝对路径或提交只在单机有效的 paths 映射。若确需新增根级 tsconfig.json、@types/node 或其他开发类型环境，必须作为明确的仓库设计变更评估，并同步更新依赖、锁文件和本文档。
• 不要从泛型或重载的 ExtensionAPI 方法直接用 Parameters<...> 猜取具体工具定义；解析失败时它可能退化为 unknown。包装第三方工具时优先使用上游导出的具体类型；没有稳定导出时定义覆盖实际访问字段的最小结构类型，并用运行时集成测试验证。
• node --test 可直接测试仓库内的纯 TypeScript helper，但测试入口不得静态导入 node_modules 中的 .ts；Node 原生 type stripping 会对这种路径报 ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING。第三方 TypeScript 扩展 wrapper 应拆出本地纯 helper 做单元测试，并通过隔离的临时 Pi agent/jiti 加载验证真实扩展入口。
• 对根目录扩展的最终验证优先组合使用：纯 helper 的 node --test、git diff --check、所需 npm 锁文件检查，以及隔离 Pi 环境的扩展加载。LSP 启动成功、单元测试通过和真实 Pi 加载通过是不同证据，不得互相替代或把类型环境基线误报为 LSP 后端启动失败。

pi-rtk-optimizer 开发约定

• 组合包运行环境为 Node.js 22.19 或更高版本；RTK 子目录开发验证还需要 npm、Bun 和项目声明的开发依赖。
• 扩展入口是 pi-rtk-optimizer/index.ts，主要实现位于 pi-rtk-optimizer/src/。
• RTK 命令改写默认关闭；若用户主动开启，其命令支持策略由已安装的 rtk rewrite 决定，不在扩展内重复维护规则。
• FFF override 独占搜索工具与搜索输出；RTK 不得处理 grep 工具结果。
• read 压缩属于有损能力。任何默认值调整都必须同时说明哪些内容可能被省略、精确读取如何恢复原文，以及对 edit 文本匹配和排障证据的影响。
• 修改配置结构时同步检查默认值、归一化逻辑、设置界面、类型定义、README 示例和相关测试。
• 工具输出压缩可能损失证据。排障和审计相关改动应优先保证原始输出可恢复，并覆盖锚点完整性和截断边界。

pi-permission-system 开发约定

• 扩展入口是 pi-permission-system/src/index.ts，公共跨扩展服务入口是 pi-permission-system/src/service.ts，测试保留在该目录的 test/。
• 同步上游必须从明确 tag/commit 移植并记录快照；保留上游 LICENSE、作者和来源，不导入 dist/、嵌套 .git 或上游包目录的 .pi 本地状态。
• 配置在 authorizerChain 中显式命名的 authorizer 可对任一普通策略 ask（包括 path）返回最终 allow / deny；defer 才继续下一个 authorizer 或终端人工 authority。
• 修改 gate、authorizer chain、子代理转发或公共 service 类型时，必须同步更新包内 README/架构文档和对应测试。
• 根包必须通过 file:./pi-permission-system 提供运行时依赖，包装入口必须直接加载仓库源码；不得同时加载 npm 预编译入口或第二个 permission-system 实例。
• 内置 AutoReview 实现位于 pi-permission-system/src/auto-review/；同步原 AutoReview 上游时必须从源码仓库明确 tag/commit 移植，保留 LICENSES/pi-permission-auto-review-MIT.txt、作者和 docs/auto-review/UPSTREAM.md，不得恢复顶层独立扩展、npm 预编译入口或平行 gate。
• reviewer 只能处理普通策略已判定为 ask 且未被 hard guard 拒绝的请求；不得绕过硬 deny。
• HardGuardPolicyLoader 必须保持 global-only、无 SessionRules、无项目覆盖；唯一的组合包 hard-guards 文件不可用时 fail closed 到 deny-all，并报告配置问题。普通 policy 与 hard guard 配置不得合并成一份文件。
• 修改 reviewer 策略、可信证据边界、配置结构、hard-guard precedence、模型解析或 authorizer/lifecycle 注册时，必须同步更新 README、配置文档、架构文档、schema 和相应测试。

pi-hermes-memory 开发约定

• 扩展入口是 pi-hermes-memory/src/index.ts，来源记录是 pi-hermes-memory/UPSTREAM.md；只从官方 chandra447/pi-hermes-memory 的明确 tag/commit 移植并保留官方 README、LICENSE 和版权。
• 根包必须通过 file:./pi-hermes-memory 提供依赖并直接加载仓库源码；不得同时安装或加载 npm 预编译入口，也不得保留第二个记忆扩展（hippo-memory-pi 已移除）。
• package.json 的 pi.extensions 必须把 ./pi-hermes-memory/src/index.ts 排在 ./pi-compaction/index.ts 之前，否则 flushOnCompact 会被 pi-compaction 的 { cancel: true } 静默跳过；根 tests/extension-load.test.ts 必须断言该顺序。
• 六个记忆工具与 context_tree_query 必须在 pi-tool-search/extensions/config.ts 的 BUNDLE_TOOL_SEARCH_DEFAULTS.alwaysEnabled 中常驻，并由 pi-tool-search/extensions/bundle-groups.ts 的 memory-recall / memory-management 分组提供目录元数据（context_tree_query 留在 memory-recall）。新增、删除或重命名这些工具时必须同步 bundle-groups.ts、BUNDLE_TOOL_SEARCH_DEFAULTS、config/tool-search.json（二者必须完全一致）、Tool Search 测试、权限策略与 pi-tool-search 的 README / CHANGELOG。
• 依赖必须保持 better-sqlite3@^13.0.3：13.x 运行时使用包内 N-API 预编译二进制 prebuilds/<platform>.node，不依赖 node-gyp 编译产物，必须能由 npm 嵌套安装并与根 better-sqlite3@12.11.1 并存。不得把它降级回 12.x（Node 24 下会在进程退出时 SIGABRT），也不得让根包提升为单一版本。
• devDependencies 中的 @earendil-works/* 必须与根包当前版本精确一致。若写成 ^0.80.2 这类与根不兼容的范围，npm 会在本目录嵌套安装第二套 Pi runtime，违反"不得在组合包内再安装一套 Pi runtime"的纪律；typebox、tsx、typescript、@types/better-sqlite3 同理，必须钉到根已有版本。
• 全局记忆、项目记忆与 skill 位于 ~/.pi/agent/pi-hermes-memory/ 与 ~/.pi/agent/projects-memory/，属于用户数据，安装、升级与卸载脚本不得创建、迁移或删除；扩展配置位于已安装组合包的 config/pi-hermes-memory.json（其中路径类默认值由代码运行时计算），旧 ~/.pi/agent/hermes-memory-config.json 被忽略。
• 修改工具注册、before_agent_start 注入策略、resources_discover 目录注册、SQLite 迁移或 consolidation 后，必须同步包内 README/CHANGELOG/docs，并运行根扩展联合加载与 Tool Search 测试。

pi-compaction 开发约定

• 扩展入口是 pi-compaction/index.ts，增量索引、投影、后台摘要、服务与 Codex native 实现在 pi-compaction/src/，测试位于 pi-compaction/test/，双上游来源记录是 pi-compaction/UPSTREAM.md。
• 根包必须通过 file:./pi-compaction 提供依赖并直接加载源码；不得重新声明或加载 pi-condense、npm @ogulcancelik/pi-codex-compaction 或 npm pi-context-view。
• pi-compaction 只支持自己的 version 1 记录和 config/pi-compaction.json 配置，不得恢复旧状态兼容、自动迁移或读写 settings.json 自定义段。
• Context Authority 是 compaction 唯一生产投影者。普通 Provider、Codex native、/context、/compaction-status 和 footer 必须消费同一 snapshot；background worker 不得在 Provider 请求中被 await。
• Segment custom entry 只能保存摘要、hash 和 source reference，不得复制完整原始工具输出。context_tree_query 恢复结果必须有界，native checkpoint 的 portable summary 也必须有界。
• 修改 projection、token accounting、threshold、checkpoint、模型切换、后台并发或恢复索引后，至少运行 npm test、npm run check、npm pack --dry-run --json、根扩展联合加载、packed 根 tarball 隔离加载和性能回归。性能门禁为 cache-hit P95 <2ms、delta projection P95 <10ms，普通 hot path 不得扫描完整 branch。
• 同步 Codex 协议代码必须从官方 ogulcancelik/pi-extensions 明确 commit 移植并保留对应 MIT 许可证；不得从 npm tarball、缓存、node_modules 或构建产物导入。

pi-subagents 开发约定

• 扩展入口是 pi-subagents/src/index.ts，测试保留在该目录的 test/，来源记录是 pi-subagents/UPSTREAM.md。
• 同步上游必须从明确 tag/commit 移植并保留 README、CHANGELOG、SECURITY、作者和 LICENSE；不得导入嵌套 .git、上游 .pi 状态、node_modules、覆盖率或构建产物。
• 根包当前必须保持禁用 pi-subagents：不得声明 file:./pi-subagents 或 npm 运行时依赖，也不得在 pi.extensions 中加载 extensions/subagents.ts 或上游入口；源码、测试、来源记录和 wrapper 继续保留，且不得把 Pi host runtime 作为组合包开发依赖带入根安装。
• 子会话必须在 bindExtensions() 前注册到 pi-permission-system 的 process-global child registry，并在真实 dispose 时清理；resume、并发和嵌套 Agent 必须维持正确 parent/child session identity。
• extensions/subagents.ts 是当前禁用但保留的组合包 wrapper：若以后经明确决定恢复加载，它只能把组合包内权威 extensions/permission-system.ts 的 canonical absolute path 作为 mandatory extension 注入。Agent frontmatter 的 extensions: false、isolated 和 exclude_extensions 均不得移除该 lifecycle；路径缺失、被同名其他路径冒充或 reload 后未精确命中必须在创建 AgentSession 前 fail-closed。
• mandatory extension 只强制绑定 handlers，不自动开放它注册的工具；工具可见性仍由 Agent 的正常 extensions/tools 策略决定。mandatory 列表不得从 Agent Markdown 或项目配置读取。
• ask 可由 auto-review 明确 allow 时自动批准，包括路径请求；reviewer defer 或异常必须转发父会话人工 authority，不得因子会话无 UI 静默放宽。父模型生成的子 Agent prompt 不得伪装成人类直接授权证据。
• 子 Agent 转发的 access facts 必须先由根 authority 的 SessionRules 匹配；父会话 whole-session grant 可覆盖语义一致的后代操作，普通单次批准不得复制为可重复消费的子 Agent grant。auto-review 必须运行在根会话并只使用根 transcript 的可信用户证据。
• 修改 Agent lifecycle、权限桥接、tool/extension scope、resume、nested agents 或 session persistence 时，必须同步包内 README、CHANGELOG、测试，并运行 npm run lint、npm run typecheck、npm run test 和 npm run build。

pi-notify 开发约定

• 扩展入口是 pi-notify/src/index.ts，Kitty/macOS 后端位于 pi-notify/src/terminal.ts，测试保留在 pi-notify/tests/，来源记录是 pi-notify/UPSTREAM.md。
• 同步上游必须从明确 tag/commit 移植，保留作者、MIT 许可声明与来源；不得导入嵌套 .git、node_modules 或构建产物。
• Kitty OSC 99 必须保留 source-window focus、Session 间唯一 ID、Base64 payload 和 tmux passthrough；修改 visibility/action、事件生命周期、fallback、模板、隐私或命令时必须同步 README 和测试。
• 完成通知默认只在 TUI agent_settled 后发送；权限通知只在 permissions:ui_prompt 后立即发送。非 TUI 输出完整性、策略/AutoReview 静默决定、隐私模式、自动 retry/compaction/follow-up 去重、总耗时、短任务阈值和多窗口点击聚焦都属于回归边界。
• 根包必须通过 file:./pi-notify 提供依赖并直接加载源码，不得同时加载 npm @smoose/pi-notify 实现。

pi-chrome 开发约定

• 扩展入口是 pi-chrome/extensions/chrome-profile-bridge/index.ts，Companion MV3 扩展位于其 browser-extension/，Session 快照存储位于 pi-chrome/src/session-snapshot-store.ts，测试保留在 pi-chrome/test/ 与 pi-chrome/test-suite/，来源记录是 pi-chrome/UPSTREAM.md。
• 同步上游必须从官方 tianrendong/pi-chrome 的明确 tag/commit 移植并保留 README、CHANGELOG、SECURITY、文档、测试、作者和 LICENSE；不得导入嵌套 .git、node_modules 或构建产物。
• 根包必须通过 file:./pi-chrome 提供依赖并直接加载仓库源码，不得同时安装或加载 npm 预编译入口。
• 完整 Chrome snapshot 不得进入普通工具文本或 details；只能原子写入当前项目 .pi/chrome-context/<session>/<target>/snapshot.json，使用哈希目录、POSIX 700 目录 / 600 文件，并只返回工作区相对路径和有界元数据。快照不得跨 Session 持久化，Session 启动/关闭、撤销和授权过期必须清理。
• chrome_snapshot 和带 includeSnapshot=true 的动作必须引导模型立即使用 ctx_execute_file，不得使用 read / cat；任何可能改变页面或目标的成功操作必须使旧快照失效，chrome_find 只可额外返回有界匹配摘要。
• 修改 bridge、Companion 扩展、授权 lifecycle、快照存储或加载入口后至少运行包内 npm test、根 Tool Routing/Tool Search/扩展联合加载测试、npm pack --dry-run --json 和实际 packed tarball 隔离安装验证；未经明确要求不得连接或控制真实 Chrome。

pi-ssh 开发约定

• 扩展入口是 pi-ssh/index.ts，ssh2 transport 与 SFTP 实现在 pi-ssh/src/ssh2-transport.ts，有界自适应远程搜索位于 pi-ssh/src/remote-search.ts，AES-GCM vault 位于 pi-ssh/src/vault.ts，选择性导入入口是根 configure.sh ssh 与 pi-ssh/scripts/ssh-config.mjs，权限桥接位于 pi-ssh/permission-integration.ts，测试保留在 pi-ssh/test/，来源记录是 pi-ssh/UPSTREAM.md。
• 同步上游必须从明确 tag/commit 移植并保留 LICENSE、作者和来源；参考其他实现时记录明确 commit，不得导入嵌套 .git、node_modules 或构建产物。
• 运行时必须保持纯 ssh2，不得回退到系统 OpenSSH、sshpass、SSH_ASKPASS 或 ControlMaster；认证可使用密码、私钥文件或 ssh2 直连的 SSH Agent socket（包括 1Password），Agent 模式只保存 socket 路径且不得导出私钥。OpenSSH 只允许由显式配置脚本通过 ssh -G 解析用户选中的 alias，已导入配置变化必须由用户显式更新。第一版遇到 ProxyJump / ProxyCommand 必须拒绝，不能静默忽略。
• 根包必须直接固定安装 ssh2@1.17.0 与配置 CLI 所需的 jiti@2.7.0，因为 packed bundle 直接加载其内置 pi-ssh/ 源码；ssh2 与 cpu-features 的 install scripts 只构建可选加速绑定，当前不得加入根 allowScripts，纯 JavaScript fallback 必须可运行。
• SSH vault 使用同目录独立随机 key 和 AES-256-GCM 整体加密，目录/文件在 POSIX 上必须保持 700 / 600；该设计只防止误看或单独泄漏密文，不防同一用户读取 key。密码、私钥 passphrase、私钥内容、Agent 提供的签名材料、vault key 与解密明文不得进入命令参数、日志、Pi session、权限证据或明文临时文件。
• 已导入主机必须固定 SHA256 Host Key；不匹配时 fail closed。私钥认证只保存文件路径，Agent 认证只保存 socket 路径，均不得复制或导出私钥内容；文件工具使用 SFTP，写入优先临时文件与原子 rename，远端断线不得自动重放命令。
• ssh_connect 是唯一运行时连接入口，只接受 vault 中已导入的 host ID 与可选绝对/~/ remote cwd，并必须默认 ask 后进入 AutoReview；它必须声明 sequential execution mode 且支持取消，Agent 必须作为独立步骤调用并等待成功后才能发出依赖连接的其他 ssh_* 调用，避免连接建立或替换与远端操作重叠。未知 host ID 只可有界列出已导入 ID，不得泄露 endpoint 或凭据。不得注册 /ssh、--ssh、session resume 自动重连或把用户 ! 命令切换到远端。用户未在直接请求中明确服务器和具体远端任务时不得推断、替换或连接主机；新连接替换旧连接，会话结束自动断开。
• ssh_find / ssh_grep 必须在已授权工具调用内部按 fd/fdfind → git ls-files → find 与 rg → git grep → find+grep 顺序检测服务器现有能力，不安装或上传远端二进制；搜索目标必须作为绝对参数与执行 cwd 分离，搜索进程始终从当前已确认 remoteCwd 启动，单文件 ssh_grep 目标不得被当作目录执行 cd。输入必须 shell-safe，结果数量/单行/总捕获必须有界并显式报告 backend 与 truncated；30 秒超时必须报告解析后的 root 并提示先缩小范围。RTK 不得处理这两个搜索工具的结果。
• ssh_cd、ssh_read、ssh_write、ssh_edit、ssh_find、ssh_grep 的远端路径不能按本机路径执行默认 input.path gate；必须通过公共 PermissionsService 注册显式 extractor 关闭本机路径推断，并保持六个工具的默认策略为 ask。权限预览必须依据远端 remoteCwd / remoteHome 解析相对路径与 ~/，同时显示请求值和解析后的绝对远端路径。
• SSH transport 在会话中持久，但不得维护隐藏的交互式 Shell/PTY 状态；ssh_bash 每次调用必须从连接当前 remoteCwd 启动独立的非交互 Bash，必须忽略 Pi 本地 Bash factory 的 cwd 与 PI_* 会话环境。跨调用的工作区切换只能通过受复核且声明 sequential execution mode 的 ssh_cd 显式验证并更新连接状态；Agent 必须把它作为独立步骤调用并等待成功后，才可发出依赖新目录的远端工具调用。普通命令中的 cd 只可作为当次命令的临时目录变化，cd、export、alias 或函数不得被伪装为持久状态。
• 远端 HOME/cwd 探测与 ssh_cd 验证必须使用可取消、输出有界、随机标记 framing 的固定命令，只接受唯一绝对 POSIX 路径；banner、畸形/多行输出、超限、超时或取消时不得更新状态。独立 exec channel 最多并发 4 路，排队调用必须可立即取消；共享 SFTP 操作继续串行。
• ssh_bash 必须在唯一全局 policy 的 shellTools 中映射 commandArgument: "command" 并设置 decisionFloor: "ask"，复用 Bash 命令拆分、硬拒绝、风险 ask 和 authorizer chain；不得新增第二个并行 tool_call 审批层。
• RTK 只把 ssh_bash 当作 Bash 输出别名执行 ANSI 清理、测试/构建/Git/Lint 聚合与兜底截断；不得对远端命令启用 RTK rewrite，也不得处理 ssh_read、ssh_find 或 ssh_grep 返回。
• SSH 工具的权限预览必须包含连接请求或当前远端的 host id、target、port、remote cwd 与有界操作摘要；连接预览只解密本地 vault 以提取非秘密目标字段，绝不包含凭据，远端 shell 的完整命令继续由 Bash payload 单独提供。权限服务缺失或注册失败时必须 fail-safe，不得转为无提示自动允许。
• pi-ssh 只用于从本地项目显式操作服务器，不得自动探测、读取或向系统提示词注入远端 AGENTS.md、CLAUDE.md 或其他项目说明；远端内容只能由明确且已授权的 ssh_* 工具调用获取。
• 修改 SSH transport、vault、导入、权限集成或加载入口后至少运行 pi-ssh 包内 npm test、根脚本语法与 mock 配置测试、pi-permission-system 的 npm run typecheck / npm run test / npm run build、根扩展联合加载和实际 packed tarball 隔离安装验证。未经明确要求不得连接真实服务器或把真实密码写入测试。
• 根加载顺序必须保持 pi-permission-system → pi-ssh → pi-chrome → system-prompt-cover → tool-routing → pi-tool-search，确保内置 authorizer 与权限服务由同一扩展先注册/发布、SSH 桥接随后安装、Chrome 工具可在授权后进入目录、系统提示词封面在 tool-routing 压平提示词之前改写开头，且 Tool Search 最后收集完整工具目录。

extensions/system-prompt-cover.ts 开发约定

• 扩展入口是 extensions/system-prompt-cover.ts；纯 helper（spliceCover / readCoverFile / resolveCoverPath / COVER_FILE_NAME）位于 extensions/system-prompt-cover-config.ts 以便 node --test 单测；组合包权威源是 config/system-prompt-cover.md，扩展运行时直接读取已安装组合包内文件，不经任何脚本部署。
• 只能使用 Pi 的 forceSystemPrompt 投影路径（before_agent_start 返回 { systemPrompt }）配合文本拼接来保持分区顺序；不得改用 customPrompt 选项。后者会抑制 tools / rules / docs 三个分区，而回填只能追加到末尾，无法恢复原顺序。
• 不得在 handler 中写 customPrompt 或依赖其生效：forceSystemPrompt 优先级更高，二者同时存在时 customPrompt 会被静默忽略而不报错。
• 分割边界必须是独占一行的裸标签（带 backreference 同名闭合），不能匹配带属性的标签：<project_instructions path="..."> 嵌套在 <project_context> 内，只有裸标签才是分区边界。
• 封面文件是已安装组合包内的 config/system-prompt-cover.md，不得改名为 SYSTEM.md 或移到 agent 根目录：后者会被 Pi 先当成 customPrompt 读入，封面扩展拿到的提示词会缺少可回填的分区。
• 文件缺失、不可读或为空白时必须静默 no-op，保持 Pi 默认封面；不得写入空 preamble，也不得因读取失败阻止其他扩展加载。
• 封面文件随组合包发布，pi install / pi update 后即就位，无需任何部署 helper；对已安装副本的临时修改由 pi update 覆盖。
• 修改 spliceCover 语义、注册顺序或封面路径后，必须运行 node --test tests/system-prompt-cover.test.ts、node --test tests/bundle-config.test.ts、node --test tests/extension-load.test.ts，并确认 npm pack --dry-run 包含 config/system-prompt-cover.md。

pi-ask-user 开发约定

• 扩展入口是 pi-ask-user/index.ts，schema、归一化、TUI、RPC extension UI bridge 与工具注册位于 pi-ask-user/src/，纯 helper 测试保留在 pi-ask-user/test/。
• 工具名必须保持 ask_user_question，并由 Tool Search 的独立 user-interaction 组按需加载；根加载顺序必须位于 pi-tool-search 之前。
• 参数必须有界并在运行时复核 question id、题型、选项和值的有效性；TUI 必须顺序执行、监听 abort、按 width 失效缓存，并把外层 Focusable 状态传播给内嵌 Editor；RPC 必须只依赖 Pi 标准 select / input extension UI、逐题执行、传递 abort signal，并把 dismiss/abort 归一化为取消。
• 成功结果的 details 必须保持 version、cancelled: false 与非空 answers，每个 answer 必须提供原始 question 和用户 answer；取消结果不得成为权限授权证据。修改结果结构时同步验证 pi-permission-system/src/auto-review/transcript.ts 解析。
• 同步上游示例时从明确 commit 移植并保留 LICENSE、UPSTREAM.md 与本地整合差异；不得恢复 /qna、重复的单题工具或多个扩展入口。
• 修改后至少运行包内 npm test / npm run check、Tool Search 的 typecheck/test/build、AutoReview transcript 测试、根扩展联合加载和 packed tarball 隔离安装验证。

pi-tool-search 开发约定

• 扩展入口是 pi-tool-search/extensions/index.ts，组合包权威分组位于 pi-tool-search/extensions/bundle-groups.ts，目录生成/校验/缓存位于 pi-tool-search/extensions/catalog.ts，配置读取与路径解析位于 pi-tool-search/extensions/config.ts（直接读取组合包 config/tool-search.json；目录缓存仍在 <agentDir>/my-pi/tool-search/catalog-v1.json），测试保留在 pi-tool-search/test/。
• 同步上游必须记录明确 tag/commit，保留 README、CHANGELOG、文档、作者和许可证说明；不得导入上游 .pi、嵌套 .git、node_modules 或构建产物。
• 修改 Tool Card 提示词、目录校验、分组、缓存、active-tool/LRU 生命周期、配置或工具结果时，必须同步更新包内 README、当前动态加载文档、CHANGELOG 和测试。
• 新增、删除或重命名组合包暴露工具时必须同步维护 BUNDLE_GROUP_DEFINITIONS；日常只读工具、provider 工具和高风险管理工具不得因名称相似而混入同一大组，根验证应确认标准组合包没有落入 unknown-tools 路径。
• 生成目录只能让模型提供摘要、使用边界、关键词与分组；工具名、参数和原始 schema 必须来自宿主。校验或模型调用失败必须 fail-safe 到确定性目录，缓存不得写入仓库或放宽权限。
• 根包必须通过 file:./pi-tool-search 提供本地依赖并直接加载仓库源码，不得同时安装或加载 npm pi-tool-search 实现。

验证

组合包依赖或加载入口变化时，至少验证根 npm install 幂等、锁文件有效，以及全部扩展可在隔离的临时 Pi agent 目录加载。权限配置变化时使用仓库内固定快照的 pi-permission-system schema 校验，并验证扩展运行时解析到的 config/ 路径确实位于组合包内。

安装、升级、卸载、搜索或 SSH 配置脚本变化时，至少运行 sh -n install.sh、sh -n update.sh、sh -n uninstall.sh、sh -n configure.sh、sh -n scripts/lib.sh 和 ShellCheck，并核对脚本仍具有可执行权限、仍包含在根 package.json 的 files 中、README 描述与实际流程一致。搜索配置测试只能使用虚拟 key 和隔离 HOME；SSH 配置测试必须使用隔离 HOME、虚拟凭据与 mock transport，不得连接真实服务器或把真实密码写入测试输出。涉及真实 pi install、pi update、pi remove、Homebrew、远程安装器、Git 克隆、真实 SSH 连接或真实用户终端配置的端到端验证属于外部写操作，未经明确要求不得执行；可以使用隔离的临时 HOME 和 mock 命令验证分支行为。

记忆扩展变化必须额外验证：pi-hermes-memory 在隔离临时 Pi agent 目录中可加载且注册 6 个工具、pi.extensions 中排在 pi-compaction 之前、Tool Search 目录把六个工具归入 memory-recall / memory-management 且全部常驻、权限策略默认 allow、better-sqlite3@13 嵌套安装与根 12.11.1 并存。不得在测试中连接真实数据库或修改真实 ~/.pi/agent/ 记忆数据。

在 pi-permission-system/ 内至少运行 npm run typecheck、npm run test 和 npm run build。涉及内置 AutoReview 或硬防御时，还要验证 authorizer 对普通工具与 path 的 allow / deny / defer、hard-guard precedence、未配置/未知 provider 或模型时的 defer 与一次性提示，以及 owner-only 持久化。

在 pi-notify/ 内至少运行 npm run typecheck、npm run test 和 npm pack --dry-run --json；涉及加载入口或 lifecycle 时还要运行根扩展联合加载测试和实际 packed tarball 的隔离安装验证。

在 pi-compaction/ 内至少运行 npm test、npm run check 和 npm pack --dry-run --json；涉及依赖、加载入口、context writer、footer 或 observer 时还要验证根 npm install 幂等、锁文件仅包含预期本地 link 变化、根扩展联合加载、性能回归，以及实际 packed 根 tarball 的隔离安装/加载。

在 pi-tool-search/ 内至少运行 npm run typecheck、npm run test 和 npm run build；涉及加载入口或 active-tool 行为时还要运行根扩展联合加载测试和实际 packed tarball 的隔离安装验证。

在 pi-rtk-optimizer/ 内按改动范围选择最小充分验证：

• npm run build：TypeScript 转译检查。
• npm run typecheck：完整类型检查。
• npm run test：运行 Bun 测试。
• npm run check：类型、测试和打包检查的完整验证。

若环境缺少依赖或未执行某项验证，交付时明确说明，不以静态检查代替运行结果。

项目记忆（pi-hermes-memory）

持久记忆由 pi-hermes-memory 提供，默认 policy-only 模式：system prompt 只注入 <memory-policy> 指令，不注入记忆正文。

• 任务开始时若可能依赖历史上下文，先调用 memory_search；需要历史对话原话时用 session_search。
• 发现值得持久化的事实、偏好、约定、纠正或失败教训时，主动用 memory_add 保存，不必等用户开口；更新或删除用 memory_replace / memory_remove。
• 完成需要反复试错、或用户教了具体流程的任务后，用 skill_manage 把可复用流程沉淀为 skill（scope: "global" 跨项目，scope: "project" 本项目）。
• 记忆与 skill 数据位于 ~/.pi/agent/pi-hermes-memory/ 与 ~/.pi/agent/projects-memory/，属于用户数据，不得提交、自动迁移或删除。