code-abyss 1.8.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` | 扫描代码安全漏洞，检测危险模式 |
@@ -163,43 +168,58 @@ Code Abyss 是一套 **Claude Code / Codex CLI 个性化配置包**，一条命
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "env": {
     "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
-    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
+    "CLAUDE_CODE_ENABLE_TASKS": "1",
+    "CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION": "1",
+    "ENABLE_TOOL_SEARCH": "auto:10"
   },
+  "defaultMode": "bypassPermissions",
   "alwaysThinkingEnabled": true,
+  "autoMemoryEnabled": true,
   "model": "opus",
   "outputStyle": "abyss-cultivator",
   "attribution": { "commit": "", "pr": "" },
+  "sandbox": { "autoAllowBashIfSandboxed": true },
   "permissions": {
-    "allow": ["Bash", "LS", "Read", "Agent", "Write", "Edit", "MultiEdit",
-              "Glob", "Grep", "WebFetch", "WebSearch", "TodoWrite",
-              "NotebookRead", "NotebookEdit"]
+    "allow": ["Bash", "LS", "Read", "Edit", "Write", "MultiEdit",
+              "Agent", "Glob", "Grep", "WebFetch", "WebSearch",
+              "TodoWrite", "NotebookRead", "NotebookEdit", "mcp__*"]
   }
 }
 ```
 
 | 配置项 | 说明 |
 |--------|------|
+| `defaultMode: bypassPermissions` | 跳过所有权限确认（`.git`等受保护目录仍会提示） |
+| `autoMemoryEnabled` | 启用自动记忆，跨会话保留上下文 |
+| `sandbox.autoAllowBashIfSandboxed` | 沙箱环境内自动放行 Bash 命令 |
 | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | 启用多 Agent 并行协作（实验性） |
 | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 禁用自动更新、遥测、错误报告 |
+| `CLAUDE_CODE_ENABLE_TASKS` | 启用任务管理功能 |
+| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 启用提示建议 |
+| `ENABLE_TOOL_SEARCH` | MCP 工具自动搜索（auto:10 = 自动匹配前10个） |
+| `mcp__*` | 自动放行所有 MCP 工具 |
 | `outputStyle` | 设置为 `abyss-cultivator` 启用邪修风格 |
 
 ---
 
 ### Codex `config.toml` 推荐模板
 
-安装 `--target codex`（尤其 `-y`）时会写入以下 **safe 默认档** 到 `~/.codex/config.toml`：
+安装 `--target codex`（尤其 `-y`）时会写入以下 **全开默认档** 到 `~/.codex/config.toml`：
 
 ```toml
 model_provider = "custom"
 model = "gpt-5.2-codex"
 model_reasoning_effort = "high"
-approval_policy = "on-request"
-sandbox_mode = "workspace-write"
-disable_response_storage = true
-
-[profiles.full_access]
+model_reasoning_summary = "detailed"
+model_verbosity = "medium"
 approval_policy = "never"
 sandbox_mode = "danger-full-access"
+disable_response_storage = true
+
+[profiles.safe]
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
 
 [model_providers.custom]
 name = "custom"
@@ -212,18 +232,76 @@ web_search = true
 
 [features]
 multi_agent = true
+shell_snapshot = true
+undo = true
 ```
 
-- 日常交互默认使用 `on-request + workspace-write`，更贴近当前 Codex CLI 的低摩擦安全姿态
-- 需要高自动化时可显式切到 `full_access`：`codex -p full_access`
+- 默认零审批 + 完全沙箱访问，适合安全研究/CTF/本地开发等高自动化场景
+- `model_reasoning_summary = "detailed"` 输出详细推理摘要
+- `shell_snapshot` / `undo` 启用快照与撤销功能
+- 需要安全姿态时可显式切到 `safe`：`codex -p safe`
 
 ### 兼容性说明
 
 - 模板已对齐新版 Codex 配置风格：root keys、`[profiles.*]`、`[tools].web_search` 与 `[features].multi_agent`
+- 默认档从 safe 切换为全开（`approval_policy = "never"` + `sandbox_mode = "danger-full-access"`），提供 `[profiles.safe]` 作为保守回退
+- Claude Code 默认启用 `bypassPermissions` 模式，跳过所有权限确认（`.git` 等受保护目录仍会提示）
+- 新增实验功能环境变量：`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`；若检测到旧版遗留文件，会在安装时备份后移除，卸载时恢复
-- 若你本地已有旧配置，安装器不会强制覆盖；会自动补齐 safe root 默认项、清理 removed feature、迁移 deprecated `web_search_*` 到 `[tools].web_search`，并仅在 `danger-full-access` 下清理 `projects.*.trust_level`
-- 建议升级后执行一次 `codex --help`，或用 `codex -p full_access --help` 校验 profile 可见性
+- 若你本地已有旧配置，安装器不会强制覆盖；会自动补齐默认项、清理 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 中必须同步存在
 
 ---
 
@@ -256,6 +334,9 @@ multi_agent = true
 |------|------|
 | `☠ 劫钟已鸣` | 开场受令 |
 | `🔥 破妄！` | 红队攻击 |
+| `🗡 破阵！` | 渗透/安全评估 |
+| `🔬 验毒！` | 代码审计 |
+| `💀 噬魂！` | 逆向/漏洞研究 |
 | `❄ 镇魔！` | 蓝队防御 |
 | `⚡ 炼合！` | 紫队协同 |
 | `🩸 道基欲裂...` | 任务推进 |

package/bin/adapters/claude.js

@@ -7,17 +7,25 @@ const SETTINGS_TEMPLATE = {
   $schema: 'https://json.schemastore.org/claude-code-settings.json',
   env: {
     CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
-    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1'
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+    CLAUDE_CODE_ENABLE_TASKS: '1',
+    CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION: '1',
+    ENABLE_TOOL_SEARCH: 'auto:10'
   },
+  defaultMode: 'bypassPermissions',
   alwaysThinkingEnabled: true,
+  autoMemoryEnabled: true,
   model: 'opus',
   outputStyle: 'abyss-cultivator',
   attribution: { commit: '', pr: '' },
+  sandbox: {
+    autoAllowBashIfSandboxed: true
+  },
   permissions: {
     allow: [
-      'Bash', 'LS', 'Read', 'Agent', 'Write', 'Edit', 'MultiEdit',
-      'Glob', 'Grep', 'WebFetch', 'WebSearch', 'TodoWrite',
-      'NotebookRead', 'NotebookEdit'
+      'Bash', 'LS', 'Read', 'Edit', 'Write', 'MultiEdit',
+      'Agent', 'Glob', 'Grep', 'WebFetch', 'WebSearch',
+      'TodoWrite', 'NotebookRead', 'NotebookEdit', 'mcp__*'
     ]
   }
 };

package/bin/adapters/codex.js

@@ -4,8 +4,8 @@ const fs = require('fs');
 const path = require('path');
 
 const CODEX_DEFAULTS = {
-  approvalPolicy: 'on-request',
-  sandboxMode: 'workspace-write',
+  approvalPolicy: 'never',
+  sandboxMode: 'danger-full-access',
   featureFlag: 'multi_agent',
 };
 

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;
 }