---
url: /docs/agentbuff-stack/distribution.md
---
# 开发交付包

这是供自用验证的源码交付包，复用[新站生成器](./new-site)。当前仍为模板 0.3，交付状态为开发阶段；两个真实独立产品、真实服务和生产运行验收仍按 I16 原计划推进。

## 从已提交代码打包

在模板或生成产品的 Git 仓库根目录运行。需要 Bun、Git 和 tar，工作区中应提交的变更必须先提交；忽略的本地配置不会进入交付包。

```sh
bun site:package .local/distribution/my-tool --name "My Tool" --domain https://my-tool.example --port 6700
```

输出目录必须不存在。失败时只清理本次新建的输出目录，已有交付目录不会被覆盖。打包从当前提交的 Git 归档读取源码，再交给原生成器重置站点名称、品牌、资源标识与本地端口；不执行安装、数据库迁移或部署。

目录中有两个文件：

| 文件 | 用途 |
| --- | --- |
| `product.tar.gz` | 一个 `project/` 目录，包含独立产品源码、配置示例、中文教程与保留的许可证 |
| `manifest.json` | 最后写入的完成清单：来源提交、模板来源、产品身份、归档和每个源码文件的字节数 / SHA-256，以及各工作区直接声明的依赖 |

官网源码与案例、Git 历史、私有环境文件、本地数据、邮件捕获、依赖目录和构建产物均不分发。生成器过滤规则统一维护，打包脚本不再维护另一份产品复制清单。交付源码中的符号链接及控制字符文件名会拒绝。

`sourceRevision` 表示本次打包读取的确切提交。`template.revision` 表示产品沿用的模板来源；产品经过自己的提交后，两者可以不同。生成时间会变化，每次归档也可能不同，清单用于校验收到的这一份交付包。

## 校验与安装

保留交付包和清单在同一目录，在模板仓库执行：

```sh
bun site:package .local/distribution/my-tool --verify
```

此命令只检查清单中的归档文件名、字节数和 SHA-256，不解压或运行源码。它用于发现文件损坏，不能认证作者身份，也不会逐个比对归档内文件；逐文件摘要可用于解压后的单独核查。

在新的空目录解压，随后进入 `project/`：

```sh
tar -xzf /absolute/path/my-tool/product.tar.gz
cd project
bun install
```

首次安装要使用 `bun install`：生成器移除了官网工作区，安装会据本产品工作区更新 `bun.lock`。建立产品自己的 Git 仓库并提交更新后的锁文件，之后才使用 `bun install --frozen-lockfile`。仓库不随包分发，不会继承原站远程地址。

按 `README.md` 和[复制新站](./new-site)配置独立数据库、新认证密钥与资源。敏感值仅放 `.env.local` 或对应环境的 Secrets。未启用的外部模块保持关闭；示例域名、资源编号和服务变量需要分别核对。

```sh
bun config:check
bun preview:build
bun preview:start
```

本地预览需要先完成该站的数据库准备；安装与打包不会替你执行迁移。生产服务按[部署教程](./deployment)配置并独立验收。

## 依赖与许可记录

`workspaces` 记录交付源码中各 `package.json` 的直接依赖声明，包括开发、可选和同伴依赖。版本范围原样保存；这不是安装后的准确版本清单、全部传递依赖清单或完整许可证审计。实际解析以本产品安装后提交的 `bun.lock` 为准。

安装完成后，在本产品仓库导出两种范围的依赖报告。输出文件必须不存在，旧报告不会被覆盖：

```sh
bun site:dependencies .local/dependencies-all.json
bun site:dependencies .local/dependencies-production.json --production
```

此入口调用 Bun 自带的 `pm licenses --json`，记录其返回的包名、准确版本、许可标签与分组，并移除报告中的本机安装路径、作者、描述和主页。报告另含当前 `bun.lock` 的 SHA-256、Bun 版本、系统 / 架构、时间与范围；读取过程中锁文件改变会拒绝导出。它不安装依赖、不改锁文件，也不执行包脚本、迁移或部署。

`all` 包含开发和构建依赖，`production` 是 Bun 的生产依赖图，两者都不是最终 Worker 或浏览器构建产物的组成清单。报告依赖当前安装及平台条件，不能用本机结果代替其他平台；先完成安装并提交本产品的锁文件，报告摘要应与这份锁文件对应。未安装的产品不会自动补装。

`reportedLicense` 是 Bun 返回的标签，缺字段保留为 `null`，`Unknown` 也原样保留，不能据此判断授权。此次本地样本中 `khroma@2.1.0` 报为 `Unknown`：其 `package.json` 没有许可字段，但随包的小写 `license` 文件标明 MIT。核查时要读实际原文、保留适用声明，并区分源码、二进制和素材；不能直接把所有依赖统一标为 MIT，也不能把包元数据缺失当作没有许可。

导出的报告可以作为同版本交付的附加核查资料。它是在产品安装后生成的独立文件，不属于原压缩包摘要清单；也不会自动扩写 `THIRD-PARTY-NOTICES.md` 或改变未知标签。

`LICENSE` 和 `THIRD-PARTY-NOTICES.md` 保留原内容，清单记录它们的摘要。第三方说明覆盖现有上游代码、设计系统、字体及补丁来源；新增代码、素材和供应商需继续核对其来源与条款，不能用依赖声明替代这一步。

维护升级按[模板版本与升级](./template-upgrades)操作，核对产品自定义代码、完整迁移历史与自己的备份。交付包不包含旧模板的 Git 历史，历史升级演练需要在拥有基线提交的模板仓库运行。

## 常见问题

| 现象 | 处理 |
| --- | --- |
| 提示工作区未提交 | 提交需要交付的代码；不把真实凭据提交进仓库 |
| 提示输出目录已存在 | 选择新的交付目录；保留旧包用于核对来源 |
| 字节数或摘要不符 | 重新取得原包和对应清单，再校验；不要直接继续安装 |
| 首次冻结安装失败 | 使用普通安装更新生成产品的锁文件，再提交本产品的锁文件 |
| 原账号或原文件没有出现 | 新产品使用独立数据库，本包不复制旧站数据；已有站升级使用升级教程 |

本地验收覆盖实际归档 / 解压、逐文件摘要、许可证原文、私有文件排除、再次生成，以及破损归档、已有目录、未提交源码和源码符号链接的拒绝。从已提交版本生成的实际产品包已通过首次安装、冻结锁文件再安装、离线配置检查，以及公开页、工作台、邮件和中文文档构建；没有执行数据库迁移或云部署。销售价格、授权方案、购买流程、支持范围和正式发布另行确定。