# 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 顶部导航。