dsh-hooks 0.4.0 → 0.5.0

package/lib/feishu.d.ts

@@ -0,0 +1,119 @@
+import type { registerApp } from '@larksuiteoapi/node-sdk';
+/** Feishu config dir: credentials + the stable copy of the notify script. */
+export declare const FEISHU_CONFIG_DIR: string;
+export declare const FEISHU_CONFIG_PATH: string;
+/** Card content truncation length written by setup (notify script default). */
+export declare const FEISHU_RESULT_MAX_CHARS_DEFAULT = 300;
+/** UI-accepted truncation range (characters). */
+export declare const FEISHU_RESULT_MAX_CHARS_MIN = 50;
+export declare const FEISHU_RESULT_MAX_CHARS_MAX = 5000;
+/** Injectable file paths, so tests (and the web routes) stay off the real home. */
+export interface FeishuSetupPaths {
+    /** Credential file (default ~/.dsh/dsh-hooks/feishu-config.json). */
+    configPath?: string;
+    /** Profile patch file (default ~/.dsh/profiles/<profile>/cordis.patch.yml). */
+    patchFile?: string;
+    /** Stable notify-script location the hooks reference. */
+    notifyScript?: string;
+}
+export interface FeishuQRCodeInfo {
+    url: string;
+    /** Seconds until the QR authorization expires. */
+    expireIn: number;
+}
+export interface RunFeishuSetupOptions {
+    /** Profile whose cordis.patch.yml receives the dsh-hooks config block. */
+    profile?: string;
+    /** Overrides the real registerApp (tests). */
+    registerAppFn?: typeof registerApp;
+    print?: (line: string) => void;
+    printErr?: (line: string) => void;
+    /** Called when the QR authorization is ready (CLI prints it; web renders it). */
+    onQRCodeReady?: (qr: FeishuQRCodeInfo) => void | Promise<void>;
+    /** Abort the scan wait (web cancel). */
+    signal?: AbortSignal;
+    /** Card content truncation length written into the credential file. */
+    resultMaxChars?: number;
+    paths?: FeishuSetupPaths;
+}
+export interface FeishuSetupResult {
+    appId: string;
+    ownerOpenId: string;
+}
+/** Profile patch file for a profile name. */
+export declare function patchPath(profile: string): string;
+/** Which hooks the setup installs into the profile. */
+export declare function setupHooks(scriptPath: string): ({
+    on: string;
+    when: string;
+    run: string;
+    timeoutMs: number;
+} | {
+    when?: undefined;
+    on: string;
+    run: string;
+    timeoutMs: number;
+})[];
+/** Absolute path of the shipped notify script (works from both lib/ and src/). */
+export declare function notifyScriptPath(): string;
+/**
+ * Resolve the stable notify-script location hooks should reference. The npx
+ * cache (where the CLI often runs from) is ephemeral, so the setup copies the
+ * zero-dependency script next to feishu-config.json:
+ * ~/.dsh/dsh-hooks/notify-feishu.mjs. Re-copies on every setup so the stable
+ * copy tracks the installed version.
+ */
+export declare function stableScriptPath(paths?: FeishuSetupPaths): string;
+/**
+ * Write the credential file with 0600 perms (owner-only): secrets stay out of
+ * the repo and argv.
+ */
+export declare function writeConfig(configPath: string, { appId, appSecret, targetType, targetId, resultMaxChars }: {
+    appId: string;
+    appSecret: string;
+    targetType?: string;
+    targetId: string;
+    resultMaxChars?: number;
+}): void;
+/**
+ * Merge the dsh-hooks config block into a profile's cordis.patch.yml:
+ * existing dsh-hooks entries keep unrelated config and get their hooks
+ * replaced with `setupHooks`; other entries stay untouched. Idempotent.
+ */
+export declare function mergePatchYaml(existingText: string, { scriptPath }: {
+    scriptPath: string;
+}): string;
+/**
+ * Full setup flow: registerApp (QR scan creates the Feishu app), write
+ * credentials + the stable notify script, merge the card hooks into the
+ * profile patch, and send a welcome card to the scanning user.
+ */
+export declare function runFeishuSetup(options?: RunFeishuSetupOptions): Promise<FeishuSetupResult>;
+export interface RunFeishuTestOptions {
+    print?: (line: string) => void;
+    paths?: FeishuSetupPaths;
+}
+/** Test the stored credentials and send a test card to the configured target. */
+export declare function runFeishuTest(options?: RunFeishuTestOptions): Promise<string>;
+/** Mask an identifier for display: `cli_a1b2…9012`. Never shows the secret. */
+export declare function maskId(value: string | null): string | null;
+/** Readable connection summary for the settings UI (credentials never leave this module). */
+export interface FeishuSummary {
+    configured: boolean;
+    appId: string | null;
+    targetKind: string | null;
+    target: string | null;
+    /** Card content truncation length (from the credential file, or the default). */
+    resultMaxChars: number;
+}
+/**
+ * Inspect the credential file for a display-only summary. The app secret is
+ * read for presence only and never enters any returned value.
+ */
+export declare function readFeishuSummary(configPath?: string): FeishuSummary;
+/**
+ * Update the card truncation length in an existing credential file, keeping
+ * every other field (credentials, target) untouched. Throws a user-facing
+ * error for invalid input or a missing/unparsable file.
+ */
+export declare function updateFeishuResultMaxChars(configPath: string | undefined, value: number): number;

package/lib/feishu.js

@@ -0,0 +1,282 @@
+/**
+ * Shared Feishu notification setup: the one-shot app-creation flow
+ * (`registerApp` + QR scan) plus credential/config plumbing. Used by both
+ * the `dsh-hooks feishu-setup` CLI and the web profile's
+ * `/dsh-hooks/feishu/*` routes — the CLI is a thin wrapper adding terminal
+ * QR printing and the browser opener.
+ *
+ * The Feishu SDK and the qrcode renderer are never loaded at plugin apply
+ * time: the SDK resolves through a dynamic import on first setup, so
+ * headless/CLI profiles without a web server pay nothing for the UI path.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import { run as notifyRun } from '../examples/notify-feishu.mjs';
+/** Feishu config dir: credentials + the stable copy of the notify script. */
+export const FEISHU_CONFIG_DIR = join(homedir(), '.dsh', 'dsh-hooks');
+export const FEISHU_CONFIG_PATH = join(FEISHU_CONFIG_DIR, 'feishu-config.json');
+/** Card content truncation length written by setup (notify script default). */
+export const FEISHU_RESULT_MAX_CHARS_DEFAULT = 300;
+/** UI-accepted truncation range (characters). */
+export const FEISHU_RESULT_MAX_CHARS_MIN = 50;
+export const FEISHU_RESULT_MAX_CHARS_MAX = 5000;
+/** Profile patch file for a profile name. */
+export function patchPath(profile) {
+    return join(homedir(), '.dsh', 'profiles', profile, 'cordis.patch.yml');
+}
+/** Which hooks the setup installs into the profile. */
+export function setupHooks(scriptPath) {
+    return [
+        { on: 'turn/end', when: 'completed', run: `node ${JSON.stringify(scriptPath)}`, timeoutMs: 30000 },
+        { on: 'turn/end', when: 'error', run: `node ${JSON.stringify(scriptPath)}`, timeoutMs: 30000 },
+        { on: 'turn/end', when: 'aborted', run: `node ${JSON.stringify(scriptPath)}`, timeoutMs: 30000 },
+        { on: 'approval/asked', run: `node ${JSON.stringify(scriptPath)} --approval`, timeoutMs: 30000 },
+        { on: 'agent/error', run: `node ${JSON.stringify(scriptPath)}`, timeoutMs: 30000 },
+    ];
+}
+/** Absolute path of the shipped notify script (works from both lib/ and src/). */
+export function notifyScriptPath() {
+    return new URL('../examples/notify-feishu.mjs', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1');
+}
+/**
+ * Resolve the stable notify-script location hooks should reference. The npx
+ * cache (where the CLI often runs from) is ephemeral, so the setup copies the
+ * zero-dependency script next to feishu-config.json:
+ * ~/.dsh/dsh-hooks/notify-feishu.mjs. Re-copies on every setup so the stable
+ * copy tracks the installed version.
+ */
+export function stableScriptPath(paths = {}) {
+    return paths.notifyScript ?? join(FEISHU_CONFIG_DIR, 'notify-feishu.mjs');
+}
+/**
+ * Write the credential file with 0600 perms (owner-only): secrets stay out of
+ * the repo and argv.
+ */
+export function writeConfig(configPath, { appId, appSecret, targetType = 'open_id', targetId, resultMaxChars = 300 }) {
+    mkdirSync(join(configPath, '..'), { recursive: true, mode: 0o700 });
+    const doc = JSON.stringify({
+        app_id: appId,
+        app_secret: appSecret,
+        target_type: targetType,
+        target_id: targetId,
+        result_max_chars: resultMaxChars,
+    }, null, 2);
+    writeFileSync(configPath, doc + '\n', 'utf8');
+    try {
+        chmodSync(configPath, 0o600);
+    }
+    catch {
+        // Windows: ACL-based protection; the file lives under the user profile.
+    }
+}
+/**
+ * Merge the dsh-hooks config block into a profile's cordis.patch.yml:
+ * existing dsh-hooks entries keep unrelated config and get their hooks
+ * replaced with `setupHooks`; other entries stay untouched. Idempotent.
+ */
+export function mergePatchYaml(existingText, { scriptPath }) {
+    let entries;
+    try {
+        entries = YAML.parse(existingText || '[]\n');
+    }
+    catch {
+        throw new Error('profile 的 cordis.patch.yml 解析失败，请先修复该文件');
+    }
+    if (!Array.isArray(entries))
+        throw new Error('cordis.patch.yml 顶层必须是 YAML 数组');
+    const hooks = setupHooks(scriptPath);
+    let found = false;
+    for (const entry of entries) {
+        if (entry && typeof entry === 'object' && entry.id === 'dsh-hooks') {
+            ;
+            entry.name = 'dsh-hooks';
+            entry.config = { hooks };
+            found = true;
+            break;
+        }
+    }
+    if (!found)
+        entries.push({ id: 'dsh-hooks', name: 'dsh-hooks', config: { hooks } });
+    return YAML.stringify(entries);
+}
+/**
+ * Full setup flow: registerApp (QR scan creates the Feishu app), write
+ * credentials + the stable notify script, merge the card hooks into the
+ * profile patch, and send a welcome card to the scanning user.
+ */
+export async function runFeishuSetup(options = {}) {
+    const profile = options.profile ?? 'web';
+    const print = options.print ?? console.log;
+    const printErr = options.printErr ?? console.error;
+    const paths = options.paths ?? {};
+    const configPath = paths.configPath ?? FEISHU_CONFIG_PATH;
+    const patchFile = paths.patchFile ?? patchPath(profile);
+    const notifyScript = stableScriptPath(paths);
+    print('dsh-hooks feishu-setup');
+    print('1/4 正在生成飞书「一键创建应用」二维码…');
+    // The SDK stays out of the module graph until the first setup actually runs.
+    const registerAppFn = options.registerAppFn ?? (await import('@larksuiteoapi/node-sdk')).registerApp;
+    const result = await registerAppFn({
+        source: 'dsh-hooks',
+        createOnly: true,
+        appPreset: {
+            name: 'DSH 通知机器人',
+            desc: 'DeepSeek Harness 会话事件通知（dsh-hooks）',
+        },
+        addons: {
+            preset: false,
+            scopes: {
+                tenant: ['im:message:send_as_bot'],
+            },
+        },
+        signal: options.signal,
+        onQRCodeReady: (authorization) => {
+            // The SDK fires this once the authorization URL exists; the scan wait
+            // is the registerApp promise itself. Caller-side failures must never
+            // break the SDK's polling loop.
+            void Promise.resolve(options.onQRCodeReady?.(authorization)).catch(() => undefined);
+        },
+    });
+    const appId = result.client_id;
+    const appSecret = result.client_secret;
+    const ownerOpenId = result.user_info?.open_id;
+    if (!appId || !appSecret)
+        throw new Error('扫码创建未完成，未拿到应用凭证');
+    if (!ownerOpenId)
+        throw new Error('扫码结果缺少 open_id，请重试');
+    print('');
+    print(`2/4 应用创建成功：${appId}（机器人将私聊通知你）`);
+    writeConfig(configPath, {
+        appId,
+        appSecret,
+        targetType: 'open_id',
+        targetId: ownerOpenId,
+        resultMaxChars: options.resultMaxChars ?? FEISHU_RESULT_MAX_CHARS_DEFAULT,
+    });
+    print(`3/4 凭据已写入 ${configPath}（权限 0600，勿提交到仓库）`);
+    // Copy the notify script to its stable location so hooks never reference
+    // the ephemeral npx cache.
+    if (!paths.notifyScript) {
+        mkdirSync(FEISHU_CONFIG_DIR, { recursive: true, mode: 0o700 });
+        writeFileSync(notifyScript, readFileSync(notifyScriptPath(), 'utf8'), 'utf8');
+    }
+    const existing = existsSync(patchFile) ? readFileSync(patchFile, 'utf8') : '[]\n';
+    const merged = mergePatchYaml(existing, { scriptPath: notifyScript });
+    writeFileSync(patchFile, merged, 'utf8');
+    print(`4/4 hook 配置已写入 ${patchFile}`);
+    print('发送欢迎卡片验证…');
+    try {
+        await notifyRun({
+            appId,
+            appSecret,
+            to: ownerOpenId,
+            event: 'agent/created',
+            sessionId: 'dsh-hooks-setup',
+            cwd: process.cwd(),
+            timestamp: new Date().toISOString(),
+        });
+        print('✅ 欢迎卡片已发送。请重启 dsh web 使 hooks 生效。');
+    }
+    catch (error) {
+        printErr(`⚠ 欢迎卡片发送失败（配置已就绪，可稍后用 feishu-test 重试）：${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { appId, ownerOpenId };
+}
+/** Test the stored credentials and send a test card to the configured target. */
+export async function runFeishuTest(options = {}) {
+    const print = options.print ?? console.log;
+    const configPath = options.paths?.configPath ?? FEISHU_CONFIG_PATH;
+    if (!existsSync(configPath)) {
+        throw new Error(`未找到配置文件 ${configPath}，请先运行 feishu-setup`);
+    }
+    let file;
+    try {
+        file = JSON.parse(readFileSync(configPath, 'utf8'));
+    }
+    catch {
+        throw new Error(`配置文件 ${configPath} 解析失败，请重新运行 feishu-setup`);
+    }
+    const { app_id: appId, app_secret: appSecret, target_id: targetId } = file;
+    if (typeof appId !== 'string' || appId === '' || typeof appSecret !== 'string' || appSecret === '' || typeof targetId !== 'string' || targetId === '') {
+        throw new Error('配置文件不完整，请重新运行 feishu-setup');
+    }
+    await notifyRun({
+        appId,
+        appSecret,
+        to: targetId,
+        event: 'agent/status',
+        status: 'connected',
+        sessionId: 'feishu-test',
+        cwd: process.cwd(),
+        timestamp: new Date().toISOString(),
+    });
+    const line = '✅ 测试卡片已发送';
+    print(line);
+    return line;
+}
+/** Mask an identifier for display: `cli_a1b2…9012`. Never shows the secret. */
+export function maskId(value) {
+    if (value === null)
+        return null;
+    if (value.length <= 12)
+        return value;
+    return `${value.slice(0, 8)}…${value.slice(-4)}`;
+}
+/**
+ * Inspect the credential file for a display-only summary. The app secret is
+ * read for presence only and never enters any returned value.
+ */
+export function readFeishuSummary(configPath = FEISHU_CONFIG_PATH) {
+    const empty = {
+        configured: false,
+        appId: null,
+        targetKind: null,
+        target: null,
+        resultMaxChars: FEISHU_RESULT_MAX_CHARS_DEFAULT,
+    };
+    if (!existsSync(configPath))
+        return empty;
+    try {
+        const file = JSON.parse(readFileSync(configPath, 'utf8'));
+        const appId = typeof file.app_id === 'string' && file.app_id !== '' ? file.app_id : null;
+        const secret = typeof file.app_secret === 'string' && file.app_secret !== '';
+        const targetKind = typeof file.target_type === 'string' && file.target_type !== '' ? file.target_type : null;
+        const target = typeof file.target_id === 'string' && file.target_id !== '' ? file.target_id : null;
+        const resultMaxChars = typeof file.result_max_chars === 'number' && Number.isFinite(file.result_max_chars) && file.result_max_chars > 0
+            ? Math.floor(file.result_max_chars)
+            : FEISHU_RESULT_MAX_CHARS_DEFAULT;
+        if (appId === null || !secret || target === null)
+            return { ...empty, resultMaxChars };
+        return { configured: true, appId: maskId(appId), targetKind, target: maskId(target), resultMaxChars };
+    }
+    catch {
+        return empty;
+    }
+}
+/**
+ * Update the card truncation length in an existing credential file, keeping
+ * every other field (credentials, target) untouched. Throws a user-facing
+ * error for invalid input or a missing/unparsable file.
+ */
+export function updateFeishuResultMaxChars(configPath = FEISHU_CONFIG_PATH, value) {
+    if (!Number.isFinite(value) || value < FEISHU_RESULT_MAX_CHARS_MIN || value > FEISHU_RESULT_MAX_CHARS_MAX) {
+        throw new Error(`截断长度必须是 ${FEISHU_RESULT_MAX_CHARS_MIN}–${FEISHU_RESULT_MAX_CHARS_MAX} 之间的数字`);
+    }
+    const rounded = Math.floor(value);
+    if (!existsSync(configPath))
+        throw new Error('尚未连接飞书，请先扫码连接');
+    let file;
+    try {
+        file = JSON.parse(readFileSync(configPath, 'utf8'));
+    }
+    catch {
+        throw new Error('飞书配置文件解析失败，请重新连接');
+    }
+    if (typeof file !== 'object' || file === null)
+        throw new Error('飞书配置文件解析失败，请重新连接');
+    file.result_max_chars = rounded;
+    writeFileSync(configPath, JSON.stringify(file, null, 2) + '\n', 'utf8');
+    return rounded;
+}

package/lib/history.d.ts

@@ -29,6 +29,11 @@ export interface HistorySink {
     record(record: Omit<HookRunRecord, 'ts'>): void;
     /** Most recent records, oldest first. */
     recent(): readonly HookRunRecord[];
+    /**
+     * Ingest JSONL bytes appended since the last read (startup seed or another
+     * process). Idempotent and best-effort: failures leave the buffer as-is.
+     */
+    sync(): void;
     dispose(): void;
 }
 export declare function createHistorySink(options?: HistorySinkOptions): HistorySink;

package/lib/history.js

@@ -2,8 +2,14 @@
  * Hook execution history: an in-memory ring buffer plus a best-effort
  * JSONL append log under ~/.dsh/dsh-hooks/ (0600, owner-only). History is
  * strictly best-effort — a failed write never breaks a hook.
+ *
+ * The buffer is not process-private memory only: it seeds from the JSONL at
+ * startup and `sync()` incrementally ingests bytes appended since the last
+ * read, so records written before a restart (or by another dsh process
+ * sharing the file, e.g. a task-board Host) surface in the web GUI instead
+ * of vanishing with the process.
  */
-import { appendFileSync, chmodSync, mkdirSync } from 'node:fs';
+import { appendFileSync, chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 export const DEFAULT_HISTORY_PATH = join(homedir(), '.dsh', 'dsh-hooks', 'history.jsonl');
@@ -15,11 +21,101 @@ export function createHistorySink(options = {}) {
     const buffer = [];
     let dirReady = false;
     let chmodded = false;
-    function record(partial) {
-        const entry = { ...partial, ts: Date.now() };
+    /** Bytes of `file` already ingested into the buffer. */
+    let syncedBytes = 0;
+    /** Trailing fragment of the last read that did not end with a newline. */
+    let pending = '';
+    function push(entry) {
         buffer.push(entry);
         if (buffer.length > max)
             buffer.splice(0, buffer.length - max);
+    }
+    /** Parse complete JSONL lines into the ring buffer; incomplete tails stay pending. */
+    function ingest(text) {
+        pending += text;
+        const lines = pending.split('\n');
+        pending = lines.pop() ?? '';
+        for (const line of lines) {
+            if (line === '')
+                continue;
+            try {
+                const entry = JSON.parse(line);
+                if (typeof entry !== 'object' || entry === null || typeof entry.ts !== 'number')
+                    continue;
+                push(entry);
+            }
+            catch {
+                // Broken line (mid-write or foreign content): skip, never fail.
+            }
+        }
+    }
+    /** Rebuild the buffer from the whole file (startup seed / truncated file). */
+    function rebuild() {
+        buffer.length = 0;
+        pending = '';
+        syncedBytes = 0;
+        const text = readFileSync(file, 'utf8');
+        syncedBytes = Buffer.byteLength(text, 'utf8');
+        ingest(text);
+    }
+    /** Seed the ring buffer from an existing JSONL log (best-effort). */
+    function seed() {
+        if (!enabled)
+            return;
+        try {
+            if (!existsSync(file))
+                return;
+            rebuild();
+        }
+        catch {
+            // Seeding is best-effort; recording starts from an empty buffer.
+        }
+    }
+    /** Ingest every byte appended since the last read (own writes included). */
+    function sync() {
+        if (!enabled)
+            return;
+        try {
+            if (!existsSync(file))
+                return;
+            const size = statSync(file).size;
+            if (size === syncedBytes)
+                return;
+            if (size < syncedBytes) {
+                // The file shrank (rotation/truncation): rebuild from its tail.
+                rebuild();
+                return;
+            }
+            const deltaBytes = size - syncedBytes;
+            const fd = openSync(file, 'r');
+            try {
+                const chunk = Buffer.allocUnsafe(deltaBytes);
+                let total = 0;
+                while (total < deltaBytes) {
+                    const n = readSync(fd, chunk, total, deltaBytes - total, syncedBytes + total);
+                    if (n <= 0)
+                        break;
+                    total += n;
+                }
+                ingest(chunk.subarray(0, total).toString('utf8'));
+            }
+            finally {
+                closeSync(fd);
+            }
+            syncedBytes = size;
+        }
+        catch {
+            // Sync is best-effort; the next call retries.
+        }
+    }
+    function record(partial) {
+        const entry = { ...partial, ts: Date.now() };
+        // Ingest other processes' appends BEFORE our own entry so the buffer
+        // stays in file order, and `syncedBytes` stays a true prefix of the
+        // file (otherwise our own advance would skip the foreign appends).
+        if (enabled)
+            sync();
+        push(entry);
         if (!enabled)
             return;
         try {
@@ -28,6 +124,7 @@ export function createHistorySink(options = {}) {
                 dirReady = true;
             }
             appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+            syncedBytes = statSync(file).size;
             if (!chmodded) {
                 try {
                     chmodSync(file, 0o600);
@@ -42,9 +139,11 @@ export function createHistorySink(options = {}) {
             // History is best-effort: a failed write never breaks a hook.
         }
     }
+    seed();
     return {
         record,
         recent: () => buffer,
+        sync,
         dispose: () => { },
     };
 }

package/lib/index.js

@@ -5,6 +5,7 @@ import { eventLabel } from './context.js';
 import { createHookRunner } from './runner.js';
 import { fireNotify } from './notify.js';
 import { createHistorySink } from './history.js';
+import { createFeishuSetupManager } from './feishu-session.js';
 import { registerHookRoutes } from './server.js';
 export const name = 'dsh-hooks';
 // Dependency on the session service: `session/event` only exists once a
@@ -22,12 +23,20 @@ export function apply(ctx, config = {}) {
     const hooks = config.hooks ?? [];
     const history = createHistorySink(config.history ?? undefined);
     const runner = createHookRunner((line) => ctx.logger?.info(line), (record) => history.record(record));
-    // Web-profile extras: /dsh-hooks routes and the agent announcement. Both
-    // services are optional — CLI/headless profiles provide neither, and the
-    // plugin keeps working there untouched.
+    // Web-profile extras: /dsh-hooks routes (incl. the Feishu connect flow)
+    // and the agent announcement. Both services are optional — CLI/headless
+    // profiles provide neither, and the plugin keeps working there untouched.
     const webServer = ctx.get('webServer', false);
     if (webServer !== undefined) {
-        ctx.effect(() => registerHookRoutes(webServer, { hooks, history }), 'dsh-hooks: /dsh-hooks routes');
+        const feishu = createFeishuSetupManager();
+        ctx.effect(() => {
+            const unregister = registerHookRoutes(webServer, { hooks, history, feishu: { manager: feishu } });
+            return () => {
+                unregister();
+                // Abort an in-flight QR scan so it never outlives the plugin.
+                feishu.dispose();
+            };
+        }, 'dsh-hooks: /dsh-hooks routes');
     }
     const systemPrompt = ctx.get('systemPrompt', false);
     if (systemPrompt !== undefined) {

package/lib/server.d.ts

@@ -1,14 +1,17 @@
 /**
  * /dsh-hooks/* HTTP routes for the web profile: status, execution history,
- * and a dry-run-style test trigger. Registered only when the shared
- * webserver service exists (web profile) — CLI/headless environments never
- * see them. Loopback-only with JSON envelopes; POSTs require an explicit
+ * a dry-run-style test trigger, and the Feishu connect flow (QR setup /
+ * cancel / test card). Registered only when the shared webserver service
+ * exists (web profile) — CLI/headless environments never see them.
+ * Loopback-only with JSON envelopes; POSTs require an explicit
  * application/json content-type (CSRF hardening, same posture as
  * dsh-aionui-panel).
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HookSpec } from './config.js';
 import type { HistorySink } from './history.js';
+import { type FeishuSetupManager } from './feishu-session.js';
+import { runFeishuTest } from './feishu.js';
 /** Minimal structural shape of the shared web server (dsh-host-webserver). */
 export interface WebServerLike {
     register(spec: {
@@ -21,10 +24,19 @@ export interface WebServerLike {
 export declare function pluginVersion(): string;
 /** Loopback fence: never let a LAN client reach /dsh-hooks operations. */
 export declare function isLoopbackRequest(req: IncomingMessage): boolean;
+export interface FeishuRouteDeps {
+    /** QR-scan session manager (one in-flight flow at a time). */
+    manager: FeishuSetupManager;
+    /** Test-card sender, injectable for tests. */
+    runTest?: typeof runFeishuTest;
+    /** Credential file the status route summarizes. */
+    configPath?: string;
+}
 export interface HookRoutesOptions {
     hooks: readonly HookSpec[];
     history: HistorySink;
     version?: string;
+    feishu?: FeishuRouteDeps;
 }
 /** Create the /dsh-hooks route handler (exported for tests). */
 export declare function createHookHandler(options: HookRoutesOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;