WorkBuddy 进阶教程捕获工具

把任意来源的 WorkBuddy 进阶教程抽取成「干净 markdown（只留正文 + 正文配图）」，再导入到 IMA 知识库。已封装成一键可用流程，配套 upload_cos.py 上传脚本。

功能特色

多来源适配：腾讯云开发者社区（SPA / ProseMirror JSON）、CSDN、搜狐、位置服务、微信公众号，各有定制抽图去噪策略。
纯净入库：只保留文章正文与正文配图，剔除导航 / 广告 / 侧边栏 / 相关推荐等网页噪声。
外链配图友好：IMA 解析后会保留 ![](url) 语法，正文配图用外链即可渲染，无需二次上传。
安全护栏：临时 COS 凭证用完即删；内置「先核对、不重复导入」逻辑，规避 IMA 无删除接口导致的重复条目。
可定时：配合自动化可每周巡检新教程、自动补库。

何时使用

用户要把多篇文章 / 教程 / 文档导入 IMA 知识库
用户要求「只保留文章内容，去掉网页噪声」后入库
需要定期（每周 / 每月）巡检新文章并补进 IMA 知识库
已知 IMA 没有删除接口，重传前必须核对避免重复

关键约束（必读）

IMA MCP 没有删除 / 移除接口 —— 删除知识库条目只能在 IMA 客户端手动操作。任何重传前都要先 get_knowledge_list 核对现有条目，避免产生重复。
IMA MCP 没有「直接贴文本」接口 —— 只能通过 create_media 拿到临时 COS 凭证 → 把文件 PUT 到腾讯云 COS → add_knowledge 注册。
IMA 解析后会保留 ![](url) 外链图片语法（已实测验证：用 fetch_media_content 能取到完整 ![](https://...)），所以正文配图用外链即可在 IMA 阅读器正常渲染，无需把图下载后重新上传。
临时 COS 凭证含 secret_id/secret_key/token，用完即删（rm cred_*.json），禁止留存到磁盘或提交。
凭证有效期约 12 小时，同一批任务里每篇都要单独 create_media 拿各自凭证，不要复用旧凭证 / 旧 cos_key。

入库链路（create_media → COS → add_knowledge）

create_media：参数 knowledge_base_id、file_name、file_size（必须与实际字节数一致，超上限会被拒）、file_ext:"md"、content_type:"text/markdown"。返回 media_id（形如 markdown_xxx_yyy）和 cos_credential（含 region/bucket/cos_key/secret_id/secret_key/token）。

把 .md 字节 PUT 到 COS（用隔离 venv 里的 qcloud_cos，脚本见本目录 upload_cos.py）：

# upload_cos.py  <cred_json>
import json, sys
from qcloud_cos import CosConfig, CosS3Client
cfg = json.load(open(sys.argv[1], encoding="utf-8"))
cred = cfg["cos_credential"]
config = CosConfig(Region=cred["region"], SecretId=cred["secret_id"],
                   SecretKey=cred["secret_key"], Token=cred["token"])
client = CosS3Client(config)
client.put_object(Bucket=cred["bucket_name"],
                  Body=open(cfg["file_path"], "rb"),
                  Key=cred["cos_key"], EnableMD5=False)
print("uploaded", cfg["file_path"])

安装：python -m pip install --no-cache-dir cos-python-sdk-v5（沙箱里加 --no-cache-dir 避免回收站不可用报错 SAFE_DELETE_FAIL_CLOSED）。
多文件批量：每篇各自 create_media → 写 cred_NN.json（含 file_path）→ 逐个 upload_cos.py cred_NN.json。

add_knowledge：参数 knowledge_base_id + media_id。注册后 IMA 异步解析，通常 1~3 分钟，状态看 media_state:2 / parse_progress:100 表示完成（用 get_knowledge_list 轮询）。
复核：get_knowledge_list(limit=50) 确认 knowledge_total_size 与每条 media_state。
清理：删除临时 cred_*.json。

文章净化与配图保留（按来源）

腾讯云开发者社区（cloud.tencent.com/developer/article/<ID>）：React SPA，正文在 <script id="__NEXT_DATA__"> 的 fallback[...].articleInfo.content，可能是纯 markdown 字符串（直接可用）也可能是 ProseMirror JSON。
- 抽图：正则 https?://[^"\\]+?\.(?:png|jpe?g|gif|webp)；若 content 里图是 {"src":"..."} 形式，转成 ![](src)。
- 注意：封面 pic 字段、栏目图标、促销 banner 不算正文配图，别误把噪声当图带进来（往往 7 张图里只有 0~3 张是正文图）。
- 解析器要点：find_content 要递归到 articleInfo.content，不要只找顶层 type:doc。
CSDN / mcp.csdn.net / lbs.qq.com / sohu.com：用 trafilatura.extract(html, include_images=True, output_format="markdown")，先 requests.get(url, headers=H, timeout=30) 取 HTML 再 extract。include_images=True 才会保留 ![](url)。
微信公众号（搜狗镜像 / mp.weixin.qq.com）：trafilatura 常返回空（反爬）。改走 fetch_media_content（IMA 工具）或 WebFetch 取纯文本后手写 .md。其图床 mmbiz.qpic.cn 签名易过期、防盗链，重传后大概率不显示，可放弃补图。
去噪原则：只留文章正文（标题 / 段落 / 列表 / 代码 / 正文配图）。导航、广告、侧边栏、相关推荐、封面图（除非用户明确要）属噪声，剔除。用户说「只留文章内容」时尤其严格。

标准流程

get_knowledge_list 确认目标 kb 当前条目（避免重复）。
抽取每篇净化 .md（保留真实正文配图，先验证图链 HEAD 返回 200）。
逐篇 create_media → 写 cred_NN.json → upload_cos.py cred_NN.json → add_knowledge。
等待解析，用 get_knowledge_list 复核 media_state。
删除临时 cred_*.json。
若库内出现重复（无删除 API），提示用户在 IMA 客户端手动删旧版。

配套文件

upload_cos.py：把 .md 按 create_media 返回的 cos_credential 上传到腾讯云 COS，供 add_knowledge 入库前调用。

已知坑

trafilatura.fetch_url(timeout=...) 不支持 timeout 参数 → 用 requests.get 取 HTML 再 trafilatura.extract(html)。
腾讯云 SPA 无服务端渲染 .markdown-body → 别用 bs4 找正文，直接解析 __NEXT_DATA__。
pip 在沙箱因回收站不可用报 OSError [SAFE_DELETE_FAIL_CLOSED] → 加 --no-cache-dir。
各文章正文配图数量差异极大（有的 0 张、有的 45 张），别假设每篇都有图；用脚本先枚举真实配图再决定补不补。
re.sub 的替换函数收到的是 Match 对象不是字符串，注意 m.group(0)。

探针验证法（首次对某 kb 用图时）

先只重传 1 篇图最多 / 最典型的文章，等解析后用 fetch_media_content 拉全文，确认 ![](url) 语法被完整保留、图能渲染，再批量铺开其余篇，避免白干。