老兵知识采集器

老兵知识采集器（caiji-for-ima）

Overview

教发老兵（李琰辉）经过大量实测，把"按主题批量给知识库某文件夹补文章素材"这件事固化成一条高速流水线：检索 → 筛选 → 编码 → 拆波并行直导 → 核验 → 噪声清理。默认目标"至少 100 篇、越多越好"，全程幂等、不空转。目前实现基于 IMA 知识库（ima.qq.com）+ 搜狗微信检索通道，可直接复用。

适用场景（用户说类似以下即触发）：

• "给【XX 知识库】的【YY 区】补一些关于『主题』的文章，至少 100 篇"
• "把科研误区/方法论/课题申报这类文章转存到我的知识库"
• 任何"按主题给知识库灌文章素材"的需求

核心原则（效率优先，来自实测）

1. 先搜齐筛好落盘，再并行直导——绝不反复重搜、绝不串行 sleep 傻等。
2. 检索收窄词数：40 词 × 2 页 ≈ 3 分钟拿 757 条候选、全程无反爬阻塞；广撒网（50 词）曾卡 39 分钟+，勿取。
3. 导入拆波并行：把批次拆成每波 13 批，每波并行起 1 个子代理各导其波；远优于串行或主 agent 手抄长 URL。
4. 核验以 import_urls 回执 ret_code=0 + media_id 为准，不以 get_knowledge_list 的 total_size 差值（受并发写入干扰、且幂等折叠会让差值偏小）。

Workflow

Step 0 定位目标（必须最先做）

• 用 get_knowledge_base_list 遍历 KBT_MINE_KB / KBT_SHARED_KB / KBT_SUBSCRIBED_JOIN_KB / KBT_SUBSCRIBED_CREATE_KB 四种类型，找到目标知识库（固定 KB 报 222001/222000 时不要止步，可能已改名重建为共享库）。
• 用 get_knowledge_list（knowledge_base_id + folder_id，limit≤50 不带 filter）定位目标文件夹 folder_id。
• 常用基线见 references/ima_kb_api.md。

Step 1 检索（搜狗微信通道）

• 运行 scripts/batch_search.js：把关键词写进一个 txt（一行一词），后台跑。脚本已含反爬换 cookie、增量落盘、2 次重试、每词默认 2 页。
• 关键词策略：每个主题拆 3–5 个同义变体（如"科研误区 / 科研踩坑 / 论文写作常见错误 / 学术写作痛点"），总词数控制在 40 左右。
• 输出：out/all_articles.json（去重后的候选，含 url/title/source/date）。

Step 2 筛选 + 编码 + 分批

• 运行 scripts/filter_topic.py [保留篇数]：
  • 强制标题命中主题词（理论/模型/方法/模板/工具/误区/痛点等，按本次主题调 THEME 表）；
  • 排除广告/中小学/育儿等噪声（JUNK 表）；
  • 内部去重（URL + 标题近似 >0.72）；
  • URL 统一 quote() 编码——这一步挡掉 220001 的裸空格坑；
  • 输出 batches.json（每批 ≤10 条，已编码）。

Step 3 拆波

• 运行 scripts/make_waves.py batches.json waves：拆成 waves/wave_1..N.json，每波 13 批。

Step 4 并行直导（关键提速步）

• 并行起 N 个后台子代理，每个子代理只读自己的 waves/wave_K.json，顺序调用 import_urls： {"knowledge_base_id":"","folder_id":"","urls":[该波 urls]}，URL 原样传。
• 子代理要点：每批间 sleep 0.5s；整批报 220001/429 原样重试一次（间隔 2s）；导入幂等，重试安全。
• 不要在主上下文里手抄长 URL——子代理 Read 自己的波次文件不会截断。
• ⚠️ folder_id 务必逐字节核对（曾因手滑把 ...7754 写成 ...7554 报 222000，浪费一轮）。

Step 5 核验 + 噪声清理

• 用 get_knowledge_list 翻目标文件夹前几页，确认 total_size 增长、create_time 为本轮、标题主题命中。
• 混入的"搜狗搜索"验证码页 / 广告软文：IMA 无删除 API，只能枚举其 media_id（按 parent_folder_id + 导入时间窗锁定）交用户在 IMA 界面手动清。噪声清理清单模板见 references/pitfalls.md。

坑点速查

• 220001：先查 URL 是否含裸空格 → 替换 %20 重试；瞬时失败概率也不低，单条重试常成功。
• 幂等：同 URL 重复导同一文件夹折叠为同一条，不产生重复项——去重可放宽，重试安全。
• search_knowledge 的 folder_id 不生效：返回全库命中，需按 parent_folder_id 二次过滤。
• get_knowledge_list limit≤50：传 100/200 报错；folder 的 media_type=99，别用 filter 过滤。
• IMA 无删除/移动接口：放错库或脏数据只能用户在 UI 手动处理。

详细工具签名与 ID 基线见 references/ima_kb_api.md；反爬与效率复盘见 references/pitfalls.md。