eve-agentic-app-design by incept5/eve-skillpacks
npx skills add https://github.com/incept5/eve-skillpacks --skill eve-agentic-app-design将一个全栈应用转变为以智能体为主要参与者的应用——智能体能够与人类一起进行推理、协调、记忆和沟通。
在以下情况下加载此技能:
首先加载 eve-fullstack-app-design。 智能体层建立在坚实的 PaaS 基础之上。如果没有设计良好的清单、服务拓扑、数据库、流水线和部署策略,智能体能力将陷入混乱。
发展顺序:
eve-agent-native-design — 原则(对等性、细粒度、可组合性、涌现能力)eve-fullstack-app-design — PaaS 基础(清单、服务、数据库、流水线、部署)每一层都依赖于前一层。不要跳过任何一层。
智能体在 agents.yaml 中定义(路径通过清单中的 x-eve.agents.config_path 设置)。每个智能体都是一个具有技能、访问范围和政策的人物角色。
Transform a full-stack app into one where agents are primary actors — reasoning, coordinating, remembering, and communicating alongside humans.
Load this skill when:
Loadeve-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:
eve-agent-native-design — Principles (parity, granularity, composability, emergent capability)eve-fullstack-app-design — PaaS foundation (manifest, services, DB, pipelines, deploys)Each layer assumes the previous. Skip none.
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
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
每个智能体的设计决策:
| 决策 | 选项 | 指导原则 |
|---|---|---|
| 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。 |
团队在 teams.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
选择正确的分发模式:
| 模式 | 何时使用 | 工作原理 |
|---|---|---|
fanout | 独立的并行工作 | 根作业 + 每个成员的并行子作业。最适合可分解的任务。 |
council | 集体判断 | 所有智能体响应,结果按策略(多数、一致、负责人决定)合并。最适合评审、审计。 |
relay | 顺序交接 | 负责人委派给第一个成员,输出传递给下一个。最适合分阶段的工作流。 |
设计原则:大多数工作是 fanout。仅当多个视角确实能改善结果时才使用 council。仅当每个阶段的输出是下一阶段的输入时才使用 relay。
在清单中定义命名的配置文件。智能体引用配置文件,而不是特定的 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 不可用,则尝试下一个。围绕能力需求设计配置文件,而不是提供商标记。
| 任务类型 | 配置文件策略 |
|---|---|
| 复杂编码、架构 | 高推理模型(opus, gpt-5.2-codex) |
| 代码审查、文档编写 | 中等推理模型(sonnet, gemini) |
| 分类、路由、分类 | 快速模型(haiku-equivalent, low reasoning) |
| 专业领域 | 选择领域性能最强的模型 |
加载 eve-agent-memory 以获取完整的存储原语目录。本节重点讨论架构决策。
| 信息类型 | 存储原语 | 原因 |
|---|---|---|
| 作业期间的临时笔记 | 工作区文件(.eve/) | 临时性,随作业结束而消失 |
| 传递给父作业的作业输出 | 作业附件 | 在作业完成后保留,可通过作业 ID 寻址 |
| 滚动的对话上下文 | 线程 | 跨会话的连续性,可总结 |
| 精选知识 | 组织文档存储 | 版本控制、可搜索、跨项目共享 |
| 文件树和资源 | 组织文件系统(同步) | 双向同步,本地编辑 |
| 结构化查询 | 托管数据库 | SQL、关系、行级安全 |
| 可重用工作流 | 技能 | 最高保真度的长期记忆 |
按智能体和目的组织组织文档:
/agents/{agent-slug}/learnings/ — 发现和模式
/agents/{agent-slug}/decisions/ — 决策记录
/agents/{agent-slug}/runbooks/ — 操作流程
/agents/shared/ — 跨智能体共享知识
/projects/{project-slug}/ — 项目范围内的知识
没有过期的记忆会变成噪音。为每个存储位置决定:
事件是智能体应用的神经系统。将它们用于响应式自动化——即响应其他事情而应该发生的事情。
| 触发器 | 事件 | 响应 |
|---|---|---|
| 代码推送到主分支 | github.push | 运行 CI 流水线 |
| PR 被打开 | github.pull_request | 运行评审委员会 |
| 部署流水线失败 | system.pipeline.failed | 运行自愈工作流 |
| 作业失败 | system.job.failed | 运行诊断智能体 |
| 组织文档创建 | 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"
从你的服务发出特定于应用的事件:
eve event emit --type app.invoice.created --source app --payload '{"invoice_id":"inv_123"}'
在清单中将这些事件连接到工作流或流水线。有意地设计你应用的事件词汇表——事件是你的应用逻辑与智能体自动化之间的 API。
Eve 通过统一的网关支持多个聊天提供商:
| 提供商 | 传输方式 | 最适合 |
|---|---|---|
| Slack | Webhook | 团队协作,现有的 Slack 工作区 |
| Nostr | 订阅 | 去中心化,注重隐私,抗审查 |
| WebChat | WebSocket | 浏览器原生,嵌入你的应用 |
在 chat.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>。
| 方法 | 何时使用 |
|---|---|
| 网关提供商(WebSocket 到 Eve) | 简单的聊天小部件,管理控制台,无需后端 |
后端代理(POST /internal/orgs/:id/chat/route) | 生产型 SaaS,当你需要拦截、丰富或存储对话时 |
如果你的应用需要添加上下文、过滤消息或维护自己的聊天历史记录——请通过你的后端进行代理。
聊天线程在消息之间保持上下文。线程键的范围限定在集成账户内。设计你的聊天用户体验以保留线程上下文——当智能体能够引用对话历史时,其效率会显著提高。
作业是智能体工作的基本单位。将复杂的工作流设计为作业树:
Parent (orchestrator)
├── Child A (research)
├── Child B (implementation)
└── Child C (testing)
父作业进行分发、等待、恢复、综合。子作业独立执行。使用 waits_for 关系来表达依赖关系。有关完整模式,请参阅 eve-orchestration。
使用作业附件在智能体之间传递结构化数据,而不是冗长的描述字符串:
# 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 发布更新。负责人智能体可以 eve supervise 来监控作业树。
后端服务需要非用户令牌来进行 API 调用。使用 eve auth mint 创建范围受限的令牌:
eve auth mint --email app-bot@example.com --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 进行同步。
| 策略 | 使用场景 |
|---|---|
default | 交互式智能体,需要对风险操作进行人工批准 |
auto_edit | 自主编辑代码和文件的工作智能体 |
never | 只读智能体(审计员、评审员) |
yolo | 受控环境中的完全自主智能体(谨慎使用) |
在 .eve/access.yaml 中声明所有访问权限并进行声明式同步。这确保了访问权限是版本控制的、可审查的和可复现的。有关完整的 v2 策略模式,请参阅 eve-auth-and-secrets。
智能体架构:
agents.yaml 中定义了具有清晰 slug、技能和配置文件的智能体teams.yaml 中定义了具有适当分发模式的团队Harness 配置文件:
记忆:
事件:
聊天:
chat.yaml)协调:
安全:
.eve/access.yaml)真正的测试——这个应用是否真正是智能体原生的?
eve-agent-native-design — 对等性、细粒度、可组合性、涌现能力eve-fullstack-app-design — 清单、服务、数据库、流水线、部署eve-agent-memory — 每个记忆原语的详细指南eve-orchestration — 深度传播、并行分解、控制信号eve-read-eve-docs → references/agents-teams.mdeve-read-eve-docs → references/harnesses.mdeve-read-eve-docs → references/gateways.mdeve-read-eve-docs → references/events.md每周安装次数
131
代码仓库
首次出现
2026年2月16日
安全审计
安装于
gemini-cli131
codex131
claude-code125
pi58
opencode41
github-copilot41
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.
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:
| Decision | Options | Guidance |
|---|---|---|
| Slug | Lowercase, alphanumeric + dashes | Org-unique. Used for chat routing: @eve coder fix the login bug |
| Skill | Any installed skill name | The agent's core competency. One skill per agent. |
| Harness profile | Named profile from manifest | Decouples 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. |
Teams are defined in teams.yaml. A team groups agents under a lead with a dispatch strategy.
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:
| Mode | When to Use | How It Works |
|---|---|---|
fanout | Independent parallel work | Root job + parallel child per member. Best for decomposable tasks. |
council | Collective judgment | All agents respond, results merged by strategy (majority, unanimous, lead-decides). Best for reviews, audits. |
relay | Sequential handoff | Lead 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.
Define named profiles in the manifest. Agents reference profiles, never specific harnesses.
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.
| Task Type | Profile Strategy |
|---|---|
| Complex coding, architecture | High-reasoning model (opus, gpt-5.2-codex) |
| Code review, documentation | Medium-reasoning model (sonnet, gemini) |
| Triage, routing, classification | Fast model (haiku-equivalent, low reasoning) |
| Specialized domains | Choose the model with strongest domain performance |
Load eve-agent-memory for the full storage primitive catalog. This section focuses on architectural decisions.
| Information Type | Storage Primitive | Why |
|---|---|---|
| Scratch notes during a job | Workspace files (.eve/) | Ephemeral, dies with the job |
| Job outputs passed to parent | Job attachments | Survives job completion, addressable by job ID |
| Rolling conversation context | Threads | Continuity across sessions, summarizable |
| Curated knowledge | Org Document Store | Versioned, searchable, shared across projects |
| File trees and assets | Org Filesystem (sync) | Bidirectional sync, local editing |
| Structured queries | Managed database | SQL, relationships, RLS |
| Reusable workflows | Skills | Highest-fidelity long-term memory |
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
Memory without expiry becomes noise. For every storage location, decide:
Events are the nervous system of an agentic app. Use them for reactive automation — things that should happen in response to other things.
| Trigger | Event | Response |
|---|---|---|
| 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 |
| 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 |
Wire system failure events to recovery pipelines:
pipelines:
self-heal:
trigger:
system:
event: job.failed
pipeline: deploy
steps:
- name: diagnose
agent:
prompt: "Diagnose the failed deploy and suggest a fix"
Emit application-specific events from your services:
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.
Eve supports multiple chat providers through a unified gateway:
| Provider | Transport | Best For |
|---|---|---|
| Slack | Webhook | Team collaboration, existing Slack workspaces |
| Nostr | Subscription | Decentralized, privacy-focused, censorship-resistant |
| WebChat | WebSocket | Browser-native, embedded in your app |
Define routes in chat.yaml to map inbound messages to agents or teams:
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>.
| Approach | When to Use |
|---|---|
| Gateway provider (WebSocket to Eve) | Simple chat widgets, admin consoles, no backend needed |
Backend-proxied (POST /internal/orgs/:id/chat/route) | Production SaaS, when you need to intercept, enrich, or store conversations |
If your app needs to add context, filter messages, or maintain its own chat history — proxy through your backend.
Chat threads maintain context across messages. Thread keys are scoped to the integration account. Design your chat UX to preserve thread context — agents are dramatically more effective when they can reference conversation history.
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.
Pass structured data between agents using job attachments, not giant description strings:
# 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
Pin specific org document versions as job inputs:
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.
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.
Backend services need non-user tokens for API calls. Use eve auth mint to create scoped tokens:
eve auth mint --email app-bot@example.com --project proj_xxx --role admin
Design each service account with minimal necessary scope.
Segment data-plane access using groups. Groups control who can read/write org docs, org filesystem paths, and database schemas:
# .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.
| Policy | Use 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) |
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.
Agent Architecture:
agents.yaml with clear slug, skill, and profileteams.yaml with appropriate dispatch modesHarness Profiles:
Memory:
Events:
Chat:
chat.yaml)Coordination:
Security:
.eve/access.yaml)The Real Test — Is This App Truly Agent-Native?
eve-agent-native-design — parity, granularity, composability, emergent capabilityeve-fullstack-app-design — manifest, services, DB, pipelines, deployseve-agent-memory — detailed guidance on each memory primitiveeve-orchestration — depth propagation, parallel decomposition, control signalseve-read-eve-docs → references/agents-teams.mdeve-read-eve-docs → references/harnesses.mdeve-read-eve-docs → references/gateways.mdeve-read-eve-docs → references/events.mdWeekly Installs
131
Repository
First Seen
Feb 16, 2026
Security Audits
Installed on
gemini-cli131
codex131
claude-code125
pi58
opencode41
github-copilot41
AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具
48,300 周安装