eve-manifest-authoring by incept5/eve-skillpacks
npx skills add https://github.com/incept5/eve-skillpacks --skill eve-manifest-authoring将清单作为构建和部署行为的单一事实来源。
schema: eve/compose/v2
project: my-project
registry: "eve" # 默认情况下,Eve 应用使用托管注册表
services:
api:
build:
context: ./apps/api # 构建上下文目录
dockerfile: Dockerfile # 可选,默认为 context/Dockerfile
# 默认省略 image;当存在 build 配置时,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
某些注册表需要包元数据以继承权限和所有权。当您的注册表支持时,请将这些标签添加到您的 Dockerfile 中:
LABEL org.opencontainers.image.source="https://github.com/YOUR_ORG/YOUR_REPO"
LABEL org.opencontainers.image.description="服务描述"
为何重要:元数据有助于保留仓库所有权并提高可追溯性。Eve 构建器会自动注入这些标签,但仍建议在您的 Dockerfile 中包含它们。
对于多阶段 Dockerfile,请将标签添加到阶段(生产镜像)。
Keep the manifest as the single source of truth for build and deploy behavior.
schema: eve/compose/v2
project: my-project
registry: "eve" # Use managed registry by default for Eve apps
services:
api:
build:
context: ./apps/api # Build context directory
dockerfile: Dockerfile # Optional, defaults to context/Dockerfile
# image omitted by default; when build is present, Eve derives image name from service key
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
Some registries require package metadata for permission and ownership inheritance. Add these labels to your Dockerfiles when supported by your registry:
LABEL org.opencontainers.image.source="https://github.com/YOUR_ORG/YOUR_REPO"
LABEL org.opencontainers.image.description="Service description"
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
registry: "eve" # Eve 原生注册表(内部 JWT 认证)
registry: "none" # 禁用注册表处理(公共镜像)
registry: # 自带注册表(完整对象 — 见下文)
host: public.ecr.aws/w7c4v0w3
namespace: myorg
auth: { username_secret: REGISTRY_USERNAME, token_secret: REGISTRY_PASSWORD }
对于自带/私有注册表,请提供:
registry:
host: public.ecr.aws/w7c4v0w3
namespace: myorg
auth:
username_secret: REGISTRY_USERNAME
token_secret: REGISTRY_PASSWORD
使用 x-eve.role: managed_db 声明平台提供的数据库:
services:
db:
x-eve:
role: managed_db
managed:
class: db.p1
engine: postgres
engine_version: "16"
不会部署到 K8s — 由编排器在首次部署时提供。在其他地方引用托管值:${managed.db.url}。
使用平台的迁移运行器,而不是 Flyway、TypeORM 或 Knex。它使用带时间戳前缀的纯 SQL 文件,并在 schema_migrations 中跟踪:
services:
migrate:
image: public.ecr.aws/w7c4v0w3/eve-horizon/migrate:latest
environment:
DATABASE_URL: ${managed.db.url}
MIGRATIONS_DIR: /migrations
x-eve:
role: job
files:
- source: db/migrations
target: /migrations
迁移文件:db/migrations/20260312000000_initial_schema.sql。x-eve.files 指令将它们挂载到容器中的 /migrations。
在流水线中,迁移步骤必须在部署之后运行(托管数据库需要提供):
pipelines:
deploy:
steps:
- name: build
action: { type: build }
- name: release
depends_on: [build]
action: { type: release }
- name: deploy
depends_on: [release]
action: { type: deploy }
- name: migrate
depends_on: [deploy]
action: { type: job, service: migrate }
对于本地开发,通过 Docker Compose 使用相同的镜像以保持一致性:
# docker-compose.yml
services:
migrate:
image: ghcr.io/incept5/eve-migrate:latest
environment:
DATABASE_URL: postgres://app:app@db:5432/myapp
volumes:
- ./db/migrations:/migrations:ro
depends_on:
db: { condition: service_healthy }
如果仓库仍在使用旧版清单中的 components:,请迁移到 services: 并添加 schema: eve/compose/v2。保持端口和环境变量键不变。
image 和可选的 build(上下文和 dockerfile)。ports、environment、healthcheck、depends_on。x-eve.external: true 和 x-eve.connection_url。x-eve.role: job。对于数据库迁移,优先使用 Eve 的 eve-migrate 镜像(见下文)。具有 Docker 镜像的服务应定义其构建配置:
services:
api:
build:
context: ./apps/api # 构建上下文目录
dockerfile: Dockerfile # 可选,默认为 context/Dockerfile
# image: api # 如果使用 build,则为可选;托管注册表会派生此名称
ports: [3000]
注意:每个部署流水线都应在 release 之前包含一个 build 步骤。构建步骤会创建跟踪的 BuildSpec/BuildRun 记录,并生成发布用于确定性部署的镜像摘要。
${secret.KEY},并使用 .eve/dev-secrets.yaml 存储本地值。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 会被遵守。Eve 会自动将这些变量注入到所有已部署的服务容器中:
| 变量 | 描述 |
|---|---|
EVE_API_URL | 用于服务器到服务器调用的内部集群 URL |
EVE_PUBLIC_API_URL | 面向浏览器应用的公共入口 URL |
EVE_PROJECT_ID | 项目 ID |
EVE_ORG_ID | 组织 ID |
EVE_ENV_NAME | 环境名称 |
从您的容器进行后端调用时,请使用 EVE_API_URL。对于浏览器/客户端代码,请使用 EVE_PUBLIC_API_URL。服务可以在其 environment 部分覆盖这些变量。
${ENV_NAME}、${PROJECT_ID}、${ORG_ID}、${ORG_SLUG}、${COMPONENT_NAME}。${secret.KEY} 从 Eve 密钥或 .eve/dev-secrets.yaml 中提取。${managed.<service>.<field>} 在部署时解析。.eve/dev-secrets.yaml 进行本地覆盖;通过 API 为生产环境设置真实的密钥。x-eve.defaults 设置顶级默认值(env、harness、harness_profile、harness_options、hints、git、workspace)。x-eve.agents 设置顶级代理策略(profiles、councils、availability rules)。x-eve.packs 设置代理包,并可选择 x-eve.install_agents 默认值。x-eve.agents.config_path 和 x-eve.agents.teams_path 设置代理配置路径。x-eve.chat.config_path 设置聊天路由配置。x-eve 下(ingress、role、api specs、worker pools、cli、object_store)。x-eve.api_spec 或 x-eve.api_specs(默认情况下,规范 URL 相对于服务)。x-eve.cli 声明一个对代理友好的服务 CLI(见下文)。toolchains 声明按需注入运行时(见下文)。references/integrations.md)。eve integrations configure 注册自己的 OAuth 应用凭证(见 eve-auth-and-secrets)。示例:
x-eve:
agents:
version: 1
config_path: agents/agents.yaml
teams_path: agents/teams.yaml
chat:
config_path: agents/chat.yaml
install_agents: [claude-code, codex]
packs:
- source: ./skillpacks/my-pack
推荐给每个带有 API 的应用。 将您的服务 API 包装在 CLI 中,并在此处注册。代理强烈倾向于使用 CLI 命令而不是原始 REST — CLI 透明地处理认证、URL 构建和错误格式化。这是 Eve 的方式:编码代理应该在仓库中构建一个 CLI,并在清单中注册它,而不是让代理直接调用 API。
平台会自动发现清单中带有 x-eve.cli 或 x-eve.api_spec 的服务,并使它们在项目的所有代理作业的 $PATH 上可用 — 无需显式的 with_apis。只需在此处声明 CLI,所有代理都会获得它。
services:
api:
x-eve:
api_spec:
type: openapi
cli:
name: myapp # 二进制名称(放在 $PATH 上)
bin: cli/bin/myapp # 相对于仓库根目录的路径(预打包)
对于编译型 CLI,使用基于镜像的分发方式:
services:
api:
x-eve:
cli:
name: myapp
image: ghcr.io/org/myapp-cli:latest # 预构建镜像
api_spec 一起存储。chmod +x 并将二进制文件符号链接到 /usr/local/bin/。EVE_APP_API_URL_{SERVICE} 和 EVE_JOB_TOKEN(已注入)— 无需手动配置认证或 URL。[a-z][a-z0-9-]*eden projects list)代理声明它们需要哪些运行时工具链。平台将它们作为初始化容器注入 — 无需臃肿的工作器镜像。
# 在 agents.yaml 中
agents:
data-analyst:
name: Data Analyst
skill: analyze-data
harness_profile: claude-sonnet
toolchains: [python] # 需要 python + uv
doc-processor:
name: Document Processor
skill: process-documents
harness_profile: claude-sonnet
toolchains: [media] # 需要 ffmpeg + whisper
可用工具链:python、media、rust、java、kotlin。
工作流可以覆盖代理默认值:
workflows:
process-document:
steps:
- name: process
agent: doc-processor
toolchains: [media, python] # 覆盖:需要两者
工具链挂载在 /opt/eve/toolchains/{name}/,二进制文件位于 $PATH 上。默认工作器镜像是 base(约 800MB);工具链仅添加每个作业所需的内容。
Google Drive 文件夹可以通过云文件系统集成挂载到组织文件系统中。配置通过集成系统完成,而不是清单。
# 组织管理员注册 Google Drive OAuth 应用凭证(自带应用)
eve integrations configure google-drive \
--client-id "xxx.apps.googleusercontent.com" \
--client-secret "GOCSPX-xxx"
# 连接并挂载一个 Drive 文件夹
eve integrations connect google-drive
eve cloud-fs mount --org org_xxx \
--provider google-drive \
--folder-id <drive-folder-id> \
--label "Shared Drive"
开发人员使用 eve cloud-fs ls 浏览挂载的内容,并使用 eve cloud-fs search 进行搜索。挂载存储提供者文件夹 ID 以及一个可选的人类可读根文件夹路径提示;没有单独的 CLI --mount-path 设置。
状态:模式存在,配置逻辑待定。 数据库模式(
storage_buckets表)和存储桶命名约定已实现。从清单自动配置的功能尚未连接。
在清单中声明应用范围的对象存储桶。每个存储桶按环境提供,凭证作为环境变量注入。
services:
api:
x-eve:
object_store:
buckets:
- name: uploads
visibility: private
- name: avatars
visibility: public
cors:
allowed_origins: ["*"]
当对象存储桶被提供时,这些环境变量会被注入到服务容器中:
| 变量 | 描述 |
|---|---|
STORAGE_ENDPOINT | S3 兼容的端点 URL |
STORAGE_ACCESS_KEY | 存储桶的访问密钥 |
STORAGE_SECRET_KEY | 存储桶的密钥 |
STORAGE_BUCKET | 物理存储桶名称 |
STORAGE_FORCE_PATH_STYLE | 对于 MinIO(本地开发)为 true,对于云存储为 false |
uploads、avatars、exports 分开。visibility: public。cors.allowed_origins。有关存储层的详细文档,请参阅 eve-read-eve-docs 技能:references/object-store-filesystem.md。
每周安装数
156
仓库
首次出现
2026年2月8日
安全审计
安装于
codex156
gemini-cli156
claude-code154
pi60
opencode35
github-copilot35
Why this matters : Metadata helps preserve repository ownership and improves traceability. The Eve builder injects these labels automatically, but including them in your Dockerfile is still recommended.
For multi-stage Dockerfiles, add the labels to the final stage (the production image).
registry: "eve" # Eve-native registry (internal JWT auth)
registry: "none" # Disable registry handling (public images)
registry: # BYO registry (full object — see section below)
host: public.ecr.aws/w7c4v0w3
namespace: myorg
auth: { username_secret: REGISTRY_USERNAME, token_secret: REGISTRY_PASSWORD }
For BYO/private registries, provide:
registry:
host: public.ecr.aws/w7c4v0w3
namespace: myorg
auth:
username_secret: REGISTRY_USERNAME
token_secret: REGISTRY_PASSWORD
Declare platform-provisioned databases with x-eve.role: managed_db:
services:
db:
x-eve:
role: managed_db
managed:
class: db.p1
engine: postgres
engine_version: "16"
Not deployed to K8s — provisioned by the orchestrator on first deploy. Reference managed values elsewhere: ${managed.db.url}.
Use the platform's migration runner instead of Flyway, TypeORM, or Knex. It uses plain SQL files with timestamp prefixes, tracked in schema_migrations:
services:
migrate:
image: public.ecr.aws/w7c4v0w3/eve-horizon/migrate:latest
environment:
DATABASE_URL: ${managed.db.url}
MIGRATIONS_DIR: /migrations
x-eve:
role: job
files:
- source: db/migrations
target: /migrations
Migration files: db/migrations/20260312000000_initial_schema.sql. The x-eve.files directive mounts them into the container at /migrations.
In the pipeline, the migrate step must run after deploy (managed DB needs provisioning):
pipelines:
deploy:
steps:
- name: build
action: { type: build }
- name: release
depends_on: [build]
action: { type: release }
- name: deploy
depends_on: [release]
action: { type: deploy }
- name: migrate
depends_on: [deploy]
action: { type: job, service: migrate }
For local dev, use the same image via Docker Compose for parity:
# docker-compose.yml
services:
migrate:
image: ghcr.io/incept5/eve-migrate:latest
environment:
DATABASE_URL: postgres://app:app@db:5432/myapp
volumes:
- ./db/migrations:/migrations:ro
depends_on:
db: { condition: service_healthy }
If the repo still uses components: from older manifests, migrate to services: and add schema: eve/compose/v2. Keep ports and env keys the same.
image and optionally build (context and dockerfile).ports, environment, healthcheck, depends_on as needed.x-eve.external: true and x-eve.connection_url for externally hosted services.x-eve.role: job for one-off services (migrations, seeds). For database migrations, prefer Eve's eve-migrate image (see below).Services with Docker images should define their build configuration:
services:
api:
build:
context: ./apps/api # Build context directory
dockerfile: Dockerfile # Optional, defaults to context/Dockerfile
# image: api # optional if using build; managed registry derives this
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.
${secret.KEY} and use .eve/dev-secrets.yaml for local values.environments.<env>.pipeline.pipeline is set, eve env deploy <env> triggers that pipeline instead of direct deploy.environments.<env>.pipeline_inputs to provide default inputs for pipeline runs.eve env deploy <env> --ref <sha> --inputs '{"key":"value"}' --repo-dir ./my-app.--direct flag to bypass pipeline and do direct deploy: eve env deploy <env> --ref <sha> --direct --repo-dir ./my-app.action, script, or agent.action.type: create-pr for PR automation when configured.workflows and are invoked via CLI; db_access is honored.Eve automatically injects these into all deployed service containers:
| Variable | Description |
|---|---|
EVE_API_URL | Internal cluster URL for server-to-server calls |
EVE_PUBLIC_API_URL | Public ingress URL for browser-facing apps |
EVE_PROJECT_ID | The project ID |
EVE_ORG_ID | The organization ID |
EVE_ENV_NAME | The environment name |
Use EVE_API_URL for backend calls from your container. Use EVE_PUBLIC_API_URL for browser/client-side code. Services can override these in their environment section.
${ENV_NAME}, ${PROJECT_ID}, ${ORG_ID}, ${ORG_SLUG}, ${COMPONENT_NAME}.${secret.KEY} pulls from Eve secrets or .eve/dev-secrets.yaml.${managed.<service>.<field>} resolves at deploy time..eve/dev-secrets.yaml for local overrides; set real secrets via the API for production.x-eve.defaults (env, harness, harness_profile, harness_options, hints, git, workspace).x-eve.agents (profiles, councils, availability rules).x-eve.packs with optional x-eve.install_agents defaults.x-eve.agents.config_path and x-eve.agents.teams_path.x-eve.chat.config_path.x-eve (ingress, role, api specs, worker pools, cli, object_store).x-eve.api_spec or x-eve.api_specs (spec URL relative to service by default).x-eve.cli declares an agent-friendly CLI for the service (see below).toolchains declarations inject on-demand runtimes (see below).references/integrations.md).eve integrations configure (see eve-auth-and-secrets).Example:
x-eve:
agents:
version: 1
config_path: agents/agents.yaml
teams_path: agents/teams.yaml
chat:
config_path: agents/chat.yaml
install_agents: [claude-code, codex]
packs:
- source: ./skillpacks/my-pack
Recommended for every app with an API. Wrap your service API in a CLI and register it here. Agents strongly prefer CLI commands over raw REST — CLIs handle auth, URL construction, and error formatting transparently. This is the Eve way: coding agents should build a CLI in the repo and register it in the manifest rather than having agents call APIs directly.
The platform auto-discovers services with x-eve.cli or x-eve.api_spec from the manifest and makes them available on $PATH for all agent jobs in the project — no explicit with_apis needed. Just declare the CLI here and all agents get it.
services:
api:
x-eve:
api_spec:
type: openapi
cli:
name: myapp # Binary name (goes on $PATH)
bin: cli/bin/myapp # Path relative to repo root (pre-bundled)
For compiled CLIs, use an image-based distribution:
services:
api:
x-eve:
cli:
name: myapp
image: ghcr.io/org/myapp-cli:latest # Pre-built image
api_spec.chmod +x and symlinks the binary to /usr/local/bin/.EVE_APP_API_URL_{SERVICE} and EVE_JOB_TOKEN (already injected) -- no manual auth or URL configuration.[a-z][a-z0-9-]*eden projects list)Agents declare which runtime toolchains they need. The platform injects them as init containers -- no fat worker image required.
# In agents.yaml
agents:
data-analyst:
name: Data Analyst
skill: analyze-data
harness_profile: claude-sonnet
toolchains: [python] # Needs python + uv
doc-processor:
name: Document Processor
skill: process-documents
harness_profile: claude-sonnet
toolchains: [media] # Needs ffmpeg + whisper
Available toolchains: python, media, rust, java, kotlin.
Workflows can override agent defaults:
workflows:
process-document:
steps:
- name: process
agent: doc-processor
toolchains: [media, python] # Override: needs both
Toolchains are mounted at /opt/eve/toolchains/{name}/ with binaries on $PATH. The default worker image is base (~800MB); toolchains add only what each job needs.
Google Drive folders can be mounted into the org filesystem via cloud FS integrations. Configuration is through the integrations system, not the manifest.
# Org admin registers Google Drive OAuth app credentials (BYOA)
eve integrations configure google-drive \
--client-id "xxx.apps.googleusercontent.com" \
--client-secret "GOCSPX-xxx"
# Connect and mount a Drive folder
eve integrations connect google-drive
eve cloud-fs mount --org org_xxx \
--provider google-drive \
--folder-id <drive-folder-id> \
--label "Shared Drive"
Developers browse mounted content with eve cloud-fs ls and search it with eve cloud-fs search. The mount stores the provider folder ID plus an optional human-readable root-folder path hint; there is no separate CLI --mount-path setting.
Status: Schema exists, provisioning logic pending. The database schema (
storage_bucketstable) and bucket naming convention are implemented. Automatic provisioning from the manifest is not yet wired.
Declare app-scoped object storage buckets in the manifest. Each bucket is provisioned per environment with credentials injected as environment variables.
services:
api:
x-eve:
object_store:
buckets:
- name: uploads
visibility: private
- name: avatars
visibility: public
cors:
allowed_origins: ["*"]
When object store buckets are provisioned, these env vars are injected into the service container:
| Variable | Description |
|---|---|
STORAGE_ENDPOINT | S3-compatible endpoint URL |
STORAGE_ACCESS_KEY | Access key for the bucket |
STORAGE_SECRET_KEY | Secret key for the bucket |
STORAGE_BUCKET | Physical bucket name |
STORAGE_FORCE_PATH_STYLE | true for MinIO (local dev), false for cloud |
uploads from avatars from exports.visibility: public.cors.allowed_origins when the frontend uploads directly via presigned URLs.For detailed storage layer documentation, see the eve-read-eve-docs skill: references/object-store-filesystem.md.
Weekly Installs
156
Repository
First Seen
Feb 8, 2026
Security Audits
Installed on
codex156
gemini-cli156
claude-code154
pi60
opencode35
github-copilot35