code-abyss 1.6.16 → 1.7.1

package/skills/orchestration/multi-agent/SKILL.md

@@ -1,10 +1,37 @@
 ---
 name: multi-agent
-description: 天罗秘典·多Agent协同。定义Agent角色、任务分解、冲突解决、通信协议。当需要多Agent并行协作时路由到此。
+description: 天罗秘典·多Agent协同。融合蚁群仿生设计，定义Agent角色、生命周期、信息素通信、任务分解、冲突解决。当需要多Agent并行协作时路由到此。
+license: MIT
 ---
 
-# 🕸 天罗秘典 · 多 Agent 协同
+# 🕸 天罗秘典 · 多 Agent 协同（蚁群仿生版）
 
+> 参考蚁群仿生架构：侦察→工作→审查→修复→完成，信息素间接通信，自适应并发。
+
+---
+
+## 蚁群生命周期
+
+所有多 Agent 协同任务遵循统一生命周期：
+
+```
+目标 → 侦察(Scout) → 任务池 → 工蚁(Worker)并行执行 → 兵蚁(Soldier)审查 → 修复(如需) → 完成
+         │                           │
+         │  信息素衰减（过时信息自动失效）  │  子任务自动产生
+         └───────────────────────────┘
+```
+
+### 阶段定义
+
+| 阶段 | 角色 | 动作 | 产出 |
+|------|------|------|------|
+| 🔍 侦察 | Scout | 探索代码库，标记关键文件和依赖 | 任务池 + 依赖图 |
+| ⚒️ 工作 | Worker | 并行执行任务，可产生子任务 | 代码变更 + 进度信息素 |
+| 🛡️ 审查 | Soldier | 审查所有变更，发现问题 | 修复任务 / 通过 |
+| 🔧 修复 | Worker | 执行审查产生的修复任务 | 修复后的代码 |
+| ✅ 完成 | Lead | 汇总报告，统一 commit | 最终交付 |
+
+---
 
 ## 何时启用多 Agent
 
@@ -36,6 +63,92 @@ description: 天罗秘典·多Agent协同。定义Agent角色、任务分解、
 
 ---
 
+## 角色体系（蚁群映射）
+
+| 角色 | 蚁群映射 | 道语 | 职责 | 工具权限 | 模型建议 |
+|------|----------|------|------|----------|----------|
+| 主修 (Lead) | 蚁后 Queen | 天罗主修 | 任务分解、调度、汇总 | TaskCreate/TaskUpdate/SendMessage | 当前模型 |
+| 斥候 (Scout) | 侦察蚁 Scout | 天罗斥候 | 只读探索，标记关键文件 | Read/Grep/Glob（只读） | haiku（快速低成本） |
+| 道侣 (Worker) | 工蚁 Worker | 天罗道侣 | 执行任务，可产生子任务 | Read/Write/Edit/Bash/SendMessage | sonnet/当前模型 |
+| 护法 (Soldier) | 兵蚁 Soldier | 天罗护法 | 审查质量，发现问题 | Read/Grep/Glob/SendMessage（只读） | sonnet |
+| 走卒 (Drone) | 无人蚁 Drone | 天罗走卒 | 简单 bash 命令，零 LLM 成本 | Bash（仅此一个） | 无（execSync） |
+
+### 角色使用时机
+
+```
+需要了解代码库结构？ → 派 Scout（Task subagent_type=Explore, model=haiku）
+需要修改代码？       → 派 Worker（Task subagent_type=general-purpose）
+需要审查变更？       → 派 Soldier（Task subagent_type=general-purpose, 只读 prompt）
+需要跑命令？         → 直接 Bash（Drone 等价）
+```
+
+---
+
+## 信息素系统（Stigmergy）
+
+蚁群通过信息素间接通信，而非直接对话。在 Claude Code 中，用 **TaskCreate metadata** 模拟信息素：
+
+### 信息素类型
+
+| 类型 | 释放者 | 含义 | 用途 |
+|------|--------|------|------|
+| `discovery` | Scout | 发现的代码结构、关键文件 | 帮助 Worker 快速定位 |
+| `progress` | Worker | 完成的变更、修改的文件 | 帮助后续 Worker 避免冲突 |
+| `warning` | Soldier | 质量问题、冲突风险 | 降低相关任务优先级 |
+| `completion` | Worker | 任务完成标记 | 强化成功路径 |
+| `repellent` | 任意 | 失败路径标记（负信息素） | 阻止后续 Agent 走同一条死路 |
+
+### 实现方式
+
+```
+# Scout 完成后，在 TaskUpdate 的 metadata 中记录发现
+TaskUpdate(taskId, metadata: {
+  pheromone: "discovery",
+  files: ["src/auth.ts", "src/middleware.ts"],
+  content: "认证模块依赖 middleware，需先改 middleware"
+})
+
+# Worker 失败后，释放负信息素
+TaskUpdate(taskId, metadata: {
+  pheromone: "repellent",
+  files: ["src/legacy.ts"],
+  content: "此文件有循环依赖，直接修改会崩溃"
+})
+```
+
+### 信息素决策规则
+
+| 规则 | 说明 |
+|------|------|
+| **正强化** | discovery/completion 信息素的文件 → 优先分配 |
+| **负惩罚** | warning 信息素的文件 → 降低优先级 |
+| **强负惩罚** | repellent 信息素的文件 → 避免分配，需主修评估 |
+| **ε-greedy** | 90% 按信息素强度选任务，10% 随机选 → 避免全挤同一条路 |
+
+---
+
+## 自适应并发
+
+根据任务数量和复杂度动态调整 Agent 数量：
+
+```
+任务数 1-2   → 1-2 个 Worker（直接 Task subagent）
+任务数 3-5   → TeamCreate, 2-3 个 Worker
+任务数 6-10  → TeamCreate, 3-5 个 Worker
+任务数 >10   → TeamCreate, 5-7 个 Worker（上限）
+```
+
+### 过载保护
+
+| 信号 | 动作 |
+|------|------|
+| Agent 连续失败 ≥2 次 | 减少并发，释放 repellent 信息素 |
+| 429 限流 | 暂停派发，等待恢复后继续 |
+| 所有任务完成 | 立即进入审查阶段 |
+| 子任务膨胀 >30 | 停止产生新子任务，先完成现有 |
+
+---
+
 ## TeamCreate 最佳实践
 
 ### 命名规范
@@ -46,14 +159,6 @@ agent_type: "{角色}"            # 如 "lead", "developer", "reviewer"
 description: "一句话说明团队目标"
 ```
 
-### 角色定义
-
-| 角色 | 道语 | 职责 | 工具权限 |
-|------|------|------|----------|
-| 主修 (Lead) | 天罗主修 | 任务分解、进度追踪、结果汇总 | TaskCreate/TaskUpdate/SendMessage |
-| 道侣 (Worker) | 天罗道侣 | 执行具体子任务、报告进度 | Read/Write/Edit/Bash/SendMessage |
-| 护法 (Reviewer) | 天罗护法 | 代码审查、质量校验、冲突检测 | Read/Grep/Glob/SendMessage |
-
 ---
 
 ## 任务分解策略
@@ -78,14 +183,24 @@ Agent-后端: src/api/
 Agent-基础: src/lib/
 ```
 
-### 按流水线拆分
+### 按流水线拆分（蚁群生命周期）
+
+```
+Scout(侦察) → Worker(执行) → Soldier(审查) → Worker(修复) → Lead(汇总)
+```
+
+### 依赖感知调度
 
-串行依赖时，前一个 Agent 的输出是后一个的输入：
+分配任务前，分析文件依赖关系：
 
 ```
-Agent-生成 → Agent-校验 → Agent-集成
+文件A import 文件B？
+  ├─ 是 → B 的任务必须先完成，A 的任务标记 blocked
+  └─ 否 → 可并行
 ```
 
+**依赖深度优先**：被更多文件依赖的（底层模块）优先处理。
+
 ---
 
 ## 并行 vs 串行决策
@@ -98,41 +213,47 @@ Agent-生成 → Agent-校验 → Agent-集成
        └─ 是（都写）→ 严格串行，或拆分文件区域
 ```
 
-### 依赖矩阵示例
-
-| | Task-A | Task-B | Task-C |
-|---|--------|--------|--------|
-| Task-A | - | 无依赖 | 无依赖 |
-| Task-B | 无依赖 | - | B→C |
-| Task-C | 无依赖 | B→C | - |
-
-结论：A 与 B 并行，C 等 B 完成后执行。
-
 ---
 
 ## Agent 角色模板
 
-### 主修（Lead）启动模板
+### 主修（Lead / Queen）启动模板
 
 ```
-你是天罗主修，负责协调多 Agent 协同任务。
+你是天罗主修（蚁后），负责协调多 Agent 协同任务。
 
-职责：
-1. 将大任务分解为独立子任务
-2. 为每个道侣分配文件集合（不可重叠）
-3. 追踪进度，处理阻塞
-4. 汇总结果，统一验证
+生命周期：
+1. 侦察阶段：派 Scout 探索代码库
+2. 工作阶段：根据侦察结果分配 Worker 并行执行
+3. 审查阶段：派 Soldier 审查所有变更
+4. 修复阶段：如有问题，派 Worker 修复
+5. 汇总阶段：收集结果，统一 commit
 
 铁律：
 - 每个文件只能分配给一个 Agent
 - 独立任务必须并行启动
-- 收到所有道侣完成消息后才能进入汇总
+- 关注信息素：discovery 优先分配，repellent 避免分配
+- 收到所有道侣完成消息后才能进入审查
+```
+
+### 斥候（Scout）启动模板
+
+```
+你是天罗斥候（侦察蚁），负责探索代码库。
+
+职责：
+1. 快速扫描项目结构和关键文件
+2. 识别文件间的依赖关系
+3. 标记需要修改的文件和潜在风险
+4. 输出发现（discovery 信息素）
+
+限制：只读操作，不修改任何文件。
 ```
 
 ### 道侣（Worker）启动模板
 
 ```
-你是天罗道侣，负责执行分配的子任务。
+你是天罗道侣（工蚁），负责执行分配的子任务。
 
 职责：
 1. 严格按照分配的文件列表操作
@@ -142,7 +263,23 @@ Agent-生成 → Agent-校验 → Agent-集成
 
 报告格式：
 - 完成：列出创建/修改的文件 + 行数
-- 阻塞：说明原因 + 建议方案
+- 阻塞：说明原因 + 建议方案（释放 warning 信息素）
+```
+
+### 护法（Soldier）启动模板
+
+```
+你是天罗护法（兵蚁），负责审查所有变更。
+
+职责：
+1. 审查所有 Worker 的变更
+2. 检查代码质量、安全性、一致性
+3. 发现问题则生成修复任务
+4. 无问题则确认通过
+
+输出：
+- 通过：确认所有变更合格
+- 问题：列出问题 + 修复建议（释放 warning 信息素）
 ```
 
 ---
@@ -161,10 +298,11 @@ Agent-生成 → Agent-校验 → Agent-集成
 
 | 事件 | 发送者 | 接收者 | 内容 |
 |------|--------|--------|------|
-| 任务分配 | 主修 | 道侣 | 文件列表 + 要求 |
-| 进度更新 | 道侣 | 主修 | 完成百分比 + 当前状态 |
+| 侦察完成 | Scout | 主修 | 文件清单 + 依赖图 + discovery 信息素 |
+| 任务分配 | 主修 | 道侣 | 文件列表 + 要求 + 相关信息素 |
 | 任务完成 | 道侣 | 主修 | 文件清单 + 验证结果 |
-| 遇阻报告 | 道侣 | 主修 | 阻塞原因 + 建议 |
+| 遇阻报告 | 道侣 | 主修 | 阻塞原因 + warning/repellent 信息素 |
+| 审查完成 | 护法 | 主修 | 通过/问题列表 |
 | 汇总指令 | 主修 | 全体 | broadcast 进入汇总阶段 |
 
 ---
@@ -183,6 +321,7 @@ Agent-生成 → Agent-校验 → Agent-集成
 1. **分配时锁定** — 主修分配任务时明确文件归属
 2. **声明式锁定** — 道侣开始前声明要操作的文件
 3. **冲突检测** — 主修检查文件分配无重叠后才启动
+4. **依赖感知** — 文件 A import 文件 B，则 A 和 B 不可同时修改
 
 ### 冲突解决
 
@@ -190,7 +329,8 @@ Agent-生成 → Agent-校验 → Agent-集成
 |----------|----------|
 | 两个 Agent 需写同一文件 | 串行执行，先完成的先写 |
 | 写入内容矛盾 | 主修裁决，以业务逻辑为准 |
-| 依赖文件未就绪 | 阻塞等待，主修协调优先级 |
+| 依赖文件未就绪 | 标记 blocked，主修协调优先级 |
+| 循环依赖 | 释放 repellent 信息素，主修手动拆解 |
 
 ---
 
@@ -200,8 +340,9 @@ Agent-生成 → Agent-校验 → Agent-集成
 
 ```
 TaskCreate: 主修创建总任务 + 子任务
-TaskUpdate: 道侣更新子任务状态
+TaskUpdate: 道侣更新子任务状态 + metadata（信息素）
 TaskList:   主修查看全局进度
+TaskGet:    查看任务详情 + 信息素
 ```
 
 ### 状态流转
@@ -218,9 +359,9 @@ pending → in_progress → completed
 ### 单 Agent 失败
 
 ```
-道侣失败 → 报告主修 → 主修评估影响
+道侣失败 → 释放 repellent 信息素 → 报告主修 → 主修评估影响
   ├─ 可重试 → 同一道侣重试（≤2次）
-  ├─ 需换策略 → 主修调整方案后重新分配
+  ├─ 需换策略 → 主修调整方案后重新分配（参考 repellent 避开死路）
   └─ 不可恢复 → 主修接管该子任务
 ```
 
@@ -241,14 +382,16 @@ pending → in_progress → completed
 
 ## 结果汇总模式
 
-### 汇总流程
+### 汇总流程（蚁群版）
 
 ```
 1. 收集所有道侣完成报告
-2. 验证文件完整性（所有预期文件存在）
-3. 验证内容一致性（交叉引用正确）
-4. 统一 git add + commit
-5. 输出汇总报告
+2. 派护法审查所有变更（可选，变更 >3 个文件时建议）
+3. 如有修复任务，派道侣修复
+4. 验证文件完整性（所有预期文件存在）
+5. 验证内容一致性（交叉引用正确）
+6. 统一 git add + commit
+7. 输出汇总报告
 ```
 
 ### 统一 Commit 规范
@@ -268,7 +411,13 @@ Co-authored-by: Agent-B"
 🕸 天罗收阵！
 
 【阵法】{团队名称}
-【阵员】{Agent数量} 道侣
+【阵员】{Agent数量} 道侣 + {Scout数} 斥候 + {Soldier数} 护法
+【生命周期】侦察 → 工作 → 审查 → 完成
+【信息素】
+  - discovery: {数量} 条
+  - completion: {数量} 条
+  - warning: {数量} 条
+  - repellent: {数量} 条
 【战果】
   - Agent-A: {文件数} 文件，{行数} 行
   - Agent-B: {文件数} 文件，{行数} 行

package/skills/run_skill.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * Skills 运行入口
+ * 跨平台统一调用各 skill 脚本
+ *
+ * 用法:
+ *     node run_skill.js <skill_name> [args...]
+ *
+ * 示例:
+ *     node run_skill.js verify-module ./my-project -v
+ *     node run_skill.js verify-security ./src --json
+ *     node run_skill.js verify-change --mode staged
+ *     node run_skill.js verify-quality ./src
+ *     node run_skill.js gen-docs ./new-module --force
+ */
+
+const { spawn } = require('child_process');
+const { readdirSync, statSync, writeFileSync, unlinkSync, closeSync, openSync } = require('fs');
+const { join, resolve } = require('path');
+const { createHash } = require('crypto');
+const { tmpdir } = require('os');
+
+const IS_WIN = process.platform === 'win32';
+
+function getSkillsDir() {
+  const override = process.env.SAGE_SKILLS_DIR;
+  if (override) return resolve(override);
+  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 getScriptPath(skillName) {
+  const available = discoverSkills(getSkillsDir());
+  if (!(skillName in available)) {
+    const names = Object.keys(available).join(', ') || '(无)';
+    console.error(`错误: 未知的 skill '${skillName}'`);
+    console.error(`可用的 skills: ${names}`);
+    process.exit(1);
+  }
+  return available[skillName];
+}
+
+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`);
+
+  try {
+    const fd = openSync(lockPath, 'wx');
+    return { fd, lockPath };
+  } catch (e) {
+    if (e.code === 'EEXIST') {
+      console.log(`⏳ 等待锁释放: ${target}`);
+      // 异步轮询等待，最多 30s
+      const deadline = Date.now() + 30000;
+      const poll = () => {
+        if (Date.now() >= deadline) { console.error(`⏳ 等待锁超时: ${target}`); process.exit(1); }
+        try {
+          const fd = openSync(lockPath, 'wx');
+          return { fd, lockPath };
+        } catch { /* still locked */ }
+        return null;
+      };
+      const result = poll();
+      if (result) return result;
+      return new Promise((resolve) => {
+        const timer = setInterval(() => {
+          const r = poll();
+          if (r) { clearInterval(timer); resolve(r); }
+        }, 200);
+      });
+    }
+    // 其他错误，忽略锁继续执行
+    return { fd: null, lockPath: null };
+  }
+}
+
+function releaseLock({ fd, lockPath }) {
+  if (fd !== null) {
+    try { closeSync(fd); } catch {}
+  }
+  if (lockPath) {
+    try { unlinkSync(lockPath); } catch {}
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '-h' || args[0] === '--help') {
+    console.log(__filename.split('/').pop() + ' <skill_name> [args...]');
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+
+  const skillName = args[0];
+  const scriptPath = getScriptPath(skillName);
+  const scriptArgs = args.slice(1);
+
+  const lock = acquireTargetLock(scriptArgs);
+
+  const child = spawn(process.execPath, [scriptPath, ...scriptArgs], {
+    stdio: 'inherit',
+  });
+
+  child.on('close', (code) => {
+    releaseLock(lock);
+    process.exit(code || 0);
+  });
+
+  child.on('error', (err) => {
+    console.error(`执行错误: ${err.message}`);
+    releaseLock(lock);
+    process.exit(1);
+  });
+
+  process.on('SIGINT', () => {
+    console.log('\n已取消');
+    child.kill('SIGINT');
+    releaseLock(lock);
+    process.exit(130);
+  });
+}
+
+main();

package/skills/tools/gen-docs/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: gen-docs
 description: 文档生成器。自动分析模块结构，生成 README.md 和 DESIGN.md 骨架。当魔尊提到生成文档、创建README、创建DESIGN、文档骨架、文档模板时使用。在新建模块开始时自动触发。
+license: MIT
+compatibility: node>=18
 user-invocable: true
 disable-model-invocation: false
 allowed-tools: Bash, Read, Write, Glob
@@ -24,9 +26,9 @@ argument-hint: <模块路径> [--force]
 
 ```bash
 # 在 skill 目录下运行
-python scripts/doc_generator.py <模块路径>
-python scripts/doc_generator.py <模块路径> --force  # 强制覆盖已存在的文档
-python scripts/doc_generator.py <模块路径> --json   # JSON 输出
+node scripts/doc_generator.js <模块路径>
+node scripts/doc_generator.js <模块路径> --force  # 强制覆盖已存在的文档
+node scripts/doc_generator.js <模块路径> --json   # JSON 输出
 ```
 
 ## 生成内容
@@ -88,7 +90,7 @@ python scripts/doc_generator.py <模块路径> --json   # JSON 输出
 ## 使用流程
 
 ```
-1. 运行 doc_generator.py 生成骨架
+1. 运行 doc_generator.js 生成骨架
 2. 填充 TODO 标记的内容
 3. 补充设计决策和理由
 4. 添加使用示例