dev-playbooks-cn 1.0.0

package/skills/Skill/345/274/200/345/217/221/346/214/207/345/215/227.md

@@ -0,0 +1,248 @@
+# DevBooks Skill 开发指南
+
+本文档定义了开发新 Skill 时必须遵循的设计原则和约束。
+
+---
+
+## 1) 核心设计原则
+
+### 1.1 单一职责原则（UNIX 哲学）
+
+- **每个 Skill 只做一件事**：一个 Skill 只负责一个明确的职责，不要混合多个职责
+- **通过文件系统传递信息**：Skill 之间通过 `<change-root>/<change-id>/` 目录下的文件交换数据，而非共享内存或会话状态
+- **产物必须是纯文本**：所有产物使用 Markdown/JSON 格式，便于版本控制和人工审查
+
+### 1.2 幂等性设计原则（强制）
+
+**幂等性定义**：重复执行相同操作得到相同结果，不产生副作用累积。
+
+| Skill 类型 | 幂等性要求 | 示例 |
+|------------|------------|------|
+| **验证/检查类** | 必须幂等（不修改文件） | `change-check.sh`、`guardrail-check.sh`、`devbooks-code-review` |
+| **生成类** | 必须明确"覆盖/增量"行为 | `change-scaffold.sh`、`devbooks-design-doc`、`devbooks-proposal-author` |
+| **修改类** | 必须可安全重跑 | `devbooks-spec-gardener`、`devbooks-design-backport` |
+
+**验证/检查类 Skill 必须遵守**：
+- [ ] 不修改任何文件（只读操作）
+- [ ] 不修改数据库、缓存或外部状态
+- [ ] 多次运行输出完全相同（给定相同输入）
+- [ ] 失败时不留下部分状态
+
+**生成类 Skill 必须遵守**：
+- [ ] 明确声明是"覆盖模式"还是"增量模式"
+- [ ] 覆盖模式：重复运行产生相同结果
+- [ ] 增量模式：重复运行不产生重复内容（需要检测已存在内容）
+- [ ] 失败时回滚到运行前状态（或明确说明无法回滚）
+
+**修改类 Skill 必须遵守**：
+- [ ] 修改前备份原文件（或可通过 git 恢复）
+- [ ] 多次运行不产生累积副作用
+- [ ] 提供"dry-run"模式预览变更
+
+### 1.3 强制验证前置原则（借鉴 VS Code）
+
+**核心要求**：生成/修改类 Skill 在输出文件后，**必须运行验证**，验证失败时禁止进入下一步。
+
+| Skill 类型 | 验证要求 | 失败处理 |
+|------------|----------|----------|
+| 代码生成 | 编译检查（TypeScript/ESLint） | 必须修复后才能继续 |
+| 测试生成 | 运行测试（预期 Red 或 Green） | 记录结果到 verification.md |
+| 配置生成 | 格式验证（JSON/YAML schema） | 必须修复后才能继续 |
+| 文档生成 | 链接检查、格式检查 | 警告但可继续 |
+
+**强制验证检查清单**：
+
+```markdown
+## 验证前置检查（生成/修改类 Skill 必须执行）
+
+- [ ] 输出文件后，立即运行相关验证命令
+- [ ] 验证命令输出必须记录到证据文件
+- [ ] 验证失败时，禁止声明"任务完成"
+- [ ] 验证失败时，必须尝试修复或明确报告失败原因
+- [ ] 禁止"假定成功"——必须实际查看命令输出
+```
+
+**示例：代码生成后的验证流程**
+
+```bash
+# 1. 生成代码
+write_code_to_file "$output_file"
+
+# 2. 立即验证（强制）
+if ! npm run compile 2>&1 | tee "$evidence_dir/compile.log"; then
+  echo "error: compilation failed, cannot proceed" >&2
+  exit 1
+fi
+
+# 3. 运行 lint 检查
+if ! npm run lint 2>&1 | tee "$evidence_dir/lint.log"; then
+  echo "error: lint failed, cannot proceed" >&2
+  exit 1
+fi
+
+# 4. 验证通过后才能继续
+echo "ok: verification passed"
+```
+
+### 1.4 任务输出监控原则
+
+**要求**：运行长时任务时，必须主动查看输出，避免"假定成功"的幻觉。
+
+- [ ] 后台任务必须有超时机制
+- [ ] 必须检查任务退出码
+- [ ] 必须读取并分析任务输出
+- [ ] 禁止仅凭"命令执行完毕"就声明成功
+
+### 1.5 真理源分离原则
+
+- **只读真理源**：Skill 只能读取 `<truth-root>/`，不能直接修改（除了 `spec-gardener` 等归档类 Skill）
+- **写入工作区**：Skill 的写入目标是 `<change-root>/<change-id>/`
+- **归档即合并**：归档操作将工作区内容合并回真理源
+
+### 1.6 资源清理原则（借鉴 VS Code）
+
+**要求**：无论成功失败，必须清理临时资源。
+
+- [ ] 临时文件必须在退出时删除
+- [ ] 后台进程必须在退出时终止
+- [ ] 数据库连接必须在退出时关闭
+- [ ] 使用 `trap` 确保异常退出时也能清理
+
+```bash
+# 示例：使用 trap 确保清理
+cleanup() {
+  rm -rf "$TEMP_DIR"
+  kill "$BG_PID" 2>/dev/null || true
+}
+trap cleanup EXIT
+```
+
+---
+
+## 2) Skill 目录结构
+
+```
+skills/
+└── devbooks-<skill-name>/
+    ├── SKILL.md           # Skill 定义（必须）
+    ├── references/        # 参考文档（可选）
+    │   ├── *.md           # 提示词、模板、清单等
+    │   └── ...
+    └── scripts/           # 可执行脚本（可选）
+        ├── *.sh           # Shell 脚本
+        └── ...
+```
+
+### 2.1 SKILL.md 模板
+
+```markdown
+---
+name: devbooks-<skill-name>
+description: 一句话描述 Skill 的职责和触发场景
+---
+
+# DevBooks：<Skill 名称>
+
+## 前置：目录根（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+## 职责
+
+<描述这个 Skill 做什么>
+
+## 幂等性声明
+
+- 类型：验证类 / 生成类 / 修改类
+- 幂等性：是 / 否（说明原因）
+- 重跑行为：<描述多次运行的行为>
+
+## 参考文档
+
+- `references/<文档名>.md`
+
+## 脚本（如有）
+
+- `scripts/<脚本名>.sh`
+```
+
+---
+
+## 3) 脚本开发规范
+
+### 3.1 必须支持的参数
+
+所有脚本必须支持以下标准参数：
+
+```bash
+--project-root <path>    # 项目根目录（必须）
+--change-root <path>     # 变更包目录根（必须）
+--truth-root <path>      # 真理源目录根（必须）
+--dry-run                # 预览模式，不实际修改（推荐）
+--help                   # 显示帮助信息（必须）
+```
+
+### 3.2 退出码规范
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 成功 |
+| 1 | 一般错误 |
+| 2 | 参数错误 |
+| 3 | 前置条件不满足 |
+| 4 | 验证失败（用于检查类脚本） |
+
+### 3.3 输出规范
+
+- 正常输出到 stdout
+- 错误信息到 stderr
+- 支持 `--json` 输出机器可读格式（推荐）
+- 不使用 ANSI 颜色码（除非检测到 TTY）
+
+---
+
+## 4) 质量检查清单
+
+新 Skill 提交前必须通过以下检查：
+
+- [ ] **单一职责**：Skill 只做一件事
+- [ ] **幂等性声明**：SKILL.md 中明确声明幂等性行为
+- [ ] **真理源分离**：不直接修改 `<truth-root>/`（除非是归档类 Skill）
+- [ ] **参数完整**：脚本支持标准参数（`--project-root`、`--change-root`、`--truth-root`）
+- [ ] **帮助信息**：`--help` 输出清晰的使用说明
+- [ ] **退出码正确**：使用标准退出码
+- [ ] **无副作用**：验证类 Skill 不修改文件
+- [ ] **可测试**：提供测试用例或验证方法
+
+---
+
+## 5) 示例：验证类 Skill 的幂等性实现
+
+```bash
+#!/usr/bin/env bash
+# change-check.sh - 验证类脚本示例
+
+set -euo pipefail
+
+# 验证类脚本：只读操作，不修改任何文件
+readonly MODE="readonly"
+
+check_change() {
+    local change_id="$1"
+    local change_path="$CHANGE_ROOT/$change_id"
+
+    # 只读操作：检查文件是否存在
+    [[ -f "$change_path/proposal.md" ]] || return 4
+    [[ -f "$change_path/design.md" ]] || return 4
+    [[ -f "$change_path/tasks.md" ]] || return 4
+
+    # 只读操作：验证内容格式
+    grep -q "^## Acceptance Criteria" "$change_path/design.md" || return 4
+
+    return 0
+}
+
+# 多次运行输出相同，不产生副作用
+check_change "$1"
+```

package/skills/_shared/context-detection-template.md

@@ -0,0 +1,315 @@
+# 上下文检测模板 (Context Detection Template)
+
+> 本模板为所有 SKILL.md 提供标准化的上下文检测规则。
+>
+> 产物落点：`skills/_shared/context-detection-template.md`
+
+---
+
+## 概述
+
+上下文检测用于自动识别当前工作状态，帮助 Skill 选择正确的运行模式。检测基于文件存在性，不依赖外部服务。
+
+---
+
+## 检测规则
+
+### 1. 产物存在性检测
+
+检测变更包目录中的关键产物是否存在。
+
+```bash
+# 检测脚本示例
+detect_artifacts() {
+  local change_root="$1"
+  local change_id="$2"
+  local change_dir="${change_root}/${change_id}"
+
+  # 检测关键产物
+  local has_proposal=false
+  local has_design=false
+  local has_tasks=false
+  local has_verification=false
+  local has_specs=false
+
+  [[ -f "${change_dir}/proposal.md" ]] && has_proposal=true
+  [[ -f "${change_dir}/design.md" ]] && has_design=true
+  [[ -f "${change_dir}/tasks.md" ]] && has_tasks=true
+  [[ -f "${change_dir}/verification.md" ]] && has_verification=true
+  [[ -d "${change_dir}/specs" ]] && has_specs=true
+
+  echo "proposal:${has_proposal}"
+  echo "design:${has_design}"
+  echo "tasks:${has_tasks}"
+  echo "verification:${has_verification}"
+  echo "specs:${has_specs}"
+}
+```
+
+### 2. 完整性判断规则
+
+按 Requirement 块校验 specs/ 的完整性。
+
+**完整性判定条件**：
+1. 每个 REQ 必须有至少一个 Scenario
+2. 每个 Scenario 必须有 Given/When/Then
+3. 不存在占位符（`[TODO]`、`[待补充]`、`[TBD]`）
+4. 所有 AC 都有对应的 Requirement
+
+```bash
+# 完整性检测脚本示例
+# [m-001 修复] 输出格式与 tests/lib/completeness-check.sh 保持一致
+check_spec_completeness() {
+  local spec_file="$1"
+
+  # 如果文件为空或不存在，视为完整
+  if [[ ! -f "$spec_file" ]] || [[ ! -s "$spec_file" ]]; then
+    echo "complete:无 Req 需校验"
+    return 0
+  fi
+
+  # 检查是否存在占位符
+  if grep -qE '\[TODO\]|\[待补充\]|\[TBD\]' "$spec_file"; then
+    echo "incomplete:存在占位符"
+    return 1
+  fi
+
+  # 检查 Requirement 块
+  local req_count=$(grep -c '^## REQ-' "$spec_file" || echo 0)
+  local scenario_count=$(grep -c '^### Scenario' "$spec_file" || echo 0)
+
+  if [[ $req_count -gt 0 && $scenario_count -eq 0 ]]; then
+    echo "incomplete:REQ 缺少 Scenario"
+    return 1
+  fi
+
+  # 检查 Given/When/Then
+  local gwt_count=$(grep -cE '^\s*-\s*(Given|When|Then)' "$spec_file" || echo 0)
+  if [[ $scenario_count -gt 0 && $gwt_count -lt $((scenario_count * 3)) ]]; then
+    echo "incomplete:Scenario 缺少完整的 Given/When/Then"
+    return 1
+  fi
+
+  echo "complete:全部校验通过"
+  return 0
+}
+```
+
+### 3. 当前阶段检测
+
+根据已有产物推断当前阶段。
+
+| 阶段 | 判定条件 |
+|------|----------|
+| **proposal** | `proposal.md` 不存在，或存在但未通过 Judge 裁决 |
+| **apply** | `proposal.md` 存在且已裁决，`design.md` 存在，正在实现 |
+| **archive** | 所有闸门通过，准备归档或已归档 |
+
+```bash
+# 阶段检测脚本示例
+detect_phase() {
+  local change_dir="$1"
+
+  # 检查产物存在性
+  local has_proposal=false
+  local has_design=false
+  local has_evidence=false
+
+  [[ -f "${change_dir}/proposal.md" ]] && has_proposal=true
+  [[ -f "${change_dir}/design.md" ]] && has_design=true
+  [[ -d "${change_dir}/evidence/green-final" ]] && has_evidence=true
+
+  # 推断阶段
+  if ! $has_proposal; then
+    echo "proposal"
+  elif $has_evidence; then
+    echo "archive"
+  else
+    echo "apply"
+  fi
+}
+```
+
+### 4. 运行模式检测
+
+根据上下文选择 Skill 的运行模式。
+
+| 模式 | 条件 | 说明 |
+|------|------|------|
+| **从零创建** | 目标产物不存在 | 创建全新产物 |
+| **补漏模式** | 产物存在但不完整 | 补充缺失部分 |
+| **同步模式** | 产物完整，需要与实现同步 | 检查一致性并更新 |
+
+```bash
+# 模式检测脚本示例
+detect_mode() {
+  local artifact_path="$1"
+  local artifact_type="$2"  # spec | design | c4
+
+  if [[ ! -e "$artifact_path" ]]; then
+    echo "create"  # 从零创建
+    return
+  fi
+
+  # 检查完整性
+  case "$artifact_type" in
+    spec)
+      local completeness=$(check_spec_completeness "$artifact_path")
+      # [m-001 修复] 使用与实现一致的格式检查
+      if [[ "$completeness" == complete:* ]]; then
+        echo "sync"  # 同步模式
+      else
+        echo "patch"  # 补漏模式
+      fi
+      ;;
+    design)
+      if grep -qE '\[TODO\]|\[待补充\]' "$artifact_path"; then
+        echo "patch"
+      else
+        echo "sync"
+      fi
+      ;;
+    c4)
+      if [[ -f "$artifact_path" ]]; then
+        echo "update"
+      else
+        echo "create"
+      fi
+      ;;
+  esac
+}
+```
+
+---
+
+## 7 个边界场景测试用例
+
+| ID | 场景 | 输入状态 | 期望输出 | 说明 |
+|----|------|----------|----------|------|
+| **CD-001** | 全空变更包 | `change-dir/` 为空 | 阶段=proposal, 模式=create | 新变更的初始状态 |
+| **CD-002** | 仅有 proposal | `proposal.md` 存在，其他为空 | 阶段=proposal, 等待裁决 | 提案已撰写但未通过 |
+| **CD-003** | proposal + design | 两个文件都存在 | 阶段=apply | 设计已完成，进入实现 |
+| **CD-004** | specs 不完整 | `specs/` 存在但有 `[TODO]` | 模式=patch | 需要补充规格 |
+| **CD-005** | specs 完整 | `specs/` 存在且无占位符 | 模式=sync | 检查与实现一致性 |
+| **CD-006** | 闸门通过 | `evidence/green-final/` 存在 | 阶段=archive | 准备归档 |
+| **CD-007** | c4.md 不存在 | `specs/architecture/c4.md` 不存在 | 模式=create | 需要创建架构图 |
+
+### 测试用例验证脚本
+
+```bash
+#!/bin/bash
+# context-detection-test.sh
+# 运行上下文检测边界场景测试
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_DIR=$(mktemp -d)
+trap "rm -rf $TEST_DIR" EXIT
+
+echo "=== 上下文检测边界场景测试 ==="
+
+# CD-001: 全空变更包
+echo -n "CD-001 全空变更包... "
+mkdir -p "$TEST_DIR/CD-001"
+phase=$(detect_phase "$TEST_DIR/CD-001")
+[[ "$phase" == "proposal" ]] && echo "PASS" || echo "FAIL (got: $phase)"
+
+# CD-002: 仅有 proposal
+echo -n "CD-002 仅有 proposal... "
+mkdir -p "$TEST_DIR/CD-002"
+touch "$TEST_DIR/CD-002/proposal.md"
+phase=$(detect_phase "$TEST_DIR/CD-002")
+[[ "$phase" == "proposal" || "$phase" == "apply" ]] && echo "PASS" || echo "FAIL (got: $phase)"
+
+# CD-003: proposal + design
+echo -n "CD-003 proposal + design... "
+mkdir -p "$TEST_DIR/CD-003"
+touch "$TEST_DIR/CD-003/proposal.md"
+touch "$TEST_DIR/CD-003/design.md"
+phase=$(detect_phase "$TEST_DIR/CD-003")
+[[ "$phase" == "apply" ]] && echo "PASS" || echo "FAIL (got: $phase)"
+
+# CD-004: specs 不完整
+echo -n "CD-004 specs 不完整... "
+mkdir -p "$TEST_DIR/CD-004/specs"
+echo "[TODO] 待补充" > "$TEST_DIR/CD-004/specs/spec.md"
+mode=$(detect_mode "$TEST_DIR/CD-004/specs/spec.md" "spec")
+[[ "$mode" == "patch" ]] && echo "PASS" || echo "FAIL (got: $mode)"
+
+# CD-005: specs 完整
+echo -n "CD-005 specs 完整... "
+mkdir -p "$TEST_DIR/CD-005/specs"
+cat > "$TEST_DIR/CD-005/specs/spec.md" << 'EOF'
+## REQ-001 示例需求
+### Scenario: 正常流程
+- Given 前置条件
+- When 执行操作
+- Then 期望结果
+EOF
+mode=$(detect_mode "$TEST_DIR/CD-005/specs/spec.md" "spec")
+[[ "$mode" == "sync" ]] && echo "PASS" || echo "FAIL (got: $mode)"
+
+# CD-006: 闸门通过
+echo -n "CD-006 闸门通过... "
+mkdir -p "$TEST_DIR/CD-006/evidence/green-final"
+touch "$TEST_DIR/CD-006/proposal.md"
+phase=$(detect_phase "$TEST_DIR/CD-006")
+[[ "$phase" == "archive" ]] && echo "PASS" || echo "FAIL (got: $phase)"
+
+# CD-007: c4.md 不存在
+echo -n "CD-007 c4.md 不存在... "
+mkdir -p "$TEST_DIR/CD-007/specs/architecture"
+mode=$(detect_mode "$TEST_DIR/CD-007/specs/architecture/c4.md" "c4")
+[[ "$mode" == "create" ]] && echo "PASS" || echo "FAIL (got: $mode)"
+
+echo "=== 测试完成 ==="
+```
+
+---
+
+## Skill 引用方式
+
+在 SKILL.md 中引用本模板：
+
+```markdown
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，选择合适的运行模式。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测产物存在性
+2. 判断完整性
+3. 推断当前阶段
+4. 选择运行模式
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| 从零创建 | <条件> | <行为> |
+| 补漏模式 | <条件> | <行为> |
+| 同步模式 | <条件> | <行为> |
+```
+
+---
+
+## 检测输出格式
+
+标准化的检测结果输出：
+
+```
+检测结果：
+- 产物存在性：<存在/不存在>
+- 完整性：<完整/不完整（缺失项：...）>
+- 当前阶段：<proposal/apply/archive>
+- 运行模式：<从零创建/补漏/同步>
+```
+
+---
+
+**文档版本**：v1.0.0
+**最后更新**：2026-01-12

package/skills/_shared/mcp-enhancement-template.md

@@ -0,0 +1,144 @@
+# MCP 增强模板（MCP Enhancement Template）
+
+> 本模板供各 SKILL.md 引用，定义 MCP 运行时检测与降级策略的标准章节格式。
+
+---
+
+## 核心原则
+
+1. **2s 超时**：所有 MCP 调用必须在 2s 内返回，否则视为不可用
+2. **优雅降级**：MCP 不可用时，Skill 继续执行基础功能，不阻塞
+3. **静默检测**：检测过程对用户透明，只在降级时输出提示
+
+---
+
+## 标准章节格式
+
+每个 SKILL.md 的"MCP 增强"章节应包含以下内容：
+
+```markdown
+## MCP 增强
+
+本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
+
+### 依赖的 MCP 服务
+
+| 服务 | 用途 | 超时 |
+|------|------|------|
+| `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
+| `mcp__ckb__getHotspots` | 获取热点文件 | 2s |
+
+### 检测流程
+
+1. 调用 `mcp__ckb__getStatus`（2s 超时）
+2. 若返回成功 → 启用增强模式
+3. 若超时或失败 → 降级到基础模式
+
+### 增强模式 vs 基础模式
+
+| 功能 | 增强模式 | 基础模式 |
+|------|----------|----------|
+| 热点检测 | CKB 实时分析 | Git 历史统计 |
+| 影响分析 | 符号级引用 | 文件级 grep |
+| 调用图 | 精确调用链 | 不可用 |
+
+### 降级提示
+
+当 MCP 不可用时，输出以下提示：
+
+```
+⚠️ CKB 不可用（超时或未配置），使用基础模式执行。
+如需启用增强功能，请运行 /devbooks:index 生成索引。
+```
+```
+
+---
+
+## 按 Skill 分类
+
+### 无 MCP 依赖的 Skills
+
+以下 Skills 不依赖 MCP，无需 MCP 增强章节：
+
+- devbooks-design-doc（纯文档生成）
+- devbooks-implementation-plan（纯计划生成）
+- devbooks-proposal-author（纯文档生成）
+- devbooks-proposal-challenger（纯评审）
+- devbooks-proposal-judge（纯裁决）
+- devbooks-proposal-debate-workflow（流程编排）
+- devbooks-design-backport（文档回写）
+- devbooks-spec-gardener（文件整理）
+- devbooks-test-reviewer（测试评审）
+
+对于这些 Skills，MCP 增强章节应写：
+
+```markdown
+## MCP 增强
+
+本 Skill 不依赖 MCP 服务，无需运行时检测。
+```
+
+### 有 MCP 依赖的 Skills
+
+以下 Skills 依赖 MCP，需要完整 MCP 增强章节：
+
+| Skill | MCP 依赖 | 增强功能 |
+|-------|----------|----------|
+| devbooks-coder | mcp__ckb__getHotspots | 热点文件预警 |
+| devbooks-code-review | mcp__ckb__getHotspots | 热点文件高亮 |
+| devbooks-impact-analysis | mcp__ckb__analyzeImpact, findReferences | 精确影响分析 |
+| devbooks-brownfield-bootstrap | mcp__ckb__* | COD 模型生成 |
+| devbooks-index-bootstrap | mcp__ckb__getStatus | 索引状态检测 |
+| devbooks-federation | mcp__ckb__*, mcp__github__* | 跨仓库分析 |
+| devbooks-router | mcp__ckb__getStatus | 索引可用性检测 |
+| devbooks-c4-map | mcp__ckb__getArchitecture | 模块依赖图 |
+| devbooks-spec-contract | mcp__ckb__findReferences | 引用检测 |
+| devbooks-entropy-monitor | mcp__ckb__getHotspots | 热点趋势分析 |
+| devbooks-delivery-workflow | mcp__ckb__getStatus | 索引检测 |
+| devbooks-test-owner | mcp__ckb__analyzeImpact | 测试覆盖分析 |
+
+---
+
+## 检测代码示例
+
+### Bash 检测脚本
+
+```bash
+#!/bin/bash
+# mcp-detect.sh - MCP 可用性检测
+
+TIMEOUT=2
+
+# 检测 CKB
+check_ckb() {
+  # 模拟 MCP 调用（实际由 Claude Code 执行）
+  # 若 2s 内无响应，返回降级状态
+  echo "⚠️ CKB 检测需要在 Claude Code 环境中执行"
+}
+
+# 输出检测结果
+detect_mcp() {
+  local ckb_status="unknown"
+
+  # 检查 index.scip 文件是否存在（文件级检测）
+  if [ -f "index.scip" ]; then
+    ckb_status="available (file-based)"
+  else
+    ckb_status="unavailable"
+  fi
+
+  echo "MCP 检测结果："
+  echo "- CKB 索引：$ckb_status"
+}
+
+detect_mcp
+```
+
+---
+
+## 注意事项
+
+1. **不要在 SKILL.md frontmatter 中添加不存在的 MCP 工具**
+2. **超时检测应在 Skill 执行开始时进行，不要多次检测**
+3. **降级后不要重复提示，只在首次检测时输出一次**
+4. **增强功能是可选的，基础功能必须完整可用**