eve-agentic-app-design

Eve Horizon 上的 Agentic 应用设计

将全栈应用转变为由 Agent 担任主要参与者的应用，让它们与人类并肩推理、协作、记忆和沟通。

适用场景

在以下情况下加载此技能：

• 设计一款由 Agent 与人类并列（或取代人类）作为主要用户的应用
• 为现有 Eve 应用添加 Agent 能力
• 在以人为先和以 Agent 为先的架构之间做出选择
• 决定 Agent 应如何协作、记忆和沟通

前置条件：从基础开始

先加载 eve-fullstack-app-design。 Agentic 层建立在稳固的 PaaS 基础之上。若没有设计完善的清单、服务拓扑、数据库、流水线和部署策略，Agentic 能力就会陷入混乱。

推进顺序：

1. eve-agent-native-design — 原则（平等性、粒度、可组合性、涌现能力）
2. eve-fullstack-app-design — PaaS 基础（清单、服务、数据库、流水线、部署）
3. 此技能 — Agentic 层（Agent、团队、记忆、事件、聊天、协作）

每一层都以前一层为基础。不要跳过任何一层。

Agent 架构

定义 Agent

Agent 定义在 agents.yaml 中（路径通过清单中的 x-eve.agents.config_path 设置）。每个 Agent 都有自己的角色、技能、访问范围和策略。

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

每个 Agent 的设计决策：

决策	选项	指导原则
Slug	小写字母、字母数字字符和连字符	在组织内唯一。用于聊天路由：@eve coder fix the login bug
技能	任意已安装的技能名称	Agent 的核心能力。每个 Agent 配备一项技能。
Harness 配置	清单中的命名配置	让 Agent 与特定模型解耦。使用配置，切勿对 Harness 进行硬编码。
网关策略	none、discoverable、routable	默认使用 none。仅对应该接收直接聊天的 Agent 使用 routable。
权限策略	default、auto_edit、never、yolo	工作 Agent 从 auto_edit 开始。需要人工批准的 Agent 使用 default。
Git 策略	commit、push	编码 Agent 使用 auto 提交和 on_success 推送。只读 Agent 使用 never。

设计团队

团队定义在 teams.yaml 中。团队由一位负责人统领，并采用一种调度策略来组织 Agent。

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

选择合适的调度模式：

模式	适用场景	工作方式
fanout	可独立并行的工作	创建根作业，并为每位成员并行创建子作业。最适合可拆分的任务。
council	集体评议	所有 Agent 都会响应，再按策略（多数、一致同意、负责人决定）合并结果。最适合评审和审计。
relay	顺序交接	负责人将任务委派给首位成员，再将其输出传递给下一位成员。最适合分阶段的工作流。

设计原则：大多数工作适合使用 fanout。仅在多种视角确实能改善结果时使用 council。仅在每个阶段的输出都是下一阶段的输入时使用 relay。

Harness 配置

在清单中定义命名配置。Agent 引用配置，而非特定 Harness。

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

配置条目构成一个回退链：如果第一个 Harness 不可用，就尝试下一个。应围绕能力需求设计配置，而非对某个提供商抱有偏好。

单任务 Harness 覆盖

当同一个 Agent 必须针对不同请求使用不同的大脑时，例如按用户项目选择模型、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）以及一个用于审计的稳定哈希。只有在确实需要按调用进行差异化时才使用覆盖；否则优先使用命名配置文件。

模型选择指南

任务类型	配置文件策略
复杂编码、架构设计	高推理能力模型（opus、gpt-5.2-codex）
代码审查、文档编写	中等推理能力模型（sonnet、gemini）
分流、路由、分类	快速模型（haiku 同等级模型、低推理能力）
专业领域	选择该领域表现最强的模型

记忆设计

加载 eve-agent-memory 以查看完整的存储原语目录。本节重点介绍架构决策。

内容存放位置

信息类型	存储原语	原因
任务期间的临时笔记	工作区文件（.eve/）	临时内容，会随任务结束而消失
传递给父级的任务输出	任务附件	任务完成后仍会保留，可通过任务 ID 访问
持续更新的对话上下文	线程	保持跨会话的连续性，且可进行摘要
精选知识	组织文档存储	有版本管理、可搜索，可在项目间共享
文件树和资源	组织文件系统（同步）	双向同步，可在本地编辑
结构化查询	托管数据库	支持 SQL、关系和 RLS
可复用工作流	技能	保真度最高的长期记忆

命名空间约定

按 Agent 和用途组织组织文档：

/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

生命周期策略

没有过期机制的记忆会变成噪声。对于每个存储位置，都要确定：

1. 谁来写入？ 哪些 Agent 会创建和更新这些知识。
2. 谁来读取？ 哪些 Agent 会在何时（任务开始时？按需？）查询这些知识。
3. 何时过期？ 标注创建日期，并构建定期清理任务。
4. 如何保持最新？ 写入前先搜索。更新优于新建。

事件驱动协调

事件主干

事件是 Agent 应用的神经系统。使用事件进行响应式自动化，也就是执行那些响应其他事项而触发的操作。

触发模式

触发条件	事件	响应
代码推送到 main	github.push	运行 CI 流水线
PR 已创建	github.pull_request	运行评审委员会
部署流水线失败	system.pipeline.failed	运行自愈工作流
任务失败	system.job.failed	运行诊断 Agent
任务尝试已完成	system.job.attempt.completed	运行会话后学习工作流（将内容写回 user/learnings 记忆）
组织文档已创建	system.doc.created	通知订阅者并更新索引
定期维护	cron.tick	运行审计、清理和报告
自定义应用事件	app.*	应用专属自动化

自愈模式

将系统故障事件接入恢复流水线：

pipelines:
  self-heal:
    trigger:
      system:
        event: job.failed
        pipeline: deploy
    steps:
      - name: diagnose
        agent:
          prompt: "Diagnose the failed deploy and suggest a fix"

Agent 学习循环

对于需要在会话内跨多次尝试学习的 Agent，请将 system.job.attempt.completed（在成功、失败和编排器错误时都会触发）接入审核工作流，将可延续的上下文提炼到 Agent 记忆中。平台会将 .eve/context/ 中的可延续内容写入下一次尝试的工作区，而 AgentContextMemorySchema 除了接受 learnings、decisions、runbooks、context 和 conventions 类别外，也接受 user 类别——请用 user 存储用户偏好和交互历史。

自定义应用事件

从服务中发出应用特定事件：

eve event emit --type app.invoice.created --source app --payload '{"invoice_id":"inv_123"}'

在清单中将这些事件接入工作流或流水线。请有意设计应用的事件词汇——事件是应用逻辑与 Agent 自动化之间的 API。

聊天与人机协作界面

网关架构

Eve 通过统一网关支持多个聊天提供方：

提供方	传输方式	适用场景
Slack	Webhook	团队协作、已有的 Slack 工作区
Nostr	订阅	去中心化、注重隐私、抗审查
WebChat	WebSocket	原生浏览器、嵌入应用

路由设计

在 chat.yaml 中定义路由，将入站消息映射到 Agent 或团队：

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>。

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

方式	适用场景
嵌入式对话 API（@eve-horizon/chat / @eve-horizon/chat-react）	作用域限定于产品对象（项目、文档、工单）的应用原生聊天面板。应用内聊天的默认选择。
网关提供方（通过 WebSocket 连接 Eve）	简单的聊天组件、管理控制台，无需限定产品对象作用域
后端代理（POST /internal/orgs/:id/chat/route）	生产级 SaaS，需要拦截、丰富或存储对话时

嵌入式应用对话

对于应用内的聊天界面，请使用对话门面，而不是直接基于 chat/route 构建。SDK 会处理线程映射、身份验证、分发、可恢复的 SSE、乐观发送和重新连接：

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" 客户端（轮询）——平台会注册一个空操作投递提供方，以确保持久化仍能正常工作。

线程连续性

聊天线程会在多条消息间保留上下文。线程键的作用域限定于集成账户。如果应用将 Eve 线程 ID 与产品对象一同存储，就可以直接通过 thr_* ID 继续已路由的线程（路由仅解析一次，后续消息会跳过重新路由）。设计聊天体验时，请保留线程上下文——能够参考对话历史的 Agent 效率会大幅提升。

将作业用作协调原语

父子编排

作业是 Agent 工作的基本单元。将复杂工作流设计为作业树：

Parent (orchestrator)
├── Child A (research)
├── Child B (implementation)
└── Child C (testing)

父作业负责分发、等待、恢复和综合。子作业独立执行。使用 waits_for 关系表示依赖项。完整模式请参阅 eve-orchestration。

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

使用作业附件在 Agent 之间传递结构化数据，而不是使用冗长的描述字符串：

# Child stores findings
eve job attach $EVE_JOB_ID --name findings.json --content '{"patterns": [...]}'

# Parent reads on resume
eve job attachment $CHILD_JOB_ID findings.json --out ./child-findings.json

用于挂载文档的资源引用

将组织中特定版本的文档固定为作业输入：

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"}]'

文档会在挂载路径处载入工作区。事件会跟踪载入成功或失败的情况。

协调线程

团队分派工作时，协调线程（coord:job:{parent_job_id}）会关联父任务和子任务。子任务会读取 .eve/coordination-inbox.md 以了解同级任务的上下文。通过 eve thread post 发布更新。主导 Agent 可以使用 eve supervise 监控任务树。

访问与安全

服务账号

后端服务需要使用非用户令牌调用 API。使用 eve auth mint 创建限定范围的令牌：

eve auth mint --email [email protected] --project proj_xxx --role admin

为每个服务账号设计时，应只授予必要的最小权限范围。

访问组

使用组划分数据平面访问权限。组用于控制谁可以读写组织文档、组织文件系统路径和数据库架构：

# .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"] }

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

Agent 权限策略

策略	使用场景
default	执行高风险操作时需要人工批准的交互式 Agent
auto_edit	可自主编辑代码和文件的工作 Agent
never	只读 Agent（审计员、审阅者）
yolo	受控环境中的完全自主 Agent（谨慎使用）

策略即代码

在 .eve/access.yaml 中声明所有访问权限，并以声明式方式同步。这样可以确保访问权限受版本控制、可审阅且可复现。完整的 v2 策略架构请参阅 eve-auth-and-secrets。

Agent 化检查清单

Agent 架构：

• 在 agents.yaml 中定义 Agent，并明确指定 slug、技能和配置文件
• 在 teams.yaml 中定义团队，并选择合适的分派模式
• 有意设置网关策略（不要让所有内容都可路由）
• 定义聊天路由以处理传入消息

Harness 配置文件：

• 在清单中定义 Harness 配置文件（Agent 引用配置文件，而非 Harness）
• 在配置文件中设置回退链以增强弹性
• 模型选择与任务复杂度相匹配

记忆：

• 为每类信息选择存储原语（见上表）
• 为组织文档制定命名空间约定
• 定义生命周期和过期策略
• Agent 在写入前先搜索（更新优于创建）

事件：

• 为关键事件（推送、PR、失败）配置触发模式
• 为部署和任务失败构建自愈流水线
• 为特定领域的自动化定义自定义应用事件

聊天：

• 选择网关提供方（Slack、Nostr、WebChat，或多个）
• 配置聊天路由（chat.yaml）
• 决定使用网关还是由后端代理
• 在用户体验中保留线程连续性

协调：

• 将复杂工作分解为任务树（父任务与子任务）
• 使用附件传递结构化上下文
• 使用协调线程进行团队沟通
• 使用资源引用挂载文档

安全：

• 为后端服务创建服务账号
• 定义访问组以划分数据平面
• 根据每个 Agent 的职责设置合适的权限策略
• 将访问策略声明为代码（.eve/access.yaml）

真正的测试——这个应用真正以 Agent 为核心吗？

• Agent 能完成用户能做的一切（能力对等）
• 添加能力意味着编写提示词，而非代码（可组合性）
• Agent 通过平台原语而非自定义胶水进行协调（细粒度）
• Agent 曾用意想不到的解决方案让你感到惊讶（涌现能力）

交叉引用

• 原则：eve-agent-native-design — 对等性、粒度、可组合性、涌现能力
• PaaS 基础：eve-fullstack-app-design — 清单、服务、数据库、管道、部署
• 存储原语：eve-agent-memory — 关于每种记忆原语的详细指南
• 作业编排：eve-orchestration — 深度传播、并行分解、控制信号
• Agent 和团队参考：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