agent-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Integrate this agent repo with Veris from scratch.

This skill takes a repo from "plain customer agent source" to "Veris-ready and pushable." If the user provided a path to an agent repo, use that as the repo root. Otherwise use the current working directory.

Treat any existing

.veris/

files or old scaffold output as starting material only. Use the current bundled references in this skill as the source of truth for what you generate.

从零开始将此代理仓库与Veris集成。

本技能可将仓库从「原生客户代理源码」状态转换为「可推送至Veris的就绪状态」。如果用户提供了代理仓库的路径，则将该路径作为仓库根目录；否则使用当前工作目录。

仅将现有

.veris/

文件或旧脚手架输出作为起始素材，以本技能中内置的参考内容作为生成内容的唯一依据。

Core framing: the agent is the constant, Veris is the test harness

核心框架：代理为核心，Veris为测试工具

Veris exists to test an agent under realistic conditions. The agent is the thing being tested; Veris is the harness around it. That asymmetry drives every decision in this skill:

The agent runs the same way in Veris as it does in production. If the agent speaks HTTP to a Slack Web API in prod, it speaks HTTP to the Veris Slack mock in sim. If it shells out to a CLI in prod, it shells out in sim. No special simulation code path.
All integration work lives in
.veris/
.
```
.veris/veris.yaml
```
,
```
.veris/Dockerfile.sandbox
```
,
```
.veris/config.yaml
```
,
```
.veris/.dockerignore
```
are the deployment descriptor — the equivalent of a Helm chart or
```
docker-compose.yaml
```
for this agent. They describe how to stand the agent up for this environment. They do not contain behavior that belongs inside the agent.
Do not write wrappers, shims, or glue code that "adapts" the agent to Veris. A Python file that wraps a CLI agent to expose a callable, a script that translates Veris's actor format into the agent's native format, a patched version of the agent that accepts Veris-specific parameters — all of these are the wrong shape. They mean the thing you end up testing is not the agent.
Do not modify the agent's source code to make it work in Veris. If the agent assumes something Veris can't satisfy as-is, that's either a Veris platform gap to be logged, or a real issue with the agent that would also break production. Either way, the fix does not belong in the agent's source.
If you find yourself needing a wrapper, stop and treat it as a finding. Ask: what is the agent's real production integration path? If the agent has an HTTP server in prod, use that. If it's CLI-only in prod and Veris's actor can't drive a CLI, escalate — that's a Veris capability gap, not a license to invent glue.
The one legitimate
.veris/
file that is not pure config is a container-orchestration
start.sh
for bundling multiple processes (e.g., a database alongside the agent). Even that starts and runs the agent as-shipped; it does not transform its behavior.

When in doubt: the agent's author should be able to read

.veris/

and recognize it as "the deploy config for Veris," not as "someone forked and patched my agent."

Veris的作用是在真实场景下测试代理。代理是被测对象，Veris是围绕它的测试工具。这种不对称性决定了本技能中的所有决策：

代理在Veris中的运行方式与生产环境完全一致。如果代理在生产环境中通过HTTP调用Slack Web API，那么在模拟环境中它也会通过HTTP调用Veris的Slack模拟服务；如果它在生产环境中调用CLI命令，那么在模拟环境中也会执行相同操作。无需添加专门的模拟代码路径。
所有集成工作都在
.veris/
目录中完成。
```
.veris/veris.yaml
```
、
```
.veris/Dockerfile.sandbox
```
、
```
.veris/config.yaml
```
、
```
.veris/.dockerignore
```
是部署描述文件——相当于该代理的Helm chart或
```
docker-compose.yaml
```
。这些文件描述了如何在此环境中启动代理，不包含属于代理内部的逻辑。
不要编写用于「适配」代理与Veris的包装器、垫片或粘合代码。比如用于封装CLI代理以暴露可调用接口的Python文件、将Veris角色格式转换为代理原生格式的脚本、接受Veris特定参数的代理补丁版本——这些都是错误的做法。这意味着你最终测试的对象并非原始代理。
不要修改代理的源代码以使其在Veris中运行。如果代理依赖的某些条件Veris无法直接满足，这要么是Veris平台的缺陷需要记录，要么是代理本身存在会影响生产环境的真实问题。无论哪种情况，修复都不应在代理源码中进行。
如果发现需要编写包装器，请立即停止并将其视为问题。思考：代理在生产环境中的真实集成方式是什么？如果代理在生产环境中运行HTTP服务器，就使用该方式；如果它在生产环境中仅支持CLI，而Veris角色无法驱动CLI，则需要上报——这是Veris的能力缺口，而非编写粘合代码的理由。
.veris/
目录中唯一合法的非纯配置文件是用于编排多进程的
start.sh
（例如在代理旁部署数据库）。即便如此，该脚本也只是按原样启动和运行代理，不会改变其行为。

存疑时请遵循：代理的开发者查看

.veris/

目录时，应将其识别为「Veris的部署配置」，而非「有人分叉并修改了我的代理」。

Core rules

核心规则

Explain what you are about to do before each major step.
Surface decisions with real tradeoffs and let the user choose.
Cite concrete evidence from the repo when you classify dependencies or decide how the agent should be integrated.
Do not silently preserve stale Veris config. Migrate it to the current preferred shape.

Do not generate

.env.simulation

. The current runtime flow is

agent.environment

plus

veris env vars set

Prefer the current
```
actor.channels
```
schema and canonical service names. Do not generate legacy
```
persona.modality
```
,
```
email_address
```
, or old service aliases unless the user explicitly asks for compatibility.
Do not write Python wrappers, shell shims, or any "adapter" code that translates between Veris and the agent. Use the agent's real production interface. If that isn't possible as-is, surface it as a platform gap, not as a wrapper opportunity.
Ask before external or irreversible actions:
- installing
```
veris-cli
```
- running
```
veris login
```
- running
```
veris env create
```
- setting environment variables with
```
veris env vars set
```
- pushing with
```
veris env push
```

在执行每个主要步骤前，向用户说明你将要做的操作。
若决策存在实际权衡，需告知用户并让其选择。
对依赖进行分类或决定代理集成方式时，需引用仓库中的具体证据。
不要静默保留过时的Veris配置，需将其迁移至当前推荐的格式。
不要生成
```
.env.simulation
```
文件。当前运行时流程为
```
agent.environment
```
搭配
```
veris env vars set
```
命令。
优先使用当前的
```
actor.channels
```
schema和标准服务名称。除非用户明确要求兼容，否则不要生成旧版的
```
persona.modality
```
、
```
email_address
```
或旧服务别名。
不要编写Python包装器、Shell垫片或任何在Veris与代理之间进行转换的「适配」代码。使用代理真实的生产环境接口。如果无法直接使用该接口，需将其列为平台缺口，而非编写适配代码。
在执行外部或不可逆操作前需询问用户：
- 安装
```
veris-cli
```
- 执行
```
veris login
```
- 执行
```
veris env create
```
- 使用
```
veris env vars set
```
  设置环境变量
- 执行
```
veris env push
```

Fast-track mode

快速跟踪模式

If the user says "go all the way", "do everything", or otherwise pre-approves the full flow:

Skip intermediate checkpoints (end-of-Phase 2, end-of-Phase 3, end-of-Phase 4)
Still explain decisions inline as you make them, so the user can follow along
Still stop and ask before truly irreversible or external actions:
```
veris env create
```
,
```
veris env push
```
,
```
veris env vars set
```
with real secrets
If a decision has genuinely ambiguous tradeoffs (e.g., bundle-vs-external for a heavy service), pause and ask even in fast-track mode
At the end, present a consolidated summary of all decisions made

如果用户说「全程执行」、「完成所有操作」或预先批准完整流程：

跳过中间检查点（第2阶段末、第3阶段末、第4阶段末）
仍需在执行决策时同步说明，以便用户跟进
仍需在执行真正不可逆或外部操作前停止并询问：
```
veris env create
```
、
```
veris env push
```
、使用真实密钥执行
```
veris env vars set
```
如果决策存在真正模糊的权衡（例如重型服务是打包到容器内还是使用外部服务），即使在快速跟踪模式下也需暂停并询问用户
操作结束后，向用户呈现所有决策的汇总信息

Read these files when needed

必要时阅读以下文件

For current service names and detection: reference/service-mapping.md
For env overrides and mock credentials: reference/env-var-overrides.md
For bundleable local infra: reference/bundling-recipes.md
For container restructuring patterns: reference/infrastructure-patterns.md
For current
```
veris.yaml
```
structure: reference/veris-yaml-schema.md
For generated config examples: templates/veris-yaml.md
For Dockerfile patterns: templates/dockerfile-sandbox.md
For runtime env var handling: templates/env-vars.md
For multi-process startup scripts: templates/start-sh.md
For integration failures: phases/troubleshooting.md

服务名称与检测：reference/service-mapping.md
环境变量覆盖与模拟凭证：reference/env-var-overrides.md
可打包的本地基础设施：reference/bundling-recipes.md
容器重构模式：reference/infrastructure-patterns.md
当前
```
veris.yaml
```
结构：reference/veris-yaml-schema.md
生成配置示例：templates/veris-yaml.md
Dockerfile模式：templates/dockerfile-sandbox.md
运行时环境变量处理：templates/env-vars.md
多进程启动脚本：templates/start-sh.md
集成故障排查：phases/troubleshooting.md

Workflow Overview

工作流程概述

Phase	Goal
0	Bootstrap Veris tooling and environment
1	Discover the repo and current runtime
2	Analyze dependencies and service strategy
3	Choose integration mode and container architecture
4	Generate `.veris/veris.yaml`
5	Generate `.veris/Dockerfile.sandbox` and supporting files
6	Configure runtime env vars, validate, and push
7	Smoke-validate with a single scenario + simulation

阶段	目标
0	初始化Veris工具与环境
1	发现仓库与当前运行时信息
2	分析依赖与服务策略
3	选择集成模式与容器架构
4	生成 `.veris/veris.yaml`
5	生成 `.veris/Dockerfile.sandbox` 及支持文件
6	配置运行时环境变量、验证并推送
7	通过单个场景与模拟进行冒烟验证

Phase 0: Bootstrap Veris Tooling And Environment

阶段0：初始化Veris工具与环境

[Phase 0/7]

Tell the user: "I'm going to make sure this repo has the Veris tooling and environment wiring needed for the rest of the integration work."

[阶段0/7]

告知用户：「我将确保此仓库具备后续集成工作所需的Veris工具与环境配置。」

0.1 Verify repo root

0.1 验证仓库根目录

Confirm the directory is an agent repo, not just a parent folder. Look for source code, dependency manifests, and app entrypoints.

确认当前目录是代理仓库，而非父文件夹。检查是否存在源代码、依赖清单和应用入口文件。

0.2 Verify

veris-cli

0.2 验证

veris-cli

Check whether

veris

is installed and working.

If not installed:

Prefer
```
uv tool install veris-cli
```
Fallback:
```
pip install veris-cli
```

Explain which install path you are using and why.

检查

veris

是否已安装且可用。

若未安装：

优先使用
```
uv tool install veris-cli
```
备选方案：
```
pip install veris-cli
```

向用户说明你将使用的安装方式及原因。

0.3 Verify Veris authentication

0.3 验证Veris身份认证

Check whether the user is already logged in and which profile/backend they are using.

If not authenticated:

Recommend
```
veris login
```
for browser auth
Use API-key login only if the user explicitly prefers it

Do not proceed to

veris env push

until auth is working.

检查用户是否已登录，以及当前使用的配置文件/后端。

若未认证：

推荐使用
```
veris login
```
进行浏览器认证
仅当用户明确偏好时才使用API密钥登录

在认证完成前，不要执行

veris env push

。

0.4 Verify or create

.veris/

0.4 验证或创建

.veris/

Inspect:

```
.veris/config.yaml
```
```
.veris/veris.yaml
```
```
.veris/Dockerfile.sandbox
```
```
.veris/.dockerignore
```

.veris/

does not exist, or it exists but has no environment binding:

Derive a candidate environment name from the repo directory.
Show the user the proposed name.
On approval, run
```
veris env create --name "<name>"
```
.

Explain what

veris env create

gives them:

```
.veris/veris.yaml
```
— Veris simulation config
```
.veris/Dockerfile.sandbox
```
— image build definition
```
.veris/.dockerignore
```
— build-context exclusions
```
.veris/config.yaml
```
— environment binding for this repo

检查以下文件：

```
.veris/config.yaml
```
```
.veris/veris.yaml
```
```
.veris/Dockerfile.sandbox
```
```
.veris/.dockerignore
```

若

.veris/

目录不存在，或存在但未绑定环境：

从仓库目录名称推导候选环境名称。
向用户展示提议的名称。
获得批准后，执行
```
veris env create --name "<name>"
```
。

向用户说明

veris env create

将创建的内容：

```
.veris/veris.yaml
```
— Veris模拟配置
```
.veris/Dockerfile.sandbox
```
— 镜像构建定义
```
.veris/.dockerignore
```
— 构建上下文排除规则
```
.veris/config.yaml
```
— 此仓库的环境绑定文件

0.5 Treat scaffolding as placeholders, not truth

0.5 将脚手架文件视为占位符，而非权威内容

The generated

.veris/

files are just a starting point. They may use old defaults or generic placeholders. You are responsible for replacing them with the correct integration for this repo.

Proceed directly to Phase 1.

生成的

.veris/

文件仅作为起点，可能使用旧默认值或通用占位符。你需要负责将其替换为适用于此仓库的正确集成配置。

直接进入阶段1。

Phase 1: Discover The Repo And Current Runtime

阶段1：发现仓库与当前运行时信息

[Phase 1/7]

Tell the user: "I'm going to inventory how this repo currently runs, what it depends on, and how users interact with it."

[阶段1/7]

告知用户：「我将梳理此仓库当前的运行方式、依赖项以及用户与它的交互方式。」

1.1 Existing Veris state

1.1 现有Veris状态

.veris/

already exists, read all existing Veris files first. Call out anything that looks stale or legacy:

```
persona.modality
```
```
email_address
```
old service names like
```
crm
```
,
```
calendar
```
,
```
oracle
```
missing
```
.veris/config.yaml
```
env binding
assumptions that conflict with the current docs

若

.veris/

目录已存在，先读取所有现有Veris文件。指出任何看起来过时或属于旧版的内容：

```
persona.modality
```
```
email_address
```
旧服务名称如
```
crm
```
、
```
calendar
```
、
```
oracle
```
缺少
```
.veris/config.yaml
```
环境绑定
与当前文档冲突的假设

1.2 Infrastructure files

1.2 基础设施文件

Read and summarize any of:

docker-compose.yml

docker-compose.yaml

compose.yml

```
Dockerfile
```
,
```
Dockerfile.*
```
```
Procfile
```
```
supervisord.conf
```
,
```
supervisord.ini
```
```
vercel.json
```
,
```
serverless.yml
```
,
```
netlify.toml
```
Kubernetes manifests

Identify:

which process is the user-facing agent
what other services exist
how the system currently starts

读取并总结以下文件：

docker-compose.yml

、

docker-compose.yaml

、

compose.yml

```
Dockerfile
```
、
```
Dockerfile.*
```
```
Procfile
```
```
supervisord.conf
```
、
```
supervisord.ini
```
```
vercel.json
```
、
```
serverless.yml
```
、
```
netlify.toml
```
Kubernetes清单

识别：

哪个进程是面向用户的代理
存在哪些其他服务
系统当前的启动方式

1.3 Environment and secrets

1.3 环境与密钥

Read:

```
.env.example
```
,
```
.env.sample
```
,
```
.env.template
```
config/settings modules
secret or vault references

Collect every env var the agent reads, and note which are:

stable non-secrets
secrets
service endpoints
optional or debug-only

读取：

```
.env.example
```
、
```
.env.sample
```
、
```
.env.template
```
config/settings模块
密钥或Vault引用

收集代理读取的所有环境变量，并标注其类型：

稳定的非密钥变量
密钥变量
服务端点
可选或仅用于调试的变量

1.4 Dependencies

1.4 依赖项

Read the package manifests for the repo’s language/runtime and identify:

package manager
framework
Python/Node runtime assumptions
SDKs for external services

读取仓库语言/运行时的包清单，识别：

包管理器
框架
Python/Node运行时要求
外部服务的SDK

1.5 Source-code entrypoints

1.5 源代码入口

Find the actual code path that handles incoming user work:

app/server entrypoint
chat/message handler
config/settings module
request routing
any background worker or webhook listener that matters during a user conversation

找到处理用户请求的实际代码路径：

应用/服务器入口
聊天/消息处理器
config/settings模块
请求路由
用户对话期间重要的后台工作进程或Webhook监听器

1.5a Platform-hosted agents (config-only repos)

1.5a 平台托管的代理（仅配置仓库）

If the repo has no traditional application entrypoint — no

main.py

app.py

server.js

index.ts

— check whether it is a platform-hosted agent: a repo of config files that runs on an installed framework (CrewAI, LangServe, AutoGen, Dify, n8n, Flowise, or similar).

Signs:

Primary files are YAML/JSON config, prompt templates, and tool definitions
```
pyproject.toml
```
or
```
package.json
```
lists a framework as the main dependency
No substantial application logic beyond small tool/hook files
README instructions say "install [framework], then run [framework command]"

If this is the case:

The framework is the runtime — it will be installed in the Dockerfile, not built from source
The entry point is the framework's CLI or server command
See Pattern 8 in
```
reference/infrastructure-patterns.md
```
for the full restructuring approach
Watch for source-tree compile errors if you attempt
```
pip install .
```
on these repos

若仓库没有传统的应用入口——没有

main.py

、

app.py

、

server.js

、

index.ts

——检查它是否为平台托管的代理：仅包含配置文件的仓库，运行在已安装的框架上（如CrewAI、LangServe、AutoGen、Dify、n8n、Flowise等）。

特征：

主要文件为YAML/JSON配置、提示模板和工具定义
```
pyproject.toml
```
或
```
package.json
```
将某个框架列为主要依赖
除小型工具/钩子文件外，无实质性应用逻辑
README说明为「安装[框架]，然后执行[框架命令]」

如果是这种情况：

框架作为运行时——将在Dockerfile中安装，而非从源码构建
入口点为框架的CLI或服务器命令
查看
```
reference/infrastructure-patterns.md
```
中的模式8获取完整重构方法
若尝试对这些仓库执行
```
pip install .
```
，需注意源码编译错误

1.6 Determine the integration interface

1.6 确定集成接口

This is critical. Determine how the simulated actor should talk to the agent.

Look for four classes of interfaces:

HTTP

Chat endpoint
Request/response body shape
Session or conversation field
JSON or SSE response style

WebSocket

WS route
Message framing
Session handling

Email

Inbox address
Polling or webhook flow

Function

A clean Python callable the agent already exposes as part of its public API
Existing
```
handle_message
```
-style functions the agent's own documentation treats as an entry point

Do not invent a function interface by wrapping a CLI or a server. If the agent is CLI-only in production, the integration is CLI-driven — surface that and find the right Veris channel for it, or log it as a platform gap. A function channel is only correct when the repo already ships a callable as its primary or documented interface.

If both network and function modes are viable, use the repo's real product interface. That is what runs in production; that is what we test.

Tell the user exactly what you found and confirm the likely best integration path before continuing.

Proceed to Phase 2.

这一步至关重要。确定模拟角色应如何与代理交互。

查找四类接口：

HTTP

聊天端点
请求/响应体格式
会话或对话字段
JSON或SSE响应类型

WebSocket

WS路由
消息帧格式
会话处理

Email

收件箱地址
轮询或Webhook流程

Function

代理已作为公共API暴露的清晰Python可调用对象
代理自身文档将其视为入口点的现有
```
handle_message
```
类函数

不要通过封装CLI或服务器来创建函数接口。如果代理在生产环境中仅支持CLI，则集成方式为CLI驱动——需明确这一点并找到合适的Veris通道，或记录为平台缺口。只有当仓库已将可调用对象作为主要或文档化接口提供时，函数通道才是正确选择。

若网络和函数模式均可行，使用仓库真实的产品接口。这是生产环境中运行的方式，也是我们需要测试的方式。

向用户明确说明你发现的内容，并确认最合适的集成路径后再继续。

进入阶段2。

Phase 2: Analyze Dependencies And Service Strategy

阶段2：分析依赖与服务策略

[Phase 2/7]

Tell the user: "I'm now classifying each dependency into mock, bundle, external, or skip."

Read:

reference/service-mapping.md
reference/env-var-overrides.md
reference/bundling-recipes.md

For every dependency, classify it as one of:

Mock with Veris
Bundle inside the container
Use an external endpoint
Skip entirely
Needs discussion
Allow real egress — the agent must reach the real internet (e.g., web search, URL scraping, live API with no mock). Results will be nondeterministic across simulation runs.

[阶段2/7]

告知用户：「我将把每个依赖项分类为模拟、打包、外部或跳过。」

阅读：

reference/service-mapping.md
reference/env-var-overrides.md
reference/bundling-recipes.md

将每个依赖项分类为以下类型之一：

使用Veris模拟
打包到容器内部
使用外部端点
完全跳过
需讨论
允许真实网络出口——代理必须连接真实互联网（如网页搜索、URL抓取、无模拟的实时API）。模拟运行的结果将具有不确定性。

Classification rules

分类规则

Always read the source code before deciding. Do not infer importance from service names alone.
Show evidence when you decide something is skippable.
Surface bundle cost when it matters, especially for heavy services like Elasticsearch or LocalStack.
Prefer mock services when the dependency maps cleanly to Veris.
Prefer env-var overrides over code changes whenever possible.

决策前务必阅读源代码，不要仅通过服务名称推断重要性。
决定跳过某项依赖时，需提供证据。
若打包成本较高（如Elasticsearch或LocalStack等重型服务），需告知用户。
若依赖可清晰映射到Veris，优先使用模拟服务。
优先使用环境变量覆盖而非代码变更。

Special cases

特殊情况

Postgres

Decide whether to use Veris
```
postgres
```
or an external DB
If using Veris
```
postgres
```
, find the schema artifact or migration source and determine the best copy path

LLM providers

No Veris service entry is needed
The LLM proxy intercepts supported domains automatically

Email

If the actor uses an email channel, note that the Veris email service is injected automatically

Auth helpers

Google/Microsoft/Atlassian/Intuit auth helpers are platform-level helpers, not services you should normally add manually

Web search and scraping

If the agent calls search APIs (Google, Bing, SerpAPI, Tavily, Brave Search, DuckDuckGo) or fetches live URLs, these cannot be mocked
Classify as "Allow real egress"
Warn the user: live internet calls make simulation results nondeterministic — the same scenario may produce different outputs on different runs
If the search is truly optional (e.g., a fallback when the knowledge base has no answer), consider disabling it via env var for deterministic simulations

Real internet egress (general)

Some agents need to hit arbitrary external endpoints that Veris cannot mock (webhooks to third-party services, real-time data feeds, public REST APIs without a Veris service)
These also classify as "Allow real egress"
The Veris container allows outbound internet by default for non-intercepted domains
Surface the nondeterminism tradeoff to the user

Postgres

决定使用Veris的
```
postgres
```
服务还是外部数据库
若使用Veris的
```
postgres
```
，找到架构文件或迁移源并确定最佳复制方式

LLM提供商

无需添加Veris服务条目
LLM代理会自动拦截支持的域名

Email

若角色使用Email通道，需注意Veris Email服务将自动注入

认证助手

Google/Microsoft/Atlassian/Intuit认证助手是平台级助手，通常无需手动添加

网页搜索与抓取

若代理调用搜索API（Google、Bing、SerpAPI、Tavily、Brave Search、DuckDuckGo）或抓取实时URL，这些无法被模拟
分类为「允许真实网络出口」
警告用户：真实互联网调用会导致模拟结果不确定——相同场景在不同运行中可能产生不同输出
若搜索是真正可选的（如知识库无答案时的 fallback），可考虑通过环境变量禁用搜索以获得确定性模拟

通用真实网络出口

某些代理需要访问Veris无法模拟的任意外部端点（如第三方服务的Webhook、实时数据源、无Veris服务的公共REST API）
这些也分类为「允许真实网络出口」
Veris容器默认允许未被拦截的域名访问外部互联网
需向用户说明不确定性的权衡

Checkpoint

检查点

Walk through your dependency analysis with the user before moving on. The user should understand:

what will be mocked
what will be bundled
what stays external
what gets skipped
what still needs a decision

Wait for approval before proceeding.

在进入下一阶段前，向用户说明你的依赖分析结果。用户应了解：

哪些依赖将被模拟
哪些依赖将被打包
哪些依赖保留为外部服务
哪些依赖将被跳过
哪些依赖仍需决策

获得用户批准后再继续。

Phase 3: Choose Integration Mode And Container Architecture

阶段3：选择集成模式与容器架构

[Phase 3/7]

Tell the user: "I'm locking down how this agent will run inside the Veris container and how the actor will talk to it."

Read reference/infrastructure-patterns.md.

[阶段3/7]

告知用户：「我将确定此代理在Veris容器中的运行方式，以及角色与它的交互方式。」

阅读reference/infrastructure-patterns.md。

3.1 Choose the channel strategy

3.1 选择通道策略

Pick one of:

HTTP — preferred when the product is already an HTTP chat API
WebSocket — preferred when real-time stateful messaging is core
Email — preferred when the product is genuinely email-driven
Function — preferred when the repo has a clean callable path or should be treated as a one-shot request/response agent

选择以下之一：

HTTP——当产品已为HTTP聊天API时优先使用
WebSocket——当实时有状态消息传递为核心功能时优先使用
Email——当产品确实基于Email驱动时优先使用
Function——当仓库有清晰的可调用路径，或应被视为一次性请求/响应代理时优先使用

3.2 Function-channel rules

3.2 函数通道规则

If you choose a function channel:

The callable path must be something the agent repo already exposes as a public interface (documented, referenced in its README, or otherwise part of its contract)
Do not create a wrapper file to conjure a callable out of a CLI or server — if the repo doesn't already expose one, function is the wrong channel
Omit
```
agent.entry_point
```
and
```
agent.port
```
in
```
veris.yaml
```
If the callable is one-shot and stateless, set
```
actor.config.MAX_TURNS: 1
```

若选择函数通道：

可调用路径必须是代理仓库已作为公共接口暴露的内容（已文档化、在README中提及或属于其契约的一部分）
不要创建包装文件来从CLI或服务器生成可调用对象——如果仓库未暴露可调用对象，函数通道并非正确选择
在
```
veris.yaml
```
中省略
```
agent.entry_point
```
和
```
agent.port
```
若可调用对象为一次性无状态类型，设置
```
actor.config.MAX_TURNS: 1
```

3.3 Network-channel rules

3.3 网络通道规则

If you choose HTTP / WS / email:

determine the exact request and response mappings
determine the startup command
choose a non-reserved port
decide whether
```
start.sh
```
is needed for bundled infra or multiple processes

若选择HTTP / WS / Email：

确定确切的请求与响应映射
确定启动命令
选择非保留端口
决定是否需要
```
start.sh
```
来打包基础设施或多进程

3.4 Container layout

3.4 容器布局

Determine:

what gets copied into
```
/agent
```
which files should stay out of the image
whether a
```
start.sh
```
is required to bundle multiple processes (this is container orchestration, not agent modification)

Do not plan "which code changes are necessary." The target is zero code changes to the agent. If an env-var override isn't enough and the agent genuinely can't run as-shipped, that's a finding — escalate it rather than patching the source.

确定：

哪些内容将被复制到
```
/agent
```
目录
哪些文件不应包含在镜像中
是否需要
```
start.sh
```
来编排多进程（这属于容器编排，而非代理修改）

不要规划「需要修改哪些代码」。目标是对代理零代码变更。如果环境变量覆盖不足以解决问题，且代理确实无法按原样运行，这是一个需要上报的问题——而非修改源码的理由。

Checkpoint

检查点

Explain:

how the actor will communicate with the agent (using the agent's real production interface)
how the agent will start inside the container (its real production start command)
what files will be copied

If you believe any agent-side code change is needed, flag it here and stop. The default answer is zero code changes. If you can't see a way forward without one, it's probably a Veris platform gap, not an integration step.

Wait for approval before proceeding.

向用户说明：

角色将如何与代理通信（使用代理真实的生产环境接口）
代理将如何在容器内启动（其真实的生产环境启动命令）
将复制哪些文件

如果你认为任何代理端代码变更都是必要的，请在此处标记并停止。默认原则是零代码变更。如果找不到无需代码变更的解决方案，这很可能是Veris平台的缺口，而非集成步骤。

获得用户批准后再继续。

Phase 4: Generate

.veris/veris.yaml

阶段4：生成

.veris/veris.yaml

[Phase 4/7]

Tell the user: "I'm generating the final Veris configuration in the current preferred schema."

Read:

reference/veris-yaml-schema.md
templates/veris-yaml.md

[阶段4/7]

告知用户：「我将按照当前推荐的schema生成最终的Veris配置。」

阅读：

reference/veris-yaml-schema.md
templates/veris-yaml.md

Rules

规则

Use
```
actor.channels
```
, not
```
persona.modality
```
Use canonical service names from
```
reference/service-mapping.md
```
Use
```
agent_inbox
```
, not
```
email_address
```
Only set
```
actor.config.MAX_TURNS
```
when there is a concrete reason, usually a one-shot function integration
Do not add the
```
*_INTERVAL
```
knobs unless the user explicitly asks for advanced tuning
Keep secrets out of
```
veris.yaml
```
Put stable non-secret defaults in
```
agent.environment
```
Only use
```
${VAR}
```
in
```
agent.environment
```
when you need expansion/composition; if the agent can read a runtime env var directly, prefer setting it with
```
veris env vars set
```

使用
```
actor.channels
```
，而非
```
persona.modality
```
使用
```
reference/service-mapping.md
```
中的标准服务名称
使用
```
agent_inbox
```
，而非
```
email_address
```
仅在有具体理由时设置
```
actor.config.MAX_TURNS
```
，通常用于一次性函数集成
除非用户明确要求高级调优，否则不要添加
```
*_INTERVAL
```
配置项
不要在
```
veris.yaml
```
中包含密钥
将稳定的非密钥默认值放入
```
agent.environment
```
仅当需要扩展/组合时才在
```
agent.environment
```
中使用
```
${VAR}
```
；如果代理可直接读取运行时环境变量，优先使用
```
veris env vars set
```
设置

Channel-specific rules

通道特定规则

HTTP / WS / Email

include
```
agent.code_path
```
include
```
agent.entry_point
```
include
```
agent.port
```

Function

include
```
agent.code_path
```
omit
```
agent.entry_point
```
omit
```
agent.port
```
set
```
actor.channels[0].type: function
```
set
```
callable: ...
```

HTTP / WS / Email

包含
```
agent.code_path
```
包含
```
agent.entry_point
```
包含
```
agent.port
```

Function

包含
```
agent.code_path
```
省略
```
agent.entry_point
```
省略
```
agent.port
```
设置
```
actor.channels[0].type: function
```
设置
```
callable: ...
```

Checkpoint

检查点

Show the complete

veris.yaml

, explain the sections, and get approval before writing or finalizing it.

展示完整的

veris.yaml

，说明各部分内容，获得用户批准后再写入或定稿。

Phase 5: Generate

.veris/Dockerfile.sandbox

And Supporting Files

阶段5：生成

.veris/Dockerfile.sandbox

及支持文件

[Phase 5/7]

Tell the user: "I'm generating the image build and any small support files needed for this integration."

Read:

templates/dockerfile-sandbox.md
templates/start-sh.md

[阶段5/7]

告知用户：「我将生成镜像构建文件及此集成所需的小型支持文件。」

阅读：

templates/dockerfile-sandbox.md
templates/start-sh.md

5.1 Dockerfile rules

5.1 Dockerfile规则

Start with:

dockerfile

ARG GVISOR_BASE
FROM ${GVISOR_BASE}

Build context is the repo root
Copy dependency manifests before source code
Copy only what the agent actually needs
End with
```
WORKDIR /app
```
Do not bake
```
veris.yaml
```
into the image

以以下内容开头：

dockerfile

ARG GVISOR_BASE
FROM ${GVISOR_BASE}

构建上下文为仓库根目录
先复制依赖清单，再复制源代码
仅复制代理实际需要的内容
以
```
WORKDIR /app
```
结尾
不要将
```
veris.yaml
```
打包到镜像中

5.2 Runtime notes

5.2 运行时说明

The current base image already includes Python,
```
uv
```
, and Node.js
Only install extra runtimes or system packages when the repo truly needs them
If using a function channel, you still package the agent code and dependencies normally; you just do not start a network server

当前基础镜像已包含Python、
```
uv
```
和Node.js
仅当仓库确实需要时才安装额外的运行时或系统包
若使用函数通道，仍需正常打包代理代码与依赖；只是无需启动网络服务器

5.3 Supporting files

5.3 支持文件

Create only what is needed:

```
start.sh
```
for bundling multiple processes (e.g., a database alongside the agent) — this is container orchestration, same as a
```
docker-compose.yaml
```
would be
```
.veris/.dockerignore
```
updates if the repo has large directories the default ignore file misses

Do not create Python "wrapper modules" that expose the agent as a callable, translate Veris actor calls into the agent's native format, or otherwise insert themselves between the actor and the agent. Use the agent's real interface.

仅创建必要的文件：

```
start.sh
```
用于编排多进程（如代理旁部署数据库）——这属于容器编排，与
```
docker-compose.yaml
```
的作用相同
若仓库存在默认忽略文件未覆盖的大型目录，更新
```
.veris/.dockerignore
```

不要创建Python「包装模块」来将代理暴露为可调用对象、转换Veris角色调用为代理原生格式，或在角色与代理之间插入任何中间层。使用代理真实的接口。

5.4 No code changes to the agent

5.4 不修改代理代码

The agent runs in Veris exactly as it runs in production. That means:

No source-code patches to accommodate simulation
No "simulation mode" flags or Veris-specific branches
No forked copies of the agent with local modifications

If you find yourself wanting to change the agent's source, stop. Either:

The change can be expressed as an env-var override (then do it that way, via
```
agent.environment
```
or
```
veris env vars set
```
), or
The change is a real issue in the agent (then it's the customer's responsibility to fix, and it would also affect production), or
Veris can't accommodate the agent as-shipped (then it's a platform gap — escalate)

Unrelated refactors are obviously out.

Proceed directly to Phase 6 once the files are in place.

代理在Veris中的运行方式与生产环境完全一致。这意味着：

无需为适配模拟而修改源代码
无需添加「模拟模式」标志或Veris特定分支
无需修改代理代码并创建分叉版本

如果你发现想要修改代理源码，请立即停止。此时要么：

变更可通过环境变量覆盖实现（则通过
```
agent.environment
```
或
```
veris env vars set
```
执行），要么
变更是代理本身的真实问题（则由客户负责修复，且该问题也会影响生产环境），要么
Veris无法按原样适配代理（则属于平台缺口——需上报）

无关的重构显然不在考虑范围内。

文件准备完成后直接进入阶段6。

Phase 6: Configure Runtime Env Vars, Validate, And Push

阶段6：配置运行时环境变量、验证并推送

[Phase 6/7]

Tell the user: "I'm turning this into a pushable Veris environment."

Read:

templates/env-vars.md
phases/troubleshooting.md

[阶段6/7]

告知用户：「我将把此配置转换为可推送至Veris的环境。」

阅读：

templates/env-vars.md
phases/troubleshooting.md

6.1 Build the env-var plan

6.1 制定环境变量方案

Classify env vars into:

Stable non-secret defaults → put in
```
agent.environment
```
Secrets / per-environment values → set with
```
veris env vars set
```
Local-only convenience values → optional root
```
.env
```
or shell exports for local smoke tests

Do not create

.env.simulation

将环境变量分类为：

稳定的非密钥默认值 → 放入
```
agent.environment
```
密钥 / 每个环境的专属值 → 使用
```
veris env vars set
```
设置
仅本地使用的便捷值 → 可选的根目录
```
.env
```
或Shell导出，用于本地冒烟测试

不要创建

.env.simulation

文件。

6.2 Produce exact commands

6.2 生成精确命令

Generate the exact

veris env vars set

commands the user needs.

If the user provides actual values and wants you to do it, run the commands for them.

Shell interpolation pitfall: when running

veris env vars set KEY="$VAR" --secret

with a shell variable, verify the source variable is actually set first (

printenv VAR

test -n "$VAR"

). An empty or unset variable expands to

""

silently — the CLI will happily save an empty secret with no error, and the agent will fail at runtime with a confusing auth/provider error instead of a clear "missing key" message.

生成用户所需的精确

veris env vars set

命令。

如果用户提供实际值并希望你执行，可代为运行命令。

Shell插值陷阱：当使用Shell变量执行

veris env vars set KEY="$VAR" --secret

时，需先验证源变量已设置（

printenv VAR

或

test -n "$VAR"

）。空值或未设置的变量会被静默展开为

""

——CLI会无错误地保存空密钥，而代理在运行时会因混淆的认证/提供商错误失败，而非明确的「密钥缺失」错误。

6.3 Validate push preconditions

6.3 验证推送前置条件

Before pushing, verify:

```
veris
```
is installed
auth/profile works
```
.veris/config.yaml
```
has an environment ID
```
.veris/veris.yaml
```
exists
```
.veris/Dockerfile.sandbox
```
exists

Optional but encouraged:

run a local
```
docker build -f .veris/Dockerfile.sandbox .
```
smoke test when that is likely to catch obvious breakage quickly

推送前需验证：

```
veris
```
已安装
认证/配置文件可用
```
.veris/config.yaml
```
包含环境ID
```
.veris/veris.yaml
```
存在
```
.veris/Dockerfile.sandbox
```
存在

可选但推荐：

运行本地
```
docker build -f .veris/Dockerfile.sandbox .
```
冒烟测试，以便快速发现明显的问题

6.4 Push

6.4 推送

If the user approves, run:

bash

veris env push

Or with an explicit tag if the user wants one:

bash

veris env push --tag <tag>

If the push fails:

diagnose the failing build step
fix the integration
retry

若用户批准，执行：

bash

veris env push

或如果用户需要，使用显式标签：

bash

veris env push --tag <tag>

若推送失败：

诊断失败的构建步骤
修复集成问题
重试

6.5 Final summary

6.5 最终总结

Summarize:

files created or modified
integration mode chosen
services mocked, bundled, external, or skipped
env vars set vs left for the user
whether
```
veris env push
```
succeeded and which tag was created

Then suggest the next commands:

```
veris scenarios create
```
```
veris simulations create
```

总结：

创建或修改的文件
选择的集成模式
被模拟、打包、保留为外部或跳过的服务
已设置的环境变量及需用户自行设置的变量
```
veris env push
```
是否成功及创建的标签

然后建议后续命令：

```
veris scenarios create
```
```
veris simulations create
```

Phase 7: Smoke Validation

阶段7：冒烟验证

[Phase 7/7]

Tell the user: "I'm going to run a single scenario and simulation to verify the integration works end-to-end."

[阶段7/7]

告知用户：「我将运行单个场景与模拟，以验证集成端到端可用。」

7.1 Create a smoke scenario

7.1 创建冒烟场景

bash

veris scenarios create --num 1

The goal is a single short interaction that exercises the agent's primary interface.

bash

veris scenarios create --num 1

目标是通过一次简短交互测试代理的主要接口。

7.2 Run a single simulation

7.2 运行单个模拟

bash

veris simulations create --scenario-set-id <id>

Wait for it to complete.

bash

veris simulations create --scenario-set-id <id>

等待模拟完成。

7.3 Check the results

7.3 检查结果

Review the simulation for:

Agent responded with real content — not an error page, empty body, or exception traceback
Mock services were called — if the agent should call Slack, Salesforce, etc., confirm those calls appear
No startup crashes — the agent process stayed alive for the duration
Channel contract is correct — the actor's messages reached the agent and responses came back in the expected shape

检查模拟结果是否满足以下条件：

代理返回真实内容——不是错误页面、空响应体或异常堆栈跟踪
模拟服务被调用——如果代理应调用Slack、Salesforce等服务，确认这些调用已发生
无启动崩溃——代理进程在整个过程中保持运行
通道契约正确——角色的消息已送达代理，且响应符合预期格式

7.4 Diagnose failures

7.4 故障排查

If the smoke test fails:

Check agent container logs for startup errors or missing env vars
Verify
```
actor.channels
```
request/response mapping matches the actual API shape
Confirm mock service credentials and DNS aliases are correct
Return to the relevant phase to fix and re-push

若冒烟测试失败：

检查代理容器日志中的启动错误或缺失的环境变量
验证
```
actor.channels
```
的请求/响应映射是否与实际API格式匹配
确认模拟服务的凭证和DNS别名正确
返回相关阶段修复并重新推送

7.5 Sign off

7.5 确认完成

If the smoke test passes, summarize:

What the actor sent and what the agent responded
Which services were exercised
Confidence level that the integration is ready for full scenario generation

Then suggest full scenario generation (

veris scenarios create --num N

) and simulation as the next step.

若冒烟测试通过，总结：

角色发送的内容及代理的响应
测试了哪些服务
集成已准备好进行完整场景生成的置信度

然后建议下一步执行完整场景生成（

veris scenarios create --num N

）和模拟。

Practical guidance

实用指南

Prefer current conventions over stale scaffolding

优先使用当前约定而非过时的脚手架

veris env create

scaffolds old-looking placeholders, overwrite them with the current preferred shape from this skill.

若

veris env create

生成的脚手架看起来过时，使用本技能中当前推荐的格式覆盖它们。

Keep the skill honest about function channels

严格遵循函数通道的使用规则

Use a function channel only when the agent already exposes a callable as part of its public interface. Do not force a networked product into a function callable just because it seems simpler, and never create a wrapper file to invent a callable the agent doesn't already have.

仅当代理已将可调用对象作为公共接口暴露时才使用函数通道。不要为了简化而将网络产品强行转换为函数可调用对象，也不要创建包装文件来生成代理原本不存在的可调用对象。

Keep the skill honest about one-shot agents

明确处理一次性代理

If the integrated agent is clearly one-shot/stateless, carry that through explicitly by setting

actor.config.MAX_TURNS: 1

若集成的代理明显为一次性/无状态类型，需明确设置

actor.config.MAX_TURNS: 1

。

Be explicit about what you did not automate

明确说明未自动化的操作

If login, secrets, or env-var values still require user action, say so plainly. The goal is to get as far as possible, not to hide blockers.

若登录、密钥或环境变量值仍需用户操作，需明确告知。目标是尽可能推进流程，而非隐藏障碍。

agent-integration

Original

Translation

Core framing: the agent is the constant, Veris is the test harness

核心框架：代理为核心，Veris为测试工具

Core rules

核心规则

Fast-track mode

快速跟踪模式

Read these files when needed

必要时阅读以下文件

Workflow Overview

工作流程概述

Phase 0: Bootstrap Veris Tooling And Environment

阶段0：初始化Veris工具与环境

0.1 Verify repo root

0.1 验证仓库根目录

0.2 Verify veris-cli

0.2 验证veris-cli

0.3 Verify Veris authentication

0.3 验证Veris身份认证

0.4 Verify or create .veris/

0.4 验证或创建.veris/目录

0.5 Treat scaffolding as placeholders, not truth

0.5 将脚手架文件视为占位符，而非权威内容

Phase 1: Discover The Repo And Current Runtime

阶段1：发现仓库与当前运行时信息

1.1 Existing Veris state

1.1 现有Veris状态

1.2 Infrastructure files

1.2 基础设施文件

1.3 Environment and secrets

1.3 环境与密钥

1.4 Dependencies

1.4 依赖项

1.5 Source-code entrypoints

1.5 源代码入口

1.5a Platform-hosted agents (config-only repos)

1.5a 平台托管的代理（仅配置仓库）

1.6 Determine the integration interface

1.6 确定集成接口

Phase 2: Analyze Dependencies And Service Strategy

阶段2：分析依赖与服务策略

Classification rules

分类规则

Special cases

特殊情况

Checkpoint

检查点

Phase 3: Choose Integration Mode And Container Architecture

阶段3：选择集成模式与容器架构

3.1 Choose the channel strategy

3.1 选择通道策略

3.2 Function-channel rules

3.2 函数通道规则

3.3 Network-channel rules

3.3 网络通道规则

3.4 Container layout

3.4 容器布局

Checkpoint

检查点

Phase 4: Generate .veris/veris.yaml

阶段4：生成.veris/veris.yaml

Rules

规则

Channel-specific rules

通道特定规则

Checkpoint

检查点

Phase 5: Generate .veris/Dockerfile.sandbox And Supporting Files

阶段5：生成.veris/Dockerfile.sandbox及支持文件

5.1 Dockerfile rules

5.1 Dockerfile规则

5.2 Runtime notes

5.2 运行时说明

5.3 Supporting files

5.3 支持文件

5.4 No code changes to the agent

5.4 不修改代理代码

Phase 6: Configure Runtime Env Vars, Validate, And Push

0.2 Verify
`veris-cli`

0.2 验证
`veris-cli`

0.4 Verify or create
`.veris/`

0.4 验证或创建
`.veris/`
目录

Phase 4: Generate
`.veris/veris.yaml`

阶段4：生成
`.veris/veris.yaml`

Phase 5: Generate
`.veris/Dockerfile.sandbox`
And Supporting Files

阶段5：生成
`.veris/Dockerfile.sandbox`
及支持文件