Back to Details

doctor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OrchestKit Health Diagnostics

OrchestKit健康诊断

Overview

概述

The 
/ork:doctor
command performs comprehensive health checks on your OrchestKit installation. It auto-detects installed plugins and validates 10 categories:
  1. Installed Plugins - Detects orkl or ork
  2. Skills Validation - Frontmatter, references, token budget (dynamic count)
  3. Agents Validation - Frontmatter, tool refs, skill refs (dynamic count)
  4. Hook Health - Registration, bundles, async patterns
  5. Permission Rules - Detects unreachable rules (CC 2.1.3 feature)
  6. Schema Compliance - Validates JSON files against schemas
  7. Coordination System - Checks lock health and registry integrity
  8. Context Budget - Monitors token usage against budget
  9. Memory System - Graph, Mem0, Fabric health
  10. Claude Code Version - Validates CC >= 2.1.16
/ork:doctor
命令会对您的OrchestKit安装执行全面的健康检查。它会自动检测已安装的插件并验证以下10个类别：
  1. 已安装插件 - 检测orkl或ork
  2. Skill验证 - 前置元数据、引用、token预算（动态计数）
  3. Agent验证 - 前置元数据、工具引用、Skill引用（动态计数）
  4. Hook健康状态 - 注册、捆绑包、异步模式
  5. 权限规则 - 检测不可达规则（CC 2.1.3新增功能）
  6. Schema合规性 - 验证JSON文件是否符合Schema规范
  7. 协调系统 - 检查锁健康状态和注册表完整性
  8. 上下文预算 - 监控token使用是否符合预算
  9. 内存系统 - Graph、Mem0、Fabric健康状态
  10. Claude Code版本 - 验证CC版本 >= 2.1.16

When to Use

使用场景

  • After installing or updating OrchestKit
  • When hooks aren't firing as expected
  • Before deploying to a team environment
  • When debugging coordination issues
  • After running 
    npm run build
  • 安装或更新OrchestKit之后
  • 当Hook未按预期触发时
  • 部署到团队环境之前
  • 调试协调问题时
  • 运行
    npm run build
    之后

Quick Start

快速开始

bash
/ork:doctor           # Standard health check
/ork:doctor -v        # Verbose output
/ork:doctor --json    # Machine-readable for CI
bash
/ork:doctor           # 标准健康检查
/ork:doctor -v        # 详细输出
/ork:doctor --json    # 机器可读格式，适用于CI

CLI Options

CLI选项

FlagDescription
-v
, 
--verbose
Detailed output per check
--json
JSON output for CI integration
--category=X
Run only specific category
标记描述
-v
, 
--verbose
详细输出每个检查的结果
--json
输出JSON格式结果，用于CI集成
--category=X
仅运行指定类别的检查

Health Check Categories

健康检查类别

0. Installed Plugins Detection

0. 已安装插件检测

Auto-detects which OrchestKit plugins are installed:
bash
undefined
自动检测已安装的OrchestKit插件：
bash
undefined

Detection logic:

检测逻辑:

- Scans for .claude-plugin/plugin.json in plugin paths

- 扫描插件路径中的.claude-plugin/plugin.json

- Identifies orkl or ork

- 识别orkl或ork

- Counts skills/agents per installed plugin

- 统计每个已安装插件的Skill/Agent数量


**Output (orkl):**
Installed Plugins: 1
  • orkl: 109 skills, 36 agents, 119 hook entries

**Output (ork full):**
Installed Plugins: 1
  • ork: 200 skills, 36 agents, 119 hook entries
undefined

**输出（orkl）：**
Installed Plugins: 1
  • orkl: 109 skills, 36 agents, 119 hook entries

**输出（完整ork）：**
Installed Plugins: 1
  • ork: 200 skills, 36 agents, 119 hook entries
undefined

1. Skills Validation

1. Skill验证

Validates skills in installed plugins (count varies by installation):
bash
undefined
验证已安装插件中的Skill（数量因安装情况而异）：
bash
undefined

Checks performed:

执行的检查:

- SKILL.md frontmatter (name, description, user-invocable)

- SKILL.md前置元数据（名称、描述、用户可调用性）

- context: fork field (required for CC 2.1.0+)

- context: fork字段（CC 2.1.0+必填）

- Token budget compliance (300-5000 tokens)

- Token预算合规性（300-5000 tokens）

- Internal link validation (references/ paths)

- 内部链接验证（references/路径）

- Related Skills references exist

相关Skill引用是否存在


**Output (full ork):**
Skills: 186/186 valid
  • User-invocable: 24 commands
  • Reference skills: 163

**Output (orkl only):**
Skills: 18/18 valid
  • User-invocable: 0 commands
  • Reference skills: 18
undefined

**输出（完整ork）：**
Skills: 186/186 valid
  • User-invocable: 24 commands
  • Reference skills: 163

**输出（仅orkl）：**
Skills: 18/18 valid
  • User-invocable: 0 commands
  • Reference skills: 18
undefined

2. Agents Validation

2. Agent验证

Validates agents in installed plugins:
bash
undefined
验证已安装插件中的Agent：
bash
undefined

Checks performed:

执行的检查:

- Frontmatter fields (name, description, model, tools, skills)

- 前置元数据字段（名称、描述、模型、工具、Skills）

- Model validation (opus, sonnet, haiku only)

- 模型验证（仅支持opus、sonnet、haiku）

- Skills references exist in src/skills/

- Skills引用在src/skills/中是否存在

- Tools are valid CC tools

- 工具是否为有效的CC工具


**Output:**
Agents: 35/35 valid
  • Models: 12 sonnet, 15 haiku, 8 opus
  • All skill references valid
undefined

**输出：**
Agents: 35/35 valid
  • Models: 12 sonnet, 15 haiku, 8 opus
  • All skill references valid
undefined

3. Hook Health

3. Hook健康状态

Verifies hooks are properly configured:
bash
undefined
验证Hook是否配置正确：
bash
undefined

Checks performed:

执行的检查:

- hooks.json schema valid

- hooks.json Schema是否有效

- Bundle files exist (11 .mjs bundles)

- 捆绑包文件是否存在（11个.mjs捆绑包）

- Async hooks use fire-and-forget pattern (6 async)

- 异步Hook是否使用即发即弃模式（6个异步Hook）

- Background hook metrics health (Issue #243)

- 后台Hook指标健康状态（Issue #243）


**Output:**
Hooks: 22/22 entries valid (11 bundles)
  • PreToolUse: 8, PostToolUse: 3, PermissionRequest: 3
  • Async hooks: 6 (fire-and-forget)
  • Error Rate: 0.3%

See [Hook Validation](references/hook-validation.md) for details.

**输出：**
Hooks: 22/22 entries valid (11 bundles)
  • PreToolUse: 8, PostToolUse: 3, PermissionRequest: 3
  • Async hooks: 6 (fire-and-forget)
  • Error Rate: 0.3%

详情请见[Hook验证](references/hook-validation.md)。

4. Memory System (NEW)

4. 内存系统（新增）

Validates 3-tier memory architecture with file-level integrity checks:
bash
undefined
通过文件级完整性检查验证三层内存架构：
bash
undefined

Automated checks:

自动检查:

- Tier 1 (Graph): .claude/memory/ exists, decisions.jsonl valid JSONL, queue depth

- 第一层（Graph）: .claude/memory/是否存在，decisions.jsonl是否为有效JSONL，队列深度

- Tier 2 (Mem0): MEM0_API_KEY detection, mem0-queue.jsonl depth, last sync

- 第二层（Mem0）: 是否检测到MEM0_API_KEY，mem0-queue.jsonl深度，最后同步时间

- Tier 3 (Fabric): Both tiers available, session registry

- 第三层（Fabric）: 前两层是否可用，会话注册表

Run these commands to gather memory health data:

运行以下命令收集内存健康数据:

wc -l .claude/memory/decisions.jsonl 2>/dev/null || echo "No decisions yet" wc -l .claude/memory/graph-queue.jsonl 2>/dev/null || echo "No graph queue" wc -l .claude/memory/mem0-queue.jsonl 2>/dev/null || echo "No mem0 queue" ls -la .claude/memory/ 2>/dev/null || echo "Memory directory missing"

Read `.claude/memory/decisions.jsonl` directly to validate JSONL integrity (each line must parse as valid JSON). Count total lines, corrupt lines, and report per-category breakdown.

**Output:**
Memory System: healthy
  • Graph Memory: 42 decisions, 0 corrupt, queue depth 3
  • Mem0 Cloud: available (API key detected), queue depth 0
  • Memory Fabric: active (both tiers)

See [Memory Health](references/memory-health.md) for details.
wc -l .claude/memory/decisions.jsonl 2>/dev/null || echo "No decisions yet" wc -l .claude/memory/graph-queue.jsonl 2>/dev/null || echo "No graph queue" wc -l .claude/memory/mem0-queue.jsonl 2>/dev/null || echo "No mem0 queue" ls -la .claude/memory/ 2>/dev/null || echo "Memory directory missing"

直接读取`.claude/memory/decisions.jsonl`以验证JSONL完整性（每行必须能解析为有效JSON）。统计总行数、损坏行数，并按类别细分报告。

**输出：**
Memory System: healthy
  • Graph Memory: 42 decisions, 0 corrupt, queue depth 3
  • Mem0 Cloud: available (API key detected), queue depth 0
  • Memory Fabric: active (both tiers)

详情请见[内存健康状态](references/memory-health.md)。

5. Build System (NEW)

5. 构建系统（新增）

Verifies plugins/ sync with src/:
bash
undefined
验证plugins/与src/是否同步：
bash
undefined

Checks performed:

执行的检查:

- plugins/ generated from src/

- plugins/是否由src/生成

- Manifest counts match actual files

- 清单计数与实际文件是否匹配

- No orphaned skills/agents

- 无孤立的Skills/Agents


**Output:**
Build System: in sync
  • Skills: 186 src/ = 186 plugins/
  • Agents: 35 src/ = 35 plugins/
  • Last build: 2 minutes ago
undefined

**输出：**
Build System: in sync
  • Skills: 186 src/ = 186 plugins/
  • Agents: 35 src/ = 35 plugins/
  • Last build: 2 minutes ago
undefined

6. Permission Rules

6. 权限规则

Leverages CC 2.1.3's unreachable permission rules detection:
Output:
Permission Rules: 12/12 reachable
利用CC 2.1.3的不可达权限规则检测功能：
输出：
Permission Rules: 12/12 reachable

7. Schema Compliance

7. Schema合规性

Validates JSON files against schemas:
Output:
Schemas: 15/15 compliant
验证JSON文件是否符合Schema规范：
输出：
Schemas: 15/15 compliant

8. Coordination System

8. 协调系统

Checks multi-worktree coordination health:
Output:
Coordination: healthy
- Active instances: 1
- Stale locks: 0
检查多工作树协调健康状态：
输出：
Coordination: healthy
- Active instances: 1
- Stale locks: 0

9. Context Budget

9. 上下文预算

Monitors token usage:
Output:
Context Budget: 1850/2200 tokens (84%)
监控token使用情况：
输出：
Context Budget: 1850/2200 tokens (84%)

10. Claude Code Version

10. Claude Code版本

Validates runtime version:
Output:
Claude Code: 2.1.25 (OK)
- Minimum required: 2.1.16
验证运行时版本：
输出：
Claude Code: 2.1.25 (OK)
- Minimum required: 2.1.16

Report Format

报告格式

Full ork plugin:
+===================================================================+
|                    OrchestKit Health Report                        |
+===================================================================+
| Version: 5.4.0  |  CC: 2.1.25  |  Plugins: ork + ork         |
+===================================================================+
| Skills           | 186/186 valid                                  |
| Agents           | 35/35 valid                                    |
| Hooks            | 22/22 entries (11 bundles)                     |
| Memory           | 3/3 tiers healthy                              |
| Permissions      | 12/12 reachable                                |
| Schemas          | 15/15 compliant                                |
| Context          | 1850/2200 tokens (84%)                         |
| Coordination     | 0 stale locks                                  |
| CC Version       | 2.1.25 (OK)                                    |
+===================================================================+
| Status: HEALTHY (9/9 checks passed)                               |
+===================================================================+
Domain-specific plugins (e.g., orkl + orkl):
+===================================================================+
|                    OrchestKit Health Report                        |
+===================================================================+
| Version: 5.4.0  |  CC: 2.1.25  |  Plugins: 3 installed            |
+===================================================================+
| Installed        | ork, orkl, orkl       |
| Skills           | 38/38 valid (combined)                         |
| Agents           | 2/2 valid                                      |
| Hooks            | 22/22 entries (via ork)                   |
| Memory           | 1/3 tiers (graph only)                         |
+===================================================================+
完整ork插件：
+===================================================================+
|                    OrchestKit Health Report                        |
+===================================================================+
| Version: 5.4.0  |  CC: 2.1.25  |  Plugins: ork + ork         |
+===================================================================+
| Skills           | 186/186 valid                                  |
| Agents           | 35/35 valid                                    |
| Hooks            | 22/22 entries (11 bundles)                     |
| Memory           | 3/3 tiers healthy                              |
| Permissions      | 12/12 reachable                                |
| Schemas          | 15/15 compliant                                |
| Context          | 1850/2200 tokens (84%)                         |
| Coordination     | 0 stale locks                                  |
| CC Version       | 2.1.25 (OK)                                    |
+===================================================================+
| Status: HEALTHY (9/9 checks passed)                               |
+===================================================================+
特定领域插件（如orkl + orkl）：
+===================================================================+
|                    OrchestKit Health Report                        |
+===================================================================+
| Version: 5.4.0  |  CC: 2.1.25  |  Plugins: 3 installed            |
+===================================================================+
| Installed        | ork, orkl, orkl       |
| Skills           | 38/38 valid (combined)                         |
| Agents           | 2/2 valid                                      |
| Hooks            | 22/22 entries (via ork)                   |
| Memory           | 1/3 tiers (graph only)                         |
+===================================================================+

JSON Output (CI Integration)

JSON输出（CI集成）

bash
/ork:doctor --json
json
{
  "version": "5.4.0",
  "claudeCode": "2.1.25",
  "status": "healthy",
  "plugins": {
    "installed": ["ork", "ork"],
    "count": 2
  },
  "checks": {
    "skills": {"passed": true, "count": 186, "perPlugin": {"ork": 186}},
    "agents": {"passed": true, "count": 35, "perPlugin": {"ork": 35}},
    "hooks": {"passed": true, "entries": 22, "bundles": 11, "source": "ork"},
    "memory": {"passed": true, "tiers": 3, "available": ["graph", "mem0", "fabric"]},
    "permissions": {"passed": true, "count": 12},
    "schemas": {"passed": true, "count": 15},
    "context": {"passed": true, "usage": 0.84},
    "coordination": {"passed": true, "staleLocks": 0},
    "ccVersion": {"passed": true, "version": "2.1.25"}
  },
  "exitCode": 0
}
bash
/ork:doctor --json
json
{
  "version": "5.4.0",
  "claudeCode": "2.1.25",
  "status": "healthy",
  "plugins": {
    "installed": ["ork", "ork"],
    "count": 2
  },
  "checks": {
    "skills": {"passed": true, "count": 186, "perPlugin": {"ork": 186}},
    "agents": {"passed": true, "count": 35, "perPlugin": {"ork": 35}},
    "hooks": {"passed": true, "entries": 22, "bundles": 11, "source": "ork"},
    "memory": {"passed": true, "tiers": 3, "available": ["graph", "mem0", "fabric"]},
    "permissions": {"passed": true, "count": 12},
    "schemas": {"passed": true, "count": 15},
    "context": {"passed": true, "usage": 0.84},
    "coordination": {"passed": true, "staleLocks": 0},
    "ccVersion": {"passed": true, "version": "2.1.25"}
  },
  "exitCode": 0
}

Exit Codes

退出码

CodeMeaning
0All checks pass
1One or more checks failed
代码含义
0所有检查通过
1一项或多项检查失败

Interpreting Results

结果解读

StatusMeaningAction
All checks passPlugin healthyNone required
Skills warningInvalid frontmatterRun 
npm run test:skills
Agents warningInvalid frontmatterRun 
npm run test:agents
Hook errorMissing/broken hookCheck hooks.json and bundles
Memory warningTier unavailableCheck .claude/memory/ or MEM0_API_KEY
Build warningOut of syncRun 
npm run build
Permission warningUnreachable rulesReview 
.claude/settings.json
状态含义操作建议
所有检查通过插件健康无需操作
Skill警告前置元数据无效运行
npm run test:skills
Agent警告前置元数据无效运行
npm run test:agents
Hook错误Hook缺失/损坏检查hooks.json和捆绑包
内存警告某层不可用检查.claude/memory/或MEM0_API_KEY
构建警告不同步运行
npm run build
权限警告存在不可达规则查看
.claude/settings.json

Troubleshooting

故障排查

"Skills validation failed"

"Skills validation failed"

bash
undefined
bash
undefined

Run skill structure tests

运行Skill结构测试

npm run test:skills ./tests/skills/structure/test-skill-md.sh
undefined
npm run test:skills ./tests/skills/structure/test-skill-md.sh
undefined

"Build out of sync"

"Build out of sync"

bash
undefined
bash
undefined

Rebuild plugins from source

从源码重新构建插件

npm run build
undefined
npm run build
undefined

"Memory tier unavailable"

"Memory tier unavailable"

bash
undefined
bash
undefined

Check graph memory

检查Graph内存

ls -la .claude/memory/
ls -la .claude/memory/

Check Mem0 (optional)

检查Mem0（可选）

echo $MEM0_API_KEY
undefined
echo $MEM0_API_KEY
undefined

Related Skills

相关Skill

  • configure
    - Configure plugin settings
  • quality-gates
    - CI/CD integration
  • security-scanning
    - Comprehensive audits
  • configure
    - 配置插件设置
  • quality-gates
    - CI/CD集成
  • security-scanning
    - 全面审计

References

参考文档

  • Skills Validation
  • Agents Validation
  • Hook Validation
  • Memory Health
  • Permission Rules
  • Schema Validation
  • Skill验证
  • Agent验证
  • Hook验证
  • 内存健康状态
  • 权限规则
  • Schema验证