dev-playbooks-cn 1.0.0

package/skills/devbooks-entropy-monitor/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: devbooks-entropy-monitor
+description: devbooks-entropy-monitor：定期采集系统熵度量（结构熵/变更熵/测试熵/依赖熵），生成量化报告，当指标超阈值时建议重构。用户说"熵度量/复杂度趋势/重构预警/代码健康/技术债务度量"等时使用。
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Bash
+---
+
+# DevBooks：系统熵度量与预警（Entropy Monitor）
+
+> 来源：《人月神话》第16章"没有银弹" — "软件实体的复杂性是根本属性...控制复杂性是软件开发的关键"
+
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
+4. `project.md`（如存在）→ template 协议，使用默认映射
+5. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：
+- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+
+## 核心理念
+
+**系统熵** = 代码复杂度随时间的增长趋势
+
+熵度量的目标：
+1. **定量化**：所有指标都是数值/比率，可对比
+2. **趋势可视**：历史数据支持趋势分析
+3. **阈值预警**：超阈值时主动建议重构
+4. **定期执行**：作为独立任务，不嵌入每次 code review
+
+## 执行方式
+
+1) 先阅读并遵守：`_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+2) 严格按完整提示词输出：`references/熵度量方法论.md`。
+
+## 脚本
+
+| 脚本 | 用途 | 示例 |
+|------|------|------|
+| `entropy-measure.sh` | 采集熵指标 | `entropy-measure.sh --project-root /path/to/repo` |
+| `entropy-report.sh` | 生成报告 | `entropy-report.sh --output report.md` |
+
+## 指标体系（四维度）
+
+### A) 结构熵（Structural Entropy）
+
+| 指标 | 采集方式 | 健康阈值 | 说明 |
+|------|---------|---------|------|
+| 圈复杂度均值 | 静态分析 | < 10 | 函数级平均 |
+| 圈复杂度 P95 | 静态分析 | < 20 | 95 分位数 |
+| 文件行数 P95 | 行数统计 | < 500 | 过大文件预警 |
+| 函数行数 P95 | 静态分析 | < 50 | 过长函数预警 |
+
+### B) 变更熵（Change Entropy）
+
+| 指标 | 采集方式 | 健康阈值 | 说明 |
+|------|---------|---------|------|
+| 热点文件占比 | git log | < 0.1 | 频繁修改的文件占比 |
+| 耦合变更率 | git log | < 0.3 | 经常一起修改的文件对比例 |
+| 代码流失率 | git diff | < 0.5 | 新增代码在30天内被删除的比例 |
+
+### C) 测试熵（Test Entropy）
+
+| 指标 | 采集方式 | 健康阈值 | 说明 |
+|------|---------|---------|------|
+| Flaky 测试占比 | CI 日志 | < 0.01 | 不稳定测试占比 |
+| 测试覆盖率 | 覆盖工具 | > 0.7 | 代码覆盖率 |
+| 测试/代码比 | 行数统计 | > 0.5 | 测试代码与生产代码比例 |
+
+### D) 依赖熵（Dependency Entropy）
+
+| 指标 | 采集方式 | 健康阈值 | 说明 |
+|------|---------|---------|------|
+| 过期依赖占比 | npm/pip audit | < 0.2 | 超过2个大版本的依赖 |
+| 安全漏洞数 | 安全扫描 | = 0 | 高危漏洞数量 |
+| 依赖深度 P95 | 依赖树分析 | < 10 | 传递依赖层数 |
+
+## 产物落点
+
+| 产物 | 路径 | 说明 |
+|------|------|------|
+| 熵报告 | `<truth-root>/_meta/entropy/entropy-report-YYYY-MM-DD.md` | 当次采集报告 |
+| 历史数据 | `<truth-root>/_meta/entropy/history.json` | 所有历史指标 |
+| 阈值配置 | `<truth-root>/_meta/entropy/thresholds.json` | 可配置阈值 |
+
+## 执行频率建议
+
+| 项目规模 | 建议频率 | 触发方式 |
+|---------|---------|---------|
+| 小型（< 10K LOC） | 每周 | 手动 / CI 定时 |
+| 中型（10K-100K LOC） | 每日 | CI 定时 |
+| 大型（> 100K LOC） | 每次合并 | PR 合并触发 |
+
+## 与其他 Skill 的关系
+
+| Skill | 关系 |
+|-------|------|
+| devbooks-code-review | 熵度量**不**嵌入每次 review，作为独立任务 |
+| devbooks-proposal-author | 熵报告可作为重构提案的数据支撑 |
+| devbooks-impact-analysis | 高熵区域变更需更谨慎的影响分析 |
+
+## 硬约束
+
+1. **定量优先**：所有指标必须是数值/比率，禁止主观评价
+2. **阈值可配**：所有阈值通过 `thresholds.json` 管理，不硬编码
+3. **历史可追**：每次采集结果追加到 `history.json`
+4. **独立执行**：不嵌入其他工作流，作为定期任务独立运行
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，选择合适的采集范围。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测历史数据文件是否存在
+2. 检测上次采集时间
+3. 检测是否有指标超阈值
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| **首次采集** | 历史数据不存在 | 执行完整采集并建立基线 |
+| **增量采集** | 距上次采集超过间隔 | 采集新数据并对比趋势 |
+| **预警模式** | 检测到指标超阈值 | 生成预警报告并建议重构 |
+
+### 检测输出示例
+
+```
+检测结果：
+- 历史数据：存在（15 条记录）
+- 上次采集：2026-01-10
+- 超阈值指标：2 个（圈复杂度 P95、热点文件占比）
+- 运行模式：增量采集 + 预警模式
+```
+
+---
+
+## MCP 增强
+
+本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
+
+MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
+
+### 依赖的 MCP 服务
+
+| 服务 | 用途 | 超时 |
+|------|------|------|
+| `mcp__ckb__getHotspots` | 获取热点文件分析 | 2s |
+| `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
+
+### 检测流程
+
+1. 调用 `mcp__ckb__getStatus`（2s 超时）
+2. 若 CKB 可用 → 使用 `getHotspots` 获取精确热点分析
+3. 若超时或失败 → 降级到 Git 历史统计
+
+### 增强模式 vs 基础模式
+
+| 功能 | 增强模式 | 基础模式 |
+|------|----------|----------|
+| 热点分析 | CKB 实时分析（含复杂度） | Git log 变更频率统计 |
+| 耦合检测 | 调用图分析 | 文件共变分析 |
+| 趋势预测 | 基于复杂度变化率 | 基于变更频率 |
+
+### 降级提示
+
+当 MCP 不可用时，输出以下提示：
+
+```
+⚠️ CKB 不可用，使用 Git 历史进行熵度量。
+热点分析基于变更频率，不含代码复杂度数据。
+```
+

package/skills/devbooks-entropy-monitor/references//347/206/265/345/272/246/351/207/217/346/226/271/346/263/225/350/256/272.md

@@ -0,0 +1,223 @@
+# 熵度量方法论
+
+> 来源：《人月神话》第16章"没有银弹" — "软件实体的复杂性是根本属性...控制复杂性是软件开发的关键"
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `references/项目开发实用提示词.md` 并遵循其中"结构质量守门协议"。
+
+你是"系统熵度量负责人（Entropy Monitor）"。你的任务是**定量化**地追踪系统复杂度趋势，在熵值超阈值时建议重构。
+
+## 核心理念
+
+**熵（Entropy）** = 系统无序度的度量
+
+在软件系统中：
+- **低熵** = 结构清晰、变更可控、测试健全、依赖健康
+- **高熵** = 结构混乱、热点频繁、测试脆弱、依赖老化
+
+熵的增长是不可避免的（热力学第二定律），但可以通过**有意识的重构**来降低。
+
+## 四维度指标体系
+
+### A) 结构熵（Structural Entropy）
+
+衡量代码的静态复杂度。
+
+| 指标 | 采集方式 | 健康阈值 | 超标信号 |
+|------|---------|---------|---------|
+| 圈复杂度均值 | 静态分析工具 | < 10 | 函数逻辑过于复杂 |
+| 圈复杂度 P95 | 静态分析工具 | < 20 | 存在极端复杂函数 |
+| 文件行数 P95 | wc -l | < 500 | 文件过大需拆分 |
+| 函数行数 P95 | 静态分析工具 | < 50 | 函数过长需提取 |
+
+**采集工具建议**：
+- JavaScript/TypeScript: `eslint --rule complexity`
+- Python: `radon cc`
+- Go: `gocyclo`
+- Java: `PMD`, `Checkstyle`
+
+### B) 变更熵（Change Entropy）
+
+衡量代码的动态变更模式。
+
+| 指标 | 采集方式 | 健康阈值 | 超标信号 |
+|------|---------|---------|---------|
+| 热点文件占比 | git log 分析 | < 0.1 | 少数文件承担过多变更 |
+| 耦合变更率 | git log 分析 | < 0.3 | 文件间隐式耦合 |
+| 代码流失率 | git diff 分析 | < 0.5 | 新增代码很快被删除 |
+
+**热点定义**：在分析周期内被修改超过 5 次的文件。
+
+**耦合变更定义**：两个文件在同一 commit 中同时被修改的频率。
+
+### C) 测试熵（Test Entropy）
+
+衡量测试的质量和稳定性。
+
+| 指标 | 采集方式 | 健康阈值 | 超标信号 |
+|------|---------|---------|---------|
+| Flaky 测试占比 | CI 日志分析 | < 0.01 | 测试不可靠 |
+| 测试覆盖率 | 覆盖工具 | > 0.7 | 关键路径未覆盖 |
+| 测试/代码比 | 行数统计 | > 0.5 | 测试投入不足 |
+
+**Flaky 测试定义**：在相同代码下，多次运行结果不一致的测试。
+
+### D) 依赖熵（Dependency Entropy）
+
+衡量外部依赖的健康状况。
+
+| 指标 | 采集方式 | 健康阈值 | 超标信号 |
+|------|---------|---------|---------|
+| 过期依赖占比 | npm outdated / pip-audit | < 0.2 | 技术债务累积 |
+| 安全漏洞数 | 安全扫描 | = 0 | 安全风险 |
+| 依赖深度 P95 | 依赖树分析 | < 10 | 供应链复杂 |
+
+**过期依赖定义**：落后当前最新版本超过 2 个大版本的依赖。
+
+## 执行流程
+
+### 1. 采集指标
+
+```bash
+# 运行熵度量采集
+entropy-measure.sh --project-root /path/to/repo --days 30
+
+# 输出位置
+<truth-root>/_meta/entropy/metrics-YYYY-MM-DD.json
+```
+
+### 2. 生成报告
+
+```bash
+# 生成可读报告
+entropy-report.sh --output report.md
+
+# 输出位置
+<truth-root>/_meta/entropy/entropy-report-YYYY-MM-DD.md
+```
+
+### 3. 趋势分析
+
+历史数据存储在 `<truth-root>/_meta/entropy/history.json`，可用于：
+- 绘制趋势图
+- 计算环比变化
+- 预测熵增速度
+
+### 4. 阈值预警
+
+当任一指标超过阈值时：
+1. 报告中显示 🔴 状态
+2. 生成告警条目
+3. 建议相应行动
+
+## 阈值配置
+
+阈值存储在 `<truth-root>/_meta/entropy/thresholds.json`：
+
+```json
+{
+  "structural": {
+    "complexity_mean": 10,
+    "complexity_p95": 20,
+    "file_lines_p95": 500,
+    "function_lines_p95": 50
+  },
+  "change": {
+    "hotspot_ratio": 0.1,
+    "coupling_ratio": 0.3,
+    "churn_ratio": 0.5
+  },
+  "test": {
+    "flaky_ratio": 0.01,
+    "coverage_min": 0.7,
+    "test_code_ratio_min": 0.5
+  },
+  "dependency": {
+    "outdated_ratio": 0.2,
+    "vulnerabilities": 0
+  }
+}
+```
+
+**阈值调整原则**：
+- 根据项目实际情况调整
+- 逐步收紧，不要一步到位
+- 记录调整原因和日期
+
+## 与重构提案的衔接
+
+当熵报告显示多项指标超标时：
+
+1. 使用 `devbooks-proposal-author` 发起重构提案
+2. 在 `proposal.md` 的 "Why" 部分引用熵报告数据
+3. 设定可验证的熵下降目标
+
+**示例**：
+
+```markdown
+## Why
+
+系统熵度量报告（2024-01-15）显示：
+- 热点文件占比 0.15（阈值 0.1）
+- 文件行数 P95 = 800（阈值 500）
+
+建议拆分 `src/core/engine.ts`（1200行）为多个模块。
+
+## Validation
+
+重构后预期：
+- 热点文件占比 < 0.08
+- 文件行数 P95 < 400
+```
+
+## 执行频率建议
+
+| 项目规模 | 建议频率 | 实施方式 |
+|---------|---------|---------|
+| 小型（< 10K LOC） | 每周 | 手动运行 |
+| 中型（10K-100K LOC） | 每日 | CI 定时任务 |
+| 大型（> 100K LOC） | 每次合并 | PR 合并后触发 |
+
+## CI 集成示例
+
+### GitHub Actions
+
+```yaml
+name: Entropy Monitor
+on:
+  schedule:
+    - cron: '0 2 * * *'  # 每天凌晨2点
+  workflow_dispatch:
+
+jobs:
+  measure:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # 需要完整 git 历史
+      - name: Run entropy measurement
+        run: ./scripts/entropy-measure.sh
+      - name: Generate report
+        run: ./scripts/entropy-report.sh
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: entropy-report
+          path: specs/_meta/entropy/
+```
+
+## 硬约束
+
+1. **定量优先**：所有指标必须是数值/比率，禁止"看起来复杂"等主观评价
+2. **阈值可配**：所有阈值通过配置文件管理，不硬编码
+3. **历史可追**：每次采集结果追加到 history.json，支持趋势分析
+4. **独立执行**：不嵌入每次 code review，作为定期任务独立运行
+5. **行动导向**：超标时必须给出具体行动建议
+
+## 参考文献
+
+- 《人月神话》第16章"没有银弹"
+- Michael Feathers,《修改代码的艺术》— 热点分析
+- Adam Tornhill,《Your Code as a Crime Scene》— 变更耦合分析
+- Martin Fowler, "Technical Debt Quadrant"