eve-agent-native-design

Eve Horizon 的 Agent 原生设计

构建将 Agent 视为一等公民，而非事后考虑的应用。

适用场景

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

• 在 Eve 上设计新应用或 API
• 评估现有应用是否适合 Agent 使用
• 添加 Agent 应能够使用的功能
• 决定将逻辑放在代码中还是提示词中
• 选择如何处理 Agent 间通信

四项原则

1. 平等性 — Agent 能完成用户能做的一切

每项用户操作都必须有对应的 Agent 操作路径。

在 Eve 上：CLI 就是平等性层。如果用户可以通过 eve ... 完成某项操作，Agent 也能做到。构建应用时，请遵循相同原则：

检查项	方法
Agent 能创建、读取、更新和删除每种实体吗？	将 UI 操作映射到对应的 CLI/API 操作
是否存在仅限 UI 的工作流？	将其公开为 API 端点或 CLI 命令
Agent 能发现可用功能吗？	为每种实体类型提供 list 操作

CRUD 完备性：对于应用中的每种实体，都要确认 Agent 具备创建、读取、更新和删除操作路径。缺少任何一项都会破坏平等性。

2. 粒度 — 原子化基础操作，而非捆绑逻辑

功能来自 Agent 循环，而非单体工具。

错误：deploy_and_monitor(app) — 将判断封装进代码 错误：classify_and_organize_files(files) — 应由 Agent 决定如何分类 正确：eve build create、eve build run、eve env deploy、eve job follow — 由 Agent 决定执行顺序

在 Eve 上：清单定义 WHAT（服务、流水线），Agent 决定如何以及何时组合它们。

设计测试：要改变行为时，你是编辑文本（提示词/技能），还是重构代码？如果是后者，说明你的工具还不够原子化。

3. 可组合性 — 新功能 = 新提示词

当工具具备原子性且实现平等性时，只需编写提示词，而非代码，就能添加功能。

Eve 示例：eve-pipelines-workflows 技能增加了组合流水线的能力。无需新增 CLI 命令 — 该技能会教 Agent 组合现有的 eve pipeline 和 eve workflow 命令。

你的应用：如果添加功能需要新的 API 端点，你可能捆绑了逻辑。可以考虑是否能以不同方式组合现有基础操作。

4. 涌现能力 — Agent 会带来意外惊喜

构建原子化工具。Agent 组合出意想不到的解决方案。观察其中的模式。优化常见模式。循环往复。

Eve 示例：Agent 组合 eve job create --parent、eve job dep add 和深度传播，构建任意工作层级。平台并未规定这种做法 — Agent 从原子化基础操作中自行发现了它。

面向 Agent 应用的平台能力

除了四项原则，Eve 还提供（或正在构建）一些特定基础能力，可大幅简化 Agent 应用的开发：

作业附件 — 结构化上下文传递

无需繁琐的文件操作，即可在 Agent 之间传递计划、报告和洞察。将文本文档（markdown、JSON、YAML）附加到作业中。下游 Agent 可读取父作业的附件。这解决了 80% 的“Agent 传递结构化上下文”问题。

服务账户身份验证 — 后端到 API 的通信

使用 eve auth mint（当前方案）或服务账户（逐步推出）对应用后端进行身份验证。每个带有后端的应用都需要非用户令牌来调用 API。限定权限可确保遵循最小权限原则。

组织文档库 — 持久化 Agent 知识

Agent 会积累超出单个作业生命周期的知识：架构报告、风险评估、约定。它基于数据库构建，支持全文搜索，并可通过 PATCH 操作进行 Agent 原生的搜索和替换编辑。

Web 聊天 — 两种机制

根据需求选择：

• Gateway Provider（机制 A）：通过 WebSocket 连接 Eve 网关。无需后端。最适合简单的聊天小组件和管理控制台。
• Backend-Proxied（机制 B）：应用后端调用 POST /internal/orgs/:id/chat/route。可全面控制增强、存储和路由。最适合生产级 SaaS。

决策：如果你的应用会拦截、增强或存储对话 → 使用 B。否则 → 使用 A。

跨项目查询 — 组织级智能

适用于组合视图、仪表板以及任何跨多个项目的工具。组织级端点可避免 N+1 API 调用。

完整目录、API 架构和优先级排名请参阅 references/eve-horizon-primitives.md。

Eve 专属设计模式

文件作为通用接口

• Agent 了解 cat、grep、mv、mkdir
• 使用 .eve/manifest.yaml 作为唯一事实来源 — Agent 会读取和编辑它
• Agent 配置存放在仓库文件（agents.yaml、teams.yaml）中 — 而非隐藏在数据库里
• 目录结构 = 信息架构：{entity_type}/{entity_id}/content
• 按用途命名文件：{entity}.json、{type}.md、agent_log.md

上下文注入（三个层级）

系统提示词应包含：

1. 可用资源 — 有哪些资源及其数量：“/notes 中有 12 条笔记，3 个项目”
2. 能力 — Agent 可以做什么：“创建、编辑、添加标签、删除笔记”
3. 近期活动 — 发生了什么：“用户 2 小时前创建了‘Project kickoff’”

Eve 会将 EVE_API_URL、EVE_PROJECT_ID、EVE_ORG_ID、EVE_ENV_NAME 注入每个环境。技能会提供领域词汇。

明确的完成信号

• 作业通过 json-result 返回 eve.status（“success”、“failed”、“waiting”）
• 不使用启发式完成检测 — 始终使用明确信号
• 通过阶段转换在任务级别跟踪进度
• 支持多步骤操作的 shouldContinue
• 创建状态检查点，以便中断后恢复

动态能力发现

• eve job list 用于发现可用工作
• eve agents list 用于发现可用 Agent
• 技能系统会在安装时自动发现能力
• 网关按 slug 将消息路由到 Agent — 新 Agent 可立即寻址
• 优先使用运行时发现（list_available_types()），而不是静态的逐端点工具映射

Agent 与 UI 通信

• 事件类型：thinking、toolCall、toolResult、textResponse、statusChange
• 不执行无声操作 — 变更会立即显示
• 执行过程中展示进度，而不只是结果
• 对于嘈杂的内部操作，可考虑使用 ephemeralToolCalls

成功检查清单

架构：

• 每个 UI 操作都有对应的 CLI/API 等效操作（一致性）
• 每个实体都支持完整的 CRUD（完整性）
• 工具各司其职；由 Agent 决定如何组合（一致性粒度）
• 添加能力 = 添加技能/提示词，而非编写代码（可组合性）
• Agent 能处理未明确设计过的请求（涌现性）

实现：

• Manifest 和配置文件是唯一事实来源（文件作为接口）
• 系统提示词包含资源、能力和近期活动（上下文注入）
• 完成状态明确，而非通过启发式判断（带有 eve.status 的 json-result）
• Agent 操作会立即反映在 UI 中（可见性）
• 新增能力可通过动态发现机制发现（可扩展性）

如果要构建带后端的应用：

• 已配置用于 API 访问的服务账户身份验证
• 已选择 Web 聊天机制（网关或代理）
• 使用作业附件提供结构化的 Agent 间上下文
• 使用组织文档存储持久化知识（可用时）

反模式

反模式	修正方式
Agent 仅充当路由器	让 Agent 执行操作，而不只是路由
工作流式工具（analyze_and_deploy）	拆分为原子级基础操作
仅支持 UI 的操作	保持功能一致——添加 CLI/API 路径
上下文匮乏	通过技能和环境变量注入资源
无缘由的门槛	默认开放；保留基础操作的可用性
基于启发式的完成判断	使用明确的完成信号
静态 API 映射	使用动态能力发现
在职位描述中塞入上下文	使用职位附件存放结构化文档
后端使用每位用户的令牌	使用服务账户 / eve auth mint
轮询事件	可用时使用 Webhook（逐渐普及）

参考资料

完整的平台基础操作目录（包含 API 架构、数据库设计和实现优先级排序）请参见 references/eve-horizon-primitives.md。

源理念：../eve-horizon/docs/ideas/agent-native-design.md 平台基础操作分析：../eve-horizon/docs/ideas/platform-primitives-for-agentic-apps.md