my-pi/README.md

# 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-web-search`：对模型只暴露 `web_search` / `web_fetch` 两个工具；`web_search` 由当前主模型在 Tavily / Exa / Keenable 间路由，`web_fetch` 固定走 Exa，三家均以纯 `fetch` 直连（Exa 为 `mcp.exa.ai` 的 JSON-RPC，不经 MCP adapter）。
- `extensions/codegraph.ts`：注册原生 `codegraph_explore` 工具，每次调用以短命 `codegraph explore` CLI 进程完成，无常驻 server/daemon；未初始化项目经确认后才 `codegraph init`，结果按索引库 mtime 缓存。
- `extensions/context-view.ts`：通过 `/context` 只读显示 `pi-compaction` 的 effective context，不建立第二套上下文口径。
- `pi-lsp@0.1.7`：为 TypeScript/JavaScript、Kotlin 和 Java 提供 LSP 诊断、跳转与符号工具；TypeScript 后端由组合包内置。
- `pi-hermes-memory/`：从官方 `pi-hermes-memory v0.9.10` 源码导入的持久记忆扩展，提供全局/项目/用户/失败四类记忆、SQLite FTS5 会话与记忆检索、`SKILL.md` 过程记忆、correction 检测与自动 consolidation。
- 本仓库维护的 `pi-minimal-footer`：基于 `@ogulcancelik/pi-minimal-footer@0.1.10`，用紧凑的上下文仪表和订阅用量条替换默认 footer。
- 本仓库维护的 `pi-notify`：基于 `@smoose/pi-notify@0.1.1`，使用 Kitty OSC 99 在 Pi 完全 settled 或权限系统即将请求人工确认时通知，并支持点击精确聚焦来源 Kitty 窗口。
- 本仓库维护的 `pi-compaction`：以增量投影统一确定性工具结果压缩、后台语义摘要、effective token 计量、`context_tree_query`、portable checkpoint 与 Codex native compaction。
- 本仓库维护的 `pi-ask-user`：提供模型主动调用的 `ask_user_question`；TUI 中保留单题、多题、选择、文本、自定义回答与提交前复核，Paseo 等兼容 RPC 客户端通过标准 Pi extension UI 逐题交互。
- 本仓库自维护的 `pi-worktree`：纯斜杠命令（`/wt` / `/worktree`）git worktree 管理，`/wt new` 一键拆分、`/wt merge` 一键合并回来源分支（默认 ff-only，可选 `--squash`），通过 `SessionManager.forkFrom` + `switchSession` 切换会话 cwd；登记状态在 `<agentDir>/pi-worktree/state.json`，不注册模型工具、不 push。
- 本仓库维护的 `pi-tool-search`：从完整工具定义生成并缓存经过校验的工作流分组，默认以最多 5 个动态组、28 个动态工具的 LRU 策略加载原始完整 schema，并支持原子批量激活。
- 本仓库维护的 `pi-chrome`：从上游 `0.15.46` 源码导入，通过显式会话授权接入用户当前已登录的 Chrome Profile；大体积页面快照写入 Session 临时文件并交给 Context Mode 隔离分析，21 个 `chrome_*` 工具仍由 Tool Search 按工作流加载。
- 本仓库维护的 `pi-permission-system`：只读取一份全局普通策略与一份独立 Hard Guards，按 pattern 具体度裁决 allow/ask/deny，并整合 Codex Guardian 风格 AutoReview 与人工 `defer` 兜底；自动评审模型完全由配置文件指定，未配置时提示并转人工审批；工具显隐仍只由 Tool Search 管理。
- 本仓库保留维护的 `pi-subagents` 源码及权限集成实现，但当前已从根组合包依赖和默认扩展加载列表中移除，不会随核心包启用。
- 本仓库维护的 `pi-ssh`：通过纯 Node `ssh2` 持久连接、显式 `ssh_cd` 远端工作区切换、SFTP 与自适应有界搜索提供独立的远端工具；Agent 只在用户明确指定已导入主机及具体任务后发起受 AutoReview 复核的连接。
- `extensions/tool-routing.ts`：保留 Pi 默认系统提示词，并按当前激活工具追加简短的工具与搜索路由规则；提供 `/dump-system-prompt` 导出当前有效提示词。

## 安装、升级与卸载

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

```bash
./install.sh
```

脚本会先执行：

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

安装组合包成功后，脚本会依次检查终端环境和机器级 CLI。所有缺失项目都逐项显示
`[y/N]`，默认拒绝，仅在用户明确选择 `Y` 后修改机器或用户配置：

- 检查 Kitty；macOS 使用 Homebrew cask 安装，其他系统使用 Kitty 官方安装器。Kitty
  可用后继续检查并可通过官方 `themes` kitten 配置 `Solarized Dark`。
- 检查 Oh My Zsh。安装采用官方 unattended 模式，不切换默认 shell、不立即启动 Zsh，
  也不覆盖现有 `.zshrc`。
- 检查 Powerlevel10k；可克隆到 Oh My Zsh 的 custom themes 目录，并把仓库内置的
  `config/p10k.zsh` 原子同步到 `~/.config/my-pi/p10k.zsh`（遵循 `XDG_CONFIG_HOME`）。
  该配置来自当前使用的 Powerlevel10k Rainbow/ASCII 单行紧凑主题；用户自己的
  `~/.p10k.zsh` 不会被覆盖。脚本只在 `.zshrc` 中写入带首尾标记的主题和加载受管块。
- 逐项检查 `git`、`zsh-autosuggestions` 和 `zsh-syntax-highlighting` 是否已经在
  `.zshrc` 的 `plugins` 数组中启用。后两个插件缺少源码时会先克隆到 Oh My Zsh 的
  custom plugins 目录；语法高亮按最后一个插件处理。
- 最后继续检查 `codegraph`、`kotlin-lsp`、Java 21+ 和 `jdtls`。Kotlin、Java 和 JDT LS
  的自动安装使用 Homebrew，CodeGraph 使用官方安装脚本。

脚本首次实际改动 `.zshrc` 前会在同目录创建带时间戳的备份。Oh My Zsh loader、
Powerlevel10k 主题/配置和各 Zsh 插件使用 `# >>> my-pi:<id> >>>` 到
`# <<< my-pi:<id> <<<` 的受管块协议；以后只替换块内内容，块外用户配置保持不变。
标记缺失、重复或不完整时脚本会拒绝修改。若机器没有所需的 Homebrew、`curl` 或 `git`，
脚本会保留已完成的安装结果、继续检查其他项目，并最终返回非零状态。
`rtk` 只供默认关闭的命令改写使用，因此不会作为必装依赖检查。

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

升级已安装的组合包请使用独立脚本：

```bash
./update.sh
```

升级脚本先执行：

```bash
pi update git:git@bitbucket.org:siakitem/my-pi.git
```

脚本不会在升级前破坏性预清理安装缓存：`pi update` 失败时立即停止后续升级——Pi 1.3.0 会在下一次 `pi update` 时依据自己的 `.pi-update-incomplete` 标记自动重新清理并恢复未完成的升级，重新运行 `update.sh` 即可，脚本不做人工恢复。

随后只处理已经安装的项目，未安装项直接跳过且不会询问安装：Kitty 及已启用的
Solarized Dark、Oh My Zsh、Powerlevel10k、两个第三方 Zsh 插件、CodeGraph，以及由
Homebrew 管理的 Kotlin LSP、Java 21 和 JDT LS。升级前会先刷新或查询对应的远端版本：
Git checkout 在 `fetch` 后比较本地与上游提交，Homebrew 包在刷新元数据后通过 `brew outdated`
判断，Kitty 官方安装和 CodeGraph 则比较本地版本与官方最新发布版本。只有检测到版本不同时才
下载并替换；无法确认安装来源或无法可靠比较版本时保留现状并报告。

日志中的“Zsh 插件未安装，升级流程跳过”不是升级失败：升级脚本不会新增用户此前未选择的
插件。需要补装时重新运行 `./install.sh`，并在对应的逐项询问中明确选择 `Y`。

升级成功后，脚本会使用**更新后**组合包中的 `scripts/rebuild-bundle-config.mjs` 整体重建 `<agentDir>/my-pi/` 受管配置目录：按 `config/bundle-manifest.json` 校验来源与目标、在临时目录完成构建后一次性替换，不备份也不保留目录内的本地改动。Powerlevel10k 受管副本只在内容不同时备份并原子同步；`.zshrc` 也只更新已有的 my-pi 受管块，不触碰块外配置。因此安装流程负责补齐缺失项，升级流程只升级已安装项并整体刷新组合包拥有的配置。

卸载组合包：

```bash
./uninstall.sh
```

卸载脚本只调用 `pi remove`，不会删除 Kitty、终端主题、Oh My Zsh、Powerlevel10k、Zsh
插件、CodeGraph、Kotlin LSP、JDT LS 或 Java，因为这些用户环境或机器级工具可能仍被其他
项目使用。三个脚本都可通过 `PI_PACKAGE_SOURCE` 覆盖默认包源，
例如在本地检出中测试：

```bash
PI_PACKAGE_SOURCE="$PWD" ./install.sh
PI_PACKAGE_SOURCE="git:git@bitbucket.org:siakitem/my-pi.git" ./update.sh
```

根 `package.json` 对外部依赖使用精确版本，对本仓库维护的包使用 `file:` 路径；`package-lock.json` 固定完整依赖树。不要再用项目级 `.pi/settings.json` 重复安装这些扩展，否则同一扩展可能被加载两次。

持久记忆由本仓库维护的 `pi-hermes-memory` 提供。它从官方 `chandra447/pi-hermes-memory`
的 `v0.9.10` / `df624056a2e8c68bc89ba0a81e1c120856ec9665` 导入源码到 `pi-hermes-memory/` 并直接加载，
通过本地 `file:` 依赖安装，不需要额外的机器级 CLI。

默认 `policy-only` 模式只把 `<memory-policy>` 指令注入 system prompt，不注入记忆正文，因此不会改变
prompt 前缀、对前缀缓存友好。模型需要历史上下文时主动调用 `memory_search` / `session_search`，
写入用 `memory_add` / `memory_replace` / `memory_remove`，过程记忆用 `skill_manage`。这六个工具由
Tool Search 常驻，保证 policy 指示与模型可见工具一致。

记忆与 skill 数据位于 `~/.pi/agent/pi-hermes-memory/`（全局）与 `~/.pi/agent/projects-memory/<项目>/`
（项目级），可选配置为 `~/.pi/agent/hermes-memory-config.json`。这些是用户数据，安装、升级与卸载脚本
不会创建、迁移或删除。

CodeGraph 采用惰性初始化：`codegraph_explore` 在未建立索引的项目上被调用时会先向用户确认，
确认后才运行 `codegraph init` 并自动重试本次探索；不需要手动执行任何初始化命令。

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

CodeGraph 本体不由组合包安装。需要使用 CodeGraph 的机器应自行确保 `codegraph` 在
启动 Pi 的 `PATH` 中（`install.sh` 会交互式提供官方安装）。扩展只有在用户于确认对话框中
明确同意后才会创建 `.codegraph/`；安装、升级和普通启动流程不会创建或维护索引，也不会修改
CodeGraph 的更新或遥测设置。

## 组合行为

### 模型主动提问

`pi-ask-user/` 把 Pi 上游的单题与多题示例合并为唯一的 `ask_user_question` 工具；不提供 `/qna` 或其他用户命令。模型只有在继续任务确实缺少用户决定、偏好、确认或澄清时才应加载 `user-interaction` 组并调用它，不得重复询问直接消息中已有的信息。工具最多一次提交 8 个问题：交互式 TUI 支持选择、自由文本、显式跳过、返回修改和最终复核；Paseo 等具备 Pi extension UI bridge 的 RPC 客户端使用逐题 `select` / `input` 对话框。取消结果不会作为 AutoReview 的授权证据，JSON/print 等无交互 UI 模式保持拒绝执行。

### 工具与搜索路由

`extensions/tool-routing.ts` 不替换 Pi 默认系统提示词，而是在每轮开始前根据当前激活工具追加简短规则。代码结构、调用关系和待修改 symbol 优先使用 CodeGraph，定义、引用、类型和修改后诊断优先使用 LSP；仓库字面搜索先用 FFF `find` 缩小文件或目录范围，再在已收敛的路径中用 `grep`/`multi_grep` 获取行号。宽泛搜索命中大量结果、发生截断或达到上限时，应继续缩小路径、glob 或 pattern，而不是提高 limit 或输出全部结果。

在线搜索默认按任务只选一个服务：关键词不确定、新闻/近期话题或需要较多候选来源时优先 Tavily；官方/API 文档、版本信息、论文和高确定性事实确认优先 Exa；中文政策、政府公告、中文网页、站点限定和日期筛选优先 Keenable。只有来源质量或不确定性确实需要时才跨服务复核，避免默认把三套结果全部塞进上下文。

日志、测试/构建输出、工作区内大文件的探索/分析/总结以及不可预测的大输出优先交给 Context Mode。只有确实需要精确源码或准备修改时，才用带 `offset/limit` 的 Hashline `read` 读取最小区域并取得 `LINE#HASH` 锚点，随后用锚定 `edit` 修改；成功编辑返回的新锚点可继续复用，只有锚点过期或下一目标区域尚未展示时才重新读取。已有工具结果足够时停止检索，避免对同一问题依次重复调用 CodeGraph、FFF 和 `read`。

使用 `/dump-system-prompt` 可将当前扩展所见的有效提示词写入当前项目的 `.pi-debug/effective-system-prompt.md`。`.pi-debug/` 属于本地诊断输出，默认不提交。

### 系统提示词封面

`extensions/system-prompt-cover.ts` 把 Pi 默认系统提示词的**开头**替换为组合包权威的 `config/system-prompt-cover.md`（部署到 `~/.pi/agent/my-pi/system-prompt-cover.md`），同时**保留其余全部分区及其原始顺序**：`<tools>`、`<rules>`、`<docs>`、`<skills>`、`<project_context>`、`<cwd>` 都不会被删除或重新排序。

实现上使用 Pi 的 `forceSystemPrompt` 投影路径（每轮把渲染结果作为强制定本发送）而不是 `customPrompt` 选项：后者会连带抑制 `tools`/`rules`/`docs` 三个分区，且回填只能追加到末尾，无法保持顺序。封面只在**请求**时应用，不修改 transcript 中已持久化的结构化分区。

封面每轮重新读取，因此修改 `~/.pi/agent/my-pi/system-prompt-cover.md` 后在**下一轮**即生效，不需要重开会话；已经结束的历史对话不受影响。文件缺失或为空白时不干预，Pi 继续使用自身默认封面。

该文件由组合包直接维护，`install.sh` 与 `update.sh` 会在组合包安装/升级后连同整个 `my-pi/` 目录一起重建，**不保留备份并且会覆盖**本地修改；要自定义请直接编辑仓库中的 `config/system-prompt-cover.md`。

`system-prompt-cover.md` 必须使用这个名字：不能改名为 `SYSTEM.md`，否则 Pi 会先把它当作 `customPrompt` 读入，封面扩展拿到的提示词就已经缺少可供回填的分区了。

### 接管当前 Chrome

组合包固定加载 `pi-chrome@0.15.46`，但不会自动取得浏览器控制权。首次安装后在 Pi 中运行 `/chrome onboard`，按提示在 `chrome://extensions` 以 Developer mode 加载组合包内的 unpacked Chrome 扩展，再执行 `/reload` 与 `/chrome doctor`。每个 Pi session 仍需由用户显式运行 `/chrome authorize`；可用 `/chrome revoke` 立即撤销。Bridge 只监听 `127.0.0.1:17318`，Chrome 扩展具有广泛的 tabs/scripting/debugger 权限，应只从可信组合包安装。

授权后注册的 21 个 `chrome_*` 工具不会常驻提示词；Tool Search 将它们分为 `chrome-navigation`、`chrome-interaction` 和 `chrome-debugging`。普通网页资料发现仍使用 Tavily/Exa/Keenable，只有需要读取登录态页面或实际操作当前 Chrome 时才加载 Chrome 组。

`chrome_snapshot`、`chrome_find` 和带 `includeSnapshot=true` 的交互不会再把完整页面结构直接塞进模型上下文：完整 JSON 只写入当前项目 `.pi/chrome-context/` 下按 Session/目标隔离的临时文件，工具结果仅返回相对路径和小型摘要。模型应立即用 `ctx_execute_file` 从该文件提取下一步所需的 uid、文本或状态，不能用 `read` / `cat` 重新读入全文。每个目标只保留最新快照；页面操作后旧快照失效，Session 结束、`/chrome revoke` 或授权过期时清理。

### 按需加载工具 schema

`pi-tool-search/` 从上游 <https://github.com/tuansondinh/pi-tool-search> 的 `v0.3.6`、commit `ddfb23646fd3957b791214de278e23aa393c9b13` 导入，并像 `pi-rtk-optimizer/` 一样由本仓库直接维护；它不是 submodule，不加载 npm 预编译入口，也不保留嵌套 `.git`、上游 `.pi` 状态或构建产物。来源、许可证说明和本地差异记录在 `pi-tool-search/UPSTREAM.md`。

本地源码直接使用 `@earendil-works/pi-coding-agent`、当前 `typebox`、`ModelRegistry.complete()` 与 `setActiveTools()`，不安装、别名映射或加载旧 `@mariozechner` runtime，也不使用 provider payload 改写、代理执行或隐藏 `sendMessage` 循环。

新 session 默认常驻 Pi 核心 `read`、`write`、`edit`、`bash`、`grep`、`find`，以及 `codegraph_explore`、`lsp_diagnostics`、`ctx_execute`、`ctx_execute_file`、`ctx_batch_execute` 和 `tool_search`；Windows 上额外把内置 `powershell` 与 `bash` 作为同类本地 Shell 核心工具固定启用，非 Windows 平台则从目录中过滤它。组合包在 `pi-tool-search/extensions/bundle-groups.ts` 中为自身暴露的工具预置权威分组，包括本地文件导航、SSH 远端文件/命令、Chrome 导航/交互/调试、用户交互、CodeGraph/LSP、Tavily、Exa、Keenable、Context Mode 执行/知识库/观测/管理、Memory 查询/维护与 Skill 管理。不可用、已固定或尚未授权而未注册的可选工具会自动从动态组中滤除。

标准组合包的全部隐藏工具都能命中预置目录，因此首次使用不调用模型、不生成用户缓存，也不把完整隐藏 schema 发送给 provider。只有用户另外安装了未识别工具，并且当前调用不是精确加载已有分组时，才可使用当前已认证模型补充目录；精确已有分组始终立即按当前确定性目录激活，不等待无关未知工具的模型增强。模型结果必须保留组合包预置分组，否则直接拒绝。有效增强缓存以 `0600` 写到 agent 目录的 `my-pi/tool-search/catalog-v1.json`，调用用量计入工具结果。用户 `groupOverrides` 的优先级高于预置目录；`/tool-search-rebuild` 会恢复预置目录，`/tool-search-status` 显示目录来源、容量、LRU 顺序和最近淘汰原因。

动态组默认最多同时加载 5 个、每个模型生成组最多 8 个工具、全部动态组最多 28 个工具。`tool_search.groups` 可在一次调用中原子加载最多 5 个精确组；完整请求本身超限时保持原状态。加载或调用组内工具会更新 LRU，超限时先卸载最久未使用且不在本次请求内的组。自然语言 query 对精确工具名和已提交 workflow alias 加权，弱匹配或近似同分只返回候选。首次纯增加载继续使用 Pi 原生增量传播；发生卸载和加载的替换由 Pi 自动走安全 fallback。

Tool Search 的用户级配置文件是 `~/.pi/agent/my-pi/tool-search/config.json`（准确位置为 Pi agent dir 下的 `my-pi/tool-search/config.json`），由 `install.sh` / `update.sh` 从仓库的 `config/tool-search.json` 部署：

```json
{
  "alwaysEnabled": [
    "codegraph_explore",
    "lsp_diagnostics",
    "ctx_execute",
    "ctx_execute_file",
    "ctx_batch_execute",
    "memory_search",
    "session_search",
    "memory_add",
    "memory_replace",
    "memory_remove",
    "skill_manage",
    "context_tree_query"
  ],
  "showToolSearchFooterStatus": false,
  "maxActiveGroups": 5,
  "maxToolsPerGroup": 8,
  "maxDynamicTools": 28,
  "groupOverrides": {}
}
```

扩展只读取该文件，从不写入：文件缺失、不可读或结构无效时回退内置的 `BUNDLE_TOOL_SEARCH_DEFAULTS`；每次运行 `install.sh` / `update.sh` 都会随整个 `my-pi/` 目录重建该文件，本地手改会被覆盖，长期自定义应改仓库 `config/tool-search.json`。`alwaysEnabled` 中的精确工具名属于固定工具，不占动态组额度；`groupOverrides` 可把指定工具强制归入命名组。默认关闭状态行，避免与 minimal footer 叠加。

### 精确读写归 Hashline

组合包固定加载 `pi-hashline-edit@0.8.3`，以带 `LINE#HASH` 行锚点的实现覆盖 Pi 内置 `read` 和 `edit`。`extensions/hashline.ts` 在加载扩展前把 `config/pi-hashline-edit.json` 同步到 `~/.pi/agent/hashline.json`：`hashLength` 保持最小的 `2`，`grep` 强制关闭以避免与 FFF 冲突，`replaceText` 关闭以要求修改使用可验证锚点。

Hashline 不负责压缩大文件；每行锚点本身还会增加少量 token。上下文节省来自先用 CodeGraph/LSP 定位、再用 Context Mode 隔离分析，最后只对真正准备修改的区域执行小范围 Hashline `read`。因此不应为了探索、计数、比较或总结而直接读取完整大文件。

### 搜索归 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 不替换这两个扩展的现有配置。

### SSH 服务器配置

`pi-ssh` 运行时使用纯 `ssh2`，不依赖系统 `ssh` 或 `sshpass`。首次使用前显式导入需要的 OpenSSH alias：

```bash
./ssh_config.sh import packaging-server
```

脚本只在导入阶段调用 `ssh -G` 解析用户选中的 alias，随后交互选择 SSH Agent（包括 1Password）、私钥文件或密码认证、显示并确认服务器 Host Key、测试连接，再把完整配置写入 `${XDG_CONFIG_HOME:-$HOME/.config}/my-pi/pi-ssh/hosts.enc`。Agent 模式只保存 socket 路径，私钥仍留在 Agent 中；邻接的随机 `vault.key` 用于 AES-256-GCM 解密，目录与两个文件在 POSIX 上分别是 `700` / `600`。该加密只避免误看或单独泄漏密文，能读取两文件的同一用户仍可解密。

可用 `./ssh_config.sh list|update|remove|rotate-key` 管理已导入主机。第一版拒绝 `ProxyJump` / `ProxyCommand`，且不会自动读取远端 `AGENTS.md` 或 `CLAUDE.md`。连接不再通过 `/ssh`、`--ssh` 或 session resume 建立：用户在具体远端任务中明确指定已导入 host ID 后，Agent 把受复核、串行且可取消的 `ssh_connect` 作为独立步骤调用并等待成功，再使用其他 `ssh_*` 工具；连接动作及后续操作均进入 `ask → auto-review`，相对远端路径会在预览中显示请求值和解析后的绝对路径，会话结束自动断开。SSH transport 在会话内持久，独立命令最多使用 4 路有界并发 exec channel，但每次 `ssh_bash` 都启动独立的非交互 Shell；需要持续改变后续远端操作的工作目录时，Agent 同样必须把受复核且串行执行的 `ssh_cd` 作为独立步骤调用并等待成功，而不是依赖某次 Shell 中临时执行的 `cd`。

远端文件搜索使用独立的 `ssh_find` / `ssh_grep`：在每次获批调用内按服务器现有能力选择 `fd/fdfind → git ls-files → find` 或 `rg → git grep → find+grep`，不安装远端软件，并以最大 200 条结果、单行截断和 `truncated` 标记约束返回。搜索目标作为绝对参数与当前远端执行 cwd 分离，因此 `ssh_grep` 可直接搜索单个文件而不会尝试把文件当目录进入；30 秒超时会报告解析后的 root 并提示先用 `ssh_find` 缩小范围。远端 HOME/cwd 通过可取消、有界随机标记探测获得，畸形结果不会更新连接状态。RTK 只压缩 `ssh_bash` 的非搜索输出，不改写远端命令，也不处理 `ssh_find`、`ssh_grep` 或 `ssh_read`。详细说明见 [`pi-ssh/README.md`](pi-ssh/README.md)。

### 在线搜索服务

运行 `./search_config.sh` 可用隐藏输入依次配置 Tavily、Exa 和 Keenable；也可一次无交互配置：

```bash
./search_config.sh --tavily '...' --exa '...' --keenable '...'
```

只传部分参数时保留其他服务的已有值。凭据写入 Pi 自己的
`auth.json`（`$PI_CODING_AGENT_DIR/auth.json`，默认 `~/.pi/agent/auth.json`，权限 `600`）：
每个 provider 一条 `{ "type": "api_key", "key": "..." }` 条目，原子加锁写入，
其他条目（如 OAuth 凭据）原样保留。`--list` 只显示配置状态、不回显 key；
`--migrate` 可从旧的 `search.env` 导入缺失条目；`--auth FILE` 可覆盖文件路径。

key 值支持 auth.json 原生解析语义：`$VAR` / `${VAR}` 环境变量插值、`!command`
执行命令取 stdout（如 `"!op read op://Vault/Tavily/key"`）、`$$` / `$!` 转义。
显式进程环境变量因此不再被直接读取——需要 env 注入时把 key 写成
`"$TAVILY_API_KEY"` 即可。`KEENABLE_API_URL`（非 secret 的端点覆盖）仍走
进程环境变量，也可放在 keenable 凭据的 `env` 字段中。

三个服务由本仓库自维护的 `pi-web-search/` 统一封装：对模型只暴露 `web_search` / `web_fetch` 两个工具，schema 与提示词中不出现任何厂商名；每次 `web_search` 先由当前主模型（`ctx.model` + `ctx.modelRegistry.complete`，零额外配置）按内置路由规则在候选厂商中选一个，再按统一参数翻译后调用，`details` 记录实际 provider 与路由方式；选择结果按会话内 LRU 缓存，路由失败或被选厂商报错时按可用性顺序自动降级。`web_fetch` 固定调用 Exa 的 `web_fetch_exa` 提取正文（默认每页 3000 字符上限），失败时静默降级到 Keenable、再到 Tavily。

`pi-web-search/clients/` 全部是纯 `fetch` 实现，三个 key 统一由 `pi-web-search/auth.ts` 从 auth.json 解析（Tavily 直连 `api.tavily.com/search|extract`，必须有 `tavily` 凭据，无 key 时不参与路由；Keenable 复刻上游 client，默认走 keyless `/public` 端点，`keenable` 凭据只提高速率限制并保留 SSRF host 防护；Exa 直接对 `https://mcp.exa.ai/mcp` 发 JSON-RPC——initialize 一次并缓存 `mcp-session-id`、随后 `tools/call`，会话失效（HTTP 404）自动重建，`exa` 凭据只通过 `x-api-key` 请求头发送，不再依赖 `pi-mcp-adapter`）。Exa 搜索统一走 `web_search_advanced_exa` 并显式限制结果数量与 `textMaxCharacters`，避免响应过大。

### CodeGraph 是原生工具

`extensions/codegraph.ts` 注册原生 `codegraph_explore` 工具，不走 MCP：每次调用以 argv 形式
直接执行机器级 `codegraph explore`（上游保证其输出与 `codegraph_explore` MCP 工具一致），
进程随调用结束，不维护常驻 server 或 daemon。`projectPath` 缺省为会话 cwd，沿目录向上寻找
最近的 `.codegraph/codegraph.db`；`maxFiles` 透传 `--max-files`。

结果按 `(索引根, query, maxFiles)` 缓存在扩展内，并以索引库 mtime 作为有效性判据：任何
重建或同步都会更新 mtime 使旧缓存自动失效，模型对同一区域反复探索时重复调用立即返回。

若目标目录没有索引，工具先弹出确认；用户同意后运行 `codegraph init` 并自动重试本次调用，
拒绝或 CLI 不可用/执行失败时把结果打回并提示改用 `find`/`grep`/`read`/LSP，不影响其他扩展。
索引状态可在项目内自行检查：

```bash
codegraph status
```

### 统一权限系统、硬防御与 AutoReview

`pi-permission-system/` 从上游 `pi-permission-system-v26.2.1` tag 导入，初始源码快照为 `ec4fdb11343dc94f7185b113e559a4cf9f8dc035`。原 `pi-permission-auto-review` 的 reviewer、可信证据边界和 Codex Guardian 风格策略已整合进同一个扩展；其 MIT 许可和来源记录保留在 `pi-permission-system/LICENSES/` 与 `docs/auto-review/`。根组合包不再加载第二个 AutoReview 扩展。

`extensions/permission-system.ts` 只加载扩展本身，不做任何配置播种或迁移；两份用户可编辑 JSONC 由 `install.sh` / `update.sh` 经 `scripts/rebuild-bundle-config.mjs` 以 `0600` 部署：

- `~/.pi/agent/my-pi/permission-system/policy.jsonc`：唯一的全局普通 allow/ask/deny 策略，同时保存运行参数与 AutoReview 配置。项目级 `.pi/extensions/pi-permission-system/policy.jsonc` 不再读取。
- `~/.pi/agent/my-pi/permission-system/hard-guards.jsonc`：仅全局生效的硬防御。硬 `deny` 先于 Session grant、per-agent 规则和 AutoReview，不能被后续层放宽。

普通 pattern 不再按“最后一条命中”覆盖，而按具体度选择：精确匹配优先，其次字面字符更多、通配符更少、pattern 更长，只有完全同级时才以后声明者为准。因此具体 deny 会稳定压过宽泛的 `"*": "allow"`。

系统不再产生 `external_directory` 判断：项目外路径与项目内路径一样，只走用户配置的工具、`path` 和 Bash 规则。Tool Search 是唯一的工具显隐/激活控制者；权限系统只在工具被调用时做裁决。

`my-pi/` 目录由组合包整体拥有：每次 `install.sh` / `update.sh` 都会按 `config/bundle-manifest.json` 删除后重建，不备份也不迁移目录内的改动；要长期保留的自定义必须改仓库 `config/` 下的权威源。旧位置 `~/.pi/agent/extensions/pi-permission-system/` 的残留文件被忽略，不迁移也不清理。

默认普通策略对未匹配请求返回 `ask`，并通过 `authorizerChain: ["auto-review"]` 先交给内置 reviewer。高危 Hard Guard 直接终止；AutoReview 的 `allow` / `deny` 对任一普通策略 `ask`（包括 `path`）直接结束当前审批；模型、配置、认证、超时或输出异常统一 `defer` 到人工界面。

自动评审模型完全由配置文件决定：`autoReview.provider` 与 `autoReview.model` 都不设内置默认值，扩展也不会合成替代模型。两者任一缺失时，若 `auto-review` 已在 `authorizerChain` 中，`session_start` 会提示一次，之后每个 `ask` 都 `defer` 到人工审批界面；provider 未注册或模型未发布同样 `defer`。`reasoning` 也由配置决定，不设默认常量。

每个 AutoReview `allow` / `deny` 记入权限 review 日志（`defer` 记为 `errorCategory`），日志只保存有界、脱敏的请求标识与风险/授权等级，不保存 rationale、原始工具参数或 transcript。扩展不汇总历史裁决，也不启动任何后台分析 Agent，更不会自动修改策略文件。

SSH 仍复用同一权限入口：`ssh_connect`、远端路径工具默认为 `ask`，`ssh_bash` 映射完整 Bash 策略并设置 `decisionFloor: "ask"`。硬拒绝不能被 reviewer 覆盖；普通 `defer` 才进入人工兜底。

### TypeScript、Kotlin 与 Java LSP

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

- `typescript-language-server@5.3.0 --stdio`：匹配 TypeScript/JavaScript 及 JSX/TSX、MTS/CTS、MJS/CJS；组合包同时固定 `typescript@6.0.3` 作为 `tsserver` 后端。
- `kotlin-lsp --stdio`：匹配 `.kt`、`.kts`。
- `jdtls`：匹配 `.java`；官方 wrapper 会按当前项目工作目录选择 cache data 目录。

TypeScript LSP 通过组合包内 Node 和 `typescript-language-server` CLI 直接启动，不依赖、调用或拉起 VS Code GUI；部署配置时会把包内 CLI 的绝对路径写入全局配置。它优先使用项目自身可用的 TypeScript，否则回退到组合包固定的 TypeScript 6 后端。

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

```bash
brew install JetBrains/utils/kotlin-lsp
```

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

### 持久记忆（pi-hermes-memory）

组合包加载仓库内 `pi-hermes-memory` 源码并注册六个工具：

| 工具 | 作用 |
|---|---|
| `memory_search` | 检索持久记忆：全局、用户、项目、失败四类 |
| `session_search` | 在 SQLite FTS5 trigram 索引中检索历史会话原话 |
| `memory_add` | 新增一条持久记忆 |
| `memory_replace` | 按子串匹配修改已有记忆 |
| `memory_remove` | 按子串匹配删除已有记忆 |
| `skill_manage` | 创建、查看、修补、重写或删除 `SKILL.md` 过程记忆 |

默认 `policy-only` 模式不在 system prompt 中注入记忆正文，只注入 `<memory-policy>` 指令告诉模型何时
检索、何时写入。因此首轮 token 成本很低，也保持 prompt 前缀稳定。写工具只写扩展自己的数据目录，
不触碰工作区。

`skill_manage` 是扩展提供的能力：Pi 宿主只负责发现并加载 skill 目录，本身没有创建 skill 的工具。
该扩展同时注册 `~/.pi/agent/projects-memory/<项目>/skills/` 供 Pi 发现，因此不加载它时，这些既有
skill 也不会出现在 Pi 的 skill 索引中。

记忆与 skill 位于 `~/.pi/agent/pi-hermes-memory/`（全局）和 `~/.pi/agent/projects-memory/<项目>/`
（项目级），配置位于 `~/.pi/agent/hermes-memory-config.json`。这些是用户数据：安装、升级和卸载脚本都
不会创建、迁移或删除它们，也不会自动转换旧 Hippo `.hippo/` 数据。

### Kitty 完成与权限确认通知

`pi-notify/` 直接加载本地维护源码。完成通知只在交互式 TUI 中监听 `agent_settled`，因此自动重试、自动
compaction 和排队 follow-up 完成前不会提前通知；同时监听 `pi-permission-system` 的
`permissions:ui_prompt`，仅在权限系统即将显示人工确认界面时立即通知，策略或 AutoReview 已直接完成的
决定不会通知。Kitty 后端使用 Base64 OSC 99、每个 Pi Session 独立的稳定通知 ID、显式 `a=focus`，
并默认设置 `o=always`：即使来源 Kitty window/pane 正在接收键盘输入也会显示通知，点击通知由 Kitty
返回原始来源；仍可通过环境变量改用 `unfocused` 或 `invisible`。

默认忽略不足 3 秒的短任务，但权限确认通知不受该时长门槛影响。`/notify on|off|test|status` 可控制
当前 Session 的两类通知；持久默认通过 `PI_NOTIFY_ENABLED`、`PI_NOTIFY_MIN_SECONDS`、
`PI_NOTIFY_VISIBILITY`、`PI_NOTIFY_ACTION`、`PI_NOTIFY_MESSAGE_SOURCE` 等环境变量配置。
`PI_NOTIFY_MESSAGE_SOURCE=none` 会同时隐藏回复摘要以及权限值和请求者细节。Kitty 位于 tmux 内时需要
`set -g allow-passthrough all` 并重启 tmux server。完整配置和上游差异见
[`pi-notify/README.md`](pi-notify/README.md)。

### Pi Compaction

组合包只加载仓库内维护的 `pi-compaction/`。它以增量 Segment Index 管理已经进入 Session 的历史：已闭合工具结果先同步替换为有界的确定性证据 stub，大于阈值的结果再由单 Session 有界后台 worker 生成语义摘要；Provider 请求不会等待后台摘要。原始工具证据不重复写入 custom entry，可通过 `context_tree_query` 使用 source key 或 tool call ID 有界恢复。

普通 Provider、阈值判断、Codex native compaction、`/context`、`/compaction-status` 和 minimal footer 都读取同一个 effective projection snapshot。Pi Core 的 raw threshold 只负责唤醒：只有 effective token 下界达到默认 90% 才执行 threshold compaction；manual 与 overflow 始终允许继续并在 native 失败时回退 Pi 默认 compaction。Codex native API 直接消费 effective ResponseItems，同时保存有界 portable summary 供模型或 Provider 切换。

唯一配置位于 Pi agent `settings.json` 的 `piCompaction` 字段，默认 soft/hard/target 比例为 72%/90%/55%，扩展只在内存中归一化且不写回配置。`/compaction-status` 显示 raw/effective/reclaimed token、置信度、segment 和后台任务。完整配置、Session version 1 格式和双上游来源见 [`pi-compaction/README.md`](pi-compaction/README.md) 与 [`pi-compaction/UPSTREAM.md`](pi-compaction/UPSTREAM.md)。

原生远程压缩同时支持 `openai-codex` + `openai-codex-responses` 和 `sub-api` + `openai-responses`，使用触发时当前会话模型。SubAPI 保留现有模型配置，从 `baseUrl` 调用公共 `/responses` 并使用 `compaction_trigger` 流式协议；优先保留非空显式 `Authorization`，否则使用 API key，也支持仅凭非空 `cf-aig-authorization` 的代理认证。缺失或空白凭据在请求前拒绝。SubAPI 不要求客户端解析 ChatGPT account ID，也不调用独立 `/responses/compact`；Codex 的 JWT 要求保持不变。网关部署须支持 Sub2API 原生压缩 v2；请求失败沿用 Pi 回退，切换模型或 Provider 时使用 portable summary。

本实现不读取或迁移旧 `contextPrune`、`context-prune-*` 或旧 Codex native checkpoint；切换后应创建新 Session。它与 Context Mode 职责互补：Context Mode 防止大型原始内容进入会话，Pi Compaction 管理已经进入会话的长期历史。