dingtalk-ask-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 姬煜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# dingtalk-ask-mcp-server
+
+把 code agent(**Claude Code / Codex**)运行中「需要人拍板的决策」和「命令审批」推送到你的**钉钉**,阻塞等你在手机/钉钉回复,再把答复注回 agent。**离开电脑也能远程拍板,一套服务两个宿主通吃。**
+
+- **`ask_human` 工具** —— agent 遇到决策/确认时调用,推钉钉、阻塞等回复、答复注回模型。
+- **命令审批路由(Claude Code)** —— 把原生命令审批弹窗推钉钉,手机上批/拒(离开模式开启时)。
+- **离开模式** —— 统一总闸:在电脑前只走终端,离开时才推钉钉,不打扰。
+- **多 Agent** —— 多个窗口共用一条钉钉连接,问题带 `#序号 [项目名]` 前缀并行推送,回 `1 允许、2 拒绝` 精准路由。
+
+## 工作原理
+
+```
+Claude Code / Codex ──(MCP: ask_human)──┐
+命令审批钩子(仅 CC) ──(HTTP /ask)────────┤
+                                         ▼
+                        dingtalk-daemon(唯一共享守护进程,自动拉起)
+                                         ▼ 主动发送 / Stream 收
+                                    钉钉单聊(你本人)
+```
+守护进程独占唯一一条钉钉 Stream 连接(同应用多连接会被负载均衡),所有窗口/宿主经它收发,自动拉起、闲置 30 分钟自动退出。
+
+---
+
+## 一、前置:配一个钉钉机器人(一次性,必需)
+
+工具需要一个钉钉**企业内部应用(H5)**上的机器人,用 Stream 模式收发消息:
+
+1. 登录 [钉钉开放平台](https://open-dev.dingtalk.com) → **创建应用 → 企业内部应用**。
+2. 应用里 **添加应用能力 → 机器人**;**消息接收模式**选 **Stream 模式**。
+3. 权限里勾上 **「企业内机器人发送消息权限」**,并**发布**应用。
+4. 记下四项:
+   - `AppKey`  → 作 `--client-id`
+   - `AppSecret` → 作 `--client-secret`
+   - 机器人 `robotCode`(通常等于 AppKey)→ 作 `--robot-code`
+   - **你本人的 userId** → 作 `--user-id`(只有这个 userId 发的消息会被采纳)
+
+> 注意:**独立的「群自定义机器人」不支持 Stream**,必须走上面的企业内部应用 + 机器人能力。
+
+---
+
+## 二、安装
+
+```bash
+npm i -g dingtalk-ask-mcp-server
+```
+
+装完得到三个全局命令:`dingtalk-ask`(一键接入/管理)、`dingtalk-ask-mcp-server`(服务本体)、`dingtalk-ask-install-hook`(单独装钩子)。
+
+> 源码方式:克隆后在包目录 `npm install && npm run build && npm link`,同样得到全局命令。
+
+---
+
+## 三、接入(改哪些东西)
+
+### 方式 A:一键接入(推荐)
+
+```bash
+dingtalk-ask install --client-id <AppKey> --client-secret <AppSecret> \
+                     --robot-code <robotCode> --user-id <你的userId> \
+                     [--timeout 1440000] [--host cc|codex|both]
+```
+
+它会自动改这些(合并保留既有内容、幂等):
+
+| 宿主 | 改动的文件 | 写入内容 |
+|---|---|---|
+| **Claude Code** | `<当前目录>/.mcp.json` | `mcpServers.dingtalk-ask`(服务 + 凭证 env) |
+| | `<当前目录>/.claude/settings.json`(`--global` 则 `~/.claude/settings.json`) | `PermissionRequest` 钩子 + `env.MCP_TOOL_TIMEOUT` |
+| **Codex** | `~/.codex/config.toml` | `[mcp_servers.dingtalk-ask]`(含 `tool_timeout_sec=1500` + 凭证,先备份 `.bak`) |
+
+默认 **CC 必装,检测到 `~/.codex` 时 Codex 一并装**。装完**重启 Claude Code / 重开 Codex 会话**生效。
+
+### 方式 B:手动接入(想自己控制时)
+
+<details>
+<summary><b>Claude Code</b> —— 两处:MCP + 钩子</summary>
+
+1. `.mcp.json`(项目根,本地不入库):
+   ```json
+   {
+     "mcpServers": {
+       "dingtalk-ask": {
+         "command": "dingtalk-ask-mcp-server",
+         "args": ["--client-id","<AppKey>","--client-secret","<AppSecret>",
+                  "--robot-code","<robotCode>","--user-id","<userId>"]
+       }
+     }
+   }
+   ```
+   (也可用 `"command":"node","args":["<绝对路径>/dist/index.js"]` + `"env":{...}` 写法。)
+2. **命令审批钩子** `.claude/settings.json`:
+   ```json
+   { "hooks": { "PermissionRequest": [ { "matcher": "Bash",
+     "hooks": [ { "type": "command", "command": "dingtalk-ask-install-hook", "timeout": 60000 } ] } ] } }
+   ```
+   实际用 `node "<绝对路径>/dist/permissionHook.js"`;或直接跑 `dingtalk-ask-install-hook` 自动写入。
+3. `settings.local.json` 或 `settings.json` 的 `env` 设 **`MCP_TOOL_TIMEOUT`**(如 `1500000`),否则阻塞式 `ask_human` 会被宿主提前掐断(默认 60s)。
+</details>
+
+<details>
+<summary><b>Codex</b> —— 只需 MCP(命令审批不走钩子)</summary>
+
+`~/.codex/config.toml`:
+```toml
+[mcp_servers.dingtalk-ask]
+command = "dingtalk-ask-mcp-server"
+args = ["--client-id","<AppKey>","--client-secret","<AppSecret>","--robot-code","<robotCode>","--user-id","<userId>"]
+startup_timeout_sec = 30
+tool_timeout_sec = 1500   # 关键!默认仅 60s,ask_human 阻塞等回复会被砍断
+```
+Codex 若 `approval_policy="never"` 本就不弹命令审批,故只提供 `ask_human` / `set_away_mode`,与其它 Codex 钩子零冲突。
+</details>
+
+---
+
+## 四、使用
+
+### 离开模式(核心开关)
+- **默认关**:在电脑前,决策/审批只走终端,不推钉钉。
+- 离开电脑前开启,四种方式任选(同一个全局开关):
+  - 钉钉里发 **`/away`**(开)、**`/back`**(关) —— 最方便,手机上就能切;
+  - 对 agent 说「我出去一下 / 我回来了」,它会调 `set_away_mode` 工具;
+  - 命令行 `dingtalk-ask away on|off|status`。
+- 用 `/` 前缀命令(非汉字)是为了不和你的自由回复误撞。
+
+### 决策与审批
+- **`ask_human`**:agent 自己决定何时调用(遇到取舍/确认)。开了离开模式就推钉钉、阻塞等你回复;没开则让 agent 在终端问你。
+- **命令审批(CC)**:开了离开模式,需要批准的命令会推钉钉,回「允许 / 拒绝」;超时/看不懂一律**回落终端**,绝不误放行。
+
+### 多 Agent / 一条消息答多个
+多个窗口并发提问时,钉钉里每条带 `#序号 [项目名]`:
+- 只有一个待答 → 直接回 `允许`(免序号);
+- 多个待答 → 回 `1 允许`、`2 拒绝`;**也可一条消息答多个**:`1 允许、2 拒绝`(空格/顿号/换行分隔均可)。
+
+---
+
+## 五、命令参考
+
+```bash
+dingtalk-ask install …            # 一键接入(见上)
+dingtalk-ask daemon status|stop   # 查看/停止共享守护进程
+dingtalk-ask away on|off|status   # 本地切换离开模式
+dingtalk-ask-mcp-server --client-id … …   # 服务本体(一般由宿主拉起,极少手动跑)
+dingtalk-ask-install-hook [--global|<path>] # 只装 CC 命令审批钩子
+```
+
+守护进程自动拉起、闲置自动退出;`DINGTALK_DAEMON_IDLE_MS` 可调(`0` 禁用)。诊断:守护进程日志在系统临时目录 `dingtalk-daemon.log`;设 `DINGTALK_DEBUG=1` 打印钉钉每帧。
+
+---
+
+## 六、配置项
+
+| 项 | 传法 | 说明 |
+|---|---|---|
+| `DINGTALK_CLIENT_ID` / `--client-id` | env 或 CLI 参数 | AppKey(必填) |
+| `DINGTALK_CLIENT_SECRET` / `--client-secret` | 同上 | AppSecret(必填) |
+| `DINGTALK_ROBOT_CODE` / `--robot-code` | 同上 | robotCode(必填) |
+| `DINGTALK_USER_ID` / `--user-id` | 同上 | 你本人 userId(必填) |
+| `DINGTALK_ASK_TIMEOUT_MS` / `--timeout` | 同上 | 内部等待上限,默认 25 分钟 |
+| `DINGTALK_AGENT_LABEL` / `--agent-label` | 同上 | 钉钉里显示的来源标签,缺省用工作目录名 |
+
+CLI 参数优先于环境变量。⚠️ 命令行参数在进程列表(`ps`/tasklist)可见,介意暴露者用 env 段。**凭证只写入宿主本地配置(均不入库),不会上传到任何地方。**
+
+## 开发
+
+```bash
+npm run check              # build + 全量单测
+npm run verify:multiagent  # 真机联调:并发推两条到手机验证编号路由(需 env 有凭证)
+```
+
+## License
+
+MIT

package/dist/agentLabel.js

@@ -0,0 +1,37 @@
+/**
+ * Agent 标签解析（纯函数，可测）：多 Agent 场景下，给每条推到钉钉的问题标注来源。
+ *
+ * 优先级：DINGTALK_AGENT_LABEL（显式配置）> cwd 的最后一段目录名 > 'agent'（兜底）。
+ * 自己实现 basename 而非用 path.basename——需同时兼容 POSIX '/' 与 Windows '\\' 分隔符，
+ * 且在跨平台单测里行为稳定（path.basename 在 POSIX 上不拆反斜杠）。
+ */
+/** cwd 取不到有效目录名时的兜底标签。 */
+const FALLBACK_LABEL = 'agent';
+/**
+ * 从路径取最后一段（兼容 / 与 \\，忽略尾部分隔符）。
+ *
+ * @param dir 目录路径（可能缺省）。
+ * @returns 最后一段目录名；无有效段时返回空串。
+ */
+function lastSegment(dir) {
+    if (dir === undefined) {
+        return '';
+    }
+    const segments = dir.split(/[/\\]+/).filter((s) => s !== '');
+    return segments.length > 0 ? segments[segments.length - 1] : '';
+}
+/**
+ * 解析 Agent 标签。
+ *
+ * @param env 环境变量对象（读 DINGTALK_AGENT_LABEL）。
+ * @param cwd 当前工作目录（MCP server 用 process.cwd()，钩子用 stdin 的 cwd）。
+ * @returns 非空 Agent 标签。
+ */
+export function resolveAgentLabel(env, cwd) {
+    const explicit = (env.DINGTALK_AGENT_LABEL ?? '').trim();
+    if (explicit !== '') {
+        return explicit;
+    }
+    const segment = lastSegment(cwd);
+    return segment !== '' ? segment : FALLBACK_LABEL;
+}

package/dist/awayState.js

@@ -0,0 +1,90 @@
+/**
+ * 「离开模式」开关状态：以 os.tmpdir() 下一个 flag 文件的存在与否表示。
+ *
+ * 语义：
+ * - 默认（无 flag，人在电脑前）：命令审批钩子立刻回落终端，不推钉钉。
+ * - 离开模式开（有 flag）：钩子才把命令审批推钉钉，用户手机上批/拒。
+ *
+ * 设计要点：
+ * - 纯逻辑（parseAwayCommand / awayFlagPath）与极薄文件 IO（isAway / setAway）分离，便于单测。
+ * - isAway / setAway 接受可选路径参数，测试注入隔离临时路径，绝不污染真实 flag。
+ * - 只用 Node 内置模块（fs/os/path）。日志留给调用方，本模块不打日志。
+ */
+import { existsSync, writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * 离开模式遥控命令：用 `/` 前缀显式命令，避免与用户的自由意见/决策回复误撞。
+ * - `/away`、`/away on` → 进离开模式；
+ * - `/back`、`/away off` → 退出。
+ */
+/** 进离开模式命令的首 token。 */
+const AWAY_HEAD = '/away';
+/** 退出离开模式命令的首 token（`/away off` 亦可）。 */
+const BACK_HEAD = '/back';
+/**
+ * 解析离开模式遥控命令（纯函数）。
+ *
+ * 规则：trim + 小写后按空白切分；**首 token 必须精确是 `/away` 或 `/back`**——
+ * `/back` → off；`/away` → 看第二 token，为 `off` 则 off，否则 on；其余一律 null。
+ * 用显式 `/` 前缀命令而非汉字关键词，彻底杜绝「我先出去买杯咖啡」这类口语被误当命令。
+ *
+ * @param text 用户发来的原始文本。
+ * @returns `/away*` → 'on'/'off'；`/back` → 'off'；不是命令 → null。
+ */
+export function parseAwayCommand(text) {
+    const normalized = text.trim().toLowerCase();
+    if (normalized === '') {
+        return null;
+    }
+    const tokens = normalized.split(/\s+/);
+    const head = tokens[0];
+    if (head === BACK_HEAD) {
+        return 'off';
+    }
+    if (head === AWAY_HEAD) {
+        return tokens[1] === 'off' ? 'off' : 'on';
+    }
+    return null;
+}
+/**
+ * 解析离开模式 flag 文件绝对路径（纯函数，便于钩子/CLI 复用与单测）。
+ *
+ * @returns os.tmpdir() 下固定文件名的绝对路径。
+ */
+export function awayFlagPath() {
+    return join(tmpdir(), 'dingtalk-ask-away.flag');
+}
+/**
+ * 当前是否处于离开模式：flag 文件存在即为开。
+ *
+ * @param flagPath flag 文件路径；缺省用 awayFlagPath()（测试注入隔离路径）。
+ * @returns 文件存在 → true；不存在或读取异常 → false。
+ */
+export function isAway(flagPath = awayFlagPath()) {
+    try {
+        return existsSync(flagPath);
+    }
+    catch {
+        // 读取异常一律视为未开离开模式（安全默认：不推钉钉）。
+        return false;
+    }
+}
+/**
+ * 设置离开模式开关。
+ *
+ * @param on true → 写 flag 文件（内容为 ISO 时间戳）；false → 删除（不存在则忽略）。
+ * @param flagPath flag 文件路径；缺省用 awayFlagPath()（测试注入隔离路径）。
+ */
+export function setAway(on, flagPath = awayFlagPath()) {
+    if (on) {
+        writeFileSync(flagPath, new Date().toISOString(), 'utf8');
+        return;
+    }
+    try {
+        unlinkSync(flagPath);
+    }
+    catch {
+        /* flag 文件不存在或已删，忽略。 */
+    }
+}

package/dist/awayToggle.js

@@ -0,0 +1,30 @@
+/**
+ * 本地 CLI：离开模式开关（不经钉钉，直接读写 flag 文件）。
+ *
+ * 构建到 dist/awayToggle.js，通过 npm scripts 调用：
+ *   npm run away:on     → 进入离开模式
+ *   npm run away:off    → 退出离开模式
+ *   npm run away:status → 打印当前状态
+ *
+ * 注意：这是 CLI 不是 MCP 信道，可用 stdout 打印结果（与 MCP server 的 stdout 禁令无关）。
+ * 只用 Node 内置模块，不引入任何依赖。
+ */
+import { setAway, isAway } from './awayState.js';
+/** 读 argv 执行开关；缺省或 status 打印当前状态。 */
+function run() {
+    const arg = process.argv[2];
+    if (arg === 'on') {
+        setAway(true);
+        process.stdout.write('已进入离开模式：命令审批会推到钉钉。\n');
+        return;
+    }
+    if (arg === 'off') {
+        setAway(false);
+        process.stdout.write('已退出离开模式：命令审批只在终端。\n');
+        return;
+    }
+    // status 或缺省：只读当前状态。
+    const away = isAway();
+    process.stdout.write(`当前离开模式：${away ? '开（推钉钉）' : '关（只在终端）'}\n`);
+}
+run();

package/dist/cliArgs.js

@@ -0,0 +1,71 @@
+/**
+ * 命令行参数解析：允许通过 CLI 参数传钉钉配置，免去在 MCP 配置里写 env 段。
+ *
+ * 支持 `--key value` 与 `--key=value`；kebab-case 与 camelCase 皆可。解析结果映射为
+ * 与环境变量同名的键，便于与 process.env 合并后交给 resolveDingtalkConfig（参数优先于 env）。
+ *
+ * 安全提示：命令行参数在进程列表（ps/tasklist）中对同机其它进程可见，比 env 略易暴露；
+ * 介意者仍可用 env 段。日志由调用方负责，本模块不打日志。
+ */
+/** CLI 标志到环境变量名的映射（含 kebab/camel 双写法）。 */
+const FLAG_TO_ENV = {
+    'client-id': 'DINGTALK_CLIENT_ID',
+    clientid: 'DINGTALK_CLIENT_ID',
+    'client-secret': 'DINGTALK_CLIENT_SECRET',
+    clientsecret: 'DINGTALK_CLIENT_SECRET',
+    'robot-code': 'DINGTALK_ROBOT_CODE',
+    robotcode: 'DINGTALK_ROBOT_CODE',
+    'user-id': 'DINGTALK_USER_ID',
+    userid: 'DINGTALK_USER_ID',
+    timeout: 'DINGTALK_ASK_TIMEOUT_MS',
+    'timeout-ms': 'DINGTALK_ASK_TIMEOUT_MS',
+    'agent-label': 'DINGTALK_AGENT_LABEL',
+    label: 'DINGTALK_AGENT_LABEL',
+};
+/**
+ * 解析 CLI 参数为「环境变量名 → 值」映射（纯函数，可测）。
+ *
+ * @param argv 参数数组（通常 process.argv.slice(2)）。
+ * @returns 仅包含被显式提供项的映射；无则空对象。
+ */
+export function parseCliArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (!token.startsWith('--')) {
+            continue;
+        }
+        const body = token.slice(2);
+        const eq = body.indexOf('=');
+        let rawKey;
+        let value;
+        if (eq >= 0) {
+            rawKey = body.slice(0, eq);
+            value = body.slice(eq + 1);
+        }
+        else {
+            rawKey = body;
+            const next = argv[i + 1];
+            // 下一个 token 不是标志才当作值；否则该标志无值、跳过。
+            if (next !== undefined && !next.startsWith('--')) {
+                value = next;
+                i += 1;
+            }
+        }
+        const envKey = FLAG_TO_ENV[rawKey.toLowerCase()];
+        if (envKey !== undefined && value !== undefined && value !== '') {
+            out[envKey] = value;
+        }
+    }
+    return out;
+}
+/**
+ * 合并 CLI 参数与环境变量（参数优先），得到供 resolveDingtalkConfig / resolveAgentLabel 用的 env 视图。
+ *
+ * @param env 基础环境变量（通常 process.env）。
+ * @param argv CLI 参数（通常 process.argv.slice(2)）。
+ * @returns 合并后的环境变量对象（不改动入参）。
+ */
+export function mergeArgsIntoEnv(env, argv) {
+    return { ...env, ...parseCliArgs(argv) };
+}

package/dist/daemon/endpoint.js

@@ -0,0 +1,170 @@
+/**
+ * 守护进程本地 HTTP 端点：只监听 127.0.0.1，供同机所有 Agent 的 MCP server 与钩子复用
+ * 守护进程持有的【唯一】钉钉 Stream 连接。
+ *
+ * 与旧 localEndpoint 的区别：
+ * - 不再负责锁文件（锁的原子选举归 daemon.ts + daemon/lock.ts）。
+ * - 新增 GET /health（带 token）返回 { ok, ready }，供 ensureDaemon 探活与就绪判定。
+ * - POST /ask body 新增可选 label（Agent 标签），透传给决策层做消息前缀。
+ *
+ * 鉴权：请求头 x-ask-token 必须等于启动时随机 token（/ask 与 /health 都校验）。
+ * 只用 Node 内置模块（http/crypto），日志走 stderr。
+ */
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+/** 请求体大小上限。 */
+const MAX_BODY_BYTES = 64 * 1024;
+/**
+ * 启动本地端点（127.0.0.1:0，OS 分配端口）。
+ *
+ * @param askDecision 决策函数。
+ * @param options 端点选项。
+ * @returns 端点句柄（含实际端口与 token）。
+ * @throws 当监听失败时 reject。
+ */
+export async function startEndpoint(askDecision, options) {
+    const token = randomBytes(24).toString('hex');
+    const isReady = options.isReady ?? (() => true);
+    const server = createServer((req, res) => {
+        handleRequest(req, res, askDecision, options, token, isReady).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`守护进程端点处理异常：${message}`);
+            if (!res.headersSent) {
+                sendJson(res, 500, { error: message });
+            }
+        });
+    });
+    const port = await listen(server);
+    console.error(`守护进程 /ask 端点已启动：http://127.0.0.1:${port}/ask`);
+    return {
+        server,
+        port,
+        token,
+        async close() {
+            await closeServer(server);
+        },
+    };
+}
+/** 监听 127.0.0.1:0 并返回实际端口。 */
+function listen(server) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (address === null || typeof address === 'string') {
+                reject(new Error('无法确定端点端口（server.address 非预期）。'));
+                return;
+            }
+            server.removeListener('error', reject);
+            resolve(address.port);
+        });
+    });
+}
+/** 路由 + 鉴权 + 分发。 */
+async function handleRequest(req, res, askDecision, options, token, isReady) {
+    // 鉴权：token 不匹配一律 403。
+    if (req.headers['x-ask-token'] !== token) {
+        sendJson(res, 403, { error: 'forbidden' });
+        return;
+    }
+    // GET /health：探活 + 就绪判定。
+    if (req.method === 'GET' && req.url === '/health') {
+        sendJson(res, 200, { ok: true, ready: isReady() });
+        return;
+    }
+    if (req.method !== 'POST' || req.url !== '/ask') {
+        sendJson(res, 404, { error: 'not found' });
+        return;
+    }
+    let body;
+    try {
+        body = await readBody(req);
+    }
+    catch (error) {
+        sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+        return;
+    }
+    let parsed;
+    try {
+        parsed = normalizeInput(JSON.parse(body));
+    }
+    catch (error) {
+        sendJson(res, 400, { error: `请求体非法：${error instanceof Error ? error.message : String(error)}` });
+        return;
+    }
+    try {
+        const result = await askDecision({
+            question: parsed.question,
+            options: parsed.options,
+            label: parsed.label,
+            timeoutMs: parsed.timeoutMs ?? options.defaultTimeoutMs,
+        });
+        sendJson(res, 200, result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`/ask 决策失败：${message}`);
+        sendJson(res, 500, { error: message });
+    }
+}
+/** 读取并限制请求体大小。 */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error('请求体过大'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+/** 校验并规整请求 JSON 为 AskDecisionInput。 */
+function normalizeInput(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new Error('必须是 JSON 对象');
+    }
+    const obj = raw;
+    if (typeof obj.question !== 'string' || obj.question.trim() === '') {
+        throw new Error('question 必填且为非空字符串');
+    }
+    let options;
+    if (obj.options !== undefined) {
+        if (!Array.isArray(obj.options) || obj.options.some((o) => typeof o !== 'string')) {
+            throw new Error('options 必须是字符串数组');
+        }
+        options = obj.options;
+    }
+    let label;
+    if (obj.label !== undefined) {
+        if (typeof obj.label !== 'string') {
+            throw new Error('label 必须是字符串');
+        }
+        label = obj.label;
+    }
+    let timeoutMs;
+    if (obj.timeoutMs !== undefined) {
+        if (typeof obj.timeoutMs !== 'number' || !Number.isInteger(obj.timeoutMs) || obj.timeoutMs <= 0) {
+            throw new Error('timeoutMs 必须是正整数');
+        }
+        timeoutMs = obj.timeoutMs;
+    }
+    return { question: obj.question, options, label, timeoutMs };
+}
+/** 写 JSON 响应。 */
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+/** 关闭 server。 */
+function closeServer(server) {
+    return new Promise((resolve) => {
+        server.close(() => resolve());
+    });
+}

package/dist/daemon/lock.js

@@ -0,0 +1,90 @@
+/**
+ * 守护进程锁文件：os.tmpdir()/dingtalk-daemon.json，记录唯一守护进程的
+ * { port, token, pid, startedAt }。它既是端点会合点（客户端据此定位 /ask），
+ * 也是单例选举的原子闸——用 O_EXCL（'wx'）独占创建，只有一个进程能创建成功。
+ *
+ * 纯解析（parseDaemonLock）与极薄 IO（read/write/remove）分离，便于单测；
+ * 只用 Node 内置 fs/os/path。日志留给调用方。
+ */
+import { writeFileSync, readFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * 守护进程锁文件绝对路径。
+ *
+ * @returns os.tmpdir() 下固定文件名。
+ */
+export function daemonLockPath() {
+    return join(tmpdir(), 'dingtalk-daemon.json');
+}
+/**
+ * 解析锁文件内容（纯函数）。port 为数字且 token 非空才有效；pid/startedAt 缺省用默认。
+ *
+ * @param raw 锁文件文本。
+ * @returns 合法则返回 DaemonLock，否则 undefined。
+ */
+export function parseDaemonLock(raw) {
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof obj.port !== 'number' || typeof obj.token !== 'string' || obj.token === '') {
+        return undefined;
+    }
+    return {
+        port: obj.port,
+        token: obj.token,
+        pid: typeof obj.pid === 'number' ? obj.pid : 0,
+        startedAt: typeof obj.startedAt === 'string' ? obj.startedAt : '',
+    };
+}
+/**
+ * 读并解析锁文件；不存在/损坏返回 undefined。
+ *
+ * @param path 锁文件路径；缺省用 daemonLockPath()。
+ * @returns 合法锁内容或 undefined。
+ */
+export function readDaemonLock(path = daemonLockPath()) {
+    try {
+        return parseDaemonLock(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 独占创建锁文件（O_EXCL）。已存在则不覆盖、返回 false（选举落败）。
+ *
+ * @param lock 要写入的锁内容。
+ * @param path 锁文件路径；缺省用 daemonLockPath()。
+ * @returns 创建成功 true；已存在 false。
+ * @throws 其它 IO 错误（非 EEXIST）向上抛。
+ */
+export function writeDaemonLockExclusive(lock, path = daemonLockPath()) {
+    try {
+        writeFileSync(path, JSON.stringify(lock), { encoding: 'utf8', flag: 'wx' });
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * 删除锁文件（不存在则忽略）。
+ *
+ * @param path 锁文件路径；缺省用 daemonLockPath()。
+ */
+export function removeDaemonLock(path = daemonLockPath()) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        /* 不存在或已删，忽略。 */
+    }
+}