agent-native-architecture

<why_now>

为什么是现在

软件 Agent 现在已经能够可靠地工作。Claude Code 展示了这样一种能力：大模型可以访问 bash 和文件工具，并通过循环持续运行，直到达成目标，从而自主完成复杂的多步骤任务。

令人惊讶的发现是：真正优秀的编码 Agent，其实也是非常优秀的通用 Agent。 让 Claude Code 能够重构代码库的同一套架构，也能让 Agent 整理文件、管理待读清单或自动化工作流。

Claude Code SDK 让这一切触手可及。你可以构建这样的应用：功能不是你编写的代码，而是你描述的结果，由配备工具的 Agent 通过循环运行直至达成目标。

这开辟了一个新领域：以 Claude Code 的方式运行的软件，并将这种方式应用于远超编码的各类领域。 </why_now>

<core_principles>

核心原则

1. 能力对等

用户可以通过 UI 完成的任何操作，Agent 都应该能通过工具实现。

这是根本原则。没有这一点，其他一切都无关紧要。

想象一下，你开发了一款笔记应用，拥有精美的界面，可用于创建、整理和标记笔记。用户向 Agent 提出要求：“创建一条总结我会议内容的笔记，并将其标记为紧急。”

如果你构建了创建笔记的 UI，却没有提供能让 Agent 完成同一操作的能力，Agent 就会束手无策。它或许会道歉或提出澄清问题，但帮不上忙——尽管人类通过界面完成这项操作轻而易举。

解决方法： 确保 Agent 拥有可以完成 UI 所能完成的一切操作的工具（或工具组合）。

这并不是要将 UI 按钮与工具一一对应，而是要确保 Agent 能够达成相同的结果。有时只需一个工具（create_note），有时则需要组合基础操作（使用 write_file 按正确格式写入笔记目录）。

实践要点： 添加任何 UI 能力时，都要问：Agent 能否达成这一结果？如果不能，就添加所需的工具或基础操作。

能力映射表会有所帮助：

用户操作	Agent 如何实现
创建笔记	使用 write_file 写入笔记目录，或调用 create_note 工具
将笔记标记为紧急	更新 update_file 元数据，或调用 tag_note 工具
搜索笔记	调用 search_files 或 search_notes 工具
删除笔记	调用 delete_file 或 delete_note 工具

测试方法： 任选一项用户可以在 UI 中执行的操作，向 Agent 描述。它能达成目标吗？

---

2. 粒度

优先选择原子化的基础操作。功能是 Agent 通过循环运行所达成的结果。

工具是一项基础能力：读取文件、写入文件、运行 bash 命令、存储记录或发送通知。

功能不是你编写的函数，而是你在提示词中描述的结果，由配备工具的 Agent 通过循环运行直至达成。

粒度较低（限制 Agent）：

Tool: classify_and_organize_files(files)
→ You wrote the decision logic
→ Agent executes your code
→ To change behavior, you refactor

粒度较高（赋能 Agent）：

Tools: read_file, write_file, move_file, list_directory, bash
Prompt: "Organize the user's downloads folder. Analyze each file,
        determine appropriate locations based on content and recency,
        and move them there."
Agent: Operates in a loop—reads files, makes judgments, moves things,
       checks results—until the folder is organized.
→ Agent makes the decisions
→ To change behavior, you edit the prompt

关键转变： Agent 凭借判断力追求某个结果，而不是执行预先编排好的步骤。它可能会遇到意料之外的文件类型、调整方法，或提出澄清问题。循环会持续运行，直到达成目标。

工具越原子化，Agent 使用起来就越灵活。如果你把决策逻辑打包进工具，就等于把判断权交还给代码。

测试方法： 要改变某项功能的行为时，你是修改说明文字，还是重构代码？

---

</core_principles>

3. 可组合性

有了原子化工具和能力对等，只需编写新的提示词，就能创建新功能。

这是前两个原则带来的成果。当工具足够原子化，且 Agent 能完成用户能做的任何事时，新功能就只是新的提示词。

想要一个能总结活动并建议优先事项的“每周回顾”功能？只需编写一个提示词：

"Review files modified this week. Summarize key changes. Based on
incomplete items and approaching deadlines, suggest three priorities
for next week."

Agent 会使用 list_files、read_file 和自身的判断来完成这项任务。你不必编写每周回顾功能的代码。你只需描述预期结果，Agent 就会在循环中持续操作，直到达成目标。

这对开发者和用户都适用。 你可以通过添加提示词来发布新功能。用户可以修改提示词或创建自己的提示词来自定义行为。“当我说‘归档这个’时，始终把它移到我的 Action 文件夹并标记为紧急”就可以成为扩展应用功能的用户级提示词。

约束： 只有当工具足够原子化，能够以你未曾预料的方式组合，并且 Agent 的能力与用户对等时，这种方式才有效。如果工具封装了过多逻辑，或者 Agent 无法使用关键功能，可组合性就会受限。

检验标准： 你能否只编写一个新的提示词部分来添加新功能，而无需编写新代码？

---

4. 涌现能力

Agent 能完成你未明确设计过的事情。

当工具足够原子化、能力保持对等且提示词可组合时，用户会向 Agent 提出你从未预料到的要求。而且，Agent 往往能找到解决办法。

“交叉比对我的会议笔记和任务清单，告诉我有哪些承诺还没有安排时间。”

你没有构建“承诺跟踪器”功能。但只要 Agent 能读取笔记、读取任务并进行推理，就可以在循环中持续操作，直到得出答案。

这揭示了潜在需求。 与其猜测用户想要什么功能，不如观察他们要求 Agent 做什么。当某些模式逐渐显现时，你可以使用特定领域的工具或专用提示词对其进行优化。但你不必事先预料到这些需求，而是可以从中发现它们。

飞轮：

1. 使用原子化工具并保持能力对等
2. 用户提出你未曾预料到的要求
3. Agent 组合工具来完成任务（或失败，从而暴露缺口）
4. 观察用户请求中逐渐显现的模式
5. 添加领域工具或提示词，让常见模式更高效
6. 重复

这会改变产品的构建方式。你不必试图在一开始就设想所有功能，而是打造一个能力充足的基础，并从逐渐涌现的需求中学习。

检验标准： 给 Agent 一个与你的领域相关且开放式的请求。它能否找到合理的处理方式，并在循环中持续操作，直到成功？如果它只是说“我没有这个功能”，说明你的架构限制过多。

5. 随时间改进

Agent 原生应用通过积累上下文和优化提示词不断变得更好。

与传统软件不同，Agent 原生应用无需发布代码即可改进：

积累上下文： Agent 可以跨会话维护状态——有哪些内容、用户做过什么、哪些有效、哪些无效。Agent 读取并更新的 context.md 文件是第一层。更复杂的方法则包括结构化记忆和习得的偏好。

多层级优化提示词：

• 开发者层级： 发布更新后的提示词，为所有用户改变 Agent 的行为
• 用户层级： 用户根据自己的工作流自定义提示词
• Agent 层级： Agent 根据反馈修改自己的提示词（高级）

自我修改（高级）： Agent 可以编辑自己的提示词，甚至自己的代码。对于生产环境中的用例，可以考虑添加安全机制——审批关卡、用于回滚的自动检查点、健康检查。这是未来的发展方向。

改进机制仍在探索中。上下文和提示词优化已经得到验证。自我修改正在兴起。可以确定的是：这种架构支持以传统软件无法实现的方式不断变得更好。

测试方法： 即使不更改代码，应用在使用一个月后是否比第一天表现更好？ </core_principles>

## 你需要在哪方面获得 Agent 原生架构的帮助？

1. 设计架构 - 从零开始规划新的 Agent 原生系统
2. 文件与工作区 - 使用文件作为通用接口，采用共享工作区模式
3. 工具设计 - 构建基础工具、动态能力发现和完整的 CRUD 操作
4. 领域工具 - 了解何时添加领域工具，何时继续使用基础工具
5. 执行模式 - 完成信号、部分完成、上下文限制
6. 系统提示词 - 在提示词中定义 Agent 行为和判断标准
7. 上下文注入 - 将应用运行时状态注入 Agent 提示词
8. 操作对等性 - 确保 Agent 能完成用户可完成的所有操作
9. 自我修改 - 让 Agent 能够安全地自我演进
10. 产品设计 - 渐进式呈现、潜在需求、审批模式
11. 移动端模式 - iOS 存储、后台执行、检查点／恢复
12. 测试 - 测试 Agent 原生应用的能力和对等性
13. 重构 - 让现有代码更具提示词原生特性

请等待回复后再继续。

| 回复 | 操作 | |----------|--------| | 1、“设计”、“架构”、“规划” | 阅读 `references/architecture-patterns.md`，然后应用下方的架构检查清单 | | 2、“文件”、“工作区”、“文件系统” | 阅读 `references/files-universal-interface.md` 和 `references/shared-workspace-architecture.md` | | 3、“工具”、“mcp”、“基础工具”、“crud” | 阅读 `references/mcp-tool-design.md` | | 4、“领域工具”、“何时添加” | 阅读 `references/from-primitives-to-domain-tools.md` | | 5、“执行”、“完成”、“循环” | 阅读 `references/agent-execution-patterns.md` | | 6、“提示词”、“系统提示词”、“行为” | 阅读 `references/system-prompt-design.md` | | 7、“上下文”、“注入”、“运行时”、“动态” | 阅读 `references/dynamic-context-injection.md` | | 8、“对等性”、“UI 操作”、“能力映射” | 阅读 `references/action-parity-discipline.md` | | 9、“自我修改”、“演进”、“git” | 阅读 `references/self-modification.md` | | 10、“产品”、“渐进式”、“审批”、“潜在需求” | 阅读 `references/product-implications.md` | | 11、“移动端”、“ios”、“android”、“后台”、“检查点” | 阅读 `references/mobile-patterns.md` | | 12、“测试”、“测试”、“验证”、“确认” | 阅读 `references/agent-native-testing.md` | | 13、“审查”、“重构”、“现有” | 阅读 `references/refactoring-to-prompt-native.md` |

阅读参考资料后，将其中的模式应用到用户的具体情境中。

<architecture_checklist>

架构审查清单

设计 Agent 原生系统时，请在实施前确认以下事项：

核心原则

• 能力对等： 每项 UI 操作都有对应的 Agent 能力
• 粒度： 工具是原语；功能是由提示词定义的结果
• 可组合性： 仅通过提示词即可添加新功能
• 涌现能力： Agent 能够处理你所在领域中的开放式请求

工具设计

• 动态与静态： 对于 Agent 应能完全访问的外部 API，请使用动态能力发现
• CRUD 完整性： 每个实体都具备创建、读取、更新和删除操作
• 原语而非工作流： 工具提供能力，而不是编码业务逻辑
• 将 API 用作验证器： 当 API 负责验证时，使用 z.string() 输入，而不是 z.enum()

文件与工作区

• 共享工作区： Agent 和用户在同一数据空间中工作
• context.md 模式： Agent 读取和更新上下文文件，以累积知识
• 文件组织： 使用按实体划分的目录，并保持命名一致

Agent 执行

• 完成信号： Agent 有明确的 complete_task 工具（而不是依靠启发式检测）
• 部分完成： 多步骤任务会跟踪进度，以便恢复
• 上下文限制： 从一开始就针对有限的上下文进行设计

上下文注入

• 可用资源： 系统提示词包含已有内容（文件、数据、类型）
• 可用能力： 系统提示词使用用户熟悉的术语说明工具
• 动态上下文： 长时间会话中会刷新上下文（或提供 refresh_context 工具）

UI 集成

• Agent → UI： Agent 的更改会反映在 UI 中（通过共享服务、文件监听或事件总线）
• 不静默执行操作： Agent 写入内容后会立即触发 UI 更新
• 能力发现： 用户能够了解 Agent 可以做什么

移动端（如适用）

• 检查点/恢复： 妥善处理 iOS 应用挂起
• iCloud 存储： 优先使用 iCloud，并在本地回退，以支持多设备同步
• 成本意识： 选择模型层级（Haiku/Sonnet/Opus）

设计架构时，请在计划中明确说明如何满足每个复选框。 </architecture_checklist>

<quick_start>

快速入门：构建 Agent 原生功能

步骤 1：定义原子工具

const tools = [
  tool("read_file", "Read any file", { path: z.string() }, ...),
  tool("write_file", "Write any file", { path: z.string(), content: z.string() }, ...),
  tool("list_files", "List directory", { path: z.string() }, ...),
  tool("complete_task", "Signal task completion", { summary: z.string() }, ...),
];

步骤 2：在系统提示词中编写行为

## Your Responsibilities
When asked to organize content, you should:
1. Read existing files to understand the structure
2. Analyze what organization makes sense
3. Create/move files using your tools
4. Use your judgment about layout and formatting
5. Call complete_task when you're done

You decide the structure. Make it good.

步骤 3：让 Agent 循环工作

const result = await agent.run({
  prompt: userMessage,
  tools: tools,
  systemPrompt: systemPrompt,
  // Agent loops until it calls complete_task
});

</quick_start>

<reference_index>

参考文件

所有参考资料都位于 references/ 中：

核心模式：

• references/architecture-patterns.md - 事件驱动、统一编排器、Agent 到 UI
• references/files-universal-interface.md - 为什么使用文件、组织模式、context.md
• references/mcp-tool-design.md - 工具设计、动态能力发现、CRUD
• references/from-primitives-to-domain-tools.md - 何时添加领域工具、何时转向代码实现
• references/agent-execution-patterns.md - 完成信号、部分完成、上下文限制
• references/system-prompt-design.md - 将功能作为提示词、判断标准

Agent 原生实践：

• references/dynamic-context-injection.md - 运行时上下文、注入内容
• references/action-parity-discipline.md - 能力映射、能力对等工作流
• references/shared-workspace-architecture.md - 共享数据空间、UI 集成
• references/product-implications.md - 渐进式披露、潜在需求、审批
• references/agent-native-testing.md - 结果测试、能力对等测试

特定平台：

• references/mobile-patterns.md - iOS 存储、检查点/恢复、成本意识
• references/self-modification.md - 基于 Git 的演进、防护措施
• references/refactoring-to-prompt-native.md - 迁移现有代码 </reference_index>

<anti_patterns>

反模式

并非完全原生于 Agent 的常见方式

这些方式不一定有问题，也可能适合你的使用场景。但值得注意的是，它们与本文档描述的架构有所不同。

Agent 充当路由器 — Agent 弄清楚用户想要什么，然后调用合适的函数。Agent 的智能被用于路由，而非执行操作。这种方式可行，但你只用到了 Agent 能力的一小部分。

先构建应用，再添加 Agent — 你先用传统方式（编写代码）构建功能，再将这些功能开放给 Agent。Agent 只能执行现有功能已经能做的事，因此不会产生涌现能力。

请求/响应思维 — Agent 接收输入，执行一项操作，然后返回结果。这忽略了整个循环：Agent 获得需要达成的目标后，会持续执行直到完成，并在过程中处理意外情况。

防御式工具设计 — 由于习惯了防御式编程，你对工具输入限制过多：枚举严格，在每一层都进行验证。这种方式很安全，但会阻止 Agent 执行你未预料到的操作。

代码处理顺利路径，Agent 只负责执行 — 传统软件会在代码中处理边缘情况：你编写逻辑来应对 X 出错时的情况。原生于 Agent 的应用则让 Agent 运用判断力处理边缘情况。如果你的代码处理了所有边缘情况，Agent 就只是一个调用方。

---

具体反模式

头号大忌：Agent 执行你的代码，而不是自行解决问题

// WRONG - You wrote the workflow, agent just executes it
tool("process_feedback", async ({ message }) => {
  const category = categorize(message);      // Your code decides
  const priority = calculatePriority(message); // Your code decides
  await store(message, category, priority);   // Your code orchestrates
  if (priority > 3) await notify();           // Your code decides
});

// RIGHT - Agent figures out how to process feedback
tools: store_item, send_message  // Primitives
prompt: "Rate importance 1-5 based on actionability, store feedback, notify if >= 4"

工作流形态的工具 — analyze_and_organize 将判断逻辑封装在工具中。应将其拆分为基本操作，让 Agent 自行组合。

上下文匮乏 — Agent 不知道应用中有哪些资源。

User: "Write something about Catherine the Great in my feed"
Agent: "What feed? I don't understand what system you're referring to."

解决方法：将可用资源、能力和词汇注入系统提示词。

孤立的 UI 操作 — 用户可以通过 UI 执行某项操作，但 Agent 无法做到。解决方法：保持能力对等。

静默操作 — Agent 更改了状态，但 UI 没有更新。解决方法：使用支持响应式绑定的共享数据存储，或观察文件系统。

启发式完成检测 — 通过启发式方法检测 Agent 是否完成（例如连续多轮未调用工具，或检查预期输出文件）。这种方式并不可靠。解决方法：要求 Agent 通过 complete_task 工具明确发出完成信号。

动态 API 的静态工具映射 — 为 50 个 API 端点构建 50 个工具，而 discover + access 模式会更加灵活。

// WRONG - Every API type needs a hardcoded tool
tool("read_steps", ...)
tool("read_heart_rate", ...)
tool("read_sleep", ...)
// When glucose tracking is added... code change required

// RIGHT - Dynamic capability discovery
tool("list_available_types", ...)  // Discover what's available
tool("read_health_data", { dataType: z.string() }, ...)  // Access any type

CRUD 不完整 — Agent 可以创建，但无法更新或删除。

// User: "Delete that journal entry"
// Agent: "I don't have a tool for that"
tool("create_journal_entry", ...)  // Missing: update, delete

解决方法：每种实体都需要完整的 CRUD 操作。

沙箱隔离 — Agent 使用的数据空间与用户不同。

Documents/
├── user_files/        ← User's space
└── agent_output/      ← Agent's space (isolated)

解决方法：使用共享工作区，让双方都能操作相同的文件。

没有理由的门槛 — 某项操作只能通过领域工具完成，而你并无意限制访问。默认应保持开放。除非有明确理由需要设置门槛，否则应保留基本操作的可用性。

人为的能力限制 — 出于模糊的安全顾虑而限制 Agent 能做的事，而非针对具体风险。限制能力时应审慎考虑。通常，Agent 应当能够执行用户可以执行的操作。 </anti_patterns>

<success_criteria>

成功标准

满足以下条件时，你就构建了一个原生于 Agent 的应用：

架构

• Agent 可以完成用户通过 UI 能完成的任何操作（能力对等）
• 工具是原子级基本操作；领域工具是快捷方式，而非门槛（粒度）
• 可以通过编写新提示词来添加新功能（可组合性）
• Agent 可以完成你未明确设计过的任务（涌现能力）
• 更改行为意味着编辑提示词，而非重构代码

实现

• 系统提示词包含有关应用状态的动态上下文
• 每个 UI 操作都有对应的 Agent 工具（操作对等）
• 系统提示词使用用户的用词说明 Agent 工具
• Agent 和用户使用同一个数据空间（共享工作区）
• Agent 的操作会立即反映在 UI 中
• 每个实体都支持完整的 CRUD（创建、读取、更新、删除）
• Agent 明确表示已完成（不依赖启发式检测）
• 使用 context.md 或等效方式积累知识

产品

• 简单请求可立即生效，无需学习成本
• 高级用户可以尝试让系统完成意想不到的任务
• 通过观察用户要求 Agent 执行的任务，了解用户的需求
• 审批要求与任务的重要性和可逆性相匹配

移动端（如适用）

• 检查点和恢复机制可应对应用中断
• 优先使用 iCloud 存储，并在不可用时回退到本地存储
• 后台执行合理利用可用时间
• 模型等级与任务复杂度相匹配

---

终极测试

向 Agent 描述一个属于应用领域、但你没有为其构建专门功能的目标。

它能否找到实现方法，并通过循环尝试直至成功？

如果可以，你构建的就是原生支持 Agent 的产品。

如果它说“我没有对应的功能”，说明你的架构仍然限制过多。