文档开发者

常见问题

按现象查。每条先给最可能的原因,再给下一步。

安装与启动

现象 原因 / 处理
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。

还可以看哪里

源文件: docs/wiki/zh/faq.md ↗ · 文档版本 v3.3.3