DSH Scriptor v8.2.0

故障排查

先记录精确的包、DSH、Node、OS 版本，以及最后成功的步骤。公开日志只保留必要片段。去掉 token、API key、用户目录和作品正文。

现象 检查与处理
审读字数和编辑器全文数不同 编辑器含标点，也可能含候选事实和未保存内容。正式审读以脚本当前稿的 正文统计.汉字数 为准，见 计数口径
升级后篇幅核对显示“未配置” 旧项目要保留原契约内容，并补充确认“章节篇幅”，见 升级步骤
世界书已有确认条目但模块不足 升级到 8.2.0。原生读取后，重新确认相应条目，以补齐声明。仍须有实际正文和最小模块内容
编辑器建议迟迟未出现，或重复发送被拒绝 核对当前主会话和请求状态。必要时取消这次请求，再调整要求重试。重启会丢失未完成的请求，详见 编辑器教程
发“你好”也报 Invalid schema for function 'novel_reference_analyze' 这是 8.1.0 的参考工具参数兼容问题。升级到 8.2.0 并重启。四个参考工具一并修复
invalid skill name "工作台总控" 中文标题被当成了加载名称。实际调用是 skill({"name":"novel-director"})。8.2.0 已修正提示和技能路由表
找不到 dsh/pnpm 新开终端。核对 Node/npm 的全局安装目录是否在 PATH 里，再查看 dsh --version
安装插件报 ERR_PNPM_ADDING_TO_ROOT 终端里的 pnpm 不是 11.27.1。用 pnpm --version 核对后，重装指定版本
启动后没有 Web 页面 确认自定义 profile 来自 --from-default-profile web。基础 profile 不会自动变成 Web
安装 tgz 报路径被拆开 把文件放到有写权限、并且路径里没有空格的目录。只在外层加引号，可能仍解决不了当前 DSH 的转发限制
安装时出现 missing peer 提示 DSH 提供这些组件。如果实际启动时缺模块，按下方的版本修复步骤核对 DSH 和插件组合
升级后设置消失、插件加载报 API 不存在，或会话格式错误 先核对精确的 DSH 版本和插件来源。不要靠反复安装 latest，也不要靠删除数据来试错
页面连接被拒绝 使用当前启动进程给出的完整链接。确认端口和进程仍在。不要复用过期 token
端口已占用 换一个空闲端口。确认不是重复启动了同一个 profile
工具或技能出现两份 同一个 profile 里，主包和完整版只能留一个。停止实例，卸载多余的那个，再重启
模型认证、额度或限流失败 在 DSH 设置里核对服务、模型和凭据。先发短消息。不要反复重跑昂贵的章节
向量维度不匹配 核对实际模型的输出维度，以及高级设置里的“将维度参数发送给 API”。配置改变后，重建对应索引
检索回退或场景识别失败 查看可选服务的状态。基础检索可能仍可用。回退不等于增强服务成功
编辑保存冲突 重新读取当前文件和版本，核对他处的修改，再保存。不要强行覆盖
进度和聊天印象不同 让工作台重新核对实际书仓。模型写出的文字不是定稿证据，也不是提交证据

警告

内容损坏时，先完整备份现场。 不要手动删除或改写书仓里的文件，来尝试“清空恢复”。提交 Bug 时，附上最小的合成复现、精确错误和相关文件名即可。

DSH 版本不对怎么修复#

  1. 先按 安装教程的版本对应表 确认目标。 8.2.0 和检索增强 8.2.0 使用 0.2.0-rc.2。旧版 preview.6 和提供方 0.0.8 使用 0.1.5-rc.2。 宿主版本不匹配时，设置、工具和会话接口都会受影响。更高的版本也不代表已经兼容。

  2. 停止正在运行的 DSH 实例。

  3. 按 备份说明 保存工作区和 DSH home。 更换版本之后必须重启。已经在运行的进程不会自动换成新版本。

  4. 在 PowerShell 里检查实际命令和版本：

    dsh --version
pnpm --version
Get-Command dsh -All | Select-Object CommandType, Source
npm prefix --global

  5. 如果当前是 npm 全局安装，按选定组合精确重装。下面的命令对应 8.2.0 / 检索增强 8.2.0：

    npm install --global pnpm@11.27.1 @deepseek-ai/dsh@0.2.0-rc.2

    如果使用已发布的 preview.6，把末尾改成 @deepseek-ai/dsh@0.1.5-rc.2，并使用对应的已发布插件。不要把它和 8.2.0 / 检索增强 8.2.0 混装。其他安装渠道使用它们自己的版本管理方式。

  6. 关闭终端，再重新打开，然后执行 dsh --version。 如果仍显示旧版本，通常是 PATH 里还有另一份 DSH，或者 PowerShell 有同名的别名或函数。

  7. 用上面的 Get-Command dsh -All 找到优先命中的路径，和 npm 全局目录比较。

  8. 切换到正确的安装目录，或通过原来的安装渠道移除多余安装。 不要删除 profile、会话或书仓来修 PATH。

  9. 确认插件包来自同一套兼容组合。

  10. 执行 dsh --profile scriptor --dump-config，然后重新启动。 先用临时工作区核对书房、设置卡片和技能。配置能输出，只说明这组配置可以读取。它不能代替实际启动检查。

警告

已经被较新 DSH 写入的会话，不要直接交给旧版读取。 0.1.7 使用 v4 会话格式。降级安装程序不会把日志改回 v3。保留当前现场。需要回退时，使用升级前的完整备份，以及与备份匹配的版本。先在副本里验证，再恢复。没有升级前的备份时，先保持能够读取该会话的版本，继续排查。不要手改会话格式号。

版本和来源都正确、却仍然失败时，保留精确错误、dsh --version 的输出，以及实际命令路径，再提交最小复现。不要反复更换宿主版本来尝试修复。

旧书卡在世界构建#

早期创建的书，可能已经有已确认的人物和规则，却没有在 世界书/模块声明.md 里登记对应模块。8.2.0 已修复确认条目时的自动登记。升级本身不会批量重写书仓。

  1. 先备份。

  2. 回到该书的主会话。

  3. 让主控用原生方式读取相关的已确认条目。

  4. 再以现有内容调用 novel_confirm_worldbook_entry 来确认。 成功时，自动补齐最小模块和当前模块，并把条目与声明一起提交。 不需要用通用文件工具修改真源声明。

  5. 重新查询书仓进度。 人物档案和世界规则各自仍需要有正文的已确认条目。补登记不会自动补写设定，也不代表其他设计阶段已经完成。

如果读取或提交失败，保留原文件。按错误修正。不要整份替换声明。

设计确认或审核停住#

  • 如果提示 FS_NOT_OBSERVED，让主会话先用原生读取工具读目标文件，再调用设计工具。进度卡和书房预览不能代替这次读取。
  • 如果提示 FS_STALE_VERSION，说明目标已被作者或其他会话修改。重新读取并核对差异之后再确认。不要强行覆盖。
  • 如果提示窗口未就绪，第一章章名必须和近期窗口里的一条可进入条目同名。先核对实际条目，再经设计工具修正。preview.6 会直接列出可进入的名称。
  • 如果显示「已确认但无内容」，确认标签仍然保留。8.2.0 会把必要内容缺失放进就绪建议。先补上真实正文。合法的远期留白，不必强行填满。
  • 如果 preview.5 显示「完成: false」，却显示「尚待回写模块: 无」，这是已知的审核清单问题。不能根据空清单当成审核完成。升级到 preview.6 之后，重新运行审核。

保存后反复更新契约#

保存后没有反应#

先分清改动从哪里进入，以及停在哪一步。

  • 外部编辑器或终端修改：回到该书的对话。说明改了哪个文件、改动目的。请工作台读取现有文件并核对影响。刷新书房只更新文件树。示例见 修改设计或正文。
  • 书房编辑器保存：分别检查文件保存、Git 提交和主控通知的结果。提交失败时，用编辑器的重试提交。通知失败时，用通知重试。已经保存的内容不必重写。
  • 已交给主控，但没有核对结果：查看正确的主会话是否仍在运行，或已经被停止。可以发送“继续核对刚才对某文件的修改，先报告影响，不改其他文件”。通知送达，不等于模型已经处理完。
  • 模型只输出 <invoke ...> 等文本：这不等于真实的工具调用。如果界面没有出现工具执行结果，要求重新使用工具读取。记录 DSH 和模型版本、操作入口，以及脱敏后的结果，供排查使用。不要把模型打印出来的调用文本当作读取证据。

反复执行同一个无改动操作#

  1. 先停止当前任务。
  2. 按 升级步骤 更新到 8.2.0 和对应的 DSH，然后重启。
  3. 保存之后，只核对这次修改和它的影响。 “内容与已提交版本一致，无需补提交”表示这一步已经完成。不需要再添加文字来产生提交。 如果编辑器提示提交失败，使用编辑器的重试提交入口。

历史设计显示疑似模板占位#

8.2.0 会把与旧 seed 整份计划模板一致、却还没有匹配上的项，列为“疑似模板占位待核对”。它不会自动删除原文，也不会替你确认计划。

  1. 读取所列来源。
  2. 说明这些条目是实际计划，还是尚未补全的模板。
  3. 再委托工作台，通过原有的设计工具修正或补全。

只有事件同名，不会触发过滤。待核对也不等于已经兑现，或不存在偏离。

在 GitHub 上查看或改进此页