Back to Details

eve-agentic-app-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agentic App Design on Eve Horizon

Eve Horizon 上的智能代理应用设计

Transform a full-stack app into one where agents are primary actors — reasoning, coordinating, remembering, and communicating alongside humans.
将全栈应用转变为以智能代理为核心角色的应用——代理可与人类协同进行推理、协作、记忆与沟通。

When to Use

适用场景

Load this skill when:
  • Designing an app where agents are primary users alongside (or instead of) humans
  • Adding agent capabilities to an existing Eve app
  • Choosing between human-first and agent-first architecture
  • Deciding how agents should coordinate, remember, and communicate
在以下场景中加载此技能：
  • 设计以智能代理为核心用户（或替代人类用户）的应用
  • 为现有Eve应用添加智能代理能力
  • 在以人为核心和以代理为核心的架构之间做选择
  • 确定代理应如何进行协作、记忆与沟通

Prerequisite: Start with the Foundation

前置要求：从基础开始

Load 
eve-fullstack-app-design
first. The agentic layer builds on a solid PaaS foundation. Without a well-designed manifest, service topology, database, pipeline, and deployment strategy, agentic capabilities collapse into chaos.
The progression:
  1. eve-agent-native-design
     — Principles (parity, granularity, composability, emergent capability)
  2. eve-fullstack-app-design
     — PaaS foundation (manifest, services, DB, pipelines, deploys)
  3. This skill — Agentic layer (agents, teams, memory, events, chat, coordination)
Each layer assumes the previous. Skip none.
请先加载
eve-fullstack-app-design
技能。 智能代理层构建在坚实的PaaS基础之上。若没有设计完善的清单、服务拓扑、数据库、流水线和部署策略，智能代理能力将陷入混乱。
学习流程：
  1. eve-agent-native-design
     —— 核心原则（对等性、粒度、可组合性、涌现能力）
  2. eve-fullstack-app-design
     —— PaaS基础（清单、服务、数据库、流水线、部署）
  3. 本技能 —— 智能代理层（代理、团队、记忆、事件、聊天、协作）
每一层都依赖前一层，请勿跳过任何步骤。

Agent Architecture

代理架构

Defining Agents

定义代理

Agents are defined in 
agents.yaml
(path set via 
x-eve.agents.config_path
in the manifest). Each agent is a persona with a skill, access scope, and policies.
yaml
version: 1
agents:
  coder:
    slug: coder
    description: "Implements features and fixes bugs"
    skill: eve-orchestration
    harness_profile: primary-coder
    access:
      envs: [staging]
      services: [api, worker]
    policies:
      permission_policy: auto_edit
      git:
        commit: auto
        push: on_success
    gateway:
      policy: routable
Design decisions for each agent:
DecisionOptionsGuidance
SlugLowercase, alphanumeric + dashesOrg-unique. Used for chat routing: 
@eve coder fix the login bug
SkillAny installed skill nameThe agent's core competency. One skill per agent.
Harness profileNamed profile from manifestDecouples agent from specific models. Use profiles, never hardcode harnesses.
Gateway policy
none
, 
discoverable
, 
routable
Default to 
none
. Make 
routable
only for agents that should receive direct chat.
Permission policy
default
, 
auto_edit
, 
never
, 
yolo
Start with 
auto_edit
for worker agents. Use 
default
for agents that need human approval.
Git policies
commit
, 
push
auto
commit + 
on_success
push for coding agents. 
never
for read-only agents.
代理在
agents.yaml
中定义（路径通过清单中的
x-eve.agents.config_path
设置）。每个代理都是具备技能、访问范围和策略的角色。
yaml
version: 1
agents:
  coder:
    slug: coder
    description: "Implements features and fixes bugs"
    skill: eve-orchestration
    harness_profile: primary-coder
    access:
      envs: [staging]
      services: [api, worker]
    policies:
      permission_policy: auto_edit
      git:
        commit: auto
        push: on_success
    gateway:
      policy: routable

Designing Teams

代理设计决策

Teams are defined in 
teams.yaml
. A team groups agents under a lead with a dispatch strategy.
yaml
version: 1
teams:
  review-council:
    lead: mission-control
    members: [code-reviewer, security-auditor]
    dispatch:
      mode: council
      merge_strategy: majority
  deploy-ops:
    lead: ops-lead
    members: [deploy-agent, monitor-agent]
    dispatch:
      mode: relay
Choose the right dispatch mode:
ModeWhen to UseHow It Works
fanout
Independent parallel workRoot job + parallel child per member. Best for decomposable tasks.
council
Collective judgmentAll agents respond, results merged by strategy (majority, unanimous, lead-decides). Best for reviews, audits.
relay
Sequential handoffLead delegates to first member, output passes to next. Best for staged workflows.
Design principle: Most work is 
fanout
. Use 
council
only when multiple perspectives genuinely improve the outcome. Use 
relay
only when each stage's output is the next stage's input.
决策项可选方案指导建议
Slug小写字母、数字加连字符在组织内唯一。用于聊天路由：
@eve coder fix the login bug
Skill任何已安装的技能名称代理的核心能力。每个代理对应一个技能。
Harness profile清单中定义的命名配置将代理与特定模型解耦。使用配置，切勿硬编码harness。
Gateway policy
none
, 
discoverable
, 
routable
默认设为
none
。仅为需要接收直接聊天的代理设置
routable
。
Permission policy
default
, 
auto_edit
, 
never
, 
yolo
工作代理初始设为
auto_edit
。对于需要人工批准的代理使用
default
。
Git policies
commit
, 
push
编码代理设为
auto
提交 + 
on_success
推送。只读代理设为
never
。

Harness Profiles

设计团队

Define named profiles in the manifest. Agents reference profiles, never specific harnesses.
yaml
x-eve:
  agents:
    profiles:
      primary-coder:
        - harness: claude
          model: opus-4.5
          reasoning_effort: high
        - harness: codex
          model: gpt-5.2-codex
          reasoning_effort: high
      fast-reviewer:
        - harness: mclaude
          model: sonnet-4.5
          reasoning_effort: medium
Profile entries are a fallback chain: if the first harness is unavailable, the next is tried. Design profiles around capability needs, not provider loyalty.
团队在
teams.yaml
中定义。团队将代理分组，由负责人管理并采用指定的调度策略。
yaml
version: 1
teams:
  review-council:
    lead: mission-control
    members: [code-reviewer, security-auditor]
    dispatch:
      mode: council
      merge_strategy: majority
  deploy-ops:
    lead: ops-lead
    members: [deploy-agent, monitor-agent]
    dispatch:
      mode: relay

Per-Job Harness Overrides

选择合适的调度模式

When the same agent must run with different brains per request — e.g., per-user-project model selection, BYOK credentials, or a self-hosted endpoint — pass an inline override at dispatch instead of mutating 
agents.yaml
per request:
  • Job create: 
    --harness-override-file <path>
    (JSON 
    {harness, model?, reasoning_effort?, variant?, temperature?}
    ) and 
    --env-override KEY=VALUE
    (repeatable, supports 
    ${secret.KEY}
    interpolation)
  • Workflow run/invoke: 
    --env-override KEY=VALUE
    (repeatable)
  • API: 
    harness_profile_override
    and 
    env_overrides
    on 
    CreateJobRequest
    and chat dispatch
The orchestrator records 
harness_profile_source
(
agent_default
, 
string_ref
, 
inline_override
, 
workflow_template
) plus a stable hash for audit. Reach for overrides only when per-invocation variation is real; otherwise prefer named profiles.
模式适用场景工作机制
fanout
独立并行工作根任务 + 每个成员对应一个并行子任务。最适合可分解的任务。
council
集体决策所有代理响应，结果按策略合并（多数同意、一致同意、负责人决定）。最适合评审、审计场景。
relay
顺序交接负责人将任务委派给第一个成员，输出传递给下一个成员。最适合分阶段工作流。

Model Selection Guidance

设计原则：大多数工作采用
fanout
模式。仅当多视角能真正提升结果时使用
council
模式。仅当前一阶段的输出是下一阶段的输入时使用
relay
模式。

—

Harness配置

Task TypeProfile Strategy
Complex coding, architectureHigh-reasoning model (opus, gpt-5.2-codex)
Code review, documentationMedium-reasoning model (sonnet, gemini)
Triage, routing, classificationFast model (haiku-equivalent, low reasoning)
Specialized domainsChoose the model with strongest domain performance
在清单中定义命名配置。代理引用配置，而非特定的harness。
yaml
x-eve:
  agents:
    profiles:
      primary-coder:
        - harness: claude
          model: opus-4.5
          reasoning_effort: high
        - harness: codex
          model: gpt-5.2-codex
          reasoning_effort: high
      fast-reviewer:
        - harness: mclaude
          model: sonnet-4.5
          reasoning_effort: medium
配置项是一个 fallback 链：如果第一个harness不可用，将尝试下一个。围绕能力需求设计配置，而非依赖特定提供商。

Memory Design

按任务覆盖Harness

Load 
eve-agent-memory
for the full storage primitive catalog. This section focuses on architectural decisions.
当同一代理需要根据请求使用不同模型时——例如，按用户项目选择模型、BYOK凭据或自托管端点——请在调度时传递内联覆盖，而非针对每个请求修改
agents.yaml
：
  • 创建任务：
    --harness-override-file <path>
    （JSON格式
    {harness, model?, reasoning_effort?, variant?, temperature?}
    ）和
    --env-override KEY=VALUE
    （可重复使用，支持
    ${secret.KEY}
    插值）
  • 运行/调用工作流：
    --env-override KEY=VALUE
    （可重复使用）
  • API：
    CreateJobRequest
    和聊天调度中的
    harness_profile_override
    与
    env_overrides
编排器会记录
harness_profile_source
（
agent_default
, 
string_ref
, 
inline_override
, 
workflow_template
）以及用于审计的稳定哈希。仅当调用时确实需要变体时才使用覆盖；否则优先使用命名配置。

What Goes Where

模型选择指导

Information TypeStorage PrimitiveWhy
Scratch notes during a jobWorkspace files (
.eve/
)		Ephemeral, dies with the job
Job outputs passed to parentJob attachmentsSurvives job completion, addressable by job ID
Rolling conversation contextThreadsContinuity across sessions, summarizable
Curated knowledgeOrg Document StoreVersioned, searchable, shared across projects
File trees and assetsOrg Filesystem (sync)Bidirectional sync, local editing
Structured queriesManaged databaseSQL, relationships, RLS
Reusable workflowsSkillsHighest-fidelity long-term memory
任务类型配置策略
复杂编码、架构设计高推理模型（opus, gpt-5.2-codex）
代码评审、文档编写中推理模型（sonnet, gemini）
分类、路由、分诊快速模型（haiku等效，低推理）
专业领域任务选择在该领域表现最佳的模型

Namespace Conventions

记忆设计

Organize org docs by agent and purpose:
/agents/{agent-slug}/learnings/      — discoveries and patterns
/agents/{agent-slug}/decisions/      — decision records
/agents/{agent-slug}/runbooks/       — operational procedures
/agents/shared/                      — cross-agent shared knowledge
/projects/{project-slug}/            — project-scoped knowledge
加载
eve-agent-memory
以获取完整的存储原语目录。本节聚焦于架构决策。

Lifecycle Strategy

存储选择

Memory without expiry becomes noise. For every storage location, decide:
  1. Who writes? Which agents create and update this knowledge.
  2. Who reads? Which agents query it and when (job start? on demand?).
  3. When does it expire? Tag with creation dates. Build periodic cleanup jobs.
  4. How does it stay current? Search before writing. Update beats create.
信息类型存储原语原因
任务中的临时笔记工作区文件（
.eve/
）		临时存储，随任务结束销毁
传递给父任务的输出任务附件任务完成后保留，可通过任务ID访问
滚动对话上下文线程跨会话保持连续性，可总结
精选知识组织文档存储版本化、可搜索，跨项目共享
文件树与资产组织文件系统（同步）双向同步，支持本地编辑
结构化查询托管数据库SQL、关系、RLS
可复用工作流技能最高保真度的长期记忆

Event-Driven Coordination

命名空间约定

The Event Spine

—
Events are the nervous system of an agentic app. Use them for reactive automation — things that should happen in response to other things.
按代理和用途组织组织文档：
/agents/{agent-slug}/learnings/      —— 发现与模式
/agents/{agent-slug}/decisions/      —— 决策记录
/agents/{agent-slug}/runbooks/       —— 操作流程
/agents/shared/                      —— 跨代理共享知识
/projects/{project-slug}/            —— 项目范围知识

Trigger Patterns

生命周期策略

TriggerEventResponse
Code pushed to main
github.push
Run CI pipeline
PR opened
github.pull_request
Run review council
Deploy pipeline failed
system.pipeline.failed
Run self-healing workflow
Job failed
system.job.failed
Run diagnostic agent
Job attempt completed
system.job.attempt.completed
Run post-session learning workflow (writes back to 
user
/
learnings
memory)
Org doc created
system.doc.created
Notify subscribers, update indexes
Scheduled maintenance
cron.tick
Run audit, cleanup, reporting
Custom app event
app.*
Application-specific automation
无过期的记忆会变成噪音。对于每个存储位置，请确定：
  1. 谁可以写入？ 哪些代理创建和更新这些知识。
  2. 谁可以读取？ 哪些代理在何时查询（任务开始时？按需？）。
  3. 何时过期？ 标记创建日期。构建定期清理任务。
  4. 如何保持更新？ 写入前先搜索。更新优先于创建。

Self-Healing Pattern

事件驱动协作

—

事件中枢

Wire system failure events to recovery pipelines:
yaml
pipelines:
  self-heal:
    trigger:
      system:
        event: job.failed
        pipeline: deploy
    steps:
      - name: diagnose
        agent:
          prompt: "Diagnose the failed deploy and suggest a fix"
事件是智能代理应用的神经系统。将其用于响应式自动化——即其他事件触发后应执行的操作。

Agent Learning Loop

触发模式

For agents that should learn across attempts within a session, wire 
system.job.attempt.completed
(emitted on success, failure, and orchestrator error) to a review workflow that distills carryover context into agent memory. The platform writes 
.eve/context/
carryover into the next attempt's workspace, and 
AgentContextMemorySchema
accepts a 
user
category alongside 
learnings
, 
decisions
, 
runbooks
, 
context
, and 
conventions
— use 
user
for per-user preferences and interaction history.
触发器事件响应
代码推送到main分支
github.push
运行CI流水线
PR创建
github.pull_request
运行评审团队
部署流水线失败
system.pipeline.failed
运行自修复工作流
任务失败
system.job.failed
运行诊断代理
任务尝试完成
system.job.attempt.completed
运行会话后学习工作流（写入
user
/
learnings
记忆）
组织文档创建
system.doc.created
通知订阅者，更新索引
定期维护
cron.tick
运行审计、清理、报告任务
自定义应用事件
app.*
应用特定自动化

Custom App Events

自修复模式

Emit application-specific events from your services:
bash
eve event emit --type app.invoice.created --source app --payload '{"invoice_id":"inv_123"}'
Wire these to workflows or pipelines in the manifest. Design your app's event vocabulary intentionally — events are the API between your app logic and your agent automation.
将系统故障事件连接到恢复流水线：
yaml
pipelines:
  self-heal:
    trigger:
      system:
        event: job.failed
        pipeline: deploy
    steps:
      - name: diagnose
        agent:
          prompt: "Diagnose the failed deploy and suggest a fix"

Chat and Human-Agent Interface

代理学习循环

Gateway Architecture

—
Eve supports multiple chat providers through a unified gateway:
ProviderTransportBest For
SlackWebhookTeam collaboration, existing Slack workspaces
NostrSubscriptionDecentralized, privacy-focused, censorship-resistant
WebChatWebSocketBrowser-native, embedded in your app
对于需要在会话中跨尝试学习的代理，将
system.job.attempt.completed
（在成功、失败和编排器错误时触发）连接到评审工作流，将可延续上下文提炼到代理记忆中。平台会将
.eve/context/
中的可延续内容写入下一次尝试的工作区，
AgentContextMemorySchema
接受
user
类别，以及
learnings
, 
decisions
, 
runbooks
, 
context
, 
conventions
——使用
user
存储每个用户的偏好和交互历史。

Routing Design

自定义应用事件

Define routes in 
chat.yaml
to map inbound messages to agents or teams:
yaml
version: 1
default_route: route_default
routes:
  - id: deploy-route
    match: "deploy|release|ship"
    target: agent:deploy-agent
  - id: review-route
    match: "review|PR|pull request"
    target: team:review-council
  - id: route_default
    match: ".*"
    target: agent:mission-control
Route targets can be 
agent:<key>
, 
team:<key>
, 
workflow:<name>
, or 
pipeline:<name>
.
从服务中触发应用特定事件：
bash
eve event emit --type app.invoice.created --source app --payload '{"invoice_id":"inv_123"}'
在清单中将这些事件连接到工作流或流水线。有意设计应用的事件词汇——事件是应用逻辑与代理自动化之间的API。

Gateway vs Backend-Proxied Chat vs Embedded Conversations

聊天与人机交互界面

—

网关架构

ApproachWhen to Use
Embedded conversation API (
@eve-horizon/chat
/ 
@eve-horizon/chat-react
)		App-native chat panes scoped to a product object (project, doc, ticket). Default choice for in-app chat.
Gateway provider (WebSocket to Eve)Simple chat widgets, admin consoles, no product-object scoping needed
Backend-proxied (
POST /internal/orgs/:id/chat/route
)		Production SaaS, when you need to intercept, enrich, or store conversations
Eve通过统一网关支持多个聊天提供商：
提供商传输方式最佳场景
SlackWebhook团队协作、现有Slack工作区
Nostr订阅去中心化、隐私优先、抗审查
WebChatWebSocket浏览器原生、嵌入应用

Embedded App Conversations

路由设计

For chat surfaces inside your app, use the conversations facade rather than building over 
chat/route
directly. The SDK handles thread mapping, auth, dispatch, resumable SSE, optimistic send, and reconnect:
ts
const conversation = createConversationClient({
  baseUrl: '/api/eve',
  projectId: 'proj_xxx',
  appKey: `open-design:${projectId}:${conversationId}`,
  getToken: async () => session.token,
});

await conversation.ensure({ metadata: { product_route: '/projects/x' } });
await conversation.send({ text: '...', target: { kind: 'agent', agent_slug: 'designer' } });
for await (const event of conversation.stream({ resumeFrom: lastEventId })) { /* ... */ }
Server endpoints: 
POST /projects/{id}/conversations
, 
POST .../conversations/{app_key}/turns
, 
GET .../conversations/{app_key}/stream
(SSE), 
GET .../conversations/{app_key}/messages
. Events stream as structured 
cevt_*
records (message, progress, status), backfill-safe and resumable via 
Last-Event-ID
. Use 
provider: "api"
clients (polling) when you can't hold a streaming connection — the platform registers a no-op delivery provider so persistence still works.
在
chat.yaml
中定义路由，将入站消息映射到代理或团队：
yaml
version: 1
default_route: route_default
routes:
  - id: deploy-route
    match: "deploy|release|ship"
    target: agent:deploy-agent
  - id: review-route
    match: "review|PR|pull request"
    target: team:review-council
  - id: route_default
    match: ".*"
    target: agent:mission-control
路由目标可以是
agent:<key>
, 
team:<key>
, 
workflow:<name>
或
pipeline:<name>
。

Thread Continuity

网关 vs 后端代理聊天 vs 嵌入式对话

Chat threads maintain context across messages. Thread keys are scoped to the integration account. If your app stores Eve thread IDs alongside its product objects, you can continue a routed thread directly by 
thr_*
ID (route is resolved once, follow-ups skip re-routing). Design your chat UX to preserve thread context — agents are dramatically more effective when they can reference conversation history.
方式适用场景
嵌入式对话API (
@eve-horizon/chat
/ 
@eve-horizon/chat-react
)		应用原生聊天窗格，限定于产品对象（项目、文档、工单）。应用内聊天的默认选择。
网关提供商（WebSocket连接到Eve）简单聊天小部件、管理控制台，无需产品对象限定
后端代理 (
POST /internal/orgs/:id/chat/route
)		生产SaaS，需要拦截、丰富或存储对话时

Jobs as Coordination Primitive

嵌入式应用对话

Parent-Child Orchestration

—
Jobs are the fundamental unit of agent work. Design complex workflows as job trees:
Parent (orchestrator)
├── Child A (research)
├── Child B (implementation)
└── Child C (testing)
The parent dispatches, waits, resumes, synthesizes. Children execute independently. Use 
waits_for
relations to express dependencies. See 
eve-orchestration
for full patterns.
对于应用内的聊天界面，使用对话 facade，而非直接基于
chat/route
构建。SDK处理线程映射、认证、调度、可恢复SSE、乐观发送和重连：
ts
const conversation = createConversationClient({
  baseUrl: '/api/eve',
  projectId: 'proj_xxx',
  appKey: `open-design:${projectId}:${conversationId}`,
  getToken: async () => session.token,
});

await conversation.ensure({ metadata: { product_route: '/projects/x' } });
await conversation.send({ text: '...', target: { kind: 'agent', agent_slug: 'designer' } });
for await (const event of conversation.stream({ resumeFrom: lastEventId })) { /* ... */ }
服务器端点：
POST /projects/{id}/conversations
, 
POST .../conversations/{app_key}/turns
, 
GET .../conversations/{app_key}/stream
（SSE）, 
GET .../conversations/{app_key}/messages
。事件以结构化
cevt_*
记录（消息、进度、状态）流式传输，支持通过
Last-Event-ID
回填和恢复。当无法保持流式连接时，使用
provider: "api"
客户端（轮询）——平台会注册一个无操作交付提供商，确保持久化仍能正常工作。

Structured Context via Attachments

线程连续性

Pass structured data between agents using job attachments, not giant description strings:
bash
undefined
聊天线程在消息之间保持上下文。线程键限定于集成账户。如果应用将Eve线程ID与产品对象一起存储，则可以通过
thr_*
ID直接延续路由线程（路由仅解析一次，后续消息跳过重新路由）。设计聊天UX以保留线程上下文——当代理可以引用对话历史时，其效率会显著提升。

Child stores findings

任务作为协作原语

—

父子编排

eve job attach $EVE_JOB_ID --name findings.json --content '{"patterns": [...]}'
任务是代理工作的基本单元。将复杂工作流设计为任务树：
父任务（编排器）
├── 子任务A（调研）
├── 子任务B（实现）
└── 子任务C（测试）
父任务负责调度、等待、恢复、综合。子任务独立执行。使用
waits_for
关系表达依赖。详见
eve-orchestration
的完整模式。

Parent reads on resume

通过附件传递结构化上下文

eve job attachment $CHILD_JOB_ID findings.json --out ./child-findings.json
undefined
使用任务附件在代理之间传递结构化数据，而非冗长的描述字符串：
bash
undefined

Resource Refs for Document Mounting

子任务存储结果

Pin specific org document versions as job inputs:
bash
eve job create \
  --description "Review the approved plan" \
  --resource-refs='[{"uri":"org_docs:/pm/features/FEAT-123.md@v3","label":"Plan","mount_path":"pm/plan.md"}]'
The document is hydrated into the workspace at the mount path. Events track hydration success or failure.
eve job attach $EVE_JOB_ID --name findings.json --content '{"patterns": [...]}'

Coordination Threads

父任务恢复时读取

When teams dispatch work, a coordination thread (
coord:job:{parent_job_id}
) links parent and children. Children read 
.eve/coordination-inbox.md
for sibling context. Post updates via 
eve thread post
. The lead agent can 
eve supervise
to monitor the job tree.
eve job attachment $CHILD_JOB_ID findings.json --out ./child-findings.json
undefined

Access and Security

文档挂载的资源引用

Service Accounts

—
Backend services need non-user tokens for API calls. Use 
eve auth mint
to create scoped tokens:
bash
eve auth mint --email app-bot@example.com --project proj_xxx --role admin
Design each service account with minimal necessary scope.
将特定版本的组织文档固定为任务输入：
bash
eve job create \
  --description "Review the approved plan" \
  --resource-refs='[{"uri":"org_docs:/pm/features/FEAT-123.md@v3","label":"Plan","mount_path":"pm/plan.md"}]'
文档会被加载到工作区的挂载路径。事件跟踪加载成功或失败。

Access Groups

协作线程

Segment data-plane access using groups. Groups control who can read/write org docs, org filesystem paths, and database schemas:
yaml
undefined
当团队调度工作时，协作线程（
coord:job:{parent_job_id}
）连接父任务和子任务。子任务读取
.eve/coordination-inbox.md
获取兄弟任务上下文。通过
eve thread post
发布更新。负责人可以使用
eve supervise
监控任务树。

.eve/access.yaml

访问与安全

—

服务账户

version: 2 access: groups: eng-team: name: Engineering members: - type: user id: user_abc bindings: - subject: { type: group, id: eng-team } roles: [data-reader] scope: orgdocs: { allow_prefixes: ["/agents/shared/"] } envdb: { schemas: ["public"] }

Sync with `eve access sync --file .eve/access.yaml --org org_xxx`.
后端服务需要非用户令牌进行API调用。使用
eve auth mint
创建限定范围的令牌：
bash
eve auth mint --email app-bot@example.com --project proj_xxx --role admin
为每个服务账户设计最小必要权限范围。

Agent Permission Policies

访问组

PolicyUse Case
default
Interactive agents that need human approval for risky actions
auto_edit
Worker agents that edit code and files autonomously
never
Read-only agents (auditors, reviewers)
yolo
Fully autonomous agents in controlled environments (use carefully)
使用组划分数据平面访问权限。组控制谁可以读写组织文档、组织文件系统路径和数据库模式：
yaml
undefined

Policy-as-Code

.eve/access.yaml

Declare all access in 
.eve/access.yaml
and sync declaratively. This ensures access is version-controlled, reviewable, and reproducible. See 
eve-auth-and-secrets
for the full v2 policy schema.
version: 2 access: groups: eng-team: name: Engineering members: - type: user id: user_abc bindings: - subject: { type: group, id: eng-team } roles: [data-reader] scope: orgdocs: { allow_prefixes: ["/agents/shared/"] } envdb: { schemas: ["public"] }

使用`eve access sync --file .eve/access.yaml --org org_xxx`同步。

The Agentic Checklist

代理权限策略

Agent Architecture:
  • Agents defined in 
    agents.yaml
    with clear slug, skill, and profile
  • Teams defined in 
    teams.yaml
    with appropriate dispatch modes
  • Gateway policies set intentionally (not everything routable)
  • Chat routes defined for inbound message handling
Harness Profiles:
  • Harness profiles defined in manifest (agents reference profiles, not harnesses)
  • Fallback chains in profiles for resilience
  • Model choice matches task complexity
Memory:
  • Storage primitive chosen for each information type (see table above)
  • Namespace conventions established for org docs
  • Lifecycle and expiry strategy defined
  • Agents search before writing (update beats create)
Events:
  • Trigger patterns wired for key events (push, PR, failures)
  • Self-healing pipeline exists for deploy and job failures
  • Custom app events defined for domain-specific automation
Chat:
  • Gateway provider chosen (Slack, Nostr, WebChat, or multiple)
  • Chat routing configured (
    chat.yaml
    )
  • Gateway vs backend-proxied decision made
  • Thread continuity preserved in UX
Coordination:
  • Complex work decomposed as job trees (parent-child)
  • Attachments used for structured context passing
  • Coordination threads used for team communication
  • Resource refs used for document mounting
Security:
  • Service accounts created for backend services
  • Access groups defined for data-plane segmentation
  • Agent permission policies appropriate to each agent's role
  • Access policy declared as code (
    .eve/access.yaml
    )
The Real Test — Is This App Truly Agent-Native?
  • Agents can do everything users can (parity)
  • Adding capability means writing prompts, not code (composability)
  • Agents coordinate through platform primitives, not custom glue (granularity)
  • Agents have surprised you with unexpected solutions (emergent capability)
策略适用场景
default
对风险操作需要人工批准的交互式代理
auto_edit
可自主编辑代码和文件的工作代理
never
只读代理（审计员、评审员）
yolo
受控环境中的完全自主代理（谨慎使用）

Cross-References

策略即代码

  • Principles: 
    eve-agent-native-design
    — parity, granularity, composability, emergent capability
  • PaaS foundation: 
    eve-fullstack-app-design
    — manifest, services, DB, pipelines, deploys
  • Storage primitives: 
    eve-agent-memory
    — detailed guidance on each memory primitive
  • Job orchestration: 
    eve-orchestration
    — depth propagation, parallel decomposition, control signals
  • Agents and teams reference: 
    eve-read-eve-docs
    → 
    references/agents-teams.md
  • Harness execution: 
    eve-read-eve-docs
    → 
    references/harnesses.md
  • Chat gateway: 
    eve-read-eve-docs
    → 
    references/gateways.md
  • Embedded conversation SDK: 
    eve-read-eve-docs
    → 
    references/eve-sdk.md
    (embedded conversation pane)
  • Events and triggers: 
    eve-read-eve-docs
    → 
    references/events.md
在
.eve/access.yaml
中声明所有访问权限，并以声明式方式同步。确保访问权限受版本控制、可评审且可重现。详见
eve-auth-and-secrets
的完整v2策略 schema。
—

智能代理检查清单

—
代理架构：
  • 代理在
    agents.yaml
    中定义，具备清晰的slug、技能和配置
  • 团队在
    teams.yaml
    中定义，采用合适的调度模式
  • 网关策略经过有意设置（并非所有代理都可路由）
  • 为入站消息处理定义了聊天路由
Harness配置：
  • 在清单中定义了Harness配置（代理引用配置，而非harness）
  • 配置中包含fallback链以提高弹性
  • 模型选择与任务复杂度匹配
记忆：
  • 为每种信息类型选择了合适的存储原语（见上表）
  • 为组织文档建立了命名空间约定
  • 定义了生命周期和过期策略
  • 代理在写入前先搜索（更新优先于创建）
事件：
  • 为关键事件（推送、PR、失败）配置了触发模式
  • 存在针对部署和任务失败的自修复流水线
  • 为领域特定自动化定义了自定义应用事件
聊天：
  • 选择了网关提供商（Slack、Nostr、WebChat或多个）
  • 配置了聊天路由（
    chat.yaml
    ）
  • 确定了网关 vs 后端代理的方案
  • 在UX中保留了线程连续性
协作：
  • 复杂工作分解为任务树（父子结构）
  • 使用附件传递结构化上下文
  • 使用协作线程进行团队沟通
  • 使用资源引用进行文档挂载
安全：
  • 为后端服务创建了服务账户
  • 为数据平面划分定义了访问组
  • 为每个代理的角色设置了合适的权限策略
  • 以代码形式声明了访问策略（
    .eve/access.yaml
    ）
真正的测试——这是否是真正的代理原生应用？
  • 代理可以完成用户能做的所有事情（对等性）
  • 添加能力只需编写提示词，无需编写代码（可组合性）
  • 代理通过平台原语协作，而非自定义胶水代码（粒度）
  • 代理为你带来了意想不到的解决方案（涌现能力）
—

交叉引用

—
  • 核心原则：
    eve-agent-native-design
    —— 对等性、粒度、可组合性、涌现能力
  • PaaS基础：
    eve-fullstack-app-design
    —— 清单、服务、数据库、流水线、部署
  • 存储原语：
    eve-agent-memory
    —— 每个记忆原语的详细指导
  • 任务编排：
    eve-orchestration
    —— 深度传播、并行分解、控制信号
  • 代理与团队参考：
    eve-read-eve-docs
    → 
    references/agents-teams.md
  • Harness执行：
    eve-read-eve-docs
    → 
    references/harnesses.md
  • 聊天网关：
    eve-read-eve-docs
    → 
    references/gateways.md
  • 嵌入式对话SDK：
    eve-read-eve-docs
    → 
    references/eve-sdk.md
    （嵌入式对话窗格）
  • 事件与触发器：
    eve-read-eve-docs
    → 
    references/events.md