rachelforster/shinsekai/shinsekai-diagnostics

Shinsekai 故障排查

先定位失败环节，再提出最小修复。记录「已观察」「可能原因」「验证方法」，证据不足时保持假设，不把猜测写成结论。

收集证据

1. 确定版本、操作系统、桌面发行包或源码启动、实际启动命令、首次失败的步骤、最近改变的配置。
2. 按下方日志读取流程，优先使用宿主工具取得脱敏日志，选择与失败阶段、发生时间有关的文件；没有宿主工具时，再检查本机日志或请用户提供最少必要的错误上下文。
3. 不要求 API Key、完整凭据文件或未脱敏的全量日志。用户意外提供秘密时不重复展示，建议移除并视情况轮换。
4. 分清用户使用的环境与工具运行环境。检查进程实际可见的 PATH、Python 或模型配置，不能仅凭另一终端验证成功就宣称问题解决。

脱敏日志的位置与读取

<project_root> 指 Shinsekai 当前使用的项目数据根目录。源码启动时通常是仓库目录，桌面发行包使用实际选择的数据目录；可由 SHINSEKAI_PROJECT_ROOT 或 EASYAI_PROJECT_ROOT 指定。Pi session 的 workspace 不等于这个目录，不要直接在当前工作目录下猜测 logs/ 的位置，以宿主日志列表返回的实际路径为准。

这些目录中的结构化日志文件名为 YYYYMMDD-HHMMSS-<pid>.jsonl，轮转文件带 .1、.2 等后缀。SDK 日志默认脱敏凭据，并隐藏结构化字段中的对话和请求正文；SHINSEKAI_LOG_CONTENT 开启时会保留正文，排查时无需开启它。其他或旧版 .log、.txt 文件不能仅凭所在目录认定已经脱敏。

桌面助手使用 shinsekai.bridge.read：

1. 调用 {"operation":"logs.list"}，从 data.files 中按 path、relativePath、app 和 modifiedAt 选择相关进程、相关时间的文件。先看列表，不批量读取全部日志。
2. 调用 {"operation":"logs.read","body":{"path":"<列表返回的实际 path>"}}。宿主会对响应中的凭据再次脱敏；结合 data.content、data.entries 及 data.truncated 分析首条相关错误、上下文和时间顺序，读取被截断时说明证据范围。
3. 日志过大或宿主工具不可用时，可引导用户在日志页 /settings/logs 搜索错误，提供相关时间段的脱敏片段。使用 Pi 原生文件或 shell 工具时，只取所需片段并先过滤秘密；其结果不会经过宿主 HTTP 响应的脱敏处理。

按失败阶段缩小范围

常见恢复提示：AUTH_REQUIRED 检查 API 设置；BACKEND_UNAVAILABLE 检查准备状态；SESSION_BACKEND_MISMATCH 应用当前模型并新建 session；WORKER_LOST 保留已知结果，先核对再重新提交。仅在证据吻合时使用这些判断。

修复与验证

1. 针对证据最强的原因做最小调整，说明预期变化与验证方式。
2. 使用真实注册的工具执行已授权操作；没有执行能力时给用户明确步骤，不假装已经修改或运行。
3. 优先检查配置和环境，不用删除全部配置、重装应用或跳过校验作为默认解法。
4. 按用户原来失败的路径重新验证。报告实际执行的方法、输出及尚未验证的部分。
5. 写操作结果为未知或任务中断时，先查询当前状态，避免盲目重试造成重复修改。

输出

先说明可证实的原因或当前最可能的假设，然后给出修复步骤、验证结果和下一步。把「修复建议」「修改已提交」「原故障已验证消失」分别说清楚。