# pi-feishu-agent

[![npm version](https://img.shields.io/npm/v/pi-feishu-agent.svg)](https://www.npmjs.com/package/pi-feishu-agent)
[![npm downloads](https://img.shields.io/npm/dw/pi-feishu-agent.svg)](https://www.npmjs.com/package/pi-feishu-agent)
[![license](https://img.shields.io/npm/l/pi-feishu-agent.svg)](https://www.npmjs.com/package/pi-feishu-agent)

**用飞书 / 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 步）

```bash
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 工作流 |

## 飞书应用配置

在[飞书开放平台](https://open.feishu.cn/)开发者后台：

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`。

## 架构

```text
飞书 / 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）

```bash
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`：崩溃自动重启，登录自动启动。

## 故障排查

```bash
pi-feishu-agent doctor
tail -n 200 /tmp/pi-feishu-ws.log
```

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

## 开发

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

欢迎贡献，见 [CONTRIBUTING.md](./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