# Claude Code Feishu Channel

飞书 (Feishu/Lark) channel plugin for [Claude Code](https://claude.ai/code) — 将飞书消息实时推送到 Claude Code session，Claude 可以直接在飞书中回复（支持纯文本 / markdown / 图片 / 文件 / 视频 / 互动卡片 等所有飞书消息类型）。

## 架构 (v2.0 — lark-cli wrapper)

```
飞书 long-conn   ↓ NDJSON events
       lark-cli event consume im.message.receive_v1
                          ↓ pipe stdout (1 line/event)
                  index.mjs (thin MCP wrapper)
                          ↓ MCP channel notification
                  Claude Code session
                          ↓ feishu_reply / feishu_reply_markdown / feishu_send_markdown
                  lark-cli im +messages-reply / +messages-send
                          ↓ Feishu IM v1 API
                       飞书
```

**为什么 v2.0 重构**：v1 自己实现了 17+ 种消息类型的转化器（fork 自 [larksuite/openclaw-lark](https://github.com/larksuite/openclaw-lark)），但 lark-cli 已经把消息转化 + 长连接 + send/reply 全包了，本插件不需要自己维护这些代码。重构后：

- ✅ 代码量：~580 行 → ~200 行（thin wrapper）
- ✅ 维护：不再追 openclaw / lark SDK 升级；跟着 lark-cli 走
- ✅ 凭证安全：用 lark-cli config（**macOS Keychain**），不再 `.env` 明文
- ✅ 消息类型：跟 lark-cli 一致（text / markdown / post / image / file / video / audio / sticker / interactive card / share_chat / share_user / location / system / hongbao / calendar / video_chat / todo / vote 等）
- ✅ markdown auto-render：lark-cli 自动把 markdown 转 Feishu post 格式（粗体 / 列表 / code block / 图片 URL 内联）

## 前置依赖

1. **lark-cli**（这个插件的核心依赖）
   ```bash
   npm install -g @larksuite/cli
   ```
   或从 https://github.com/larksuite/cli/releases 拉 binary。装完跑 `lark-cli --version` verify。

2. **lark-cli 配置 Feishu 应用**
   ```bash
   lark-cli config init --new
   ```
   交互流程会：
   - 在 https://open.feishu.cn/app 创建一个自建应用
   - 把 App Secret 存到 macOS Keychain（不是明文 .env）
   - 把 App ID + identity 存到 `~/.lark-cli/config.json`

3. **飞书开发者后台**为该应用启用：
   - **事件与回调 → 订阅方式**：长连接
   - **添加事件**：`im.message.receive_v1`
   - **权限管理**：`im:message` + `im:message:send_as_bot`

## 安装

### 一键安装（推荐）

```bash
# 克隆到本地工作目录（install.sh 会建 symlink 到 ~/.claude/channels/feishu）
git clone <repo-url> ~/Desktop/code/claude-code-feishu-channel
cd ~/Desktop/code/claude-code-feishu-channel

# 一键脚本：lark-cli 检查 + npm install + symlink + 注册 MCP + 配权限
./install.sh
```

`install.sh` 自动做的事：

1. 检查 `lark-cli` 已装且 `lark-cli config` 已初始化
2. `npm install` 装 `@modelcontextprotocol/sdk`（唯一依赖）
3. 建 symlink `~/.claude/channels/feishu` → 你的工作目录（改 repo 自动同步）
4. 在 `~/.claude.json` 注册 `feishu` MCP server
5. 在 `~/.claude/settings.json` 加 `mcp__feishu__feishu_reply` / `feishu_reply_markdown` / `feishu_send_markdown` 到 `permissions.allow`（飞书收到消息 = 想要回复，每次问没必要）

脚本幂等，重跑不会重复或覆盖（两个 JSON 文件改前都备份）。

### 手动安装

```bash
brew install lark-cli && lark-cli config init --new

git clone <repo-url> ~/Desktop/code/claude-code-feishu-channel
cd ~/Desktop/code/claude-code-feishu-channel
npm install
ln -s "$(pwd)" ~/.claude/channels/feishu
# 然后看 install.sh 第 4 + 5 步手动改 ~/.claude.json + ~/.claude/settings.json
```

## 启动

```bash
claude --dangerously-load-development-channels server:feishu
```

启动后在飞书里给你的 bot 发消息 — 推到 CC session。Claude 用 `feishu_reply` / `feishu_reply_markdown` 工具回复。

## 工具

| 工具 | 说明 | 内部命令 |
|---|---|---|
| `feishu_reply` | 纯文本回复指定消息 | `lark-cli im +messages-reply --text` |
| `feishu_reply_markdown` | markdown 富文本回复（自动转 Feishu post） | `lark-cli im +messages-reply --markdown` |
| `feishu_send_markdown` | 主动发新消息到 chat（不是 reply） | `lark-cli im +messages-send --markdown` |
| `feishu_allowlist` | 管理发送者白名单 (list/add/remove) | 本地文件 |
| `feishu_pair` | 通过配对码授权 un-allowlisted 用户 | 本地文件 |

## 消息类型

接收端：lark-cli 已自动渲染所有飞书消息类型为 human-readable text。详见 `lark-cli event schema im.message.receive_v1`。

发送端：lark-cli 支持 text / markdown / post / image / file / audio / video / interactive / share_chat / share_user 等。本插件目前只暴露 text + markdown 两个工具（覆盖 99% chat 场景）；如需 image / file / interactive 等，扩展 `index.mjs` 加新工具即可（依然是 spawn lark-cli 一行）。

## Debug

```bash
tail -f ~/.claude/channels/feishu/debug.log
```

## License

MIT