dsh-channel-feishu 0.9.5 → 0.9.6

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.
package/README.md CHANGED
@@ -1,79 +1,22 @@
1
1
  # dsh-channel-feishu
2
2
 
3
- 给 DeepSeek Harness(DSH)装一条**专用飞书通道**:DSH 里的 Agent 可以把消息发到飞书,
4
- 用的是你自己在飞书开放平台新建的自建应用(独立机器人,不和 MyAgents 现有 4 个通道抢事件)。
3
+ 给 DeepSeek Harness(DSH)装一条**专用飞书通道**:DSH 里的 Agent 可以直接在飞书里聊,
4
+ 每轮答复自动回传成流式卡片,收到的图片和文件落进工作区,需要你拍板时发交互式问答卡。
5
5
 
6
- > **给 Agent:安装前必读 [AGENTS.md](AGENTS.md)。** 装完不等于可用——入站默认关闭,
7
- > 飞书应用、凭证、权限、发布版本都需要引导用户逐步完成,并按那里的验证清单跑通后再向用户反馈。
8
- > 人类用户可以直接读下面的"快速开始"。
6
+ 用的是你自己在飞书开放平台新建的自建应用(独立机器人),不和别的通道共用事件。
9
7
 
10
- ## 快速开始(人类)
8
+ ## 它提供什么
11
9
 
12
- 1. 飞书开放平台建**企业自建应用**(不是商店应用),开机器人能力,按"权限"一节开通 scope;
13
- 2. 事件订阅选**长连接**,加 `im.message.receive_v1`,**发布版本**并等审批;
14
- 3. 把 App ID / Secret 写进 `~/.dsh/feishu-channel.json`(或 DSH 凭据库);
15
- 4. 在 profile 的 `cordis.patch.yml` 打开 `inboundEnabled: true` 并填 `sessionId` / `allowedUsers`;
16
- 5. 飞书里发一条消息,看到流式卡片 + 思考过程即成功;失败先看 `~/.dsh/feishu-inbound.log`。
17
-
18
-
19
- ## 架构(v0.5.0:框架 + provider)
20
-
21
- ```
22
- index.js 通道框架:工具、入站投递、turn 回传、会话/工作区/权限/命名/状态/日志
23
- providers/registry.js provider 注册表:provider: 'feishu' → 工厂
24
- providers/feishu.js 飞书适配器:token、收发消息、附件上传、卡片、事件解析、长连接
25
- ```
26
-
27
- 框架不 import 任何飞书 API;它只调用 provider 的契约:
28
-
29
- | 方法 | 作用 |
30
- |---|---|
31
- | `settings()` | `{ appId, appSecret, region, baseUrl, defaultChatId }` |
32
- | `checkStatus(signal)` | 凭据/令牌状态 |
33
- | `sendText({ chatId, text })` | 发纯文本 |
34
- | `sendAttachment({ chatId, path, name })` | 发附件(图片或文件) |
35
- | `parseInbound(event)` | 归一化入站事件;`unsupported` 表示类型不支持 |
36
- | `downloadImage({ messageId, imageKey })` | 入站图片落盘,返回本地路径 |
37
- | `card.create/attach/update/close` | 流式卡片的四个原子操作 |
38
- | `connect({ onEvent, onState })` | 建长连接,返回清理函数 |
39
-
40
- 接新 IM = 写一个 `providers/<id>.js` 实现上表 + 在 `registry.js` 注册 + 配置 `provider: '<id>'`,
41
- `index.js` 一行不用改。
42
-
43
- ## 当前能力(v0.8.0)
44
-
45
- | 能力 | 作用 |
46
- |---|---|
47
- | 入站 | 飞书私信经 websocket 长连接投递进一个 DSH 会话,**正文就是用户原话**,不带任何路由提示词 |
48
- | 出站(自动) | 每轮结束时把该轮答复自动发回来源飞书会话;默认用 **CardKit 流式卡片**(打字机),失败降级为纯文本 |
49
- | `feishu_send_file` | 发**附件**:图片走 image 消息,其余走 file 消息(先上传拿 key,再发引用) |
50
- | `feishu_send_message` | 主动发到**别的**会话时才需要;来源会话的回复已自动回传,不要重复调用 |
51
- | `feishu_channel_status` | 报告通道是否配置、region / 默认目标,以及 tenant_access_token 能否取到 |
52
- | 问答卡 | 模型调用 `ask_user_question` 时,把问题发到来源飞书会话:**选项按钮**点选即答,或直接回复序号/选项文字/自由文本;超时按"跳过"结算,不挂死回合 |
53
-
54
- 设计要点:**通道是传输层,不是提示词约定**。飞书会话 id、发送者、回复目标都存在插件的
55
- sidecar(`feishu-channel-state.json` 的 `chats`,以及进程内的 chat memory),不进用户消息——
56
- 所以会话记录里不会出现 `[飞书私信] chat_id=…` 这类前缀,也不会逼模型每轮调工具。
57
-
58
- 出站链路(`apply` → `startInbound` 内注册监听):
59
-
60
- - `agent/assistant-stream` 的 `text-delta` → 节流写进本轮的卡片(**~120ms 一批,同一张卡串行写,sequence 严格递增**,接近打字机)
61
- - `session/event` 的 `assistant/message` → 提交该步正文
62
- - `session/event` 的 `turn/end` → 收尾:补最后一段、关闭 `streaming_mode`、写摘要
63
- - 本轮若已调用 `feishu_send_message`(卡片关闭或失败时)则跳过自动回传,避免双发
64
-
65
- **入站**接受纯文本、富文本(图文 post)和单张图片:post 抽文字、图片下载到本地并把路径写进消息;
66
- 文件/语音/卡片仍会丢弃并在日志里记原因。目标会话**不需要在 app 里打开**——没有活 agent 时插件
67
- 自己 `resume` 上次对话,会话还不存在时可以按 `sessionMode: create` 新建。
68
-
69
- 实现上没有依赖任何 npm 包:直接用平台 `fetch` 调飞书 Open API,并用 `ctx.tools.register()`
70
- 接受的原始 JSON Schema 形式声明工具(入站长连接额外用飞书官方 `@larksuiteoapi/node-sdk`,
71
- 缺它只是入站关闭,工具照常可用)。
10
+ - **双向通道**:飞书私聊 → DSH 会话;一轮结束把答复自动发回原聊天,不需要模型调工具
11
+ - **流式卡片**:思考过程单独一条消息,正文卡片逐字出现,底栏依次是 `等待回答 → 流式输出中 → 完成`
12
+ - **问答卡**:`ask_user_question` 渲染成按钮卡,选项一行一个、超过 3 项自动折叠;多题**逐题发**,答完才发下一题;答完的答复直接落在问答卡下方
13
+ - **附件**:入站图片和 `file` 消息(pdf/docx/xlsx/zip/音频)都下载到 `<workspacePath>/attachments/`,消息里附上绝对路径
14
+ - **会话自动创建**:全新安装时,第一条飞书消息会自动建会话和「飞书」工作区,不需要先手填 `sessionId`
15
+ - **桌面端镜像**:在桌面 GUI 里给同一会话发的消息,会以「来自桌面端:…」转发到飞书
16
+ - **诊断日志**:`~/.dsh/feishu-inbound.log`,JSONL、带 `level` 分级、4 MB 轮转
72
17
 
73
18
  ## 安装
74
19
 
75
- npm(<https://www.npmjs.com/package/dsh-channel-feishu>):
76
-
77
20
  ```bash
78
21
  dsh plugin add dsh-channel-feishu
79
22
  ```
@@ -82,334 +25,133 @@ dsh plugin add dsh-channel-feishu
82
25
 
83
26
  ```bash
84
27
  dsh plugin add https://github.com/Poy-Coder/dsh-channel-feishu
85
- dsh plugin add https://github.com/Poy-Coder/dsh-channel-feishu/releases/download/v0.9.5/dsh-channel-feishu-0.9.5.tgz
28
+ dsh plugin add https://github.com/Poy-Coder/dsh-channel-feishu/releases/download/v0.9.6/dsh-channel-feishu-0.9.6.tgz
86
29
  ```
87
30
 
88
- 依赖必须用扁平结构装(非 ASCII 目录下 pnpm 的软链会把路径写坏):
31
+ 依赖必须用扁平结构装(非 ASCII 目录下 pnpm 的软链会把路径写坏):`pnpm install --node-linker=hoisted`。
89
32
 
90
- ```bash
91
- pnpm install --node-linker=hoisted
92
- ```
33
+ 安装包的 bundle patch 会插入通道行并默认开启入站,装完重启一次即可;
34
+ 第一条飞书消息会自动建会话和「飞书」工作区,不需要先手填 `sessionId`。
93
35
 
94
- ### 启用入站(默认关闭)
36
+ 凭据写到 `~/.dsh/feishu-channel.json`(或设 `FEISHU_APP_ID` / `FEISHU_APP_SECRET`),
37
+ 也可以跑 `node scripts/setup.mjs`:它会从环境变量、现有凭据文件、各 profile 配置里找出
38
+ appId/appSecret,先用飞书接口校验 token,再以 UTF-8 无 BOM 写入。
95
39
 
96
- 新装的 bundle 只注册工具,`inboundEnabled` 默认是 `false`:不打开长连接、不接收飞书消息。要让它成为双向通道,在 profile 的 `cordis.patch.yml` 里覆盖(或用设置页表单):
97
-
98
- ```yaml
99
- - id: feishu-channel
100
- name: dsh-channel-feishu
101
- config:
102
- inboundEnabled: true
103
- sessionMode: create
104
- # 首次收消息时按此 id 建会话
105
- sessionId: session-<uuid>
106
- # 只允许你自己;留空表示任何人
107
- allowedUsers: ["ou_..."]
108
- # 省略则用 %USERPROFILE%\dsh-feishu
109
- workspacePath: ""
110
- permissionPreset: danger-full-access
111
- ```
112
-
113
- 入站是显式选择,因为它会让飞书里能发消息的人驱动本机 agent,并把该工作区的会话切到完全权限。
114
-
115
- ## 飞书应用类型:必须是「企业自建应用」
116
-
117
- | 类型 | 能不能用 | 原因 |
118
- |---|---|---|
119
- | **企业自建应用**(推荐,唯一顺畅路径) | 可以 | 自己租户内创建,能用**长连接**收事件、能申请全部 scope、发布由自己管理员审批 |
120
- | 商店应用 / ISV | 不行 | 面向其它租户分发,事件只能走公网 HTTP 回调(需要公网地址 + 验签解密),长连接不可用,多数权限要平台审核 |
121
- | 个人版 / 免费版租户 | 不完整 | `im:message.p2p_msg`、`contact:user.id:readonly`、`cardkit:card:write` 等 scope 通常需要企业租户 + 管理员审批发布 |
122
- | 群自定义机器人 webhook | 只能发 | 无法接收消息,做不了双向通道 |
123
-
124
- 关键动作顺序:**加机器人能力 → 开权限 → 事件订阅选长连接并加 `im.message.receive_v1` → 创建版本并发布 → 等管理员审批**。权限与事件订阅在版本发布前都不生效。
125
-
126
- ## 稳定性与语义
127
-
128
- | 话题 | 行为 |
129
- |---|---|
130
- | 历史消息 | **不补投**。长连接只接收建连之后的事件;DSH 关闭期间的消息不会在下次启动时补发(需要追溯就用 API 读会话) |
131
- | 重复事件 | 入站 `event_id` 去重并**持久化**在 `feishu-channel-state.json`(保留最近 400 条),重连/重启不会重复投递 |
132
- | 多客户端 | 飞书长连接是集群模式:同一 app 开两条连接,事件只会随机投给其中一个。**同一应用只跑一个 DSH**,要并行就用第二个应用 |
133
- | 从别的机器人切换过来 | 先停掉旧框架的长连接,否则两边抢事件;换用**另一个 app** 是安全的,会话与 chat 映射按会话 id 存,不依赖 app |
134
- | 限流 | 写卡 200ms/次(≤5 次/秒),遇 `230020` 退避 2 秒,终局 `close` 重试一次;不要调小间隔 |
135
- | 并发建卡 | 每轮单飞,`sequence` 严格递增,避免一张卡变多张 |
136
- | CoT 超长 | 飞书按 **UTF-8 字节**限长(不是字符),推理文本自动分片(每片 400 字符,事件内容上限 3000 字节) |
137
- | 工作区幂等 | 按 canonical 路径 `resolveByPath` → 复用;缺目录自动创建;更新插件不会重复建工作区 |
138
- | 默认路径 | 不落在 Windows 系统盘:优先非 C: 盘根目录,`workspacePath` 永远优先 |
139
-
140
- ## 与其他飞书 / IM 插件的区别
141
-
142
- | 维度 | 本插件 | 常见同类做法 |
143
- |---|---|---|
144
- | 入站提示词 | **原文直投**,会话记录里没有 chat id、没有"用某工具回复"的前缀 | 常在消息外再包一层说明与输出要求 |
145
- | 会话落点 | 桌面 profile 的「飞书」工作区:自动创建、先命名再挂载、无人值守权限预设 | 另起 headless 进程或独立会话目录,GUI 列表里看不到 |
146
- | 思考过程 | **飞书原生 CoT**(推理 + 工具调用带图标) | 多数没有,或只有一个"思考中"占位 |
147
- | 答案呈现 | CardKit 流式卡片(服务端打字机 + 200ms 增量 + 突发文本切片回放) | 整卡更新、无打字机,或纯文本 |
148
- | 附件 | 双向:入站图片落盘,出站 `feishu_send_file` 发图/文件 | 多为单向或缺失 |
149
- | 交互 | 原生 `/help /status /new /rename /stop /model /think`、问答卡(选项按钮) | 视项目而定,常见只有 `/new` |
150
- | 依赖 | 运行期 2 个(`@deepseek-ai/schemastery`、可选的 `@larksuiteoapi/node-sdk`) | 常见依赖 `lark-cli`、`@larksuite/channel` 等更重的栈 |
151
- | 配置 | `Config` schema(设置页表单)+ 凭据库,secret 不进 patch | 多为手改配置、secret 明文进配置文件 |
152
-
153
- ## 权限(飞书后台)
154
-
155
- - `im:message`、`im:message:send_as_bot`:发消息
156
- - `im:message.p2p_msg:readonly`(私聊)或 `im:message.group_at_msg:readonly`(群 @):收消息
157
- - `cardkit:card:write`:流式卡片;缺这条 `streamingCards` 会自动降级为纯文本
158
- - 事件订阅方式选 **使用长连接接收事件**,订阅 `im.message.receive_v1`,改完要**发布版本**才生效
159
-
160
-
161
- ## 一次性准备:创建飞书自建应用(约 5 分钟)
162
-
163
- 1. 打开 <https://open.feishu.cn/app>,开发者后台 → **创建企业自建应用**(名称例如 `DSH`)。
164
- 2. **凭证与基础信息** → 记下 `App ID` 与 `App Secret`。
165
- 3. **添加应用能力** → 勾选 **机器人**。
166
- 4. **权限管理** → 开通(至少):
167
- - `im:message`(读取与发送单聊、群组消息)
168
- - `im:message:send_as_bot`(以应用身份发消息)
169
- - 之后做入站还需要 `im:message:receive_v1` 相关事件权限
170
- 5. **版本管理与发布** → 创建版本 → 申请发布(企业内需管理员审批);审批通过后机器人才能对外发消息。
171
- 6. 把机器人加进目标群,或先在飞书里私聊机器人。
172
-
173
- ### 拿到目标 ID(open_id / user_id / chat_id)
174
-
175
- 飞书**客户端看不到 open_id / user_id**(个人资料页不展示),只能在开放平台侧取:
176
-
177
- | 想要 | 接口 | 需要的权限 | 本应用现状 |
178
- |---|---|---|---|
179
- | 应用可见范围内所有用户 open_id | `GET /open-apis/contact/v3/scopes` | 无需额外权限 | 可用,返回 `ou_xxxxxxxxxxxx`(= 应用创建者/你本人) |
180
- | 邮箱或手机号 → open_id | `POST /open-apis/contact/v3/users/batch_get_id?user_id_type=open_id`,body `{"emails":["..."]}` | `contact:user.id:readonly` | 未开通(报 99991672,按返回里的链接申请即可) |
181
- | 机器人所在群列表 → `oc_...` | `GET /open-apis/im/v1/chats` | `im:chat:read` | 可用(当前为空:机器人还没进群) |
182
- | 发送者是谁(事件回调) | 订阅 `im.message.receive_v1`,读事件里的 `sender.sender_id.open_id` | `im:message.p2p_msg:readonly` | 已具备权限;回调已是 **websocket 长连接**模式 |
183
- | user_id(企业内标识) | `contact:user.employee_id:readonly`(user token)或管理后台导出 | 按接口 | 未开通;机器人发送用 open_id 就够 |
184
-
185
- 本机实测结论(应用 `示例应用` / `cli_xxxxxxxxxxxx`):
186
-
187
- - `contact/v3/scopes` → `ou_xxxxxxxxxxxx`
188
- - 用它发消息成功,返回该单聊的 `chat_id` = `oc_xxxxxxxxxxxx`
189
- → 已写入 row config 的 `defaultChatId`,`feishu_send_message` 不带参数即可发到你的飞书单聊。
190
-
191
- 也可以不配默认值,每次调用显式传 `receiveId`:`oc_...` 自动按 `chat_id`,`ou_...` 按 `open_id`,
192
- 其它情况用 `receiveIdType` 指明(`email` / `user_id` / `union_id`)。
40
+ 允许名单:`allowedUsers` 留空时第一个发消息的人绑定该通道,其他发送者会被拒绝;
41
+ 想指定多人就显式列出 open_id。
193
42
 
194
43
  ## 配置
195
44
 
196
- 凭据按 **row config → 环境变量 → 凭据文件** 的优先级合并,任何一处给全即可。
45
+ ### 1. 凭据
197
46
 
198
- ### 方式 A(推荐):凭据文件,不写进 profile patch
199
-
200
- 编辑/新建 `~/.dsh/feishu-channel.json`:
47
+ 按优先级取第一个非空值:行 `config` → 环境变量 → 凭据文件。
201
48
 
202
49
  ```json
203
50
  {
204
- "appId": "cli_xxxxxxxxxxxx",
205
- "appSecret": "xxxxxxxxxxxxxxxx",
51
+ "appId": "cli_xxxxxxxxxxxxxxxx",
52
+ "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
206
53
  "region": "feishu",
207
- "defaultChatId": "oc_xxxxxxxxxxxx"
54
+ "defaultChatId": "oc_xxxxxxxxxxxxxxxx"
208
55
  }
209
56
  ```
210
57
 
211
- 插件最多每 5 秒重读一次该文件,改完直接重试工具即可(前提是新代码已加载,见下)。
212
- secret 留在 profile patch 之外;文件权限依赖用户目录本身。
58
+ 写到 `~/.dsh/feishu-channel.json`;也可以用环境变量 `FEISHU_APP_ID` / `FEISHU_APP_SECRET`。
59
+ `region` 中国大陆用 `feishu`,国际版用 `lark`。
60
+
61
+ 仓库自带一条命令完成"找凭据 + 校验 + 写文件":
213
62
 
214
- ### 方式 B:环境变量
63
+ ```bash
64
+ node <profile>/node_modules/dsh-channel-feishu/scripts/setup.mjs
65
+ ```
215
66
 
216
- 给 Harness 进程设 `FEISHU_APP_ID` / `FEISHU_APP_SECRET`(Windows 上从终端启动 Harness 时才方便)。
67
+ 它会扫描环境变量、现有凭据文件、各 profile 的 `cordis.patch.yml`,先用飞书接口验证 token,
68
+ 通过后才写入(UTF-8 无 BOM、`0600`)。**不要用 PowerShell 5.1 的 `Set-Content -Encoding UTF8`
69
+ 手写这个文件**:它会加 BOM,插件会加载失败。
217
70
 
218
- ### 方式 C:profile patch(会覆盖整段 config)
71
+ ### 2. profile 行
219
72
 
220
- **不要把 appSecret 写在这里。** patch 是整段替换,混入凭据后一旦被备份/贴图就泄漏;
221
- 凭据只放方式 A 的文件里,patch 只写行为字段:
73
+ 安装包自带的 bundle patch 会插入这一行,通常不需要手动加:
222
74
 
223
75
  ```yaml
224
76
  - id: feishu-channel
225
- name: 'dsh-channel-feishu'
77
+ name: "dsh-channel-feishu"
226
78
  config:
79
+ provider: feishu
227
80
  enabled: true
228
- inboundEnabled: true
229
- sessionId: 'session-xxxxxxxx-…'
230
- sessionMode: create
231
- allowedUsers: ['ou_…']
232
- streamingCards: true # 流式卡片;false 或权限缺失时自动降级纯文本
81
+ inboundEnabled: true # 收消息;关掉只剩发送工具
82
+ sessionMode: create # 没有会话时,第一条消息自动建
83
+ workspacePath: "" # 空 = <DSH_HOME>/dsh-feishu
84
+ allowedUsers: [] # 空 = 第一个发消息的人绑定此通道
85
+ streamingCards: true
86
+ autoReply: true
87
+ mirrorUserMessages: true # 桌面端消息转发到飞书
88
+ permissionPreset: danger-full-access
89
+ applyPermissionPreset: true
90
+ region: feishu
91
+ logLevel: info # debug | info | warn | error
233
92
  ```
234
93
 
235
- 注意:profile patch 语法错误会导致 Harness 启动失败;这个文件被 HMR 监视,改完即时生效。
94
+ `permissionPreset` 默认 `danger-full-access`:飞书是无值守通道,卡在授权确认上就永远没人点。
236
95
 
237
- ### 入站相关字段(都在同一个 config 里)
96
+ ### 3. 飞书侧
238
97
 
239
- ```yaml
240
- enabled: true
241
- inboundEnabled: true
242
- sessionId: 'session-3c379bd7-…' # 入站消息投递到哪个会话
243
- allowedUsers: # 只接受这些 open_id;留空/省略 = 不限制
244
- - 'ou_…'
245
- sessionMode: resume # resume(默认)| create | off
246
- streamingCards: true # 出站用 CardKit 流式卡片(默认 true)
247
- preset: cordis # 可选:固定 agent preset;省略则用会话里存的那个
248
- cwd: '<workspace>' # 仅在 create/新建会话时使用;省略则用插件所在工作区
249
- idleReleaseMinutes: 30 # 空闲多少分钟后交还 agent;0 = 保活到插件卸载
250
- logFile: 'C:\Users\…\feishu-inbound.log' # 省略则写 <DSH_HOME>/feishu-inbound.log
251
- stateFile: 'C:\Users\…\feishu-channel-state.json' # /new 切换的会话 + 会话→飞书 chat 映射
252
- notifyOnNew: true # /new 不带内容时,是否在飞书回一句确认
253
- workspacePath: '%USERPROFILE%\dsh-feishu' # 飞书会话的专用工作区目录(省略则用该默认值)
254
- inboundFilesDir: 'C:\Users\…\feishu-inbound-files' # 入站图片落盘目录(省略则同目录)
255
- ```
98
+ 1. 开放平台建**企业自建应用**,开「机器人」能力,加权限 `im:message`、`im:message:send_as_bot`、
99
+ `im:resource`(发文件用)、`im:message.react`(表情回执);
100
+ 2. 事件订阅选**长连接**,加 `im.message.receive_v1`;
101
+ 3. 发布版本并等审核通过。
256
102
 
257
- ### 权限(无人值守)
103
+ ## 允许名单
258
104
 
259
- 飞书轮次没有人在界面前点授权,`approval: ask` 会卡在第一次授权上,所以通道给**飞书工作区**
260
- 的会话套用固定预设:
105
+ `allowedUsers` 为空时**不是对所有人开放**:第一个给机器人发消息的人会被记为该通道的 owner,
106
+ 之后其他人发消息会被拒绝并收到一条说明。想换人或放开多人,显式写出 open_id:
261
107
 
262
108
  ```yaml
263
- permissionPreset: 'danger-full-access' # 默认值;applyPermissionPreset: false 可关闭
109
+ allowedUsers:
110
+ - "ou_xxxxxxxxxxxxxxxx"
264
111
  ```
265
112
 
266
- 生效范围是 `cwd` 等于 `workspacePath`(默认 `%USERPROFILE%\dsh-feishu`)的**所有**会话,包括:
267
-
268
- - 入站消息激活/新建的会话(`resume` / `create` / `/new` 三条路径都会调);
269
- - 你在 GUI 里于「飞书」工作区手动新建的会话(`turn/start` 时套用)。
113
+ owner 记在通道状态文件里,删掉状态文件里的 `owner` 字段即可重新绑定。
270
114
 
271
- `permissionPresets.current()` 先比对,已经在该预设上就不再写事件,所以每轮重复调用是幂等的。
272
- 想恢复逐次确认:把 `permissionPreset` 设成 `workspace-write` 或 `applyPermissionPreset: false`。
115
+ ## 会话
273
116
 
274
- ### 会话命名(列表里不出现无名条目)
117
+ - 全新安装:`sessionMode: create`,第一条消息自动建会话并挂到「飞书」工作区;
118
+ - `/new`:开一段新会话(可带内容 `/new 帮我看下 X`),切换结果写入状态文件,重启后仍有效;
119
+ - 每次切换都会给会话起一个可见标题,避免在 app 的会话列表里出现无名条目;
120
+ - 想切回配置里的会话:删掉状态文件里的 `sessionId` 字段。
275
121
 
276
- 工作区列表那一行读的是**挂载那一刻**的 projection cache;标题由模型异步生成,所以顺序必须是
277
- 「投递首条消息 → 生成标题 → 挂到工作区」,反过来就会留下没名字的行(客户端不会因标题后到而刷新该行)。
122
+ ## 命令
278
123
 
279
- 插件现在的顺序:
280
-
281
- 1. `sessionTitle.refresh()` 让模型生成标题(6 秒超时);
282
- 2. 模型失败、超时,或返回 `Greeting` / `New session` / `未命名` 这类占位词时,
283
- 用消息首行 `rename()` **钉住**一个短标题(`session/title` 事件,source=user);
284
- 3. 有了标题再 `attachSession()` 到 `workspacePath`;失败时也照样挂载,只是标题为空。
285
-
286
- 已有会话若标题仍是占位词,下一条消息到达时会被换成那一条的原话。
124
+ | 命令 | 作用 |
125
+ |---|---|
126
+ | `/help` | 命令列表 |
127
+ | `/status` | 当前会话、工作区、权限、入站状态 |
128
+ | `/new [内容]` | 开新会话(带内容则作为第一条消息) |
129
+ | `/rename <标题>` | 改名 |
130
+ | `/stop` | 中断进行中的回合 |
131
+ | `/model` | 看/切模型 |
132
+ | `/think` | 看/切思考强度 |
287
133
 
288
- ### 思考过程与消息反馈
134
+ 命令在插件侧拦截,不进模型、不占回合。
289
135
 
290
- - **原生思考过程(CoT)**:每轮开始 `POST /open-apis/im/v1/message_cot` 建一条独立的"思考过程"消息,推理增量走 `REASONING_MESSAGE_*`、工具调用走 `TOOL_CALL_START/ARGS/END/RESULT`,回合结束 `RUN_FINISHED`(出错则 `RUN_ERROR`)。飞书按它自己 agent 的样式渲染,所以工具调用有图标和标题。
291
- - **消息反应**:收到消息立即在你那条消息上加 `THINKING` 表情,回合结束移除,手机端一眼能看出"在处理"。
292
- - **卡片版式**:无标题栏、`width_mode: fill` 撑满、正文与灰色页脚之间有分隔线;页脚从"流式输出中"变成"完成"。
136
+ ## 日志
293
137
 
294
- 对应开关(默认全开):
138
+ `~/.dsh/feishu-inbound.log`,每行一条 JSON:
295
139
 
296
- ```yaml
297
- thinking: true # 显示思考过程
298
- thinkingHidden: false # 回合结束后折叠思考过程
299
- reactions: true # 加/移除 THINKING 反应
140
+ ```json
141
+ {"time":...,"level":"info","event":"inbound","result":"delivered","sessionId":"..."}
300
142
  ```
301
143
 
302
- ### 斜杠命令(在飞书里直接发,不消耗回合)
144
+ - `logLevel` 控制写入门槛,排查时设 `debug`;
145
+ - 超过 4 MB 轮转为 `.log.1`,只保留一份;
146
+ - 常见 `result`:`delivered`、`bootstrap`(自动建会话)、`owner-bound`、`dropped`(附 `reason`)、
147
+ `card-sent`、`answered`、`card-update-failed`。
303
148
 
304
- | 命令 | 作用 |
149
+ ## 常见问题
150
+
151
+ | 现象 | 处理 |
305
152
  |---|---|
306
- | `/help` | 命令清单 |
307
- | `/status` | 当前会话、标题、运行状态、工作区、权限、入站与目标群 |
308
- | `/new [内容]` | 开一段新会话;带内容则作为第一条消息 |
309
- | `/rename <标题>` | 给当前会话改名(钉住标题,模型不会再改) |
310
- | `/stop` | 中断进行中的回合(`agent.cancel({kind:'user'})`) |
311
-
312
- 命令在 `handleInboundEvent` 里被拦截:**既不会投递给模型,也不会写进会话记录**,只回一条飞书消息并把 `event=slash` 记进诊断日志。未识别的 `/xxx` 同样拦截并回帮助,避免误当任务执行。
313
-
314
- ### 入站工作方式
315
-
316
- 1. 飞书私信 → websocket 长连接 → `im.message.receive_v1` → 过滤(`allowedUsers`、消息类型、去重)→ 投递。
317
- 消息类型:`text` 直接取文本;`post`(图文富文本)抽出标题/正文,并把其中的 `img` 下载到
318
- `inboundFilesDir`;`image`(单图消息)下载那一条。图片最多取 4 张,文件名形如
319
- `<message_id>-<image_key 尾 10 位>.<webp|png|jpg|gif>`,消息里会附上本地绝对路径,agent 直接 `read_image` 就能看。
320
- 其它类型(`file`/`audio`/`media`/`sticker`/卡片)照旧丢弃,日志记 `dropped reason=non-text message_type=…`。
321
- 2. **开新会话**:在飞书发 `/new` 即新建一段对话并切过去(不带内容时用机器人回一句确认);
322
- `/new 帮我看下 X` 则把后面那句作为新会话的第一条消息。切换结果写进 `stateFile`,重启后依然有效。
323
- 想切回配置里的会话:删掉 `stateFile`(或把 `sessionId` 指过去后删掉它)。
324
- 3. 找 agent 的顺序(因此**不需要**把会话开在 app 里):
325
- - 已有活 agent → 直接用(app 的会话控制器也是先复用活 agent,所以你随后在 GUI 打开同一会话,
326
- 看到的是**同一个 agent、同一份对话**,不会互斥);
327
- - 否则 `ctx.agents.resume({ resumeSessionId: sessionId })` 激活上次对话
328
- (DSH 自带的无界面 ACP 客户端走的就是这条);
329
- - 再失败且 `sessionMode: create` → `ctx.agents.create()` 新建(`cwd` 用 `cwd` 配置值,
330
- 否则用 `workspacePath`,默认 `%USERPROFILE%\dsh-feishu`)。
331
- 注意:默认**续接原会话**;`create` 只是"会话不存在时"的兜底,不会主动新开一段对话。
332
- 4. **工作区归属**:插件新建的会话在建完立刻登记到 `workspacePath` 指向的「飞书」工作区
333
- (`workspaceRegistry.resolveByPath` → 没有就 `create` → `attachSession`),所以 GUI 的工作区
334
- 列表里会实时出现这些会话,不需要重开 app。
335
- 限制:DSH 的 `attachSession()` 会校验会话 header 的 `cwd` 必须等于工作区目录,因此
336
- **已有会话不能直接搬过来**——想让老会话进飞书工作区,只能让它以该目录为 cwd 重建。
337
- `workspaceRegistry` 不可用(DSH 大版本变化)时只设 cwd、不登记,投递照常。
338
- 4. resume/create 都会用 `ctx.get('agentPresets').resolve/mount` 挂上会话里存的 agent preset
339
- (和 app 打开会话时的组合完全一致)。不挂的话 agent 只剩全局注册的工具——本机实测 16 个,
340
- 挂上后 39 个(缺的那批是 `pwsh/read/write/edit/grep/glob` 等)。
341
- 5. 投递的消息是**完整带身份**的 user 消息(`id` + `role: 'user'` + `source` + `content`)。
342
- 缺 `id` 或 `role` 会让会话日志在下次加载时报 corrupt / 请求被 API 422 拒绝。
343
- 6. 空闲 `idleReleaseMinutes` 分钟后(且没有回合在跑)插件交还 agent;app 随后按需重新 resume,
344
- 所以释放是安全的,静默通道不占内存。
345
- 7. 每次入站的结论都写一行 JSONL 到 `logFile`:`delivered` / `dropped`(含原因)/ `error` /
346
- `release` / `switched`。飞书"发消息没反应"时先看这个文件。
347
-
348
- ### 飞书问答卡(ask_user_question)
349
-
350
- `ask_user_question` 在 DSH 里走 Agent 作用域的 `user-questions/request` 瀑布:Web GUI 用一个
351
- Remote Event 应答,**纯飞书会话没有浏览器页面时没有任何应答方**,工具调用会立刻以
352
- `NO_PROVIDER` 失败。插件现在组合了第二个应答方(`answerUserQuestion`):
353
-
354
- 1. 只认"从飞书会话发起、且在 chat memory 里"的问题(其他会话交给 GUI,`next()` 放行);
355
- 2. 发一张 schema 2.0 交互卡:每个选项一个 callback 按钮(`value: {c,q,o}`),多选另有「提交」,
356
- 每个问题另有「跳过」,卡底一条状态行(等待/已选/超时);
357
- 3. 点按钮 → `card.action.trigger` 经同一条长连接回到插件(`providers/feishu.js` 的 dispatcher
358
- 已注册),校验 `allowedUsers` 后结算;没有按钮回调时用户直接回复
359
- **序号 / 选项文字 / 自由文本 / 「跳过」** 也能答(单问题批次),该消息不再当成普通提问投递;
360
- 4. 超时(`questionTimeoutSeconds`,默认 600 秒,0 为不限)按"跳过"结算并在卡底记一笔;
361
- 卡片本身发不出去时降级为纯文本问题(文字回复照常可答)。
362
-
363
- 配置字段:
364
-
365
- | 字段 | 默认 | 作用 |
366
- |---|---|---|
367
- | `questionCards` | `true` | 关掉后问题只留在 Web GUI,飞书不接管 |
368
- | `questionTimeoutSeconds` | `600` | 等问题多久;`0` 表示一直等(不推荐,回合会挂着) |
369
-
370
- 日志新增 `question` 事件:`card-sent` / `text-sent` / `card-failed` / `answered`(含 `via: text`)/
371
- `timeout` / `skipped` / `aborted` / `card-dropped`,都在 `feishu-inbound.log` 里。
372
-
373
- **飞书后台要求**:按钮回调依赖应用订阅「卡片回传交互」事件(`card.action.trigger`,长连接即可);
374
- 没配也不影响文字回复路径。问题卡只发给**已知来源会话**(chat memory / `sessionId` + `defaultChatId`),
375
- 不会接管其它会话的问答。
376
-
377
- 已知限制(v0.8.0):文字回复只解析**单问题**批次,多问题批次需要点按钮;回答后用 cardkit 更新卡底
378
- 状态行,按钮仍留在卡上(重复点击会得到"这个问题已经结束"的 toast)。
379
-
380
- ### 什么时候要重启
381
-
382
- 装入新 bundle 时 HMR 会直接生效;但**替换已加载插件的 JS 代码需要重启一次 Harness**
383
- 才能加载新的模块代(profile 的 patch/manifest 变更不算)。本机就是这样:
384
- 插件装好后先加载的是 v0.1 代码,加入凭据文件支持后需要重启一次才认这个文件。
385
-
386
- ## 验证
387
-
388
- 在任意 DSH 会话里:
389
-
390
- 1. 调 `feishu_channel_status` → 应返回 `configured=true, tokenOk=true`;
391
- 2. 调 `feishu_send_message`,参数 `{"text":"DSH 通道测试"}`(配了 defaultChatId)→ 飞书应收到消息,返回 messageId。
392
-
393
- ## 已知边界
394
-
395
- - 入站支持**纯文本、富文本(图文 post)与单张图片**:post 抽文字 + 最多下载 4 张图,图片落到
396
- `inboundFilesDir` 并在消息里给出本地路径。`file`/`audio`/`media`/`sticker` 仍未支持;出站问答卡
397
- 的按钮回调已支持(见上),但**别人发的**任意交互卡片仍不会被处理。
398
- - token 按 appId 进程内缓存,提前 60s 过期;不做持久化。
399
- - 错误以工具错误结果返回(不会中断整轮对话),包含飞书 `code/msg`。
400
- - 入站要求飞书应用开通 `im.message.receive_v1` 事件(长连接模式)并已发布版本。
401
- - 入站自动 `resume`/`create` 出来的 agent 会用会话里存的 preset 组合(见上);但不会安装 API
402
- 控制器额外的模型选择控件,模型路由走 agent-loop 默认 + 会话 `request/header` 的历史选择。
403
- - 插件持有的 agent 空闲释放时若你正在 GUI 里看那个会话,视图会掉一次(下次交互会重新 resolve)。
404
- - 缺 `id`/`role` 的消息会写坏会话日志,且 DSH 目前只在加载时校验——所以投递形状由
405
- `test/smoke.mjs` 钉死,改动时别绕过。
406
-
407
- ## 开发
408
-
409
- ```powershell
410
- node test/smoke.mjs # 用假 ctx 校验注册、schema 子集与错误路径,不发网络请求
411
- node test/question-cards.mjs # 问答卡 JSON、按钮值、文字解析、卡片事件归一化(纯函数)
412
- node test/question-flow.mjs # 用假 provider 跑通整条问答链路:建卡、点按钮、超时、文字兜底
413
- node test/question-card-probe.mjs # 用真实凭据校验卡片 JSON(只建卡不发消息)
414
- node test/question-card-probe.mjs --send # 真发一张探针卡到默认群
415
- ```
153
+ | 装完能收到「通道已就绪」,发消息没反应 | 看日志有没有 `inbound`;老版本在无会话时会直接丢弃 |
154
+ | `card-update-failed` / `300309 streaming mode is closed` | 卡片不是流式模式,更新写不进去;0.9.0 起问答卡已开启流式 |
155
+ | 插件加载失败、工具全消失 | 检查 `package.json` 是否被写成带 BOM 的 UTF-8 |
156
+ | 发文件报权限错误 | 应用要开 `im:resource` 上传权限 |
157
+ | 同一 App 两条长连接 | 只能有一个通道插件用这个 App,旧通道要先 `disabled: true` |
package/docs/DETAIL.zh.md CHANGED
@@ -1 +1,10 @@
1
1
  ![飞书会话与 DSH 会话之间双向收发消息和附件](preview.svg)
2
+
3
+ # dsh-channel-feishu
4
+
5
+ 在飞书里和 DSH 里的 Agent 对话:流式卡片答复、交互式问答卡、图片与文件自动落盘到工作区。
6
+
7
+ - 安装:`dsh plugin add dsh-channel-feishu`
8
+ - 凭据:`~/.dsh/feishu-channel.json`(或 `FEISHU_APP_ID` / `FEISHU_APP_SECRET`)
9
+ - 一条命令写入凭据并校验:`node scripts/setup.mjs`
10
+ - 完整说明见仓库 README
package/index.js CHANGED
@@ -1887,6 +1887,14 @@ async function switchToNewSession(ctx, config, { chatId, senderId, firstMessage
1887
1887
  }
1888
1888
 
1889
1889
  await attachToFeishuWorkspace(ctx, config, sessionId)
1890
+ // Give the new session a name right away: an untitled row is easy to miss in
1891
+ // the app's session list, which is what "/new did nothing" looked like.
1892
+ try {
1893
+ const stamp = new Date().toLocaleString('zh-CN', { hour12: false }).replace(/\//g, '-')
1894
+ await ensureSessionTitle(ctx, config, handle.agent.session, `飞书会话 ${stamp}`)
1895
+ } catch (error) {
1896
+ warnTo(ctx, `session title failed: ${errorText(error)}`)
1897
+ }
1890
1898
  if (config.notifyOnNew === false) return
1891
1899
  try {
1892
1900
  await sendChannelText(config, chatId, `已开新会话 ${sessionId},接下来发消息都会进入这段对话。`)
@@ -2195,11 +2203,32 @@ export async function handleInboundEvent(ctx, config, data, seen) {
2195
2203
  const allowed = Array.isArray(config.allowedUsers)
2196
2204
  ? config.allowedUsers.map((value) => String(value)).filter(Boolean)
2197
2205
  : []
2198
- if (allowed.length > 0 && !allowed.includes(senderId)) {
2199
- warnTo(ctx, `ignored message from ${senderId}: not in allowedUsers`)
2200
- log({ event: 'inbound', result: 'dropped', reason: 'sender not in allowedUsers', senderId })
2201
- markSeen()
2202
- return
2206
+ // An empty allowlist is not "open to everyone": the first sender binds the
2207
+ // channel and later senders are refused. An unattended channel runs with
2208
+ // danger-full-access, so a stranger who finds the bot must not get a shell.
2209
+ if (allowed.length > 0) {
2210
+ if (!allowed.includes(senderId)) {
2211
+ warnTo(ctx, `ignored message from ${senderId}: not in allowedUsers`)
2212
+ log({ event: 'inbound', result: 'dropped', reason: 'sender not in allowedUsers', senderId })
2213
+ markSeen()
2214
+ return
2215
+ }
2216
+ } else {
2217
+ const owner = readChannelState(config).owner
2218
+ const ownerId = String(owner?.openId ?? '').trim()
2219
+ if (!ownerId) {
2220
+ writeChannelState(config, { owner: { openId: senderId, at: Date.now() } })
2221
+ log({ event: 'inbound', result: 'owner-bound', senderId, chatId: inbound.chatId })
2222
+ } else if (ownerId !== senderId) {
2223
+ log({ event: 'inbound', result: 'dropped', reason: 'sender is not the channel owner', senderId, ownerId })
2224
+ void sendChannelText(
2225
+ config,
2226
+ inbound.chatId,
2227
+ '这个飞书通道已绑定给其他用户使用。如需更换,请在 DSH 配置里显式设置 allowedUsers。',
2228
+ ).catch(() => {})
2229
+ markSeen()
2230
+ return
2231
+ }
2203
2232
  }
2204
2233
 
2205
2234
  const chatId = inbound.chatId
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "dsh-channel-feishu",
3
- "version": "0.9.5",
3
+ "version": "0.9.6",
4
4
  "type": "module",
5
- "description": "Feishu/Lark (椋炰功) channel for DeepSeek Harness: a chat bound to a DSH session, with streaming cards and attachments.",
5
+ "description": "Feishu/Lark (飞书) channel for DeepSeek Harness: a chat bound to a DSH session, with streaming cards and attachments.",
6
6
  "license": "MIT",
7
7
  "repository": {
8
8
  "type": "git",