dingtalk-ask-mcp-server 0.1.0

package/dist/daemon.js

@@ -0,0 +1,160 @@
+/**
+ * dingtalk-daemon：唯一持有钉钉 Stream 连接的共享守护进程。
+ *
+ * 多个 Agent（多个 Claude Code 窗口 / 未来 Codex）的 MCP server 与命令审批钩子都作为 HTTP
+ * 瘦客户端连到本进程的 /ask 端点，共用这一条连接——规避"同应用并发 Stream 连接被负载均衡"
+ * 导致回复投给随机 Agent 的问题。并发决策由 DecisionRegistry 多槽 + 编号路由处理。
+ *
+ * 单例选举：先绑定端点拿到 port/token，再用 O_EXCL 独占创建锁文件；创建成功者才连接钉钉，
+ * 落败者关端点退出（从不建连，避免多开连接）。凭证仅经 env（由拉起它的 MCP server 转发）。
+ *
+ * 本进程由 daemonClient.spawnDaemon detached 拉起；stderr 重定向到 tmpdir/dingtalk-daemon.log。
+ */
+import { resolveDingtalkConfig } from './dingtalk/config.js';
+import { DingtalkClient } from './dingtalk/client.js';
+import { DecisionRegistry } from './decision/registry.js';
+import { askWithTimeout } from './decision/coordinator.js';
+import { startEndpoint } from './daemon/endpoint.js';
+import { daemonLockPath, writeDaemonLockExclusive, readDaemonLock, removeDaemonLock, } from './daemon/lock.js';
+import { probeHealth } from './daemonClient.js';
+/** 选举重试次数（应对陈旧锁的回收竞争）。 */
+const ELECT_ATTEMPTS = 3;
+/** 空闲自关默认阈值（毫秒）：无待答且这么久无 /ask 则退出。0 = 禁用（常驻）。 */
+const DEFAULT_IDLE_MS = 30 * 60_000;
+/** 空闲检查间隔（毫秒）。 */
+const IDLE_CHECK_INTERVAL_MS = 60_000;
+/**
+ * 解析空闲自关阈值（env DINGTALK_DAEMON_IDLE_MS 覆盖，非法则用默认；0 = 禁用）。
+ *
+ * @param raw 环境变量原值。
+ * @returns 阈值毫秒；0 表示禁用。
+ */
+function resolveIdleMs(raw) {
+    const trimmed = (raw ?? '').trim();
+    if (trimmed === '') {
+        return DEFAULT_IDLE_MS;
+    }
+    const parsed = Number(trimmed);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : DEFAULT_IDLE_MS;
+}
+/** 解析配置；缺凭证 → stderr 打印并 exit(1)。 */
+function loadConfigOrExit() {
+    try {
+        return resolveDingtalkConfig(process.env);
+    }
+    catch (error) {
+        console.error(`dingtalk-daemon 配置错误：${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+}
+/** 生成决策 id（单进程内唯一即可）。 */
+function randomId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * 单例选举：独占创建锁则当选；已存在且属活着的守护进程则退让；陈旧锁则回收后重试。
+ *
+ * @param lock 本进程锁（port + token）。
+ * @param lockPath 锁路径。
+ * @returns true 当选；false 退让。
+ */
+async function elect(lock, lockPath) {
+    for (let i = 0; i < ELECT_ATTEMPTS; i += 1) {
+        if (writeDaemonLockExclusive(lock, lockPath)) {
+            return true;
+        }
+        const existing = readDaemonLock(lockPath);
+        if (existing !== undefined && (await probeHealth(existing)).ok) {
+            return false; // 有活跃守护进程占位 → 退让。
+        }
+        // 陈旧锁（端点不应答）→ 回收后重试独占创建。
+        removeDaemonLock(lockPath);
+    }
+    return false;
+}
+/** 注册退出清理：删锁 + 断连。 */
+function registerCleanup(endpoint, client, lockPath) {
+    const onSignal = (signal) => {
+        console.error(`收到 ${signal}，清理锁文件并断开钉钉连接。`);
+        removeDaemonLock(lockPath);
+        void client.close();
+        void endpoint.close();
+        process.exit(0);
+    };
+    process.once('SIGINT', () => onSignal('SIGINT'));
+    process.once('SIGTERM', () => onSignal('SIGTERM'));
+    process.once('beforeExit', () => removeDaemonLock(lockPath));
+}
+/** 守护进程主入口。 */
+async function main() {
+    const config = loadConfigOrExit();
+    const lockPath = daemonLockPath();
+    let ready = false;
+    let registry;
+    // 最近一次 /ask 活动时间（空闲自关判定用）。
+    let lastActivityMs = Date.now();
+    // 端点决策函数：去掉进程级 mutex，交 registry 多槽并发；askWithTimeout 保证超时不挂死。
+    const askDecision = async (input) => {
+        if (registry === undefined) {
+            throw new Error('守护进程尚未就绪。');
+        }
+        lastActivityMs = Date.now();
+        return askWithTimeout(registry, {
+            id: randomId(),
+            question: input.question,
+            options: input.options,
+            label: input.label,
+            timeoutMs: input.timeoutMs ?? config.timeoutMs,
+        });
+    };
+    // 先绑定端点（拿 port/token），此时 ready=false；接好钉钉后置 true。
+    const endpoint = await startEndpoint(askDecision, {
+        defaultTimeoutMs: config.timeoutMs,
+        isReady: () => ready,
+    });
+    const lock = {
+        port: endpoint.port,
+        token: endpoint.token,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    };
+    const won = await elect(lock, lockPath);
+    if (!won) {
+        console.error('已有活跃钉钉守护进程，本进程退让退出。');
+        await endpoint.close();
+        process.exit(0);
+    }
+    // 当选后才建连（落败者从不建连，避免同应用多开 Stream 连接）。
+    const client = new DingtalkClient(config);
+    try {
+        await client.connect();
+        console.error('钉钉 Stream 长连已建立。');
+    }
+    catch (error) {
+        console.error(`钉钉 Stream 长连建立失败：${error instanceof Error ? error.message : String(error)}。已启用后台重连，恢复前回复无法送达。`);
+    }
+    registry = new DecisionRegistry(client);
+    ready = true;
+    registerCleanup(endpoint, client, lockPath);
+    // 空闲自关：无待答且超过阈值无 /ask 活动则退出删锁（下次 MCP server 再拉起）。
+    const idleMs = resolveIdleMs(process.env.DINGTALK_DAEMON_IDLE_MS);
+    if (idleMs > 0) {
+        const timer = setInterval(() => {
+            if (registry !== undefined && registry.pendingCount() === 0 && Date.now() - lastActivityMs > idleMs) {
+                console.error(`空闲超过 ${Math.round(idleMs / 60_000)} 分钟且无待答，守护进程自动退出。`);
+                clearInterval(timer);
+                removeDaemonLock(lockPath);
+                void client.close();
+                void endpoint.close();
+                process.exit(0);
+            }
+        }, IDLE_CHECK_INTERVAL_MS);
+        // 不阻止进程退出（守护进程本就靠 http/stream 存活）。
+        timer.unref();
+    }
+    console.error(`钉钉守护进程就绪（port=${endpoint.port}，pid=${process.pid}，空闲自关=${idleMs > 0 ? `${Math.round(idleMs / 60_000)}分钟` : '禁用'}）。`);
+}
+main().catch((error) => {
+    console.error(`dingtalk-daemon 启动失败：${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});

package/dist/daemonCli.js

@@ -0,0 +1,51 @@
+/**
+ * 守护进程 CLI：查看/停止共享钉钉守护进程。
+ *
+ * 用法（仓库根目录）：
+ *   npm run daemon:status --workspace mcps/dingtalk-ask-mcp-server
+ *   npm run daemon:stop   --workspace mcps/dingtalk-ask-mcp-server
+ *
+ * status：读锁 + 探活，打印 port/pid/就绪态。
+ * stop：读锁 → 向 pid 发 SIGTERM → 删锁（守护进程自身也会在退出时删锁，这里兜底）。
+ */
+import { daemonLockPath, readDaemonLock, removeDaemonLock } from './daemon/lock.js';
+import { probeHealth } from './daemonClient.js';
+async function status() {
+    const lock = readDaemonLock(daemonLockPath());
+    if (lock === undefined) {
+        console.log('钉钉守护进程：未运行（无锁文件）。');
+        return;
+    }
+    const probe = await probeHealth(lock);
+    console.log(`钉钉守护进程：${probe.ok ? '在跑' : '锁存在但端点无应答（可能已死）'}` +
+        `，port=${lock.port}，pid=${lock.pid}，就绪=${probe.ready}。`);
+}
+function stop() {
+    const lock = readDaemonLock(daemonLockPath());
+    if (lock === undefined) {
+        console.log('钉钉守护进程：无锁文件，无需停止。');
+        return;
+    }
+    if (lock.pid > 0) {
+        try {
+            process.kill(lock.pid, 'SIGTERM');
+            console.log(`已向守护进程 pid=${lock.pid} 发送 SIGTERM。`);
+        }
+        catch (error) {
+            console.log(`发送 SIGTERM 失败（进程可能已退出）：${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    removeDaemonLock(daemonLockPath());
+    console.log('已清理锁文件。');
+}
+const command = process.argv[2];
+if (command === 'status') {
+    void status();
+}
+else if (command === 'stop') {
+    stop();
+}
+else {
+    console.log('用法：node dist/daemonCli.js <status|stop>');
+    process.exit(1);
+}

package/dist/daemonClient.js

@@ -0,0 +1,207 @@
+/**
+ * 守护进程客户端：MCP server 用之确保守护进程在跑（ensureDaemon）并向其转发决策
+ * （postAskToDaemon）；daemon.ts 选举时也用 probeHealth 判定既有锁是否属活着的守护进程。
+ *
+ * 只用 Node 内置 http/child_process/url。日志走 stderr。
+ */
+import { request } from 'node:http';
+import { spawn } from 'node:child_process';
+import { openSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { daemonLockPath, readDaemonLock } from './daemon/lock.js';
+/** 探活默认超时（毫秒）。 */
+const HEALTH_TIMEOUT_MS = 1500;
+/** ensureDaemon 等待守护进程就绪的总时长与轮询间隔。 */
+const SPAWN_WAIT_MS = 10_000;
+const POLL_INTERVAL_MS = 200;
+/** 睡眠。 */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * 探活守护进程端点。
+ *
+ * @param lock 锁（含 port + token）。
+ * @param timeoutMs 探活超时。
+ * @returns { ok, ready }；任何错误/超时 → { ok:false, ready:false }。
+ */
+export function probeHealth(lock, timeoutMs = HEALTH_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const req = request({
+            host: '127.0.0.1',
+            port: lock.port,
+            path: '/health',
+            method: 'GET',
+            headers: { 'x-ask-token': lock.token },
+            timeout: timeoutMs,
+        }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (c) => {
+                body += c;
+            });
+            res.on('end', () => {
+                if (res.statusCode !== 200) {
+                    resolve({ ok: false, ready: false });
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(body);
+                    resolve({ ok: true, ready: parsed.ready === true });
+                }
+                catch {
+                    resolve({ ok: true, ready: false });
+                }
+            });
+        });
+        req.on('error', () => resolve({ ok: false, ready: false }));
+        req.on('timeout', () => {
+            req.destroy();
+            resolve({ ok: false, ready: false });
+        });
+        req.end();
+    });
+}
+/**
+ * 向守护进程转发一次决策，阻塞等待结果。
+ *
+ * @param lock 锁（含 port + token）。
+ * @param input 决策入参（含 label、timeoutMs）。
+ * @returns 决策结果 { kind, value }。
+ * @throws 网络/超时/非 200/解析错误时抛。
+ */
+export function postAskToDaemon(lock, input) {
+    return new Promise((resolve, reject) => {
+        const payload = JSON.stringify(input);
+        // HTTP 兜底超时略大于决策超时，防连接吊死。
+        const httpTimeout = (input.timeoutMs ?? 60_000) + 5_000;
+        const req = request({
+            host: '127.0.0.1',
+            port: lock.port,
+            path: '/ask',
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(payload),
+                'x-ask-token': lock.token,
+            },
+            timeout: httpTimeout,
+        }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (c) => {
+                body += c;
+            });
+            res.on('end', () => {
+                if (res.statusCode !== 200) {
+                    reject(new Error(`/ask 返回非 200：${res.statusCode ?? '?'}（${body}）`));
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(body);
+                    if (parsed.kind !== 'answered' && parsed.kind !== 'timeout') {
+                        reject(new Error('/ask 响应 kind 非法'));
+                        return;
+                    }
+                    resolve(parsed);
+                }
+                catch (error) {
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        });
+        req.on('error', reject);
+        req.on('timeout', () => {
+            req.destroy(new Error('/ask 请求超时'));
+        });
+        req.write(payload);
+        req.end();
+    });
+}
+/** 守护进程 stderr 重定向日志路径（便于排查）。 */
+function daemonLogPath() {
+    return join(tmpdir(), 'dingtalk-daemon.log');
+}
+/**
+ * 解析要拉起的守护进程脚本路径。
+ *
+ * 守护进程必须是编译后的 `dist/daemon.js`（用 node 拉起，跑不了 .ts）。生产下本模块位于
+ * `dist/daemonClient.js`，同级解析即得 `dist/daemon.js`；但在 dev/tsx 下本模块从 `src/`
+ * 运行，同级会解析到不存在的 `src/daemon.js` —— 此时回退到 `dist/daemon.js`。
+ *
+ * @returns 存在的守护进程脚本绝对路径。
+ */
+function resolveDaemonScript() {
+    const sibling = fileURLToPath(new URL('./daemon.js', import.meta.url));
+    if (existsSync(sibling)) {
+        return sibling;
+    }
+    // dev/tsx：本模块在 src，编译产物在 dist。
+    const inDist = sibling.replace(/([\\/])src\1/, '$1dist$1');
+    return existsSync(inDist) ? inDist : sibling;
+}
+/**
+ * detached 拉起守护进程子进程（脱离父进程存活）。
+ *
+ * 把已解析的钉钉配置注入子进程 env —— 这样即便 MCP server 的凭证来自 CLI 参数（非 env），
+ * 守护进程（只读 process.env）也能拿到。凭证只经 env 传递，不落盘、不入命令行。
+ *
+ * @param config 已解析的钉钉配置。
+ */
+function spawnDaemon(config) {
+    const daemonScript = resolveDaemonScript();
+    const logFd = openSync(daemonLogPath(), 'a');
+    const child = spawn(process.execPath, [daemonScript], {
+        detached: true,
+        windowsHide: true,
+        stdio: ['ignore', logFd, logFd],
+        env: {
+            ...process.env,
+            // 注入解析后的凭证，覆盖可能缺失/过期的 env（支持 CLI 参数来源）。
+            DINGTALK_CLIENT_ID: config.clientId,
+            DINGTALK_CLIENT_SECRET: config.clientSecret,
+            DINGTALK_ROBOT_CODE: config.robotCode,
+            DINGTALK_USER_ID: config.userId,
+            DINGTALK_ASK_TIMEOUT_MS: String(config.timeoutMs),
+        },
+    });
+    child.unref();
+    console.error(`已拉起钉钉守护进程（pid=${child.pid ?? '?'}，脚本 ${daemonScript}，日志 ${daemonLogPath()}）。`);
+}
+/**
+ * 确保守护进程在跑并就绪，返回其锁（port + token）。
+ *
+ * 流程：读锁探活——就绪则直接用；有锁但活着未就绪则轮询等待；无锁/锁属死进程则拉起并轮询。
+ *
+ * @param config 钉钉配置（拉起子进程需具备凭证）。
+ * @param lockPath 锁路径；缺省用 daemonLockPath()（测试注入隔离路径）。
+ * @returns 就绪守护进程的锁。
+ * @throws 当在 SPAWN_WAIT_MS 内仍未就绪时抛错。
+ */
+export async function ensureDaemon(config, lockPath = daemonLockPath()) {
+    const existing = readDaemonLock(lockPath);
+    if (existing !== undefined) {
+        const probe = await probeHealth(existing);
+        if (probe.ready) {
+            return existing;
+        }
+        // 有锁但未就绪：若端点根本不应答（死进程留下的陈旧锁）才拉起，否则等它就绪。
+        if (!probe.ok) {
+            spawnDaemon(config);
+        }
+    }
+    else {
+        spawnDaemon(config);
+    }
+    const deadline = Date.now() + SPAWN_WAIT_MS;
+    while (Date.now() < deadline) {
+        await sleep(POLL_INTERVAL_MS);
+        const lock = readDaemonLock(lockPath);
+        if (lock !== undefined && (await probeHealth(lock)).ready) {
+            return lock;
+        }
+    }
+    throw new Error(`守护进程未在 ${SPAWN_WAIT_MS}ms 内就绪（见日志 ${daemonLogPath()}）。`);
+}

package/dist/decision/coordinator.js

@@ -0,0 +1,36 @@
+/**
+ * 推送决策并等待回答，超时则返回 timeout 结果。
+ *
+ * @param channel 决策通道（钉钉等实现之）。
+ * @param req 决策请求，含 timeoutMs。
+ * @returns 决策结果，永不因超时挂死。
+ */
+export async function askWithTimeout(channel, req) {
+    const controller = new AbortController();
+    let timer;
+    // 超时侧：到点后返回一个专属哨兵，用于区分是超时还是 channel 答复。
+    const timeoutSignal = Symbol("timeout");
+    const timeoutPromise = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(timeoutSignal), req.timeoutMs);
+    });
+    try {
+        // channel.wait 在 abort 时可能 reject，但只要超时侧先胜出即由外层处理。
+        const winner = await Promise.race([
+            channel.wait(req, controller.signal),
+            timeoutPromise,
+        ]);
+        if (winner === timeoutSignal) {
+            // 超时先到：abort channel，让其放弃等待并清理 pending。
+            controller.abort();
+            return { kind: "timeout" };
+        }
+        // channel 先答：winner 是回复字符串。
+        return { kind: "answered", value: winner };
+    }
+    finally {
+        // 无论何种结局都清除超时定时器，防止泄漏。
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/decision/registry.js

@@ -0,0 +1,166 @@
+/**
+ * DecisionRegistry：多 Agent 并发决策的多槽通道（替代单槽 DingtalkChannel）。
+ *
+ * 实现同一个 DecisionChannel.wait(req, signal) 抽象，coordinator 不变；去掉进程级 mutex 后
+ * 多个 Agent 的决策可并发挂起。每个待决策分配一个短序号 seq（答完释放、复用最小空号），
+ * 消息带 `#seq [label]` 前缀推到钉钉；用户回复经 routeReply 按序号路由到对应槽。
+ *
+ * 单一 onReply 处理器：命中则 resolve 对应槽；多待答时歧义回复回一条编号提示（消费但不 resolve）；
+ * 零待答时返回 false，交上层（client.handleRobotMessage）判离开模式遥控命令——保持"决策优先"。
+ *
+ * 依赖注入 RegistryClient（真实为 DingtalkClient），便于用假 client 单测，不碰 SDK/网络。
+ * 日志走 stderr。
+ */
+import { allocSeq, routeReply, parseBatchReply } from './routing.js';
+import { resolveReplyValue } from '../dingtalk/replyMatcher.js';
+import { buildAskMessage, buildTextMessage } from '../dingtalk/cardPayload.js';
+import { parseAwayCommand } from '../awayState.js';
+/**
+ * 多槽决策通道。
+ */
+export class DecisionRegistry {
+    client;
+    /** seq → 槽；并发多待决策。 */
+    slots = new Map();
+    constructor(client) {
+        this.client = client;
+        this.client.onReply((text) => this.handleReply(text));
+    }
+    /**
+     * 推送一次决策到钉钉并等待用户回复。
+     *
+     * @param req 决策请求（含可选 label，用于消息前缀）。
+     * @param signal abort 信号：超时/取消时清槽并 reject。
+     * @returns 用户回复解析后的值。
+     * @throws 当 sendOto 失败或 abort 时 reject。
+     */
+    wait(req, signal) {
+        if (signal.aborted) {
+            return Promise.reject(new Error('决策等待已被取消（abort）。'));
+        }
+        // 同步分配 seq 并占槽（无 await，保证并发 wait 拿到不同序号）。
+        const seq = allocSeq(this.slots.keys());
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                if (this.slots.get(seq) === slot) {
+                    this.slots.delete(seq);
+                }
+                reject(new Error('决策等待超时或被取消。'));
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+            const slot = {
+                seq,
+                request: req,
+                resolve: (value) => {
+                    signal.removeEventListener('abort', onAbort);
+                    resolve(value);
+                },
+            };
+            this.slots.set(seq, slot);
+            // 推送失败：清槽、摘 abort 监听、reject（交 coordinator 收敛为可读文本）。
+            this.client.sendOto(buildAskMessage(req, { seq, label: req.label })).catch((error) => {
+                if (this.slots.get(seq) === slot) {
+                    this.slots.delete(seq);
+                    signal.removeEventListener('abort', onAbort);
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        });
+    }
+    /**
+     * 当前待答槽数（守护进程空闲自关判定用）。
+     *
+     * @returns 挂起中的决策数量。
+     */
+    pendingCount() {
+        return this.slots.size;
+    }
+    /**
+     * 处理一条文本回复：按当前待答数与序号路由。
+     *
+     * @param text 用户回复原文。
+     * @returns true 表示已被决策消费（不再当遥控命令）；false 表示无待答，交上层。
+     */
+    handleReply(text) {
+        // /away、/back 等显式遥控命令优先于决策路由：即便有待答也交上层切换离开模式。
+        // 命令带 `/` 前缀、不会与决策答案混淆，避免"多个决策挂起时够不到离开遥控"的死角。
+        if (parseAwayCommand(text) !== null) {
+            return false;
+        }
+        const pendingSeqs = [...this.slots.keys()];
+        if (pendingSeqs.length === 0) {
+            return false; // 无待答：交上层判遥控命令。
+        }
+        // 恰一个待答：免序号，整串为答案。
+        if (pendingSeqs.length === 1) {
+            const slot = this.slots.get(pendingSeqs[0]);
+            return slot !== undefined ? this.tryResolve(slot, text.trim()) : false;
+        }
+        // 多待答：先尝试批量解析（一条消息答多个，如 "1 允许、2 拒绝"）。
+        const batch = parseBatchReply(text, pendingSeqs);
+        if (batch.length > 0) {
+            for (const { seq, answer } of batch) {
+                const slot = this.slots.get(seq);
+                if (slot !== undefined) {
+                    this.tryResolve(slot, answer);
+                }
+            }
+            return true;
+        }
+        // 无可解析序号：用 routeReply 给出针对性提示（缺序号/序号无效/缺答案）。
+        const route = routeReply(text, pendingSeqs);
+        if (route.kind === 'need-seq' || route.kind === 'unknown-seq' || route.kind === 'need-answer') {
+            this.sendNudge(route);
+        }
+        return true;
+    }
+    /**
+     * 尝试用答案 resolve 一个槽；空白答案则消费但继续等待。
+     *
+     * @param slot 目标槽。
+     * @param answer 去序号后的答案原文。
+     * @returns 恒为 true（消费本消息）。
+     */
+    tryResolve(slot, answer) {
+        const value = resolveReplyValue(answer, slot.request.options);
+        if (value === undefined) {
+            console.error('收到空白钉钉回复，已忽略，继续等待。');
+            return true;
+        }
+        this.slots.delete(slot.seq);
+        slot.resolve(value);
+        return true;
+    }
+    /**
+     * 对歧义回复回一条编号提示（不 resolve 任何槽）。
+     *
+     * @param route 需要提示的路由结果。
+     */
+    sendNudge(route) {
+        let text;
+        if (route.kind === 'need-answer') {
+            text = `请在编号 #${route.seq} 后带上你的选择，如「${route.seq} 允许」。`;
+        }
+        else if (route.kind === 'unknown-seq') {
+            text = `序号 #${route.seq} 无对应待答。当前待答：${this.describePending()}，请用其中的编号回复（如「1 允许」）。`;
+        }
+        else {
+            text = `当前有多个待答，请在前面加编号回复，如「1 允许」。当前待答：${this.describePending()}`;
+        }
+        this.client.sendOto(buildTextMessage(text)).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`编号提示发送失败：${message}`);
+        });
+    }
+    /**
+     * 列出当前待答槽，形如 `#1 [web]、#2 [api]`（按 seq 升序）。
+     *
+     * @returns 待答描述串。
+     */
+    describePending() {
+        return [...this.slots.values()]
+            .sort((a, b) => a.seq - b.seq)
+            .map((s) => `#${s.seq} [${s.request.label ?? '?'}]`)
+            .join('、');
+    }
+}

package/dist/decision/resultText.js

@@ -0,0 +1,15 @@
+/**
+ * 把决策结果转成工具返回字符串。
+ *
+ * @param outcome 决策结果。
+ * @param timeoutMs 该次决策的超时毫秒数，仅 timeout 分支用于换算分钟数展示。
+ */
+export function resultText(outcome, timeoutMs = 0) {
+    if (outcome.kind === "answered") {
+        return `用户选择：${outcome.value ?? ""}`;
+    }
+    // timeout：换算成分钟（四舍五入），便于模型对用户复述等待时长。
+    const minutes = Math.round(timeoutMs / 60_000);
+    return (`用户未在约 ${minutes} 分钟内回复。请你自行决定：` +
+        `继续等待（可再次调用 ask_human）、选择一个安全默认、或停止并说明原因。`);
+}