dingtalk-ask-mcp-server 0.1.0 → 0.1.1

package/README.md

@@ -140,10 +140,14 @@ Codex 若 `approval_policy="never"` 本就不弹命令审批,故只提供 `ask_h
 dingtalk-ask install …            # 一键接入(见上)
 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,16 +10,17 @@
  * 写入均为宿主本地配置（.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 } 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 { isAway, setAway, awayFlagPath } from './awayState.js';
 import { buildMcpEntry, mergeMcpServers, ensureMcpToolTimeout, codexHasDingtalk, buildCodexBlock, MCP_SERVER_NAME, } from './installConfig.js';
 /** 解析目标宿主。默认 CC；Codex 见 resolveCodexTarget。 */
 function parseHost(argv) {
@@ -93,15 +94,100 @@ 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 clean                                              # 清空运行时状态(守护进程/锁/flag/标记/日志)');
+    console.log('  dingtalk-ask -v | --version                                     # 版本');
+    console.log('  dingtalk-ask -h | --help                                        # 帮助');
     process.exit(1);
 }
+/** clean 子命令：清空运行时临时状态（不动配置文件）。 */
+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)未改动。');
+}
+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 === 'clean') {
+        runClean();
+    }
+    else {
+        usage();
+    }
+}
+main();
 /** install 子命令：装 MCP + 钩子。 */
 function runInstall(rest) {
     let config;
@@ -187,21 +273,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/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.1",
   "description": "Human-in-the-loop MCP server：把 code agent（Claude Code / Codex）的决策与命令审批推送到钉钉，阻塞等你在手机回复。离开电脑也能远程拍板。",
   "keywords": [
     "mcp",