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

package/README.md

@@ -1,5 +1,7 @@
 # @vrs-soft/wecom-aibot-mcp
 
+中文 | [English](README_EN.md)
+
 企业微信智能机器人 MCP 服务 - Claude Code 远程审批通道
 
 > 通过企业微信智能机器人实现 Claude Code 的远程审批和消息推送，离开电脑也能处理决策请求。
@@ -9,7 +11,6 @@
 - 🔐 **远程审批**：敏感操作通过微信卡片审批，支持"允许一次/拒绝"
 - 💬 **双向通信**：任务进度、完成通知实时推送到微信
 - 📱 **Headless 模式**：离开电脑时切换到微信交互，长轮询实时接收消息
-- 🔄 **智能代批**：超时自动审批，项目内操作允许，删除操作拒绝
 - 🤖 **多机器人支持**：支持配置多个机器人，团队场景下多人独立使用
 - 🌐 **HTTP Transport**：使用 HTTP 传输，支持多实例共享服务
 
@@ -143,6 +144,7 @@ npx @vrs-soft/wecom-aibot-mcp
 | `npx @vrs-soft/wecom-aibot-mcp --add` | 添加新机器人 |
 | `npx @vrs-soft/wecom-aibot-mcp --delete` | 删除机器人配置 |
 | `npx @vrs-soft/wecom-aibot-mcp --uninstall` | 完全卸载 |
+| `npx @vrs-soft/wecom-aibot-mcp --debug` | 前台启动（输出调试日志） |
 
 ### 添加新机器人
 
@@ -290,6 +292,36 @@ Claude：执行命令，发送结果到群聊
 }
 ```
 
+### 超时审批配置
+
+在 `~/.wecom-aibot-mcp/config.json` 中可配置审批超时时间：
+
+```json
+{
+  "botId": "bot-xxx",
+  "secret": "sec-yyy",
+  "targetUserId": "user1",
+  "nameTag": "机器人1",
+  "autoApproveTimeout": 600
+}
+```
+
+- `autoApproveTimeout`: 审批超时时间（秒），默认 600 秒（10 分钟）
+- 超时后，项目目录内的操作会自动允许，项目外的操作会自动拒绝
+
+### 调试模式
+
+使用 `--debug` 启动可在终端查看 hook 脚本的调试日志：
+
+```bash
+npx @vrs-soft/wecom-aibot-mcp --debug
+```
+
+调试日志会输出到 stderr，包括：
+- 审批请求拦截信息
+- 超时时间配置
+- 操作类型判断详情
+
 ## 故障排查
 
 ### 认证失败（错误码 40058）

package/dist/approval-manager.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 审批管理器
+ *
+ * 负责：
+ * 1. 存储 pendingApprovals Map（http-server 审批记录）
+ * 2. 持久化到 approval-state.json，MCP 重启后恢复
+ * 3. 恢复时将 approvalRecord 注入对应的 WecomClient
+ *
+ * 与 WecomClient.approvals 的关系：
+ * - WecomClient.approvals 记录企业微信卡片状态（用户点击后更新）
+ * - approval-manager 记录 http-server 层的审批条目
+ * - MCP 重启后，WecomClient 实例是全新的，需要 injectApprovalRecord 恢复
+ */
+export interface ApprovalEntry {
+    taskId: string;
+    status: 'pending' | 'allow-once' | 'allow-always' | 'deny';
+    timestamp: number;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    description: string;
+    robotName: string;
+}
+/**
+ * 设置配置目录（仅用于测试）
+ */
+export declare function setConfigDir(dir: string): void;
+export declare function addApproval(entry: ApprovalEntry): void;
+export declare function getApproval(taskId: string): ApprovalEntry | undefined;
+export declare function updateApprovalStatus(taskId: string, status: 'allow-once' | 'allow-always' | 'deny'): void;
+export declare function getPendingApprovals(): Map<string, ApprovalEntry>;
+export declare function saveApprovalState(): void;
+/**
+ * 从文件恢复审批状态，并将审批记录注入对应的 WecomClient
+ * 需在 connectAllRobots() 完成后调用，确保 client 已存在
+ */
+export declare function loadApprovalState(getClientFn: (robotName: string) => Promise<import('./client.js').WecomClient | null>): Promise<void>;
+export declare function startAutoSave(): void;
+export declare function stopAutoSave(): void;

package/dist/approval-manager.js

@@ -0,0 +1,129 @@
+/**
+ * 审批管理器
+ *
+ * 负责：
+ * 1. 存储 pendingApprovals Map（http-server 审批记录）
+ * 2. 持久化到 approval-state.json，MCP 重启后恢复
+ * 3. 恢复时将 approvalRecord 注入对应的 WecomClient
+ *
+ * 与 WecomClient.approvals 的关系：
+ * - WecomClient.approvals 记录企业微信卡片状态（用户点击后更新）
+ * - approval-manager 记录 http-server 层的审批条目
+ * - MCP 重启后，WecomClient 实例是全新的，需要 injectApprovalRecord 恢复
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { atomicWriteFileSync } from './utils/atomic-write.js';
+const pendingApprovals = new Map();
+// 支持测试环境覆盖
+let CONFIG_DIR = path.join(os.homedir(), '.wecom-aibot-mcp');
+let APPROVAL_STATE_FILE = path.join(CONFIG_DIR, 'approval-state.json');
+/**
+ * 设置配置目录（仅用于测试）
+ */
+export function setConfigDir(dir) {
+    CONFIG_DIR = dir;
+    APPROVAL_STATE_FILE = path.join(CONFIG_DIR, 'approval-state.json');
+}
+let saveInterval = null;
+// ────────────────────────────────────────────
+// 审批 CRUD
+// ────────────────────────────────────────────
+export function addApproval(entry) {
+    pendingApprovals.set(entry.taskId, entry);
+}
+export function getApproval(taskId) {
+    return pendingApprovals.get(taskId);
+}
+export function updateApprovalStatus(taskId, status) {
+    const entry = pendingApprovals.get(taskId);
+    if (entry) {
+        entry.status = status;
+        // 审批完成后从 Map 中移除，避免 pendingApprovals.size 持续增长
+        pendingApprovals.delete(taskId);
+    }
+}
+export function getPendingApprovals() {
+    return pendingApprovals;
+}
+// ────────────────────────────────────────────
+// 持久化
+// ────────────────────────────────────────────
+export function saveApprovalState() {
+    const approvals = [];
+    for (const [taskId, entry] of pendingApprovals) {
+        if (entry.status === 'pending') {
+            approvals.push({ taskId, entry });
+        }
+    }
+    // 无待处理审批时不创建文件
+    if (approvals.length === 0)
+        return;
+    try {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+        atomicWriteFileSync(APPROVAL_STATE_FILE, JSON.stringify({ approvals, savedAt: Date.now() }, null, 2));
+        console.log(`[approval-manager] 已保存 ${approvals.length} 个待处理审批`);
+    }
+    catch (err) {
+        console.error('[approval-manager] 保存审批状态失败:', err);
+    }
+}
+/**
+ * 从文件恢复审批状态，并将审批记录注入对应的 WecomClient
+ * 需在 connectAllRobots() 完成后调用，确保 client 已存在
+ */
+export async function loadApprovalState(getClientFn) {
+    if (!fs.existsSync(APPROVAL_STATE_FILE))
+        return;
+    try {
+        const content = fs.readFileSync(APPROVAL_STATE_FILE, 'utf-8');
+        const state = JSON.parse(content);
+        // 只恢复 10 分钟内的 pending 审批（超时的不再有效）
+        const now = Date.now();
+        const maxAge = 10 * 60 * 1000;
+        let restored = 0;
+        for (const { taskId, entry } of state.approvals) {
+            if (entry.status === 'pending' && now - entry.timestamp < maxAge) {
+                pendingApprovals.set(taskId, entry);
+                // 将审批记录注入对应 WecomClient，使用户点击后能正确路由
+                const client = await getClientFn(entry.robotName);
+                if (client) {
+                    client.injectApprovalRecord(taskId, {
+                        toolName: entry.tool_name,
+                        toolInput: entry.tool_input,
+                    });
+                    console.log(`[approval-manager] 恢复审批: ${taskId} → robot=${entry.robotName}`);
+                    restored++;
+                }
+                else {
+                    console.warn(`[approval-manager] 恢复审批 ${taskId} 失败：机器人 ${entry.robotName} 不在线`);
+                }
+            }
+        }
+        // 恢复完成，删除持久化文件
+        fs.unlinkSync(APPROVAL_STATE_FILE);
+        console.log(`[approval-manager] 共恢复 ${restored} 个审批`);
+    }
+    catch (err) {
+        console.warn('[approval-manager] 恢复审批状态失败:', err);
+    }
+}
+// ────────────────────────────────────────────
+// 定时保存
+// ────────────────────────────────────────────
+export function startAutoSave() {
+    if (saveInterval)
+        return;
+    saveInterval = setInterval(() => {
+        if (pendingApprovals.size > 0) {
+            saveApprovalState();
+        }
+    }, 30000);
+}
+export function stopAutoSave() {
+    if (saveInterval) {
+        clearInterval(saveInterval);
+        saveInterval = null;
+    }
+}

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, deleteConfig, deleteMcpConfigInteractive, 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,7 @@ 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';
+const VERSION = '1.4.2';
 const PID_FILE = path.join(os.homedir(), '.wecom-aibot-mcp', 'server.pid');
 function showHelp() {
     console.log(`
@@ -36,6 +36,8 @@ function showHelp() {
 选项:
   --help, -h      显示帮助信息
   --version, -v   显示版本号
+  --upgrade       强制升级全局配置（覆盖 MCP 配置、权限、skill）
+  --reinstall     重新安装全局配置（删除后重新写入，保留机器人配置）
   --start         启动 MCP Server（后台服务模式）
   --stop          停止 MCP Server
   --debug         前台启动 MCP Server（日志直接输出到终端，用于调试）
@@ -256,6 +258,11 @@ function startMcpServerBackground() {
 }
 async function main() {
     const args = process.argv.slice(2);
+    // --reinstall 命令需要先删除再安装，跳过开头的 ensureGlobalConfigs
+    if (!args.includes('--reinstall')) {
+        // 强制覆盖所有全局配置（不依赖智能体）
+        ensureGlobalConfigs();
+    }
     // 解析命令行参数
     if (args.includes('--help') || args.includes('-h')) {
         showHelp();
@@ -265,6 +272,75 @@ 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('  - ~/.claude/skills/headless-mode/ (Skill)');
+        console.log('  - ~/.wecom-aibot-mcp/version.json (版本记录)');
+        console.log('\n[mcp] 请重启 Claude Code 以加载最新配置');
+        process.exit(0);
+    }
+    // --reinstall 命令：删除所有全局配置（保留机器人配置）后重新安装
+    if (args.includes('--reinstall')) {
+        console.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 SKILL_DIR = path.join(os.homedir(), '.claude', 'skills', 'headless-mode');
+        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. 删除 skill 目录
+        if (fs.existsSync(SKILL_DIR)) {
+            fs.rmSync(SKILL_DIR, { recursive: true });
+            console.log('[mcp] 已删除 ~/.claude/skills/headless-mode/');
+        }
+        // 4. 删除版本文件
+        if (fs.existsSync(VERSION_FILE)) {
+            fs.unlinkSync(VERSION_FILE);
+            console.log('[mcp] 已删除 ~/.wecom-aibot-mcp/version.json');
+        }
+        // 5. 删除 hook 脚本
+        if (fs.existsSync(HOOK_SCRIPT)) {
+            fs.unlinkSync(HOOK_SCRIPT);
+            console.log('[mcp] 已删除 ~/.wecom-aibot-mcp/permission-hook.sh');
+        }
+        // 6. 重新安装全局配置
+        console.log('\n[mcp] 正在重新安装...');
+        ensureGlobalConfigs();
+        console.log('\n[mcp] ✅ 重新安装完成！');
+        console.log('[mcp] 请重启 Claude Code 以加载最新配置');
+        process.exit(0);
+    }
     if (args.includes('--status') || args.includes('--list')) {
         showStatus();
         process.exit(0);
@@ -302,7 +378,12 @@ async function main() {
     // --debug：前台启动，日志直接输出到终端
     if (args.includes('--debug')) {
         console.log('[mcp] Debug 模式：前台运行，Ctrl+C 退出');
+        // 写入 debug 标记文件，hook 脚本检测后日志输出到 stderr
+        const debugFile = path.join(os.homedir(), '.wecom-aibot-mcp', 'debug');
+        fs.writeFileSync(debugFile, 'true');
         await startMcpServerForeground();
+        // 退出时删除标记文件
+        fs.unlinkSync(debugFile);
         return;
     }
     // --start：后台启动

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 {};

package/dist/cc-registry.js

@@ -0,0 +1,278 @@
+/**
+ * ccId 注册表
+ *
+ * 管理 ~/.wecom-aibot-mcp/cc-registry.json
+ * 维护 ccId → { robotName, lastActive, createdAt } 的映射
+ *
+ * 文件锁通过 .lock 文件实现（EEXIST 原子性）
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { atomicWriteFileSync } from './utils/atomic-write.js';
+import { logWarn } from './connection-log.js';
+const WARNING_MS = 10 * 24 * 60 * 60 * 1000; // 10 天：过期前警告
+const EXPIRY_MS = 14 * 24 * 60 * 60 * 1000; // 14 天：清理
+// 心跳检测常量
+const OFFLINE_THRESHOLD = 10 * 60 * 1000; // 10 分钟无心跳视为离线
+const NOTIFICATION_INTERVAL = 30 * 60 * 1000; // 30 分钟最多通知一次
+// 支持测试环境覆盖
+let CONFIG_DIR = path.join(os.homedir(), '.wecom-aibot-mcp');
+let REGISTRY_FILE = path.join(CONFIG_DIR, 'cc-registry.json');
+let LOCK_FILE = path.join(CONFIG_DIR, 'cc-registry.lock');
+/**
+ * 设置配置目录（仅用于测试）
+ */
+export function setConfigDir(dir) {
+    CONFIG_DIR = dir;
+    REGISTRY_FILE = path.join(CONFIG_DIR, 'cc-registry.json');
+    LOCK_FILE = path.join(CONFIG_DIR, 'cc-registry.lock');
+}
+// ────────────────────────────────────────────
+// 文件锁（基于 EEXIST 原子性）
+// ────────────────────────────────────────────
+function acquireLock() {
+    try {
+        fs.openSync(LOCK_FILE, 'wx');
+        return true;
+    }
+    catch (e) {
+        if (e.code === 'EEXIST')
+            return false;
+        throw e;
+    }
+}
+function releaseLock() {
+    try {
+        fs.unlinkSync(LOCK_FILE);
+    }
+    catch { /* ignore */ }
+}
+function withLock(fn) {
+    const deadline = Date.now() + 3000;
+    while (!acquireLock()) {
+        if (Date.now() > deadline)
+            throw new Error('cc-registry: 获取锁超时');
+        // 自旋等待（锁持有时间极短）
+        const start = Date.now();
+        while (Date.now() - start < 50) { /* busy wait */ }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        releaseLock();
+    }
+}
+// ────────────────────────────────────────────
+// 注册表 I/O
+// ────────────────────────────────────────────
+function readRegistry() {
+    try {
+        return JSON.parse(fs.readFileSync(REGISTRY_FILE, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeRegistry(registry) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    atomicWriteFileSync(REGISTRY_FILE, JSON.stringify(registry, null, 2));
+}
+// ────────────────────────────────────────────
+// 过期清理
+// ────────────────────────────────────────────
+/**
+ * 内部清理：在已持锁的上下文中直接操作传入的 registry 对象。
+ * 不获取锁，调用方负责锁安全。
+ */
+function pruneExpired(registry) {
+    const now = Date.now();
+    let changed = false;
+    for (const [ccId, entry] of Object.entries(registry)) {
+        const inactive = now - entry.lastActive;
+        if (inactive > EXPIRY_MS) {
+            logWarn(`[cc-registry] 已清理过期 ccId "${ccId}" (robot: ${entry.robotName})，超过 14 天未活跃`);
+            delete registry[ccId];
+            changed = true;
+        }
+        else if (inactive > WARNING_MS) {
+            logWarn(`[cc-registry] 警告：ccId "${ccId}" (robot: ${entry.robotName}) 已 10 天未活跃，4 天后将自动清理`);
+        }
+    }
+    return changed;
+}
+/**
+ * 公开接口：独立调用时使用（内部会获取锁）
+ */
+export function cleanupExpiredEntries() {
+    withLock(() => {
+        const registry = readRegistry();
+        if (pruneExpired(registry))
+            writeRegistry(registry);
+    });
+}
+/**
+ * 注册 ccId
+ * - 新 ccId → registered
+ * - 已存在且 robotName 相同 → renewed（续期）
+ * - 已存在且 robotName 不同 → occupied（被占用）
+ */
+export function registerCcId(ccId, robotName) {
+    return withLock(() => {
+        const registry = readRegistry();
+        pruneExpired(registry); // 已在锁内，不二次获取
+        const existing = registry[ccId];
+        if (existing) {
+            if (existing.robotName === robotName) {
+                // 同 ccId + 同 robotName → 续期
+                existing.lastActive = Date.now();
+                writeRegistry(registry);
+                return 'renewed';
+            }
+            else {
+                return 'occupied';
+            }
+        }
+        registry[ccId] = {
+            robotName,
+            lastActive: Date.now(),
+            createdAt: Date.now(),
+        };
+        writeRegistry(registry);
+        return 'registered';
+    });
+}
+/**
+ * 注销 ccId
+ */
+export function unregisterCcId(ccId) {
+    withLock(() => {
+        const registry = readRegistry();
+        delete registry[ccId];
+        writeRegistry(registry);
+    });
+}
+/**
+ * 检查 ccId 是否已注册
+ */
+export function isCcIdRegistered(ccId) {
+    const registry = readRegistry();
+    return ccId in registry;
+}
+/**
+ * 更新 ccId 的最后活跃时间
+ */
+export function touchCcId(ccId) {
+    withLock(() => {
+        const registry = readRegistry();
+        if (registry[ccId]) {
+            registry[ccId].lastActive = Date.now();
+            writeRegistry(registry);
+        }
+    });
+}
+/**
+ * 获取 ccId 绑定的机器人名称
+ */
+export function getCcIdBinding(ccId) {
+    const registry = readRegistry();
+    const entry = registry[ccId];
+    if (!entry)
+        return null;
+    return { robotName: entry.robotName };
+}
+/**
+ * 获取完整注册表（调试用）
+ */
+export function getRegistry() {
+    return readRegistry();
+}
+// ────────────────────────────────────────────
+// 心跳检测
+// ────────────────────────────────────────────
+let heartbeatInterval = null;
+/**
+ * 检查 CC 心跳并发送离线通知
+ */
+async function checkCcHeartbeat() {
+    const registry = readRegistry();
+    const now = Date.now();
+    let changed = false;
+    for (const [ccId, entry] of Object.entries(registry)) {
+        const inactive = now - entry.lastActive;
+        if (inactive > OFFLINE_THRESHOLD) {
+            // 检查是否需要通知（避免重复）
+            const shouldNotify = !entry.lastNotified ||
+                (now - entry.lastNotified > NOTIFICATION_INTERVAL);
+            if (shouldNotify) {
+                await sendOfflineNotification(ccId, entry.robotName);
+                entry.lastNotified = now;
+                changed = true;
+            }
+        }
+    }
+    if (changed) {
+        withLock(() => {
+            const reg = readRegistry();
+            for (const [ccId, entry] of Object.entries(registry)) {
+                if (entry.lastNotified && reg[ccId]) {
+                    reg[ccId].lastNotified = entry.lastNotified;
+                }
+            }
+            writeRegistry(reg);
+        });
+    }
+}
+/**
+ * 发送离线通知到微信
+ */
+async function sendOfflineNotification(ccId, robotName) {
+    try {
+        // 动态导入避免循环依赖
+        const { getClient } = await import('./connection-manager.js');
+        const client = await getClient(robotName);
+        if (!client) {
+            console.log(`[heartbeat] 机器人 ${robotName} 未连接，无法发送离线通知`);
+            return;
+        }
+        const registryEntry = getRegistry()[ccId];
+        const inactiveMinutes = registryEntry ? Math.floor((Date.now() - registryEntry.lastActive) / 60000) : 0;
+        const message = `【系统警告】CC "${ccId}" 已超过 ${inactiveMinutes} 分钟无心跳，可能已离线。
+
+可能原因：
+• CC 进程已退出
+• 网络连接中断
+• CC 正在执行长时间任务
+
+建议：请检查终端状态或重新启动 CC。`;
+        await client.sendText(message);
+        console.log(`[heartbeat] 已发送离线通知: ccId=${ccId}, robot=${robotName}`);
+    }
+    catch (err) {
+        console.error(`[heartbeat] 发送离线通知失败:`, err);
+    }
+}
+/**
+ * 启动心跳检测（5 分钟扫描一次）
+ */
+export function startHeartbeatMonitor() {
+    if (heartbeatInterval)
+        return;
+    heartbeatInterval = setInterval(() => {
+        checkCcHeartbeat().catch(err => {
+            console.error('[heartbeat] 心跳检测错误:', err);
+        });
+    }, 5 * 60 * 1000);
+    console.log('[heartbeat] 心跳检测已启动（5 分钟周期）');
+}
+/**
+ * 停止心跳检测
+ */
+export function stopHeartbeatMonitor() {
+    if (heartbeatInterval) {
+        clearInterval(heartbeatInterval);
+        heartbeatInterval = null;
+        console.log('[heartbeat] 心跳检测已停止');
+    }
+}