mirror of https://github.com/NanmiCoder/cc-haha synced 2026-07-16 13:03:31 +08:00

程序员阿江(Relakkes) f2fa6fc56d chore: gitignore .claude and docs/superpowers, clean up temp files

Remove .claude/ and docs/superpowers/ from git tracking as they are
local-only config and planning files. Also remove stale screenshots
and update docs/channel content.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-09 00:50:43 +08:00

4.8 KiB

Raw Permalink Blame History

IM 接入

当前可用的 IM 接入方案总览。
如果你只是想把 Telegram 或飞书接进来，从这篇开始。

当前方案是什么

当前仓库里的 IM 接入，已经不是早期文档里设想的 “IM Gateway / MCP Channel 插件” 主路径。

现在真实在跑的是一条更轻的链路：

flowchart TD
    A["Desktop Webapp<br/>Settings -> IM 接入"] --> B["GET / PUT /api/adapters"]
    B --> C["Desktop Server<br/>配置接口"]
    C --> D["本地配置持久化"]
    D --> E["~/.claude/adapters.json"]

    E --> F["Telegram / 飞书 Adapter 进程"]
    F --> G["加载平台配置"]
    F --> H["校验配对与授权"]
    F --> I["读取 / 写入会话映射"]
    I --> J["~/.claude/adapter-sessions.json"]

    F --> K{"当前 chatId<br/>是否已有 session?"}
    K -->|有历史映射| L["复用已有 sessionId"]
    K -->|无历史映射| M{"是否配置<br/>defaultProjectDir?"}
    M -->|是| N["POST /api/sessions<br/>创建新 session"]
    M -->|否| O["GET /api/sessions/recent-projects<br/>让用户选择项目"]
    O --> P["用户回复编号"]
    P --> N

    N --> Q["获得 sessionId"]
    L --> R["连接 /ws/:sessionId"]
    Q --> R

    R --> S["adapters/common/ws-bridge.ts"]
    S --> T["Desktop Server"]
    T --> U["Claude Code session / CLI 子进程"]

    U --> V["流式消息 / 权限请求 / 状态事件"]
    V --> S
    S --> F
    F --> W["Telegram / 飞书用户"]

可以把这条链路理解成四层：

配置层：桌面端 webapp 负责填写平台凭据、默认项目和配对码管理
存储层：本地服务端把配置写入 ~/.claude/adapters.json
适配层：Telegram / 飞书 adapter 进程负责接 IM 平台、做授权检查、恢复或创建会话
会话层：adapter 通过 HTTP 创建 session，再通过 WebSocket 把 IM 消息桥接到 Claude Code 会话

用户怎么用

1. 在 Desktop Webapp 里配置

打开桌面端设置页的 IM 接入 标签，填写：

serverUrl
defaultProjectDir
Telegram 或飞书各自的凭据
可选 allowedUsers

这里的配置会通过 GET /api/adapters 和 PUT /api/adapters 读写到 ~/.claude/adapters.json。

2. 生成配对码

配对也在同一个设置页完成：

点击“生成配对码”
前端生成 6 位码并写入 pairing.code / expiresAt / createdAt
码有效期 60 分钟
配对成功后立即失效

配对码是平台无关的，同一个码可以在 Telegram 或飞书私聊里使用一次。

3. 启动对应 Adapter 进程

Webapp 负责配置和配对，不负责代你启动 bot 进程。当前仍需要手动启动：

cd adapters
bun install
bun run telegram
# 或
bun run feishu

4. 在 IM 里私聊 Bot

未配对用户：先把配对码发给 bot
已配对用户：直接发送自然语言消息
没有默认项目时：bot 会先让你从最近项目里选一个
后续消息会复用同一个 Claude session

配置和状态分别存哪

`~/.claude/adapters.json`

保存平台配置和授权状态，包括：

serverUrl
defaultProjectDir
pairing
telegram
feishu

其中：

敏感字段会在 API 返回时被脱敏
配对码也会被 /api/adapters 返回值掩码为 ******

`~/.claude/adapter-sessions.json`

保存 IM chat 到 Claude session 的映射：

chatId
sessionId
workDir
updatedAt

这让 bot 重启后仍然能接回原来的会话。

当前安全模型

授权规则是：

allowedUsers 和 pairedUsers 取并集
两者都为空时，默认拒绝访问
配对码为 6 位安全字符集
配对码一次性使用
同一用户 5 分钟内最多失败 5 次

这和旧 README 里“allowedUsers 为空就允许所有人”的说法已经不同，旧说法已过时。

会话行为

Adapter 不是直接把消息丢给一个全局 Claude 进程，而是：

先用 POST /api/sessions 创建 session
再用 ws://.../ws/:sessionId 建立桥接
把 IM 消息转成：
- user_message
- permission_response
- stop_generation
把服务端流式消息再格式化回 IM

如果没有 defaultProjectDir，Adapter 会调用 GET /api/sessions/recent-projects 让用户先选项目。

平台差异

Telegram：grammy，按钮审批，纯私聊模式
飞书：@larksuiteoapi/node-sdk，长连接事件订阅，交互卡片审批，当前只处理 p2p

分别看：

和 `docs/channel/` 的关系

docs/channel/ 主要是 Claude Code 原生 Channel/MCP 体系的源码研究资料，不是这个仓库当前推荐的 IM 接入方式。

如果你是要“把 bot 真跑起来”，看本目录。
如果你是要研究 Claude Code 原始 Channel 设计，再去看 docs/channel/。

4.8 KiB Raw Permalink Blame History Unescape Escape