qq-bot-roost 0.8.12 → 0.8.14

package/README.md

@@ -8,9 +8,9 @@
 
 <img src="https://img.shields.io/badge/Node.js-22.13%2B-339933?logo=node.js&logoColor=white" alt="Node.js 22.13+">
 <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="零依赖">
-<img src="https://img.shields.io/badge/tests-600%2B%20passed-brightgreen" alt="测试 600+ 项">
+<img src="https://img.shields.io/badge/tests-700%2B%20passed-brightgreen" alt="测试 700+ 项">
 <img src="https://img.shields.io/badge/plugins-JS%20%7C%20Python%20%7C%20Go%20%7C%20any-blue" alt="多语言插件">
-<img src="https://img.shields.io/badge/version-0.8.12-blueviolet" alt="版本 0.8.12">
+<img src="https://img.shields.io/badge/version-0.8.14-blueviolet" alt="版本 0.8.14">
 <img src="https://img.shields.io/badge/license-Non--Commercial-red" alt="禁止商用">
 <a href="https://github.com/tdcq9594/qq-bot-roost/actions"><img src="https://img.shields.io/github/actions/workflow/status/tdcq9594/qq-bot-roost/ci.yml?branch=master" alt="CI"></a>
 
@@ -424,8 +424,8 @@ bot/
 │   ├── web/server.js           面板服务端（REST + SSE）
 │   └── plugin/                 插件加载、配置、依赖、子进程宿主、面板页面注册
 ├── test/
-│   ├── selftest.mjs            框架自检（431 项）
-│   ├── e2e.mjs                 端到端测试（168 项，起真实服务打接口）
+│   ├── selftest.mjs            框架自检（511 项）
+│   ├── e2e.mjs                 端到端测试（185 项，起真实服务打接口）
 │   ├── qrlogin.mjs             扫码建机器人（8 项）
 │   └── deps.mjs                插件依赖安装（11 项）
 ├── web/                        面板前端（原生 JS/CSS，无构建）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

package/src/api.js

@@ -10,8 +10,11 @@ const log = createLogger('api');
 export const FILE_TYPE = { IMAGE: 1, VIDEO: 2, VOICE: 3, FILE: 4 };
 
 /**
- * 官方硬限制：同一条消息最多被动回复 5 次（`msg_seq` 取 1–5）。
- * 第 6 次服务端返回 40034128「被动回复时间或次数超限」。
+ * 被动回复序号的**最后一道**兜底上限。
+ *
+ * 官方口径按会话类型不同：群聊 5 次（`msg_seq` 1–5），单聊 4 次（1–4）。
+ * 这里只按 `msgId` 记，拿不到会话类型，所以取两者较大的 5 当「绝不可能超过」的硬顶。
+ * 精确拦截在 `outbound.js`（`PASSIVE_MAX_REPLIES[kind]`），正常流程走不到这里。
  */
 const PASSIVE_MAX_SEQ = 5;
 
@@ -164,6 +167,16 @@ export class QQApi {
       const err = new Error(`HTTP ${res.status} ${method} ${path}: ${msg}`);
       err.status = res.status;
       err.body = data;
+      /**
+       * QQ 的业务错误码，和 HTTP 状态码是两回事。
+       *
+       * 同样是 400，`40054004`（无好友关系）和 `40034006`（内容违规）
+       * 该做的事完全不同：前者要更新可达性状态，后者只能改文案。
+       * 上层拿不到这个码就只能瞎猜，所以在这里就拆出来。
+       *
+       * 常见值见 `docs/官方接口限制.md` 与 `src/reach.js`。
+       */
+      err.qqCode = Number(data?.code ?? data?.err_code ?? 0) || 0;
       throw err;
     }
     return data;
@@ -946,14 +959,14 @@ export class QQApi {
   }
 
   /**
-   * 被动回复序号。官方硬限制：**同一条消息最多回复 5 次**（msg_seq 取 1–5），
-   * 第 6 次返回 40034128。这里兜一道，正常流程由 outbound.js 先拦。
+   * 被动回复序号。硬顶见 `PASSIVE_MAX_SEQ`（群聊 5 / 单聊 4，这里取 5 兜底），
+   * 超了服务端返回 40034128。正常流程由 outbound.js 按会话类型先拦。
    */
   #nextSeq(msgId) {
     const cur = this.seqMap.get(msgId) ?? 0;
     if (cur >= PASSIVE_MAX_SEQ) {
       throw new Error(
-        `同一条消息最多回复 ${PASSIVE_MAX_SEQ} 次（QQ 官方限制），这条已经回了 ${cur} 次`,
+        `同一条消息最多回复 5 次（群聊）/ 4 次（单聊），这条已经回了 ${cur} 次`,
       );
     }
     const next = cur + 1;

package/src/bot.js

@@ -16,6 +16,7 @@ import { BotMetrics } from './runtime.js';
 import { claimInstance, releaseInstance } from './instance.js';
 import { botPaths, DIRS, rel } from './paths.js';
 import { StatsStore } from './storage/index.js';
+import { createReach } from './reach.js';
 
 /**
  * 一个机器人的完整运行时。
@@ -86,6 +87,14 @@ export class BotRuntime {
      */
     this.groupNames = new Map();
     this.roles = new RoleStore(this.paths.roles);
+    /**
+     * 可达性：谁能私聊、哪个群能主动推。
+     *
+     * 官方没有查好友的接口，只能靠 6 个事件维护（FRIEND_ADD/DEL、
+     * C2C_MSG_REJECT/RECEIVE、GROUP_MSG_REJECT/RECEIVE）。
+     * 插件可以通过 `bot.reach` 直接问，不用自己监听一遍。
+     */
+    this.reach = createReach({ file: this.paths.reach });
     this.outbound = null;
     this.session = null;
     this.pipeline = null;
@@ -183,6 +192,7 @@ export class BotRuntime {
       outbound: this.outbound,
       session: this.session,
       pipeline: this.pipeline,
+      reach: this.reach,
       isOwner: (uid) => cfg.owners.includes(uid),
       // 插件声明了 frameworkVersion 就做兼容校验；作者本地调试可以关掉
       ignoreCompat: this.globalCfg.plugins?.ignoreFrameworkVersion === true,
@@ -344,6 +354,51 @@ export class BotRuntime {
     return this.groupNames.get(groupOpenid)?.name || undefined;
   }
 
+  /**
+   * 用 6 个事件维护可达性。
+   *
+   * 官方**没有查好友列表的接口**（sitemap 里 `friend` 只有两个事件页），
+   * 所以「接入之前就存在的关系」永远是未知的，只能维护「接入之后的变化」。
+   * 三态语义与判定顺序见 `src/reach.js` 头注释。
+   */
+  async #noteReach(eventName, d) {
+    const openid = d?.openid ?? '';
+    switch (eventName) {
+      case 'FRIEND_ADD':
+        await this.reach.noteFriendAdd({
+          openid,
+          unionOpenid: d?.author?.union_openid ?? '',
+          scene: d?.scene ?? 0,
+        });
+        break;
+      case 'FRIEND_DEL':
+        await this.reach.noteFriendDel({ openid });
+        break;
+      case 'C2C_MSG_REJECT':
+        await this.reach.noteC2cPush({ openid, on: false });
+        break;
+      case 'C2C_MSG_RECEIVE':
+        await this.reach.noteC2cPush({ openid, on: true });
+        break;
+      case 'GROUP_MSG_REJECT':
+        await this.reach.noteGroupPush({
+          groupOpenid: d?.group_openid,
+          on: false,
+          by: d?.op_member_openid,
+        });
+        break;
+      case 'GROUP_MSG_RECEIVE':
+        await this.reach.noteGroupPush({
+          groupOpenid: d?.group_openid,
+          on: true,
+          by: d?.op_member_openid,
+        });
+        break;
+      default:
+        break;
+    }
+  }
+
   /**
    * 补一个群的名字（给面板调的公开入口，内部走带缓存的那份）。
    * 不会抛异常，调用方不用 try/catch。
@@ -415,6 +470,7 @@ export class BotRuntime {
     await this.outbound?.flush().catch(() => {});
     await this.groups?.flush().catch(() => {});
     await this.roles?.flush().catch(() => {});
+    await this.reach?.flush().catch(() => {});
     this.stats?.close();
     if (!this.mock) await releaseInstance(this.cfg.appId).catch(() => {});
     this.state = 'stopped';
@@ -456,6 +512,12 @@ export class BotRuntime {
         await groups.onRemoved(d?.group_openid);
       }
 
+      // 可达性：官方没有查询接口，只能靠这 6 个事件维护（见 src/reach.js）
+      // 放在插件监听器之前，插件读到的就是最新状态
+      await this.#noteReach(eventName, d).catch((e) => {
+        this.log.warn(`可达性更新失败: ${e.message}`);
+      });
+
       const meta = EVENTS[eventName] ?? null;
       for (const l of registry.listeners.get(eventName) ?? []) {
         // 事件里的群：有 group_openid 就按群开关过滤，没有（如私聊事件）就放行
@@ -478,6 +540,14 @@ export class BotRuntime {
 
     /* ---- 消息事件 ---- */
     const msg = buildMessage(eventName, d, { api: this.api, cfg, outbound, session });
+
+    // 收到私聊 = 好友关系存在的强证据。不置 c2cPush：他能发不等于他允许机器人主动推
+    if (msg.kind === 'c2c' && msg.userId) {
+      this.reach
+        .noteC2cObserved({ openid: msg.userId, unionOpenid: d?.author?.union_openid })
+        .catch(() => {});
+    }
+
     /**
      * 先播出去，再做业务处理。
      *

package/src/gitee.js

@@ -69,7 +69,14 @@ export function giteeRawUrl(repo, ref, filePath) {
  *                            如 ['src/', 'package.json']；不传拉全仓
  * @param {number} [o.timeoutMs] 单文件超时
  * @param {(msg:string)=>void} [o.onProgress] 每拉完一个文件调一次
- * @returns {Promise<{files:number, skipped:number}>}
+ * @param {boolean} [o.allowPartial] 有文件拉不下时**不抛错**，把失败清单放进
+ *   返回值的 `failed` 里，交给调用方用别的源补拉。默认 false（整体中止）。
+ *
+ *   为什么要这个开关：Gitee 会对个别文件返回 451（内容审查），而**同一个
+ *   文件在 GitHub 上是好的**（实测 douluo 的 content-pack.sql 等 4 个文件）。
+ *   以前只要有一个失败就整包中止，等于一个文件被屏蔽 → 整个插件装不上。
+ *
+ * @returns {Promise<{files:number, skipped:number, failed:Array<{path:string,error:string}>}>}
  */
 export async function fetchGiteeTree({
   repo,
@@ -79,6 +86,7 @@ export async function fetchGiteeTree({
   only = null,
   timeoutMs = 120000,
   onProgress,
+  allowPartial = false,
 }) {
   if (!repo || !/^[\w.-]+\/[\w.-]+$/.test(repo)) throw new Error(`Gitee 仓库名不合法：${repo}`);
   if (!ref) throw new Error('Gitee 下载缺少分支/tag');
@@ -121,6 +129,7 @@ export async function fetchGiteeTree({
   await fs.mkdir(destDir, { recursive: true });
   let done = 0;
   let failed = 0;
+  const failedList = [];
   let cursor = 0;
 
   async function worker() {
@@ -145,7 +154,15 @@ export async function fetchGiteeTree({
               signal: AbortSignal.timeout(timeoutMs),
             });
             if (res.ok) break;
-            lastErr = new Error(`HTTP ${res.status}`);
+            /**
+             * 451 = Unavailable For Legal Reasons。Gitee 会对个别文件返回它
+             * （内容审查），而同一个文件在 GitHub 上是 200。光写「HTTP 451」
+             * 没人看得懂该去换下载源，所以翻成人话。
+             */
+            lastErr =
+              res.status === 451
+                ? new Error('HTTP 451（Gitee 上这个文件不可用，多半被内容审查挡了）')
+                : new Error(`HTTP ${res.status}`);
             if (!isRetryable(res, null)) {
               res = null;
               break;
@@ -169,6 +186,7 @@ export async function fetchGiteeTree({
         onProgress?.(`${done}/${files.length} ${f.path}`);
       } catch (e) {
         failed += 1;
+        failedList.push({ path: f.path, error: e.message });
         log.warn(`拉取失败 ${f.path}: ${e.message}`);
       }
     }
@@ -177,9 +195,11 @@ export async function fetchGiteeTree({
   await Promise.all(Array.from({ length: Math.min(CONCURRENCY, files.length) }, worker));
 
   if (failed) {
+    // 调用方要自己补拉就不抛 —— 它补完还失败会自己报错，那时信息更全
+    if (allowPartial) return { files: done, skipped: files.length - done, failed: failedList };
     throw new Error(`Gitee 下载 ${repo}@${ref}：${files.length} 个文件里 ${failed} 个失败，已中止`);
   }
-  return { files: done, skipped: files.length - done };
+  return { files: done, skipped: files.length - done, failed: [] };
 }
 
 /**

package/src/message-bus.js

@@ -104,7 +104,7 @@ export function serializeMessage(botId, msg) {
     mentioned: Boolean(msg.mentioned),
     addressed: Boolean(msg.addressed),
     isCommand: Boolean(msg.isCommand),
-    /** 被动回复用（5 分钟窗口，同一条最多 5 次） */
+    /** 被动回复用（群聊 5 分钟 / 5 次，单聊 60 分钟 / 4 次） */
     msgId: msg.id,
     /** 引用回复用（message_reference.message_id） */
     msgIdx: msg.msgIdx,

package/src/message.js

@@ -362,7 +362,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
   }
 
   // 底层发送：group 走群接口，c2c 走单聊接口。
-  // 一律经过 outbound，由它处理 5 分钟窗口、每秒限速、主动消息额度。
+  // 一律经过 outbound，由它处理被动窗口（群聊 5 分钟 / 单聊 60 分钟）、每秒限速、主动消息额度。
   const send = (opts, passive) => {
     if (kind !== 'group' && kind !== 'c2c') return Promise.resolve(null);
     const body = passive ? { msgId: msg.id, ...opts } : { ...opts };
@@ -410,7 +410,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
   const MAX_CHUNK = 1500; // 单条上限，超了按行切成多条
 
   /**
-   * 被动回复（带 msg_id，5 分钟内有效）。
+   * 被动回复（带 msg_id，群聊 5 分钟内、单聊 60 分钟内有效）。
    * **不会立刻发出**，而是攒到本次处理结束，由 flushReplies() 合并成一条。
    * 想立刻发用 msg.replyNow()。
    */
@@ -446,7 +446,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
    * 引用回复：以「引用某条消息」的样式发出去（官方 `message_reference`）。
    *
    * 跟 `reply()` 不是一回事：
-   *   - `reply()` 是**被动回复**，靠 msg_id，5 分钟内、同一条最多 5 次
+   *   - `reply()` 是**被动回复**，靠 msg_id，群聊 5 分钟 / 5 次，单聊 60 分钟 / 4 次
    *   - 这个是**引用**，靠 `REFIDX`，视觉上带"回复某某"的引用块
    *
    * 默认引用当前这条消息（用它的 `msg_idx`）。想引用别的传 `refIdx`。

package/src/outbound.js

@@ -20,15 +20,36 @@ const log = createLogger('outbound');
  * 插件只管调 msg.reply()，剩下的交给这里。
  */
 
-/** 官方给的有效期是 5 分钟，留 15 秒给网络和服务端时钟差 */
-const PASSIVE_WINDOW_MS = 5 * 60 * 1000;
-const PASSIVE_SAFE_MS = PASSIVE_WINDOW_MS - 15_000;
+/**
+ * 被动回复窗口。**两个接口不一样，别再用一个值。**
+ *
+ *   群聊 `/v2/groups/{group_openid}/messages`：5 分钟、最多 5 次
+ *   单聊 `/v2/users/{user_openid}/messages`：**60 分钟、最多 4 次**
+ *
+ * 以前两者共用「5 分钟 / 5 次」（群聊的口径），单聊的后果是：
+ *   · 5 分钟后就降级成主动消息，白吃「每个好友 1000 条/天」的额度，
+ *     而被动回复本来不占主动额度；
+ *   · 第 5 次回复会被服务端拒（40034128）。
+ *
+ * 各留 15 秒给网络和服务端时钟差。
+ */
+const PASSIVE_WINDOW_MS = {
+  group: 5 * 60 * 1000,
+  c2c: 60 * 60 * 1000,
+};
+const PASSIVE_SAFE_MS = {
+  group: PASSIVE_WINDOW_MS.group - 15_000,
+  c2c: PASSIVE_WINDOW_MS.c2c - 15_000,
+};
 
 /**
- * 官方硬限制：同一条消息最多回复 5 次（`msg_seq` 取 1–5）。
- * 第 6 次服务端会返回 40034128「被动回复时间或次数超限」。
+ * 同一条消息最多回复次数：群聊 5、单聊 4。
+ * 超过会返回 40034128「被动回复时间或次数超限」。
  */
-const PASSIVE_MAX_REPLIES = 5;
+const PASSIVE_MAX_REPLIES = {
+  group: 5,
+  c2c: 4,
+};
 
 /** 主动消息进入审核的返回码，属于正常结果 */
 const CODE_AUDIT = 304023;
@@ -245,11 +266,12 @@ export class Outbound {
     // 1) 被动窗口检查：快过期就别发请求了，直接按主动消息处理
     if (wantPassive) {
       const age = receivedAt ? Date.now() - receivedAt : 0;
-      if (age > PASSIVE_SAFE_MS) {
+      const safeMs = PASSIVE_SAFE_MS[kind];
+      if (age > safeMs) {
         if (!this.downgrade) {
           this.stats.expired += 1;
           throw new SendError(
-            `这条消息已经过去 ${Math.round(age / 1000)} 秒，超过 QQ 的 5 分钟被动回复窗口，回复发不出去了`,
+            `这条消息已经过去 ${Math.round(age / 1000)} 秒，超过 QQ 的 ${Math.round(safeMs / 1000)} 秒被动回复窗口，回复发不出去了`,
             'expired',
           );
         }
@@ -267,17 +289,18 @@ export class Outbound {
     // 2) 排队 + 限速 + 额度扣减 + 实际发送
     //    额度的「查」和「扣」都放在队列里，避免两个并发推送同时通过检查后超额
     return this.#enqueue(chatKey, async () => {
-      // 2a) 被动回复次数上限：官方「每个消息最多回复 5 次」
+      // 2a) 被动回复次数上限：群聊 5 次、单聊 4 次
       //     同一条消息被多个插件连着回、或用户一句话触发多轮时很容易撞上，
       //     本地先拦，省得服务端返回 40034128 再兜底
       let passiveNow = wantPassive && !active;
       if (passiveNow) {
+        const maxReplies = PASSIVE_MAX_REPLIES[kind];
         const used = this.passiveCount.get(body.msgId) ?? 0;
-        if (used >= PASSIVE_MAX_REPLIES) {
+        if (used >= maxReplies) {
           if (!this.downgrade) {
             this.stats.expired += 1;
             throw new SendError(
-              `同一条消息最多回复 ${PASSIVE_MAX_REPLIES} 次（QQ 官方限制），这条已经回满了。\n` +
+              `同一条消息最多回复 ${maxReplies} 次（QQ 官方限制），这条已经回满了。\n` +
                 `等用户再说一句，就能继续用被动回复。`,
               'expired',
             );

package/src/paths.js

@@ -113,6 +113,8 @@ export function botPaths(id) {
     groups: path.join(base, 'groups.json'),
     roles: path.join(base, 'roles.json'),
     quota: path.join(base, 'quota.json'),
+    /** 可达性（好友关系 / 主动推送开关），官方无查询接口，靠事件维护 */
+    reach: path.join(base, 'reach.json'),
     /** 统计库（SQLite，存消息计数与成员活跃，不存正文） */
     stats: path.join(base, 'stats.db'),
     pluginState: path.join(base, 'plugins.json'),

package/src/plugin/context.js

@@ -302,7 +302,7 @@ export class PluginStorage {
 /**
  * 插件上下文：插件能用的全部能力都在这里，不暴露内部实现。
  */
-export function createContext({ meta, paths, registry, api, cfg, config, configStore, groups, roles, levels, outbound, session, pipeline, isOwner, pages = null, routes = null, state = null }) {
+export function createContext({ meta, paths, registry, api, cfg, config, configStore, groups, roles, levels, outbound, session, pipeline, reach, isOwner, pages = null, routes = null, state = null }) {
   const id = meta.id;
   // 日志 tag 带机器人 id，多机器人下同名插件的日志不会串
   const logger = createLogger(`plugin:${paths?.id ?? '-'}:${id}`);
@@ -343,6 +343,13 @@ export function createContext({ meta, paths, registry, api, cfg, config, configS
     state: state ?? {},
     api,
     logger,
+    /**
+     * 可达性：`ctx.reach.canC2C(openid)` / `ctx.reach.canGroupPush(groupOpenid)`。
+     *
+     * 返回 `{ verdict: 'yes'|'no'|'unknown', reason? }`。
+     * **`unknown` 不能当 `no` 用**——未知是「不知道」，不是「不行」。
+     */
+    reach,
     storage: new PluginStorage(paths.pluginData(id)),
 
     /**

package/src/plugin/loader.js

@@ -27,7 +27,7 @@ const log = createLogger('plugins');
  * 启用状态存在 data/bots/<机器人id>/plugins.json，删掉文件夹即等于卸载。
  */
 export class PluginManager {
-  constructor({ pluginsDir, paths, registry, api, cfg, goBin, groups, roles, outbound, session, pipeline, isOwner, ignoreCompat }) {
+  constructor({ pluginsDir, paths, registry, api, cfg, goBin, groups, roles, outbound, session, pipeline, isOwner, reach, ignoreCompat }) {
     this.dir = pluginsDir;
     // 该机器人的全套路径（配置/数据/日志），多机器人下互不干扰
     this.paths = paths;
@@ -41,6 +41,8 @@ export class PluginManager {
     this.outbound = outbound;
     this.session = session;
     this.pipeline = pipeline;
+    /** 可达性（能不能私聊/能不能往这个群主动推），见 src/reach.js */
+    this.reach = reach;
     this.isOwner = isOwner;
     /** 跳过插件声明的 frameworkVersion 校验（作者本地调试用） */
     this.ignoreCompat = Boolean(ignoreCompat);
@@ -407,6 +409,7 @@ export class PluginManager {
       outbound: this.outbound,
       session: this.session,
       pipeline: this.pipeline,
+      reach: this.reach,
       isOwner: this.isOwner,
       pages: this.pages,
       routes: this.routes,

package/src/plugin/market.js

@@ -251,6 +251,69 @@ export async function verifyPluginDir(entry, dir) {
  * @param {number} [o.timeoutMs]
  * @param {(msg:string)=>void} [o.onRetry]
  */
+/**
+ * 单个文件的 GitHub raw 地址。
+ * 走 `fetchViaMirror`，所以自定义镜像 / 代理一样生效。
+ */
+function githubRawUrl(repo, ref, filePath) {
+  const p = String(filePath ?? '')
+    .split('/')
+    .map((s) => encodeURIComponent(s))
+    .join('/');
+  return `https://raw.githubusercontent.com/${repo}/${encodeURIComponent(ref)}/${p}`;
+}
+
+/**
+ * 把 Gitee 拉不下来的那几个文件，**逐个**从 GitHub 补回来。
+ *
+ * 为什么只补这几个而不是整包重拉：Gitee 的 451 是**按文件**来的 —— douluo
+ * 那么大一个插件只有 4 个文件被挡，其余都拉成功了。为 4 个文件重拉整包
+ * （几十上百个文件）纯属浪费，国内网络下很容易再断一次。
+ *
+ * @param {Array<{path:string,error:string}>} failed fetchGiteeTree 返回的失败清单
+ * @param {(url:string, init?:object)=>Promise<Response>} [fetcher] 取数函数，默认
+ *   走镜像。**给测试注入假网络用**，正常调用不需要传。
+ * @returns {Promise<Array<{path:string,error:string}>>} 补拉后仍然失败的（空数组 = 全补齐了）
+ *
+ * @internal 导出只为可测（selftest 里用它跑假网络），不是公共 API。
+ */
+export async function backfillFromGitHub({
+  repo,
+  branch,
+  destDir,
+  failed,
+  timeoutMs = 120000,
+  onProgress,
+  fetcher = fetchViaMirror,
+}) {
+  const still = [];
+  for (const item of failed) {
+    const dest = path.resolve(path.join(destDir, item.path));
+    // 清单来自服务端，仍按不可信处理，防路径穿越
+    const base = path.resolve(destDir);
+    if (dest !== base && !dest.startsWith(base + path.sep)) {
+      still.push({ path: item.path, error: '越界路径' });
+      continue;
+    }
+    try {
+      const res = await fetcher(githubRawUrl(repo, branch, item.path), {
+        headers: { 'User-Agent': 'qq-bot-roost' },
+        signal: AbortSignal.timeout(Math.min(timeoutMs, 30000)),
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const buf = Buffer.from(await res.arrayBuffer());
+      if (!buf.length) throw new Error('内容是空的');
+      await fs.mkdir(path.dirname(dest), { recursive: true });
+      await fs.writeFile(dest, buf);
+      log.info(`已从 GitHub 补齐 ${item.path}（Gitee 上拉不到）`);
+      onProgress?.(`补齐 ${item.path}`);
+    } catch (e) {
+      still.push({ path: item.path, error: `Gitee 失败后 GitHub 也失败：${e.message}` });
+    }
+  }
+  return still;
+}
+
 async function downloadRepoContents({
   repo,
   branch,
@@ -259,13 +322,53 @@ async function downloadRepoContents({
   expectSha256 = null,
   timeoutMs = 120000,
   onRetry,
+  onProgress,
 }) {
   const id = currentMirror().id;
   const token = currentMirror().giteeToken;
 
-  if (id === 'gitee') {
-    return fetchGiteeTree({ repo, ref: branch, destDir, only, timeoutMs, token });
-  }
+  /**
+   * Gitee 路径统一走这里：允许部分失败，再用 GitHub 把缺口补上。
+   * `allowPartial` 打开后 fetchGiteeTree 不再抛错，失败清单交给下面处理。
+   */
+  const viaGitee = async () => {
+    const r = await fetchGiteeTree({
+      repo,
+      ref: branch,
+      destDir,
+      only,
+      timeoutMs,
+      token,
+      allowPartial: true,
+    });
+    if (!r.failed?.length) return r;
+    log.warn(
+      `Gitee 上有 ${r.failed.length} 个文件拉不到（常见原因是 451 内容审查），` +
+        `改用 GitHub 逐个补齐：${r.failed.slice(0, 3).map((f) => f.path).join('、')}` +
+        (r.failed.length > 3 ? ' 等' : ''),
+    );
+    const still = await backfillFromGitHub({
+      repo,
+      branch,
+      destDir,
+      failed: r.failed,
+      timeoutMs,
+      onProgress,
+    });
+    if (still.length) {
+      throw new Error(
+        `${still.length} 个文件在 Gitee 和 GitHub 上都拉不到：\n  ` +
+          still
+            .slice(0, 5)
+            .map((f) => `${f.path}（${f.error}）`)
+            .join('\n  ') +
+          '\n可以在面板「下载源」里换一个镜像再试。',
+      );
+    }
+    return { ...r, failed: [], backfilled: r.failed.length };
+  };
+
+  if (id === 'gitee') return viaGitee();
 
   try {
     return await fetchAndExtract(branchTarballUrl(repo, branch), destDir, {
@@ -280,7 +383,7 @@ async function downloadRepoContents({
     log.warn(`GitHub 下载失败（${e.message}），改用 Gitee 镜像`);
     // 清掉可能写了一半的残留，再整树重拉
     await fs.rm(destDir, { recursive: true, force: true }).catch(() => {});
-    return fetchGiteeTree({ repo, ref: branch, destDir, only, timeoutMs, token });
+    return viaGitee();
   }
 }