docs: mode_workflow 设计文档(三表入库+三tab单页)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/superpowers/specs/2026-06-12-mode-workflow-design.md

@@ -0,0 +1,206 @@
+# mode_workflow 设计文档
+
+日期:2026-06-12
+状态:已确认(用户口头批准)
+位置:`examples/mode_workflow/`
+
+## 目标
+
+在 `examples/` 下新建 `mode_workflow` 项目,把 `examples/process_pipeline/script/search_eval/` 中
+`fixed_query_eval`(固定 query 搜索评估 + 工具解构)和 `mode_procedure`(工序解构)两套服务
+合并简化为一套:单服务 + 单页 HTML(Dashboard / Dataset / 聚类库 三 tab),
+数据以 MySQL 三张新表为唯一事实源。
+
+## 已确认的决策
+
+1. **数据库**:复用现有 MySQL(`.env` 的 `MYSQL_*` 配置,同一个库),新建三张表
+   `search_data` / `mode_process` / `mode_tools`,与旧表 `fqe_posts` / `fqe_tools` 并存。
+2. **历史数据**:只导入搜索结果(runs_full 的 `form_A.json` → `search_data`);
+   工序/工具解构数据不导入,由新系统重新产生。
+3. **mode_process 行粒度**:一行一个工序(procedure),`steps` 等嵌套结构存 JSON 列。
+4. **架构**:DB 为唯一事实源(区别于旧系统"文件为主 + DB 双写");
+   本地 JSON 仅作运行中间产物(`runs/`,gitignore)。
+5. **范围裁剪**:只保留 form A 单形式;工序/工具解构只要大模型解构
+   (不含 procedure-dsl 执行引擎、mode-dsl 模式提取);去掉 cloudflared 公网分享、
+   规范文档编辑弹窗、pid/log 等冗余。
+6. **聚类库** tab 仅占位。
+
+## 文件结构
+
+```
+examples/mode_workflow/
+├── README.md                  # 项目说明 + 启动方式
+├── server.py                  # 唯一服务(端口 8772):页面 + 全部 API
+├── db.py                      # MySQL 连接 + 三表建表/读写(读 .env MYSQL_*)
+├── index.html                 # 单文件前端:Dashboard / Dataset / 聚类库 三 tab
+├── import_history.py          # 一次性脚本:runs_full form_A.json → search_data
+├── pipeline/
+│   ├── search_eval.py         # 搜索+评估(从 search_and_evaluate.py 精简,写 search_data)
+│   ├── procedure_extract.py   # 工序解构(仅大模型),写 mode_process
+│   └── tool_extract.py        # 工具解构(仅大模型),写 mode_tools
+├── prompts/
+│   ├── eval_prompt.md         # 搜索评估 prompt(同步自 search_eval)
+│   ├── procedure_extract_system.md
+│   └── tool_extract_system.md
+├── reference/
+│   └── judged_matrix.json     # 内容树(27 动作 × 50 类型,643 有效节点)
+└── runs/                      # 运行中间产物(gitignore)
+```
+
+来源映射:
+
+| 新文件 | 来源 |
+|---|---|
+| `pipeline/search_eval.py` | `search_eval/search_and_evaluate.py`(只保留 form A 路径) |
+| `pipeline/procedure_extract.py` | `mode_procedure/` 的工序解构调用链(仅 LLM 解构部分) |
+| `pipeline/tool_extract.py` | `fixed_query_eval/tool_extract.py` |
+| `prompts/procedure_extract_system.md` | `mode_procedure/mode-dsl/prompts/procedure_extract_system.md` |
+| `prompts/tool_extract_system.md` | `fixed_query_eval/prompts/tool_extract_system.md` |
+| `db.py` | 参考 `fixed_query_eval/db.py`(pymysql + .env),表结构全新 |
+| `reference/judged_matrix.json` | `search_eval/evaluation/judged_matrix.json` |
+
+## 三张表 Schema(MySQL)
+
+### search_data — 一行一帖
+
+唯一键 `(query_id, case_id)`。
+
+| 列 | 类型 | 说明 |
+|---|---|---|
+| id | BIGINT PK AUTO_INCREMENT | |
+| query_id | VARCHAR(32) | 如 q0000 |
+| query_text | VARCHAR(512) | query 原文 |
+| case_id | VARCHAR(128) | 平台_内容ID |
+| platform | VARCHAR(32) | xhs / gzh / zhihu |
+| title | TEXT | 帖子标题 |
+| url | TEXT | 帖子链接 |
+| content_type | VARCHAR(32) | note / video 等 |
+| body_text | LONGTEXT | 正文 |
+| images | JSON | 图片 URL 数组 |
+| videos | JSON | 视频 URL 数组 |
+| like_count | INT | |
+| publish_time | DATETIME NULL | |
+| quality_score | FLOAT NULL | post._quality_score |
+| quality_grade | VARCHAR(8) NULL | A/B/C |
+| found_by_queries | JSON | 命中的子 query |
+| knowledge_type | JSON | ["能力","工序","工具"] 子集 |
+| overall_score | FLOAT NULL | 综合分(相关均值+质量均值)/2 |
+| llm_evaluation | JSON | 评估全量原始 JSON |
+| created_at / updated_at | DATETIME | |
+
+### mode_process — 一行一工序
+
+| 列 | 类型 | 说明 |
+|---|---|---|
+| id | BIGINT PK | |
+| query_id / case_id / platform / post_title | 同上 | 关联帖子 |
+| source | JSON | 解构返回的 source 块 |
+| procedure_id | VARCHAR(16) | p1, p2… |
+| name / purpose | VARCHAR/TEXT | 工序名 / 目的 |
+| category | VARCHAR(32) | 产物创造/资产建设/自动化/分析/学习 |
+| declarations | JSON | inputs / resources / returns |
+| type_registry | JSON | 自定义类型表 |
+| steps | JSON | 步骤数组全量(id/kind/via/effect/action/substance/form/directive/intent/inputs/outputs) |
+| step_count | INT | |
+| tools_used | JSON | 从 steps[].via 去重提取 |
+| model | VARCHAR(64) | 解构用模型 |
+| version | VARCHAR(16) | v_MMDDHHMM,保留历史版本 |
+| cost_usd | DECIMAL(10,6) NULL | 本次解构 LLM 成本 |
+| duration_s | FLOAT NULL | 本次解构耗时 |
+| created_at | DATETIME | |
+
+### mode_tools — 一行一工具
+
+字段风格与旧 `fqe_tools` 对齐,新增成本/耗时:
+
+| 列 | 类型 | 说明 |
+|---|---|---|
+| id | BIGINT PK | |
+| query_id / case_id / platform / post_title | | 关联帖子 |
+| tool_name | VARCHAR(256) | 工具名称 |
+| substance_scope | JSON | 实质作用域 |
+| form_scope | JSON NULL | 形式作用域 |
+| creation_layer | VARCHAR(16) | 制作层 / 创作层 |
+| source_link | TEXT NULL | |
+| input_desc / output_desc | TEXT NULL | 输入 / 输出 |
+| usage_json | JSON NULL | 用法 |
+| cases_json | JSON NULL | 案例(输入/输出/效果) |
+| defects_json | JSON NULL | 缺点 |
+| last_update_time | VARCHAR(32) NULL | 工具最新更新时间 |
+| model / version | VARCHAR | 同 mode_process |
+| cost_usd / duration_s | | 同 mode_process |
+| created_at | DATETIME | |
+
+## Dashboard 指标口径
+
+结果数据:
+
+| 指标 | 计算方式 | 图表 |
+|---|---|---|
+| 内容树覆盖节点 | mode_process.steps 的 (action × 输入/输出 type) 命中 judged_matrix 有效节点数 / 643 | 数字卡 + 27×50 热力图 |
+| 实质覆盖度 | steps.substance ∪ mode_tools.substance_scope 去重数(无固定分母,展示数量 + 分布) | 条形图 |
+| 形式覆盖度 | steps.form ∪ mode_tools.form_scope 同上 | 条形图 |
+| 采集帖子数量 | count(search_data) | 数字卡 |
+| 解构帖子数量 | distinct case_id in (mode_process ∪ mode_tools) | 数字卡 |
+| 工具数量 | distinct tool_name in mode_tools | 数字卡 |
+| 工序提及工具 Top10 | steps[].via 频次 Top10 | 横向条形图 |
+
+过程数据:
+
+| 指标 | 计算方式 | 图表 |
+|---|---|---|
+| 单条/累计解构成本 | avg/sum(cost_usd),mode_process ∪ mode_tools | 数字卡 + 按日趋势线 |
+| 平均/总耗时 | avg/sum(duration_s) | 数字卡 |
+| 工序进度 | distinct case_id in mode_process ÷ search_data 中 knowledge_type 含「工序」的帖子数 | 进度环 |
+| 工具进度 | 同理,knowledge_type 含「工具」 | 进度环 |
+
+注:实质/形式覆盖度按"去重数量 + 分布图"处理(非百分比);进度分母取
+"knowledge_type 含对应类型的帖子数"。两个口径已经用户确认,后续如有标准分类体系可改为百分比。
+
+## Dataset 页面(核心)
+
+顶部「工序 / 工具」子切换,三栏布局:
+
+- **左栏** query 列表:从 search_data 按 query_id 聚合,显示帖子数 / 解构进度。
+- **中栏** 帖子列表:该 query 下帖子卡片(标题/平台/评分/知识类型),带「解构」触发按钮。
+- **右栏** 解构结果:
+  - 工序模式:复刻现有大模型工序结果页——版本下拉(v_xxx)、重新生成按钮、
+    工序卡片(名称/目的/类别/平台/作者 + 输入/返回声明)、
+    需求-输入-实现-输出分区明细表格、推断字段高亮(inferred 标记 + hover 理由)。
+  - 工具模式:渲染 mode_tools 工具卡片(作用域/层级/输入输出/用法/案例/缺点)。
+
+数据流:index.html → `/api/*` → MySQL。点「解构」→ server 起子进程跑 pipeline 脚本 →
+写库 → 前端轮询任务状态接口刷新。
+
+## API 概要(server.py,端口 8772)
+
+- `GET /` — index.html
+- `GET /api/dashboard` — 全部 Dashboard 聚合指标
+- `GET /api/queries` — query 列表 + 进度
+- `GET /api/posts?query_id=` — 帖子列表
+- `GET /api/process?case_id=&version=` / `GET /api/process_versions?case_id=`
+- `GET /api/tools?case_id=&version=` / `GET /api/tools_versions?case_id=`
+- `POST /api/extract_process` / `POST /api/extract_tools` — 触发解构(子进程)
+- `GET /api/task_status?task_id=` — 轮询任务状态
+- `POST /api/run_search` — 触发搜索评估
+
+## 错误处理
+
+- MySQL 不可达:server 启动报错并明确提示检查 `.env`;不做静默文件回退(与旧系统不同)。
+- 解构子进程失败:任务状态接口返回 failed + 日志尾部,前端弹出错误。
+- LLM 返回 JSON 解析失败:重试 1 次,仍失败则记任务失败,不写脏数据。
+
+## 测试 / 验收
+
+仓库无 pytest 体系,按现有惯例用独立脚本 + 手工验收:
+
+1. `python db.py --init` 建三张表成功。
+2. `python import_history.py` 导入 q0000–q0003 搜索结果,行数与 form_A.json 条数一致。
+3. 启动 server,Dashboard 各卡片/图表出数(解构类指标为 0 是正常初始态)。
+4. Dataset 选一个帖子触发工具解构、工序解构,落库且右栏渲染正确,版本切换可用。
+5. 聚类库 tab 显示占位页。
+
+## UI
+
+单文件 HTML + 原生 JS + ECharts(CDN)。实现阶段用 frontend-design 技能出定制视觉:
+延续现有工序结果页风格(深色表头多色分区表格、标签 pill、卡片),三 tab 顶部导航。