用途
本技能用于为 NanoClaw 添加飞书（Feishu/飞书，国际版为 Lark）作为消息渠道。它借助 skills 引擎执行确定性的代码变更，并随后引导用户完成交互式配置。该渠道使用 WebSocket 长连接，因此不需要公网 URL 或 ngrok。它可以与 WhatsApp、Telegram、Slack 等渠道同时使用，也可以作为独立渠道运行。
主要能力
应用本技能后，会确定性地完成以下变更：
- 新增 src/channels/feishu.ts（FeishuChannel 类，通过 registerChannel 自注册）
- 新增 src/channels/feishu.test.ts（单元测试）
- 在渠道汇总文件 src/channels/index.ts 中追加 import './feishu.js'
- 安装 @larksuiteoapi/node-sdk npm 依赖
- 在 .env.example 中新增 FEISHU_APP_ID 与 FEISHU_APP_SECRET
- 在 .nanoclaw/state.yaml 中记录本次应用
使用方式
阶段一：预检
读取 .nanoclaw/state.yaml，若 applied_skills 中已包含 feishu，则直接跳到阶段三（配置）。随后通过 AskUserQuestion 收集配置：询问用户是否已创建飞书（Lark）应用，若已有则索取 App ID 与 App Secret，若没有则在阶段三引导创建。
阶段二：应用代码变更
若 .nanoclaw/ 目录尚不存在，先初始化技能系统：
npx tsx scripts/apply-skill.ts --init
然后应用技能：
npx tsx scripts/apply-skill.ts .claude/skills/add-feishu
若应用报告合并冲突，阅读意图文件 modify/src/channels/index.ts.intent.md（说明变更内容与不变量）。随后验证代码变更：
npm test npm run build
所有测试（包括新增的 feishu 测试）必须通过，且构建必须干净，才能继续。
阶段三：配置
若用户尚无应用，需引导其创建飞书应用：
- 前往飞书开放平台（国际版为 Lark Open Platform）
- 点击创建应用 → 自建应用
- 填写应用名称与描述（例如 “NanoClaw Assistant”）
- 前往凭证与基础信息，复制 App ID 与 App Secret
- 前往事件订阅 → 添加事件 → 搜索并添加：im.message.receive_v1（接收消息 — v2.0）
- 前往权限与范围 → 添加以下权限：im:message（收发消息）、im:message:send_as_bot（以机器人身份发送消息）、im:chat（读取群信息）、im:chat.members:read（读取群成员）
- 前往机器人标签页 → 启用机器人功能
- 点击发布 / 申请发布
注意：企业使用时，IT 管理员可能需要审批该应用。
等待用户提供 App ID（格式：cli_xxxxxxxxxxxxxxxxxx）与 App Secret。
配置环境变量，在 .env 中添加：
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxxxx FEISHU_APP_SECRET=your_app_secret_here
渠道在凭据存在时会自动启用，无需额外配置。同步到容器环境：
mkdir -p data/env && cp .env data/env/env
容器从 data/env/env 读取环境变量，而非直接读取 .env。
构建并重启：
npm run build launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
Linux: systemctl --user restart nanoclaw
阶段四：注册
获取聊天 ID。要注册飞书聊天，需要该聊天的 ID：
单聊（p2p）：
- 将机器人添加到飞书联系人
- 打开与机器人的私信
- 发送任意消息 — NanoClaw 会记录 JID 为 fs:p2p:<your_open_id>
- 在 logs/nanoclaw.log 中查找：Message from unregistered Feishu chat
群聊：
- 将机器人添加到群：群设置 → 成员 → 添加机器人
- 在群中发送任意消息（或 @提及机器人）
- NanoClaw 会记录 JID 为 fs:oc_<chat_id>
- 在 logs/nanoclaw.log 中查找：Message from unregistered Feishu chat
提示用户查看日志：
tail -f logs/nanoclaw.log | grep "unregistered Feishu"
等待用户提供 JID（格式：fs:oc_xxxxx 或 fs:p2p:ou_xxxxx）。
注册聊天。主聊天（响应所有消息）：
registerGroup("fs:<chat-id>", {
name: "<chat-name>",
folder: "feishu_main",
trigger: @${ASSISTANT_NAME},
added_at: new Date().toISOString(),
requiresTrigger: false,
isMain: true,
});
其他聊天（基于触发，仅在 @提及或触发时响应）：
registerGroup("fs:<chat-id>", {
name: "<chat-name>",
folder: "feishu_<group-name>",
trigger: @${ASSISTANT_NAME},
added_at: new Date().toISOString(),
requiresTrigger: true,
});
阶段五：验证
向已注册的飞书聊天发送消息：主聊天发送任意消息即可；非主聊天需 @提及机器人或包含问题/请求关键词。机器人应在几秒内响应。如需排查可查看日志：
tail -f logs/nanoclaw.log
适用场景
- 希望将飞书（Lark）作为 NanoClaw 消息渠道的用户
- 需要在不暴露公网 URL、不使用 ngrok 的情况下接入飞书
- 需要飞书渠道与 WhatsApp、Telegram、Slack 等渠道并存或独立运行
- 企业或团队环境中通过飞书群聊或单聊与机器人交互
限制与注意事项
- 企业使用时，应用可能需要 IT 管理员审批。
- 群聊中默认仅在以下情况响应：机器人被 @提及；消息包含请求关键词（帮、请、分析等）；消息以 ? 或 ？ 结尾。若要让机器人在群中响应所有消息，需以 requiresTrigger: false 注册。
- 日志中出现 “Message from unregistered Feishu chat” 属正常现象，表示机器人已收到消息但聊天尚未注册，需按阶段四完成注册。
- App Secret 属敏感信息，仅应存储在 .env 与 data/env/env 中，切勿提交到版本控制。
- 若日志难以查找 JID，可执行：sqlite3 store/messages.db "SELECT DISTINCT chat_jid FROM chats WHERE channel = 'feishu'"
JID 格式参考
群聊：fs:oc_<id>，例如 fs:oc_4e359893776d45f7cd05d40e3ee10f55 单聊（p2p）：fs:p2p:<open_id>，例如 fs:p2p:ou_7a66d6bd1baa3e6e3d7b3df9a8c90000
配置完成后
若在服务运行时执行 npm run dev：
macOS:
launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist npm run dev
测试完成后:
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
Linux:
systemctl --user stop nanoclaw
npm run dev
systemctl --user start nanoclaw
移除
移除飞书集成：
- 删除 src/channels/feishu.ts 与 src/channels/feishu.test.ts
- 从 src/channels/index.ts 移除 import './feishu.js'
- 从 .env 移除 FEISHU_APP_ID 与 FEISHU_APP_SECRET
- 从 SQLite 移除飞书注册：sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE 'fs:%'"
- 卸载依赖：npm uninstall @larksuiteoapi/node-sdk
- 重新构建：npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw（macOS）或 npm run build && systemctl --user restart nanoclaw（Linux）