my-pi/AGENTS.md

仓库说明

本仓库维护可通过一次 pi install 部署的个人 Pi 扩展组合包。根 package.json 是唯一的组合包安装入口；install.sh / update.sh / uninstall.sh 只是 pi install / pi update / pi remove 的便捷包装，不形成第二套部署机制。仓库 config/ 是组合包唯一配置来源，扩展运行时直接读取已安装组合包内的文件，不复制、不播种、不迁移；仅外部 npm 扩展固定读取 agent 目录路径时（当前 hashline.json、lsp.json）才允许加载时从 config/ 覆盖写入。每个自维护扩展使用独立顶层目录；各扩展的维护约定见各自目录的 AGENTS.md（extensions/ 下 wrapper 见 extensions/AGENTS.md），上游来源记录见各自 UPSTREAM.md（中文维护）。

扩展清单

目录 / 文件	职责
pi-rtk-optimizer/	默认只压缩非搜索工具输出；RTK 命令改写为可选能力
pi-ssh/	纯 ssh2 持久远程连接、远端工作区、SFTP 与有界自适应搜索
pi-permission-system/	工具/路径/MCP/Skill/子代理转发权限基线，内置 AutoReview 与人工 defer 兜底
pi-subagents/	Claude Code 风格隔离子 Agent：后台执行、steering、resume、嵌套与自定义 Agent
pi-web-search/	统一 web_search / web_fetch，内部路由 Tavily/Exa/Keenable，对模型隐藏厂商
pi-chrome/	显式授权接入已登录 Chrome Profile，授权后提供 21 个 chrome_* 工具
pi-tool-search/	校验过的工具目录 + 固定工具 + 有界动态组 LRU，按需加载原始 schema
pi-ask-user/	ask_user_question：模型主动发起的单题/多题/选择/文本提问（TUI + RPC）
pi-worktree/	/wt（/worktree）git worktree 斜杠命令，不注册模型工具
pi-hermes-memory/	Hermes 风格持久记忆：policy-only 注入、六记忆工具、skill_manage
pi-minimal-footer/	紧凑 footer：上下文仪表、订阅用量条、扩展状态
pi-notify/	Kitty OSC 99 完成与权限确认通知，精确聚焦来源窗口
pi-compaction/	压力触发的观察遮蔽（Pi context_edit）、阈值整段摘要、effective token、native compaction
pi-overflow/	新工具结果统一截断：超阈值原文落盘 + 有界视图 + overflow_query
extensions/fff-override.ts	FFF override 模式接管 find/grep 与 @ 补全，multi_grep 按上游保持关闭
extensions/bash-override.ts	用 Pi 的 createBashToolDefinition 重新注册 bash，仅替换模型可见描述（追加 tools.jsonc descriptionAppend）；执行逻辑、输出结构、codemode 说明不变
extensions/codegraph.ts	原生 codegraph_explore，自有 stdio JSON-RPC 直连 codegraph serve（codegraph-client.ts）
extensions/hashline.ts	部署 config/pi-hashline-edit.json 后加载 pi-hashline-edit 覆盖 read/edit（hashline-config.ts）
extensions/permission-system.ts	直接加载仓库内 pi-permission-system/src/index.ts
extensions/lsp.ts	物化包内 typescript-language-server、部署 LSP 配置并加载 pi-lsp（lsp-config.ts）
extensions/prompt-guard.ts	第三方扩展代理 API：丢弃 systemPrompt 返回、应用 tools.jsonc description 覆盖、context 过滤器
extensions/subagents.ts	pi-subagents 加载 wrapper，注入权威 permission-system.ts 为 mandatory extension
extensions/context-view.ts	只读 /context observer，消费 pi-compaction projection metrics
extensions/system-prompt.ts	唯一系统提示词出口（system-prompt-config.ts 为纯 helper），排在最后
configure.sh + scripts/	交互式写入搜索 key（auth.json）与 SSH 主机导入
install.sh / update.sh / uninstall.sh	pi install/update/remove 包装 + 逐项询问的机器级依赖与终端配置

全局硬规则

• 系统提示词单一所有权：extensions/system-prompt.ts 排在 pi.extensions 最后，是唯一允许在 before_agent_start 返回 systemPrompt 的扩展；其他扩展只能经 systemPromptOptions.sections.<name> 贡献分区，第三方扩展必须经 extensions/ wrapper + prompt-guard.ts 加载，新增工具必须在 config/prompt/tools.jsonc 登记。宿主传入 customPrompt（子 Agent / SYSTEM.md）时不覆盖其开场白；子 Agent 有独立提示词画像 config/prompt/subagent/（preamble + 内置 Agent），判定规则与路由 scope/subagentExclude 细则见 extensions/AGENTS.md。
• 加载顺序：pi-overflow/capture.ts 必须排在最前（先于 RTK 等结果改写扩展暂存原文），permission-system → subagents → pi-ssh → pi-chrome → pi-tool-search → pi-overflow/index.ts → system-prompt（最后）；pi-hermes-memory 必须排在 pi-compaction 之前（session_before_compact 取消语义），pi-compaction 在 pi-minimal-footer 与 context-view 之前。
• 依赖：外部依赖在根 package.json 用精确版本，自维护扩展一律 file: 本地依赖并更新锁文件；Pi 核心包只作 optional host peer，根 runtime deps 不含 Pi runtime，任何目录不得再装一套 Pi runtime；各子包用于测试的 @earendil-works/* devDependencies 一律写 "latest"，经 scripts/update-pi-devdeps.sh 统一刷新；原生构建依赖只按锁定版本进根 allowScripts（当前无放行项；pi-hermes-memory 的 better-sqlite3@13 用包内 N-API 预编译，不经根 allowScripts）。不要用仓库级 .pi/settings.json 代替组合包依赖。根 files 对子包按运行时子路径白名单列出（源码、package.json、README/LICENSE/CHANGELOG/UPSTREAM），不得整目录列入，以免打入嵌套 node_modules、dist 和测试；由 tests/package-files.test.ts 守护。
• 配置：config/ 下全部文件是权威源、必须提交；不得读写 settings.json 自定义段、agent 目录独立配置文件或以环境变量作持久默认值；config/ 只放机器无关值，路径类默认值在代码中运行时计算。<agentDir>/my-pi/ 只放可丢弃运行时状态（日志、缓存），连同旧 extensions/pi-permission-system/ 残留、构建产物与依赖目录都不提交；用户数据（记忆、会话、auth.json 等）不属于组合包配置，也不得放入该目录。
• 组合包不加载任何 MCP adapter/SDK：Exa 与 CodeGraph 均用自有直连客户端。
• 导入/同步上游：只从官方 Git 仓库的明确 tag/commit 取源码快照，禁止 npm tarball/缓存/node_modules/dist/ 等预编译产物作导入源；保留上游 LICENSE、作者、测试与来源说明，移除嵌套 .git、.pi 状态、node_modules 与构建产物；同步前先核对本地改动再按明确范围移植，不得整体覆盖。各目录的维护约定见 AGENTS.md，每个自维护目录必须有中文 UPSTREAM.md 记录来源，上游原文文件不翻译不改写。
• 脚本：install.sh、update.sh、uninstall.sh、configure.sh 与 scripts/lib.sh 保持 POSIX sh 兼容并留在 files 中，行为变化同步 README；安装默认来源 git:git@bitbucket.org:siakitem/my-pi.git，可由 PI_PACKAGE_SOURCE 覆盖（update/uninstall 同规则）；组合包安装失败立即停止，机器级依赖失败继续检查其余项并最终返回非零。
• 安装/升级纪律：机器级依赖与终端配置逐项询问、默认拒绝；update.sh 只升级已安装项、缺失项跳过，组件升级先比较本地与远端版本、一致不重装，成功升级后把 git 来源的受管 checkout git reset --hard 还原到已发布版本（本地路径来源不 reset、不 git clean）；update.sh 先 pi update --self 同步 Pi 最新 release（版本比较由 Pi 自身完成，失败记录后继续），再升级组合包；组合包 pi update 失败 fail-fast——Pi 1.3.0 会据 .pi-update-incomplete 标记在下次 update 自愈，不做预清理或人工恢复。pi update 只在有新版本时整体覆盖已安装副本（含 config/），不逐字段迁移本机改动；需长期保留的自定义必须改仓库 config/ 源文件。.zshrc 只改 # >>> my-pi:<id> >>> 受管块并先建时间戳备份，不覆盖用户 ~/.p10k.zsh；卸载不得删除用户记忆数据（.pi/agent/pi-hermes-memory/、projects-memory/、.hippo/）或共享机器级工具。
• 未经明确要求不执行发布、提交、推送、运行安装/卸载脚本、安装到用户 Pi 目录等外部写操作；凭据不进入命令参数、日志、会话或仓库（auth.json 权限 600、不提交）。
• 优先在目标扩展目录内完成改动；保留原项目 LICENSE 与版权；不让一个扩展依赖另一个扩展的未公开内部实现。

验证

• 组合包依赖或加载入口变化：验证根 npm install 幂等、锁文件有效、全部扩展可在隔离临时 Pi agent 目录加载（见 tests/extension-load.test.ts）；权限配置变化用包内固定 schema 校验，并确认运行时 config/ 路径确实位于组合包内。
• 脚本变化：sh -n 每个脚本 + ShellCheck，并确认可执行权限、files 包含与 README 一致；搜索/SSH 配置测试只用虚拟凭据、隔离 HOME 与 mock transport，不连真实服务器。
• 真实 pi install/update/remove、Homebrew、远程安装器、Git 克隆、真实 SSH、真实终端配置的端到端验证属外部写操作，未经要求不执行；用隔离 HOME + mock 验证分支行为。
• 根目录测试：node --test 'tests/*.test.ts'、git diff --check；各扩展目录的验证命令见其 AGENTS.md。未能运行的验证交付时明确说明，不以静态检查代替运行结果。

项目记忆（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/，属于用户数据，不得提交、自动迁移或删除。