pi-remote-feishu 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.en.md +83 -0
  2. package/README.md +69 -46
  3. package/package.json +3 -2
package/README.en.md ADDED
@@ -0,0 +1,83 @@
1
+ # pi-remote-feishu
2
+
3
+ [中文文档](./README.md) | English
4
+
5
+ Remote control **Pi Agent** via **Feishu (飞书) / Lark** chat. A WebSocket bridge that turns your Feishu chat into a full Pi interface — with interactive cards, attachments, and file delivery.
6
+
7
+ This is an independent Pi extension. It does not modify Pi core.
8
+
9
+ ## Features
10
+
11
+ - 💬 **Feishu WebSocket transport** — long-lived connection, no public server needed
12
+ - 🔒 **Session isolation** — private chat per user, group chat shared or per-user (configurable)
13
+ - 🧠 **One Pi runtime per session** — sessions survive restarts via persisted session files
14
+ - 🃏 **Interactive cards** — model picking, session management, stop/status, permission confirmations
15
+ - 📎 **Attachment processing** — images (base64), small text (inlined), other files (downloaded)
16
+ - 📤 **`send_file_to_chat`** — the agent returns generated local files straight to the current chat
17
+ - 🧩 **Optional Lark CLI skills** — `lark-doc-cli`, `lark-im-readonly` when `lark-cli` is installed
18
+ - 🛡️ **Guardrails** — blocks `lark-cli im` send/reply/receive commands
19
+
20
+ ## Quick Start
21
+
22
+ ```bash
23
+ # 1. Install and build
24
+ npm install --ignore-scripts
25
+ npm run build
26
+
27
+ # 2. Create a config template (replace <your-pi-project> with your Pi working directory)
28
+ node dist/bin/pi-remote-feishu.js init --cwd <your-pi-project>
29
+
30
+ # 3. Edit the generated config: .pi/feishu.json
31
+ # - put your Feishu appId / appSecret
32
+ # - adjust policy / sessions / rendering options
33
+
34
+ # 4. Start the bridge
35
+ node dist/bin/pi-remote-feishu.js serve --cwd <your-pi-project>
36
+ ```
37
+
38
+ You can also pass credentials via environment variables:
39
+
40
+ ```bash
41
+ export FEISHU_APP_ID="cli_xxx"
42
+ export FEISHU_APP_SECRET="xxx"
43
+ node dist/bin/pi-remote-feishu.js serve --cwd <your-pi-project>
44
+ ```
45
+
46
+ ## CLI Commands
47
+
48
+ ```bash
49
+ pi-remote-feishu serve # start the Feishu bridge (default)
50
+ pi-remote-feishu init # generate .pi/feishu.json template
51
+ pi-remote-feishu doctor # check config and WebSocket connectivity
52
+ pi-remote-feishu send-test --chat-id <id> --text "hello" # send a test message
53
+ pi-remote-feishu help # show usage
54
+ ```
55
+
56
+ Log incoming message/card summaries with `--debug-events` (or set `debug.logIncomingEvents: true`).
57
+
58
+ ## Feishu Chat Commands
59
+
60
+ | Command | Description |
61
+ |---|---|
62
+ | `/help` | Show help |
63
+ | `/sessions` | Manage sessions (list / switch / delete) |
64
+ | `/models` | Pick model and thinking level |
65
+ | `/new` | Start a fresh Pi session |
66
+ | `/stop` | Stop the current generation |
67
+ | `/reset` | Reset the current session mapping |
68
+ | `/status` | Show connection / queue / model status |
69
+
70
+ Group chats require mentioning the bot (`@bot`) by default.
71
+
72
+ ## Files And Skills
73
+
74
+ - The agent can return generated files to the chat via the `send_file_to_chat` tool (path whitelist and size limit enforced).
75
+ - When `lark-cli` is installed, two optional skills are exposed: `lark-doc-cli` (Feishu documents) and `lark-im-readonly` (read-only IM inspection).
76
+ - The extension blocks `lark-cli im +messages-send / +messages-reply / +messages-receive` through bash, so replies always go through the pi-remote-feishu transport.
77
+
78
+ ## Docs
79
+
80
+ - [ARCHITECTURE.md](./ARCHITECTURE.md) — design document (English)
81
+ - [ARCHITECTURE.zh-CN.md](./ARCHITECTURE.zh-CN.md) — design document (中文)
82
+ - [`docs/`](./docs/00-README.md) — in-depth source code walkthrough
83
+ - [`tutorial/`](./tutorial/index.html) — HTML tutorial site (24 chapters)
package/README.md CHANGED
@@ -1,60 +1,83 @@
1
1
  # pi-remote-feishu
2
2
 
3
- Feishu transport and extension package for Pi Agent.
3
+ [English](./README.en.md) | 中文文档
4
4
 
5
- This package is designed as a separate extension project. It does not modify Pi core. The first implementation targets Feishu WebSocket, private chats, group chats, card interactions, session isolation, and file delivery through a Pi tool.
5
+ 通过 **飞书（Feishu / Lark）** 远程操控 **Pi Agent**。一个 WebSocket 桥接器，把飞书聊天变成完整的 Pi 交互界面——支持交互卡片、附件处理和文件回传。
6
6
 
7
- ## 📖 源码教程（面向教学）
7
+ 这是一个独立的 Pi 扩展项目，不修改 Pi 核心。
8
8
 
9
- > 🎓 两套教程内容同源，任选一种阅读方式：
9
+ ## 功能特性
10
10
 
11
- | 方式 | 位置 | 适合 |
12
- |---|---|---|
13
- | 🖥️ **HTML 教程站** | [`tutorial/`](./tutorial/index.html) | 边读边学、GitHub 直接预览、带导航/高亮 |
14
- | 📝 **Markdown 文档** | [`docs/`](./docs/00-README.md) | 快速检索、二次编辑、纯文本阅读 |
11
+ - 💬 **飞书 WebSocket 传输** — 长连接，无需公网服务器
12
+ - 🔒 **会话隔离** — 私聊按用户隔离；群聊可整群共享或按用户隔离（可配置）
13
+ - 🧠 **每个会话一个 Pi 运行时** — 会话文件持久化，重启后自动恢复
14
+ - 🃏 **交互卡片** — 模型选择、会话管理、停止/状态、权限确认
15
+ - 📎 **附件处理** — 图片（base64）、小文本（内联）、其他文件（下载落盘）
16
+ - 📤 **`send_file_to_chat` 文件回传** — 模型把生成的本地文件直接发回当前聊天
17
+ - 🧩 **可选 Lark CLI 技能** — 安装 `lark-cli` 后启用 `lark-doc-cli`、`lark-im-readonly`
18
+ - 🛡️ **安全护栏** — 拦截 `lark-cli im` 的发送/回复/接收命令
15
19
 
16
- ### HTML 教程站结构（3 部分 · 24 章）
20
+ ## 快速开始
17
21
 
18
- ```
19
- tutorial/
20
- ├── index.html ← 教程首页（从这里开始）
21
- ├── architecture/ 第一部分 · 架构设计（6 章）
22
- │ ├── 00-guide.html 教程导读
23
- │ ├── 01-overview.html 项目概览
24
- │ ├── 02-architecture.html 总体架构
25
- │ ├── 03-core-concepts.html 核心概念
26
- │ ├── 04-message-flow.html 消息处理全链路
27
- │ └── 05-design-decisions.html 关键设计决策
28
- ├── source/ 第二部分 · 源码解读（14 章）
29
- │ ├── 01-source-map.html 源码地图
30
- │ ├── 02-config.html 配置系统
31
- │ ├── 03-feishu-channel.html 通道层
32
- │ ├── 04-router-normalizer.html 路由与归一化
33
- │ ├── 05-session-host-manager.html 会话管理
34
- │ ├── 06-runtime-host.html 运行时封装
35
- │ ├── 07-stream-renderer.html 流式渲染
36
- │ ├── 08-ui-context.html UI 桥接与权限确认
37
- │ ├── 09-cards.html 卡片系统
38
- │ ├── 10-attachments.html 附件处理
39
- │ ├── 11-send-file-tool.html 文件回传工具
40
- │ ├── 12-store.html 存储
41
- │ ├── 13-bin-extensions.html 入口与扩展
42
- │ └── 14-testing-extending.html 测试与二次开发
43
- ├── interview/ 第三部分 · 面试准备（4 章）✨ 新增
44
- │ ├── 01-qa.html 面试问答 60 题
45
- │ ├── 02-patterns.html 设计模式与编程范式
46
- │ ├── 03-labs.html 动手实验室
47
- │ └── 04-cheatsheet.html 面试速查卡
48
- └── assets/ 共享样式与脚本（零依赖，GitHub 可直接预览）
22
+ ```bash
23
+ # 1. 安装并构建
24
+ npm install --ignore-scripts
25
+ npm run build
26
+
27
+ # 2. 生成配置模板（把 <你的Pi项目路径> 换成你的 Pi 工作目录）
28
+ node dist/bin/pi-remote-feishu.js init --cwd <你的Pi项目路径>
29
+
30
+ # 3. 编辑生成的配置：.pi/feishu.json
31
+ # - 填入你的飞书 appId / appSecret
32
+ # - 按需调整 policy / sessions / rendering 等选项
33
+
34
+ # 4. 启动桥接
35
+ node dist/bin/pi-remote-feishu.js serve --cwd <你的Pi项目路径>
49
36
  ```
50
37
 
51
- > `ARCHITECTURE.md` / `ARCHITECTURE.zh-CN.md` 是设计稿（规划怎么做），
52
- > `tutorial/` 与 `docs/` 是实现精读（实际代码怎么写的），两者互补。
38
+ 也可以用环境变量传入凭据：
53
39
 
54
- ## 快速开始
40
+ ```bash
41
+ export FEISHU_APP_ID="cli_xxx"
42
+ export FEISHU_APP_SECRET="xxx"
43
+ node dist/bin/pi-remote-feishu.js serve --cwd <你的Pi项目路径>
44
+ ```
45
+
46
+ ## CLI 命令
55
47
 
56
48
  ```bash
57
- npm install
58
- npm run build
59
- FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx node dist/bin/pi-remote-feishu.js serve
49
+ pi-remote-feishu serve # 启动飞书桥接（默认命令）
50
+ pi-remote-feishu init # 生成 .pi/feishu.json 配置模板
51
+ pi-remote-feishu doctor # 检查配置与 WebSocket 连通性
52
+ pi-remote-feishu send-test --chat-id <id> --text "hello" # 发送测试消息
53
+ pi-remote-feishu help # 查看帮助
60
54
  ```
55
+
56
+ 加 `--debug-events` 参数（或配置 `debug.logIncomingEvents: true`）可打印收到的消息/卡片摘要。
57
+
58
+ ## 飞书聊天命令
59
+
60
+ | 命令 | 说明 |
61
+ |---|---|
62
+ | `/help` | 查看帮助 |
63
+ | `/sessions` | 管理会话（查看/切换/删除） |
64
+ | `/models` | 选择模型和思考等级 |
65
+ | `/new` | 新建 Pi 会话 |
66
+ | `/stop` | 停止当前生成 |
67
+ | `/reset` | 重置当前会话映射 |
68
+ | `/status` | 查看连接/队列/模型状态 |
69
+
70
+ 群聊默认需要 @机器人 才会响应。
71
+
72
+ ## 文件与技能
73
+
74
+ - 模型可通过 `send_file_to_chat` 工具把生成的文件发回聊天（受目录白名单和大小上限限制）。
75
+ - 安装了 `lark-cli` 时，会暴露两个可选技能：`lark-doc-cli`（飞书文档）和 `lark-im-readonly`（只读 IM 查询）。
76
+ - 扩展会拦截通过 bash 执行的 `lark-cli im +messages-send / +messages-reply / +messages-receive`，保证回复始终走 pi-remote-feishu 自己的传输通道。
77
+
78
+ ## 文档
79
+
80
+ - [ARCHITECTURE.zh-CN.md](./ARCHITECTURE.zh-CN.md) — 设计文档（中文）
81
+ - [ARCHITECTURE.md](./ARCHITECTURE.md) — 设计文档（English）
82
+ - [`docs/`](./docs/00-README.md) — 源码精读文档
83
+ - [`tutorial/`](./tutorial/index.html) — HTML 教程站（24 章）
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-remote-feishu",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
4
4
  "description": "Remote control Pi Agent via Feishu (飞书) chat: WebSocket bridge, cards, attachments and file sending.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -42,7 +42,8 @@
42
42
  "skills",
43
43
  "ARCHITECTURE.md",
44
44
  "ARCHITECTURE.zh-CN.md",
45
- "README.md"
45
+ "README.md",
46
+ "README.en.md"
46
47
  ],
47
48
  "scripts": {
48
49
  "build": "tsc -p tsconfig.build.json",