code-yangzz 1.0.0

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,126 @@
+---
+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 <模块路径>
+```
+
+---

package/skills/tools/verify-module/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Verify Module"
+  short_description: "模块完整性校验关卡"
+  default_prompt: "Read the skill at skills/tools/verify-module/SKILL.md, then run: node skills/run_skill.js verify-module $ARGUMENTS"

package/skills/tools/verify-module/scripts/module_scanner.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseCliArgs, buildReport, hasFatal } = require(path.join(__dirname, '..', '..', 'lib', 'shared.js'));
+
+const REQUIRED_FILES = { 'README.md': '模块说明文档', 'DESIGN.md': '设计决策文档' };
+const ALT_SRC_DIRS = ['src', 'lib', 'pkg', 'internal', 'cmd', 'app'];
+const ALT_TEST_DIRS = ['tests', 'test', '__tests__', 'spec'];
+const ROOT_SCRIPT_FILES = new Set([
+  'install.sh', 'uninstall.sh', 'install.ps1',
+  'uninstall.ps1', 'Dockerfile', 'Makefile'
+]);
+const CODE_EXTS = new Set(['.py', '.go', '.rs', '.ts', '.js', '.java', '.sh', '.ps1']);
+const TEST_PATTERNS = ['test_', '_test.', '.test.', 'spec_', '_spec.'];
+
+function scanStructure(p, depth = 3) {
+  const s = { name: path.basename(p), type: 'dir', children: [] };
+  if (depth <= 0) return s;
+  try {
+    for (const name of fs.readdirSync(p).sort()) {
+      if (name.startsWith('.')) continue;
+      const full = path.join(p, name);
+      const stat = fs.statSync(full);
+      if (stat.isFile()) s.children.push({ name, type: 'file', size: stat.size });
+      else if (stat.isDirectory()) s.children.push(scanStructure(full, depth - 1));
+    }
+  } catch {}
+  return s;
+}
+
+function rglob(dir, test) {
+  try {
+    for (const name of fs.readdirSync(dir)) {
+      const full = path.join(dir, name);
+      try {
+        const stat = fs.statSync(full);
+        if (stat.isFile() && test(name)) return true;
+        if (stat.isDirectory()) { if (rglob(full, test)) return true; }
+      } catch {}
+    }
+  } catch {}
+  return false;
+}
+
+function scanModule(target) {
+  const modulePath = path.resolve(target);
+  const issues = [];
+  const add = (severity, message, p) => issues.push({ severity, message, path: p || null });
+
+  if (!fs.existsSync(modulePath)) {
+    add('error', `路径不存在: ${modulePath}`);
+    return { modulePath, issues, structure: {} };
+  }
+  if (!fs.statSync(modulePath).isDirectory()) {
+    add('error', `不是目录: ${modulePath}`);
+    return { modulePath, issues, structure: {} };
+  }
+
+  const structure = scanStructure(modulePath);
+
+  // required files
+  for (const [file, desc] of Object.entries(REQUIRED_FILES)) {
+    const fp = path.join(modulePath, file);
+    if (!fs.existsSync(fp)) add('error', `缺少必需文档: ${file} (${desc})`, fp);
+    else if (fs.statSync(fp).size < 50) add('warning', `文档内容过少: ${file} (< 50 bytes)`, fp);
+  }
+
+  // source dirs
+  let srcFound = ALT_SRC_DIRS.some(d => {
+    try { return fs.statSync(path.join(modulePath, d)).isDirectory(); }
+    catch { return false; }
+  });
+  const entries = fs.readdirSync(modulePath);
+  const rootCode = entries.filter(n => {
+    try {
+      const s = fs.statSync(path.join(modulePath, n));
+      return s.isFile() && CODE_EXTS.has(path.extname(n));
+    } catch { return false; }
+  });
+  const rootScript = entries.filter(n => {
+    try {
+      return fs.statSync(path.join(modulePath, n)).isFile()
+        && ROOT_SCRIPT_FILES.has(n);
+    } catch { return false; }
+  });
+  if (rootCode.length || rootScript.length) {
+    srcFound = true;
+    if (rootCode.length > 5) {
+      add('warning', `根目录代码文件过多 (${rootCode.length}个)，建议整理到 src/ 目录`);
+    }
+  }
+  if (!srcFound) add('warning', '未找到源码目录或代码文件');
+
+  // test dirs
+  let testFound = ALT_TEST_DIRS.some(d => {
+    try { return fs.statSync(path.join(modulePath, d)).isDirectory(); }
+    catch { return false; }
+  });
+  if (!testFound) testFound = rglob(modulePath, n => TEST_PATTERNS.some(p => n.includes(p)));
+  if (!testFound) add('warning', '未找到测试目录或测试文件');
+
+  // doc quality
+  const readme = path.join(modulePath, 'README.md');
+  if (fs.existsSync(readme)) {
+    const c = fs.readFileSync(readme, 'utf-8');
+    if (!c.includes('#')) add('warning', 'README.md 缺少标题', readme);
+    const docKeys = ['usage', 'install', '使用', '安装', 'example', '示例'];
+    if (!docKeys.some(k => c.toLowerCase().includes(k)))
+      add('info', 'README.md 建议添加使用说明或示例', readme);
+  }
+  const design = path.join(modulePath, 'DESIGN.md');
+  if (fs.existsSync(design)) {
+    const c = fs.readFileSync(design, 'utf-8');
+    const designKeys = ['决策', 'decision', '选择', 'choice', '权衡', 'trade'];
+    if (!designKeys.some(k => c.toLowerCase().includes(k)))
+      add('info', 'DESIGN.md 建议记录设计决策和权衡', design);
+  }
+
+  return { modulePath, issues, structure };
+}
+
+function formatStructure(s, indent = 0) {
+  const pre = '  '.repeat(indent);
+  if (s.type === 'dir') {
+    const lines = [`${pre}\u{1F4C1} ${s.name}/`];
+    for (const ch of (s.children || [])) lines.push(formatStructure(ch, indent + 1));
+    return lines.join('\n');
+  }
+  const sz = (s.size || 0) < 1024 ? `(${s.size} B)` : `(${Math.floor(s.size / 1024)} KB)`;
+  return `${pre}\u{1F4C4} ${s.name} ${sz}`;
+}
+
+function formatReport(r, verbose) {
+  const errs = r.issues.filter(i => i.severity === 'error').length;
+  const warns = r.issues.filter(i => i.severity === 'warning').length;
+  const passed = !hasFatal(r.issues);
+  const fields = {
+    '模块路径': r.modulePath,
+    '扫描结果': passed ? '\u2713 通过' : '\u2717 未通过',
+    '统计': `错误: ${errs} | 警告: ${warns}`,
+  };
+  const issues = r.issues.map(i => ({
+    severity: i.severity, message: i.message, path: i.path,
+    file_path: i.path || '', line_number: null,
+  }));
+  let report = buildReport('模块完整性扫描报告', fields, issues, verbose);
+  if (verbose && r.structure.name) {
+    report += '\n' + '-'.repeat(40) + '\n目录结构:\n' + '-'.repeat(40) + '\n' + formatStructure(r.structure);
+  }
+  return report;
+}
+
+// CLI
+const opts = parseCliArgs(process.argv);
+const result = scanModule(opts.target);
+const passed = !hasFatal(result.issues);
+
+if (opts.json) {
+  console.log(JSON.stringify({
+    module_path: result.modulePath, passed,
+    error_count: result.issues.filter(i => i.severity === 'error').length,
+    warning_count: result.issues.filter(i => i.severity === 'warning').length,
+    issues: result.issues
+  }, null, 2));
+} else {
+  console.log(formatReport(result, opts.verbose));
+}
+
+process.exit(passed ? 0 : 1);