CLI 中的 Artifact registry 验证

标志参考：agentengine 代理 validate，agentengine 构建。

受众：运行 agentengine agent validate 或 agentengine build 的 CLI 用户。

CLI 在存档上传之前，在本地运行与 ECP 构建启动验证相同的 declared-索引 工件注册表检查。

命令

命令	强制验证	密钥警告
`agentengine agent validate [path]`	当 `artifact_repositories` 非空时	登录时（尽力而为）；`--strict` → 退出 1
`agentengine build`	相同，之前 `InitArchiveBuild`	在客户端可用时始终执行；非阻塞
`agentengine build --upload-build-secrets`	相同	首先从环境中上传声明的密钥 — 请参阅下方

这两个命令都从与 ``agent.yaml`` 相同的目录中读取工具文件。

验证内容

始终（模式 — `agentconfig.Validate`）

artifact_repositories 条目结构: name、type、secret、scope、auth、npm_scope

当 `artifact_repositories` 非空时（跨文件）

已声明的 name (或 npm npm_scope) 必须存在于项目工具链中。
匹配的工具条目必须具有 HTTPS 注册表 URL。
工具和已加载的锁定文件中的 URL 会被扫描，以查找不安全的 SSRF 托管。

选择加入模式（而非错误）

没有 artifact_repositories 块 → 没有跨文件获取。
/ 中未声明的私有 HTTPS URLuv.lockpackage-lock.json → 将在没有平台凭据的情况下通过。
当 artifact_repositories 非空时，工具或加载的锁文件中不安全的 SSRF URL 仍会因 INVALID_REGISTRY_URL 而失败。

秘密警告（在线）

镜像 ECP 密钥查找的范围规则。在 CLI 中，除非指定 agentengine agent validate --strict（退出代码 1），否则这些是警告。ECP 构建-start 将缺失的密钥视为严重故障（在 CodeBuild 之前为 MISSING_BUILD_SECRET）。

代码	CLI `validate`	ECP 构建开始	含义
`MISSING_BUILD_SECRET`	警告；`--strict` → 退出 1	硬故障	在声明的作用域内没有 ASM 密钥
`SCOPE_MISMATCH_HINT`	警告；`--strict` → 退出 1	硬故障	密钥存在于其他作用域中
`WORKSPACE_CONTEXT_NEEDED`	警告；`--strict` → 退出 1	不适用（CLI 需要 `agentengine init`）	工作区范围的条目，但没有工作区上下文
`SECRET_METADATA_LOOKUP_FAILED`	警告；`--strict` → 退出 1	硬故障（不可重试）；在瞬态故障时重试	无法验证在线密钥列表

跨文件硬错误

当 artifact_repositories 非空时，这些会失败 agentengine agent validate、agentengine build（上传前）和 ECP 构建开始交叉检查：

代码	含义	操作指南
`UNKNOWN_INDEX_NAME`	在工具中找不到声明的 `name`（或 npm `npm_scope`）	将 `agent.yaml` 与 `pyproject.toml` / `.npmrc` / `publishConfig.registry` 对齐
`MISSING_REGISTRY_URL`	名称匹配，但工具没有 HTTPS URL	将 `url` 添加到索引/注册表配置中
`INVALID_REGISTRY_URL`	非 HTTPS URL、嵌入式凭证或被阻止的托管	使用 `https://`；切勿将令牌放入 URL 中

锁文件中未声明的私有 HTTPS URL 在没有平台凭据的情况下可以通过（选择加入模式）。当 artifact_repositories 非空时，工具或加载的锁文件中 SSRF 不安全的 URL 仍会因 INVALID_REGISTRY_URL 而失败。设置演练、CI 令牌刷新、Webhook 预植入以及从供应商处迁移 wheels/ 的相关内容，请参阅 agent-yaml.md。

示例

有效的声明索引 (Python)

agent.yaml:

language: pythonrequired_secrets:artifact_repositories:  - name: corps-pypi    type: pypi    secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN

pyproject.toml 必须包含匹配的 [[tool.uv.index]] 名称和 HTTPS url。

agentengine agent validate# ✓ ./agent.yaml valid (egress rules: 0, atlas clusters: 0, artifact repositories: 1)

未知声明名

agentengine agent validate# ✗ ./agent.yaml: artifact registry: UNKNOWN_INDEX_NAME: declared name "missing-index" not found in project tooling# exit 1

未声明的锁定文件 URL（通过）

在 uv.lock 中具有私有包但没有 artifact_repositories 块的代理会退出 0 — 仅限客户数托管的身份验证。

严格模式

agentengine agent validate --strict# Any artifact-registry secret warning (or secret-list failure) becomes exit 1.

在构建之前上传声明的密钥

agentengine build --upload-build-secrets 是一项自选启用的便利功能，用于短期有效的注册令牌。它从同名的环境变量中读取每个 artifact_repositories[].secret，并在构建创建之前在已声明的范围内 PUT 它。它从不读取 agent.yaml 未声明的环境变量。

export ARTIFACT_REPO_CORPS_PYPI_TOKEN="$(aws codeartifact get-authorization-token \  --domain my-domain --query authorizationToken --output text)"agentengine build --upload-build-secrets# ✓ uploaded project secret ARTIFACT_REPO_CORPS_PYPI_TOKEN (version 3)

如果不使用该标志，请使用 agentengine secret set <NAME> 设置一次凭证；该标志适用于在构建之间过期的令牌。

行为	Detail
范围	每个条目，从 `scope`（默认 `project`）→ 项目或工作区 `PUT`
排序	在构建创建之前运行 — ECP 会在构建-start 中将声明的密钥解析为 ASM ARN，如果缺少密钥，则会使构建失败
去重	在相同范围和项目下，相同的密钥只需上传一次，包括跨 `--all`
Missing / empty env var	在代理上传或构建之前失败，并一次性列出所有违规名称。使用 `--all`，解析按工作区运行，因此较早的工作区可能已经上传并构建
保留或无效的名称	已在本地拒绝（`agent.yaml` 个权限命名了 secrets API 保留的名称）
授权	项目范围需要 `PROJECT_OWNER`（或 `ORG_ADMIN`）；工作区范围需要 `PROJECT_OWNER` 或 `AGENT_DEVELOPER`
验证	工作区的 `artifact_repositories` 必须通过模式和跨文件验证，然后才能上传其任何机密，无论是在单工作区路径还是 `--all` 路径上
`--all`	按工作区上传；失败仅影响该工作区

密钥值绝不会出现在 stdout、日志或错误文本中 — 上传失败时，会通过与 agentengine secret set 相同的路径进行清理。