# my-pi 维护约定（pi-chrome）

- 扩展入口是 `pi-chrome/extensions/chrome-profile-bridge/index.ts`，Companion MV3 扩展位于 `browser-extension/`，Session 快照存储位于 `src/session-snapshot-store.ts`，测试保留在 `test/` 与 `test-suite/`，来源记录是 `UPSTREAM.md`。
- 同步上游必须从官方 `tianrendong/pi-chrome` 的明确 tag/commit 移植并保留 README、CHANGELOG、SECURITY、文档、测试、作者和 LICENSE；不得导入嵌套 `.git`、`node_modules` 或构建产物。
- 根包必须通过 `file:./pi-chrome` 提供依赖并直接加载仓库源码，不得同时安装或加载 npm 预编译入口。
- 控制默认锁定，每个 Pi session 必须显式 `/chrome authorize`；未授权时不注册 Chrome 工具。显式授权后出现的 21 个 `chrome_*` 工具必须由 Tool Search 分入 `chrome-navigation`、`chrome-interaction`、`chrome-debugging`，不得落入 unknown-tools 模型增强路径。授权撤销或过期时必须停用全部 21 个工具，包括 `chrome_find` / `chrome_inspect`；Tool Search 重新激活 schema 不能替代每次执行时的授权校验。
- 完整 Chrome snapshot 不得进入普通工具文本或 `details`；只能原子写入当前项目 `.pi/chrome-context/<session>/<target>/snapshot.json`，使用哈希目录、POSIX `700` 目录 / `600` 文件，并只返回工作区相对路径和有界元数据。快照不得跨 Session 持久化，Session 启动/关闭、撤销和授权过期必须清理。
- `chrome_snapshot` 和带 `includeSnapshot=true` 的动作必须引导模型立即使用 `ctx_execute_file`，不得使用 `read` / `cat` 把原始 JSON 重新塞入上下文；任何可能改变页面或目标的成功操作必须使旧快照失效，`chrome_find` 只可额外返回有界匹配摘要。
- 修改 bridge、Companion 扩展、授权 lifecycle、快照存储或加载入口后至少运行包内 `npm test`、根 Tool Routing/Tool Search/扩展联合加载测试、`npm pack --dry-run --json` 和实际 packed tarball 隔离安装验证；未经明确要求不得连接或控制真实 Chrome。