# oh-my-open-pi 迁移溯源

本文件记录 `oh-my-openagent` 到 `oh-my-open-pi` 的迁移依据。迁移目标是把 OpenCode 插件里的可复用能力转成 Pi Coding Agent package：扩展入口、工具、hook、provider 注册、技能和 prompt 资源都走 Pi 原生扩展机制。

## 依据代码

| 来源 | 证据路径 | 用途 |
| --- | --- | --- |
| 原始 OpenCode 插件入口 | `/Volumes/JJZ/jerryjiang/unicom/dev/oh-my-openagent/src/index.ts` | 原始插件加载 config、tools、hooks、plugin interface 的主流程 |
| 原始 config 合并 | `/Volumes/JJZ/jerryjiang/unicom/dev/oh-my-openagent/src/plugin-config.ts` | user/project 配置合并、数组去重、agents/categories 深合并 |
| 原始工具注册 | `/Volumes/JJZ/jerryjiang/unicom/dev/oh-my-openagent/src/plugin/tool-registry.ts` | grep、glob、ast-grep、session、background、skill、task、hashline edit 等工具来源 |
| 原始 hook 聚合 | `/Volumes/JJZ/jerryjiang/unicom/dev/oh-my-openagent/src/create-hooks.ts` | core、continuation、skill hook 的组合方式 |
| Pi 扩展文档 | `/Volumes/JJZ/jerryjiang/unicom/dev/pi-mono/packages/coding-agent/docs/extensions.md` | default factory、`pi.registerTool()`、`pi.on()`、`pi.registerCommand()` |
| Pi package 文档 | `/Volumes/JJZ/jerryjiang/unicom/dev/pi-mono/packages/coding-agent/docs/packages.md` | `package.json#pi` 的 extensions/skills/prompts 声明 |
| Pi 扩展类型 | `/Volumes/JJZ/jerryjiang/unicom/dev/pi-mono/packages/coding-agent/src/core/extensions/types.ts` | `ExtensionAPI`、`ToolDefinition<TSchema>`、事件返回值和 provider config contract |
| Pi loader | `/Volumes/JJZ/jerryjiang/unicom/dev/pi-mono/packages/coding-agent/src/core/extensions/loader.ts` | package manifest extension entry 发现逻辑 |
| Pi runner | `/Volumes/JJZ/jerryjiang/unicom/dev/pi-mono/packages/coding-agent/src/core/extensions/runner.ts` | `before_provider_request`、`before_agent_start`、`tool_call`、`tool_result` 的执行语义 |
| Pi package manager | `/Volumes/JJZ/jerryjiang/unicom/dev/pi-mono/packages/coding-agent/src/core/package-manager.ts` | package resources 解析和启用逻辑 |

## 功能映射

| 原始能力 | Pi native 映射 | 当前实现 | 验证 |
| --- | --- | --- | --- |
| OpenCode plugin module | Pi default extension factory | `src/index.ts` 导出 default factory，`package.json#pi.extensions` 指向 `src/index.ts` | `tests/pi-contract.test.ts` 使用 Pi `discoverAndLoadExtensions()` 加载包 |
| user/project 配置合并 | Pi 扩展加载时读取全局 agent dir 和项目 `.pi` 配置 | `src/config.ts` 支持 JSON/JSONC、数组去重、agents/categories/routing 深合并 | `test/config.test.ts` |
| agents/categories 模型路由 | `before_agent_start` 设置 Pi model/thinking level，`before_provider_request` 改写 provider payload | `src/hooks.ts` 的 model router 和 provider payload router | `test/hooks.test.ts` |
| provider 注册 | `pi.registerProvider()` | `src/extension.ts` 读取 `providers` 并注册到 Pi | `test/extension.test.ts` |
| grep/glob | Pi 自定义工具 | `src/tools/search.ts`，参数 schema 使用 TypeBox | `test/search-tools.test.ts`、`tests/pi-contract.test.ts` |
| ast-grep search/replace | Pi 自定义工具 | `src/tools/ast-grep.ts`，支持 search、dry-run replace、apply replace，并识别 postinstall shim | `test/ast-grep-tools.test.ts` |
| session 工具 | Pi `SessionManager` | `src/tools/session.ts` 的 list/read/search/info | `test/session-tools.test.ts` |
| background agent | Pi 子进程后台任务 | `src/background/manager.ts` 和 `src/tools/background.ts`，有并发上限、状态持久化、输出读取、取消 | `test/background-manager.test.ts` |
| runtime reload/status | Pi command context 和 API active tools | `src/tools/runtime.ts`、`src/extension.ts` | `test/runtime-tools.test.ts`、`test/extension.test.ts` |
| tool_call guard | Pi `tool_call` event | `src/hooks.ts` 阻断 bash deny pattern 和 protected paths | `test/hooks.test.ts` |
| tool_result truncation | Pi `tool_result` event | `src/hooks.ts` 按配置截断文本结果 | `test/hooks.test.ts` |
| context injection | Pi `before_agent_start` event message injection | `src/hooks.ts` 注入隐藏 custom message | `test/hooks.test.ts` |
| skills/prompts package resources | `package.json#pi.skills`、`package.json#pi.prompts` | `skills/oh-my-open-pi/SKILL.md`、`prompts/oh-my-open-pi.md` | `tests/pi-contract.test.ts` |
| disabled tools | Pi 注册前过滤工具 | `src/extension.ts` 读取 `disabled_tools` | `test/extension.test.ts` |

## Pi 原生边界

这些 OpenCode 专属能力在当前 Pi package 中保留为配置兼容或由 Pi 原生机制承接：

| OpenCode 能力 | 当前处理 |
| --- | --- |
| Claude Code/OpenCode hook 兼容层 | Pi 的 lifecycle events 承接当前已迁移的 guard、routing、context、result 处理 |
| OpenCode MCP 管理 | Pi package resources 和 Pi 自身扩展生态承接技能、prompt、extension 分发 |
| OpenCode task/agent 专用 UI | Pi commands、tools、session resources 承接当前可验证的运行路径 |
| OpenCode telemetry/OpenClaw/tmux | 运行时外部系统集成留在 OpenCode 侧，Pi package 当前聚焦 Pi 原生扩展 contract |

## 当前验证闸门

```bash
rtk bun test test tests
rtk bunx tsc --noEmit
```

`tests/pi-contract.test.ts` 是 Pi 对接主闸门：它直接调用 Pi Coding Agent 导出的 `discoverAndLoadExtensions()` 和 `DefaultPackageManager.resolveExtensionSources()`，验证本包能被 Pi loader 识别，所有工具参数都是 TypeBox schema，并且 extension、skill、prompt 都能按 package manifest 解析。