dingtalk-ask-mcp-server 0.1.0

package/dist/index.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * dingtalk-ask-mcp-server：基于 stdio transport 的 human-in-the-loop MCP server（瘦客户端）。
+ *
+ * 暴露 ask_human / set_away_mode 两个工具。多 Agent 架构下，本 server 不再自持钉钉连接，
+ * 而是把决策经本地 HTTP 转发给【唯一】的 dingtalk-daemon（共享持连守护进程），由它推钉钉、
+ * 收回复、按 Agent 标签与编号路由——规避同应用多开 Stream 连接被负载均衡的问题。
+ *
+ * 启动时 ensureDaemon 确保守护进程在跑（不在则 detached 拉起）。stdio 是 MCP 协议信道，
+ * 严禁向 stdout 打印日志，一律走 stderr。
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { resultText } from "./decision/resultText.js";
+import { resolveDingtalkConfig } from "./dingtalk/config.js";
+import { isAway, setAway } from "./awayState.js";
+import { resolveAgentLabel } from "./agentLabel.js";
+import { mergeArgsIntoEnv } from "./cliArgs.js";
+import { ensureDaemon, postAskToDaemon } from "./daemonClient.js";
+import { daemonLockPath } from "./daemon/lock.js";
+/** 合并 CLI 参数与环境变量（参数优先）：允许用 --client-id 等命令行参数传钉钉配置。 */
+const env = mergeArgsIntoEnv(process.env, process.argv.slice(2));
+/**
+ * 解析钉钉配置；缺凭证时打印缺失项到 stderr 并 exit(1)（AC5：不产生半可用状态）。
+ *
+ * @returns 已校验的钉钉配置。
+ */
+function loadConfigOrExit() {
+    try {
+        return resolveDingtalkConfig(env);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`dingtalk-ask-mcp-server 配置错误：${message}`);
+        process.exit(1);
+    }
+}
+const config = loadConfigOrExit();
+/** 本 Agent 标签：优先 --agent-label / DINGTALK_AGENT_LABEL，其次工作目录名（推钉钉时标注来源）。 */
+const agentLabel = resolveAgentLabel(env, process.cwd());
+/** 缓存的守护进程锁；POST 失败时清空重新 ensure。 */
+let cachedLock;
+/**
+ * 取一个就绪守护进程的锁（缓存优先，缺省则 ensure 拉起/等待）。
+ *
+ * @returns 守护进程锁。
+ */
+async function getLock() {
+    if (cachedLock !== undefined) {
+        return cachedLock;
+    }
+    cachedLock = await ensureDaemon(config, daemonLockPath());
+    return cachedLock;
+}
+/**
+ * 共享决策入口：把一次决策转发给守护进程，等待结果。POST 失败时重新 ensure 一次再试
+ * （守护进程可能刚重启换了端口）。
+ *
+ * @param input 决策入参（question、可选 options、可选 timeoutMs）。
+ * @returns 决策结果（answered/timeout）。
+ */
+async function askDecision(input) {
+    const body = {
+        question: input.question,
+        options: input.options,
+        label: agentLabel,
+        timeoutMs: input.timeoutMs ?? config.timeoutMs,
+    };
+    try {
+        return await postAskToDaemon(await getLock(), body);
+    }
+    catch (error) {
+        console.error(`转发守护进程失败，重新 ensure 后重试：${error instanceof Error ? error.message : String(error)}`);
+        cachedLock = undefined;
+        return postAskToDaemon(await getLock(), body);
+    }
+}
+const server = new McpServer({
+    name: "dingtalk-ask-mcp-server",
+    version: "0.1.0",
+}, {
+    // server 级引导：随 server 分发、无需用户写任何配置文件。
+    // 客户端（如 Claude Code）会把它注入模型上下文，作为 ask_human 何时该调的总纲。
+    instructions: "本 server 提供 ask_human 工具，用于把「需要用户拍板的决策」或「执行有副作用操作前的确认」" +
+        "推送到用户钉钉并阻塞等待回复。遇到这两类情况时优先调用 ask_human，而不是把问题写在回复里停下干等" +
+        "（用户可能已离开电脑）。克制使用：只在重大、有副作用、或你无法替用户判断时调用，" +
+        "日常只读小步骤不要打扰。",
+});
+server.registerTool("ask_human", {
+    description: "把需要人来拍板的问题推送到用户钉钉，阻塞等待用户在手机/钉钉上的回复，" +
+        "并把用户的选择或文字作为结果返回。用户可能已离开电脑，这是你在无人值守时获取人工决策的通道。\n" +
+        "在以下两类情况【主动调用本工具】，而不是把问题写在回复里停下干等：\n" +
+        "1) 决策类——存在多个可行方案且取舍会明显影响结果（架构/技术选型/实现路径/命名与模块边界/数据结构），" +
+        "或需求有歧义、按不同理解会做出不同东西：用 options 给出 2~4 个候选方向。\n" +
+        "2) 确认类——在执行【有副作用或难以回滚】的操作之前先征得同意（运行进程或改动系统状态的命令、" +
+        "删除或覆盖文件、git push、发布/部署、改数据库 schema、数据迁移、安装或升级依赖、跨多文件批量改动）：" +
+        "用 options 传 [\"是，执行\",\"否，先别\"] 之类的 yes/no。\n" +
+        "克制使用：只在重大、有副作用、或你无法替用户判断时调用；日常小步骤、只读操作、无争议的事不要调用，避免频繁打扰。",
+    inputSchema: {
+        question: z.string().describe("要请用户拍板的问题正文；决策类说清各方向影响，确认类说清「要做什么+风险」。"),
+        options: z
+            .array(z.string())
+            .optional()
+            .describe("可选的候选方向：决策类给 2~4 个方向；确认类给 [\"是，执行\",\"否，先别\"]；无则纯文本问答。"),
+    },
+}, async ({ question, options }) => {
+    // 离开模式是统一总闸：关（用户在电脑前）时不推钉钉，直接让模型在终端向用户提问。
+    // 开（用户已离开）时才把问题推钉钉、阻塞等回复。
+    if (!isAway()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "【离开模式关闭·用户在电脑前】无需推钉钉。请直接在当前终端对话里向用户提出这个问题并等待其回复，" +
+                        "不要依赖本工具的返回值作为答复。（用户离开电脑时会发 /away 开启离开模式，届时再调用 ask_human 才会推送到钉钉。）",
+                },
+            ],
+        };
+    }
+    // 转发守护进程；失败收敛成可读文本让模型自决，不向宿主抛异常。
+    try {
+        const outcome = await askDecision({ question, options });
+        return {
+            content: [{ type: "text", text: resultText(outcome, config.timeoutMs) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`ask_human 处理失败：${message}`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `无法把决策推送到钉钉：${message}。请你自行决定：稍后重试（再次调用 ask_human）、选择一个安全默认、或停止并说明原因。`,
+                },
+            ],
+        };
+    }
+});
+server.registerTool("set_away_mode", {
+    description: "开启或关闭「离开模式」。当用户在对话中表示要离开电脑（如「我出去一下」「去开会」「下班了」「先走了」）时，" +
+        "调用 set_away_mode(away=true)；表示回到电脑前（如「我回来了」「继续吧」）时调用 set_away_mode(away=false)。\n" +
+        "离开模式开启后，需要用户拍板的决策（ask_human）与命令审批会推送到用户钉钉、由用户在手机上处理；" +
+        "关闭后（默认）这些只在终端进行、不打扰手机。用户也可自行在钉钉发 /away（离开）、/back（回来）或用本地命令切换。",
+    inputSchema: {
+        away: z
+            .boolean()
+            .describe("true=进入离开模式（决策/命令审批推钉钉）；false=退出（只在终端）。"),
+    },
+}, async ({ away }) => {
+    setAway(away);
+    return {
+        content: [
+            {
+                type: "text",
+                text: away
+                    ? "已进入离开模式：后续需要你拍板的决策与命令审批会推送到你的钉钉。"
+                    : "已退出离开模式：决策与命令审批只在终端进行，不推钉钉。",
+            },
+        ],
+    };
+});
+/**
+ * 应用主入口：先确保共享守护进程在跑（不在则拉起），再通过 stdio 连接 MCP server。
+ *
+ * 取舍：ensureDaemon 失败时不 exit——保留 server 存活可让 ask_human 仍返回可读错误文本让模型自决
+ * （复刻旧版"钉钉连接失败不退出"的容错）。缺凭证是启动即 exit(1)，与此区分。
+ *
+ * @returns 服务启动完成后返回的 Promise。
+ * @throws 当 stdio 传输连接失败时抛出错误（由 main().catch 兜底 exit 1）。
+ */
+async function main() {
+    try {
+        cachedLock = await ensureDaemon(config, daemonLockPath());
+        console.error(`钉钉守护进程就绪（port=${cachedLock.port}）。`);
+    }
+    catch (error) {
+        console.error(`确保钉钉守护进程失败：${error instanceof Error ? error.message : String(error)}。server 仍启动，ask_human 将在调用时重试。`);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`dingtalk-ask-mcp-server 已启动（stdio，Agent 标签=${agentLabel}）。`);
+    console.error(`当前离开模式：${isAway() ? '开（命令审批/决策推钉钉）' : '关（只在终端）'}。可在钉钉发 /away、/back 遥控。`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`dingtalk-ask-mcp-server 启动失败：${message}`);
+    process.exit(1);
+});

package/dist/installCli.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * 统一安装命令 `dingtalk-ask install`（bin 入口）：一次装 MCP + 命令审批钩子，支持 CC 与 Codex。
+ *
+ * 用法：
+ *   dingtalk-ask install --client-id … --client-secret … --robot-code … --user-id … \
+ *                        [--timeout <ms>] [--host cc|codex|both]
+ *
+ * 默认宿主：CC 必装；Codex 仅当检测到 ~/.codex 时自动一并装（或 --host 显式指定）。
+ * 写入均为宿主本地配置（.mcp.json / .claude/settings.json / ~/.codex/config.toml，皆不入库），
+ * 合并保留既有内容、幂等。纯逻辑在 installConfig.ts / installHookCore.ts。
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveDingtalkConfig } from './dingtalk/config.js';
+import { mergeArgsIntoEnv } from './cliArgs.js';
+import { mergeHook, permissionHookPath, resolveSettingsPath } from './installHookCore.js';
+import { daemonLockPath, readDaemonLock, removeDaemonLock } from './daemon/lock.js';
+import { probeHealth } from './daemonClient.js';
+import { isAway, setAway } from './awayState.js';
+import { buildMcpEntry, mergeMcpServers, ensureMcpToolTimeout, codexHasDingtalk, buildCodexBlock, MCP_SERVER_NAME, } from './installConfig.js';
+/** 解析目标宿主。默认 CC；Codex 见 resolveCodexTarget。 */
+function parseHost(argv) {
+    const i = argv.indexOf('--host');
+    const v = i >= 0 ? argv[i + 1] : undefined;
+    if (v === 'cc' || v === 'codex' || v === 'both') {
+        return v;
+    }
+    return undefined;
+}
+/** 读 JSON 文件；不存在/空 → {}；损坏 → 抛错（不覆盖）。 */
+function readJson(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (raw.trim() === '') {
+        return {};
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${path} 不是合法 JSON（${error instanceof Error ? error.message : String(error)}），已中止，未改动。`);
+    }
+}
+function writeJson(path, obj) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
+}
+/** 装 Claude Code：.mcp.json（MCP server）+ .claude/settings.json（钩子 + MCP_TOOL_TIMEOUT）。 */
+function installClaudeCode(config, argv, nodePath, indexPath) {
+    const cwd = process.cwd();
+    // 1. .mcp.json
+    const mcpPath = join(cwd, '.mcp.json');
+    const entry = buildMcpEntry(config, nodePath, indexPath);
+    const { settings: mcpMerged, existed } = mergeMcpServers(readJson(mcpPath), MCP_SERVER_NAME, entry);
+    writeJson(mcpPath, mcpMerged);
+    console.log(`✅ [CC] ${existed ? '更新' : '写入'} MCP server 到 ${mcpPath}`);
+    // 2. .claude/settings.json：钩子 + MCP_TOOL_TIMEOUT（略大于 ask 超时）
+    const settingsPath = resolveSettingsPath(argv.includes('--global') ? ['--global'] : [], cwd, homedir());
+    const command = `node "${permissionHookPath()}"`;
+    const hookMerged = mergeHook(readJson(settingsPath), command);
+    const tmMerged = ensureMcpToolTimeout(hookMerged.settings, config.timeoutMs + 60_000);
+    writeJson(settingsPath, tmMerged.settings);
+    console.log(`✅ [CC] ${hookMerged.changed ? '安装' : '已存在'}命令审批钩子；` +
+        `${tmMerged.changed ? '设置' : '保留'} MCP_TOOL_TIMEOUT → ${settingsPath}`);
+}
+/** 装 Codex：追加 ~/.codex/config.toml 的 [mcp_servers.dingtalk-ask]（幂等，先备份）。 */
+function installCodex(config, nodePath, indexPath) {
+    const cfgPath = join(homedir(), '.codex', 'config.toml');
+    let content = '';
+    try {
+        content = readFileSync(cfgPath, 'utf8');
+    }
+    catch {
+        content = '';
+    }
+    if (codexHasDingtalk(content)) {
+        console.log(`✅ [Codex] ${cfgPath} 已含 dingtalk-ask，跳过。`);
+        return;
+    }
+    mkdirSync(dirname(cfgPath), { recursive: true });
+    if (content !== '') {
+        copyFileSync(cfgPath, `${cfgPath}.bak`);
+    }
+    writeFileSync(cfgPath, content + buildCodexBlock(config, nodePath, indexPath), 'utf8');
+    console.log(`✅ [Codex] 追加 [mcp_servers.dingtalk-ask] 到 ${cfgPath}${content !== '' ? '（已备份 .bak）' : ''}`);
+}
+function usage() {
+    console.log('dingtalk-ask —— 钉钉 human-in-the-loop MCP 工具');
+    console.log('');
+    console.log('用法：');
+    console.log('  dingtalk-ask install --client-id … --client-secret … --robot-code … --user-id … \\');
+    console.log('                       [--timeout <ms>] [--host cc|codex|both]   # 一键装 MCP+钩子');
+    console.log('  dingtalk-ask daemon <status|stop>                               # 查看/停止共享守护进程');
+    console.log('  dingtalk-ask away <on|off|status>                               # 本地切换离开模式');
+    process.exit(1);
+}
+/** install 子命令：装 MCP + 钩子。 */
+function runInstall(rest) {
+    let config;
+    try {
+        config = resolveDingtalkConfig(mergeArgsIntoEnv(process.env, rest));
+    }
+    catch (error) {
+        console.error(`配置错误：${error instanceof Error ? error.message : String(error)}`);
+        console.error('请用 --client-id / --client-secret / --robot-code / --user-id 提供凭证。');
+        process.exit(1);
+    }
+    const nodePath = process.execPath;
+    const indexPath = fileURLToPath(new URL('./index.js', import.meta.url));
+    // 目标宿主：显式 --host 优先；否则 CC 必装，Codex 存在则一并装。
+    const host = parseHost(rest);
+    const doCc = host === undefined || host === 'cc' || host === 'both';
+    const doCodex = host === 'codex' || host === 'both' || (host === undefined && existsSync(join(homedir(), '.codex')));
+    if (doCc) {
+        installClaudeCode(config, rest, nodePath, indexPath);
+    }
+    if (doCodex) {
+        installCodex(config, nodePath, indexPath);
+    }
+    console.log('\n完成。后续：');
+    if (doCc) {
+        console.log('  · 重启 Claude Code 让新 MCP server 与 MCP_TOOL_TIMEOUT 生效。');
+    }
+    if (doCodex) {
+        console.log('  · 重开 Codex 会话让 config.toml 生效（tool_timeout_sec 已设 1500）。');
+    }
+    console.log('  · 前提：钉钉企业内部应用(H5)+机器人+Stream 已配好。');
+    console.log('  · 离开电脑时在钉钉发 /away 开启推送，/back 关闭。');
+}
+/** daemon 子命令：查看/停止共享守护进程。 */
+async function runDaemon(rest) {
+    const sub = rest[0];
+    const lock = readDaemonLock(daemonLockPath());
+    if (sub === 'status') {
+        if (lock === undefined) {
+            console.log('钉钉守护进程：未运行（无锁文件）。');
+            return;
+        }
+        const probe = await probeHealth(lock);
+        console.log(`钉钉守护进程：${probe.ok ? '在跑' : '锁存在但无应答（可能已死）'}，port=${lock.port}，pid=${lock.pid}，就绪=${probe.ready}。`);
+        return;
+    }
+    if (sub === 'stop') {
+        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('已清理锁文件。');
+        return;
+    }
+    usage();
+}
+/** away 子命令：本地切换离开模式（与钉钉 /away、set_away_mode 工具同一开关）。 */
+function runAway(rest) {
+    const sub = rest[0];
+    if (sub === 'on') {
+        setAway(true);
+        console.log('已开启离开模式：决策与命令审批推钉钉。');
+        return;
+    }
+    if (sub === 'off') {
+        setAway(false);
+        console.log('已关闭离开模式：只在终端。');
+        return;
+    }
+    if (sub === 'status') {
+        console.log(`当前离开模式：${isAway() ? '开' : '关'}。`);
+        return;
+    }
+    usage();
+}
+function main() {
+    const args = process.argv.slice(2);
+    const cmd = args[0];
+    const rest = args.slice(1);
+    if (cmd === 'install') {
+        runInstall(rest);
+    }
+    else if (cmd === 'daemon') {
+        void runDaemon(rest);
+    }
+    else if (cmd === 'away') {
+        runAway(rest);
+    }
+    else {
+        usage();
+    }
+}
+main();

package/dist/installConfig.js

@@ -0,0 +1,80 @@
+/** MCP server 名（各宿主统一）。 */
+export const MCP_SERVER_NAME = 'dingtalk-ask';
+/** 由配置构造凭证 env（写入宿主配置的 env 段）。 */
+function credEnv(config) {
+    return {
+        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),
+    };
+}
+/**
+ * 构造 .mcp.json 的 dingtalk-ask 条目：用绝对 node 路径 + 绝对入口，免依赖宿主 PATH。
+ *
+ * @param config 已解析钉钉配置。
+ * @param nodePath 绝对 node 可执行路径。
+ * @param indexPath 绝对 dist/index.js 路径。
+ * @returns MCP server 条目。
+ */
+export function buildMcpEntry(config, nodePath, indexPath) {
+    return { command: nodePath, args: [indexPath], env: credEnv(config) };
+}
+/**
+ * 把 MCP server 条目合并进现有配置对象（保留其它 server 与顶层字段）。
+ *
+ * @param existing 现有 .mcp.json 对象（可空）。
+ * @param name server 名。
+ * @param entry 要写入的条目。
+ * @returns { settings: 合并后对象, existed: 该名是否已存在（被覆盖更新） }。
+ */
+export function mergeMcpServers(existing, name, entry) {
+    const servers = { ...(existing.mcpServers ?? {}) };
+    const existed = name in servers;
+    servers[name] = entry;
+    return { settings: { ...existing, mcpServers: servers }, existed };
+}
+/**
+ * 在 settings 对象上确保 env.MCP_TOOL_TIMEOUT（不覆盖已有值）。
+ *
+ * @param settings 现有 settings 对象。
+ * @param ms 期望的超时毫秒（通常略大于 ask 超时）。
+ * @returns { settings, changed }。
+ */
+export function ensureMcpToolTimeout(settings, ms) {
+    const env = { ...(settings.env ?? {}) };
+    if (typeof env.MCP_TOOL_TIMEOUT === 'string' && env.MCP_TOOL_TIMEOUT !== '') {
+        return { settings, changed: false };
+    }
+    env.MCP_TOOL_TIMEOUT = String(ms);
+    return { settings: { ...settings, env }, changed: true };
+}
+/** 判断 Codex config.toml 是否已含 dingtalk-ask（幂等用）。 */
+export function codexHasDingtalk(content) {
+    return content.includes(`[mcp_servers.${MCP_SERVER_NAME}]`);
+}
+/**
+ * 构造 Codex config.toml 追加块（TOML 基本字符串转义，无需 TOML 库）。
+ *
+ * @param config 已解析钉钉配置。
+ * @param nodePath 绝对 node 路径。
+ * @param indexPath 绝对 dist/index.js 路径。
+ * @returns 可直接追加到 config.toml 末尾的文本块。
+ */
+export function buildCodexBlock(config, nodePath, indexPath) {
+    const q = (v) => JSON.stringify(v);
+    const env = credEnv(config);
+    return [
+        '',
+        `[mcp_servers.${MCP_SERVER_NAME}]`,
+        `command = ${q(nodePath)}`,
+        `args = [${q(indexPath)}]`,
+        'startup_timeout_sec = 30',
+        'tool_timeout_sec = 1500',
+        '',
+        `[mcp_servers.${MCP_SERVER_NAME}.env]`,
+        ...Object.entries(env).map(([k, v]) => `${k} = ${q(v)}`),
+        '',
+    ].join('\n');
+}

package/dist/installHook.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * 一键安装 Claude Code 的 PermissionRequest 钩子到 settings.json（bin 入口）。
+ *
+ * 用法：
+ *   dingtalk-ask-install-hook            # 装到 <cwd>/.claude/settings.json（项目级）
+ *   dingtalk-ask-install-hook --global   # 装到 ~/.claude/settings.json（用户级）
+ *   dingtalk-ask-install-hook <path>     # 装到指定 settings.json
+ *
+ * 纯逻辑在 installHookCore.ts；本文件仅无条件调用主流程（全局命令经 shim 调用时也能跑）。
+ */
+import { homedir } from 'node:os';
+import { runInstallHook } from './installHookCore.js';
+runInstallHook(process.argv.slice(2), process.cwd(), homedir());

package/dist/installHookCore.js

@@ -0,0 +1,97 @@
+/**
+ * install-hook 的纯逻辑与主流程（无 shebang、可被测试安全 import，不含"直接运行"副作用）。
+ *
+ * bin 入口 installHook.ts 只 import runInstallHook 并无条件调用——避免全局命令经 npm shim
+ * 调用时 process.argv[1] 与 import.meta.url 对不上导致 main 不执行。
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** 钩子内部超时（毫秒），与 settings 钩子 timeout 对齐。 */
+const HOOK_TIMEOUT_MS = 60_000;
+/** 解析目标 settings.json 路径（纯函数，便于单测）。 */
+export function resolveSettingsPath(argv, cwd, home) {
+    const arg = argv[0];
+    if (arg === '--global') {
+        return join(home, '.claude', 'settings.json');
+    }
+    if (arg !== undefined && arg !== '') {
+        return arg;
+    }
+    return join(cwd, '.claude', 'settings.json');
+}
+/** dist/permissionHook.js 的绝对路径（与本文件同级）。 */
+export function permissionHookPath() {
+    return fileURLToPath(new URL('./permissionHook.js', import.meta.url));
+}
+/**
+ * 把 PermissionRequest 钩子合并进 settings 对象（纯函数，便于单测）。
+ *
+ * @param settings 现有 settings 对象（可为空对象）。
+ * @param command 钩子命令串。
+ * @returns { settings: 合并后对象, changed: 是否有改动 }。
+ */
+export function mergeHook(settings, command) {
+    const hooks = (settings.hooks ?? {});
+    const list = Array.isArray(hooks.PermissionRequest) ? [...hooks.PermissionRequest] : [];
+    // 幂等：任一条目的命令已含 permissionHook.js 则视为已安装。
+    const already = list.some((entry) => Array.isArray(entry.hooks) && entry.hooks.some((h) => typeof h.command === 'string' && h.command.includes('permissionHook.js')));
+    if (already) {
+        return { settings, changed: false };
+    }
+    list.push({ matcher: 'Bash', hooks: [{ type: 'command', command, timeout: HOOK_TIMEOUT_MS }] });
+    return {
+        settings: { ...settings, hooks: { ...hooks, PermissionRequest: list } },
+        changed: true,
+    };
+}
+/** 读取 settings.json；不存在返回空对象；解析失败抛错（不覆盖用户文件）。 */
+function readSettings(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (raw.trim() === '') {
+        return {};
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${path} 不是合法 JSON（${error instanceof Error ? error.message : String(error)}），已中止，未改动。`);
+    }
+}
+/**
+ * install-hook 主流程：解析路径 → 合并钩子 → 写回 → 打印后续提示。
+ *
+ * @param argv CLI 参数（process.argv.slice(2)）。
+ * @param cwd 当前工作目录。
+ * @param home 用户主目录。
+ */
+export function runInstallHook(argv, cwd, home) {
+    const settingsPath = resolveSettingsPath(argv, cwd, home);
+    const command = `node "${permissionHookPath()}"`;
+    let settings;
+    try {
+        settings = readSettings(settingsPath);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    const { settings: merged, changed } = mergeHook(settings, command);
+    if (!changed) {
+        console.log(`PermissionRequest 钩子已存在于 ${settingsPath}，无需重复安装。`);
+        return;
+    }
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+    console.log(`✅ 已安装 PermissionRequest 钩子到 ${settingsPath}`);
+    console.log(`   command: ${command}`);
+    console.log('\n还需两步（若未做）：');
+    console.log('  1. 配 .mcp.json 的 dingtalk-ask server（含 DINGTALK_* env，或用 CLI 参数传配置）。');
+    console.log('  2. Claude Code 设 MCP_TOOL_TIMEOUT（如 settings.local.json 的 env）给阻塞式工具留时间。');
+}

package/dist/permissionDecision.js

@@ -0,0 +1,82 @@
+/**
+ * PermissionRequest 钩子的纯判定逻辑（无 I/O，便于单测）。
+ *
+ * 拆出两件事：
+ * 1. buildPermissionQuestion：把 命令 + 目录 组装成推给用户的问题正文。
+ * 2. decideFromReply：把 /ask 端点返回的 { kind, value } 映射到钩子该做的三态决定。
+ *
+ * 安全铁律（design-cc-permission-hook.md）：只有明确的"允许"才 allow；
+ * 其余一切（拒绝、超时、歧义、空、错误）都不能误放行——要么 deny、要么回落，绝不 allow。
+ */
+/** 明确表示"允许"的回复词（trim + 小写后精确匹配）。 */
+const ALLOW_WORDS = new Set(['允许', '同意', '是', '可以', 'y', 'yes', '1', 'allow', 'ok']);
+/** 明确表示"拒绝"的回复词（trim + 小写后精确匹配）。 */
+const DENY_WORDS = new Set(['拒绝', '否', '不', '不行', 'n', 'no', '2', 'deny']);
+/**
+ * 组装推送给用户的审批问题正文。
+ *
+ * @param command 待批准执行的命令原文。
+ * @param cwd 命令的工作目录（可能缺省）。
+ * @returns 形如 "是否允许执行命令？\n$ <cmd>\n(目录: <cwd>)" 的问题串。
+ */
+export function buildPermissionQuestion(command, cwd) {
+    const dirLine = cwd !== undefined && cwd !== '' ? `\n(目录: ${cwd})` : '';
+    return `是否允许执行命令？\n$ ${command}${dirLine}`;
+}
+/**
+ * 把 /ask 响应映射为钩子决定。
+ *
+ * 判定规则：
+ * - kind==="timeout" → fallthrough（超时绝不放行，回落让用户在终端处理）。
+ * - kind==="answered"：
+ *   · value 命中允许词 → allow。
+ *   · value 命中拒绝词 → deny（message 用回复原文，空则用默认理由）。
+ *   · 其它（自由文本/歧义/空）→ fallthrough（安全兜底，绝不误放行）。
+ *
+ * @param res /ask 端点返回的结果。
+ * @returns 钩子应执行的三态决定。
+ */
+export function decideFromReply(res) {
+    if (res.kind !== 'answered') {
+        return { behavior: 'fallthrough' };
+    }
+    const raw = (res.value ?? '').trim();
+    if (raw === '') {
+        return { behavior: 'fallthrough' };
+    }
+    const normalized = raw.toLowerCase();
+    if (ALLOW_WORDS.has(normalized)) {
+        return { behavior: 'allow' };
+    }
+    if (DENY_WORDS.has(normalized)) {
+        // 拒绝理由优先用用户回复原文（可能含解释），否则给默认。
+        return { behavior: 'deny', message: raw === '' ? '用户在钉钉拒绝执行该命令。' : `用户在钉钉拒绝：${raw}` };
+    }
+    // 歧义/自由文本：不敢自作主张放行，也不硬拦，回落终端由用户定夺。
+    return { behavior: 'fallthrough' };
+}
+/**
+ * 把三态决定序列化为 Claude Code PermissionRequest 钩子的 stdout 输出。
+ *
+ * @param decision 三态决定。
+ * @returns 应写入 stdout 的字符串；fallthrough 返回空串（→ 回落）。
+ */
+export function serializeDecision(decision) {
+    if (decision.behavior === 'fallthrough') {
+        return '';
+    }
+    if (decision.behavior === 'allow') {
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: 'PermissionRequest',
+                decision: { behavior: 'allow' },
+            },
+        });
+    }
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'PermissionRequest',
+            decision: { behavior: 'deny', message: decision.message },
+        },
+    });
+}