按现象查。每条先给最可能的原因,再给下一步。
安装与启动
| 现象 | 原因 / 处理 |
|---|---|
| macOS 提示无法验证开发者 | 构建为 ad-hoc 签名。右键 → 打开,或在 系统设置 → 隐私与安全性 里放行 |
| 商店版与安装包版设置不互通 | MSIX 把 %APPDATA% 重定向到 %LOCALAPPDATA%\Packages\XLBBB.RabbitChatStudio\LocalCache\,两版各有一份配置;工作区里的 .data 仍是共享的。切换时把旧配置复制到新目录 |
| 商店版永远不提示"有新版本" | 设计如此:商店负责更新,is_store_packaged() 让应用内检查直接答"已是最新"。用 Microsoft Store → 库 → 获取更新 |
| Windows 提示缺少 WebView2 | 安装 Microsoft Edge WebView2 运行时 |
| Linux 双击 AppImage 没反应 | chmod +x 后在终端里运行,看具体报错 |
| Linux 缺 WebKitGTK | 安装 Tauri 2 依赖,如 libwebkit2gtk-4.1-dev |
| 开发时 1420 端口被占 | Vite 用固定 strictPort;释放端口或停掉占用进程 |
npm run build 说没有 git tag |
先打 tag,或只构建前端用 npx vite build |
| 版本号不一致 | node scripts/sync-version.cjs --from-git-tag |
API 与模型
| 现象 | 原因 / 处理 |
|---|---|
401 Unauthorized |
密钥错误/过期;组织头;本地服务可能要求任意非空密钥 |
403 Forbidden |
账号权限、地区限制、模型未开通 |
404 Not Found |
基础地址错;不要带 /chat/completions;确认是否需要 /v1 |
429 Too Many Requests |
限流;降低并发/频率或换密钥。应用会重试 429/5xx 并遵守 Retry-After |
5xx |
供应商故障;在交互监视器里看错误 |
| 模型列表为空 | 供应商可能没实现 /models;手动填模型 id |
| 能聊天但工具从不执行 | 模型不支持工具;换成支持函数调用的模型 |
| 上下文窗口不对 | 手动设置;供应商不一定上报 |
| 附件被跳过 | 模型不支持视觉/文件/音频;换模型或去掉文件 |
reasoning_content 400 |
DeepSeek 思考模型;开启 DS-Format |
reasoning_effort 400 |
供应商拒绝该参数;思考深度设为默认 |
| 回复被截断 | 调大 最大补全 token;确认供应商上限 |
| 模型相似度匹配很低 | 合并目录不认识该 id,能力信息可能不全——手动设上下文窗口 |
聊天与历史
| 现象 | 原因 / 处理 |
|---|---|
| 发送按钮是灰的 | 输入为空且无附件;配置导出进行中;正在生成 |
| 生成过程中不能切换会话 | 设计如此;先按 Stop |
| Stop 之后内容还在 | Stop 只中断流式输出,已生成内容保留 |
| 历史是空的 | 历史按工作区;确认当前工作区 |
| 历史只显示标题 | 标题取首条用户消息;点进会话看完整消息 |
| 没有重试按钮 | 只有最后一条是未完成的用户消息时才显示 |
| 删除消息后上下文乱了 | 删除是物理的;需要时开新会话 |
| 分叉失败 | 该消息必须已有 dbId(已落库);稍等再试 |
| 导出 PDF 没反应 | 应用会把 PDF 写到所选路径;检查目录写权限,并在交互监视器里看错误 |
| 定时器在别的会话触发 | 正常;用提示里的 插入到输入框 |
| 聊天里看不到后台结果 | 设计如此:结果给模型而不是记录——看回复末尾的 后台任务 卡片 |
| 已经"最终答复"了却还在跑 | 待办还有开放条目,这就是目标循环;做完或取消,或用定时器 / [WAIT_EVT: …] 等待 |
| 还有开放条目却结束了 | 有定时器待触发、答复声明了 [WAIT_EVT: …],或已用满 4 次续跑 |
| 没有费用芯片 | 该轮供应商没有返回用量 |
工作区与数据
| 现象 | 原因 / 处理 |
|---|---|
看不到 .data |
Windows 隐藏属性;用终端或打开"显示隐藏项目" |
助手找不到 .data |
文件工具把它当普通目录——让它 list ./.data |
| 换了工作区技能/历史都变了 | 工作区级状态随目录切换 |
| 换工作区后打开了一个空白新对话 | 设计如此:切换工作区会落到新会话,避免旧记录与新目录混在一起 |
| 换工作区后第一次 MCP 调用很慢 | stdio 被停了,会在新工作区重启 |
| 数据库被锁 | 关掉其他占用 chat.db 的进程;应用会等自己的连接 |
| 磁盘占用高 | 调低日志保留、压缩数据库、删除旧会话 |
| 导入后 MCP/历史缺失 | 导入会恢复 mcp_servers.json;chat.db 仍需手动——关掉应用再复制 |
| 应用配置档后模型没变 | 配置档只含工具/智能体/MCP/编排 |
改 config.json 不生效 |
先完全退出应用;设置面板可能覆盖 |
| 第二个窗口丢了设置改动 | single_instance 关闭时额外窗口是配置分叉的影子窗口,只合并 workspace_history 回来——请在主窗口改设置 |
| 保存的工作区路径已不存在 | 应用会退回到应用数据目录下的默认工作区,而不是拒绝启动 |
技能
| 现象 | 原因 / 处理 |
|---|---|
| 没有技能 | .data/skills 存在吗?文件名是 skill.md / SKILL.md 吗? |
| 启用了却从不使用 | description 没写触发条件,或任务不需要它 |
use_skill 说找不到 |
文件夹名与 frontmatter name 不一致;当前工作区对吗? |
| 同一会话里改了不生效 | 已加载的技能不会重载;开新对话或重新启用 |
| 命令被拒 | 该可执行文件不在 allowed-commands 并集里 |
run_cmd 拒绝某个程序 |
它只运行 PATH 解析的名字;带路径请用 run_shell |
| 助手自己改了技能 | 自我进化模式开着;查看 .data/skills/*/*.bak.N |
| 文件操作 / 记忆是灰的 | 自我进化模式强制占用这两个工具 |
| 导入 zip 后名字不对 | frontmatter 的 name 才是权威 |
| 技能开关丢了 | skills.status 迁移问题或目录被删 |
工具
| 现象 | 原因 / 处理 |
|---|---|
| 模型从不调工具 | 工具被禁用;模型不支持;系统提示禁止了 |
| 确认弹窗不出现/卡住 | 检查是否有挂起的 ConfirmDialog;超过 120 秒视为拒绝 |
| 确认了却没执行 | 读工具结果;可能被路径或白名单拦住 |
Path ... outside the workspace |
file_actions 不能离开工作区;用 run_shell |
写 .data/chat.db 被拒 |
工作区数据库受保护——文件工具只能截断或删除它 |
run_cmd 里管道不工作 |
用 run_shell |
run_cmd 拒绝绝对路径 |
它只运行 PATH 解析的程序名;用 run_shell |
| 命令超时 | 调大 timeout_seconds(最大 3600)或用 serve |
| serve 下一轮就没了 | serve 进程树在轮次结束时被杀;长期服务请放应用之外 |
run_cmd 找不到工作区脚本 |
文件必须直接在 .data/scripts 下、用裸名调用(扩展名可省)——不支持子目录与路径 |
| patch 失败 | 上下文行不匹配;重新读取并原样复制 |
| 工具输出被截断 | 保留头部 6,000 + 尾部 2,000;缩小范围 |
| 自动接受没生效 | 检查 auto_accept_confirm_kinds(L0–L3 类型或 "*");external_agent 不在该面板 |
MCP
| 现象 | 原因 / 处理 |
|---|---|
找不到 npx / uvx |
缺 Node/Python;PATH;Windows 包装;看日志 |
| 测试卡住 | 首次下载包;网络/代理;看日志 |
initialize 失败 |
该命令不是 MCP 服务器;打印了非 JSON 横幅 |
| 远程 401 | auth_token;要求的请求头 |
| 远程 404 | URL 路径;SSE 与 Streamable HTTP 端点不同 |
| 工具列表为空 | 服务器没实现 tools/list;未启用 |
| 工具重名 | 只启用一个同名服务器 |
| 参数含空格 | 界面按空白切分;用包装脚本或改 JSON |
| 换工作区后工具失败一次 | stdio 被停;下一次调用会重启 |
| 残留进程 | 正常退出会清理;崩溃由 Windows job object 兜底 |
子智能体
| 现象 | 原因 / 处理 |
|---|---|
| 编排开着却直接回答 | 没有启用的智能体;编排失败;看日志 |
| CLI 测试失败 | 命令不在 PATH;Windows .cmd;读 --version |
| CLI 输出为空 | 提示没传进去;试试 stdin;看超时/退出码 |
| Cloud 401/403 | 令牌/请求头 |
| Cloud 结果为空 | result_path 不匹配 |
| 轮询一直不结束 | 状态路径/完成值/轮询 URL |
| 子智能体看不到文件 | cwd、权限、工具白名单 |
| Stop 后仍有进程 | 正常会杀;检查任务管理器与日志 |
| 任务监视器是空的 | 没跑过子智能体;工作区数据库换了? |
| 外部智能体没弹批准 | require_approval 关了;本次运行已批准过 |
| 子智能体互相刷消息 | 撞到每对上限并已通知规划器;确实是正常协作就调大 每对智能体消息数 |
| 交付物文件夹是空的 | 任务全部内联返回,或是 cloud 智能体(够不到工作区) |
定时器
| 现象 | 原因 / 处理 |
|---|---|
| 定时器不触发 | 应用必须在运行;检查 <工作区>/.data/timers.json;会话被删了? |
| 重启后定时器丢了 | timers.json 被删/损坏;它在该工作区的 .data,不在应用数据目录 |
| 换工作区后定时器没了 | 定时器按工作区;切回去或重新设置 |
| 启动时立刻触发 | 关闭期间已过期 |
| 在别的会话触发 | 用提示把提示词插入当前输入框 |
| 重复定时器 | timer_set 前先 timer_list |
| 子智能体不能设定时器 | 设计如此;只有主智能体有定时器工具 |
| 系统还是会睡 | 锁是尽力而为:Linux 需要桌面 D-Bus 服务;合盖与电源策略仍会休眠 |
更新
| 现象 | 原因 / 处理 |
|---|---|
| 看不到新版本 | 草稿未发布;预发布开关;没有平台资产;网络 |
| 下载失败 | 资产还在上传;代理;到 Release 页手动下载 |
| 安装包运行不了 | macOS 右键打开;Windows SmartScreen;Linux 执行权限 |
| 想用 winget 安装 | 暂无包管理器构建(winget / Homebrew / Scoop);用商店版或 Release 安装包 |
| 更新后配置丢了 | 检查安装方式/用户目录;更新不应删除应用数据 |
构建与发布
| 现象 | 原因 / 处理 |
|---|---|
| 构建要求 git tag | npm run build 会同步版本;先打 tag |
| Windows GNU 链接错误 | 用 MSVC 工具链 |
| Linux 缺 WebKitGTK | 安装 Tauri 2 依赖 |
| CI 报错:tag 不是最新 | 推送的 tag 必须是最新的 |
| CI 没有发布 | 手动 workflow_dispatch 只是冒烟测试;检查权限/密钥 |
| 站上缺少 Wiki 页 | node scripts/gen-wiki.mjs 失败,或工作流的路径过滤没包含 docs/wiki/**;看 Pages 运行日志 |
| winget 没提交 | 包还没被 winget-pkgs 接受,或缺 WINGET_TOKEN/fork;该工作流暂未启用 |
收集调试信息
提 issue 时请附:
- Rabbit Chat Studio 版本(设置 → 关于与更新);
- 操作系统与架构;
- 复现步骤与期望/实际结果;
- 截图;
- 交互监视器里的错误详情(先去掉 API 密钥、口令与业务数据);
- MCP 日志(MCP 问题);
- CLI 智能体的
--version输出(CLI 问题)。
不要公开:
- API 密钥;
- MCP 的
auth_token/env; - 完整
config.json/mcp_servers.json(先脱敏); - 含用户数据的
chat.db。