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 三张新表为唯一事实源。

已确认的决策

数据库:复用现有 MySQL(.env 的 MYSQL_* 配置,同一个库),新建三张表 search_data / mode_process / mode_tools,与旧表 fqe_posts / fqe_tools 并存。
历史数据:只导入搜索结果(runs_full 的 form_A.json → search_data); 工序/工具解构数据不导入,由新系统重新产生。
mode_process 行粒度:一行一个工序(procedure),steps 等嵌套结构存 JSON 列。
架构:DB 为唯一事实源(区别于旧系统"文件为主 + DB 双写"); 本地 JSON 仅作运行中间产物(runs/,gitignore)。
范围裁剪:只保留 form A 单形式;工序/工具解构只要大模型解构 (不含 procedure-dsl 执行引擎、mode-dsl 模式提取);去掉 cloudflared 公网分享、规范文档编辑弹窗、pid/log 等冗余。
聚类库 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 体系,按现有惯例用独立脚本 + 手工验收:

python db.py --init 建三张表成功。
python import_history.py 导入 q0000–q0003 搜索结果,行数与 form_A.json 条数一致。
启动 server,Dashboard 各卡片/图表出数(解构类指标为 0 是正常初始态)。
Dataset 选一个帖子触发工具解构、工序解构,落库且右栏渲染正确,版本切换可用。
聚类库 tab 显示占位页。

UI

单文件 HTML + 原生 JS + ECharts(CDN)。实现阶段用 frontend-design 技能出定制视觉: 延续现有工序结果页风格(深色表头多色分区表格、标签 pill、卡片),三 tab 顶部导航。

2026-06-12-mode-workflow-design.md 9.5 KB Vēsture Neapstrādāts