Agent/examples/mode_workflow

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

MySQL 四表(search_process / search_tools / mode_process / mode_tools)为唯一事实源的单页工作台: Dashboard(结果/过程指标可视化)、Dataset(query → 帖子 → 工序/工具解构)、聚类库(占位)。 顶栏「Query 规则」按内容树维度铺词 → Sonnet 评分 → 高亮达标组合 → 一键搜(见下「Query 规则组织器」)。

设计文档:docs/superpowers/specs/2026-06-12-mode-workflow-design.md、 docs/superpowers/specs/2026-06-18-query-builder-design.md(Query 规则 + 端到端管线)

启动

# 0. 前置:.env 配 MYSQL_* 与 OPEN_ROUTER_API_KEY;pip install -e .
python db.py init             # 建四张表(幂等);db.py clear 清空数据
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;Query 规则接口 query_matrix/category_tree/query_score
index.html	单文件前端:Dashboard / Dataset / 聚类库 / Query 规则弹层
stages/search_eval.py	任意 query 搜索+评估 → search_process / search_tools(按解构方向分表)
stages/procedure_extract.py	工序解构(LLM 直出)→ mode_process
stages/tool_extract.py	工具解构 → mode_tools
stages/import_process_knowledge.py	已采纳工序(mode_process 最新版)→ 知识导入接口;读 DB 非本地文件,采纳口径同 Dashboard(db.is_adopted_rel)
prompts/	工序/工具解构 system prompt(可单独迭代)
reference/judged_matrix.json	内容树(27 动作×50 类型),Dashboard 覆盖度用
stages/query_score.py	Query 正交格评分:tier≥1 格 × 维度上下文 → Sonnet 打分,结果缓存 .cache/query_score/
prompts/query_score_system.md	评分 system prompt(可单独迭代)
runs/	运行日志与调试副本(gitignore):search / mode_process / mode_tools / logs

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

数据流

Query 规则(UI) → /api/query_score(Sonnet 评 tier≥1 格)→ 高亮达标(keep 且 综合分≥阈值)→ 点格/搜全部达标
新建搜索(UI) → server 子进程 stages/search_eval.py → 统一评估 → 按 知识类型 标签路由
                                                     (工序/能力→search_process,工具→search_tools,两者都含写两表)
选帖解构(UI) → server 子进程 stages/{procedure,tool}_extract.py → mode_process / mode_tools
              (Dataset 工序/工具 tab「解构全部已采纳」一键解构该 query 该方向全部采纳帖)
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 搜到时只真实解构一次——stages/{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。

Query 规则组织器（铺词 → 评分 → 搜索）

顶栏「Query 规则」打开弹层,把"凭直觉拍 query"变成系统化铺词 + LLM 筛选:

• 维度 chips:工具类型/模态/后缀(扁平单选,拼入 query 词)、实质/形式(从 library.aiddit.com 分类树逐级下钻,仅作 Sonnet 领域上下文)、动作/类型(从 judged_matrix 的 l1/l2 下钻,筛选下方表格显示)。
• 正交表:动作 × 类型 整张 27×50(来自 reference/judged_matrix.json),每格 query = [工具类型] 动作叶 类型叶 [模态] [后缀],tier 决定底色。
• 评估高亮:POST /api/query_score 起 stages/query_score.py,对 643 个 tier≥1 格在 当前维度上下文下用 Sonnet 打分(natural/findable/useful + keep + rewrite + reason), 综合分 = natural*0.4 + findable*0.3 + useful*0.3。结果按选择哈希缓存 .cache/query_score/<sel>.json,同选择不重复付费。
• 达标 = keep 且 综合分 ≥ 阈值(弹层可调,默认 7):达标格蓝框高亮 + 角标分数, 点格弹气泡(分数拆解 / 理由 / 发起搜索 / 复制)。
• 发起搜索:点单格 或「搜全部达标」→ POST /api/run_search(默认 xhs,gzh 各 20、 方向无关,落表由评估标签自动路由)。

命令行单独跑评分(不依赖 UI):

python stages/query_score.py --tool-type AI --modality 图片 --suffix 怎么做 --dry-run  # 只拼词,不调 LLM
python stages/query_score.py --tool-type AI --suffix 怎么做 --limit 20 --sel _t        # 小样真评(写 .cache)

外部依赖:library.aiddit.com 的 category-tree 接口(实质/形式),server 端直连 + .cache/category_tree/ 缓存。

知识导入(工序上传）

把 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)。

python stages/import_process_knowledge.py --dry-run            # 只取数+组装 payload,不调接口(先验证)
python stages/import_process_knowledge.py --dry-run -v         # 同上,打印完整 payload JSON
python stages/import_process_knowledge.py --query-id q0001     # 只传某搜索任务下的采纳 case
python stages/import_process_knowledge.py --case-ids xhs_a,gzh_b # 只传指定 case(采纳集内精确补传/重传单帖)
python stages/import_process_knowledge.py --limit 5            # 只处理前 5 个 case(调试)
python stages/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 三形式对比未迁移(按设计裁剪)。