code-abyss 1.6.16 → 1.7.1

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

@@ -0,0 +1,363 @@
+#!/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/lib/shared.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * 验证工具共享库
+ * 消灭 verify-* 脚本间的重复代码
+ */
+
+// --- CLI 参数解析 ---
+
+function parseCliArgs(argv, extraFlags) {
+  const args = argv.slice(2);
+  const result = { target: '.', verbose: false, json: false };
+  if (extraFlags) Object.assign(result, extraFlags);
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '-v' || args[i] === '--verbose') result.verbose = true;
+    else if (args[i] === '--json') result.json = true;
+    else if (args[i] === '-h' || args[i] === '--help') { result.help = true; }
+    else if (args[i] === '--mode' && args[i + 1]) { result.mode = args[++i]; }
+    else if (args[i] === '--exclude') {
+      result.exclude = result.exclude || [];
+      while (i + 1 < args.length && !args[i + 1].startsWith('-')) result.exclude.push(args[++i]);
+    }
+    else if (!args[i].startsWith('-')) result.target = args[i];
+  }
+  return result;
+}
+
+// --- 报告格式化 ---
+
+const SEP = '='.repeat(60);
+const DASH = '-'.repeat(40);
+const ICONS = {
+  error: '\u2717', warning: '\u26A0', info: '\u2139',
+  critical: '\u{1F534}', high: '\u{1F7E0}', medium: '\u{1F7E1}', low: '\u{1F535}'
+};
+
+function reportHeader(title, fields) {
+  const lines = [SEP, title, SEP];
+  for (const [k, v] of Object.entries(fields)) {
+    lines.push(`\n${k}: ${v}`);
+  }
+  return lines;
+}
+
+function reportIssues(issues, verbose, groupBy) {
+  if (!issues.length) return [];
+  const lines = ['\n' + DASH, '问题列表:', DASH];
+
+  if (groupBy) {
+    const groups = {};
+    for (const i of issues) (groups[i[groupBy]] || (groups[i[groupBy]] = [])).push(i);
+    for (const cat of Object.keys(groups).sort()) {
+      const items = groups[cat];
+      lines.push(`\n【${cat}】(${items.length} 个)`);
+      for (const i of items.slice(0, 10)) {
+        lines.push(`  ${ICONS[i.severity] || '\u2139'} ` +
+          `${i.file_path || ''}${i.line_number ? ':' + i.line_number : ''}`);
+        lines.push(`    ${i.message}`);
+        if (verbose && i.suggestion) lines.push(`    \u{1F4A1} ${i.suggestion}`);
+        if (verbose && i.recommendation) lines.push(`    \u{1F4A1} ${i.recommendation}`);
+      }
+      if (items.length > 10) lines.push(`  ... 及其他 ${items.length - 10} 个问题`);
+    }
+  } else {
+    for (const i of issues) {
+      const icon = ICONS[i.severity] || '\u2139';
+      lines.push(`  ${icon} [${i.severity.toUpperCase()}] ${i.message}`);
+      if (i.path && verbose) lines.push(`    路径: ${i.path}`);
+    }
+  }
+  return lines;
+}
+
+function reportFooter() { return ['\n' + SEP]; }
+
+function buildReport(title, fields, issues, verbose, groupBy) {
+  return [...reportHeader(title, fields), ...reportIssues(issues, verbose, groupBy), ...reportFooter()].join('\n');
+}
+
+// --- 通用计数 ---
+
+function countBySeverity(issues, field) {
+  field = field || 'severity';
+  const counts = {};
+  for (const i of issues) counts[i[field]] = (counts[i[field]] || 0) + 1;
+  return counts;
+}
+
+function hasFatal(issues, fatalLevels) {
+  fatalLevels = fatalLevels || ['error'];
+  return issues.some(i => fatalLevels.includes(i.severity));
+}
+
+module.exports = {
+  parseCliArgs, buildReport, reportHeader, reportIssues,
+  reportFooter, countBySeverity, hasFatal, SEP, DASH, ICONS
+};

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. 评估变更影响