故障排查
先记录精确的包、DSH、Node、OS 版本,以及最后成功的步骤。公开日志只保留必要片段。去掉 token、API key、用户目录和作品正文。
| 现象 | 检查与处理 |
|---|---|
确定性检查等脚本报找不到 @deepseek-ai/dsh-llm |
8.3.0 的脚本打包问题,更新到 8.4.2 并重启。不要向 profile 手动补装 DSH 框架包;仍失败时保留完整错误和安装版本 |
| 工作区末行或按钮被裁切,切回书房后无法滚动 | 更新到 8.4.2。新版已修复DSH rc.3的侧栏绑定和高度,升级后重启 |
| 审读字数和编辑器全文数不同 | 编辑器含标点,也可能含候选事实和未保存内容。正式审读以脚本当前稿的 正文统计.汉字数 为准,见 计数口径 |
| 升级后篇幅核对显示“未配置” | 旧项目要保留原契约内容,并补充确认“章节篇幅”,见 升级步骤 |
| 编辑器 AI 操作提示需要写作模式 | 新建对话,选择“写作模式”,打开原工作区再试;旧对话不会自动迁移,手动编辑仍可用 |
| 世界书已有确认条目但模块不足 | 升级到 8.4.2。原生读取后,重新确认相应条目,以补齐声明。仍须有实际正文和最小模块内容 |
| 编辑器建议迟迟未出现,或重复发送被拒绝 | 核对当前主会话和请求状态。必要时取消这次请求,再调整要求重试。重启会丢失未完成的请求,详见 编辑器教程 |
发“你好”也报 Invalid schema for function 'novel_reference_analyze' |
这是 8.1.0 的参考工具参数兼容问题。升级到 8.4.2 并重启。四个参考工具一并修复 |
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 时,附上最小的合成复现、精确错误和相关文件名即可。
书仓无法写入#
工作台在写入书仓前会加锁,并先恢复上次中断的批次。下面三种情况会让写入失败。
| 报错或诊断 | 原因 | 处理 |
|---|---|---|
书仓写入锁定中 |
另一个写入操作正在进行 | 等几秒后重试一次。仍然失败时,关闭其他写作窗口 |
书仓锁获取曾中断 |
上次写入在加锁时异常退出,或暂时无法确认锁归属 | 先等 30 秒再重试一次。仍失败时,请作者核对归属,确认没有其他写作窗口后再清理 .webnovel/acquire.lock |
事务恢复冲突 或 已隔离的冲突事务 |
中断的批次和你后来的修改冲突 | 按下面的步骤处理隔离区 |
工作台会自动回收确认进程已退出的锁。心跳超时不代表进程已退出,不会仅凭超时抢占写入权。
.webnovel/writer.lock 是带进程身份文件的锁目录。归属不明时保留现场,先请作者核对。不要删除活跃进程的锁。
novel_get_story_status 的 书仓诊断 字段会列出残留锁和隔离的事务。它不是完整的书仓格式检查。
以下两个检查入口属于8.4.2。
需要检查格式时,让工作台调用 novel_check_book。它只报告问题和检查范围,不修文件、清锁、恢复事务或升级书仓。返回未检查、部分失败或无法核实时,不要把结果当作通过。
不要删除旧稿来绕过开章检查。已收尾章节的历史稿可以留档。明确开始新章时,工作台用 novel_begin_chapter 替换原状态查询。它先核对书级边界,再检查书仓,不创建章节。发现真正的未完稿、未提交归档或证据不足时,先恢复或人工核对,不继续全仓检查。
普通查询、同章恢复和改稿仍用 novel_get_story_status,不附加全仓检查。
警告
不要直接删除 .webnovel/quarantine/ 下的目录。先核对里面的备份。备份是中断前的原文。
处理隔离的事务:
- 打开
书仓诊断中给出的目录,例如.webnovel/quarantine/<编号>。 - 打开
quarantine.json,查看targets和reason。 - 对照
transaction/backups/中的备份和当前文件,决定保留哪一份。旧版隔离目录的备份仍在backups/。 - 需要恢复时,把备份内容复制回目标文件。
- 删除这个隔离目录。 成功时,涉及的文件可以重新写入。
隔离记录损坏时,工作台会尝试从原事务清单识别目标。仍无法识别时暂停所有写入,请作者先核对现场。
书仓格式升级与失败续办#
以下维护能力属于8.4.2。它处理有明确来源证据的 v8/DSH 旧格式,不是安装包更新,也不修改故事含义。
- 让工作台预览这本书的格式升级。
成功时,
novel_preview_book_upgrade列出文件差异、受影响工件和阻断项。预览不会写入。 - 核对全部差异。 先暂停写作和自动任务,保持 Git 干净且无写入锁或待处理事务。已核验的未完工件可以保留。整仓还有未支持或无法核实的内容时,先处理阻断项,不能只挑几个文件修复。
- 在本次升级问答中决定是否批准。
novel_apply_book_upgrade绑定刚才的精确预览。等待期间资料变化时,原批准失效,须重新预览。 - 核对结果中的提交状态。 “升级已提交”表示本批文件与格式标记已提交。“无需升级”表示没有新变化,不必重复操作。
预览分别列出“原书检查”和“拟变换后检查(未写入)”。后者通过不代表原书已升级。预计过期的材料会另列,实际复用前仍须复核。
分卷状态冲突时,报告会列出对应卷及小节、卷行状态。各卷状态不同,可以让小节标题不标状态,卷行分别声明。通过分卷布局工具保存已核对的完整内容。
旧草稿身份如果是一段文本,工具会核对目录与同卷同名的确认细纲或定稿。只有唯一章号证据才能转换,稿件版本不能当章号。无法证明时保留原稿并报告缺口。
预览会列出保留的未完工件。升级不再要求先完成本章,也不会删除草稿、材料或审核。草稿完整前后文保存在本地维护收据,Git 提交绑定收据校验值。继续写作前重核受影响证据;不要手改收据或哈希。
不要直接修改或删除 草稿区/.maintenance-receipts/ 的收据。它们用于核对原操作,不代表当前文学内容已经通过审读。
| 结果 | 下一步 |
|---|---|
| 已写待提交 | 保留原操作编号;处理具体原因后,让工作台用 novel_resume_book_upgrade 续办。只补原提交,不重新转换文件 |
| 已恢复,待重新预览 | 原中断批次已恢复;重新预览并决定是否批准升级,这不表示升级已完成 |
| 已核实原提交 | 原升级已有完整提交证据,本次没有重复写入,无须补交 |
| 收据损坏、指纹变化或冲突 | 保留当前文件和证据,先核对原因,不覆盖作者后来的修改 |
续办前,工作台会重新核对并请求作者批准。主动撤销已成功升级不在当前入口中,不要用重试代替撤销。材料或审核证据若受格式变化影响,按报告逐项复查;不会自动重建需要模型处理的内容。
DSH 版本不对怎么修复#
-
先按 安装教程的版本对应表 确认目标。 8.4.2 和检索增强 8.4.2 使用 0.2.2-rc.5。旧版 preview.6 和提供方 0.0.8 使用 0.1.5-rc.2。 宿主版本不匹配时,设置、工具和会话接口都会受影响。更高的版本也不代表已经兼容。
-
停止正在运行的 DSH 实例。
-
按 备份说明 保存工作区和 DSH home。 更换版本之后必须重启。已经在运行的进程不会自动换成新版本。
-
在 PowerShell 里检查实际命令和版本:
dsh --version pnpm --version Get-Command dsh -All | Select-Object CommandType, Source npm prefix --global -
如果当前是 npm 全局安装,按选定组合精确重装。下面的命令对应 8.4.2 / 检索增强 8.4.2:
npm install --global pnpm@11.27.1 @deepseek-ai/dsh@0.2.2-rc.5如果使用已发布的 preview.6,把末尾改成
@deepseek-ai/dsh@0.1.5-rc.2,并使用对应的已发布插件。不要把它和 8.4.2 / 检索增强 8.4.2 混装。其他安装渠道使用它们自己的版本管理方式。 -
关闭终端,再重新打开,然后执行
dsh --version。 如果仍显示旧版本,通常是 PATH 里还有另一份 DSH,或者 PowerShell 有同名的别名或函数。 -
用上面的
Get-Command dsh -All找到优先命中的路径,和 npm 全局目录比较。 -
切换到正确的安装目录,或通过原来的安装渠道移除多余安装。 不要删除 profile、会话或书仓来修 PATH。
-
确认插件包来自同一套兼容组合。
-
执行
dsh --profile scriptor --dump-config,然后重新启动。 先用临时工作区核对书房、设置卡片和技能。配置能输出,只说明这组配置可以读取。它不能代替实际启动检查。
警告
已经被较新 DSH 写入的会话,不要直接交给旧版读取。 0.1.7 使用 v4 会话格式。降级安装程序不会把日志改回 v3。保留当前现场。需要回退时,使用升级前的完整备份,以及与备份匹配的版本。先在副本里验证,再恢复。没有升级前的备份时,先保持能够读取该会话的版本,继续排查。不要手改会话格式号。
版本和来源都正确、却仍然失败时,保留精确错误、dsh --version 的输出,以及实际命令路径,再提交最小复现。不要反复更换宿主版本来尝试修复。
旧书卡在世界构建#
早期创建的书,可能已经有已确认的人物和规则,却没有在 世界书/模块声明.md 里登记对应模块。8.2.0 已修复确认条目时的自动登记。升级本身不会批量重写书仓。
-
先备份。
-
回到该书的主会话。
-
让主控用原生方式读取相关的已确认条目。
-
再以现有内容调用
novel_confirm_worldbook_entry来确认。 成功时,自动补齐最小模块和当前模块,并把条目与声明一起提交。 不需要用通用文件工具修改真源声明。 -
重新查询书仓进度。 人物档案和世界规则各自仍需要有正文的已确认条目。补登记不会自动补写设定,也不代表其他设计阶段已经完成。
如果读取或提交失败,保留原文件。按错误修正。不要整份替换声明。
设计确认或审核停住#
- 如果提示
FS_NOT_OBSERVED,让主会话先用原生读取工具读目标文件,再调用设计工具。进度卡和书房预览不能代替这次读取。 - 如果提示
FS_STALE_VERSION,说明目标已被作者或其他会话修改。重新读取并核对差异之后再确认。不要强行覆盖。 - 如果提示窗口未就绪,第一章章名必须和近期窗口里的一条可进入条目同名。先核对实际条目,再经设计工具修正。preview.6 会直接列出可进入的名称。
- 如果显示「已确认但无内容」,确认标签仍然保留。8.2.0 会把必要内容缺失放进就绪建议。先补上真实正文。合法的远期留白,不必强行填满。
- 如果 preview.5 显示「完成: false」,却显示「尚待回写模块: 无」,这是已知的审核清单问题。不能根据空清单当成审核完成。升级到 preview.6 之后,重新运行审核。
保存后反复更新契约#
保存后没有反应#
先分清改动从哪里进入,以及停在哪一步。
- 外部编辑器或终端修改:回到该书的对话。说明改了哪个文件、改动目的。请工作台读取现有文件并核对影响。刷新书房只更新文件树。示例见 修改设计或正文。
- 书房编辑器保存:分别检查文件保存、Git 提交和主控通知的结果。提交失败时,用编辑器的重试提交。通知失败时,用通知重试。已经保存的内容不必重写。
- 已交给主控,但没有核对结果:查看正确的主会话是否仍在运行,或已经被停止。可以发送“继续核对刚才对某文件的修改,先报告影响,不改其他文件”。通知送达,不等于模型已经处理完。
- 模型只输出
<invoke ...>等文本:这不等于真实的工具调用。如果界面没有出现工具执行结果,要求重新使用工具读取。记录 DSH 和模型版本、操作入口,以及脱敏后的结果,供排查使用。不要把模型打印出来的调用文本当作读取证据。
反复执行同一个无改动操作#
- 先停止当前任务。
- 按 升级步骤 更新到 8.4.2 和对应的 DSH,然后重启。
- 保存之后,只核对这次修改和它的影响。 “内容与已提交版本一致,无需补提交”表示这一步已经完成。不需要再添加文字来产生提交。 如果编辑器提示提交失败,使用编辑器的重试提交入口。
历史设计显示疑似模板占位#
8.2.0 会把与旧 seed 整份计划模板一致、却还没有匹配上的项,列为“疑似模板占位待核对”。它不会自动删除原文,也不会替你确认计划。
- 读取所列来源。
- 说明这些条目是实际计划,还是尚未补全的模板。
- 再委托工作台,通过原有的设计工具修正或补全。
只有事件同名,不会触发过滤。待核对也不等于已经兑现,或不存在偏离。