概述

PinableAgents 的飞书集成让你在飞书里发消息，终端自动执行。远程操作、结果推送、状态追踪，一个不落。

真正实现：人在飞书，码在终端。

两种接入模式

模式	说明	是否需要公网	推荐程度
长连接 (ws)	使用飞书官方 SDK 建立 WebSocket 长连接	不需要	推荐
Webhook	传统 HTTP 回调方式	需要（ngrok 等）	备选

长连接模式的优势：

• 无需公网 IP 或域名，无需 ngrok
• 内置通信加密和鉴权，无需额外配置 Encrypt Key 和 Verification Token
• 只需填写 App ID 和 App Secret 即可使用
• 自动重连，稳定性更好

快速配置

第一步：创建飞书应用

1. 访问 飞书开放平台 → 登录 → 点击「创建企业自建应用」
2. 填写应用名称（例如 "PinableAgent"）和应用描述
3. 进入「凭证与基础信息」页面，记录 App ID 和 App Secret

第二步：配置权限

在飞书开放平台的「权限管理」页面申请以下权限：

权限标识	说明
im:message	获取与发送单聊、群组消息（必须）
im:message.group_msg	读取群组消息
im:message.p2p_msg:readonly	读取用户发给机器人的单聊消息
im:resource	获取消息中的资源文件
contact:user.base:readonly	获取用户基本信息
aily:message:read	读取 Aily 消息
aily:message:write	发送 Aily 消息

第三步：配置网关

在 pinable-desktop 或 pinable 配置文件中填写：

{
  "feishu": {
    "mode": "ws",
    "app_id": "cli_xxxxxxxxxxxxxxxx",
    "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auto_reconnect": true
  }
}

第四步：启动

启动后，飞书机器人即进入在线状态。向机器人发送消息，即可触发终端执行。

核心功能

消息指令

在飞书里可以直接发送以下指令：

指令	说明
/do <任务描述>	启动 do 工作流
/ask <技术问题>	技术咨询
/debug <问题描述>	系统调试
/status	查看当前任务状态
/log	获取最近执行日志

结果推送

执行完成后，机器人自动推送：

• 执行结果摘要
• 关键日志片段
• 产物路径（如有文件变更）

群组协作

支持在飞书群中使用：

• @机器人 触发指令
• 群内实时看到执行进度
• 多人协作时自动排队

使用场景

远程 hotfix

在飞书收到告警 → @PinableAgent → "修复 XXX 问题" → 自动诊断并修复 → 推送结果

随时查询

在飞书 → "帮我看看 API 错误率上升的原因" → 自动分析日志 → 推送结论

CI/CD 触发

GitHub Actions → 飞书通知 → @PinableAgent → "分析失败原因" → 自动定位并报告

安全说明

• 所有通信通过飞书官方加密通道
• App Secret 仅存储在本地配置，不经过第三方
• 支持配置白名单，仅特定用户可以使用