setup

只需将此仓库接入 Veris 一次。再次运行时会跳过已完成的步骤。 由设置流程负责选择传输方式并进行配置。将所选路径的准备、执行、证据和清理步骤保存在 如何运行 中，这样 build 和 fix 就能重复使用，无需再次选择传输方式。

设置流程既要完成一次已验证的应用运行，也要交付 build 和 fix 所需的交接文件：.veris/twin.yaml、.veris/NOTES.md 和 .veris/setup.json（经验证的插件会话使用其会话元数据，而不是 twin.yaml）。账本辅助工具是可选的。交接时复用已成功执行的、与保存命令完全一致的执行结果；结束时不要重复运行。没有 Git 时，创建相同的文件并跳过提交。

始终遵守以下三条规则：

• 绝不修改应用代码，也绝不将应用指向沙箱。唯一例外是第 3 步中的直连层级：应用已通过环境变量读取各供应商的 URL，且生产环境设置了相同变量。在其他所有情况下，容器或托管层级都会从进程外重定向应用流量，代码仍保留生产主机名和凭据。
• 绝不输出 API 密钥。登录／状态输出会遮蔽平台密钥，但读取数据时可能返回完整的供应商凭据。将包含凭据的数据重定向到受保护的文件中，并确保值不会出现在命令、报告或终端输出中。
• 创建环境、安装任何内容或提升沙箱前，必须先询问。

主 CLI 是 veris；托管运行器有各自的供应商命令。veris <command> --help 会列出相应标志。你在无终端环境中运行，因此所有需要给出的答案都必须通过标志传入。--yes 表示确认。 如果某条命令本来会停止并询问，它会改为拒绝执行，并指出所需的标志。 每个 get 和 list 命令都支持 --json。env get 和 env use 接受表格中显示的简短 ID；--from 需要完整 ID，可通过 --json 查看。

对于包含凭据的表格，首次读取前先确定保存位置： umask 077; CREDS_DIR=$(mktemp -d)，然后将数据命令的输出重定向到 "$CREDS_DIR" 下的文件。使用 jq 'map(keys)' 查看字段名，不要查看原始行。直接将值提取到应用的凭据文件或环境中，不要显示这些值。在交接内容中保留变量名和提取命令，绝不保留提取出的值。JSON 选择器错误可能会引用被拒绝的值，因此也要将解析器的 stderr 重定向到该受保护目录。打印值后再将其移入受保护文件，并不能撤销泄露。

0. 检查当前会话

在检查任何本地 CLI、登录状态或 Docker 之前，先检查可用的插件工具和运行时上下文。如果它们表明当前会话已在插件管理的沙箱中运行，请阅读 ../veris-reference/session.md，进行实时验证，并遵循其中的设置路径。该路径将替代下方的配置／运行／清理步骤，之后再接续通用的说明和元数据流程。未附加 twin 的插件存在尚未满足的供应商前置条件；不要配置替代项。仅仅缺少 Docker 或 API 密钥，并不意味着应选择此路径。

1. 检查机器

同时检查 git rev-parse --verify HEAD 和 git remote -v。没有 Git 提交时，仍可运行 setup、build 和 fix；只有可选的源记录辅助工具需要提交，以固定其比较基准。 没有 PR 远程仓库时，请保留本地更改说明；除非工程师要求，否则不要初始化 Git 或添加 远程仓库。以下提交说明仅适用于存在 Git 的情况。

运行 veris doctor。它会按以下顺序逐行打印检查结果：二进制文件版本、 登录状态、控制平面、网关模式、控制平面提供服务的供应商主机名、Docker、 隧道二进制文件（cloudflared）、证书文件、项目文件、环境、沙盒。

只有在适用时才会显示某些行。网关模式和供应商主机名需要你已登录且控制平面有响应，因此在新机器上不会显示。环境行需要项目文件。运行中的沙盒会显示其时钟和回调注册信息。如果 shell 中的 VERIS_API_KEY 覆盖了配置文件自身的密钥，则会在登录行后立即显示一条警告。

✓ 表示通过，! 表示值得注意，✗ 表示运行会失败。Doctor 本身不会更改任何内容；→ 行会指出对应的命令。任何检查失败时，它都会以状态码 1 退出。--json 会将相同的检查结果输出到 stdout。

• command not found：尚未安装 veris，这里的其他步骤都不会安装它。询问工程师，然后运行适用于其机器的命令。macOS 和 Linux：

  curl -LsSf https://raw.githubusercontent.com/veris-ai/veris-cli/main/scripts/install.sh | sh
  

  Windows：

  powershell -c "irm https://raw.githubusercontent.com/veris-ai/veris-cli/main/scripts/install.ps1 | iex"
  

  无需 root 权限或包管理器。在 macOS 和 Linux 上，二进制文件会安装到 ~/.local/bin，所以如果再次出现 command not found，说明该目录不在 PATH 中：说明这一点，然后停止。 当 veris doctor 打印出版本行时，即表示完成。版本必须为 0.19.0 或更高：较旧的 CLI 不会发送 twin 的控制 URL 现在要求的密钥（其 veris sandbox 命令会因 401 invalid or missing API key 而失败），也缺少每个 twin 的 reset 和 services operations 动词。重新运行安装命令以升级。

• ✗ Not logged in：运行 veris login。它会打印配对码和控制台链接。 将两者提供给工程师，并告诉他们在浏览器中批准配对。然后等待：配对获批后，命令会自行完成，并将密钥保存到配置文件中。--no-browser 会打印链接，但不会打开浏览器。使用其他控制平面时：veris login --profile dev --api-base <url>。在 CI 中无人能批准配对，因此 veris login --key-stdin 会从 stdin 读取现有密钥。 veris whoami 会显示命令将使用的密钥、组织和控制平面。

• 关于 Docker 的 !：第 3 步中的容器层需要正在运行的守护进程。如果工程师要求使用托管执行，请改为检查该层的网关和提供商前置条件。否则请让他们启动 Docker；如果这台机器无法运行守护进程，第 3 步中的托管层就是可行路径。对于正在测试的代码，绝不要退回到不带 --image 运行。托管层的网关检查见 ../veris-reference/hosted.md。

• 如果控制平面出现 no such host 的 ✗，或在工程师表示两者都能正常工作时，docker.sock 出现 permission denied 的 !：你处于沙盒中。请查看 ../veris-reference/troubleshooting.md 中的 The agent is sandboxed。到此停止。

• 在新仓库中，缺少项目文件或沙盒的 ! 是预期状态，并非问题。

• 其他任何 ✗：说明是哪一行以及如何修复，然后停止。

2. 查找代码实际调用的内容

阅读代码，而不是 README：SDK 导入、主机名、基础 URL 设置。列出测试路径上的每个供应商主机名。

veris services 是目录。它会为每个孪生服务打印一行：孪生服务的名称、它代表的对象、应用接收其 URL 时使用的变量，以及代理为其拦截的供应商主机名。--services 接受的就是这个名称。

打印为 name (+issuer) 的孪生服务会通过一个系列身份提供方登录；控制平面会将该身份提供方与持有该孪生服务的每个沙箱一同部署：google-calendar 会与 google-identity 一同部署。--services 接受不带附加标记的名称，同时指定身份提供方也不会有任何影响。因此，沙箱可能持有环境中未指定的孪生服务，而 veris status 会将每个此类服务标记为 +。孪生服务及该标记都不是需要修复的错误。

没有主机名的孪生服务不会被拦截，原因有二。它可能是数据平面：应用使用运行时传给它的 URL 直接连接，而不是通过重定向主机名连接。数据库通常属于这种情况。或者，控制平面目前尚未为它提供主机名。veris doctor 的 vendor-hostnames 行会列出所有处于这种状态的孪生服务，其中只能有 postgres 和 yente。还要列出应用自身需要的数据平面，例如应用自己的数据库或可自托管服务，因为缺少它们会导致测试套件失败。

匹配主机名，而不是供应商。一个供应商可能使用多个主机，而一个孪生服务可能只覆盖其中一部分：Stripe 的孪生服务会响应 api.stripe.com，但不覆盖 files 和 meter-events 主机。多个孪生服务也可能响应同一个主机名，例如三个 Google 孪生服务都列出了 www.googleapis.com。沙箱会按路径路由，因此要包含代码实际调用路径所对应的每个孪生服务。

没有对应孪生服务的主机名属于限制。在第 7 步中记下它，不要模拟它。

通过此命令提供的名称只是起始列表。向工程师展示最终列表，并在创建任何内容之前征得同意。

3. 选择层级，然后构建映像

运行测试有三种方式，每种都称为一个层级。开始构建前先做出决定。明确要求远程运行时，选择下面的托管层级，即使 Docker 可用也不例外。否则，先按代码检查直接层级的门槛，再使用 veris doctor 在容器执行和托管执行之间做出选择。

检查测试路径上的每次供应商调用。如果每次调用都通过应用已读取的环境变量构造 URL，并且生产环境设置了相同的变量，真实主机名仅作为默认值，那么设置这些变量就是已发布的代码路径。不需要代理。这就是直接层级。

在直接层级中，前往 ../veris-reference/direct.md，完成其中的门槛检查和接线，然后回到此处继续第 7 步。跳过本步骤其余内容，并跳过第 5 步和第 6 步：无需映像，也无需验证运行。第 4 步的环境规则仍适用于接线所创建的环境，因此请先运行 veris env list --json，并复用已包含所有服务的环境。第 4 步的代理标志不适用。

如果应用中或其调用的 SDK 内有写死的供应商主机名，就需要通过容器层级或托管层级进行重定向。应用注册的供应商基础 URL 也是如此：如果没有对应的 twin 发布环境提示变量，且没有任何受测路径会访问该基础 URL，则不在此限。在直接层级中，这类基础 URL 会继续连接真实供应商，不会被拦截。veris services 会列出每个 twin 对应的提示变量，而且无需沙箱，因此请在启动任何内容之前检查是否缺少提示变量。

容器层级使用 veris run --image：测试在容器中运行，代理则在旁边运行。当需要重定向且 Docker 可用时，这是默认选择。它支持所有运行时，还可以修补 SDK 捆绑的证书。

托管层级会在远程环境中运行测试，该环境的出站代理是 twin 的网关。工程师要求远程执行，或代码需要重定向且 veris doctor 报告 Docker 不可用、无法在此处启动时，选择此层级。如果没有明确要求托管执行，则优先检查上述直接层级的门槛。在此层级中，前往 ../veris-reference/hosted.md，检查其中的门槛，并按照所选提供商的 所需条件 说明操作。然后回到此处继续第 4 步，不使用映像：省略 --image，让 proxy.image 保持未设置。第 5 步不变；第 6 步则使用提供商的运行步骤和托管收据规则。跳过本步骤其余内容。

使用任何能运行测试的映像：仓库自己的测试映像或 Dockerfile 阶段，或者挂载仓库目录的常规工具链映像。现在构建映像；第 4 步会记录其标签。映像中不要放入任何 Veris 专用内容：不要放密钥、证书或代理设置。如果派生映像需要实际投入不少工作，请将其保留为根目录下的 Dockerfile.veris，并添加注释注明构建标签。如果测试根本无法在容器中运行，请停止并告知工程师。当 docker image inspect <tag> 成功时，即为完成。

如果第 6 步的验证运行在应用访问供应商之前失败——例如解释器找不到某个模块、导入无法解析，或二进制文件不在 PATH 中——请修复并重新构建映像。不要通过 -e PYTHONPATH=… 或挂载覆盖映像自身的副本来修复运行命令：.veris/NOTES.md 会记录在映像构建完成后可用的命令，之后的每次运行都会继承这种变通方法。通常原因是在源代码进入映像之前就安装了项目。使用 uv 时：

FROM ghcr.io/astral-sh/uv:0.9-python3.12-bookworm-slim
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project
COPY src ./src
COPY tests ./tests
RUN uv sync --frozen

先安装依赖项，以便缓存；等源代码就位后，最后再安装项目。

4. 创建环境

veris env create <project-name> --services stripe,asana --ttl 60 \
  --command '<the smallest test command that calls a vendor>' \
  --image <tag> --require-service stripe --default

如果服务名称未知，系统会拒绝并打印目录。请从 veris services 获取名称。

上面的 --ttl 60 是一个选择，并非必需。不提供 --ttl，就不会记录该项，控制平面会应用自己的默认值。超出服务器允许范围的数值会被拒绝，拒绝信息会列出范围。请为镜像拉取、构建和回读预留时间；在执行 veris up 前拉取工作负载镜像。运行中的沙箱无法延长。请在过期和拆除之前保存证据。

--boot、--snapshot、--data 和 --command 的行为相同：只有在提供时才会记录，未提供的选项不会写入任何内容，因此沙箱会启动该套件，不会播种任何数据，而 veris run 会在 -- 后接收命令。在终端外，只需提供名称和 --services（或 --from），因此，只有在你确实想记录某个标志所指定的内容时才传入它，而不是为了回答问题。唯一需要成对使用的是 --boot snapshot；没有 --snapshot ID|NAME 时会被拒绝。

创建环境之前，运行 veris env list --json，读取服务器上每个已有环境的名称和服务。只有当某个环境属于此项目时才采用：它的服务恰好是你的列表，或者它的服务器名称就是项目名称。 然后运行 veris env create <project-name> --from <full id>，并带上相同的其余标志。否则，请创建一个以项目命名的环境，即使现有环境包含你需要的所有服务也不例外。包含额外服务的环境会启动并计费那些代码不会调用的孪生服务，而其他项目的环境是与该项目共享的：任一方执行 env delete --server 和 baseline promote 都会影响双方。采用现有环境时，在创建任何内容之前，你提出的问题中必须使用服务器上的环境名称，附上其 ID，并说明该环境是共享的。--from 和 --services 不能组合使用，因此，采用现有环境后会保留服务器上的服务列表，你无法在此处扩展它。服务器上的名称并不唯一，因此请说明你使用的是哪个 ID。

创建环境之前，请确认所有入口点所需服务的完整并集。缺少某项服务就需要创建新环境；更改本地默认值并不会添加该服务。

名称和服务会发送到服务器。其他所有内容都会写入环境下的 .veris/twin.yaml：如果你提供了 TTL，就会记录该值；还会记录启动来源、数据文件、作为 run.command 的测试命令，以及根据代理标志构建的 proxy: 块：

environments:
  <project-name>:
    proxy:
      image: <tag>
      require_service: [stripe]

提交 .veris/twin.yaml。veris run 会从中读取这两项设置，因此日常命令无需携带任何一个标志。--require-callback、--expose <port> 和 --strict 也会写入同一块。

对于多个入口点，保留一个默认项，并在 NOTES 中为每个工作流记录完整命令，包括各自的 --require-service 和任何回调标志。 require_service 是一个列表，而显式传入的 --require-service 标志会替换该次运行的列表。在 -- 后使用不同命令并不会替换所需服务。对于不兼容的默认项，例如一个 webhook 工作流和一个没有接收端的工作流，请使用 veris env create <flow> --from <full-id>，并为每个工作流传入各自的标志，记录名称各异的本地条目；然后使用 veris run --env <flow> 选择其中一个。 使用 veris env get <flow> 回读其设置。 采用现有环境会写入本地默认值，但不会创建另一个服务器环境。 默认项验证通过，不代表其他入口点也已验证。

挂载、-e 变量、--patch-bundled-cas 和 --cap-add 在文件中没有对应字段。 请将它们写入第 7 步的 .veris/NOTES.md 中记录的 veris run 命令行。除非通过 --data 指定数据文件，否则就没有数据文件。该命令还会将 .veris/twin.local.yaml 添加到 .gitignore；该文件只适用于当前计算机，永远不会被提交。完成的标准是：veris env get 显示每项设置、其来源以及服务器上的记录。

5. 启动沙盒

运行 veris up。它会创建环境的沙盒，并立即记住此文件夹对应的沙盒 ID。随后，它会等待控制平面报告沙盒已就绪，并等待每个孪生服务响应。它会添加环境的数据文件，并打印每个孪生服务的 URL，以及应用接收该 URL 时所用的变量。环境中未命名的孪生服务表示平台添加的登录颁发方（步骤 2）；其提示旁边的行会对此进行说明。

当命令以退出码 0 结束并列出孪生服务时，即表示完成。随时运行 veris status 可查看沙盒状态：包括其状态、启动来源和过期时间，以及每个孪生服务的状态、环境变量提示、URL 和表计数。沙盒会在 TTL 到期后消失。

如果失败，请查看退出码。沙盒失败时会以退出码 1 结束，并显示原因。如果等待结束时沙盒仍在配置中，则会以退出码 4 结束。默认等待时间为五分钟，使用 --timeout 10m 可延长等待时间。退出码为 4 时，沙盒会保留，而且仍可能启动，因此稍后请检查 veris status。如果孪生服务拒绝了某个数据文件，则会以退出码 1 结束，并保留沙盒：修复文件，然后使用 veris sandbox data add <file> 添加它。

6. 验证

veris run --patch-bundled-cas -- <the smallest test that calls the vendor>

像使用 docker run 一样，添加命令所需的内容。

在托管层级中，没有 veris run。请使用提供商的操作步骤，在已配置的容器中运行测试命令。其收据是自某个水位标记以来读取的孪生服务跟踪记录：../veris-reference/hosted.md，参见 提供商操作步骤 和 收据。其中也说明了完成条件。本步骤的其余部分适用于容器层级；请从步骤 7 继续。

• 当镜像不含代码时，使用 -v 将代码库挂载到镜像所需的位置。docker image inspect <tag> 会显示镜像的 WORKDIR。
• 对于应用会读取的凭据目录，使用 -v <dir>:/run/keys:ro -e KEYS_DIR=/run/keys。填写前请阅读孪生服务的 Credentials 部分。需要时，请使用其发布的合成凭据或颁发方提供的令牌；宽松模式并不会让臆造的令牌变为有效令牌。下方的身份验证指南会说明凭据的传递方式。
• 使用 -e 设置测试所需的任何变量。

除代码库、依赖缓存或凭据目录外，不要挂载其他内容。

--patch-bundled-cas 会将代理的证书追加到它识别的每个 SDK 内置 CA 文件中：certifi、botocore、stripe、httplib2。Stripe、botocore 和 httplib2 需要此证书；如果镜像未内置这些文件，则不会产生额外开销。--receipt <file> 会将收据以 JSON 格式写入该文件，绝不会写入 stdout。

运行结果会为每个孪生服务打印两个计数：

veris: the sandbox received 6 request(s):          ← what the proxy saw leave the app
  stripe   6
veris: the sandbox recorded 6 request(s) since the watermark:   ← what the twin logged
  stripe   6
veris: ✓ required stripe ≥1: saw 6   ✓ ledgers agree (6 = 6)

这两个计数是本次运行的两本账。计数以及下方的判定行，就是本次运行的收据。

沙盒总数可能高于代理总数：产品孪生服务可能会在沙盒内通过其配对的颁发方验证令牌。并发流量也可能影响计数。诊断不一致之前，请先比较每个孪生服务的跟踪记录。计数一致本身并不能证明应用运行成功；如果存在差异，则需要根据跟踪记录解释原因。

当运行以退出码 0 结束、所有要求均通过，并且收据和读取回执都能确认流量来自预期的应用流程时，即表示完成。 数据平面可能只出现在沙盒账本中。仅有内部颁发方流量并不能证明应用已运行。 仅凭大于零的计数还不够。如果两个计数都大于零，但运行失败，请查看应用错误和未满足的要求。流量到达后，供应商拒绝、缺少回调或后续应用断言都可能导致失败。使用 veris sandbox data get <twin> auth 查看该 twin 的认证模式。即使凭据检查较宽松，产品 twin（例如 Google Calendar）仍要求令牌来自其发行方。enforced twin 会根据已知状态检查凭据。使用 veris sandbox services manual <twin> --raw 查看 twin 自身的 Credentials 部分；其中说明了这些已发布凭据的存放位置。请使用 veris sandbox data get <twin> <table> --json，因为表格视图会截断较长的单元格。将该 JSON 重定向到仓库外、仅所有者可访问的临时目录中新建的文件中（使用 mktemp -d，并设置 umask 077），然后只提取应用所需的字段，放入环境变量或只读凭据文件中。不要回显凭据值，也不要将其保存在证据中，并在运行后删除临时凭据文件。如果工具拒绝访问凭据，请解决该权限问题；不要改道绕过拒绝。然后，为应用提供 twin 接受的凭据，或者用你持有其凭据的 twin 证明接线正确。无论哪种情况，都要将其记录在第 7 步的 Credentials and versions 下。

然后在第 7 步将完整命令记录到 .veris/NOTES.md。twin.yaml 只保存镜像、必需的 twin，以及 -- 后的命令。只有产生收据的挂载才写入 How to run。因此，如果后续任务需要本次运行未使用的挂载（例如覆盖镜像内置副本的仓库挂载、fixture 目录树），也要在此处证明该挂载有效。

最终成功的命令和必需的 twin 可能与第 4 步记录的不同。如果不同，请使用 veris env create <name> --from <full id> --force 重新记录。保留条目中已有的所有标志：修正后的 --command 和 --require-service，以及相同的 --image 和 --default；如果条目记录了 --ttl、--boot 和 --data，也要一并保留。该条目会被替换，而不是合并，因此省略的标志会被删除。删除 --require-service 后，后续每次运行都不再断言该 twin，空收据也会被判定为成功。如果不使用 --from，该命令还会在服务端创建第二个环境。之后重新运行 veris env get，并再次检查第 4 步的完成条件。

你自己的 veris sandbox 读取不会计入运行总数。运行开始时会设置一个水位线，只统计此后沙盒记录的内容。运行期间进行的任何 /veris/* 读取都会显示在单独的 control-plane (/veris/*) 行中，并标记为不计入统计。

任一计数达到要求即可通过检查。如果只有一侧的计数决定了 ✓，该行会注明是哪一侧：(engine; …) 或 (sandbox ledger; …)。退出码 4 表示两个计数都无法确定检查结果，因此结果未知。请重新运行。如果问题再次出现，请检查 veris status 并报告。

对于入站流量，除了 --require-service，还要使用 --expose <port> 和 --require-callback <path>。按照 ../veris-reference/webhooks.md 中的说明完成注册、签名和投递回读。请证明接收方自身的断言；付款成功并不能证明已收到其 webhook。

退出码 3 表示某项要求未满足。如果其中指出回调问题，请先参阅 webhook 参考文档，再更改出站接线。对于未满足的服务要求，请检查：

1. 测试并未调用供应商：进程内模拟仍处于活动状态，或者有筛选器跳过了它。选择一个确实会调用供应商的测试。
2. 供应商的主机名不在环境中的孪生服务所响应的范围内：对照代码中的主机名与 veris services 和 veris env get。
3. SDK 拒绝了证书：出现 CERTIFICATE_VERIFY_FAILED、SSLError，或连接供应商主机时发生连接错误。如果某个主机拒绝了所有握手，运行会打印一行，注明该主机和一个 Next: 步骤。按步骤操作。 --patch-bundled-cas 可修复捆绑的 CA 文件。容器运行（--image）会自动注入 JVM 信任库。--java-truststore 仅适用于主机层级，不能与 --image 一起使用。固定证书的 SDK 无法修补：请停止并报告。完整流程见 ../veris-reference/troubleshooting.md 中的 An SDK refuses the proxy's certificate。
4. 孪生服务是没有主机名的数据平面，例如数据库或 Yente 之类的可自托管服务。这些服务不会经过代理。运行会将孪生服务的 URL 通过 veris up 为其打印的变量传递给应用，并说明这一点： veris: yente: not proxied; handed YENTE_API_BASE=…。应用必须读取该变量；如果你自己为同一变量指定了 -e，则以你的设置为准。发往数据平面的流量只会显示在沙箱的计数中，不会显示在代理的计数中，判定结果会注明 (sandbox ledger; not proxied)。这是预期行为。
5. 对于普通供应商孪生服务，控制平面不会提供任何供应商主机名。此时，运行会像第 4 条一样将该孪生服务的 URL 传递给应用，并打印相同的 not proxied 行。这里不应出现该行。veris doctor 的 vendor-hostnames 行会列出控制平面未提供主机名的所有孪生服务，其中的供应商孪生服务就是问题所在。满足条件时，doctor 在那里只列出数据平面 postgres 和 yente；或者，--route <twin>=<host> 为此次运行指定主机名。
6. 应用从运行未启动的进程（compose sidecar）连接供应商：../veris-reference/troubleshooting.md。

切勿通过更改测试中的供应商调用或其基础 URL 来修复退出码 3。

7. 记录你测量到的内容

创建 .veris/NOTES.md 并提交。build 和 fix 会先读取它，因此后续任务无需再次摸索的内容都应记在这里。根据你的实际操作填写：手册、认证模式和验证运行。手册命令为 veris sandbox services manual <twin> --raw；--raw 会将 Markdown 输出到标准输出，不加此参数时，手册会渲染到标准错误。认证模式命令为 veris sandbox data get <twin> auth。

使用以下标题。在每个标题下写明 已测量 或 未测量；空着的标题本身也是一种发现。身份与匹配和错误与去重键除外。一次顺利的运行不会触发任何合并，而且手册不会描述记录身份，因此在设置阶段，这两项的预期内容都是未测量。build 或 fix 首次使用时会通过 ../veris-reference/twin.md 中的读取来补全这两项。

• 如何运行。 保存所选路径的有效准备、启动和重连步骤，所需服务、源代码/构建命令和应用测试命令，包括如何选择受影响的测试。记录如何检查过期状态，以及在需要时如何刷新当前沙箱绑定、URL 或凭据；设置阶段的旧 ID 只是观察结果。记录如何收集该次运行的收据或跟踪记录，包括所选路径需要的运行前/后读取。注明生命周期负责人及其清理或变更交接步骤。链接该路径的参考文档，以便解读收据、退出代码或连接失败。 对于容器执行，保存完整且已验证的 veris run 命令行，其中包含收据文件、挂载项和变量。使用真实路径。对于外部挂载，说明其中的内容以及如何创建。使用相同的缓存挂载，从空目录开始证明依赖缓存的准备过程；离线构建无法填充空缓存。记录镜像和构建命令，以及应用如何在不保存密钥的情况下获取凭据。 对于直接执行，保存变量初始化和应用命令，以及每项服务的水位标记和运行后的跟踪记录读取，详见 direct.md。 对于托管执行，保存提供商的准备/运行/拆除命令，以及来自 hosted.md 的证据流程。 对于插件管理的会话，保存应用命令、提供商工具，以及来自 session.md 的证据/交接流程。 保留用于验证此方案的现有证据；记录这些内容无需额外运行应用。
• Twin 无法表示的内容。 没有对应 twin 的主机名、数据平面 twin，以及冒烟测试无法执行的任何内容。
• 身份与匹配。 供应商会将哪些字段视为同一条记录，以及处理过程中是否会对字段进行规范化、截断或拼接。
• 错误与去重键。 哪些失败会绑定到幂等键并在重用时重放，哪些失败会让该键保持可用。重试修复方案以此答案为基础。
• 凭据与版本。 每个 twin 接受的密钥格式、固定的 API 版本，以及虚构值能够通过的任何情况。
• 仓库自身的测试无法触达供应商之处。 进程内模拟的测试套件即使收据为空也会通过。在大多数仓库中，面向供应商的测试根本无法生成收据，因此，指出那个能够生成收据的测试，比长篇说明哪些测试不能生成更有价值。
• Twin 出错的任何情况。

8. 文件，仅当应用会使用文件时

如果应用不上传或读取文件，则跳过此步骤：Drive、Dropbox、附件。 仅包含行的数据状态很容易按任务填充，无需基线。

应用可能会使用文件，却没有任何内容需要填充——没有固定数据，或者没有文件能力孪生接受的凭据。将此情况写在 孪生无法表示的内容 下，然后继续：半填充的基线还不如没有。

否则，先填充一次文件，让之后的每个沙箱都从这些文件开始。步骤见 ../veris-reference/state.md 中的 Files。读回文件，并对照本地文件检查每一行的 SHA-256。先询问工程师，再运行 veris baseline promote。该命令会捕获此文件夹的沙箱，将其保存为快照，将该快照设为环境默认值，然后删除源沙箱。--keep-source 会保留该沙箱，并将其冻结和清理。Promote 是你对该沙箱执行的最后一项操作。运行 veris baseline get 显示固定版本即表示完成。之后每次运行 veris up 都会从该状态启动，而且只有在此处设置才会执行 promote。将沙箱中的内容写入 .veris/NOTES.md：所有者、路径、哈希值。

9. 保存构建信息和产物偏好

让 .veris/setup.json 与仓库的构建定义保持同步。沿用有效的现有信息；构建或工作命令发生变化时更新：

{"source_roots": ["api/app"], "build_command": "make build", "build_outputs": ["dist"]}

source_roots 是生产源码所在位置。build_command 和 build_outputs 分别是仓库自身的构建命令，以及构建写入的目录。缺少这些信息时，后续任务无法判断构建结果是最新还是过期；它会如实说明，而不会假装能够判断。如果应用已预先构建到测试镜像中，build_command 用于构建该镜像，build_outputs 为 []；将镜像标签写入 .veris/NOTES.md。如果使用标准工具链镜像编译挂载的源码，记录包含源码和缓存挂载的编译命令，以及写回仓库的输出目录（例如 Maven 的 target）。使用你已验证的确切命令。解释型语言通常完全不会写入构建目录，此时如实填写 []。不要指定与被测代码无关的构建。

保留现有的 artifact_policy 以及工程师的忽略/保留选择。如果未记录偏好，则使用 pr-body；不要在每个任务中重复询问：

• pr-body：在变更说明中附上简洁的验证摘要和选定的脱敏证据。已保存的任务产物保留在本地。
• local：产物保留在磁盘上。远程会话需要显式导出，才能在其沙箱过期后保留这些产物。
• commit：将选定的脱敏任务产物/证据纳入 Git。

对于使用 pr-body 或 local 的新设置，追加以下缺失的忽略条目。对于已有设置，保留有意作出的选择。绝不要整体忽略 .veris/：那样也会隐藏 twin.yaml 和 NOTES.md。

.veris/bin/
.veris/tasks/
.veris/evidence/

对于 commit，保留对 .veris/bin/ 的忽略设置，并使选定的任务/证据路径可纳入版本控制。不要仅仅因为任务产物未被忽略，就提交它们。

可选审计辅助工具

除非工程师要求审计，或调查需要使用记录/账本辅助工具，否则跳过暂存步骤。从此安装中的 veris-reference/scripts/ 将所需的 record.sh/ledger.sh 复制到 .veris/bin/。根据此技能推导路径；在 OpenCode 中，使用 verisSkill 读取已安装的脚本，并在暂存后验证其 SHA-256。使用提供方的远程写入工具或远程 bash 回退方案，不要使用主机的 apply_patch。升级后再次使用暂存的辅助工具之前，先验证或刷新它；常规设置/构建/修复不依赖是否有副本。

10. 完成

对于由 CLI 管理的设置，使用 Python 3 运行已安装插件的 veris-reference/scripts/check-setup.py，指定其绝对路径，并通过 --project 指向此仓库。该脚本会检查交接文件和构建元数据，不会执行项目中的任何内容。修复报告中指出的遗漏。如果无法使用 Python 3，请根据步骤 7 和 9 手动检查相同的文件和元数据；不要仅为此检查安装运行时。这是结构检查，不能替代步骤 6 中的应用验证。先前成功执行过完全相同的已保存 How to run 命令，即可满足此项要求。也要复用从 veris env get <flow> --json 读取的工作流配置。仅当已保存的配方发生变化，或仍有必需的设置条件未经测试时才重新运行；例如，暖缓存运行并不能验证所声称的冷缓存配方。明确说明任何未经测试的配方或缺失的回读结果。 插件会话使用 session.md 中所述的等效会话元数据和交接，无需 CLI 配置文件，也无需运行本地检查器。

以全新会话的方式审查 How to run：包含重新创建临时凭据文件和外部缓存的命令，且不得包含凭据值或未定义的 shell 变量。按要求提供 RUN.md 和 COVERAGE.md，作为交接材料；它们不能替代 .veris/NOTES.md 或 .veris/setup.json。

清理前保存脱敏证据，包括验证运行失败后的证据。veris down --yes 会删除此文件夹的沙盒。步骤 8 中执行 promote 后，就没有沙盒需要删除了。在托管层级中，先使用提供方的拆除命令删除托管机器（../veris-reference/hosted.md）。告知工程师需要提交哪些文件：.veris/twin.yaml、.veris/NOTES.md、.veris/setup.json，以及（如果你创建了）Dockerfile.veris。报告步骤 6 中的回执行；在 direct 和 hosted 层级中，报告代替回执的跟踪条目。接下来由 build 或 fix 处理任务。向新位置发送仓库代码前先征求同意。