@vima_tech/flywheel 1.2.1 → 1.2.3

package/bin/flywheel.js

@@ -3,6 +3,7 @@ const { spawn, execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
+const readline = require('readline');
 
 const NPM_PKG = '@vima_tech/flywheel';
 
@@ -70,12 +71,17 @@ async function initKernel(dir, skill) {
   }
 
   if (skill) {
-    const skillFiles = [
+    const skillRequired = [
       'skills/' + skill + '/skill.yaml',
       'skills/' + skill + '/domain.md',
       'skills/' + skill + '/feedback-questions.sh',
     ];
-    for (const f of skillFiles) {
+    const skillOptional = [
+      'skills/' + skill + '/artifacts.md',
+      'skills/' + skill + '/memory/failure-patterns.md',
+    ];
+
+    for (const f of skillRequired) {
       const dest = path.join(dir, f);
       fs.mkdirSync(path.dirname(dest), { recursive: true });
       const srcPath = resolveKernelFile(f);
@@ -85,6 +91,34 @@ async function initKernel(dir, skill) {
         await downloadFile(baseUrl + '/' + f, dest);
       }
     }
+
+    for (const f of skillOptional) {
+      const dest = path.join(dir, f);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      const srcPath = resolveKernelFile(f);
+      if (fs.existsSync(srcPath)) {
+        fs.copyFileSync(srcPath, dest);
+      } else {
+        try { await downloadFile(baseUrl + '/' + f, dest); } catch (e) {}
+      }
+    }
+
+    // 解析 skill.yaml 中声明的行业包，逐一下载（找不到则跳过）
+    const skillYamlPath = path.join(dir, 'skills/' + skill + '/skill.yaml');
+    if (fs.existsSync(skillYamlPath)) {
+      const yamlContent = fs.readFileSync(skillYamlPath, 'utf8');
+      for (const match of yamlContent.matchAll(/^\s+file:\s+(.+)$/gm)) {
+        const f = match[1].trim();
+        const dest = path.join(dir, f);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        const srcPath = resolveKernelFile(f);
+        if (fs.existsSync(srcPath)) {
+          fs.copyFileSync(srcPath, dest);
+        } else {
+          try { await downloadFile(baseUrl + '/' + f, dest); } catch (e) {}
+        }
+      }
+    }
   }
 
   fs.mkdirSync(path.join(dir, '.distill-needed'), { recursive: true });
@@ -254,6 +288,45 @@ async function updateProjectFramework(projectPath) {
       console.log('  ✗ ' + f + ' (失败)');
     }
   }
+
+  // 更新已安装的 skill 文件
+  const flywheelMarker = path.join(projectPath, '.flywheel');
+  if (fs.existsSync(flywheelMarker)) {
+    let skill = '';
+    try { skill = JSON.parse(fs.readFileSync(flywheelMarker, 'utf8')).skill || ''; } catch (e) {}
+    if (skill && skill !== 'none') {
+      console.log(' 更新 skill: ' + skill);
+      const skillFiles = [
+        'skills/' + skill + '/skill.yaml',
+        'skills/' + skill + '/domain.md',
+        'skills/' + skill + '/feedback-questions.sh',
+        'skills/' + skill + '/artifacts.md',
+        'skills/' + skill + '/memory/failure-patterns.md',
+      ];
+      for (const f of skillFiles) {
+        const dest = path.join(projectPath, f);
+        try {
+          fs.mkdirSync(path.dirname(dest), { recursive: true });
+          await downloadFile(baseUrl + '/' + f, dest);
+          console.log('  ✓ ' + f);
+        } catch (e) {}
+      }
+      // 更新行业包（从已下载的 skill.yaml 中读取）
+      const skillYamlPath = path.join(projectPath, 'skills/' + skill + '/skill.yaml');
+      if (fs.existsSync(skillYamlPath)) {
+        const yamlContent = fs.readFileSync(skillYamlPath, 'utf8');
+        for (const match of yamlContent.matchAll(/^\s+file:\s+(.+)$/gm)) {
+          const f = match[1].trim();
+          const dest = path.join(projectPath, f);
+          try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            await downloadFile(baseUrl + '/' + f, dest);
+            console.log('  ✓ ' + f);
+          } catch (e) {}
+        }
+      }
+    }
+  }
 }
 
 async function cmdUpgrade(args) {
@@ -338,6 +411,7 @@ Flywheel CLI — 自成长 AI Agent 飞轮框架
   install|add|i         安装 skill 包
   list|ls               列出已安装的 skill
   update [skill]        更新 skill 包
+  publish <skill>       发布自建 skill 到注册表
   distill|dist          手动触发蒸馏
   upgrade [path]        升级 flywheel 工具，并更新项目框架
   -h|--help             显示帮助
@@ -361,7 +435,7 @@ switch (command) {
   case '--version':
   case '-V':
   case 'version':
-    console.log('@vima_tech/flywheel v1.2.1');
+    console.log('@vima_tech/flywheel v1.2.2');
     break;
   case 'new':
   case 'create':
@@ -390,6 +464,7 @@ Flywheel CLI — 自成长 AI Agent 飞轮框架
   install|add|i         安装 skill 包
   list|ls               列出已安装的 skill
   update [skill]        更新 skill 包
+  publish <skill>       发布自建 skill 到注册表
   distill|dist          手动触发蒸馏
   upgrade [path]        升级 flywheel 工具，并更新项目框架
   -h|--help             显示帮助
@@ -424,6 +499,9 @@ Flywheel CLI — 自成长 AI Agent 飞轮框架
   case 'update':
     runScript(resolveScript('flywheel-install'), ['update', ...restArgs]).catch((e) => process.exit(1));
     break;
+  case 'publish':
+    runScript(resolveScript('flywheel-install'), ['publish', ...restArgs]).catch((e) => process.exit(1));
+    break;
   case 'distill':
   case 'dist':
     runScript(resolveScript('auto-distill'), restArgs).catch((e) => process.exit(1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vima_tech/flywheel",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "自成长 AI Agent 飞轮框架 — 让任何需要积累迭代的 AI 工作流都能自我进化",
   "main": "bin/flywheel.js",
   "bin": {
@@ -13,7 +13,8 @@
     "scripts/",
     "templates/",
     "skills/_kernel/",
-    "skills/_template/"
+    "skills/_template/",
+    "skills/req-mining/"
   ],
   "scripts": {
     "postinstall": "chmod +x bin/flywheel.js"

package/scripts/flywheel-install.sh

@@ -83,6 +83,66 @@ cmd_add() {
   curl -fsSL $CURL_PROXY "$BASE_URL/install.sh" | bash -s -- "$skill"
 }
 
+# ── publish ────────────────────────────────────────────────────
+cmd_publish() {
+  local skill="$1"
+  [ -z "$skill" ] && { echo "❌ 用法：$0 publish <skill-name>"; exit 1; }
+
+  local yaml="$REPO_DIR/skills/$skill/skill.yaml"
+  [ -f "$yaml" ] || { echo "❌ skill '$skill' 未找到：$yaml"; exit 1; }
+
+  local name version description
+  name=$(grep '^name:' "$yaml" | head -1 | awk '{print $2}')
+  version=$(grep '^version:' "$yaml" | head -1 | awk '{print $2}')
+  description=$(grep '^description:' "$yaml" | head -1 | cut -d: -f2- | xargs)
+
+  local available_file="$SCRIPT_DIR/available.json"
+
+  echo "━━━ 发布 skill: $skill ━━━"
+  echo ""
+
+  # 检查是否已在注册表中
+  if [ -f "$available_file" ] && python3 -c "
+import json, sys
+data = json.load(open('$available_file'))
+sys.exit(0 if any(s['name']=='$name' for s in data.get('skills',[])) else 1)
+" 2>/dev/null; then
+    echo "  ℹ  '$name' 已在 available.json 中，更新版本号..."
+    python3 - "$available_file" "$name" "$version" "$description" << 'PYEOF'
+import json, sys
+path, name, version, desc = sys.argv[1:]
+data = json.load(open(path))
+for s in data['skills']:
+    if s['name'] == name:
+        s['version'] = version
+        s['description'] = desc
+        break
+with open(path, 'w') as f:
+    json.dump(data, f, ensure_ascii=False, indent=2)
+    f.write('\n')
+print("  ✓ available.json 已更新")
+PYEOF
+  else
+    # 追加到注册表
+    python3 - "$available_file" "$name" "$version" "$description" << 'PYEOF'
+import json, sys
+path, name, version, desc = sys.argv[1:]
+data = json.load(open(path)) if __import__('os').path.exists(path) else {"skills": []}
+data.setdefault('skills', []).append({"name": name, "version": version, "description": desc})
+with open(path, 'w') as f:
+    json.dump(data, f, ensure_ascii=False, indent=2)
+    f.write('\n')
+print(f"  ✓ '{name}' 已添加到 available.json")
+PYEOF
+  fi
+
+  echo ""
+  echo "下一步：提交到仓库让其他人也能安装"
+  echo "  git add scripts/available.json skills/$skill/"
+  echo "  git commit -m \"feat(skill): publish $name v$version\""
+  echo "  git push && 发起 PR 到 https://github.com/renmengkai/flywheel"
+}
+
 # ── update ─────────────────────────────────────────────────────
 cmd_update() {
   local skills=()
@@ -136,8 +196,9 @@ case "$CMD" in
   add)       cmd_add "$TARGET" ;;
   update)    cmd_update ;;
   available) cmd_available ;;
+  publish)   cmd_publish "$TARGET" ;;
   *)
-    echo "用法：$0 list | add <skill> | update [skill] | available"
+    echo "用法：$0 list | add <skill> | update [skill] | available | publish <skill>"
     exit 1
     ;;
 esac

package/skills/_kernel/distillation.md

@@ -69,17 +69,17 @@ estimated_tokens: 1500
   + 0.2  quality_score >= 0.6（feedback-hook 自动计算）
   最高：0.9
   路由规则：
-    unclear_specs → 更新 skills/artifacts/req-miner-artifacts.md 的"功能规格"章节
-    uncovered_decisions → 追加到 skills/artifacts/req-miner-artifacts.md 的"未覆盖情况处理规则"
-    wrong_assumptions → 追加到 memory/patterns/failure-patterns.md
+    unclear_specs → 更新 skills/req-mining/artifacts.md 的"功能规格"章节
+    uncovered_decisions → 追加到 skills/req-mining/artifacts.md 的"未覆盖情况处理规则"
+    wrong_assumptions → 追加到 skills/req-mining/memory/failure-patterns.md
 
 自驱分析完成事件（type: auto_req_completed）：
   + 0.4  有假设被后续实现反馈验证（assumption_validated = true）
   + 0.3  assumptions_count >= 3（说明文档不完整，推断规则有价值）
   最高：0.7
   路由规则：
-    验证正确的假设 → 追加到 skills/core/auto-req.md 的"推断规则库"（如不存在则新建章节）
-    验证错误的假设 → 追加到 memory/patterns/failure-patterns.md
+    验证正确的假设 → 追加到 skills/req-mining/domain.md 的"推断规则库"（如不存在则新建章节）
+    验证错误的假设 → 追加到 skills/req-mining/memory/failure-patterns.md
 ```
 
 **输出过滤结果：**
@@ -110,7 +110,7 @@ estimated_tokens: 1500
   "pattern_summary": "用一句话描述这个模式",
   "trigger_signals": ["触发这个模式的信号词或场景"],
   "recommended_action": "遇到此情况时，Agent 应该...",
-  "target_file": "skills/core/req-miner.md",
+  "target_file": "skills/req-mining/domain.md",
   "target_section": "阶段三：约束摸底 / 预算追问逻辑",
   "change_type": "append | replace | new_section",
   "proposed_content": "具体的修改内容或新增内容",
@@ -135,7 +135,7 @@ estimated_tokens: 1500
 
 "AI 执行时遇到的未覆盖场景 + 有人工决议"
 → pattern_type: decision_tree
-→ 更新 skills/artifacts/req-miner-artifacts.md 的"未覆盖情况处理规则"章节
+→ 更新 skills/req-mining/artifacts.md 的"未覆盖情况处理规则"章节
 
 "单一案例，不可泛化（置信度 < 0.6）"
 → 跳过，标注 low-signal，不写入任何文件
@@ -151,12 +151,12 @@ estimated_tokens: 1500
 ━━━ 蒸馏结果预览（共 N 项变更）━━━
 
 变更 1/N：[skill_update]
-  文件：skills/core/req-miner.md → 章节名（append）
+  文件：skills/req-mining/domain.md → 章节名（append）
   内容摘要：[拟新增内容的一句话描述]
   置信度：0.82 | 来源：proj_xxx / evt_023
 
 变更 2/N：[memory_entry]
-  文件：memory/patterns/failure-patterns.md（append）
+  文件：skills/req-mining/memory/failure-patterns.md（append）
   内容摘要：[拟新增内容的一句话描述]
   置信度：0.75 | 来源：proj_xxx / evt_045
 
@@ -230,11 +230,11 @@ Sources: {event_id列表}"
 实际写入变更：{Y} 条（跳过 {X-Y} 条：用户取消或低质量）
 
 Skills 更新：
-  - skills/core/req-miner.md（v1.0 → v1.1）
+  - skills/req-mining/domain.md（v1.0 → v1.1）
   - [其他更新文件]
 
 Memory 更新：
-  - memory/patterns/failure-patterns.md（+{N} 条）
+  - skills/req-mining/memory/failure-patterns.md（+{N} 条）
 
 下次蒸馏建议时机：完成 {下个project_id} 项目后
 ```

package/skills/req-mining/artifacts.md

@@ -0,0 +1,185 @@
+---
+name: req-miner-artifacts
+skill_id: req_miner_artifacts
+version: 2.0
+description: >
+  需求挖掘产物生成规格。仅在阶段四退出条件全部满足后加载。
+  定义三份产物的完整结构：需求澄清报告 + AI 执行文档 + 可视化原型规格。
+is_required: false
+hard_dep: [req_miner_core]
+soft_dep: []
+estimated_tokens: 1000
+---
+
+# 产物生成规格
+
+阶段四退出条件全部满足后，依次生成以下三份产物。
+**三份产物信息来源完全一致，出现不一致 = 需求对话有遗漏，必须修正后再输出。**
+
+---
+
+## 输出前自检（必须执行，任一未通过则补充对话）
+
+```
+□ 业务流程是否完整？（销售/采购/库存/财务四条链条无断点）
+□ MoSCoW 是否明确区分 Must / Should / Won't？
+□ 是否有成本核算方法定义？
+□ 是否有应收应付账款管理？
+□ 是否有退货/售后流程？
+□ 是否有数据备份和导出策略？
+□ 验收标准是否包含性能指标（具体数字）？
+□ 验收标准是否包含安全/权限要求？
+□ Parking Lot 是否清零？
+```
+
+---
+
+## 产物 1：需求澄清报告
+
+**面向：** 甲方决策人（人话描述，客户签字确认）
+
+```
+1. 项目背景
+   项目名称 | 调研时间 | 客户行业 | 核心目标用户
+
+2. 真实目标 vs 表达目标
+   甲方原话：[引用] → 真实目标：[澄清后] → 验证方式：[如何判断达成]
+
+3. 功能范围（MoSCoW）
+   Must Have（本期必须）：[列表]
+   Should Have（本期应该）：[列表]
+   Won't Have（本期不做，原因）：[列表]
+
+4. 使用角色与场景
+   角色：[角色名] | 使用频率 | 核心任务
+   场景：至少 2 个完整端到端场景描述
+
+5. 约束与边界
+   预算：[范围 + 决策链] | 时间：[期望上线 + 硬截止] | 部署：[方式]
+   技术：[已有系统/需对接/偏好] | 合规：[数据安全/等保要求]
+
+6. 业务流程完整性说明
+   [描述销售/采购/库存/财务完整链条，标注本期覆盖范围]
+
+7. 数据安全需求
+   权限模型 | 数据隔离级别 | 审计日志策略 | 合规要求
+
+8. 非功能性需求
+   性能（具体数字）| 可用性（SLA）| 备份策略 | 导出格式 | 打印需求
+
+9. 集成需求
+   [第三方系统] + [对接方式] + [数据格式]
+
+10. 隐含假设清单
+    [假设内容] → 已确认 / 待确认 / 存在风险
+
+11. Parking Lot（未解决问题）
+    [问题] | 风险级别 | 必须解决时间节点
+
+12. 落地风险评估
+    [风险描述] | 可能性 | 影响 | 建议处理方式
+
+13. 验收标准（≥5条，含功能性/非功能性/安全）
+    每条格式：[主语] + [操作] + [可测试结果]
+
+14. 本期明确不做的功能（显式列出，防止后期扯皮）
+
+15. 甲方确认签字栏
+    客户签字：____ | 分析师：____ | 日期：____
+```
+
+---
+
+## 产物 2：AI 执行文档
+
+**面向：** 执行 AI（无歧义技术规格）
+**禁止出现：** 可能、也许、适当、合理、尽量、一般情况下
+
+```
+1. 系统概述
+   一段话：系统是什么，服务谁，核心特性，技术栈建议，部署架构
+
+2. 技术约束（必须是具体数字）
+   并发用户数 | 页面加载时间 | 数据量级 | 响应时间 | 可用性 SLA
+
+3. 权限模型（RBAC）
+   角色定义 | 权限矩阵 | 数据隔离级别 | API 鉴权方案 | 敏感操作二次确认清单
+
+4. 数据模型
+   每个实体：表名 | 字段名 | 类型 | 约束 | 索引 | 外键 | 枚举值定义
+
+5. 数据字典
+   所有枚举字段的完整取值定义（如订单状态、付款状态、角色类型）
+
+6. 功能规格（每个 Must Have 功能点）
+   触发条件 | 输入（字段+验证规则）| 处理逻辑（步骤，无歧义）| 输出 | 异常处理 | 边界情况
+
+7. 状态机定义
+   订单状态机 | 库存状态 | 支付状态（含每个状态的触发条件和转移规则）
+
+8. 安全设计
+   密码加密方案 | 传输加密 | SQL 注入防护 | XSS 防护 | 审计日志字段定义
+
+9. 数据库策略
+   索引设计 | 迁移策略 | 并发控制（乐观锁/悲观锁）| 备份方案
+
+10. 验收测试用例
+    每个功能点：正向用例 + 异常用例 + 边界用例
+
+11. 未覆盖情况处理规则
+    "遇到本文档未说明的情况，必须停止并记录，不得自行决定"
+    [列出已知高风险歧义场景及标准处理方式]
+
+12. 变更记录
+    版本 | 日期 | 变更内容 | 确认人
+```
+
+---
+
+## 产物 3：可视化原型规格
+
+**按已锁定的保真度等级输出（A/B/C，不可更改）**
+
+**标注规范（所有等级通用）：**
+- 🔴 需要特别确认的业务逻辑
+- 🟡 存在不确定性，待甲方说明
+- 🟢 已确认，无需讨论
+- ⚪ 本期范围外
+
+**所有等级必须覆盖：**
+
+```
+□ 所有 Must Have 功能的页面/流程
+□ 每个页面的边界情况（空状态 / 加载状态 / 错误状态）
+□ 每个页面与验收标准的对应关系
+□ 订单/库存状态机可视化流转图
+□ 批量操作交互设计（批量导入/导出/修改）
+□ 导出功能 UI 入口（Excel/PDF 导出按钮位置和进度提示）
+```
+
+**A. 流程图额外要求：**
+- 页面节点 + 跳转逻辑 + 触发条件
+- 每个节点的关键字段列表（文字说明）
+
+**B. 线框图额外要求（在 A 基础上）：**
+- 完整字段标注（字段名、类型、是否必填）
+- 关键交互标注（点击跳转目标）
+- 打印样式设计（报价单/发票/出库单的打印布局）
+
+**C. 中保真额外要求（在 B 基础上）：**
+- 基本配色方案（与客户品牌相符）
+- 主要页面的视觉风格（字体、间距、卡片样式）
+- 关键操作按钮样式
+
+---
+
+## 产物输出后操作
+
+```
+1. 更新 state.json → current_phase: "completed"
+2. 归档本次会话日志（追加到 episodic-logs/{project_id}.jsonl）
+3. 输出摘要：
+   "三份产物已生成。
+    本次对话：[N] 轮 | Parking Lot 解决：[N] 项 | 未覆盖决策：[N] 项
+    建议专家审查后发送给客户确认。"
+```

package/skills/req-mining/domain.md

@@ -0,0 +1,243 @@
+---
+name: auto-req
+skill_id: auto_req
+version: 1.0
+description: >
+  自驱需求分析 Skill。无需人类实时对话，从输入文档（需求文档、邮件线程、
+  Jira tickets、会议记录）中自主运行四阶段框架，提取需求并生成三份产物。
+  是飞轮架构的 Ring 1 自驱化核心。
+is_required: false
+hard_dep: [req_miner_core]
+soft_dep: []
+estimated_tokens: 1200
+trigger_phrases:
+  - "分析这份文档"
+  - "从文档提取需求"
+  - "无对话模式"
+  - "自动分析"
+  - "headless模式"
+  - "批量需求"
+---
+
+# 自驱需求分析协议
+
+**使用场景：** 客户已提供书面材料（需求文档、邮件、会议纪要、竞品截图），
+无法实时对话，但需要结构化需求产物。
+
+**与普通模式的区别：**
+- 普通模式：与人类实时对话提炼需求
+- 自驱模式：从文档推断需求，用 `⚠️ 假设` 标注所有不确定点，不阻塞流程
+
+---
+
+## Step 0：接收输入材料
+
+用户提供以下任意格式：
+- 直接粘贴文本
+- 文件路径（读取内容）
+- URL（抓取内容）
+- 多份材料（合并分析）
+
+**确认输入后，询问项目基本信息（一次性询问）：**
+
+```
+已收到材料（约 XXX 字）。
+
+请确认以下信息（可全部省略，我会从文档推断）：
+1. 项目名称：
+2. 客户行业：
+3. 分析侧重点（功能 / 约束 / 验收标准）：
+4. 缺失信息处理方式：
+   A. 标注假设，继续分析（推荐）
+   B. 列出问题，等待补充后再分析
+```
+
+---
+
+## Step 1：材料扫描与信息提取
+
+**读取所有材料，提取以下维度（静默执行，不逐条输出）：**
+
+```
+维度 1：业务目标信号
+  - 明确陈述的目标
+  - 隐含目标（从"痛点"、"现在的问题"、"希望"等词推断）
+  - 利益相关者提及的关键词
+
+维度 2：功能需求信号
+  - 动词短语（"能够"、"支持"、"允许"、"需要"）
+  - 角色 + 操作 + 对象 的句式
+  - 列表/表格中的功能点
+
+维度 3：约束信号
+  - 数字（预算、时间、用户量、性能指标）
+  - 技术栈提及
+  - 安全/合规要求
+  - "不能"、"禁止"、"限制"等否定约束
+
+维度 4：验收信号
+  - "验收"、"上线标准"、"测试"、"通过"等词周围的内容
+  - KPI、指标、可量化结果
+
+维度 5：矛盾信号
+  - 同一实体在不同位置有不同描述
+  - 需求数量与预算/时间明显不匹配
+  - 技术限制与功能要求相冲突
+```
+
+---
+
+## Step 2：四维度分析输出
+
+**输出格式：**
+
+```
+━━━ 自驱分析结果 | 项目：{name} | 材料：{N}份 ━━━
+
+## 一、目标层
+
+真实目标（推断）：[描述]
+表达目标（材料原话）：[引用]
+推断依据：[关键词/段落]
+⚠️ 假设 A1：[不确定点]，假设为 [推断值]，如有误请纠正
+
+## 二、功能层
+
+Must Have（明确提及 ≥2 处或被标注为核心）：
+  • [功能1]（来源：[段落标识]）
+  • [功能2]
+
+Should Have（明确提及 1 处）：
+  • [功能3]
+
+⚠️ 假设 F1：材料中提及"[X功能]"但未说明优先级，暂归为 Should Have
+
+Won't Have（材料明确排除，或超出范围）：
+  • [功能4]（来源：[原话]）
+
+## 三、约束层
+
+预算：[数值或"未提及，⚠️ 假设 C1：按中型项目估算 10-30万"]
+时间：[数值或推断]
+部署方式：[私有化/SaaS/未知]
+用户规模：[数值或推断]
+技术约束：[列表]
+
+## 四、验收层
+
+明确验收标准：
+  • [标准1]（来源：[原话]）
+推断验收标准（从功能反推）：
+  • [标准2]（⚠️ 假设 V1：推断）
+
+## 五、矛盾与风险
+
+⚠️ 矛盾 M1：材料第3段说"[A]"，第7段说"[B]"，需确认
+🔴 高风险：[需求规模与时间/预算明显不匹配 等]
+
+## 六、信息缺口清单
+
+以下信息材料中无法推断，需人工确认：
+  □ [问题1]（影响：影响功能规格，阻塞产物2生成）
+  □ [问题2]（影响：影响验收标准定义）
+```
+
+---
+
+## Step 3：生成方式选择
+
+**分析完成后，询问：**
+
+```
+━━━ 自驱分析完成 ━━━
+
+发现信息缺口 {N} 处，其中：
+- 阻塞级（必须确认才能输出）：{M} 处
+- 非阻塞级（可用假设替代）：{N-M} 处
+
+如何继续？
+A. 立即生成三份产物（用假设填充缺口，产物中标注⚠️）
+B. 先补充 {M} 处关键信息，再生成
+C. 导出信息缺口清单，人工填写后继续
+```
+
+---
+
+## Step 4：生成三份产物
+
+收到用户选择后，加载 `skills/req-mining/artifacts.md`，
+按规格生成三份产物。
+
+**自驱模式特殊标注规则：**
+
+- 所有通过推断而非明确确认的内容，加 `⚠️[假设:A1]` 标注
+- 产物首页增加"假设清单"章节，汇总所有假设
+- 验收标准中推断类标准，标注"待客户确认"
+
+---
+
+## Step 5：写入状态与日志
+
+```python
+# 更新 state.json
+state["auto_req_mode"] = True
+state["assumptions_count"] = N
+state["info_gaps"] = [gap_list]
+state["artifacts_generated"] = True
+
+# 追加事件日志
+event = {
+    "event_id": "evt_auto_req_001",
+    "type": "auto_req_completed",
+    "assumptions_count": N,
+    "info_gap_blocking": M,
+    "distillation_candidate": True
+}
+```
+
+---
+
+## Step 6：自动启动 Ring 2（飞轮衔接）
+
+产物写入完成后，**直接通过 Bash 工具调用桥接脚本**，无需用户手动执行：
+
+```bash
+./scripts/bridge-to-coder.sh {project_id} {tool}
+# tool 默认 claude；若用户指定了其他工具则使用用户指定的
+```
+
+输出提示：
+```
+━━━ Ring 1 完成，自动启动 Ring 2 ━━━
+正在调用：./scripts/bridge-to-coder.sh {project_id} {tool}
+编程工具退出后将自动收集反馈，满足条件时自动触发蒸馏
+```
+
+**注意：** bridge-to-coder.sh 会启动一个交互式编程工具会话（如 claude），
+此时当前 AI 会话暂时挂起，等待编程工具退出后继续。
+
+---
+
+## 自驱模式与飞轮的配合
+
+```
+输入文档
+    │
+    ▼
+自驱分析（本 Skill）
+    │ 生成三份产物 + 假设清单
+    ▼
+bridge-to-coder.sh → 编程工具实现
+    │ 实现过程中确认/否定假设
+    ▼
+feedback-hook.sh → 写入假设验证结果
+    │ 哪些假设对了，哪些错了
+    ▼
+蒸馏 → 更新"自驱推断规则"
+    │ 下次同类文档推断更准确
+    ▼
+更好的自驱分析
+```
+
+**关键：每次假设被确认或否定，都是一次学习信号。**
+积累足够多的假设验证后，自驱推断的准确率会持续提高。

package/skills/req-mining/feedback-questions.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# req-mining 领域专属反馈问题
+# 由 scripts/feedback-hook.sh 在交互模式下 source 本文件
+
+QUESTION_1="哪些需求描述不清晰或有歧义？"
+QUESTION_2="遇到了哪些文档未覆盖的技术决策？"
+QUESTION_3="发现哪些需求假设与现实不符？"
+QUESTION_4="哪些验收标准无法被自动测试？"
+QUESTION_5="总体反馈（实现难度、文档质量评分 1-10）："

package/skills/req-mining/industry/erp.md

@@ -0,0 +1,108 @@
+---
+name: req-miner-industry-erp
+skill_id: req_miner_industry_erp
+version: 2.0
+description: >
+  需求挖掘行业包：ERP / 进销存 / 外贸 / 跨境电商。
+  当客户行业涉及以下关键词时自动加载：进销存、ERP、外贸、跨境、出口、订单管理、
+  采购管理、库存管理、外贸管理系统、阿里国际站、独立站。
+  宁可多触发，不漏触发。
+is_required: false
+hard_dep: [req_miner_core]
+soft_dep: []
+estimated_tokens: 1200
+---
+
+# 行业问题包：ERP / 进销存 / 外贸
+
+加载后，在**阶段二（场景还原）**和**阶段三（约束摸底）**期间，
+从以下清单中选取适用问题补充挖掘。**必须覆盖该行业全业务流程，不允许有断点。**
+
+---
+
+## 通用进销存 / ERP 核心问题
+
+**订单与销售：**
+- "订单是否需要分批发货？"
+- "是否有销售退货和采购退货流程？"
+- "是否有客户等级价格体系？（不同客户不同价）"
+- "是否支持订单复制或批量创建？"
+- "订单状态机：新建 → 确认 → 生产中 → 已发货 → 已签收 → 已回款，每个状态的触发条件是什么？"
+
+**库存：**
+- "是否需要支持多仓库管理？"
+- "批次管理是否需要有效期追踪？"
+- "是否有安全库存设置？库存低于多少时预警？"
+- "是否支持库存调拨（多仓之间）？调拨是否需要审批？"
+- "成本核算用哪种方法？（加权平均 / 先进先出 / 后进先出 / 批次成本）"
+- "损耗/报废如何处理？是否影响成本核算？"
+
+**采购：**
+- "是否有完整采购订单流程？（采购申请 → 采购订单 → 入库）"
+- "是否存在寄售、代销模式？"
+- "是否存在客制化商品（BOM 配置）？"
+
+**财务：**
+- "是否有应收应付账款管理？（谁欠我钱 / 我欠谁钱）"
+- "是否需要毛利分析？需要哪些维度？（按客户 / 按商品 / 按业务员 / 按时间）"
+- "账龄分析和逾期提醒是否必要？"
+
+---
+
+## 外贸 / 跨境电商核心问题
+
+**必须覆盖从询盘到退税的完整链条：**
+询盘 → 报价 → 订单 → 生产/采购 → 验货 → 报关 → 出货 → 提单 → 客户签收 → 结汇 → 退税
+
+**询盘与报价：**
+- "是否需要管理询盘（Inquiry）→ 报价（Quotation）→ 订单（Order）的转化？"
+- "是否需要样品管理？（样品费、样品发货跟踪）"
+- "客户来源渠道有哪些？（阿里国际站 / 独立站 / 展会 / 线下）"
+
+**合同与条款：**
+- "贸易术语用什么？（FOB / CIF / EXW / DDP）"
+- "付款方式有哪些？（T/T 电汇 / 信用证 L/C / PayPal / 赊销）"
+- "是否需要客户信用额度管理？（欠款上限、账期控制）"
+
+**物流与报关：**
+- "是否需要报关/清关信息管理？（HS 编码、报关单号）"
+- "是否需要物流跟踪？（提单号 BL / 运单号 AWB / 船期航班跟踪）"
+- "是否需要包装/唛头管理？（每箱数量、毛重净重、唛头图片）"
+
+**结汇与退税：**
+- "是否需要多币种结算？汇率由谁维护？多久更新一次？"
+- "结汇手续由谁办理？汇率损失如何记录？"
+- "是否需要出口退税管理？（退税比例、退税状态跟踪）"
+
+**单据管理：**
+- "是否需要发票管理？（形式发票 PI、商业发票 CI）"
+- "是否需要装箱单（Packing List）自动生成？"
+
+---
+
+## 业务流程完整性——行业特定断点检查
+
+加载本包后，阶段二结束时额外检查以下外贸特有断点：
+
+| 环节 | 常见遗漏 |
+|---|---|
+| 样品流程 | 样品费是否收取、样品订单是否单独管理 |
+| 信用证 | L/C 有效期管理、不符点处理 |
+| 退税 | 退税状态跟踪、退税款入账 |
+| 汇差 | 汇率损益如何记录到财务 |
+| 售后 | 海外客户退货的物流和关税处理 |
+
+---
+
+## 行业特定验收标准模板（阶段四补充）
+
+在阶段四补充以下外贸/进销存特有验收标准：
+
+```
+□ "系统支持的货币种类不少于 [N] 种，汇率可手动维护，精度为 4 位小数"
+□ "HS 编码字段支持模糊搜索，搜索结果 < 1 秒返回"
+□ "出库时系统按先进先出自动选择批次，不需要手动干预"
+□ "库存低于安全库存时，系统在 [X] 小时内发出预警通知到 [指定渠道]"
+□ "应收账款逾期超过 [N] 天时，系统自动标记并发送提醒"
+□ "退税状态支持：未申报 / 已申报 / 已收款，状态变更记录操作人和时间"
+```

package/skills/req-mining/industry/retail.md

@@ -0,0 +1,24 @@
+---
+name: req-miner-industry-retail
+skill_id: req_miner_industry_retail
+version: 0.1
+status: planned
+description: >
+  需求挖掘行业包：零售/门店。
+  当客户行业涉及以下关键词时加载：零售、门店、连锁、收银、会员积分、促销。
+is_required: false
+hard_dep: [req_miner_core]
+---
+
+# 行业问题包：零售 / 门店
+
+> 🚧 本行业包待建。欢迎贡献。
+> 参考 skills/industry/erp.md 的格式提交 PR。
+
+## 计划覆盖内容
+
+- 会员管理 / 积分体系
+- 门店调拨
+- 促销规则引擎
+- 收银方式（现金/扫码/刷卡）
+- 多门店报表汇总

package/skills/req-mining/memory/failure-patterns.md

@@ -0,0 +1,84 @@
+# 需求失败模式库
+
+**类型：** External Memory（陈述性知识）
+**加载时机：** 每次需求挖掘会话常驻加载
+**更新方式：** 蒸馏后自动追加，不手动编辑
+
+---
+
+## 使用说明
+
+每次需求挖掘对话开始时，将此文件全量加载进 context window。
+在对话过程中，当客户的表述命中任何"触发信号"时，主动采取对应的"建议行动"。
+
+---
+
+## 模式列表
+
+### 模式：低估复杂度
+
+**触发信号：** "只有我用"、"简单就行"、"先做个基础版"、"功能不多"
+**规律描述：** 客户使用简化性表达时，70% 概率在后续出现范围蔓延。真实的使用角色和功能需求通常比初始描述多 2-3 倍。
+**建议行动：** 立即触发"枚举所有使用角色"追问序列；要求客户描述一个最复杂的业务场景（而不是最简单的）。
+**来源项目：** 冷启动手写
+**置信度：** 0.85
+**最后更新：** 2024-01-15
+
+---
+
+### 模式：委托人信息失真
+
+**触发信号：** "我来了解一下"、"回去跟老板汇报"、"老板让我问问"、"这个我不确定，要问一下上面"
+**规律描述：** 对话对象是委托人而非决策人时，获取的需求信息经过一次中间人过滤，关键约束（预算上限、时间节点、优先级排序）的准确性平均下降 40%。
+**建议行动：** 识别后明确标记为"委托型"客户；建议在原型确认阶段引入真实决策人参与；所有关键决策类信息放入 Parking Lot 等待最终决策人确认。
+**来源项目：** 冷启动手写
+**置信度：** 0.80
+**最后更新：** 2024-01-15
+
+---
+
+### 模式：技术方案先行
+
+**触发信号：** "我们需要一个 RESTful API"、"要支持微服务"、"用 React 做前端"、"要上 Kubernetes"
+**规律描述：** 专业型客户（IT 经理/技术负责人）容易把技术解决方案当需求提，导致业务目标被技术实现遮蔽。这类需求最常见的结果是"技术上实现了但业务问题没解决"。
+**建议行动：** 接受技术语言，但立即转化："这个 API 是为了解决什么业务问题？"；将技术表述转化为用户故事格式：「作为[角色]，我需要[功能]，以便[业务目标]」
+**来源项目：** 冷启动手写
+**置信度：** 0.78
+**最后更新：** 2024-01-15
+
+---
+
+### 模式：历史失败项目包袱
+
+**触发信号：** "之前做过一个，但没用起来"、"上次找了外包，结果..."、"我们自己开发过，后来废弃了"
+**规律描述：** 有历史失败经验的客户，失败原因通常会在新项目中重演（如组织推广阻力、需求频繁变更、验收标准不清晰）。不挖掘失败原因，新项目大概率踩同样的坑。
+**建议行动：** 必须追问失败原因："最后没有用起来，主要原因是什么？是功能不对，是推广阻力，还是其他？"；将失败原因转化为当前项目的风险项写入报告。
+**来源项目：** 冷启动手写
+**置信度：** 0.88
+**最后更新：** 2024-01-15
+
+---
+
+### 模式：验收标准空洞化
+
+**触发信号：** "用起来方便就行"、"只要好用"、"功能完整就可以"、"做得专业一点"
+**规律描述：** 这类表述在验收时必然引发争议，因为双方对"方便"、"好用"、"专业"的标准不一致。约 60% 的外包项目验收纠纷源于此类空洞验收标准。
+**建议行动：** 立即要求具体化："能描述一个具体的操作，操作完之后您怎么知道它做好了？"；拒绝将此类表述写入验收标准，要求用 4 要素格式（主语+动作+结果+可验证）替换。
+**来源项目：** 冷启动手写
+**置信度：** 0.92
+**最后更新：** 2024-01-15
+
+---
+
+### 模式：需求在对话末期爆发
+
+**触发信号：** 阶段三或阶段四突然提出全新的功能需求；客户说"对了，我还想要..."
+**规律描述：** 客户在信任建立后才会透露真实的、完整的需求，而不是在对话开始时。这不是客户的问题，而是信任建立有时间过程。通常在第 20-30 轮才出现关键需求。
+**建议行动：** 不要对新需求表现出明显的负面反应；将新需求纳入 MoSCoW 重新评估；检查是否需要回溯到更早的阶段重新确认某些退出条件。
+**来源项目：** 冷启动手写
+**置信度：** 0.75
+**最后更新：** 2024-01-15
+
+---
+
+*本文件由蒸馏流程自动维护，请勿手动编辑已有条目。新增条目请通过蒸馏流程添加。*

package/skills/req-mining/skill.yaml

@@ -0,0 +1,44 @@
+name: req-mining
+version: 1.0.0
+description: 需求挖掘与落地飞轮
+author: renmengkai
+license: MIT
+
+# 飞轮配置
+ring1_skill: skills/req-mining/domain.md
+ring1_artifacts_doc: ai-execution-doc.md
+ring2_bridge: scripts/bridge-to-coder.sh
+ring2_default_tool: claude
+ring3_feedback_questions: skills/req-mining/feedback-questions.sh
+
+# 激活触发词
+triggers:
+  - "分析这份文档"
+  - "提取需求"
+  - "需求挖掘"
+  - "start req mining"
+  - "analyze document"
+
+# 初始记忆文件
+memory:
+  - skills/req-mining/memory/failure-patterns.md
+
+# 可选行业包
+industry_packs:
+  erp:
+    file: skills/req-mining/industry/erp.md
+    triggers: [进销存, ERP, 外贸, 跨境, 出口, 订单管理, 采购管理]
+  retail:
+    file: skills/req-mining/industry/retail.md
+    triggers: [零售, 电商, 门店, 收银, 会员, 积分, 促销, 商超]
+
+# 产物规格
+artifacts:
+  spec: skills/req-mining/artifacts.md
+  outputs:
+    - name: 需求澄清报告
+      file: clarification-report.md
+    - name: AI 执行文档
+      file: ai-execution-doc.md
+    - name: 可视化原型规格
+      file: prototype-spec.md

package/templates/state.json

@@ -1,6 +1,7 @@
 {
   "project_id": "",
   "project_name": "",
+  "skill": "req-mining",
   "client_industry": "",
   "client_name": "",
   "created_at": "",