常见问题

按主题整理的高频问题；每一条都对应到具体机制或命令。遇到这里没写的，去 GitHub 提 Issue（附日志片段与复现步骤）。

安装与启动

桌面版安装报 Error opening file for writing: …vec0.dll

原因是上一次运行留下了没退干净的后端进程，加载着 sqlite-vec\vec0.dll。处理：任务管理器结束所有 Hetu.Api.exe 后点「重试」。新版本安装包内置安装钩子，会在覆盖文件前自动清理残留进程。

源码运行打不开 5174

• 先确认后端在跑：curl http://localhost:5000/api/health。
• 前端首次运行要先 npm install；Vite 端口被占会自动换端口，看终端输出。

想换端口 / 数据目录

后端用 --urls 指定地址，用 HETU_DATA_DIR 指定数据目录；前端 Vite 端口在 frontend/vite.config.ts 的 server.port。

模型

能只用本地模型吗

可以。任何暴露 OpenAI 兼容接口的本地服务（Ollama / LM Studio / vLLM 等）都能作为供应商，填本地 Base URL 即可。Embedding 也用本地模型时，注意把维度与 Embedding:Dimensions 对齐。

为什么 Anthropic 不能做 Embedding

Anthropic 没有公开 Embedding 接口。把 embedding 用途指到 OpenAI 兼容供应商即可。

模型报错 / 超时怎么排查

• 供应商配置页有连接测试；先用 chat 用途的模型测试。
• 用量页的明细里能看到失败请求的时间与来源，结合 logs/ 里的后端日志定位。
• 本地推理服务要注意上下文长度与并发：长会话压缩后仍然超限时，降低单轮注入的检索条数。

索引与检索

索引卡住 / 覆盖率上不去

• 看「后台任务」是否有失败记录，失败原因写在任务详情里。
• 确认 Embedding 供应商可用：知识库 → 搜索测试，看是否返回命中。
• 换过 Embedding 模型会导致维度不匹配，需要重新索引。

语义搜索结果不理想

• 先确认该项确实已索引（索引管理里看分块数）。
• 问法换得更具体；在搜索测试里调 Top-K 观察召回差异。
• 结构化的长笔记比零散记录更容易被切出好的块。

Code 会话与工作树

工作树会不会影响我的仓库

不会。工作树是 git worktree 创建的独立目录（默认在仓库父目录的 .hetu-worktrees/ 下），有自己的分支和工作区；主仓库目录的当前分支与文件不受影响。

会话中途想换分支

会话开始后工作区与分支固定，避免改动错位；换环境请新建会话，或在「Git」面板里操作。

工作树越来越多

设置 → 工作区里开启自动清理并设定空闲阈值（默认只删已合并且干净的工作树），也可以点「立即清理」手动跑一次；关闭自动清理时需自己删目录或用 git worktree remove。

PR 面板提示找不到 gh / glab

PR 功能复用本机的 GitHub CLI / GitLab CLI；面板会按平台给出安装命令（例如 winget install --id GitHub.cli），装完点刷新。

更新

报 Could not fetch a valid release JSON from the remote

更新清单没取到。请升级到最新版；仍失败时用浏览器打开 https://github.com/wosledon/Hetu/releases/latest/download/latest.json（slim 渠道换成 latest-slim.json）确认可访问，再检查网络对镜像（ghproxy.net 等）的连通性。

性能与体积

数据多了会不会变慢

列表与统计都在数据库侧完成（COUNT + OFFSET/FETCH、GROUP BY 聚合），状态类接口有短时缓存；万级笔记量下翻页与统计仍是常量级开销。

数据库文件多大

主要是向量：每块一个向量（默认 1536 维 float32 ≈ 6 KB）。想减小体积可以降低块数量（更少但更长的分块）或使用维度更小的 Embedding 模型（需同步改配置并重新索引）。

能离线用吗

应用本体完全离线可用；只有使用云端模型、联网搜索或外部 MCP 服务时才需要网络。