cc-haha/adapters/README.md

Claude Code IM Adapters

通过 Telegram / 飞书与 Claude Code Desktop 对话。

每个 Adapter 是一个轻量独立脚本，直连 Desktop 服务端的 WebSocket 接口，与桌面 UI 走完全相同的协议。

架构

Telegram / 飞书
      ↕ (各平台 SDK)
IM Adapter (独立脚本)
      ↕ ws://localhost:3456/ws/{sessionId}
Claude Code Desktop 服务端 (已有，零改动)
      ↕
CLI 子进程 (Claude Code Agent)

前置条件

• Claude Code Desktop 已运行（服务端默认在 localhost:3456）
• Bun 运行时 >= 1.0

安装

cd adapters
bun install

---

Telegram

1. 创建 Bot

1. 在 Telegram 中找到 @BotFather
2. 发送 /newbot，按提示创建
3. 获取 Bot Token（格式：123456:ABC-DEF...）

2. 配置

方式一：环境变量（推荐）

export TELEGRAM_BOT_TOKEN="你的Bot Token"

方式二：配置文件

编辑 ~/.claude/adapters.json：

{
  "telegram": {
    "botToken": "你的Bot Token",
    "allowedUsers": [],
    "defaultWorkDir": "/path/to/your/project"
  }
}

• allowedUsers：Telegram User ID 白名单。留空 [] 允许所有人（适合个人使用）
• defaultWorkDir：Claude Code 的工作目录

3. 启动

cd adapters
bun run telegram

4. 使用

在 Telegram 中找到你的 Bot，直接发消息即可。

命令：

命令	说明
/start	显示帮助信息
/new	新建会话（重置上下文）
/stop	停止当前生成

权限审批： 当 Claude 需要执行敏感操作（如运行终端命令、写文件），Bot 会发送带按钮的消息，点击 允许 或 拒绝 即可。

---

飞书 (Feishu)

1. 创建应用

1. 打开 飞书开放平台
2. 创建「企业自建应用」
3. 记下 App ID 和 App Secret

2. 配置应用权限

在应用后台「权限管理」中开启：

• im:message — 获取与发送消息
• im:message:send_as_bot — 以机器人身份发送消息
• im:resource — 获取消息中的资源文件

3. 配置事件订阅

在应用后台「事件订阅」中：

1. 选择「使用长连接接收事件」(WebSocket 模式，无需公网地址)
2. 添加事件：
   • im.message.receive_v1 — 接收消息
   • card.action.trigger — 卡片按钮点击回调

4. 配置 Adapter

方式一：环境变量（推荐）

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="你的App Secret"

方式二：配置文件

编辑 ~/.claude/adapters.json：

{
  "feishu": {
    "appId": "cli_xxx",
    "appSecret": "你的App Secret",
    "allowedUsers": [],
    "defaultWorkDir": "/path/to/your/project",
    "streamingCard": false
  }
}

• allowedUsers：飞书 Open ID 白名单。留空 [] 允许所有人
• streamingCard：启用流式卡片模式（实时更新消息内容，体验更好）

5. 发布应用

在应用后台「版本管理与发布」中创建版本并发布（至少发布到「开发中」状态，机器人才能收发消息）。

6. 启动

cd adapters
bun run feishu

7. 使用

• 私聊：直接给机器人发消息
• 群聊：需要 @机器人
• 新会话：发送 /new 或 新会话
• 停止：发送 /stop 或 停止

权限审批： 当 Claude 需要执行敏感操作，Bot 会发送交互式卡片，点击 允许 或 拒绝 按钮。

---

配置文件完整示例

~/.claude/adapters.json：

{
  "serverUrl": "ws://127.0.0.1:3456",
  "telegram": {
    "botToken": "123456:ABC-DEF...",
    "allowedUsers": [123456789, 987654321],
    "defaultWorkDir": "/Users/me/workspace/my-project"
  },
  "feishu": {
    "appId": "cli_xxx",
    "appSecret": "xxx",
    "encryptKey": "",
    "verificationToken": "",
    "allowedUsers": ["ou_xxx"],
    "defaultWorkDir": "/Users/me/workspace/my-project",
    "streamingCard": false
  }
}

环境变量优先级高于配置文件。

---

常见问题

连不上服务器

[WsBridge] Error on tg-xxx: connect ECONNREFUSED 127.0.0.1:3456

原因：Claude Code Desktop 没有运行。启动 Desktop App 后再启动 Adapter。

Telegram Bot 无响应

1. 检查 Bot Token 是否正确
2. 检查 Bot 是否被 Telegram 封禁（找 @BotFather 查看状态）
3. 如果配置了 allowedUsers，确认你的 User ID 在列表中

获取你的 Telegram User ID：给 @userinfobot 发条消息。

飞书收不到消息

1. 检查 App ID / App Secret 是否正确
2. 检查应用是否已发布
3. 检查事件订阅是否配置了 im.message.receive_v1
4. 检查应用权限是否已开启 im:message
5. 群聊中确认已 @机器人

权限按钮不响应

• Telegram：可能是 callback_data 格式问题，查看 Adapter 日志
• 飞书：检查事件订阅是否配置了 card.action.trigger

---

开发

运行测试

cd adapters
bun test              # 全部测试
bun test common/      # 公共模块测试
bun test telegram/    # Telegram 测试
bun test feishu/      # 飞书测试

目录结构

adapters/
├── common/                 # 公共模块
│   ├── ws-bridge.ts        # WebSocket 桥接
│   ├── message-buffer.ts   # 流式消息缓冲
│   ├── message-dedup.ts    # 消息去重
│   ├── chat-queue.ts       # 会话串行队列
│   ├── format.ts           # 消息格式化
│   ├── config.ts           # 配置加载
│   └── __tests__/          # 公共模块测试
├── telegram/
│   ├── index.ts            # Telegram Adapter 入口
│   └── __tests__/          # Telegram 测试
├── feishu/
│   ├── index.ts            # 飞书 Adapter 入口
│   └── __tests__/          # 飞书测试
├── package.json
├── tsconfig.json
└── README.md