Zhao 内容采集器（独立采集脚手架）

Overview

本 skill 提供一套独立、可复用的 L1 外部内容采集脚手架：接收输入（URL / 本地文件 / 粘贴文本）→ 路由到对应平台适配器 → 抓取内容 → 转成 markdown → 写入 frontmatter → 落盘到 raw/。核心定位是纯采集搬运：只做「抓取 + 转 md + 落盘 + 写元数据」，不做任何下游加工。

脚手架位于 scripts/collector-template/，复制即可运行。已内置 7 类适配器，覆盖主流内容形态。

When to use

需要为某个软件 / 项目搭建「抓网页/文章/文件 → 存成结构化 md」的采集能力
要求采集程序独立运行、不依赖大模型、不接入 IMA、不实现 MCP server
要快速新增一个平台的适配器（如微博、B 站、微信公众号）
需要本地 PDF 转 md、图片 OCR 转 md、视频语音转写（ASR）等离线内容抽取

不适用：需要 LLM 摘要 / 知识图谱构建 / 自动蒸馏的下游流程（本脚手架明确不做）。

Quick Start（初始化脚手架）

将模板复制到目标软件的项目目录，即可获得一份独立可跑的采集程序：

# 复制脚手架到你的项目（自定目录名，如 my-collector/）
cp -r scripts/collector-template/ /path/to/my-collector/
cd /path/to/my-collector
pip install -r requirements.txt

运行示例：

# 采集单个网页
python collector.py collect --url "https://www.toutiao.com/article/xxxx/"

# 采集本地文件（md / 代码 / pdf / 图片 / 视频 → md）
python collector.py collect --file note.md
python collector.py collect --file slide.pdf
python collector.py collect --file photo.png
python collector.py collect --file lecture.mp4

# 批量采集（文件里每行一个 URL）
python collector.py collect --batch urls.txt

# 粘贴文本
python collector.py collect --text "今天想到的结论…"

输出目录参数化（多软件复用）

每个软件应拥有独立的落盘目录，互不干扰。三种方式（优先级从低到高）：

默认：脚手架目录下的 ./raw/
环境变量：COLLECTOR_OUTPUT_DIR=/path/to/raw
命令行（最高优先）：python collector.py collect --outdir /path/to/raw

Cookie 目录同理可用 COLLECTOR_COOKIES_DIR 覆盖。

落盘文件命名 raw-<uuid16>.md，内容结构：

---
id: raw-xxxxxxxxxxxxxxxx
status: pending
software_identity: 今日头条
timestamp: 2026-08-12T16:12:13
sensitivity: private
source_url: https://...
source_links: []
---

# 文章标题
整篇正文…

适配器模式（新增平台）

核心是可插拔适配器。每个适配器只需实现两件事：

matches(item) → 是否接这个输入
handle(item) → 返回 CollectResult(markdown, title, source_links)

新增适配器步骤

在 adapters/ 下新建 xxx.py，实现 BaseAdapter 子类
在 collector.py 的 ADAPTERS 列表注册（平台适配器放通用 URL 之前）
在 adapters/__init__ 或 collector.py 导入

适配器骨架：

# adapters/weibo.py
from adapters.base import AdapterError, BaseAdapter, CollectResult
# 强反爬平台用 Playwright 渲染：from adapters._browser import render_html

class WeiboAdapter(BaseAdapter):
    identity = "weibo"          # 内部键（英文，用于 cookie 文件名）
    software_name = "微博"       # 写入 frontmatter 的中文来源名

    def matches(self, item) -> bool:
        return item.kind == "url" and "weibo.com" in item.value

    def handle(self, item) -> CollectResult:
        # 1) 抓取内容（requests / Playwright / 平台 API）
        # 2) 转成 markdown（整篇，不截断、不摘要）
        # 3) 顺手抽取正文里的超链接作为 source_links
        md, title, links = "...", "...", []
        return CollectResult(markdown=md, title=title, source_links=links)

frontmatter 中的 software_identity 取 software_name（中文平台名）；identity（英文）仅用于内部键与 cookie 文件名，二者解耦，避免 cookies/微博.json 这类耦合。

强反爬平台的两种打法

普通反爬（如知乎、今日头条）：优先用 requests + 移动端 UA，并从页面内嵌 JSON 解析正文；失败再降级。
强反爬（如小红书、抖音）：用 adapters/_browser.py 的 render_html() 启动无头 Chromium 渲染后再抽 DOM。需 pip install playwright && playwright install chromium。
登录墙站点：在 cookies/ 放 cookies/<identity>.json（Playwright add_cookies 格式），或运行期 --cookies file.json 注入登录态。获取 Cookie 由使用者自行负责。

Frontmatter 契约（七字段）

| 字段 | 说明 | |---|---| | id | raw-<uuid16>，稳定唯一 | | status: pending | 标记未加工，下游消费用 | | software_identity | 来源平台中文名（今日头条 / 知乎 / 小红书 / 抖音 / 通用网页 / 本地文件 / 粘贴文本） | | timestamp | 摄入时间 ISO | | sensitivity: private | 采集默认 private，不做敏感识别 | | source_url | 被采对象出处（URL 或本地文件路径）；粘贴文本省略 | | source_links | 正文里顺手抽到的超链接候选（可选，可为 []） |

越界红线（本脚手架的核心边界）

采集程序只做搬运，以下全部不做，新增适配器时务必遵守：

❌ 不调用 LLM / 不摘要 / 不改写正文
❌ 不接入 IMA、不做 MCP server
❌ 不评级 / 不判域 / 不敏感词识别
❌ 不建知识图谱 / 不蒸馏

保存整篇原文，不截断。失败项不阻塞其余采集（采集核心聚合失败并继续）。

已知限制

反爬 / 登录墙：小红书、抖音无登录态时返回登录墙；需注入 Cookie（见上）。
图片懒加载：部分站点图片是动态图，适配器可能只抽到占位符，未取真实图。
视频 ASR 精度：默认 tiny 模型（快、偶有音近字误差），设 VIDEO_ASR_MODEL=base 提升精度（需模型已缓存）。
依赖体积：playwright（浏览器渲染）、openai-whisper（语音转写）、rapidocr-onnxruntime（图片 OCR）按需安装，非全部必需。

Resources

scripts/collector-template/ — 完整可运行脚手架（collector.py + adapters/ + config.py + requirements.txt）
references/需求规格.md — 原始需求规格 v1.0（边界、frontmatter 定义、DoD）
references/开发说明文档.md — 详细设计（目录结构、适配器清单、Cookie 注入、范围决定追溯表）
references/开发分级与流程.md — 能力分级与实现进度（T0–T5 + 本地文件形态）