docs(examples/mode_workflow): 新增mode工作流命令行执行手册

该手册为mode_workflow示例项目的命令行执行手册，以q0020任务为例，详细说明了绕过UI直接执行「搜索→评估→工序解构→上传知识库」完整流程的步骤、常用参数、排查命令与成本时间参考。

examples/mode_workflow/流程执行手册.md

@@ -0,0 +1,182 @@
+# mode_workflow 流程执行手册
+
+手动跑「搜索 → 评估 → 工序解构 → 上传知识库」四步的命令清单。
+以一次真实任务(query `q0020`「人物 姿势 精准控制 怎么做」)为例。
+
+> 这些脚本平时由 `server.py` 起子进程调用(点 UI 按钮);本手册是**绕过 UI、直接命令行跑**的等价方式。
+
+---
+
+## 0. 前置
+
+```bash
+# 1) 进项目目录(所有命令都在这里跑)
+cd /Users/max_liu/max_liu/company/Agent/examples/mode_workflow
+
+# 2) 用哪个 python:本手册用 python3(已验证能 import 整条链路)。
+#    若 python3 不是项目环境,就用启动 server.py 的同一个 python(conda base 的 python)。
+```
+
+约定:
+- **渠道代码**:`xhs` = 小红书,`gzh` = 公众号(还有 `sph` 视频号、`douyin`、`zhihu` 等,以支持搜索的为准)。
+- **方向**:`工序`(怎么做/流程)写 `search_process` / `mode_process`;`工具`(测评/工具)写 `search_tools` / `mode_tools`。本手册走**工序**。
+- 脚本基本都带 `-h`,记不清参数时 `python3 pipeline/xxx.py -h`。
+
+---
+
+## 步骤 1 + 2:新建 query + 搜索评估
+
+「新建 query」不需要单独建表 —— **query 列表是从搜索结果表里派生的**,所以跑一次搜索(用一个新的 `query_id`)就等于新增了一个 query。
+
+### 1) 先拿到下一个 query_id
+
+```bash
+python3 -c "import server; print(server._next_query_id())"
+# 例如输出:q0020
+```
+
+### 2) 跑搜索 + 评估
+
+```bash
+python3 pipeline/search_eval.py \
+  --query-id q0020 \
+  --query "人物 姿势 精准控制 怎么做" \
+  --mode-type 工序 \
+  --platforms xhs,gzh \
+  --max-count 20
+```
+
+要点:
+- `--max-count` 是**每个渠道**的条数(按 `平台 × query` 算)。`xhs,gzh` + `20` ≈ 每渠道 20、共最多 40 帖。
+- 想各渠道不同数量:`--platforms xhs:30,gzh:10`(冒号后覆盖该渠道,未写的用 `--max-count`)。
+- 同义措辞(扩大召回):`--synonyms "人物动作控制,姿势控制 AI"`。
+- 评估会调多模态大模型逐帖打分,**有成本**(本例 30 帖约 $0.10)。
+
+常用可选项:
+| 参数 | 作用 |
+|---|---|
+| `--eval-model <id>` | 换评估模型 |
+| `--escalate-model <id>` | 模糊带帖子交强模型复核(如 sonnet) |
+| `--no-images` | 不发配图,纯文本评估(更省、但更糙) |
+| `--force-eval` | **跳过评估去重**,所有帖都走完整评估 |
+
+> **评估去重(默认开)**:某帖若在别的 query 已评过,会**复用质量/通用相关/时效分,只用一次轻量纯文本调用重算「和 query 相关」分**,不再跑整套多模态评估,省钱。换 prompt/模型做对比时才加 `--force-eval`。
+
+---
+
+## 步骤 3:对「已采纳」的帖子做工序解构
+
+### 1) 取出该 query 下已采纳的 case_id
+
+```bash
+# 直接打印(逗号分隔),核对数量
+python3 -c "import db; cs=[p['case_id'] for p in db.fetch_posts('q0020','process') if p.get('adopted')]; print(len(cs),'个'); print(','.join(cs))"
+```
+
+```bash
+# 存进 shell 变量,供下一步直接用
+CIDS=$(python3 -c "import db; print(','.join(p['case_id'] for p in db.fetch_posts('q0020','process') if p.get('adopted')))")
+echo "$CIDS"
+```
+
+### 2) 跑工序解构
+
+```bash
+python3 pipeline/procedure_extract.py \
+  --query-id q0020 \
+  --case-ids "$CIDS"
+```
+
+要点:
+- 默认模型 `anthropic/claude-sonnet-4-6`,换模型 `--model google/gemini-3.1-flash-lite`。
+- **token 重、串行跑**,19 帖大约十几分钟、约 $2;耐心等。
+- `--no-images` 不发配图;`--max-images N` 调每帖配图上限(默认 8)。
+
+> **解构去重(默认开)**:某 case 若**已真实解构过**(任意 query),不会再调大模型 —— 同 query 直接跳过,跨 query 用 `link_*` 复制补齐关联(成本 $0)。要换 prompt/模型重解构才加 `--force`。
+
+> 工具方向同理,换脚本:`python3 pipeline/tool_extract.py --query-id q0020 --case-ids "$CIDS"`(需先有 `search_tools` 数据)。
+
+---
+
+## 步骤 4:上传知识库
+
+把该 query 下**已采纳且已工序解构**的帖子,每个工序作为一条知识推到接口
+`http://47.236.83.130:8001/api/v1/knowledge/ingest`。
+
+### 1) 先 dry-run 看条数(不真传)
+
+```bash
+python3 import_process_knowledge.py --query-id q0020 --dry-run
+# 看「发现 N 个采纳 case … 合计导入 M」,确认范围对
+```
+
+### 2) 真实上传
+
+```bash
+python3 import_process_knowledge.py --query-id q0020
+```
+
+要点:
+- **上传去重(默认开,DB 台账)**:每条知识按 `case_id + 工序序号` 记台账,**已传过且版本未变的自动跳过**。所以:
+  - 上传中途有失败(如超时)→ 失败的没记台账,**直接重跑命令**即可只补传失败的、跳过已成功的。
+  - 重新解构过(版本变了)→ 重跑会自动重传更新那几条。
+- `--query-id` 不写 = 全量采纳 case(慎用,先 dry-run 看量)。
+- `--limit N` 只处理前 N 个 case(调试)。
+- `--force` 忽略台账强制全量重传。
+- `--delay <毫秒>` 调每条间隔(默认 100);`--api-url <根地址>` 换后端。
+
+---
+
+## 一键串联(步骤 2→3→4,同一个 query)
+
+```bash
+cd /Users/max_liu/max_liu/company/Agent/examples/mode_workflow
+QID=q0021                                   # 用步骤1的 _next_query_id() 拿到的新号
+QUERY="你的检索词 怎么做"
+
+# 2) 搜索+评估
+python3 pipeline/search_eval.py --query-id "$QID" --query "$QUERY" \
+  --mode-type 工序 --platforms xhs,gzh --max-count 20
+
+# 3) 取采纳 → 工序解构
+CIDS=$(python3 -c "import db; print(','.join(p['case_id'] for p in db.fetch_posts('$QID','process') if p.get('adopted')))")
+[ -n "$CIDS" ] && python3 pipeline/procedure_extract.py --query-id "$QID" --case-ids "$CIDS"
+
+# 4) 上传(先 dry-run 再真传)
+python3 import_process_knowledge.py --query-id "$QID" --dry-run
+python3 import_process_knowledge.py --query-id "$QID"
+```
+
+> 每步都是**前台阻塞**跑,跑完再跑下一步,日志直接打在终端。
+> 想后台跑长任务:`nohup python3 … > 某日志.log 2>&1 &`,再 `tail -f 某日志.log` 看进度
+> (注意 Python 重定向到文件时输出是缓冲的,逐条结果可能跑完才一次性刷出来)。
+
+---
+
+## 常用查询 / 排查
+
+```bash
+# 某 query 的总数 / 采纳数 / 已解构数
+python3 -c "import db; ps=db.fetch_posts('q0020','process'); print('总',len(ps),'采纳',sum(p['adopted'] for p in ps),'已解构',sum(p['has_process'] for p in ps))"
+
+# 看某 case 的解构版本
+python3 -c "import db; print(db.fetch_process_versions('gzh_xxx'))"
+
+# 看四表行数
+python3 db.py check
+
+# 某 query 已上传知识库的台账条数
+python3 -c "import db; c=db._conn(); cur=c.cursor(); cur.execute(\"SELECT COUNT(*) n FROM knowledge_ingest_log WHERE case_id IN (SELECT DISTINCT case_id FROM mode_process WHERE query_id='q0020')\"); print(cur.fetchone()); c.close()"
+```
+
+---
+
+## 成本与时间参考(以 q0020 / 19 帖为例)
+
+| 步骤 | 时间 | 成本 |
+|---|---|---|
+| 搜索+评估(30 帖) | ~1–2 分钟 | ~$0.10 |
+| 工序解构(19 帖,串行) | ~15 分钟 | ~$2.05 |
+| 上传知识库(51 条) | ~1–2 分钟 | 不计费 |
+
+> 数量越多、配图越多越贵越慢。去重(评估/解构/上传三处默认都开)会让**重复跑同一批基本不花钱**。