cc-im 1.0.0

package/.env.example

@@ -0,0 +1,43 @@
+# 平台配置
+# 可以同时启用多个平台，只需配置对应的凭证即可
+# - 配置了 TELEGRAM_BOT_TOKEN 即启用 Telegram
+# - 配置了 FEISHU_APP_ID 和 FEISHU_APP_SECRET 即启用飞书
+# - 可以两者都配置，同时运行多个平台的 bot
+
+# 飞书应用凭证（启用飞书平台需要）
+# 需要在飞书开放平台为应用开通以下权限：
+#   - im:message:send_as_bot    以应用的身份发消息
+#   - im:message                获取与发送单聊、群组消息
+#   - im:message:patch_as_bot   更新应用发送的消息（权限卡片更新）
+#   - cardkit:card              创建与更新 CardKit 卡片（流式输出必需）
+FEISHU_APP_ID=your_app_id
+FEISHU_APP_SECRET=your_app_secret
+
+# Telegram Bot Token（启用 Telegram 平台需要，通过 @BotFather 获取）
+TELEGRAM_BOT_TOKEN=your_bot_token
+
+# 白名单用户 ID（逗号分隔，留空表示不限制）
+# 飞书: open_id 格式（如 ou_xxxx）
+# Telegram: 用户数字 ID（如 123456789）
+ALLOWED_USER_IDS=
+
+# Claude CLI 路径
+CLAUDE_CLI_PATH=claude
+
+# Claude Code 工作目录
+CLAUDE_WORK_DIR=.
+
+# 允许 /cd 切换的基础目录（逗号分隔，留空则限制在 CLAUDE_WORK_DIR 下）
+ALLOWED_BASE_DIRS=
+
+# 是否跳过 Claude CLI 权限检查（默认 false，生产环境建议保持 false）
+CLAUDE_SKIP_PERMISSIONS=false
+
+# Claude CLI 执行超时（毫秒，默认 300000 即5分钟）
+CLAUDE_TIMEOUT_MS=300000
+
+# 权限确认 Hook 服务端口（默认 18900，仅 CLAUDE_SKIP_PERMISSIONS=false 时使用）
+HOOK_SERVER_PORT=18900
+
+# 日志文件存储目录（默认 ~/.cc-im/logs）
+LOG_DIR=

package/README.md

@@ -0,0 +1,219 @@
+# cc-im
+
+多平台（飞书 & Telegram）机器人 ↔ Claude Code CLI 桥接服务。
+
+用户在飞书或 Telegram 中发消息，服务器接收后调用 Claude Code 执行，并将输出实时流式推送回聊天窗口。
+
+## 功能
+
+- **多平台支持**：飞书和 Telegram，可同时运行或单独使用
+- **流式输出**：飞书端使用 CardKit 打字机效果，Telegram 端通过 editMessage 实时更新
+- **会话管理**：每用户独立 session，支持 `/new` 重置
+- **并发控制**：同会话串行执行，不同会话可并发，最多排队 3 条消息
+- **长消息分片**：超长内容自动拆分为多条消息
+- **权限确认**：通过 Hook 机制实现工具调用的交互式审批
+- **白名单**：通过环境变量或配置文件控制访问
+- **停止按钮**：执行过程中可随时停止
+
+## 快速开始
+
+### 同时运行多个平台
+
+可以同时启用飞书和 Telegram，只需配置两个平台的凭证即可：
+
+```bash
+export FEISHU_APP_ID=your_app_id
+export FEISHU_APP_SECRET=your_app_secret
+export TELEGRAM_BOT_TOKEN=your_bot_token
+npx cc-im
+```
+
+服务会自动检测已配置的平台并启动对应的 bot。
+
+### Telegram 平台
+
+1. 通过 [@BotFather](https://t.me/BotFather) 创建 Bot，获取 Token
+2. 配置并启动：
+
+```bash
+# 方式一：环境变量
+export TELEGRAM_BOT_TOKEN=your_bot_token
+npx cc-im
+
+# 方式二：从源码运行
+pnpm install
+cp .env.example .env
+# 编辑 .env，填入 TELEGRAM_BOT_TOKEN
+pnpm dev
+```
+
+3. 在 Telegram 中找到你的 Bot，发送 `/start` 开始使用
+
+### 飞书平台
+
+1. 在[飞书开放平台](https://open.feishu.cn)创建应用
+2. 开启机器人能力
+3. 添加权限：`im:message`、`im:message:send_as_bot`、`im:message:patch_as_bot`、`cardkit:card`
+4. 事件订阅中启用 **长连接模式**，订阅以下事件：
+   - `im.message.receive_v1` — 接收消息
+   - `card.action.trigger` — 卡片交互（停止按钮）
+5. 发布应用
+6. 配置并启动：
+
+```bash
+export FEISHU_APP_ID=your_app_id
+export FEISHU_APP_SECRET=your_app_secret
+npx cc-im
+```
+
+### 从源码构建
+
+```bash
+git clone <repo-url>
+cd cc-im
+pnpm install
+cp .env.example .env
+# 编辑 .env 填入对应平台凭证
+
+pnpm dev      # 开发模式
+pnpm build    # 编译
+pnpm start    # 生产模式
+```
+
+## 命令列表
+
+| 命令 | 说明 |
+|------|------|
+| `/start` | 显示欢迎信息（Telegram） |
+| `/help` | 显示帮助信息 |
+| `/new` | 开始新会话 |
+| `/cd <path>` | 切换工作目录（同时重置会话） |
+| `/pwd` | 查看当前工作目录 |
+| `/list` | 列出所有项目的工作区 |
+| `/cost` | 查看 Claude API 用量和费用 |
+| `/status` | 查看当前会话状态 |
+| `/model [name]` | 查看或切换模型 |
+| `/doctor` | 运行 Claude 诊断 |
+| `/compact [topic]` | 压缩当前对话上下文 |
+| `/todos` | 查看待办事项 |
+
+### 权限相关命令
+
+当 `CLAUDE_SKIP_PERMISSIONS=false`（默认）时，Claude Code 执行敏感操作（如 Bash 命令、写文件）会弹出权限确认卡片：
+
+| 命令 | 说明 |
+|------|------|
+| `/allow` 或 `/y` | 允许当前待确认的操作 |
+| `/deny` 或 `/n` | 拒绝当前待确认的操作 |
+| `/allowall` | 允许所有待确认的操作 |
+| `/pending` | 查看当前待确认的操作列表 |
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `PLATFORM` | 平台选择（`telegram` 或 `feishu`），留空自动检测 | 自动检测 |
+| `FEISHU_APP_ID` | 飞书应用 App ID | 飞书平台必填 |
+| `FEISHU_APP_SECRET` | 飞书应用 App Secret | 飞书平台必填 |
+| `TELEGRAM_BOT_TOKEN` | Telegram Bot Token | Telegram 平台必填 |
+| `ALLOWED_USER_IDS` | 白名单用户 ID，逗号分隔，留空不限制 | 空（不限制） |
+| `CLAUDE_CLI_PATH` | Claude CLI 可执行文件路径 | `claude` |
+| `CLAUDE_WORK_DIR` | 默认工作目录 | 当前目录 |
+| `ALLOWED_BASE_DIRS` | 允许 `/cd` 切换的基础目录，逗号分隔 | 同 `CLAUDE_WORK_DIR` |
+| `CLAUDE_SKIP_PERMISSIONS` | 跳过权限检查（生产环境建议 `false`） | `false` |
+| `CLAUDE_TIMEOUT_MS` | 执行超时（毫秒） | `300000`（5分钟） |
+| `HOOK_SERVER_PORT` | 权限确认 Hook 服务端口 | `18900` |
+| `LOG_DIR` | 日志文件存储目录 | `~/.cc-im/logs` |
+
+### 白名单用户 ID 格式
+
+- **飞书**：open_id 格式，如 `ou_xxxx`
+- **Telegram**：用户数字 ID，如 `123456789`（可通过 [@userinfobot](https://t.me/userinfobot) 获取）
+
+## 配置文件
+
+除环境变量外，也支持通过 `~/.cc-im/config.json` 文件配置：
+
+```json
+{
+  "platform": "telegram",
+  "telegramBotToken": "your_bot_token",
+  "allowedUserIds": ["123456789"],
+  "claudeCliPath": "/usr/local/bin/claude",
+  "claudeWorkDir": "/home/user/projects",
+  "allowedBaseDirs": ["/home/user/projects", "/tmp"],
+  "claudeSkipPermissions": false,
+  "claudeTimeoutMs": 300000,
+  "logDir": "/var/log/cc-im"
+}
+```
+
+环境变量优先级高于配置文件。
+
+## 应用数据目录
+
+默认数据目录：`~/.cc-im`（常量 `APP_HOME`）
+
+```
+~/.cc-im/
+├── config.json          # 配置文件
+├── data/
+│   └── sessions.json    # 会话持久化数据
+└── logs/                # 日志文件（可通过 LOG_DIR 自定义）
+    ├── 2026-02-14.log
+    └── 2026-02-15.log
+```
+
+## 权限确认机制
+
+当 `CLAUDE_SKIP_PERMISSIONS=false` 时，系统会通过 PreToolUse Hook 拦截敏感操作：
+
+1. Claude Code 尝试调用工具（如执行 Bash 命令）
+2. Hook 脚本将请求发送到权限确认服务（端口由 `HOOK_SERVER_PORT` 指定）
+3. 服务向用户发送权限确认卡片/消息
+4. 用户回复 `/allow` 或 `/deny`
+5. 决定结果返回给 Claude Code，继续或中止操作
+
+以下只读工具会自动放行，无需确认：
+`Read`、`Glob`、`Grep`、`WebFetch`、`WebSearch`、`Task`、`TodoRead`
+
+## 项目结构
+
+```
+src/
+├── index.ts                  # 入口，多平台并行初始化
+├── config.ts                 # 配置加载（环境变量 + ~/.cc-im/config.json）
+├── constants.ts              # 系统常量（节流、长度限制、错误码等）
+├── logger.ts                 # 带标签的日志系统（自动脱敏）
+├── sanitize.ts               # 日志脱敏规则
+├── cli.ts                    # CLI 入口
+├── access/
+│   └── access-control.ts     # 白名单访问控制
+├── claude/
+│   ├── cli-runner.ts         # Claude CLI 子进程管理
+│   ├── stream-parser.ts      # stream-json 格式解析
+│   └── types.ts              # Claude 消息类型定义
+├── commands/
+│   └── handler.ts            # 平台无关的命令处理器
+├── feishu/
+│   ├── client.ts             # 飞书 SDK 初始化
+│   ├── event-handler.ts      # 飞书事件处理
+│   ├── message-sender.ts     # 飞书消息发送封装
+│   ├── card-builder.ts       # 飞书卡片构建（JSON 1.0 + 2.0）
+│   └── cardkit-manager.ts    # CardKit 卡片生命周期管理
+├── telegram/
+│   ├── client.ts             # Telegraf 初始化
+│   ├── event-handler.ts      # Telegram 事件处理
+│   └── message-sender.ts     # Telegram 消息发送
+├── hook/
+│   ├── permission-server.ts  # 权限确认 HTTP 服务
+│   └── hook-script.ts        # Claude Code PreToolUse Hook
+├── session/
+│   └── session-manager.ts    # 会话管理（持久化到 data/sessions.json）
+└── queue/
+    └── request-queue.ts      # 请求队列与并发控制
+```
+
+## License
+
+MIT

package/dist/access/access-control.js

@@ -0,0 +1,12 @@
+export class AccessControl {
+    allowedUserIds;
+    constructor(allowedUserIds) {
+        this.allowedUserIds = new Set(allowedUserIds);
+    }
+    isAllowed(userId) {
+        // Empty whitelist = allow all (dev mode)
+        if (this.allowedUserIds.size === 0)
+            return true;
+        return this.allowedUserIds.has(userId);
+    }
+}

package/dist/claude/cli-runner.js

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { parseStreamLine, extractTextDelta, extractThinkingDelta, extractResult } from './stream-parser.js';
+import { isStreamInit, isContentBlockStart, isContentBlockDelta, isContentBlockStop } from './types.js';
+export function runClaude(cliPath, prompt, sessionId, workDir, callbacks, options) {
+    const args = [
+        '-p',
+        '--output-format', 'stream-json',
+        '--verbose',
+        '--include-partial-messages',
+    ];
+    if (options?.skipPermissions) {
+        args.push('--dangerously-skip-permissions');
+    }
+    if (options?.model) {
+        args.push('--model', options.model);
+    }
+    if (sessionId) {
+        args.push('--resume', sessionId);
+    }
+    args.push('--', prompt);
+    const env = { ...process.env };
+    if (options?.chatId) {
+        env.CC_BOT_CHAT_ID = options.chatId;
+    }
+    if (options?.hookPort) {
+        env.CC_BOT_HOOK_PORT = String(options.hookPort);
+    }
+    if (options?.threadRootMsgId) {
+        env.CC_BOT_THREAD_ROOT_MSG_ID = options.threadRootMsgId;
+    }
+    if (options?.threadId) {
+        env.CC_BOT_THREAD_ID = options.threadId;
+    }
+    if (options?.platform) {
+        env.CC_BOT_PLATFORM = options.platform;
+    }
+    const child = spawn(cliPath, args, {
+        cwd: workDir,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env,
+    });
+    let accumulated = '';
+    let accumulatedThinking = '';
+    let completed = false;
+    let model = '';
+    let toolStats = {};
+    let timeoutHandle = null;
+    const pendingToolInputs = new Map();
+    // 设置超时
+    if (options?.timeoutMs && options.timeoutMs > 0) {
+        timeoutHandle = setTimeout(() => {
+            if (!completed && !child.killed) {
+                child.kill('SIGTERM');
+                callbacks.onError(`执行超时（${options.timeoutMs}ms），已终止进程`);
+            }
+        }, options.timeoutMs);
+    }
+    const rl = createInterface({ input: child.stdout });
+    rl.on('line', (line) => {
+        const event = parseStreamLine(line);
+        if (!event)
+            return;
+        if (isStreamInit(event)) {
+            model = event.model;
+            callbacks.onSessionId?.(event.session_id);
+        }
+        const delta = extractTextDelta(event);
+        if (delta) {
+            accumulated += delta.text;
+            callbacks.onText(accumulated);
+            return;
+        }
+        const thinking = extractThinkingDelta(event);
+        if (thinking) {
+            accumulatedThinking += thinking.text;
+            callbacks.onThinking?.(accumulatedThinking);
+            return;
+        }
+        if (isContentBlockStart(event) && event.event.content_block.type === 'tool_use') {
+            const { name } = event.event.content_block;
+            if (name)
+                pendingToolInputs.set(event.event.index, { name, json: '' });
+            return;
+        }
+        if (isContentBlockDelta(event) && event.event.delta.type === 'input_json_delta') {
+            const pending = pendingToolInputs.get(event.event.index);
+            if (pending)
+                pending.json += event.event.delta.partial_json ?? '';
+            return;
+        }
+        if (isContentBlockStop(event)) {
+            const pending = pendingToolInputs.get(event.event.index);
+            if (pending) {
+                toolStats[pending.name] = (toolStats[pending.name] || 0) + 1;
+                let input;
+                try {
+                    input = JSON.parse(pending.json);
+                }
+                catch { /* empty input */ }
+                callbacks.onToolUse?.(pending.name, input);
+                pendingToolInputs.delete(event.event.index);
+            }
+            return;
+        }
+        const result = extractResult(event);
+        if (result) {
+            completed = true;
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+            result.accumulated = accumulated;
+            result.model = model;
+            result.toolStats = toolStats;
+            if (!accumulated && result.result) {
+                accumulated = result.result;
+            }
+            callbacks.onComplete(result);
+        }
+    });
+    // 保留首部和尾部的 stderr，避免丢失关键错误信息
+    const MAX_HEAD_LEN = 4 * 1024; // 保留前 4KB
+    const MAX_TAIL_LEN = 6 * 1024; // 保留后 6KB
+    let stderrHead = '';
+    let stderrTail = '';
+    let stderrTotal = 0;
+    let headFull = false;
+    child.stderr?.on('data', (chunk) => {
+        const text = chunk.toString();
+        stderrTotal += text.length;
+        if (!headFull) {
+            const headRoom = MAX_HEAD_LEN - stderrHead.length;
+            if (headRoom > 0) {
+                stderrHead += text.slice(0, headRoom);
+                if (stderrHead.length >= MAX_HEAD_LEN) {
+                    headFull = true;
+                }
+            }
+        }
+        stderrTail += text;
+        if (stderrTail.length > MAX_TAIL_LEN) {
+            stderrTail = stderrTail.slice(-MAX_TAIL_LEN);
+        }
+    });
+    let exitCode = null;
+    let rlClosed = false;
+    let childClosed = false;
+    const finalize = () => {
+        if (!rlClosed || !childClosed)
+            return;
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+        if (!completed) {
+            if (exitCode !== null && exitCode !== 0) {
+                // 组合首尾 stderr 信息
+                let stderrData = '';
+                if (stderrTotal <= MAX_HEAD_LEN + MAX_TAIL_LEN) {
+                    // 内容未超限，直接使用
+                    stderrData = stderrHead + (headFull ? stderrTail : '');
+                }
+                else {
+                    // 内容超限，显示首尾部分
+                    stderrData = stderrHead + `\n\n... (省略 ${stderrTotal - MAX_HEAD_LEN - MAX_TAIL_LEN} 字节) ...\n\n` + stderrTail;
+                }
+                callbacks.onError(stderrData || `Claude CLI exited with code ${exitCode}`);
+            }
+            else {
+                // Completed without a result event — treat accumulated text as result
+                callbacks.onComplete({
+                    success: true,
+                    result: accumulated,
+                    accumulated,
+                    cost: 0,
+                    durationMs: 0,
+                    model,
+                    numTurns: 0,
+                    toolStats,
+                });
+            }
+        }
+    };
+    child.on('close', (code) => {
+        exitCode = code;
+        childClosed = true;
+        finalize();
+    });
+    // 使用 rl 的 close 事件而非 child 的 close，确保所有行都处理完毕
+    rl.on('close', () => {
+        rlClosed = true;
+        finalize();
+    });
+    child.on('error', (err) => {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+        if (!completed) {
+            callbacks.onError(`Failed to start Claude CLI: ${err.message}`);
+        }
+        // spawn 失败时可能不触发 close 事件，手动标记以确保 finalize 执行
+        childClosed = true;
+        finalize();
+    });
+    return {
+        process: child,
+        abort: () => {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+            if (!child.killed) {
+                child.kill('SIGTERM');
+            }
+        },
+    };
+}

package/dist/claude/stream-parser.js

@@ -0,0 +1,42 @@
+import { isContentBlockDelta, isStreamResult } from './types.js';
+export function parseStreamLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed === 'object' && parsed !== null && 'type' in parsed) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function extractTextDelta(event) {
+    if (isContentBlockDelta(event) && event.event.delta?.type === 'text_delta' && event.event.delta.text) {
+        return { text: event.event.delta.text };
+    }
+    return null;
+}
+export function extractThinkingDelta(event) {
+    if (isContentBlockDelta(event) && event.event.delta?.type === 'thinking_delta' && event.event.delta.thinking) {
+        return { text: event.event.delta.thinking };
+    }
+    return null;
+}
+export function extractResult(event) {
+    if (isStreamResult(event)) {
+        return {
+            success: event.subtype === 'success',
+            result: event.result,
+            accumulated: '',
+            cost: event.total_cost_usd,
+            durationMs: event.duration_ms,
+            numTurns: event.num_turns,
+            toolStats: {},
+        };
+    }
+    return null;
+}

package/dist/claude/types.js

@@ -0,0 +1,30 @@
+export function isStreamInit(event) {
+    return event.type === 'system' && 'subtype' in event && event.subtype === 'init';
+}
+export function isContentBlockDelta(event) {
+    return (event.type === 'stream_event' &&
+        'event' in event &&
+        typeof event.event === 'object' &&
+        event.event !== null &&
+        'type' in event.event &&
+        event.event.type === 'content_block_delta');
+}
+export function isStreamResult(event) {
+    return event.type === 'result' && 'subtype' in event;
+}
+export function isContentBlockStart(event) {
+    return (event.type === 'stream_event' &&
+        'event' in event &&
+        typeof event.event === 'object' &&
+        event.event !== null &&
+        'type' in event.event &&
+        event.event.type === 'content_block_start');
+}
+export function isContentBlockStop(event) {
+    return (event.type === 'stream_event' &&
+        'event' in event &&
+        typeof event.event === 'object' &&
+        event.event !== null &&
+        'type' in event.event &&
+        event.event.type === 'content_block_stop');
+}

package/dist/cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { join } from 'path';
+import { existsSync, writeFileSync, unlinkSync, mkdirSync, readFileSync, openSync, closeSync } from 'fs';
+import { createLogger } from './logger.js';
+import { APP_HOME } from './constants.js';
+const PID_FILE = join(APP_HOME, 'pid');
+const logger = createLogger('CLI');
+function getPidFromFile() {
+    if (existsSync(PID_FILE)) {
+        try {
+            return parseInt(readFileSync(PID_FILE, 'utf-8'), 10);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function isRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function stop() {
+    const pid = getPidFromFile();
+    if (pid && isRunning(pid)) {
+        try {
+            process.kill(pid);
+            logger.info(`已停止服务 (PID: ${pid})`);
+        }
+        catch (e) {
+            const error = e;
+            logger.error('停止失败:', error.message);
+            process.exit(1);
+        }
+    }
+    else {
+        logger.info('服务未运行');
+    }
+    if (existsSync(PID_FILE)) {
+        unlinkSync(PID_FILE);
+    }
+}
+async function start() {
+    // 先检查旧的 PID 文件
+    const oldPid = getPidFromFile();
+    if (oldPid && isRunning(oldPid)) {
+        logger.info(`服务已在运行中 (PID: ${oldPid})`);
+        logger.info(`请先运行: cc-im stop`);
+        process.exit(1);
+    }
+    // 清理失效的 PID 文件
+    if (oldPid && !isRunning(oldPid) && existsSync(PID_FILE)) {
+        unlinkSync(PID_FILE);
+    }
+    if (!existsSync(APP_HOME)) {
+        mkdirSync(APP_HOME, { recursive: true });
+    }
+    // 使用 exclusive 模式写入 PID 文件，防止竞态条件
+    let fd = null;
+    try {
+        // 'wx' 模式：如果文件存在会抛出错误，原子操作
+        fd = openSync(PID_FILE, 'wx');
+        writeFileSync(fd, String(process.pid));
+        closeSync(fd);
+        fd = null;
+    }
+    catch (err) {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch { }
+        }
+        const error = err;
+        if (error.code === 'EEXIST') {
+            logger.error('服务正在启动中或 PID 文件被锁定，请稍后再试');
+            process.exit(1);
+        }
+        throw err;
+    }
+    try {
+        const { main } = await import('./index.js');
+        await main();
+    }
+    finally {
+        if (existsSync(PID_FILE)) {
+            unlinkSync(PID_FILE);
+        }
+    }
+}
+const command = process.argv[2];
+if (command === 'stop') {
+    await stop();
+}
+else {
+    await start();
+}