# dsh-wechat-collector

[English](README.md)

这是一个原生 DSH 公众号采集与博主分析插件：在 DSH 右侧提供「公众号」面板和
Agent 工具，负责扫码登录、公众号管理、文章抓取、DeepSeek 内容方法分析、结果
回看、素材筛选、反馈写回，以及把来源卡交给 ContentStudio。

![DSH 公众号采集面板](assets/dsh-wechat-collector-panel.png)

插件内置的 Python 运行时来自
[`pika-weixin-collection`](https://github.com/bescriptkiddie/pika-weixin-collection)，
发布包只保留运行所需代码，不包含任何微信凭证、历史文章或个人信源配置。

## 安装

当前正在等待精选市场目录收录。收录前可以直接从公开 GitHub 仓库安装：

```bash
dsh plugin --profile web add github:bescriptkiddie/dsh-wechat-collector
```

如果当前 DSH 没有热加载新 bundle，请重启由系统托管的 DSH web 进程。加载后，
屏幕右缘会出现「公众号」。

## macOS 首次使用

打开「公众号」，点击「安装本地运行时」。插件会先把将要发生的本机改动完整
展示出来，并要求你明确确认。确认后才会：

1. 从 Astral GitHub Release 下载 uv `0.12.6`，并校验固定 SHA-256；
2. 把随插件打包、无凭证、无用户数据的采集代码部署到
   `~/.local/share/dsh-wechat-collector`；
3. 创建只属于当前用户、监听 `127.0.0.1:8000` 的 launchd 常驻服务；
4. 真实检查本机 API 就绪后再报告安装完成。

插件不会通过 `postinstall` 静默执行这些动作。内置运行时目前支持 Apple
Silicon 和 Intel Mac；其他平台仍可在 `collectorBaseUrl` 中连接自行运行的
兼容 API。

## 能力

- `wechat_collector_runtime`：查看、明确安装、启动、停止或停用本地运行时。
- `wechat_collector_login`：启动或查看扫码登录；二维码数据只进入本机面板路由。
- `wechat_collector_account`：搜索、添加、查看或移除公众号。
- `wechat_collector_crawl`：立即抓取、查看进度、管理每日定时，以及读取/调整请求节奏策略（账号间隔、翻页间隔、随机抖动、限流冷却时长）。
- `wechat_collector_credentials`：列出、切换或删除多套凭证档案；档案只能由扫码登录创建，工具不返回 token/cookie。
- `wechat_collector_sources`：管理外部信源（文章 RSS、播客、B 站）；公众号文章 RSS 作为限流期间也能独立更新的第二水源。
- `wechat_collector_items`：读取最近的公众号候选素材和短预览。
- `wechat_collector_feedback`：把真实人工判断写回采集端。
- `wechat_collector_analysis_config`：查看分析配置或测试 DeepSeek 连接，不接收密钥。
- `wechat_collector_author_analysis`：按指定公众号生成、列出或读取本地分析报告。
- `wechat_collector_import_to_studio`：幂等创建 ContentStudio 来源卡和 JSON 回执。
- `studio_wechat_collect`：给 ContentStudio 内容工作流使用的兼容入口。

面板对应的正常路径是：安装/启动 → 扫码登录 → 添加公众号 → 抓取 → 配置
DeepSeek → 选择博主和分析 Skill → 查看报告 → 筛选 → 导入来源卡。

## 多套凭证与限流保护

每次扫码登录都会把凭证存成一套命名档案，可随时在面板或工具间切换；
当前激活的档案不允许删除，凭证值永远不进入 DSH。爬取按可配置节奏进行
（账号间默认 20 秒、翻页间默认 8 秒，带随机抖动）；微信返回 freq control
时会立刻终止本轮并进入可配置时长的冷却期，冷却期内手动与定时抓取都会
被拒绝（HTTP 429），避免在风控窗口内反复请求加重处罚。

## 外部信源（第二水源）

运行时支持 `rss_feed` 文章信源：任何文章 RSS/Atom（典型用法是配合本机
WeWe RSS 的公众号订阅源）都会以公众号文章身份进入统一内容池，与后台抓取
走同一条管道。微信公众平台接口被限流时，这条水源仍能独立更新；两者互为
备份，互不影响。

### 用 WeWe RSS 搭公众号第二水源（可选）

`rss_feed` 能力随插件发布，但 RSS 源本身需要自己提供。推荐用
[WeWe RSS](https://github.com/cooderl/wewe-rss)（走微信读书接口，免费、自托管），
任何机器上的 Agent 都可以按下面的步骤带用户完成：

```bash
mkdir -p ~/.local/share/wewe-rss && cd ~/.local/share/wewe-rss
cat > docker-compose.yml <<'YAML'
services:
  wewe-rss:
    image: cooderl/wewe-rss-sqlite:latest
    container_name: wewe-rss
    ports:
      - "4100:4000"        # 4000 被占用时改用其他端口
    environment:
      - DATABASE_TYPE=sqlite
      - AUTH_CODE=改成你自己的管理码
      - FEED_MODE=fulltext
      - CRON_EXPRESSION=35 5,17 * * *
      - MAX_REQUEST_PER_MINUTE=60
    volumes:
      - ./data:/app/data
    restart: unless-stopped
YAML
docker compose up -d
```

然后：

1. 打开 `http://127.0.0.1:4100/dash`，输入管理码；
2. 添加微信读书账号（微信扫码登录，与公众平台后台是两套独立体系）；
3. 用每个公众号任意一篇文章的 `https://mp.weixin.qq.com/s/...` 链接添加订阅
   （面板支持直接粘贴链接，也可调 `platform.getMpInfo` + `feed.add`）；
4. 每个号的 feed 地址形如
   `http://127.0.0.1:4100/feeds/<MP_WXS_xxx>.atom?auth_code=<管理码>&limit=20`；
5. 在插件面板「信源管理」粘贴该地址，或调用
   `wechat_collector_sources(action=add, sourceType="rss_feed", url=...)` 注册并立即同步。

RSS 条目以 `wechat_article` 身份进入统一内容池，`wechat_collector_items` 与
`import_to_studio` 对两条水源一视同仁；feed 地址中的 `auth_code` 在面板和
工具输出中一律打码。

## 博主分析

打开「博主分析设置」，配置 API 地址、模型、分析 Skill 和文章数量。API Key
写入 DSH 自带的凭据服务，默认引用 `DEEPSEEK_API_KEY`；插件设置和分析报告都不
保存密钥。

当前内置三个分析 Skill：

- `author-methodology-analysis`：完整分析选题、标题、开头、结构、句式和判断标准。
- `topic-title-analysis`：重点分析选题桶、读者问题和标题公式。
- `structure-style-analysis`：重点分析开头、论证节奏、案例位置和表达结构。

抓取完成后，在具体公众号旁点击「分析」。确认后，插件最多发送设置数量的文章，
单篇最多 6000 字符、总计最多 60000 字符到配置的 DeepSeek-compatible API。
分析结果写入 `~/.local/share/dsh-wechat-collector/analysis/reports`，并直接显示在
插件面板。有效长文少于 5 篇时，报告会强制标记为小样本，不能表述为博主长期
风格。

## 证据和发布边界

采集结果只是来源线索，不是已经核验的事实，也不能进入个人 IP 风格语料。博主
分析只提炼内容方法、结构和判断逻辑，不冒充作者身份，不复制其经历、私有资源、
数据或标志性原句。这个插件不负责公众号发表；排版、草稿箱上传和最终发表继续
走独立的 ContentStudio 发布链，并保留人工确认。

## 数据与卸载

微信凭证和采集数据保存在
`~/.local/share/dsh-wechat-collector/data`，不会进入 npm 包，也不会由 Agent
工具返回。DeepSeek API Key 由 DSH credentials 保存；分析设置和报告位于
`~/.local/share/dsh-wechat-collector/analysis`。

卸载插件前，在面板点击「停用常驻服务」，或明确调用
`wechat_collector_runtime(action=unconfigure)`。它会停止 launchd，并把 plist
移动到可恢复备份；插件卸载默认保留登录态、历史文章和运行文件。详见
[PRIVACY.md](PRIVACY.md) 与 [SECURITY.md](SECURITY.md)。

## 开发验证

需要 Node.js 22.19 或更高版本：

```bash
npm install --ignore-scripts
npm run check
npm test
npm pack --dry-run
```

发布包已经包含可运行的 JavaScript 和 Python 源码，没有安装期构建步骤。

## 许可证

MIT。内置运行时源码及其来源回执位于 [`runtime/`](runtime/)。