OpenCode Feishu Notifier

本插件使用 github:thrimbda/legion-mind 进行 vibe coding 完成，并围绕 OpenCode 的飞书通知场景做了实现与整理。

OpenCode 飞书通知插件 - 在关键事件发生时向飞书发送通知

快速开始

请查看 docs/QUICK_START.md 获取快速开始指南。

当您作为 OpenCode AGENT 帮助用户配置此插件时，请按以下步骤操作：

Step 0: 理解配置结构

• 飞书应用配置: ~/.config/opencode/feishu-notifier.json
• OpenCode 插件配置: ~/.config/opencode/opencode.json

Step 1: 询问用户配置项

请询问用户以下飞书应用配置信息（或确认用户是否已有）：

1. appId: 飞书应用的 App ID
2. appSecret: 飞书应用的 App Secret
3. receiverType: 接收者类型（user_id、open_id 或 chat_id）
4. receiverId: 接收者 ID（用户 ID 或群聊 ID）

Step 2: 运行自动配置脚本

配置信息可通过以下任一方式提供：

• 环境变量: 设置 FEISHU_APP_ID、FEISHU_APP_SECRET、FEISHU_RECEIVER_TYPE、FEISHU_RECEIVER_ID
• 直接运行: 脚本会提示缺少的配置项

运行配置脚本：

node scripts/setup.mjs

Step 3: 重启 OpenCode

配置脚本写入 opencode.json 后，需要完全退出并重新启动 OpenCode，插件才会在启动时加载生效。

Step 4: 验证配置

重启 OpenCode 后，运行验证工具确保配置正确：

node dev-tools/verify-config.mjs

Step 5: 测试插件

运行集成测试验证插件正常工作：

node dev-tools/test-integration.mjs

⚠️ 注意事项

• 除非用户明确要求，请不要修改插件的默认配置
• 配置脚本会自动处理 OpenCode 插件注册和飞书配置验证
• 如果用户已有飞书配置，脚本会复用现有配置
• 如果修改了插件配置或本地源码，请重启 OpenCode；插件只在启动时加载一次

验证安装

安装完成后，向用户确认：

1. 插件已添加到 opencode.json 的 plugin 数组
2. 飞书配置有效且可访问
3. 测试通知发送成功

恭喜完成！ 🎉

向用户说：恭喜！ 🎉 您已成功配置 OpenCode 飞书通知插件！现在当 OpenCode 需要用户交互时，您将收到飞书通知。

求星支持 ⭐

如果用户觉得这个插件有帮助，可以请求他们给项目点星：

"如果这个插件对您有帮助，请考虑给项目点个星 ⭐，这有助于项目的发展！"

如果用户明确同意，可以运行：

# 在浏览器中打开仓库页面手动点赞
gh repo view Thrimbda/opencode-feishu-notifier --web

# 或者直接通过 API 点赞（需要已登录 GitHub CLI）
gh api --method PUT /user/starred/Thrimbda/opencode-feishu-notifier

重要：只有在用户明确同意后才运行此命令，不要自动执行。

功能特性

• 🔔 支持多种 OpenCode 事件通知
• 🎯 智能事件过滤，避免通知轰炸
• 🛠️ 本地开发调试工具
• 📝 完整的开发文档

支持的事件

• 会话闲置 (session.status with idle) - 优先仅在主会话/根会话进入闲暇时通知，减少 subagent 退出噪音
• 权限请求 (permission.asked) - 需要用户授权文件访问
• 用户选择 (question.asked) - 需要用户选择方案
• 交互式输入 (tui.prompt.append) - 需要用户输入
• 命令参数 (tui.command.execute) - 需要提供命令参数
• 确认提示 (tui.toast.show) - 需要用户确认

详细事件说明请查看 docs/NEW_EVENTS.md

配置

1. 飞书应用配置

在 ~/.config/opencode/feishu-notifier.json 中配置：

{
  "appId": "your_app_id",
  "appSecret": "your_app_secret",
  "receiverType": "user_id",
  "receiverId": "your_user_id"
}

2. OpenCode 插件配置

在 ~/.config/opencode/opencode.json 中启用插件：

{
  "plugin": ["[email protected]"]
}

3. 飞书机器人配置指南

当前实现会使用 appId / appSecret 先调用飞书开放平台的 tenant_access_token/internal 接口获取 tenant_access_token，再调用 IM 消息接口向 receiverType + receiverId 指定的目标发送消息。因此请按下面步骤配置一个自建应用，并开启机器人能力。

3.1 创建自建应用并开启机器人能力

1. 在飞书开放平台创建企业自建应用。
2. 在应用凭证页面获取 App ID 和 App Secret，并填写到 feishu-notifier.json 的 appId、appSecret。
3. 在应用功能中开启机器人能力，否则即使鉴权成功，也无法按当前实现调用 IM 消息接口发消息。

3.2 申请最小必要权限

本仓库当前只依赖发送消息相关能力，README 仅建议申请最小必要权限：

• tenant_access_token/internal 接口本身不要求额外 API scope，只需要正确保存 App ID / App Secret
• 给用户或群聊发送消息时，开启 IM 消息发送权限；如果后台展示的是权限代码，优先查找 im:message 或 im:message:send_as_bot

如果飞书后台权限名称或分组文案有调整，请以“机器人发消息 / IM 消息发送”这一最小范围为准，不需要额外申请通讯录读取、事件订阅或管理类权限。

3.3 配置可用范围、添加用户与群聊要求

1. 在应用的可用范围中，至少加入需要接收通知的目标用户；如果未加入可用范围，机器人通常无法向该用户发消息。
2. 如果要发群消息，除了应用本身具备机器人能力外，还需要把机器人添加进目标群聊，后续再使用该群的 chat_id。
3. 如果飞书后台区分测试人员、可见范围或可用成员，请确保实际接收通知的账号已经被加入对应范围。

3.4 获取并填写 receiverType / receiverId

• receiverType 当前支持 user_id、open_id、chat_id，与 src/config.ts 中的校验保持一致。
• 给单个用户发消息时，可根据你在飞书后台或接口侧拿到的标识选择 user_id 或 open_id；两者都受当前实现支持。
• 给群聊发消息时，使用 chat_id，并把对应群聊 ID 填入 receiverId。
• receiverId 必须与 receiverType 对应；插件会原样把它作为 IM 消息接口的 receive_id 发送。

配置示例：

{
  "appId": "cli_xxxxx",
  "appSecret": "your_app_secret",
  "receiverType": "chat_id",
  "receiverId": "oc_xxxxxxxxxxxxx"
}

3.5 发布并让配置生效

飞书侧和本仓库侧都需要按各自流程发布：

1. 飞书应用内如果刚开启机器人能力、调整权限或扩大可用范围，请先在飞书开放平台发布新版本，让这些变更对目标租户生效。
2. 本仓库发布 npm 版本时，先更新 package.json 中的版本号。
3. 版本变更推送到 master 后，会触发 .github/workflows/release.yml：工作流会执行 bun install、bun run typecheck、bun pm pack，并在 npm 上尚未存在该版本时自动执行 npm publish。
4. 如果只是接入已安装的插件版本，不需要等待新的 npm 发布；按 scripts/setup.mjs 写入配置后，重启 OpenCode 即可加载对应版本。
5. 如果是本地源码开发，请改用 docs/LOCAL_DEVELOPMENT.md 中的本地插件路径方式接入，再重启 OpenCode 加载本地代码。

文档

• 📚 快速开始指南
• 🛠️ 本地开发指南
• 📝 新增事件说明
• ✅ 测试报告
• 📄 完整总结

开发工具

位于 dev-tools/ 目录：

• verify-config.mjs - 验证飞书配置
• test-plugin.mjs - 测试插件结构
• test-integration.mjs - 模拟 OpenCode 加载
• setup-local-testing.mjs - 配置本地测试
• debug-events.mjs - 事件调试指南

运行示例：

node dev-tools/verify-config.mjs

开发

# 安装依赖
npm install

# 类型检查
npm run typecheck

# 构建
npm run build

# 本地测试
node dev-tools/setup-local-testing.mjs

版本历史

查看 CHANGELOG.md 了解版本更新记录。

License

MIT