# pi-oc-style-agent-switcher

[**English**](README.md)

為 [Pi](https://pi.dev) 提供鍵盤驅動的主 agent **model** 切換功能，靈感來自
opencode 的 `<a-left>` / `<a-right>` agent 切換。

## 安裝

```bash
pi install npm:pi-oc-style-agent-switcher
```

重新載入 Pi：`/reload`

## Agent 設定檔

`agent` 區塊可視為參考 OpenCode 的 primary-agent 配置方式。在
`~/.pi/agent/settings.json` 定義可切換的 profile；本套件只會讀取其 `model`
欄位。`mode` 是選填；未填時仍可切換。若明確設為 `mode: "subagent"`，目前
只保留語意，不會進入切換清單，未來才可能擴充相關行為。

為了相容 OpenCode，`agent.<name>` 也可使用同層的 `variant` 欄位；但同一個
agent entry 不可同時設定 `thinking` 與 `variant`。

### 範例：OpenCode 風格的 `agent`

```json
{
  "agent": {
    "opencodezen": {
      "model": "opencode/deepseek-v4-flash-free",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "build": {
      "mode": "primary",
      "model": "opencode/deepseek-v4-flash-free",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "orchestrator": {
      "model": "github-copilot/claude-sonnet-4.6",
      "variant": "high"
    }
  }
}
```

`<project>/.pi/settings.json` 會逐欄覆寫 global 設定。

### 範例：專案覆寫

```json
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "model": "openai-codex/gpt-5.4"
    }
  }
}
```

若 global 設定內有 `opencodezen`、`build`、`orchestrator`，而這個專案只覆寫
`orchestrator.model`，則切換器仍會看到相同的 primary profiles，只是使用這個
專案專屬的 orchestrator model。

切換器在有設定時會讀取 `agent.<name>.model` 來切 Pi 目前使用的 model；若
選到的 `build` 或 `orchestrator` profile 沒有設定 `agent.<name>.model`，就沿用
目前 session 的 model，並保留當前 thinking level 不變。當選到
`orchestrator` 時，本套件會依照以下順序取第一個可用的 prompt 正文並附加到主
session 的 system prompt：專案內 `.pi/agents/orchestrator.md` → 全域
`~/.pi/agent/agents/orchestrator.md` → 套件內 fallback
`templates/agents/orchestrator.md`。`build` 則維持普通主 session 模式，不會
自動注入特殊 prompt。為了相容 OpenCode，它也接受 `tools` 的布林物件寫法，但
目前不會實際套用這些 tools。`thinking` 與所有 `/run <agent>` child session
行為，仍交由 Pi 與已安裝的 subagent 套件處理。本套件不會呼叫 subagent。

`mode: "subagent"` 的語意保留給未來功能；目前 child agent 的執行方式仍由
subagent 套件自行管理。

合法：

```json
{
  "agent": {
    "A": { "thinking": "high" },
    "B": { "variant": "low" }
  }
}
```

不合法：

```json
{
  "agent": {
    "A": {
      "thinking": "high",
      "variant": "low"
    }
  }
}
```

### Subagent 設定

child agent 的行為應依你使用的 subagent 套件來配置。若是 `pi-subagents`，
則使用 `subagents.agentOverrides`。

```json
{
  "subagents": {
    "agentOverrides": {
      "orchestrator": {
        "model": "github-copilot/claude-sonnet-4.6",
        "thinking": "high",
        "tools": [
          "read",
          "grep",
          "find",
          "ls",
          "bash",
          "edit",
          "write",
          "subagent",
          "wait",
          "web_search",
          "fetch_content",
          "get_search_content"
        ]
      },
      "explorer": {
        "model": "github-copilot/gpt-5-mini",
        "thinking": "low",
        "tools": ["read", "grep", "find", "ls", "bash"]
      }
    }
  }
}
```

這裡就是用來微調 `orchestrator` 作為 child session 時的細節。若你偏好，也可以
把這些細節直接寫在 `~/.pi/agent/agents/orchestrator.md` 的 frontmatter，而不是
放在 JSON。若 orchestrator prompt 正文還會點名 `researcher`、`reviewer`、
`scout`、`worker` 這類額外 child helper，也要讓這些名稱和 Pi 的 child-agent
定義對齊：不是補進 `subagents.agentOverrides`，就是明確依賴 builtin subagent
預設。

首次載入時，若 `~/.pi/agent/agents/orchestrator.md` 與
`<project>/.pi/agents/orchestrator.md` 都不存在，套件會把內建 fallback 模板
複製到 `~/.pi/agent/agents/orchestrator.md`，讓 `/run orchestrator` 無須額外設定
即可使用。

## 按鍵

| 按鍵 | 功能 |
|---|---|
| `Alt+Shift+←` `Alt+Shift+→` | 選擇並套用上一個／下一個主 agent model |
| `/agents` | 顯示可切換 profile 與按鍵 |

### 改用 `Alt+←/→`

本套件自己的快捷鍵設定讀自 `~/.pi/agent/agent-switcher.json`。
只改 `~/.pi/agent/keybindings.json` 並不夠。

`~/.pi/agent/agent-switcher.json`：

```json
{ "cyclePrev": "alt+left", "cycleNext": "alt+right" }
```

在 `~/.pi/agent/keybindings.json` 釋放 Pi 的衝突鍵位：

```json
{
  "tui.editor.cursorWordLeft": [],
  "tui.editor.cursorWordRight": [],
  "app.tree.foldOrUp": [],
  "app.tree.unfoldOrDown": [],
  "app.model.cycleBackward": ["alt+shift+left"],
  "app.model.cycleForward": ["alt+shift+right"]
}
```

## 從 oh-my-opencode-slim 遷移

本套件內建兩個互補 skill：

```text
/skill:omo-slim-conf-mig [all|global|local]
/skill:omo-slim-mig      [all|global|local]
```

`omo-slim-conf-mig` 讀取使用者本機 global/local OpenCode JSONC，遷移明確設定；
`omo-slim-mig` 則讀取 upstream raw GitHub README 與 agent prompt，只補齊未設定
的值。若已存在 `orchestrator.md`，`omo-slim-mig` 會先和 upstream 轉換後的 Pi
版本比對，再詢問是否同步。兩者都支援 `all`、`global`、`local`；都會確保全域
orchestrator prompt 存在，且即使來源缺少，也會建立 `agent.orchestrator`。

將 oh-my-opencode-slim 作為 agent prompt 與 JSON 配置的遷移參考。可切換的主
model 設定在 `agent`；child agent 的 model、thinking、tools 與 prompt 則設定在
`subagents.agentOverrides`。

### 必備的全域 Orchestrator Prompt

每次遷移預設都必須建立：

```text
~/.pi/agent/agents/orchestrator.md
```

此檔案承載 orchestrator 的角色 prompt。使用 YAML frontmatter 定義身分與 Pi
行為，並在其後放入轉換後的系統提示詞本體：

```markdown
---
name: orchestrator
description: Master delegator and strategic coordinator
systemPromptMode: replace
inheritProjectContext: true
inheritSkills: false
---

<Role>
Converted orchestrator instructions from oh-my-opencode-slim.
</Role>
```

除非專案確實需要不同的角色 prompt，否則不要建立 project-local
`orchestrator.md`。model、thinking、tools 可留在此檔案、
`subagents.agentOverrides`，或使用 Pi 預設；若預期由 `agentOverrides`
控制某欄位，請勿在 frontmatter 重複該欄位。建立或同步這份 prompt 時，請保留
明確的 Pi child-agent roster：`explorer`、`librarian`、`oracle`、`designer`、
`fixer`、`observer`、`council` 應作為主要 specialists；若這些 child-agent
名稱可用，則再把 `researcher`、`reviewer`、`scout`、`worker` 補成 workflow
helpers。不要把 `build`、`opencodezen` 這種 main-session profile 寫成 child
specialist。

### 遷移方法

若要直接採用 HTTP upstream 遷移、而非執行 `/skill:omo-slim-mig`，可複製其中
一組 prompt 給 LLM agent（Claude Code、Cursor 等）。LLM 應把連結中的指南當作
參考，**不可**安裝或修改 oh-my-opencode-slim。

**global**：遷移全域配置

```
Use oh-my-opencode-slim as a migration reference:
https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/master/README.md

Do not install or modify oh-my-opencode-slim. Read its README and relevant
src/agents/*.ts files, then migrate my global configuration to Pi:

1. Put switchable primary model profiles in ~/.pi/agent/settings.json → agent.
   Keep only agents intended for model switching, with mode: "primary".
2. Put child-agent model, thinking, tools, and prompt overrides in
   ~/.pi/agent/settings.json → subagents.agentOverrides.
3. Always ensure ~/.pi/agent/agents/orchestrator.md exists using the required
   frontmatter/body format documented above.
4. If an orchestrator.md already exists, compare it with the upstream-based Pi
   version instead of overwriting it blindly. Summarize differences and ask
   whether to keep it, sync only Pi/subagent integration parts, or fully sync.
5. When you create or sync orchestrator.md, preserve an explicit Pi child-agent
   roster. Keep `explorer`, `librarian`, `oracle`, `designer`, `fixer`,
   `observer`, and `council` as primary specialists, and add `researcher`,
   `reviewer`, `scout`, and `worker` as workflow helpers when available. Do not
   list main-session profiles like `build` or `opencodezen` as specialists.
6. Create other global agent markdown files only when their role prompts are
   needed.
7. Preserve existing unrelated Pi settings.
```

**local**：遷移單一專案

```
Use oh-my-opencode-slim as a migration reference:
https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/master/README.md

Do not install or modify oh-my-opencode-slim. Read its README and relevant
src/agents/*.ts files, then migrate configuration for this Pi project only:

1. Write project primary-model overrides to .pi/settings.json → agent.
2. Write project child-agent overrides to
   .pi/settings.json → subagents.agentOverrides.
3. Keep ~/.pi/agent/agents/orchestrator.md as the default orchestrator prompt.
4. If an orchestrator.md already exists, compare it against the upstream-based
   Pi version first. Summarize differences and ask whether to keep it, sync
   only Pi/subagent integration details, or fully sync.
5. When you create or sync orchestrator.md, preserve an explicit Pi child-agent
   roster. Keep `explorer`, `librarian`, `oracle`, `designer`, `fixer`,
   `observer`, and `council` as primary specialists, and add `researcher`,
   `reviewer`, `scout`, and `worker` as workflow helpers when available. Do not
   list main-session profiles like `build` or `opencodezen` as specialists.
6. Create .pi/agents/orchestrator.md only when this project needs a genuinely
   different orchestrator role prompt.
7. Create other .pi/agents/*.md only for project-specific prompt overrides.
8. Preserve global Pi configuration and unrelated project settings.
```

**global+local**：遷移共用配置與專案覆寫

```
Use oh-my-opencode-slim as a migration reference:
https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/master/README.md

Do not install or modify oh-my-opencode-slim. Migrate shared configuration to
~/.pi/agent/settings.json, then add only differing project values to
.pi/settings.json:

1. Primary model switch profiles belong in agent.
2. Child subagent behavior belongs in subagents.agentOverrides.
3. Always ensure ~/.pi/agent/agents/orchestrator.md exists as the shared
   default prompt.
4. If an orchestrator.md already exists, do not overwrite it blindly. Compare
   the current file with the upstream-based Pi version, summarize the
   differences (especially Pi/subagent integration vs upstream workflow drift),
   and ask whether to keep it, sync only integration parts, or fully sync.
5. When you create or sync orchestrator.md, preserve an explicit Pi child-agent
   roster. Keep `explorer`, `librarian`, `oracle`, `designer`, `fixer`,
   `observer`, and `council` as primary specialists, and add `researcher`,
   `reviewer`, `scout`, and `worker` as workflow helpers when available. Do not
   list main-session profiles like `build` or `opencodezen` as specialists.
6. Create a project-local replacement only for a genuinely different role
   prompt.
7. Use project settings only to override model/thinking/tools/prompt fields
   that differ from global settings.
8. Preserve all unrelated existing JSON fields and agent files.
```

### 概念對照

| oh-my-opencode-slim | Pi 對應 |
|---|---|
| OpenCode primary `agent` | `settings.json → agent` |
| oh-my agent model/variant | `subagents.agentOverrides.<name>.model/thinking` |
| `@agentName` | `subagent({ agent: "name", ... })` |
| `task(background: true)` | `subagent({ async: true })` |
| Agent prompt 在 `src/agents/*.ts` | `~/.pi/agent/agents/*.md` 或 `.pi/agents/*.md` |

## License

MIT