pi-feishu-agent

从飞书/Lark 远程控制 Pi 编程 Agent：WebSocket 长连接、常驻 RPC Agent、移动端富文本。Control Pi coding agents from Feishu/Lark with low-latency WebSocket, persistent RPC agents, and mobile-first rich text replies.

Packages

Package details

extension

Install pi-feishu-agent from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-feishu-agent
Package
pi-feishu-agent
Version
0.2.1
Published
Aug 5, 2026
Downloads
504/mo · 36/wk
Author
louisezhang666
License
MIT
Types
extension
Size
59 KB
Dependencies
1 dependency · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-feishu-agent

npm version npm downloads license

用飞书 / Lark 远程指挥你的 Pi 编程 Agent。 在飞书里发一句任务，你的电脑就开始干活：改代码、跑测试、查资料、写文件——结果以富文本实时回到飞书，手机上也能看得清清楚楚。

⚡ 低延迟设计：飞书 WebSocket 长连接 + 常驻 Pi RPC Agent。不像简单的 webhook 方案每条消息冷启动 pi -p，这里的 Agent 一直在等你。

为什么值得装

pi-feishu-agent
📱 移动端优先 回复渲染为飞书富文本（加粗/列表/代码块/链接），长消息自动分段，表格与代码块安全降级，不会出现 ** 语法裸奔或消息被吞
⚡ 常驻 Agent 每个会话一个持久 Pi RPC 进程，不用每次冷启动，延迟低、上下文连续
👥 团队工作流 团队 <任务>：Manager 拆解 → Coder 执行 → Reviewer 验收 → 自动返工
🔌 无需公网 WebSocket 长连接，不需要服务器、隧道、ngrok、webhook URL
🛡️ 配对授权 一次性配对码 + 会话白名单，未授权会话默认拒绝
🩺 自检诊断 doctor 一键检查配置、凭证、模型、权限
💻 独立服务 不依赖 Pi 常驻：npm 全局安装即可，macOS launchd 守护自动重启

快速开始（3 步）

npm install -g pi-feishu-agent
pi-feishu-agent init        # 输入飞书 App ID / App Secret
pi-feishu-agent install-service   # macOS：立即启动 + 开机自启

在飞书里给你的机器人发：

/pair <配对码>

配对成功后，直接发任务即可：

修复这个项目失败的测试

或者用团队模式自动推进：

团队 完善项目的错误处理，跑测试并检查结果

不想全局安装？也可以作为 Pi 扩展使用：pi install npm:pi-feishu-agent，重启后 /feishu-agent-config → /feishu-agent-start。

手机上的效果

所有回复默认渲染为飞书富文本消息（post 类型）：

  • 加粗、列表、行内代码、链接 在移动端正常渲染
  • 代码块 独立成段，不会被 md 渲染器吞掉
  • markdown 表格 自动降级为纯文本（飞书富文本不渲染表格，避免整条空白）
  • 超长回复 按行自动分段（每段 ≤ 8000 字），不会一堵墙
  • Typing 指示：Agent 干活时消息上有「正在输入」表情，完成自动移除
  • 实时进度：工具执行过程通过进度消息实时更新（🔧 正在执行：bash → edit）

与 Pi 原生体验的差异

场景 传统 webhook 方案 pi-feishu-agent
每条消息 冷启动 pi -p（秒级延迟） 常驻 RPC Agent（毫秒级）
对话连续性 无 / 靠外部存储 每会话独立持久 Agent
复杂任务 单 Agent 硬扛 可选 Manager→Coder→Reviewer
安全性 通常全量信任 配对码 + 白名单 + 0600 权限
移动端 纯文本，语法裸奔 富文本 + 分段 + 降级兜底
部署 需要常驻 Pi 独立 CLI / launchd 守护

聊天用法

Direct 模式（默认，最快）

直接发任务即可：

检查这个项目，修复失败的测试

也可以显式指定：

直接 打开 Chrome 查询相关文档并总结

Team 模式（自动多 Agent 工作流）

团队 完善这个项目的错误处理，运行测试并检查结果

执行链路：Manager 拆解 → Coder 执行 → Reviewer 验收 → 不通过自动返工。适合需要动真格的任务。

命令

聊天命令 作用
帮助 / /help 显示帮助
状态 / /status 队列与 Agent 池状态
停止 / /abort 中止当前 Agent
重置 / /reset 重启当前会话的常驻 Agent 池
直接 <任务> 强制 Direct 模式
团队 <任务> 运行多 Agent 工作流

飞书应用配置

在飞书开放平台开发者后台：

  1. 创建企业自建应用，开启机器人能力
  2. 事件与回调 → 选择 WebSocket / 长连接
  3. 订阅事件：im.message.receive_v1
  4. 至少开通权限：
    • im:message
    • im:message:send_as_bot
    • im:message.group_at_msg:readonly
    • im:message.p2p_msg:readonly
  5. 发布版本，把机器人拉进会话

不需要公网 IP、Cloudflare Tunnel、ngrok 或 webhook URL。海外用户使用 Lark：先 export FEISHU_DOMAIN=lark 再运行 init / install-service。

架构

飞书 / Lark 会话
      │ WebSocket 长连接
      ▼
pi-feishu-agent
      │ JSONL RPC（常驻进程）
      ├── Direct Agent
      ├── Manager Agent
      ├── Coder Agent
      └── Reviewer Agent
             │
             ▼
      Pi 工具 / 文件系统 / Shell / 浏览器

安全

Pi 扩展以你的系统权限执行操作，请把机器人当作远程 Shell 对待。

  • 新装默认拒绝一切会话，配对后才放行
  • 配对生成会话白名单；群聊配对等于授权群里所有人
  • 每个配对会话独立隔离的常驻 Agent 池
  • 凭证与任务记录存放在 ~/.pi/agent/feishu-agent/，权限 0600
  • 默认不在日志写消息内容（调试可设 FEISHU_LOG_CONTENT=1）
  • 不要把机器人拉进不可信群聊

配置

配置文件：~/.pi/agent/feishu-agent/config.json

环境变量覆盖：

变量 默认值 说明
FEISHU_DOMAIN feishu 平台：feishu 或 lark
FEISHU_OPEN_BASE_URL 平台默认 自定义 Open Platform 地址
FEISHU_PI_CWD ~ Pi 工作目录
FEISHU_PI_PROVIDER Pi 默认 覆盖 Provider
FEISHU_PI_MODEL Pi 默认 覆盖模型
FEISHU_PI_THINKING Pi 默认 覆盖思考级别
FEISHU_REPLY_MAX_CHARS 12000 最大回复长度
FEISHU_RPC_TIMEOUT_MS 1800000 Agent 超时
FEISHU_REVIEW_ROUNDS 1 Team 返工轮数
FEISHU_ACK_DELAY_MS 800 进度提示延迟
FEISHU_LOG_CONTENT 0 设为 1 记录消息文本
PI_FEISHU_AGENT_HOME ~/.pi/agent/feishu-agent 数据目录

服务管理（macOS）

pi-feishu-agent install-service
pi-feishu-agent uninstall-service
launchctl print gui/$(id -u)/com.pi-feishu-agent
tail -f /tmp/pi-feishu-ws.log

launchd 服务启用 KeepAlive：崩溃自动重启，登录自动启动。

故障排查

pi-feishu-agent doctor
tail -n 200 /tmp/pi-feishu-ws.log
  • 机器人连上但不理人 → 本地跑 pi-feishu-agent pairing-code，在会话里 /pair <码>
  • Agent 卡住 → 发 /abort；彻底重启发 /reset
  • 回复为纯文本而非富文本 → 检查是否有 markdown 表格（设计如此，防止空白消息）

开发

cd /path/to/pi-feishu-agent
npm install
npm test
npm pack --dry-run
node ws-standalone.mjs doctor

欢迎贡献，见 CONTRIBUTING.md。

更新日志

0.2.0 — 移动端优先

  • 富文本回复：post 消息渲染 markdown，移动端告别语法裸奔（借鉴 hermes Feishu 适配器的成熟模式：代码块隔离、表格降级、失败兜底）
  • 长消息分段：超长回复按行拆分为多条消息（≤ 8000 字/条）
  • Typing 指示：Agent 工作期间消息带「正在输入」表情
  • 纯文本兜底：post 被 API 拒绝时自动降级并剥离 markdown 语法
  • 渲染层独立：render.mjs 模块化 + 单元测试

0.1.0 — 首发

  • 飞书 WebSocket 长连接桥
  • 常驻 RPC Agent（Direct / Manager / Coder / Reviewer）
  • 配对授权 + 白名单
  • 实时进度更新
  • macOS launchd 服务
  • doctor 诊断

License

MIT