@samp3ng/aster-plugin-feishu-cli

让 Stellar Agent (Aster) 通过官方 lark-cli 主动操作飞书 —— 读消息、搜文档、发文件、查/改日程等。

R4 立项 2026-05-19;v0.1.0 当前已实装 13 个工具(auth / contact / messages / docs / calendar / call)。真机回归待跑。

它和飞书网关 (@samp3ng/aster-core/gateways/platforms/feishu) 有什么区别

| | 网关 | 本插件 | |---|---|---| | 方向 | 入站(用户 → Aster) | 出站(Aster → 飞书) | | 触发 | 飞书 WSClient 推消息事件 | LLM 调 feishu_* 工具 | | 身份 | 应用机器人(as bot) | 用户本人(as user,默认)/ 机器人(as bot) | | 鉴权 | App ID + Secret | OAuth Device Flow,token 存 OS keychain |

两者共存,互补。

安装

1. 安装 lark-cli 二进制:

   npx @larksuite/cli@latest install

   默认安装到 ~/.larksuite/bin/lark(Windows 自动加 .exe)。

2. 完成 OAuth 登录:

   lark-cli auth login

   浏览器扫码完成 Device Flow,token 自动存 OS keychain。

3. 启用本插件 —— 在 ~/.stellar/config.yaml 加:

   plugins:
     installed:
       - name: feishu-cli
         package: '@samp3ng/aster-plugin-feishu-cli'
         enabled: true
         config:
           # 可选:覆盖 lark-cli 二进制路径
           larkCliPath: ~/.larksuite/bin/lark
           # 可选:默认身份(user / bot),工具可逐次覆盖
           defaultIdentity: user

工具清单(v0.1.0)

| 工具 | 类型 | 默认 dry-run | |---|---|---| | feishu_auth_status | 读 | — | | feishu_search_user | 读 | — | | feishu_list_chats | 读 | — | | feishu_search_message | 读 | — | | feishu_read_chat_history | 读 | — | | feishu_send_message | 写 | 是 | | feishu_send_file | 写 | 是 | | feishu_search_doc | 读 | — | | feishu_read_doc | 读 | — | | feishu_create_doc | 写 | 是 | | feishu_calendar_agenda | 读 | — | | feishu_create_event | 写 | 是 | | feishu_call | escape | GET/HEAD 否,其他是 |

dry-run / confirm 协议

所有写工具默认 confirm:false → 注入 --dry-run,只返回 lark-cli 解析后的请求体计划。 LLM 把计划展示给用户,用户确认后,LLM 再次调用并显式传 confirm:true 才真发。

故障排查

| 错误 | 含义 | 处理 | |---|---|---| | not_installed | 找不到 lark-cli 二进制 | npx @larksuite/cli@latest install | | auth_required | 没登录或 token 过期 | lark-cli auth login | | api_error | lark-cli 调通了但 API 返回错 | 看 stderr,通常是权限不足或参数错 | | timeout | 30s 超时 | 网络问题,或目标 API 真的慢 | | parse_error | lark-cli 输出不是合法 JSON | 升级 lark-cli,或报 issue |

许可

MIT