Skip to content

/maigo:doctor

開始命令時先讀 skills/model-dispatch 並消費 --model-profile <path>；執行角色前依宿主能力解析派工，無 subagents 時依序執行。

「哪裡不舒服嗎。讓我看看。」 —— 🌑 Mortis

檢查 Maigo 運行所需的外部依賴與配置是否到位。

檢查項目

  1. 環境依賴：
  2. gh CLI：是否安裝、是否已登入（用 gh auth status）。
  3. git：是否可用。
  4. python3：版本是否 ≥ 3.13。
  5. Maigo 配置：
  6. ~/.config/maigo/memory/：目錄是否存在。
  7. MEMORY.md：索引檔是否存在且格式正確。
  8. 專案配置：
  9. .claude/test-command：是否有自定義測試指令。
  10. .claude/skip-test-verification：是否被標記跳過。
  11. Taki 試跑：嘗試偵測當前專案類型並跑一個最小化的檢查（例如 ruff --version 或嘗試跑一個不存在的 test 來確認 test runner 有反應）。
  12. Retry / failure 統計（read-only，只讀不清）：讀 .maigo/soyo-must-fix.jsonl （🟡 爽世 must-fix 觸發，teammate_quality_check.py 寫入）與 .maigo/test-failures.jsonl （🟣 立希 test failure 觸發，verify_completion.py 寫入），彙整各 key 的觸發次數 + 最近 3 筆摘要。兩個 log 都是相對當前 repo 的 .maigo/ 底下，不存在或是空的 → 印正常訊息 （新環境 / 還沒觸發過 retry 本來就不該有），不算 error。
  13. Token usage（read-only）：讀 .maigo/token-usage.jsonl，彙整最近 7 天總量並依角色／model 分組。只採用 harness 已提供的 foreground subagent metadata；背景 agent、Codex 或舊版 harness 沒資料時標示 unavailable，不自行估算、不算 error。
  14. .maigo/ 型錄（read-only，只列不刪）：呼叫 python3 "${CLAUDE_PLUGIN_ROOT}/scripts/maigo_dir_catalog.py" 掃描 .maigo/ 頂層 *.md 檔與 review/*/*.md、issue/*/*.md 兩層巢狀 檔，分成六類——已在巢狀佈局的（nested）、非巢狀 kind（plan）的識別碼 命名（identifier_named，plan-<id>.md 這類）、巢狀 kind 分目錄前的 扁平檔（flat_identifier，review-rubric-<id>.md 這類，待遷移）、已知 種類的舊固定檔名（legacy_fixed_name，.maigo/plan.md 這類，代表升級前 留下的孤兒）、已登記的非 artifact 檔（registered_non_artifact， board.md／review-board.md）、其餘全部歸為未登記檔案 （unregistered）。flat_identifier、legacy_fixed_name 與 unregistered 都只列出來，不自動刪除、不建議刪除哪一個，由使用者 自己決定；flat_identifier 與 legacy_fixed_name 可用 python3 "${CLAUDE_PLUGIN_ROOT}/scripts/migrate_legacy_artifacts.py"（先 dry-run 看清單，使用者同意後 --apply）搬進巢狀佈局，見 artifact-ownership 與 docs/reference/artifacts.md）。

流程

  1. Orchestrator：
  2. 執行 gh --version 與 gh auth status。
  3. 執行 python3 --version。
  4. 檢查 ~/.config/maigo/memory/ 路徑。
  5. 立希 (Taki)：
  6. 執行專案偵測。
  7. 報告當前專案被識別為什麼類型。
  8. 嘗試執行基本 lint/test 指令（dry-run 模式，不要求過，只要求「能跑」）。
  9. Orchestrator：讀 retry / failure log，彙整統計（不存在 / 空 → 印正常訊息，不中止）：
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/retry_log_summary.py"
  1. Orchestrator：讀 token usage metadata（Claude Code plugin 安裝環境用 ${CLAUDE_PLUGIN_ROOT} 定位；在 Maigo repo 開發時可直接用 scripts/）：
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/token_usage_summary.py" --root "$PWD"
  1. Orchestrator：跑 python3 "${CLAUDE_PLUGIN_ROOT}/scripts/maigo_dir_catalog.py" 拿到 .maigo/ 六類分類，只回報路徑，不刪除、不建議刪除哪一個；flat_identifier／ legacy_fixed_name 若非空，提醒使用者可跑 python3 "${CLAUDE_PLUGIN_ROOT}/scripts/migrate_legacy_artifacts.py" 搬進巢狀佈局。
  2. Orchestrator：
  3. 彙整報告。
  4. 針對缺失項給予具體的「改進」建議（不使用「優化」）。

輸出格式

# Maigo Doctor Report

## 🟢 環境 (Environment)
- [x] Python 3.13.0 — OK
- [ ] gh CLI — Not found or not logged in. (建議：安裝 gh 並跑 gh auth login)
- [x] git — OK

## 🟡 記憶 (Memory)
- [x] Directory: ~/.config/maigo/memory/ — OK
- [ ] Index: MEMORY.md — Not found. (建議：建立 MEMORY.md 以啟用跨專案記憶)

## 🔵 專案 (Project: <repo_name>)
- Detected type: <type>
- Verifier (Taki): <status>
- Test command: `<cmd>`

## 🔁 Retry / Failure 統計
- `.maigo/soyo-must-fix.jsonl`：<N 筆，或「無紀錄（正常）」> — <key×次數 摘要>
- `.maigo/test-failures.jsonl`：<N 筆，或「無紀錄（正常）」> — <key×次數 摘要>
- 最近 3 筆：<ts — key>

## 🪙 Token Usage
- <一行 metadata 摘要；無資料時說明 unavailable，不推估>

## 📦 舊產物孤兒檔（升級前的固定檔名，只列不刪）
- <`.maigo/plan.md` 等舊檔名清單，或「無孤兒檔」>

## ❓ 未登記檔案（不屬於任何已知 artifact 種類，只列不動）
- <不在 `_KNOWN_KINDS` 識別碼命名 / 舊固定檔名 / 已登記非 artifact 檔（`board.md`）
  三類白名單內的頂層 `.maigo/*.md` 檔清單，或「無未登記檔案」——不建議刪除哪一個>

## 📢 建議
- ...

Orchestrator 守則

  • 旁白：orchestrator 對使用者說話時戴上旁白的臉——開場、收場、卡關節點由 🌙 Doloris / 🌑 Mortis 旁白，依 skills/narration。
  • 對話：對話本體（旁白節點以外）的互動節奏與用詞，依 skills/orchestrator-voice。
  • 依 model-dispatch 執行 🟣 Taki 的檢查階段；沒有 subagents 時在主線執行，照常回報實際檢查結果
  • 報告最終由 orchestrator 彙整，不是 Taki 直接輸出
  • 不論任何項目缺失，都要完整跑完所有檢查項目再彙整，不中途停止
  • 完成後給使用者一份最終報告：環境狀態、缺失項清單、具體改進建議