# mode_workflow · 搜索评估 + 工序/工具解构工作台

MySQL 四表(search_process / search_tools / mode_process / mode_tools)为唯一事实源的单页工作台:
Dashboard(结果/过程指标可视化)、Dataset(query → 帖子 → 工序/工具解构)、聚类库(占位)。

设计文档:`docs/superpowers/specs/2026-06-12-mode-workflow-design.md`

## 启动

```bash
# 0. 前置:.env 配 MYSQL_* 与 OPEN_ROUTER_API_KEY;pip install -e .
python db.py init             # 建四张表(幂等);db.py clear 清空数据
python import_history.py      # (可选)导入 fixed_query_eval 历史搜索结果
python server.py              # http://localhost:8772
```

## 结构

| 文件 | 职责 |
|---|---|
| `db.py` | 四表 DDL + 全部读写(读 .env MYSQL_*);连接走 `PooledDB` 池(远程 RDS 每次握手 ~0.5s,池复用避免每请求重连) |
| `server.py` | 页面 + API + 解构任务子进程管理(端口 8772);`/api/dashboard` 结果带缓存(任务完成时作废 + 60s 兜底 TTL),`/api/extract` 等带 ETag/304 |
| `index.html` | 单文件前端:Dashboard / Dataset / 聚类库 |
| `pipeline/search_eval.py` | 任意 query 搜索+评估 → search_process / search_tools(按解构方向分表) |
| `pipeline/procedure_extract.py` | 工序解构(LLM 直出)→ mode_process |
| `pipeline/tool_extract.py` | 工具解构 → mode_tools |
| `import_process_knowledge.py` | 已采纳工序(mode_process 最新版)→ 知识导入接口;**读 DB 非本地文件**,采纳口径同 Dashboard(`db.is_adopted_rel`) |
| `prompts/` | 工序/工具解构 system prompt(可单独迭代) |
| `reference/judged_matrix.json` | 内容树(27 动作×50 类型),Dashboard 覆盖度用 |
| `runs/` | 运行日志与调试副本(gitignore):search_process / search_tools / mode_process / mode_tools / logs |

搜索/评估/转写引擎函数只读复用
`examples/process_pipeline/script/search_eval/search_and_evaluate.py`,本目录不复制引擎代码。

## 数据流

```
新建搜索(UI) → server 子进程 pipeline/search_eval.py → search_process / search_tools(方向分表)
选帖解构(UI) → server 子进程 pipeline/{procedure,tool}_extract.py → mode_process / mode_tools
Dashboard    → /api/dashboard 实时聚合四表(内容树覆盖按 steps 的 action×type 命中有效节点)
```

解构按版本(`v_MMDDHHMM`)保留历史:同版本重跑幂等覆盖,跨版本共存,前端版本下拉可回看。
`cost_usd` / `duration_s` 记录每次解构调用;同一 `(case_id, version)` 的多行重复存同一值,
聚合统计时按该键去重(见 `server.py:_dashboard` 的 `cost_groups`)。

**解构前按 case 全局去重(省钱):** `case_id` 是帖子物理身份,与 query 无关。同一帖被多个
query 搜到时只真实解构一次——`pipeline/{procedure,tool}_extract.py` 在调 LLM 前先查
`db.latest_real_version(case_id)`,已解构过的帖跨 query 用 `db.link_process` 复制 `link_*`
行补齐关联(`cost=0`),不再付费重跑。换 prompt/模型要对比时传 `--force`(API `force:true`)
跳过去重。`runs/backfill_links.py` 是事后扫尾工具,复用同一 `link_process`。

## 知识导入(工序上传）

把 DB 中**已采纳**的工序解构导入到知识接口(`/api/v1/knowledge/ingest`)。数据来源是
`mode_process`(每 case 取最新版本),不读本地文件——`db.fetch_adopted_process_cases()`
把工序解构与 `search_process` 评估 JOIN,用 `is_adopted_rel`(相关性<4 / 超两年 / 综合分<6
任一即不采纳)过滤;每个 procedure 组装一条知识,字段映射与
`Downloads/import/how_process_knowledge/main.py` 一致(steps→scopes/custom_ext)。

```bash
python import_process_knowledge.py --dry-run            # 只取数+组装 payload,不调接口(先验证)
python import_process_knowledge.py --dry-run -v         # 同上,打印完整 payload JSON
python import_process_knowledge.py --query-id q0001     # 只传某搜索任务下的采纳 case
python import_process_knowledge.py --limit 5            # 只处理前 5 个 case(调试)
python import_process_knowledge.py                      # 真实导入(去掉 --dry-run)
# 其它:--api-url <根地址>(默认 47.236.83.130:8001)  --delay <毫秒>(调用间隔,默认 100)
```

## 与旧 search_eval 的关系

取代 `fixed_query_eval`(8770)+ `mode_procedure`(8771)两套服务的"搜索评估 + 大模型解构"
部分;procedure-dsl 执行引擎、mode-dsl 模式提取、A/B/C 三形式对比未迁移(按设计裁剪)。