oh-my-open-pi
v0.1.4
Published
Pi Coding Agent extension package for model routing, tools, background tasks, and safety hooks.
Maintainers
takltcReadme
oh-my-open-pi
oh-my-open-pi 是一个 Pi Coding Agent 增强包。安装后可以在 Pi 里配置模型路由、agent 默认模型、任务分类模型、备用模型、工具开关、后台任务和安全规则。
安装
pi install npm:oh-my-open-pi安装后打开配置界面：
pi config启用 oh-my-open-pi，然后重启 Pi，或在 Pi 里执行：
/oh-my-open-pi-reload配置文件
全局配置：
~/.pi/agent/oh-my-open-pi.jsonc项目配置：
.pi/oh-my-open-pi.jsonc项目配置优先级更高，适合给单个代码仓设置专属模型、agent 和工具策略。配置文件支持 JSONC，可以写注释。
最小模型路由配置
把下面内容放进 ~/.pi/agent/oh-my-open-pi.jsonc 或项目里的 .pi/oh-my-open-pi.jsonc：
{
"model_fallback": true,
"default_run_agent": "sisyphus",
"agent_switch": {
"shortcut": "ctrl+shift+a"
},
"agents": {
"sisyphus": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"oracle": {
"model": "openai-codex/gpt-5.4",
"variant": "high",
"reasoningEffort": "high"
}
},
"categories": {
"quick": {
"model": "openai-codex/gpt-5.3-codex-spark",
"variant": "low",
"reasoningEffort": "low"
},
"deep": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
}
}
}model 使用 provider/model 格式。provider 需要在 Pi 里可用，或在本配置文件里注册。
每个内置 agent 名称会匹配对应的 OhMyOpenCode 工作模式、系统提示词和工具策略。当前内置 profile 包括：
sisyphus, hephaestus, oracle, librarian, explore, multimodal-looker,
prometheus, metis, momus, atlas, sisyphus-junior切换当前 agent 路由：
/oh-my-open-pi-agent oracle默认快捷键 Ctrl+Shift+A 会按当前配置的 agents 列表循环切换 agent。需要沿用 Tab 手势时，可以把快捷键配置成 tab：
{
"agent_switch": {
"shortcut": "tab"
}
}不带参数执行会列出当前配置的 agent。切换成功后，插件会立即调用 Pi 的模型和思考等级选择 API，后续请求也会继续使用这个 agent 对应的路由；带 category 的请求继续按 categories 路由处理。
agent 启动时，插件会把对应 profile 追加进 Pi 的 system prompt。prompt 可以覆盖内置 profile，prompt_append 会追加到内置 profile 后面；两者支持普通字符串和 file:// 路径。
全量模型路由配置
下面是一份完整的 agents 和 categories 路由示例，可以按你的团队模型策略直接调整：
{
"model_fallback": true,
"default_run_agent": "sisyphus",
"agents": {
"sisyphus": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"hephaestus": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"prometheus": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"oracle": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"librarian": {
"model": "zai/glm-5-turbo",
"variant": "high",
"reasoningEffort": "high"
},
"explore": {
"model": "zai/glm-5-turbo",
"variant": "high",
"reasoningEffort": "high"
},
"multimodal-looker": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"metis": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"momus": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"atlas": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"sisyphus-junior": {
"model": "deepseek/deepseek-v4-pro",
"variant": "max",
"reasoningEffort": "max"
}
},
"categories": {
"visual-engineering": {
"model": "kimi-coding/kimi-for-coding",
"variant": "high",
"reasoningEffort": "high"
},
"ultrabrain": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"deep": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"artistry": {
"model": "kimi-coding/kimi-for-coding",
"variant": "high",
"reasoningEffort": "high"
},
"quick": {
"model": "deepseek/deepseek-v4-flash",
"variant": "max",
"reasoningEffort": "max"
},
"unspecified-low": {
"model": "deepseek/deepseek-v4-pro",
"variant": "max",
"reasoningEffort": "max"
},
"unspecified-high": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"writing": {
"model": "deepseek/deepseek-v4-pro",
"variant": "max",
"reasoningEffort": "max"
},
"visual": {
"model": "kimi-coding/kimi-for-coding",
"variant": "high",
"reasoningEffort": "high"
},
"business-logic": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
},
"data-analysis": {
"model": "deepseek/deepseek-v4-pro",
"variant": "max",
"reasoningEffort": "max"
}
}
}常用字段：
agents: 给具体 agent 指定模型。categories: 给任务分类指定模型。model: 主模型，格式是provider/model，Pi 内置 Kimi Coding Provider 写作kimi-coding/kimi-for-coding，Z.ai 写作zai/glm-5-turbo。variant: 模型档位，例如low、high、xhigh、max。reasoningEffort: 推理强度。OpenAI Codex 使用minimal、low、medium、high、xhigh；DeepSeek 使用high、max；Anthropic 使用minimal、low、medium、high、xhigh，Claude Opus 4.6 可用max。model_fallback: 备用模型策略字段（兼容性保留，当前为 inert 字段）。default_run_agent: 默认运行使用的 agent。fallback_models: 备用模型列表字段（兼容性保留，当前为 inert 字段，不触发自动重试）。tools: 控制某个 agent 或分类可用的工具。prompt_append: 给某个 agent 或分类追加固定提示。prompt: 覆盖某个 agent 的内置系统提示词。
使用 routing 包裹模型路由
你也可以把模型路由集中放在 routing 里：
{
"routing": {
"model_fallback": true,
"default_run_agent": "sisyphus",
"agents": {
"sisyphus": {
"model": "deepseek/deepseek-v4-pro",
"variant": "max",
"reasoningEffort": "max"
}
},
"categories": {
"deep": {
"model": "openai-codex/gpt-5.5",
"variant": "xhigh",
"reasoningEffort": "xhigh"
}
}
}
}顶层写法和 routing 写法可以同时使用。项目配置会覆盖全局配置，同名 agent 或 category 会按项目配置生效。
注册 Provider
如果你要接入 OpenAI-compatible 网关，可以在 providers 里注册：
{
"providers": {
"my-gateway": {
"name": "My Gateway",
"baseUrl": "https://gateway.example.com/v1",
"apiKey": "MY_GATEWAY_API_KEY",
"api": "openai-responses",
"authHeader": true,
"models": [
{
"id": "gpt-5.4",
"name": "GPT-5.4",
"reasoning": true,
"input": ["text", "image"],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 200000,
"maxTokens": 16000
}
]
}
},
"categories": {
"deep": {
"model": "my-gateway/gpt-5.4",
"variant": "high",
"reasoningEffort": "high"
}
}
}apiKey 可以写环境变量名，运行 Pi 前把对应环境变量设好。
工具和安全规则
{
"disabled_tools": [],
"disabled_agents": [],
"tools": {
"grep": true,
"glob": true,
"ast_grep": true,
"session": true,
"background": true,
"runtime": true
},
"background_task": {
"command": "pi",
"args": ["-p"],
"maxConcurrent": 4
},
"hooks": {
"bash_deny_patterns": [
"rm\\s+-rf\\s+/"
],
"protected_paths": [
".env",
".env.local",
".git"
],
// 以下安全选项默认关闭，按需启用
"truncate_tool_output": {
"enabled": false,
"maxChars": 120000
}
},
// context 将 message 注入 agent system prompt（默认关闭）
"context": {
"enabled": false,
"message": "优先使用项目现有约定，修改前先读取相关文件。"
}
}工具开关：
grep: 内容搜索。glob: 文件匹配。ast_grep: 结构化代码搜索和替换。session: 会话查看工具。background: 后台任务工具。runtime: 运行时状态工具：reload_runtime：重新加载 Pi 扩展、技能、提示词和主题。tool_profile：显示当前激活的工具名称。
禁用特定 agent：在 disabled_agents 数组中列出 agent 名称（大小写不敏感），或在 agent 路由中设 "disable": true。被禁用的 agent 不会出现在命令列表、快捷键循环、补全和路由解析中。
单数 provider 兼容：原始 OpenCode 配置文件中的 "provider": { "name": {...} } （单数）会自动合并进 providers，等同 pi.registerProvider() 行为。
常用命令
查看已安装包：
pi list更新包：
pi update npm:oh-my-open-pi查看当前启用的工具：
/oh-my-open-pi-status切换当前 agent 路由：
/oh-my-open-pi-agent hephaestus循环切换当前 agent 路由：
Ctrl+Shift+A默认快捷键来自 agent_switch.shortcut。设置为其他 Pi 支持的按键可以改绑定，设置为 false 可以关闭快捷键注册。Pi 的 tab 默认负责输入补全，覆盖它会在 Pi 里产生快捷键冲突诊断。
重新加载扩展：
/oh-my-open-pi-reload后台子 agent：
delegate_task(description: "review plan", prompt: "Review .sisyphus/plans/app.md", agent: "momus")查看后台任务输出：
background_output(taskId: "task-uuid")取消后台任务：
background_cancel(taskId: "task-uuid")后台 agent 继承规则：
- 后台 agent 路由必须显式指定：启动后台任务时，只有明确传入
agent参数才会设置OH_MY_OPEN_PI_AGENT环境变量；父进程当前激活的 agent 路由不会被自动继承。 - 省略、空字符串或仅含空白字符的
agent视为未提供，不会设置OH_MY_OPEN_PI_AGENT，子进程按默认路由启动。 - 合法的非空白
agent字符串会原样透传给子 Pi 进程，即便该名称不是当前已配置的 agent 名称。子进程启动后在自己的 agent 路由解析中处理（匹配到已知 route 则应用对应策略，否则安全降级）。 - 启动后台任务不会变更或覆盖父进程的当前激活 agent 路由。后台子进程的 agent 选择和父进程的后续请求互不影响。
迁移溯源
迁移依据、Pi native contract、原始 oh-my-openagent 功能映射和验证闸门记录在 docs/migration-trace.md。
以下 OpenCode 字段可安全保留在配置中，不会报错也不会触发任何行为：disabled_skills, disabled_hooks, disabled_commands, hashline_edit, runtime_fallback, experimental, new_task_system_enabled, agent_definitions。
推荐配置方式
通用 provider、默认 agent、常用 category 放在全局配置里：
~/.pi/agent/oh-my-open-pi.jsonc项目专属模型、受保护路径和上下文提示放在项目配置里：
.pi/oh-my-open-pi.jsonc