FAQ 与排错

检索相关

明明有这篇笔记，Agent 却说找不到

• search 默认覆盖 Markdown 和 TXT 笔记，以及已索引的 DOCX/PDF 文档；用 fileTypes 可以只查某一类。
• 文档要先被扫描到（.docx/.docm/.pdf），旧版 .doc 不支持，请另存为 .docx。
• 检查这篇笔记所在的知识库是否在当前会话的授权范围里。

扫描件 / 文档里的图片读不出来

不做 OCR：页面和图片必须交给支持视觉的模型。到 设置 → 模型 → Provider 打开「支持视觉」，再让 Agent 用 read 读该文档；未开启时工具结果会返回 visionUnavailable 并说明原因。

PDF 会由内置的纯 Rust 渲染器把页面转成图片，不需要另外安装 PDFium。

引用能跳到原文吗

可以。回答底部的资料库引用可点击：PDF 跳到对应页，DOCX 切到文本视图并高亮对应结构块。文件已删除或改名时会给出提示。

PDF 阅读器支持页码导航，并可在顶部搜索框输入文字，命中后跳到对应页（只跳页，不做页内高亮）。

DOCX 的页码为什么和 Word 里不一样

DOCX 没有可靠的物理页码，橘记用结构块和标题路径定位；需要页码时请导出为 PDF 再读。DOCX 阅读器提供「版式视图 / 文本视图」切换，版式视图在本地渲染表格、图片和页眉页脚。

语义检索显示回退到关键词了

常见原因：

• embedding 服务不可用（探测一下连通性）。
• 索引为空，或还在构建中。
• provider / model 配置变了，索引需要重建。

过程面板会显示 keyword_fallback，并给出原因。

引用里的行号和我看到的对不上

引用定位是「标题路径 · L起-L止」，基于被索引时的文件内容。文件之后被外部修改过，行号可能偏移。

写入相关

Agent 说改了，但文件没变

检查会话的安全级别和是否在计划模式：

• 计划模式下 edit / write 对模型不可见，不会产生写入。
• 基础 / 进阶级别需要你在 diff 界面确认。

确认写入时报 hash 不匹配

说明你审阅 diff 之后，文件被别的程序改过。橘记会拒绝覆盖，重新生成一次 diff 再确认即可。

想关掉每次确认

选择「完全权限，无需审批」（full-auto），并确认真实环境自动执行能力。它只自动应用本次工具新生成的变更，旧 pending 仍须单独处理；冲突检查继续执行。

模型相关

本地 Ollama / LM Studio 连不上

• 确认服务已经启动，地址填的是本机地址。
• 本地服务强制使用回环地址，不能用远程地址冒充本地。

云端模型提示需要授权上传

云端 embedding 需要显式同意上传（allow_cloud_upload），授权绑定当前配置指纹。改了配置就需要重新授权。

浏览器相关

浏览器功能打不开

• 功能默认关闭，需要先在设置里启用。
• 需要先下载浏览器内核。
• 只有本机交互会话、进阶级别及以上可用。

IM 相关

在群里发消息机器人没反应

群聊必须直接 @ 机器人。

收到「未授权」提示

发送人或群还没有被允许。去 设置 → 即时通讯 → 待授权对象 里点允许，然后保存设置。

开发相关

Windows 上 cargo 找不到

首次安装 Rust 后需要重启终端或 IDE，让 cargo 进入 PATH。可以用下面的命令确认环境：

rustup default stable-msvc
npx tauri info

还没解决？

到 GitHub Issues 反馈，附上运行日志里对应的片段。