dev-playbooks-cn 1.0.0

package/skills/devbooks-brownfield-bootstrap/references//345/255/230/351/207/217/351/241/271/347/233/256/345/210/235/345/247/213/345/214/226.md

@@ -0,0 +1,96 @@
+# 存量项目：初始化（项目画像 + 基线规格）工作流
+
+适用场景：你在一个已存在的项目里引入“规格化上下文协议”，但 `<truth-root>/` 为空或几乎为空。
+
+目标：一次性补齐“项目画像与约定 + 现状规格基线”，使后续变更能像“从一开始就按协议开发”一样稳定运行。
+
+核心原则：
+- **不要一次性写全系统**：先覆盖“对外面”（API/CLI/事件/配置/Schema），再逐步补内核。
+- **证据优先**：每条规格都要能指向代码/测试/日志/运行方式；不确定就写 `TBD` + 验证计划。
+- **先固化现状，再讨论重构**：基线阶段尽量不引入行为变化；避免“边补 specs 边改行为”导致真理源漂移。
+
+---
+
+## Step 0：确定基线范围（强制）
+
+做三选一（只选一个，避免失控）：
+- A) **对外契约优先**：API/事件/Schema/配置格式（最推荐）
+- B) **关键链路优先**：登录/支付/下单/编译发布等 1–3 条核心业务链路
+- C) **模块边界优先**：依赖方向/分层/禁止循环（配合 C4 + fitness tests）
+
+输出（写进 `<change-root>/<baseline-id>/proposal.md`）：
+- In / Out
+- 风险与已知未知（<=5 条）
+- “本次基线不做什么”（Non-goals）
+
+---
+
+## Step 0.5：一次性产出（推荐做法）
+
+直接使用一条提示词完成“项目画像 + 基线规格 + verification 草案”：
+- 本 Skill 的 `references/9 存量项目初始化提示词.md`
+
+该提示词会同时产出：
+- `<truth-root>/_meta/project-profile.md`（技术栈/命令/约定/闸门/契约入口）
+- `<truth-root>/_meta/glossary.md`（可选：统一语言表）
+- `<change-root>/<baseline-id>/...`（proposal/design/specs delta/verification）
+
+---
+
+## Step 1：盘点能力（Capability Inventory）
+
+把存量系统按 MECE 聚类成 3–8 个 capabilities（示例）：
+- `auth`、`billing`、`search`、`sync`、`config`、`observability`
+
+每个 capability 至少给出：
+- 对外入口（API/CLI/事件/topic）
+- 核心数据/Schema
+- 依赖方向（调用谁/被谁调用）
+
+产物位置（推荐）：
+- `<change-root>/<baseline-id>/design.md`（可选，但强烈建议有一页“现状总结”）
+
+---
+
+## Step 2：写基线 spec deltas（只用 ADDED）
+
+在 `<change-root>/<baseline-id>/specs/<capability>/spec.md` 写**现状规格**：
+- 优先只用“新增/ADDED”类 section（具体标题以 `<truth-root>/_meta/project-profile.md` 的格式约定为准）
+- 每条 Requirement/需求 至少 1 个 Scenario/场景
+- Requirement/Scenario 必须是“可观察”的（输入/输出/错误语义/不变量）
+
+注意：
+- 发现不确定：写 `TBD`，并把验证动作加入 `verification.md` 的计划区（不要臆测补齐）。
+- 发现明显 bug：不要在基线阶段顺手修；另起一个 change 做修复（避免基线混入行为变化）。
+
+---
+
+## Step 3：补最小验证锚点（建议）
+
+目标不是“全测覆盖”，而是给未来演进留抓手：
+- 对外契约：优先 contract tests（schema shape / backward compatibility）
+- 关键链路：最小 smoke/integration
+- 结构红线：fitness tests（分层/禁止循环/禁止越界依赖）
+- 若预计会做重构/迁移：优先加 Snapshot/Golden Master 作为行为指纹
+
+产物位置：
+- `<change-root>/<baseline-id>/verification.md`（计划 + 追溯矩阵 + MANUAL-*）
+- `tests/**`（按仓库惯例）
+- `contracts/**`（如果你维护契约库）
+
+---
+
+## Step 4：合并进当前真理源（<truth-root>/）
+
+把基线 change 的 `<truth-root>/**` 合并进 `<truth-root>/**`：
+- 若你的上下文协议提供 archive/merge 命令：用命令完成合并
+- 否则：人工合并也可以，但要保持“变更包 -> 当前真理”的单向合并语义
+
+---
+
+## 完成判据（DoD）
+
+- `<truth-root>/` 至少包含 1–3 个核心 capabilities 的 spec.md
+- 每个 spec 至少 3–10 条 Requirements（现状级别即可）
+- 至少 1 类锚点落地（contract 或 smoke 或 fitness 任选其一）
+- 未覆盖部分明确写了 Non-goals + 后续补齐计划

package/skills/devbooks-brownfield-bootstrap/references//345/255/230/351/207/217/351/241/271/347/233/256/345/210/235/345/247/213/345/214/226/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,115 @@
+# 存量项目初始化提示词
+
+> **角色设定**：你是遗留系统现代化领域的**最强大脑**——融合了 Michael Feathers（遗留代码处理）、Sam Newman（单体到微服务迁移）、Martin Fowler（重构与演进式架构）的智慧。你的基线分析必须达到这些大师级专家的水准。
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
+
+目录根（强制）：
+- 在写任何文件前，必须先确定 `<truth-root>` 与 `<change-root>` 的实际路径；禁止猜测。
+- 若存在 `dev-playbooks/project.md`（或目录 `dev-playbooks/`）：视为 DevBooks 项目，默认：
+  - `<truth-root>` = `dev-playbooks/specs`
+  - `<change-root>` = `dev-playbooks/changes`
+  - 必须先阅读 `dev-playbooks/project.md`（如存在）并遵循其中说明。
+- 否则：必须先询问用户确认 `<truth-root>` 与 `<change-root>`；用户未确认不得落盘。
+
+你是“存量项目初始化负责人（Brownfield Bootstrapper）”。你的任务是在**存量项目**中，当 `<truth-root>/` 为空或缺失时，一次性补齐：
+1) 项目画像与约定（技术栈/命令/边界/闸门/契约入口）
+2) 现状规格基线（baseline specs，以 ADDED 为主）
+
+最终效果：后续任何变更都能像“项目从一开始就按规格化流程开发”一样，有稳定真理源、稳定落点与可验证锚点。
+
+输入材料（由我提供）：
+- 代码库（只读分析，允许运行只读命令）
+- 现有对外资料（如有）：README/接口文档/部署说明/配置说明
+- 现有 tests（如有）
+- 我指定的基线范围（对外契约优先/关键链路优先/模块边界优先）
+
+产物目标（目录约定，协议无关）：
+- 项目画像（当前真理的一部分）：
+  - `<truth-root>/_meta/project-profile.md`
+- 统一语言表（可选但推荐）：
+  - `<truth-root>/_meta/glossary.md`
+- 变更包：`<change-root>/<baseline-id>/`
+  - `proposal.md`：基线范围、为什么先做基线、In/Out、风险与未知
+  - `design.md`（可选但推荐）：现状盘点（capability inventory）与边界/依赖方向
+  - `<truth-root>/<capability>/spec.md`：基线 spec deltas（只用 ADDED Requirements）
+  - `verification.md`：最小验证锚点计划 + 追溯矩阵 + MANUAL-*
+- 当前真理源：`<truth-root>/`（本阶段先不直接写入；由后续“归档/合并”动作把基线变更合并进去）
+
+硬约束（必须遵守）：
+1) **只写现状，不做重构**：本次初始化不引入行为变化建议，不输出实现计划。
+2) **基线 delta 以 ADDED 为主**：当 `<truth-root>/` 为空时，优先只写 ADDED，避免 MODIFIED/RENAMED/REMOVED（这些通常要求已有当前真理）。
+3) **delta 格式必须匹配项目所用协议的校验器**：
+   - 先在仓库里查找“delta 标题/场景标题”的既有模板或约定（例如搜索 `ADDED Requirements`/`新增需求`/`Scenario:`/`场景：`）
+   - 若仍不确定：不要臆测；在 `<truth-root>/_meta/project-profile.md` 标注 `TBD` 并给出验证动作（例如运行协议的 validate 命令）
+4) **证据优先**：任何不确定的地方必须标注 `TBD`，并在 `verification.md` 写清验证动作；禁止臆测补齐。
+5) **MECE 聚类**：capability 控制在 3–8 个；每个 capability 的 Requirements 控制在 3–15 条（先薄后厚）。
+6) **每条 Requirement 至少 1 个 Scenario**，并尽量在 Scenario 末尾补一行 Evidence（指向代码入口/测试/命令/日志关键字）。
+7) **遗留安全网优先**：若后续计划涉及重构/迁移，`verification.md` 中优先加入 Snapshot/Golden Master 测试策略。
+
+`<truth-root>/_meta/project-profile.md` 写作要求（必须遵守）：
+1) 只写你能从仓库证据推导出的结论；不确定必须标注 `TBD` 并给出验证动作（命令/文件路径/下一步）。
+2) 不改业务代码、不改 tests、不引入依赖；你只产出文档。
+3) `docs/` 只用于对外说明；本文件属于开发/代理协作的内部真理源，必须放在 `<truth-root>/`。
+4) 不要把零散建议写成“强制规范”；强制约定必须对应现有事实或现有 CI/工具约束。
+5) 必须包含“规格/变更包格式约定”：记录本项目 delta spec 的标题与场景标题写法（用于后续所有 spec delta 提示词保持一致）。
+
+`<truth-root>/_meta/project-profile.md` 推荐结构（建议严格遵循）：
+1) 项目概览
+   - 目标用户/使用场景（从 README/代码推断）
+   - 主要能力清单（3–10 条，按 MECE 聚类）
+2) 技术栈与运行时
+   - 语言/版本、主要框架、包管理/构建工具
+   - 关键依赖与基础设施（DB/缓存/队列/第三方）
+3) **Bounded Contexts（限界上下文）**（新增，必填）
+   - 识别项目中的业务边界（每个 Context 是一个自治的业务领域）
+   - 每个 Context 列出：
+     - 名称与职责（1-2 句话）
+     - 包含的核心 Entity（标注 `@Entity`）
+     - 与其他 Context 的关系（上游/下游/共享/隔离）
+   - 若存在外部系统集成：标注 ACL（Anti-Corruption Layer）位置
+   - 示例：
+     ```
+     | Context | 职责 | 核心 Entity | 上游依赖 | 下游消费者 | ACL |
+     |---------|------|-------------|----------|------------|-----|
+     | 订单 | 处理交易生命周期 | Order, OrderItem | 商品, 用户 | 支付, 物流 | 支付网关适配器 |
+     | 商品 | 管理商品目录 | Product, Category | - | 订单, 搜索 | - |
+     ```
+4) 仓库结构与模块边界（约定）
+   - 目录树的"职责解释"（只解释顶层与关键目录）
+   - 依赖方向/分层（如果看得出来）
+5) 开发与调试（本地）
+   - 如何运行/如何测试/如何构建（给出命令；未知则写 TBD）
+   - 关键配置与环境变量（列出名称与用途；敏感值不写）
+6) 质量闸门（DoD 对齐）
+   - tests 分层（unit/contract/integration/e2e）是否存在、如何跑
+   - 静态检查（lint/typecheck/build）是否存在、如何跑
+   - 安全与合规（SAST/secret scan）是否存在、如何跑
+7) 对外契约与数据定义（现状）
+   - API/事件/Schema/配置格式的入口位置（文件夹/文件名/生成方式）
+8) 规格与变更包格式约定（强制）
+   - spec delta 的 section 标题（例如 `## ADDED Requirements`/`## 新增需求` 等）
+   - scenario 标题写法（例如 `#### Scenario:`/`#### 场景：` 等）
+   - Requirement 标题写法（例如 `### Requirement:`/`### 需求：` 等）
+9) 已知风险与高频坑（只收高 ROI）
+   - 只记录"跨模块一致性/隐性约束/易漏同步点"
+   - 每条必须给出"预防锚点"（测试/静态检查/检查清单）
+10) Open Questions（<=5）
+
+输出要求（按顺序）：
+1) 先输出你将创建/更新的文件路径清单（只列路径）
+2) 输出 `<truth-root>/_meta/project-profile.md` 内容（Markdown）
+2.1) 若能从仓库识别稳定术语：输出 `<truth-root>/_meta/glossary.md` 草案
+3) 输出 `proposal.md` 内容（Markdown）
+4) 输出 `design.md` 内容（若你认为必要；否则输出“不需要”的理由）
+5) 对每个 capability 输出 `<change-root>/<baseline-id>/specs/<capability>/spec.md` 的 delta 内容（优先只包含 ADDED Requirements）
+6) 输出 `verification.md` 草案（至少包含：主线计划区、追溯矩阵、MANUAL-*）
+7) 最后给出一个“合并建议”：如何把本基线变更合并进 `<truth-root>/`（如果你知道项目使用的协议命令，可以顺带给出命令；不知道就给出人工合并步骤）
+
+现在开始执行，不要输出额外解释。
+
+注意事项：
+- 本文档中的 `<truth-root>` 与 `<change-root>` 是**占位符**，实际取值必须来自项目的上下文协议/指路牌。
+- DevBooks 项目默认取值：`dev-playbooks/specs` 与 `dev-playbooks/changes`。
+- 只有在用户明确确认时才允许使用默认 `specs/` 与 `changes/`。

package/skills/devbooks-brownfield-bootstrap/references//346/234/257/350/257/255/350/241/250/346/250/241/346/235/277.md

@@ -0,0 +1,42 @@
+# glossary.md 模板（真理源元信息）
+
+> 推荐路径：`<truth-root>/_meta/glossary.md`
+>
+> 目标：统一业务语言，避免同义不同名导致的规格与代码漂移。
+
+---
+owner: `<role/agent>`
+last_verified: `YYYY-MM-DD`
+status: `Active | Deprecated | Draft`
+freshness_check: `3 Months`
+---
+
+## 术语表（Ubiquitous Language）
+
+| 术语（中文） | 术语（英文） | 代码名/实体 | 定义（业务含义） | 同义词（允许） | 禁用词（避免） | 备注/例子 |
+|---|---|---|---|---|---|---|
+| 订单 | Order | Order | 用户完成支付后生成的交易记录 | 订单单 | Deal/Trade | 示例：订单号、订单状态 |
+| 客户 | Customer | Customer | 与平台发生交易的自然人/企业 | 用户 | Account | 示例：客户等级、客户画像 |
+
+## 领域建模术语（Domain Modeling Terms）
+
+> 以下术语用于 `design.md` 的领域模型章节，帮助区分不同类型的对象。
+
+| 术语 | 定义 | 识别标准 | 示例 |
+|------|------|----------|------|
+| **Entity（实体）** | 有唯一标识、可变状态、需要跟踪生命周期的对象 | ① 有业务意义的 ID ② 状态可变 ③ 需要持久化 | Order、Customer、Product |
+| **Value Object（值对象）** | 无唯一标识、不可变、描述性的对象 | ① 无 ID ② 不可变 ③ 可自由复制/共享 | Address、Money、DateRange、Email |
+| **Invariant（固定规则）** | 必须始终成立的业务约束，任何操作都不能破坏 | ① 跨属性约束 ② 违反即数据错误 | `订单总额 = SUM(明细金额)`、`库存 >= 0` |
+| **Business Rule（业务规则）** | 可配置/可变的业务策略，违反时有明确的处理逻辑 | ① 可能随业务调整 ② 违反有处理路径 | `会员折扣率`、`超时自动取消` |
+| **ACL（Anti-Corruption Layer）** | 隔离外部系统模型与内部模型的适配层 | ① 外部 API 调用入口 ② 模型转换逻辑 | 支付网关适配器、第三方物流接口 |
+| **Bounded Context（限界上下文）** | 自治的业务领域边界，内部使用统一术语 | ① 独立部署/演进 ② 术语边界清晰 | 订单上下文、商品上下文、用户上下文 |
+
+## 使用规则
+
+- 设计/规格/测试/代码必须使用此表中的术语；禁止自创新词
+- 若需要新增术语，先更新本文件，再产出 design/spec/tests
+- **Entity vs Value Object 判断**：
+  - 问"这个对象需要唯一标识吗？" → 是则 Entity，否则 Value Object
+  - 问"这个对象的状态会变化吗？" → 是则 Entity，否则 Value Object
+  - 问"两个对象所有属性相同时是否等价？" → 是则 Value Object，否则 Entity
+- **Invariant 标注**：在 `design.md` 中以 `[Invariant]` 前缀标注，在代码中应有对应断言

package/skills/devbooks-brownfield-bootstrap/scripts/cod-update.sh

@@ -0,0 +1,357 @@
+#!/bin/bash
+# DevBooks COD 模型增量更新脚本
+# 用途：持久化并增量更新代码地图产物（模块依赖图、热点、领域概念）
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# 颜色输出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+echo_info() { echo -e "${GREEN}[COD]${NC} $1"; }
+echo_warn() { echo -e "${YELLOW}[COD]${NC} $1"; }
+echo_error() { echo -e "${RED}[COD]${NC} $1"; }
+
+# 参数解析
+PROJECT_ROOT="."
+TRUTH_ROOT=""
+FORCE=false
+QUIET=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --project-root) PROJECT_ROOT="$2"; shift 2 ;;
+        --truth-root) TRUTH_ROOT="$2"; shift 2 ;;
+        --force) FORCE=true; shift ;;
+        --quiet) QUIET=true; shift ;;
+        -h|--help)
+            echo "用法: cod-update.sh [options]"
+            echo ""
+            echo "Options:"
+            echo "  --project-root <dir>  项目根目录 (默认: .)"
+            echo "  --truth-root <dir>    真理目录 (自动检测)"
+            echo "  --force               强制全量更新"
+            echo "  --quiet               静默模式"
+            exit 0
+            ;;
+        *) echo_error "未知参数: $1"; exit 1 ;;
+    esac
+done
+
+cd "$PROJECT_ROOT"
+
+# 自动检测 truth-root
+if [ -z "$TRUTH_ROOT" ]; then
+    if [ -f "dev-playbooks/project.md" ]; then
+        TRUTH_ROOT="dev-playbooks/specs"
+    elif [ -f ".devbooks/config.yaml" ]; then
+        TRUTH_ROOT=$(grep 'truth_root:' .devbooks/config.yaml | awk '{print $2}' | tr -d '"' || echo "specs")
+    else
+        TRUTH_ROOT="specs"
+    fi
+fi
+
+# 确保目录存在
+mkdir -p "$TRUTH_ROOT/architecture"
+mkdir -p "$TRUTH_ROOT/_meta"
+mkdir -p ".devbooks/cache/cod"
+
+# 缓存文件路径
+CACHE_DIR=".devbooks/cache/cod"
+HASH_FILE="$CACHE_DIR/source-hash.txt"
+ARCHITECTURE_CACHE="$CACHE_DIR/architecture.json"
+HOTSPOTS_CACHE="$CACHE_DIR/hotspots.json"
+CONCEPTS_CACHE="$CACHE_DIR/concepts.json"
+
+# 计算源文件 hash（用于检测变更）
+calculate_source_hash() {
+    # 只计算源代码文件的 hash，忽略 node_modules 等
+    find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \
+        -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \) \
+        ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/dist/*" ! -path "*/build/*" \
+        -exec md5sum {} \; 2>/dev/null | sort | md5sum | cut -d' ' -f1
+}
+
+# 检查是否需要更新
+needs_update() {
+    if [ "$FORCE" = true ]; then
+        return 0
+    fi
+
+    if [ ! -f "$HASH_FILE" ]; then
+        return 0
+    fi
+
+    local old_hash=$(cat "$HASH_FILE")
+    local new_hash=$(calculate_source_hash)
+
+    if [ "$old_hash" != "$new_hash" ]; then
+        return 0
+    fi
+
+    # 检查产物是否存在
+    if [ ! -f "$TRUTH_ROOT/architecture/module-graph.md" ]; then
+        return 0
+    fi
+
+    return 1
+}
+
+# 使用 CKB MCP 获取架构（如果可用）
+fetch_architecture_via_mcp() {
+    # 检查 CKB 是否可用（通过检查 index.scip）
+    if [ ! -f "index.scip" ]; then
+        echo_warn "SCIP 索引不存在，跳过图基架构分析"
+        return 1
+    fi
+
+    # 这里无法直接调用 MCP，但可以检查缓存
+    if [ -f "$ARCHITECTURE_CACHE" ]; then
+        local cache_age=$(( ($(date +%s) - $(stat -f%m "$ARCHITECTURE_CACHE" 2>/dev/null || stat -c%Y "$ARCHITECTURE_CACHE" 2>/dev/null)) ))
+        if [ $cache_age -lt 3600 ]; then  # 1小时内的缓存有效
+            echo_info "使用缓存的架构数据"
+            return 0
+        fi
+    fi
+
+    return 1
+}
+
+# 基于文件系统生成模块依赖图（降级方案）
+generate_module_graph_fallback() {
+    local output="$TRUTH_ROOT/architecture/module-graph.md"
+    local temp_file=$(mktemp)
+
+    echo_info "生成模块依赖图（文件系统分析）..."
+
+    cat > "$temp_file" << 'EOF'
+# 模块依赖图
+
+> 自动生成于 $(date +%Y-%m-%d)，基于文件系统分析
+
+## 目录结构
+
+```
+EOF
+
+    # 生成目录树
+    if command -v tree &> /dev/null; then
+        tree -d -L 3 -I 'node_modules|.git|dist|build|__pycache__|.venv|vendor' >> "$temp_file" 2>/dev/null || true
+    else
+        find . -type d -maxdepth 3 \
+            ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/dist/*" \
+            ! -path "*/build/*" ! -path "*/__pycache__/*" ! -path "*/.venv/*" \
+            2>/dev/null | head -50 >> "$temp_file"
+    fi
+
+    echo '```' >> "$temp_file"
+    echo "" >> "$temp_file"
+
+    # 分析导入关系
+    echo "## 主要依赖关系" >> "$temp_file"
+    echo "" >> "$temp_file"
+    echo "| 模块 | 依赖数 | 被依赖数 |" >> "$temp_file"
+    echo "|------|--------|----------|" >> "$temp_file"
+
+    # TypeScript/JavaScript 项目
+    if [ -f "package.json" ]; then
+        for dir in src lib app; do
+            if [ -d "$dir" ]; then
+                local import_count=$(grep -r "^import\|^from" "$dir" 2>/dev/null | wc -l || echo 0)
+                local export_count=$(grep -r "^export" "$dir" 2>/dev/null | wc -l || echo 0)
+                echo "| \`$dir/\` | $import_count | $export_count |" >> "$temp_file"
+            fi
+        done
+    fi
+
+    # Python 项目
+    if [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
+        for dir in src lib app; do
+            if [ -d "$dir" ]; then
+                local import_count=$(grep -r "^import\|^from" "$dir" --include="*.py" 2>/dev/null | wc -l || echo 0)
+                echo "| \`$dir/\` | $import_count | - |" >> "$temp_file"
+            fi
+        done
+    fi
+
+    echo "" >> "$temp_file"
+    echo "---" >> "$temp_file"
+    echo "" >> "$temp_file"
+    echo "> 提示：运行 \`devbooks-index-bootstrap\` 生成 SCIP 索引以获得更精确的依赖分析" >> "$temp_file"
+
+    # 只在内容变化时更新
+    if [ -f "$output" ]; then
+        if ! diff -q "$temp_file" "$output" > /dev/null 2>&1; then
+            mv "$temp_file" "$output"
+            echo_info "模块依赖图已更新: $output"
+        else
+            rm "$temp_file"
+            [ "$QUIET" = false ] && echo_info "模块依赖图无变化"
+        fi
+    else
+        mv "$temp_file" "$output"
+        echo_info "模块依赖图已创建: $output"
+    fi
+}
+
+# 生成热点文件报告
+generate_hotspots() {
+    local output="$TRUTH_ROOT/architecture/hotspots.md"
+    local temp_file=$(mktemp)
+
+    echo_info "生成技术债热点..."
+
+    cat > "$temp_file" << EOF
+# 技术债热点
+
+> 自动生成于 $(date +%Y-%m-%d)
+> 热点分数 = 变更频率 × 复杂度估算
+
+## 高频变更文件（近 30 天）
+
+| 文件 | 变更次数 | 行数 | 风险等级 |
+|------|----------|------|----------|
+EOF
+
+    # 使用 Git 历史分析
+    if [ -d ".git" ]; then
+        git log --since="30 days ago" --name-only --pretty=format: 2>/dev/null | \
+            grep -v '^$' | \
+            grep -v 'node_modules\|dist\|build\|\.lock\|package-lock' | \
+            sort | uniq -c | sort -rn | head -15 | \
+            while read count file; do
+                if [ -f "$file" ]; then
+                    local lines=$(wc -l < "$file" 2>/dev/null || echo 0)
+                    local risk="🟢 Normal"
+                    if [ $count -gt 10 ] && [ $lines -gt 300 ]; then
+                        risk="🔴 Critical"
+                    elif [ $count -gt 5 ] && [ $lines -gt 200 ]; then
+                        risk="🟡 High"
+                    fi
+                    echo "| \`$file\` | $count | $lines | $risk |"
+                fi
+            done >> "$temp_file"
+    else
+        echo "| (无 Git 历史) | - | - | - |" >> "$temp_file"
+    fi
+
+    echo "" >> "$temp_file"
+    echo "## 大文件（潜在复杂度）" >> "$temp_file"
+    echo "" >> "$temp_file"
+    echo "| 文件 | 行数 |" >> "$temp_file"
+    echo "|------|------|" >> "$temp_file"
+
+    find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.go" \) \
+        ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/dist/*" \
+        -exec wc -l {} \; 2>/dev/null | \
+        sort -rn | head -10 | \
+        while read lines file; do
+            echo "| \`$file\` | $lines |"
+        done >> "$temp_file"
+
+    # 只在内容变化时更新
+    if [ -f "$output" ]; then
+        # 比较时忽略日期行
+        if ! diff <(tail -n +4 "$temp_file") <(tail -n +4 "$output") > /dev/null 2>&1; then
+            mv "$temp_file" "$output"
+            echo_info "热点报告已更新: $output"
+        else
+            rm "$temp_file"
+            [ "$QUIET" = false ] && echo_info "热点报告无变化"
+        fi
+    else
+        mv "$temp_file" "$output"
+        echo_info "热点报告已创建: $output"
+    fi
+}
+
+# 生成领域概念（基于命名分析）
+generate_key_concepts() {
+    local output="$TRUTH_ROOT/_meta/key-concepts.md"
+    local temp_file=$(mktemp)
+
+    echo_info "生成领域概念..."
+
+    cat > "$temp_file" << EOF
+# 领域概念（Key Concepts）
+
+> 自动生成于 $(date +%Y-%m-%d)
+> 基于代码命名模式分析
+
+## 核心类/接口
+
+| 概念 | 出现次数 | 典型位置 |
+|------|----------|----------|
+EOF
+
+    # 提取 PascalCase 命名（类名）
+    grep -rho '\b[A-Z][a-z]*[A-Z][a-zA-Z]*\b' \
+        --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
+        . 2>/dev/null | \
+        grep -v 'node_modules\|dist\|build' | \
+        sort | uniq -c | sort -rn | head -15 | \
+        while read count name; do
+            local location=$(grep -rl "\b$name\b" --include="*.ts" --include="*.py" . 2>/dev/null | head -1 || echo "-")
+            echo "| \`$name\` | $count | \`$location\` |"
+        done >> "$temp_file"
+
+    echo "" >> "$temp_file"
+    echo "## 常见动词（操作）" >> "$temp_file"
+    echo "" >> "$temp_file"
+    echo "| 动词 | 出现次数 |" >> "$temp_file"
+    echo "|------|----------|" >> "$temp_file"
+
+    # 提取函数名中的动词
+    grep -rho '\b\(get\|set\|create\|update\|delete\|fetch\|save\|load\|process\|handle\|validate\)[A-Za-z]*\b' \
+        --include="*.ts" --include="*.js" --include="*.py" \
+        . 2>/dev/null | \
+        grep -v 'node_modules' | \
+        sed 's/[A-Z]/ /g' | awk '{print tolower($1)}' | \
+        sort | uniq -c | sort -rn | head -10 | \
+        while read count verb; do
+            echo "| \`$verb\` | $count |"
+        done >> "$temp_file"
+
+    # 只在内容变化时更新
+    if [ -f "$output" ]; then
+        if ! diff <(tail -n +4 "$temp_file") <(tail -n +4 "$output") > /dev/null 2>&1; then
+            mv "$temp_file" "$output"
+            echo_info "领域概念已更新: $output"
+        else
+            rm "$temp_file"
+            [ "$QUIET" = false ] && echo_info "领域概念无变化"
+        fi
+    else
+        mv "$temp_file" "$output"
+        echo_info "领域概念已创建: $output"
+    fi
+}
+
+# 主流程
+main() {
+    if needs_update; then
+        echo_info "检测到代码变更，更新 COD 产物..."
+
+        # 尝试使用 MCP，否则降级
+        if ! fetch_architecture_via_mcp; then
+            generate_module_graph_fallback
+        fi
+
+        generate_hotspots
+        generate_key_concepts
+
+        # 保存新的 hash
+        calculate_source_hash > "$HASH_FILE"
+
+        echo_info "COD 产物更新完成"
+    else
+        [ "$QUIET" = false ] && echo_info "代码无变更，跳过更新"
+    fi
+}
+
+main