dsh-rabiroute-agent

Readme

## DSH 原生钩子（0.13.29）

插件默认启用 `agentHooksEnabled`，直接监听 DSH 会话入口、用户提交、工具执行前后与轮次结束。自动化规则统一在 RabiRoute「人格 → 自动化 → Agent Hook」设置；不读取 Codex 配置，也不启动其它 Agent。Manager 返回的上下文、工具拒绝和本轮继续处理决定由 DSH 执行；继续处理每轮最多触发一次，仍受宿主权限限制。

DSH 日志保存 `plugin:dsh-rabiroute-agent/hook-invoked` 与 `hook-result` 记录，供 `dsh-hook-insights` 0.2.0 起统计。记录只含阶段、关联标识、耗时、HTTP 状态与处理结果，不包含原始正文、工具参数或输出。Manager 失败、回执待核对和取消都留真实结果；不从缓存补造上下文、不自动重发。安装后需重启 DSH 并刷新页面，新轮次才产生记录。

记录通过宿主传入会话的 `append()` 写入，并保留 `ignorable: true`；源码启动与构建版插件同时加载时，不跨模块调用 `Session` 私有方法。宿主须支持 `append()` 的 `ignorable` 选项。开发验收可设置 `DSH_TEST_SOURCE_ROOT` 为待测 harness 源码根目录，运行 `node --test tests/native-hooks-source-session.test.mjs`；测试使用源码会话、构建版插件和固定 Hook 回执快照，不调用真实 Manager。

Hook 注入与继续处理消息统一使用 `source.kind: dsh-rabiroute-agent`，不再写 V4 已退役的 `kind: plugin` 包装。自身上下文不会再次作为用户提交送回 Manager。完整循环测试必须写入 JSONL、关闭写句柄后重新打开读取，验证消息来源、Hook 回执和轮次结束均可恢复。

# dsh-rabiroute-agent

This release requires DSH 0.2.1-alpha.1 or a compatible 0.2 release. See [compatibility details](docs/dsh-0.2-compatibility.md).

v0.13.31

普通回答通过可选 `proactive-answer.message` Component Factory 显示为提问回答卡片。来源封套仍由本插件处理；Factory 缺席或文本不匹配时保留原消息展示。

Rabi助手模式装配 DSH 官方自动压缩、`/compact` 和工具结果裁剪，已开始的原会话在更新并重启后恢复这些能力。模型输入和输出预留共同计入上下文预算；摘要与替换沿用宿主持久事件，完整历史仍可读取。压缩只整理 DSH 会话上下文，Rabi 仍持有人格、计划、记忆与陪伴状态。

工作区与路由人格的工作空间匹配时，标题右侧显示 Rabi 按钮。弹窗仅列出该工作区真实 DSH 会话绑定的计划；复用 WebGUI 的搜索与状态颜色，支持状态、标签、范围、排序和分页。计划标题仅作展示；打开绑定会话后由会话自动加载对应计划，多绑定时先选择会话。按钮发现不扫描计划。已加载页面在插件生命周期内缓存；关闭取消当前读取，保留一个轻量事件订阅。无变更时再次打开不查询；变更按角色失效，当前页只传输和合并变动行，关闭的页下次打开再校验。顺序、计数和筛选项由服务端核对，断线重连重新校验；失败保留旧数据并显示错误。`workspacePlanCachePages`（默认 32）限制缓存页数，`workspacePlanEventDelayMs`（默认 200）控制事件合并时间，均可在插件配置中调整。需要 Rabi `POST /api/roles/:roleId/plans/query` 及宿主 `sidebar.workspaces.workspace.actions` 插槽。

计划状态标签常驻会话文字左侧。绑定计划的标题最多隐藏两个开头分类前缀，悬浮显示原始标题；名称和重命名草稿不变。宿主需安装本包的[会话行扩展补丁](patches/README.md)。

## 计划材料归档（0.10.0）

用户截图和文件自动归入单个绑定计划；多计划由 Agent 调用专用工具选择归属。文件改动记录到指定步骤，区分工具观察与 Agent 报告。后台归档可恢复，不阻塞消息发送。详见[计划材料归档](PLAN-RESOURCES.md)。

## 计划上下文（0.9.5）

用户消息进入模型时，通过官方 `systemPrompt.context` 附带当前会话绑定计划的摘要：标题、状态、当前步骤、完成进度，以及可直接调用的 `rabiroute_manager_api` 详情参数。多计划保留各自身份。它与 DSH 全局提示词在同一 pre-step 阶段装配；计划绑定、状态或进度变化会更新快照，压缩移除旧快照后会重新注入。无已知绑定时不注入占位；缓存刷新、读取时间、标题或标签单独变化不触发新快照。用户原文不改写；上下文变化由官方运行上下文追加快照并写入会话日志，解绑后追加清除标记；不改写此前请求历史。

与侧栏共用事件失效及 TTL 缓存，发送和模型装配不等待网络、不读取计划正文。冷缓存不提供计划摘要；已有摘要注明可能过期，不能据此判定未绑定或把旧状态当成最新。`planContextEnabled` 默认 true；`planContextMaxPlans` 默认 16，`planContextTextLimit` 默认 300，限制单次摘要体积。

业务真源仍是 Rabi；本插件仅负责 DSH 模型上下文的装配和持久化接入。


[English](README_en.md) | 简体中文

把 DSH 会话接入 RabiRoute 的受管任务、消息、计划和记忆接口。业务合同与 Codex 对齐，实际会话、工具和权限仍由 DSH 持有，不另启 Runtime、不改投 Codex。

> 连接优化已随 **0.1.5** 发布，并通过官方入口的隔离安装及只读连接验证。**0.2.0** 增加右侧栏 Rabi 计划面板，**0.2.1** 把入口改成 Rabi 图标按钮并让它在「已绑定人格」时即可见，**0.2.2** 让消息解析覆盖「计划」与「系统」来源并默认折叠它们的正文，**0.3.0** 让非 DSH 来源（如 `codex`）的「定位到Agent」也能用——交给 RabiRoute 唤起对应客户端窗口。源码测试、正式环境安装、运行中工具、Hook 和真实业务投递分别验收，不能用隔离验证代替正式环境部署。

标签刷新逐页合并已验证的摘要，后续页失败不清空已知绑定；完整读取后才移除失效绑定。后台总预算 `planStatusTimeoutMs` 默认 120 秒，HTTP 缓存读取仍立即返回。

## 会话计划状态标签（0.13.18）

分组、平铺和搜索结果在会话文字左侧常驻状态标签。运行、未读、待交互及归档状态保留标签；宿主状态图标继续独立显示。使用 root 插槽 `sidebar.session.row.badges` 和 `sidebar.session.row.title`，按实际行 `sessionId` 读取，不激活列表中的会话。标签与标题共用一个查询和事件订阅；状态名和配色由 Rabi 提供。

`GET /rabiroute/plan-statuses` 立即返回缓存，并按需在后台更新。所有会话共享一次摘要分页扫描，不读取计划正文，不阻塞会话打开或 Agent 执行。`planStatusCacheMs` 默认 60000 毫秒，`planStatusTimeoutMs` 默认 15000 毫秒，`planStatusMaxPages` 默认 24 页；通过同源 `GET /rabiroute/plan-events` 订阅 Manager 的计划提交和状态配置事件，合并刷新；正常状态不定时查询。重连时重新校准，页面隐藏、无标签订阅或插件卸载时关闭事件连接。首次加载可能需要数秒显示标签。

多个计划绑定同一会话时显示“多个计划”，不任意选择状态；刷新失败保留上次完整结果，仅在悬浮提示中说明缓存状态，刷新不改变标签文字与颜色；状态标签和颜色来自摘要接口的 presentation 配置，使用 Rabi 的强调色与主题背景混合。未启用 view 过滤，覆盖暂停和完成等状态；超过分页预算不提交不完整结果。启用路由的人格范围以当前 Manager 路由目录为准。

## 消息处理模式（0.7.0）

工作区人格技能另见本文末尾；消息处理模式使用 Rabi 工具，所有 Rabi API 均可调用。

会话模式菜单可增加「消息处理模式」（`message-processing`）：接收消息、通过 Rabi 向渠道或其他人格投递消息、读取和创建 Agent 会话、分派与跟进任务，以及创建、查询、更新和删除计划、管理计划状态、绑定与反馈，读取和维护记忆，读取人格正文与人格 Skill。

只使用 `rabiroute_agent_threads`、`rabiroute_agent_send`、`rabiroute_manager_api`。预设不加载 Shell、直接文件/Skill、网页、子 Agent 或工作流工具，强制 native 呈现，并通过 `tools.guard` 拒绝非 Rabi 工具执行，包括后来注册的工具和 PTC。标准模式及其他会话不受影响。Rabi 全部接口可经 Manager 工具调用，包括设备、资源和附件；预设不筛选 API 路径、方法、请求头或载荷字段，权限与业务校验归 Rabi。

插件注入的提示词建议当前人格会话处理消息、计划和任务跟进，其他业务工作尽量安排独立会话；先复用负责同一事项的原任务，没有合适任务时再创建。独立任务完成自己的目标并正式回报，不层层转派同一工作。这是优先分工，当前会话始终可以调用全部 Rabi 接口；必要的上下文核对、用户要求直接处理或简单已授权动作可直接进行。委派不增加接口限制。

消息处理预设只向模型提供 Rabi 工具及调用提示；Rabi助手另保留官方 `web_search` 和 `web_fetch`，使用现有联网服务及搜索提供方配置。不提供其他工具相关的 Skill 目录。当前绑定人格的 Skill 经 `/api/roles/<roleId>/skills` 及单项接口按需读取和使用；接口合同与技能正文保留在 Rabi，加载技能不扩大工具权限。Rabi助手和消息处理模式遵循同一分工原则，标准执行会话保留自身能力。

模式内置调用指南直接说明接口、字段、来源身份、幂等与 ETag、回执和跟进方式，无需先打开本地文档。当前会话 ID 和工作区来自每次正式 prompt 装配；人格绑定可通过只读 `/api/codex-hook/sessions/<sessionId>` 查询。没有当前绑定或跨人格发送凭据时不得臆造。近期记忆可新增和更新；已有沉淀记忆按 Manager 合同只读，修正先记录到近期记忆，整理工作交给其他 Agent。

消息、会话与计划仍由 Rabi 持有，DSH 仅添加模式选择和本地工具权限。这些限制必须进入 DSH 工具运行时，Rabi 无法替宿主实施；不另建消息队列或计划库。Manager 不可用时明确失败，不转用命令或文件。Rabi 内部持久化、宿主保存会话和 Host 连接发现仍属于基础设施，不是授予模型文件权限。现有 Agent 输入与独立生命周期 Hook 不由此模式替换。

安装新插件固定 Git 提交后，将已安装包的 `presets/message-processing/` 两个 YAML 文件复制到实际 DSH Home 的 `.agent-presets/message-processing/`；存在同名预设时先核对，不覆盖用户配置。预设只引用包导出 `dsh-rabiroute-agent/message-mode`，不复制运行代码。也可把已安装包的 `presets/` 追加到现有 `agent-presets.config.roots`，保留其他根与默认模式。官方预设发现负责显示菜单，新会话选择此模式；已有消息的会话不能切换模式。需要提供 `tools.guard`、`tools.restrict`、`tools.presentAs` 的 DSH，缺少接口或未注册 Rabi 工具时拒绝启动该模式。

`npm test` 验证接口和预设；在已构建的官方源码环境设置 `DSH_SOURCE_ROOT` 后运行 `node --test tests/message-mode.integration.mjs`，验证实际工具运行时的作用域、拒绝、Rabi 转发及卸载。集成测试使用模拟 Manager 回执，不对外发消息；本机安装、菜单显示和真实业务验收另行报告。

工作区 Rabi 计划弹窗提供“检查推进”和“推进设置”。规则按人格工作区保存，每种计划状态分别设置提示词、触发条件、动作、冷却时间和当前步骤次数上限。自动推进默认关闭；开启后监听计划及反馈变化、会话结束，并可选择启动检查和到期检查。检查页先展示可推进项和实际投递提示词，选中后只向原绑定 DSH 会话排队投递；“推进所有非运行中的会话”复用当前检查页并继续逐页查找，每个符合规则的空闲原会话本轮最多投递一次。查找和启动分别显示进度条；没有候选时禁用批量按钮，可重新检查。待审批、暂停、终态、绑定不匹配和运行中会话会跳过。Rabi 保存派发回执，避免同一计划变化重复投递；结果不明确时停止重试并等待核对。

推进设置页直接说明触发、检查与原会话排队投递的过程，并默认展开首个可配置状态，显示人格状态说明和该状态的可编辑推进提示词。保存走 Rabi 人格工作区规则接口；状态说明仍由人格工作流统一维护。实际提示词由 Rabi 合并状态说明、规则提示词、计划及步骤身份与授权约束，Agent 收到后重新读取最新计划。

## 统一帮助与发送能力（0.13.16）

家庭设备目录默认返回分页摘要。先用 `/api/agent/xiaomi-home/devices?q=<关键词>&limit=5` 或 `/resources?kind=climate&limit=5` 筛选，关键词 URL 编码，支持名称、描述、型号、房间和属性信息。按 `data.nextOffset` 续页，设备摘要的 `resourcesPath` 可查所属实体；定位后只读单项 `/resources/<resourceId>` 状态和 `/entity-actions?resourceId=...` 动作。完整目录字段使用显式 `view=detail`，仍须分页。插件只注入调用提示，筛选、分页和详情由 Rabi 提供，不增加接口白名单。

通过 `rabiroute_manager_api` 调用 `GET /api/agent/help` 获取 Manager 当前统一帮助，或 `GET /api/agent/send/capabilities` 查询发送能力。支持正常 query，例如 `{"method":"GET","path":"/api/agent/help?method=GET&path=%2Fapi%2Fagent%2Fxiaomi-home%2Fdevices"}`；参数语义以当前 Manager 合同为准。

从 0.13.22 起，本插件不维护 Manager API 白名单；当前和未来的 Rabi 接口均可调用，路径、HTTP 方法和业务请求头不按接口清单筛选。Rabi 拥有接口合同、授权、参数校验、幂等与版本要求。插件仍核对同源相对路径、Host 动态发现、`/meta` 身份与就绪状态，拒绝重定向和路径穿越，不自动重放请求。调用能力不扩大用户授权。源码实现不等于当前宿主已加载，须发布固定提交、受管安装并重启后另行验收。

## 定位与开发边界

本插件是 DSH 调用 Rabi 的工具适配层，不是 DSH 内的计划、记忆、人格或消息系统。工具可用不等于 Rabi 自动调度已启用，也不证明独立生命周期 Hook 已加载。

功能归属遵循 Rabi 的[统一 Agent 接入规范](https://github.com/vb2250158/RabiRoute/blob/main/docs/agent-adapter-standard-requirements.md)：能由 Rabi 统一实现的业务和策略放在 Rabi，供 DSH、Codex 及其他 Agent 复用。Rabi 暂时缺接口时优先补公共接口，不在 DSH 复制业务规则、状态库或调度器。

本插件只承担工具注册、请求与结果转换、连接校验和必要通信约束。必须进入 DSH 的内部事件、上下文注入、权限执行或 UI 才考虑宿主侧增强，并通过正式扩展点实现；Rabi 的业务决定不能扩大 DSH 本地权限。生命周期适配由独立 `rabi-dsh-context` Hook 负责，不在本插件重复实现。

新增需求必须说明：Rabi 为何无法直接完成、DSH 最小本地职责、业务真源、跨端共用合同、可选增强缺席时的行为及验收证据。公共能力不能要求 Codex 复制 DSH 界面，也不能把本插件的安装状态作为 Rabi 基础会话发现和投递的前提。能力说明分别标注工具接入、Hook 接入和实际业务验收，不把 API 名称当成 DSH 自有功能。

## 回复迷你播放器（0.5.0）

回复底部喇叭只朗读所点消息的正文，不含思考、工具调用或其他消息；空正文隐藏，超过 10000 字符拒绝。点击后显示“生成中”和不定进度条，禁用重复点击。当前 Rabi TTS 接口不提供生成百分比，因此不显示虚构进度。

生成完成后自动尝试在当前浏览器播放；浏览器阻止自动播放时可再次点击播放。播放器高度 24px，提供播放/暂停、时间和可拖动进度条。暂停、续播和拖动复用已生成音频，不重复请求 TTS。音频只存于当前页面内存，离开消息时停止并释放；不持久保存，不进入 Rabi 主机播放队列。

通过公开 `conversation.chat.assistant-actions` 插槽呈现，经同源 `POST /rabiroute/speech` 校验 Manager 身份和服务状态，使用 Rabi 默认提供方/模型及默认音色，以 `play: false`、WAV 格式请求 `/api/speech/tts`。DSH 不另存 TTS 设置、不启动服务、不自动重试。成功响应为最多 32 MiB 的 `audio/wav`，失败响应为 JSON；新版前后端需同时加载，安装后重启 DSH 并刷新页面。

`speechTimeoutMs` 为独立生成等待预算，默认 300000 毫秒、有效范围 1000–900000；普通工具继续使用 `requestTimeoutMs`。请求断开时取消等待；Rabi 已开始的模型计算可能继续，但不会产生主机播放。失败在图标旁显示警示，悬停或辅助技术可读取原因。

Rabi 拥有合成和默认配置；本插件仅适配指定回复取文、同源音频响应和 DSH 页面中的播放交互。测试覆盖重复点击、正文隔离、拖动、暂停/续播及资源释放；安装、运行加载和实际页面验收分别报告。

## 自动朗读回复

从 0.13.15 起，自动朗读的开关、会话观察与播放队列由独立的 [语音服务增强插件](https://github.com/vb2250158/dsh-speech-service) 持有。本插件保留手动朗读和公开合成接口 `/rabiroute/speech`，Rabi 继续拥有合成与音色配置；不再依赖对官方语音服务源码的改动。

## 官方提问卡强化（0.6.2）

`ask_user_question` 仍由官方 `conversation.composer` 提问卡回答：选项、跳过、取消和草稿都不另做一套。本插件以更高优先级包住同一张卡，只做两件宿主侧的事：把自由文本标成「自己的分支」，并在该输入旁提供语音按钮。

语音走同源 `POST /rabiroute/speech/asr`。Host 核对 Manager 身份后，使用 Rabi **当前默认 ASR**（本机预加载的 `faster-whisper/small`，热态约 0.5 秒，快于 Qwen3-ASR 0.6B）转写浏览器录到的 WAV，把识别结果写回官方受控输入，不伪造选项点击。DSH 不另存 ASR 设置、不挑选模型、不启动语音服务。失败原因原样显示；识别为空不提交。需重启 DSH 并刷新页面。

## 聊天消息展示增强（Unreleased，未安装验收）

目标是在聊天加载或历史消息重新渲染时识别开头的 `[消息源]` 封套，在正文上方显示来源行，并提供「查看原始消息内容」菜单。识别仅用于显示，不改会话日志、模型输入、来源身份或回传参数；原文必须可查看。文本中的来源只是消息自述，不是经过认证的发送者证明，回传 JSON 不得自动执行。

三类来源按各自的身份字段呈现，**Agent** 行可在正文上方显示发送会话并提供「定位到Agent」；**计划**与**系统**行没有自己的会话身份，标题栏写它们描述的对象（计划名称与计划 ID / 事件名称与事件类型），正文默认折叠，可用行内按钮或标题栏展开。未知或拼写不符的来源类型不解析，仍按原文平铺。

解析源码位于 `src/message-envelope.js`，由浏览器构建打包；Host 工具入口不加载解析器。它支持新旧字段名称及 LF/CRLF，保留原始字符串与正文空白；只拆出格式有效的末尾回传 JSON。重复字段、未知头字段、混用其他来源类型的字段、半写的来源身份、回传 JSON 歧义或投递 ID 冲突返回 `null`，调用方必须显示原文。`消息端` 尚无呈现方式，与未知上下文块一样不作业务解释。

不符合支持格式或存在歧义时保留原样。来源会话按完整 ID 定位，不以名称猜测、不创建替代会话。**DSH** 来源在本地目录中按完整 ID 精确匹配后打开；**其他处理端**（当前为 `codex`）交给 RabiRoute 的 Agent 任务桥 `action=open` 唤起对应客户端窗口——本地客户端没有那个会话，自己判断只会猜错。未知目标和 Rabi 拒绝的原因都原样提示。计划与系统行不提供定位入口——它们没有可定位的会话，放一个按不动的按钮会读成坏链。

折叠只影响显示：正文在折叠时不渲染，也不跑 `projectUserText` 投影，展开与「查看原始消息内容」都能取回完整内容。

浏览器源码通过公开 `conversation.chat.node` 插槽替换 `user` 和 `steering`，而不是装饰或调用官方 renderer；普通消息同样由本插件显示。正文复用公开 `projectUserText`，图片交回 owner 的图片呈现回调，文件、其他数据块、引用、时间与复制分别显示。复制保留完整原文；原文菜单使用 Modal。注册优先级为 -10，同一 key 的其他插件替换可能冲突，须核对当前组合。不接管 `context`、待提交回显或 Trajectory。

点击 DSH 来源会刷新会话目录，仅打开目录中完整 ID 精确匹配的会话；点击其他处理端的来源会把该会话交给 RabiRoute，由它唤起对应客户端窗口。外部窗口是否真的被带到前台由 Rabi 回执说明，插件不假设成功。Rabi 不可达、它拒绝该会话、或处理端不在支持下时都明确提示，不创建会话。未列入目录的子会话定位及原生界面逐像素一致性不在当前实现保证内。Client 源码和构建测试不替代实际安装后的浅色、深色、自定义主题、历史加载和键盘交互验收。

### 定位外部处理端（0.3.0）

浏览器请求同源路由 `POST /rabiroute/locate-agent`，请求体只有 `{ agentAdapter, threadId }`。Rabi 没有为 DSH 源站声明 CORS，浏览器不能直接调 Manager，所以由 Host 代答：核对 `/meta` 身份后调 `POST /api/agent/threads`（`action=open`），把 Rabi 的回执转成结果。只转发这两个字段——不代理消息正文，也不代理凭据。

`dsh` 来源不走这条路，它在本地会话目录里就地切换。`agentAdapter` 不在 Rabi 支持的处理端内时，插件在发请求前就拒绝，而不是让 Rabi 用一个更含糊的理由回拒。Rabi 自己的拒绝原因原样返回，插件不改写成自己编的说法。

## Rabi 计划面板（0.2.0）

会话在 Rabi 侧绑定了**人格或计划**时，右侧栏出现「Rabi 计划」页：进入该会话会自动打开一次，之后由会话标题旁的 **Rabi 图标按钮**随时重开。面板渲染的不是重画的计划，而是 **Rabi 自己的单计划视图**（`#/routes/<路由>/plan/<计划 ID>`）；计划的步骤、反馈、审批与附件全部由 Rabi 呈现和驱动，DSH 不持有第二份。

### 入口与关闭（0.2.1）

| 行为 | 规则 |
| --- | --- |
| 入口按钮 | 会话标题旁的 **Rabi 图标**（本插件自带，64px 内联，无运行时请求）。按钮在**该会话已绑定 Rabi 人格或已找到绑定计划**时出现；`roleId` 为空（未绑定、或 Manager 不可达）时不显示。 |
| 为什么不再以"有计划"为条件 | 0.2.0 把入口卡在"面板可用"上，于是"已绑定人格但计划尚未记录"这个**正常中间态**里入口反而消失——正是需要入口的时候。现在入口只看绑定，面板负责解释空态。 |
| 自动打开 | 仅当**确实有绑定计划**时自动开一次，按会话去重。已绑定但还没计划时不自动开，免得弹出一个空列。 |
| 关闭与切换 | 关闭、折叠或切换右栏页时，插件记录该会话的面板选择；切回会话不会再次弹出已关闭的计划。DSH 右栏仍持有当前布局，插件只在浏览器会话存储中保留选择，页面重载后也尊重它。 |
| 重开 | 点图标按钮即 `sidebarRight.openTab`，与自动打开是同一条路径。 |

**图标来源**：`RabiRoute/assets/rabiroute-icon.png`，缩到 64px 后内联进客户端产物（`src/plan-icon.js`，约 4 KB）。不运行时抓取的理由是 DSH 客户端没有可靠取得 Rabi 静态资源的地址，且抓取会让按钮闪一下空。

单个绑定计划直接显示详情；多个绑定计划显示可点击的目录，保留各计划的人格和路由身份。目录使用 Rabi 摘要返回的状态名称与配色，点击后只挂载所选计划的详情页。目录切换不重新查询绑定，重新加载按钮重新读取 Rabi。

数据只有一条路径。浏览器请求同源只读路由 `GET /rabiroute/plan-panel?sessionId=<DSH 会话 ID>`，Host 侧发现 Manager、核对 `/meta` 身份后依次读只读接口——`GET /api/codex-hook/sessions/<会话>` 取绑定角色；没有 Hook 人格记录时，从 `GET /api/gateways?summary=1` 取得去重后的角色，并行分页查询其当前计划。按完整会话 ID 匹配任务或秘书绑定，不创建人格绑定。存在 Hook 人格记录时，分页读取该角色的**当前计划摘要**并按 Rabi 的判据匹配绑定（`view=current`，每页 200 条摘要，最多 8 页），`GET /api/gateways?summary=1` 把角色映射到路由——再返回页面地址。不读计划正文，不读整份目录（那是按百条、每次上百 KB 的量级），不写入任何状态。浏览器在当前插件生命周期内按会话保留已确认的面板解析结果，不因切换多个会话逐出；浏览器重载时从会话存储还原计划身份和无凭据的地址信息，再在后台核对。相关计划事件只核对受影响的会话；失败时显示上次确认的结果与过期提示，手动重新加载会强制重读。带凭据的地址不写入浏览器存储。

面板返回单计划地址或多计划目录；无绑定、无计划、无路由及 Manager 不可达分别显示原因。分页读取完整的当前计划摘要，达到查询上限仍未结束时显示读取失败，不返回截断目录。

计划 tab 以本插件自己的 id（`dsh-rabiroute-agent/plan`）注册为独立页面类型，不接管任何既有 tab 类型；也不贡献 guide 条目，因此未绑定计划会话的侧边栏行为完全不变。

### 跨仓库依赖（RabiRoute 前端需含单计划地址）

单计划视图住在 Rabi 前端：`ribiwebgui` 的计划页使用 `/routes/:id/plan/:planId` 聚焦地址，复用同一套计划渲染，只收窄加载与显示范围（无目录、无分页、无记忆面板，计划默认展开）。重复打开时由 Rabi Web 的浏览器会话存档立即展示详情，Manager 以视图版本返回 `304` 或新详情；因此此缓存功能同时依赖 Rabi Web 和 Manager 更新。

RabiRoute 前端不含该地址时，面板会给出不可达或未找到的原因，不会退化成显示整页目录。

当前版本已知边界：

- 面板以 iframe 呈现，因此仍带有 Rabi WebGUI 的页面外壳（顶栏与导航），只是内容收窄到一个计划。
- 前提是浏览器能访问 Manager。同机时成立：loopback 请求免令牌；若 Rabi 开启了局域网 WebGUI 访问，页面会自行跳到局域网地址并带上访问令牌，面板不受影响（已实测）。从另一台机器访问 DSH 时，iframe 指向的是那台机器自己的 `127.0.0.1`，面板会不可用；跨机访问尚未处理。
- Electron 客户端以 `file://` 加载界面，相对路径的同源路由不可用，面板会给出不可达原因。
- 自动打开每个会话只发生一次（按会话去重）；手动关闭后不会反复自动弹出。

## 安装

通过「设置 → 我的插件」或 DSH 官方入口使用可获取的固定提交：

```powershell
pnpm dsh plugin --profile web add --save-exact github:vb2250158/dsh-rabiroute-agent#<commit>
```

使用本机实际 DSH Home 和 profile。包通过 `dsh.bundle` 注册配置层，不改官方源码。更新前保留配置与锁文件；未完成的插件/环境事务先走同步器受管恢复，不删除记录、不覆盖安装缓存、不用本地 link 代替正式安装。活动任务结束后通过既有受管入口重载，再核对真实加载版本及工具 schema。

## 配置

当前 profile 的 `cordis.patch.yml`：

```yaml
- id: rabiroute-agent
  config:
    managerBaseUrl: ""
    hostExecutable: ""
    enforceAgentCommunication: true
    requestTimeoutMs: 30000
```

机器专属值只保存在本机，不加入共享补丁。

- `managerBaseUrl` 留空：每项操作经 Host `status --json` 发现当前完整地址，核对 `/meta` 的健康、必需能力及非空 generation/实例身份，与 Host 一致才发业务请求。不缓存旧地址，不扫描端口。
- 非空 `managerBaseUrl`：显式开发/外部 Manager 的完整 HTTP(S) origin，不带路径、查询、片段或凭据；仍核对健康与身份，失败不换目标。源码模式可显式配置当前结构化 READY 地址。
- `hostExecutable`：可选本机 Host 可执行文件。留空时 Windows 根据 `LOCALAPPDATA` 派生常规安装位置；其它平台需显式配置 Host 或 Manager。只执行只读 status，不启停服务。
- `requestTimeoutMs`：整项操作预算，默认 30 秒，范围 1–120 秒。每次 HTTP 请求另限最多 12 秒，Host status 最多 3 秒，取消信号向下传播。
- `enforceAgentCommunication`：保留正式通信使用专用工具的约束。

注册插件不访问 Host，Manager 不可用不阻止 DSH 启动。`active=true` 仅说明工具已注册，不是业务健康证明。已有显式旧地址需清空才能选择 Host 模式，不会偷偷忽略显式目标。

## 降级连接合同（0.8.0）

普通请求和计划面板发现要求 `/meta` 的 `live=true`、`requiredReady=true`、状态为 `healthy` 或 `degraded`，并校验非空 generation/实例身份与 Host 一致。无关消息路线失败不再阻止所有工具；计划恢复、目标路线及 Agent 的可用性仍由 Manager 对应接口判定。

精确 `GET /meta` 只要求身份校验，直接复用发现响应，因此核心未就绪时仍可诊断；查询参数或其它路径不继承该豁免。写后只复核身份，不因健康波动否定已有成功回执；身份变化、无法核对、超时及 5xx 仍保留不确定性，不自动重放。接口白名单已移除，地址、取消、重定向与身份保护保留；幂等键与 ETag 要求由 Rabi 校验。

## 工具合同

- `rabiroute_agent_threads`：通过 Manager 查找、读取、解析、创建、改名、续投及正式回复。保留完整任务身份和原绑定；来源与 `sourceThreadId` 不一致时拒绝。旧 `deliverySource` 输入仅在边界归一化，发送字段始终是 `messageSource`。回复策略和正式回复字段遵守当前 Manager 合同。
- `rabiroute_agent_send`：明确外发，保留 `deliveryId`、发送者及渠道回执。HTTP 成功不代替真实渠道送达。
- `rabiroute_manager_api`：调用全部 Rabi Manager 接口；不维护路径、方法、请求头或业务载荷白名单。接口权限、合法方法与写入条件由 Rabi 校验。同源路径、身份核对和不重放保护仍由插件执行。

通用工具接受合法 HTTP 方法，包括 `GET/HEAD/OPTIONS/POST/PUT/PATCH/DELETE`。可选 `requestHeadersJson` 接受 Rabi 所需的 HTTP 请求头；仅检查名称、字符串值和重复字段的 HTTP 格式。写入自动携带本次核验的 application generation 与 Manager instance 头，不由模型填写旧身份。`bodyJson` 接受任意 JSON 值，`bodyText` 传文本，`bodyBase64` 传二进制；最多选一种，GET/HEAD 不带正文。二进制响应在 `body` 中表示为 `{contentType, contentBase64}`，文本响应保留为 `{text}`，JSON 响应格式不变；响应头完整返回。示例：

```json
{
  "method": "PATCH",
  "path": "/api/roles/example-role/plans/example-plan",
  "bodyJson": "{\"currentStep\":\"已按实际证据更新\"}",
  "requestHeadersJson": "{\"If-Match\":\"\\\"revision-from-get\\\"\",\"Idempotency-Key\":\"stable-operation-id\"}"
}
```

此例不是执行授权。写入前读取现行接口文档、状态目录、资源与强 ETag。

- 新建计划、近期记忆、发起整理需要稳定键；更新计划/近期记忆、反馈、整理结果及版本化状态目录还需要强 ETag `If-Match`。不对所有 API 一刀切，业务规则仍由 Manager 判定。
- 输出保留 HTTP 状态、正文字符串、允许的响应头、ETag、身份及 `uncertain/error`，渲染不隐藏这些字段。成功仍须核对回显键、强 ETag、资源身份并读回，插件不自动完成语义验收。
- 写入不自动重放。超时、503、网络失败或写后身份变化保留不确定状态及已有响应，保持原键原正文先读回。412 重新读后确认原意，再用新键与新 ETag。
- 仅 GET 操作的业务请求发送前发现失败允许一次重新发现；业务 GET 也不重放，因为读取近期记忆可能刷新 `viewedAt`。健康探针仅用 `/meta`。

## Hook 与 Codex 边界

对齐现行 Manager 合同，不照搬旧 Codex 客户端缺失的身份/响应头校验。`rabi-dsh-context` 是独立生命周期 Hook；本插件不复制人格、记忆、Hook 决策，也不证明 SessionStart、权限检查、Stop 或真实投递已验证。Hook 与工具连接配置须分别核对，不用另一条路径掩盖故障。

## 验证与排障

```powershell
npm test
npm run build
npm pack --dry-run
```

构建同步 `src/index.js`、`src/connection.js` 到实际包入口 `lib`。测试检查产物一致、换代、身份拒绝、响应头、412/503、不重放、来源冲突、路径隔离和取消。发布前检查安装包没有用户配置、凭据、业务记录或私有标识。

最小真实验收：用新包工具定义执行 `GET /meta`，核对 Host 身份；安装重载后用会话内正式工具复验。前者不能代替后者，更不证明业务写入或 Hook 正常。

旧版 `fetch failed` 先比较工具配置与 Host 当前地址。旧端口失败不代表 Manager 已挂，不要把今天的动态端口写成新固定默认值。

## 许可证

MIT

## 自动语音输入（0.7.2）

提问卡增加滑轨开关，监听、断句、识别和自动提交跟随 Rabi 当前麦克风配置。关闭开关、修改草稿或离开页面取消监听；成功识别后开关关闭。详见 [自动语音输入](AUTO-VOICE.md)。

## 技能与宿主适配

[DSH Rabi 工具技能](skills/dsh-rabi-tools/SKILL.md) 只维护工具映射及注入诊断。检索、投递与计划使用 Rabi 的通用技能；包内技能不自动注册，按 skill-catalog.json 分发到宿主技能目录后，在新会话核对发现与读取。

## 工作区人格技能（0.8.0）

Rabi 增强默认通过 DSH 的 `skills.registerProvider` 加入人格技能。工作区来自 Rabi `/api/gateways` 返回的已启用 Agent 状态（`monitorThreadCwd` 或 `monitorProjectPath`）。每次发现及加载使用当前会话的 `cwd`；人格与技能仍由 Rabi 管理。该接口未提供的远程实例配置不参与匹配。

工作区按绝对路径精确匹配，统一 Windows 大小写、斜杠和扩展路径前缀；子目录不自动继承。相同工作区合并多个人格的 active 技能，重复路由只计一次。技能名称使用 `rabi-人格ID-技能ID`，不附加哈希编号；名称转小写，符号统一为连字符。同名技能在同一入口一起展示说明，加载时按原始人格和技能 ID 读取全部有效正文，并标明各自来源；停用项不进入正文。官方目录、技能工具及显式触发共用此提供器，并沿用官方会话记录。

`workspaceSkillsEnabled` 默认为 `true`；正整数 `workspaceSkillCacheMs` 默认为 `30000`。内存缓存保存映射与目录，到期使 DSH 目录失效；正文按需读取。Rabi 失败时不缓存空目录，其他提供器保持可用。加载时核对工作区和 active 状态；卸载终止请求并清除定时器。资源标记为 Rabi 虚拟资源，不把 Manager 路径当作 DSH 本地路径。

运行 `node --test tests/workspace-skills.test.mjs`；设置 `DSH_SOURCE_ROOT` 指向已构建的 DSH 后，运行 `node --test tests/workspace-skills-registry.test.mjs`，验证真实注册表、模型目录、技能工具、显式触发、到期与卸载。

## Plugin display metadata

The plugin list shows **RabiRoute integration** in English and **RabiRoute 接入** in Chinese, following the DSH interface language. `locale/en.json` and `locale/zh.json` provide the title and description; `icon.svg` supplies self-contained artwork. The package exports and publishes these resources. The icon is adapted from Lucide; see [ICON_LICENSE.txt](ICON_LICENSE.txt).

The icon uses a centered 36 × 36 viewBox to leave more space around the artwork inside the plugin icon frame.
## Rabi助手模式（0.13.19）

安装插件后自动注册 `rabi-assistant`，会话菜单显示“Rabi助手模式”。人格、记忆、计划和消息由 Rabi 提供；开放三个 Rabi 工具，以及官方 `web_search` 联网搜索和 `web_fetch` 网页读取。助手预设在自己的作用域装配联网工具，在每个 Agent 创建或恢复后、首次上下文组装前筛选工具目录；通用终端、文件、浏览器控制、Skill 和其他工具仍被隐藏并在执行入口拒绝。支持正常人格对话，消息和计划以外的业务优先安排独立任务。

在 Rabi 的 DSH 设置中选择这个会话模式并保存。新会话按所选模式创建，空白会话通过 DSH 的正式选择接口同步；已经开始过对话的会话不能切换模式，需要明确选择新的会话。Rabi 不可用时报告连接问题；联网搜索仍可查公开资料，但不能替代 Rabi 人格、记忆和计划真源。标准会话不受限制。


## 桌宠移动（0.13.20）

`rabiroute_manager_api` 支持 `POST /api/desktop-pet/roles/:roleId/motion` 和 `GET /api/desktop-pet/roles/:roleId/motion/:requestId`。请求体、Idempotency-Key 与完成状态从当前 Rabi `/api/agent/help` 获取。移动业务和动画归 Rabi；受理不代表抵达。Rabi助手模式工具集合不变，内部 runtime 接口不开放。