@vima_tech/flywheel 1.0.0

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/artifacts/req-miner-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,41 @@
+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, 外贸, 跨境, 出口, 订单管理, 采购管理]
+
+# 产物规格
+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

@@ -0,0 +1,90 @@
+{
+  "project_id": "",
+  "project_name": "",
+  "client_industry": "",
+  "client_name": "",
+  "created_at": "",
+  "updated_at": "",
+
+  "current_phase": "goal_confirmation",
+  "turn_count": 0,
+  "phase_turn_counts": {
+    "goal_confirmation": 0,
+    "scene_restoration": 0,
+    "constraint_probing": 0,
+    "acceptance_definition": 0
+  },
+
+  "prototype_fidelity": null,
+  "prototype_fidelity_locked": false,
+
+  "exit_conditions": {
+    "goal_confirmation": {
+      "true_goal_stated": false,
+      "decision_maker_identified": false,
+      "history_checked": false
+    },
+    "scene_restoration": {
+      "scenarios_count": 0,
+      "roles_identified": false,
+      "current_process_understood": false,
+      "flow_completeness_checked": false
+    },
+    "constraint_probing": {
+      "budget_locked": false,
+      "timeline_locked": false,
+      "deployment_confirmed": false,
+      "user_scale_confirmed": false,
+      "security_confirmed": false,
+      "parking_lot_high_risk_cleared": false
+    },
+    "acceptance_definition": {
+      "functional_criteria_count": 0,
+      "nonfunctional_criteria_count": 0,
+      "out_of_scope_listed": false,
+      "parking_lot_cleared": false
+    }
+  },
+
+  "confirmed_info": {
+    "true_goal": null,
+    "expressed_goal": null,
+    "decision_maker": null,
+    "client_type": null,
+    "has_previous_project": null,
+    "previous_project_result": null,
+    "budget_range": {
+      "min": null,
+      "max": null,
+      "currency": "CNY",
+      "locked": false
+    },
+    "timeline": null,
+    "deployment_type": null,
+    "mobile_required": null,
+    "user_scale": null,
+    "roles": [],
+    "must_have": [],
+    "should_have": [],
+    "wont_have": [],
+    "integrations": [],
+    "security_requirements": [],
+    "acceptance_criteria": []
+  },
+
+  "parking_lot": [],
+
+  "contradictions": [],
+
+  "uncovered_decisions": [],
+
+  "skills_loaded": [],
+
+  "distilled": false,
+  "distilled_at": null,
+
+  "dialog_summary": null,
+
+  "artifacts_generated": false,
+  "artifacts_path": null
+}