@vima_tech/flywheel 1.0.0

package/scripts/flywheel-install.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# scripts/flywheel-install.sh
+# 在已安装 flywheel 的项目中管理 skill 包
+#
+# 用法：
+#   ./scripts/flywheel-install.sh list           # 列出已安装 skill
+#   ./scripts/flywheel-install.sh add <skill>    # 安装新 skill
+#   ./scripts/flywheel-install.sh update         # 更新所有 skill 到最新版
+#   ./scripts/flywheel-install.sh update <skill> # 更新指定 skill
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO="renmengkai/flywheel"
+BRANCH="main"
+BASE_URL="https://raw.githubusercontent.com/$REPO/$BRANCH"
+CMD="${1:-list}"
+TARGET="${2:-}"
+
+# ── list ───────────────────────────────────────────────────────
+cmd_list() {
+  echo "━━━ 已安装 Skill 包 ━━━"
+  local found=false
+  for yaml in "$REPO_DIR/skills"/*/skill.yaml; do
+    [ -f "$yaml" ] || continue
+    local skill_dir
+    skill_dir=$(dirname "$yaml")
+    local name
+    name=$(basename "$skill_dir")
+    local version
+    version=$(grep '^version:' "$yaml" 2>/dev/null | awk '{print $2}' || echo "?")
+    local desc
+    desc=$(grep '^description:' "$yaml" 2>/dev/null | cut -d: -f2- | xargs || echo "")
+    echo "  • $name  v$version  —  $desc"
+    found=true
+  done
+  $found || echo "  （未安装任何 skill）"
+  echo ""
+  echo "安装新 skill：./scripts/flywheel-install.sh add <skill-name>"
+}
+
+# ── add ────────────────────────────────────────────────────────
+cmd_add() {
+  local skill="$1"
+  [ -z "$skill" ] && { echo "❌ 用法：$0 add <skill-name>"; exit 1; }
+
+  echo "安装 skill：$skill"
+
+  # 检查 skill 是否存在
+  if ! curl -fsSL "$BASE_URL/skills/$skill/skill.yaml" -o /dev/null 2>/dev/null; then
+    echo "❌ skill '$skill' 不存在"
+    echo "   运行 list 查看可用 skill"
+    exit 1
+  fi
+
+  # 使用主安装器的 install_skill 逻辑
+  curl -fsSL "$BASE_URL/install.sh" | bash -s -- "$skill"
+}
+
+# ── update ─────────────────────────────────────────────────────
+cmd_update() {
+  local skills=()
+
+  if [ -n "$TARGET" ]; then
+    skills=("$TARGET")
+  else
+    for yaml in "$REPO_DIR/skills"/*/skill.yaml; do
+      [ -f "$yaml" ] || continue
+      skills+=("$(basename "$(dirname "$yaml")")")
+    done
+  fi
+
+  [ ${#skills[@]} -eq 0 ] && { echo "没有已安装的 skill"; exit 0; }
+
+  echo "━━━ 更新 Skill 包 ━━━"
+  for skill in "${skills[@]}"; do
+    echo ""
+    echo "更新 $skill..."
+    local yaml_url="$BASE_URL/skills/$skill/skill.yaml"
+    local remote_ver
+    remote_ver=$(curl -fsSL "$yaml_url" 2>/dev/null | grep '^version:' | awk '{print $2}' || echo "?")
+    local local_ver
+    local_ver=$(grep '^version:' "$REPO_DIR/skills/$skill/skill.yaml" 2>/dev/null | awk '{print $2}' || echo "0")
+
+    if [ "$remote_ver" = "$local_ver" ]; then
+      echo "  ✓ $skill 已是最新版 v$local_ver"
+    else
+      echo "  $local_ver → $remote_ver，更新中..."
+      cmd_add "$skill"
+    fi
+  done
+}
+
+case "$CMD" in
+  list)   cmd_list ;;
+  add)    cmd_add "$TARGET" ;;
+  update) cmd_update ;;
+  *)
+    echo "用法：$0 list | add <skill> | update [skill]"
+    exit 1
+    ;;
+esac

package/skills/_kernel/distillation.md

@@ -0,0 +1,254 @@
+---
+name: distillation
+skill_id: distillation_core
+version: 1.0
+description: >
+  蒸馏元 Skill。从需求挖掘会话的事件日志中提炼经验模式，
+  直接更新 skills/ 和 memory/ 文件，实现系统自成长。
+  当用户说"蒸馏"、"更新skill"、"从日志学习"、"处理日志"时触发。
+is_required: false
+hard_dep: []
+soft_dep: []
+estimated_tokens: 1500
+---
+
+# 蒸馏协议
+
+**你的任务：** 读取事件日志，提炼可复用的模式，更新 Skills 和 Memory 文件。
+**核心原则：** 质量优先于数量。宁可少蒸馏一些，不引入低质量噪音。
+
+---
+
+## Step 0：确认蒸馏范围
+
+询问用户（或读取默认配置）：
+
+```
+"请确认蒸馏范围：
+ A. 指定项目（输入 project_id）
+ B. 所有未蒸馏日志（自动扫描 episodic-logs/ 目录）
+ C. 单条事件（粘贴事件 JSON）"
+```
+
+读取对应的 `episodic-logs/{project_id}.jsonl` 文件。
+
+---
+
+## Step 1：质量过滤
+
+扫描所有事件，按以下规则评分（0-1），**低于 0.6 的事件跳过，不蒸馏**：
+
+```
+人类干预事件（type: human_intervention）：
+  + 0.4  有明确的 correct_angle 字段
+  + 0.3  同类 intervention_category 在本日志中出现 ≥ 2 次
+  + 0.2  notes 字段有具体说明
+  最高：0.9
+
+原型否定事件（type: prototype_rejection）：
+  + 0.4  有 root_cause_analysis.root_question
+  + 0.3  severity = high
+  + 0.2  missed_at_turn 字段有值
+  最高：0.9
+
+矛盾事件（type: contradiction_detected）：
+  + 0.3  resolved = true，且有 resolution 说明
+  + 0.2  severity = high
+  + 0.2  turn_gap > 10（说明矛盾隐蔽，不易发现）
+  最高：0.7
+
+未覆盖决策事件（type: uncovered_decision）：
+  + 0.4  有人工决议（resolution != "pending"）
+  + 0.3  distillation_candidate = true
+  最高：0.7
+
+实现反馈事件（type: implementation_feedback）：
+  + 0.4  unclear_specs 非空（说明需求文档有明确不清晰点）
+  + 0.3  uncovered_decisions 非空（执行 AI 遇到文档漏洞）
+  + 0.2  wrong_assumptions 非空（需求假设被现实否定）
+  + 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
+
+自驱分析完成事件（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
+```
+
+**输出过滤结果：**
+```
+共扫描 N 条事件
+通过质量阈值（≥0.6）：X 条
+跳过（低质量）：Y 条
+```
+
+---
+
+## Step 2：模式提炼
+
+对通过质量过滤的事件，逐条提炼模式。
+
+**提炼的核心问题：**
+
+> 这个事件揭示了什么普遍规律？
+> 如果下次遇到类似情况，Agent 应该怎么做？
+
+**提炼格式：**
+
+```json
+{
+  "source_event_id": "evt_001",
+  "source_project": "proj_2024_001",
+  "pattern_type": "skill_update | memory_entry | decision_tree",
+  "pattern_summary": "用一句话描述这个模式",
+  "trigger_signals": ["触发这个模式的信号词或场景"],
+  "recommended_action": "遇到此情况时，Agent 应该...",
+  "target_file": "skills/core/req-miner.md",
+  "target_section": "阶段三：约束摸底 / 预算追问逻辑",
+  "change_type": "append | replace | new_section",
+  "proposed_content": "具体的修改内容或新增内容",
+  "confidence": 0.82
+}
+```
+
+---
+
+## Step 3：路由判断
+
+每条提炼出的模式，按以下规则路由：
+
+```
+"如何做某件事"的步骤、序列、框架
+→ pattern_type: skill_update
+→ 更新 skills/ 下对应文件的对应章节
+
+"某类客户/行业的特征规律、高频表现"
+→ pattern_type: memory_entry
+→ 写入 memory/patterns/ 或 memory/industry/ 对应文件
+
+"AI 执行时遇到的未覆盖场景 + 有人工决议"
+→ pattern_type: decision_tree
+→ 更新 skills/artifacts/req-miner-artifacts.md 的"未覆盖情况处理规则"章节
+
+"单一案例，不可泛化（置信度 < 0.6）"
+→ 跳过，标注 low-signal，不写入任何文件
+```
+
+---
+
+## Step 4：人工确认（一次性预览 + 单次确认）
+
+**一次性展示全部变更，等待用户单次确认：**
+
+```
+━━━ 蒸馏结果预览（共 N 项变更）━━━
+
+变更 1/N：[skill_update]
+  文件：skills/core/req-miner.md → 章节名（append）
+  内容摘要：[拟新增内容的一句话描述]
+  置信度：0.82 | 来源：proj_xxx / evt_023
+
+变更 2/N：[memory_entry]
+  文件：memory/patterns/failure-patterns.md（append）
+  内容摘要：[拟新增内容的一句话描述]
+  置信度：0.75 | 来源：proj_xxx / evt_045
+
+━━━ 确认应用全部 N 项变更？
+  y     → 全部应用
+  n     → 全部取消
+  1,3   → 仅应用编号 1 和 3，跳过其余
+```
+
+**规则：**
+- 等待用户输入 y / n / 编号列表后再执行写入
+- 不允许跳过此步骤自动写入
+
+---
+
+## Step 5：执行写入
+
+按用户确认的变更列表，逐一修改对应文件：
+
+**Skills 文件修改规则：**
+- `append`：在目标章节末尾追加内容
+- `replace`：替换目标章节中的特定段落（必须精确匹配）
+- `new_section`：在目标章节同级别新增章节
+- 修改后更新文件顶部的 `version` 字段（minor version +1）
+
+**Memory 文件修改规则：**
+- 新增条目时，包含以下字段：
+
+```markdown
+### 模式：[模式名称]
+**触发信号：** [信号词列表]
+**规律描述：** [描述]
+**建议行动：** [遇到此情况时应该...]
+**来源项目：** [project_id]
+**置信度：** [0.0-1.0]
+**最后更新：** [YYYY-MM-DD]
+```
+
+**写入完成后，清除蒸馏标记文件：**
+```bash
+rm -f .distill-needed/{project_id}
+```
+
+---
+
+## Step 6：Git 提交
+
+所有文件修改完成后，提示用户执行 Git 提交：
+
+```bash
+git add skills/ memory/
+git commit -m "distill({project_id}): {一句话描述主要变更}
+
+- {变更1简述}
+- {变更2简述}
+
+Sources: {event_id列表}"
+```
+
+**或由用户自行提交，蒸馏 Agent 不自动执行 git 命令。**
+
+---
+
+## 蒸馏结束报告
+
+```
+━━━ 蒸馏完成 ━━━
+来源项目：{project_id}
+处理事件：{N} 条
+通过质量过滤：{X} 条
+实际写入变更：{Y} 条（跳过 {X-Y} 条：用户取消或低质量）
+
+Skills 更新：
+  - skills/core/req-miner.md（v1.0 → v1.1）
+  - [其他更新文件]
+
+Memory 更新：
+  - memory/patterns/failure-patterns.md（+{N} 条）
+
+下次蒸馏建议时机：完成 {下个project_id} 项目后
+```
+
+---
+
+## 蒸馏质量的自我评估
+
+蒸馏完成后，检查以下问题，有助于判断蒸馏质量：
+
+```
+□ 提炼的模式是否足够普遍，能在至少 2 个不同项目中适用？
+□ 写入 Skills 的内容是否是"如何做"，而不是"什么事实"？
+□ 写入 Memory 的内容是否是"特征规律"，而不是"操作步骤"？
+□ 修改后的 Skills 文件是否仍然清晰易读，没有变得冗长混乱？
+□ 是否有内容其实应该在行业包里，而不是核心框架里？
+```

package/skills/_template/domain.md

@@ -0,0 +1,93 @@
+---
+name: your-skill-name
+skill_id: your_skill_id
+version: 0.1.0
+description: >
+  一句话描述这个 skill 做什么。
+  它是飞轮 Ring 1 的核心——定义"如何分析输入材料并生成产物"。
+is_required: true
+hard_dep: []
+soft_dep: []
+trigger_phrases:
+  - "触发词1"
+  - "触发词2"
+---
+
+# [Skill 名称] 分析协议
+
+**使用场景：** 描述在什么情况下使用此 skill。
+
+---
+
+## Step 0：接收输入材料
+
+用户提供以下任意格式：
+- 直接粘贴文本
+- 文件路径
+- URL
+
+**确认输入后，询问（一次性）：**
+```
+已收到材料（约 XXX 字）。
+请确认以下信息（可省略，我会推断）：
+1. 项目名称：
+2. 分析侧重点：
+```
+
+---
+
+## Step 1：材料扫描
+
+**静默执行，不逐条输出。扫描以下维度：**
+
+```
+维度 1：[你的维度1]
+维度 2：[你的维度2]
+维度 3：[你的维度3]
+```
+
+---
+
+## Step 2：分析输出
+
+**输出格式：**
+
+```
+━━━ 分析结果 | 项目：{name} ━━━
+
+## 一、[核心输出1]
+[内容]
+⚠️ 假设 A1：[不确定点]
+
+## 二、[核心输出2]
+[内容]
+```
+
+---
+
+## Step 3：生成产物
+
+加载 `skills/your-skill-name/artifacts.md`，按规格生成产物。
+
+---
+
+## Step 4：写入状态
+
+```python
+state["skill"] = "your-skill-name"
+state["artifacts_generated"] = True
+```
+
+追加事件日志：
+```json
+{"type": "analysis_completed", "distillation_candidate": true}
+```
+
+---
+
+## Step 5：自动启动 Ring 2
+
+产物完成后，通过 Bash 工具调用：
+```bash
+./scripts/bridge-to-coder.sh {project_id} {tool}
+```

package/skills/_template/feedback-questions.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# [your-skill-name] 领域专属反馈问题
+# 替换为与你的 skill 相关的问题
+
+QUESTION_1="执行过程中哪些输入信息不清晰？"
+QUESTION_2="遇到了哪些未覆盖的决策点？"
+QUESTION_3="哪些假设与实际情况不符？"
+QUESTION_4="哪些产出无法验证质量？"
+QUESTION_5="总体反馈（执行难度、输入质量评分 1-10）："

package/skills/_template/skill.yaml

@@ -0,0 +1,21 @@
+name: your-skill-name
+version: 0.1.0
+description: 一句话描述这个 skill 的用途
+author: your-name
+license: MIT
+
+# 飞轮配置
+ring1_skill: skills/your-skill-name/domain.md
+ring1_artifacts_doc: execution-doc.md       # Ring 1 输出给 Ring 2 的文档名
+ring2_bridge: scripts/bridge-to-coder.sh    # 使用内核默认 bridge，也可替换为自定义脚本
+ring2_default_tool: claude
+ring3_feedback_questions: skills/your-skill-name/feedback-questions.sh
+
+# 激活触发词（用户说这些话时自动加载本 skill）
+triggers:
+  - "触发词1"
+  - "触发词2"
+
+# 初始记忆文件（蒸馏结果会写回这里）
+memory:
+  - skills/your-skill-name/memory/patterns.md

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] 项
+    建议专家审查后发送给客户确认。"
+```