Maestro健康检查医生Skill doctor

---

name: doctor description: 诊断和修复 Maestro 安装问题 argument-hint: “[–fix] [–check <name>]” allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion disable-model-invocation: true

医生 — Maestro 健康检查

诊断安装问题，检测配置漂移，并自动修复常见问题。

参数

• [--fix] — 自动修复具有安全自动补救措施的问题。
• [--check <name>] — 仅运行一个检查。

有效检查名称：

• agent-teams
• hooks
• state-dirs
• stale-state
• plugin
• claude-md
• permissions
• orphaned-teams

如果 --check 提供了未知名称，停止并显示有效选项。

硬性规则

• 运行所有检查，除非指定了 --check <name>。
• 将每个结果分类为 OK、WARN 或 CRITICAL。
• 保持检查特定于 Maestro。不运行 oh-my-claudecode 诊断。
• 在 --fix 模式下，仅自动应用安全修复。对于破坏性修复，先询问。

健康检查

运行以下每个检查并捕获状态和详细信息。

1. 代理团队 (agent-teams)

检查在 ~/.claude/settings.json 中 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 是否设置为 "1"。

jq -r '.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS // empty' ~/.claude/settings.json

• OK: 值为 "1"
• CRITICAL: 缺失或不是 "1"（代理团队已禁用）

–fix 补救措施:

• 安全。在 ~/.claude/settings.json 中添加/更新 env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 为 "1"。
• 保留现有设置键。

2. 钩子完整性 (hooks)

验证 .claude/hooks/hooks.json 是有效的 JSON，并且所有引用的脚本都存在并通过 shell 语法检查。

jq . .claude/hooks/hooks.json > /dev/null

对于 hooks.json 中的每个脚本命令引用，验证：

bash -n <script_path>

• OK: hooks.json 有效，脚本存在，所有 bash -n 检查通过
• CRITICAL: hooks.json 缺失或 JSON 无效
• WARN: 一个或多个脚本路径缺失，或脚本有语法错误

–fix 补救措施:

• 不自动更改钩子定义。
• 如果仅缺失执行位，依赖检查 7 的修复。
• 否则报告需要手动补救。

3. 状态目录 (state-dirs)

检查必需的 Maestro 状态目录：

• .maestro/plans/

• .maestro/archive/

• .maestro/wisdom/

• .maestro/drafts/

• .maestro/handoff/

• .maestro/research/

• OK: 所有目录都存在

• WARN: 一个或多个目录缺失

–fix 补救措施:

• 安全。创建缺失目录：

mkdir -p .maestro/plans .maestro/archive .maestro/wisdom .maestro/drafts .maestro/handoff .maestro/research

4. 陈旧状态 (stale-state)

检查陈旧文件：

• 移交文件 (.maestro/handoff/*.json) 超过 24 小时，其中 status 为 "executing" 或 "designing"
• 草稿文件 (.maestro/drafts/*) 超过 48 小时

find .maestro/handoff -name "*.json" -mtime +0 2>/dev/null
find .maestro/drafts -type f -mtime +2 2>/dev/null

对于移交候选者，读取 JSON 并仅包括状态为 executing 或 designing 的。

• OK: 没有陈旧文件
• WARN: 找到陈旧文件（列出文件路径）

–fix 补救措施:

• 潜在破坏性（文件删除）。在移除前使用 AskUserQuestion 请求确认。
• 如果批准，移除陈旧移交/草稿文件并报告每个删除的路径。

5. 插件清单 (plugin)

验证 .claude-plugin/plugin.json 是有效的 JSON。

jq . .claude-plugin/plugin.json > /dev/null

• OK: JSON 有效
• CRITICAL: 文件缺失或 JSON 无效

–fix 补救措施:

• 没有安全的自动修复。报告需要手动干预。

6. CLAUDE.md 新鲜度 (claude-md)

检查项目 CLAUDE.md 中预期的 Maestro 标记：

grep -q "## Commands" CLAUDE.md
grep -q "## Architecture" CLAUDE.md

• OK: 两个标记都存在
• WARN: 缺少一个或两个标记（文件可能已过时）

–fix 补救措施:

• 不自动重写。报告需要手动刷新。

7. 脚本权限 (permissions)

检查 .claude/scripts/*.sh 中的所有脚本是否可执行。

find .claude/scripts -name "*.sh" ! -perm -u+x

• OK: 所有脚本都可执行
• WARN: 找到一个或多个不可执行的脚本（列出路径）

–fix 补救措施:

• 安全。对每个不可执行的脚本运行 chmod +x。

8. 孤立团队 (orphaned-teams)

检查可能陈旧的团队目录：

ls ~/.claude/teams/ 2>/dev/null

将团队目录视为可疑，如果它们不匹配当前会话中的活动工作。

• OK: 没有找到目录，或仅当前活动团队
• WARN: 找到潜在的孤立团队目录（列出名称）

–fix 补救措施:

• 不自动删除团队目录。
• 推荐运行 /reset 进行清理。
• 如果用户明确请求删除，先请求确认。

报告格式

显示结果为：

## Maestro 医生报告

### 摘要
[健康 / 发现问题（N 警告，M 严重）]

### 检查

| # | 检查 | 状态 | 详情 |
|---|-------|--------|---------|
| 1 | 代理团队 | OK | 在 settings.json 中启用 |
| 2 | 钩子完整性 | OK | hooks.json 有效，脚本有效 |
| 3 | 状态目录 | WARN | 缺失：research/ |
| 4 | 陈旧状态 | OK | 没有陈旧文件 |
| 5 | 插件清单 | OK | JSON 有效 |
| 6 | CLAUDE.md | OK | 所有标记存在 |
| 7 | 脚本权限 | OK | 所有脚本可执行 |
| 8 | 孤立团队 | WARN | 找到团队目录：... |

如果存在问题，附加：

• ### 发现问题（项目符号列表）
• ### 推荐操作（手动下一步）

自动修复（--fix 标志）

当 --fix 存在且发现问题时：

1. 列出所有可修复的问题。
2. 自动应用安全修复：
   • 代理团队环境条目
   • 缺失状态目录
   • 脚本执行权限
3. 对于破坏性修复（陈旧文件删除），先请求确认。
4. 每次应用修复后重新运行受影响的检查。
5. 以以下结束：

### 自动修复结果
修复了 N 个问题。M 个问题需要手动干预。

如果没有找到可修复问题，明确说明。