my-pi/AGENTS.md

仓库说明

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

当前扩展

• pi-rtk-optimizer/：默认只负责非搜索工具输出压缩；RTK 命令改写为可选能力。
• 上游来源：https://github.com/MasuRii/pi-rtk-optimizer
• 初始导入快照：d155d253cb2f1358e34e717d47a82ebccb08cb8e（2026-07-03，0.9.0）。
• 该目录已纳入本仓库直接维护，不是 submodule，也不保留嵌套 .git。
• extensions/fff-override.ts：强制使用 FFF 官方 override 模式，统一接管 find、grep、multi_grep 和 FFF 的 @ 补全；显式 CLI flag 仍遵循 FFF 官方优先级。
• context-mode：加载上游 Pi adapter 与 skills，提供 ctx_* 工具、隔离式大输出处理和会话连续性。
• extensions/codegraph.ts：通过隔离的 pi-mcp-adapter 配置连接机器现有的 codegraph serve --mcp，只暴露 codegraph_explore。
• extensions/permission-system.ts：在权限扩展注册前，将 config/pi-permission-system.json 同步为全局权威配置。
• extensions/lsp.ts：部署 Kotlin/JDT LS 全局配置并加载 pi-lsp。
• extensions/auto-permissions.ts：部署 contextual Bash guardian 规则并加载 pi-auto-permissions。
• pi-lsp@0.1.7：提供声明式 LSP 接入；组合包配置 kotlin-lsp --stdio 与 jdtls。
• pi-hermes-memory@0.9.6：提供持久记忆、会话搜索、后台学习和 secret scanning，默认使用 policy-only 模式。
• @ogulcancelik/pi-auto-permissions@0.1.3：根据当前对话复核配置命中的 Bash 命令，不是全工具审批层。
• @ogulcancelik/pi-codex-compaction@0.1.3：为 openai-codex 提供原生远程 compaction，默认阈值为 90%。
• 根包还固定安装 pi-context-view、@firstpick/pi-extension-codex-fast-mode 和 @gotgenes/pi-permission-system。

当前职责与默认行为

• FFF 独占字面搜索。RTK 不得处理 grep、find、multi_grep 的调用或结果，也不得通过默认命令改写接管 rg、grep、find、fd。
• RTK 默认只压缩非搜索输出，包括 Bash ANSI 清理、测试聚合、构建过滤、Git 压缩和 Lint 聚合，并记录压缩统计。
• commandRewritingEnabled 默认 false。默认安装不依赖系统 rtk CLI；只有用户主动开启命令改写时才需要 rtk rewrite。
• readCompaction.enabled、sourceCodeFilteringEnabled 和 smartTruncate.enabled 当前均默认 false，源码读取保持原样。未经用户明确决定，不因节省上下文而改变这些默认值。
• 若以后开启 read 压缩，优先考虑 readCompaction + smartTruncate，源码过滤仍独立评估；必须保留精确 offset/limit 读取、短文件和行锚点的完整性。
• Context Mode 负责避免批量读取、命令研究和网页原始内容直接撑大上下文；FFF 仍负责精确字面搜索，RTK 仍处理未走 Context Mode 的普通输出。
• CodeGraph 只配置 Pi 到外部 codegraph 命令的 MCP 连接。组合包不安装 CodeGraph，不执行 codegraph init，不创建或管理 .codegraph/，也不改动索引、更新或遥测设置。
• CodeGraph MCP 使用 keep-alive 并只直接暴露 codegraph_explore；命令缺失、项目未初始化或连接失败时不得阻止其他扩展加载。
• pi-context-view 只观察上下文占用，不参与压缩策略。
• Codex fast mode 只为符合条件的 openai-codex-responses 请求设置 priority service tier，由 /fast-mode 在会话内控制。
• 权限策略默认允许常规工具，允许 FFF 工具；拒绝 Bash 直搜和敏感凭据路径，外部目录、文件/系统/网络高风险操作与普通 MCP 调用由 pi-permission-system 询问。
• pi-auto-permissions 不是 Codex 式全工具审批层：它只监听 bash 及名称以 .bash 结尾的工具，只复核自身 config.json 中正则命中的命令；它不处理 read、write、edit、MCP、Skill、路径或外部目录权限，也不接收或批准 pi-permission-system 产生的 ask。
• 两个权限扩展是彼此独立的 tool_call gate。若同一 Bash 命令同时命中 Auto Permissions 规则和 pi-permission-system 的 ask，会依次经过两层审批，而不是把旧系统的请求转交给 guardian；配置时不得为同一 Bash 类别重复设置审批。
• 当前只把 Git 非只读操作和包管理类 Bash 命令交给 pi-auto-permissions 根据用户上下文复核。低风险操作可自动允许；中风险操作仅在用户明确授权目标与约束时自动允许；高风险操作即使已有概括授权也必须回到用户确认。文件/系统/网络高风险操作继续由现有解析能力更强的 pi-permission-system 处理。
• 将 Auto Permissions 规则配置为 .* 最多只能复核所有 Bash 命令，不能覆盖其他工具，并会为普通 Bash 调用增加额外模型请求、延迟和成本。若未来目标是让现有所有 ask 先经模型裁决，必须另行实现 pi-permission-system authorizer 集成，不能仅靠该 npm 包配置实现。
• pi-lsp 使用组合包部署的 kotlin-lsp --stdio 与 jdtls 配置，但不安装这两个系统可执行文件。
• Codex 远程压缩只对 openai-codex 生效，默认在 turn boundary 达到 90% 时触发；Hermes Memory 默认使用 policy-only 模式。

修改边界

• 优先在目标扩展目录内完成改动；不要让一个扩展依赖另一个扩展的未公开内部实现。
• 保留原项目的 LICENSE、版权信息和必要的来源说明。
• 扩展运行目录中的 config.json、日志、构建产物、覆盖率目录和依赖目录属于本地状态，不应提交；config/pi-permission-system.json 是组合包的权威源配置，必须提交并维护。
• 外部 Pi 扩展依赖必须在根 package.json 中使用精确版本，并更新根 package-lock.json；不要用仓库级 .pi/settings.json 代替组合包依赖。
• 需要原生构建的依赖只按锁定版本加入根 allowScripts；当前仅允许 Hermes Memory 所需的 better-sqlite3，不得批量批准其他 install scripts。
• Pi 核心包只作为宿主 peer dependencies，不得在组合包内再安装或打包一套 Pi runtime；保留根 .npmrc 的 peer 安装策略。
• 上游仅作为参考来源。同步上游改动时先核对本仓库已有修改，再按明确范围移植；不要直接覆盖本地实现。
• 未经明确要求，不执行发布、提交、推送或安装到用户 Pi 运行目录等外部写操作。

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 示例和相关测试。
• 工具输出压缩可能损失证据。排障和审计相关改动应优先保证原始输出可恢复，并覆盖锚点完整性和截断边界。

验证

组合包依赖或加载入口变化时，至少验证根 npm install 幂等、锁文件有效，以及全部扩展可在隔离的临时 Pi agent 目录加载。权限配置变化时使用当前固定版本的 pi-permission-system schema 校验，并验证包装入口部署后的文件与仓库源配置一致。

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

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

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