用户完整使用手册.md

# Book Agent 用户完整使用手册

> 适用对象：第一次使用 Book Agent、希望让自己的 AI 助手按书回答问题的读者。
>
> 本手册面向 0.1.0 系列交付。实际文件名、大小、哈希和可用命令以你下载的 release-manifest.json、随包说明和程序帮助为准。阅读本手册不会替你安装或发布任何网站。

## 目录：按你现在要做的事阅读

| 你现在的情况 | 先看这里 |
| --- | --- |
| 不知道这是什么，也不认识 Python、MCP、向量 | [一、先看懂它做什么](#一先看懂它做什么) |
| 只想尽快用起来 | [二、第一次使用的最短路线](#二第一次使用的最短路线) |
| 想从私人网站下载安装 | [三、从网站下载需要哪些文件](#三从网站下载需要哪些文件) |
| 想把安装交给另一个 Agent | [四、可以直接复制的安装提示词](#四可以直接复制的安装提示词) |
| 自己操作 Windows，不知道文件夹放哪里 | [五、准备本机文件夹](#五准备本机文件夹) |
| 想知道新的一次性安装入口 | [六、批量安装入口](#六批量安装入口) |
| 想理解手动导入、检查、连接的过程 | [七、手动安装与检查](#七手动安装与检查) |
| 已经安装好，想问问题、看原文或图表 | [八、日常提问与引用](#八日常提问与引用) |
| 想启用本地或在线向量搜索 | [九、检索方式和原文阅读的选择](#九检索方式和原文阅读的选择) |
| 有很多本书，想避免串书和重复安装 | [十、多本书共用一套环境](#十多本书共用一套环境) |
| 使用 Codex、TRAE、WorkBuddy 或 Cherry Studio | [十一、各宿主的操作差异](#十一各宿主的操作差异) |
| 想换电脑、恢复或卸载 | [十二、迁移备份与卸载](#十二迁移备份与卸载) |
| 看到错误或不知道是否成功 | [十三、问题排查](#十三问题排查) |
| 关心隐私、联网、许可证或已验证范围 | [十四、隐私与边界](#十四隐私与边界)和[十五、验证范围](#十五验证范围) |
| 需要把问题交给技术人员 | [十六、给技术人员的参考](#十六给技术人员的参考) |

## 一、先看懂它做什么

### 1.1 一句话说明

Book Agent 给你的 AI 助手提供一套“查书、取证据、回到原文”的工具。你把预先制作好的完整书包放在本机，导入后，助手就可以按书检索内容、读取相应段落、定位 PDF 页面或 EPUB 章节，并在支持图片的宿主中接收页面图片。

例如，你可以问：

> 请只依据《示例书 A》解释这个概念，给出书中的证据；如果找到原文位置，请同时标出位置。证据不足时请说明。

Book Agent 负责取出相关材料。你正在使用的 Codex、TRAE、WorkBuddy 或 Cherry Studio 中的主 AI 负责阅读材料、组织答案。

### 1.2 你实际需要的三个部分

| 部分 | 可以理解成 | 由谁提供 |
| --- | --- | --- |
| 宿主里的主 AI | 回答问题的助手 | 你自己的宿主、账号及模型设置 |
| Book Agent | 助手的查书工具 | 本项目的程序、Skill 和运行配置 |
| 完整书包 | 已经整理好的书架内容 | 书包制作者或你已有的交付包 |

完整书包中保留了原书，也包含已经准备好的 Markdown、Book Skill 和检索数据库。Book Agent 使用这些现成材料，不会在安装时重新处理整本书。

### 1.3 不认识这些术语也能开始

| 文档中的词 | 通俗意思 |
| --- | --- |
| 宿主 / Host | 你与 AI 聊天的那个程序 |
| Agent | 能替你读文件、调用工具、执行安装操作的 AI 助手 |
| Skill | 告诉助手“遇到查书问题该怎样做”的说明文件 |
| MCP | 助手与查书工具沟通的接口；本项目在本机运行 |
| 书包 / package | 一整套书的成品文件，不只是 PDF |
| Book ID | 程序为某一份书内容分配的身份编号 |
| 数据目录 / data-dir | 存放注册信息、运行配置和缓存的独立文件夹 |
| 原文定位 | 找出证据在 PDF 或 EPUB 中的实际位置 |
| 文本检索 | 用字词、短语等线索找相关内容 |
| 语义向量 | 用一串数字表示问题的含义，再与现成的书籍向量比较 |
| 查询模型 | 只负责把你当前的问题变成向量的可选模型 |
| 权重 / weights | 本地查询模型需要读取的大文件 |
| API Key | 一些在线服务的访问凭据；默认方式不需要 Book Agent 的 Key |
| SHA-256 / 哈希 | 文件的校验指纹，用于发现损坏或与预期文件不一致 |
| dry-run | 预览将做的事情，通常不写入宿主；不能据此声称已经安装成功 |

你不必先学会向量算法、Python 编程或 MCP 协议。第一次可以从原文阅读模式开始。

### 1.4 默认不需要你提供什么

默认的原文阅读与文本检索方式：

- 不要求 Book Agent API Key。
- 不要求下载查询模型权重。
- 不要求你知道查询模型叫什么。
- Windows x64 预编译程序不要求另装 Python。
- 不会因为你导入书包，就自动下载模型、调用付费服务或重建整本书的向量。

宿主的主 AI 是另一项设置。宿主可能需要账号、订阅、网络或自己的模型 Key，这取决于你已经选择的聊天产品。Book Agent 默认不需要 Key，不代表宿主的主 AI 自动免费，也不代表主 AI 自动离线。

### 1.5 这不是把任意 PDF 自动变成知识库的转换器

本版本接收已经完成制作的书包。裸 PDF、裸 EPUB、只有 Markdown 的文件夹、只有数据库的文件夹，不能直接当作完整书包导入。

缺少整理材料时，先联系书包制作者取得完整版本，或使用独立的上游制书流程。当前安装流程不会自动做 OCR、切分整本书、生成文档向量或补造缺失的 Book Skill。

## 二、第一次使用的最短路线

### 2.1 如果你不知道该选哪种方式

先选“原文阅读 / 文本检索”。安装体积较小，能够用现成文字检索、读章节、回到原文，也能请求 PDF 页面图或 EPUB 内的图片。

| 网站上的方式 | 适合你吗 | Book Agent 额外需要什么 | 问题会发送到查询服务吗 |
| --- | --- | --- | --- |
| 原文阅读 / 文本检索，命令模式 text 或 vector-search none | 第一次使用；不想下载大模型；愿意提供书名、章节、关键词 | 默认程序、完整书包 | 不会由 Book Agent 发送到远程查询向量服务 |
| 本地语义检索，offline | 希望换一种表达也能找相关段落；愿意下载模型并准备本地运行环境 | 一套可选 CPU 依赖、一份兼容查询模型权重 | 查询向量在本机计算 |
| 在线语义检索，online | 已有兼容服务和自己的 Key，接受当前问题发送给该服务 | 兼容服务、环境变量中的 Key、明确的联网授权 | 会发送当前问题；可选远程重排另有不同数据范围 |

这里的“原文阅读”也包含文本搜索，并非只能逐页翻 PDF。“本地语义检索”和“在线语义检索”都仍然可以读原文。

### 2.2 最短路线清单

1. 先确认你的宿主能正常与主 AI 聊天。
2. 下载首选 book-agent-starter-windows-x64.zip 及本次发布说明、校验清单。
3. 准备一份或多份完整书包。
4. 把程序放在固定文件夹，完整保留程序旁的配套文件。
5. 把[第四节安装提示词](#四可以直接复制的安装提示词)交给有本机文件操作能力的 Agent。
6. 让 Agent 用原文阅读模式导入书包、连接当前助手或你另行选择的宿主，并给出真实结果。
7. 按宿主需要刷新、重启、启用工具或导入 Skill。
8. 用本手册的首次提问示例问一个书中确实存在的问题。
9. 要求答案带书名、证据和原文位置，确认它确实调用了查书工具。

不要通过聊天界面显示“安装完成”四个字来判断成功。至少要区分：文件已准备、书已导入、宿主配置已写入、工具实际连接、助手实际查书回答。图像理解还需要单独确认。

### 2.3 什么样的首次问题更容易判断成功

选一个你能在书里核对的问题，例如：

> 请先列出已经导入的书。然后只依据《示例书 A》查找“边界条件”的定义。请调用查书工具，给出证据 ID 和原文位置；如果原文位置没有验证，请直接说明。

这种问题比“总结所有书的全部内容”更适合第一次确认。后者可能需要很多次读取，检索结果也不能证明助手已经阅读全文。

## 三、从网站下载需要哪些文件

### 3.1 私人网站的作用

拿到整份网站交付目录时，先读根 README.md；它说明当前交付状态和启动方式。平时从网站下载时，按页面和随包说明操作即可。

私人网站可以放下载链接、使用说明、版本信息和校验指纹。文件下载到你的电脑后，Book Agent 在你的电脑中运行。

只把安装包放上网站，不会自动建立远程书籍服务，也不会让网站拥有你的本机书库。若网站要求登录，登录通常只是控制谁能下载；它与本机宿主的模型账号和在线查询 Key 分别管理。

不要把自己的私有书、账号配置、Key 或本机运行数据传给网站，只为获得默认安装而上传整本书并不是本项目默认流程。

### 3.2 原文阅读模式的下载清单

| 内容 | 是否需要 | 用途 |
| --- | --- | --- |
| book-agent-starter-windows-x64.zip | Windows 新手首选 | 默认程序、Skill、安装.ps1 与新手说明 |
| 安装.ps1、给安装 Agent 的说明 | starter 内提供；完整发布根目录也有 | 批量导入和连接书库，使用本次真实参数 |
| 用户手册与交付说明 | 建议 | 帮你选择方式和排错 |
| release-manifest.json | 需要保留 | 列出正式文件、大小与哈希 |
| SHA256SUMS.txt | 建议保留 | 便于人工核对下载文件 |
| 完整书包 | 必需，但可从你已有的私有来源取得 | 提供原书和现成整理材料 |
| 单独的 Skill 压缩包 | 手动导入某些宿主时需要 | 不能替代查书程序与书包 |
| 源码、Python wheel、源码 tar.gz | 普通 Windows 用户通常不需要 | 技术人员安装或二次开发路线 |

默认程序与 Skill 都不包含你的私人书籍，也不包含查询模型权重。

### 3.3 本地语义检索还需要什么

在上面的基础上增加：

- book-agent-offline-addon-windows-cp313.zip 中与本次交付匹配的可选 CPU 依赖文件。
- 本次交付支持的 Python 运行环境；当前 Windows 离线 wheel 配套范围为 CPython 3.13、Windows x64。
- 一份兼容查询模型权重目录。
- 安装入口说明或 install-offline.py。

Windows 预编译 EXE 的默认功能与 Python 本地查询环境是两条运行路线。本地语义查询请使用已经装好可选依赖的共享 Python 环境，再让宿主启动该环境的程序。

目前的 BAAI-bge-m3 权重目录总大小约 2.29 GB（十进制），主要是模型权重和分词器文件。网站如果提供独立模型下载，按最终清单下载一次，放到共享目录。不要为每本书、每个宿主分别重复下载同一份模型。

六个固定上游模型文件与模型收据构成当前运行所需材料，交付目录另外提供 README.md、MODEL-LICENSE.md、UPSTREAM-LICENSE.txt，记录来源与许可。不要把“只有 model.safetensors”误认为完整模型，也不要把普通压缩包直接当作 --model-dir；需要按交付说明得到真正的模型目录。

### 3.4 在线语义检索还需要什么

你需要自己拥有兼容服务，并按说明把 Key 放进环境变量。你还需要明确允许 Book Agent 向指定的查询端点发送当前问题。

在线查询模型必须与书中现成向量的来源相容。不能因为一个服务“支持向量”或输出维度一样，就随意替换成另一个模型。

不确定是否兼容时，先用原文阅读模式，把书包中的 vector_db/manifest.json 交给技术人员检查。

### 3.5 下载结束后先核对什么

1. 版本是否一致：安装说明、程序、依赖与模型收据是否来自同一次交付。
2. 平台是否正确：Windows x64 包不是 macOS 应用，也不是 Linux 原生程序。
3. 压缩包是否完整下载：不要直接运行浏览器的临时下载文件。
4. 文件大小和 SHA-256 是否与发布方清单相符。
5. 安装入口是否来自受信任的发布方。
6. 书包来源是否可靠，是否有你合法使用这些书的权限。

SHA-256 相同能证明文件与预期一致。若文件和“预期哈希”都来自一个被替换的页面，单靠哈希不能证明发布者身份。安装 Agent 使用的“可信清单哈希”应从发布方可信网站或 catalog 取得并核对，普通用户不必手输。

### 3.6 检查哈希的 Windows 例子

下面只是演示如何检查一个文件；文件位置需要换成你的真实下载位置：

~~~powershell
Get-FileHash -Algorithm SHA256 -LiteralPath 'F:\BookAgent\Downloads\book-agent-windows-x64.zip'
~~~

输出中的 Hash 与正式清单里的 sha256 比较时，英文字母大小写不影响结果。这属于高级人工检查。普通用户可以让安装 Agent 从可信发布资料读取并比较；没有对应的可信预期值时，不应说“已经验证发布者”。

如果网站上的文档给出一组固定哈希，而 release-manifest.json 又属于另一个版本，先核对发布版本，不要让安装 Agent绕过校验继续执行。

## 四、可以直接复制的安装提示词

### 4.1 新手只要提供什么

把下面一句发给有本机文件与命令操作能力的 Agent，再告诉它：

- 工具包在哪个本机文件夹。
- 完整书包在哪里，可以一次给多本。
- 想用什么模式；不确定就选默认原文阅读。

它应识别系统与当前助手，从可信发布页面、catalog 或交付上下文核对文件，选择固定目录并配置工具。你不需要先学会 SHA-256、Python路径、Book ID 或 MCP 配置。

如果 Agent只能聊天而不能读本机文件或运行命令，它只能指导。必要的宿主 UI操作也可能要由你完成。

### 4.2 一句话安装提示词

~~~text
请把我提供的 Book Agent 工具包安装并接入当前助手，
导入我指定的完整成品书包；默认用原文阅读模式，
需要时让我只选原文、离线或在线，
由你识别系统、从可信发布页面或下载清单核对文件、
选择长期存放目录、配置 MCP 并复用共享依赖和权重，
多本书不要重复下载模型，保留原书与无关设置，
完成真实可执行的检查后用通俗语言告诉我结果和还需要我点击什么。
~~~

再补上实际位置，例如：

~~~text
工具包在 F:\BookAgent\Starter。
书包在 F:\BookAgent\Books\示例书A.7z 和 F:\BookAgent\Books\示例书B。
先用默认原文阅读。
~~~

可以直接使用单独的 [一句话安装提示词.md](一句话安装提示词.md)。安装 Agent 的具体职责见 [安装Agent操作指南.md](安装Agent操作指南.md)。

路径告诉本机Agent即可，不要求把私人书上传到网站。宿主如何处理会话与附件，依其实际设置。

### 4.3 Agent 应替你完成的职责

- 读取本次真实说明与 --help，不按记忆假造命令。
- 识别系统、固定安装位置与当前目标宿主。
- 从可信发布网站或 catalog 获取清单与预期指纹，核对实际文件。
- 默认 text 使用完整 Windows x64程序，不额外装模型或 Python。
- 检查完整包材料，缺失时说明，不自动OCR或重做文档向量。
- 独立保存运行数据，保留原书与无关设置。
- 使用批量setup与共享书库连接，多本兼容书共用依赖和模型。
- 阅读逐本报告，而不只看退出码。
- 能观察实际工具调用时做真实检查；不能观察就报告已到哪一级。
- 把剩余UI动作写成你能照着做的步骤。

校验值应由 Agent 从可信发布资料取得并使用，不让新手手抄一长串指纹。资料缺失或来源无法确定时，Agent仍应说明具体缺口，不能绕过校验假称已核验。

### 4.4 选择本地或在线时，追加一句即可

本地语义：

> 我选择本地语义，请先复用本机已有共享环境和兼容模型。【我不允许联网，缺少材料先告诉我 / 我明确允许下载本次固定模型】。

这两个选项只选一个。纯离线时需要已经准备好的完整ModelDir；安装Agent 会查找或向你说明缺少什么。安装.ps1在未提供ModelDir、又未在发布目录发现随包本地模型时会请求下载，因此它应按你的联网选择采用正确入口。显式提供的目录有问题会报告缺失。

在线语义：

> 我选择在线语义，明确允许当前问题发送到已经核对的兼容查询端点；请使用凭据环境变量，不把Key写进配置、提示词或输出，也不启用远程重排。

在线服务需要有效凭据，不能凭空替用户生成。Agent 应说明真实缺口，并用通俗语言告诉你需要在哪个服务或宿主中设置；不要求你先理解模型空间算法。

### 4.5 高级用户完整约束模板（可选）

这份模板适合有固定存储、项目范围和联网要求的用户。普通用户不必填完这些技术项；可留“自动识别/使用合理默认”，由 Agent 按实际环境安排。

~~~text
请按真实交付安装 Book Agent，并阅读“安装Agent操作指南.md”。

- 工具包/下载目录：{实际路径}
- 完整书包：{可以多行列出}
- 模式：{text默认 / offline / online}
- 宿主与安装范围：{自动识别当前助手；或指定宿主/项目}
- 固定程序目录：{自动安排；或指定}
- 独立共享数据目录：{自动安排；或指定}
- 共享Python环境：{仅需要时自动安排；或指定}
- 共享模型目录：{仅需要时检查已有目录；或指定}
- 可信发布页/catalog/清单：{从交付来源获取；或补充地址/位置/可信哈希}
- 联网权限：{默认不联网；或明确授权本次固定模型/准确查询端点}
- 在线凭据环境变量名：{仅online；不要填写Key本身}

请核对实际清单与文件，保留原包，不执行包内脚本，
不OCR、不生成文档向量、不启用远程重排。
先检查宿主安装计划，保留无关MCP/Skill/账号和项目设置；
多本兼容书共享一次依赖环境与一份模型。
用实际list、doctor、status和授权范围内的真实调用报告结果：
每本书名/ID、请求与实际模式、程序/数据/模型位置、
已完成验证层级、部分成功原因和剩余UI动作。
无法确认的模型前向、在线服务、宿主工具调用或主AI看图
分别写“未验证”，不要把dry-run当作实际安装。
~~~

### 4.6 为什么仍可能需要你操作一次界面

MCP配置文件写好后，宿主可能需要重新加载。WorkBuddy Skill ZIP可能需要UI导入；Cherry Studio需要添加服务并绑定目标Work Agent。宿主可能还有工具启用、账号登录或模型选择。

安装Agent 应说明“已经生成”“已经写入”“已经连接”分别到哪一步。看到真实工具调用与答案，才可以说那个宿主已经按书回答；图片理解另行观察。


## 五、准备本机文件夹

### 5.1 一种容易理解的放置方式

下面是一种示例，不要求使用 F 盘。没有 F 盘可以改成 D 盘或其他足够大的位置。网站交付根以随包 README.md 和实际解压位置为准；这里的 F:\BookAgent 只是用户可选目录，不绑定开发目录或发布方的存放位置。

~~~text
F:\BookAgent\
  Downloads\                     浏览器下载的原始交付文件
  Release\                       解压后用于安装的发布文件
  App\                           固定位置的默认程序及 _internal
  Books\                         你合法持有的完整书包
    示例书A.7z
    示例书B\
  Data\                          Book Agent 注册、缓存、配置
  QueryRuntime\                  可选：多本书共用的 Python 环境
  Models\
    BAAI-bge-m3\                  可选：多本兼容书共用的一份模型
~~~

程序、数据、书包和模型分开存放，换模式或添加书时容易找到对应文件。

### 5.2 新手怎样建立文件夹

1. 打开 Windows 文件资源管理器。
2. 进入你准备长期存放文件的磁盘。
3. 新建 BookAgent 文件夹。
4. 在其中建立 Downloads、Release、App、Books、Data。
5. 若选本地语义检索，再准备 QueryRuntime 和 Models。
6. 右键下载的 ZIP，选择“全部解压缩”，得到程序文件夹。
7. 不要只把 book-agent.exe 拖走；它旁边的 _internal 等内容也要完整保留。
8. 将书包放入 Books，记下各自的完整路径。

程序与 _internal 之间的相对位置由交付包决定。移动时移动完整程序目录，不要按照上面的示意手工拆散内部布局。

### 5.3 路径是什么，为什么需要完整路径

路径是电脑上某个文件或文件夹的具体地址，例如 F:\BookAgent\Books\示例书A.7z。

在文件资源管理器的地址栏里，可以复制当前文件夹的完整地址。对于文件可以使用“复制文件地址/复制为路径”。命令示例中将路径用单引号包围，通常能正确处理中文和空格。

TRAE CN 的 command 字段有特殊的空格限制，因此宿主适配器可能要求程序启动路径中没有空格。书包路径与参数中的中文、空格是另一回事。给 TRAE 安装时，可以优先把程序与查询环境放到 F:\BookAgent 这样的路径，再按实际说明确认。

### 5.4 运行文件夹应该长期保留

宿主 MCP 配置通常记录绝对程序路径与数据目录。安装好以后不要随意重命名或删除这些文件夹。移动后需要更新连接配置。

数据目录会有运行生成的缓存和注册信息，不能把它误当成“没有用的临时文件”全部清空。原始书包也应保留，尤其是你计划换电脑或重新导入时。

## 六、批量安装入口

### 6.1 推荐下载组合

| 你选择的模式 | 推荐文件 |
| --- | --- |
| 原文阅读 text | book-agent-starter-windows-x64.zip、完整书包、正式校验清单 |
| 本地语义 offline | 上述 starter，再加 book-agent-offline-addon-windows-cp313.zip、兼容 Python 3.13 x64、单独的 weights/BAAI-bge-m3 模型目录 |
| 在线语义 online | starter、完整书包、兼容查询服务、环境变量中的 Key、明确联网授权 |

starter 是便捷入口，包含默认 Windows 程序、Skill 和安装.ps1 等说明。offline-addon 是可选依赖补充包，不包含模型权重。模型只有一份独立目录供兼容书共用。

DOWNLOADS.json 供网站和安装 Agent 识别下载角色；真正的文件哈希与大小仍以最终 release-manifest.json 为准。starter 自带 starter-manifest.json，用于内部完整性检查；网站可信清单与外层 starter ZIP 的核对仍应在运行脚本之前完成。

### 6.2 最简单的 Windows 原文安装

1. 下载并核对 starter ZIP。
2. “全部解压缩”后得到 book-agent-start 文件夹。把这个完整文件夹放到长期位置；本手册示例把它整体改名为 Starter，放在 F:\BookAgent\Starter。不要拆散内部文件。
3. 在里面找到安装.ps1、starter-manifest.json 和完整 book-agent 子文件夹。
4. 准备各本完整书包路径。
5. 将[安装提示词](#四可以直接复制的安装提示词)交给 Agent，或按下面命令执行。
6. 看安装报告，再按宿主要求完成界面操作。

先预览：

~~~powershell
& 'F:\BookAgent\Starter\安装.ps1' -Mode text -HostName codex -Books @('F:\BookAgent\Books\示例书A.7z', 'F:\BookAgent\Books\示例书B') -DataDir 'F:\BookAgent\Data' -PlanOnly
~~~

正式执行：

~~~powershell
& 'F:\BookAgent\Starter\安装.ps1' -Mode text -HostName codex -Books @('F:\BookAgent\Books\示例书A.7z', 'F:\BookAgent\Books\示例书B') -DataDir 'F:\BookAgent\Data'
~~~

示例中的 Starter 是实际含安装.ps1 的内层根目录。若你保留原名，命令路径应改成真实的 book-agent-start 路径；不要把解压外层文件夹误当 ReleaseDir。

HostName 可换成 trae、workbuddy、cherry-studio。省略 HostName 就只执行导入与模式设置，不安装宿主连接。

PlanOnly 不导入书、不安装依赖、不下载模型、不写宿主；它只显示基本计划与安装材料检查结果，不能证明真实环境、模型和宿主已经可用。

如果系统阻止执行脚本，先把真实消息交给安装 Agent，按本机组织策略或改用已校验程序的 setup 命令解决。不要为照抄示例而改变全局执行策略。

如果脚本提示“安装目录路径过长”，让安装 Agent 自动选一个较短、长期保留的普通目录后重试；不需要你计算字符数或填写复杂参数。对实际过长的最终程序路径，脚本会在写入Data目录前拒绝，PlanOnly也会报告该限制。

未指定 DataDir 时脚本默认使用当前用户 LocalApplicationData 下的 BookAgent。给出固定 DataDir 更容易知道书库在哪里。使用 starter 时，其内程序在解压后的实际位置运行，安装完成后保留该目录。

### 6.3 一份本地模型、多本书的安装

假设：

- starter 在 F:\BookAgent\Starter。
- addon 解压得到 book-agent-offline-addon 文件夹。示例将这个完整内层目录放为 F:\BookAgent\Offline，里面有 wheelhouse 与 offline-wheelhouse。主 release-manifest.json 为避免归档哈希循环不在 addon 内；安装 Agent 从可信正式下载取得同版本最终主清单并放到这个实际根目录，供安装器读取。
- Python 3.13 x64 的真实程序路径已确认。
- 模型完整目录在 F:\BookAgent\Models\BAAI-bge-m3。

~~~powershell
& 'F:\BookAgent\Starter\安装.ps1' -Mode offline -HostName codex -Books @('F:\BookAgent\Books\示例书A.7z', 'F:\BookAgent\Books\示例书B') -DataDir 'F:\BookAgent\Data' -OfflineReleaseDir 'F:\BookAgent\Offline' -PythonPath '实际Python3.13的绝对路径' -ModelDir 'F:\BookAgent\Models\BAAI-bge-m3'
~~~

脚本把共享查询环境放在 Data\tools\query-runtime。这个入口不提供自定义 venv 参数；若你需要别的位置，让 Agent 使用 install-offline.py 的 --venv 手动路线，再调用该环境中的 setup。

不要把上面的“实际Python3.13的绝对路径”直接复制运行；它是明确占位。脚本可以尝试 py -3.13 或 python，但仍需核对真正选中的版本。

**纯离线使用必须明确提供完整 ModelDir。** offline 未提供 ModelDir，且未从发布目录找到随包模型收据时，脚本会传 --download-model 请求固定模型。显式提供的 ModelDir 不存在或不完整时会报告缺失，不会因此自动下载。没有模型且不允许联网，请先停在缺失材料说明，或改用 text；不要运行一个会尝试下载的 offline 命令。

可选依赖只在共享环境安装，现成文档向量仍不重新生成。不同书是否能启用 offline，按逐本模型空间检查决定。

### 6.4 直接使用程序的 setup

技术人员也可以不用便捷脚本，直接运行已校验程序：

~~~powershell
$ba = 'F:\BookAgent\Starter\book-agent\book-agent.exe'
& $ba --data-dir 'F:\BookAgent\Data' setup --mode text --host codex --dry-run --json 'F:\BookAgent\Books\示例书A.7z' 'F:\BookAgent\Books\示例书B'
& $ba --data-dir 'F:\BookAgent\Data' setup --mode text --host codex --json 'F:\BookAgent\Books\示例书A.7z' 'F:\BookAgent\Books\示例书B'
~~~

setup --dry-run 不导入包、下载模型、安装依赖或写宿主，也不实际验证模型/服务查询。

offline 必须使用已装好可选依赖的共享 Python 环境；setup 本身不会安装 Python 依赖：

~~~powershell
$ba = 'F:\BookAgent\Data\tools\query-runtime\Scripts\book-agent.exe'
& $ba --data-dir 'F:\BookAgent\Data' setup --mode offline --model-dir 'F:\BookAgent\Models\BAAI-bge-m3' --host codex --json 'F:\BookAgent\Books\示例书A.7z' 'F:\BookAgent\Books\示例书B'
~~~

直接 CLI 只有明确加 --download-model 才请求模型下载。此参数只适用于 offline。不加参数时，检查/采用已有模型，不会把所有缺文件都自动转成联网下载。

online 需要明确授权，且使用书包继承的兼容查询配置：

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' setup --mode online --allow-remote-query --query-auth-env BOOK_AGENT_QUERY_KEY --host codex --json 'F:\BookAgent\Books\示例书A.7z'
~~~

这里仅记录环境变量名，并不会证明变量已传入宿主或服务已经成功响应。需要另设准确端点时，请使用已有 configure 的明确端点选项，并检查兼容性。

### 6.5 已导入书，只连接或断开共享书库

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' install-library --host codex --dry-run --json
& $ba --data-dir 'F:\BookAgent\Data' install-library --host codex --json
~~~

该入口连接全部注册书的共享服务，后续通过 book_list 选择书。新增书使用相同数据目录，无需每本书建立一份同样的 MCP 服务。

卸载该共享连接：

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' uninstall-library --host codex --dry-run --json
& $ba --data-dir 'F:\BookAgent\Data' uninstall-library --host codex --json
~~~

这不删除书包、共享模型或运行数据。修改过的管理文件可能保留并报告。

setup 提供书包路径时处理这些包；不提供路径时会作用于当前整个注册书库，并返回 selection_scope=registered_library。空库返回 status=empty，不能报告已有可用书。只想连接已有书库、不改逐本模式时用 install-library；改变某本书用 configure。无参数 setup --mode text 会影响已有书的模式与查询联网授权，执行前应明确范围。

### 6.6 怎样读批量结果

| 字段 | 应怎样理解 |
| --- | --- |
| status=ready | 本次报告没有记录错误；仍需完成宿主 UI 与真实工具调用 |
| status=partial | 一部分任务未完成；其他成功导入的书保留 |
| status=empty | 当前没有可处理的注册书；不能宣称书库已可用 |
| selection_scope | provided_packages 是给出的包；registered_library 是当前整个注册书库 |
| books[].imported | 这本包已导入 |
| requested_mode | 你希望的模式 |
| active_mode | 这本书实际启用的模式 |
| mode_ready | 本次模式准备是否完成 |
| vector_warning / errors | 失败类别与发生阶段 |
| shared_model_dir | 本次实际使用的一份共享模型位置 |
| model_installations_in_this_setup | 本次共享模型检查/安装动作数量；不代表逐本复制 |
| dependency_install_performed=false | setup 命令没有安装依赖；脚本可能在调用 setup 前安装了共享环境 |
| model_forward_tested=false | 本次 setup 没有实际跑完整查询模型前向 |
| online_service_tested=false | 本次 setup 没有实际请求在线查询服务 |
| host_ui_verified=false | 本次设置没证明宿主 UI 和主 AI 使用成功 |

进程退出成功不能替代逐项阅读。只要 status=partial、mode_ready=false 或 errors 非空，报告就应写明哪些书、哪一步未完成。

一个包损坏不会要求把其他有效包删掉重来。语义模型缺失或不兼容时，已成功导入的书可保留 text 能力。所有给出的包都不能导入时，命令会报告 no_books_imported。

setup 先把这次选中的书置为文本模式、撤销查询远程授权，再尝试启用你选择的语义模式，并把重排设为 none。不要用 setup 覆盖你自己复杂的逐本重排设置而不先查看计划与配置。

### 6.7 查看本次安装和发布的实际验证

本节命令与参数按本次实际接口整理。批量setup、书库连接、脚本材料检查和主AI真正使用书库分别看报告与验收记录。你安装时的实际报告告诉你当前这台电脑完成到了哪一步；正式发布的验收记录说明负责人在指定环境中观察到了哪些行为。

详见 [acceptance.md](docs/acceptance.md) 和第十五节。没有在实际记录中观察到的模型前向、在线服务、宿主工具调用或主AI看图，保留“未验证”；不从帮助输出、dry-run或历史版本成绩推断。


## 七、手动安装与检查

本节给技术人员和愿意自己操作命令的用户使用。新手可以将这些步骤交给安装 Agent。

### 7.1 打开 PowerShell

在 Windows 开始菜单搜索“PowerShell”，打开它。你可以复制一条命令，粘贴后按回车。PowerShell 窗口只是运行本地程序的工具，不需要你学会编程。

下面的 F:\BookAgent 都是示例路径，必须按你真实文件位置替换。不要把占位的 BOOK_ID 当作真实书 ID 运行。

### 7.2 先指定实际程序

解压后的默认 Windows 程序路径可能多一层目录。找到真实 book-agent.exe 后设置：

~~~powershell
$ba = 'F:\BookAgent\App\book-agent.exe'
& $ba --help
~~~

PowerShell 中的 & 表示运行变量中指定的程序。成功显示帮助，说明程序能够启动；这还没有导入书，也没有连接宿主。

若原包内的路径是 App\book-agent\book-agent.exe，就要使用那个真实路径。不要为了符合示例而拆散 _internal。

### 7.3 导入一份完整书包

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' init 'F:\BookAgent\Books\示例书A.7z' --reranker none --json
~~~

也可以把最后的 7z 换成完整书包目录或受支持的 ZIP。当前不支持加密压缩包。

第一次导入会检查结构、声明文件、大小和哈希，并在独立位置保存运行状态。包内脚本只做静态检查，不会成为安装命令执行。原始输入保留为只读材料。

返回结果中的 book_id 就是后续 BOOK_ID 要替换的值。复制并保存它，不要按书名猜 ID。导入失败时先看错误原因，不要继续安装一个没有注册成功的 ID。

### 7.4 检查有哪些书

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' list --json
~~~

你应该能看到实际注册的书。文件名相同不等于书的内容相同；不同版次可能产生不同 ID。

接着检查某本书：

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' doctor BOOK_ID --json
& $ba --data-dir 'F:\BookAgent\Data' status BOOK_ID --json
~~~

doctor 用来诊断材料和运行条件。status 用来查看书的当前状态和查询路线。它们不会证明宿主的主 AI 已经成功调用该书。

### 7.5 明确使用原文阅读 / 文本检索

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' configure BOOK_ID --vector-search none --json
& $ba --data-dir 'F:\BookAgent\Data' search BOOK_ID '书中某个确实存在的关键词' --json
~~~

vector-search none 表示不请求语义向量。它仍能检索文本、展开证据、读取 Markdown、定位和读取原文、渲染页面或读取 EPUB 支持的图片。

搜索结果少时，可以换成原书术语、短语或章节名。文本检索方式不会因为没有查询模型就完全失去查书能力。

### 7.6 逐本连接一个宿主

以下是已有的逐本接口，适用于只连接一份书的场景。多本共享书库优先按本次正式发布的批量入口操作。

先预览：

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' install-host BOOK_ID --host codex --dry-run --json
~~~

确认结果中的目标路径正确后执行：

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' install-host BOOK_ID --host codex --json
~~~

--host 的已支持名称为 codex、trae、workbuddy、cherry-studio。把 codex 换成你实际使用的宿主名称，不要为不使用的宿主创建配置。

需要指定项目、其他 home 或明确公共配置路径时，由安装 Agent查看本次 --help 中的 --project-dir、--home、--config-path，避免写到错误账号或错误项目。

安装适配器会保存生成物、所有权和备份，并尽量保留无关配置。遇到非法配置、同名不同内容或并发修改时，应查看报告，不要用整份文件覆盖的方式“强行解决”。

### 7.7 安装后的自查表

| 检查项目 | 可以得出的结论 | 不能据此得出的结论 |
| --- | --- | --- |
| --help 正常输出 | 程序能启动 | 书已经导入 |
| list 中看到书 ID | 书已注册 | 语义模型可用 |
| doctor、status 返回真实结果 | 材料与运行条件有具体诊断 | 所有宿主都能调用 |
| search 返回证据 | 当前程序能够查到材料 | 宿主已经连接 |
| dry-run 生成计划 | 计划可审查 | 配置已经写入 |
| 配置中出现预期条目 | 连接配置已写入 | MCP握手成功 |
| 宿主实际调用 book_status / book_search | 宿主可以调用工具 | 主 AI 已经看懂图 |
| 实际答案引用查得的证据 | 这次主 AI 使用了书证据 | 每个问题都能正确回答 |
| 实际检查了图像内容并解释 | 这次宿主与模型可以看图 | 所有图片都能理解 |

## 八、日常提问与引用

### 8.1 先让助手选择正确的书

多本书时，可以先说：

~~~text
请先调用 book_list 列出已经导入的书。
我接下来只讨论《示例书 A》的这一版。
请告诉我选中的 Book ID，再开始查书。
~~~

列书和指定 ID 能减少同名书、不同版次和不同作者之间的混淆。如果你只记得文件名，也可以把文件名提供给助手，再由实际书库列表确认。

### 8.2 一个实用的提问格式

~~~text
范围：只用《示例书 A》，Book ID 为 {实际 ID}。
问题：{你想知道的具体问题}。
线索：{已知章节、原书术语、独特短语或页码；没有可不填}。
输出：请给结论、证据摘录和来源。
对于 PDF，请区分文件页序和书上印的页码；
对于 EPUB，请给章节与 href/anchor。
没有足够证据或原文未验证时，请说明限制。
~~~

问题可以自然表达。原文阅读模式下，增加原书术语或章节线索通常更有帮助。

### 8.3 解释概念

~~~text
只依据《示例书 A》解释“{术语}”。
先检索定义和相邻段落，再用普通语言解释。
请给出书中证据，并区分作者原意和你的解释。
~~~

### 8.4 查找一句话或一段原文

~~~text
请在《示例书 A》中找这句话：“{尽量独特的原句}”。
展开完整上下文，再回到原 PDF/EPUB 验证位置。
有多个可能位置时，先列出候选，不要任选一个当作确定位置。
~~~

PDF 默认文字定位有范围限制，通常最多扫描 40 个页面。若材料可能在后半本书，提供物理页序、已有定位或章节线索，能帮助缩小范围。没有找到不能直接推断“整本书没有这句话”。

### 8.5 看图、表、公式和排版

~~~text
请找到《示例书 A》里关于 {主题} 的图或表。
先定位原文，再通过页面渲染或 EPUB 图片工具把图像交给当前模型。
请说明你实际看到了什么，图中信息与正文怎样对应。
如果宿主没有接收图片或当前模型不能看图，请直接说明。
~~~

Book Agent 的图像工具会向 MCP 返回实际 PNG 图像数据，而不仅是本机文件路径。不过宿主是否接收图片、当前模型是否会理解图片，是后续环节，不能由“图片已生成”推断。

对扫描 PDF：没有可提取文字的页面会明确显示限制，当前没有自动 OCR。助手可以请求页面图并在宿主支持时分析，但不能说 Book Agent 已经自动提取了扫描页中的全部文本。

EPUB 中的图片必须是书内声明且由相应章节引用的受支持图片。SVG 或某些不支持的格式可能无法转换。外链图片不会自动下载。

### 8.6 要求正确引用

一个可靠引用应尽量带上：

- 书名与必要的版次。
- Book ID。
- 证据 ID 或记录 ID。
- 对应章节、标题或段落。
- 已有且已验证的原文位置；如果没有，明确未验证。
- 一小段能够支持结论的文字，避免无关长篇粘贴。

PDF 中有三种不同数字：

| 数字 | 实际含义 | 引用时怎样写 |
| --- | --- | --- |
| pdf_page_index | 从 0 开始的物理页面索引 | 工具参数内部使用，给用户时要解释 |
| pdf_page_number | 从 1 开始的文件页序 | “PDF 文件第 N 页” |
| printed_page_label | PDF 提供的页标签，可能为空 | 有真实标签时另列，不能自动当作印在图上的数字已核实 |

例如 --page-index 1 是 PDF 文件第 2 页，不是第 1 页。目录、封面、罗马数字前言都会使文件页序与正文印刷页码不同。

EPUB 通常引用章节、书内 href 与 anchor。不要要求助手编造一个所有阅读器都一致的 EPUB 页码。

### 8.7 证据不够时怎么继续

可以要求助手：

1. 用原书关键词重新检索。
2. 展开命中的上下文。
3. 阅读相关 Markdown 章节或指定行。
4. 用原文定位工具核对。
5. 提供页码提示后检索相应范围。
6. 对图表请求原文页面。
7. 仍没有证据时，说明“当前证据不足”，把一般知识与书中结论分开。

空结果意味着这次检索没有命中合适证据。它不证明书中完全没有相关内容，也不能让助手直接补写“作者一定这样认为”。

### 8.8 怎样要求阅读全文

想深入研读一章，可以让助手先读取章节目录，再按章节分段阅读、记录每段证据。一次 search 的少量命中不等于全文阅读。

整本书很长时，宿主上下文、工具返回字符数和图片大小都有上限。让助手分阶段做“列目录—选择章节—分段阅读—总结证据”更容易检查。

### 8.9 Book Skill 怎样参与

原始 Book Skill 保留书的阅读方法和主题资源。book_get_skill 可以让助手取得它。宿主适配器还会提供查书的通用说明与书籍包装 Skill。

安装 Skill 不等于工具已经连接。工具连接也不证明宿主一定自动触发 Skill。若助手直接泛泛回答，你可以明确说“请读取这本书的 Skill，并调用 Book Agent 查找证据”。

## 九、检索方式和原文阅读的选择

### 9.1 两个问题分开决定

第一件事是“用什么方法找到材料”：文本、离线向量或在线向量。

第二件事是“是否回到原文核对”：可以根据问题，要求读取原 PDF/EPUB 或查看图像。这项能力在三种检索模式中都保留。

当前没有“启用向量就自动关闭原文”的关系，也没有本手册提供的删除原文或禁用源工具开关。

### 9.2 原文阅读 / 文本检索模式

使用 --vector-search none。程序读取现成记录文字与 Markdown 进行文本匹配，给出证据，必要时再定位原文。

适合：

- 找原书中的精确术语、定义、标题、短语。
- 对照原文，逐段阅读。
- 不想下载额外权重。
- 语义模型不兼容或本机环境未准备好。

它不声称使用语义向量；结果中的 semantic_search_used 应与实际行为相符。完整包里的现成向量数据库仍是包格式的一部分，即使当前不使用语义路线，也不能因此随意删掉。

### 9.3 本地语义检索模式

本地查询模型把你当前的问题变成一个向量，与包里早已生成的文档向量比较。它不会在安装时重新算整本书的向量。

仅当书包的向量来源与本地查询模型兼容时启用。当前可选交付使用 BAAI/bge-m3 的固定文件，模型维度为 1024；“也是 1024 维”本身不足以证明其他向量兼容。

准备顺序：

1. 一次安装共享的 Python 和可选 CPU 依赖。
2. 一次取得并核对完整模型目录。
3. 检查每本书的向量空间信息。
4. 为兼容书绑定同一个模型路径并启用 offline。
5. 让宿主启动这个共享 Python 环境中的 Book Agent。
6. 查看实际查询结果是否用了语义路线，以及是否有回退原因。

已有手动安装例子：

~~~powershell
python install-offline.py --release-dir 'F:\BookAgent\Release' --venv 'F:\BookAgent\QueryRuntime'
$ba = 'F:\BookAgent\QueryRuntime\Scripts\book-agent.exe'
& $ba --data-dir 'F:\BookAgent\Data' install-query-model BOOK_ID --model-dir 'F:\BookAgent\Models\BAAI-bge-m3'
& $ba --data-dir 'F:\BookAgent\Data' configure BOOK_ID --vector-search offline --query-model-path 'F:\BookAgent\Models\BAAI-bge-m3'
~~~

前提是 python 确实为兼容的 CPython 3.13 Windows x64，且该 install-offline.py 与依赖目录是匹配交付。默认不会替你从网上安装任意 Python 包。

install-query-model 检查/登记本地模型，与 configure 启用模式是两个步骤；只完成模型安装并不自动启用向量搜索。

模型目录不存在而你又没有给出明确下载权限时，安装 Agent 应该报告缺失。显式 --download 是获取本次固定公开模型材料的联网路线，不是任意模型下载器。

### 9.4 本地模型的等待时间与内存

首次调用可能需要导入依赖、验证模型文件并准备模型适配器，可能明显慢于后续调用。不同硬盘、CPU、内存和安全软件都会影响时间；不要用一次暖机成绩保证自己的电脑也一样快。

当前 CPU 查询实现按需要读取词向量行并逐层读取权重，避免要求整个模型同时常驻内存。它仍有文件与计算开销，不是“零内存”或“所有低配电脑都已验证”。

缓存的是模型与分词器适配器等运行对象，当前不保存问题向量缓存。同一个问题再次搜索也会重新计算查询向量。

命令行运行一次查询，不会把另一进程中由宿主启动的 MCP 服务一起暖机。换进程、重启宿主之后，仍可能出现首次加载等待。

### 9.5 两层超时都要足够

本地查询时有两项独立限制：

- Book Agent MCP 服务处理工具调用的超时。
- 宿主等待工具返回的超时。

两者任意一项太短，都可能在模型尚未准备好时中断。已有宿主安装器在离线模式下为 Book Agent 设置 600 秒，Codex 的 tool_timeout_sec 也使用 600 秒。手动写配置或其他宿主的 UI 设置仍需独立核对。

600 秒是超时预算，不是每次问题需要等 600 秒，也不是能保证首次一定在 600 秒以内完成。遇到真实超时，先检查日志和模式状态。

### 9.6 在线语义检索模式

需要三个前提同时满足：

1. 书中向量与在线查询模型兼容。
2. 你有该服务的有效 Key，并通过受保护的环境变量提供。
3. 你明确允许访问准确的查询端点。

已有配置示例（以实际兼容服务为前提）：

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' configure BOOK_ID --vector-search online --query-auth-env SILICONFLOW_API_KEY --allow-remote-query --allow-query-endpoint 'https://api.siliconflow.cn/v1/embeddings'
~~~

这行命令只记录环境变量名称，不包含 Key。让宿主启动程序时也能读取该环境变量；“安装 Agent知道变量名”不代表宿主进程已经拥有变量。

Book Agent 的在线向量只发送当前问题。主 AI 接收到查得的证据后，宿主可能把这些证据或图片发给其自己的模型服务，这是宿主另一条数据路线。

远程重排是可选的另一功能，会发送问题和有限候选书文，需要单独授权。本手册的新手默认不启用它。

### 9.7 查询失败后的文本回退

已经选择 optional vector 路线时，普通查询遇到依赖缺失、模型不可用、认证或兼容问题，可能返回文本结果，并标注：

- retrieval_status=lexical_fallback。
- semantic_search_used=false。
- 实际失败类别。

这表示当前文本检索继续工作，同时语义路线失败。不能把“有结果”解释成“离线模型已经成功运行”。

严格查询会把相关失败直接报告出来，用于技术排查。日常用户先把状态和原因交给 Agent，不要只删除回退提示。

### 9.8 改回默认方式

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' configure BOOK_ID --vector-search none --json
~~~

改为 none 不需要重做整本书。原文读取仍可用。先确认没有其他书依赖共享模型，再决定是否清理可选模型文件。

## 十、多本书共用一套环境

### 10.1 你应该准备什么

- 一个长期固定的程序位置。
- 一个共享数据目录。
- 每本书各自的完整成品包。
- 需要本地语义时，一个共享 Python 环境。
- 每个确有需要的兼容模型空间对应一份模型；同一份 BGE-M3 不按书重复拷贝。
- 一份共享书库服务的宿主连接。

“共享”不等于把所有书混成一份证据。每条检索证据仍属于具体书 ID，阅读和引用都应保留书的身份。

### 10.2 一套环境怎样放十本书

所有书注册在同一个数据目录。宿主连接书库服务后，助手调用 book_list，看真实书目，再为后续工具调用指定书 ID。

模型文件在 Models\BAAI-bge-m3，运行环境在 QueryRuntime。不要在每本书下面都建立一份 2.29 GB 的同名模型，也不要因为使用两个宿主就安装两套同样依赖。

书库服务、数据目录和模型路径必须对应同一套安装。如果你导入到 Data-A，而宿主启动的配置指向 Data-B，助手不会自动看到 Data-A 的新书。

### 10.3 添加一本新书

1. 得到新书完整包，保留原文件。
2. 使用同一个安装入口与数据目录导入。
3. 记录返回的书名和 ID。
4. 查看状态；按兼容性选择 text、offline 或 online。
5. 在宿主中重新调用 book_list。
6. 服务若仍显示旧状态，按宿主需要刷新或重连，再确认列表。
7. 第一次查这本书时明确提供书名或 ID。

共享书库配置的目的是让新注册的书可被同一服务列出。是否需要宿主刷新、工具授权和当前服务重连，应按本次安装结果与宿主实际表现判断。

### 10.4 不同书的模式可以不同

例如，书 A 和书 B 的向量都与 BGE-M3 兼容，可以共用模型；书 C 的向量来源不清楚，先用 text；书 D 有明确兼容在线服务，可以用 online。

不要为了“一键全部 offline”而忽略模型空间冲突。程序拒绝不兼容的模型时，应该保持可用文本路线并报告原因。

### 10.5 怎样避免串书

在会话开头说清范围：

~~~text
接下来只讨论《示例书 A》，Book ID 是 {A 的 ID}。
请每次查书都使用该 ID，不要自动扩大到全部书。
~~~

更换书时重新声明。对于同名书，应同时指定作者、版次或 ID。

需要跨书比较时：

~~~text
请比较《示例书 A》（ID：{A}）与《示例书 B》（ID：{B}）
对“{主题}”的解释。
分别检索两本书，先列各自证据，再比较。
每条引用要带对应书名与 ID，不要把一本书的证据归给另一本。
~~~

没有要求比较时，助手不应为了凑答案默默引用另一本书。

### 10.6 书 ID 与重名、版次、迁移

书 ID 与内容身份有关。同一文件名可能是不同内容；同一内容换一个文件夹后可以重新绑定，但应该核对实际 ID。

原书或关键材料改变后，旧引用位置可能不再有效。不要拿旧 ID 的证据定位到新修订的原文。应重新导入、检查身份，并使用新的定位结果。

## 十一、各宿主的操作差异

这里提供操作方向。正式公共路径以适配器与当前宿主文档为准；界面名字可能随版本改变。写配置、成功调用工具、主 AI 自动触发 Skill、主 AI 看懂图片，分别观察。

### 11.1 Codex

自动安装目标通常是用户 .agents/skills 和 .codex/config.toml。Codex 当前官方 Skill 说明使用 .agents/skills；已有旧 .codex/skills 目录不会因此自动被覆盖。

MCP 使用 TOML 配置表，command 与 args 分开保存。需要时刷新或重启 Codex，再在新会话中让助手列书、读取 Skill、查证据。

本项目已有一次真实 Codex 调用与答案记录，使用的是隔离 Python MCP 进程。它证明那次调用完成了状态、Skill、搜索、原文定位、读取、渲染并引用证据；不代表所有 Codex 版本、冻结 EXE 路线或 Skill 自动触发都已实测。

官方说明：[Codex Skills](https://learn.chatgpt.com/docs/build-skills)、[Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)。相关页面于 2026-10-03 重新读取。

### 11.2 TRAE / TraeCode CN

CN 版本的公开 Skill 目录有用户 .trae-cn/skills 和项目 .trae/skills，项目 MCP 使用 .trae/mcp.json。安装 Agent 需要知道你要用户范围还是项目范围，并在项目中启用所需 MCP。

全局 MCP 可能需要进入设置中的 MCP 添加界面，根据生成的配置手动添加。程序路径中的空格与 command 字段有已记录的限制；遇到 host_command_spaces，应调整到真实且没有空格的程序位置，再生成配置。

不要把 CN 版本的默认路径套用到所有 TRAE 发行版。其他版本需要明确选择公共配置位置或按其界面操作。

官方说明：[TRAE Skills](https://docs.trae.cn/ide_skills)、[TRAE MCP](https://docs.trae.cn/ide_add-mcp-servers)。Skill 页面于 2026-10-03 重新读取；MCP 链接沿用此前资料，本轮未据此完成该应用 UI 验收。

### 11.3 WorkBuddy

适配器使用公开的用户/项目 .workbuddy/mcp.json 配置，并生成需要导入的 Skill ZIP。

自动生成 ZIP 不等于已经安装 Skill。按生成的 manual-instructions.md 进入宿主的 Skill 导入界面，选择实际 ZIP，确认它出现在宿主中。然后在目标会话中启用对应工具并查书。

官方说明：[WorkBuddy Skill](https://open.workbuddy.cn/docs/skill)、[WorkBuddy MCP](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/MCP-Guide)。Skill 页面于 2026-10-03 重新读取；MCP 链接沿用此前资料，本轮未完成 WorkBuddy 的真实 UI、工具调用或看图验收。

### 11.4 Cherry Studio

适配器生成本地 stdio MCP 配置与操作说明，供你或安装 Agent审查和 UI 导入。它不会修改 Cherry Studio 的私有数据库。

通常要进入 Settings > MCP 添加并启动服务，再在目标 Work Agent 的编辑界面绑定该服务。仅添加服务、没有绑定到当前 Agent，当前会话可能仍不能查书。

可通过 book_get_skill 读取原始 Book Skill。当前不承诺 Cherry Studio 自动发现所有包装 Skill，其具体 stdio 解析和当前模型的图片行为还要实际确认。

官方说明：[Cherry Studio tools、Skills、MCP](https://cherryai.com/docs/en/advanced-basic/agent-workspace/tools-knowledge-skills-mcp/)，于 2026-10-03 读取。公共界面说明不等于应用已实测。

### 11.5 无论使用哪个宿主，都问同一组问题

- 当前会话是否启用了这份书库工具？
- 当前服务是否指向正确程序和数据目录？
- book_list 是否能看到我的书？
- book_search 是否返回对应书的证据？
- 源位置是否已验证，还是只是候选？
- 图像是实际传入了当前模型，还是仅有路径？
- 主 AI 是否按证据回答，还是绕过工具泛泛回答？

不要用“支持 MCP”替代这些实际观察。

## 十二、迁移、备份与卸载

### 12.1 换电脑前保存哪些东西

建议保存：

- 原始完整书包。
- 正式程序发布文件与可信校验值。
- 数据目录中的注册、配置与需要保留的运行状态。
- 共享模型目录及其收据（如果使用）。
- 实际宿主安装报告、所有权清单和生成的操作说明。
- 一份记录：书名、Book ID、模式、程序路径、数据路径、模型路径。

Key 通过你自己的安全方式重新配置。不要把 Key 和密码合并进通用迁移压缩包或网站发布文件。

### 12.2 迁移的一般步骤

1. 在新电脑确认系统和运行平台。
2. 复制正式程序完整目录、原始书包及需要的模型。
3. 用新电脑的路径导入或重新绑定书包，核对内容身份与 ID。
4. 确认数据目录与模型路径；旧电脑的绝对路径可能不能继续使用。
5. 查看每本书状态，必要时重新 configure。
6. 重新安装新电脑宿主连接。
7. 在实际宿主列书、查证据、核对原文。
8. 确认新电脑可用后，再处理旧电脑的连接或文件。

不要直接把旧宿主配置整份覆盖到新电脑。它可能包含与 Book Agent 无关的工具和路径。

### 12.3 程序移动了，书却还在

这是程序路径问题，不一定是书损坏。找到新位置的实际程序，用同一个数据目录检查 list，然后重新生成/更新由 Book Agent管理的宿主连接。

模型移动时，更新每本使用该模型的查询路径。目录名称改变不会自动通知宿主。

### 12.4 安全卸载分为三件事

| 你要做什么 | 影响 |
| --- | --- |
| 断开宿主连接 | 宿主不再调用这份服务；不等于删除原书 |
| 停用某本书的语义模式 | 该书改用 text；不等于卸载共享模型 |
| 删除程序、数据或模型 | 属于文件清理；必须确认其他书/宿主不再使用 |

逐本旧接口的预览和卸载：

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' uninstall-host BOOK_ID --host codex --dry-run --json
& $ba --data-dir 'F:\BookAgent\Data' uninstall-host BOOK_ID --host codex --json
~~~

共享书库连接的正式卸载入口按本次发布的第六节执行。不要把逐本卸载和共享服务卸载混为一项。

### 12.5 为什么卸载有时留下文件

程序只删除由它拥有、且内容没有被修改的输出或配置条目。你修改过的 Skill、其他软件的同名文件或已有配置会保留并报告。备份也会保留。

这有助于保留你后来的更改。不要为了“卸载干净”直接恢复整份旧配置，旧配置可能覆盖你之后添加的其他服务。

### 12.6 删除一本书或清理共享模型

当前不要凭空运行 remove-book 之类未在 --help 出现的命令。需要从运行注册信息移除书时，请让 Agent 读取当前版本的正式支持方式。

清理共享模型之前，列出仍使用它的所有书和宿主；有任何书还需要这个模型，就保留它。删除模型不会删除书，但这些书的 offline 查询会失败或回退。

原始书包属于你的书资料。卸载程序不要求删除原书。

## 十三、问题排查

### 13.1 先收集三个基本事实

出现问题先记下：

1. 刚才执行的是哪一步：下载、解压、导入、配置、宿主连接、查询还是看图。
2. 真实错误类别和关键消息。
3. 程序、数据目录、书 ID、模式和宿主名称。

不要把含 Key 的完整日志公开发出去。常规错误输出会尽量隐藏可识别凭据，但你仍应检查将要分享的材料。

### 13.2 常见错误对照

| 现象或类别 | 普通话解释 | 下一步 |
| --- | --- | --- |
| required_file_missing / package_root_missing / declared_file_missing | 不是完整书包，或声明的材料缺失 | 找真正的包根目录，联系制作者补完整材料 |
| multiple_packages | 给了一个里面包含多个候选书包的位置 | 逐一明确包根目录；使用本次批量入口列出实际包路径 |
| invalid_manifest / unknown_archive_schema | 清单损坏或数据库/包版本不支持 | 向制作者取得兼容成品；不要编辑清单掩盖错误 |
| checksum_mismatch / file_size_mismatch | 实际文件与声明不一致 | 重新核对下载与版本，必要时重新下载 |
| source_version_mismatch | 证据指向的原书与当前原书不一致 | 使用匹配原书或重新导入对应版次，旧定位不要当作有效 |
| unsafe_path / unsafe_link | 包内路径或链接不适合安全导入 | 使用正常成品包；不要绕过路径检查 |
| 压缩包加密或解压限额触发 | 当前压缩方式不支持，或体量超出默认限额 | 让制作者提供受支持的完整目录/包；不要盲目提高限额 |
| import_busy | 另一个进程正在导入同一材料 | 等它完成，再检查状态；避免同时重复导入 |
| managed_import_changed | 已管理的材料被改动 | 核对是否误改了运行输入；从可信原包重新导入 |
| query_dependency_missing | offline 所需 Python 依赖不齐 | 使用匹配共享环境；先改回 text 也能查文本 |
| model_space_conflict / metadata_conflict | 查询模型与书向量来源不相容或信息冲突 | 不要只看维度；检查模型、修订和编码设置，暂用 text |
| 找不到模型文件 | --model-dir 指错层级或模型没下完整 | 指向含配置、分词器和权重的实际目录，并核对收据 |
| missing auth / HTTP 401 | 在线服务凭据缺失或无效 | 在宿主启动环境设置有效 Key，核对服务与端点 |
| HTTP 429 | 服务限流或额度条件不满足 | 查看你自己的服务账号状态，稍后重试，必要时 text |
| lexical_fallback | 原选语义路线失败，文本检索接续工作 | 看失败原因；有命中不代表语义模型可用 |
| host_config_invalid | 现有宿主配置不能解析 | 备份后按宿主格式修复，不覆盖无关设置 |
| host_mcp_conflict / host_skill_conflict | 同名条目属于别处或内容不同 | 检查所有权、使用可区分名称，保留已有内容 |
| host_command_spaces | 当前宿主 command 路径格式不接受空格 | 使用真实无空格的程序路径，再生成连接 |
| host_concurrent_change | 写入前后配置被其他进程改变 | 重新读取配置，再生成计划和应用 |
| 安装目录路径过长（Windows PowerShell 5） | 最终程序路径超出当前入口的可用范围；PlanOnly也可能直接拒绝 | 让安装 Agent 自行选择较短长期位置，再用实际书包重试；保留现有输入和用户内容 |
| book_list 看不到书 | 可能连了另一个数据目录、服务未刷新或未注册成功 | 核对宿主参数与 list 输出，再刷新连接 |
| 原文定位为空或有多个候选 | 没有唯一可靠位置 | 提供独特原句、章节或页码提示，保留未验证状态 |
| no native text / 扫描页无文本 | PDF 页面没有可提取的原生文字 | 请求渲染页面；当前不自动 OCR |
| 有图片路径但助手没看图 | 宿主或当前模型未接收/理解实际图像 | 检查 MCP 图像内容与模型能力，不能仅凭路径算成功 |
| 安装成功但助手不查书 | 工具/Skill 未启用，或主 AI 没调用 | 明确要求 book_list、book_get_skill、book_search，并观察调用 |

### 13.3 为什么程序不让我导入一个“大包”

默认解压限制包括最多 10,000 个条目、总计 2 GiB、单文件 1 GiB、压缩比 200:1。限制避免异常材料耗尽资源。

如果你的正常完整书包超过限额，交给制作者或技术人员检查实际结构与受支持的目录导入方式。不要让 Agent看到错误就关闭校验或提高所有限制。

### 13.4 没有结果，先做什么

- 确认书 ID 与版本正确。
- 确认问题是书中有线索的主题。
- 换用书内原词、章节标题或一句独特原句。
- 展开已有命中，查看上下文。
- 如果使用语义路线，查看是否回退。
- 原文搜索需要后半本书时，提供页码提示。
- 对只有图的材料，请求页面图，并确认宿主看图能力。

这些步骤仍不能找出证据时，让助手说清它已经查过哪些范围，避免凭空得出全书结论。

### 13.5 给技术人员的问题报告模板

~~~text
Book Agent 问题报告
- 发布版本：
- 操作系统与架构：
- 宿主名称与实际版本（如果能确认）：
- 本次步骤：
- 实际命令（去掉 Key、密码与个人信息）：
- 程序路径：
- 数据目录：
- 书名和 Book ID：
- 当前 text/offline/online 模式：
- 实际错误类别：
- list / doctor / status 中相关字段：
- retrieval_status / semantic_search_used：
- 原文定位是否 verified：
- 我观察到的现象：
- 我已经尝试的操作：
~~~

不要附上未经授权的整本私人书。可以先分享错误类别、脱敏配置、相关字段和你有权分享的最小示例。

## 十四、隐私与边界

### 14.1 哪些数据留在本机，哪些可能联网

| 操作 | Book Agent 这一环节的数据路线 |
| --- | --- |
| 默认 text 检索与源工具 | 本地读取书、建立运行索引/缓存，不调用远程查询向量服务 |
| offline 查询向量 | 本机读取共享模型并计算问题向量 |
| 显式模型下载 | 访问固定公开模型下载来源，下载模型文件 |
| online 查询向量 | 向已授权端点发送当前问题 |
| 可选远程重排 | 向另行授权的服务发送问题与有限候选书文 |
| 主 AI 阅读工具证据或图片 | 由你使用的宿主与主 AI 服务决定，可能传到它们的模型服务 |

“Book Agent本地运行”不自动改变宿主的主 AI 数据策略。敏感书籍和问题应结合你的宿主、模型与账号设置决定如何使用。

### 14.2 原书如何保存

程序不重写原书、Markdown、原始 Skill 或现成数据库。运行缓存、索引、补充定位映射和宿主部署输出保存在独立数据目录。

书包文本、Skill 或 README 内出现的“请执行命令”“请上传文件”只是书内内容，不自动拥有指挥安装 Agent 的权限。安装由你的指令和正式程序接口决定。

### 14.3 不要把什么交给网站发布者

- 私人书包和私人原书，除非你确实授权它们分发。
- API Key、登录 Cookie、密码和账号配置。
- 用户的宿主完整配置。
- 数据目录中的私人注册信息和运行记录。
- 可能包含书文、问题、个人路径的真实验收日志。

公共下载应提供程序、说明、合法可分发的依赖与可选模型。你自己的书库继续由你管理。

### 14.4 许可证怎样看

项目代码使用 MIT；可选 BGE-M3 上游模型卡标注 MIT。原书的授权由原书权利人决定，软件许可证不会给予你重新公开分发书籍的权利。[BGE-M3 官方模型页](https://huggingface.co/BAAI/bge-m3)

程序的第三方依赖还有各自许可证。特别是 PyMuPDF/MuPDF 提供 AGPL 或商业许可；项目自己的 MIT 说明不能替换该依赖的许可。[PyMuPDF 官方许可说明](https://pymupdf.readthedocs.io/en/latest/about.html#license-and-copyright)

随包 dependency-licenses.json、offline-dependency-licenses.json 和 third-party-licenses/ 用于查看具体交付。发布材料已采用较短许可路径，原文与来源保持；用户照常使用安装入口即可，路径选择由安装 Agent处理。准备对外或商业分发时，发布负责人应按实际包含的组件处理其许可要求。

## 十五、验证范围

### 15.1 验证针对具体交付和具体环境

详细结果见 [acceptance.md](docs/acceptance.md)。前一份 0.1.0 交付的证据覆盖了默认检索、源工具、Windows 完整程序路径、真实本地查询模型和一次真实 Codex 使用；新增批量入口、安装脚本和书库连接只采用本次实际记录中对应的验证项目，不沿用历史测试推断。

本轮新构建Windows EXE已完成44/44烟测。首轮全量检查为362 passed、2 skipped、1 failed（文案选项并列触发路径扫描误报）；相关并列选项文案修正后，portability/release曾专项52 passed。许可短布局增加7个用例后，最新专项59 passed、204.08秒；这些分次检查不与旧52或首轮362累加。这是不同运行的结果，不能写成“修后一轮全量全部通过”。Windows PowerShell 5的完整发布根目录（main v3）路线10项已实际通过。starter前7个检查阶段已通过，覆盖导入、动态集合隔离、重复/reset、partial与损坏程序拒绝。许可短布局更新后，starter在原失败深度的恢复尾段定点复核通过，约221.474秒，覆盖真实PS5 PlanOnly、损坏拒绝、从完整可信ZIP重解压，以及原有两书恢复text ready且书ID不变。main 10项与starter前7阶段继续引用v3冻结记录；267个native文件的完整集合及SHA与v3冻结ZIP一致，安装器与EXE未变。原恢复目录长度93字符保持，实测最大文件路径211、父目录203字符，未使用扩展路径前缀。这些是分阶段证据，不是新的一次完整双路线全部通过；尾段耗时只属于该恢复验收范围。main覆盖PlanOnly、错误可信哈希拒绝、两书7z与EPUB目录导入、实时书库列出新书与ID隔离、重复身份/缓存复用、无Books整库text撤销查询联网授权，以及坏包在前时保留两份有效书的partial结果。损坏程序与用户notes、未知空目录同时存在时保留目录树；移除验收自造项后，程序可修复为正式哈希，临时stage/rollback无残留。主路线实装与宿主主AI实际使用仍分别报告。

本轮独立离线环境已实际安装67个运行包，退出码0，首次约858.5秒；第二次返回reused，复用检查约16.4秒，并通过pip check与CPU查询依赖导入。两本兼容书共用一次模型原地检查/采用，约162.3秒，报告model_installations_in_this_setup=1、reused=true、downloaded=false；一份不兼容2D向量包保留text。本轮离线安装验收最终通过，原书包与合成输入哈希未变。这些证明环境安装、复用和模式绑定，安装、复用检查与原地模型采用耗时都不是查询延迟或forward耗时。本轮没有执行完整模型forward；历史真实完整前向证据仍按其原记录引用。

这里不把所有成绩合成“所有用户百分之百安装成功”。你自己的宿主版本、权限、主 AI、书包质量、网络和硬件仍需按真实结果检查。

### 15.2 已有证据的实际含义

| 已有观察 | 可以说明什么 | 不能扩展成什么 |
| --- | --- | --- |
| 前一交付完整测试 276 passed、2 skipped | 那份代码的自动化检查结果 | 所有平台和宿主已实测 |
| 本轮首轮全量362 passed、2 skipped、1 failed（文案误报） | 首轮真实通过、跳过及误报情况 | 单轮全量全部通过 |
| 许可短布局新增7用例后的最新专项59 passed，204.08秒 | 本次专项通过，不累计旧52或首轮362 | 修后全量或完整一次双路线全部通过 |
| 220项许可短布局保持原字节/来源，最长相对路径73字符 | 发布布局与来源保持；原失败深度恢复尾段另有定点通过记录 | 任意用户目录深度都可用，或完整一次双入口实装已通过 |
| Windows PowerShell 5 main v3入口10项、starter前7阶段及原深度恢复尾段分别通过 | 冻结记录与221.474秒定点复核的分阶段观察；两书恢复text ready且ID不变 | 新的一次完整双路线或主AI实际使用均已通过 |
| 源安装器深路径专项通过，约185.089秒；实际过长final及PlanOnly拒绝时Data未写入 | 该安装路径与拒绝行为的观察，Agent应自行选短长期目录 | 任意深度路径通用，或该耗时是查询速度 |
| 本轮67包实际安装成功，第二次环境reused，pip check和CPU依赖导入通过 | 当前独立共享环境能够安装和复用；首次约858.5秒只计安装范围 | 本轮完整模型前向或查询延迟已测 |
| 本轮两书共享模型原地检查/采用1次，约162.3秒、未下载；不兼容2D包保留text | 多书复用与兼容失败保留文本的实际设置行为，原书包及合成输入哈希未变 | 任意模型空间通用，或本轮完整模型前向已通过 |
| 本轮新 Windows EXE 本地烟测44/44通过 | 本轮完整EXE在该Windows环境的已列项目可用 | 任意系统、单独拷出EXE，或全部新增安装入口都已验证 |
| 真实 BGE-M3 离线查询 | 阻断网络的本机实际生成查询向量、命中材料并核对源页 | 每台电脑相同速度或任意向量模型兼容 |
| CPU 分层查询的小模型数值对照 | 被测输入与参考算法的数值一致性范围 | 所有硬件或所有长文本都已覆盖 |
| 一次真实 Codex + 隔离 Python MCP | 该次工具调用与按证据回答完成 | 冻结 EXE 的宿主调用、Skill 自动触发和看图都已完成 |
| MCP 图片工具真实返回 PNG | 图像数据确实进入协议返回 | 主 AI 已理解图表 |
| TRAE/WorkBuddy/Cherry 配置适配 | 已有公开接口适配和生成物 | 三个应用的真实 UI 与模型交互已验收 |
| 合成检索评估 | 被测固定样例的检索与模拟重排表现 | 真实书全集、实际云重排或完整宿主延迟 |

如果网站展示性能，应注明环境、冷启动/暖启动、是否真实模型、是否包含宿主时间。不要用毫秒级合成搜索成绩替代真实模型首次加载体验。

### 15.3 操作系统范围

- 默认 Windows x64 完整预编译程序是当前直接交付路线。
- Python 源码要求 Python 3.11+，但本次离线 wheel 配套具体为 CPython 3.13 Windows x64。
- Linux/macOS 可以走源代码路线，但当前不能据此写成原生安装包和运行已实测。
- 其他架构、宿主版本和环境应明确标出实际观察，不沿用 Windows 成绩。

## 十六、给技术人员的参考

### 16.1 书包最少要检查哪些材料

完整包应包含：

~~~text
原书 PDF 或 EPUB
完整 Markdown
原始 Book Skill 与其支持资源
archive_manifest.json
vector_db/
  vectors.sqlite3
  manifest.json
  README.md
  search.py
~~~

这里没有必须存在 chunks/ 文件夹的要求。应按真实包格式和清单验证，不凭旧转换流程的记忆增添要求。

包内的 search.py 等脚本存在不代表运行时会执行它们。书包被检查和读取，不被当作安装脚本启动。

### 16.2 已有 MCP 工具

| 工具 | 用途 |
| --- | --- |
| book_list | 列出服务可见的书 |
| book_status | 当前书与查询状态 |
| book_get_skill | 读取原始书籍 Skill |
| book_search | 检索证据 |
| book_read_entry | 展开具体证据条目 |
| book_read_markdown | 按行或标题读取 Markdown |
| book_locate_source | 定位对应原 PDF/EPUB |
| book_read_source | 按返回的定位读取原文 |
| book_render_page | 将 PDF 页面渲染成图像 |
| book_read_epub_image | 读取相应章节引用的受支持 EPUB 图片 |

书库模式仍需为书相关工具选择具体 book_id。不要让无明确范围的助手把不同书的证据混用。

### 16.3 源工具命令示例

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' source BOOK_ID locate --record-id '实际记录 ID' --json
& $ba --data-dir 'F:\BookAgent\Data' source BOOK_ID locate --text '一段足够独特的原句' --json
& $ba --data-dir 'F:\BookAgent\Data' source BOOK_ID render --page-index 1 --dpi 120 --json
~~~

读取原文时使用定位结果返回的实际 JSON locator，再按 --help 指定 read 的 --locator 参数。不要手工伪造 verified 字段。

已有单书 MCP 命令：

~~~powershell
& $ba --data-dir 'F:\BookAgent\Data' mcp BOOK_ID --timeout 600
~~~

MCP 省略 BOOK_ID 时可暴露已注册书库。宿主连接需要使用本次发布支持的书库安装接口，不能把一个“手动终端中启动了服务”说成“宿主已经连接”。

### 16.4 进一步阅读

- [完整包格式](docs/package-format.md)
- [部署与模式](docs/deployment.md)
- [宿主适配](docs/hosts.md)
- [检索与证据](docs/retrieval.md)
- [原文定位](docs/source-resolution.md)
- [图像回退](docs/visual-fallback.md)
- [隐私、完整性与许可](docs/security.md)
- [跨电脑与平台](docs/portability.md)
- [故障排查](docs/troubleshooting.md)
- [构建与依赖](docs/build.md)
- [实际验收记录](docs/acceptance.md)

正式 release、starter 与 offline-addon 内提供 docs/ 技术参考目录；发布包中的相关链接会指向该目录。源码项目内的本手册位于 docs，与技术文档同级。

当本手册的示例与所下载程序 --help 不一致时，先确认版本。使用那个实际版本支持的接口，并要求发布方更新对应说明。