create-windy 0.6.6 → 0.6.8

package/template/docs/operations/incremental-delivery.md

@@ -0,0 +1,213 @@
+# 增量交付与确定性归档
+
+Windy 的交付传输层提供两条增量路径，并保留完整 bundle 作为兼容和真正离线
+fallback。传输层只改变“镜像字节如何到达目标机”，不会替代现有部署事务中的数据库
+备份、volume 冻结、migration、readiness、安装账本原子提交和失败回滚。
+
+## 不变量
+
+- release manifest 绑定完整 Git SHA、目标平台、镜像角色、镜像 config digest、registry
+  digest、Docker archive 文件图和所有内容 blob。
+- 在线镜像事实必须是 `repository@sha256:<64 hex>`；tag 仅可作为发布入口，不能写入
+  安装账本或作为已部署版本证明。
+- V2 manifest 自身在传输前计算 SHA-256，目标机在 stage 前重新计算。每个 blob 同时
+  校验声明尺寸和 SHA-256；缺失、损坏、重复路径、路径穿越或 schema 不支持都会停止。
+- blob 传输完成不等于部署完成。只有旧部署事务完成备份、镜像 load/pull、migration、
+  readiness 和账本提交后，release 才生效。
+- 失败的传输保留已校验完整 blob 和合法 partial，以便续传；失败 stage 会删除自己的
+  nonce 目录，不会删除当前 release、备份或其它 owner 的资源。
+
+## Manifest V2
+
+`DeliveryManifestV2` 使用 `schemaVersion=2` 和 `minimumReaderVersion=2`。核心字段为：
+
+- `images[]`：稳定 role、platform、Docker config digest，以及可选的 registry repository
+  与 manifest digest、layer digest/size；repository 不允许包含 tag、digest、scheme 或
+  凭据。config、manifest 和 layer descriptor 必须绑定归档中的同一内容 blob。
+- `dockerArchive`：格式固定为 `oci-image-layout-v1`；`entries[]` 绑定重建离线 OCI image
+  layout 所需的相对路径、内容 digest、size 和 mode。
+- `releaseFiles[]`：除 `images.tar` 外的完整 release 文件图；stage 会连同重建的
+  `images.tar` 一起原子落盘，不只生成镜像归档。
+- `blobs[]`：去重后的内容寻址集合；多个 archive entry 可复用同一个 blob。
+- `compatibility.fullBundle`：可选 V1 完整 bundle 的文件名、digest 和 size。
+
+reader 必须先协商能力：
+
+1. 目标支持 registry digest 且 manifest 中每个镜像都有 registry 事实时，优先在线拉取。
+2. 否则，双方支持 V2、blob delta 和 resumable transfer 时，使用 SSH blob 差量。
+3. 否则，只有 manifest 显式携带 V1 fallback 时才回退完整 bundle。
+4. 没有共同 schema 时直接失败；不得把未知 V2 当成 V1，也不得静默上传完整包。
+
+## 在线 registry 路径
+
+发布端把镜像推送到标准 OCI Registry（腾讯云 TCR 等），冻结 registry 返回的 manifest
+digest。目标机按 digest pull：
+
+```text
+ccr.ccs.tencentyun.com/example/windy-server@sha256:...
+```
+
+Docker/Containerd 会根据本地 content store 只下载缺失 layer。pull 后必须再次 inspect，
+确认目标 `repo@digest` 的 image config digest 与 manifest 一致，再把 digest-pinned image
+变量交给现有部署事务。Registry 登录由 Docker credential helper 或目标机受控 Secret
+管理；manifest、日志和统计不得包含用户名、密码、token、签名 URL 或 Docker config。
+
+在线统计以 OCI descriptor 为单位记录总 bytes/blob、已存在 bytes/blob 和 Docker 报告
+`Pull complete` 的 descriptor bytes/blob。当前 `pull-registry` 无法从 Docker CLI 审计
+部分缓存、续传及 HTTP/manifest/config 协议开销，因此 `uploadedBytes` 与
+`uploadedBlobs` 明确返回 `null`，另以 `descriptorPulledBytes` /
+`descriptorPulledBlobs` 报告 descriptor 状态；不得把它冒充精确网络字节。无法取得逐
+layer 状态时直接失败，也不用镜像虚拟大小估算。
+
+目标机执行示例：
+
+```bash
+manifest_digest="$(tr -d '\n' < ./DELIVERY-MANIFEST.sha256)"
+bun run delivery:remote -- pull-registry \
+  --manifest-digest "$manifest_digest" \
+  < ./delivery-manifest.v2.json
+```
+
+命令只接受 manifest 中的 `repository@digest`，pull 后用 Docker image config digest 二次
+验真，再输出 descriptor 总量、复用量与上述可审计性标记。镜像推送与
+digest 冻结由发布流水线的 OCI Registry adapter 完成；adapter 必须把 Registry 返回的
+manifest digest 和 descriptor size 写入 `images.json`，不能把输入 tag 当作冻结事实。
+
+## SSH / 离线 blob 差量
+
+生成物中的 `@southwind-ai/delivery` 是 Starter 私有 workspace package。远端命令入口：
+
+```bash
+bun run delivery:remote -- capabilities
+```
+
+协调器的协议顺序固定为：
+
+1. 调用 `capabilities`，协商 schema 和传输方式。
+2. 在安装根目录用原子 `mkdir` 获取 `.delivery-lock`，写入随机 owner token；并发部署失败。
+3. 把 manifest 的 blob 描述发送给 `inventory`。远端逐个重新计算尺寸和 SHA-256，损坏
+   blob 不计为复用。
+4. 对缺失 blob 调用 `partial` 获取已落盘 offset。发送端只从该 offset 继续；接收端要求
+   offset 精确相等、每段 `fsync`，完整后校验 digest 并原子 rename。
+5. `stage` 重新验证 manifest 和所有 blob，检查空间预算，在随机 nonce 目录重建确定性
+   OCI `images.tar` 与其余 release 文件，并验证 `CHECKSUMS.sha256` 的精确集合和每个
+   digest，再把包含 `release/` 与 delivery sidecar 的目录原子 rename 到
+   `releases/<releaseId>`。既有部署事务只消费其中的 `release/`，delivery sidecar 不污染
+   原 verifier 的文件集合。
+6. 释放 owner 匹配的锁。后续由项目既有 `update-offline` 或生产发布事务消费 stage 目录。
+
+远端低层命令使用 stdin 传 manifest/blob 列表和 blob bytes，不把内容放入 shell 参数。
+本地 `SshProcessTransport` 用参数数组调用 `ssh`，目标、二进制和远端路径均先做字符与
+路径边界校验。错误输出会截断并脱敏 credential marker。
+
+`packages/delivery/bin/windy-delivery` 是受管的远端 launcher；它不注册为 workspace
+package `bin`，避免 fresh `bun install` 改写受管源码的 POSIX mode。第一次启用 V2 前，
+从已验真的 Starter/release SHA 把整个 `packages/delivery` 安装到版本目录，再原子切换
+稳定入口（以下命令在目标 Linux 上执行）：
+
+```bash
+sudo install -d -m 0755 /opt/windy/runtime /opt/windy/bin
+sudo cp -R ./packages/delivery /opt/windy/runtime/delivery-0.6.7.tmp
+sudo chmod 0555 /opt/windy/runtime/delivery-0.6.7.tmp/bin/windy-delivery
+sudo mv /opt/windy/runtime/delivery-0.6.7.tmp \
+  /opt/windy/runtime/delivery-0.6.7
+sudo ln -s /opt/windy/runtime/delivery-0.6.7/bin/windy-delivery \
+  /opt/windy/bin/windy-delivery.next
+sudo mv -Tf /opt/windy/bin/windy-delivery.next \
+  /opt/windy/bin/windy-delivery
+/opt/windy/bin/windy-delivery capabilities
+```
+
+版本目录必须来自已经校验的 release，不从 registry tag、临时工作树或目标机网络重新
+生成。若目标还没有 launcher，能力探测只允许按下文显式回退 V1 完整 bundle；SSH
+鉴权、权限、摘要或原子切换失败都不得降级。保留上一版本目录，直到新 launcher 完成
+`capabilities` 与一次部署事务；回滚只需把稳定 symlink 原子切回上一版本。
+
+空间预算在上传缺失 blob 前执行，分别检查 blob store 与 install root 所在文件系统；同一
+挂载点按缺失 blob、完整 release、delivery sidecar、重建 OCI archive 的
+header/padding/payload 和 512 MiB 默认安全余量合并预算，不同挂载点分别 fail closed。
+blob store 的保留/回收策略必须以已提交 release、
+previous release 和未过期 partial 的引用闭包为依据；不得用目录 mtime 猜测后直接删除。
+
+V2 差量示例（`auto` 在具备 registry facts 时只返回 `registry-preferred`，不会暗中改走
+SSH；需要 SSH 时显式选择 `blob-delta`）：
+
+```bash
+manifest_digest="$(tr -d '\n' < ./DELIVERY-MANIFEST.sha256)"
+bun run delivery:remote -- sync-ssh \
+  --manifest ./delivery-manifest.v2.json \
+  --manifest-digest "$manifest_digest" \
+  --store . \
+  --target deploy@example.internal \
+  --remote-binary /opt/windy/bin/windy-delivery \
+  --remote-store /opt/windy/blob-store \
+  --remote-install-root /opt/windy \
+  --remote-fallback-root /opt/windy/fallback \
+  --mode blob-delta
+```
+
+旧端或显式兼容模式使用同一命令的 `--mode full-bundle --fallback
+./full-bundle.tar.gz`。fallback 同样持有 owner 锁并预检目标挂载点；完整包先传到
+owner-scoped partial，摘要核对成功后 no-clobber 原子 rename，失败只清理自己的 partial。
+远端已有同 digest 文件会复用，同名不同 digest 会 fail closed。capability 只有明确的旧端
+“命令不存在/不支持”响应才可降级；SSH 鉴权、网络、权限或畸形 JSON 一律中止。
+
+## 传输统计
+
+每次 blob 计划和实际传输输出以下不含凭据的整数：
+
+- `totalBytes` / `totalBlobs`：当前 release 的去重 blob 集合。
+- `reusedBytes` / `reusedBlobs`：远端完整 blob，加上本次从 partial 续传前已存在的 bytes。
+- `uploadedBytes` / `uploadedBlobs`：本次真正写入 SSH 的 bytes 和涉及的 blob 数。
+
+统计来自内容 descriptor 和接收端确认，不解析 registry URL，也不输出命令环境变量。
+
+## 确定性归档与 macOS
+
+正式 `.tar.gz` 和重建的 `images.tar` 由 Windy 的 ustar writer 按排序后的显式文件集合
+生成：uid/gid/mtime 固定为 0，owner/group 固定为 root，mode 归一化，不写 pax xattr、
+resource fork 或 Finder metadata。路径组件以 `._` 开头时直接拒绝。因此 macOS 上即使
+源目录具有 extended attributes，归档也不会产生 AppleDouble `._*`。
+
+不要改回普通 `tar -czf` 依赖宿主机默认行为。`COPYFILE_DISABLE=1` 只作为调用系统 tar
+读取/验收时的额外保护，不是正式修复本身。回归测试在 macOS 写入真实 xattr，再把归档
+交给无网络的 Alpine 容器解压并比较精确文件集合。
+
+## 构建与旧项目升级
+
+`create-windy@0.6.7` 候选把 `packages/delivery`、本说明和 `delivery:remote` 脚本加入
+受管 Starter。`0.6.6 -> 0.6.7` 通过连续 recipe 事务升级；现有 project-owned 发布脚本
+不会被覆盖。正式构建先准备一个完整 release 目录，其中 `images.tar` 必须是 OCI image
+layout（含 `oci-layout`、`index.json` 和 `blobs/sha256/*`），再运行：
+
+```bash
+bun run delivery:remote -- pack \
+  --release-dir ./.artifacts/release \
+  --output-dir ./.artifacts/delivery \
+  --product windy \
+  --release-id 2026.08.08-1 \
+  --git-sha "$release_git_sha" \
+  --platform linux/amd64 \
+  --created-at 2026-08-08T00:00:00.000Z \
+  --images-json ./.artifacts/images.json
+```
+
+`pack` 不改输入目录：它在临时目录重建确定性的 OCI `images.tar`，重新生成覆盖最终精确
+文件集合的 `CHECKSUMS.sha256`，并以这组相同字节同时构建 V1 与 V2。输出目录独立包含
+`full-bundle.tar.gz`、`delivery-manifest.v2.json`、
+`DELIVERY-MANIFEST.sha256` 和 `blobs/sha256/*`。`images.json` 由 Registry/OCI exporter
+生成，必须记录每个镜像的 role、platform、config digest，以及可选的 repository、
+manifest digest 和 layer digest/size。`pack` 会拒绝普通 Docker save archive、缺失 OCI
+layout、digest 路径不一致、镜像 descriptor 未绑定归档 blob 或输出目录覆盖。
+
+旧项目按以下顺序接入：
+
+1. 先让现有 build-release 生成 OCI layout，并调用 `pack` 同时产出独立 V1 完整 bundle
+   与 V2 manifest/blob store；不要用 rsync 整个 `images.tar` 伪装差量。
+2. 在线发布增加 registry push 与 digest 冻结，目标事务改用 digest-pinned refs。
+3. SSH wrapper 接入 `SshProcessTransport`，stage 成功后仍调用原 `update-offline`。
+4. 至少连续保留一个兼容周期的 V1 bundle；确认所有安装端支持 V2 后，才可由产品版本
+   决策是否停止生成 fallback。
+
+升级器的三方合并、备份和冲突处理规则不变。客户已有同名 project-owned 文件时必须
+报告真实冲突，不能用 `--force` 或手工复制覆盖。

package/template/docs/platform/agent-runtime.md

@@ -3,7 +3,7 @@
 更新时间：2026-07-26。
 
 Windy 的 Agent Runtime 是可选平台能力。业务模块声明稳定的 AI Operation 和允许调用的
-Tool；Southwind AI Server 负责身份、Feature、Permission、License、Scope、Execution
+Tool；Windy Server 负责身份、Feature、Permission、License、Scope、Execution
 Grant 与审计；独立 Agent Server 只负责模型循环、canonical event 和受限 Tool Host
 回调。业务模块不选择 Provider、模型、Endpoint 或凭据。
 
@@ -94,7 +94,7 @@ host.registerAiOperationHandlers([
 放进返回值。`prepare` 只负责把已经过宿主 Guard 的类型化输入转成指令和用户消息。
 
 Tool handler 仍通过 `registerToolHandlers` 注册。模型提出 Tool Call 后，Agent Server
-携带短时 opaque grant 回调 Southwind AI Server；受限 Tool Host 会验证：
+携带短时 opaque grant 回调 Windy Server；受限 Tool Host 会验证：
 
 1. grant 是否绑定当前 Run、Operation、Actor 且未过期；
 2. Tool 是否属于 Operation 的 `allowedToolKeys`；
@@ -106,7 +106,7 @@ Tool 请求不能携带权限列表、License、Scope 或“已授权”标志
 
 ## 跨进程 Limits 契约
 
-Manifest 的 Operation limits 同时包含输入、执行时间和输出上限。Southwind AI Server
+Manifest 的 Operation limits 同时包含输入、执行时间和输出上限。Windy Server
 在调用远端 Agent Server 前先执行文本输入与 Artifact 声明的 `maxInputBytes` 校验；
 跨进程请求逐字段发送 Agent Server 需要再次执行的时长、输入、输出、图片数量与像素
 上限。禁止通过展开 Manifest 对象透传 limits：TypeScript 的结构类型不会在运行时
@@ -293,7 +293,7 @@ Operation 契约。
 
 ## 客户端协议
 
-浏览器继续使用 `@southwind-ai/ai-client` 访问同源 Southwind AI Server：
+浏览器继续使用 `@southwind-ai/ai-client` 访问同源 Windy Server：
 
 ```text
 POST /api/agent/runs

package/template/docs/platform/document-ai-runtime.md

@@ -4,7 +4,7 @@
 
 Windy 的 Document AI 是可选的独立故障域。业务模块声明稳定的
 `kind=document` Operation，并先把当前 Actor 有权读取的业务资源换成短时
-`ArtifactRef`；Southwind Server 完成 Feature、RBAC、License、数据范围、业务对象绑定
+`ArtifactRef`；Windy Server 完成 Feature、RBAC、License、数据范围、业务对象绑定
 和审计后，才把任务交给 Document Server。未安装或未配置 Document Server 时，对应
 Operation 稳定返回 `CAPABILITY_UNAVAILABLE`，普通业务和文本 Agent 仍可启动。
 
@@ -103,7 +103,7 @@ Repository 证明当前 Actor 可访问真实资源并绑定该文件时才会
 
 ## HTTP 与事件协议
 
-浏览器通过同源 Southwind Server 调用：
+浏览器通过同源 Windy Server 调用：
 
 ```text
 POST /api/document/runs
@@ -131,7 +131,7 @@ fail closed；Adapter 的单源 multipart 字段为 `file`，多源字段为重
 
 ### Output Artifact 握手
 
-Output Sink 启用时，Southwind Host 在调用 Runtime 前冻结：
+Output Sink 启用时，Windy Host 在调用 Runtime 前冻结：
 
 - 预分配的 `runId`；
 - 不含 credential 的 Sink Descriptor，包括 scope、output kind、部署/Release/Offer/

package/template/docs/platform/speech-ai-runtime.md

@@ -16,7 +16,7 @@ Agent 启动。
    Repository 回查 `resourceId`、`fileId` 与当前 Actor 的真实关系。
 2. 模块路由调用 `context.aiArtifacts.issue(...)` 换取加密、短时、opaque
    `ArtifactRef`。
-3. `@southwind-ai/ai-client/speech` 只把 Artifact 与领域选项提交到同源 Southwind
+3. `@southwind-ai/ai-client/speech` 只把 Artifact 与领域选项提交到同源 Windy
    Server。
 4. Server 重新检查 Feature、Permission、License、数据范围、能力摘要和 Artifact
    元数据，并按 Actor + Operation 作用域化幂等键。

package/template/docs/platform/vision-ai-runtime.md

@@ -12,7 +12,7 @@ Windy 的首个 Vision 切片在现有 Agent canonical Run 上增加受治理的
 
 - 浏览器和业务模块只提交平台签发的 opaque `ArtifactRef`，不能提交 URL、Base64、
   BlobStore Key、宿主路径、模型名或 Provider Endpoint。
-- Southwind Server 在 Feature、Permission、License、数据范围通过后重新打开资源，
+- Windy Server 在 Feature、Permission、License、数据范围通过后重新打开资源，
   校验 MIME、字节数与 SHA-256，再为 Agent Server 轮换短时引用。
 - Agent Server 只从固定 `AI_ARTIFACT_URL` 内网入口读取图片，拒绝调用方 URL。
 - 只接受 JPEG、PNG、WebP；解码后强制检查图片数量、总字节与单图像素。

package/template/docs/product/built-in-roles.md

@@ -21,6 +21,14 @@ Starter 首次安装提供四个稳定角色。角色 ID 和 code 是升级契
 
 ## 安全边界
 
-当前 `dataScope` 和 `departmentIds` 已持久化，但 Repository 查询级的数据范围 Guard 仍是产品缺口。为避免默认角色越权写入，部门负责人基线暂不授予 `system.user.manage` 或 `system.department.manage`。在部门及下级查询约束和越权测试完成前，不应通过 seed 扩大该角色的写权限；管理员仍可按部署需求显式配置自定义角色。
+`dataScope` 和 `departmentIds` 已持久化，用户、示例工单、Agent Tool、导出与受支持的
+后台路径已经接入 Repository 级查询范围强制。列表、总数、详情、更新和删除把同一 scope
+predicate 下推到查询，缺少 nominal `ScopeContext` 或 ownership 绑定时 fail closed；完整
+边界见[Repository 级 Data Scope 强制](../architecture/data-scope-query-enforcement.md)。新增
+Repository 或异步资源仍必须显式登记 `dataAccess`，不能因已有基础设施而默认视为已覆盖。
+
+部门负责人基线继续不授予 `system.user.manage` 或 `system.department.manage`。这是最小
+权限的产品默认值，不是用前端隐藏替代服务端 Guard；管理员可按部署需求显式配置自定义
+角色，最终仍受 Feature、Permission 和 Repository scope 共同约束。
 
 用户敏感字段策略将 `system.user.read`、`system.user.reveal` 和 `system.user.export` 分为三类能力。普通读取只能取得服务端脱敏结果；明文查看与治理导出即使由超级管理员执行，也必须重新授权并写入关键审计。客户端提交的角色 code、权限数组或展示模式不是授权来源。

package/template/package.json

@@ -52,6 +52,7 @@
     "test:ops:tool-sandbox": "bun run scripts/tool-sandbox-isolation-regression.ts",
     "ops:db": "bun run scripts/production-database.ts",
     "ops:release": "bun run scripts/production-release.ts",
+    "delivery:remote": "bun run packages/delivery/src/cli.ts",
     "test:merge": "bun run scripts/merge-gate.ts",
     "release:verify": "bun run scripts/release-verify.ts --full",
     "release:candidate": "bun run scripts/release-candidate.ts",
@@ -65,7 +66,7 @@
     "check:document": "uv run --directory apps/document-server ruff check . && uv run --directory apps/document-server ruff format --check . && uv run --directory apps/document-server mypy",
     "check:speech": "uv run --directory apps/speech-server ruff check . && uv run --directory apps/speech-server ruff format --check . && uv run --directory apps/speech-server mypy",
     "check:embedding": "uv run --directory apps/embedding-server ruff check . && uv run --directory apps/embedding-server ruff format --check . && uv run --directory apps/embedding-server mypy",
-    "typecheck": "bun run --cwd apps/web typecheck && bun run --cwd apps/server typecheck && bun run --cwd apps/license typecheck && bun run --cwd apps/signing-service typecheck && bun run --cwd packages/ai-client typecheck && bun run --cwd packages/license-sdk typecheck && bun run --cwd packages/jobs typecheck && bun run --cwd packages/server-sdk typecheck && bun run --cwd packages/storage typecheck && bun run --cwd packages/database typecheck && bun run --cwd packages/crud-generator typecheck && bun run --cwd packages/create-windy typecheck",
+    "typecheck": "bun run --cwd apps/web typecheck && bun run --cwd apps/server typecheck && bun run --cwd apps/license typecheck && bun run --cwd apps/signing-service typecheck && bun run --cwd packages/ai-client typecheck && bun run --cwd packages/license-sdk typecheck && bun run --cwd packages/jobs typecheck && bun run --cwd packages/server-sdk typecheck && bun run --cwd packages/storage typecheck && bun run --cwd packages/database typecheck && bun run --cwd packages/crud-generator typecheck && bun run --cwd packages/delivery typecheck && bun run --cwd packages/create-windy typecheck",
     "lint": "oxlint .",
     "format": "oxfmt",
     "check:static": "bun run lint && bun run typecheck && bun run check:agent && bun run check:document && bun run check:speech && bun run check:embedding",

package/template/packages/delivery/bin/windy-delivery

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+await import("../src/cli.ts");

package/template/packages/delivery/index.ts

@@ -0,0 +1,14 @@
+export * from "./src/archive.js";
+export * from "./src/blob-store.js";
+export * from "./src/builder.js";
+export * from "./src/checksums.js";
+export * from "./src/digest.js";
+export * from "./src/manifest.js";
+export * from "./src/negotiation.js";
+export * from "./src/registry.js";
+export * from "./src/redact.js";
+export * from "./src/staging.js";
+export * from "./src/ssh-process.js";
+export * from "./src/ssh-sync.js";
+export * from "./src/transfer.js";
+export * from "./src/types.js";

package/template/packages/delivery/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@southwind-ai/delivery",
+  "version": "0.1.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "files": [
+    "bin/windy-delivery",
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "delivery": "bun run src/cli.ts",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "exports": {
+    ".": "./index.ts"
+  }
+}

package/template/packages/delivery/src/archive-portability.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createDeterministicTarGz, listTarGzEntries } from "./archive.js";
+import { listArchiveFiles } from "./builder.js";
+
+const roots: string[] = [];
+const acceptanceTest =
+  process.env.WINDY_DELIVERY_LINUX_ACCEPTANCE === "1" &&
+  process.platform === "darwin"
+    ? test
+    : test.skip;
+
+afterEach(async () => {
+  await Promise.all(
+    roots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
+  );
+});
+
+acceptanceTest(
+  "macOS xattr 输入经确定性构建后在 Linux 解压保持精确文件集合",
+  async () => {
+    const root = await mkdtemp(join(tmpdir(), "windy-archive-portability-"));
+    roots.push(root);
+    const input = join(root, "input");
+    const output = join(root, "linux");
+    const archive = join(root, "bundle.tar.gz");
+    await mkdir(join(input, "bin"), { recursive: true });
+    await writeFile(join(input, "manifest.json"), "{}\n");
+    await writeFile(join(input, "bin/delivery"), "#!/bin/sh\n", {
+      mode: 0o755,
+    });
+    await run([
+      "xattr",
+      "-w",
+      "com.southwind.delivery",
+      "portable-metadata",
+      join(input, "manifest.json"),
+    ]);
+    await createDeterministicTarGz(archive, [
+      { source: join(input, "manifest.json"), path: "manifest.json" },
+      {
+        source: join(input, "bin/delivery"),
+        path: "bin/delivery",
+        mode: 0o755,
+      },
+    ]);
+    expect(await listTarGzEntries(archive)).toEqual([
+      "bin/delivery",
+      "manifest.json",
+    ]);
+    await mkdir(output);
+    await run([
+      "docker",
+      "run",
+      "--rm",
+      "--network",
+      "none",
+      "-v",
+      `${root}:/work`,
+      "alpine:3.21",
+      "sh",
+      "-eu",
+      "-c",
+      "tar -xzf /work/bundle.tar.gz -C /work/linux",
+    ]);
+    expect(await listArchiveFiles(output)).toEqual([
+      "bin/delivery",
+      "manifest.json",
+    ]);
+    expect(await readFile(join(output, "manifest.json"), "utf8")).toBe("{}\n");
+  },
+  30_000,
+);
+
+async function run(command: string[]): Promise<void> {
+  const child = Bun.spawn(command, { stdout: "pipe", stderr: "pipe" });
+  const [exitCode, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stderr).text(),
+  ]);
+  if (exitCode !== 0) throw new Error(`${command[0]} 失败：${stderr.trim()}`);
+}