网站发布交接说明.md

# Book Agent 网站发布交接说明

> 当前目录是最终交付根。请先读取根目录 README.md，按其中的交付状态和启动指引工作；文件位置与下载链接以当前目录的正式清单为准，不依赖开发机器路径。交付根可整体移动，保留相对目录布局和唯一 weights/ 模型目录；网站 Agent 使用当前实际位置。
>
> 本文是给网站制作与发布 Agent 的交接任务书。它说明页面、下载结构、文案和发布前需要核对的交付物。
>
> 本次工作只准备说明与本地交付，不代表网站已经建立或部署。目标域名、站点位置、访问范围和最终发布授权由发布负责人提供。
>
> 下载文件名与校验值必须读取最终 release-manifest.json 和 DOWNLOADS.json。不要把工作目录中“看起来像安装包”的任意文件当作正式发布材料。

## 一、先理解要交付的网站

### 1.1 网站目标

让一个计算机知识较少的读者完成下面的路径：

1. 看懂 Book Agent 能帮自己做什么。
2. 选择默认原文阅读、本地语义或在线语义。
3. 下载正确且完整的文件。
4. 复制一段安装提示词给本机 Agent。
5. 按宿主需要完成必要的界面操作。
6. 用一个带引用的首次问题确认真实结果。
7. 能找到详细手册、错误解释、迁移与卸载方法。

首页优先帮助用户选择与下载。详细技术信息放到相应展开区或文档链接，普通用户不需要在下载之前理解向量维度、模型配方或 MCP 配置表。

### 1.2 下载站与书库服务的区别

这个网站分发程序、说明、合法可分发的依赖和一份可选模型。Book Agent 在用户本机以 stdio MCP 运行。

把文件上传到网站，不会自动提供一个远程 MCP 服务器，也不会自动托管用户的书库。不要在页面上写“上传 PDF 即在线问书”，也不要为了下载流程新增书籍上传入口。

私人网站可以按负责人的意图设置登录或限制下载。访问限制与文件组织由站点方案决定；不应把它与用户宿主的 AI 账号、订阅或 API Key 混成同一项。

### 1.3 本次交接的范围

| 项目 | 本文要求 |
| --- | --- |
| 首页、模式选择、下载页、使用说明 | 需要规划与实现 |
| 下载材料的版本、大小和校验值 | 来自最终清单，发布前核对 |
| 一句话安装提示词与详细安装 Agent说明 | 从本次交付文档引用 |
| 网站预览 | 由网站 Agent 按授权完成并交付 |
| 正式发布 | 等目标与发布授权明确后执行 |
| 用户私有书库上传 | 不属于默认网站功能 |
| 远程 Book Agent服务 | 不属于此下载站 |
| 新的 OCR、制书或文档向量平台 | 不属于现有功能承诺 |

## 二、网站 Agent 开始前应收到的材料

### 2.1 发布负责人提供的信息

根 README.md 已给出的目录、状态和任务范围直接使用；以下交接表补充尚未明确的站点目标：

| 信息 | 需要填写什么 |
| --- | --- |
| 网站目标 | 私人下载站、团队分发站或其他明确用途 |
| 目标域名 / URL | 已有地址或待分配地址 |
| 可写的站点项目 / 目录 | 本次真正要修改的项目位置 |
| 发布环境 | 指定托管方或现有站点方式 |
| 访问范围 | 谁可以下载、是否需要已有登录系统 |
| 已批准的发布目录 | 最终 release 所在绝对路径 |
| 正式版本 | 与清单中的 version 相同 |
| 可信清单 SHA-256 | 最终 release-manifest.json 的可信哈希 |
| 大文件分发方式 | 现有文件托管、对象存储或负责人指定方式 |
| 文案与文档 | 四份新中文说明及既有技术文档 |
| 发布授权 | 是否仅做预览，或已经明确授权正式发布 |
| 联系与更新入口 | 有权公开的支持地址和更新方式 |

缺少目标域名不阻止先完成页面与本地预览。缺少正式发布授权时，交付可审查结果和需要发布的具体文件，不把“任务需要网站”自动理解成已批准上传任何私人材料。

### 2.2 本次应交付给网站的说明文件

- 用户完整使用手册.md：完整新手手册和进阶参考。
- 一句话安装提示词.md：适合首页直接复制的简短提示词。
- 安装Agent操作指南.md：给执行安装的 Agent 使用的详细流程。
- 网站发布交接说明.md：本文。
- 根 README.md：当前交付的启动入口与任务状态。
- README-交付说明.md：版本与交付范围。
- 既有技术文档：包格式、部署、宿主、源定位、安全、构建、故障与验收说明。

如果正文来自 docs 中的文件，网站发布目录应提供可访问的链接或渲染版本。不要让用户点击一个只存在于开发者电脑上的 F:\ 路径。

正式 release、starter 和 offline-addon 已提供 docs/ 技术参考目录，四份主中文说明位于根目录；打包时相应链接指向 docs/<技术文档名>。网站按这套已准备的目录布局提供即可。若把 Markdown 渲染成网页，保持这些链接可达；源码文档可另指向同版本正式源码包或仓库。

### 2.3 不需要提供给网站的材料

- 用户私人完整书包或原始 PDF/EPUB。
- 真实书库数据库、运行缓存、注册目录。
- API Key、登录 Cookie、密码。
- 用户或开发者完整宿主配置。
- 私人账号、个人 home 目录或本机路径列表。
- .work 中的真实测试收据、真实书查询记录和本地截图。
- 生产制书流水线中的原始输入、工作文件和未发布输出。

演示书若要提供下载，必须单独确认可分发授权，并在清单中明确其用途。现有真实验收书不自动变成公开样例。

## 三、正式下载文件如何组织

### 3.1 交付层级

| 层级 | 正式名称 / 路径 | 用户意义 | 权重是否在里面 |
| --- | --- | --- | --- |
| 推荐入门包 | book-agent-starter-windows-x64.zip | 默认程序、Skill、安装.ps1、新手说明 | 无 |
| 可选离线依赖补充 | book-agent-offline-addon-windows-cp313.zip | 一次准备共享 CPU 查询环境所需配套依赖 | 无 |
| 独立模型 | weights/BAAI-bge-m3/ | 所有兼容书共用一份查询模型目录 | 有，且只在这一处 |
| 原始默认程序包 | book-agent-windows-x64.zip | 高级用户或原有安装流程 | 无 |
| 通用 Skill | book-assistant-skill-0.1.0.zip | 手动 Skill 安装入口 | 无 |
| 源码包 | book-agent-source-0.1.0.zip | 技术人员、源码安装与审查 | 无 |
| Python wheel | prebuilt_book_agent-0.1.0-py3-none-any.whl | Python安装路线 | 无 |
| Python 源码分发包 | prebuilt_book_agent-0.1.0.tar.gz | Python构建路线 | 无 |
| 安装入口 | 安装.ps1、install-offline.py | 本机安装辅助 | 无 |
| 下载角色索引 | DOWNLOADS.json | 下载页面选择与关联文件 | 无 |
| 完整发布清单 | release-manifest.json | 正式路径、大小、哈希 | 无 |
| 人工校验清单 | SHA256SUMS.txt | 人工核对文件 | 无 |
| 许可证材料 | dependency-licenses.json、offline-dependency-licenses.json、许可证目录 | 具体第三方组件许可 | 无 |

本表的主张是角色分开。实际是否包含某个文件、最终名称和版本，只认本次 final manifest。没有在最终清单中出现的计划产物不能挂成可下载成功的按钮。

starter 为便捷使用可能包含默认程序与说明；单独默认程序包仍可作为高级路线提供。**模型权重不能同时塞进 starter、offline-addon、源码包、Skill 包、程序包或每本书。**

### 3.2 唯一模型目录的当前内容

当前目录包含六个固定上游运行文件、模型收据和来源许可材料：

~~~text
weights/BAAI-bge-m3/
  config.json
  tokenizer_config.json
  special_tokens_map.json
  tokenizer.json
  sentencepiece.bpe.model
  model.safetensors
  book-agent-query-contract.json
  README.md                       来源与使用说明
  MODEL-LICENSE.md                交付许可说明
  UPSTREAM-LICENSE.txt            上游许可文本
~~~

大约 2.29 GB（十进制），精确体积从最终清单求和显示。model.safetensors 是主要大文件。

当前独立交付是一个能够直接加载的目录，不要自己编造 book-agent-model.zip 等新归档名称。网站可以对这份目录中的正式文件提供清楚的下载列表，或让安装 Agent 按清单逐个取得。下载后必须保持目录结构和收据。

如果负责人以后确实增加一份独立模型归档，它应有唯一正式名称、版本与清单项，并更新本说明。不要另发两三种含相同权重的模型包，造成用户重复下载。

### 3.3 为什么依赖和权重分开

- 原文阅读模式不需要 Python 可选模型依赖或权重。
- offline-addon 帮用户一次建立共享 Python 查询环境。
- 权重目录只需取一次，可用于多本兼容书。
- 一个用户使用多个宿主时，仍可共用同一个本机运行环境和模型。
- 更换程序说明或网站文案，不应让用户重新下载约 2.29 GB 模型。
- 更新模型必须核对向量空间兼容性，不能因为程序更新就自动换成任意最新模型。

“共享”条件是模型与书中向量兼容；不同向量空间可能需要不同模型。不要承诺一份模型能用于一切来源的书包。

### 3.4 同一程序代码的三种使用路线

| 路线 | 适用范围 | 网站应怎样标记 |
| --- | --- | --- |
| Windows x64 完整 EXE | 默认 text 与已授权 online；不要求 Python | 推荐默认路线 |
| CPython 3.13 Windows x64 离线 wheel + CPU 依赖 | 当前交付的本地模型路线 | 可选、需额外准备 Python与模型 |
| Python 3.11+ 源码 | 技术人员、其他受支持环境的源码安装 | 源码可用；不声称所有 OS 原生包已实测 |

不要给 starter 标一个“Windows/macOS/Linux通用”徽章。Windows 安装脚本也不要标成所有平台通用。

### 3.5 只用正式目录

下载目录必须从 final release 清单提取。禁止直接开放工作目录、代码根目录或整个磁盘浏览。

特别不要把 dist 中的调试构建、.work 中的旧包、临时日志和历史验收文件与正式 release 混放。相同版本号的说明修改后，文件哈希可能改变；发布方须重建最终清单，网站引用最终值。

不要硬编码此前 SHA-256，也不要从历史聊天中抄一份旧清单哈希。

### 3.6 解压后真实目录与外置主清单

starter ZIP 内层根为 book-agent-start/，addon为book-agent-offline-addon/。安装Agent自动识别真正含安装入口或依赖目录的内层根；新手只提供解压位置，不必手写ReleaseDir。

addon 不把 release-manifest.json 放进自己的ZIP，因为主清单记录该ZIP的哈希会形成循环。下载站需在同一版本旁明确提供外置最终主清单；安装Agent可信核验后，将主清单放在addon实际根目录供当前安装器读取。默认下载角色与安装说明应包含这一关联，不能宣称addon已经内嵌最终主清单。

## 四、网站的信息结构与页面文案

### 4.1 顶部导航

建议只保留：

- 下载。
- 怎么开始。
- 完整手册。
- 常见问题。
- 版本与校验。
- 许可证。

技术参考与源码可以在底部或高级区。无需把底层依赖列表塞进主导航。

### 4.2 首页首屏

建议标题：

> 让你的 AI 助手按书查证据

建议说明：

> Book Agent 把本机完整书包接入你的 AI 助手，帮助它查找段落、读取原文，并在宿主支持时查看页面图片。先用原文阅读模式开始，不需要 Book Agent API Key 或查询模型权重。

主按钮：

> 下载 Windows 入门包

第二按钮：

> 复制安装提示词

旁边的短说明：

> 需要完整成品书包。宿主的主 AI、账号和网络设置由你自己的聊天程序提供。

不要使用“零配置、任何电脑、任何 Agent立即可用”作为首屏承诺。可以写“一次给出书包路径，让安装 Agent 按实际环境配置”。

### 4.3 三种模式选择

页面先问一句：

> 你希望怎样查书？

| 选项卡 | 主文案 | 下载动作 |
| --- | --- | --- |
| 原文阅读 / 文本检索 | 第一次使用推荐。用现成文字找证据，读取原书，必要时看页面图 | 下载 starter |
| 本地语义检索 | 在本机计算当前问题的向量；多本兼容书共用模型 | starter + offline-addon + 独立权重 |
| 在线语义检索 | 使用你明确授权的兼容在线服务；当前问题会发送给它 | starter + 说明；不下载本地权重 |

选择原文阅读不需要额外询问 Key 或模型目录。选择 offline 后再展示 Python、CPU依赖、模型和磁盘说明。选择 online 后再展示凭据环境变量、端点、数据发送范围与兼容要求。

不要让一个新用户在点击默认下载前被迫理解 model revision、pooling 或 embedding space。

### 4.4 推荐下载卡

每张卡至少显示：

- 名称与用途。
- 版本。
- 平台 / 架构。
- 精确大小及友好大小显示。
- 是否包含模型权重。
- 需要搭配的文件。
- 下载按钮。
- SHA-256 复制入口。
- 对应的安装说明链接。

首选 starter 卡应写：

> Windows x64 入门包  
> 包含默认程序、Skill、安装入口与说明。原文模式不需要 Python、查询模型或 Book Agent Key。  
> 请完整解压并保留程序配套文件；准备完整书包后，把安装提示词交给本机 Agent。

offline-addon 卡应写：

> 可选：本地语义依赖  
> 当前配套 CPython 3.13 Windows x64。只补充运行依赖，不包含模型；只需为共享环境安装一次。

权重卡应写：

> 可选：共享 BGE-M3 查询模型  
> 独立目录，约 2.29 GB。所有兼容书共用一份；需要完整六个上游文件与收据。它是查询模型，不是用来聊天的主 AI。

源码、wheel、tar.gz 放在“技术人员下载”展开区。它们不应与 starter 并列成四五个同样突出的新手选择。

### 4.5 三步开始区域

**第一步：下载与解压**

> 下载并核对入门包，完整解压到固定文件夹。

**第二步：提供书包**

> 准备完整成品书包：原书、Markdown、Book Skill、清单与现成数据库。裸 PDF/EPUB 还不能直接作为书包导入。

**第三步：安装与提问**

> 把工具包和书包位置告诉当前安装 Agent，默认用原文阅读；它识别当前助手并完成可执行步骤，你再按提示刷新或启用工具。

每一步链接到完整手册的对应章节，不用首屏展示十几条终端命令。

### 4.6 复制安装提示词区域

用本次 一句话安装提示词.md 的内容；不要另写一个省掉可信校验、完整书包和真实验证边界的“营销版”。

按钮文案：

> 复制安装提示词

按钮旁说明：

> 复制后只需提供本机工具包与书包位置、选择模式。安装 Agent 自动识别系统和当前助手、从可信发布资料读取清单校验值，并选择长期目录。它需要本机文件与命令权限；个别宿主仍可能需要你导入 Skill 或启用工具。

默认可提供一个不保存的简单输入表单：

- 工具包下载 / 解压位置。
- 完整书包位置，可多行。
- 模式，默认原文阅读 text。

宿主范围、数据目录、可信清单SHA-256、Python路径、模型目录与查询环境变量名放在高级可选区，普通用户不必填写。可信校验值由页面/catalog提供给安装Agent读取，默认识别当前助手和合理长期目录。只有选择offline/online时再显示相应额外条件。

表单不要收集 Key 本身，不要默认把路径或提示词发给服务器。若实现有保存行为，应让用户知道实际保存什么。网站默认可只提供静态文本，避免为简单复制引入账号或上传流程。

### 4.7 第一次提问区域

建议可复制示例：

~~~text
请先调用 book_list 列出我的书。
然后只依据《我选择的书》解释“我指定的术语”。
请使用 Book Agent 查证据，展开相关段落，并给出书名、Book ID、
证据 ID 与已验证的原文位置。位置未验证或证据不足时请说明。
~~~

另提供两个折叠例子：看图、跨书比较。跨书例子必须保留每条证据属于哪本书，不写“自动综合全部书库”作为默认行为。

### 4.8 配置好不等于全部成功

首页或 FAQ 放一个简短状态解释：

> 下载、导入、写入宿主配置、实际调用工具、AI 按证据回答、AI 看懂图像，是不同步骤。安装报告会告诉你已经完成到哪一步。

使用 ready 徽章时只用于具体被核对的状态。setup 的 status=ready 不等于主 AI 已真实使用；status=partial 的用户也可能有可用的 text 书，不应把全部结果简化为“失败需从头重装”。

## 五、FAQ 应写出的答案

### 5.1 “我要 API Key 吗？”

> 默认原文阅读和文本检索不需要 Book Agent API Key。本地语义需要可选依赖与模型，不需要在线查询 Key。在线语义才需要兼容服务的 Key 和明确授权。宿主的主 AI 账号或 Key 是另一项设置。

### 5.2 “只下载一个 PDF 可以吗？”

> 本版本需要完整成品书包，包括原书、Markdown、Book Skill、清单和现成数据库。不会在安装时自动做 OCR、分段或生成整本文档向量。只有 PDF/EPUB 时，请先取得完整书包。

### 5.3 “不开向量还能用吗？”

> 能。text 模式可以搜索现成文字、读取上下文、按行或章节读 Markdown，并回到原 PDF/EPUB。图像工具在三种模式中都保留，实际看图需要宿主和主 AI 支持。

### 5.4 “我有二十本书，要下载二十个模型吗？”

> 不需要按书重复下载。兼容书共用一次依赖安装和一份模型目录；不同向量空间需要先检查相容性，不能只看维度相同。

### 5.5 “是不是任何 Agent都能替我安装？”

> 能读本机文件和运行命令的 Agent 可以执行许多步骤。没有本机权限的聊天助手只能指导；宿主登录、工具启用、Skill ZIP 导入等界面步骤可能需要你操作。安装结果按实际完成层级报告。

### 5.6 “我的书会上传吗？”

> 默认 Book Agent 在本机读书。在线查询向量会发送当前问题；可选远程重排会发送问题和有限候选书文，需要另外授权。宿主把工具证据或图片交给主 AI时，其数据路线取决于你自己的宿主和模型设置。

### 5.7 “它能理解每张图、扫描页和复杂公式吗？”

> 它能把受支持的原文页面或 EPUB 图片交给宿主。是否接收和理解图像要实际检查；当前不会自动 OCR。扫描页没有原生文本时会说明限制，不保证所有复杂图表理解。

### 5.8 “本地语义是不是整套 AI 都离线？”

> 本地语义只表示 Book Agent 在本机计算查询向量。主 AI是否离线由宿主模型决定。

### 5.9 “为什么第一次本地语义慢？”

> 首次可能需要导入依赖、校验大文件并准备查询适配器。硬盘和硬件会影响时间。不要把后续暖机结果当作所有电脑的首次速度。

### 5.10 “看到 lexical_fallback 是坏了吗？”

> 这说明所选语义路线未完成，程序用文本检索继续提供材料。查看具体原因；不能把有文本结果当作语义模型成功。

### 5.11 “卸载会把其他 MCP 配置删除吗？”

> 卸载只处理由 Book Agent拥有且未修改的输出或配置条目。无关或用户改过的内容保留并报告，备份也保留。不要恢复整份旧配置覆盖后来的其他改动。

### 5.12 “网站为什么没有我的书？”

> 这是程序下载站。私有书包由你在本机管理；它们不自动公开，也不应为了默认安装上传到网站。

## 六、文件清单、哈希和可信来源

### 6.1 数据来源

网站 Agent 读取：

1. DOWNLOADS.json：按实际格式了解推荐下载角色和依赖关系。
2. release-manifest.json：读取 version 与 artifacts，每项 path、size_bytes、sha256。
3. SHA256SUMS.txt：用于人工可见的校验列表。
4. starter-manifest.json：若展示内部材料说明，从正式 starter 中读取，但不能代替外层发布来源核对。

当前 catalog 格式为 book-agent-download-catalog/1。网站按实际生成内容读取，不抄历史值。主要字段：

| 字段 | 网站怎样使用 |
| --- | --- |
| format / version / default_mode | 核对格式、正式版本与默认text |
| base_url | 当前为null，由负责人指定真实下载基址 |
| publish_paths_relative | 当前为true，文件path相对正式发布根目录 |
| downloads[] | id、label、modes及path/size_bytes/sha256，用于下载卡 |
| optional_model | 唯一独立模型path、files、size_bytes、layout和license |
| guides[] | 四份主中文说明的正式文件项 |
| release_manifest_path / checksum_path | 主清单与人工校验文件的位置 |
| offline_addon_requires_external_manifest | true，依赖补充包需搭配外置主清单 |
| publisher_action | 负责人填真实下载URL，并在可信页面发布最终清单SHA-256 |

例如id为starter对应入门包，offline_dependencies对应可选依赖，其他高级下载按实际downloads显示。字段缺失或format变化时报告实际不兼容，不杜撰值。catalog自身不替用户部署站点，也不声明发布者身份。

### 6.2 哪些校验值应展示

- 每个正式下载文件的 SHA-256。
- 下载前可核对的精确大小。
- 本次 release-manifest.json 自身的 SHA-256，作为安装 Agent 的信任锚输入。
- 版本和发布时点。
- 模型目录各文件的哈希，若权重按文件交付。
- 一个可复制的完整校验文件链接。

清单自身的哈希应由发布负责人在最终内容生成后计算，并通过可信发布位置提供。不要尝试让 manifest 在自己的 artifacts 中递归包含自己的内容哈希。

### 6.3 安装 Agent怎样使用哈希

1. 从发布负责人可信渠道得到最终清单哈希。
2. 下载并核对清单本身。
3. 根据清单核对 starter、addon、脚本和实际要用的文件。
4. 解压 starter 后核对其内部清单。
5. 在实际执行前确认固定目录与版本一致。

脚本的内部完整性检查有用，但它已经开始执行。因此“脚本会自己检查”不能代替运行前验证外层 ZIP 与脚本来源。

### 6.4 页面不得做的校验宣称

不要写：

- “SHA 相同，所以发布者身份百分之百可信。”
- “HTTPS 页面里的所有文件无需校验。”
- “下载包有自己写的 manifest，所以可以执行任何包内脚本。”
- “校验失败也可以跳过，反正只是一本书。”
- “本地 model.safetensors 文件名正确，就证明模型兼容。”

可写：

> 请使用发布方可信渠道给出的清单指纹核对下载。哈希能发现文件与预期不同；模型还会按固定文件与书籍向量空间检查。

## 七、大文件下载体验

### 7.1 单独管理模型

权重约 2.29 GB，网站主页面不要等待整份权重加载，也不要为了预览自动下载它。

权重页面应显示：

- 它是可选的查询模型。
- 完整目录结构。
- 每个文件大小与哈希。
- 下载一次供兼容书共用。
- 放在哪个共享目录。
- 如何让安装 Agent 按正式清单取得。
- 纯离线用户如何先准备全文件。
- 哪些安装命令会在未提供本地模型时尝试下载。

不要只放一个“模型已包含”的图标，却让用户实际得到不完整的分词器目录。

### 7.2 下载服务与链接

按负责人现有托管能力使用可靠文件下载。若存在独立文件域名、授权下载链接或 CDN，发布记录要列出对应的正式文件与哈希。

大文件下载应尽量支持断点续传；如果目标平台不支持，应在实际交付中说明限制，而不是声称已经支持。不要把大文件经过会修改字节的文本或图片处理通道。

私有站的临时授权链接到期后，要给出重新取得链接的方式。网站 Agent不应把临时带权限 URL 复制进可公开传播的文档。

### 7.3 解压提示

starter 需要完整解压。offline-addon 解压后要得到匹配的依赖目录与清单。模型目录不是程序 ZIP 内的一项，也不是每本书的新文件夹。

没有足够磁盘空间时，可选 offline 不应成为默认下载障碍。用户仍可从 text 开始，再按需要增加依赖和权重。

## 八、平台、宿主和验证文案

### 8.1 页面上的支持矩阵

| 对象 | 建议表述 |
| --- | --- |
| Windows x64 默认程序 | 当前直接交付；详细项目见验收记录 |
| CPython 3.13 Windows x64 CPU离线组件 | 本次离线依赖的具体平台 |
| Python 3.11+ 源码 | 源码路线；其他平台按实际安装确认 |
| Codex | 配置/Skill 支持；已有一次真实隔离 Python MCP 使用记录 |
| TRAE CN | 按公开接口生成配置；必要时启用项目工具或手工UI操作 |
| WorkBuddy | 配置生成与 Skill ZIP；导入需 UI |
| Cherry Studio | 生成 stdio 配置供UI审查/添加，绑定到Work Agent；自动Skill发现未验证 |
| 图像工具 | 能返回实际 PNG；宿主接收和主 AI理解需单独验证 |

不要把尚未观察过的宿主显示成绿色“全部验收通过”。“官方文档说明”和“实际安装应用已成功运行”用不同措辞。

### 8.2 可以使用的宣传语

- “把完整书包接入你的 AI 助手。”
- “答案可以带书籍证据与原文位置。”
- “先用原文模式，不需要 Book Agent查询 Key 或权重。”
- “多本兼容书共用运行环境和查询模型。”
- “支持检索后回到原文；图片能力按宿主与模型确认。”
- “安装 Agent 按实际环境完成可执行步骤，并报告剩余 UI 操作。”
- “完整保留原书，运行状态存放在独立目录。”

### 8.3 不应使用的宣传语

- “任意 Agent百分之百全自动安装。”
- “随便扔一个 PDF 就自动获得全部知识。”
- “一次搜索读完所有书。”
- “每张图表、扫描页和公式都能理解。”
- “本地查询模型就是离线聊天大模型。”
- “所有 Windows、Linux、macOS 都已实测。”
- “没有 Key，所以所有宿主也免费离线。”
- “统一 1024 维模型适配所有书。”
- “毫秒级回答任何书籍问题。”
- “已有图片回传，所以实际模型看图验收已完成。”

### 8.4 性能与测试数字

详细数字最好放在验收页面，不放在入门下载卡上。如果使用数字，必须附：

- 对应交付或提交范围。
- 实际执行环境。
- 真实模型还是固定合成向量。
- 模拟服务还是实际在线服务。
- 冷启动还是暖启动。
- 只计搜索核心还是包含依赖加载、宿主与主 AI。
- 未验证项目。

前一交付的测试276 passed、2 skipped、真实本地模型与真实Codex等记录可作为历史证据。本轮新Windows EXE已完成44/44烟测；首轮全量为362 passed、2 skipped、1 failed（文案选项并列触发路径扫描误报）；文案修正后曾专项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字符，未使用扩展路径前缀。必须按分阶段证据说明，不宣称新的一次完整双路线全部通过；221.474秒属于恢复验收范围，不能作为查询延迟。主路线观察到两书7z/EPUB导入、实时书库动态列书与ID隔离、重复身份/缓存、整库text撤销查询联网授权、坏包在前时有效书继续，以及用户notes/未知空目录保护和受管理程序修复。源安装器深路径专项约185.089秒通过；真正过长final与PlanOnly拒绝时未写入Data。网站只引用已观察项目，把宿主主AI工具使用与入口实装分开。

本轮离线安装验收最终通过：67个运行包首次实际安装成功，退出码0，约858.5秒；第二次status=reused，约16.4秒，pip check与CPU依赖导入通过。两本兼容书共享一次模型原地检查/采用，约162.3秒，reused=true、downloaded=false；不兼容2D向量包保留text。原书包与合成输入哈希未变。此处耗时分别属于安装、复用检查及模型采用，不能作搜索性能或完整forward的宣传。本轮没有完整模型forward，历史真实完整前向证据保留其原有范围。

## 九、隐私和许可证

### 9.1 隐私说明文案

建议页面使用以下短文：

> 默认 Book Agent 在本机读取书包。在线查询会向你明确授权的兼容端点发送当前问题；可选远程重排另会发送有限候选书文，需要独立授权。你的宿主和主 AI如何处理证据与图片，请按自己的模型与账号设置确认。

网站无需收集 Key 来提供默认下载。不要创建“粘贴 API Key 以生成安装命令”的字段。

### 9.2 软件与模型许可

| 内容 | 许可说明 |
| --- | --- |
| Book Agent 项目代码 | MIT，以本次 LICENSE 为准 |
| 默认与可选 Python依赖 | 各自许可，见本次元数据和许可证文件 |
| PyMuPDF/MuPDF | AGPL 或商业许可；项目 MIT 不重新许可该组件 |
| 可选 BGE-M3 | 上游模型卡标注 MIT，保留来源与固定修订信息 |
| 原书、Markdown和书籍资源 | 原权利人的授权；不因使用本工具而获得再分发权 |

PyMuPDF/MuPDF 官方明确提供 AGPL 与商业许可两种途径。发布负责人应按真实包含的组件、使用方式和分发方式处理相应义务；保留清单与许可文本不能被写成“自动满足所有许可要求”。[官方许可说明](https://pymupdf.readthedocs.io/en/latest/about.html#license-and-copyright)

BGE-M3 上游模型卡标注 MIT。网站保留来源链接和交付收据，不用项目自己的许可替代上游来源信息。[BGE-M3 官方模型页](https://huggingface.co/BAAI/bge-m3)

### 9.3 许可证下载与页面入口

页面应能访问：

- 项目 LICENSE。
- dependency-licenses.json。
- offline-dependency-licenses.json。
- third-party-licenses/：正式交付中的默认与可选依赖许可证统一目录。
- 固定模型的来源和许可材料。
- 源码获取说明或正式源码包。

许可短布局的220项均保留原始字节与来源，最长相对路径73字符。inventory中的bundled_license_sources映射保存实际短发布路径与原上游相对来源；网站按inventory中的正式路径提供文件，保留映射，不依据上游深目录名自行重建发布目录。该布局事实与Windows恢复尾段定点实装结果分别记录；原失败深度的starter尾段已通过PS5 PlanOnly、损坏拒绝、可信ZIP重解压与原有两书text ready恢复，书ID不变。main与starter前段沿用v3冻结记录，整体仍按分阶段证据报告。

若负责人采用商业许可，页面与分发材料应使用其真实授权方案，不自行写成已经购买。

## 十、给网站 Agent 的可复制任务

下面的提示词用于另一个网站 Agent。请发布负责人填入路径与权限，不要保留占位后要求它猜测上线目标。

~~~text
请根据本次 Book Agent 正式交付，制作一个面向计算机新手的下载网站。

材料：
- 已批准的网站项目/可写目录：{路径}
- 目标域名/网址：{网址，尚无则先做预览}
- 使用的托管环境：{现有环境}
- 访问范围：{私人/团队/公开；现有权限方案}
- 最终发布文件目录：{默认当前交付根，按根README确认；或负责人明确指定}
- 版本：{与 manifest 相同}
- 可信 release-manifest.json SHA-256：{最终值}
- 本次文案：用户完整使用手册.md、网站发布交接说明.md、
  一句话安装提示词.md、安装Agent操作指南.md
- 大文件下载位置：{已批准的文件托管位置}
- 当前授权：{只完成页面与预览 / 已明确授权发布到指定位置}

请先阅读网站发布交接说明和最终 DOWNLOADS.json/release-manifest.json。
按实际 schema使用文件名、大小与哈希，禁止抄历史哈希。

首页以“下载Windows入门包”“复制安装提示词”为主。
默认选text原文阅读，不让新用户先填Key或下载大模型。
offline-addon仅包含可选依赖，weights/BAAI-bge-m3是唯一独立模型交付，
不能把相同权重重复放到程序、Skill、依赖包、每本书或多个下载包。

网站要包括：三种模式选择、下载卡、三步开始、安装提示词复制、
首次提问例子、详细手册、FAQ、版本/哈希、支持范围与许可证。
说明完整成品书包要求，裸PDF/EPUB不被当前安装流程自动转换。
说明下载站不等于远程书库服务；用户书库在其本机管理。

只使用最终批准文件，不发布.work、dist临时包、私人书、真实验收收据、
用户目录、Key或完整宿主配置。
保持每个下载按钮对应真实文件；文档内链接也要能访问。
图片回传、实际主AI看图、官方宿主文档和应用实测分开陈述。
若展示测试/性能，给具体版本、环境和范围，不写所有Agent自动成功。

完成可审查页面与下载清单后，交付预览、实际文件映射、
最终清单哈希、未解决项目和更新/回滚方法。
只有上面的授权明确允许正式发布时才部署到所指定位置；
否则交付具体待发布结果，等待发布负责人决定。
~~~

## 十一、发布前的交接检查

这不是让你重新运行重模型测试。网站 Agent只核对将发布的材料与实际站点行为；程序测试由程序负责人负责。

### 11.1 文件与版本

- [ ] 使用的是最终 release，而非中间工作目录。
- [ ] 清单哈希来自本次可信交接。
- [ ] starter、addon、程序、Skill、源码与依赖属于匹配版本。
- [ ] 每个下载按钮的文件真实存在，大小与清单一致。
- [ ] 模型只在独立交付中出现一次。
- [ ] 权重六个固定上游文件与收据完整。
- [ ] 没有把私有书、真实运行记录、Key 或用户配置公开。
- [ ] 技术文档与许可证材料能访问。
- [ ] 没有沿用旧哈希或旧验收的最终版本宣称。

### 11.2 页面与用户流程

- [ ] 默认路线清楚，第一屏不要求理解模型术语。
- [ ] default text 不需要Book Agent Key、Python或权重的说明准确。
- [ ] 宿主主 AI、账号、网络与Book Agent查询服务分开解释。
- [ ] 裸 PDF/EPUB 不能直接导入的要求可见。
- [ ] 一句话提示词可直接复制，新手只需提供工具包、书包位置与模式。
- [ ] offline 需要共享环境与模型，纯离线需要完整本地ModelDir。
- [ ] online 清楚说明当前问题发送与Key环境变量。
- [ ] WorkBuddy/Cherry等UI步骤没有写成全自动完成。
- [ ] status=partial 和未验证层级有FAQ解释。
- [ ] 下载站与远程书服务器的区别清楚。
- [ ] 桌面与手机阅读、长文件名、哈希复制不会遮挡重要内容。

### 11.3 交付记录

网站 Agent交付：

| 项目 | 记录内容 |
| --- | --- |
| 页面预览 | 可审查地址或负责人能打开的预览 |
| 正式发布状态 | 尚未发布 / 已按具体授权发布 |
| 目标网址 | 实际地址 |
| 版本 | 清单版本 |
| 清单哈希 | 最终 release-manifest.json SHA-256 |
| 文件映射 | 本地正式path → 实际下载位置 |
| 模型交付方式 | 唯一目录或未来正式单独归档，按真实结果 |
| 访问权限 | 实际采用的方案 |
| 支持说明 | 真实验证范围与剩余UI操作 |
| 未完成项目 | 哪项缺材料、缺权限或需负责人决定 |
| 更新/回滚方法 | 具体发布目录与恢复路径 |

报告“部署成功”时要有真实目标与可访问结果。只写了页面代码、生成了下载清单或建立本地预览时，应使用对应阶段名称。

## 十二、后续更新与回滚

### 12.1 更新流程

1. 程序负责人完成新的正式交付与对应验证记录。
2. 重新生成 DOWNLOADS.json、release-manifest.json 和 SHA256SUMS.txt。
3. 发布负责人通过可信渠道交付新的清单哈希。
4. 网站 Agent 读取新清单，更新实际文件与卡片。
5. 检查文档、复制提示词、平台范围和许可证是否变化。
6. 如果模型没有变，不让用户重复下载；继续引用同一份独立模型交付。
7. 如果模型变了，说明兼容空间与旧书影响，再给正式独立交付。
8. 完成预览后按授权发布，并记录新版本目标。
9. 保留恢复所需的上一版本页面与清单对应关系。

只修改中文文案也可能改变 starter/源码归档与清单哈希。网站必须使用更新后的最终值。

### 12.2 回滚流程

回滚网站的版本选择和下载映射时，保持整组文件、清单、说明一致。不要只把一个 EXE 换回去，仍展示新版本哈希与文档。

如果只是当前下载链接坏了，优先修复链接与交付映射，不让用户删除本机书库。回滚网站不会自动修改用户已经安装的本机配置。

### 12.3 长期保留的交接资料

保存正式版本、最终清单、可信哈希、文件映射、授权范围、网站源码和使用说明。不要以长期留存为由存储用户Key或私有书。

## 十三、官方说明与技术参考

宿主资料可帮助网站解释 UI 步骤，但不能替代真实应用验收：

- [Codex Skills](https://learn.chatgpt.com/docs/build-skills)
- [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
- [TRAE Skills](https://docs.trae.cn/ide_skills)
- [TRAE MCP](https://docs.trae.cn/ide_add-mcp-servers)
- [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)
- [Cherry Studio 工具、Skills、MCP](https://cherryai.com/docs/en/advanced-basic/agent-workspace/tools-knowledge-skills-mcp/)
- [PyMuPDF/MuPDF 许可](https://pymupdf.readthedocs.io/en/latest/about.html#license-and-copyright)
- [BGE-M3 上游模型页](https://huggingface.co/BAAI/bge-m3)

Codex、TRAE Skill、WorkBuddy Skill、Cherry 与许可/模型页面有 2026-10-03 读取记录；TRAE MCP 和 WorkBuddy MCP 链接沿用此前资料，本轮没有用这些链接完成最新界面或应用验收。

程序技术细节以同版本 docs 中的 package-format、deployment、hosts、security、retrieval、source-resolution、troubleshooting、build 和 acceptance 文档为准。网站不应在重新措辞时改变实际功能与验证边界。