dingtalk-ask-mcp-server 0.1.0

package/dist/decision/routing.js

@@ -0,0 +1,102 @@
+/**
+ * 多 Agent 并发决策的回复路由（纯函数，可测）。
+ *
+ * 并发/回复模型 = 并行 + 编号回复：
+ * - 多个 Agent 的问题同时挂在钉钉，每条带 #序号；用户回 "1 允许"/"2 拒绝" 按序号路由。
+ * - 只有一个待答时可免序号，整串即答案。
+ *
+ * 本模块只负责"从原始回复文本 + 当前待答序号集"判断该路由给谁 / 是否需要提示补全，
+ * 不涉及 IM/网络/选项匹配（选项匹配交给已测的 replyMatcher.resolveReplyValue）。
+ */
+/** 拆"前缀数字 + 其余"的正则：其余用 [\s\S]* 以容纳多行自由文本。 */
+const SEQ_PREFIX = /^\s*(\d+)\s*([\s\S]*)$/;
+/**
+ * 分配一个不在活跃集合里的最小正整数序号（答完释放、复用，保持号短好记）。
+ *
+ * @param activeSeqs 当前已占用的序号集合（任意可迭代）。
+ * @returns 最小的、未被占用的正整数。
+ */
+export function allocSeq(activeSeqs) {
+    const set = new Set(activeSeqs);
+    let n = 1;
+    while (set.has(n)) {
+        n += 1;
+    }
+    return n;
+}
+/**
+ * 把一条用户回复分流为路由结果。
+ *
+ * 规则：
+ * - 待答数 0 → none（上层走离开模式遥控命令判定）。
+ * - 待答数 1 → single，整串 trim 后为答案（免序号；即使以数字开头也当答案，避免歧义）。
+ * - 待答数 >1 → 必须带命中的前缀序号：
+ *   · 无数字前缀 → need-seq；
+ *   · 有前缀但不在待答集 → unknown-seq；
+ *   · 有前缀在待答集但答案为空 → need-answer；
+ *   · 否则 → routed（answer 为去掉序号后的原文，保留内部空格/换行）。
+ *
+ * @param text 用户回复原文。
+ * @param pendingSeqs 当前待答的序号集合。
+ * @returns 路由结果。
+ */
+export function routeReply(text, pendingSeqs) {
+    if (pendingSeqs.length === 0) {
+        return { kind: 'none' };
+    }
+    if (pendingSeqs.length === 1) {
+        return { kind: 'single', answer: text.trim() };
+    }
+    const match = SEQ_PREFIX.exec(text);
+    if (match === null) {
+        return { kind: 'need-seq' };
+    }
+    const seq = Number(match[1]);
+    if (!pendingSeqs.includes(seq)) {
+        return { kind: 'unknown-seq', seq };
+    }
+    const answer = match[2].trim();
+    if (answer === '') {
+        return { kind: 'need-answer', seq };
+    }
+    return { kind: 'routed', seq, answer };
+}
+/** 批量回复的分隔符：序号前须是行首或这些分隔符之一，才当作新段起点（避免答案里的数字被误拆）。 */
+const BATCH_DELIM = /(?:^|[\s、,，;；])(\d+)/g;
+/**
+ * 从一条消息里解析出多段"序号 答案"（支持用户把多个回复写在同一条消息，如 "1 允许、2 拒绝"）。
+ *
+ * 只把"行首或分隔符后紧跟的、且命中待答集的数字"当作段起点；答案取到下一个段起点之前，
+ * 去掉首尾分隔符与空白。这样 "我选方案2" 里的 2 不会被误当序号（前面是汉字非分隔符）。
+ *
+ * @param text 用户回复原文。
+ * @param pendingSeqs 当前待答序号集合。
+ * @returns 依出现顺序的 {seq, answer} 段；答案为空的段丢弃；无有效段则空数组。
+ */
+export function parseBatchReply(text, pendingSeqs) {
+    const pending = new Set(pendingSeqs);
+    const marks = [];
+    BATCH_DELIM.lastIndex = 0;
+    let m;
+    while ((m = BATCH_DELIM.exec(text)) !== null) {
+        const seq = Number(m[1]);
+        if (pending.has(seq)) {
+            marks.push({ seq, matchStart: m.index, answerStart: m.index + m[0].length });
+        }
+    }
+    const segments = [];
+    const seen = new Set();
+    for (let i = 0; i < marks.length; i += 1) {
+        const cur = marks[i];
+        if (seen.has(cur.seq)) {
+            continue; // 同一序号重复出现，保留首个。
+        }
+        const end = i + 1 < marks.length ? marks[i + 1].matchStart : text.length;
+        const answer = text.slice(cur.answerStart, end).replace(/^[\s、,，;；]+/, '').trim();
+        if (answer !== '') {
+            seen.add(cur.seq);
+            segments.push({ seq: cur.seq, answer });
+        }
+    }
+    return segments;
+}

package/dist/decision/types.js

@@ -0,0 +1,8 @@
+/**
+ * 决策层核心契约：与钉钉/任何具体 IM 无关的抽象类型。
+ *
+ * decision 层刻意不依赖钉钉 SDK，只描述"一次待人拍板的决策请求、
+ * 决策结果、以及一个可回答决策的通道"。钉钉在 M2 作为首个 DecisionChannel
+ * 实现之，未来可扩其它 IM。全部字段无 any。
+ */
+export {};

package/dist/dingtalk/cardPayload.js

@@ -0,0 +1,76 @@
+/** markdown 形态消息标题（钉钉 markdown 消息体要求 title 非空）。 */
+const MARKDOWN_TITLE = '需要你拍板一个决策';
+/**
+ * 拼 `#seq [label] ` 前缀（两者按各自有无分别拼，允许只有其一）。
+ *
+ * @param ctx 渲染上下文。
+ * @returns 前缀串（末尾带一个空格）；无 seq 无 label 时为空串。
+ */
+function buildPrefix(ctx) {
+    const parts = [];
+    if (ctx.seq !== undefined) {
+        parts.push(`#${ctx.seq}`);
+    }
+    if (ctx.label !== undefined && ctx.label !== '') {
+        parts.push(`[${ctx.label}]`);
+    }
+    return parts.length > 0 ? `${parts.join(' ')} ` : '';
+}
+/**
+ * 拼编号回复提示（仅当有 seq 时）。示例优先用首个选项，否则用「你的决定」。
+ *
+ * @param ctx 渲染上下文。
+ * @param options 候选选项（用于取示例词）。
+ * @returns 编号提示串；无 seq 时为空串。
+ */
+function buildNumberHint(ctx, options) {
+    if (ctx.seq === undefined) {
+        return '';
+    }
+    const example = options !== undefined && options.length > 0 ? options[0] : '你的决定';
+    return `\n\n（多个问题时在前面加编号回复，如「${ctx.seq} ${example}」；只有一个待答时可直接回复）`;
+}
+/**
+ * 由决策请求构造主动发送消息体。
+ *
+ * @param req 决策请求，含 question 与可选 options。
+ * @param ctx 多 Agent 渲染上下文（seq/label）；缺省则为单 Agent 旧形态。
+ * @returns 钉钉 OTO 主动发送消息体（文本或 markdown）。
+ */
+export function buildAskMessage(req, ctx = {}) {
+    const options = req.options;
+    const prefix = buildPrefix(ctx);
+    const heading = `${prefix}${req.question}`;
+    const numberHint = buildNumberHint(ctx, options);
+    // 无 options（含空数组）：纯文本问答，提示直接回复决定。
+    if (options === undefined || options.length === 0) {
+        const content = `${heading}\n\n（直接回复你的决定即可）${numberHint}`;
+        return {
+            msgKey: 'sampleText',
+            msgParam: JSON.stringify({ content })
+        };
+    }
+    // 有 options：markdown 列出带 1-based 序号的选项，提示回复序号或自由文本。
+    const optionLines = options.map((opt, i) => `${i + 1}. ${opt}`).join('\n');
+    const text = `${heading}\n\n` +
+        `${optionLines}\n\n` +
+        `（回复序号选择，或直接输入你的选择/意见）${numberHint}`;
+    return {
+        msgKey: 'sampleMarkdown',
+        msgParam: JSON.stringify({ title: MARKDOWN_TITLE, text })
+    };
+}
+/**
+ * 构造一条纯文本 OTO 主动发送消息体（纯函数，可测）。
+ *
+ * 用于系统回执类消息（如离开模式开关确认），不走决策问答格式。
+ *
+ * @param content 文本正文。
+ * @returns sampleText 形态消息体（msgParam 为 { content } 的 JSON 字符串）。
+ */
+export function buildTextMessage(content) {
+    return {
+        msgKey: 'sampleText',
+        msgParam: JSON.stringify({ content })
+    };
+}

package/dist/dingtalk/channel.js

@@ -0,0 +1,68 @@
+import { resolveReplyValue } from './replyMatcher.js';
+import { buildAskMessage } from './cardPayload.js';
+// resolveReplyValue 已归位到 replyMatcher.ts（channel 与 registry 共用）；此处 re-export 保持既有引用。
+export { resolveReplyValue };
+/**
+ * 决定一条回复是否应 resolve 当前决策、以及 resolve 的值：见 replyMatcher.resolveReplyValue。
+ */
+export class DingtalkChannel {
+    client;
+    /** 单槽 pending：至多一个待决策；无待决策时为 undefined。 */
+    active;
+    constructor(client) {
+        this.client = client;
+        // 注册一次文本回复处理器；返回是否存在待决策（有则本消息归决策，不当遥控命令）。
+        this.client.onReply((text) => this.handleReply(text));
+    }
+    /**
+     * 推送决策到钉钉并等待用户文本回复。
+     *
+     * @param req 决策请求。
+     * @param signal abort 信号：超时/取消时清空 active 并放弃等待。
+     * @returns 用户回复解析后的值（选项文本或自由文本原文）。
+     * @throws 当 sendOto 主动发送失败时抛错（交 coordinator，最终转可读文本给模型）。
+     */
+    async wait(req, signal) {
+        // 先推送再挂 pending：推送失败直接抛错，不占用单槽。
+        await this.client.sendOto(buildAskMessage(req));
+        return new Promise((resolve, reject) => {
+            // 已 abort（极端时序）：立即放弃。
+            if (signal.aborted) {
+                reject(new Error('决策等待已被取消（abort）。'));
+                return;
+            }
+            this.active = { request: req, resolve };
+            const onAbort = () => {
+                // 超时/取消：清空单槽并 reject，coordinator 由超时侧接管返回 timeout。
+                if (this.active?.request.id === req.id) {
+                    this.active = undefined;
+                }
+                reject(new Error('决策等待超时或被取消。'));
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    /**
+     * 处理一条文本回复：仅在有 active 决策且回复有效时 resolve 并清空单槽。
+     *
+     * @param text 用户回复原文。
+     * @returns true 表示当前有待决策、本消息归它（即便空白也不外泄给遥控命令判定）；
+     *          false 表示无待决策（上层可再判离开模式遥控命令）。
+     */
+    handleReply(text) {
+        if (this.active === undefined) {
+            // 无待决策：交回上层（可能是离开模式遥控命令）。
+            return false;
+        }
+        const value = resolveReplyValue(text, this.active.request.options);
+        if (value === undefined) {
+            // 空白回复：不结束等待，但有待决策，消息仍归它（不当遥控命令）。
+            console.error('收到空白钉钉回复，已忽略，继续等待。');
+            return true;
+        }
+        const { resolve } = this.active;
+        this.active = undefined;
+        resolve(value);
+        return true;
+    }
+}

package/dist/dingtalk/client.js

@@ -0,0 +1,253 @@
+/**
+ * 钉钉 SDK/网络调用的集中封装：所有与 dingtalk-stream / axios 的交互都收敛到本文件，
+ * 便于上层（channel.ts）注入 mock 单测，且把易变的"官方端点/鉴权细节"集中在一处。
+ *
+ * 职责：
+ * - connect()：建 DWClient、订阅机器人消息回调（TOPIC_ROBOT）、建立 Stream 长连。
+ *   收到单聊文本时解析出 text.content + senderStaffId，**只接受来自 config.userId 的消息**，
+ *   转交上层注册的 reply 处理器。
+ * - sendOto()：取 accessToken → axios POST 机器人 OTO 批量发单聊（batchSend）。
+ * - onReply()：注册文本回复回调（channel.ts 用之等待回复）。
+ * - close()：断开 Stream 长连。
+ *
+ * 纯逻辑抽出：buildBatchSendBody(config, message) —— 组装 batchSend 请求 body，无副作用可单测。
+ *
+ * 安全：绝不硬编码任何凭证；一切从注入的 DingtalkConfig（其源头是 process.env）读取。
+ * 日志一律走 stderr（stdout 是 MCP 协议信道）。
+ */
+import axios from 'axios';
+import { DWClient, TOPIC_ROBOT } from 'dingtalk-stream';
+import { buildTextMessage } from './cardPayload.js';
+import { setAway, parseAwayCommand } from '../awayState.js';
+/** 机器人 OTO 批量发单聊端点（官方 v1.0）。 */
+const BATCH_SEND_URL = 'https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend';
+/** accessToken 兜底端点（SDK getAccessToken 不可用时用）。 */
+const ACCESS_TOKEN_URL = 'https://api.dingtalk.com/v1.0/oauth2/accessToken';
+/**
+ * 组装机器人 OTO 批量发单聊的请求 body（纯函数，可单测）。
+ *
+ * @param config 钉钉配置，提供 robotCode 与目标 userId。
+ * @param message 消息内容（msgKey + msgParam，来自 buildAskMessage）。
+ * @returns 可直接作为 batchSend 请求体的对象。
+ */
+export function buildBatchSendBody(config, message) {
+    return {
+        robotCode: config.robotCode,
+        // 单聊单目标：MVP 只推给配置的本人 userId。
+        userIds: [config.userId],
+        msgKey: message.msgKey,
+        msgParam: message.msgParam,
+    };
+}
+/**
+ * 钉钉客户端：集中所有 SDK/网络调用。进程级单例，server 启动时 connect，退出时 close。
+ */
+export class DingtalkClient {
+    config;
+    /** Stream 长连客户端；connect 前为 undefined。 */
+    dwClient;
+    /** 上层注册的文本回复处理器；未注册时收到消息仅记日志。 */
+    replyHandler;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * 建立 Stream 长连并订阅机器人消息回调。
+     *
+     * 收到消息时：解析 data JSON → 取 text.content + senderStaffId → 仅接受 config.userId
+     * 的文本消息 → 转交 replyHandler。非目标用户/非文本/无处理器时忽略（记 stderr）。
+     *
+     * @returns 长连建立完成的 Promise。
+     * @throws 当 SDK 连接失败时抛错，交上层决定告警/降级。
+     */
+    async connect() {
+        const client = new DWClient({
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            // 心跳保活：MCP server 会挂着等待用户决策（分钟~十几分钟级），
+            // 不开保活时空闲长连可能被钉钉网关断开，导致回复丢失。
+            keepAlive: true,
+            // 可选 debug（DINGTALK_DEBUG=1）：打印握手/订阅/每帧下行，便于排查连接问题。
+            debug: process.env.DINGTALK_DEBUG === '1',
+        });
+        client.registerCallbackListener(TOPIC_ROBOT, (res) => {
+            // 无论后续处理成败，都先 ack，避免服务端 60s 内重推同一消息。
+            try {
+                client.socketCallBackResponse(res.headers.messageId, { status: 'SUCCESS' });
+            }
+            catch {
+                // ack 失败不致命（最多重复推送），不阻断消息处理。
+            }
+            this.handleRobotMessage(res.data);
+        });
+        await client.connect();
+        this.dwClient = client;
+        // SDK 的 connect() 会吞掉网关握手失败（内部 catch + 后台自动重连后正常返回），
+        // 因此这里显式校验 connected，避免"假报连接成功"。未连上仅告警不抛：
+        // autoReconnect 会在后台持续重试，恢复后即可收到回复（期间 ask_human 走超时分支）。
+        if (!client.connected) {
+            console.error('钉钉 Stream 首次握手未成功（可能凭证/消息接收模式/发布状态有误）；已启用后台自动重连。');
+        }
+    }
+    /**
+     * 解析并分发一条机器人消息（从 registerCallbackListener 回调进入）。
+     *
+     * 拆成独立方法便于阅读与将来单测；只处理"文本 + 目标用户"的消息，其余忽略并记 stderr。
+     *
+     * @param rawData Stream 下行消息的 data 字段（JSON 字符串）。
+     */
+    handleRobotMessage(rawData) {
+        let parsed;
+        try {
+            parsed = JSON.parse(rawData);
+        }
+        catch {
+            console.error('钉钉消息解析失败：data 非合法 JSON，已忽略。');
+            return;
+        }
+        const senderStaffId = parsed.senderStaffId ?? '';
+        // 只接受配置的本人 userId 的消息，防止其他人误触决策。
+        if (senderStaffId !== this.config.userId) {
+            console.error(`钉钉消息来自非目标用户（senderStaffId=${senderStaffId}），已忽略。`);
+            return;
+        }
+        // M2 只处理文本消息；非文本（图片/卡片等）暂不支持。
+        if (parsed.msgtype !== 'text' || parsed.text?.content === undefined) {
+            console.error(`钉钉消息非文本类型（msgtype=${parsed.msgtype}），已忽略。`);
+            return;
+        }
+        const content = parsed.text.content;
+        // 决策优先：有待决策时，回复先归决策消费，避免被误当遥控命令。
+        // replyHandler 返回 true 表示存在待决策并已消费本消息。
+        const consumedByDecision = this.replyHandler?.(content, senderStaffId) ?? false;
+        if (consumedByDecision) {
+            return;
+        }
+        // 无待决策 → 再判离开模式遥控命令（手机遥控开关）：命中则切换状态 + 回执确认。
+        const awayCmd = parseAwayCommand(content);
+        if (awayCmd !== null) {
+            setAway(awayCmd === 'on');
+            const receipt = awayCmd === 'on'
+                ? '✅ 已进入离开模式，命令审批与决策会推到这里（发 /back 退出）'
+                : '✅ 已退出离开模式，命令审批与决策只在终端（发 /away 再进入）';
+            // 回执发送失败仅告警不抛：遥控状态已切换成功，回执只是告知。
+            this.sendOto(buildTextMessage(receipt)).catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`离开模式回执发送失败：${message}`);
+            });
+            return;
+        }
+        // 既无待决策、也非遥控命令：忽略（记 stderr）。
+        console.error('收到钉钉消息但当前无待决策、也非遥控命令，已忽略。');
+    }
+    /**
+     * 注册文本回复回调（channel.ts 用之接收用户回复）。MVP 单处理器，后注册覆盖先注册。
+     *
+     * @param handler 文本回复处理器。
+     */
+    onReply(handler) {
+        this.replyHandler = handler;
+    }
+    /**
+     * 主动发送 OTO 单聊消息（batchSend）。
+     *
+     * 流程：取 accessToken → axios POST batchSend（robotCode + userIds=[config.userId] + msgKey/msgParam）。
+     * 失败抛错，错误信息含 HTTP 状态与钉钉 errcode/message，便于定位。
+     *
+     * @param message 消息内容（来自 buildAskMessage）。
+     * @throws 当取 token 或 batchSend 请求失败时抛错。
+     */
+    async sendOto(message) {
+        const token = await this.getAccessToken();
+        const body = buildBatchSendBody(this.config, message);
+        try {
+            await axios.post(BATCH_SEND_URL, body, {
+                headers: {
+                    'x-acs-dingtalk-access-token': token,
+                    'Content-Type': 'application/json',
+                },
+            });
+        }
+        catch (error) {
+            throw new Error(`钉钉 OTO 主动发送失败：${describeAxiosError(error)}`);
+        }
+    }
+    /**
+     * 取 accessToken：优先复用 SDK 的 DWClient.getAccessToken()（已建连时）；
+     * 否则兜底走官方 oauth2/accessToken 端点。
+     *
+     * @returns accessToken 字符串。
+     * @throws 当两条路径都取不到 token 时抛错。
+     */
+    async getAccessToken() {
+        if (this.dwClient !== undefined) {
+            try {
+                const token = await this.dwClient.getAccessToken();
+                if (typeof token === 'string' && token !== '') {
+                    return token;
+                }
+                console.error('SDK getAccessToken 返回空，改用 oauth2 兜底。');
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`SDK getAccessToken 失败（${message}），改用 oauth2 兜底。`);
+            }
+        }
+        // 兜底：官方 v1.0 oauth2 端点，body { appKey, appSecret } → { accessToken }。
+        try {
+            const res = await axios.post(ACCESS_TOKEN_URL, {
+                appKey: this.config.clientId,
+                appSecret: this.config.clientSecret,
+            });
+            const accessToken = res.data.accessToken;
+            if (typeof accessToken !== 'string' || accessToken === '') {
+                throw new Error('响应缺少 accessToken 字段');
+            }
+            return accessToken;
+        }
+        catch (error) {
+            throw new Error(`获取钉钉 accessToken 失败：${describeAxiosError(error)}`);
+        }
+    }
+    /**
+     * 断开 Stream 长连（若已建连）。进程退出前调用，释放 socket。
+     *
+     * @returns 断连完成的 Promise（SDK disconnect 为同步，这里统一成 async 契约）。
+     */
+    async close() {
+        if (this.dwClient !== undefined) {
+            this.dwClient.disconnect();
+            this.dwClient = undefined;
+        }
+    }
+}
+/**
+ * 把 axios / 未知错误转成含 HTTP 状态与钉钉 errcode/message 的可读文本。
+ *
+ * @param error 捕获到的未知错误。
+ * @returns 可读错误描述。
+ */
+function describeAxiosError(error) {
+    if (axios.isAxiosError(error)) {
+        const axiosError = error;
+        const status = axiosError.response?.status;
+        const data = axiosError.response?.data;
+        const parts = [];
+        if (status !== undefined) {
+            parts.push(`HTTP ${status}`);
+        }
+        // 钉钉 v1.0 错误体常见 { code, message }；旧接口为 { errcode, errmsg }，两者都收。
+        if (data?.errcode !== undefined) {
+            parts.push(`errcode=${data.errcode}`);
+        }
+        if (data?.code !== undefined) {
+            parts.push(`code=${data.code}`);
+        }
+        const detail = data?.message ?? data?.errmsg ?? axiosError.message;
+        if (detail !== undefined && detail !== '') {
+            parts.push(detail);
+        }
+        return parts.length > 0 ? parts.join(' ') : axiosError.message;
+    }
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/dingtalk/config.js

@@ -0,0 +1,79 @@
+/**
+ * 钉钉凭证与运行参数解析（纯函数，可测：给假 env 注入，不读模块顶层 process.env）。
+ *
+ * 从传入的 env 解析四项必填凭证与一项可选超时：
+ * - 必填：DINGTALK_CLIENT_ID / DINGTALK_CLIENT_SECRET / DINGTALK_ROBOT_CODE / DINGTALK_USER_ID。
+ * - 可选：DINGTALK_ASK_TIMEOUT_MS（默认 1_500_000 ≈ 25 分钟，留足宿主 MCP 工具超时余量）。
+ *
+ * 设计取舍：
+ * - 不在模块顶层读 process.env，改为接收 env 参数，便于单测注入且无副作用。
+ * - 任一必填缺失/空串（含仅空白）→ 抛错，错误信息逐项列出所有缺失项，方便一次补齐（AC5）。
+ * - 超时非法（非数字/非正整数）视为配置错误直接抛错，而非静默回退默认——避免用户误配
+ *   却拿到与预期不符的等待时长；空串/仅空白视为"未提供"，回退默认。
+ */
+/** 内部超时默认值（毫秒）：约 25 分钟，留足宿主 MCP 工具超时余量。 */
+export const DEFAULT_ASK_TIMEOUT_MS = 1_500_000;
+/** 必填环境变量名，顺序即错误信息中的列出顺序。 */
+const REQUIRED_KEYS = [
+    'DINGTALK_CLIENT_ID',
+    'DINGTALK_CLIENT_SECRET',
+    'DINGTALK_ROBOT_CODE',
+    'DINGTALK_USER_ID'
+];
+/** 可选超时环境变量名。 */
+const TIMEOUT_KEY = 'DINGTALK_ASK_TIMEOUT_MS';
+/**
+ * 从 env 解析钉钉配置。
+ *
+ * @param env 环境变量对象（生产传 process.env，测试传假对象）。
+ * @returns 已校验的 DingtalkConfig。
+ * @throws 当任一必填缺失/空，或 timeout 非法（非正整数）时抛错，信息明确指出问题项。
+ */
+export function resolveDingtalkConfig(env) {
+    // 逐项收集缺失的必填项，一次性列全，避免用户"补一个报一个"。
+    const missing = [];
+    const values = {
+        DINGTALK_CLIENT_ID: '',
+        DINGTALK_CLIENT_SECRET: '',
+        DINGTALK_ROBOT_CODE: '',
+        DINGTALK_USER_ID: ''
+    };
+    for (const key of REQUIRED_KEYS) {
+        const trimmed = (env[key] ?? '').trim();
+        if (trimmed === '') {
+            missing.push(key);
+        }
+        else {
+            values[key] = trimmed;
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(`缺少必填钉钉环境变量：${missing.join('、')}`);
+    }
+    return {
+        clientId: values.DINGTALK_CLIENT_ID,
+        clientSecret: values.DINGTALK_CLIENT_SECRET,
+        robotCode: values.DINGTALK_ROBOT_CODE,
+        userId: values.DINGTALK_USER_ID,
+        timeoutMs: resolveTimeoutMs(env[TIMEOUT_KEY])
+    };
+}
+/**
+ * 解析可选超时：未提供/空串 → 默认；提供则必须为正整数，否则抛错。
+ *
+ * @param raw 原始超时字符串（可能为 undefined）。
+ * @returns 校验后的正整数毫秒数。
+ * @throws 当提供了非正整数值时抛错。
+ */
+function resolveTimeoutMs(raw) {
+    const trimmed = (raw ?? '').trim();
+    if (trimmed === '') {
+        return DEFAULT_ASK_TIMEOUT_MS;
+    }
+    // 用 Number 而非 parseInt，避免 "1000abc" 被静默截断为 1000。
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`环境变量 ${TIMEOUT_KEY} 必须为正整数毫秒数，当前值非法：${trimmed}`);
+    }
+    return parsed;
+}

package/dist/dingtalk/replyMatcher.js

@@ -0,0 +1,69 @@
+/**
+ * 回复匹配（纯函数，可测）：把用户在钉钉里的文本回复映射到候选选项，或作为自由文本。
+ *
+ * 匹配优先级（trim 首尾空白后）：
+ * 1. 序号：用户回 "1"/"2"（1-based），映射 options[i-1]；越界或 0/负数当作非序号继续后续匹配。
+ * 2. 精确文本命中：trim 后的回复等于某个 option。
+ * 3. 包含命中：回复文本包含某个 option（如"我选继续部署吧"含"继续部署"）。
+ *
+ * 边界约定：
+ * - 无 options：任何非空回复直接作为自由文本（kind: "free"）；纯数字也是自由文本（无候选可映射）。
+ * - 有 options 但都不中：作为自由文本透传原文（trim 后），让上层/模型自行判断，不强行归类。
+ * - 多个 option 同时被"包含"命中：取 options 顺序中第一个命中者（稳定、可预期）。
+ * - 空串/仅空白：作为 free，value 为空串。
+ *
+ * 返回结构用 kind 区分命中的是候选选项还是自由文本，option 情形附带 0-based index，
+ * 便于上层（如卡片回传核对）使用。
+ */
+/**
+ * 匹配用户回复。
+ *
+ * @param replyText 用户在钉钉里的原始回复文本。
+ * @param options 候选选项；缺省或空数组时任何非空回复都作为自由文本。
+ * @returns 命中的选项或自由文本结果。
+ */
+export function matchReply(replyText, options) {
+    const trimmed = replyText.trim();
+    // 无候选：直接作为自由文本（含纯数字，因为没有可映射的候选）。
+    if (options === undefined || options.length === 0) {
+        return { kind: 'free', value: trimmed };
+    }
+    // 1. 序号命中：整串是纯正整数且落在 1..options.length 范围内。
+    if (/^\d+$/.test(trimmed)) {
+        const ordinal = Number(trimmed);
+        if (ordinal >= 1 && ordinal <= options.length) {
+            const index = ordinal - 1;
+            return { kind: 'option', value: options[index], index };
+        }
+        // 越界/为 0：不 return，落到后续文本匹配（通常会归为 free）。
+    }
+    // 2. 精确文本命中。
+    const exactIndex = options.findIndex((opt) => opt === trimmed);
+    if (exactIndex !== -1) {
+        return { kind: 'option', value: options[exactIndex], index: exactIndex };
+    }
+    // 3. 包含命中：按 options 顺序取第一个被回复文本包含的选项。
+    const containIndex = options.findIndex((opt) => opt !== '' && trimmed.includes(opt));
+    if (containIndex !== -1) {
+        return { kind: 'option', value: options[containIndex], index: containIndex };
+    }
+    // 有 options 但都不中：透传为自由文本，交上层/模型判断。
+    return { kind: 'free', value: trimmed };
+}
+/**
+ * 决定一条回复应 resolve 的值（纯判定，复用已测 matchReply）。
+ *
+ * 任何非空回复都会给值：命中选项取选项文本，否则取自由文本原文（透传交模型判断）。
+ * 空串/仅空白（matchReply 返回 free 且 value 为空）视为无效回复，返回 undefined（不结束等待）。
+ *
+ * @param text 用户回复原文。
+ * @param options 当前决策的候选选项。
+ * @returns 应 resolve 的值；undefined 表示忽略此回复继续等待。
+ */
+export function resolveReplyValue(text, options) {
+    const match = matchReply(text, options);
+    if (match.value === '') {
+        return undefined;
+    }
+    return match.value;
+}