admin/my-pi
1
0
Fork 0
mirror of https://bitbucket.org/siakitem/my-pi.git synced 2026-08-28 07:23:06 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
a690d147d1c67adde41cd4872e6e41e743984ed3
my-pi/README.md
T

9.0 KiB
Raw Blame History

my-pi

个人维护的 Pi 扩展组合包。安装一次即可加载并配置：

  • @ff-labs/pi-fff@0.10.5：使用官方 override 模式接管 find、grep 和 multi_grep。
  • 本仓库维护的 pi-rtk-optimizer：只处理 Bash/read 等输出压缩，默认不改写命令，也不处理搜索工具结果。
  • context-mode@1.0.169：通过 Pi adapter 提供 ctx_* 工具、上下文隔离和会话连续性。
  • pi-mcp-adapter@2.26.0：只用于把机器现有的 CodeGraph MCP Server 接入为 codegraph_explore。
  • pi-context-view@0.4.2：查看上下文占用。
  • @firstpick/pi-extension-codex-fast-mode@0.1.1：为 Codex provider 提供会话级 /fast-mode。
  • pi-lsp@0.1.7：为 Kotlin 和 Java 提供 LSP 诊断、跳转与符号工具。
  • pi-hermes-memory@0.9.6：提供持久记忆、会话搜索和 secret scanning。
  • @ogulcancelik/pi-codex-compaction@0.1.3：为 openai-codex 提供原生远程压缩。
  • @ogulcancelik/pi-auto-permissions@0.1.3：按当前对话自动复核受控 Bash 操作。
  • @gotgenes/pi-permission-system@26.2.1：负责工具、路径、MCP、硬拒绝和兜底权限基线。

安装与卸载

推荐从仓库检出目录运行安装脚本：

./install.sh

脚本会先执行：

pi install git:git@bitbucket.org:siakitem/my-pi.git

安装组合包成功后，脚本会检查 codegraph、kotlin-lsp、Java 21+ 和 jdtls。缺失的 依赖会逐项显示 [y/N] 选项，仅在用户明确选择 Y 后安装。Kotlin、Java 和 JDT LS 的 自动安装使用 Homebrew；如果机器没有 Homebrew，脚本会保留组合包安装结果并给出提示。 rtk 只供默认关闭的命令改写使用，因此不会作为必装依赖检查。

也可以绕过脚本，直接运行上面的 pi install 命令，此时机器级 CLI 不会被检查。

卸载组合包：

./uninstall.sh

卸载脚本只调用 pi remove，不会删除 CodeGraph、Kotlin LSP、JDT LS 或 Java，因为这些 机器级工具可能仍被其他项目使用。两个脚本都可通过 PI_PACKAGE_SOURCE 覆盖默认包源， 例如在本地检出中测试：

PI_PACKAGE_SOURCE="$PWD" ./install.sh

根 package.json 使用精确版本，package-lock.json 固定完整依赖树。不要再用项目级 .pi/settings.json 重复安装这些扩展，否则同一扩展可能被加载两次。

Hermes Memory 的 SQLite search 依赖 better-sqlite3 原生模块；根包只在 allowScripts 中 精确放行当前锁定版本的构建脚本。若升级 Hermes 或 better-sqlite3，必须同步核对并更新该精确 版本，不能把其他依赖的 install scripts 一并放行。

默认配置不需要系统 rtk CLI。只有以后在 /rtk 中主动开启 RTK command rewriting 时，才需要另外安装 rtk 可执行文件。

CodeGraph 本体不由组合包安装。需要使用 CodeGraph 的机器应自行确保 codegraph 在 启动 Pi 的 PATH 中，并在目标项目执行过 codegraph init。组合包不会创建或维护 .codegraph/，也不会修改 CodeGraph 的索引、更新或遥测设置。

组合行为

搜索归 FFF

extensions/fff-override.ts 强制设置 FFF 官方的 PI_FFF_MODE=override（显式传入 --fff-mode 仍按 FFF 官方优先级覆盖它）。FFF 替换 Pi 的 find 和 grep，并提供 multi_grep；RTK 对所有 grep 工具结果直接跳过， 也默认关闭 Bash 命令改写，因此不会把 rg、grep、find 或 fd 改写到 RTK。

输出压缩归 RTK

RTK 保留 Bash、read、build、test、lint 和 Git 输出压缩。默认 read 的有损压缩 仍关闭；可用 /rtk 查看或调整。旧机器已有的 RTK 配置若没有 commandRewritingEnabled 字段，也会按 false 归一化，不需要迁移配置。

大输出归 Context Mode

Context Mode 直接加载 npm 包内置的 Pi adapter 和 skills，不需要额外写入 ~/.pi/agent/mcp.json，也不需要全局安装 context-mode 命令。它提供 ctx_* 工具， 将批量读取、命令研究和网页内容先在隔离进程中处理，再把收敛后的结果送入上下文。

FFF 仍负责精确字面搜索；RTK 继续压缩未走 Context Mode 的 Bash、build、test、lint 和 Git 输出。Context Mode 不替换这两个扩展的现有配置。

CodeGraph 只负责连接

extensions/codegraph.ts 使用隔离的 pi-mcp-adapter 配置启动 codegraph serve --mcp，不会读取或覆盖用户已有的 MCP 配置。连接采用 keep-alive，并只把官方当前主工具 codegraph_explore 作为同名 Pi 工具暴露； CodeGraph 的文件 watcher 由该 MCP 进程自身维护。

若机器没有 codegraph，或当前项目尚未建立索引，CodeGraph 会报告连接/初始化错误， 其他扩展仍可正常工作。安装与索引状态可在机器上自行检查：

codegraph --version
codegraph status

权限基线自动部署

extensions/permission-system.ts 在权限扩展注册前，把仓库中的 config/pi-permission-system.json 同步到 Pi agent 目录。仓库文件是权威配置；直接在 运行目录通过 UI 修改的策略会在下次加载组合包时被覆盖，长期调整应提交到本仓库。

当前策略按类别划分：

  • 默认工具：默认允许，避免常规编码操作反复确认；FFF 的 grep、find、 multi_grep 明确允许。
  • 搜索边界：直接通过 Bash 调用 rg、grep、find、fd、git grep 拒绝，统一走 FFF。
  • 路径与凭据：外部目录询问；环境文件、SSH/GPG、云凭据、Keychain 和 Pi 认证文件拒绝； .env.example 作为无密钥模板允许。
  • Git：状态、diff、日志、对象查看等只读命令允许；其他 Git 命令交给 Auto Permissions。
  • Bash 变更操作：Git 非只读操作和包管理操作交给 Auto Permissions；文件变更、系统操作、 网络访问和环境导出继续由权限基线询问。
  • MCP 与 Skill：列举 MCP 状态允许，调用其他 MCP 工具询问；本地 Skill 加载允许。

permissionReviewLog 已开启，后续可依据真实命中记录继续收敛规则。

Auto Permissions 与权限基线的边界

extensions/auto-permissions.ts 会先部署 config/pi-auto-permissions.json，再注册 contextual guardian。它只复核配置命中的 Bash 命令，并根据当前对话返回自动允许、要求修正或请求用户确认。

两个权限扩展是并列的 tool_call gate，不存在“pi-permission-system 的 ask 自动转发给 Auto Permissions”的机制。若同一命令在两边都配置为询问，会产生两层独立审批。因此组合包 不再在旧权限配置中重复声明 Git 非只读操作与包管理的 Bash ask 规则；旧扩展仍独占以下边界：

  • deny：Bash 直搜、敏感凭据路径等硬拒绝不会被 guardian 绕过。
  • ask：外部目录、.git/* 路径、文件/系统/网络/环境操作和普通 MCP 调用仍走旧权限 UI。
  • Auto Permissions：只处理其正则命中的 Bash 命令。高风险操作始终回落到用户确认；中风险操作 只有在当前用户消息明确授权且满足约束时才自动批准。guardian 使用 raw shell regex，故只接管 这两类能获得明确收益的命令；现有解析器继续保护高风险类别。

配置选择 widget 展示，不替换当前 Bash renderer；guardian 默认复用当前 Pi model，并以 low reasoning effort 运行。项目受信任时，根 AGENTS.md 可作为约束证据，但不能单独授权操作。

Kotlin 与 Java LSP

extensions/lsp.ts 会把 config/lsp.json 部署到全局 ~/.pi/agent/lsp.json，其中启用：

  • kotlin-lsp --stdio：匹配 .kt、.kts。
  • jdtls：匹配 .java；官方 wrapper 会按当前项目工作目录选择 cache data 目录。

两者按 Gradle、Maven 或 Git marker 定位项目根，忽略常见构建输出，并为大型 Android/Gradle 项目预留 120 秒启动时间。pi-lsp 只负责接入，不安装 language server 可执行文件；使用前需 确保 kotlin-lsp 和 jdtls 位于启动 Pi 的 PATH。Kotlin 官方 Homebrew 安装方式为：

brew install JetBrains/utils/kotlin-lsp

JDT LS 需要 Java 21 或更高版本；可使用带 jdtls wrapper 的官方发行包或系统包。

Hermes Memory

Hermes Memory 使用上游默认的 policy-only 模式：不把完整记忆直接注入每轮上下文，由工具按需 搜索；同时启用后台复核、自动 consolidation、session search 和 secret scanning。首次需要检索 旧会话时运行 /memory-index-sessions。

Codex 原生远程压缩

远程压缩只对 openai-codex/openai-codex-responses 生效，使用上游默认配置：在 turn boundary 达到 90% 上下文占用时触发，并写入 Pi 原生 compaction boundary。失败时保持原历史且不静默 回退到文本摘要；checkpoint 与创建它的 Codex model 绑定。

Codex fast mode

该扩展只在 openai-codex provider 的 Responses 请求上加入 service_tier: "priority"。使用 /fast-mode on|off|status 控制当前会话，不影响 其他 provider。

Reference in New Issue View Git Blame Copy Permalink