README.md

# 给网站搭建 Agent 的开始文件

本目录是 Book Agent 的完整网站发布交付根目录。请从这里开始读取材料，以本目录的相对路径为准。开发目录、私人账号、生产书籍和密钥不是使用前提。

这个 `README.md` 是整组文件完成验收后最后放入的接手入口。接手 Agent 可开始网站搭建；当前交付的是工具与发布材料，网站尚未上线。

## 开始工作

1. 先读取 [网站发布交接说明](网站发布交接说明.md)，再读取 [用户完整使用手册](用户完整使用手册.md) 和 [一句话安装提示词](一句话安装提示词.md)。需要安装细节时读取 [安装 Agent 操作指南](安装Agent操作指南.md)。
2. 核对 `SHA256SUMS.txt`、`release-manifest.json`、`DOWNLOADS.json` 与实际文件。保持整组发行文件一致；不要只更换一个程序而沿用其他版本清单。
3. 建立下载页面，向普通用户提供三种简单选择：**原文阅读（默认）/ 本地离线语义 / 在线语义**。除工具包和书包位置、模式外，技术细节交由用户的安装 Agent 自动处理。
4. 根据 `DOWNLOADS.json` 为实际部署的网站生成真实下载 URL。当前没有写入域名，也没有发布网站。保持下载路径与完整目录布局一致，发布最终清单的可信 SHA-256。
5. 在网页提供可复制的一句话安装提示词、详细手册、下载大小、模式说明、已验证平台及必要的简单界面操作。网站发布与实际平台验收按交接文档完成。

## 下载项目

| 项目 | 文件 / 目录 | 适用情况 |
| --- | --- | --- |
| 首选入门包 | `book-agent-starter-windows-x64.zip` | Windows 64 位用户；默认原文模式无需 Python、Key 或模型 |
| 可选离线运行组件 | `book-agent-offline-addon-windows-cp313.zip` | Windows x64 CPython 3.13；只在选本地向量时需要 |
| 独立模型权重包 | `weights/BAAI-bge-m3/` | 约 2.29 GB，离线模式可选，一套兼容模型供多书共用 |
| 独立 Windows 程序 | `book-agent-windows-x64.zip` | 高级入口，完整保留旁边的 `_internal` |
| 通用 Skill | `book-assistant-skill-0.1.0.zip` | 安装与书籍问答的 Agent 指引；不包含书籍正文或模型 |
| 源码与 Python 发行物 | `book-agent-source-0.1.0.zip`、`.whl`、`.tar.gz` | 开发、跨平台源码安装及对应源码获取 |
| 说明和清单 | 四份中文主文档、`docs/`、两个许可清单、`third-party-licenses/`、`release-manifest.json`、`SHA256SUMS.txt`、`DOWNLOADS.json` | 安装、发布、功能与验证边界、许可和哈希 |

完整目录也提供一次性的 `wheelhouse/` 和 `offline-wheelhouse/`，安装器使用本地批准 wheels。离线 addon 的主发行清单单独提供，安装 Agent 将同版本可信清单放在 addon 解压根后使用，避免内嵌清单形成哈希循环。

## 发布时必须保留的真实边界

- 导入对象是已经生成的完整成品书籍知识包，含原书 PDF/EPUB、全文 Markdown、Book Skill、清单和既有 SQLite 向量库。裸 PDF 不会通过此工具自动变成知识包。
- 本工具读取成品、检索证据、回溯原文，并接入 MCP。不会重新蒸馏、生成正文向量或创建外部 chunks。
- 原文模式不下载权重；离线模式多书共享环境与权重。已验证的模型文件直接采用，失败下载有按固定模型契约的续传与并发锁。
- 在线向量只在用户明确授权后编码问题。远程重排另需授权，可能发送候选正文；主 AI 宿主本身也有独立网络与账号设置。
- “一句话安装”适用于有本机文件、执行和 MCP 能力的 Agent。纯聊天助手无法替用户安装，部分宿主仍需用户点击导入、刷新或启用连接。
- Windows 已进行实际验证；Linux/macOS 提供源码路线，其他宿主真实 UI 和模型视觉理解不能宣传为已通过本机验收。完整验证范围见手册。
- 本目录没有私人书籍、用户账号或 Key。网站不要索要或收集用户的本地书籍与密钥。
- 自有代码 MIT；权重 MIT；第三方依赖许可各异，PyMuPDF/MuPDF 为 AGPL 或另行商业许可。保留清单、许可文件及对应源码获取方式。

## 避免重复和额外磁盘占用

首选包不包含模型或 PyTorch。离线组件与模型都是独立可选下载，模型文件在本交付中仅保留一份；不要在服务器或用户安装流程中为每本书复制或下载一份权重。不需要将整套材料再复制成多份大合集。网站如需单文件模型下载，可在服务器按需打包或采用文件清单下载，不在客户端留下多份约 2 GB 副本。

页面功能、下载与用户体验的详细执行步骤以 [网站发布交接说明](网站发布交接说明.md) 为准。不要改写书包契约或把历史测试结果宣传成新平台验收。