add-feishu

添加飞书频道

此技能使用技能引擎进行确定性代码更改，为 NanoClaw 添加飞书支持，然后引导用户完成交互式设置。

阶段 1：准备工作

检查是否已应用

读取 .nanoclaw/state.yaml。如果 applied_skills 中包含 feishu，则跳到阶段 3（设置）。代码更改已就位。

询问用户

使用 AskUserQuestion 收集配置：

AskUserQuestion：你已经有飞书应用了吗？还是需要创建一个？

如果用户已经有应用，现在就收集 FEISHU_APP_ID 和 FEISHU_APP_SECRET。如果没有，我们将在阶段 3 创建一个。

阶段 2：应用代码更改

运行技能引擎以应用此技能的代码包。软件包文件位于此目录中，与此 SKILL.md 同级。

初始化技能系统（如有需要）

如果 .nanoclaw/ 目录尚不存在：

npx tsx scripts/apply-skill.ts --init

应用技能

npx tsx scripts/apply-skill.ts .claude/skills/add-feishu

此操作将以确定性方式：

• 添加 src/channels/feishu.ts（实现 Channel 接口的 FeishuChannel 类）
• 将飞书支持通过三方合并加入 src/index.ts（通过 readEnvFile 读取凭据，并在配置完成时创建 FeishuChannel）
• 安装 @larksuiteoapi/node-sdk npm 依赖
• 使用 FEISHU_APP_ID 和 FEISHU_APP_SECRET 更新 .env
• 在 .nanoclaw/state.yaml 中记录应用情况

如果应用过程报告合并冲突，请阅读意图文件：

• modify/src/index.ts.intent.md — 说明 index.ts 中的更改及不变量

验证代码更改

npm run build

继续之前，构建必须无错误。

阶段 3：设置

创建飞书应用（如有需要）

如果用户没有飞书应用，请告诉他们：

我需要你创建一个飞书机器人：

1. 前往 飞书开放平台 并创建一个新应用
2. 在 凭证与基础信息 下，复制 App ID 和 App Secret
3. 在 事件订阅 下，启用 长连接（WebSocket） 模式
4. 添加事件：im.message.receive_v1（接收消息）
5. 在 权限管理 下，添加：
   • im:message:send_as_bot（以机器人身份发送消息）
   • im:message（读取消息）
6. 发布应用（或创建一个版本并提交审核）

等待用户提供 App ID 和 App Secret。

配置环境

添加到 .env：

FEISHU_APP_ID=<their-app-id>
FEISHU_APP_SECRET=<their-app-secret>

构建并重启

npm run build
launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
# Linux: systemctl --user restart nanoclaw

阶段 4：注册

获取 Chat ID

告诉用户：

1. 启动机器人：npm run dev
2. 在飞书中向机器人发送任意消息（私聊或群聊均可）
3. 查看日志 — chat_id 会显示在元数据中
4. JID 格式为 {chat_id}@feishu

也可以直接查询数据库：

sqlite3 store/messages.db "SELECT jid FROM chats WHERE jid LIKE '%@feishu'"

注册聊天

直接在 SQLite 中注册：

INSERT INTO registered_groups (jid, name, folder, trigger_pattern, added_at, requires_trigger)
VALUES ('{chat_id}@feishu', 'feishu', 'feishu', '@{ASSISTANT_NAME}', datetime('now'), 0);

注意：requires_trigger 设置为 0（false），因此机器人会响应所有消息，无需 @提及。

然后重启服务以加载新的注册信息。

阶段 5：验证

测试连接

告诉用户：

在飞书中向机器人发送一条消息。它应该会在几秒内回复。

必要时检查日志

tail -f logs/nanoclaw.log
# Or run interactively:
npm run dev

查找：

• Feishu bot info fetched — 机器人已连接并完成身份识别
• Connected to Feishu via WebSocket — WebSocket 已建立
• Feishu message sent — 已发送外发消息

故障排除

机器人无响应

检查：

1. .env 中已设置 FEISHU_APP_ID 和 FEISHU_APP_SECRET
2. 聊天已注册：sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE '%@feishu'"
3. 应用已在飞书开放平台发布（草稿应用不会接收事件）
4. 已启用事件订阅 im.message.receive_v1
5. 已启用长连接（WebSocket）模式（而非 webhook）
6. 服务正在运行：launchctl list | grep nanoclaw（macOS）或 systemctl --user status nanoclaw（Linux）

机器人已连接，但收不到消息

• 确认应用具有 im:message 权限
• 确认已订阅事件 im.message.receive_v1
• 检查应用版本是否已发布并通过审核

Bot 能接收但无法发送

• 确认应用拥有 im:message:send_as_bot 权限
• 对于群聊：必须先将 Bot 添加到群组

“Failed to fetch Feishu bot info”

非关键警告。Bot 消息检测（过滤自身消息）将无法使用，但消息发送和接收仍正常。通常表示无法访问 Bot API 端点，请检查网络连接。

移除

移除 Feishu 集成：

1. 删除 src/channels/feishu.ts
2. 从 src/index.ts 中移除 FeishuChannel 导入和创建代码块
3. 如果没有其他频道使用 readEnvFile，则移除其导入
4. 从 .env 中移除 FEISHU_APP_ID 和 FEISHU_APP_SECRET
5. 移除 Feishu 注册项：sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE '%@feishu'"
6. 卸载：npm uninstall @larksuiteoapi/node-sdk
7. 重新构建：npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw（macOS），或 npm run build && systemctl --user restart nanoclaw（Linux）