README-交付说明.md

# Book Agent 交付目录

本目录可复制到其他机器、其他账号。没有私人 API Key、账号池、生产配置或测试书籍全文。接收端自行提供有权使用的书籍知识包，并在本机生成宿主配置。

## 首次使用与网站发布

普通 Windows 用户首选 `book-agent-starter-windows-x64.zip`，使用其中的 `安装.ps1`。默认 `text` 原文模式无需 Python、账号、Key 或模型权重；向量功能为可选 `offline` / `online`。所有书共享一个书库 MCP 连接。离线运行组件在 `book-agent-offline-addon-windows-cp313.zip`，权重独立位于 `weights/BAAI-bge-m3/`；不要逐书重复下载。

- [用户完整使用手册](用户完整使用手册.md)：模式选择、安装、批量导入、问答、故障处理与迁移。
- [一句话安装提示词](一句话安装提示词.md)：交给有本地工具能力的 Agent。
- [安装 Agent 操作指南](安装Agent操作指南.md)：安装细节由 Agent 自动处理。
- [网站发布交接说明](网站发布交接说明.md)：下载项、哈希、许可、展示文案和发布检查。
- `DOWNLOADS.json`：网站下载项目及相对路径，无虚构域名。

完整目录就是网站发布交付根目录。本机没有上传或发布网站，也不包含用户书籍正文、账号或 Key。请使用最终 `release-manifest.json` 和 `SHA256SUMS.txt` 核验整组材料。

## 更新前的基线验收（2026-10-03；新入口结果见用户手册）

最终 Windows EXE 独立 smoke **44 项全部通过**，run `0a3d5ab2`，EXE SHA-256 为 `880f5ae8bd6e8c169887ae901d81cf9b7768beeae60d175c8a64ef74eb2b00e6`；中文/空格路径完整副本、CLI、导入、检索回退、原文及 MCP SDK 图像交付通过。旧版 35/35 成功、中间 4 通过/7 失败与上一轮 44/44 成功对应不同 EXE 哈希，作为历史结果保留。层流式编码器的 14 项真实小模型测试已通过（131.04 秒）；完整 BGE-M3 CPU 禁网查询也已通过，生成 1024 维 CLS/L2 向量，原包与 29 个输入文件不变、正文嵌入 0 次。

本机两轮真实权重验收的首次编码（含依赖加载及编码前权重检查）分别为 33.609/155.887 秒，冷启动耗时不稳定；整轮含权重登记/哈希校验分别为 88.695/256.183 秒。调用计数复验在模型/依赖预热后，同问题搜索 0.973 秒、新问题搜索 0.869 秒，各执行一次真实 forward；每次搜索仍重新编码问题，缓存的是 tokenizer/流式模型适配器。耗时是本机样本，不代表其他问题或其他机器的性能。最新发行完整回归为 276 passed、2 skipped（161.38 秒）。

Python 原包读取、在线查询和 MCP SDK 图像交付已有独立验证；原生 Codex CLI + 隔离 Python MCP 问答也通过（67.592 秒、6 个完成工具调用、全局配置未改），正确报告证据、核实物理页码、fallback 标签和实际图片交付。Skill 自动触发、其他宿主真实 UI/模型问答与真实视觉理解未单独验证。以下操作说明描述实现路线，完整最新结果见源码 `docs/acceptance.md` 和 `docs/windows-binary-validation.md`。

## 三种使用情况

| 向量模式 | 交付组件 | 凭据/网络 |
| --- | --- | --- |
| 关闭或不可用 `none`（默认） | Windows 程序，或 Python 应用 wheel + 基础依赖；部署 Skill | 不需要 |
| 本地离线 `offline` | 上述应用 + `offline-wheelhouse` + `weights/BAAI-bge-m3` | 查询不需要账号、Key 或网络 |
| 可选在线 `online` | 轻量程序 + 自行配置的兼容原编码空间的服务 | 需接收端自己的授权及账号 |

所有模式都保留全文检索、书籍 Skill、PDF/EPUB 回溯。离线或在线向量失败时，普通查询明确降级全文检索；严格查询报结构化错误。不会重新切分、生成正文向量或蒸馏书籍。

## 文件

- `book-agent-windows-x64.zip`：轻量 Windows x64 程序，解压后完整保留 `_internal`。
- `book-assistant-skill-0.1.0.zip`：可交给其他 Agent 的部署 Skill。
- `book-agent-source-0.1.0.zip`、wheel、sdist：源码及 Python 安装入口。
- `wheelhouse/`：基础运行依赖，Windows x64 CPython 3.13。
- `offline-wheelhouse/`：可选 CPU 查询依赖；与基础依赖相同的 wheel 只存一份。
- `weights/BAAI-bge-m3/`：独立权重包，约 2.29 GB，含模型、tokenizer、SHA 契约及许可来源。目录可直接加载，避免另存重复压缩包；多本书共用。
- `install-offline.py`：校验并从本地批准的 wheel 安装完整离线查询环境。
- `release-manifest.json`、`SHA256SUMS.txt`：交付内容清单、大小及哈希。
- `third-party-licenses/`、依赖许可 JSON：运行依赖与可选离线依赖的许可记录。

先通过可信渠道核对 manifest 的 SHA，再使用安装器。程序本身不把自带哈希当作发布者身份签名。

## 离线安装（Windows x64 Python 3.13）

从本目录执行：

```powershell
python install-offline.py --release-dir . --venv '.\query-runtime'
$ba = '.\query-runtime\Scripts\book-agent.exe'
& $ba --data-dir '.\runtime-data' init '<书籍目录或7z文件>' --json
& $ba --data-dir '.\runtime-data' install-query-model BOOK_ID --model-dir '.\weights\BAAI-bge-m3'
& $ba --data-dir '.\runtime-data' configure BOOK_ID --vector-search offline --query-model-path '.\weights\BAAI-bge-m3'
& $ba --data-dir '.\runtime-data' doctor BOOK_ID --json
& $ba --data-dir '.\runtime-data' search BOOK_ID '<问题>' --strict --json
& $ba --data-dir '.\runtime-data' install-host BOOK_ID --host codex --dry-run
& $ba --data-dir '.\runtime-data' mcp BOOK_ID --timeout 600
```

将 BOOK_ID 替换为 init 返回的 ID。迁移路径后重新登记输入包和权重路径，身份由内容校验决定。Linux/macOS 提供源码安装路线，当前交付的 Windows EXE 和依赖 wheels 不适用于它们。

Codex 的对应 MCP 配置需使用这个 `query-runtime` 中的 Python/Book Agent 入口，保持同一 `--data-dir`，在 `args` 加入 `"--timeout", "600"`，并设置 `tool_timeout_sec = 600`。服务端 `--timeout` 与宿主 `tool_timeout_sec` 是独立期限，需要同时设置。一次 CLI 搜索不会预热另一个 MCP 进程；可用配置示例见源码 `docs/query-runtime.md`。

离线编码器采用 CPU float32 层流式推理：仅载入当前问题所需的嵌入行和一层参数，计算后释放该层，再载入下一层。磁盘权重仍约 2.29 GB；上述真实权重结果未记录进程峰值内存，不据此保证跨机器资源上限。默认两线程、512 tokens 问题预算；不会静默截断。多本书可共用一个 MCP 进程和同一权重目录。

### 已实际完成的安装验收

默认部署 Skill bootstrap 已离线实装 46 wheels（73.259 秒）；上面的专用 `install-offline.py` 已在另一独立 CPython 3.13 venv 离线实装 67 项（233.145 秒），批准 wheels 哈希和 pip check 通过。两个新环境均实测默认全文 3 hits、原文定位、Codex host dry-run、46/67 项两个 bootstrap plan、禁网且原包不变。

默认新环境 probe 共 16.747 秒；可选新环境 probe 共 245.664 秒，含冷依赖导入、CPU tensor 运算和计划哈希检查，没有重复完整 BGE-M3 forward，不能当作搜索耗时。可选 Skill bootstrap 的 67 项路线仅验证 plan，真实 67 项安装采用专用安装器。报告记录的是本轮文档更新前的同代码/依赖产物，最终 manifest 随文档重建；具体报告见源码 `docs/acceptance.md`。

## 限制

固定权重来自官方仓库 convertbot 尚未合并的 Safetensors 转换，已核对固定文件哈希；未保证与原在线服务浮点输出完全一致。真实验收与各宿主范围见源码中的 `docs/acceptance.md`。

离线安装器与 bootstrap 共 29 项单元测试已通过（20 项安装器、9 项 bootstrap），使用 mocks 和合成 wheels，覆盖批准 wheel 哈希、环境隔离、安装检查及部署资源一致性；上述 46/67 项真实安装与新环境 probe 另有完成报告。这些不同范围的结果不相加为 pytest 总数。新环境 probe 没有重复完整模型推理，真实视觉模型理解能力也未验证。

离线模式的新 `install-host` 安装会自动为 MCP 设置 600 秒工具期限，并同步 Codex 的 `tool_timeout_sec`；其他模式保持原默认参数。已有旧离线配置若出现所有权冲突，先用 `uninstall-host BOOK_ID --host codex` 安全卸载本项目拥有且未改变的配置，再重新安装。手工接入其他宿主时，仍需在宿主中配置匹配的工具期限。