@xjuai/pi-feishu-lark

飞书 / Lark ↔ Pi coding agent 桥接扩展。

基于 AX1202/pi-feishu-lark 的重构式 fork（MIT），面向 Docker 守护与生产告警场景增强。

架构

┌──────────────────────────────────────────────────────────────────────────┐
│  Runtime（Pi 扩展 / Docker worker / 可选 daemon）                          │
│  gateway-lock · 配置 · 健康状态 · 调试日志                                 │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │
        ┌───────────────────────▼───────────────────────┐
        │  Feishu Transport（传输层）                     │
        │  WS 长连接 · SDK · 卡片回调                     │
        │  发送/回复（text · post · interactive）         │
        │  getMessage（引用父/根消息）· 出站重试          │
        └───────────────────────┬───────────────────────┘
                                │ InboundEvent
        ┌───────────────────────▼───────────────────────┐
        │  Inbound Pipeline（入站流水线）                 │
        │  去重 → 群策略 → parseMessageInput              │
        │  解析器：text / post / interactive / file       │
        │  引用展开 → 命令（/new /model /…）              │
        └───────────────────────┬───────────────────────┘
                                │ AgentRequest
        ┌───────────────────────▼───────────────────────┐
        │  Session Orchestrator（ConversationManager）  │
        │  会话键 → Pi session                           │
        │  按 key 串行队列 · 模型/工作区 · 停止           │
        │  可配置 prompt / 队列超时                       │
        └───────────────────────┬───────────────────────┘
                                │ 流式事件 + 最终回复
        ┌───────────────────────▼───────────────────────┐
        │  Pi Session Port                               │
        │  createAgentSession · prompt · abort           │
        │  SessionManager（落盘 session）                 │
        └───────────────────────┬───────────────────────┘
                                │ delta + 最终文本
        ┌───────────────────────▼───────────────────────┐
        │  Outbound Presenter（出站呈现）                 │
        │  CardKit 流式（失败回落普通回复）               │
        │  rich-text 模式 · 分片 · 重试                   │
        │  任务状态卡 · bridge（定时任务回投）            │
        └───────────────────────────────────────────────┘

主路径消息流：

飞书用户 / 告警卡片
    → Transport（WS）
    → 去重 + 解析（interactive / 引用）
    → ConversationManager.prompt
    → Pi agent 一轮
    → StreamingReply / replyText
    → 飞书会话

相对上游的改动

• 入站 interactive 卡片解析：告警机器人卡片可转为可读文本进入 agent
• 引用/回复父消息展开：用户回复卡片并 @bot 时，自动拉取 parent/root 正文
• 可配置超时：默认 prompt / 队列等待 1h（可用环境变量调整）
• 出站重试：飞书 API 可重试错误指数退避
• 流式回复：CardKit 流式卡片，失败回落普通文本
• 保留上游能力：/workspace、resume 卡片、gateway lock、daemon、model 切换
• 命令：新增 /status、/commands

分支、版本与发布

| 项 | 策略 | |----|------| | 默认分支 | main（始终可发布） | | 功能开发 | 短生命周期 feat/* / fix/* / docs/* PR 合入 main | | 版本 | SemVer + Conventional Commits | | Release | Release Please 自动开 Release PR；合并后打 vX.Y.Z 并创建 GitHub Release | | npm | publish.yml 在 release: published 时执行 npm publish --access public --provenance |

完整说明见 CONTRIBUTING.md。

安装

# 本地 path（Docker / monorepo）
pi install /path/to/packages/pi-feishu-lark -a

# 或 npm（若已发布）
pi install npm:@xjuai/pi-feishu-lark -a

使用

/feishu setup
/feishu start

飞书侧命令： /new /resume /model /workspace /status /stop /commands

Pi 侧管理： /feishu setup /feishu start /feishu stop /feishu restart /feishu status /feishu autostart /feishu debug /feishu reset

配置

~/.pi/agent/feishu/config.json 或环境变量：

| 变量 | 默认 | 说明 | |------|------|------| | FEISHU_APP_ID / FEISHU_APP_SECRET | — | 应用凭证 | | FEISHU_DOMAIN | feishu | feishu / lark | | FEISHU_GROUP_POLICY | open | open（群内均可）/ mention（需 @ 机器人） | | FEISHU_GROUP_KEYWORDS | — | 群聊关键词触发（逗号/分号分隔），与 mention 叠加：命中即可无需 @。匹配为去空白后大小写不敏感子串 | | FEISHU_GROUP_ALSO_ON_REPLY | false | true 时回复本 bot 消息也会触发（无需再 @），与 mention 叠加 |

运行时配置（热更新 + 落盘）

除 env 外，可通过对话修改白名单配置，立即生效并写入 ~/.pi/agent/feishu/runtime-overrides.json（覆盖 env 中同名项；不含密钥）。

飞书命令

/config                         # 查看有效配置
/config groupKeywords 志胜,zs   # 设置关键词
/config groupAlsoOnReply true
/config streamingReply false
/config clear groupKeywords     # 清除单项 override
/config clear all               # 清除全部 overrides

模型 Tool

• feishu_config_get — 读取白名单配置
• feishu_config_set — 设置 key/value
• feishu_config_clear — 清除 override

可改项：groupPolicy groupKeywords groupAlsoOnReply reactEmoji language streamingReply streamPrintFrequencyMs streamPrintStep streamPushIntervalMs
禁止：appId / appSecret / 连接通道相关项。 | FEISHU_PARSE_INTERACTIVE_CARDS | true | 解析入站 interactive 卡片 | | FEISHU_INCLUDE_QUOTED_MESSAGE | true | 展开引用/回复的父消息 | | FEISHU_QUOTED_MESSAGE_MAX_CHARS | 8000 | 引用正文最大字符数 | | FEISHU_PROMPT_TIMEOUT_MS | 3600000 | 单轮 prompt 超时（毫秒） | | FEISHU_QUEUE_WAIT_TIMEOUT_MS | 3600000 | 等待上一轮队列超时 | | FEISHU_SEND_MAX_RETRIES | 2 | 出站 API 重试次数（不含首次） | | FEISHU_STREAMING_REPLY | true | 同一张卡边生成边刷新最终可见正文 | | FEISHU_STREAM_FLUSH_MS | 350 | 流式 patch 最小间隔（毫秒） | | FEISHU_STREAM_FIRST_FLUSH_MS | 50 | 首次出字延迟（毫秒） | | FEISHU_STREAM_MIN_CHARS | 8 | 触发 patch 的最少新增字符数 | | FEISHU_STREAM_MAX_BODY_CHARS | 12000 | 卡片正文最大字符数 | | FEISHU_AUTO_START | true | Pi 启动时自动连接 | | FEISHU_LANGUAGE | zh | zh / en |

落盘路径

| 路径 | 内容 | |------|------| | ~/.pi/agent/feishu/config.json | 凭证与配置 | | ~/.pi/agent/feishu/runtime-overrides.json | 运行时白名单配置覆盖（热更新落盘） | | ~/.pi/agent/feishu/state.json | 飞书 ↔ Pi 会话映射 | | ~/.pi/agent/feishu/bridge.json | 定时任务等路由 | | ~/.pi/agent/feishu/debug.log | 调试日志 | | ~/.pi/agent/sessions/ | 各飞书会话对应的 Pi session |

开发

npm install
npm run check
npm test

常见问题

机器人不回复？

• 确认飞书应用与权限已配置
• 确认已执行 /feishu start
• 群聊 mention 策略下需要 @ 机器人；open 还需开通「获取群组中所有消息」

告警卡片 agent 看不到内容？

• 确认 FEISHU_PARSE_INTERACTIVE_CARDS=true
• 用户回复卡片时确认 FEISHU_INCLUDE_QUOTED_MESSAGE=true，并具备消息读取权限

License

MIT（上游 AX1202/pi-feishu-lark）