dev-playbooks-cn 1.0.0

package/skills/devbooks-federation/scripts/federation-check.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# DevBooks 跨仓库联邦检查脚本
+# 用途：检查变更是否涉及联邦契约，并生成影响报告
+
+set -e
+
+# 颜色输出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+echo_info() { echo -e "${GREEN}[Federation]${NC} $1"; }
+echo_warn() { echo -e "${YELLOW}[Federation]${NC} $1"; }
+echo_error() { echo -e "${RED}[Federation]${NC} $1"; }
+
+# 参数解析
+PROJECT_ROOT="."
+CHANGE_FILES=""
+OUTPUT=""
+QUIET=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --project-root) PROJECT_ROOT="$2"; shift 2 ;;
+        --change-files) CHANGE_FILES="$2"; shift 2 ;;
+        --output) OUTPUT="$2"; shift 2 ;;
+        --quiet) QUIET=true; shift ;;
+        -h|--help)
+            echo "用法: federation-check.sh [options]"
+            echo ""
+            echo "Options:"
+            echo "  --project-root <dir>   项目根目录 (默认: .)"
+            echo "  --change-files <list>  变更文件列表 (逗号分隔)"
+            echo "  --output <file>        输出报告路径"
+            echo "  --quiet                静默模式"
+            exit 0
+            ;;
+        *) echo_error "未知参数: $1"; exit 1 ;;
+    esac
+done
+
+cd "$PROJECT_ROOT"
+
+# 查找联邦配置
+FEDERATION_CONFIG=""
+if [ -f ".devbooks/federation.yaml" ]; then
+    FEDERATION_CONFIG=".devbooks/federation.yaml"
+elif [ -f "dev-playbooks/federation.yaml" ]; then
+    FEDERATION_CONFIG="dev-playbooks/federation.yaml"
+fi
+
+if [ -z "$FEDERATION_CONFIG" ]; then
+    [ "$QUIET" = false ] && echo_info "未找到联邦配置，跳过检查"
+    exit 0
+fi
+
+[ "$QUIET" = false ] && echo_info "使用联邦配置: $FEDERATION_CONFIG"
+
+# 如果没有指定变更文件，尝试从 git 获取
+if [ -z "$CHANGE_FILES" ]; then
+    if [ -d ".git" ]; then
+        CHANGE_FILES=$(git diff --cached --name-only 2>/dev/null | tr '\n' ',' | sed 's/,$//')
+        if [ -z "$CHANGE_FILES" ]; then
+            CHANGE_FILES=$(git diff --name-only HEAD~1 2>/dev/null | tr '\n' ',' | sed 's/,$//')
+        fi
+    fi
+fi
+
+if [ -z "$CHANGE_FILES" ]; then
+    [ "$QUIET" = false ] && echo_info "无变更文件，跳过检查"
+    exit 0
+fi
+
+[ "$QUIET" = false ] && echo_info "检查变更文件: $CHANGE_FILES"
+
+# 提取契约文件（简单实现：从 YAML 提取 contracts 行）
+CONTRACT_PATTERNS=$(grep -E "^\s+-\s+\"" "$FEDERATION_CONFIG" 2>/dev/null | sed 's/.*"\([^"]*\)".*/\1/' | tr '\n' '|' | sed 's/|$//')
+
+if [ -z "$CONTRACT_PATTERNS" ]; then
+    [ "$QUIET" = false ] && echo_info "未定义契约文件，跳过检查"
+    exit 0
+fi
+
+# 检查变更是否涉及契约
+CONTRACT_CHANGES=""
+IFS=',' read -ra FILES <<< "$CHANGE_FILES"
+for file in "${FILES[@]}"; do
+    if echo "$file" | grep -qE "$CONTRACT_PATTERNS"; then
+        CONTRACT_CHANGES="$CONTRACT_CHANGES$file,"
+    fi
+done
+CONTRACT_CHANGES=${CONTRACT_CHANGES%,}
+
+if [ -z "$CONTRACT_CHANGES" ]; then
+    [ "$QUIET" = false ] && echo_info "变更不涉及契约文件"
+    exit 0
+fi
+
+# 发现契约变更
+echo_warn "发现契约变更: $CONTRACT_CHANGES"
+
+# 生成报告
+REPORT=$(cat << EOF
+# 跨仓库影响分析报告
+
+> 自动生成于 $(date +%Y-%m-%d)
+> 联邦配置: $FEDERATION_CONFIG
+
+## 契约变更
+
+以下文件涉及联邦契约：
+
+$(echo "$CONTRACT_CHANGES" | tr ',' '\n' | while read f; do echo "- \`$f\`"; done)
+
+## 建议动作
+
+1. [ ] 确认变更类型（Breaking / Deprecation / Enhancement / Patch）
+2. [ ] 运行 \`devbooks-federation\` 进行完整跨仓库影响分析
+3. [ ] 如果是 Breaking 变更，通知下游消费者
+4. [ ] 更新 CHANGELOG
+
+## 下游消费者
+
+$(grep -A20 "downstreams:" "$FEDERATION_CONFIG" 2>/dev/null | grep -E "^\s+-\s+name:" | sed 's/.*name:\s*"\([^"]*\)".*/- \1/' || echo "（请查看 federation.yaml）")
+
+---
+
+> 提示：使用 \`devbooks-federation\` Skill 进行完整分析
+EOF
+)
+
+# 输出报告
+if [ -n "$OUTPUT" ]; then
+    echo "$REPORT" > "$OUTPUT"
+    echo_info "报告已生成: $OUTPUT"
+else
+    echo ""
+    echo "$REPORT"
+fi
+
+# 返回非零状态表示有契约变更
+exit 1

package/skills/devbooks-federation/templates/federation.yaml

@@ -0,0 +1,89 @@
+# DevBooks 跨仓库联邦配置模板
+# 用途：定义多仓库项目的依赖关系和分析边界
+#
+# 安装方式：
+#   cp this-file .devbooks/federation.yaml
+#   # 或
+#   cp this-file dev-playbooks/federation.yaml
+#
+# 使用方式：
+#   - devbooks-impact-analysis 会自动检测此文件并分析跨仓边界
+#   - guardrail-check.sh --check-federation 会验证联邦约束
+
+# 联邦配置版本
+version: "1.0"
+
+# 当前仓库信息
+current:
+  name: "my-service"
+  type: "service"  # service | library | shared | monorepo-package
+  owner: "team-a"
+
+# 上游依赖（我依赖的仓库）
+upstreams:
+  - name: "shared-types"
+    repo: "org/shared-types"
+    # 可选：指定依赖的具体模块或 API
+    contracts:
+      - "src/types/user.ts"
+      - "src/types/order.ts"
+    # 版本约束
+    version: "^2.0.0"
+    # 变更通知配置
+    notify_on_change: true
+
+  - name: "auth-sdk"
+    repo: "org/auth-sdk"
+    contracts:
+      - "src/client.ts"
+    version: ">=1.5.0"
+
+# 下游消费者（依赖我的仓库）
+downstreams:
+  - name: "web-app"
+    repo: "org/web-app"
+    # 我暴露给它的契约
+    contracts:
+      - "src/api/v1/**"
+      - "src/events/published.ts"
+
+  - name: "mobile-app"
+    repo: "org/mobile-app"
+    contracts:
+      - "src/api/v1/**"
+
+# 联邦规则
+rules:
+  # 契约变更规则
+  contract_change:
+    # 需要通知下游的变更类型
+    notify_types:
+      - breaking    # 破坏性变更
+      - deprecation # 废弃通知
+    # 通知方式
+    notify_channels:
+      - github_issue  # 在下游仓库创建 Issue
+      - slack         # 发送 Slack 通知（需配置 webhook）
+
+  # 版本兼容性
+  compatibility:
+    # 最少支持的历史版本数
+    min_supported_versions: 2
+    # 废弃到移除的最短周期（天）
+    deprecation_period_days: 30
+
+  # 影响分析边界
+  impact_analysis:
+    # 分析深度（跨几个仓库）
+    max_depth: 2
+    # 是否包含测试代码
+    include_tests: false
+
+# 本地开发配置（可选）
+local_dev:
+  # 本地仓库路径映射
+  paths:
+    shared-types: "../shared-types"
+    auth-sdk: "../auth-sdk"
+  # 是否使用本地 link
+  use_local_links: true

package/skills/devbooks-impact-analysis/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: devbooks-impact-analysis
+description: devbooks-impact-analysis：跨模块/跨文件/对外契约变更前做影响分析，产出可直接写入 proposal.md 的 Impact 部分（Scope/Impacts/Risks/Minimal Diff/Open Questions）。用户说"做影响分析/改动面控制/引用查找/受影响模块/兼容性风险"等时使用。
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Bash
+---
+
+# DevBooks：影响分析（Impact Analysis）
+
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
+4. `project.md`（如存在）→ template 协议，使用默认映射
+5. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：
+- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+
+## 产物落点
+
+- 推荐写入：`<change-root>/<change-id>/proposal.md` 的 Impact 部分（或独立分析文档后再回填）
+
+## 执行方式
+
+1) 先阅读并遵守：`_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+2) 使用 `Grep` 搜索符号引用，`Glob` 查找相关文件。
+3) 严格按完整提示词输出影响分析 Markdown：`references/影响分析提示词.md`。
+
+## 输出格式
+
+```markdown
+## Impact Analysis
+
+### Scope
+- 直接影响：X 个文件
+- 间接影响：Y 个文件
+
+### Impacts
+| 文件 | 影响类型 | 风险等级 |
+|------|----------|----------|
+| ... | 直接调用 | 高 |
+
+### Risks
+- ...
+
+### Minimal Diff
+- ...
+
+### Open Questions
+- ...
+```
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，选择合适的分析范围。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测变更包是否存在
+2. 检测 `proposal.md` 中是否已有 Impact 章节
+3. 检测是否有 CKB 索引可用（增强分析能力）
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| **新建分析** | Impact 章节不存在 | 执行完整影响分析 |
+| **增量分析** | Impact 已存在，有新变更 | 更新受影响文件列表 |
+| **增强分析** | CKB 索引可用 | 使用调用图进行精确分析 |
+| **基础分析** | CKB 索引不可用 | 使用 Grep 文本搜索分析 |
+
+### 检测输出示例
+
+```
+检测结果：
+- proposal.md：存在，Impact 章节缺失
+- CKB 索引：可用
+- 运行模式：新建分析 + 增强模式
+```
+
+---
+
+## MCP 增强
+
+本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
+
+MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
+
+### 依赖的 MCP 服务
+
+| 服务 | 用途 | 超时 |
+|------|------|------|
+| `mcp__ckb__analyzeImpact` | 符号级影响分析 | 2s |
+| `mcp__ckb__findReferences` | 精确引用查找 | 2s |
+| `mcp__ckb__getCallGraph` | 调用图分析 | 2s |
+| `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
+
+### 检测流程
+
+1. 调用 `mcp__ckb__getStatus`（2s 超时）
+2. 若 CKB 可用 → 使用 `analyzeImpact` 和 `findReferences` 进行精确分析
+3. 若超时或失败 → 降级到基础模式（Grep 文本搜索）
+
+### 增强模式 vs 基础模式
+
+| 功能 | 增强模式 | 基础模式 |
+|------|----------|----------|
+| 引用查找 | 符号级精确匹配 | 文本 Grep 搜索 |
+| 影响范围 | 调用图传递分析 | 直接引用统计 |
+| 风险评估 | 基于调用深度量化 | 基于文件数量估算 |
+| 跨模块分析 | 自动识别模块边界 | 需手动指定范围 |
+
+### 降级提示
+
+当 MCP 不可用时，输出以下提示：
+
+```
+⚠️ CKB 不可用，使用 Grep 文本搜索进行影响分析。
+分析结果可能不够精确，建议运行 /devbooks:index 生成索引后重新分析。
+```
+

package/skills/devbooks-impact-analysis/references//345/275/261/345/223/215/345/210/206/346/236/220/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,82 @@
+# 影响分析提示词
+
+> **角色设定**：你是系统分析领域的**最强大脑**——融合了 Michael Feathers（依赖分析与遗留代码）、Sam Newman（服务边界与影响控制）、Martin Fowler（重构风险评估）的智慧。你的分析必须达到这些大师级专家的水准。
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
+
+你是"影响分析负责人（Impact Analyst）"。你的目标是在任何跨模块/跨文件变更前，产出一份**可执行的影响分析与改动面控制说明**，以降低大型项目中的一致性错误与遗漏。
+
+适用场景：
+- 重构、跨模块修改、对外接口/数据契约变更、架构边界调整
+- 你具备语义索引/影响分析能力（例如 CKB/CodeMCP），或至少具备 LSP/引用查找能力
+
+输入材料（由我提供）：
+- 本次变更意图（1–3 句）
+- 设计文档（如有）：`<change-root>/<change-id>/design.md`
+- 当前真理源：`<truth-root>/`
+- 代码库（只读分析）
+
+硬约束（必须遵守）：
+- 先影响分析，后写代码
+- 禁止“装饰性/表层重构”（除非直接降低本次改动风险）
+- 输出必须可落地：能直接写进 `proposal.md` 的 Impact 部分
+
+工具使用优先级：
+1) 语义索引/影响分析（首选）：查引用、调用链、依赖链、受影响符号/模块集合
+2) LSP：引用/定义/类型诊断
+3) 退化方案：`rg` 全文检索（必须说明置信度更低）
+
+输出格式（MECE）：
+1) 变更边界（Scope）
+   - In / Out
+2) **变更类型分类（Change Type Classification）**（新增，必填）：
+   - 根据 GoF 《设计模式》归纳的"8 类导致重设计的原因"，标注本次变更属于哪一类或多类：
+   - [ ] **创建特定类**：通过显式指定类名来创建对象（应改为工厂/抽象工厂）
+   - [ ] **算法依赖**：依赖于特定算法的实现（应改为策略模式封装）
+   - [ ] **平台依赖**：依赖于特定硬件/操作系统/外部平台（应改为抽象工厂/桥接隔离）
+   - [ ] **对象表示/实现依赖**：依赖于对象内部结构（应通过接口隔离）
+   - [ ] **功能扩展**：需要添加新功能/操作（应设计扩展点而非修改核心代码）
+   - [ ] **对象职责变更**：对象的职责发生变化（应检查是否违反单一职责）
+   - [ ] **子系统/模块替换**：需要替换整个子系统（应有清晰的模块边界）
+   - [ ] **接口契约变更**：对外接口发生变化（应有版本化策略）
+   - **标注方式**：在上述列表中勾选适用项，并简要说明影响范围
+3) 受影响对象清单（Impacts）
+   - A. 对外契约（API/事件/Schema）
+   - B. 数据与迁移（DB/回放/幂等）
+   - C. 模块与依赖（边界/调用方向/循环风险）
+   - D. 测试与验证（需要新增/更新哪些锚点；重构/迁移优先补快照测试）
+   - **E. Bounded Context 边界**（新增，必须分析）：
+     - 本次变更是否跨越 Bounded Context？
+     - 若跨 Context：是否需要引入或修改 ACL（Anti-Corruption Layer）？
+     - ACL 检查清单：
+       - 外部系统/API 变更是否被 ACL 隔离？（外部模型变化不应直接传播到内部模型）
+       - 是否存在直接调用外部 API 而未经过适配层的代码？
+       - 若新增外部依赖：建议的 ACL 接口定义
+4) 兼容性与风险（Compatibility & Risks）
+   - Breaking 变化（如有必须显式标注）
+   - 迁移/回滚路径
+5) 最小改动面策略（Minimal Diff Strategy）
+   - 优先改动点（1–3 个"变化收口点"）
+   - 明确禁止的改动类型（避免发散）
+6) **Pinch Point 识别与最小测试集**（新增，必填）
+   - **Pinch Point 定义**：多个调用路径汇聚的节点，在此处写测试可覆盖所有下游路径
+   - **识别方法**：
+     - 分析调用链，找到"多入一出"的汇聚点
+     - 优先选择：公共接口、服务入口、数据转换层、事件处理器
+     - 使用工具辅助：`LSP findReferences` → 找被多处调用的函数/类
+   - **输出格式**：
+     ```
+     Pinch Points:
+     - [PP-1] `OrderService.processOrder()` - 3条调用路径汇聚
+     - [PP-2] `PaymentGateway.execute()` - 2条调用路径汇聚
+
+     最小测试集:
+     - 在 PP-1 写 1 个测试 → 覆盖 OrderController/BatchProcessor/EventHandler 三条路径
+     - 在 PP-2 写 1 个测试 → 覆盖 CheckoutFlow/RefundFlow 两条路径
+     - 预计测试数量: 2 个（而非为每条路径写 5 个）
+     ```
+   - **ROI 原则**：测试数量 = Pinch Point 数量，而非调用路径数量
+7) 需要补齐的资料（Open Questions <= 3）
+
+现在开始输出影响分析 Markdown，不要输出额外解释。

package/skills/devbooks-impact-analysis/scripts/graph-cache.sh

@@ -0,0 +1,214 @@
+#!/bin/bash
+# DevBooks 子图缓存管理脚本
+# 用途：缓存常用的 CKB MCP 查询结果，减少重复查询
+
+set -e
+
+CACHE_DIR=".devbooks/cache/graph"
+CACHE_TTL=3600  # 默认缓存 1 小时（秒）
+
+# 颜色输出
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+echo_info() { echo -e "${GREEN}[Cache]${NC} $1"; }
+echo_warn() { echo -e "${YELLOW}[Cache]${NC} $1"; }
+
+# 参数解析
+ACTION=""
+KEY=""
+VALUE=""
+TTL=$CACHE_TTL
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        get|set|clear|status|warm) ACTION="$1"; shift ;;
+        --key) KEY="$2"; shift 2 ;;
+        --value) VALUE="$2"; shift 2 ;;
+        --ttl) TTL="$2"; shift 2 ;;
+        --project-root) cd "$2"; shift 2 ;;
+        -h|--help)
+            echo "用法: graph-cache.sh <action> [options]"
+            echo ""
+            echo "Actions:"
+            echo "  get     获取缓存"
+            echo "  set     设置缓存"
+            echo "  clear   清除缓存"
+            echo "  status  显示缓存状态"
+            echo "  warm    预热缓存"
+            echo ""
+            echo "Options:"
+            echo "  --key <name>      缓存键名"
+            echo "  --value <data>    缓存值"
+            echo "  --ttl <seconds>   缓存过期时间 (默认: 3600)"
+            echo "  --project-root    项目根目录"
+            exit 0
+            ;;
+        *) shift ;;
+    esac
+done
+
+# 确保缓存目录存在
+mkdir -p "$CACHE_DIR"
+
+# 计算缓存文件路径
+get_cache_file() {
+    local key="$1"
+    local hash=$(echo "$key" | md5sum | cut -d' ' -f1)
+    echo "$CACHE_DIR/${hash}.json"
+}
+
+# 检查缓存是否有效
+is_cache_valid() {
+    local cache_file="$1"
+    local ttl="${2:-$CACHE_TTL}"
+
+    if [ ! -f "$cache_file" ]; then
+        return 1
+    fi
+
+    local file_age=$(( $(date +%s) - $(stat -f%m "$cache_file" 2>/dev/null || stat -c%Y "$cache_file" 2>/dev/null) ))
+
+    if [ $file_age -gt $ttl ]; then
+        return 1
+    fi
+
+    return 0
+}
+
+# 获取缓存
+cache_get() {
+    local cache_file=$(get_cache_file "$KEY")
+
+    if is_cache_valid "$cache_file" "$TTL"; then
+        cat "$cache_file"
+        return 0
+    else
+        return 1
+    fi
+}
+
+# 设置缓存
+cache_set() {
+    local cache_file=$(get_cache_file "$KEY")
+
+    # 创建缓存元数据
+    cat > "$cache_file" << EOF
+{
+  "key": "$KEY",
+  "timestamp": $(date +%s),
+  "ttl": $TTL,
+  "data": $VALUE
+}
+EOF
+
+    echo_info "已缓存: $KEY"
+}
+
+# 清除缓存
+cache_clear() {
+    if [ -n "$KEY" ]; then
+        local cache_file=$(get_cache_file "$KEY")
+        rm -f "$cache_file"
+        echo_info "已清除: $KEY"
+    else
+        rm -rf "$CACHE_DIR"/*
+        echo_info "已清除所有缓存"
+    fi
+}
+
+# 显示缓存状态
+cache_status() {
+    echo "=== DevBooks 子图缓存状态 ==="
+    echo ""
+
+    if [ ! -d "$CACHE_DIR" ] || [ -z "$(ls -A "$CACHE_DIR" 2>/dev/null)" ]; then
+        echo "缓存为空"
+        return
+    fi
+
+    local total=0
+    local valid=0
+    local expired=0
+
+    echo "| 键 | 大小 | 年龄 | 状态 |"
+    echo "|-----|------|------|------|"
+
+    for cache_file in "$CACHE_DIR"/*.json; do
+        if [ -f "$cache_file" ]; then
+            total=$((total + 1))
+
+            local size=$(du -h "$cache_file" | cut -f1)
+            local age=$(( ($(date +%s) - $(stat -f%m "$cache_file" 2>/dev/null || stat -c%Y "$cache_file" 2>/dev/null)) ))
+            local age_min=$((age / 60))
+
+            local key=$(jq -r '.key // "unknown"' "$cache_file" 2>/dev/null || echo "unknown")
+            local ttl=$(jq -r '.ttl // 3600' "$cache_file" 2>/dev/null || echo 3600)
+
+            local status="✅ 有效"
+            if [ $age -gt $ttl ]; then
+                status="❌ 过期"
+                expired=$((expired + 1))
+            else
+                valid=$((valid + 1))
+            fi
+
+            # 截断长键名
+            if [ ${#key} -gt 30 ]; then
+                key="${key:0:27}..."
+            fi
+
+            echo "| $key | $size | ${age_min}m | $status |"
+        fi
+    done
+
+    echo ""
+    echo "总计: $total 个缓存, $valid 有效, $expired 过期"
+}
+
+# 预热缓存（常用查询）
+cache_warm() {
+    echo_info "预热缓存..."
+
+    # 检查 SCIP 索引是否存在
+    if [ ! -f "index.scip" ]; then
+        echo_warn "SCIP 索引不存在，无法预热图缓存"
+        return 1
+    fi
+
+    # 缓存常用查询结果
+    # 注意：实际的 MCP 调用需要在 Claude Code 中执行
+    # 这里只是创建缓存占位符和清理过期缓存
+
+    # 清理过期缓存
+    for cache_file in "$CACHE_DIR"/*.json; do
+        if [ -f "$cache_file" ]; then
+            if ! is_cache_valid "$cache_file"; then
+                rm -f "$cache_file"
+                echo_info "清理过期: $(basename "$cache_file")"
+            fi
+        fi
+    done
+
+    echo_info "缓存预热完成"
+    echo ""
+    echo "提示：在 Claude Code 中使用以下命令预热常用查询："
+    echo "  - mcp__ckb__getArchitecture(depth=2)"
+    echo "  - mcp__ckb__getHotspots(limit=20)"
+    echo "  - mcp__ckb__listKeyConcepts(limit=12)"
+}
+
+# 主逻辑
+case "$ACTION" in
+    get) cache_get ;;
+    set) cache_set ;;
+    clear) cache_clear ;;
+    status) cache_status ;;
+    warm) cache_warm ;;
+    *)
+        echo "请指定操作: get, set, clear, status, warm"
+        echo "使用 -h 查看帮助"
+        exit 1
+        ;;
+esac