dsh-qq-digest 0.1.0 → 0.2.0

package/scripts/final-check.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * 发布前/后的全量自检：仓库、脱敏、测试、npm、GitHub、DSH 运行态，一次跑完。
+ *
+ * 用法：node scripts/final-check.mjs
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+let failures = 0;
+const ok = (label, detail) => console.log(`PASS  ${label}${detail ? `  ${detail}` : ''}`);
+const bad = (label, detail) => { console.log(`FAIL  ${label}${detail ? `  ${detail}` : ''}`); failures += 1; };
+const info = (label, detail) => console.log(`INFO  ${label}${detail ? `  ${detail}` : ''}`);
+
+function run(cmd, args, options = {}) {
+  try {
+    return {
+      ok: true,
+      out: execFileSync(cmd, args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...options }).trim(),
+    };
+  } catch (err) {
+    return { ok: false, out: String(err.stdout ?? '').trim(), err: String(err.stderr ?? err.message).trim() };
+  }
+}
+
+// ── 1. 仓库 ──────────────────────────────────────────────────────────────
+const log = run('git', ['log', '--oneline']);
+if (log.ok && log.out) {
+  const commits = log.out.split('\n');
+  ok('git 提交', `${commits.length} 个：${commits[0]}`);
+} else bad('git 提交读不到');
+
+const status = run('git', ['status', '--porcelain']);
+if (status.ok) {
+  if (status.out === '') ok('工作区干净');
+  else bad('工作区有未提交改动', status.out.split('\n').slice(0, 3).join(' | '));
+}
+
+const tracked = run('git', ['ls-files']);
+const fileCount = tracked.ok ? tracked.out.split('\n').filter(Boolean).length : 0;
+info('跟踪文件', `${fileCount} 个`);
+
+const remote = run('git', ['remote', '-v']);
+info('remote', remote.ok && remote.out ? remote.out.split('\n')[0] : '(未配置)');
+
+// ── 2. 脱敏 ──────────────────────────────────────────────────────────────
+// 敏感词**不能写在这个文件里**：本文件随 npm 包一起发布（package.json files 含 scripts），
+// 把真实 QQ 号/群号写进来，等于用「检查泄漏的脚本」本身泄漏一遍，而且它还会命中自己，
+// 于是永远报 4 项 FAIL。现在改为外部注入：
+//   QQ_DIGEST_SENSITIVE_PATTERNS="123456,88888888" node scripts/final-check.mjs
+const PATTERNS = String(process.env.QQ_DIGEST_SENSITIVE_PATTERNS ?? '')
+  .split(',')
+  .map((value) => value.trim())
+  .filter((value) => value !== '');
+
+// 排除检查器自身：否则只要配了词，就必然命中这个文件。
+const GREP_EXCLUDE = [':(exclude)scripts/final-check.mjs'];
+
+let leak = 0;
+if (PATTERNS.length === 0) {
+  info('脱敏', '未设置 QQ_DIGEST_SENSITIVE_PATTERNS，已跳过（仓库内不得残留个人标识）');
+} else {
+  for (const pattern of PATTERNS) {
+    const hit = run('git', ['grep', '-n', pattern, '--', '.', ...GREP_EXCLUDE]);
+    if (hit.ok && hit.out !== '') {
+      bad(`仓库里仍有 ${pattern}`, hit.out.split('\n').slice(0, 2).join(' | '));
+      leak += 1;
+    }
+  }
+  if (leak === 0) ok('仓库内无个人标识（QQ/群号/用户名）');
+}
+
+const bridgePath = join(root, 'src', 'adapters', 'bridge.js');
+const bridgeSrc = run('node', ['-e', `process.stdout.write(require('node:fs').readFileSync(${JSON.stringify(bridgePath)},'utf8'))`]);
+if (bridgeSrc.ok && /resolveBridgePaths/.test(bridgeSrc.out)) ok('桥接路径可解析（无硬编码目录）');
+else bad('bridge.js 仍在硬编码路径');
+
+// ── 3. 测试 ──────────────────────────────────────────────────────────────
+const tests = run('node', ['--test']);
+const summary = (tests.out.match(/# tests (\d+)/) ?? tests.out.match(/ℹ tests (\d+)/) ?? [])[1];
+const failed = (tests.out.match(/# fail (\d+)/) ?? tests.out.match(/ℹ fail (\d+)/) ?? [])[1];
+if (tests.ok && failed === '0') ok('单元/集成测试', `${summary} 用例全过`);
+else bad('测试失败', `fail=${failed ?? '?'}`);
+
+const purity = run('node', ['scripts/check-core-purity.mjs']);
+if (purity.ok) ok('core 纯净性', purity.out.split('\n')[0].slice(0, 60));
+else bad('core 纯净性检查失败', purity.out);
+
+const smoke = run('node', ['scripts/host-smoke.mjs']);
+const smokeLine = (smoke.out.match(/(\d+)\/(\d+) 通过/) ?? []).slice(1).join('/');
+if (smoke.ok && smokeLine && smokeLine.split('/')[0] === smokeLine.split('/')[1]) ok('宿主冒烟', `${smokeLine} 通过`);
+else bad('宿主冒烟失败', smokeLine || smoke.out.slice(-200));
+
+// ── 4. npm ──────────────────────────────────────────────────────────────
+const whoami = run('npm', ['whoami'], { shell: true });
+info('npm 登录', whoami.ok ? whoami.out : '(未登录)');
+
+try {
+  const res = await fetch('https://registry.npmjs.org/dsh-qq-digest', { signal: AbortSignal.timeout(15000) });
+  if (res.status === 404) {
+    info('npm 包', '尚未创建');
+  } else {
+    const meta = await res.json();
+    const versions = Object.keys(meta.versions ?? {});
+    const latest = meta['dist-tags']?.latest;
+    info('npm 版本', versions.join(', ') || '(无)');
+    info('npm latest', String(latest));
+    info('npm maintainer', (meta.maintainers ?? []).map((m) => `${m.name}<${m.email}>`).join(', ') || '(无)');
+
+    if (versions.some((v) => v !== '0.0.0-stage')) {
+      ok('npm 已有正式版本', versions.filter((v) => v !== '0.0.0-stage').join(', '));
+    } else {
+      bad('npm 只有占位版 0.0.0-stage —— 暂存版本仍未批准', String(latest));
+    }
+  }
+} catch (err) {
+  bad('npm registry 查询失败', String(err.message));
+}
+
+// ── 5. GitHub ───────────────────────────────────────────────────────────
+const lsRemote = run('git', ['ls-remote', 'origin'], {
+  env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  timeout: 20000,
+});
+if (lsRemote.ok && lsRemote.out !== '') {
+  const heads = lsRemote.out.split('\n').filter((line) => line.includes('refs/heads/'));
+  ok('GitHub 仓库可达', heads.length ? heads.map((h) => h.split('refs/heads/')[1]).join(',') : '(空仓库)');
+} else if (lsRemote.ok) {
+  info('GitHub 仓库', '存在但为空，可以直接 push');
+} else {
+  bad('GitHub 仓库不可达', lsRemote.err.split('\n').slice(0, 2).join(' '));
+}
+
+/**
+ * 猜不出端口就等于误报。这里从 DSH 自己留下的痕迹里取：
+ *  1) QQ_DIGEST_PORT（显式）
+ *  2) ~/.dsh/dsh-process.json 里记录的端口
+ *  3) 几个历史默认端口兜底
+ */
+function detectDshPorts() {
+  const ports = new Set([8784, 1402, 14802]);
+  try {
+    const home = process.env.DSH_HOME && process.env.DSH_HOME.trim() !== ''
+      ? process.env.DSH_HOME.trim()
+      : join(homedir(), '.dsh');
+    const parsed = JSON.parse(readFileSync(join(home, 'dsh-process.json'), 'utf8'));
+    for (const value of [parsed?.port, parsed?.webPort, parsed?.web?.port]) {
+      if (Number.isInteger(value) && value > 0) ports.add(value);
+    }
+  } catch {
+    // 没有就只试兜底端口
+  }
+  return [...ports];
+}
+
+// ── 6. DSH 运行态 ───────────────────────────────────────────────────────
+// DSH 的 Web 端口每次重启都可能变（同一台机器实测过 4845 / 1875 / 4260），
+// 因此优先用显式指定，其次才试历史端口，最后直接问 DSH 的进程信息。
+const explicitPort = process.env.QQ_DIGEST_PORT
+  || (process.argv.find((arg) => arg.startsWith('--port=')) ?? '').split('=')[1]
+  || '';
+const candidatePorts = [
+  ...(explicitPort === '' ? [] : [Number(explicitPort)]),
+  ...detectDshPorts(),
+];
+let base = null;
+for (const port of candidatePorts) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/qq-digest-api/state`, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (res.status === 200) { base = `http://127.0.0.1:${port}`; break; }
+  } catch { /* 下一个端口 */ }
+}
+
+if (base === null) {
+  bad('DSH 里插件没在跑', `试过端口：${candidatePorts.join(', ') || '(无)'}；可用 QQ_DIGEST_PORT=<端口> 指定`);
+} else {
+  const state = await (await fetch(`${base}/qq-digest-api/state`, { headers: { accept: 'application/json' } })).json();
+  ok('宿主半在线', base);
+  if (typeof state.groupsEnabled === 'boolean') ok('群聊总开关在位', String(state.groupsEnabled));
+  else bad('宿主半是旧版本（缺 groupsEnabled）—— 需要重启 DSH');
+  if (Array.isArray(state.privateRooms)) {
+    ok('私聊列表中', `${state.privateRooms.length} 条，打开 ${state.privateRooms.filter((r) => r.enabled).length} 条`);
+  } else bad('宿主半是旧版本（缺 privateRooms）');
+  info('群数', String((state.rooms ?? []).length));
+  info('客户端心跳', state.clientBoot ? (state.clientBoot.mountedAt ? '已注册设置页' : `未注册（${state.clientBoot.lastError ?? state.clientBoot.lastPhase}）`) : '(旧版宿主无此字段)');
+}
+
+console.log(`\n${failures === 0 ? '全部通过' : `${failures} 项失败`}`);
+process.exit(failures === 0 ? 0 : 1);

package/scripts/host-smoke.mjs

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/**
+ * 宿主半冒烟：不启动 DSH，直接用一个假 ctx 把 apply() 跑起来，
+ * 再对着它注册的 HTTP 路由发真实的 req/res 对象。
+ *
+ * 这能提前抓到「路由没注册 / 路径写错 / JSON 形状不对 / 私聊没被拒」，
+ * 不必等到重启 DSH 之后才在设置页里发现。
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+
+const dataDir = mkdtempSync(join(tmpdir(), 'qq-digest-host-'));
+process.env.QQ_DIGEST_DATA_DIR = dataDir;
+process.env.QQ_DIGEST_SOURCE = process.env.QQ_DIGEST_SOURCE || 'fixture';
+
+const { apply } = await import('../lib/index.js');
+
+let captured = null;
+const ctx = {
+  webServer: {
+    register(options) {
+      captured = options;
+      return () => {};
+    },
+  },
+  effect(fn) {
+    const disposer = fn();
+    return () => {};
+  },
+  get() {
+    return undefined;
+  },
+  logger: { info() {}, warn() {} },
+};
+
+apply(ctx);
+
+if (captured === null) {
+  console.error('FAIL: 没有注册任何路由');
+  process.exit(1);
+}
+if (captured.kind !== 'prefix' || captured.path !== '/qq-digest-api') {
+  console.error(`FAIL: 路由形状不对 ${JSON.stringify({ kind: captured.kind, path: captured.path })}`);
+  process.exit(1);
+}
+
+function request(handler, { method = 'GET', url, body, headers = {}, remoteAddress = '127.0.0.1' }) {
+  return new Promise((resolve, reject) => {
+    const req = new Readable({ read() {} });
+    req.method = method;
+    req.url = url;
+    // 真实请求一定带 Host；写操作还带 content-type。
+    // 宿主半现在会校验 Host / Origin / Sec-Fetch-Site，所以这里要把「正常浏览器」的形状补齐。
+    req.headers = {
+      host: '127.0.0.1:4845',
+      ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+      ...headers,
+    };
+    req.socket = { remoteAddress };
+    if (body !== undefined) req.push(JSON.stringify(body));
+    req.push(null);
+
+    const chunks = [];
+    const res = {
+      statusCode: 200,
+      headers: {},
+      writeHead(status, headers) {
+        this.statusCode = status;
+        this.headers = headers ?? {};
+      },
+      end(chunk) {
+        if (chunk) chunks.push(Buffer.from(chunk));
+        const text = Buffer.concat(chunks).toString('utf8');
+        try {
+          resolve({ status: this.statusCode, json: JSON.parse(text) });
+        } catch {
+          reject(new Error(`非 JSON 响应：${text.slice(0, 200)}`));
+        }
+      },
+    };
+
+    handler(req, res);
+  });
+}
+
+const results = [];
+function check(name, condition, detail) {
+  results.push({ name, ok: Boolean(condition), detail });
+}
+
+const state = await request(captured.handler, { url: '/qq-digest-api/state' });
+check('GET /state 返回 200', state.status === 200, state.status);
+check('状态里有 groups 数组', Array.isArray(state.json.rooms), typeof state.json.rooms);
+check('只暴露群', (state.json.rooms ?? []).every((room) => /^\d+$/.test(String(room.groupId))), JSON.stringify(state.json.rooms?.slice(0, 2)));
+check('fixture 下应看到 2 个群', (state.json.rooms ?? []).length === 2, (state.json.rooms ?? []).length);
+check('默认群聊总开关是开的', state.json.groupsEnabled === true, state.json.groupsEnabled);
+check('私聊单独成列且默认全关', Array.isArray(state.json.privateRooms) && state.json.privateRooms.length === 1 && state.json.privateRooms[0].enabled === false, JSON.stringify(state.json.privateRooms));
+
+const saved = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/config',
+  body: { groups: { '100000': { enabled: false } }, summarizer: 'heuristic', schedule: { enabled: true, kind: 'daily', time: '09:30', weekdays: ['MO'], timeZone: 'Asia/Shanghai' } },
+});
+check('POST /config 保存成功', saved.status === 200 && saved.json.ok === true, saved.status);
+check('关掉的群出现在配置里', saved.json.config?.groups?.['group:100000']?.enabled === false, JSON.stringify(saved.json.config?.groups));
+check('定时时间被保存', saved.json.config?.schedule?.time === '09:30', saved.json.config?.schedule?.time);
+
+const afterSave = await request(captured.handler, { url: '/qq-digest-api/state' });
+const closed = (afterSave.json.rooms ?? []).find((room) => room.groupId === '100000');
+check('关掉的群在列表里标记为关闭', closed?.enabled === false, JSON.stringify(closed));
+
+const privateAttempt = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/config',
+  body: { groups: { '88880001-private': { enabled: true }, 'private:88880001': { enabled: true } } },
+});
+check('私聊 id 被拒（400）', privateAttempt.status === 400, `${privateAttempt.status} ${JSON.stringify(privateAttempt.json)}`);
+
+const badTime = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/config',
+  body: { groups: {}, summarizer: 'heuristic', schedule: { enabled: true, kind: 'daily', time: '9:3', weekdays: ['MO'], timeZone: 'Asia/Shanghai' } },
+});
+check('非法时间被拒（400）', badTime.status === 400, `${badTime.status} ${JSON.stringify(badTime.json)}`);
+
+const privSave = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/config',
+  body: { groupsEnabled: false, groups: {}, private: { '88880001': { enabled: true, name: '测试私聊' } }, summarizer: 'heuristic', schedule: { enabled: false, kind: 'daily', time: '09:00', weekdays: ['MO'], timeZone: 'Asia/Shanghai' } },
+});
+check('可以逐条打开私聊', privSave.status === 200, privSave.status);
+check('总开关可以关掉', privSave.json.state?.groupsEnabled === false, privSave.json.state?.groupsEnabled);
+check('私聊开关落盘', privSave.json.state?.privateRooms?.[0]?.enabled === true, JSON.stringify(privSave.json.state?.privateRooms));
+check('私聊名字落盘', privSave.json.state?.privateRooms?.[0]?.name === '测试私聊', privSave.json.state?.privateRooms?.[0]?.name);
+
+const blockedRun = await request(captured.handler, { method: 'POST', url: '/qq-digest-api/run', body: {} });
+const blockedDenied = (blockedRun.json?.result?.denied ?? []).filter((item) => item.reason === 'GROUP_DISABLED');
+check('总开关关掉后所有群都被拒（单群覆盖也失效）', blockedDenied.length === 2, blockedDenied.length);
+
+const restore = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/config',
+  body: { groupsEnabled: true, groups: {}, private: { '88880001': { enabled: false } }, summarizer: 'heuristic', schedule: { enabled: false, kind: 'daily', time: '09:00', weekdays: ['MO'], timeZone: 'Asia/Shanghai' } },
+});
+check('可以再恢复默认', restore.status === 200 && restore.json.state?.groupsEnabled === true, restore.status);
+
+const run = await request(captured.handler, { method: 'POST', url: '/qq-digest-api/run', body: {} });
+check('POST /run 返回结果', run.status === 200 && typeof run.json.result?.status === 'string', JSON.stringify(run.json.result?.status));
+
+const digest = await request(captured.handler, { url: '/qq-digest-api/digest?group=70001111' });
+check('GET /digest 只认群号', digest.status === 200 || digest.json.digest === null, digest.status);
+
+const privateDigest = await request(captured.handler, { url: '/qq-digest-api/digest?group=private%3A1' });
+check('私聊句柄读不到摘要（400）', privateDigest.status === 400, privateDigest.status);
+
+// 客户端半心跳：证明「设置页看不见」时能分清是哪一层的问题
+const bootFactory = await request(captured.handler, { method: 'POST', url: '/qq-digest-api/client-boot', body: { phase: 'factory' } });
+check('POST /client-boot 接受 factory 心跳', bootFactory.status === 200, bootFactory.status);
+const bootMounted = await request(captured.handler, { method: 'POST', url: '/qq-digest-api/client-boot', body: { phase: 'mounted', sectionId: 'qq-digest' } });
+check('POST /client-boot 接受 mounted 心跳', bootMounted.status === 200, bootMounted.status);
+const withBoot = await request(captured.handler, { url: '/qq-digest-api/state' });
+check('状态里回显客户端心跳', Boolean(withBoot.json.clientBoot?.factoryAt && withBoot.json.clientBoot?.mountedAt), JSON.stringify(withBoot.json.clientBoot));
+
+const notFound = await request(captured.handler, { url: '/qq-digest-api/nope' });
+check('未知路径 404', notFound.status === 404, notFound.status);
+
+// 重名：群和私聊同名必须被拒（放在最后，避免改动状态影响前面的用例）
+const dupSave = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/config',
+  body: { groupsEnabled: true, groups: { '100000': { enabled: true, name: '重名' } }, private: { '88880001': { enabled: false, name: '重名' } }, summarizer: 'heuristic', schedule: { enabled: false, kind: 'daily', time: '09:00', weekdays: ['MO'], timeZone: 'Asia/Shanghai' } },
+});
+check('群与私聊同名 → 400', dupSave.status === 400 && String(dupSave.json.error ?? '').includes('DUPLICATE_NAME'), `${dupSave.status} ${JSON.stringify(dupSave.json)}`);
+
+const uniqueSave = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/config',
+  body: { groupsEnabled: true, groups: { '100000': { enabled: true, name: '甲' } }, private: { '88880001': { enabled: false, name: '乙' } }, summarizer: 'heuristic', schedule: { enabled: false, kind: 'daily', time: '09:00', weekdays: ['MO'], timeZone: 'Asia/Shanghai' } },
+});
+check('名字互不相同 → 200', uniqueSave.status === 200, uniqueSave.status);
+
+
+// ── 管理面来源校验（跨站 / rebinding / 隧道 / CSRF）──────────────────────
+// 这些用例锁住的是「只判 remoteAddress 不够」这件事本身：
+// 每一条的攻击前提都能让 remoteAddress 看起来是回环。
+const evilOrigin = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/config',
+  body: { groupsEnabled: false },
+  headers: { origin: 'https://evil.example' },
+});
+check('跨站 Origin → 403', evilOrigin.status === 403 && evilOrigin.json.error === 'BAD_ORIGIN', `${evilOrigin.status} ${JSON.stringify(evilOrigin.json)}`);
+
+const evilHost = await request(captured.handler, { url: '/qq-digest-api/state', headers: { host: 'evil.example:4845' } });
+check('伪造 Host（DNS rebinding）→ 403', evilHost.status === 403 && evilHost.json.error === 'BAD_HOST', `${evilHost.status} ${JSON.stringify(evilHost.json)}`);
+
+const crossSite = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/run',
+  body: {},
+  headers: { 'sec-fetch-site': 'cross-site' },
+});
+check('Sec-Fetch-Site: cross-site → 403', crossSite.status === 403 && crossSite.json.error === 'CROSS_SITE', `${crossSite.status} ${JSON.stringify(crossSite.json)}`);
+
+const textPlain = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/config',
+  body: { groupsEnabled: true },
+  headers: { 'content-type': 'text/plain', origin: 'https://evil.example' },
+});
+check('text/plain 简单请求（CSRF）→ 被来源校验挡住', textPlain.status === 403 || textPlain.status === 415, `${textPlain.status} ${JSON.stringify(textPlain.json)}`);
+
+const sameOriginNoBody = await request(captured.handler, {
+  method: 'POST',
+  url: '/qq-digest-api/client-boot',
+  body: { phase: 'factory' },
+  headers: { origin: 'http://127.0.0.1:4845' },
+});
+check('同源 Origin + application/json → 放行', sameOriginNoBody.status === 200, `${sameOriginNoBody.status} ${JSON.stringify(sameOriginNoBody.json)}`);
+
+const nonLoopback = await request(captured.handler, { url: '/qq-digest-api/state', remoteAddress: '192.168.1.10' });
+check('非回环来源 → 403 LOCAL_ONLY', nonLoopback.status === 403 && nonLoopback.json.error === 'LOCAL_ONLY', `${nonLoopback.status} ${JSON.stringify(nonLoopback.json)}`);
+
+for (const result of results) {
+  console.log(`${result.ok ? 'PASS' : 'FAIL'}  ${result.name}${result.detail === undefined ? '' : `  (${result.detail})`}`);
+}
+
+rmSync(dataDir, { recursive: true, force: true });
+
+const failed = results.filter((result) => !result.ok).length;
+console.log(`\n${results.length - failed}/${results.length} 通过`);
+process.exit(failed === 0 ? 0 : 1);

package/scripts/install.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * 把 qq-digest 接进 DSH profile —— 只做**本机接线**，不改任何源码。
+ *
+ * 做三件事：
+ *   1) 在 profile 的 cordis.patch.yml 里维护一段带标记的区块，插入 MCP 行；
+ *   2) 把本仓库的真实路径替换进安装片段（模板里是 __PACKAGE_ROOT__ 占位符，
+ *      这样仓库本身不携带作者机器的绝对路径）；
+ *   3) 把本机 qq-bridge 的位置写进 <DSH_HOME>/qq-digest/bridge-root.txt，
+ *      插件运行时靠它找到桥接（源码里不硬编码任何绝对路径）。
+ *
+ * 用法：
+ *   node scripts/install.mjs                      # 预览
+ *   node scripts/install.mjs --apply              # 写入（自动备份）
+ *   node scripts/install.mjs --apply --profile desktop
+ *   node scripts/install.mjs --apply --remove     # 移除 MCP 行
+ *   node scripts/install.mjs --apply --bridge-root=D:/path/to/qq-bridge
+ */
+
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const args = process.argv.slice(2);
+const apply = args.includes('--apply');
+const remove = args.includes('--remove');
+const profileArg = args.find((arg) => arg.startsWith('--profile='));
+const bridgeArg = args.find((arg) => arg.startsWith('--bridge-root='));
+const profile = profileArg ? profileArg.split('=')[1] : process.env.DSH_PROFILE || 'desktop';
+
+const BEGIN = '# === qq-digest MCP BEGIN ===';
+const END = '# === qq-digest MCP END ===';
+const BRIDGE_ROOT_FILE = 'bridge-root.txt';
+
+function resolveDshHome(env = process.env) {
+  const fromEnv = env.DSH_HOME;
+  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return resolve(fromEnv.trim());
+  return join(homedir(), '.dsh');
+}
+
+/** 找一个真实存在的 qq-bridge 目录（有 state/console-token 才算）。 */
+function detectBridgeRoot(explicit) {
+  const candidates = [
+    explicit,
+    process.env.QQ_DIGEST_BRIDGE_ROOT,
+    join(homedir(), 'AI', 'qq-bridge'),
+    process.env.USERNAME ? `D:/Users/${process.env.USERNAME}/AI/qq-bridge` : null,
+    process.env.USERNAME ? `C:/Users/${process.env.USERNAME}/AI/qq-bridge` : null,
+  ].filter((value) => typeof value === 'string' && value.trim() !== '');
+
+  for (const candidate of candidates) {
+    if (existsSync(join(candidate, 'state', 'console-token'))) return resolve(candidate);
+  }
+  return null;
+}
+
+const dshHome = resolveDshHome();
+const dataDir = join(dshHome, 'qq-digest');
+const patchFile = join(dshHome, 'profiles', profile, 'cordis.patch.yml');
+const bridgeRoot = detectBridgeRoot(bridgeArg ? bridgeArg.split('=').slice(1).join('=') : null);
+
+if (!existsSync(patchFile)) {
+  console.error(`找不到 profile 配置：${patchFile}`);
+  process.exit(1);
+}
+
+const fragment = readFileSync(join(root, 'install', 'cordis.patch.fragment.yml'), 'utf8');
+const block = fragment
+  .replace(/__PACKAGE_ROOT__/g, root.replace(/\\/g, '/'))
+  // node 可执行文件必须取当前这台机器上的真实路径：写死任何一台机器的路径，
+  // 换机安装都会 spawn ENOENT，而症状是「工具全部消失、插件却像是装好了」。
+  .replace(/__NODE_EXE__/g, process.execPath.replace(/\\/g, '/'))
+  .trimEnd();
+
+const current = readFileSync(patchFile, 'utf8');
+
+function stripBlock(text) {
+  const begin = text.indexOf(BEGIN);
+  if (begin === -1) return text;
+  const end = text.indexOf(END);
+  if (end === -1) return text;
+  return `${text.slice(0, begin)}${text.slice(end + END.length)}`.replace(/\n{3,}/g, '\n\n').trimEnd();
+}
+
+const withoutBlock = stripBlock(current);
+const next = remove ? `${withoutBlock}\n` : `${withoutBlock}\n\n${block}\n`;
+const changed = next !== current;
+
+console.log(`profile     = ${profile}`);
+console.log(`patch       = ${patchFile}`);
+console.log(`packageRoot = ${root.replace(/\\/g, '/')}`);
+console.log(`bridgeRoot  = ${bridgeRoot ?? '(没找到；插件会退回 ~/AI/qq-bridge)'}`);
+console.log(`action      = ${remove ? '移除 qq-digest 行' : '写入/更新 qq-digest 行'}`);
+console.log(`patch 变化  = ${changed ? 'yes' : 'no（已是目标状态）'}`);
+
+if (!apply) {
+  console.log('（预览模式：没有写入。加 --apply 才真正落盘。）');
+  process.exit(0);
+}
+
+if (changed) {
+  const backup = `${patchFile}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+  copyFileSync(patchFile, backup);
+  writeFileSync(patchFile, next, 'utf8');
+  console.log(`已写入。备份：${backup}`);
+} else {
+  console.log('profile patch 无需改动。');
+}
+
+// 本机桥接位置：只写一次，不覆盖用户已有设置
+if (!remove) {
+  const bridgeFile = join(dataDir, BRIDGE_ROOT_FILE);
+  if (bridgeRoot === null) {
+    console.log(`跳过 ${BRIDGE_ROOT_FILE}：没检测到 qq-bridge（可用 --bridge-root=... 指定）`);
+  } else if (existsSync(bridgeFile)) {
+    console.log(`${BRIDGE_ROOT_FILE} 已存在，保持不动：${bridgeFile}`);
+  } else {
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(bridgeFile, `${bridgeRoot.replace(/\\/g, '/')}\n`, 'utf8');
+    console.log(`已记录桥接位置：${bridgeFile}`);
+  }
+}
+
+console.log('重启 DSH 后生效（MCP 行通常可热加载，bundle 行需要重启）。');

package/scripts/link-profile.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * 把本包挂进 DSH profile —— 不经过 pnpm。
+ *
+ * 为什么不用 plugin_manager 的 install_bundle：本机 profile 的 node_modules 里有
+ * 文件被占用（@img/sharp-win32-x64 EPERM），pnpm 一跑就整批重装并中途失败。
+ * 这里只做两件不依赖网络的事：
+ *   1) 在 profile 的 node_modules 里建一个 junction 指向本仓库；
+ *   2) 在 profile 的 package.json 里登记依赖与 bundle 名单。
+ *
+ * 用法：
+ *   node scripts/link-profile.mjs            # 预览
+ *   node scripts/link-profile.mjs --apply    # 写入（自动备份 package.json）
+ *   node scripts/link-profile.mjs --apply --profile desktop
+ *   node scripts/link-profile.mjs --apply --remove
+ */
+
+import { copyFileSync, existsSync, lstatSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const PACKAGE_NAME = 'dsh-qq-digest';
+
+const args = process.argv.slice(2);
+const apply = args.includes('--apply');
+const remove = args.includes('--remove');
+const profileArg = args.find((arg) => arg.startsWith('--profile='));
+const profile = profileArg ? profileArg.split('=')[1] : process.env.DSH_PROFILE || 'desktop';
+
+function resolveDshHome() {
+  const fromEnv = process.env.DSH_HOME;
+  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return resolve(fromEnv.trim());
+  return join(homedir(), '.dsh');
+}
+
+const profileDir = join(resolveDshHome(), 'profiles', profile);
+const manifestPath = join(profileDir, 'package.json');
+const linkPath = join(profileDir, 'node_modules', PACKAGE_NAME);
+
+if (!existsSync(manifestPath)) {
+  console.error(`找不到 profile：${manifestPath}`);
+  process.exit(1);
+}
+
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+const deps = manifest.dependencies ?? {};
+const bundles = manifest.dsh?.profile?.bundles ?? [];
+
+const linkSpec = `link:${root.replace(/\\/g, '/')}`;
+const linked = existsSync(linkPath) && lstatSync(linkPath).isSymbolicLink();
+
+console.log(`profile   = ${profile}`);
+console.log(`package   = ${root}`);
+console.log(`junction  = ${linkPath}${linked ? '（已存在）' : '（待创建）'}`);
+console.log(`dep       = ${deps[PACKAGE_NAME] ?? '(未登记)'} → ${remove ? '(移除)' : linkSpec}`);
+console.log(`bundles   = ${bundles.includes(PACKAGE_NAME) ? '已登记' : '未登记'}`);
+
+if (!apply) {
+  console.log('（预览模式：没有写入。加 --apply 才真正落盘。）');
+  process.exit(0);
+}
+
+if (remove) {
+  if (linked) rmSync(linkPath, { recursive: false, force: true });
+  delete deps[PACKAGE_NAME];
+  manifest.dependencies = deps;
+  if (manifest.dsh?.profile) {
+    manifest.dsh.profile.bundles = bundles.filter((name) => name !== PACKAGE_NAME);
+  }
+} else {
+  if (!linked) {
+    if (existsSync(linkPath)) {
+      console.error(`目标已存在且不是 junction：${linkPath}（先手动确认再处理）`);
+      process.exit(1);
+    }
+    symlinkSync(root, linkPath, 'junction');
+    console.log('已创建 junction');
+  }
+  deps[PACKAGE_NAME] = linkSpec;
+  manifest.dependencies = deps;
+  manifest.dsh = manifest.dsh ?? {};
+  manifest.dsh.profile = manifest.dsh.profile ?? {};
+  const nextBundles = bundles.includes(PACKAGE_NAME) ? bundles : [...bundles, PACKAGE_NAME];
+  manifest.dsh.profile.bundles = nextBundles;
+}
+
+const backup = `${manifestPath}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+copyFileSync(manifestPath, backup);
+writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+
+console.log(`已写入 ${manifestPath}`);
+console.log(`备份：${backup}`);
+console.log('重启 DSH 后生效（bundle 的客户端半在启动时随页加载）。');