@vrs-soft/wecom-aibot-mcp 1.4.0 → 2.3.0

package/dist/bin.js

@@ -13,7 +13,7 @@ import { spawn } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { runConfigWizard, loadConfig, saveConfig, deleteConfig, deleteMcpConfigInteractive, uninstall, addMcpConfig, detectUserIdFromMessage, ensureHookInstalled, listAllRobots, } from './config-wizard.js';
+import { runConfigWizard, loadConfig, saveConfig, deleteRobotConfigInteractive, uninstall, addMcpConfig, detectUserIdFromMessage, ensureHookInstalled, listAllRobots, ensureGlobalConfigs, } from './config-wizard.js';
 import { initClient } from './client.js';
 import { registerTools } from './tools/index.js';
 import { startHttpServer, stopHttpServer, HTTP_PORT } from './http-server.js';
@@ -21,7 +21,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { getAllConnectionStates } from './connection-manager.js';
 import { loadStats, cleanupOldLogs } from './connection-log.js';
 import { startKeepaliveMonitor, stopKeepaliveMonitor } from './keepalive-monitor.js';
-const VERSION = '1.2.0';
+import { logger } from './logger.js';
+const VERSION = '2.0.0';
 const PID_FILE = path.join(os.homedir(), '.wecom-aibot-mcp', 'server.pid');
 function showHelp() {
     console.log(`
@@ -36,15 +37,22 @@ function showHelp() {
 选项:
   --help, -h      显示帮助信息
   --version, -v   显示版本号
+  --upgrade       强制升级全局配置（覆盖 MCP 配置、权限、skill）
+  --reinstall     重新安装全局配置（删除后重新写入，保留机器人配置）
   --start         启动 MCP Server（后台服务模式）
   --stop          停止 MCP Server
   --debug         前台启动 MCP Server（日志直接输出到终端，用于调试）
+  --channel       启动 Channel MCP Proxy（stdio 代理 + SSE 唤醒）
+  --http-only     仅启动 HTTP Server（远程部署场景，不安装 Channel MCP 配置）
+  --channel-only  仅配置 Channel MCP（本地连接远程 HTTP Server）
   --status        显示服务状态和机器人配置
   --config        重新配置默认机器人（修改 Bot ID / Secret / 目标用户）
   --add           添加新的机器人配置（多机器人场景）
+  --rename [名称] 重命名机器人（可选参数：旧名称，交互式输入新名称）
   --list          列出所有已配置的机器人及其占用状态
-  --delete [名称] 删除指定的机器人配置（无参数则显示列表选择）
+  --delete [名称] 删除指定的机器人配置（保留 MCP 配置）
   --uninstall     卸载并删除所有配置（包括 MCP 配置、hook、skill）
+  --clean-cache   清空 CC 注册表缓存（清理异常断线残留的 ccId）
 
 使用流程:
   1. 首次安装: npx @vrs-soft/wecom-aibot-mcp
@@ -58,18 +66,34 @@ function showHelp() {
 
   4. 停止服务: npx @vrs-soft/wecom-aibot-mcp --stop
 
-MCP 配置（HTTP Transport）:
+拆分部署（远程 HTTP + 本地 Channel）:
 
-  编辑 ~/.claude.json：
+  远程服务器:
+    npx @vrs-soft/wecom-aibot-mcp --http-only --start
+    # 只启动 HTTP Server，不写入本地 MCP 配置
 
-  {
-    "mcpServers": {
-      "wecom-aibot": {
-        "type": "http",
-        "url": "http://127.0.0.1:18963/mcp"
-      }
-    }
-  }
+  本地机器:
+    MCP_URL=http://远程IP:18963 npx @vrs-soft/wecom-aibot-mcp --channel-only
+    # 必须通过 MCP_URL 指定远程 HTTP MCP 地址
+    # 只配置 Channel MCP，连接远程 HTTP Server
+
+MCP 配置（默认安装同时配置两种模式）:
+
+  HTTP Transport（轮询模式）:
+    "wecom-aibot": {
+      "type": "http",
+      "url": "http://127.0.0.1:18963/mcp"
+    }
+
+  Channel Transport（SSE 推送模式）:
+    "wecom-aibot-channel": {
+      "command": "npx",
+      "args": ["@vrs-soft/wecom-aibot-mcp", "--channel"]
+    }
+
+  Channel 模式优势：微信消息自动唤醒 agent，无需主动轮询
+  启动 Channel 模式（研究预览）：
+    claude --dangerously-load-development-channels server:wecom-aibot-channel
 
 更多信息: https://github.com/eric2877/wecom-aibot-mcp
 `);
@@ -98,11 +122,11 @@ function showStatus() {
     for (const robot of allRobots) {
         const usage = robotUsage.get(robot.name);
         const statusTag = usage ? ` [使用中]` : '';
-        console.log(`  ${robot.name}${statusTag}`);
-        console.log(`    Bot ID:     ${robot.botId}`);
-        console.log(`    目标用户:   ${robot.targetUserId}`);
+        console.log(`    Bot名称：  ${robot.name}${statusTag}`);
+        console.log(`    Bot ID：   ${robot.botId}`);
+        console.log(`    目标用户：${robot.targetUserId}`);
         if (usage) {
-            console.log(`    使用者:     ${usage.agentName}`);
+            console.log(`    使用者：  ${usage.agentName}`);
         }
         console.log('');
     }
@@ -157,7 +181,7 @@ function stopServer() {
         return true;
     }
     catch (err) {
-        console.error('[mcp] 停止服务失败:', err);
+        logger.error('[mcp] 停止服务失败:', err);
         if (fs.existsSync(PID_FILE)) {
             fs.unlinkSync(PID_FILE);
         }
@@ -181,14 +205,20 @@ async function waitForConnection(client, timeoutMs = 10000) {
     });
 }
 // 启动 MCP Server（前台运行，供 --start 使用）
-async function startMcpServerForeground() {
+async function startMcpServerForeground(isDebug = false) {
     const savedConfig = loadConfig();
     if (!savedConfig || !savedConfig.botId || !savedConfig.secret || !savedConfig.targetUserId) {
-        console.error('[mcp] 未找到配置，请先运行: npx @vrs-soft/wecom-aibot-mcp');
+        logger.error('[mcp] 未找到配置，请先运行: npx @vrs-soft/wecom-aibot-mcp');
         process.exit(1);
     }
     // 写入 PID 文件
     fs.writeFileSync(PID_FILE, String(process.pid));
+    // Debug 模式：创建 debug 标记文件
+    if (isDebug) {
+        const debugFile = path.join(os.homedir(), '.wecom-aibot-mcp', 'debug');
+        fs.writeFileSync(debugFile, 'true');
+        console.log('[mcp] Debug 标记文件已创建');
+    }
     // 确保 hook 已安装
     ensureHookInstalled();
     // 加载统计并清理旧日志
@@ -201,20 +231,20 @@ async function startMcpServerForeground() {
     });
     registerTools(server);
     // 启动 HTTP 服务
-    console.log('');
-    console.log('  ╔════════════════════════════════════════════════════════╗');
-    console.log(`  ║   企业微信智能机器人 MCP 服务 v${VERSION}                   ║`);
-    console.log('  ║   Claude Code 审批通道                                 ║');
-    console.log('  ╚════════════════════════════════════════════════════════╝');
-    console.log('');
-    console.log(`[mcp] 启动 MCP HTTP Server (端口: ${HTTP_PORT})...`);
+    logger.log('');
+    logger.log('  ╔════════════════════════════════════════════════════════╗');
+    logger.log(`  ║   企业微信智能机器人 MCP 服务 v${VERSION}                   ║`);
+    logger.log('  ║   Claude Code 审批通道                                 ║');
+    logger.log('  ╚════════════════════════════════════════════════════════╝');
+    logger.log('');
+    logger.log(`[mcp] 启动 MCP HTTP Server (端口: ${HTTP_PORT})...`);
     await startHttpServer(server);
     startKeepaliveMonitor();
-    console.log(`[mcp] MCP Server 已就绪`);
-    console.log(`[mcp] HTTP endpoint: http://127.0.0.1:${HTTP_PORT}/mcp`);
-    console.log(`[mcp] 健康检查: http://127.0.0.1:${HTTP_PORT}/health`);
-    console.log(`[mcp] 微信模式：enter_headless_mode 时建立连接`);
-    console.log(`[mcp] PID: ${process.pid}`);
+    logger.log(`[mcp] MCP Server 已就绪`);
+    logger.log(`[mcp] HTTP endpoint: http://127.0.0.1:${HTTP_PORT}/mcp`);
+    logger.log(`[mcp] 健康检查: http://127.0.0.1:${HTTP_PORT}/health`);
+    logger.log(`[mcp] 微信模式：enter_headless_mode 时建立连接`);
+    logger.log(`[mcp] PID: ${process.pid}`);
     // 退出处理
     const gracefulShutdown = () => {
         console.log('[mcp] 正在关闭...');
@@ -223,6 +253,14 @@ async function startMcpServerForeground() {
         if (fs.existsSync(PID_FILE)) {
             fs.unlinkSync(PID_FILE);
         }
+        // Debug 模式：删除 debug 标记文件
+        if (isDebug) {
+            const debugFile = path.join(os.homedir(), '.wecom-aibot-mcp', 'debug');
+            if (fs.existsSync(debugFile)) {
+                fs.unlinkSync(debugFile);
+                console.log('[mcp] Debug 标记文件已删除');
+            }
+        }
         process.exit(0);
     };
     process.on('SIGINT', gracefulShutdown);
@@ -233,7 +271,7 @@ function startMcpServerBackground() {
     // 检查配置是否存在
     const savedConfig = loadConfig();
     if (!savedConfig || !savedConfig.botId || !savedConfig.secret || !savedConfig.targetUserId) {
-        console.error('[mcp] 未找到配置，请先运行: npx @vrs-soft/wecom-aibot-mcp');
+        logger.error('[mcp] 未找到配置，请先运行: npx @vrs-soft/wecom-aibot-mcp');
         process.exit(1);
     }
     // 检查是否已运行
@@ -249,13 +287,22 @@ function startMcpServerBackground() {
     });
     child.unref();
     console.log('[mcp] MCP Server 已在后台启动');
-    console.log(`[mcp] HTTP endpoint: http://127.0.0.1:18963/mcp`);
+    logger.log(`[mcp] HTTP endpoint: http://127.0.0.1:18963/mcp`);
     console.log('[mcp] 健康检查: curl http://127.0.0.1:18963/health');
     console.log('[mcp] 停止服务: npx @vrs-soft/wecom-aibot-mcp --stop');
     console.log('[mcp] 调试模式: npx @vrs-soft/wecom-aibot-mcp --debug');
 }
 async function main() {
     const args = process.argv.slice(2);
+    // 确定安装模式
+    const installMode = args.includes('--http-only') ? 'http-only' :
+        args.includes('--channel-only') ? 'channel-only' : 'full';
+    // --reinstall 命令需要先删除再安装，跳过开头的 ensureGlobalConfigs
+    // --http-only 模式不需要写 MCP 配置
+    if (!args.includes('--reinstall') && !args.includes('--http-only')) {
+        // 强制覆盖所有全局配置（不依赖智能体）
+        ensureGlobalConfigs(installMode);
+    }
     // 解析命令行参数
     if (args.includes('--help') || args.includes('-h')) {
         showHelp();
@@ -265,6 +312,68 @@ async function main() {
         showVersion();
         process.exit(0);
     }
+    // --upgrade 命令：强制升级全局配置（已在启动时执行，这里显示结果）
+    if (args.includes('--upgrade')) {
+        console.log('\n[mcp] ✅ 全局配置已更新完成！');
+        console.log('[mcp] 配置位置:');
+        console.log('  - ~/.claude.json (MCP Server 配置)');
+        console.log('  - ~/.claude/settings.local.json (权限和 Hook)');
+        console.log('  - ~/.wecom-aibot-mcp/version.json (版本记录)');
+        console.log('\n[mcp] 请重启 Claude Code 以加载最新配置');
+        process.exit(0);
+    }
+    // --reinstall 命令：删除所有全局配置（保留机器人配置）后重新安装
+    if (args.includes('--reinstall')) {
+        logger.log('\n[mcp] 重新安装全局配置...');
+        console.log('[mcp] 保留所有机器人配置: ~/.wecom-aibot-mcp/config.json 和 robot-*.json');
+        const CLAUDE_CONFIG_FILE = path.join(os.homedir(), '.claude.json');
+        const CLAUDE_SETTINGS_FILE = path.join(os.homedir(), '.claude', 'settings.local.json');
+        const VERSION_FILE = path.join(os.homedir(), '.wecom-aibot-mcp', 'version.json');
+        const HOOK_SCRIPT = path.join(os.homedir(), '.wecom-aibot-mcp', 'permission-hook.sh');
+        // 1. 删除 ~/.claude.json 中的 wecom-aibot 配置
+        if (fs.existsSync(CLAUDE_CONFIG_FILE)) {
+            const content = fs.readFileSync(CLAUDE_CONFIG_FILE, 'utf-8');
+            const config = JSON.parse(content);
+            if (config.mcpServers?.['wecom-aibot']) {
+                delete config.mcpServers['wecom-aibot'];
+                fs.writeFileSync(CLAUDE_CONFIG_FILE, JSON.stringify(config, null, 2));
+                console.log('[mcp] 已删除 ~/.claude.json 中的 wecom-aibot 配置');
+            }
+        }
+        // 2. 删除 ~/.claude/settings.local.json 中的权限和 Hook
+        if (fs.existsSync(CLAUDE_SETTINGS_FILE)) {
+            const content = fs.readFileSync(CLAUDE_SETTINGS_FILE, 'utf-8');
+            const config = JSON.parse(content);
+            if (config.permissions?.allow) {
+                config.permissions.allow = config.permissions.allow.filter((p) => !p.startsWith('mcp__wecom-aibot__'));
+                console.log('[mcp] 已删除 wecom-aibot 工具权限');
+            }
+            if (config.hooks?.PermissionRequest) {
+                config.hooks.PermissionRequest = config.hooks.PermissionRequest.filter((h) => !h.hooks?.some?.((hook) => hook.command?.includes?.('wecom-aibot-mcp')));
+                if (config.hooks.PermissionRequest.length === 0) {
+                    delete config.hooks.PermissionRequest;
+                }
+                console.log('[mcp] 已删除 PermissionRequest hook');
+            }
+            fs.writeFileSync(CLAUDE_SETTINGS_FILE, JSON.stringify(config, null, 2));
+        }
+        // 3. 删除版本文件
+        if (fs.existsSync(VERSION_FILE)) {
+            fs.unlinkSync(VERSION_FILE);
+            console.log('[mcp] 已删除 ~/.wecom-aibot-mcp/version.json');
+        }
+        // 4. 删除 hook 脚本
+        if (fs.existsSync(HOOK_SCRIPT)) {
+            fs.unlinkSync(HOOK_SCRIPT);
+            console.log('[mcp] 已删除 ~/.wecom-aibot-mcp/permission-hook.sh');
+        }
+        // 5. 重新安装全局配置
+        logger.log('\n[mcp] 正在重新安装...');
+        ensureGlobalConfigs();
+        logger.log('\n[mcp] ✅ 重新安装完成！');
+        console.log('[mcp] 请重启 Claude Code 以加载最新配置');
+        process.exit(0);
+    }
     if (args.includes('--status') || args.includes('--list')) {
         showStatus();
         process.exit(0);
@@ -274,6 +383,27 @@ async function main() {
         stopServer();
         process.exit(0);
     }
+    // --clean-cache 命令：清空 CC 注册表缓存
+    if (args.includes('--clean-cache')) {
+        if (!isServerRunning()) {
+            console.log('[mcp] 服务未运行，无需清理缓存');
+            process.exit(0);
+        }
+        try {
+            const res = await fetch(`http://127.0.0.1:${HTTP_PORT}/admin/clean-cache`, { method: 'POST' });
+            const data = await res.json();
+            if (data.ok) {
+                console.log(`[mcp] 已清空 CC 注册表，共清理 ${data.cleared} 条`);
+                if (data.entries.length > 0) {
+                    console.log(`[mcp] 已清理: ${data.entries.join(', ')}`);
+                }
+            }
+        }
+        catch (err) {
+            console.error('[mcp] 清理失败:', err);
+        }
+        process.exit(0);
+    }
     // --uninstall 命令：先停止服务再卸载
     if (args.includes('--uninstall')) {
         if (isServerRunning()) {
@@ -290,8 +420,8 @@ async function main() {
     // --delete 命令：删除单个机器人配置
     const deleteIndex = args.indexOf('--delete');
     if (deleteIndex !== -1) {
-        const instanceName = args[deleteIndex + 1]; // 可选参数：实例名
-        await deleteMcpConfigInteractive(instanceName);
+        const robotName = args[deleteIndex + 1]; // 可选参数：机器人名称
+        await deleteRobotConfigInteractive(robotName);
         process.exit(0);
     }
     // --start --foreground：前台启动（内部调用，输出到日志文件）
@@ -299,12 +429,52 @@ async function main() {
         await startMcpServerForeground();
         return; // 保持运行，不 exit
     }
+    // --channel：启动 Channel MCP 代理（stdio）
+    // 注意：必须在 --debug 之前检查，否则 --channel --debug 会先触发 HTTP Server
+    if (args.includes('--channel')) {
+        // 检查 HTTP MCP 的 debug 标记文件
+        const debugFile = path.join(os.homedir(), '.wecom-aibot-mcp', 'debug');
+        const isDebug = fs.existsSync(debugFile) || args.includes('--debug');
+        if (isDebug) {
+            console.log('[channel] Debug 模式：日志输出到 stderr（跟随 HTTP MCP debug）');
+            if (!fs.existsSync(debugFile)) {
+                fs.writeFileSync(debugFile, 'true');
+            }
+        }
+        console.log('[channel] Starting Channel MCP Proxy...');
+        const { startChannelServer } = await import('./channel-server.js');
+        await startChannelServer();
+        // Channel MCP 退出时不删除 debug 文件（由 HTTP MCP 管理）
+        return; // 保持运行，不 exit
+    }
     // --debug：前台启动，日志直接输出到终端
     if (args.includes('--debug')) {
         console.log('[mcp] Debug 模式：前台运行，Ctrl+C 退出');
-        await startMcpServerForeground();
+        await startMcpServerForeground(true);
         return;
     }
+    // --http-only：仅启动 HTTP Server（远程部署场景）
+    if (args.includes('--http-only') && !args.includes('--start')) {
+        console.log('[mcp] HTTP-only 模式：仅启动 HTTP Server');
+        console.log('[mcp] 不写入 MCP 配置（远程部署场景）');
+        console.log('[mcp] 使用 --http-only --start 启动服务');
+        process.exit(0);
+    }
+    // --channel-only：仅配置 Channel MCP（本地连接远程 HTTP Server）
+    if (args.includes('--channel-only')) {
+        const mcpUrl = process.env.MCP_URL;
+        if (!mcpUrl) {
+            console.log('[mcp] ❌ Channel-only 模式需要指定远程 HTTP MCP 地址');
+            console.log('[mcp] 请设置环境变量 MCP_URL:');
+            console.log('[mcp]   MCP_URL=http://远程IP:18963 npx @vrs-soft/wecom-aibot-mcp --channel-only');
+            process.exit(1);
+        }
+        console.log(`[mcp] Channel-only 模式：Channel MCP 已配置`);
+        console.log(`[mcp] 连接地址: ${mcpUrl}`);
+        console.log('[mcp] 请确保远程 HTTP Server 已启动');
+        console.log('[mcp] 启动 Channel: npx @vrs-soft/wecom-aibot-mcp --channel');
+        process.exit(0);
+    }
     // --start：后台启动
     if (args.includes('--start')) {
         startMcpServerBackground();
@@ -312,12 +482,12 @@ async function main() {
     }
     const reconfig = args.includes('--config');
     const isInteractive = process.stdin.isTTY; // 是否为用户交互模式
-    console.log('');
-    console.log('  ╔════════════════════════════════════════════════════════╗');
-    console.log(`  ║   企业微信智能机器人 MCP 服务 v${VERSION}                   ║`);
-    console.log('  ║   Claude Code 审批通道                                 ║');
-    console.log('  ╚════════════════════════════════════════════════════════╝');
-    console.log('');
+    logger.log('');
+    logger.log('  ╔════════════════════════════════════════════════════════╗');
+    logger.log(`  ║   企业微信智能机器人 MCP 服务 v${VERSION}                   ║`);
+    logger.log('  ║   Claude Code 审批通道                                 ║');
+    logger.log('  ╚════════════════════════════════════════════════════════╝');
+    logger.log('');
     // 加载统计并清理旧日志（保留 1 小时）
     loadStats();
     cleanupOldLogs(1 / 24);
@@ -348,8 +518,8 @@ async function main() {
         }
         else {
             // 非 TTY 模式（MCP HTTP），必须有配置
-            console.error('[config] 未找到配置，且当前为非交互模式。');
-            console.error('[config] 请在终端运行: npx @vrs-soft/wecom-aibot-mcp --config');
+            logger.error('[config] 未找到配置，且当前为非交互模式。');
+            logger.error('[config] 请在终端运行: npx @vrs-soft/wecom-aibot-mcp --config');
             process.exit(1);
         }
     }
@@ -362,11 +532,7 @@ async function main() {
         const tempClient = initClient(config.botId, config.secret, config.targetUserId || 'placeholder', 'temp-validation');
         const connected = await waitForConnection(tempClient, 10000);
         if (!connected) {
-            console.log('[mcp] 连接失败，可能是配置错误或机器人未授权');
-            console.log('[mcp] 请检查上面的错误提示，修复后重新配置');
-            // 删除无效配置，让用户重新输入
-            deleteConfig();
-            console.log('\n请检查：');
+            console.log('[mcp] ❌ 连接失败，请检查：');
             console.log('  1. Bot ID 和 Secret 是否正确');
             console.log('  2. 新建机器人需等待约 2 分钟同步');
             console.log('  3. 是否已完成授权（机器人详情 → 可使用权限 → 授权）');
@@ -375,35 +541,37 @@ async function main() {
             process.exit(1);
         }
         // 连接成功
-        console.log('\n[mcp] ✅ 机器人连接成功！');
-        // 提示用户发送消息来识别用户 ID
-        const userId = await detectUserIdFromMessage(tempClient, 180);
-        if (!userId) {
-            console.log('\n[mcp] 未能在规定时间内识别用户 ID');
-            console.log('[mcp] 请重新运行配置：npx @vrs-soft/wecom-aibot-mcp --config');
-            tempClient.disconnect();
-            process.exit(1);
+        logger.log('\n[mcp] ✅ 机器人凭证验证成功！');
+        // 保存配置（使用原用户 ID 或等待识别）
+        if (!config.targetUserId || config.targetUserId === 'placeholder' || config.targetUserId === '') {
+            // 新机器人，需要识别用户 ID
+            const userId = await detectUserIdFromMessage(tempClient, 180);
+            if (!userId) {
+                logger.log('\n[mcp] 未能在规定时间内识别用户 ID');
+                console.log('[mcp] 请重新运行配置：npx @vrs-soft/wecom-aibot-mcp --config');
+                tempClient.disconnect();
+                process.exit(1);
+            }
+            config.targetUserId = userId;
         }
-        // 更新配置中的用户 ID
-        config.targetUserId = userId;
         // 保存最终配置
         saveConfig(config, instanceName);
-        console.log('\n[mcp] ✅ 配置完成！');
-        console.log(`[mcp] 用户 ID: ${userId}`);
+        logger.log('\n[mcp] ✅ 配置完成！');
+        logger.log(`[mcp] 用户 ID: ${config.targetUserId}`);
         // 配置完成后断开连接
         tempClient.disconnect();
         // 首次安装后自动后台启动服务
-        console.log('\n[mcp] 正在后台启动 MCP Server...');
+        logger.log('\n[mcp] 正在后台启动 MCP Server...');
         startMcpServerBackground();
         console.log('[mcp] 请重启 Claude Code 以加载 MCP 服务\n');
         process.exit(0);
     }
     // 已有配置，显示状态并提示启动命令
     showStatus();
-    console.log('\n[mcp] 使用 --start 启动服务，--stop 停止服务');
+    logger.log('\n[mcp] 使用 --start 启动服务，--stop 停止服务');
     console.log('[mcp] 命令: npx @vrs-soft/wecom-aibot-mcp --start\n');
 }
 main().catch((err) => {
-    console.error('[mcp] 启动失败:', err);
+    logger.error('[mcp] 启动失败:', err);
     process.exit(1);
 });

package/dist/cc-registry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ccId 注册表
+ *
+ * 管理 ~/.wecom-aibot-mcp/cc-registry.json
+ * 维护 ccId → { robotName, lastActive, createdAt } 的映射
+ *
+ * 文件锁通过 .lock 文件实现（EEXIST 原子性）
+ */
+/**
+ * 设置配置目录（仅用于测试）
+ */
+export declare function setConfigDir(dir: string): void;
+export interface CcRegistryEntry {
+    robotName: string;
+    lastActive: number;
+    createdAt: number;
+    lastNotified?: number;
+}
+type Registry = Record<string, CcRegistryEntry>;
+/**
+ * 公开接口：独立调用时使用（内部会获取锁）
+ */
+export declare function cleanupExpiredEntries(): void;
+export type RegisterResult = 'registered' | 'renewed' | 'occupied';
+/**
+ * 注册 ccId
+ * - 新 ccId → registered
+ * - 已存在且 robotName 相同 → renewed（续期）
+ * - 已存在且 robotName 不同 → occupied（被占用）
+ */
+export declare function registerCcId(ccId: string, robotName: string): RegisterResult;
+/**
+ * 注销 ccId
+ */
+export declare function unregisterCcId(ccId: string): void;
+/**
+ * 检查 ccId 是否已注册
+ */
+export declare function isCcIdRegistered(ccId: string): boolean;
+/**
+ * 更新 ccId 的最后活跃时间
+ */
+export declare function touchCcId(ccId: string): void;
+/**
+ * 获取 ccId 绑定的机器人名称
+ */
+export declare function getCcIdBinding(ccId: string): {
+    robotName: string;
+} | null;
+/**
+ * 获取完整注册表（调试用）
+ */
+export declare function getRegistry(): Registry;
+/**
+ * 启动心跳检测（5 分钟扫描一次）
+ */
+export declare function startHeartbeatMonitor(): void;
+/**
+ * 停止心跳检测
+ */
+export declare function stopHeartbeatMonitor(): void;
+export {};