ccbot-cli 2.0.1 → 2.2.0

package/skills/tools/verify-change/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: verify-change
+description: 变更校验关卡。分析代码变更，检测文档同步状态，评估变更影响范围。当魔尊提到变更检查、文档同步、代码审查、提交前检查、diff分析时使用。在设计级变更、重构完成时自动触发。
+license: MIT
+compatibility: node>=18
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: Bash, Read, Grep
+argument-hint: [--mode working|staged|committed]
+---
+
+# ⚖ 校验关卡 · 变更校验
+
+
+## 核心原则
+
+```
+变更 = 代码改动 + 文档更新 + 理由记录
+无理由的变更是隐患，无记录的变更是灾难
+每一次变更都是历史，每一个决策都要留痕
+```
+
+## 自动分析
+
+运行变更分析脚本（跨平台）：
+
+```bash
+# 在 skill 目录下运行
+node scripts/change_analyzer.js                    # 分析工作区变更（默认）
+node scripts/change_analyzer.js --mode staged      # 分析暂存区变更
+node scripts/change_analyzer.js --mode committed   # 分析已提交变更
+node scripts/change_analyzer.js -v                 # 详细模式
+node scripts/change_analyzer.js --json             # JSON 输出
+```
+
+## 检测能力
+
+### 自动检测项
+
+| 检测项 | 说明 |
+|--------|------|
+| **文件分类** | 自动识别代码/文档/测试/配置文件 |
+| **模块识别** | 识别受影响的模块 |
+| **文档同步** | 检测代码变更是否同步更新文档 |
+| **测试覆盖** | 检测代码变更是否有对应测试 |
+| **影响评估** | 评估变更规模和影响范围 |
+
+### 触发警告的情况
+
+- ⚠️ 代码变更 > 50 行但 DESIGN.md 未更新
+- ⚠️ 代码变更 > 30 行但无测试更新
+- ⚠️ 新增文件但 README.md 未更新
+- ⚠️ 配置文件变更未记录
+- ℹ️ 删除文件需确认引用已清理
+
+## 变更前置检查
+
+在修改任何模块前，必须：
+
+1. **读取 README.md** — 理解模块定位
+2. **读取 DESIGN.md** — 理解现有决策
+3. **评估影响范围** — 此变更影响哪些部分
+4. **确认变更理由** — 为什么要改
+
+## 变更后置检查
+
+代码修改完成后，必须：
+
+### README.md 更新检查
+
+- [ ] 模块职责是否变化 → 更新职责描述
+- [ ] 依赖关系是否变化 → 更新依赖说明
+- [ ] 使用方式是否变化 → 更新示例代码
+
+### DESIGN.md 更新检查
+
+- [ ] 新增设计决策 → 记录决策及理由
+- [ ] 修改现有设计 → 记录变更及原因
+- [ ] 引入新限制 → 更新已知限制
+- [ ] 添加变更记录 → 更新变更历史
+
+## 变更记录格式
+
+在 DESIGN.md 的变更历史中添加：
+
+```markdown
+## 变更历史
+
+### [日期] - [变更标题]
+
+**变更内容**: 简述改了什么
+
+**变更理由**: 为什么要改
+
+**影响范围**: 影响哪些功能/模块
+
+**决策依据**: 为何选择此方案（如适用）
+```
+
+## 自动触发时机
+
+| 场景 | 触发条件 |
+|------|----------|
+| 设计级变更 | 修改架构、接口、数据结构 |
+| 重构完成 | 重构任务完成时 |
+| 代码变更 > 30 行 | 较大规模代码修改 |
+| 提交前 | 代码提交前检查 |
+
+## 校验流程
+
+```
+1. 运行 change_analyzer.js 自动分析
+2. 识别变更文件和受影响模块
+3. 检查文档同步状态
+4. 评估变更影响
+5. 输出变更校验报告
+```
+
+## 校验报告格式
+
+```
+## 变更校验报告
+
+### 变更概览
+- 变更文件数: N
+- 代码变更行数: +X / -Y
+- 受影响模块: [模块列表]
+
+### 文档同步状态
+- README.md: ✓ 已同步 / ⚠️ 需更新
+- DESIGN.md: ✓ 已同步 / ⚠️ 需更新
+
+### 测试覆盖
+- 测试文件变更: ✓ 有 / ⚠️ 无
+
+### 结论
+可提交 / 需补充文档后提交
+```
+
+---

package/skills/tools/verify-change/scripts/change_analyzer.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const { parseCliArgs, buildReport, hasFatal, DASH } = require(path.join(__dirname, '..', '..', 'lib', 'shared.js'));
+
+const CODE_EXT = new Set([".py",".go",".rs",".ts",".js",".jsx",".tsx",".java",".c",".cpp",".h",".hpp"]);
+const DOC_EXT = new Set([".md",".rst",".txt",".adoc"]);
+const TEST_PATTERNS = ["test_","_test.",".test.","spec_","_spec.","/tests/","/test/","/__tests__/"];
+const CONFIG_FILES = new Set(["package.json","pyproject.toml","go.mod","cargo.toml","pom.xml","makefile","dockerfile"]);
+const CONFIG_EXT = new Set([".yaml",".yml",".json",".toml",".ini"]);
+
+function normalizePath(p) {
+  let s = p.trim();
+  if (s.startsWith('"') && s.endsWith('"') && s.length >= 2) {
+    s = s.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+  }
+  if (s.startsWith("./")) s = s.slice(2);
+  return s;
+}
+
+function classifyFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const name = path.basename(filePath).toLowerCase();
+  const lower = filePath.toLowerCase();
+  return {
+    path: filePath, type: "modified", additions: 0, deletions: 0,
+    is_code: CODE_EXT.has(ext), is_doc: DOC_EXT.has(ext),
+    is_test: TEST_PATTERNS.some(p => lower.includes(p)),
+    is_config: CONFIG_FILES.has(name) || CONFIG_EXT.has(ext),
+  };
+}
+
+function parseNameStatusLine(line) {
+  const parts = line.split("\t");
+  if (parts.length < 2) return null;
+  const status = parts[0][0];
+  const p = normalizePath(parts[parts.length - 1]);
+  if (!p) return null;
+  const c = classifyFile(p);
+  const map = { A: "added", M: "modified", D: "deleted", R: "renamed" };
+  if (map[status]) c.type = map[status];
+  return c;
+}
+
+function parsePorcelainLine(line) {
+  if (line.length < 3) return null;
+  const status = line.slice(0, 2);
+  let raw = line.slice(3);
+  if (!raw) return null;
+  if (raw.includes(" -> ")) raw = raw.split(" -> ")[1];
+  const p = normalizePath(raw);
+  if (!p) return null;
+  const c = classifyFile(p);
+  if (status.includes("?") || status.includes("A")) c.type = "added";
+  else if (status.includes("R")) c.type = "renamed";
+  else if (status.includes("M")) c.type = "modified";
+  else if (status.includes("D")) c.type = "deleted";
+  return c;
+}
+
+function git(...args) {
+  try { return execFileSync('git', args, { encoding: "utf8", stdio: ["pipe","pipe","pipe"] }); }
+  catch { return ""; }
+}
+
+function getGitChanges(base = "HEAD~1", target = "HEAD") {
+  const changes = [];
+  for (const line of git('diff', '--name-status', base, target).split("\n")) {
+    if (!line) continue;
+    const c = parseNameStatusLine(line);
+    if (c) changes.push(c);
+  }
+  const statMap = {};
+  for (const line of git('diff', '--numstat', base, target).split("\n")) {
+    if (!line) continue;
+    const parts = line.split("\t");
+    if (parts.length >= 3) {
+      statMap[normalizePath(parts[2])] = [
+        parts[0] === "-" ? 0 : parseInt(parts[0], 10),
+        parts[1] === "-" ? 0 : parseInt(parts[1], 10),
+      ];
+    }
+  }
+  for (const c of changes) {
+    if (statMap[c.path]) { [c.additions, c.deletions] = statMap[c.path]; }
+  }
+  return changes;
+}
+
+function getStagedChanges() {
+  const changes = [];
+  for (const line of git('diff', '--cached', '--name-status').split("\n")) {
+    if (!line) continue;
+    const c = parseNameStatusLine(line);
+    if (c) changes.push(c);
+  }
+  return changes;
+}
+
+function getWorkingChanges() {
+  const changes = [];
+  for (const line of git('status', '--porcelain').split("\n")) {
+    if (!line) continue;
+    const c = parsePorcelainLine(line);
+    if (c) changes.push(c);
+  }
+  return changes;
+}
+
+function isPathInModule(filePath, mod) {
+  const np = normalizePath(filePath);
+  if (mod === ".") return !np.includes("/");
+  return np === mod || np.startsWith(mod + "/");
+}
+
+function identifyModules(changes) {
+  const modules = new Set();
+  for (const c of changes) {
+    const np = normalizePath(c.path);
+    const parts = np.split("/").filter(Boolean);
+    if (parts.length === 1) { modules.add("."); continue; }
+    let found = false;
+    for (let i = 0; i < parts.length; i++) {
+      const mp = parts.slice(0, i + 1).join("/");
+      if (fs.existsSync(path.join(mp, "README.md")) || fs.existsSync(path.join(mp, "DESIGN.md"))) {
+        modules.add(mp); found = true; break;
+      }
+    }
+    if (!found && parts.length > 1) modules.add(parts[0]);
+  }
+  return modules;
+}
+
+function checkDocSync(changes, modules) {
+  const docStatus = {};
+  const issues = [];
+  const codeChanges = changes.filter(c => c.is_code && c.type !== "deleted");
+  const docPaths = new Set(changes.filter(c => c.is_doc).map(c => normalizePath(c.path)));
+
+  for (const mod of modules) {
+    const readme = normalizePath(mod === "." ? "README.md" : `${mod}/README.md`);
+    const design = normalizePath(mod === "." ? "DESIGN.md" : `${mod}/DESIGN.md`);
+    const modCode = codeChanges.filter(c => isPathInModule(c.path, mod));
+    if (!modCode.length) continue;
+    const total = modCode.reduce((s, c) => s + c.additions + c.deletions, 0);
+    if (total > 50 && !docPaths.has(design)) {
+      issues.push({
+        severity: "warning",
+        message: `模块 ${mod} 有较大代码变更 (${total} 行)，但 DESIGN.md 未更新`,
+        related_files: modCode.map(c => c.path)
+      });
+      docStatus[`${mod}/DESIGN.md`] = false;
+    } else {
+      docStatus[`${mod}/DESIGN.md`] = true;
+    }
+    const newFiles = modCode.filter(c => c.type === "added");
+    if (newFiles.length && !docPaths.has(readme)) {
+      issues.push({
+        severity: "info",
+        message: `模块 ${mod} 新增了文件，建议更新 README.md`,
+        related_files: newFiles.map(c => c.path)
+      });
+    }
+  }
+  return { docStatus, issues };
+}
+
+function analyzeImpact(changes) {
+  const issues = [];
+  const code = changes.filter(c => c.is_code && !c.is_test);
+  const tests = changes.filter(c => c.is_test);
+  if (code.length && !tests.length) {
+    const total = code.reduce((s, c) => s + c.additions + c.deletions, 0);
+    if (total > 30) {
+      issues.push({
+        severity: "warning",
+        message: `代码变更 ${total} 行，但没有对应的测试更新`,
+        related_files: code.map(c => c.path)
+      });
+    }
+  }
+  const configs = changes.filter(c => c.is_config);
+  if (configs.length) {
+    issues.push({
+      severity: "info",
+      message: "配置文件有变更，请确认是否需要更新文档",
+      related_files: configs.map(c => c.path)
+    });
+  }
+  const deleted = changes.filter(c => c.type === "deleted");
+  if (deleted.length) {
+    issues.push({
+      severity: "info",
+      message: `删除了 ${deleted.length} 个文件，请确认相关引用已清理`,
+      related_files: deleted.map(c => c.path)
+    });
+  }
+  return issues;
+}
+
+function analyzeChanges(mode = "working") {
+  let changes;
+  if (mode === "staged") changes = getStagedChanges();
+  else if (mode === "committed") changes = getGitChanges();
+  else changes = getWorkingChanges();
+
+  const issues = [];
+  let modules = new Set(), docStatus = {};
+  if (changes.length) {
+    modules = identifyModules(changes);
+    const ds = checkDocSync(changes, modules);
+    docStatus = ds.docStatus;
+    issues.push(...ds.issues, ...analyzeImpact(changes));
+  }
+  const passed = !issues.some(i => i.severity === "error");
+  const totalAdd = changes.reduce((s, c) => s + c.additions, 0);
+  const totalDel = changes.reduce((s, c) => s + c.deletions, 0);
+  return { changes, issues, modules, docStatus, passed, totalAdd, totalDel };
+}
+
+function formatReport(r, verbose) {
+  const fields = {
+    '变更文件': r.changes.length,
+    '新增行数': `+${r.totalAdd}`,
+    '删除行数': `-${r.totalDel}`,
+    '受影响模块': [...r.modules].join(", ") || "无",
+    '分析结果': r.passed ? "✓ 通过" : "✗ 需要关注",
+  };
+  let report = buildReport('变更分析报告', fields, r.issues, verbose);
+
+  if (r.changes.length && verbose) {
+    const lines = ["\n" + DASH, "变更文件列表:", DASH];
+    const icons = { added: "➕", modified: "📝", deleted: "➖", renamed: "📋" };
+    for (const c of r.changes) {
+      const tags = [];
+      if (c.is_code) tags.push("代码");
+      if (c.is_doc) tags.push("文档");
+      if (c.is_test) tags.push("测试");
+      if (c.is_config) tags.push("配置");
+      const t = tags.length ? ` [${tags.join(", ")}]` : "";
+      lines.push(`  ${icons[c.type] || "📝"} ${c.path}${t} (+${c.additions}/-${c.deletions})`);
+    }
+    report += '\n' + lines.join('\n');
+  }
+
+  if (Object.keys(r.docStatus).length) {
+    const lines = ["\n" + DASH, "文档同步状态:", DASH];
+    for (const [doc, synced] of Object.entries(r.docStatus)) {
+      lines.push(`  ${synced ? "✓" : "✗"} ${doc}`);
+    }
+    report += '\n' + lines.join('\n');
+  }
+
+  return report;
+}
+
+// CLI
+if (require.main === module) {
+  const opts = parseCliArgs(process.argv);
+  const result = analyzeChanges(opts.mode || "working");
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      passed: result.passed,
+      total_additions: result.totalAdd,
+      total_deletions: result.totalDel,
+      affected_modules: [...result.modules],
+      changes: result.changes.map(c => ({
+        path: c.path, type: c.type, additions: c.additions,
+        deletions: c.deletions, is_code: c.is_code,
+        is_doc: c.is_doc, is_test: c.is_test
+      })),
+      issues: result.issues.map(i => ({
+        severity: i.severity, message: i.message,
+        related_files: i.related_files,
+      })),
+      doc_sync_status: result.docStatus,
+    }, null, 2));
+  } else {
+    console.log(formatReport(result, opts.verbose));
+  }
+
+  process.exit(result.passed ? 0 : 1);
+}
+
+module.exports = { normalizePath, classifyFile, parsePorcelainLine, parseNameStatusLine, identifyModules };

package/skills/tools/verify-module/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: verify-module
+description: 模块完整性校验关卡。扫描目录结构、检测缺失文档、验证代码与文档同步。当魔尊提到模块校验、文档检查、结构完整性、README检查、DESIGN检查时使用。在新建模块完成时自动触发。
+license: MIT
+compatibility: node>=18
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: Bash, Read, Glob
+argument-hint: <模块路径>
+---
+
+# ⚖ 校验关卡 · 模块完整性
+
+
+## 核心原则
+
+```
+模块 = 代码 + README.md + DESIGN.md
+缺一不可，残缺即异端
+```
+
+## 自动扫描
+
+运行扫描脚本（跨平台）：
+
+```bash
+# 在 verify-module 目录下运行（推荐）
+node scripts/module_scanner.js <模块路径>
+node scripts/module_scanner.js <模块路径> -v      # 详细模式
+node scripts/module_scanner.js <模块路径> --json  # JSON 输出
+```
+
+## 校验标准
+
+一个完整的模块必须包含：
+
+```
+module/
+├── README.md      # 必须 - 模块是什么、为什么存在
+├── DESIGN.md      # 必须 - 设计决策、权衡取舍
+├── src/           # 代码实现
+└── tests/         # 测试用例（如适用）
+```
+
+## 检测项
+
+### 必须存在
+
+| 文件 | 说明 | 缺失后果 |
+|------|------|----------|
+| `README.md` | 模块说明文档 | 🔴 阻断交付 |
+| `DESIGN.md` | 设计决策文档 | 🔴 阻断交付 |
+
+### 推荐存在
+
+| 文件/目录 | 说明 | 缺失后果 |
+|-----------|------|----------|
+| `tests/` | 测试目录 | 🟠 警告 |
+| `__init__.py` | Python 包标识 | 🟡 提示 |
+| `.gitignore` | Git 忽略配置 | 🔵 信息 |
+
+### README.md 必须包含
+
+- [ ] **模块名称与定位** — 一句话说明是什么
+- [ ] **存在理由** — 为什么需要这个模块
+- [ ] **核心职责** — 做什么、不做什么
+- [ ] **依赖关系** — 依赖谁、被谁依赖
+- [ ] **快速使用** — 最简示例
+
+### DESIGN.md 必须包含
+
+- [ ] **设计目标** — 要解决什么问题
+- [ ] **方案选择** — 考虑过哪些方案、为何选当前方案
+- [ ] **关键决策** — 重要的技术决策及理由
+- [ ] **已知限制** — 当前方案的局限性
+- [ ] **变更历史** — 重大变更记录
+
+## 自动触发时机
+
+| 场景 | 触发条件 |
+|------|----------|
+| 新建模块 | 模块创建完成时 |
+| 模块重构 | 重构完成时 |
+| 提交前 | 代码提交前检查 |
+
+## 校验流程
+
+```
+1. 运行 module_scanner.js 自动扫描
+2. 检查文件结构是否完整
+3. 检查 README.md 各项是否齐全
+4. 检查 DESIGN.md 各项是否齐全
+5. 检查代码与文档描述是否一致
+6. 输出校验报告
+```
+
+## 校验报告格式
+
+```
+## 模块校验报告
+
+### 模块: <模块名>
+
+✓ 通过 | ✗ 未通过
+
+### 文件检查
+- README.md: ✓ 存在 / ✗ 缺失
+- DESIGN.md: ✓ 存在 / ✗ 缺失
+- tests/: ✓ 存在 / ⚠️ 缺失
+
+### 内容检查
+- README 完整性: ✓ 完整 / ⚠️ 缺少 [X, Y, Z]
+- DESIGN 完整性: ✓ 完整 / ⚠️ 缺少 [X, Y, Z]
+
+### 结论
+可交付 / 需补充后交付
+```
+
+## 快速修复
+
+如果缺少文档，可使用文档生成器：
+
+```bash
+/gen-docs <模块路径>
+```
+
+---