eve-new-project-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eve New Project Setup

Eve Horizon新项目设置

Use this after a developer has run

eve init

and needs to configure the project for Eve Horizon.

开发者在运行

eve init

后，需要为Eve Horizon配置项目时可使用本指南。

Context

背景信息

The user has already run:

bash

npm install -g @eve-horizon/cli
eve init my-project
cd my-project

This skill handles the remaining setup: profile, authentication, org/project registration, manifest customization, and git remote configuration.

用户已执行以下命令：

bash

npm install -g @eve-horizon/cli
eve init my-project
cd my-project

本指南将处理剩余的设置步骤：配置文件、认证、组织/项目注册、清单自定义以及Git远程仓库配置。

Step 1: Verify CLI

步骤1：验证CLI

bash

eve --version

If this fails, the CLI wasn't installed. Have them run:

bash

npm install -g @eve-horizon/cli

bash

eve --version

如果该命令执行失败，说明CLI未安装。请执行以下命令：

bash

npm install -g @eve-horizon/cli

Step 2: Profile Setup

步骤2：配置文件设置

Create a profile for the staging environment:

bash

eve profile create staging --api-url https://api.eh1.incept5.dev
eve profile use staging

Ask the user for their email and set defaults:

bash

eve profile set --default-email user@example.com

为预发布环境（staging）创建配置文件：

bash

eve profile create staging --api-url https://api.eh1.incept5.dev
eve profile use staging

向用户索要邮箱并设置默认值：

bash

eve profile set --default-email user@example.com

Step 3: Authentication

步骤3：认证

Check current auth status:

bash

eve auth status

If not authenticated, log in:

bash

eve auth login

The CLI will guide them through SSH key discovery (can fetch from GitHub if needed).

We'll set harness credentials after project creation.

检查当前认证状态：

bash

eve auth status

如果未认证，请登录：

bash

eve auth login

CLI将引导用户完成SSH密钥发现（必要时可从GitHub获取）。

我们将在项目创建后设置Harness凭证。

Step 4: Org + Project

步骤4：组织 + 项目

Ask the user for:

Organization name (e.g., "my-company")
Project name (e.g., "My App")
Project slug (e.g., "my-app")
Repo URL (e.g., "git@github.com:me/my-app.git")

Create or ensure they exist:

bash

eve org ensure my-company --slug myco
eve project ensure --name "My App" --slug my-app --repo-url git@github.com:me/my-app.git --branch main

URL impact: The org and project slugs directly form deployment URLs and K8s namespaces:

URL:

{service}.{orgSlug}-{projectSlug}-{env}.{domain}

(e.g.,

api.myco-my-app-staging.eh1.incept5.dev

)

Namespace:

eve-{orgSlug}-{projectSlug}-{env}

(e.g.,

eve-myco-my-app-staging

)

```
${ORG_SLUG}
```
is available for interpolation in manifest values

Slugs are immutable — choose short, meaningful values.

Set as defaults in the profile:

bash

eve profile set --org org_xxx --project proj_xxx

向用户索要以下信息：

组织名称（例如："my-company"）
项目名称（例如："My App"）
项目标识（slug）（例如："my-app"）
仓库URL（例如："git@github.com:me/my-app.git"）

创建或确认组织和项目已存在：

bash

eve org ensure my-company --slug myco
eve project ensure --name "My App" --slug my-app --repo-url git@github.com:me/my-app.git --branch main

URL影响：组织和项目标识（slug）直接构成部署URL和K8s命名空间：

URL格式：

{service}.{orgSlug}-{projectSlug}-{env}.{domain}

（例如：

api.myco-my-app-staging.eh1.incept5.dev

）

命名空间格式：

eve-{orgSlug}-{projectSlug}-{env}

（例如：

eve-myco-my-app-staging

）

```
${ORG_SLUG}
```
可在清单值中进行插值

标识（slug）不可修改——请选择简短且有意义的值。

在配置文件中设置为默认值：

bash

eve profile set --org org_xxx --project proj_xxx

Step 5: Choose Harness + Set API Keys

步骤5：选择Harness并设置API密钥

Ask which harness they want to target (can be more than one):

mclaude / claude (Anthropic)
code / codex (OpenAI)
zai (Z.ai)
gemini (Google)

Map harnesses to required secrets:

mclaude/claude:
```
ANTHROPIC_API_KEY
```
(preferred) or Claude OAuth via
```
eve auth sync
```
code/codex:
```
OPENAI_API_KEY
```
(preferred) or
```
CODEX_AUTH_JSON_B64
```
zai:
```
Z_AI_API_KEY
```
gemini:
```
GEMINI_API_KEY
```
(or
```
GOOGLE_API_KEY
```
)

Decide where to store secrets:

Org (recommended) for shared keys across projects
Project for app-specific keys
User for personal keys

Use a secrets file for batch setup (starter repo includes

secrets.env.example

bash

cp secrets.env.example secrets.env
eve secrets import --org org_xxx --file ./secrets.env

For Claude/Codex OAuth tokens on the host:

bash

undefined

询问用户要对接的Harness（可多选）：

mclaude / claude（Anthropic）
code / codex（OpenAI）
zai（Z.ai）
gemini（Google）

Harness对应的所需密钥：

mclaude/claude：
```
ANTHROPIC_API_KEY
```
（推荐）或通过
```
eve auth sync
```
进行Claude OAuth认证
code/codex：
```
OPENAI_API_KEY
```
（推荐）或
```
CODEX_AUTH_JSON_B64
```
zai：
```
Z_AI_API_KEY
```
gemini：
```
GEMINI_API_KEY
```
（或
```
GOOGLE_API_KEY
```
）

决定密钥的存储位置：

组织级别（推荐）：供多个项目共享密钥
项目级别：应用专属密钥
用户级别：个人密钥

使用密钥文件进行批量设置（初始仓库包含

secrets.env.example

）：

bash

cp secrets.env.example secrets.env
eve secrets import --org org_xxx --file ./secrets.env

如需在主机上使用Claude/Codex OAuth令牌：

bash

undefined

Store OAuth tokens in the project scope (or add --system if admin)

将OAuth令牌存储在项目范围内（如果是管理员可添加--system参数）

eve auth sync --project proj_xxx

undefined

eve auth sync --project proj_xxx

undefined

Step 6: Manifest Configuration

步骤6：清单配置

The starter template includes

.eve/manifest.yaml

. Update it with the project details:

yaml

schema: eve/compose/v2
project: my-app

services:
  api:
    build:
      context: apps/api
    ports: [3000]
    x-eve:
      ingress:
        public: true
        port: 3000

environments:
  staging:
    pipeline: deploy

pipelines:
  deploy:
    steps:
      - name: deploy
        action: { type: deploy }

Key fields to customize:

```
project
```
: Match the project slug
```
services
```
: Define your app's services
```
x-eve.ingress
```
: Configure public access

初始模板包含

.eve/manifest.yaml

。使用项目详情更新该文件：

yaml

schema: eve/compose/v2
project: my-app

services:
  api:
    build:
      context: apps/api
    ports: [3000]
    x-eve:
      ingress:
        public: true
        port: 3000

environments:
  staging:
    pipeline: deploy

pipelines:
  deploy:
    steps:
      - name: deploy
        action: { type: deploy }

需要自定义的关键字段：

```
project
```
：与项目标识（slug）匹配
```
services
```
：定义应用的服务
```
x-eve.ingress
```
：配置公共访问权限

Step 7: Git Remote

步骤7：Git远程仓库

The project starts with no remote. Help set one up:

bash

git remote -v
git remote add origin git@github.com:user/my-app.git
git push -u origin main

项目初始状态无远程仓库。帮助设置远程仓库：

bash

git remote -v
git remote add origin git@github.com:user/my-app.git
git push -u origin main

Step 8: Verification

步骤8：验证

Run these checks to confirm setup:

bash

eve system health
eve auth status
eve profile show

运行以下检查以确认设置完成：

bash

eve system health
eve auth status
eve profile show

Next Steps

后续步骤

After setup is complete, suggest:

Run locally:
```
docker compose up --build
```

Set secrets:

eve secrets set MY_KEY "value"

eve secrets import --file ./secrets.env

Deploy to staging:

eve env deploy staging --ref main --repo-dir .

Create a job:

eve job create --prompt "Review the codebase"

Note: If the environment has a

pipeline

configured in the manifest,

eve env deploy <env> --ref <sha>

will trigger that pipeline. Use

--direct

to bypass the pipeline and do a direct deploy.

--ref

must be a 40-character SHA, or a ref resolved against

--repo-dir

/cwd.

设置完成后，建议执行以下操作：

本地运行：
```
docker compose up --build
```

设置密钥：

eve secrets set MY_KEY "value"

或

eve secrets import --file ./secrets.env

部署到预发布环境：

eve env deploy staging --ref main --repo-dir .

创建任务：

eve job create --prompt "Review the codebase"

注意：如果清单中为环境配置了

pipeline

，则

eve env deploy <env> --ref <sha>

将触发该流水线。使用

--direct

参数可绕过流水线直接部署。

--ref

必须是40字符的SHA，或是基于

--repo-dir

/当前工作目录解析的引用。

Troubleshooting

故障排除

"eve: command not found"

bash

npm install -g @eve-horizon/cli

bash

npm install -g @eve-horizon/cli

"Not authenticated"

bash

eve auth login

bash

eve auth login

"No profile"

bash

eve profile create staging --api-url https://api.eh1.incept5.dev

bash

eve profile create staging --api-url https://api.eh1.incept5.dev