BOT_GUIDE.zh-CN.md - DeepSeek-Reasonix

BOT_GUIDE.zh-CN.md

1	# Reasonix 机器人使用指南
2
3	<a href="../README.zh-CN.md">README</a>
4	·
5	<a href="./BOT_GUIDE.md">English</a>
6	·
7	<a href="./GUIDE.zh-CN.md">通用指南</a>
8
9	> 面向桌面端和 CLI 用户。本文说明如何连接飞书、Lark、微信和 QQ 机器人，
10	> 如何在 IM 里使用 Reasonix，以及审批、问答、YOLO 和常用命令的交互方式。
11
12	## 目录
13
14	- [能做什么](#能做什么)
15	- [在哪里运行](#在哪里运行)
16	- [连接四个渠道](#连接四个渠道)
17	- [无界面运行 Bot](#无界面运行-bot)
18	- [使用流程](#使用流程)
19	- [四种渠道的交互差异](#四种渠道的交互差异)
20	- [命令速查](#命令速查)
21	- [审批与 YOLO](#审批与-yolo)
22	- [升级后是否需要重新绑定](#升级后是否需要重新绑定)
23	- [排障](#排障)
24
25	## 能做什么
26
27	连接机器人后，你可以在飞书、Lark、微信或 QQ 里给 Reasonix 发消息，让桌面端
28	Reasonix 或 `reasonix bot start` 进程在本机执行同一套模型、工具、权限与
29	沙盒逻辑。
30
31	典型场景：
32
33	- 让 Reasonix 查代码、读文档、解释错误、整理结论。
34	- 在 IM 中触发工具调用，并把执行过程和结果回传到聊天窗口。
35	- 遇到写文件、执行命令等敏感操作时，在 IM 中审批或拒绝。
36	- 对临时测试任务开启 YOLO，跳过普通工具审批。
37	- 打开桌面端对应 IM 会话，继续查看上下文、成本、tokens 和工具轨迹。
38
39	## 在哪里运行
40
41	Bot gateway 是一套共享的 Go runtime。核心行为在 Windows、macOS 和 Linux
42	上都生效；实际差异主要来自各 IM 平台的凭据、网络、回调或 WebSocket 配置，
43	以及本机保存的账号状态。
44
45	目前有两个入口：
46
47	- 桌面端 runtime：在设置 -> 机器人中配置。桌面端会启动 gateway，
48	在应用内维护状态，持久化每个连接的工具审批模式变化，并允许打开匹配的
49	本地 IM 会话。
50	- CLI runtime：执行 `reasonix bot start` 启动无界面长期进程。它复用
51	与桌面端相同的配置、白名单、路由、队列设置、配对存储、适配器和
52	项目/会话索引。
53
54	普通 `reasonix run` 不会自动启动 IM 网关。只有桌面端 bot runtime 正在运行，
55	或存在一个存活的 `reasonix bot start` 进程时，远端 IM bot 能力才会生效。
56
57	## 连接四个渠道
58
59	打开桌面端 Reasonix，进入设置 -> 机器人。在添加 IM Bot 区域选择
60	渠道并扫码。
61
62	```mermaid
63	flowchart LR
64	A["打开桌面端设置"] --> B["机器人"]
65	B --> C["添加 IM Bot"]
66	C --> D{"选择渠道"}
67	D --> E["飞书扫码创建 PersonalAgent"]
68	D --> F["Lark 扫码创建 PersonalAgent"]
69	D --> G["微信扫码登录 Bot 助手"]
70	D --> H["QQ 手动配置 Bot 助手"]
71	E --> I["连接保存到本机"]
72	F --> I
73	G --> I
74	H --> I
75	I --> J["在 IM 中发送第一条消息"]
76	J --> K["桌面端创建对应会话"]
77	```
78
79	### 飞书
80
81	1. 在设置 -> 机器人 -> 添加 IM Bot 里选择飞书。
82	2. 点击生成二维码。
83	3. 用飞书扫码并完成授权。
84	4. 等待页面显示已连接。
85	5. 给飞书 Bot 发送消息，例如 `你好` 或 `帮我看一下这个报错`。
86
87	### Lark
88
89	1. 在设置 -> 机器人 -> 添加 IM Bot 里选择 Lark。
90	2. 点击生成二维码。
91	3. 用 Lark 扫码并完成授权。
92	4. 等待页面显示已连接。
93	5. 给 Lark Bot 发送消息。
94
95	飞书和 Lark 使用同一套能力，但作为两个独立连接保存。你可以给它们设置不同
96	模型、工作目录或工具审批模式。Bot 文本回复会以独立 Interactive Card JSON
97	2.0 markdown 发送，避免飞书/Lark 平台级引用前缀，同时保留 CommonMark
98	格式；如果卡片超过平台限制，Reasonix 会自动降级为纯文本。
99
100	Webhook 模式需要配置 verification token。传入事件会 fail-closed 校验：如果
101	配置中的 token 为空或缺失，调用方会被拒绝，不会静默开放 webhook。
102
103	### 微信
104
105	1. 在设置 -> 机器人 -> 添加 IM Bot 里选择微信。
106	2. 点击生成二维码。
107	3. 用微信扫码登录 Bot 助手。
108	4. 等待页面显示已连接。
109	5. 给微信 Bot 发送消息。
110
111	微信没有交互卡片按钮，因此审批通过数字或文字命令完成。Ask 问题可以直接
112	回复普通文本、选项编号，或使用 `/answer <id> <回答>`。
113
114	### QQ
115
116	1. 在设置 -> 机器人 -> 添加 IM Bot 里选择 QQ。
117	2. 填写 App ID 和 App Secret（或设置环境变量 `QQ_BOT_APP_SECRET`）。
118	3. 点击保存存储凭据。
119	4. 等待页面显示已连接。
120	5. 给 QQ Bot 发送消息。
121
122	QQ Bot 使用官方 QQ Bot 平台 API。它支持内联键盘按钮来完成审批。
123	Ask 问答会以文字形式发送；可以直接回复普通文本、选项编号，或使用
124	`/answer <id> <回答>`。当按钮过期或平台提示操作失败时，可以直接复制
125	卡片里的 ID，用文字命令继续。
126
127	QQ 不支持扫码连接，必须手动配置 App ID 和 App Secret。适配器只读取配置的
128	`app_secret_env`，不会再回退读取无关的 `QQ_SECRET` 环境变量。QQ 和微信的
129	HTTP 调用使用带超时的 client，避免平台请求卡住后无限阻塞 gateway。
130
131	## 无界面运行 Bot
132
133	桌面端是创建和测试 Bot 连接最简单的入口，但 Bot 运行时也可以作为长期运行的
134	无界面网关启动：
135
136	```sh
137	reasonix bot doctor
138	reasonix bot doctor --deep
139	reasonix bot start --channels qq,feishu,lark,weixin --dir /path/to/project
140	```
141
142	`--channels` 用来选择接受哪些已配置的 IM 输入。`feishu` 和 `lark` 会选择对应
143	飞书系连接，`weixin` 会选择已保存的微信 iLink 账号，`qq` 会选择已配置的 QQ
144	Bot。`--dir` 用来把远端消息绑定到某个项目工作区，`--model` 可以为这个进程
145	临时覆盖默认模型。
146
147	无界面网关复用桌面端保存的同一套配置：
148
149	- `[[bot.connections]]` 标识每个 IM 输入。`provider` 是适配器类型
150	（`feishu`、`weixin` 或 `qq`），`domain` 用来区分飞书和 Lark 等变体。
151	- `credential.app_id`、`credential.app_secret_env`、`credential.account_id`
152	和 `credential.token_env` 指向应用 ID、应用密钥、保存的账号或 token。
153	密钥仍保存在环境变量或 Reasonix 用户凭据中。
154	- `workspace_root`、`model` 和 `tool_approval_mode` 可以按连接单独设置，
155	因此不同 IM 渠道可以路由到不同本地项目或审批模式。
156	- `access` 也可以按连接单独设置，包括 `enabled`、`allow_all`、
157	`pairing_enabled`、`users`、`groups`、`admins` 和 `approvers`。当某个连接
158	有启用中的 access 配置时，会优先检查该连接自己的访问控制，再退回旧的全局
159	`[bot.allowlist]`。
160	- `[[bot.routes]]` 可以继续按远端连接、平台、会话类型、chat ID、用户 ID
161	或 thread ID 做更细粒度路由；空匹配字段表示通配，按配置顺序第一个命中。
162	命中后可覆盖 `workspace_root`、`model` 和 `tool_approval_mode`。
163	- `session_mappings` 会根据收到的远端消息自动填充远端 chat ID 和作用域。
164	只有当该映射同时具备本地 `session_id` 目标时，桌面端才能打开对应会话；
165	例如桌面端托管的 Bot runtime 保存了 `path:` 会话目标，或用户手动配置了
166	映射目标。
167	- Bot 的项目/会话索引只来自已配置的 `workspace_root`、route workspace、
168	当前活跃 bot 会话，以及已保存的 `session_mappings`。`/use project` 和
169	`/attach session` 只能跳到这些已索引目标；IM 文本里临时输入的任意本地
170	目录不会被接受。
171
172	访问控制仍然是必需项。桌面端新建的 Bot 通常建议在该 Bot 自己的详情面板里
173	设置谁可以使用，这会保存到 `[[bot.connections]]` 或 `[bot.qq].access`。
174	旧的全局 `[bot.allowlist]` 仍然作为兼容兜底，适用于旧配置或没有启用单
175	Bot access 的连接。你可以有意设置 `allow_all = true`，也可以为单个 Bot
176	启用 `pairing_enabled`，或全局启用 `[bot.pairing]`，让未知私聊用户先收到
177	一次性配对码。配对码需要在本机执行 `reasonix bot pairing approve <code>`
178	后才会放行；如果该请求带有连接 ID，批准后会把发送者加入对应 Bot 自己的
179	access 名单。列在 `admins` / `approvers` 或旧的 `*_admins` /
180	`*_approvers` 里的用户也会获得基础 bot 准入，不需要再重复写进 `users` /
181	`*_users`。群聊不会因为私聊配对或角色准入自动开放，群 ID 仍是额外收窄
182	条件。常用配对管理命令：
183
184	```sh
185	reasonix bot pairing list
186	reasonix bot pairing approve CODE
187	reasonix bot pairing reject CODE
188	```
189
190	如果配置了 `qq_admins`、`feishu_admins`、`weixin_admins` 或对应
191	`*_approvers`，`/yolo`、`/mode` 等运行模式命令只允许 admin 使用；
192	`/projects`、`/use project`、`/sessions`、`/attach session` 和
193	`/search all` 也只允许 admin 使用。`/approve` 和 `/deny` 只允许 approver
194	或 admin 使用。没有配置角色列表时，为兼容旧配置，已允许的用户保持原有
195	命令能力。远端用户进入的是同一个 Reasonix controller、权限策略、工具
196	审批模式和沙盒边界，和本地桌面端或 CLI 回合一致。
197
198	```toml
199	[bot.allowlist]
200	enabled = true
201	feishu_users = ["ou_member"]
202	feishu_admins = ["ou_admin"]
203	feishu_approvers = ["ou_approver"]
204	```
205
206	默认启用 `ignore_self_messages = true`。网关会记录刚发出的平台
207	`message_id`，并忽略平台回传的同 ID 消息；如果某个平台不会稳定回传同一
208	消息 ID，可以在 `[bot.self_user_ids]` 里配置 bot 自己的用户 ID 作为第二层
209	回声防护。`/status` 会显示当前会话队列模式和各连接的健康状态，例如
210	`feishu-lark=running` 或 `weixin-weixin=degraded`。
211
212	可选的 `[bot.control]` 提供本机 loopback HTTP API，默认关闭。启用后必须
213	设置 `token_env` 对应的环境变量，所有请求都需要
214	`Authorization: Bearer <token>`；地址只能绑定 `localhost`、`127.0.0.1`
215	或 `::1`。当前接口包括 `GET /status`（会话与连接健康快照）和
216	`GET /metrics`（Prometheus 文本指标）以及 `POST /send`（向指定连接发送
217	文本或媒体消息）。
218
219	示例：
220
221	```sh
222	export REASONIX_BOT_CONTROL_TOKEN="change-me"
223
224	curl -H "Authorization: Bearer $REASONIX_BOT_CONTROL_TOKEN" \
225	http://127.0.0.1:37913/status
226
227	curl -X POST http://127.0.0.1:37913/send \
228	-H "Authorization: Bearer $REASONIX_BOT_CONTROL_TOKEN" \
229	-H "Content-Type: application/json" \
230	-d '{
231	"connection_id": "feishu-lark",
232	"domain": "lark",
233	"chat_id": "oc_xxx",
234	"chat_type": "dm",
235	"text": "hello from local control API"
236	}'
237	```
238
239	## 使用流程
240
241	```mermaid
242	sequenceDiagram
243	participant U as "用户"
244	participant IM as "飞书 / Lark / 微信 / QQ"
245	participant R as "Reasonix 桌面端或 bot start"
246	participant T as "本机工具与模型"
247
248	U->>IM: "发送需求"
249	IM->>R: "消息进入本机 Bot 网关"
250	R->>T: "模型思考并调用工具"
251	alt "普通回复"
252	R-->>IM: "返回答案"
253	else "需要审批"
254	R-->>IM: "发送审批卡片或审批文本"
255	U->>IM: "允许 / 拒绝"
256	IM->>R: "审批命令"
257	R->>T: "继续或停止工具调用"
258	R-->>IM: "返回结果"
259	else "需要用户选择"
260	R-->>IM: "发送 Ask 问题"
261	U->>IM: "选择选项或回复 /answer"
262	R-->>IM: "继续执行并返回结果"
263	end
264	```
265
266	桌面端左侧的机器人入口会显示已连接 Bot。收到第一条 IM 消息后，可以
267	从这里打开对应本地会话，查看上下文、工具轨迹、成本和运行指标。
268
269	## 四种渠道的交互差异
270
271	下面三张图是虚构内容的交互示意，用来帮助理解真实软件里的操作形态。
272
273	![飞书审批卡片示意](./assets/bot-feishu-approval.svg)
274
275	![Lark 开启 YOLO 示意](./assets/bot-lark-yolo.svg)
276
277	![微信文字命令示意](./assets/bot-weixin-text-commands.svg)
278
279	![QQ 审批卡片示意](./assets/bot-qq-approval.svg)
280
281	\| 渠道 \| 连接方式 \| 审批方式 \| Ask 问答 \| 适合场景 \|
282	\| --- \| --- \| --- \| --- \| --- \|
283	\| 飞书 \| 扫码创建 PersonalAgent \| 交互卡片按钮，也可用命令 \| 交互卡片按钮，也可用命令 \| 国内飞书工作流、群聊或个人助手 \|
284	\| Lark \| 扫码创建 PersonalAgent \| 交互卡片按钮，也可用命令 \| 交互卡片按钮，也可用命令 \| 国际版 Lark 工作流 \|
285	\| 微信 \| 微信扫码登录 \| 回复 `1` / `2` 或命令 \| 回复普通文本、选项编号或命令 \| 微信个人测试、轻量移动触发 \|
286	\| QQ \| 手动配置（App ID + App Secret） \| 内联键盘按钮、数字回复或命令 \| 回复普通文本、选项编号或命令 \| QQ 群聊、个人会话和官方 QQ Bot 平台 \|
287
288	飞书和 Lark 的卡片按钮会在后台转换为命令，例如 `/approve <id>`、
289	`/deny <id>` 或 `/answer <id> <选项>`。QQ 的审批按钮也是如此。
290	如果按钮过期或平台提示操作失败，可以直接复制卡片里的 ID，用文字
291	命令继续。
292
293	## 命令速查
294
295	这些命令在飞书、Lark、微信和 QQ 中通用。
296
297	\| 命令 \| 作用 \| 示例 \|
298	\| --- \| --- \| --- \|
299	\| `/help` \| 查看可用命令 \| `/help` \|
300	\| `/status` \| 查看活跃任务、队列、工具审批模式和连接健康 \| `/status` \|
301	\| `/stop` \| 停止当前任务 \| `/stop` \|
302	\| `/new` \| 开始新会话 \| `/new` \|
303	\| `/reset` \| 重置当前会话 \| `/reset` \|
304	\| `/approve <id>` \| 批准待审批操作 \| `/approve 1` \|
305	\| `/deny <id>` \| 拒绝待审批操作 \| `/deny 1` \|
306	\| `/answer <id> <选项>` \| 回答 Ask 问题 \| `/answer ask-1 2` \|
307	\| `/yolo` \| 开启 YOLO \| `/yolo` \|
308	\| `/yolo on` \| 开启 YOLO \| `/yolo on` \|
309	\| `/yolo off` \| 切回询问模式 \| `/yolo off` \|
310	\| `/yolo auto` \| 切换到自动审批模式 \| `/yolo auto` \|
311	\| `/yolo status` \| 查看当前工具审批模式 \| `/yolo status` \|
312	\| `/mode yolo` \| 切换到 YOLO \| `/mode yolo` \|
313	\| `/mode ask` \| 切换到询问模式 \| `/mode ask` \|
314	\| `/mode auto` \| 切换到自动模式 \| `/mode auto` \|
315	\| `/queue status` \| 查看当前队列模式 \| `/queue status` \|
316	\| `/queue steer` \| 运行中消息作为当前任务补充 \| `/queue steer` \|
317	\| `/queue followup` \| 运行中消息排队为后续回合 \| `/queue followup` \|
318	\| `/queue collect` \| 合并排队消息为一个后续回合 \| `/queue collect` \|
319	\| `/queue interrupt` \| 取消当前任务并处理最新消息 \| `/queue interrupt` \|
320	\| `/projects [关键词]` \| 查看已索引项目工作区 \| `/projects reasonix` \|
321	\| `/use project <id\\|名称>` \| 将当前远端会话路由到已索引项目 \| `/use project p1` \|
322	\| `/use project default` \| 清除项目覆盖，恢复配置路由 \| `/use project default` \|
323	\| `/sessions search <关键词>` \| 搜索已索引桌面/bot 会话 \| `/sessions search 发布 bug` \|
324	\| `/attach session <id\\|关键词>` \| 从已索引 `path:` transcript 继续当前远端会话 \| `/attach session s1` \|
325	\| `/search all <关键词>` \| 跨已索引项目检索文件内容 \| `/search all TODO` \|
326
327	快捷回复：
328
329	- 有待审批操作时，回复 `1` 表示批准，回复 `2` 表示拒绝。
330	- 有待处理 Ask 问题时，可以直接回复任意普通非 slash 文本；选择题仍然可以
331	直接回复选项编号。
332	- `/stop`、`/mode`、`/answer ...` 等 slash 命令不会被 Ask 快捷回复截获。
333	- 如果没有待处理操作，`1` / `2` 会被当作普通消息或收到提示。
334
335	默认队列模式是 `steer`：同一会话正在运行时，新消息会作为当前任务的
336	mid-turn guidance 注入，而不是等完整回合结束。`queue_cap` 和 `queue_drop`
337	可以在配置里限制排队堆积；`reasonix bot doctor --deep` 会显示当前队列、
338	配对和角色诊断信息。
339
340	队列模式：
341
342	- `steer`：运行中的消息会尽量作为当前回合的补充指导。
343	- `followup`：运行中的消息排队成为后续回合。
344	- `collect`：把排队消息合并成一个后续回合。
345	- `interrupt`：取消当前回合，并保留最新消息作为下一回合。
346
347	项目与会话跳转：
348
349	- `/projects [关键词]` 会列出来自 bot route、连接工作区、活跃 bot 会话和
350	已保存 session mapping 的工作区。
351	- `/use project <id\|名称>` 会把当前远端会话固定到某个已索引项目；
352	`/use project default` 会清除覆盖。
353	- `/sessions search <关键词>` 搜索已索引桌面端和 bot 会话元数据。
354	- `/attach session <id\|关键词>` 从已索引 `path:` transcript 继续当前远端
355	会话。
356	- `/search all <关键词>` 跨已索引项目根目录检索文件内容；有 `rg` 时优先用
357	`rg`，否则使用带边界的 Go fallback scanner。
358
359	这些跳转命令不会接受 IM 中临时输入的任意本地路径，只能跳到索引内目标；
360	配置了角色列表时，这些命令需要 admin 权限。
361
362	当适配器提供媒体 URL 时，gateway 会把文件下载到当前工作区的
363	`.reasonix/attachments`，并以 `@.reasonix/attachments/...` 形式传给
364	Reasonix。保存失败的附件会在 IM 中提示，文本内容仍会继续处理。内置
365	Feishu、Weixin、QQ 适配器当前仍以文本事件为主，普通 IM 附件抽取可以继续在
366	适配器层补齐。
367
368	## 审批与 YOLO
369
370	Reasonix 的机器人沿用桌面端权限系统。默认是询问模式：写文件、执行命令等
371	敏感工具调用会先请求确认。
372
373	```mermaid
374	flowchart TD
375	A["模型准备调用工具"] --> B{"是否命中 deny 规则"}
376	B -- "是" --> C["直接拒绝"]
377	B -- "否" --> D{"工具审批模式"}
378	D -- "询问 Ask" --> E["向 IM 发送审批"]
379	D -- "自动 Auto" --> F["策略允许时自动放行"]
380	D -- "YOLO" --> G["普通工具审批自动放行"]
381	E --> H{"用户选择"}
382	H -- "允许" --> I["执行工具"]
383	H -- "拒绝" --> J["停止该操作"]
384	F --> I
385	G --> I
386	```
387
388	YOLO 的边界很重要：
389
390	- YOLO 会跳过普通工具审批。
391	- YOLO 不会跳过硬性 `deny` 规则。
392	- YOLO 不会自动回答模型提出的 Ask 问题。
393	- YOLO 不会自动批准计划模式里的计划批准。
394
395	建议：
396
397	- 临时调试、可信项目、需要快速连续读写时，可以用 `/yolo`。
398	- 做高风险操作、生产代码或不确定任务时，用 `/mode ask` 切回询问模式。
399	- 想减少普通审批但保留策略判断时，用 `/mode auto`。
400
401	## 升级后是否需要重新绑定
402
403	正常升级或覆盖安装 Reasonix app 后，不需要重新绑定。
404
405	绑定信息保存在用户配置目录，而不是 app 包内：
406
407	- Bot 连接、远端 ID、白名单、模型和审批模式保存在用户配置文件。
408	- 飞书和 Lark 的密钥保存在 CLI 与桌面端共用的 Reasonix 全局
409	`<Reasonix home>/.env`。
410	- 微信扫码后的账号 token 保存在 Reasonix 的用户数据目录。
411	- QQ 的 App ID 保存在用户配置文件；App Secret 通过配置的环境变量
412	（默认 `QQ_BOT_APP_SECRET`）保存在 Reasonix 全局凭据文件中。
413
414	需要重新扫码或重新配置的情况：
415
416	- 删除了 Reasonix 用户配置目录。
417	- 换了 macOS 用户或换了机器。
418	- 平台侧撤销授权。
419	- 微信 token 失效。
420	- 飞书或 Lark 应用密钥被清除。
421	- QQ 的 App ID 或 App Secret 失效或被更改。
422
423	## 排障
424
425	\| 现象 \| 可以检查 \|
426	\| --- \| --- \|
427	\| 扫码提示链接失效 \| 回到设置页重新生成二维码；二维码有有效期（飞书、Lark、微信；QQ 不使用扫码，请检查手动配置）。 \|
428	\| 已连接但没有回复 \| 确认桌面端 bot runtime 或 `reasonix bot start` 进程正在运行，Bot 连接已开启，用户 ID 在白名单内、已配对或允许所有人。 \|
429	\| 飞书或 Lark 按钮提示失败 \| 直接发送卡片里的命令，例如 `/approve <id>` 或 `/deny <id>`。 \|
430	\| QQ 按钮提示失败 \| 与飞书/Lark 相同 —— 直接发送卡片里的命令，例如 `/approve <id>` 或 `/deny <id>`。 \|
431	\| 微信回复 `1` 没反应 \| 只有存在待审批或 Ask 时数字快捷回复才生效；也可以使用完整命令。 \|
432	\| QQ 回复 `1` 没反应 \| 与微信相同 —— 只有存在待审批或 Ask 时数字快捷回复才生效；也可以使用完整命令。 \|
433	\| 想确认当前模式 \| 发送 `/status` 或 `/yolo status`。 \|
434	\| 想重新开始上下文 \| 发送 `/new` 或 `/reset`。 \|
435	\| 想停止当前任务 \| 发送 `/stop`。 \|
436
437	如果仍然无法连通，可以在设置 -> 机器人中打开对应 Bot 的高级设置，使用
438	检查配置、测试发送和运行设置来定位问题。
439

439 lines MARKDOWN