dingtalk-ask-mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -138,12 +138,17 @@ Codex 若 `approval_policy="never"` 本就不弹命令审批,故只提供 `ask_h
 
 ```bash
 dingtalk-ask install …            # 一键接入(见上)
+dingtalk-ask info                 # 查看配置与进程状态(守护进程/离开模式/各宿主是否配好)
 dingtalk-ask daemon status|stop   # 查看/停止共享守护进程
 dingtalk-ask away on|off|status   # 本地切换离开模式
-dingtalk-ask-mcp-server --client-id … …   # 服务本体(一般由宿主拉起,极少手动跑)
+dingtalk-ask clean                # 清空运行时状态(守护进程/锁/flag/就绪标记/日志),不动配置文件
+dingtalk-ask -v | -h              # 版本 / 帮助
+dingtalk-ask-mcp-server --client-id … …   # 服务本体(一般由宿主拉起,极少手动跑;支持 -v/-h)
 dingtalk-ask-install-hook [--global|<path>] # 只装 CC 命令审批钩子
 ```
 
+首次连上钉钉时,会给你单聊发一条**「已连接就绪(附 robotCode)」**确认,便于核对连的是哪个机器人;每个机器人只发一次。
+
 守护进程自动拉起、闲置自动退出;`DINGTALK_DAEMON_IDLE_MS` 可调(`0` 禁用)。诊断:守护进程日志在系统临时目录 `dingtalk-daemon.log`;设 `DINGTALK_DEBUG=1` 打印钉钉每帧。
 
 ---

package/dist/daemon.js

@@ -15,6 +15,8 @@ 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 { buildTextMessage } from './dingtalk/cardPayload.js';
+import { hasGreeted, markGreeted, buildGreeting } from './greeting.js';
 import { daemonLockPath, writeDaemonLockExclusive, readDaemonLock, removeDaemonLock, } from './daemon/lock.js';
 import { probeHealth } from './daemonClient.js';
 /** 选举重试次数（应对陈旧锁的回收竞争）。 */
@@ -136,6 +138,13 @@ async function main() {
     registry = new DecisionRegistry(client);
     ready = true;
     registerCleanup(endpoint, client, lockPath);
+    // 首次连接成功时给钉钉发一条就绪提示（每个 robotCode 只发一次），便于确认连的是哪个机器人。
+    if (client.isConnected() && !hasGreeted(config.robotCode)) {
+        client
+            .sendOto(buildTextMessage(buildGreeting(config.robotCode)))
+            .then(() => markGreeted(config.robotCode))
+            .catch((error) => console.error(`就绪提示发送失败：${error instanceof Error ? error.message : String(error)}`));
+    }
     // 空闲自关：无待答且超过阈值无 /ask 活动则退出删锁（下次 MCP server 再拉起）。
     const idleMs = resolveIdleMs(process.env.DINGTALK_DAEMON_IDLE_MS);
     if (idleMs > 0) {

package/dist/dingtalk/client.js

@@ -209,6 +209,14 @@ export class DingtalkClient {
             throw new Error(`获取钉钉 accessToken 失败：${describeAxiosError(error)}`);
         }
     }
+    /**
+     * 当前是否已成功建立 Stream 长连（用于首次连接就绪提示等）。
+     *
+     * @returns 已连上 → true；未建连或握手未成功 → false。
+     */
+    isConnected() {
+        return this.dwClient?.connected === true;
+    }
     /**
      * 断开 Stream 长连（若已建连）。进程退出前调用，释放 socket。
      *

package/dist/greeting.js

@@ -0,0 +1,60 @@
+/**
+ * 首次连接就绪提示：守护进程成功连上钉钉后，给用户单聊发一条"已连接（哪个机器人）"确认，
+ * 便于确认凭证对不对、连的是哪个 bot、接收链路通不通。
+ *
+ * 每个 robotCode 只发一次（tmpdir 标记文件），避免每次开 CC / 重启守护进程都刷屏。
+ * 纯逻辑（路径/文案）与极薄 IO 分离，便于单测。
+ */
+import { existsSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * 就绪提示标记文件路径（按 robotCode 区分；非法字符替换为下划线）。
+ *
+ * @param robotCode 机器人 robotCode。
+ * @returns tmpdir 下的标记文件绝对路径。
+ */
+export function greetingMarkerPath(robotCode) {
+    const safe = robotCode.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(tmpdir(), `dingtalk-greeted-${safe}.flag`);
+}
+/**
+ * 是否已对该 robotCode 发过就绪提示。
+ *
+ * @param robotCode 机器人 robotCode。
+ * @param path 标记路径；缺省用 greetingMarkerPath（测试注入隔离路径）。
+ * @returns 已发过 → true。
+ */
+export function hasGreeted(robotCode, path = greetingMarkerPath(robotCode)) {
+    try {
+        return existsSync(path);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 记录已发过就绪提示（写标记文件，内容为 ISO 时间戳）。
+ *
+ * @param robotCode 机器人 robotCode。
+ * @param path 标记路径；缺省用 greetingMarkerPath（测试注入隔离路径）。
+ */
+export function markGreeted(robotCode, path = greetingMarkerPath(robotCode)) {
+    try {
+        writeFileSync(path, new Date().toISOString(), 'utf8');
+    }
+    catch {
+        /* 写标记失败不影响主流程（最多下次重复发一次）。 */
+    }
+}
+/**
+ * 构造就绪提示文案（纯函数，可测）。
+ *
+ * @param robotCode 机器人 robotCode（帮用户确认连的是哪个 bot）。
+ * @returns 提示正文。
+ */
+export function buildGreeting(robotCode) {
+    return (`✅ dingtalk-ask 已连接就绪，可以在这里接收决策与命令审批。\n` +
+        `机器人 robotCode：${robotCode}\n` +
+        `离开电脑时发 /away 开启推送，回来发 /back 关闭。`);
+}

package/dist/index.js

@@ -17,10 +17,29 @@ import { resolveDingtalkConfig } from "./dingtalk/config.js";
 import { isAway, setAway } from "./awayState.js";
 import { resolveAgentLabel } from "./agentLabel.js";
 import { mergeArgsIntoEnv } from "./cliArgs.js";
+import { packageVersion } from "./version.js";
 import { ensureDaemon, postAskToDaemon } from "./daemonClient.js";
 import { daemonLockPath } from "./daemon/lock.js";
+// -v/--version、-h/--help：在读配置前拦截，免凭证也能用。
+const rawArgs = process.argv.slice(2);
+if (rawArgs.includes("-v") || rawArgs.includes("--version")) {
+    console.log(packageVersion());
+    process.exit(0);
+}
+if (rawArgs.includes("-h") || rawArgs.includes("--help")) {
+    console.log(`dingtalk-ask-mcp-server v${packageVersion()} —— 钉钉 human-in-the-loop MCP server`);
+    console.log("");
+    console.log("一般由宿主(Claude Code / Codex)按 MCP 配置拉起，也可手动启动：");
+    console.log("  dingtalk-ask-mcp-server --client-id <AppKey> --client-secret <AppSecret> \\");
+    console.log("                          --robot-code <robotCode> --user-id <userId> \\");
+    console.log("                          [--timeout <ms>] [--agent-label <名字>]");
+    console.log("");
+    console.log("一键接入 / 管理请用 `dingtalk-ask`（install / daemon / away / clean）。");
+    console.log("凭证也可用 DINGTALK_CLIENT_ID 等环境变量提供。");
+    process.exit(0);
+}
 /** 合并 CLI 参数与环境变量（参数优先）：允许用 --client-id 等命令行参数传钉钉配置。 */
-const env = mergeArgsIntoEnv(process.env, process.argv.slice(2));
+const env = mergeArgsIntoEnv(process.env, rawArgs);
 /**
  * 解析钉钉配置；缺凭证时打印缺失项到 stderr 并 exit(1)（AC5：不产生半可用状态）。
  *

package/dist/installCli.js

@@ -10,17 +10,18 @@
  * 写入均为宿主本地配置（.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 { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync, unlinkSync, readdirSync, statSync } from 'node:fs';
+import { homedir, tmpdir } 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 { packageVersion } from './version.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';
+import { isAway, setAway, awayFlagPath } from './awayState.js';
+import { buildMcpEntry, mergeMcpServers, ensureMcpToolTimeout, codexHasDingtalk, buildCodexBlock, inspectMcpJson, inspectSettingsHook, MCP_SERVER_NAME, } from './installConfig.js';
 /** 解析目标宿主。默认 CC；Codex 见 resolveCodexTarget。 */
 function parseHost(argv) {
     const i = argv.indexOf('--host');
@@ -93,15 +94,183 @@ function installCodex(config, nodePath, indexPath) {
     console.log(`✅ [Codex] 追加 [mcp_servers.dingtalk-ask] 到 ${cfgPath}${content !== '' ? '（已备份 .bak）' : ''}`);
 }
 function usage() {
-    console.log('dingtalk-ask —— 钉钉 human-in-the-loop MCP 工具');
+    console.log(`dingtalk-ask v${packageVersion()} —— 钉钉 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>                               # 本地切换离开模式');
+    console.log('  dingtalk-ask info                                               # 查看配置与进程状态');
+    console.log('  dingtalk-ask clean                                              # 清空运行时状态(守护进程/锁/flag/标记/日志)');
+    console.log('  dingtalk-ask -v | --version                                     # 版本');
+    console.log('  dingtalk-ask -h | --help                                        # 帮助');
     process.exit(1);
 }
+/** 宽松读 JSON：文件缺失/损坏都返回空对象（info 用，不抛错）。 */
+function tolerantJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** 轻度掩码（展示 userId 等，不完全暴露）。 */
+function mask(v) {
+    if (v === undefined || v === '') {
+        return '(未知)';
+    }
+    return v.length <= 4 ? '***' : `${v.slice(0, 3)}***${v.slice(-2)}`;
+}
+/** info 子命令：一屏看配置与进程状态。 */
+async function runInfo() {
+    const tmp = tmpdir();
+    const cwd = process.cwd();
+    console.log(`dingtalk-ask v${packageVersion()}`);
+    console.log('\n【进程】');
+    const lock = readDaemonLock(daemonLockPath());
+    if (lock === undefined) {
+        console.log('  守护进程：未运行');
+    }
+    else {
+        const probe = await probeHealth(lock);
+        console.log(`  守护进程：${probe.ok ? '在跑' : '锁存在但无应答'}  port=${lock.port} pid=${lock.pid} 就绪=${probe.ready}`);
+    }
+    console.log(`  离开模式：${isAway() ? '开（推钉钉）' : '关（只在终端）'}`);
+    let greeted = [];
+    try {
+        greeted = readdirSync(tmp)
+            .filter((f) => f.startsWith('dingtalk-greeted-'))
+            .map((f) => f.replace(/^dingtalk-greeted-/, '').replace(/\.flag$/, ''));
+    }
+    catch {
+        /* 忽略 */
+    }
+    console.log(`  已发就绪提示的机器人：${greeted.length > 0 ? greeted.join('、') : '无'}`);
+    const logPath = join(tmp, 'dingtalk-daemon.log');
+    try {
+        const st = statSync(logPath);
+        console.log(`  守护进程日志：${logPath}（${Math.round(st.size / 1024)}KB）`);
+    }
+    catch {
+        console.log('  守护进程日志：无');
+    }
+    console.log('\n【配置 · Claude Code】');
+    const mcp = inspectMcpJson(tolerantJson(join(cwd, '.mcp.json')));
+    console.log(`  .mcp.json (${cwd})：${mcp.configured ? `✅ 已配（command=${mcp.command ?? '?'}, userId=${mask(mcp.userId)}）` : '❌ 未配'}`);
+    const projSettings = inspectSettingsHook(tolerantJson(join(cwd, '.claude', 'settings.json')));
+    // MCP_TOOL_TIMEOUT 可能在 settings.json 或 settings.local.json，两处都看。
+    const localTimeout = inspectSettingsHook(tolerantJson(join(cwd, '.claude', 'settings.local.json'))).mcpToolTimeout;
+    const mcpToolTimeout = projSettings.mcpToolTimeout ?? localTimeout;
+    console.log(`  项目 settings.json：命令审批钩子 ${projSettings.hook ? '✅' : '❌'}` +
+        `，MCP_TOOL_TIMEOUT=${mcpToolTimeout ?? '未设'}`);
+    const userSettings = inspectSettingsHook(tolerantJson(join(homedir(), '.claude', 'settings.json')));
+    console.log(`  用户 settings.json (~)：命令审批钩子 ${userSettings.hook ? '✅' : '❌'}`);
+    console.log('\n【配置 · Codex】');
+    const codexPath = join(homedir(), '.codex', 'config.toml');
+    let codexContent = '';
+    try {
+        codexContent = readFileSync(codexPath, 'utf8');
+    }
+    catch {
+        codexContent = '';
+    }
+    if (codexContent === '') {
+        console.log(`  ${codexPath}：无文件（未用 Codex？）`);
+    }
+    else if (codexHasDingtalk(codexContent)) {
+        const m = /\[mcp_servers\.dingtalk-ask\][\s\S]*?tool_timeout_sec\s*=\s*(\d+)/.exec(codexContent);
+        console.log(`  ${codexPath}：✅ 已配（tool_timeout_sec=${m ? m[1] : '?'}）`);
+    }
+    else {
+        console.log(`  ${codexPath}：❌ 未配 dingtalk-ask`);
+    }
+}
+function main() {
+    const args = process.argv.slice(2);
+    const cmd = args[0];
+    const rest = args.slice(1);
+    if (cmd === '-v' || cmd === '--version') {
+        console.log(packageVersion());
+        return;
+    }
+    if (cmd === '-h' || cmd === '--help') {
+        usage();
+    }
+    if (cmd === 'install') {
+        runInstall(rest);
+    }
+    else if (cmd === 'daemon') {
+        void runDaemon(rest);
+    }
+    else if (cmd === 'away') {
+        runAway(rest);
+    }
+    else if (cmd === 'info') {
+        void runInfo();
+    }
+    else if (cmd === 'clean') {
+        runClean();
+    }
+    else {
+        usage();
+    }
+}
+main();
+function runClean() {
+    const tmp = tmpdir();
+    // 1. 停守护进程 + 删锁。
+    const lock = readDaemonLock(daemonLockPath());
+    if (lock !== undefined && lock.pid > 0) {
+        try {
+            process.kill(lock.pid, 'SIGTERM');
+            console.log(`· 已停守护进程 pid=${lock.pid}`);
+        }
+        catch {
+            /* 可能已退出 */
+        }
+    }
+    removeDaemonLock(daemonLockPath());
+    // 2. 离开模式 flag。
+    try {
+        unlinkSync(awayFlagPath());
+        console.log('· 已删离开模式 flag');
+    }
+    catch {
+        /* 不存在忽略 */
+    }
+    // 3. 就绪提示标记（各 robotCode）。
+    let markers = 0;
+    try {
+        for (const f of readdirSync(tmp)) {
+            if (f.startsWith('dingtalk-greeted-')) {
+                try {
+                    unlinkSync(join(tmp, f));
+                    markers += 1;
+                }
+                catch {
+                    /* 忽略 */
+                }
+            }
+        }
+    }
+    catch {
+        /* 忽略 */
+    }
+    if (markers > 0) {
+        console.log(`· 已删 ${markers} 个就绪提示标记`);
+    }
+    // 4. 守护进程日志。
+    try {
+        unlinkSync(join(tmp, 'dingtalk-daemon.log'));
+        console.log('· 已删守护进程日志');
+    }
+    catch {
+        /* 忽略 */
+    }
+    console.log('✅ 已清空运行时状态。配置文件(.mcp.json / settings.json / config.toml)未改动。');
+}
 /** install 子命令：装 MCP + 钩子。 */
 function runInstall(rest) {
     let config;
@@ -187,21 +356,3 @@ function runAway(rest) {
     }
     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

@@ -54,6 +54,32 @@ export function ensureMcpToolTimeout(settings, ms) {
 export function codexHasDingtalk(content) {
     return content.includes(`[mcp_servers.${MCP_SERVER_NAME}]`);
 }
+/** 检查 .mcp.json 是否配了 dingtalk-ask，并抽取 command / userId 供展示（纯函数）。 */
+export function inspectMcpJson(obj) {
+    const servers = obj.mcpServers;
+    const s = servers?.[MCP_SERVER_NAME];
+    if (s === undefined) {
+        return { configured: false };
+    }
+    let userId = s.env?.DINGTALK_USER_ID;
+    if (userId === undefined && Array.isArray(s.args)) {
+        const i = s.args.indexOf('--user-id');
+        if (i >= 0) {
+            userId = s.args[i + 1];
+        }
+    }
+    return { configured: true, command: s.command, userId };
+}
+/** 检查 settings.json 是否装了命令审批钩子、以及 MCP_TOOL_TIMEOUT（纯函数）。 */
+export function inspectSettingsHook(obj) {
+    const hooks = obj.hooks;
+    const list = hooks?.PermissionRequest;
+    const hook = Array.isArray(list) &&
+        list.some((e) => Array.isArray(e.hooks) && e.hooks.some((h) => typeof h.command === 'string' && h.command.includes('permissionHook.js')));
+    const env = obj.env;
+    const t = env?.MCP_TOOL_TIMEOUT;
+    return { hook, mcpToolTimeout: typeof t === 'string' ? t : undefined };
+}
 /**
  * 构造 Codex config.toml 追加块（TOML 基本字符串转义，无需 TOML 库）。
  *

package/dist/version.js

@@ -0,0 +1,20 @@
+/**
+ * 读取本包版本号（从 dist 上层的 package.json 动态读，随发版自动更新）。
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/**
+ * 读取 package.json 的 version。
+ *
+ * @returns 版本号；读取失败时返回 'unknown'。
+ */
+export function packageVersion() {
+    try {
+        const p = fileURLToPath(new URL('../package.json', import.meta.url));
+        const pkg = JSON.parse(readFileSync(p, 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dingtalk-ask-mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Human-in-the-loop MCP server：把 code agent（Claude Code / Codex）的决策与命令审批推送到钉钉，阻塞等你在手机回复。离开电脑也能远程拍板。",
   "keywords": [
     "mcp",