# 下载与校验

公开目录、版本和下载通过 S3/CDN 获取，无需 PAT。部署方提供分发地址和 authority UUID。

## 选择平台

| 系统                   | os        | arch          |
| ---------------------- | --------- | ------------- |
| 通用内容或预设         | universal | universal     |
| macOS Apple silicon    | darwin    | arm64         |
| macOS Intel            | darwin    | amd64         |
| Linux ARM64 / x86-64   | linux     | arm64 / amd64 |
| Windows ARM64 / x86-64 | windows   | arm64 / amd64 |

平台由你明确选择；工具不会把缺失平台替换成另一平台。

## 查询并下载

```sh
export PLUGINCTL_DISTRIBUTION_URL=https://packages.example/
export PLUGINCTL_AUTHORITY_ID=<authority-uuid>
pluginctl list --channel stable --search pluginctl --json
pluginctl show --name my-team/pluginctl --json
pluginctl download --name my-team/pluginctl --version 1.0.0 --platform darwin-arm64 --out ./pluginctl.tar.gz --json
```

可以用 show 中的准确 release-id 替代 --version，两者互斥。只有显式 --version latest 才按
SemVer 选择可用版本。download 校验快照给出的 SHA-256 和字节大小，保存原始归档；
目标文件必须不存在。工具不执行、安装或启用归档内容，生产地址使用 HTTPS。

默认 stable 只有批准的稳定版本；--channel preview 同时包含批准的稳定版和预发布版。
--refresh 重验证 channel pointer；`--revision-id <sha256>` 固定历史快照，并按该快照的事实读取。
一次操作固定一个 revision，不混用后来更新的目录和版本。

## 手动校验

macOS 使用 `shasum -a 256 pluginctl.tar.gz`；Linux 使用 `sha256sum pluginctl.tar.gz`；
PowerShell 使用 `Get-FileHash pluginctl.tar.gz -Algorithm SHA256`。
结果必须与版本页面公开的摘要一致。校验失败时不要执行归档内容。

## 下载不可用

隐藏移除当前目录和搜索结果，已知名称/ID 的正式版本仍可精确选择。停用、yank、缺少平台
或预设依赖不可用时，当前快照的正常选择会拒绝。历史快照、metadata 和原归档 URL 仍可读。
这些动作不能收回已经公开的字节，也不改变历史 artifact URL。

网络中断或校验失败不会留下成功输出，也不覆盖已有文件。需要最新政策时使用 --refresh；
明确选择历史 revision 时，结果只代表该历史快照。