miku@astro-koharu:~/docs$ omp read oh-my-pi-usage.md --style terminal --no-content-loss

source895 行完整手册

workspaceastro-koharu

modecoding agent terminal

coverage登录 / 配置 / 会话 / 工具 / 子代理

Oh My Pi 使用手册

本文面向 astro-koharu 项目使用者，说明如何用 Oh My Pi（命令通常为 omp）进行代码理解、修改、验证、会话管理和项目级配置。

当前推荐工作空间：

ompprompt

/home/miku/Documents/astro-koharu

建议始终从项目根目录启动：

ompshell

cd /home/miku/Documents/astro-koharu
omp

也可以一次性给任务：

ompshell

cd /home/miku/Documents/astro-koharu
omp "检查这个 Astro 项目为什么 build 失败，并修复"

1. Oh My Pi 是什么

Oh My Pi 是终端里的 coding agent，主命令通常是 omp。它可以：

读取项目文件、目录、文档、图片、压缩包、SQLite 和网页。
搜索代码、理解调用关系、使用语言服务器做引用查找和重命名。
编辑文件、运行命令、启动服务、用浏览器验证 UI。
切换模型、调整思考等级、管理会话、导出和分享结果。
使用项目级上下文、规则、技能、斜杠命令、MCP 工具和子代理。

适合的任务包括：

解释陌生代码和架构。
修复 bug 并验证。
增加功能。
重构并迁移所有调用点。
审查代码质量、安全性、性能和可访问性。
根据截图或浏览器行为修 UI。

2. 第一次使用：登录模型供应商

如果当前模型没有可用凭证，omp 会提示你登录或配置 API key。

2.1 交互式登录

在 omp 会话里输入：

ompprompt

/login

或指定供应商：

ompprompt

/login anthropic
/login openai
/login google

退出登录：

ompprompt

/logout

登录是按 provider 独立管理的。登录 Anthropic 不等于登录 OpenAI 或 Google。

2.2 环境变量方式

常见环境变量：

ompshell

export ANTHROPIC_API_KEY=...
export OPENAI_API_KEY=...
export GEMINI_API_KEY=...
export OPENROUTER_API_KEY=...
export GROQ_API_KEY=...

omp 会读取 .env。有效优先级从高到低：

进程环境变量。
当前项目 <cwd>/.env。
~/.omp/agent/.env。
~/.omp/.env。
~/.env。

项目私有 key 可以放在项目 .env，但不要提交到 Git。

3. 基本交互方式

启动后直接描述目标即可。

示例：

ompprompt

帮我看一下首页为什么样式错乱

ompprompt

修复 pnpm build 报错，改完后跑 build 验证

ompprompt

阅读 src/pages 下的路由结构，解释这个站点怎么组织页面

ompprompt

给 astro-koharu 添加一个日语/英语切换入口，遵循现有 i18n 结构

更好的任务格式是“目标 + 范围 + 验收”：

ompprompt

目标：修复文章详情页移动端目录遮挡正文的问题。
范围：只改 src/layouts 和 src/components 中相关文件。
验收：pnpm build 通过，并用浏览器打开本地预览确认移动端布局正常。

如果你只想让 agent 先调查，不要直接修改：

ompprompt

先定位根因，给出证据，暂时不要改代码

如果要它完成后验证：

ompprompt

修复后必须运行 pnpm build，并报告实际输出

4. 常用斜杠命令

交互式会话里输入 / 会触发命令补全。常用命令如下。

4.1 设置与快捷键

ompprompt

/settings

打开设置面板。

ompprompt

/hotkeys

查看当前快捷键。这个列表会反映用户自定义 keybindings 和扩展添加的按键。

4.2 模型与登录

ompprompt

/model

选择或切换模型。

ompprompt

/login
/logout

管理供应商凭证。

4.3 工作目录

ompprompt

/move

切换当前会话的工作目录。切换后会刷新项目级配置、命令和上下文。

如果当前会话不在 astro-koharu 目录，可以切到：

ompprompt

/home/miku/Documents/astro-koharu

4.4 会话管理

ompprompt

/resume

打开会话选择器，恢复已有会话。

ompprompt

/fork

从当前会话 fork 一个新会话。适合保留当前上下文，但尝试另一条路线。

ompprompt

/fresh

清空 provider-facing 的上下文状态，但不新建 session 文件。

4.5 导出与分享

ompprompt

/dump

把当前会话格式化成文本并复制到剪贴板。

ompprompt

/export
/export output.html

导出 HTML。

ompprompt

/share

生成端到端加密分享链接。默认会做 secret redaction。

5. 会话恢复与导出

会话文件默认在：

ompprompt

~/.omp/agent/sessions/

5.1 继续最近会话

ompshell

cd /home/miku/Documents/astro-koharu
omp --continue

--continue 会优先使用当前终端的 breadcrumb，否则找当前目录最近会话；没有会话则新建。

5.2 选择恢复

ompshell

omp --resume

打开选择器。

5.3 用 id 或路径恢复

ompshell

omp --resume <session-id>
omp --resume /path/to/session.jsonl

5.4 从已有会话 fork

ompshell

omp --fork <session-id>
omp --fork /path/to/session.jsonl

适合从历史上下文继续，但不污染原会话。

5.5 导出历史会话

ompshell

omp --export /path/to/session.jsonl output.html

6. 配置系统

omp 配置是 YAML。

6.1 全局配置

路径：

ompprompt

~/.omp/agent/config.yml

命令：

ompshell

omp config list
omp config get theme.dark
omp config set defaultThinkingLevel high
omp config reset steeringMode
omp config path

6.2 项目配置

路径：

ompprompt

<repo>/.omp/config.yml

对本项目就是：

ompprompt

/home/miku/Documents/astro-koharu/.omp/config.yml

注意：项目设置只读取当前工作目录里的 .omp/，不是自动向上寻找最近的 .omp/config.yml。因此应从项目根目录启动，或用 /move 切到项目根。

6.3 一次性配置 overlay

ompshell

omp --config ./local.yml "用这个配置检查 build"

多个 overlay 后面的覆盖前面的：

ompshell

omp --config base.yml --config experiment.yml "跑一次实验"

6.4 配置优先级

从低到高：

ompprompt

内置默认值
<- 全局 config
<- 项目 config
<- --config overlay
<- CLI flag / 环境运行时覆盖

7. 常用配置项

7.1 模型角色

ompconfig

modelRoles:
  default: anthropic/claude-sonnet-4-5
  smol: openai/gpt-4.1-mini
  slow: anthropic/claude-opus-4-5:high
  plan: anthropic/claude-opus-4-5

常见角色：

default：默认主模型。
smol：轻量模型。
slow：更强但更慢的模型。
plan：计划模式模型。
advisor：顾问模型。

7.2 思考等级

ompconfig

defaultThinkingLevel: high
hideThinkingBlock: false

可选等级：

ompprompt

minimal, low, medium, high, xhigh, max, auto

也可以临时启动：

ompshell

omp --thinking high

7.3 工具审批

ompconfig

tools:
  approvalMode: yolo

三种模式：

模式	自动批准	需要确认
`always-ask`	只读工具	写入、执行
`write`	只读、写入	执行
`yolo`	全部	无

可以按工具覆盖：

ompconfig

tools:
  approvalMode: write
  approval:
    bash: prompt
    edit: allow
    read: allow

启动时也可以：

ompshell

omp --approval-mode write
omp --yolo
omp --auto-approve

7.4 主题和外观

ompconfig

theme: dark: titanium light: light statusLine: preset: compact

symbolPreset: unicode

8. 快捷键

实际快捷键以 /hotkeys 为准。常见默认值：

快捷键	作用
`Ctrl+P`	向前切换模型角色
`Shift+Ctrl+P`	向后切换模型角色
`Alt+P`	临时选择模型
`Alt+M`	打开模型选择器
`Alt+Shift+P`	切换 plan mode
`Ctrl+R`	搜索 prompt 历史
`Ctrl+O`	展开或折叠工具输出
`Ctrl+T`	显示或隐藏 thinking block
`Shift+Tab`	循环 thinking level
`Ctrl+G`	用 `$EDITOR` / `$VISUAL` 编辑当前输入
`Ctrl+Q` 或 `Ctrl+Enter`	排队 follow-up 消息
`Alt+Up`	把队列消息拿回编辑器
`Alt+R`	重试上次失败回答
`Ctrl+L`	重置终端显示
`Ctrl+V`	粘贴图片或文本，终端支持时可直接贴图

自定义快捷键文件：

ompprompt

~/.omp/agent/keybindings.yml

示例：

ompconfig

app.model.cycleForward: Ctrl+P
app.model.selectTemporary: Alt+P
app.plan.toggle: Alt+Shift+P
app.history.search: []

空数组表示禁用这个动作。

9. 让 `omp` 自动理解项目

推荐项目结构：

ompprompt

repo/
  .omp/
    AGENTS.md
    RULES.md
    config.yml

9.1 `.omp/AGENTS.md`

放项目背景、架构、代码风格、测试命令、维护约定。

示例：

ompmarkdown

# Project instructions This is an Astro site using pnpm. Use Biome for formatting/linting: pnpm lint pnpm format

Before changing i18n, inspect config/site.yaml and src/i18n.

omp 启动时会自动加载它，不需要每次说“请阅读 AGENTS.md”。

9.2 `.omp/RULES.md`

放必须长期生效的硬规则。它是 sticky rules，会在长会话中持续靠近当前上下文。

示例：

ompmarkdown

Never commit or push unless explicitly asked.
Do not edit generated files.
Do not change pnpm-lock.yaml unless dependencies changed.

保持短小。长背景放 AGENTS.md。

9.3 其他兼容文件

omp 也能读取其他工具的约定：

.claude/CLAUDE.md
.gemini/GEMINI.md
.github/copilot-instructions.md
AGENTS.md
.agent/AGENTS.md
.agents/AGENTS.md

新项目建议优先使用 .omp/AGENTS.md 和 .omp/RULES.md。

10. Slash Commands：自定义常用提示

可以创建项目命令：

ompprompt

<repo>/.omp/commands/*.md

例如：

ompprompt

/home/miku/Documents/astro-koharu/.omp/commands/review.md

内容：

ompmarkdown

--- description: Review changed files for maintainability and regressions ---

Review the current changes. Focus on correctness, regressions, tests, and maintainability.

会话里输入：

ompprompt

/review

文件命令支持参数：

ompmarkdown

Fix issue $1. Scope: $ARGUMENTS

调用：

ompprompt

/fix 123 mobile nav broken on Safari

$1 是第一个参数，$ARGUMENTS 是所有参数。

11. Skills：可复用能力包

Skill 是一个带说明的知识或工作流包。布局：

ompprompt

<skills-root>/
  my-skill/
    SKILL.md

12. Magic Keywords：临时增强一轮任务

这些是特殊关键词，必须小写、独立成词。

关键词	作用
`ultrathink`	要求这一轮更仔细地多步推理；自动 thinking 开启时会提高思考等级
`orchestrate`	要求使用多代理编排：拆分、并行、验证、直到完成
`workflowz`	要求构建并运行确定性的多子代理工作流，适合大范围研究、审查、迁移

示例：

ompprompt

ultrathink 分析这个 build failure 的根因，不要先改代码

ompprompt

orchestrate 完成 docs/plan.md 里的迁移，并跑验证

ompprompt

workflowz 对认证相关改动做一次对抗性 review

注意：

Ultrathink 不触发，必须是 ultrathink。
orchestrated 不触发，必须是独立词 orchestrate。
代码块、行内代码里的关键词不触发。

关闭：

ompshell

omp config set magicKeywords.enabled false
omp config set magicKeywords.ultrathink false
omp config set magicKeywords.orchestrate false
omp config set magicKeywords.workflow false

13. 子代理与并行任务

omp 支持子代理。普通用户通常不用直接操作它们，只要明确要求“并行检查”，或使用 orchestrate / workflowz。

适合并行的任务：

ompprompt

orchestrate 审查这个项目的性能、安全、可访问性和构建配置，分别给出问题和修复建议

ompprompt

workflowz 扫描 src/pages、src/components、src/lib 三块，找出未使用代码和潜在类型问题

常见内置子代理类型：

scout：只读探索，适合快速查代码。
reviewer：代码审查。
designer：UI/UX。
librarian：查外部库或 API。
sonic：机械性收集或简单批量改动。
默认通用任务代理。

子代理完成后会有 transcript，可以继续追问它们；系统内部通过 agent://... 和 history://... 保存输出和历史。

14. 典型项目工作流

14.1 解释代码

ompprompt

解释 astro-koharu 的内容加载流程：从 src/content 到页面渲染，指出关键文件和数据结构

适合先理解，不急着改。

14.2 修 bug

ompprompt

复现 pnpm build 的错误，定位根因并修复。改完必须再次运行 pnpm build 验证。

14.3 新功能

ompprompt

给站点添加文章系列页。要求：
1. 使用现有内容集合和 i18n 约定
2. 不新增无必要抽象
3. 保持 pnpm build 通过
4. 如果有现有测试/检查命令，运行覆盖相关路径的验证

14.4 UI 改动

ompprompt

修改移动端导航交互。完成后启动 dev server，用浏览器验证 375px 宽度下菜单能打开、关闭、导航。

UI 改动最好明确要求浏览器验证。

14.5 重构

ompprompt

重构 src/lib 下的日期格式化逻辑，统一调用点。必须先找所有引用，不能留下兼容 shim。

如果涉及跨文件符号重命名，omp 应优先使用语言服务器做引用查找和重命名，避免漏 callsite。

15. 和文件、图片、网页一起工作

可以给路径：

ompprompt

阅读 src/pages/index.astro，解释页面数据来源

指定范围：

ompprompt

只看 src/lib/posts.ts 和 config/site.yaml，解释文章 metadata 怎么生成

让它读 URL：

ompprompt

根据 https://docs.astro.build/en/guides/content-collections/ 检查我们项目的写法是否过时

给图片：

ompprompt

看这张截图，指出移动端布局哪里有问题

它能处理：

本地文件。
目录。
压缩包。
SQLite。
PDF / Office 文档。
图片。
URL。
GitHub issue / PR 缓存资源。
内部资源，如 skill://、agent://、artifact://。

16. 常用 CLI 示例

16.1 用指定模型启动

ompshell

omp --model anthropic/claude-sonnet-4-5

16.2 设置 slow / smol / plan 模型

ompshell

omp --smol openai/gpt-4.1-mini
omp --slow anthropic/claude-opus-4-5:high
omp --plan anthropic/claude-opus-4-5

16.3 指定审批模式

ompshell

omp --approval-mode write
omp --yolo

16.4 用一次性配置

ompshell

omp --config ./omp.local.yml "检查构建"

16.5 查看本地使用统计

ompshell

omp stats
omp stats --summary
omp stats --json

omp stats 会读取本地 session 日志，默认开启一个 dashboard。

17. 针对 astro-koharu 的建议配置

建议在项目里放：

ompprompt

/home/miku/Documents/astro-koharu/.omp/AGENTS.md
/home/miku/Documents/astro-koharu/.omp/RULES.md
/home/miku/Documents/astro-koharu/.omp/config.yml

17.1 `.omp/AGENTS.md` 示例

ompmarkdown

# astro-koharu project instructions This is an Astro site using pnpm. Common commands: pnpm build pnpm check pnpm lint pnpm format Before changing content or i18n, inspect: config/site.yaml config/i18n-content.yaml src/i18n src/content

Prefer existing components and styling conventions. Do not introduce a second state-management or styling convention.

17.2 `.omp/RULES.md` 示例

ompmarkdown

Do not commit or push unless explicitly asked.
Do not edit generated files.
Do not change pnpm-lock.yaml unless dependencies changed.
Run the narrowest meaningful verification before reporting completion.

17.3 `.omp/config.yml` 示例

ompconfig

tools: approvalMode: write approval: bash: prompt defaultThinkingLevel: high lsp: enabled: true

theme: dark: titanium

18. 最重要的使用习惯

从项目根目录启动。

ompshell

cd /home/miku/Documents/astro-koharu
omp

给目标、范围、验收。

比“帮我优化”更好的是：

ompprompt

优化首页图片加载，不能改内容 schema，pnpm build 必须通过

复杂问题先调查再改。

ompprompt

先定位根因，给出证据，再改代码

UI 任务要求浏览器验证。

只跑 build 不足以证明 UI 行为正确。
大任务用 orchestrate 或 workflowz。

适合并行审查、迁移和验证。
把长期规则写进 .omp/AGENTS.md / .omp/RULES.md。

不要每次重复告诉 agent 项目约定。
用 /resume 和 --continue 保持上下文。

长项目不要每次开新会话。
用 /fork 做实验。

想尝试不同实现路线时 fork，避免污染原会话。

plain

Oh My Pi 终端风格使用手册

Oh My Pi 使用手册

1. Oh My Pi 是什么

2. 第一次使用：登录模型供应商

2.1 交互式登录

2.2 环境变量方式

3. 基本交互方式

4. 常用斜杠命令

4.1 设置与快捷键

4.2 模型与登录

4.3 工作目录

4.4 会话管理

4.5 导出与分享

5. 会话恢复与导出

5.1 继续最近会话

5.2 选择恢复

5.3 用 id 或路径恢复

5.4 从已有会话 fork

5.5 导出历史会话

6. 配置系统

6.1 全局配置

6.2 项目配置

6.3 一次性配置 overlay

6.4 配置优先级

7. 常用配置项

7.1 模型角色

7.2 思考等级

7.3 工具审批

7.4 主题和外观

8. 快捷键

9. 让 omp 自动理解项目

9.1 .omp/AGENTS.md

9.2 .omp/RULES.md

9.3 其他兼容文件

10. Slash Commands：自定义常用提示

11. Skills：可复用能力包

Skill body

12. Magic Keywords：临时增强一轮任务

13. 子代理与并行任务

14. 典型项目工作流

14.1 解释代码

14.2 修 bug

14.3 新功能

14.4 UI 改动

14.5 重构

15. 和文件、图片、网页一起工作

16. 常用 CLI 示例

16.1 用指定模型启动

16.2 设置 slow / smol / plan 模型

16.3 指定审批模式

16.4 用一次性配置

16.5 查看本地使用统计

17. 针对 astro-koharu 的建议配置

17.1 .omp/AGENTS.md 示例

17.2 .omp/RULES.md 示例

17.3 .omp/config.yml 示例

18. 最重要的使用习惯

9. 让 `omp` 自动理解项目

9.1 `.omp/AGENTS.md`

9.2 `.omp/RULES.md`

17.1 `.omp/AGENTS.md` 示例

17.2 `.omp/RULES.md` 示例

17.3 `.omp/config.yml` 示例