最近，Claude Code 的流行不仅源于其作为“Vibe编程神器”的体验，更在于它正在重塑智能体的开发范式。过去那种依赖胶水代码或拖拽式构建的、面向过程的传统智能体，正面临被一种全新模式的挑战：这种模式只需开发者描述目标结果，然后交由智能体通过持续循环运行来达成目标。

Claude Code 配合其恰到好处的插件与技能机制证明，一个优秀的编程智能体，本身就是一个优秀的通用智能体。能让它重构代码库架构的能力，同样能让它整理文件、管理阅读列表或自动化工作流程。

近日，Dan Shipper 与 Claude 联合发布的《Agent-Native Architecture》技术指南，详细阐述了这种全新的智能体构建方式，提出了 Agent 原生架构的五大核心原则及一系列值得探讨的细节。

五大核心原则

1. 对等性（Parity）

用户能通过用户界面完成的所有操作，智能体都应该能通过其工具集来实现。
这是最基础的原则。没有对等性，其他原则都无从谈起。必须确保智能体拥有能够覆盖 UI 所有功能的工具。
测试方法：任意选取一个 UI 操作，智能体能否完成？

2. 粒度（Granularity）

工具应设计为原子性的基础功能，而特性则是智能体通过循环操作这些工具达成的结果。
工具是底层能力，特性是在提示词中描述的目标，由配备相应工具的智能体循环运行直至达成。
判断标准：当你需要改变行为时，你是在编辑提示词，还是在重构代码？

3. 可组合性（Composability）

在拥有原子工具和对等性的基础上，开发者可以通过编写新的提示词来创造新功能。
例如，想要一个“生成周报”的功能？只需一个提示词：“回顾本周修改过的文件，总结关键变化。基于未完成项目和临近的截止日期，建议下周的三个优先级。”
智能体将组合使用 list_files、read_file 等工具及其自身的判断能力。你只需描述结果，智能体将循环运行直到目标达成。

4. 涌现能力（Emergent Capability）

智能体能够完成开发者未曾明确设计的任务。
其运作循环如下：
1. 基于原子工具和对等性构建应用。
2. 用户提出一个你未预料到的功能请求。
3. 智能体尝试组合现有工具来完成，若失败则暴露出能力差距。
4. 观察并分析用户的请求模式。
5. 为常见模式添加领域专用工具或优化提示词。
6. 重复此过程。
测试标准：它能否处理你所在领域内的开放式请求？

5. 自我改进（Self-improvement）

Agent 原生应用能够通过累积上下文和优化提示词来持续改进，而无需发布新的代码版本。
* 累积上下文：状态通过上下文文件在会话之间得以保持。
* 开发者级优化：为所有用户发布更新后的提示词。
* 用户级定制：用户可以根据自己的特定工作流修改提示词。

文件作为通用接口

一个关键的设计理念是“文件作为通用接口”。在传统软件中，API 承担着系统间通信的主要工作。而在智能体原生架构中，文件成为了更自然的交互媒介。

为什么选择文件？

• 智能体天然擅长：智能体已经理解 cat、grep、mv、mkdir 等操作，文件处理是它们最熟练的基础功能。
• 用户可见：用户可以直观地看到智能体创建了什么，并能进行编辑、移动或删除。没有黑盒操作。
• 便携性强：数据导出和备份都非常简单，用户真正拥有自己的数据。
• 跨设备同步：在移动端配合 iCloud 等服务，所有设备共享同一文件系统。智能体的工作成果会出现在各处，无需构建复杂的服务器同步逻辑。
• 自文档化：/projects/acme/notes/ 这样的路径比 SELECT * FROM notes WHERE project_id = 123 这样的查询语句更易于理解。

目录结构设计

Documents/
├── AgentCheckpoints/ # 临时文件与检查点
│ └── {sessionId}.checkpoint
├── AgentLogs/ # 调试日志
│ └── {type}/{sessionId}.md
└── Research/ # 用户工作区
└── books/{bookId}/
├── full_text.txt
├── notes.md
└── agent_log.md

上下文注入模式

“`

Context

Who I Am

Reading assistant for the Every app.

What I Know About This User

• Interested in military history and Russian literature
• Prefers concise analysis

What Exists

• 12 notes in /notes
• three active projects

Recent Activity

• User created “Project kickoff” (two hours ago)

My Guidelines

• Don’t spoil books they’re reading
• Use their interests to personalize insights
  “`
  智能体在每次会话开始时读取这个上下文文件，并随着状态变化更新它——这形成了一种无需代码变更的、可移植的工作记忆。

移动端的独特机遇与挑战

机遇

• 文件系统支持：智能体可以自然地使用文件，采用与其他平台一致的基础功能。
• 丰富的设备上下文：可以访问健康数据、位置、照片、日历等“围墙花园”内的信息，这些是桌面或网页端通常不具备的上下文。
• 本地应用：每个用户都拥有自己应用的一个副本。应用可以自我修改、分叉，并针对用户进行演化。
• 应用状态同步：通过 iCloud 等服务，所有设备共享同一文件系统。智能体的工作成果会出现在所有设备上，无需额外构建服务器。

挑战

智能体通常是长时间运行的，而移动应用则不然。
智能体可能需要 30 秒、5 分钟甚至 1 小时来完成任务。但 iOS 等系统会在应用不活动几秒钟后将其置于后台，并可能完全终止应用以回收内存。
这需要精心设计：
* 检查点机制：保存状态以防止工作丢失。
* 恢复功能：中断后能够从离开的地方继续。
* 后台执行：明智地利用操作系统给予的有限后台执行时间。
* 本地 vs 云端：决策哪些任务在本地运行，哪些需要服务器支持。

检查点和恢复实现

“`
struct AgentCheckpoint: Codable {
let agentType: String
let messages: [[String: Any]]
let iterationCount: Int
let taskListJSON: String?
let customState: [String: String]
let timestamp: Date
}

func isValid(maxAge: TimeInterval = 3600) -> Bool {
Date().timeIntervalSince(timestamp) < maxAge
}
``
* **检查点时机**：应用进入后台时、每次工具调用返回结果后、长时间操作期间定期保存。
* **恢复流程**：
1.loadInterruptedSessions()扫描检查点目录。
2. 使用isValid(maxAge:)` 方法过滤有效的检查点。
3. 向用户显示恢复提示。
4. 恢复消息历史并继续智能体的运行循环。
5. 任务完成后删除对应的检查点。

高级模式：动态能力发现

动态能力发现：从静态映射到原子化原语

传统的静态映射方法存在明显局限：

“`python

为50种数据类型构建50个工具

read_steps()
read_heart_rate()
read_sleep()

添加新指标时…需要代码变更

智能体只能访问你预期的内容

“`

而动态能力发现则通过原子化工具实现灵活性：

“`python

两个工具处理一切

list_available_types() → 返回 [“steps”, “heart_rate”, “sleep”, …]
read_data(type) → 读取任何发现的类型

添加新指标时…智能体自动发现

智能体能访问你构建时不知道的功能

“`

这是粒度原则的逻辑延伸。当工具足够原子化时，它们就能处理系统构建时未知的数据类型。

适用场景：
* 智能体需要完整访问权限的外部API（如HealthKit、HomeKit、GraphQL端点）
* 随时间动态添加新能力的系统
* 希望智能体能够执行API支持的任何操作

实现模式详解

共享工作空间

智能体与用户应在同一数据空间中协作，而非独立的沙盒环境：

UserData/
├── notes/ ← 智能体和用户都在此读写
├── projects/ ← 智能体可以整理，用户可以覆盖
└── preferences.md ← 智能体读取，用户可以编辑

优势：
* 用户可检查和修改智能体的工作成果
* 智能体可基于用户创建的内容进行构建
* 无需额外的数据同步层
* 操作过程完全透明

这应作为默认选择。仅在特定需求场景（如安全性要求、防止关键数据损坏）下使用沙盒模式。

智能体执行模式

完成信号机制：智能体需要明确的方式宣告任务完成，避免依赖启发式检测：

“`swift
struct ToolResult {
let success: Bool
let output: String
let shouldContinue: Bool
}

.success(“Result”) // 继续执行
.error(“Message”) // 继续（允许重试）
.complete(“Done”) // 停止循环
“`

模型层级选择：不同智能体操作需要匹配的智能水平：

| 任务类型 | 推荐层级 | 原因 |
|———|———|——|
| 研究智能体 | 平衡型 | 需要工具循环和良好推理能力 |
| 聊天对话 | 平衡型 | 对话响应需足够快速 |
| 复杂综合分析 | 强大型 | 涉及多源信息分析 |
| 快速分类任务 | 快速型 | 处理大量简单任务 |

智能体到UI通信

智能体行动时，用户界面应立即反映状态变化。聊天集成的典型事件类型：

swift
enum AgentEvent {
case thinking(String) // → 显示为思考指示器
case toolCall(String, String) // → 显示正在使用的工具
case toolResult(String) // → 显示执行结果（可选）
case textResponse(String) // → 流式传输到聊天界面
case statusChange(Status) // → 更新状态栏信息
}

核心原则：杜绝静默操作。智能体的所有变化都应立即可见。

静默的智能体会让用户感觉系统已损坏。可见的进度展示有助于建立信任。

产品层面的影响

渐进式披露

系统应从简单开始但具备无限扩展能力。基础功能应能立即生效，高级用户可将系统推向未预期的方向。

以Excel为例：无论是制作购物清单还是构建财务模型，都使用同一工具。Claude Code也具备这种特质——界面保持简洁，能力随用户需求自然扩展。

• 简单入口：基础请求无需学习成本即可生效
• 可发现的深度：用户在探索过程中发现新能力
• 无上限扩展：高级用户可将系统推向开发者未预期的方向

潜在需求发现

构建强大的基础能力，观察用户要求智能体执行的任务，将涌现的模式形式化。这是发现而非猜测的过程。

传统产品开发：想象用户需求 → 构建功能 → 验证是否正确

智能体原生产品开发：构建强大基础 → 观察用户要求智能体做什么 → 将涌现的模式形式化

当用户要求智能体执行任务并成功时，这是积极的信号。当用户要求但失败时，这同样是重要信号——揭示了工具能力或对等性方面的差距。

反模式警告

常见的非智能体原生方法

以下方法不一定错误，但与Agent原生架构理念存在差异：

智能体作为路由器：智能体仅分析用户意图，然后调用预设函数。智能体的智能被用于路由决策，而非实际行动。

先构建应用，再添加智能体：以传统方式构建功能后，再将其暴露给智能体。智能体只能执行已有功能。

请求/响应思维：智能体接收输入 → 执行单一操作 → 返回输出。这种模式错过了循环执行的核心价值：智能体应持续操作直至达成目标。

防御性工具设计：过度约束工具输入参数，使用严格枚举，每层都进行验证。虽然安全，但限制了智能体执行未预期任务的能力。

代码处理快乐路径，智能体仅执行：传统软件在代码中处理边缘情况。Agent原生架构让智能体运用判断力处理边缘情况。

具体反模式实例

智能体执行预设工作流，而非追求结果：开发者编写完整逻辑，智能体仅负责调用。决策逻辑固化在代码中，未融入智能体判断。

工作流形状的工具：如analyze_and_organize()将判断逻辑打包到单一工具中。应将其分解为原子化原语，让智能体自由组合。

孤立的UI操作：用户可通过UI执行某操作，但智能体无法实现相同功能。解决方案：维护UI与智能体的对等性。

上下文饥饿：智能体不了解环境中存在的资源。用户说”整理我的笔记”，智能体却不知道有笔记存在。解决方案：在系统提示中注入可用资源和能力信息。

启发式完成检测：通过启发式规则判断智能体是否完成任务是脆弱的。解决方案：要求智能体通过专门的完成工具明确宣告任务结束。

成功标准检查清单

架构层面

• [ ] 对等性：智能体能实现用户通过UI可执行的所有操作
• [ ] 粒度：工具是原子化原语；领域工具仅作为快捷方式，不具门控作用
• [ ] 可组合性：可通过编写新提示词添加新功能
• [ ] 涌现能力：智能体能完成开发者未明确设计的任务
• [ ] 行为修改方式：改变行为意味着编辑提示词，而非重构代码

实现层面

• [ ] 系统提示包含可用资源和能力：智能体了解当前环境中存在的资源
• [ ] 共享数据空间：智能体与用户在同一数据空间中工作
• [ ] 实时反馈：智能体的行动立即在UI中反映
• [ ] 完整的CRUD能力：每个实体都具备完整的创建、读取、更新、删除能力
• [ ] 动态能力发现：在适当场景下，外部API使用动态能力发现机制
• [ ] 明确的完成信号：智能体通过专门机制明确表示任务完成

产品层面

• [ ] 渐进式披露：简单请求无需学习成本即可立即生效
• [ ] 无限扩展：高级用户可将系统推向未预期的方向
• [ ] 需求发现：通过观察用户要求智能体执行的任务来了解真实需求
• [ ] 合理的批准机制：批准要求与操作风险和可逆性相匹配

移动端特定

• [ ] 检查点/恢复机制：妥善处理应用中断情况
• [ ] iCloud优先存储：采用云存储优先、本地回退的策略
• [ ] 后台执行：明智利用有限的后台执行时间

终极测试

用户能否要求智能体执行你从未想象过的任务，并且智能体能够成功完成？

向智能体描述一个在你应用领域内、但你没有为其构建特定功能的任务。

智能体能否找到方法来完成它？它能否在循环中持续尝试，直到成功？

如果能，那么你构建的就是一个Agent原生的应用。
如果不能，则意味着你的架构可能过于受限。

这个测试的核心在于验证系统的涌现能力。一个真正的Agent原生应用不仅能执行预设的、已编程的功能，更能通过自主组合已有的原子工具和逻辑，来解决全新的、未预期的问题。这种能力的存在，表明你赋予了智能体足够的基础工具和自主判断空间，使其能够灵活应对不断变化的需求。

Claude Code 本质上是一个被其名称所局限的通用智能体产品。它的出现，可能标志着过去许多智能体开发方法将被颠覆。深入分析其设计理念，并学习如何基于此构建智能体，是紧跟技术浪潮、面向未来的关键。[[IMAGE_X]]

关注“鲸栖”小程序，掌握最新AI资讯