内容
# 飞书-克劳德个人助理
[](https://github.com/Songokou1983/feishu-claude-pal/actions/workflows/test.yml)
[](https://github.com/Songokou1983/feishu-claude-pal/releases)
[](./LICENSE)
> 您的个人AI助理，居住在飞书（Lark）中，由克劳德代码CLI驱动。
从 [PI-33/feishu-claude-bridge](https://github.com/PI-33/feishu-claude-bridge) 分叉，专注于 **个人助理使用场景** —— 更少的平台，更多的内存，更多的“了解您”。
## 为什么存在这个分叉
大多数克劳德 + 即时通讯桥梁（例如 [lark-coding-agent-bridge](https://github.com/zarazhangrui/lark-coding-agent-bridge)，[cc-connect](https://github.com/chenhg5/cc-connect)）都是作为 **通用工具** 构建的 —— 多平台，多代理，多用户。
这个分叉则相反：**一个用户，一个平台，与克劳德代码CLI深度集成**。我们的赌注是，个人助理应该 *了解* 其用户，而不仅仅是 *服务* 他们。
### 有什么不同
| 功能 | 这个分叉 | 典型桥梁 |
|---|---|---|
| 仅限飞书（Lark） | ✅ | 多IM |
| 仅限克劳德代码CLI | ✅ | 多代理 |
| **私有内存** （桥接到 `~/.claude/CLAUDE.md`） | ✅ | ❌ |
| **飞书-MCP** （让克劳德调用飞书API：文档，驱动） | ✅ | ❌ |
| 多模型（克劳德 + minimax + GLM-5.1） | ✅ | 仅克劳德 |
| systemd服务（Linux），launchd（macOS） | ✅ | ✅ |
## 快速开始（5分钟）
### 1. 安装
```bash
git clone https://github.com/Songokou1983/feishu-claude-pal.git
cd feishu-claude-pal
npm install
npm run build
```
### 2. 创建飞书应用
1. 前往 [飞书开放平台](https://open.feishu.cn/app) 并创建一个新的企业自建应用
2. 启用 **机器人** 功能
3. 订阅事件 `im.message.receive_v1` （WebSocket — 无需公网IP）
4. 添加 `CLAUDE.md` 中列出的作用域 § “飞书-MCP”
5. 发布版本并由管理员审批
### 3. 配置
```bash
cp config.env.example config.env
# 编辑 config.env 以设置您的 CTI_FEISHU_APP_ID、CTI_FEISHU_APP_SECRET 和 CTI_DEFAULT_WORKDIR
```
### 4. 安装 systemd 服务（Linux）
```bash
# 编辑 .config/systemd/user/feishu-bridge.service 以匹配您的安装路径
systemctl --user daemon-reload
systemctl --user enable feishu-bridge.service
systemctl --user start feishu-bridge.service
journalctl --user -u feishu-bridge.service -f
```
### 4b. Docker（替代方案）
```bash
# 构建镜像
docker compose build
# 编辑 config.env 以设置您的飞书应用凭证
cp config.env.example config.env
$EDITOR config.env
# 启动守护进程
docker compose up -d
# 日志
docker compose logs -f
# 健康检查
curl http://localhost:18888/health
# 停止
docker compose down
```
`docker-compose.yml` 挂载：
- `config.env` （只读）用于凭证
- `bridge-data` 命名卷用于 `.bridge/` 运行时数据（会话，绑定）
- 暴露端口 18888 到本地主机仅用于健康检查端点
注意：`/remember` 会写入 `~/.claude/CLAUDE.md` —— Docker 用户需要挂载 `~/.claude/` （在 `docker-compose.yml` 中注释）以在主机上持久化内存。
### 5. 与您的机器人对话
在飞书中向机器人发送任意消息。您将获得带有回复的流式卡片。
## 命令
| 命令 | 执行操作 |
|---|---|
| `/help` | 显示所有命令 |
| `/status` | 当前会话状态（模型，CWD，SDK会话ID） |
| `/list` | 发现本地CLI会话 |
| `/resume <id>` | 恢复CLI会话 |
| `/new [path]` | 启动新会话 |
| `/cwd /path` | 更改工作目录 |
| `/mode plan\|code\|ask` | 切换克劳德权限模式 |
| `/tree [depth] [path]` | 显示项目文件树 |
| `/diff [--staged]` | 显示git差异 |
| `/models` | 列出可用模型提供商 |
| `/cost` | 显示当前会话的令牌使用情况 |
| `/remember <key> <value>` | 持久化内存（桥接到 `~/.claude/CLAUDE.md`） |
| `/recall [key]` | 查看内存或单个键 |
| `/forget <key>` | 删除内存 |
| `/memories` | 列出桥接管理的内存 |
| `/stop` | 停止当前任务 |
| `/perm allow\|deny <id>` | 权限响应 |
## 私有内存
杀手功能：`/remember` 直接写入您的 `~/.claude/CLAUDE.md` （克劳德代码CLI已经自动加载）。无需重复KV存储，无需与CLI自己的 `/memory` 冲突 —— 桥接管理的内容被明确标记：
```markdown
... （您的现有内容 / CLI /memory 输出） ...
<!-- BRIDGE_MEMORY_START -->
## 风格
简短直接
## 语言
中文回复
<!-- BRIDGE_MEMORY_END -->
```
在飞书（或终端！）中的下一个克劳德查询将以该风格回应。
## 飞书-MCP
让克劳德从飞书聊天中读取/写入飞书文档和浏览驱动。由 [cso1z/Feishu-MCP](https://github.com/cso1z/Feishu-MCP) 驱动。
示例：
> “用飞书工具列出我能访问的所有飞书云文档”
> “读取飞书 wiki https://feishu.cn/wiki/abc123 并总结”
参见 `CLAUDE.md` 以获取所需作用域和故障排除信息。
## 配置
所有配置均位于 `config.env`。最重要的字段：
| 变量 | 目的 |
|---|---|
| `CTI_FEISHU_APP_ID` / `CTI_FEISHU_APP_SECRET` | 飞书应用凭证 |
| `CTI_DEFAULT_WORKDIR` | 新会话的默认CWD |
| `CTI_FEISHU_ALLOWED_USERS` | 开放ID的逗号分隔允许列表（安全） |
| `CTI_AUTO_APPROVE` | `true` 以自动允许所有工具调用（较不安全） |
| `MINIMAX_BASE_URL` / `MINIMAX_AUTH_TOKEN` | 启用 `minimax` 模型提供商 |
| `GLM_BASE_URL` / `GLM_API_KEY` | 启用 `glm-5.1` 模型提供商 |
参见 `config.env.example` 以获取完整列表。
## 架构
```
飞书IM（移动/桌面）
↕ WebSocket（无需公网IP）
┌─────────────────────────────────┐
│ 守护进程（Node.js + systemd） │
│ ┌──────────┐ ┌─────────────┐ │
│ │ feishu.ts│ │ bridge.ts │ │
│ │ WS + │ │ /commands + │ │
│ │ CardKit │ │ 消息 │ │
│ │ v2 │ │ 路由 │ │
│ └────┬─────┘ └──────┬──────┘ │
│ │ │ │
│ ┌────┴───────────────┴──────┐ │
│ │ claude-provider.ts │ │
│ │ + 飞书-MCP服务器 │ │
│ └────────────┬──────────────┘ │
└───────────────┼─────────────────┘
↕ （SDK query() 使用 mcpServers）
┌────────────────────┐
│ 克劳德代码CLI │
│ （使用 mcp 配置） │
└────────────────────┘
```
持久状态：`~/.bridge/data/` （会话，绑定，消息，审计日志，重复数据删除）。
## 已知限制
- **克劳德代码CLI 2.1.159** 已固定（较新版本可能会阻止第三方LLM提供商）。有关详细信息，请参见 [CLAUDE.md](./CLAUDE.md)。
- 飞书卡片2.0的 `collapsible_panel` 在聊天消息中 **不会** 折叠 —— 长响应会内联渲染。
- `~/.claude/CLAUDE.md` 上无文件锁（单个用户，低并发；第2阶段）。
## 开发
```bash
npm run typecheck # tsc --noEmit
npm test # 99 个单元测试
npm run build # esbuild 捆绑 → dist/daemon.mjs
```
## 许可证
MIT —— 参见 [LICENSE](./LICENSE)。从 [PI-33/feishu-claude-bridge](https://github.com/PI-33/feishu-claude-bridge) （MIT）分叉。
## 致谢
- [PI-33/feishu-claude-bridge](https://github.com/PI-33/feishu-claude-bridge) —— 原始桥梁
- [cso1z/Feishu-MCP](https://github.com/cso1z/Feishu-MCP) —— 飞书MCP服务器
- [@larksuiteoapi/node-sdk](https://www.npmjs.com/package/@larksuiteoapi/node-sdk) —— 飞书SDK
- [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) —— 克劳德代码SDK
