#快速开始

A3S Use 是 A3S 的 AI Native Package Manager，用于解析和管理原生能力， 以及包含 Tool、MCP、OKF、A3S Flow、Skill、UI 的版本化认知包依赖图。

#main 已实现什么

当前只接受一条预览协议基线。manifest v3、catalog v3、receipt v6、plan v4、 host protocol v6、managed scope v2、manager tools v5、pending graph v4、 pre-lock resolution attempt/diagnostic v1、pre-plan download attempt/diagnostic v1，以及 enablement state/operation v3。过时的预览状态会被拒绝， 并提示清理后重新安装。

#安装 A3S CLI

A3S CLI 已提供独立于 Use 产品状态的跨平台安装器。macOS 与 glibc Linux 使用：

curl --proto '=https' --tlsv1.2 -LsSf \
  https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.sh | sh

Windows PowerShell 5.1 或更高版本使用：

irm https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.ps1 | iex

脚本从官方 A3S-Lab/CLI 稳定 Release 选择当前平台归档、校验 SHA-256， 并以当前用户权限原子替换安装。默认不会改写 shell 配置或用户 PATH。

安装 CLI 后，可以显式安装并检查 CLI Release 携带的 Use 开发预览组件：

a3s install use --source release
a3s use doctor --json

#安装 standalone Use 预览版

standalone Use release installer 与上面的根 a3s CLI installer 相互独立。 先下载脚本以便审查；它要求 Cosign 按精确 tag workflow identity 与 GitHub OIDC issuer 验证 release checksum，并只在签名、SHA-256 与提取检查通过后 发布命令。受管命令还会绑定归档内的 OCR model、OCR Skill 与 Browser Skill， 同时保留显式环境变量覆盖。

Linux 或 macOS：

curl --proto '=https' --tlsv1.2 -fsSLo /tmp/a3s-use-install.sh \
  https://raw.githubusercontent.com/A3S-Lab/Use/main/install.sh
sh /tmp/a3s-use-install.sh

Windows x86_64 与 Windows PowerShell 5.1 或 PowerShell 7：

$installer = Join-Path $env:TEMP 'a3s-use-install.ps1'
Invoke-WebRequest https://raw.githubusercontent.com/A3S-Lab/Use/main/install.ps1 -OutFile $installer
& $installer

需要先把 cosign 安装到 PATH，也可在 Unix 通过 --cosign、Windows 通过 -CosignPath 指定可信可执行文件。

这仍是 development-preview 分发路径。带 tag 的 release 已提供确定性归档 序列化、逐平台 SPDX SBOM、GitHub OIDC provenance/SBOM attestation 与 keyless Sigstore checksum bundle。installer 会在下载平台归档前 fail closed 地验证该 bundle，并把已验证 manifest 与 bundle 保留在安装版本目录中。 第二台无编译缓存的干净 runner 还必须逐字节匹配全部随包原生可执行文件， 通过后才会发布带 attestation 的 reproducibility 证据。带 tag 的 v0.3.2 尝试在四个 target 上未通过该门禁。当前非发布资格运行 33651777660 以精确的 main 提交 4f6e4725205d06ab81f8ea98bfee85c7eb4b2bcd 让全部五个平台通过，并作为历史 证据保留。v0.3.5 发布尝试因 public core crate 过期而未创建 Release。 发布工作流 33675697857 的 13 个 job 均通过，并从精确的 main 提交 54758910f2f4ad9498137410e0a2207d412e99a1 为 tag v0.3.6 发布 development-preview v0.3.6 Release， 包含已验证归档与 typed crate。剩余 bootstrap 边界与可选 GitHub attestation 验证见信任与安全。 随后发布工作流 33687297386 的 13 个 job 也全部通过，并从精确的 main 提交 48a0b76f8a4a87a11d16627c7bd7567920852508 为 tag v0.3.7 发布当前 development-preview v0.3.7 Release， 包含已验证归档与 typed crate（a3s-use-core 0.2.6、 a3s-use-extension 0.3.7、a3s-use 0.3.7）。剩余 bootstrap 边界与可选 GitHub attestation 验证见信任与安全。 随后发布工作流 33720485826 的 13 个 job 也全部通过，并从精确的 main 提交 6d3a7baf32ce998a2e487c40fbf78b4a6cda2579 为 tag v0.3.8 发布当前 development-preview v0.3.8 Release， 包含已验证归档与 typed crate（a3s-use-core 0.2.7、 a3s-use-extension 0.3.8、a3s-use 0.3.8）。剩余 bootstrap 边界与可选 GitHub attestation 验证见信任与安全。 随后发布工作流 33756618837 的 13 个 job 也全部通过，并从精确的 main 提交 a5f3cc40bfb0a1021ca150d2ce4295409b74d220 为 tag v0.3.9 发布当前 development-preview v0.3.9 Release， 包含 19 个已验证发布资产与 typed crate（a3s-use-core 0.2.7、 a3s-use-extension 0.3.9、a3s-use 0.3.9）。剩余 bootstrap 边界与可选 GitHub attestation 验证见信任与安全。 随后发布工作流 33791616307 的 13 个 job 也全部通过，并从精确的 main 提交 c4c80a223bfff3698ca4b4598e7175c6e3303239 为 tag v0.3.10 发布当前 development-preview v0.3.10 Release， 包含 19 个已验证发布资产与 typed crate（a3s-use-core 0.2.8、 a3s-use-extension 0.3.10、a3s-use 0.3.10）。剩余 bootstrap 边界与可选 GitHub attestation 验证见信任与安全。 随后发布工作流 33830280138 的验证、 五平台主构建、typed crate 与五平台独立重建门禁全部通过，并从精确的 main 提交 c25028ae0245ba1d28f7e2837e2a87f7e9f6fe40 为 tag v0.3.11 发布当前 development-preview v0.3.11 Release，包含 19 个已验证发布资产与 typed crate（a3s-use-core 0.2.9、 a3s-use-extension 0.3.11、a3s-use 0.3.11）。剩余 bootstrap 边界与可选 GitHub attestation 验证见信任与安全。

#从源码构建

需要 Rust 1.85 或更高版本：

git clone https://github.com/A3S-Lab/Use.git
cd Use
cargo build --workspace --bins --locked
./target/debug/a3s-use doctor \
  --scope-kind user --scope-id user/current --json
./target/debug/a3s-use capability snapshot \
  --scope-kind user --scope-id user/current --json

在 Use checkout 内运行仓库门禁：

cargo fmt --all -- --check
cargo test --workspace --all-targets --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings

#试用开发版 CLI

#通过标准 MCP 暴露共享 Manager

standalone manager endpoint 与 CLI、TUI 共用同一个类型化 PluginManagerService。它在 stdout 上使用标准 MCP framing，因此不要给该 命令传入 --json：

a3s-use mcp serve manager \
  --scope-kind user \
  --scope-id user/current \
  --offline

manager、package-manager 与 use/package-manager 是等价的 target 名称。 该 endpoint 属于高权限管理平面；任意 agent 只有在启用独立的 Capability Gateway embedding API 后，才能获得被授权的能力。

Embedding host 可以使用注入 CapabilityGatewayInvocationProvider 的 CapabilityGatewayMcpServer。它接收 immutable、无路径的 catalog，只发布 catalog 授权的 Tool，并通过标准 MCP dispatch；opaque invocation reference 始终留在 server 侧。宿主还可以调用 serve_streamable_http 在 /mcp 暴露 同一个 server，并显式配置 bearer token、可选的精确 browser Origin，以及 有界的 in-flight 和 rolling-window admission。原生 client 可以省略 Origin； 配置了 allowed Origin 时，仅在请求带有 Origin 才进行匹配。该 HTTP helper 不提供 TLS，应绑定 loopback 或置于可信 TLS terminator 后。Embedding API 现在还提供 CapabilityGatewayInvocationResolver 与 CapabilityGatewayResolvedProvider：宿主将一个 opaque reference 解析为私有 lease，校验精确 descriptor identity，只授权一次，并在整个 invocation 期间保留 该 lease。HTTP 还支持最多 64 项、不可变的 token→principal registry，拒绝重复 token 并完整扫描 credential。生产 receipt/Runtime/Grant 组合与 CLI 接线仍在 路线图中。

Embedding host 也可以从一个 immutable CapabilityRegistrySnapshot 构建该 catalog，使用 CapabilityRegistrySnapshot::capability_gateway_catalog 在 CapabilityGatewayMcpServer::from_registry_snapshot 保留 RAII lease 前检查精确的 package、publication、selected surface 与 readiness evidence。签名验证和 opaque reference 解析仍由宿主负责。

standalone CLI 会先持久化由宿主选择的 Registry 信任边界，再从同一组 enabled source 解析签名包及其完整 SemVer 依赖闭包：

a3s-use registry source add packages \
  --url https://packages.example.org/a3s/ \
  --trust-root sha256:<64-hex-digits> \
  --json

a3s-use install acme/research \
  --scope-kind user \
  --scope-id user/current \
  --registry-name packages \
  --version 2.0.0 \
  --json

a3s-use upgrade acme/research \
  --scope-kind user \
  --scope-id user/current \
  --registry-name packages \
  --json

a3s-use uninstall acme/research \
  --scope-kind user --scope-id user/current --json

需要把 plan 审查与 mutation 分开时，使用一对一 Plugin Manager CLI。 plan-* 命令会返回完整 typed Host plan，但不会修改包状态。从输出复制精确 operationId 与 planDigest；apply 只会重开这一持久化组合，并且只有显式 --yes 才表示确认：

a3s-use plugin search research --kind tool \
  --scope-kind user --scope-id user/current --json
a3s-use plugin inspect acme/research --version 2.0.0 \
  --scope-kind user --scope-id user/current --json
a3s-use plugin plan-install acme/research \
  --scope-kind user \
  --scope-id user/current \
  --registry-name packages \
  --version-requirement 2.0.0 \
  --surface tool/research \
  --json
a3s-use plugin apply-plan \
  --scope-kind user \
  --scope-id user/current \
  --operation-id <operation-id> \
  --plan-digest sha256:<64-hex-digits> \
  --yes \
  --json
a3s-use plugin plan-disable acme/research \
  --scope-kind user --scope-id user/current --json

search、inspect、planning、精确 apply 与 replay 会在适用位置使用已验证 cache； apply 本身不会访问 Registry。MCP Agent call 永远不会隐含用户确认，缺少 --yes 的 CLI call 也不会创建确认。

如果精确的 install、upgrade 或 uninstall 图仍被保留、enable/disable apply 已持久化其 active admitted operation，或者 Host 已审查但尚未 admit 最新 enablement plan，可以在不访问 Registry、也不修改恢复状态的前提下查看其无路径 操作证据：

a3s-use extension diagnose acme/research \
  --scope-kind user --scope-id user/current --json
a3s-use extension diagnose acme/research --history \
  --scope-kind user --scope-id user/current --json

选择 Workspace installation 时提供 --scope-kind workspace --scope-id <id>。该命令报告 reviewed plan、 Registry/TUF 与 cutover 状态、provider readiness、Grant phase、lifecycle publication/drain/rollback 证据和稳定的恢复建议。输出不会包含 path、Registry URL、idempotency key、credential、secret、package content 或任意包作者文本。 图诊断覆盖 planned、admitted 和 cancelled operation。Enablement 诊断优先读取 active Use 证据；否则 digest-bound index 会把最新 Host-reviewed plan 投影为 planned 或精确 cancelled，且不公开 Host/request/fence identity。Use completion 或 Host outcome 会抑制陈旧 plan。对已保留且由 Registry 支持的 install/upgrade 图以及 durable pre-plan download attempt，projection 会依据精确历史 provenance， 在不联网、不写入、不暴露路径的前提下分别报告 expected/retained archive 与签名 executable-planning-target bytes，以及每个 target 的 missing/partial/complete 状态。attempt 在进程退出后仍会保留，并只在 reviewed graph 持久化后删除；target 与 partial 仅供观察，绝不是 authority。 生成精确 lock 之前，durable pre-lock attempt 会记录 refreshed/cached Registry/TUF 进度、每个 source 的验证状态和摘要、TUF role version、有界失败码与 最终 lock 证据。resolver 失败或进程退出后仍可诊断；成功路径会先写入 download attempt，再删除 resolution evidence，不留下人为的诊断空窗。输出不含 URL、路径、 原始 transport error、credential 或 metadata bytes。 --history 会返回该明确 scope/package 中最新 16 个 completed 或 rolled-back operation，以及 cancelled graph plan，总存储上限为 8 MiB；每项同时 包含完整无路径 diagnostic 与单独验证的终结 outcome。系统会先持久化历史，再删除 recovery authority；精确重放按 (operationId, planDigest) 去重，uninstall 后仍可 查询。损坏、链接或超限历史会 fail closed，且不会泄漏原始字节或路径。 真实进程终止与 Host/CLI 测试已证明精确 planning-target resume、无副作用的 planned/cancelled enablement projection，以及 Host finalization 期间的陈旧 plan 抑制。

应用单独审查过的解析结果时增加 --package-lock-digest sha256:<64-hex-digits>。lock 漂移会在下载 archive 前失败。source replace/default/enable/disable/remove 需要 registry source list --json 返回的精确 revision 与 --yes；identity-bound TUF/cache state 和 installed provenance 会被保留。以上 Registry 值仅用于说明； 项目当前没有宣传公共生产 Registry。

对已经精确 promoted 的 OKF projection 执行带引用搜索：

a3s-use knowledge search "retrieval policy" --limit 5 \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge audit \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge backup ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge verify-backup ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge backup-retention ./backups \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge plan-restore ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge restore ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current \
  --plan-digest sha256:<reviewed-plan-digest> --yes --json
a3s-use knowledge restore-status \
  --scope-kind user --scope-id user/current --json
a3s-use state backup ./use-state.a3s-use-state-backup \
  --scope-kind user --scope-id user/current --json
a3s-use state verify-backup ./use-state.a3s-use-state-backup \
  --scope-kind user --scope-id user/current --json
a3s-use state backup-retention ./backups \
  --scope-kind user --scope-id user/current \
  --max-backups 32 --max-bytes 2199023255552 --json
a3s-use state plan-restore ./use-state.a3s-use-state-backup \
  --scope-kind user --scope-id user/current --json
a3s-use state restore ./use-state.a3s-use-state-backup \
  --scope-kind user --scope-id user/current \
  --rollback-backup ./pre-restore.a3s-use-state-backup \
  --plan-digest sha256:<reviewed-plan-digest> --yes --json
a3s-use state restore-status \
  --scope-kind user --scope-id user/current --json

备份验证可以发现损坏，但不能重建 package、Registry、lifecycle 或 Grant authority。Standalone restore 会校验这些独立 authority，要求当前 binding set 是备份 inventory 的精确子集，在无路径计划中绑定该状态与 live main/WAL/SHM evidence，并只接受已审查 digest 的确认执行。它只能创建缺失的精确 binding 文件，绝不覆盖冲突或更新 evidence。更广泛的 authority 恢复、clean-machine 恢复、其他 state family 与 whole-product disaster recovery 仍是 release gate。 restore-status 会报告 global active phase，以及 requested scope 的有界、无路径 history 与剩余容量，不会轮换或改写 evidence。

独立的 state backup 命令会在同一个独占 maintenance fence 内捕获所有 allowlisted Registry、generation、Grant、binding、 lifecycle/package operation、Knowledge、enablement、Host Manager 与 Flow Runtime state family。确定性的 a3s.use.state-backup.v2 manifest 只记录可移植相对路径、 精确 length/SHA-256/mode、family accounting、Registry 和 installed receipt evidence。创建时会拒绝 active/partial work、link/reparse point、special file、 未知 family 与不可移植路径，并在不可覆盖发布前重新扫描完整 inventory。 verify-backup 无需提取、网络或本机 Use state，即可检查 canonical manifest、 精确 archive 长度和每个 payload。backup-retention 会在一个外部目录锁下完整 校验每个托管 archive，返回无路径、oldest-first 的 canonical plan，只接受未变化 的 digest 与显式确认，并至少保留两个已验证 generation。plan-restore 还会要求 精确匹配当前 Use version、OS、architecture，以及独立保留的 Registry/receipt/Grant authority，随后生成无路径的 Add/Replace/Remove/Retain 计划。确认后的 restore 会先创建或验证独立的外部 rollback archive，再以拒绝 link/reparse point 的 candidate staging 和七阶段 journal 执行恢复；15 个真实进程 退出边界均有收敛测试。restore-status 只读报告有界的 active/history/capacity 证据。原始 archive 属于敏感的完整性证据，不是签名，也不能恢复缺失 authority； clean-machine recovery、跨平台运营演练与 disaster-recovery 演练仍是 release gate。

Runtime Service、HTTP MCP、Flow、Knowledge、Skill、UI 的 readiness 都依赖 embedding host 显式提供 owner。owner 缺失时直接 fail closed，不会替换为宽松 runner 或 source-only binding。

#standalone installer 仍缺少什么

预览 installer 与签名 release 证据已经存在；受支持的产品 installer 仍需在 外部运营的 witness 中复核完整 staged tree/最终归档、把证据保留在 GitHub Release 之外、通过完整跨平台恢复矩阵，并完成剩余产品运维。CLI 携带的预览 组件不能替代这些门禁。

#下一步

• 理解认知包模型
• 使用 A3S Flow 打包工作流
• 设计 OKF 知识包
• 配置 Registry 信任与授权
• 查看 Use 与宿主之间的所有权
• 跟踪发布阻塞项