Sites to IMA

sites_to_ima

运行环境：本 skill 依赖 ima.copilot（腾讯智能工作台）平台能力（push_note / import_urls / ima_cos_util 等 OpenAPI 与沙箱命令），需在 ima.copilot 环境中使用，非独立运行工具。

网站内容批量标记入库：全量抓取指定网站的内容列表（遍历"加载更多"/分页），导出 xlsx/csv 表格，建立 ima 分类索引笔记体系并批量导入知识库，最后生成可复用的增量更新手册。

适用边界

触发：用户说"标记网站 XX"、"爬取 XX 网站入库"、"把 XX 建成分类索引"、"抓取 XX 全量内容列表"、"更新 marksites 站点 XX"。

不适用：单篇文章的抓取与阅读、非网站类数据处理、纯知识库管理（用 ima-knowledge）。

核心概念：双轨笔记模型（源自 PR Daily 实战体系）

为什么双轨：统一更新笔记收录的是"实际导入 KB 的文章"（初次约 180 篇，保持轻量可打开）；独立分类笔记是全量目录（大站可能数千行，客户端打不开也保留为历史归档/目录指引，标题可加 (建议绕过) 前缀提示）。两者用途不同，不可合并。

核心概念：本地进度底座 progress.json（增量更新第一信源 + 记忆兜底）

每站点维护一个本地进度文件 output/{site}_progress.json，解决两个问题：①用户说"pr daily 更新"等关键词时，不依赖读取 ima 笔记即可锁定站点与进度；②会话记忆重置后，进度记录仍有本地文件兜底。

{
  "site": "PR Daily",
  "domain": "prdaily.com",
  "keywords": ["pr daily", "prdaily"],
  "last_fetch": "YYYY-MM-DD",
  "notebook_folder_id": "笔记本ID",
  "manual_note_id": "更新手册笔记ID",
  "unified_note": {"note_id": "统一更新笔记ID", "last_seq": 0},
  "categories": {
    "{分类名}": {
      "slug": "{WP分类slug或入口标识}",
      "index_note": {"note_id": "...", "last_date": "YYYY-MM-DD", "total": 0, "last_seq": 0},
      "kb_import": {"folder_id": "...", "last_date": "YYYY-MM-DD", "total": 0}
    }
  }
}

字段语义（双轨进度分开记录，与双轨笔记模型一一对应）：

• keywords：站点识别关键词（小写；含站名常用叫法与去空格变体），用户说"更新 XX"时做包含匹配
• index_note.last_date / total / last_seq：索引进度--该类独立索引笔记已收录的最新文章发布日期 / 累计篇数 / 最后序号（序号供追加续编）
• unified_note.note_id / last_seq：统一更新笔记定位与全局序号（全站一篇，跨类全局续编）
• kb_import.last_date / total：导入进度--知识库该类文件夹已导入的最新文章日期 / 累计篇数（全量目录与实际导入量不同，必须分开记）
• last_fetch：最近一次执行增量更新的日期

笔记获取方式（note_id 优先，标题兜底）：所有笔记（索引/统一更新/手册）一律按 progress.json 记录的 note_id 直接定位（export_note / push_note 直用）；note_id 失效或文件中缺失时，按标题搜索兜底：【{站点}·分类索引】{分类名} /【{站点}·分类索引·更新】/【{站点}·更新手册】，找到后回填 progress.json。禁止每次更新都靠标题搜索定位笔记（慢且可能误中同名笔记）。

双源策略：本地 progress.json 为第一信源（每次执行后必同步）；【{站点}·更新手册】笔记为兜底（本地文件丢失时按手册的 note_id/folder_id/最新抓取日期恢复重建 progress.json）。

硬性规则（违反任何一条不得继续）

1. 录入前置确认门（触发时机：收到用户"标记/爬取/索引 XX 站点"请求后的第一个动作，先于一切探测、抓取、查找知识库/笔记本的操作）：必须先从用户处获得 ①目标知识库 kb_id（或名称）+ 目标文件夹（名称或 folder_id）--文章导入的归宿，核心必问项 ②笔记的目标笔记本（名称或 folder_id）--索引笔记/更新笔记/手册的归宿。任一缺失时，明确向用户索要，不得录入，也不得开始探测。
   • 目标笔记本未设立的提醒规则：用户可能还没有专门的目标笔记本（很多人只建了知识库）。索要时若用户表示没有或不确定，必须主动提醒并建议由助手代建：推荐以站点主题命名（如"Marketing""PR 资讯"），经用户同意后 add_notebook 创建，再继续流程；用户拒绝代建时请用户自行建好后再来。禁止在无目标笔记本的情况下把笔记散落写入默认位置。
   • 索要话术："请提供：①要导入的目标知识库名称及目标文件夹 ②存放笔记的目标笔记本（如果还没建，我可以帮你新建一个，告诉我名字就行）。"
2. 首次执行确认门：首次对某站点执行前，必须向用户展示【首次执行确认模板】（见下），获用户明确确认后才能开始。用户调整要求的，按调整后的执行。
3. 笔记只增不删：ima 笔记 API 无删除能力。写入前必须严格遵循现有笔记结构（读取 references/note-formats.md），更新记录一律追加在笔记最底部，序号全局续编。绝不尝试删除/改写已有内容。
4. 写入不可逆：import_doc / append_doc / push_note 一经成功无法撤回。任何一次写入前，确认内容已按格式规范生成并本地留档。
5. 导入前置说明门（绝对红线）：任何 import_urls 调用前（包括可行性验证的 1-2 篇试导入），必须已向用户明确说明：①将对该站做全量内容提取 ②初次导入知识库的具体总篇数与各分类分配 ③（强防护站点）试导入可能产生需用户手动删除的残留条目。说明未发出或用户未确认，坚决不得执行任何导入行为，一条都不行。

首次执行确认模板

首次执行（探测完抓取通道、抓到分类清单后、任何导入动作执行前）发送给用户。此模板未发出且未获用户确认前，禁止调用 import_urls（含 1-2 篇试导入）：

【ima_marksites 执行计划确认】{站点名}（{域名}）

■ 抓取通道：{WordPress API / RSS+sitemap / 浏览器遍历 / 平台导入+fetch读取}
■ 检测到 {n} 个分类：
  {分类A}（{数量}篇）｜{分类B}（{数量}篇）｜…

■ 将对该站做**全量提取**，检测到内容共约 {总量} 篇

■ 将建立 {n+2} 篇笔记（笔记本：{目标笔记本名}）：
  1.【{站点}·分类索引】{分类A} 等 {n} 篇——全量目录指引（各类约{行数}行）
  2.【{站点}·分类索引·更新】——正式导入记录（初始约{总导入数}行，带类别列）
  3.【{站点}·更新手册】——增量更新方法

■ 知识库：{KB名} / {目标文件夹} 下新建 {n} 个分类子文件夹
  **初次导入共 {总导入数} 篇**（分配：{分类A} {x}篇、{分类B} {y}篇…）

■ 强防护站点附加说明（仅适用时保留）：验证通道需先试导入 1-2 篇，若平台抓取失败将产生需您手动删除的残留条目

■ 表格文件：output/{site}_full.json + 每分类 1 个 xlsx（序号/发布日期/标题/摘要/URL，序号与索引笔记一一对应）

■ 预计耗时：抓取约{X}分钟｜KB 导入+复核约{Y}分钟｜笔记写入约{Z}分钟｜合计约{T}

■ 注意：独立目录笔记为全量收录，大站单篇可能数千行，客户端或有打不开的情况（仍保留为目录指引，助手可读）。

确认开始？（回复"确认"，或直接说要调整的地方）

耗时估算基准：API 抓取每千篇约 2-5 分钟；浏览器抓取每页 3-8 秒；KB 导入每 10 篇约 3 秒调用 + 全部导完等 20 秒复核，180 篇约 5 分钟；笔记写入每千行约 5 分钟（分批追加）。

执行流程

第 0 步：站点可行性判定（哪些网站无法提取与导入）

先判定可行性，再动手抓取。以下类型站点全通道不可行，应立即向用户摊牌，勿换库反复试错。

不可抓取站点类型（2026-08 实测）

已知不可抓取站点黑名单：marketingweek.com（2026-08-15 全通道实测失败，含平台导入）。

可行性探测流程（总时间盒 20 分钟，超时即摊牌）

1. curl 带 UA 测 WP API / RSS / sitemap（3 分钟内）：全部 403 -> 下一步。
2. curl_cffi impersonate=chrome 测首页（2 分钟）：仍 403 且响应含 "Just a moment" -> 判定 CF 强防护，进入第 3 步；否则按正常降级流程走。
3. 平台通道验证（唯一还有希望的通道，执行前必须获得用户同意）：先向用户说明"该站防护较强，本地通道全灭，唯一方案是试导入 1-2 篇文章验证平台能否抓取，若失败将产生需手动删除的残留条目"，获同意后 import_urls 小批量导入 1-2 个文章 URL，等 5 分钟：
   • 条目标题从 URL 变为文章真实标题、fetch(media_id) 可读 -> 平台能过 CF，全流程改走「平台导入 + fetch 读取」通道，随后照常发【首次执行确认模板】（含全量提取范围与具体导入数量），二次确认后才可批量导入。
   • 仍 "Parsing not completed" 且标题仍为 URL -> 服务端也被挡，判定本站不可抓取，立即停止。
   • 强防护站点采用两段式确认：第一段=试导入风险确认（本步骤），第二段=完整执行计划确认（含数量）。两段都过才能批量导入。
4. 摊牌话术要点：说明防护类型与已试通道、知识库残留需用户手动删、给出替代方案（用户本地浏览器另存列表页 HTML 上传，由助手解析走完整流程）。

强防护站点的两条铁律

1. 禁止在平台通道验证通过前批量 import_urls：服务端摄取失败的条目可能永久卡在"解析中"成为僵尸条目（标题一直显示 URL），IMA API 无删除能力，只能用户客户端手动清理。
2. 探测阶段每换一种库/浏览器最多试 2 种参数，信息不再增长即停，把决策交回用户。

Phase 1 探测抓取通道（按优先级自动降级）

Phase 1 开工前必须先完成上方「第 0 步：站点可行性判定」：命中 Cloudflare 强防护（403 + "Just a moment"）时按该步骤处理，不要进入本 Phase 的常规降级链。

1. WordPress REST API（首选）：请求 {域名}/wp-json/wp/v2/posts?per_page=1，返回 JSON 即命中。用 /wp-json/wp/v2/categories 找分类（用户给的目录链接若含 ?cat= 或分类 slug，对应匹配）。API 只返回文章对象，天然避开导航/侧边栏/相关报道。
2. RSS/Atom + sitemap：/feed/、/sitemap.xml、/post-sitemap*.xml。feed 提供结构与字段样例，sitemap 提供全量 URL（缺日期/摘要时逐篇补抓或留空）。
3. 浏览器兜底（playwright）：前两者都失败时用。打开用户给的目录链接，识别主内容列表区（文章卡片的重复结构：标题链接+日期），排除 header/footer/侧边栏/相关报道区（选择器通常含 nav/sidebar/related/recommended 关键词）。然后循环点击"加载更多/下一页"按钮或滚动加载，直到无新内容，收集全部条目。

用户一次给多个目录链接 = 多个分类；单链接 = 单分类（此时独立分类笔记仍建，命名取链接锚文本或栏目名）。

Phase 2 全量抓取

• API 方式：/wp-json/wp/v2/posts?categories={id}&per_page=100&page=N 翻页至返回空。字段映射：link→URL、title.rendered→标题（去 HTML 标签与实体）、date→发布日期（取 YYYY-MM-DD）、excerpt.rendered→描述（无则留空）。
• 必须带浏览器 User-Agent（裸 requests 会被 Cloudflare 拦成空响应）；被拦则退避重试（间隔 1.5s 递增）。
• 结果按分类存 output/{site}_full.json（结构：{分类名: {items: [{url,title,date,excerpt}]}}），此文件是后续一切操作的数据底座，务必落盘。

Phase 3 导出表格

• 每分类一个文件：output/{site}_{分类名}.xlsx，列=序号｜发布日期｜标题｜摘要｜URL（与索引笔记列序一致；摘要即站点现成的描述/摘要，缺失留空，不猜测）。
• 排序从旧到新，序号每分类内从 1 递增，与该分类独立索引笔记的序号一一对应，便于文件与笔记互相核对。
• xlsx 用 openpyxl；安装失败自动降级 csv（同列）。文件路径在完成汇报中告知用户。

Phase 4 建立笔记体系

格式细节（标题行/元信息块/表列/追加小节/更新记录沉底）必须先读 references/note-formats.md，按模板生成。要点：

• 全部表格内容含 |，直接走 API JSON body 会触发 WAF。写入路径：Markdown 写 .md 文件 → ima_cos_util -f 上传拿 cosKey → push_note（新建不传 note_id / 追加传 note_id + content_cos_key）。长笔记（>1000 行）分批追加，每批 ≤1000 行。
• 独立分类笔记：全量收录，从旧到新，序号 1 起。
• 统一更新笔记：初始收录 = 各类初次导入 KB 的那批文章（约 180 篇），多「类别」列，全局从旧到新、序号全局递增。
• 完成后用 export_note 下载原文核验行数（fetch 对长笔记会降级返回加工摘要，不可信）。

Phase 5 知识库导入

**前置条件：硬性规则第 5 条（导入前置说明门）与首次执行确认门均已通过。**未向用户说明具体导入数量并获确认，不得执行本 Phase。

• 初次导入总量约 180 篇，平均分配到各分类，每类数量取整十。分配算法：per = round(180/n) 取整到十（不足 10 按 10），余数按 +10 依序补给前面的分类。示例：6 类=30×6；5 类=40,40,40,30,30；4 类=50,50,40,40；3 类=60×3。每类取最新发布的 X 篇。
• 在目标文件夹下为每类 create_folder 建子文件夹（命名=分类名），然后 import_urls 导入（≤10 URL/批，批间 1.5s）。
• import_urls 返回成功是乐观的：个别源页面后台异步摄取失败会删条目、计数回弹。全部导完后等 20 秒，用 get_knowledge_list 复核各类实际条目数；不足则从该类更早文章继续补，直到达标或候选耗尽（如实告知用户）。
• 摄取失败不一定回弹，也可能永久卡死：强防护站点的条目会一直停在"解析中"（标题始终显示 URL）且无法用 API 删除。首次导入任何新站点，必须先小批量导入 1-2 篇验证解析完成（标题变为文章标题）后再批量。超过 5 分钟未解析完成的站点按「站点可行性限制」章节判定处理。
• import_urls 自带去重（重导已存在 URL 返回原 media_id），增量更新时无需担心重复。

Phase 6 生成更新手册

按 references/manual-template.md 的七章模板生成【{站点}·更新手册】，写入目标笔记本。手册必须记录：本次实际使用的抓取通道与参数（slug/cat_id 或选择器）、全部笔记 note_id、全部 KB 文件夹 folder_id、最新抓取日期。这些 ID 是下次增量更新的钥匙，缺失会导致下次无法续接。

同时写本地进度底座 output/{site}_progress.json（结构见「核心概念：本地进度底座」）：keywords 取站点常用叫法（含去空格变体），每类填入 index_note（note_id/last_date/total/last_seq=初次收录数）与 kb_import（folder_id/last_date/total=初次导入数），unified_note 填统一更新笔记 note_id 与初始全局序号，顶层 last_fetch 填本次日期。

增量更新模式（用户说"更新 XX 站点/更新知识库"时）

第 1 步：站点识别（关键词匹配，不依赖读笔记）

从用户消息提取站点名（如"pr daily 更新"中的"pr daily"），按顺序匹配：

1. 本地 progress.json 优先：遍历 output/*_progress.json，将提取词与各文件 keywords 做不区分大小写的包含匹配 -> 命中即锁定站点，直接读取其进度（各类 last_date），跳到第 3 步。
2. 多站点同时命中（如"marketing"同时命中 Marketing Brew 与 Marketing Week）：列出候选让用户选择，不得擅自猜测。
3. 本地无匹配 -> 按标题搜索笔记【{XX}·更新手册】，找到则按手册恢复重建 progress.json（见第 2 步）。
4. 都失败 -> 请用户提供站点全名或目录链接。

第 2 步：进度读取（双源策略）

• 第一信源：本地 progress.json（每次执行后同步，含各类双轨进度与续编序号）。
• 兜底：更新手册笔记--本地文件丢失/损坏时，读手册中记录的 note_id / folder_id / 最新抓取日期，重建 progress.json 后继续。
• 两源同时存在且日期不一致时，以较新者为准并向用户说明。

第 3 步：增量抓取与导入

1. 按手册/progress.json 记录的通道，抓取各类 last_date 之后的新文章（API 用 after={日期}T23:59:59）。
2. 新文章导入 KB 对应分类文件夹（import_urls 去重，直接导）。
3. 新文章追加到统一更新笔记（带类别列，序号全局续编）和对应独立分类笔记（序号按 progress.json 的 last_seq 续编）。
4. 各笔记末尾追加更新记录（日期沉底），手册"最新抓取日期"追加新日期。
5. 更新 output/{site}_full.json 数据底座。
6. 增量可能很少甚至为 0（站点更新慢是常态），先用去 after 的最新 15 篇日期分布验证抓取无漏，再向用户如实汇报。

第 4 步：进度回写（每次更新完成必须执行，顺序不可颠倒）

1. 先写本地：更新 progress.json--各类 index_note（last_date/total/last_seq）、unified_note.last_seq、kb_import（last_date/total）、顶层 last_fetch。写失败立即重试一次，仍失败则中止并向用户报告（笔记写入前必须先保住本地进度）。
2. 后写手册：更新手册笔记的"最新抓取日期"。
3. 进度汇报（固定模板，向用户展示）：

【{站点名} 更新完成】本次新增：索引 {X} 篇｜知识库导入 {Y} 篇

| 分类 | 索引收录至 | 索引累计 | 知识库导入至 | 导入累计 |
|---|---|---|---|---|
| {分类A} | {最新文章日期} | {N} 篇 | {最新文章日期} | {M} 篇 |
| ... | | | | |

第 5 步：增量更新检查（强制自检，未通过不得汇报"完成"）

进度回写后立即执行三项校验，任何一项失败都必须如实告知用户并说明缺了什么：

1. 本地进度校验：重新读取 progress.json，核对 ①顶层 last_fetch = 本次执行日期 ②有新增的分类其 index_note.last_date / kb_import.last_date 已前移、total 已增加 ③unified_note.last_seq 等于旧值+本次新增数。任一不符 -> 重写 progress.json 再验一次，仍不符则报告。
2. 笔记落笔校验：export_note 下载统一更新笔记原文，确认尾部存在本次新增行（末行序号 = unified_note.last_seq）；独立索引笔记抽验至少 1 类（挑本次新增最多的类），确认末行序号 = 该类 last_seq。fetch 返回的加工摘要不可作为校验依据。
3. 知识库计数校验：get_knowledge_list 复核有导入的分类，实际条目数 >= 该类 kb_import.total（import_urls 计数回弹时以实际为准回写 total）。

校验全部通过后才允许输出第 4 步的进度汇报表；汇报表末尾附一行：[OK] 进度校验通过（本地/笔记/知识库 三项）。

依赖与环境

pip install requests openpyxl            # 必装
pip install playwright                    # 浏览器兜底通道需要
# 浏览器下载必须走国内镜像，直连必超时：
PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/ playwright install chromium
apt-get install -y --no-install-recommends xvfb   # 有头模式（过 CF 必需）配合 xvfb-run
pip install patchright                    # playwright 反检测 fork，CF 站点备选（安装后同样走镜像装浏览器）

沙箱要点（实测）：

• playwright 优先装进本地 venv 固定路径（uvx 冷启动 monorepo 依赖易超时）。
• playwright install 直连下载必超时，必须设 PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/（镜像约 30 秒装完）。
• 不要用 chromium-headless-shell（旧版无头，指纹特征明显，CF 必拦）；要装完整版 chromium（new headless）。apt 装 chromium 完整包会 OOM(exit 137)，不要尝试。
• apt 报锁占用（前次超时进程残留）：kill -9 ; rm -f /var/lib/dpkg/lock*; dpkg --configure -a 后重试。
• 有头模式运行：xvfb-run -a --server-args="-screen 0 1280x800x24" 。
• 以上全部就位仍过不了强 CF 站点（见「站点可行性限制」），环境配置只解决"能跑"，不解决"能过"。

避坑速查