# 使用与故障排查

本页用于区分 Agent RP、Tavern Helper、世界书和 DSH Host 的故障。先保留具体错误，再决定应该更新、补兼容还是修复内容。默认关闭 Debug 时，「复制诊断」只说明哪条链路异常；开启全局 Debug 后，同一个按钮会附加当前会话内可用的失败详情。

## 更新后仍像旧版本

使用 README 中与当前平台对应的安装器更新，并重启实际提供页面的 DSH Host。默认安装器跟随 npm 的 `next` 标签；直接安装 GitHub 版本时，不要继续固定到旧提交，例如 `github:hewzhew/dsh-agent-rp#ac55cca` 永远只会安装该提交。反馈时请同时提供平台、DSH 启动方式、安装来源和实际安装的 Agent RP 版本。

不要只凭 DSH 的版本号判断 Host 能力。DSH Desktop、官方 runner 和 Agent Host 可能显示相同版本号，却包含不同的插件接口；各入口的支持范围见 README 的安装章节。

### 从 `@dsh-external` 包名升级后无法启动

早期版本使用 `@dsh-external/dsh-agent-rp`，当前版本使用 `@hewzhew/dsh-agent-rp`。请重新运行当前平台的安装器；安装器会先装好新包，再从同一 `web` profile 移除历史包名，并把未被本地修改的托管预设所有权更新为新包名。

若升级后曾出现 `duplicate loader entry id: dsh-agent-rp-host` 或 `has an invalid ownership manifest`，不要删除角色卡、会话或整个 DSH 数据目录。这两条错误分别表示 profile 同时保留了新旧包名，或托管预设仍记录旧所有者；当前安装器会迁移这两项。托管预设内容曾被本地修改时，安装器仍会拒绝覆盖，并要求先把修改复制到另一个 preset id。

## Tavern Helper 脚本失败

在发生问题的角色会话底部打开「脚本 x/y」。失败项会显示「加载失败」或「运行失败」；点击失败列表顶部的「复制失败详情」，检查后把完整结果附到 Issue。报告包含脚本名、全局/预设/角色作用域、失败阶段和有限长度的本地错误，不含脚本源码。

全局 Debug 默认关闭，此时「复制诊断」只包含聚合计数。如果报告显示 `failed: 1` 或 `load-error: 1`，可以打开「设置 → Agent RP → 诊断 Debug」，启用「在诊断复制中包含详细错误信息」，然后回到同一会话重新复制。Debug 报告会附加失败脚本的名称、作用域、阶段和有长度上限的本地错误。

## 世界书或 EJS 失败

在发生问题的角色会话顶部依次打开「会话设置 → 世界书」。存在失败条目时，界面会显示「复制失败详情」。全局 Debug 关闭时，结果包含世界书名、条目标识和稳定失败类别，并且不复制条目正文、关键词或表达式。全局 Debug 开启时，同一个按钮还会复制 EJS 隔离运行时返回的错误名称、消息和调用栈；各字段在进入投影前已经限制长度，截断会明确标记。模板可以主动把运行时值写入错误消息，因此发送 Debug 报告前必须检查具体内容。

没有失败时不会显示世界书失败详情复制按钮。若默认诊断报告 `world-engine-degraded`，可以启用全局 Debug 后重新点击「复制诊断」，也可以在世界书管理器重新点击「复制失败详情」。Debug 报告会附加世界书名称、来源、条目标识、失败类别、模板失败细分类别和本轮已有的 EJS 错误。如果当前会话的世界书页仍没有失败项，请确认选中的是同一个角色会话，并在更新、重启 Host、刷新页面后再检查。

## 行动选项没有出现

`<JSONPatch>...</JSONPatch>` 文本本身不足以定位故障。行动选项可能由状态结算、显示正则或 Tavern Helper 脚本呈现；其中任一阶段失败都可能留下补丁文本而没有按钮。请提供：

1. 从输入到缺少选项的最短操作步骤；
2. 全局 Debug 开启后，「脚本 x/y → 复制诊断」生成的结构化报告；
3. 如需分别核对，附上「脚本 x/y → 复制失败详情」与「会话设置 → 世界书 → 复制失败详情」中实际存在的报告；
4. 可公开时提供预设、角色卡或一个最小失败脚本。

`Invalid asm.js: Unexpected token` 是旧 Host bundle 内联并改写 `es-module-lexer` 后产生的 V8 警告，不是某个 Tavern 脚本的 `load-error`，也不能单独解释行动选项缺失。当前构建把该解析器保留为正常运行时依赖；更新并重启 Host 后仍出现时，请附上实际安装的 Git 引用和完整启动命令。

完整 HTML 轻前端里的 `getChatMessages(range, option)` 会同步返回消息数组。状态栏若发现 `Array.isArray(getChatMessages(...))` 为 `false` 或返回值是 Promise，说明浏览器仍在使用旧的 Agent RP 客户端资源；请更新插件、重启 Host，并在复现信息中附上页面实际加载的 `client.js?rev=...` 地址。

行动按钮调用 `createChatMessages` 时只能在玩家点击产生的浏览器激活期间追加一条用户消息；保存成功后紧随其后的 `/trigger` 只消费一次短时许可。页面加载后自动出现用户消息、一次点击创建多条消息或不点击就开始回复都属于 Host 校验失效；点击后既没有用户消息也没有回复时，请同时记录轻前端根节点的 `data-agent-rp-capability-state` 与外层 iframe 的 `data-agent-rp-capability-request`，以区分点击校验、Session 保存和生成触发阶段。

## 新角色会话进入「未分组」

从某个工作区里的空白会话打开 Agent RP 并开始游玩时，新角色会话应加入同一工作区。Agent RP 设置中的工作区开关只控制该工作区是否显示 Agent RP 入口，不负责把任意来源会话强制放进该工作区。

当前 Host 无法找到来源工作区或挂靠失败时，新会话仍会创建，并在页面右上角显示「新角色会话未加入工作区」及具体原因；Host 日志同时保留 `remains ungrouped` 记录。反馈时请复制这条原因，并说明来源空白会话在创建前显示在哪个工作区。不要只说“设置中已经绑定工作区”，因为入口授权与会话归属是两项不同状态。

## 「RP 互通」是什么

「RP 互通」是实验性可选工具，用于连接同一台电脑上另行运行的 [dsh-rp-distribution](https://github.com/yhny1001/dsh-rp-distribution)，在两套 RP 运行时之间复制角色卡、预设、Persona、世界书，或从模块化 RP 迁移会话。默认地址是 `http://127.0.0.1:3092`，只接受本机回环地址。

普通 Agent RP 游玩、SillyTavern 导入和 Tavern Helper 兼容均不需要这项服务。没有安装 `dsh-rp-distribution` 时可以忽略该设置，连接失败也不会影响现有角色会话。

## 提交 Issue 前

请提供预期表现、实际表现、最短复现步骤、平台、DSH 启动方式、Agent RP 安装来源和版本。不要上传 API Key、NPM Token、完整私人对话、无权再分发的角色卡或完整 Session Log。脚本与世界书的「复制失败详情」已经限制内容范围，优先使用这两个入口。开启 Debug 后的「复制诊断」还会包含脚本名称、本地错误、世界书名称和条目标识；发送前必须检查报告内容，诊断不会自动上传。