故障排查

分别检查两个进程

• 后端不可用 — 检查终端 A，试试 curl --fail http://127.0.0.1:4318/api/health，确认 HOST 和 PORT 跟教程一致。
• 页面打不开 — 检查终端 B。如果 3001 端口被占了，停掉你自己的冲突进程，或者有意识地选一个后端允许的前端 origin。这个版本后端的 CORS 接受 localhost/127.0.0.1 的 3000 和 3001 端口。
• 页面正常但 API 或 WebSocket 不通 — 确认使用了 NEXT_PUBLIC_API_BASE_URL 和 NEXT_PUBLIC_WS_BASE_URL，中间有 _BASE_。旧版 README 里缺少这部分的示例跟当前源码不匹配。改完环境变量后要重启 Next。
• SQLite 原生绑定失败 — 确认 Node 22，然后在当前运行时下重新跑锁定安装。用其他 Node 版本安装的原生模块可能需要重建，看具体错误信息。

区分空数据、新工作台和已有工作台

新的 DB_PATH 会创建一个全新的工作台。初始化配置只在数据库的房间为空时才运行；编辑初始化文件不会自动替换已有房间。重启时用相同的 DB_PATH 和 ARCHIVE_DIR。相对路径会随工作目录变化，所以"快速开始"给的是绝对路径。

归档列出来了但读不了的话，检查配置的归档目录下对应文件是否还在。导出报错可能是路径不存在、JSON 无效或目标目录不可写。导出器生成的是 template.json，不是完整的数据库备份。

对话没有推进

检查 provider/model 设置、选中的角色，以及 ASK 面板里有没有等待回答的问题。本地归档成功不等于验证了凭据、provider 可用性或模型行为。排错时不要反复启动自动对话。查看本地日志就好，不要把凭据或完整的私人对话贴出去。

此版本已知限制

这是一个开发中的网页应用，不是已经验证的桌面发行版或多用户托管服务。浏览器标题和产品 README 用的名字不同。模板导出器会省略显示定义，详见归档与预设。本次首次使用验收覆盖了本地变量、归档和预设输出；真实模型对话质量和 OAuth 不在验证范围内。