dsh-social-trace 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Social Trace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# Social Trace
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**把你在微博、雪球关注的博主说过的话，完整留在本地。**
+
+Social Trace 是 DeepSeek Harness 的本地社交动态监控插件。它按博主持续检查新动态，把正文、转发原文和配图归档到本机；有新内容时，可以通过 dsh-im 推送到 QQ / 微信。
+
+[![npm](https://img.shields.io/npm/v/dsh-social-trace.svg)](https://www.npmjs.com/package/dsh-social-trace)
+[![license](https://img.shields.io/npm/l/dsh-social-trace.svg)](LICENSE)
+
+## 为什么用它
+
+- **平台上的内容会消失。** 博主删帖、改口、设置半年可见，刷过去就找不到了。Social Trace 把看到的动态按博主留在本地，之后还能搜索、导出。
+- **不想每天手动刷主页。** 按博主设置检查频率和时间段，只在新动态出现时记录和提醒。
+- **不想把账号交给 AI。** 登录在插件自己的浏览器里完成，Cookie 不经过模型，资料库只落在本机。
+
+## 核心能力
+
+| 能力 | 说明 |
+| --- | --- |
+| 按博主监控 | 微博、雪球；每位博主独立开关、频率和时间段 |
+| 增量检查 | 定时读取新动态；关机/重启后补查期间仍可见的内容 |
+| 历史缓存 | 按日期范围回补旧动态，支持断点续传，不重复抓取 |
+| 完整留档 | 正文、转发原文、配图；按平台和博主 UID 分目录保存 |
+| 本地资料库 | SQLite + 按博主分目录的 Markdown；支持中文正文搜索 |
+| 导出 | 单博主 Markdown / JSONL，正文和来源一起带走 |
+| 可视化流向 | 博主 → 平台 → Social Trace → 资料库四层拓扑，状态、进度、异常一眼可见 |
+| dsh-im 推送 | 新动态原文推送到 QQ / 微信；支持多个接收目标；默认关闭 |
+| 本地优先 | 授权会话只存插件目录（0600），资料库不额外上传云端，不写进仓库 |
+
+## 它怎么工作
+
+1. **添加博主**：粘贴微博/雪球主页链接或数字 UID。
+2. **选择记录方式**：从现在开始，或按日期范围缓存历史消息。
+3. **交给它跑**：按设定频率检查；新内容入库后写 Markdown、下载配图；需要时通过 dsh-im 推送。
+
+## 安装
+
+需要 DeepSeek Harness 桌面版、Google Chrome，以及 Node.js 22.19 或以上。
+
+从 npm 安装（也可以在 Harness 的插件管理里直接安装 `dsh-social-trace`）：
+
+```sh
+dsh plugin --profile desktop add dsh-social-trace
+```
+
+也可以从源码安装：
+
+```sh
+git clone https://github.com/chiinsight/dsh-social-trace.git
+cd dsh-social-trace
+npm ci
+dsh plugin --profile desktop add .
+```
+
+安装后完全退出并重新打开 Harness，在侧栏打开 Social Trace。
+
+## 快速开始
+
+1. **选保存位置**：在「连接与设置」里选择资料库文件夹。
+2. **登录平台**：点「登录微博」/「登录雪球」，在独立浏览器窗口完成登录，回来点「我已登录，继续」。
+3. **添加博主**：粘贴主页或 UID，读取昵称/头像/总数，选择从现在记录或缓存历史。
+4. **调频率**：点大屏里的博主、平台或总控齿轮，设置检查频率、时间段和历史范围。
+5. **开推送（可选）**：先在 dsh-im 里连接机器人并创建接收目标，再到 Social Trace 的 dsh-im 节点添加渠道、选择博主范围、开启自动推送。
+
+## 通过 dsh-im 推送
+
+推送的是**新动态原文通知**，不是 AI 摘要：包含博主、发布时间、正文节选、转发引用和原文链接。
+
+- 默认关闭；安装、打开设置或选择目标都不会自动发送。
+- 只推送开启之后新采集的内容；历史缓存和此前已存内容不补发。
+- 支持多个接收目标（QQ、微信等），每个目标可单独开关；一个渠道失败不影响其他渠道。
+- 投递记录可查；失败或结果未知不会自动重发，避免重复打扰。
+- 机器人密钥由 dsh-im 管理，Social Trace 不重复保存。
+
+配置入口：大屏的 dsh-im 节点，或「连接与设置」里的消息推送区域。
+
+## 数据放在哪
+
+默认在 `~/.local/share/dsh-social-trace/`，也可以在设置里改到自己的文件夹。
+
+```text
+你选择的文件夹/
+  archive.sqlite       正文、任务、状态和消息
+  documents/
+    weibo/<UID>/       该博主的 Markdown 与配图
+    xueqiu/<UID>/
+```
+
+登录会话单独保存在插件目录，权限 0600，不进入仓库，也不会复制到资料文件夹。资料库不是加密数据库；需要更高保护时请把文件夹放在加密磁盘里。
+
+## 边界
+
+- 需要电脑唤醒且 Harness/插件在运行；关机期间不会采集，重开后补查仍可见的内容。
+- 已删除、被权限挡住或超出平台可见范围的内容无法补回。
+- 平台要求登录/验证时会暂停采集，处理后继续；不会绕过验证码、轮换账号或使用代理池。
+- 雪球文章只保存标题和原文链接，不保存文章正文。
+- 当前推送的是原文通知；AI 总结和 IM 内问答尚未接入。
+
+## 开发
+
+```sh
+npm ci
+npm test        # 244 项离线测试
+npm run test:ui # 5 项界面测试（需要 Chrome）
+```
+
+## 许可
+
+[MIT](LICENSE)。平台标识的权利说明见 [assets/NOTICE.md](assets/NOTICE.md)。

package/assets/NOTICE.md

@@ -0,0 +1,3 @@
+微博标识（weibo.ico）取自微博官网 https://weibo.com/favicon.ico（2026-11-05），仅用于标识监控平台。商标与图形权利归相关权利人所有，不包含在本项目 MIT 授权范围内。
+
+雪球标识（xueqiu.png）取自雪球官网 https://xueqiu.com/ 的 favicon 链接 https://xqimg.imedao.com/17af5fe80fb1844b3fd48941.png（2026-11-06），仅用于标识平台。商标与图形权利归相关权利人所有，不包含在本项目 MIT 授权范围内。

package/assets/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" rx="16" fill="#15251f"/><g fill="none" stroke="#a0dfc1" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M17 17h30v25H28L17 50V17Z"/><path d="M24 26h16M24 34h11"/></g></svg>

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-social-trace
+      name: 'dsh-social-trace'

package/lib/agent.js

@@ -0,0 +1,198 @@
+import { deliveryDestinations, activeDestinations } from './delivery-config.js';
+const defaults = { enabled: false, botId: '', targetId: '', uids: [] };
+export const agentConfig = store => store.getSetting('agentDelivery', defaults);
+
+export class SocialAgent {
+  constructor(getStore, getIM, paused = () => false) {
+    this.getStore = getStore;
+    this.getIM = getIM;
+    this.paused = paused;
+    this.timer = null;
+    this.startedAt = Date.now();
+    this.connections = { bots: [], targets: {}, checkedAt: 0, error: '' };
+    this.refreshing = null;
+    this.busy = null;
+    this.controller = new AbortController();
+  }
+  async refreshConnections() {
+    if (this.refreshing) return this.refreshing;
+    const im = this.getIM(), config = agentConfig(this.getStore());
+    if (!im?.listBots || !im?.listTargets) return;
+    this.refreshing = (async () => {
+      try {
+        const bots = (await im.listBots()).map(({ botId, channel }) => ({ botId, channel }));
+        const targets = {};
+        for (const botId of new Set(deliveryDestinations(config).map(item => item.botId))) {
+          if (!bots.some(bot => bot.botId === botId)) continue;
+          try { targets[botId] = (await im.listTargets(botId)).map(({ targetId, name }) => ({ targetId, name })); }
+          catch { targets[botId] = null; }
+        }
+        this.connections = { bots, targets, checkedAt: Date.now(), error: '' };
+      } catch { this.connections = { ...this.connections, checkedAt: Date.now(), error: '无法读取 dsh-im 配置，请检查插件' }; }
+    })();
+    try { await this.refreshing; } finally { this.refreshing = null; }
+  }
+  status() {
+    const store = this.getStore(), config = agentConfig(store);
+    const transportAvailable = ['send', 'listBots', 'listTargets'].every(key => typeof this.getIM()?.[key] === 'function');
+    if (transportAvailable && Date.now() - this.connections.checkedAt > 30000) void this.refreshConnections();
+    const destinations = deliveryDestinations(config).map(item => {
+      const bot = this.connections.bots.find(bot => bot.botId === item.botId);
+      const target = this.connections.targets[item.botId]?.find(target => target.targetId === item.targetId);
+      const delivery = store.db.prepare("SELECT status,error,sent_at,finished_at,created_at FROM social_deliveries WHERE bot_id=? AND target_id=? AND status IN ('sent','failed','uncertain') ORDER BY COALESCE(finished_at,sent_at,created_at) DESC,id DESC LIMIT 1").get(item.botId, item.targetId);
+      const test = store.getSetting('imTest:' + item.botId + ':' + item.targetId, null);
+      const last = test && test.created_at > (delivery?.finished_at || delivery?.sent_at || delivery?.created_at || 0) ? test : delivery;
+      const state = !transportAvailable ? 'unavailable' : !config.enabled || item.enabled === false ? 'paused'
+        : !this.connections.checkedAt ? 'checking' : this.connections.error || !bot || !target ? 'invalid'
+        : last && ['failed', 'uncertain'].includes(last.status) ? 'failed' : last?.status === 'sent' ? 'accepted' : 'configured';
+      return { ...item, channel: bot?.channel || item.channel || '', name: target?.name || item.name || item.targetId, state, last };
+    });
+    return { config, transportAvailable, destinations, integration: this.connections, summaryAvailable: false,
+      deliveries: store.db.prepare('SELECT d.id,d.author,d.bot_id,d.target_id,d.status,d.error,d.created_at,d.sent_at,d.finished_at,p.published_at,p.detected_at,p.first_seen_at AS saved_at FROM social_deliveries d LEFT JOIN posts p ON p.id=d.post_id ORDER BY d.created_at DESC,d.id DESC LIMIT 30').all() };
+  }
+  async bots() {
+    const im = this.getIM();
+    if (typeof im?.listBots !== 'function') return [];
+    return (await im.listBots()).map(({ botId, channel }) => ({ botId, channel }));
+  }
+  async targets(botId) {
+    const im = this.getIM();
+    if (typeof im?.listTargets !== 'function') throw new Error('尚未连接 dsh-im，请在 Harness 中启用 IM 机器人插件');
+    return (await im.listTargets(botId)).map(({ targetId, name, kind }) => ({ targetId, name, kind }));
+  }
+  async validate(body, { force = false } = {}) {
+    if (typeof body.enabled !== 'boolean' || !Array.isArray(body.uids) || body.uids.length > 2000 || body.uids.some(uid => typeof uid !== 'string' || !this.getStore().target(uid))) throw new Error('请选择有效的推送开关与博主');
+    const multiple = Array.isArray(body.destinations);
+    const input = multiple ? body.destinations : [{ botId: body.botId, targetId: body.targetId, enabled: true }];
+    if (input.length > 20) throw new Error('最多配置 20 个推送目标');
+    const destinations = [], keys = new Set(), current = agentConfig(this.getStore());
+    let bots;
+    for (const item of input) {
+      if (typeof item.botId !== 'string' || typeof item.targetId !== 'string' || item.enabled !== undefined && typeof item.enabled !== 'boolean') throw new Error('请选择有效的机器人和接收目标');
+      const value = { botId: item.botId.trim(), targetId: item.targetId.trim(), enabled: item.enabled !== false };
+      if (value.botId.length > 256 || value.targetId.length > 256) throw new Error('机器人或目标标识格式无效，请从 dsh-im 选择');
+      const previous = deliveryDestinations(current).find(row => row.botId === value.botId && row.targetId === value.targetId);
+      if (previous?.channel) value.channel = previous.channel;
+      if (previous?.name) value.name = previous.name;
+      const key = value.botId + ':' + value.targetId;
+      if (keys.has(key)) throw new Error('该接收目标已添加');
+      keys.add(key);
+      if (multiple && (!value.botId || !value.targetId)) throw new Error('请选择机器人和接收目标');
+      if (body.enabled && value.enabled && (force || !current.enabled || !previous || previous.enabled === false)) {
+        if (typeof this.getIM()?.send !== 'function') throw new Error('dsh-im 尚未连接，不能开启推送');
+        bots ??= await this.bots();
+        const bot = bots.find(bot => bot.botId === value.botId);
+        const target = bot && (await this.targets(value.botId)).find(target => target.targetId === value.targetId);
+        if (!target) throw new Error('请先在 dsh-im 保存机器人和接收目标，再刷新选择');
+        value.channel = bot.channel; value.name = target.name || value.targetId;
+      }
+      destinations.push(value);
+    }
+    if (body.enabled && !destinations.some(item => item.enabled)) throw new Error('请至少开启一个接收目标');
+    return multiple ? { enabled: body.enabled, uids: [...new Set(body.uids)], destinations }
+      : { enabled: body.enabled, botId: destinations[0].botId, targetId: destinations[0].targetId, uids: [...new Set(body.uids)] };
+  }
+  async configure(body) {
+    const value = await this.validate(body), store = this.getStore();
+    const previous = agentConfig(store);
+    store.transaction(() => {
+      store.setSetting('agentDelivery', value);
+      const destinations = deliveryDestinations(value);
+      for (const item of activeDestinations(value)) {
+        if (!activeDestinations(previous).some(old => old.botId === item.botId && old.targetId === item.targetId)) store.setSetting('deliveryFrom:' + item.botId + ':' + item.targetId, Date.now());
+      }
+      for (const row of store.db.prepare("SELECT id,bot_id,target_id FROM social_deliveries WHERE status='queued'").all()) {
+        if (!destinations.some(item => item.botId === row.bot_id && item.targetId === row.target_id)) store.db.prepare("UPDATE social_deliveries SET status='cancelled',error='接收目标已移除' WHERE id=?").run(row.id);
+      }
+      for (const platform of ['weibo', 'xueqiu']) if (!Array.isArray(previous.destinations) && store.getSetting('accountAlerted:' + platform, false)) {
+        for (const item of deliveryDestinations(previous)) store.setSetting('accountAlerted:' + platform + ':' + item.botId + ':' + item.targetId, true);
+      }
+      for (const platform of ['weibo', 'xueqiu']) for (const item of destinations) {
+        if (!deliveryDestinations(previous).some(old => old.botId === item.botId && old.targetId === item.targetId)) store.setSetting('accountAlerted:' + platform + ':' + item.botId + ':' + item.targetId, false);
+      }
+      if (value.uids.length) for (const row of store.db.prepare("SELECT id,uid FROM social_deliveries WHERE status='queued' AND message=''").all()) if (!value.uids.includes(row.uid)) store.db.prepare("UPDATE social_deliveries SET status='cancelled',error='此博主已移出推送范围' WHERE id=?").run(row.id);
+    })();
+    for (const platform of ['weibo', 'xueqiu']) {
+      const account = store.account(platform);
+      if (value.enabled && account?.uid && ['needs_login', 'needs_verification'].includes(account.status)) store.setAccount({ status: account.status, reason: account.reason }, platform, true);
+    }
+    if (this.refreshing) await this.refreshing;
+    this.connections.checkedAt = 0;
+    await this.refreshConnections();
+    return value;
+  }
+  async test(body) {
+    const value = await this.validate({ enabled: true, botId: body.botId, targetId: body.targetId, uids: body.uids || [] }, { force: true });
+    const store = this.getStore(), key = 'imTest:' + value.botId + ':' + value.targetId;
+    try {
+      const result = await this.getIM().send(value.botId, value.targetId, 'Social Trace 推送连接测试：这是一条由你主动发送的测试消息。', { signal: AbortSignal.timeout(15000) });
+      if (result?.sent !== true) throw new Error('dsh-im 未确认接受测试消息');
+      store.setSetting(key, { status: 'sent', error: '', created_at: Date.now(), sent_at: Date.now() });
+      store.setSetting('imDeliveryAlert:' + value.botId + ':' + value.targetId, false);
+      return { sent: true };
+    } catch (error) {
+      store.setSetting(key, { status: 'uncertain', error: String(error.message || '发送未确认').slice(0, 300), created_at: Date.now() });
+      throw error;
+    }
+  }
+
+  start() {
+    if (this.timer) return;
+    this.controller = new AbortController();
+    this.startedAt = Date.now();
+    const store = this.getStore(), config = agentConfig(store);
+    const pending = activeDestinations(config).reduce((total, item) => total + store.db.prepare("SELECT COUNT(*) AS n FROM social_deliveries WHERE status='queued' AND message='' AND bot_id=? AND target_id=? AND created_at<?").get(item.botId, item.targetId, this.startedAt).n, 0);
+    if (pending) store.notice('task', '恢复推送：上次运行时已保存的 ' + pending + ' 条动态尚未发送，将继续推送；这不是刚发布的新消息。');
+    for (const platform of ['weibo', 'xueqiu']) {
+      const account = this.getStore().account(platform);
+      if (account?.uid && ['needs_login', 'needs_verification'].includes(account.status)) this.getStore().setAccount({ status: account.status, reason: account.reason }, platform, true);
+    }
+    this.getStore().db.prepare("UPDATE social_deliveries SET status='uncertain',finished_at=?,error='上次投递时进程中断，结果未知；未自动重发' WHERE status='sending'").run(Date.now());
+    this.timer = setInterval(() => { void this.tick(); }, 5000);
+    this.timer.unref?.();
+  }
+  async tick() {
+    if (this.busy || this.paused() || this.controller.signal.aborted) return;
+    const store = this.getStore(), config = agentConfig(store), im = this.getIM();
+    if (!config.enabled || !im?.send) return;
+    const destinations = activeDestinations(config);
+    if (!destinations.length) return;
+    const where = destinations.map(() => '(bot_id=? AND target_id=?)').join(' OR ');
+    const row = store.db.prepare("SELECT * FROM social_deliveries WHERE status='queued' AND (" + where + ") AND (? OR message<>'') ORDER BY (message<>'') DESC,created_at,id LIMIT 1").get(...destinations.flatMap(item => [item.botId, item.targetId]), store.getSetting('monitorEnabled', true) === false ? 0 : 1);
+    if (!row) return;
+    const post = row.message ? null : store.posts({ ids: [row.post_id], limit: 1 })[0];
+    if (!post && !row.message) { store.db.prepare("UPDATE social_deliveries SET status='cancelled',error='原文不存在' WHERE id=?").run(row.id); return; }
+    store.db.prepare("UPDATE social_deliveries SET status='sending' WHERE id=?").run(row.id);
+    this.busy = (async () => {
+      try {
+        const stamp = time => new Date(time).toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai', hour12: false });
+        const prefix = post?.capture_kind === 'catchup' ? '离线补查通知：恢复运行后补查到的内容，并非刚刚发布。\n' : row.created_at < this.startedAt ? '恢复待发通知：上次运行时已保存，本次继续发送。\n' : '';
+        const text = row.message || prefix + `${post.author} · ${post.quote ? '转发' : '新动态'}\n博主发布：${stamp(post.published_at)}\n监控发现：${post.detected_at ? stamp(post.detected_at) : '旧记录未记录'}\n首次保存：${stamp(post.first_seen_at)}\n发起推送：${stamp(Date.now())}（以上均为北京时间）\n\n${post.text.slice(0, 1400)}${post.quote ? '\n\n引用 ' + post.quote.author + '：' + post.quote.text.slice(0, 400) : ''}\n\n原文：${post.url}`;
+        const result = await im.send(row.bot_id, row.target_id, text, { signal: AbortSignal.any([this.controller.signal, AbortSignal.timeout(15000)]) });
+        if (result?.sent !== true) throw new Error('dsh-im 未确认接受消息');
+        store.setSetting('imDeliveryAlert:' + row.bot_id + ':' + row.target_id, false);
+        const finishedAt = Date.now();
+        store.db.prepare("UPDATE social_deliveries SET status='sent',sent_at=?,finished_at=?,error='' WHERE id=?").run(finishedAt, finishedAt, row.id);
+      } catch (error) {
+        const status = ['unknown-bot', 'unknown-target', 'invalid-target', 'target-rejected', 'bot-not-connected'].includes(error.code) ? 'failed' : 'uncertain';
+        store.db.prepare('UPDATE social_deliveries SET status=?,finished_at=?,error=? WHERE id=?').run(status, Date.now(), String(error.message || '投递失败').slice(0, 300), row.id);
+        const alertKey = 'imDeliveryAlert:' + row.bot_id + ':' + row.target_id;
+        if (!store.getSetting(alertKey, false)) {
+          const destination = deliveryDestinations(config).find(item => item.botId === row.bot_id && item.targetId === row.target_id);
+          const channel = destination?.channel || this.connections.bots.find(bot => bot.botId === row.bot_id)?.channel || 'IM';
+          const recipient = '\n接收渠道：' + ({ weixin: '微信', qq: 'QQ' }[channel] || channel) + ' · ' + (destination?.name || row.target_id);
+          store.notice('attention', error.code === 'delivery-failed' || error.message === 'delivery-failed'
+            ? 'dsh-im 插件发送失败：请检查 dsh-im 的机器人连接和接收目标。消息已保存在本地，未确认是否送达；详见推送记录。' + recipient
+            : 'dsh-im 推送未确认：请检查机器人连接与接收目标，详见推送记录。消息已保存在本地。' + recipient, Date.now());
+          store.setSetting(alertKey, true);
+        }
+      }
+    })();
+    try { await this.busy; } finally { this.busy = null; }
+  }
+  async close() {
+    clearInterval(this.timer); this.timer = null;
+    this.controller.abort();
+    if (this.busy) await this.busy;
+  }
+}

package/lib/avatars.js

@@ -0,0 +1,63 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, mkdir, writeFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { imageReferer } from './text.js';
+
+const types = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/gif']);
+const limit = 2 * 1024 * 1024;
+
+export class Avatars {
+  constructor(directory, fetchImage = fetch) {
+    this.directory = directory;
+    this.fetchImage = fetchImage;
+    this.pending = new Map();
+    this.controller = new AbortController();
+  }
+
+  get(image) {
+    if (!this.pending.has(image)) {
+      const task = this.load(image).finally(() => this.pending.delete(image));
+      this.pending.set(image, task);
+    }
+    return this.pending.get(image);
+  }
+
+  async load(image) {
+    const file = join(this.directory, createHash('sha256').update(image).digest('hex') + '.avatar');
+    try {
+      const cached = await readFile(file);
+      const end = cached.indexOf(10);
+      const type = cached.subarray(0, end).toString();
+      if (end > 0 && types.has(type) && cached.length > end + 1 && cached.length <= limit + end + 1) return { type, bytes: cached.subarray(end + 1) };
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const response = await this.fetchImage(image, { headers: { Referer: imageReferer(image) }, redirect: 'error',
+      signal: AbortSignal.any([this.controller.signal, AbortSignal.timeout(10000)]) });
+    const type = response.headers.get('content-type')?.split(';')[0];
+    if (!response.ok || !types.has(type) || Number(response.headers.get('content-length')) > limit) {
+      await response.body?.cancel();
+      throw new Error('头像暂时无法读取');
+    }
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of response.body) {
+      length += chunk.length;
+      if (length > limit) throw new Error('头像文件过大');
+      chunks.push(chunk);
+    }
+    if (!length) throw new Error('头像内容为空');
+    const bytes = Buffer.concat(chunks, length);
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const temporary = file + '.' + randomUUID() + '.tmp';
+    try {
+      await writeFile(temporary, Buffer.concat([Buffer.from(type + '\n'), bytes]), { mode: 0o600 });
+      await rename(temporary, file);
+    } finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+    return { type, bytes };
+  }
+
+  async close() {
+    this.controller.abort();
+    await Promise.allSettled(this.pending.values());
+  }
+}

package/lib/capture-error.js

@@ -0,0 +1,8 @@
+// Platform adapters translate their own responses into these shared failure kinds.
+export class CaptureError extends Error {
+  constructor(kind, message, retryAfter = 0) {
+    super(message);
+    this.kind = kind;
+    this.retryAfter = retryAfter;
+  }
+}