mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-08-28 08:35:57 +00:00
63 lines
5.9 KiB
Markdown
63 lines
5.9 KiB
Markdown
# 仓库说明
|
||
|
||
本仓库用于维护可通过一次 `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` 同步为全局权威配置。
|
||
- 根包还固定安装 `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 直搜，敏感凭据路径拒绝，外部目录、Git 写操作、破坏性系统操作、网络和安装操作询问。
|
||
|
||
## 修改边界
|
||
|
||
- 优先在目标扩展目录内完成改动；不要让一个扩展依赖另一个扩展的未公开内部实现。
|
||
- 保留原项目的 `LICENSE`、版权信息和必要的来源说明。
|
||
- 扩展运行目录中的 `config.json`、日志、构建产物、覆盖率目录和依赖目录属于本地状态，不应提交；`config/pi-permission-system.json` 是组合包的权威源配置，必须提交并维护。
|
||
- 外部 Pi 扩展依赖必须在根 `package.json` 中使用精确版本，并更新根 `package-lock.json`；不要用仓库级 `.pi/settings.json` 代替组合包依赖。
|
||
- 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`：类型、测试和打包检查的完整验证。
|
||
|
||
若环境缺少依赖或未执行某项验证，交付时明确说明，不以静态检查代替运行结果。
|