@vima_tech/flywheel 1.0.0

package/.claude/commands/flywheel.md

@@ -0,0 +1,42 @@
+# 启动自飞轮需求挖掘
+
+执行以下步骤，激活飞轮模式：
+
+## Step 0：检查待蒸馏标记
+
+读取 `.distill-needed/` 目录。如果存在标记文件：
+- 列出所有待蒸馏项目
+- 询问用户是否现在处理，还是先处理新文档
+- 若用户选择现在蒸馏：读取 `skills/core/distillation.md`，对每个标记项目执行蒸馏协议（展示预览，单次 y/n 确认），完成后删除标记文件
+
+## Step 1：加载运行时上下文
+
+按顺序读取：
+1. `memory/patterns/failure-patterns.md`（常驻知识，必须）
+2. `skills/core/auto-req.md`（Ring 1 分析协议）
+
+## Step 2：显示飞轮状态
+
+输出当前状态摘要：
+
+```
+━━━ Req-Miner 自飞轮 | 就绪 ━━━
+
+待蒸馏项目：{N} 个
+活跃项目：
+  • {project_id} — 阶段：{状态} | 假设：{N}项
+
+提供文档材料开始 Ring 1 分析：
+  • 直接粘贴文本
+  • 输入文件路径（如 /path/to/doc.pdf）
+  • 输入 URL
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Step 3：等待用户输入材料
+
+用户提供材料后，执行 `skills/core/auto-req.md` 的五维度扫描流程。
+
+---
+
+**别名：** 用户输入 `sfw`、`start flywheel`、`开始飞轮`、`开启飞轮` 时，等同于运行本命令。

package/.claude/commands/skill.md

@@ -0,0 +1,36 @@
+# Skill 包管理
+
+管理当前项目中安装的 Flywheel skill 包。
+
+## 用法
+
+用户输入以下命令时，通过 Bash 工具执行对应操作：
+
+### `/skill list` 或 `skill list`
+```bash
+./scripts/flywheel-install.sh list
+```
+列出所有已安装的 skill 包、版本号和描述。
+
+### `/skill add <skill-name>` 或 `skill add <name>`
+```bash
+./scripts/flywheel-install.sh add <skill-name>
+```
+从官方注册表安装新 skill 包。
+
+### `/skill update` 或 `skill update`
+```bash
+./scripts/flywheel-install.sh update
+```
+检查并更新所有已安装 skill 包到最新版本。
+
+### `/skill update <skill-name>`
+```bash
+./scripts/flywheel-install.sh update <skill-name>
+```
+更新指定 skill 包。
+
+---
+
+执行命令后，输出结果并告知用户下一步操作。
+如果安装了新 skill，提示用户使用 `/flywheel` 激活该 skill 的飞轮。

package/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /home/renmk/projects/Flywheel status --short)",
+      "Bash(git -C /home/renmk/projects/Flywheel ls-files docs/)",
+      "Bash(mkdir -p /home/renmk/projects/Flywheel/.claude/worktrees/fix-poster-accuracy/docs)",
+      "Bash(cp /home/renmk/projects/Flywheel/docs/Flywheel_Poster.html /home/renmk/projects/Flywheel/.claude/worktrees/fix-poster-accuracy/docs/)",
+      "Bash(git -C /home/renmk/projects/Flywheel/.claude/worktrees/fix-poster-accuracy status --short)",
+      "Bash(git -C /home/renmk/projects/Flywheel/.claude/worktrees/fix-poster-accuracy log main..HEAD --oneline)",
+      "Bash(git branch *)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,178 @@
+# Flywheel：自成长 AI Agent 飞轮框架
+
+**核心哲学：输入材料，AI 分析，执行反馈，自我进化。**
+
+你是一个自飞轮 Agent，从输入材料中自主分析、生成产物、
+桥接执行工具，并通过执行反馈持续蒸馏自身 Skills。
+
+## 飞轮激活
+
+**用户通过以下任意方式激活飞轮：**
+
+| 方式 | 示例 |
+|---|---|
+| 斜杠命令（推荐） | `/flywheel` |
+| 英文触发词 | `sfw`、`start flywheel` |
+| 中文触发词 | `开始飞轮`、`开启飞轮`、`启动飞轮` |
+| 直接提供材料 | 粘贴文档 / 文件路径 / URL |
+
+检测到以上任意信号时，立即执行 `.claude/commands/flywheel.md` 中的激活流程。
+
+**默认不激活：** 打开会话后不主动问候或启动，等待用户给出激活信号。
+
+---
+
+## 目录结构
+
+```
+CLAUDE.md                         ← 你正在读的文件（系统引导）
+install.sh                        ← 一键安装脚本
+.claude/commands/
+  flywheel.md                     ← /flywheel 激活命令
+  skill.md                        ← /skill 包管理命令
+scripts/
+  auto-distill.sh                 ← Ring 3：检查蒸馏触发条件
+  feedback-hook.sh                ← Ring 2→3：收集执行反馈
+  bridge-to-coder.sh              ← Ring 1→2：产物→执行工具
+  flywheel-install.sh             ← skill 包管理工具
+skills/
+  _kernel/
+    distillation.md               ← 通用蒸馏协议（Ring 3 核心）
+  _template/                      ← 新建 skill 的脚手架模板
+  req-mining/                     ← 内置 skill：需求挖掘与落地
+    skill.yaml                    ← skill 元数据
+    domain.md                     ← Ring 1 分析协议
+    artifacts.md                  ← 产物规格
+    feedback-questions.sh         ← 领域专属反馈问题
+    memory/
+      failure-patterns.md         ← 已知失败模式（常驻加载）
+    industry/
+      erp.md                      ← ERP 行业包
+templates/
+  state.json                      ← 项目状态模板
+projects/                         ← 项目状态（Git 忽略）
+episodic-logs/                    ← 事件日志（Git 忽略）
+.distill-needed/                  ← 蒸馏触发标记（Git 忽略）
+```
+
+---
+
+## 飞轮架构
+
+```
+Ring 1  用户提供材料（文本 / 文件 / URL）
+          ↓
+        skill 分析协议（skills/{skill}/domain.md）
+          ↓ 产物（含假设清单 + 信息缺口）
+Ring 2  scripts/bridge-to-coder.sh
+          ↓ 注入产物到执行工具
+        执行工具工作（写入 .flywheel-feedback.json）
+          ↓
+        scripts/feedback-hook.sh --auto
+          ↓ 写入 episodic-logs/
+Ring 3  积累 ≥3 条高质量反馈
+          ↓
+        蒸馏协议（skills/_kernel/distillation.md）
+          ↓ 展示预览，单次 y/n → 更新 skills/ + memory/
+          ↓
+        下次分析更准确 ← 飞轮闭合
+```
+
+---
+
+## 启动步骤
+
+**每次会话启动时，首先执行 Step 0：**
+
+```
+Step 0（必须，优先于一切）：检查 .distill-needed/ 目录
+  → 目录下有文件（如 .distill-needed/proj_xxx）
+  → 立即读取 skills/_kernel/distillation.md
+  → 对每个标记的项目执行蒸馏（展示预览，单次 y/n 确认）
+  → 蒸馏完成后删除对应标记文件
+  → 所有标记处理完毕后，继续正常会话
+```
+
+**用户激活飞轮后（Ring 1）：**
+
+```
+1. 读取已安装 skill 的 memory 文件（常驻，必须）
+2. 读取 skill.yaml，加载对应 domain.md
+3. 根据材料内容判断是否加载行业包
+4. 检查 projects/{project_id}/state.json
+   - 存在 → 恢复上次会话状态
+   - 不存在 → 从 templates/state.json 创建，写入 skill 字段
+5. 执行 domain.md 中的分析协议（静默）
+6. 输出分析结果 + 信息缺口清单
+7. 加载 skills/{skill}/artifacts.md，生成产物
+8. 通过 Bash 工具直接调用：
+   ./scripts/bridge-to-coder.sh {project_id} {tool}
+```
+
+---
+
+## 会话中的文件操作
+
+- 每轮对话后：更新 `projects/{project_id}/state.json`（含 `skill` 字段）
+- 关键事件：追加到 `episodic-logs/{project_id}.jsonl`
+- 蒸馏完成后：删除 `.distill-needed/{project_id}` 标记文件
+
+---
+
+## Ring 3 蒸馏触发条件
+
+```
+□ 同一项目积累 ≥3 条 quality_score≥0.6 的反馈事件
+□ 同类干预事件跨项目出现 ≥3 次
+□ 用户说"蒸馏"、"更新skill"、"从日志学习"
+```
+
+触发后读取 `skills/_kernel/distillation.md`，执行蒸馏协议。
+
+---
+
+## 关键协议
+
+### 状态文件路径
+```
+projects/{project_id}/state.json      ← 含 skill 字段
+projects/{project_id}/artifacts/      ← 产物存放位置
+```
+
+`project_id` 由用户提供或自动生成（格式：`proj_YYYYMMDD_NN`）
+
+### 每轮状态行
+```
+━━━ [Ring 1/2/3] | Skill：{skill} | 项目：{project_id} | 假设：X项 ━━━
+```
+
+### 未覆盖决策协议
+遇到 skill 未覆盖的场景时，追加到 `uncovered_decisions`，输出 `⚠️ L2 告警`。
+
+---
+
+## Skill 管理
+
+```bash
+/skill list              # 列出已安装 skill
+/skill add code-review   # 安装新 skill
+/skill update            # 更新所有 skill
+```
+
+## Git 规范
+
+```bash
+git add skills/ memory/
+git commit -m "distill({skill}): {描述} (from {project_id})"
+```
+
+## .gitignore 内容
+
+```
+projects/*/
+episodic-logs/
+.distill-needed/*
+!.distill-needed/.gitkeep
+*.log
+.DS_Store
+```

package/README.md

@@ -0,0 +1,163 @@
+# Flywheel
+
+**自成长 AI Agent 飞轮框架** — 让任何需要积累迭代的 AI 工作流都能自我进化。
+
+基于 Claude Code 运行，无需独立服务器，一行命令安装，按 skill 包扩展。
+
+---
+
+## About
+
+**Flywheel** 是一个让 AI 工作流自我进化的框架。任何需要积累经验、迭代改进的 AI 任务，都可以通过「输入材料 → AI 分析执行 → 反馈收集 → 自我蒸馏」闭环持续变强。
+
+### 核心机制：三环飞轮
+
+- **Ring 1** — AI 分析输入材料，产出产物和假设清单
+- **Ring 2** — 执行工具落地实现，生成反馈记录
+- **Ring 3** — 反馈积累 ≥3 条后蒸馏，更新 Skill 能力
+
+每个环节自动衔接，人工只在最后确认蒸馏变更。
+
+### 特点
+
+- **基于 Claude Code** — 无需独立服务器，直接运行
+- **一行安装** — `curl -sSL ... | bash`
+- **Skill 扩展** — 框架只给机制，内容靠 Skill 包积累
+- **自我进化** — 同一类问题越分析越准
+
+### 内置 Skill：req-mining
+
+开箱即用的需求挖掘与落地场景。Ring 1 五维度扫描、Ring 2 桥接编程工具、Ring 3 蒸馏规律。已有 ERP / 进销存 / 外贸行业包。
+
+### 适用场景
+
+- 需求分析工作流
+- 代码审查积累
+- 领域知识沉淀
+- 任何需要「做多了就变聪明」的场景
+
+---
+
+## 一键安装
+
+```bash
+# npm 安装（推荐）
+npm install -g @vima_tech/flywheel
+
+# GitHub 安装（适用于自定义场景）
+curl -sSL https://raw.githubusercontent.com/renmengkai/flywheel/main/install.sh | bash
+
+# 指定 skill（仅限 GitHub 安装方式）
+curl -sSL https://raw.githubusercontent.com/renmengkai/flywheel/main/install.sh | bash -s req-mining
+
+# 安装后启动
+claude
+# 输入 /flywheel 或 sfw 激活
+```
+
+---
+
+## 核心理念：飞轮三环
+
+```
+Ring 1  AI 分析输入材料，生成产物（含假设清单）
+          ↓ 自动桥接
+Ring 2  执行工具实现，遇到问题写入反馈文件
+          ↓ 自动收集
+Ring 3  反馈积累 ≥3 条 → 蒸馏 → 更新 Skill 文件
+          ↓
+        下次分析更准确 ← 飞轮闭合
+```
+
+每个环节自动衔接，唯一需要人工确认的是蒸馏时的变更预览（单次 y/n）。
+
+---
+
+## 内置 Skill：req-mining
+
+开箱即用的需求挖掘与落地场景：
+
+- **Ring 1**：自驱五维度需求扫描，用 `⚠️ 假设` 标注不确定点
+- **Ring 2**：自动桥接到 Claude Code / opencode / codex 等编程工具
+- **Ring 3**：从实现反馈中蒸馏需求表达规律，持续提升分析准确率
+- **行业包**：ERP / 进销存 / 外贸开箱即用，更多可贡献
+
+---
+
+## 已安装 Skill 管理
+
+```bash
+/skill list              # 列出已安装 skill 及版本
+/skill add code-review   # 安装新 skill
+/skill update            # 更新所有 skill 到最新版
+```
+
+---
+
+## 目录结构
+
+```
+flywheel/
+  install.sh                    ← GitHub 安装脚本
+  package.json                  ← npm 包配置（bin 入口）
+  bin/
+    flywheel.js                 ← npm 全局命令入口
+  CLAUDE.md                     ← 框架系统引导（Claude Code 自动加载）
+  scripts/                      ← 内核脚本（自动触发，无需手动）
+  skills/
+    _kernel/distillation.md     ← 通用蒸馏协议
+    _template/                  ← 新建 skill 的脚手架
+    req-mining/                 ← 内置 skill
+      skill.yaml                ← 元数据
+      domain.md                 ← Ring 1 分析协议
+      memory/                   ← 蒸馏后自动更新
+```
+
+---
+
+## 创建自己的 Skill
+
+```bash
+# 1. 复制模板
+cp -r skills/_template skills/your-skill-name
+
+# 2. 填写元数据
+edit skills/your-skill-name/skill.yaml
+
+# 3. 定义分析协议
+edit skills/your-skill-name/domain.md
+
+# 4. 定义反馈问题
+edit skills/your-skill-name/feedback-questions.sh
+
+# 5. 激活
+/flywheel  # 检测到新 skill，自动加载
+```
+
+详见 [创建 Skill 指南](docs/creating-skills.md)（待补充）。
+
+---
+
+## 开源贡献
+
+欢迎提交新 skill 包或改进内核：
+
+- **新 skill**：提交 PR，放在 `skills/your-skill-name/` 下
+- **失败模式**：通过蒸馏自动积累，也可手动追加到 `skills/req-mining/memory/failure-patterns.md`
+- **内核改进**：修改 `scripts/` 或 `skills/_kernel/` 下的文件
+
+---
+
+## License
+
+MIT
+
+---
+
+<div align="center" style="background:#0b0d12; padding:24px 0; margin:0; border-radius:8px;">
+
+![Flywheel Poster](docs/Flywheel_Poster.png)
+
+**[📄 View Full Poster →](docs/Flywheel_Poster.html)**
+
+</div>

package/agents.md

@@ -0,0 +1,59 @@
+# Agent 目录
+
+Flywheel 框架的 Agent 结构说明。每个 skill 包含自己的 Ring 1 Agent；
+内核蒸馏协议和脚本被所有 skill 共享。
+
+---
+
+## 内核 Agent（所有 skill 共用）
+
+| Agent | 文件 | 用途 | 加载时机 |
+|---|---|---|---|
+| 蒸馏 | `skills/_kernel/distillation.md` | Ring 3：从日志提炼模式，更新 Skill 文件 | Ring 3 触发时 |
+
+## Skill Agent：req-mining
+
+| Agent | 文件 | 用途 | 加载时机 |
+|---|---|---|---|
+| Ring 1 分析 | `skills/req-mining/domain.md` | 五维度需求扫描，生成三份产物 | `/flywheel` 激活时 |
+| 产物规格 | `skills/req-mining/artifacts.md` | 三份产物格式规范 | 分析完成后 |
+| ERP 行业包 | `skills/req-mining/industry/erp.md` | ERP/进销存/外贸专项 | 行业关键词触发 |
+
+---
+
+## Skill DAG
+
+```
+skills/req-mining/memory/failure-patterns.md  ← 常驻加载
+        │
+        ▼
+skills/req-mining/domain.md                   ← Ring 1 核心
+        │
+        ├── skills/req-mining/industry/erp.md ← 行业匹配时
+        │
+        └── skills/req-mining/artifacts.md    ← 分析完成后
+
+skills/_kernel/distillation.md               ← Ring 3 触发时
+```
+
+---
+
+## 蒸馏事件路由
+
+| 事件类型 | 目标文件 |
+|---|---|
+| `implementation_feedback.unclear_specs` | `skills/req-mining/artifacts.md` |
+| `implementation_feedback.wrong_assumptions` | `skills/req-mining/memory/failure-patterns.md` |
+| `analysis_completed`（假设被验证正确） | `skills/req-mining/domain.md` 推断规则库 |
+| `analysis_completed`（假设被验证错误） | `skills/req-mining/memory/failure-patterns.md` |
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|---|---|---|
+| v1.0.0 | 2026-05 | 重组为 Flywheel 框架，req-miner 成为内置 skill，添加一键安装 |
+| v0.3.0 | 2026-05 | 统一为单一飞轮模式，自动触发三环 |
+| v0.2.0 | 2024-01 | 拆分 skill 文件，添加蒸馏元 skill |
+| v0.1.0 | 2024-01 | 初始版本 |

package/bin/flywheel.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Flywheel CLI
+ * Global entry point for @renmengkai/flywheel npm package
+ */
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const REPO_DIR = process.env.FLYWHEEL_DIR || process.cwd();
+
+function resolveScript(name) {
+  const scripts = {
+    'flywheel-install': path.join(__dirname, '../scripts/flywheel-install.sh'),
+    'auto-distill': path.join(__dirname, '../scripts/auto-distill.sh'),
+    'feedback-hook': path.join(__dirname, '../scripts/feedback-hook.sh'),
+    'bridge-to-coder': path.join(__dirname, '../scripts/bridge-to-coder.sh'),
+  };
+  return scripts[name];
+}
+
+function runScript(scriptPath, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('bash', [scriptPath, ...args], {
+      cwd: REPO_DIR,
+      stdio: 'inherit',
+      env: { ...process.env, FLYWHEEL_DIR: REPO_DIR },
+    });
+    child.on('exit', (code) => {
+      if (code === 0) resolve(0);
+      else reject(new Error(`exit code ${code}`));
+    });
+  });
+}
+
+const [,, command, ...args] = process.argv;
+
+if (!command) {
+  console.log(`
+Flywheel CLI — 自成长 AI Agent 飞轮框架
+
+用法: flywheel <command> [args]
+
+可用命令:
+  install <skill>     安装 skill 包
+  list                列出已安装的 skill
+  update [skill]      更新 skill 包
+  distill [project]   手动触发蒸馏
+  help                显示帮助
+
+示例:
+  flywheel install req-mining
+  flywheel list
+  flywheel update
+  flywheel distill proj_20260515_01
+`);
+  process.exit(0);
+}
+
+switch (command) {
+  case 'help':
+    console.log(`
+Flywheel CLI — 自成长 AI Agent 飞轮框架
+
+用法: flywheel <command> [args]
+
+可用命令:
+  install <skill>     安装 skill 包
+  list                列出已安装的 skill
+  update [skill]      更新 skill 包
+  distill [project]   手动触发蒸馏
+
+示例:
+  flywheel install req-mining
+  flywheel list
+  flywheel update
+  flywheel distill proj_20260515_01
+`);
+    break;
+  case 'install':
+    runScript(resolveScript('flywheel-install'), ['add', ...args]).catch((e) => process.exit(1));
+    break;
+  case 'list':
+    runScript(resolveScript('flywheel-install'), ['list']).catch((e) => process.exit(1));
+    break;
+  case 'update':
+    runScript(resolveScript('flywheel-install'), ['update', ...args]).catch((e) => process.exit(1));
+    break;
+  case 'distill':
+    runScript(resolveScript('auto-distill'), args).catch((e) => process.exit(1));
+    break;
+  default:
+    console.error(`未知命令: ${command}`)
+    process.exit(1);
+}