eve-manifest-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eve Manifest Authoring

Eve 清单编写

Keep the manifest as the single source of truth for build and deploy behavior.

将清单作为构建和部署行为的唯一可信来源。

Minimal skeleton (v2)

最小化骨架（v2版本）

yaml

schema: eve/compose/v1
project: my-project

registry:
  host: ghcr.io
  namespace: myorg
  auth:
    username_secret: GHCR_USERNAME
    token_secret: GHCR_TOKEN

yaml

schema: eve/compose/v1
project: my-project

registry:
  host: ghcr.io
  namespace: myorg
  auth:
    username_secret: GHCR_USERNAME
    token_secret: GHCR_TOKEN

OCI Image Labels (GHCR Auto-Linking)

OCI 镜像标签（GHCR自动关联）

GHCR requires packages to be linked to a repository for proper permission inheritance. Add these labels to your Dockerfiles to enable automatic linking:

dockerfile

LABEL org.opencontainers.image.source="https://github.com/YOUR_ORG/YOUR_REPO"
LABEL org.opencontainers.image.description="Service description"

Why this matters: Without this label, GHCR creates "orphaned" packages that only org admins can push to. The Eve builder injects this label automatically at build time, but including it in your Dockerfile is recommended as defense-in-depth.

For multi-stage Dockerfiles, add the labels to the final stage (the production image).

services: api: build: context: ./apps/api # Build context directory dockerfile: Dockerfile # Optional, defaults to context/Dockerfile image: ghcr.io/myorg/my-api # Target image (no tag needed - managed by Eve) ports: [3000] environment: NODE_ENV: production x-eve: ingress: public: true port: 3000

environments: staging: pipeline: deploy pipeline_inputs: some_key: default_value

pipelines: deploy: steps: - name: build action: type: build # Builds all services with build: config - name: release depends_on: [build] action: type: release - name: deploy depends_on: [release] action: type: deploy

undefined

GHCR要求将包关联到代码仓库，以实现正确的权限继承。在Dockerfile中添加以下标签即可启用自动关联：

dockerfile

LABEL org.opencontainers.image.source="https://github.com/YOUR_ORG/YOUR_REPO"
LABEL org.opencontainers.image.description="Service description"

重要性说明：如果没有此标签，GHCR会创建“孤立”的包，只有组织管理员才能推送。Eve构建器会在构建时自动注入此标签，但推荐在Dockerfile中显式添加，作为纵深防御的措施。

对于多阶段Dockerfile，请将标签添加到最终阶段（即生产镜像阶段）。

services: api: build: context: ./apps/api # 构建上下文目录 dockerfile: Dockerfile # 可选参数，默认值为context/Dockerfile image: ghcr.io/myorg/my-api # 目标镜像（无需指定标签 - 由Eve管理） ports: [3000] environment: NODE_ENV: production x-eve: ingress: public: true port: 3000

environments: staging: pipeline: deploy pipeline_inputs: some_key: default_value

pipelines: deploy: steps: - name: build action: type: build # 构建所有包含build配置的服务 - name: release depends_on: [build] action: type: release - name: deploy depends_on: [release] action: type: deploy

undefined

Legacy manifests

旧版清单

If the repo still uses

components:

from older manifests, migrate to

services:

and add

schema: eve/compose/v1

. Keep ports and env keys the same.

如果代码仓库仍在使用旧版清单中的

components:

字段，请迁移为

services:

并添加

schema: eve/compose/v1

。端口和环境变量键保持不变。

Services

服务配置

Provide
```
image
```
and optionally
```
build
```
(context and dockerfile).
Use
```
ports
```
,
```
environment
```
,
```
healthcheck
```
,
```
depends_on
```
as needed.

Use

x-eve.external: true

and

x-eve.connection_url

for externally hosted services.

Use
```
x-eve.role: job
```
for one-off services (migrations, seeds).

需提供
```
image
```
，可选提供
```
build
```
（包含context和dockerfile）。
根据需要使用
```
ports
```
、
```
environment
```
、
```
healthcheck
```
、
```
depends_on
```
字段。
对于外部托管的服务，使用
```
x-eve.external: true
```
和
```
x-eve.connection_url
```
。
对于一次性服务（如迁移、数据初始化），使用
```
x-eve.role: job
```
。

Build configuration

构建配置

Services with Docker images should define their build configuration:

yaml

services:
  api:
    build:
      context: ./apps/api           # Build context directory
      dockerfile: Dockerfile        # Optional, defaults to context/Dockerfile
    image: ghcr.io/org/my-api       # Target image (no tag needed - managed by Eve)
    ports: [3000]

Note: Every deploy pipeline should include a

build

step before

release

. The build step creates tracked BuildSpec/BuildRun records and produces image digests that releases use for deterministic deployments.

带有Docker镜像的服务应定义其构建配置：

yaml

services:
  api:
    build:
      context: ./apps/api           # 构建上下文目录
      dockerfile: Dockerfile        # 可选参数，默认值为context/Dockerfile
    image: ghcr.io/org/my-api       # 目标镜像（无需指定标签 - 由Eve管理）
    ports: [3000]

注意：每个部署流水线应在

release

步骤之前包含

build

步骤。build步骤会创建可追踪的BuildSpec/BuildRun记录，并生成镜像摘要，供release步骤用于确定性部署。

Local dev alignment

本地开发对齐

Keep service names and ports aligned with Docker Compose.
Prefer
```
${secret.KEY}
```
and use
```
.eve/secrets.yaml
```
for local values.

保持服务名称和端口与Docker Compose一致。
优先使用
```
${secret.KEY}
```
，并通过
```
.eve/secrets.yaml
```
设置本地值。

Environments, pipelines, workflows

环境、流水线与工作流

Link each environment to a pipeline via
```
environments.<env>.pipeline
```
.
When
```
pipeline
```
is set,
```
eve env deploy <env>
```
triggers that pipeline instead of direct deploy.
Use
```
environments.<env>.pipeline_inputs
```
to provide default inputs for pipeline runs.

Override inputs at runtime with

eve env deploy <env> --ref <sha> --inputs '{"key":"value"}' --repo-dir ./my-app

Use

--direct

flag to bypass pipeline and do direct deploy:

eve env deploy <env> --ref <sha> --direct --repo-dir ./my-app

Pipeline steps can be
```
action
```
,
```
script
```
, or
```
agent
```
.
Use
```
action.type: create-pr
```
for PR automation when configured.
Workflows live under
```
workflows
```
and are invoked via CLI;
```
db_access
```
is honored.

通过
```
environments.<env>.pipeline
```
将每个环境关联到一条流水线。
当设置
```
pipeline
```
后，执行
```
eve env deploy <env>
```
会触发该流水线，而非直接部署。
使用
```
environments.<env>.pipeline_inputs
```
为流水线运行提供默认输入参数。

在运行时可通过以下命令覆盖输入参数：

eve env deploy <env> --ref <sha> --inputs '{"key":"value"}' --repo-dir ./my-app

。

使用

--direct

标志绕过流水线直接部署：

eve env deploy <env> --ref <sha> --direct --repo-dir ./my-app

。

流水线步骤类型可以是
```
action
```
、
```
script
```
或
```
agent
```
。
配置完成后，使用
```
action.type: create-pr
```
实现PR自动化。
工作流定义在
```
workflows
```
字段下，可通过CLI调用；
```
db_access
```
权限会被尊重。

Interpolation and secrets

插值与密钥管理

Env interpolation:

${ENV_NAME}

${PROJECT_ID}

${ORG_ID}

${ORG_SLUG}

${COMPONENT_NAME}

Secret interpolation:
```
${secret.KEY}
```
pulls from Eve secrets or
```
.eve/secrets.yaml
```
.
Use
```
.eve/secrets.yaml
```
for local overrides; set real secrets via the API for production.

环境变量插值：

${ENV_NAME}

、

${PROJECT_ID}

、

${ORG_ID}

、

${ORG_SLUG}

、

${COMPONENT_NAME}

。

密钥插值：
```
${secret.KEY}
```
会从Eve密钥或
```
.eve/secrets.yaml
```
中取值。
使用
```
.eve/secrets.yaml
```
进行本地覆盖；生产环境的真实密钥通过API设置。

Eve extensions

Eve 扩展配置

Top-level defaults via
```
x-eve.defaults
```
(env, harness, harness_profile, harness_options, hints, git, workspace).
Top-level agent policy via
```
x-eve.agents
```
(profiles, councils, availability rules).

Agent config paths via

x-eve.agents.config_path

and

x-eve.agents.teams_path

Chat routing config via
```
x-eve.chat.config_path
```
.
Service extensions under
```
x-eve
```
(ingress, role, api specs, worker pools).
API specs:
```
x-eve.api_spec
```
or
```
x-eve.api_specs
```
(spec URL relative to service by default).

Example:

yaml

x-eve:
  agents:
    version: 1
    config_path: agents/agents.yaml
    teams_path: agents/teams.yaml
  chat:
    config_path: agents/chat.yaml

通过
```
x-eve.defaults
```
设置顶层默认值（包括env、harness、harness_profile、harness_options、hints、git、workspace）。
通过
```
x-eve.agents
```
设置顶层代理策略（包括profiles、councils、availability rules）。

通过

x-eve.agents.config_path

和

x-eve.agents.teams_path

指定代理配置路径。

通过
```
x-eve.chat.config_path
```
指定聊天路由配置路径。
服务级扩展配置在
```
x-eve
```
字段下（包括ingress、role、api specs、worker pools）。
API规格：
```
x-eve.api_spec
```
或
```
x-eve.api_specs
```
（默认情况下，规格URL相对于服务路径）。

示例：

yaml

x-eve:
  agents:
    version: 1
    config_path: agents/agents.yaml
    teams_path: agents/teams.yaml
  chat:
    config_path: agents/chat.yaml

Recursive skill distillation

技能迭代优化

Add new manifest patterns and pitfalls as they emerge.
Split deep details into a
```
references/
```
file if this skill grows.
Update the eve-skillpacks README and ARCHITECTURE listings after changes.

随着新的清单模式和问题出现，及时添加相关内容。
如果此技能内容增多，可将深层细节拆分到
```
references/
```
目录下的文件中。
修改后更新eve-skillpacks的README和ARCHITECTURE列表。