esengine--deepseek-reasonix/docs/BOT_GUIDE.zh-CN.md

Reasonix 机器人使用指南

README  ·  English  ·  通用指南

面向桌面端和 CLI 用户。本文说明如何连接飞书、Lark、微信和 QQ 机器人， 如何在 IM 里使用 Reasonix，以及审批、问答、YOLO 和常用命令的交互方式。

目录

• 能做什么
• 在哪里运行
• 连接四个渠道
• 无界面运行 Bot
• 使用流程
• 四种渠道的交互差异
• 命令速查
• 审批与 YOLO
• 升级后是否需要重新绑定
• 排障

能做什么

连接机器人后，你可以在飞书、Lark、微信或 QQ 里给 Reasonix 发消息，让桌面端 Reasonix 或 reasonix bot start 进程在本机执行同一套模型、工具、权限与 沙盒逻辑。

典型场景：

• 让 Reasonix 查代码、读文档、解释错误、整理结论。
• 在 IM 中触发工具调用，并把执行过程和结果回传到聊天窗口。
• 遇到写文件、执行命令等敏感操作时，在 IM 中审批或拒绝。
• 对临时测试任务开启 YOLO，跳过普通工具审批。
• 打开桌面端对应 IM 会话，继续查看上下文、成本、tokens 和工具轨迹。

在哪里运行

Bot gateway 是一套共享的 Go runtime。核心行为在 Windows、macOS 和 Linux 上都生效；实际差异主要来自各 IM 平台的凭据、网络、回调或 WebSocket 配置， 以及本机保存的账号状态。

目前有两个入口：

• 桌面端 runtime：在 设置 -> 机器人 中配置。桌面端会启动 gateway， 在应用内维护状态，持久化每个连接的工具审批模式变化，并允许打开匹配的 本地 IM 会话。
• CLI runtime：执行 reasonix bot start 启动无界面长期进程。它复用 与桌面端相同的配置、白名单、路由、队列设置、配对存储、适配器和 项目/会话索引。

普通 reasonix run 不会自动启动 IM 网关。只有桌面端 bot runtime 正在运行， 或存在一个存活的 reasonix bot start 进程时，远端 IM bot 能力才会生效。

连接四个渠道

打开桌面端 Reasonix，进入 设置 -> 机器人。在 添加 IM Bot 区域选择 渠道并扫码。

flowchart LR
  A["打开桌面端设置"] --> B["机器人"]
  B --> C["添加 IM Bot"]
  C --> D{"选择渠道"}
  D --> E["飞书扫码创建 PersonalAgent"]
  D --> F["Lark 扫码创建 PersonalAgent"]
  D --> G["微信扫码登录 Bot 助手"]
  D --> H["QQ 手动配置 Bot 助手"]
  E --> I["连接保存到本机"]
  F --> I
  G --> I
  H --> I
  I --> J["在 IM 中发送第一条消息"]
  J --> K["桌面端创建对应会话"]

飞书

1. 在 设置 -> 机器人 -> 添加 IM Bot 里选择 飞书。
2. 点击生成二维码。
3. 用飞书扫码并完成授权。
4. 等待页面显示已连接。
5. 给飞书 Bot 发送消息，例如 你好 或 帮我看一下这个报错。

Lark

1. 在 设置 -> 机器人 -> 添加 IM Bot 里选择 Lark。
2. 点击生成二维码。
3. 用 Lark 扫码并完成授权。
4. 等待页面显示已连接。
5. 给 Lark Bot 发送消息。

飞书和 Lark 使用同一套能力，但作为两个独立连接保存。你可以给它们设置不同 模型、工作目录或工具审批模式。Bot 文本回复会以独立 Interactive Card JSON 2.0 markdown 发送，避免飞书/Lark 平台级引用前缀，同时保留 CommonMark 格式；如果卡片超过平台限制，Reasonix 会自动降级为纯文本。

Webhook 模式需要配置 verification token。传入事件会 fail-closed 校验：如果 配置中的 token 为空或缺失，调用方会被拒绝，不会静默开放 webhook。

微信

1. 在 设置 -> 机器人 -> 添加 IM Bot 里选择 微信。
2. 点击生成二维码。
3. 用微信扫码登录 Bot 助手。
4. 等待页面显示已连接。
5. 给微信 Bot 发送消息。

微信没有交互卡片按钮，因此审批通过数字或文字命令完成。Ask 问题可以直接 回复普通文本、选项编号，或使用 /answer <id> <回答>。

QQ

1. 在 设置 -> 机器人 -> 添加 IM Bot 里选择 QQ。
2. 填写 App ID 和 App Secret（或设置环境变量 QQ_BOT_APP_SECRET）。
3. 点击 保存 存储凭据。
4. 等待页面显示已连接。
5. 给 QQ Bot 发送消息。

QQ Bot 使用官方 QQ Bot 平台 API。它支持内联键盘按钮来完成审批。 Ask 问答会以文字形式发送；可以直接回复普通文本、选项编号，或使用 /answer <id> <回答>。当按钮过期或平台提示操作失败时，可以直接复制 卡片里的 ID，用文字命令继续。

QQ 不支持扫码连接，必须手动配置 App ID 和 App Secret。适配器只读取配置的 app_secret_env，不会再回退读取无关的 QQ_SECRET 环境变量。QQ 和微信的 HTTP 调用使用带超时的 client，避免平台请求卡住后无限阻塞 gateway。

无界面运行 Bot

桌面端是创建和测试 Bot 连接最简单的入口，但 Bot 运行时也可以作为长期运行的 无界面网关启动：

reasonix bot doctor
reasonix bot doctor --deep
reasonix bot start --channels qq,feishu,lark,weixin --dir /path/to/project

--channels 用来选择接受哪些已配置的 IM 输入。feishu 和 lark 会选择对应 飞书系连接，weixin 会选择已保存的微信 iLink 账号，qq 会选择已配置的 QQ Bot。--dir 用来把远端消息绑定到某个项目工作区，--model 可以为这个进程 临时覆盖默认模型。

无界面网关复用桌面端保存的同一套配置：

• [[bot.connections]] 标识每个 IM 输入。provider 是适配器类型 （feishu、weixin 或 qq），domain 用来区分飞书和 Lark 等变体。
• credential.app_id、credential.app_secret_env、credential.account_id 和 credential.token_env 指向应用 ID、应用密钥、保存的账号或 token。 密钥仍保存在环境变量或 Reasonix 用户凭据中。
• workspace_root、model 和 tool_approval_mode 可以按连接单独设置， 因此不同 IM 渠道可以路由到不同本地项目或审批模式。
• access 也可以按连接单独设置，包括 enabled、allow_all、 pairing_enabled、users、groups、admins 和 approvers。当某个连接 有启用中的 access 配置时，会优先检查该连接自己的访问控制，再退回旧的全局 [bot.allowlist]。
• [[bot.routes]] 可以继续按远端连接、平台、会话类型、chat ID、用户 ID 或 thread ID 做更细粒度路由；空匹配字段表示通配，按配置顺序第一个命中。 命中后可覆盖 workspace_root、model 和 tool_approval_mode。
• session_mappings 会根据收到的远端消息自动填充远端 chat ID 和作用域。 只有当该映射同时具备本地 session_id 目标时，桌面端才能打开对应会话； 例如桌面端托管的 Bot runtime 保存了 path: 会话目标，或用户手动配置了 映射目标。
• Bot 的项目/会话索引只来自已配置的 workspace_root、route workspace、 当前活跃 bot 会话，以及已保存的 session_mappings。/use project 和 /attach session 只能跳到这些已索引目标；IM 文本里临时输入的任意本地 目录不会被接受。

访问控制仍然是必需项。桌面端新建的 Bot 通常建议在该 Bot 自己的详情面板里 设置谁可以使用，这会保存到 [[bot.connections]] 或 [bot.qq].access。 旧的全局 [bot.allowlist] 仍然作为兼容兜底，适用于旧配置或没有启用单 Bot access 的连接。你可以有意设置 allow_all = true，也可以为单个 Bot 启用 pairing_enabled，或全局启用 [bot.pairing]，让未知私聊用户先收到 一次性配对码。配对码需要在本机执行 reasonix bot pairing approve <code> 后才会放行；如果该请求带有连接 ID，批准后会把发送者加入对应 Bot 自己的 access 名单。列在 admins / approvers 或旧的 *_admins / *_approvers 里的用户也会获得基础 bot 准入，不需要再重复写进 users / *_users。群聊不会因为私聊配对或角色准入自动开放，群 ID 仍是额外收窄 条件。常用配对管理命令：

reasonix bot pairing list
reasonix bot pairing approve CODE
reasonix bot pairing reject CODE

如果配置了 qq_admins、feishu_admins、weixin_admins 或对应 *_approvers，/yolo、/mode 等运行模式命令只允许 admin 使用； /projects、/use project、/sessions、/attach session 和 /search all 也只允许 admin 使用。/approve 和 /deny 只允许 approver 或 admin 使用。没有配置角色列表时，为兼容旧配置，已允许的用户保持原有 命令能力。远端用户进入的是同一个 Reasonix controller、权限策略、工具 审批模式和沙盒边界，和本地桌面端或 CLI 回合一致。

[bot.allowlist]
enabled = true
feishu_users = ["ou_member"]
feishu_admins = ["ou_admin"]
feishu_approvers = ["ou_approver"]

默认启用 ignore_self_messages = true。网关会记录刚发出的平台 message_id，并忽略平台回传的同 ID 消息；如果某个平台不会稳定回传同一 消息 ID，可以在 [bot.self_user_ids] 里配置 bot 自己的用户 ID 作为第二层 回声防护。/status 会显示当前会话队列模式和各连接的健康状态，例如 feishu-lark=running 或 weixin-weixin=degraded。

可选的 [bot.control] 提供本机 loopback HTTP API，默认关闭。启用后必须 设置 token_env 对应的环境变量，所有请求都需要 Authorization: Bearer <token>；地址只能绑定 localhost、127.0.0.1 或 ::1。当前接口包括 GET /status（会话与连接健康快照）和 GET /metrics（Prometheus 文本指标）以及 POST /send（向指定连接发送 文本或媒体消息）。

示例：

export REASONIX_BOT_CONTROL_TOKEN="change-me"

curl -H "Authorization: Bearer $REASONIX_BOT_CONTROL_TOKEN" \
  http://127.0.0.1:37913/status

curl -X POST http://127.0.0.1:37913/send \
  -H "Authorization: Bearer $REASONIX_BOT_CONTROL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "feishu-lark",
    "domain": "lark",
    "chat_id": "oc_xxx",
    "chat_type": "dm",
    "text": "hello from local control API"
  }'

使用流程

sequenceDiagram
  participant U as "用户"
  participant IM as "飞书 / Lark / 微信 / QQ"
  participant R as "Reasonix 桌面端或 bot start"
  participant T as "本机工具与模型"

  U->>IM: "发送需求"
  IM->>R: "消息进入本机 Bot 网关"
  R->>T: "模型思考并调用工具"
  alt "普通回复"
    R-->>IM: "返回答案"
  else "需要审批"
    R-->>IM: "发送审批卡片或审批文本"
    U->>IM: "允许 / 拒绝"
    IM->>R: "审批命令"
    R->>T: "继续或停止工具调用"
    R-->>IM: "返回结果"
  else "需要用户选择"
    R-->>IM: "发送 Ask 问题"
    U->>IM: "选择选项或回复 /answer"
    R-->>IM: "继续执行并返回结果"
  end

桌面端左侧的 机器人 入口会显示已连接 Bot。收到第一条 IM 消息后，可以 从这里打开对应本地会话，查看上下文、工具轨迹、成本和运行指标。

四种渠道的交互差异

下面三张图是虚构内容的交互示意，用来帮助理解真实软件里的操作形态。

渠道	连接方式	审批方式	Ask 问答	适合场景
飞书	扫码创建 PersonalAgent	交互卡片按钮，也可用命令	交互卡片按钮，也可用命令	国内飞书工作流、群聊或个人助手
Lark	扫码创建 PersonalAgent	交互卡片按钮，也可用命令	交互卡片按钮，也可用命令	国际版 Lark 工作流
微信	微信扫码登录	回复 1 / 2 或命令	回复普通文本、选项编号或命令	微信个人测试、轻量移动触发
QQ	手动配置（App ID + App Secret）	内联键盘按钮、数字回复或命令	回复普通文本、选项编号或命令	QQ 群聊、个人会话和官方 QQ Bot 平台

飞书和 Lark 的卡片按钮会在后台转换为命令，例如 /approve <id>、 /deny <id> 或 /answer <id> <选项>。QQ 的审批按钮也是如此。 如果按钮过期或平台提示操作失败，可以直接复制卡片里的 ID，用文字 命令继续。

命令速查

这些命令在飞书、Lark、微信和 QQ 中通用。

命令	作用	示例
/help	查看可用命令	/help
/status	查看活跃任务、队列、工具审批模式和连接健康	/status
/stop	停止当前任务	/stop
/new	开始新会话	/new
/reset	重置当前会话	/reset
/approve <id>	批准待审批操作	/approve 1
/deny <id>	拒绝待审批操作	/deny 1
/answer <id> <选项>	回答 Ask 问题	/answer ask-1 2
/yolo	开启 YOLO	/yolo
/yolo on	开启 YOLO	/yolo on
/yolo off	切回询问模式	/yolo off
/yolo auto	切换到自动审批模式	/yolo auto
/yolo status	查看当前工具审批模式	/yolo status
/mode yolo	切换到 YOLO	/mode yolo
/mode ask	切换到询问模式	/mode ask
/mode auto	切换到自动模式	/mode auto
/queue status	查看当前队列模式	/queue status
/queue steer	运行中消息作为当前任务补充	/queue steer
/queue followup	运行中消息排队为后续回合	/queue followup
/queue collect	合并排队消息为一个后续回合	/queue collect
/queue interrupt	取消当前任务并处理最新消息	/queue interrupt
/projects [关键词]	查看已索引项目工作区	/projects reasonix
/use project <id|名称>	将当前远端会话路由到已索引项目	/use project p1
/use project default	清除项目覆盖，恢复配置路由	/use project default
/sessions search <关键词>	搜索已索引桌面/bot 会话	/sessions search 发布 bug
/attach session <id|关键词>	从已索引 path: transcript 继续当前远端会话	/attach session s1
/search all <关键词>	跨已索引项目检索文件内容	/search all TODO

快捷回复：

• 有待审批操作时，回复 1 表示批准，回复 2 表示拒绝。
• 有待处理 Ask 问题时，可以直接回复任意普通非 slash 文本；选择题仍然可以 直接回复选项编号。
• /stop、/mode、/answer ... 等 slash 命令不会被 Ask 快捷回复截获。
• 如果没有待处理操作，1 / 2 会被当作普通消息或收到提示。

默认队列模式是 steer：同一会话正在运行时，新消息会作为当前任务的 mid-turn guidance 注入，而不是等完整回合结束。queue_cap 和 queue_drop 可以在配置里限制排队堆积；reasonix bot doctor --deep 会显示当前队列、 配对和角色诊断信息。

队列模式：

• steer：运行中的消息会尽量作为当前回合的补充指导。
• followup：运行中的消息排队成为后续回合。
• collect：把排队消息合并成一个后续回合。
• interrupt：取消当前回合，并保留最新消息作为下一回合。

项目与会话跳转：

• /projects [关键词] 会列出来自 bot route、连接工作区、活跃 bot 会话和 已保存 session mapping 的工作区。
• /use project <id|名称> 会把当前远端会话固定到某个已索引项目； /use project default 会清除覆盖。
• /sessions search <关键词> 搜索已索引桌面端和 bot 会话元数据。
• /attach session <id|关键词> 从已索引 path: transcript 继续当前远端 会话。
• /search all <关键词> 跨已索引项目根目录检索文件内容；有 rg 时优先用 rg，否则使用带边界的 Go fallback scanner。

这些跳转命令不会接受 IM 中临时输入的任意本地路径，只能跳到索引内目标； 配置了角色列表时，这些命令需要 admin 权限。

当适配器提供媒体 URL 时，gateway 会把文件下载到当前工作区的 .reasonix/attachments，并以 @.reasonix/attachments/... 形式传给 Reasonix。保存失败的附件会在 IM 中提示，文本内容仍会继续处理。内置 Feishu、Weixin、QQ 适配器当前仍以文本事件为主，普通 IM 附件抽取可以继续在 适配器层补齐。

审批与 YOLO

Reasonix 的机器人沿用桌面端权限系统。默认是询问模式：写文件、执行命令等 敏感工具调用会先请求确认。

flowchart TD
  A["模型准备调用工具"] --> B{"是否命中 deny 规则"}
  B -- "是" --> C["直接拒绝"]
  B -- "否" --> D{"工具审批模式"}
  D -- "询问 Ask" --> E["向 IM 发送审批"]
  D -- "自动 Auto" --> F["策略允许时自动放行"]
  D -- "YOLO" --> G["普通工具审批自动放行"]
  E --> H{"用户选择"}
  H -- "允许" --> I["执行工具"]
  H -- "拒绝" --> J["停止该操作"]
  F --> I
  G --> I

YOLO 的边界很重要：

• YOLO 会跳过普通工具审批。
• YOLO 不会跳过硬性 deny 规则。
• YOLO 不会自动回答模型提出的 Ask 问题。
• YOLO 不会自动批准计划模式里的计划批准。

建议：

• 临时调试、可信项目、需要快速连续读写时，可以用 /yolo。
• 做高风险操作、生产代码或不确定任务时，用 /mode ask 切回询问模式。
• 想减少普通审批但保留策略判断时，用 /mode auto。

升级后是否需要重新绑定

正常升级或覆盖安装 Reasonix app 后，不需要重新绑定。

绑定信息保存在用户配置目录，而不是 app 包内：

• Bot 连接、远端 ID、白名单、模型和审批模式保存在用户配置文件。
• 飞书和 Lark 的密钥保存在 CLI 与桌面端共用的 Reasonix 全局 <Reasonix home>/.env。
• 微信扫码后的账号 token 保存在 Reasonix 的用户数据目录。
• QQ 的 App ID 保存在用户配置文件；App Secret 通过配置的环境变量 （默认 QQ_BOT_APP_SECRET）保存在 Reasonix 全局凭据文件中。

需要重新扫码或重新配置的情况：

• 删除了 Reasonix 用户配置目录。
• 换了 macOS 用户或换了机器。
• 平台侧撤销授权。
• 微信 token 失效。
• 飞书或 Lark 应用密钥被清除。
• QQ 的 App ID 或 App Secret 失效或被更改。

排障

现象	可以检查
扫码提示链接失效	回到设置页重新生成二维码；二维码有有效期（飞书、Lark、微信；QQ 不使用扫码，请检查手动配置）。
已连接但没有回复	确认桌面端 bot runtime 或 reasonix bot start 进程正在运行，Bot 连接已开启，用户 ID 在白名单内、已配对或允许所有人。
飞书或 Lark 按钮提示失败	直接发送卡片里的命令，例如 /approve <id> 或 /deny <id>。
QQ 按钮提示失败	与飞书/Lark 相同 —— 直接发送卡片里的命令，例如 /approve <id> 或 /deny <id>。
微信回复 1 没反应	只有存在待审批或 Ask 时数字快捷回复才生效；也可以使用完整命令。
QQ 回复 1 没反应	与微信相同 —— 只有存在待审批或 Ask 时数字快捷回复才生效；也可以使用完整命令。
想确认当前模式	发送 /status 或 /yolo status。
想重新开始上下文	发送 /new 或 /reset。
想停止当前任务	发送 /stop。

如果仍然无法连通，可以在 设置 -> 机器人 中打开对应 Bot 的高级设置，使用 检查配置、测试发送和运行设置来定位问题。