@tencent-connect/dsh-qqbot 0.5.0 → 0.5.1

package/dist/setup/bind-routes.js

@@ -0,0 +1,311 @@
+import { persistCredentialsToProfile, removeCredentialsFromProfile, updateProfileConfig, } from "./persist.js";
+import { getProfileDir } from "../shared/index.js";
+import { AccessControlSchema } from "../config.js";
+import { BIND_CONFIG_PATH, BIND_MANUAL_PATH, BIND_REFRESH_PATH, BIND_STATE_PATH, BIND_UNBIND_PATH, } from "../shared/bind-protocol.js";
+// 协议单一来源：shared/bind-protocol.ts（类型 + 路径常量，客户端共用）
+export { BIND_CONFIG_PATH, BIND_MANUAL_PATH, BIND_REFRESH_PATH, BIND_STATE_PATH, BIND_UNBIND_PATH };
+/** 可经 UI 编辑的配置键（白名单：只收用户必要的字段，其余走 patch/env） */
+const EDITABLE_CONFIG_KEYS = new Set([
+    'requireMention', 'streaming', 'showToolResults', 'debug',
+    'provider', 'model', 'preset',
+    'groupPrompt', 'directPrompt',
+    'access',
+]);
+/** 白名单键的子 Schema（服务端校验：客户端校验仅为体验，安全边界在宿主） */
+const EDITABLE_CONFIG_SCHEMAS = {
+    requireMention: (v) => booleanSchema(v, 'requireMention'),
+    streaming: (v) => booleanSchema(v, 'streaming'),
+    showToolResults: (v) => booleanSchema(v, 'showToolResults'),
+    debug: (v) => booleanSchema(v, 'debug'),
+    provider: stringSchema('provider'),
+    model: stringSchema('model'),
+    preset: stringSchema('preset'),
+    groupPrompt: stringSchema('groupPrompt'),
+    directPrompt: stringSchema('directPrompt'),
+    access: (v) => AccessControlSchema(v),
+};
+function booleanSchema(value, name) {
+    if (typeof value !== 'boolean')
+        throw new TypeError(`${name} 必须是布尔值`);
+    return value;
+}
+function stringSchema(name) {
+    return (value) => {
+        if (typeof value !== 'string')
+            throw new TypeError(`${name} 必须是字符串`);
+        if (value.length > 20000)
+            throw new TypeError(`${name} 过长`);
+        return value;
+    };
+}
+/** manual 请求体大小上限（appId + appSecret 远小于此值） */
+const MAX_MANUAL_BODY_BYTES = 4096;
+/**
+ * 注册绑定路由（状态查询 / 刷新二维码 / 手动凭据）。
+ *
+ * @param webServer - ctx.webServer
+ * @param service - 绑定状态机；已绑定 fiber 传 null（无扫码流程）
+ * @param logger - 日志
+ * @param options - 行为注入（bound 态回显、manual 处理）
+ * @returns 注销函数（与插件 fiber 生命周期绑定）
+ */
+export function registerBindRoutes(webServer, service, logger, options = {}) {
+    const defaultManual = (credentials) => {
+        const persisted = persistCredentialsToProfile(credentials, getProfileDir() ?? undefined, logger);
+        return persisted ? { persisted: true } : { persisted: false, error: '无法定位 profile 目录或写入失败，请改用环境变量配置' };
+    };
+    const handleManualSubmit = options.onManualCredentials ?? defaultManual;
+    const disposers = [
+        webServer.register({
+            kind: 'exact',
+            path: BIND_STATE_PATH,
+            handler: (req, res) => { handleState(req, res, service, options); },
+        }),
+        webServer.register({
+            kind: 'exact',
+            path: BIND_REFRESH_PATH,
+            handler: (req, res) => { handleRefresh(req, res, service); },
+        }),
+        webServer.register({
+            kind: 'exact',
+            path: BIND_MANUAL_PATH,
+            handler: (req, res) => handleManual(req, res, handleManualSubmit),
+        }),
+        webServer.register({
+            kind: 'exact',
+            path: BIND_UNBIND_PATH,
+            handler: (req, res) => handleUnbind(req, res, options),
+        }),
+        webServer.register({
+            kind: 'exact',
+            path: BIND_CONFIG_PATH,
+            handler: (req, res) => handleConfig(req, res, options),
+        }),
+    ];
+    logger.info(`im-qqbot: 端内绑定页已就绪: ${BIND_STATE_PATH}`);
+    return () => { for (const dispose of disposers)
+        dispose(); };
+}
+/**
+ * 请求来源校验（最小 CSRF 防护）。
+ *
+ * 带 Origin 的请求必须与 Host 同源；同源 fetch 与 Desktop IPC 桥
+ * （后者会删除 origin 头）均放行。本路由数据不敏感且动作无害，
+ * 该级别的防护足够。
+ */
+function trusted(req) {
+    const origin = req.headers.origin;
+    if (origin === undefined)
+        return true;
+    try {
+        return new URL(origin).host === req.headers.host;
+    }
+    catch {
+        return false;
+    }
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+    });
+    res.end(payload);
+}
+function handleState(req, res, service, options) {
+    if (!trusted(req)) {
+        sendJson(res, 403, { error: 'forbidden' });
+        return;
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        sendJson(res, 405, { error: 'method not allowed' });
+        return;
+    }
+    // 已绑定优先（appSecret 不回传，appId 非机密可回显）
+    const boundAppId = options.boundAppId?.() ?? null;
+    if (boundAppId !== null) {
+        sendJson(res, 200, { phase: 'bound', appId: boundAppId });
+        return;
+    }
+    sendJson(res, 200, service === null ? { phase: 'starting' } : service.wireState());
+}
+function handleRefresh(req, res, service) {
+    if (!trusted(req)) {
+        sendJson(res, 403, { error: 'forbidden' });
+        return;
+    }
+    if (req.method !== 'POST') {
+        sendJson(res, 405, { error: 'method not allowed' });
+        return;
+    }
+    // 丢弃可能的请求体（refresh 无参数）
+    req.resume();
+    service?.refresh();
+    // 新二维码异步生成，统一由状态轮询收敛
+    sendJson(res, 200, { phase: 'starting' });
+}
+/** 读取并解析 JSON 请求体（带大小上限） */
+async function readJsonBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = chunk;
+        size += buffer.length;
+        if (size > MAX_MANUAL_BODY_BYTES)
+            throw new Error('request body too large');
+        chunks.push(buffer);
+    }
+    if (size === 0)
+        throw new Error('empty request body');
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+/** 校验手动提交的凭据形态（不打印内容） */
+function parseCredentials(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const record = body;
+    const appId = typeof record.appId === 'string' ? record.appId.trim() : '';
+    const appSecret = typeof record.appSecret === 'string' ? record.appSecret.trim() : '';
+    if (appId.length === 0 || appSecret.length === 0)
+        return null;
+    if (appId.length > 128 || appSecret.length > 256)
+        return null;
+    return { appId, appSecret };
+}
+async function handleManual(req, res, submit) {
+    if (!trusted(req)) {
+        sendJson(res, 403, { error: 'forbidden' });
+        return;
+    }
+    if (req.method !== 'POST') {
+        sendJson(res, 405, { error: 'method not allowed' });
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (err) {
+        sendJson(res, 400, { ok: false, error: `invalid request body: ${err instanceof Error ? err.message : String(err)}` });
+        return;
+    }
+    const credentials = parseCredentials(body);
+    if (credentials === null) {
+        sendJson(res, 400, { ok: false, error: 'appId 与 appSecret 不能为空' });
+        return;
+    }
+    const result = submit(credentials);
+    if (!result.persisted) {
+        sendJson(res, 500, { ok: false, error: result.error ?? '保存失败' });
+        return;
+    }
+    // 写入 profile patch 触发 HMR 重载，新 fiber 以新凭据启动网关
+    sendJson(res, 200, { ok: true, message: '凭据已保存，插件将自动重载' });
+}
+/** 解绑：仅已绑定态可执行；移除 profile patch 中的凭据并触发 HMR 重载 */
+function handleUnbind(req, res, options) {
+    if (!trusted(req)) {
+        sendJson(res, 403, { error: 'forbidden' });
+        return;
+    }
+    if (req.method !== 'POST') {
+        sendJson(res, 405, { error: 'method not allowed' });
+        return;
+    }
+    req.resume();
+    if ((options.boundAppId?.() ?? null) === null) {
+        sendJson(res, 409, { ok: false, error: '当前未绑定' });
+        return;
+    }
+    const result = options.onUnbind === undefined
+        ? (() => {
+            const removed = removeCredentialsFromProfile(getProfileDir() ?? undefined, undefined);
+            if (removed) {
+                // 清除进程内凭据：扫码绑定成功时会写入 env（供热更新后的下次
+                // apply 兜底读取）；不清则 HMR 重载后新 fiber 仍从 env 读到
+                // 凭据，解绑不生效（状态一直停留在 bound）
+                delete process.env.QQBOT_APPID;
+                delete process.env.QQBOT_SECRET;
+            }
+            return removed
+                ? { persisted: true }
+                : { persisted: false, error: '无法定位 profile 目录或写入失败，请手动编辑 cordis.patch.yml' };
+        })()
+        : options.onUnbind();
+    if (!result.persisted) {
+        sendJson(res, 500, { ok: false, error: result.error ?? '解绑失败' });
+        return;
+    }
+    // 移除后写入触发 HMR 重载，插件回到未绑定态（绑定流程重新可用）
+    sendJson(res, 200, { ok: true, message: '已解绑，插件将重载并重新进入绑定流程' });
+}
+/**
+ * 配置读写：
+ * - GET：回显当前生效配置（appSecret 剔除，cwd 等只读字段正常返回）
+ * - POST：白名单 + 子 Schema 校验 → 最小写入 profile patch → HMR 重载
+ */
+async function handleConfig(req, res, options) {
+    if (!trusted(req)) {
+        sendJson(res, 403, { error: 'forbidden' });
+        return;
+    }
+    if (req.method !== 'GET' && req.method !== 'POST') {
+        sendJson(res, 405, { error: 'method not allowed' });
+        return;
+    }
+    if (req.method === 'GET') {
+        const current = options.currentConfig?.() ?? {};
+        // appSecret 永不回传；其余（含只读 cwd）原样回显
+        const { appSecret: _s, ...safe } = current;
+        sendJson(res, 200, { config: safe });
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (err) {
+        sendJson(res, 400, { ok: false, error: `invalid request body: ${err instanceof Error ? err.message : String(err)}` });
+        return;
+    }
+    if (typeof body !== 'object' || body === null) {
+        sendJson(res, 400, { ok: false, error: '请求体必须是 JSON 对象' });
+        return;
+    }
+    const submitted = body;
+    // 白名单与凭据/只读字段拦截
+    for (const key of Object.keys(submitted)) {
+        if (!EDITABLE_CONFIG_KEYS.has(key)) {
+            const reason = key === 'appId' || key === 'appSecret'
+                ? '凭据请使用绑定/更换/解绑功能'
+                : key === 'cwd'
+                    ? 'cwd 为只读字段'
+                    : '不支持的字段';
+            sendJson(res, 400, { ok: false, error: `${reason}: ${key}` });
+            return;
+        }
+    }
+    // 逐键 Schema 校验（非法值拒绝，返回首个错误）
+    let validated = {};
+    try {
+        validated = Object.fromEntries(Object.entries(submitted).map(([key, value]) => {
+            const check = EDITABLE_CONFIG_SCHEMAS[key];
+            if (check === undefined)
+                throw new TypeError(`不支持的字段: ${key}`);
+            return [key, check(value)];
+        }));
+    }
+    catch (err) {
+        sendJson(res, 400, { ok: false, error: err instanceof TypeError ? err.message : String(err) });
+        return;
+    }
+    const persisted = options.onUpdateConfig === undefined
+        ? updateProfileConfig(validated, getProfileDir() ?? undefined, undefined)
+        : options.onUpdateConfig(validated);
+    if (!persisted) {
+        sendJson(res, 500, { ok: false, error: '无法定位 profile 目录或写入失败' });
+        return;
+    }
+    sendJson(res, 200, { ok: true, message: '配置已保存，插件将自动重载（进行中的机器人会话将重置）' });
+}
+//# sourceMappingURL=bind-routes.js.map

package/dist/setup/bind-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-routes.js","sourceRoot":"","sources":["../../src/setup/bind-routes.ts"],"names":[],"mappings":"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"}

package/dist/setup/binding-service.d.ts

@@ -0,0 +1,86 @@
+import type { QrConnectCallbacks, QrConnectOptions } from '@tencent-connect/qqbot-connector';
+import type { Logger } from '../types.ts';
+import type { QrPresenter } from './presenters.ts';
+import { renderQrSvgDataUrl } from './qr-svg.ts';
+import type { SetupCredentials } from './persist.ts';
+/** connector 连接函数签名（可注入便于测试） */
+export type ConnectFn = (callbacks: QrConnectCallbacks, options?: QrConnectOptions) => () => void;
+/** 绑定状态机相位 */
+export type BindPhase = {
+    kind: 'idle';
+} | {
+    kind: 'waiting';
+    url: string;
+    qrSvg?: string;
+    issuedAt: number;
+} | {
+    kind: 'saving';
+} | {
+    kind: 'failed';
+    reason: string;
+};
+/** HTTP 路由序列化形态（线上协议，供端内绑定页消费） */
+export type BindStateWire = {
+    phase: 'starting';
+} | {
+    phase: 'waiting';
+    url: string;
+    qrSvg?: string;
+    issuedAt: number;
+} | {
+    phase: 'saving';
+} | {
+    phase: 'failed';
+    reason: string;
+};
+/** 构造参数 */
+export interface BindingServiceOptions {
+    /** 调用来源标识，拼入二维码 URL */
+    source: string;
+    logger: Logger;
+    /** connector 注入点（默认真实实现） */
+    connect?: ConnectFn;
+    /** 二维码渲染注入点（默认真实实现） */
+    renderQr?: typeof renderQrSvgDataUrl;
+}
+/**
+ * 单个绑定会话的状态机。
+ *
+ * start() 幂等；refresh() 通过 abort 当前 connectOnce 使 run 循环
+ * 重建绑定任务（新二维码）；dispose() 终止一切轮询。
+ */
+export declare class BindingService {
+    private phase;
+    private readonly listeners;
+    private readonly presenters;
+    private readonly connectFn;
+    private readonly renderQrFn;
+    private readonly source;
+    private readonly logger;
+    private readonly lifetime;
+    private refreshCtl;
+    private runId;
+    private startPromise;
+    private disposed;
+    constructor(options: BindingServiceOptions);
+    /** 当前相位（路由轮询读取） */
+    get currentPhase(): BindPhase;
+    /** 状态订阅（预留给 SSE 推送等增强） */
+    subscribe(listener: () => void): () => void;
+    /** 挂载呈现策略（须在 start() 前调用） */
+    attach(presenter: QrPresenter): void;
+    /** 序列化为线上协议 */
+    wireState(): BindStateWire;
+    /** 启动绑定流程（幂等） */
+    start(): Promise<SetupCredentials | null>;
+    /** 用户请求刷新：废弃当前二维码任务，run 循环会重建 */
+    refresh(): void;
+    /** 终止绑定（插件卸载 / HMR 接管 / 替换） */
+    dispose(): void;
+    private run;
+    private connectOnce;
+    private handleQrDisplayed;
+    private handleQrExpired;
+    private setPhase;
+}
+//# sourceMappingURL=binding-service.d.ts.map

package/dist/setup/binding-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-service.d.ts","sourceRoot":"","sources":["../../src/setup/binding-service.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,kBAAkB,EAAwB,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACnH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,gCAAgC;AAChC,MAAM,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;AAElG,cAAc;AACd,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,kCAAkC;AAClC,MAAM,MAAM,aAAa,GACrB;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,GACrB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,WAAW;AACX,MAAM,WAAW,qBAAqB;IACpC,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,uBAAuB;IACvB,QAAQ,CAAC,EAAE,OAAO,kBAAkB,CAAC;CACtC;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,UAAU,CAAgC;IAClD,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,YAAY,CAAiD;IACrE,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,qBAAqB;IAO1C,mBAAmB;IACnB,IAAI,YAAY,IAAI,SAAS,CAE5B;IAED,0BAA0B;IAC1B,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAK3C,6BAA6B;IAC7B,MAAM,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI;IAIpC,eAAe;IACf,SAAS,IAAI,aAAa;IAa1B,iBAAiB;IACjB,KAAK,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IASzC,iCAAiC;IACjC,OAAO,IAAI,IAAI;IAMf,+BAA+B;IAC/B,OAAO,IAAI,IAAI;YASD,GAAG;IAwBjB,OAAO,CAAC,WAAW;YAqCL,iBAAiB;IAgB/B,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,QAAQ;CAIjB"}

package/dist/setup/binding-service.js

@@ -0,0 +1,175 @@
+/**
+ * QQ Bot 绑定服务 — 扫码状态机（宿主内唯一事实源）
+ *
+ * - 协议轮询只在宿主执行（appSecret 解密后绝不出宿主进程）
+ * - 端内绑定页（bind-routes）只读投影本服务状态
+ * - 生命周期可取消（HMR / 插件卸载时 abort 轮询，不留孤儿任务）
+ * - refresh() 仅废弃当前二维码任务并重建（用户点击「刷新二维码」）
+ */
+import { startQrConnect } from '@tencent-connect/qqbot-connector';
+import { renderQrSvgDataUrl } from "./qr-svg.js";
+/**
+ * 单个绑定会话的状态机。
+ *
+ * start() 幂等；refresh() 通过 abort 当前 connectOnce 使 run 循环
+ * 重建绑定任务（新二维码）；dispose() 终止一切轮询。
+ */
+export class BindingService {
+    phase = { kind: 'idle' };
+    listeners = new Set();
+    presenters = [];
+    connectFn;
+    renderQrFn;
+    source;
+    logger;
+    lifetime = new AbortController();
+    refreshCtl = null;
+    runId = 0;
+    startPromise = null;
+    disposed = false;
+    constructor(options) {
+        this.source = options.source;
+        this.logger = options.logger;
+        this.connectFn = options.connect ?? startQrConnect;
+        this.renderQrFn = options.renderQr ?? renderQrSvgDataUrl;
+    }
+    /** 当前相位（路由轮询读取） */
+    get currentPhase() {
+        return this.phase;
+    }
+    /** 状态订阅（预留给 SSE 推送等增强） */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** 挂载呈现策略（须在 start() 前调用） */
+    attach(presenter) {
+        this.presenters.push(presenter);
+    }
+    /** 序列化为线上协议 */
+    wireState() {
+        switch (this.phase.kind) {
+            case 'idle':
+                return { phase: 'starting' };
+            case 'waiting':
+                return { phase: 'waiting', url: this.phase.url, qrSvg: this.phase.qrSvg, issuedAt: this.phase.issuedAt };
+            case 'saving':
+                return { phase: 'saving' };
+            case 'failed':
+                return { phase: 'failed', reason: this.phase.reason };
+        }
+    }
+    /** 启动绑定流程（幂等） */
+    start() {
+        if (this.startPromise === null) {
+            this.startPromise = this.run().finally(() => {
+                this.refreshCtl = null;
+            });
+        }
+        return this.startPromise;
+    }
+    /** 用户请求刷新：废弃当前二维码任务，run 循环会重建 */
+    refresh() {
+        if (this.disposed || this.startPromise === null)
+            return;
+        console.log('正在刷新二维码…\n');
+        this.refreshCtl?.abort();
+    }
+    /** 终止绑定（插件卸载 / HMR 接管 / 替换） */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.refreshCtl?.abort();
+        this.lifetime.abort();
+        this.presenters.length = 0;
+        this.listeners.clear();
+    }
+    async run() {
+        while (!this.disposed) {
+            const generation = ++this.runId;
+            let credentials;
+            try {
+                credentials = await this.connectOnce(generation);
+            }
+            catch (err) {
+                if (this.disposed)
+                    return null;
+                const reason = err instanceof Error ? err.message : String(err);
+                this.setPhase({ kind: 'failed', reason });
+                console.error(`[im-qqbot] 扫码绑定失败: ${reason}`);
+                return null;
+            }
+            if (this.disposed)
+                return null;
+            if (credentials !== null) {
+                console.log(`\n✔ 扫码绑定成功! AppID: ${credentials.appId}\n`);
+                this.setPhase({ kind: 'saving' });
+                return credentials;
+            }
+            // null = refresh 触发的重启或空凭据软失败，循环重建新二维码任务
+        }
+        return null;
+    }
+    connectOnce(generation) {
+        return new Promise((resolve, reject) => {
+            const refreshCtl = new AbortController();
+            this.refreshCtl = refreshCtl;
+            const signal = AbortSignal.any([this.lifetime.signal, refreshCtl.signal]);
+            this.connectFn({
+                onSuccess: (credentials) => {
+                    const cred = credentials[0];
+                    if (!cred) {
+                        // 软失败：以 failed 终结（不进入 refresh 循环，避免无限重试）
+                        reject(new Error('扫码未返回有效凭据'));
+                        return;
+                    }
+                    resolve({ appId: cred.appId, appSecret: cred.appSecret });
+                },
+                onFailure: (error) => {
+                    // refresh / dispose 触发的取消按「重启」或「静默退出」处理
+                    if (this.lifetime.signal.aborted || refreshCtl.signal.aborted) {
+                        resolve(null);
+                        return;
+                    }
+                    reject(error);
+                },
+                onQrDisplayed: (url) => { void this.handleQrDisplayed(generation, url); },
+                onQrExpired: () => { this.handleQrExpired(generation); },
+            }, {
+                displayQrCodeToConsole: this.presenters.some((p) => p.printQrToConsole),
+                signal,
+                source: this.source,
+            });
+        });
+    }
+    async handleQrDisplayed(generation, url) {
+        // 终端链接指引先于 SVG 渲染：指引是二维码渲染错位时的自救通道，
+        // 必须与 connector 的二维码打印同步衔接，不隔任何异步间隙
+        for (const presenter of this.presenters)
+            presenter.onQrDisplayed(url);
+        let qrSvg;
+        try {
+            qrSvg = await this.renderQrFn(url);
+        }
+        catch (err) {
+            this.logger.warn(`im-qqbot: 二维码 SVG 渲染失败（页面将降级为链接）: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // 渲染期间可能已被 refresh/dispose 淘汰
+        if (generation !== this.runId || this.disposed)
+            return;
+        this.setPhase({ kind: 'waiting', url, qrSvg, issuedAt: Date.now() });
+    }
+    handleQrExpired(generation) {
+        if (generation !== this.runId)
+            return;
+        for (const presenter of this.presenters)
+            presenter.onQrExpired?.();
+    }
+    setPhase(phase) {
+        this.phase = phase;
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+//# sourceMappingURL=binding-service.js.map

package/dist/setup/binding-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-service.js","sourceRoot":"","sources":["../../src/setup/binding-service.ts"],"names":[],"mappings":"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"}

package/dist/setup/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 凭据绑定编排 — setup/ 模块入口
+ *
+ * apply() 检测到凭据缺失时调用 ensureCredentials：
+ * 1. 创建 BindingService（单例接管，HMR 双 fiber 安全）
+ * 2. Web 宿主（dsh web / Desktop）注册端内绑定页路由
+ *    —— 经 ctx.inject(['webServer'], ...) 可选注入：服务未就绪时插件
+ *       照常加载（CLI profile），就绪/替换时自动（重）注册路由
+ * 3. 按宿主形态挂呈现策略（终端 / 浏览器降级）
+ * 4. 生命周期与 ctx fiber 绑定（dispose 时 abort 轮询、注销路由）
+ *
+ * 凭据已配置的 fiber 调用 registerBoundCredentialRoutes 注册常驻路由
+ * （bound 状态回显 + 手动编辑），与扫码流程共用持久化路径。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Logger } from '../types.ts';
+import { type SetupCredentials } from './persist.ts';
+export type { SetupCredentials } from './persist.ts';
+export { persistCredentialsToProfile } from './persist.ts';
+export { isDesktopHost } from './presenters.ts';
+/** ensureCredentials 参数 */
+export interface EnsureCredentialsOptions {
+    logger: Logger;
+    /** 二维码 URL 的 source 标识 */
+    source?: string;
+    /** 当前生效配置（apply 时 loader 合并值；config 路由 GET 回显用） */
+    config: Record<string, unknown>;
+}
+/**
+ * 执行扫码绑定编排，返回凭据就绪的 Promise；失败/取消 resolve null。
+ *
+ * 【同步契约】函数体必须保持无 await——绑定编排（服务接管、路由注册、
+ * 呈现策略、ctx 生命周期挂载）在调用后的同步阶段全部完成，随后返回
+ * `service.start()` 的挂起 Promise。调用方（插件 apply）因此可以不等待
+ * 扫码结果直接完成加载：boot 的 `loader.await()` 会等所有插件 fiber
+ * settle，若 apply 无限期等待用户扫码，Host ready 会被阻塞
+ * （Desktop 界面无法进入、Web URL 延迟输出）。
+ *
+ * 凭据持久化由调用方在 Promise 的 then 链中执行——成功写入
+ * cordis.patch.yml 会触发 HMR 热重载，新 fiber 以凭据启动网关。
+ */
+export declare function ensureCredentials(ctx: Context, options: EnsureCredentialsOptions): Promise<SetupCredentials | null>;
+/**
+ * 凭据已配置的 fiber 注册常驻路由（状态回显 + 手动编辑/更换）。
+ *
+ * 在 apply 的 bootstrapGateway 之前调用；写入经同一 persist 路径，
+ * 保存后触发 HMR 重载、新 fiber 以新凭据重启网关。
+ */
+export declare function registerBoundCredentialRoutes(ctx: Context, logger: Logger, appId: string, config: Record<string, unknown>): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/setup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/setup/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI1C,OAAO,EAA+B,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGlF,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAKhD,2BAA2B;AAC3B,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAmDlC;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAehI"}