code-abyss 1.6.16 → 1.7.0

package/skills/tools/gen-docs/scripts/doc_generator.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+/**
+ * 文档生成器
+ * 自动生成/更新 README.md 和 DESIGN.md 骨架
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// --- Utilities ---
+
+function rglob(dir, filter) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...rglob(full, filter));
+    } else if (!filter || filter(entry.name, full)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+// --- Language Detection ---
+
+const LANG_MAP = {
+  '.py': 'Python', '.go': 'Go', '.rs': 'Rust', '.ts': 'TypeScript',
+  '.js': 'JavaScript', '.java': 'Java', '.c': 'C', '.cpp': 'C++',
+};
+
+function detectLanguage(modPath) {
+  const exts = {};
+  try {
+    for (const f of rglob(modPath)) {
+      const ext = path.extname(f).toLowerCase();
+      if (ext) exts[ext] = (exts[ext] || 0) + 1;
+    }
+  } catch { return 'Unknown'; }
+  const codeExts = Object.entries(exts).filter(([k]) => k in LANG_MAP);
+  if (codeExts.length) {
+    const best = codeExts.reduce((a, b) => b[1] > a[1] ? b : a);
+    return LANG_MAP[best[0]] || 'Unknown';
+  }
+  return 'Unknown';
+}
+
+// --- Python AST-lite extraction via regex ---
+
+function analyzePythonModule(modPath) {
+  const info = makeInfo(modPath, 'Python');
+  const pyFiles = rglob(modPath, (name) => name.endsWith('.py'));
+  info.files = pyFiles.map(f => path.relative(modPath, f));
+
+  for (const pyFile of pyFiles) {
+    const basename = path.basename(pyFile);
+    if (basename.startsWith('test_') || basename.includes('_test')) continue;
+    let content;
+    try { content = fs.readFileSync(pyFile, 'utf-8'); } catch { continue; }
+
+    // Module docstring (triple-quoted at top)
+    if (!info.description) {
+      const docM = content.match(/^(?:#[^\n]*\n)*\s*(?:"""([\s\S]*?)"""|'''([\s\S]*?)''')/);
+      if (docM) info.description = (docM[1] || docM[2]).split('\n')[0].trim();
+    }
+
+    const rel = path.relative(modPath, pyFile);
+
+    // Functions
+    for (const m of content.matchAll(/^def\s+([A-Za-z]\w*)\s*\(/gm)) {
+      info.functions.push({ name: m[1], file: rel, doc: '' });
+    }
+    // Classes
+    for (const m of content.matchAll(/^class\s+([A-Za-z]\w*)\s*[:(]/gm)) {
+      info.classes.push({ name: m[1], file: rel, doc: '' });
+    }
+
+    // Entry points
+    if (['main.py', '__main__.py', 'cli.py', 'app.py'].includes(basename)) {
+      info.entry_points.push(rel);
+    }
+  }
+
+  // Dependencies
+  const reqPath = path.join(modPath, 'requirements.txt');
+  try {
+    const content = fs.readFileSync(reqPath, 'utf-8');
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith('#')) {
+        info.dependencies.push(trimmed.split(/[=><]/)[0]);
+      }
+    }
+  } catch {}
+
+  return info;
+}
+
+// --- Generic analysis (regex fallback) ---
+
+const LANG_PATTERNS = {
+  'Go':         [/^\s*func\s+(\w+)/,              /^\s*type\s+(\w+)\s+struct\b/],
+  'Rust':       [/^\s*(?:pub\s+)?fn\s+(\w+)/,     /^\s*(?:pub\s+)?struct\s+(\w+)/],
+  'TypeScript': [/^\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)/, /^\s*(?:export\s+)?class\s+(\w+)/],
+  'JavaScript': [/^\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)/, /^\s*(?:export\s+)?class\s+(\w+)/],
+  'Java':       [/^\s*(?:public|private|protected)?\s*(?:static\s+)?\w+\s+(\w+)\s*\(/, /^\s*(?:public\s+)?class\s+(\w+)/],
+  'C++':        [/^\s*(?:\w+\s+)+(\w+)\s*\([^;]*$/, /^\s*class\s+(\w+)/],
+  'C':          [/^\s*(?:\w+\s+)+(\w+)\s*\([^;]*$/, null],
+};
+
+const CODE_EXTS = new Set(['.py', '.go', '.rs', '.ts', '.js', '.java', '.c', '.cpp']);
+
+function analyzeModule(modPath) {
+  const language = detectLanguage(modPath);
+  if (language === 'Python') return analyzePythonModule(modPath);
+
+  const info = makeInfo(modPath, language);
+  const [funcPat, clsPat] = LANG_PATTERNS[language] || [null, null];
+
+  try {
+    for (const f of rglob(modPath)) {
+      if (!CODE_EXTS.has(path.extname(f).toLowerCase())) continue;
+      const rel = path.relative(modPath, f);
+      info.files.push(rel);
+
+      if (!funcPat && !clsPat) continue;
+      let content;
+      try { content = fs.readFileSync(f, 'utf-8'); } catch { continue; }
+      for (const line of content.split('\n')) {
+        if (funcPat) {
+          const m = line.match(funcPat);
+          if (m && !m[1].startsWith('_')) info.functions.push({ name: m[1], file: rel, doc: '' });
+        }
+        if (clsPat) {
+          const m = line.match(clsPat);
+          if (m && !m[1].startsWith('_')) info.classes.push({ name: m[1], file: rel, doc: '' });
+        }
+      }
+    }
+  } catch {}
+
+  return info;
+}
+
+function makeInfo(modPath, language) {
+  return {
+    name: path.basename(modPath), path: modPath, description: '', language,
+    files: [], functions: [], classes: [], dependencies: [], entry_points: [],
+  };
+}
+
+// --- README Generation ---
+
+function generateReadme(info) {
+  const L = [];
+  L.push(`# ${info.name}`, '');
+  if (info.description) {
+    L.push(info.description);
+  } else {
+    L.push('> 请在此描述模块的核心功能、解决的问题和主要用途。');
+    L.push('> 例如：本模块提供 X 功能，用于解决 Y 问题。');
+  }
+  L.push('', '## 概述', '', '<!-- 描述这个模块是什么，解决什么问题 -->', '');
+  L.push('## 特性', '', '<!-- 列出模块的主要特性，每项应包含简短描述 -->', '');
+  L.push('- **特性1**: 请描述第一个主要特性');
+  L.push('- **特性2**: 请描述第二个主要特性');
+  L.push('- **特性3**: 请描述第三个主要特性', '');
+
+  if (info.dependencies.length) {
+    L.push('## 依赖', '', '```');
+    info.dependencies.slice(0, 10).forEach(d => L.push(d));
+    if (info.dependencies.length > 10) L.push(`# ... 及其他 ${info.dependencies.length - 10} 个依赖`);
+    L.push('```', '');
+  }
+
+  L.push('## 使用方法', '');
+  if (info.entry_points.length) {
+    L.push('### 运行', '', '```bash');
+    const cmds = { Python: `python -m ${info.name}`, Go: 'go run ./cmd/main.go', Rust: 'cargo run', TypeScript: 'npm start', JavaScript: 'npm start' };
+    L.push(cmds[info.language] || `# 请根据 ${info.language} 项目结构添加运行命令`);
+    L.push('```', '');
+  }
+
+  L.push('### 示例', '');
+  const EXAMPLES = {
+    Python: `from ${info.name.toLowerCase()} import main\n\n# 初始化\nobj = main()\n\n# 执行操作\nresult = obj.process()\nprint(result)`,
+    Go: `package main\n\nimport "${info.name.toLowerCase()}"\n\nfunc main() {\n    // 初始化\n    obj := ${info.name.toLowerCase()}.New()\n\n    // 执行操作\n    result := obj.Process()\n    println(result)\n}`,
+    Rust: `use ${info.name.toLowerCase()}::*;\n\nfn main() {\n    // 初始化\n    let obj = Object::new();\n\n    // 执行操作\n    let result = obj.process();\n    println!("{}", result);\n}`,
+    TypeScript: `import { main } from "./${info.name.toLowerCase()}";\n\n// 初始化\nconst obj = new main();\n\n// 执行操作\nconst result = obj.process();\nconsole.log(result);`,
+    JavaScript: `const { main } = require("./${info.name.toLowerCase()}");\n\n// 初始化\nconst obj = new main();\n\n// 执行操作\nconst result = obj.process();\nconsole.log(result);`,
+  };
+  if (EXAMPLES[info.language]) {
+    L.push('```' + info.language.toLowerCase(), EXAMPLES[info.language], '```');
+  } else {
+    L.push('```' + info.language.toLowerCase());
+    L.push(`<!-- 请根据 ${info.language} 语言特性提供使用示例 -->`);
+    L.push(`<!-- 示例应包含：初始化、基本操作、结果处理 -->`);
+    L.push('```');
+  }
+  L.push('');
+
+  if (info.classes.length || info.functions.length) {
+    L.push('## API 概览', '');
+    if (info.classes.length) {
+      L.push('### 类', '', '| 类名 | 描述 |', '|------|------|');
+      info.classes.slice(0, 10).forEach(c => L.push(`| \`${c.name}\` | ${c.doc || '请补充此类的功能描述'} |`));
+      L.push('');
+    }
+    if (info.functions.length) {
+      L.push('### 函数', '', '| 函数 | 描述 |', '|------|------|');
+      info.functions.slice(0, 10).forEach(f => L.push(`| \`${f.name}()\` | ${f.doc || '请补充此函数的功能描述'} |`));
+      L.push('');
+    }
+  }
+
+  L.push('## 目录结构', '', '```', `${info.name}/`);
+  info.files.sort().slice(0, 15).forEach(f => L.push(`├── ${f}`));
+  if (info.files.length > 15) L.push(`└── ... (${info.files.length - 15} more files)`);
+  L.push('```', '');
+  L.push('## 相关文档', '', '- [设计文档](DESIGN.md)', '');
+  return L.join('\n');
+}
+
+// --- DESIGN Generation ---
+
+function generateDesign(info) {
+  const today = new Date().toISOString().slice(0, 10);
+  const L = [];
+  L.push(`# ${info.name} 设计文档`, '');
+  L.push('## 设计概述', '', '### 目标', '', '<!-- 这个模块要解决什么问题？ -->', '');
+  L.push('### 非目标', '', '<!-- 这个模块明确不做什么？ -->', '');
+  L.push('## 架构设计', '', '### 整体架构', '', '```');
+  L.push('┌─────────────────────────────────────┐');
+  L.push('│  请在此绘制模块的整体架构图          │');
+  L.push('│  包括主要组件、数据流、依赖关系      │');
+  L.push('│  可使用 ASCII 图或 Mermaid 图表      │');
+  L.push('└─────────────────────────────────────┘');
+  L.push('```', '');
+  L.push('### 核心组件', '');
+  if (info.classes.length) {
+    info.classes.slice(0, 5).forEach(c => L.push(`- **${c.name}**: ${c.doc || '请描述此组件的职责和功能'}`));
+  } else {
+    L.push('<!-- 列出模块的核心组件及其职责 -->');
+    L.push('- **组件1**: 请描述第一个核心组件的职责');
+    L.push('- **组件2**: 请描述第二个核心组件的职责');
+    L.push('- **组件3**: 请描述第三个核心组件的职责');
+  }
+  L.push('');
+  L.push('## 设计决策', '', '### 决策记录', '');
+  L.push('| 日期 | 决策 | 理由 | 影响 |', '|------|------|------|------|');
+  L.push(`| ${today} | 初始设计 | - | - |`, '');
+  L.push('### 技术选型', '', `- **语言**: ${info.language}`);
+  if (info.dependencies.length) L.push(`- **主要依赖**: ${info.dependencies.slice(0, 5).join(', ')}`);
+  L.push('- **理由**: <!-- 请说明为什么选择这些技术栈，包括性能、可维护性、生态等考量 -->', '');
+  L.push('## 权衡取舍', '', '### 已知限制', '');
+  L.push('<!-- 列出模块的已知限制和约束条件 -->');
+  L.push('- **限制1**: 请描述第一个已知限制及其原因');
+  L.push('- **限制2**: 请描述第二个已知限制及其原因', '');
+  L.push('### 技术债务', '');
+  L.push('<!-- 记录有意引入的技术债务、临时方案及其原因 -->');
+  L.push('- **债务1**: 描述 | 原因：性能优先 | 计划偿还时间：v2.0', '');
+  L.push('## 安全考量', '', '### 威胁模型', '');
+  L.push('<!-- 识别潜在的安全威胁，如认证、授权、数据泄露等 -->');
+  L.push('- **威胁1**: 请描述潜在威胁及其影响');
+  L.push('- **威胁2**: 请描述潜在威胁及其影响', '');
+  L.push('### 安全措施', '');
+  L.push('<!-- 列出已实施的安全措施，如输入验证、加密、访问控制等 -->');
+  L.push('- **措施1**: 请描述已实施的安全措施');
+  L.push('- **措施2**: 请描述已实施的安全措施', '');
+  L.push('## 变更历史', '', `### ${today} - 初始版本`, '');
+  L.push('**变更内容**: 创建模块', '', '**变更理由**: 初始开发', '');
+  return L.join('\n');
+}
+
+// --- Core: generate_docs ---
+
+function generateDocs(targetPath, force) {
+  const modPath = path.resolve(targetPath);
+  const result = { readme: null, design: null, status: 'success', messages: [] };
+
+  if (!fs.existsSync(modPath)) {
+    result.status = 'error';
+    result.messages.push(`路径不存在: ${modPath}`);
+    return result;
+  }
+
+  const info = analyzeModule(modPath);
+
+  const readmePath = path.join(modPath, 'README.md');
+  if (fs.existsSync(readmePath) && !force) {
+    result.messages.push('README.md 已存在，跳过（使用 --force 覆盖）');
+  } else {
+    fs.writeFileSync(readmePath, generateReadme(info));
+    result.readme = readmePath;
+    result.messages.push('已生成 README.md');
+  }
+
+  const designPath = path.join(modPath, 'DESIGN.md');
+  if (fs.existsSync(designPath) && !force) {
+    result.messages.push('DESIGN.md 已存在，跳过（使用 --force 覆盖）');
+  } else {
+    fs.writeFileSync(designPath, generateDesign(info));
+    result.design = designPath;
+    result.messages.push('已生成 DESIGN.md');
+  }
+
+  return result;
+}
+
+// --- CLI ---
+
+function parseArgs(argv) {
+  const args = { path: '.', force: false, json: false, readmeOnly: false, designOnly: false };
+  const rest = argv.slice(2);
+  const positional = [];
+  for (const a of rest) {
+    if (a === '-f' || a === '--force') args.force = true;
+    else if (a === '--json') args.json = true;
+    else if (a === '--readme-only') args.readmeOnly = true;
+    else if (a === '--design-only') args.designOnly = true;
+    else if (a === '-h' || a === '--help') {
+      console.log('Usage: doc_generator.js [path] [-f|--force] [--json] [--readme-only] [--design-only]');
+      process.exit(0);
+    } else positional.push(a);
+  }
+  if (positional.length) args.path = positional[0];
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const result = generateDocs(args.path, args.force);
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log('='.repeat(50));
+    console.log('文档生成报告');
+    console.log('='.repeat(50));
+    for (const msg of result.messages) {
+      console.log(`  \u2022 ${msg}`);
+    }
+    console.log('='.repeat(50));
+  }
+
+  process.exit(result.status === 'success' ? 0 : 1);
+}
+
+main();

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

@@ -1,6 +1,8 @@
 ---
 name: verify-change
 description: 变更校验关卡。分析代码变更，检测文档同步状态，评估变更影响范围。当魔尊提到变更检查、文档同步、代码审查、提交前检查、diff分析时使用。在设计级变更、重构完成时自动触发。
+license: MIT
+compatibility: node>=18
 user-invocable: true
 disable-model-invocation: false
 allowed-tools: Bash, Read, Grep
@@ -24,11 +26,11 @@ argument-hint: [--mode working|staged|committed]
 
 ```bash
 # 在 skill 目录下运行
-python scripts/change_analyzer.py                    # 分析工作区变更（默认）
-python scripts/change_analyzer.py --mode staged      # 分析暂存区变更
-python scripts/change_analyzer.py --mode committed   # 分析已提交变更
-python scripts/change_analyzer.py -v                 # 详细模式
-python scripts/change_analyzer.py --json             # JSON 输出
+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 输出
 ```
 
 ## 检测能力
@@ -107,7 +109,7 @@ python scripts/change_analyzer.py --json             # JSON 输出
 ## 校验流程
 
 ```
-1. 运行 change_analyzer.py 自动分析
+1. 运行 change_analyzer.js 自动分析
 2. 识别变更文件和受影响模块
 3. 检查文档同步状态
 4. 评估变更影响

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

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+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 execSync(`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 L = [];
+  const sep = "=".repeat(60);
+  const sep2 = "-".repeat(40);
+  L.push(sep, "变更分析报告", sep);
+  L.push(`\n变更文件: ${r.changes.length}`);
+  L.push(`新增行数: +${r.totalAdd}`);
+  L.push(`删除行数: -${r.totalDel}`);
+  L.push(`受影响模块: ${[...r.modules].join(", ") || "无"}`);
+  L.push(`分析结果: ${r.passed ? "✓ 通过" : "✗ 需要关注"}`);
+
+  if (r.changes.length && verbose) {
+    L.push("\n" + sep2, "变更文件列表:", sep2);
+    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(", ")}]` : "";
+      L.push(`  ${icons[c.type] || "📝"} ${c.path}${t} (+${c.additions}/-${c.deletions})`);
+    }
+  }
+
+  if (r.issues.length) {
+    L.push("\n" + sep2, "问题与建议:", sep2);
+    const si = { error: "✗", warning: "⚠", info: "ℹ" };
+    for (const i of r.issues) {
+      L.push(`\n  ${si[i.severity] || "ℹ"} [${i.severity.toUpperCase()}] ${i.message}`);
+      if (verbose && i.related_files.length) {
+        for (const f of i.related_files.slice(0, 5)) L.push(`      - ${f}`);
+        if (i.related_files.length > 5) L.push(`      ... 及其他 ${i.related_files.length - 5} 个文件`);
+      }
+    }
+  }
+
+  if (Object.keys(r.docStatus).length) {
+    L.push("\n" + sep2, "文档同步状态:", sep2);
+    for (const [doc, synced] of Object.entries(r.docStatus)) {
+      L.push(`  ${synced ? "✓" : "✗"} ${doc}`);
+    }
+  }
+
+  L.push("\n" + sep);
+  return L.join("\n");
+}
+
+// CLI
+const args = process.argv.slice(2);
+let mode = "working", verbose = false, jsonOut = false;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--mode" && args[i + 1]) { mode = args[++i]; }
+  else if (args[i] === "-v" || args[i] === "--verbose") { verbose = true; }
+  else if (args[i] === "--json") { jsonOut = true; }
+}
+
+const result = analyzeChanges(mode);
+
+if (jsonOut) {
+  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, verbose));
+}
+
+process.exit(result.passed ? 0 : 1);

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

@@ -1,6 +1,8 @@
 ---
 name: verify-module
 description: 模块完整性校验关卡。扫描目录结构、检测缺失文档、验证代码与文档同步。当魔尊提到模块校验、文档检查、结构完整性、README检查、DESIGN检查时使用。在新建模块完成时自动触发。
+license: MIT
+compatibility: node>=18
 user-invocable: true
 disable-model-invocation: false
 allowed-tools: Bash, Read, Glob
@@ -23,9 +25,9 @@ argument-hint: <模块路径>
 
 ```bash
 # 在 verify-module 目录下运行（推荐）
-python scripts/module_scanner.py <模块路径>
-python scripts/module_scanner.py <模块路径> -v      # 详细模式
-python scripts/module_scanner.py <模块路径> --json  # JSON 输出
+node scripts/module_scanner.js <模块路径>
+node scripts/module_scanner.js <模块路径> -v      # 详细模式
+node scripts/module_scanner.js <模块路径> --json  # JSON 输出
 ```
 
 ## 校验标准
@@ -84,7 +86,7 @@ module/
 ## 校验流程
 
 ```
-1. 运行 module_scanner.py 自动扫描
+1. 运行 module_scanner.js 自动扫描
 2. 检查文件结构是否完整
 3. 检查 README.md 各项是否齐全
 4. 检查 DESIGN.md 各项是否齐全