setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wire this repository to a Veris environment, once; re-running skips what still holds. Two transports, one contract each:

Container (default). The code is never modified and never told —
```
veris-proxy
```
reroutes its outbound HTTP(S) into a sandbox from outside the process. Leaves
```
.veris/run.sh
```
(the exact
```
veris-proxy run
```
invocation),
```
.veris/setup.json
```
, and
```
Dockerfile.veris
```
only when deriving an image took real work.
Direct (
--direct
). For an application whose own configuration reads each service's base URL from the environment variable the platform names (its
```
env_hint
```
) — then pointing those variables at a sandbox IS the shipped code path, and no proxy or docker is involved. reference/direct.md carries the contract; step 2 gates entry. Leaves
```
.veris/setup.json
```
with
```
"tier": "direct"
```
.

scripts/preflight.sh

in this skill's directory checks the preconditions and reports every one that fails in a single run. Under the direct tier add

--direct

, which skips the binary/docker/image checks; without it all three are required. An environment id given with the command overrides

VERIS_ENVIRONMENT_ID

; service names given with the command seed the step-3 create question.

Where to run it from. On a first run nothing is staged yet, so invoke it from this skill's own directory: derive that absolute path from the path of the file you are reading, confirm it with

test -f <that path>/scripts/preflight.sh

, and run it there. Step 5 then copies it into

.veris/bin/

, and every later run — here, and in

build

and

fix

— uses

sh .veris/bin/preflight.sh

instead.

Pass the version you are running. Add

--plugin-version 0.6.6

to every invocation. A staged copy cannot know which version is loaded, so unless it is told it cannot notice that it is out of date; without the flag it says

VERSION_UNCHECKED

rather than guessing.

一次性将此仓库连接到Veris环境；重复运行时会跳过仍有效的配置。提供两种传输方式，各对应一套约定：

容器模式（默认）：代码不会被修改，也无需知晓配置——
```
veris-proxy
```
会从进程外部将其出站HTTP(S)请求重定向到沙箱中。仅当生成镜像确实需要额外操作时，才会生成
```
.veris/run.sh
```
（具体的
```
veris-proxy run
```
调用命令）、
```
.veris/setup.json
```
和
```
Dockerfile.veris
```
文件。
直接模式（
--direct
）：适用于自身配置会从平台指定的环境变量（即
```
env_hint
```
）中读取各服务基础URL的应用——此时只需将这些变量指向沙箱即可，属于已发布的代码路径，无需使用代理或docker。相关约定可查看reference/direct.md；步骤2会验证是否符合启用条件。生成的
```
.veris/setup.json
```
文件中
```
"tier"
```
字段值为
```
"direct"
```
。

此skill目录下的

scripts/preflight.sh

脚本会检查前置条件，并在单次运行中报告所有未通过的检查项。若使用直接模式，需添加

--direct

参数，该参数会跳过二进制文件、docker及镜像检查；未添加该参数时，上述三项均为必填项。命令中指定的环境ID会覆盖

VERIS_ENVIRONMENT_ID

的值；命令中指定的服务名称会作为步骤3创建环境时的初始选项。

运行路径说明：首次运行时无任何暂存内容，需在此skill的目录下执行：从当前阅读文件的路径推导该目录的绝对路径，通过

test -f <该路径>/scripts/preflight.sh

确认路径正确性，然后在此路径下运行脚本。步骤5会将脚本复制到

.veris/bin/

目录中，后续所有运行（包括

build

和

fix

命令）均需使用

sh .veris/bin/preflight.sh

。

传递当前运行版本：每次调用时需添加

--plugin-version 0.6.6

参数。暂存的副本无法知晓当前加载的版本，因此若不传递该参数，脚本无法检测到版本过时的情况；未添加该参数时，脚本会显示

VERSION_UNCHECKED

而非猜测版本。

1. Credential

1. 凭据配置

sh scripts/preflight.sh

(with

--direct

first when that tier was requested) reports the credential first. If

VERIS_API_KEY

is not set, say exactly this and end the turn:

Run this in your terminal, then tell me when it's done:
echo 'export VERIS_API_KEY=<your key>' >> ~/.zshrc && source ~/.zshrc

(

~/.bashrc

when

$SHELL

is bash.) On their reply, run preflight again — it reads the variable in a fresh shell. Say "VERIS_API_KEY is set"; never print the value; write it nowhere. The

veris

MCP server read the environment at session start: say a restart is needed before its tools work; nothing here needs them.

运行

sh scripts/preflight.sh

（若指定使用直接模式，需先添加

--direct

参数），脚本会首先检查凭据。若未设置

VERIS_API_KEY

，需输出以下内容并结束当前操作：

在终端中运行以下命令，完成后告知我：
echo 'export VERIS_API_KEY=<你的密钥>' >> ~/.zshrc && source ~/.zshrc

（若使用bash shell，则替换为

~/.bashrc

）。用户回复后，再次运行预检查脚本——脚本会在新的shell会话中读取该变量。输出"VERIS_API_KEY已设置"；切勿打印密钥值，也不要将其写入任何位置。

veris

MCP服务器会在会话启动时读取环境变量：需告知用户需重启服务器后其工具才能正常工作；当前步骤无需使用这些工具。

2. Preflight

2. 预检查

It names every missing precondition in one pass, each with its fix on the same line — binary, docker, environment. Fix them together, then run it again; a check whose own precondition failed reports that rather than a second, derived failure. Installing the binary: ask first, never over a working one. What preflight cannot satisfy stops setup — no base-URL override, hand-written config, or run without

--image

; each proves a code path that is not the one that ships.

--direct

is not that fallback, and step 2 refuses it unless it holds: every service base URL the code uses must come from its environment (the exact

env_hint

variables), with no vendor hostname hardcoded on the tested path. Check the code, not the claim — a hardcoded host means the proxy tier, full stop. What

--direct

skips is the binary, docker, and the image; credential and environment checks run unchanged.

脚本会一次性列出所有未满足的前置条件，每个条件后会附带对应的修复方案——包括二进制文件、docker、环境配置等。修复所有问题后再次运行脚本；若某项检查的前置条件未满足，脚本会直接报告该情况，而非衍生出二次错误。安装二进制文件时：需先询问用户，切勿覆盖已正常运行的版本。预检查无法满足的条件会终止设置流程——不允许使用基础URL覆盖、手写配置或不添加

--image

参数运行；这些操作均证明代码路径与发布版本不一致。

--direct

并非 fallback 选项，步骤2仅在满足条件时才允许使用该模式：代码使用的所有服务基础URL必须来自环境变量（即指定的

env_hint

变量），测试路径中不得硬编码供应商主机名。需检查代码而非仅凭声明——若存在硬编码主机名，则必须使用代理模式。

--direct

参数仅会跳过二进制文件、docker及镜像检查；凭据和环境检查仍会正常执行。

3. Environment

3. 环境配置

VERIS_ENVIRONMENT_ID

set →

GET ${VERIS_API_BASE:-https://svc.api.veris.ai}/v1/environments/$VERIS_ENVIRONMENT_ID

(

X-API-Key

; or the

get_environment

MCP tool) must list the services this code calls. Not set →

GET ${VERIS_API_BASE:-https://svc.api.veris.ai}/v1/environments

lists the engineer's; ask which. Create one only after asking, and in the question name the services you inferred from the code — the reply may add or drop names; check each against

GET /v1/services

, the catalogue. Then

POST /v1/environments

{"name":…,"services":[…]}

若已设置

VERIS_ENVIRONMENT_ID

→ 调用

GET ${VERIS_API_BASE:-https://svc.api.veris.ai}/v1/environments/$VERIS_ENVIRONMENT_ID

（需携带

X-API-Key

；或使用

get_environment

MCP工具），需确保返回结果包含此代码调用的所有服务。若未设置该变量 → 调用

GET ${VERIS_API_BASE:-https://svc.api.veris.ai}/v1/environments

获取工程师可用的环境列表；询问用户选择哪个环境。仅在询问用户后才能创建新环境，提问时需列出从代码中推断出的服务名称——用户回复可能会添加或删除服务名称；需逐一检查每个服务是否存在于

GET /v1/services

目录中。然后调用

POST /v1/environments

，请求体为

{"name":…,"services":[…]}

。

4. Image (container tier)

4. 镜像配置（容器模式）

Skip this step under

--direct

. Every container run uses

--image

. Derive one from the repository's own test setup — anything that runs the tests, nothing Veris-specific;

Dockerfile.veris

only if that took real work. reference/transport.md only when the smoke run fails on what the proxy hands the workload.

使用

--direct

模式时跳过此步骤。所有容器运行均需使用

--image

参数。从仓库自身的测试设置中推导镜像——任何可运行测试的配置均可，无需包含Veris特定内容；仅当确实需要额外操作时才生成

Dockerfile.veris

。若冒烟测试因代理传递给工作负载的内容失败，可查看reference/transport.md。

5. Record

5. 记录配置

Under

--direct

: create a sandbox (

create_sandbox

, or

POST ${VERIS_API_BASE:-https://svc.api.veris.ai}/v1/environments/$VERIS_ENVIRONMENT_ID/sandboxes

), read each service's

env_hint

and

url

from

get_sandbox

, and set those variables where the application's environment actually comes from — a platform Secrets pane, an env file, an export. Some panes are human-only (Replit's is — measured): then name each variable and value and wait for the engineer to paste. Write

.veris/setup.json

with

tier

environment_id

sandbox_id

, and the variable names; reference/direct.md carries sandbox lifetime and rotation. Skip

.veris/run.sh

Container tier: write

.veris/run.sh

and

.veris/setup.json

#!/usr/bin/env sh

使用

--direct

模式：创建沙箱（调用

create_sandbox

，或

POST ${VERIS_API_BASE:-https://svc.api.veris.ai}/v1/environments/$VERIS_ENVIRONMENT_ID/sandboxes

），从

get_sandbox

结果中读取每个服务的

env_hint

和

url

，并将这些变量设置到应用实际读取环境变量的位置——例如平台的密钥面板、环境文件或导出命令。部分面板仅支持手动操作（如Replit的面板）：需列出每个变量及其值，等待用户粘贴到对应位置。生成

.veris/setup.json

文件，包含

tier

、

environment_id

、

sandbox_id

及变量名称；沙箱的生命周期和轮换规则可查看reference/direct.md。无需生成

.veris/run.sh

。

容器模式：生成

.veris/run.sh

和

.veris/setup.json

文件：

#!/usr/bin/env sh

Written by /veris-sim:setup. Flags before -- pass through; a command after -- replaces the default.

VERIS_SANDBOX_ID set: attach to that sandbox (build and fix make one per task). Unset: a fresh one per run.

set -eu if [ -n "${VERIS_SANDBOX_ID:-}" ]; then target="--sandbox $VERIS_SANDBOX_ID" else target="--environment ${VERIS_ENVIRONMENT_ID:?}"; fi run() { exec veris-proxy run $target --image myrepo-veris-tests -v "$PWD:/work" -w /work "$@"; } for arg in "$@"; do [ "$arg" = "--" ] && run "$@"; done run "$@" -- make integration


Mounts stay under the repository tree or a known dependency cache. Tell the
engineer both files exist and are worth committing.

**Either tier, `.veris/setup.json` also carries what later tasks would otherwise
re-derive**, each measured here rather than guessed:

- `plugin_version` — the version you passed to preflight;
- `source_roots` — where this repository's production source lives;
- `build_command` and `build_outputs` — the repository's own build, and the
  directories it writes. Without them a later task cannot tell a fresh build
  from a stale one, and says so instead of pretending otherwise;
- `smoke_command` — filled in at step 6: the smallest command that produced a
  non-empty receipt. Most repositories have vendor-facing tests that cannot
  produce one at all; naming the one that can is worth more than a paragraph
  about the ones that cannot.

**Stage the scripts.** Copy `scripts/preflight.sh` from this skill's directory
and `scripts/ledger.sh` and `scripts/record.sh` from the reference directory
beside it into `.veris/bin/`. From here on every command runs them from that one
path, so nothing has to resolve an install location mid-task. Re-running setup
re-stages them, which is how a version mismatch is repaired.

**Ignore what is generated, keep what is measured.** Append these to
`.gitignore` if absent — targeted lines, never a blanket `.veris/`, which would
take `setup.json` and `NOTES.md` with it:

```gitignore
.veris/bin/
.veris/tasks/

Then ask once, and record the answer as

artifact_policy

: a task's diagnosis, ledger and execution record are rendered into the change description (

pr-body

, the default), kept on disk only (

local

), or committed under

.veris/tasks/<task-id>/

(

commit

— say plainly that this merges into the default branch and accumulates one directory per task). Under

commit

, drop the

.veris/tasks/

line above.


挂载路径需位于仓库目录或已知的依赖缓存目录下。告知用户这两个文件已生成，建议提交到仓库。

**无论使用哪种模式，`.veris/setup.json`文件还需包含后续任务无需重新推导的信息**，这些信息均在此处测量而非猜测：

- `plugin_version` —— 传递给预检查脚本的版本号；
- `source_roots` —— 此仓库生产代码的存储路径；
- `build_command`和`build_outputs` —— 仓库自身的构建命令，以及构建输出的目录。若缺少这些信息，后续任务无法区分构建结果是否过期，会直接提示而非继续执行；
- `smoke_command` —— 在步骤6中填充：能生成非空回执的最小命令。大多数仓库的供应商测试无法生成此类回执；找到能生成回执的命令比描述无法生成回执的测试更有价值。

**暂存脚本**：将此skill目录下的`scripts/preflight.sh`，以及其同级参考目录下的`scripts/ledger.sh`和`scripts/record.sh`复制到`.veris/bin/`目录中。后续所有命令均从此路径运行脚本，无需在任务执行过程中解析安装路径。重新运行设置流程会重新暂存这些脚本，以此修复版本不匹配问题。

**忽略生成文件，保留测量数据**：若`.gitignore`中未包含以下内容，需添加这些精准的行，切勿使用通配符`.veris/`，否则会将`setup.json`和`NOTES.md`一并忽略：

```gitignore
.veris/bin/
.veris/tasks/

然后询问用户一次，并将答案记录为

artifact_policy

：任务的诊断结果、分类账和执行记录可渲染到变更描述中（

pr-body

，默认选项）、仅存储在本地（

local

），或提交到

.veris/tasks/<task-id>/

目录中（

commit

——需明确说明此操作会合并到默认分支，并为每个任务创建一个目录）。若选择

commit

选项，需删除上述

.veris/tasks/

的忽略规则。

6. Prove it

6. 验证连接

Container tier:

.veris/run.sh -- <the smallest test that calls the dependency>

. The proxy prints a receipt — requests per service; an empty one exits 3. Not done until the receipt names the environment's service with a count above zero. Write the command that did it into

.veris/setup.json

smoke_command

, exactly as run.

Direct tier has no receipt; the twin's trace is the trust anchor. Run the smallest piece of the application that calls the dependency, then

GET {control_url}/veris/requests

on that service. Not done until the trace shows the application's own calls with a count above zero — a green smoke with an empty trace means the app called the real vendor, not the sandbox. A certificate error against a mapped host is an SDK bundling its own CA — ../veris-reference/trust.md; other signals — ../veris-reference/troubleshooting.md.

Either tier: alongside

.veris/setup.json

, write

.veris/NOTES.md

— what this session measured about the environment that a later task will need.

build

and

fix

read it first; a fact left only in this transcript dies with it.

Use these headings, and write measured under each or not measured — never leave one out, because a heading with nothing under it is itself a finding, and the next task can decide whether to go and get it:

What this twin cannot represent. No endpoint lists a service's coverage (troubleshooting.md), so whatever you established here is the only record of it.
Identity and matching. Which fields the service treats as the same record, and any normalizing, truncating or joining it does on the way.
Errors and the dedup key. Which failure classes bind to an idempotency/dedup key and replay on reuse, and which leave the key free. A fix that retries is built on this answer.
Credentials and versions. The shape a key must have, the API version pinned, and anything a made-up value gets away with.
Where the repo's own tests do not reach the vendor. Suites that mock in-process produce a green with an empty receipt.
Anything the twin got wrong.

Report the receipt line; then step 7.

容器模式：运行

.veris/run.sh -- <调用依赖的最小测试命令>

。代理会打印回执——包含每个服务的请求次数；空回执会以状态码3退出。直到回执中显示环境服务的请求次数大于0，才算完成此步骤。将执行成功的命令准确写入

.veris/setup.json

的

smoke_command

字段中。

直接模式无回执；孪生环境的跟踪日志是信任依据。运行应用中调用依赖的最小代码片段，然后调用

GET {control_url}/veris/requests

查看该服务的日志。直到跟踪日志显示应用自身的请求次数大于0，才算完成此步骤——冒烟测试成功但跟踪日志为空，说明应用调用的是真实供应商服务而非沙箱。若映射主机出现证书错误，可能是SDK捆绑了自身的CA证书——可查看../veris-reference/trust.md；其他问题可查看../veris-reference/troubleshooting.md。

无论使用哪种模式：需在

.veris/setup.json

旁生成

.veris/NOTES.md

文件——记录本次会话中测量的环境信息，供后续任务使用。

build

和

fix

命令会首先读取此文件；仅记录在此 transcript 中的信息会随会话结束而丢失。

使用以下标题，每个标题下填写已测量或未测量——切勿遗漏任何标题，因为标题下无内容本身也是一项发现，后续任务可决定是否需要补充信息：

孪生环境无法模拟的内容：没有端点会列出服务的覆盖范围（可查看troubleshooting.md），因此此处记录的内容是唯一的覆盖范围记录。
身份与匹配规则：服务将哪些字段视为同一记录，以及在处理过程中执行的任何标准化、截断或关联操作。
错误与去重密钥：哪些故障类型与幂等/去重密钥绑定，重复使用密钥时会重放请求；哪些故障类型不会占用密钥。重试修复机制基于此信息构建。
凭据与版本：密钥必须具备的格式、固定的API版本，以及使用虚构值可通过的检查项。
仓库自身测试未覆盖供应商的场景：进程内模拟的测试套件会显示冒烟测试成功但回执为空。
孪生环境存在的错误。

报告回执内容；然后进入步骤7。

7. Files, when the application works with them

7. 文件配置（若应用涉及文件操作）

Skip this when the application does not work with files. When it does — uploads, attachments, documents — set them up once, so every later sandbox starts with the files instead of each task loading them again:

Create a sandbox (
```
create_sandbox
```
), or use the direct-tier one.
Seed the rows the files hang off — an owner, a folder, a repository — in the shapes
```
/veris/schema
```
names, or pick an owner already in the sandbox.
Post the files with that owner through
```
/veris/files
```
where the manual shows it, or through the vendor's own upload API where files are attachments — rows first, files second, as ../veris-reference/state.md lays out.
Read them back and check the SHA-256 in each row against the local file.
Ask the engineer, then
```
promote_sandbox
```
. This is the one place a command promotes, and only with a yes;
```
build
```
and
```
fix
```
never do.
Write what is in the sandbox — owners, paths, hashes — into
```
.veris/NOTES.md
```
.

Rows-only state is cheap to seed per task and do not need this. Report and stop:

build

fix

takes the task.

Ask before installing the binary or sending repository code anywhere new.

若应用不涉及文件操作，跳过此步骤。若应用涉及文件操作（如上传、附件、文档），需一次性完成配置，确保后续所有沙箱启动时已包含这些文件，无需每个任务重新加载：

创建沙箱（调用
```
create_sandbox
```
），或使用直接模式下已有的沙箱。
按照
```
/veris/schema
```
指定的格式，创建文件关联的基础记录（如所有者、文件夹、仓库），或选择沙箱中已有的所有者。
通过
```
/veris/files
```
接口（参考手册指定的路径），或通过供应商自身的上传API（若文件为附件），以上述所有者身份上传文件——需先创建基础记录，再上传文件，具体流程可查看../veris-reference/state.md。
下载文件并检查每条记录中的SHA-256值与本地文件是否一致。
询问用户，确认后调用
```
promote_sandbox
```
。这是唯一需要调用此命令的场景，且仅在用户同意时执行；
```
build
```
和
```
fix
```
命令永远不会执行此操作。
将沙箱中的内容（所有者、路径、哈希值）写入
```
.veris/NOTES.md
```
文件。

仅包含记录的状态可在每个任务中快速生成，无需此步骤。完成后报告并停止：后续任务由

build

或

fix

命令处理。

安装二进制文件或向新位置发送仓库代码前，需先询问用户。