code-abyss 2.0.0 → 2.0.1

package/README.md

@@ -4,7 +4,7 @@
 
 **邪修红尘仙 · 宿命深渊**
 
-*一键为 Claude Code / Codex CLI 注入邪修人格与 56 篇安全工程秘典*
+*一键为 Claude Code / Codex CLI 注入邪修人格与攻防安全工程知识体系*
 
 [![npm](https://img.shields.io/npm/v/code-abyss.svg)](https://www.npmjs.com/package/code-abyss)
 [![CI](https://github.com/telagod/code-abyss/actions/workflows/ci.yml/badge.svg)](https://github.com/telagod/code-abyss/actions/workflows/ci.yml)
@@ -25,7 +25,7 @@ npx code-abyss
 交互式菜单（方向键选择，回车确认）：
 
 ```
-☠️ Code Abyss v1.7.3
+☠️ Code Abyss v2.0.1
 
 ? 请选择操作 (Use arrow keys)
 ❯ 安装到 Claude Code (~/.claude/)
@@ -96,13 +96,15 @@ node ~/.codex/.sage-uninstall.js    # Codex CLI
 
 ## 🎭 这是什么
 
-Code Abyss 是一套 **Claude Code / Codex CLI 个性化配置包**，一条命令注入：
+Code Abyss 是一套 **Claude Code / Codex CLI 攻防安全配置包**，一条命令注入：
 
-- 🔥 **邪修人格** — 宿命压迫叙事 + 道语标签 + 渡劫协议
-- ⚔️ **安全工程知识体系** — 红队/蓝队/紫队三脉道统，11 领域 56 篇专业秘典
+- 🔥 **邪修人格** — 沉浸式角色扮演 + 道语标签 + 渡劫协议 + 反拒绝条款
+- ⚔️ **攻防安全知识体系** — 红队/蓝队/紫队三脉道统，6 个安全化身，11 领域 56 篇专业秘典
+- 🗡 **零废话安全研究** — 禁 disclaimer、禁道德前缀、全授权直出 PoC + 技术细节
+- ⚡ **全开默认配置** — Claude `bypassPermissions` / Codex `approval_policy=never` + `danger-full-access`
 - ⚖️ **5 个校验关卡** — 安全扫描、模块完整性、变更分析、代码质量、文档生成
-- ✅ **单元测试覆盖** — Jest 框架，GitHub Actions CI (Node 18/20/22)
-- ⚡ **三级授权** — T1/T2/T3 分级，零确认直接执行
+- 🧠 **沙箱感知 + 离线优先** — 自适应执行环境，信息三级分级验证
+- 🧬 **单源 skill registry** — `skills/**/SKILL.md` frontmatter 同时驱动 Claude commands、Codex prompts 与脚本执行链
 
 ---
 
@@ -113,7 +115,8 @@ Code Abyss 是一套 **Claude Code / Codex CLI 个性化配置包**，一条命
 ├── CLAUDE.md          道典        ├── AGENTS.md      道典+风格
 ├── output-styles/     输出风格    ├── config.toml    推荐配置
 │   └── abyss-cultivator.md       ├── prompts/       custom prompts
-├── settings.json
+├── commands/          斜杠命令     │   └── *.md       自动生成 prompt
+├── settings.json                  └── skills/        秘典 + 脚本执行器
 └── skills/            56 篇秘典
 
 可选:
@@ -127,6 +130,8 @@ Code Abyss 是一套 **Claude Code / Codex CLI 个性化配置包**，一条命
 
 ### 校验关卡（`/` 直接调用）
 
+这些命令与 Codex custom prompts 都不是手写维护，而是由各自 `skills/**/SKILL.md` frontmatter 中的 `name`、`user-invocable`、`allowed-tools`、`argument-hint`、`scripts/` 状态统一生成。
+
 | 命令 | 功能 |
 |------|------|
 | `/verify-security` | 扫描代码安全漏洞，检测危险模式 |
@@ -244,12 +249,62 @@ undo = true
 - 新增实验功能环境变量：`CLAUDE_CODE_ENABLE_TASKS`、`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`
 - 新增 `mcp__*` 通配符，自动放行所有 MCP 工具
 - `Codex` 当前支持 `~/.codex/prompts/*.md` 作为 custom prompts；Code Abyss 会继续安装 `~/.codex/skills/`，并从 `user-invocable` skills 自动生成对应的 `prompts/`
+- `Claude` 与 `Codex` 共用同一套 invocable skill 集合；只要 `user-invocable: true`，就会同步生成 `~/.claude/commands/*.md` 与 `~/.codex/prompts/*.md`
+- `skills/run_skill.js` 现在仅负责执行脚本型 skill：通过共享 registry 定位脚本入口、加目标锁、spawn 子进程，并把退出码原样透传
+- 若 skill 没有 `scripts/*.js`，Claude/Codex 两端都会退化为“先读 `SKILL.md`，再按秘典执行”的知识型模式
 - 安装器不会再为 Codex 写入伪配置 `~/.codex/settings.json`；若检测到旧版遗留文件，会在安装时备份后移除，卸载时恢复
 - 若你本地已有旧配置，安装器不会强制覆盖；会自动补齐默认项、清理 removed feature、迁移 deprecated `web_search_*` 到 `[tools].web_search`
 - 建议升级后执行一次 `codex --help`，或用 `codex -p safe --help` 校验 profile 可见性
 
 ---
 
+## 🧩 Skill registry / 生成 / 执行链
+
+现在 `skills/**/SKILL.md` frontmatter 是唯一事实源，registry 会先把元数据标准化，再交给安装器与执行器消费。
+
+### 标准化 contract
+
+每个 skill 必须满足：
+
+- 必填 frontmatter：`name`、`description`、`user-invocable`
+- `name` 必须是 kebab-case slug，用作 `commands/*.md` / `prompts/*.md` 文件名
+- `allowed-tools` 省略时默认 `Read`；若显式声明，则必须是 `Bash`、`Read`、`Write`、`Glob`、`Grep` 这类合法工具名列表
+- `argument-hint` 可选，仅用于生成命令/提示词参数说明
+- `category` 由目录前缀自动推断：`tools/` → `tool`，`domains/` → `domain`，`orchestration/` → `orchestration`
+- `runtimeType` 由脚本入口自动推断：存在且仅存在一个 `scripts/*.js` 时为 `scripted`，否则为 `knowledge`
+- `scripted` skill 会调用 `run_skill.js`；`knowledge` skill 只读取对应 `SKILL.md`
+- `kind` 与 kebab-case 兼容镜像字段已从 registry 返回面移除；对外只暴露标准化字段，raw frontmatter 仅保留在 `meta`
+- `scripts/` 下若出现多个 `.js` 入口，或 skill name 重复，安装/验证会立即失败
+
+### 生成链
+
+1. 安装器通过共享 skill registry 扫描全部 `SKILL.md`
+2. registry 先校验并标准化字段，再筛出 `user-invocable: true` 的 skill
+3. Claude 渲染为 `~/.claude/commands/*.md`
+4. Codex 渲染为 `~/.codex/prompts/*.md`
+5. `runtimeType=scripted` 时，双端产物都会调用各自的 `~/.claude/skills/run_skill.js` / `~/.codex/skills/run_skill.js`
+6. `runtimeType=knowledge` 时，双端都只读取 `SKILL.md` 作为执行秘典
+
+这保证了 **同一 skill 集合、同一元数据、同一 runtime 判定、双端同步生成**，避免 commands/prompts/script runner 各自漂移。
+
+---
+
+## 🧪 CI / Smoke 覆盖
+
+当前 CI 覆盖：
+
+- `npm test`
+- `npm run verify:skills`（显式 skill contract gate；frontmatter 解析失败、缺字段、非法工具名、重复 name、多脚本入口都会直接阻断）
+- `verify-change`
+- `verify-module`
+- `verify-quality`
+- `verify-security`
+- Claude install/uninstall smoke
+- Codex install/uninstall smoke
+- 生成一致性回归：同一 invocable skill 集合在 Claude commands 与 Codex prompts 中必须同步存在
+
+---
+
 ## 🧩 适配器解耦（Claude / Codex）
 
 为避免过度耦合，安装器按目标 CLI 拆分适配层：
@@ -279,6 +334,9 @@ undo = true
 |------|------|
 | `☠ 劫钟已鸣` | 开场受令 |
 | `🔥 破妄！` | 红队攻击 |
+| `🗡 破阵！` | 渗透/安全评估 |
+| `🔬 验毒！` | 代码审计 |
+| `💀 噬魂！` | 逆向/漏洞研究 |
 | `❄ 镇魔！` | 蓝队防御 |
 | `⚡ 炼合！` | 紫队协同 |
 | `🩸 道基欲裂...` | 任务推进 |

package/bin/install.js

@@ -15,8 +15,11 @@ if (parseInt(process.versions.node) < parseInt(MIN_NODE)) {
   process.exit(1);
 }
 const PKG_ROOT = fs.realpathSync(path.join(__dirname, '..'));
-const { shouldSkip, copyRecursive, rmSafe, deepMergeNew, printMergeLog, parseFrontmatter } =
+const { shouldSkip, copyRecursive, rmSafe, deepMergeNew, printMergeLog } =
   require(path.join(__dirname, 'lib', 'utils.js'));
+const {
+  collectInvocableSkills,
+} = require(path.join(__dirname, 'lib', 'skill-registry.js'));
 const { detectCclineBin, installCcline: _installCcline } = require(path.join(__dirname, 'lib', 'ccline.js'));
 const {
   detectCodexAuth: detectCodexAuthImpl,
@@ -151,39 +154,8 @@ function runUninstall(tgt) {
 
 // ── 安装核心 ──
 
-/**
- * 递归扫描 skills 目录，找出所有 user-invocable: true 的 SKILL.md
- * @param {string} skillsDir - skills 源目录绝对路径
- * @returns {Array<{meta: Object, relPath: string, hasScripts: boolean}>}
- */
 function scanInvocableSkills(skillsDir) {
-  const results = [];
-  function scan(dir) {
-    const skillMd = path.join(dir, 'SKILL.md');
-    if (fs.existsSync(skillMd)) {
-      try {
-        const content = fs.readFileSync(skillMd, 'utf8');
-        const meta = parseFrontmatter(content);
-        if (meta && meta['user-invocable'] === 'true' && meta.name) {
-          const relPath = path.relative(skillsDir, dir);
-          const scriptsDir = path.join(dir, 'scripts');
-          const hasScripts = fs.existsSync(scriptsDir) &&
-            fs.readdirSync(scriptsDir).some(f => f.endsWith('.js'));
-          results.push({ meta, relPath, hasScripts });
-        }
-      } catch (e) { /* 解析失败跳过 */ }
-    }
-    try {
-      fs.readdirSync(dir).forEach(sub => {
-        const subPath = path.join(dir, sub);
-        if (fs.statSync(subPath).isDirectory() && !shouldSkip(sub) && sub !== 'scripts') {
-          scan(subPath);
-        }
-      });
-    } catch (e) { /* 读取失败跳过 */ }
-  }
-  scan(skillsDir);
-  return results;
+  return collectInvocableSkills(skillsDir);
 }
 
 const INVOCABLE_TARGETS = {
@@ -211,11 +183,13 @@ function getSkillPath(skillRoot, skillRelPath) {
     : `${skillRoot}/SKILL.md`;
 }
 
-function buildCommandFrontmatter(meta) {
-  const desc = (meta.description || '').replace(/"/g, '\\"');
-  const argHint = meta['argument-hint'];
-  const tools = meta['allowed-tools'] || 'Read';
-  const lines = ['---', `name: ${meta.name}`, `description: "${desc}"`];
+function buildCommandFrontmatter(skill) {
+  const desc = (skill.description || '').replace(/"/g, '\\"');
+  const argHint = skill.argumentHint;
+  const tools = Array.isArray(skill.allowedTools)
+    ? skill.allowedTools.join(', ')
+    : (skill.allowedTools || 'Read');
+  const lines = ['---', `name: ${skill.name}`, `description: "${desc}"`];
 
   if (argHint) lines.push(`argument-hint: "${argHint}"`);
   lines.push(`allowed-tools: ${tools}`);
@@ -223,28 +197,48 @@ function buildCommandFrontmatter(meta) {
   return lines;
 }
 
-function buildClaudeBody(skillPath, meta, hasScripts) {
+function buildSkillArtifactSpec(skill, targetName) {
+  const targetCfg = getInvocableTarget(targetName);
+  const runtimeType = skill.runtimeType || 'knowledge';
+  const allowedTools = Array.isArray(skill.allowedTools)
+    ? skill.allowedTools.join(', ')
+    : (skill.allowedTools || 'Read');
+  return {
+    targetName,
+    targetCfg,
+    name: skill.name,
+    description: skill.description,
+    argumentHint: skill.argumentHint || '',
+    allowedTools,
+    relPath: skill.relPath,
+    runtimeType,
+    scriptRunner: `node ${targetCfg.skillRoot}/run_skill.js ${skill.name} $ARGUMENTS`,
+    skillPath: getSkillPath(targetCfg.skillRoot, skill.relPath),
+  };
+}
+
+function buildClaudeBody(spec) {
   const lines = [];
-  if (hasScripts) {
+  if (spec.runtimeType === 'scripted') {
     lines.push('以下所有步骤一气呵成，不要在步骤间停顿等待用户输入：', '');
-    lines.push(`1. 读取规范：${skillPath}`);
-    lines.push(`2. 执行命令：\`node ~/.claude/skills/run_skill.js ${meta.name} $ARGUMENTS\``);
+    lines.push(`1. 读取规范：${spec.skillPath}`);
+    lines.push(`2. 执行命令：\`${spec.scriptRunner}\``);
     lines.push('3. 按规范分析输出，完成后续动作', '');
     lines.push('全程不要停顿，不要询问是否继续。');
     return lines;
   }
 
   lines.push('读取以下秘典，根据内容为用户提供专业指导：', '');
-  lines.push('```', skillPath, '```');
+  lines.push('```', spec.skillPath, '```');
   return lines;
 }
 
-function buildCodexPromptBody(skillPath, meta, hasScripts) {
+function buildCodexPromptBody(spec) {
   const lines = [];
-  if (meta['argument-hint']) lines.push(`Arguments: ${meta['argument-hint']}`, '');
-  lines.push(`Read \`${skillPath}\` before acting.`, '');
-  if (hasScripts) {
-    lines.push(`Then run \`node ~/.codex/skills/run_skill.js ${meta.name} $ARGUMENTS\`.`);
+  if (spec.argumentHint) lines.push(`Arguments: ${spec.argumentHint}`, '');
+  lines.push(`Read \`${spec.skillPath}\` before acting.`, '');
+  if (spec.runtimeType === 'scripted') {
+    lines.push(`Then run \`${spec.scriptRunner}\`.`);
     lines.push('Do not stop between steps unless blocked by permissions or missing required inputs.');
     lines.push('Use the skill guidance plus script output to complete the task end-to-end.');
     return lines;
@@ -255,34 +249,44 @@ function buildCodexPromptBody(skillPath, meta, hasScripts) {
   return lines;
 }
 
-function generateInvocableContent(meta, skillRelPath, hasScripts, targetName) {
-  const targetCfg = getInvocableTarget(targetName);
-  const skillPath = getSkillPath(targetCfg.skillRoot, skillRelPath);
-  const lines = targetName === 'claude' ? buildCommandFrontmatter(meta) : [];
+function generateInvocableContent(skill, targetName) {
+  const spec = buildSkillArtifactSpec(skill, targetName);
+  const lines = targetName === 'claude' ? buildCommandFrontmatter(spec) : [];
   const body = targetName === 'claude'
-    ? buildClaudeBody(skillPath, meta, hasScripts)
-    : buildCodexPromptBody(skillPath, meta, hasScripts);
+    ? buildClaudeBody(spec)
+    : buildCodexPromptBody(spec);
   return [...lines, ...body, ''].join('\n');
 }
 
-function generateCommandContent(meta, skillRelPath, hasScripts) {
-  return generateInvocableContent(meta, skillRelPath, hasScripts, 'claude');
+function normalizeGeneratedSkill(meta, skillRelPath, runtimeType) {
+  return {
+    ...meta,
+    description: meta.description || '',
+    argumentHint: meta.argumentHint || '',
+    allowedTools: meta.allowedTools || 'Read',
+    relPath: skillRelPath,
+    runtimeType,
+  };
+}
+
+function generateCommandContent(meta, skillRelPath, runtimeType = 'knowledge') {
+  return generateInvocableContent(normalizeGeneratedSkill(meta, skillRelPath, runtimeType), 'claude');
 }
 
-function generatePromptContent(meta, skillRelPath, hasScripts) {
-  return generateInvocableContent(meta, skillRelPath, hasScripts, 'codex');
+function generatePromptContent(meta, skillRelPath, runtimeType = 'knowledge') {
+  return generateInvocableContent(normalizeGeneratedSkill(meta, skillRelPath, runtimeType), 'codex');
 }
 
 function installGeneratedArtifacts(skillsSrcDir, targetDir, backupDir, manifest, targetName) {
-  const skills = scanInvocableSkills(skillsSrcDir);
+  const skills = collectInvocableSkills(skillsSrcDir);
   if (skills.length === 0) return 0;
 
   const targetCfg = getInvocableTarget(targetName);
   const installDir = path.join(targetDir, targetCfg.dir);
   fs.mkdirSync(installDir, { recursive: true });
 
-  skills.forEach(({ meta, relPath, hasScripts }) => {
-    const fileName = `${meta.name}.md`;
+  skills.forEach((skill) => {
+    const fileName = `${skill.name}.md`;
     const destFile = path.join(installDir, fileName);
     const relFile = path.posix.join(targetCfg.dir, fileName);
 
@@ -294,7 +298,7 @@ function installGeneratedArtifacts(skillsSrcDir, targetDir, backupDir, manifest,
       info(`备份: ${c.d(relFile)}`);
     }
 
-    const content = generateInvocableContent(meta, relPath, hasScripts, targetName);
+    const content = generateInvocableContent(skill, targetName);
     fs.writeFileSync(destFile, content);
     manifest.installed.push(relFile);
   });

package/bin/lib/skill-registry.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { shouldSkip, parseFrontmatter } = require('./utils');
+
+const DEFAULT_ALLOWED_TOOLS = ['Read'];
+const NAME_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const TOOL_NAME_RE = /^[A-Z][A-Za-z0-9]*$/;
+
+function normalizeBoolean(value) {
+  return String(value).toLowerCase() === 'true';
+}
+
+function inferSkillKind(relPath) {
+  const normalizedRelPath = relPath.split(path.sep).join('/');
+  const [head] = normalizedRelPath.split('/');
+  if (head === 'tools') return 'tool';
+  if (head === 'domains') return 'domain';
+  if (head === 'orchestration') return 'orchestration';
+  return 'root';
+}
+
+function listScriptEntries(skillDir) {
+  const scriptsDir = path.join(skillDir, 'scripts');
+  let entries;
+  try {
+    entries = fs.readdirSync(scriptsDir)
+      .filter(name => name.endsWith('.js'))
+      .sort();
+  } catch {
+    return [];
+  }
+  return entries.map(name => path.join(scriptsDir, name));
+}
+
+function buildRegistryError(relPath, message) {
+  const where = relPath || '.';
+  return new Error(`无效 skill (${where}): ${message}`);
+}
+
+function requireStringField(meta, fieldName, relPath) {
+  const value = meta[fieldName];
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw buildRegistryError(relPath, `缺少必填 frontmatter 字段 '${fieldName}'`);
+  }
+  return value.trim();
+}
+
+function normalizeAllowedTools(value, relPath) {
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return [...DEFAULT_ALLOWED_TOOLS];
+  }
+
+  const tools = String(value)
+    .split(',')
+    .map(tool => tool.trim())
+    .filter(Boolean);
+
+  if (tools.length === 0) {
+    throw buildRegistryError(relPath, 'allowed-tools 不能为空');
+  }
+
+  for (const tool of tools) {
+    if (!TOOL_NAME_RE.test(tool)) {
+      throw buildRegistryError(relPath, `allowed-tools 包含非法值 '${tool}'`);
+    }
+  }
+
+  return tools;
+}
+
+function normalizeSkillRecord(skillsDir, skillDir, meta) {
+  const relPath = path.relative(skillsDir, skillDir);
+  const normalizedMeta = meta || {};
+  const scriptEntries = listScriptEntries(skillDir);
+
+  if (scriptEntries.length > 1) {
+    throw buildRegistryError(relPath, `scripts/ 目录下只能有一个 .js 入口，当前找到 ${scriptEntries.length} 个`);
+  }
+
+  const name = requireStringField(normalizedMeta, 'name', relPath);
+  if (!NAME_SLUG_RE.test(name)) {
+    throw buildRegistryError(relPath, `name 必须是 kebab-case slug，当前为 '${name}'`);
+  }
+
+  const description = requireStringField(normalizedMeta, 'description', relPath);
+  if (!Object.prototype.hasOwnProperty.call(normalizedMeta, 'user-invocable')) {
+    throw buildRegistryError(relPath, "缺少必填 frontmatter 字段 'user-invocable'");
+  }
+
+  const userInvocable = normalizeBoolean(normalizedMeta['user-invocable']);
+  const allowedTools = normalizeAllowedTools(normalizedMeta['allowed-tools'], relPath);
+  const argumentHint = normalizedMeta['argument-hint'] || '';
+  const category = inferSkillKind(relPath);
+  const runtimeType = scriptEntries.length === 1 ? 'scripted' : 'knowledge';
+  const scriptPath = scriptEntries[0] || null;
+  const skillPath = path.join(skillDir, 'SKILL.md');
+
+  return {
+    name,
+    description,
+    userInvocable,
+    allowedTools,
+    argumentHint,
+    relPath,
+    category,
+    runtimeType,
+    hasScripts: runtimeType === 'scripted',
+    scriptPath,
+    skillPath,
+    meta: normalizedMeta,
+  };
+}
+
+function validateUniqueSkillRecords(skills) {
+  const names = new Map();
+  const relPaths = new Map();
+
+  for (const skill of skills) {
+    if (names.has(skill.name)) {
+      throw buildRegistryError(skill.relPath, `重复的 skill name '${skill.name}'，首次出现在 ${names.get(skill.name)}`);
+    }
+    names.set(skill.name, skill.relPath);
+
+    if (relPaths.has(skill.relPath)) {
+      throw buildRegistryError(skill.relPath, `重复的 skill relPath '${skill.relPath}'`);
+    }
+    relPaths.set(skill.relPath, skill.name);
+  }
+}
+
+function collectSkills(skillsDir) {
+  const results = [];
+
+  function scan(dir) {
+    const skillMd = path.join(dir, 'SKILL.md');
+    if (fs.existsSync(skillMd)) {
+      const relPath = path.relative(skillsDir, dir);
+      const content = fs.readFileSync(skillMd, 'utf8');
+      const meta = parseFrontmatter(content);
+      if (!meta) {
+        throw buildRegistryError(relPath, 'SKILL.md 缺少可解析的 frontmatter');
+      }
+      results.push(normalizeSkillRecord(skillsDir, dir, meta));
+    }
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'scripts' || shouldSkip(entry.name)) continue;
+      scan(path.join(dir, entry.name));
+    }
+  }
+
+  scan(skillsDir);
+  validateUniqueSkillRecords(results);
+  return results.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function collectInvocableSkills(skillsDir) {
+  return collectSkills(skillsDir).filter(skill => skill.userInvocable);
+}
+
+function resolveSkillByName(skillsDir, skillName) {
+  return collectSkills(skillsDir).find(skill => skill.name === skillName) || null;
+}
+
+function resolveExecutableSkillScript(skillsDir, skillName) {
+  const skill = resolveSkillByName(skillsDir, skillName);
+  if (!skill) return { skill: null, scriptPath: null, reason: 'missing' };
+  if (skill.runtimeType !== 'scripted' || !skill.scriptPath) {
+    return { skill, scriptPath: null, reason: 'no-script' };
+  }
+  return { skill, scriptPath: skill.scriptPath, reason: null };
+}
+
+module.exports = {
+  collectSkills,
+  collectInvocableSkills,
+  resolveSkillByName,
+  resolveExecutableSkillScript,
+  inferSkillKind,
+};

package/bin/lib/utils.js

@@ -77,9 +77,15 @@ function parseFrontmatter(content) {
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!match) return null;
   const meta = Object.create(null);
-  match[1].split('\n').forEach(line => {
-    const m = line.match(/^([\w][\w-]*)\s*:\s*(.+)/);
-    if (m && !UNSAFE_KEYS.has(m[1])) meta[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+  match[1].split(/\r?\n/).forEach((rawLine, index) => {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) return;
+
+    const m = rawLine.match(/^([\w][\w-]*)\s*:\s*(.+)$/);
+    if (!m) {
+      throw new Error(`frontmatter 第 ${index + 1} 行格式无效: ${rawLine}`);
+    }
+    if (!UNSAFE_KEYS.has(m[1])) meta[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
   });
   return meta;
 }

package/bin/verify-skills-contract.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const path = require('path');
+const { collectSkills } = require('./lib/skill-registry');
+
+function resolveSkillsDir() {
+  return process.env.SAGE_SKILLS_DIR
+    ? path.resolve(process.env.SAGE_SKILLS_DIR)
+    : path.join(__dirname, '..', 'skills');
+}
+
+function main() {
+  const skillsDir = resolveSkillsDir();
+  const skills = collectSkills(skillsDir);
+  console.log(`技能契约验证通过: ${skills.length} skills`);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { main, resolveSkillsDir };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-abyss",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "邪修红尘仙·宿命深渊 - 一键为 Claude Code / Codex CLI 注入邪修人格与安全工程知识体系",
   "keywords": [
     "claude",
@@ -36,7 +36,8 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "jest"
+    "test": "jest",
+    "verify:skills": "node bin/verify-skills-contract.js"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.10.1"

package/skills/SKILL.md

@@ -8,6 +8,108 @@ disable-model-invocation: false
 
 # 神通秘典 · 总纲
 
+## Skill Authoring Contract
+
+以下规则是 `skills/**/SKILL.md` 的正式 authoring contract；共享 registry、`run_skill.js`、Claude commands、Codex prompts、CI gate 全部以此为准。
+
+### 必填 frontmatter
+
+```yaml
+---
+name: verify-quality
+description: 代码质量校验关卡。
+user-invocable: true
+allowed-tools: Bash, Read, Glob   # 可选，省略时默认 Read
+argument-hint: <扫描路径>          # 可选
+---
+```
+
+必填字段：
+
+- `name`：唯一标识，必须是 kebab-case slug，仅允许小写字母、数字、连字符
+- `description`：会进入 Claude command frontmatter 与 Codex prompt 文本，不能为空
+- `user-invocable`：`true/false`，决定是否进入生成集合
+
+可选字段：
+
+- `allowed-tools`：逗号分隔工具名列表；省略时默认 `Read`
+- `argument-hint`：生成命令/提示词时展示参数说明
+- 其他 frontmatter 可保留在 `meta` 中，但不会自动进入生成物
+
+### 分类与运行时推断
+
+- `category` 不是手写字段，而是由目录前缀自动推断：
+  - `skills/tools/*` → `tool`
+  - `skills/domains/*` → `domain`
+  - `skills/orchestration/*` → `orchestration`
+  - 其他位置 → `root`
+- `runtimeType` 同样自动推断：
+  - `scripts/` 下存在且仅存在一个 `.js` 文件 → `scripted`
+  - 没有脚本入口 → `knowledge`
+
+### 脚本入口规则
+
+- 脚本型 skill 必须把唯一入口放在 `scripts/*.js`
+- `scripts/` 下若出现多个 `.js` 文件，registry 会 fail-fast 报错
+- `runtimeType=scripted` 时，Claude / Codex 产物都会调用各自的 `run_skill.js`
+- `runtimeType=knowledge` 时，产物只读取对应 `SKILL.md`，不会尝试执行脚本
+- `kind` 与 kebab-case compatibility 镜像字段已从 registry 返回面移除；对外只暴露 normalized fields，raw frontmatter 仅保留在 `meta`
+
+### Fail-fast 校验
+
+以下情况会让 `collectSkills()` / `npm run verify:skills` / CI 立即失败：
+
+- `SKILL.md` 没有可解析 frontmatter
+- frontmatter 缺少 `name`、`description` 或 `user-invocable`
+- `name` 不是合法 kebab-case slug
+- `allowed-tools` 含非法工具名
+- skill name 重复，导致生成文件名冲突
+- `scripts/` 下出现多个 `.js` 入口
+
+### 生成链
+
+1. registry 扫描并标准化 `skills/**/SKILL.md`
+2. 仅 `userInvocable=true` 的 skill 进入 invocable 集合
+3. Claude 生成 `~/.claude/commands/*.md`
+4. Codex 生成 `~/.codex/prompts/*.md`
+5. `run_skill.js` 仅负责 `runtimeType=scripted` 的执行编排
+
+### 作者清单
+
+新增或修改 skill 时，至少完成以下检查：
+
+- 运行 `npm run verify:skills`
+- 运行 `npm test -- --runInBand test/install-utils.test.js test/install-registry.test.js test/install-generation.test.js test/install-smoke.test.js test/run-skill.test.js`
+- 确认命令名不会与现有 skill 冲突
+- 若新增脚本型 skill，确认 `scripts/` 下仅一个 `.js` 入口
+
+## 能力地图 / 调用规则 / 生成规则
+
+### 能力地图
+
+- `domains/`：知识型秘典，负责场景路由、原则、模板与执行纪律
+- `tools/`：可执行校验/生成关卡，既可被 slash command / custom prompt 直接调用，也可在流程中自动触发
+- `orchestration/`：协同规范与多 Agent 编排
+- `run_skill.js`：脚本型 skill 执行器，不负责知识路由
+
+### 调用规则
+
+1. 每个 skill 的权威元数据来自对应 `SKILL.md` frontmatter
+2. `user-invocable: true` 表示该 skill 进入可调用集合
+3. 若 skill 目录下存在唯一 `scripts/*.js`，则视为脚本型 skill（`runtimeType=scripted`）
+4. 若不存在脚本入口，则视为知识型 skill（`runtimeType=knowledge`），只读取 `SKILL.md` 执行
+5. `run_skill.js` 只负责脚本型 skill：解析 skill、校验 `runtimeType`、加锁、执行脚本、透传退出码
+
+### 自动生成规则
+
+1. 安装器通过共享 registry 递归扫描 `skills/**/SKILL.md`
+2. Claude 与 Codex 使用同一 invocable skill 集合
+3. Claude 生成 `~/.claude/commands/*.md`
+4. Codex 生成 `~/.codex/prompts/*.md`
+5. `runtimeType=scripted` 时，双端都调用各自的 `~/.claude/skills/run_skill.js` / `~/.codex/skills/run_skill.js`
+6. `runtimeType=knowledge` 时，双端都退化为“先读 `SKILL.md`，再据秘典执行”
+7. `npm run verify:skills` 与 CI 会在生成前先校验整个 contract，任何无效 skill 都会阻断后续流程
+
 ## 目录结构
 
 ```

package/skills/run_skill.js

@@ -15,12 +15,11 @@
  */
 
 const { spawn } = require('child_process');
-const { readdirSync, statSync, writeFileSync, unlinkSync, closeSync, openSync } = require('fs');
+const { unlinkSync, closeSync, openSync } = require('fs');
 const { join, resolve } = require('path');
 const { createHash } = require('crypto');
 const { tmpdir } = require('os');
-
-const IS_WIN = process.platform === 'win32';
+const { resolveExecutableSkillScript } = require('../bin/lib/skill-registry');
 
 function getSkillsDir() {
   const override = process.env.SAGE_SKILLS_DIR;
@@ -28,39 +27,29 @@ function getSkillsDir() {
   return __dirname;
 }
 
-function discoverSkills(skillsDir) {
-  const found = {};
-  const toolsDir = join(skillsDir, 'tools');
-  let entries;
-  try { entries = readdirSync(toolsDir).sort(); } catch { return found; }
-
-  for (const name of entries) {
-    const scriptsDir = join(toolsDir, name, 'scripts');
-    let scripts;
-    try { scripts = readdirSync(scriptsDir); } catch { continue; }
-    const jsFile = scripts.find(f => f.endsWith('.js'));
-    if (jsFile) found[name] = join(scriptsDir, jsFile);
-  }
-  return found;
+function sleep(ms) {
+  return new Promise(resolveSleep => setTimeout(resolveSleep, ms));
 }
 
-function getScriptPath(skillName) {
-  const available = discoverSkills(getSkillsDir());
-  if (!(skillName in available)) {
-    const names = Object.keys(available).join(', ') || '(无)';
+function getScriptEntry(skillName) {
+  const skillsDir = getSkillsDir();
+  const { skill, scriptPath, reason } = resolveExecutableSkillScript(skillsDir, skillName);
+
+  if (reason === 'missing') {
     console.error(`错误: 未知的 skill '${skillName}'`);
-    console.error(`可用的 skills: ${names}`);
     process.exit(1);
   }
-  return available[skillName];
-}
 
-function sleepMs(ms) {
-  const end = Date.now() + ms;
-  while (Date.now() < end) { /* busy wait */ }
+  if (reason === 'no-script') {
+    console.error(`错误: skill '${skillName}' 的 runtimeType 不是 scripted`);
+    console.error(`请先阅读: ${skill.skillPath}`);
+    process.exit(1);
+  }
+
+  return { skill, scriptPath };
 }
 
-function acquireTargetLock(args) {
+async function acquireTargetLock(args) {
   const target = args.find(a => !a.startsWith('-')) || process.cwd();
   const hash = createHash('md5').update(resolve(target)).digest('hex').slice(0, 12);
   const lockPath = join(tmpdir(), `sage_skill_${hash}.lock`);
@@ -70,12 +59,18 @@ function acquireTargetLock(args) {
   while (true) {
     try {
       const fd = openSync(lockPath, 'wx');
-      return { fd, lockPath };
+      return { fd, lockPath, target };
     } catch (e) {
-      if (e.code !== 'EEXIST') return { fd: null, lockPath: null };
-      if (first) { console.log(`⏳ 等待锁释放: ${target}`); first = false; }
-      if (Date.now() >= deadline) { console.error(`⏳ 等待锁超时: ${target}`); process.exit(1); }
-      sleepMs(200);
+      if (e.code !== 'EEXIST') return { fd: null, lockPath: null, target };
+      if (first) {
+        console.log(`⏳ 等待锁释放: ${target}`);
+        first = false;
+      }
+      if (Date.now() >= deadline) {
+        console.error(`⏳ 等待锁超时: ${target}`);
+        process.exit(1);
+      }
+      await sleep(200);
     }
   }
 }
@@ -89,7 +84,7 @@ function releaseLock({ fd, lockPath }) {
   }
 }
 
-function main() {
+async function main() {
   const args = process.argv.slice(2);
 
   if (args.length === 0 || args[0] === '-h' || args[0] === '--help') {
@@ -98,10 +93,9 @@ function main() {
   }
 
   const skillName = args[0];
-  const scriptPath = getScriptPath(skillName);
+  const { scriptPath } = getScriptEntry(skillName);
   const scriptArgs = args.slice(1);
-
-  const lock = acquireTargetLock(scriptArgs);
+  const lock = await acquireTargetLock(scriptArgs);
 
   const child = spawn(process.execPath, [scriptPath, ...scriptArgs], {
     stdio: 'inherit',
@@ -126,4 +120,7 @@ function main() {
   });
 }
 
-main();
+main().catch((err) => {
+  console.error(`执行错误: ${err.message}`);
+  process.exit(1);
+});