agent-native-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent-Native Architecture

Agent-Native架构

Core Principles

核心原则

Five principles govern agent-native design. For detailed explanations, examples, and test criteria, see core-principles.md.

Principle	One-line test
Parity	Can the agent achieve every outcome the UI allows?
Granularity	Changing behavior means editing prose, not refactoring code
Composability	Can a feature be added by writing a new prompt, without new code?
Emergent Capability	Can the agent handle open-ended requests it wasn't designed for?
Improvement Over Time	Does the app work better after a month, even without code changes?

以Agent为核心的设计遵循五大原则。如需详细解释、示例和测试标准，请参阅core-principles.md。

原则	一句话测试标准
对等性（Parity）	Agent能否实现UI支持的所有操作结果？
粒度（Granularity）	更改行为只需编辑文本描述，无需重构代码
可组合性（Composability）	是否只需编写新的提示词即可添加功能，无需新增代码？
涌现能力（Emergent Capability）	Agent能否处理未专门设计的开放式请求？
持续改进（Improvement Over Time）	即使不修改代码，应用程序在一个月后是否能表现得更好？

Focus Area Selection

重点领域选择

Design architecture - Plan a new agent-native system from scratch
Files & workspace - Use files as the universal interface, shared workspace patterns
Tool design - Build primitive tools, dynamic capability discovery, CRUD completeness
Domain tools - Know when to add domain tools vs stay with primitives
Execution patterns - Completion signals, partial completion, context limits
System prompts - Define agent behavior in prompts, judgment criteria
Context injection - Inject runtime app state into agent prompts
Action parity - Ensure agents can do everything users can do
Self-modification - Enable agents to safely evolve themselves
Product design - Progressive disclosure, latent demand, approval patterns
Mobile patterns - iOS storage, background execution, checkpoint/resume
Testing - Test agent-native apps for capability and parity
Refactoring - Make existing code more agent-native
Anti-patterns - Common mistakes and how to avoid them
Success criteria - Verify your architecture is agent-native
Hooks patterns - Hook events, decision control, MCP matchers, async hooks

Wait for response before proceeding.

设计架构 - 从零开始规划全新的Agent-Native系统
文件与工作区 - 将文件作为通用接口，采用共享工作区模式
工具设计 - 构建基础工具、动态能力发现、CRUD完整性
领域工具 - 了解何时添加领域工具而非仅使用基础工具
执行模式 - 完成信号、部分完成、上下文限制
系统提示词 - 在提示词中定义Agent行为、判断标准
上下文注入 - 将运行时应用状态注入Agent提示词
操作对等性 - 确保Agent能完成用户可执行的所有操作
自修改 - 允许Agent安全地自我演进
产品设计 - 渐进式披露、潜在需求、审批模式
移动模式 - iOS存储、后台执行、检查点/恢复
测试 - 针对能力和对等性测试Agent-Native应用
重构 - 让现有代码更贴合Agent-Native特性
反模式 - 常见错误及规避方法
成功标准 - 验证你的架构是否符合Agent-Native特性
钩子模式 - 钩子事件、决策控制、MCP匹配器、异步钩子

继续前请等待响应。

Reference Routing

参考文档指引

Response	Action
1, "design", "architecture", "plan"	Read architecture-patterns.md, then apply Architecture Checklist below
2, "files", "workspace", "filesystem"	Read files-universal-interface.md and shared-workspace-architecture.md
3, "tool", "mcp", "primitive", "crud"	Read mcp-tool-design.md
4, "domain tool", "when to add"	Read from-primitives-to-domain-tools.md
5, "execution", "completion", "loop"	Read agent-execution-patterns.md
6, "prompt", "system prompt", "behavior"	Read system-prompt-design.md
7, "context", "inject", "runtime", "dynamic"	Read dynamic-context-injection.md
8, "parity", "ui action", "capability map"	Read action-parity-discipline.md
9, "self-modify", "evolve", "git"	Read self-modification.md
10, "product", "progressive", "approval", "latent demand"	Read product-implications.md
11, "mobile", "ios", "android", "background", "checkpoint"	Read mobile-patterns.md
11a, "icloud", "storage", "documents", "file state", "entitlement"	Read mobile-storage.md
11b, "background task", "battery", "on-device", "cloud routing"	Read mobile-execution.md
11c, "model tier", "token budget", "cost-aware", "batch", "caching"	Read mobile-cost.md
12, "test", "testing", "verify", "validate"	Read agent-native-testing.md
13, "review", "refactor", "existing"	Read refactoring-to-prompt-native.md
14, "anti-pattern", "mistake", "wrong"	Read anti-patterns.md
15, "success", "criteria", "verify", "checklist"	Read success-criteria.md
16, "hook", "hooks", "PreToolUse", "decision control", "async hook", "permissionDecision"	Read hooks-patterns.md
0, "quick start", "getting started", "overview", "introduction"	Read quick-start.md

After reading the reference, apply those patterns to the user's specific context.

响应内容	操作
1, "design", "architecture", "plan"	阅读architecture-patterns.md，然后应用下方的架构评审清单
2, "files", "workspace", "filesystem"	阅读files-universal-interface.md和shared-workspace-architecture.md
3, "tool", "mcp", "primitive", "crud"	阅读mcp-tool-design.md
4, "domain tool", "when to add"	阅读from-primitives-to-domain-tools.md
5, "execution", "completion", "loop"	阅读agent-execution-patterns.md
6, "prompt", "system prompt", "behavior"	阅读system-prompt-design.md
7, "context", "inject", "runtime", "dynamic"	阅读dynamic-context-injection.md
8, "parity", "ui action", "capability map"	阅读action-parity-discipline.md
9, "self-modify", "evolve", "git"	阅读self-modification.md
10, "product", "progressive", "approval", "latent demand"	阅读product-implications.md
11, "mobile", "ios", "android", "background", "checkpoint"	阅读mobile-patterns.md
11a, "icloud", "storage", "documents", "file state", "entitlement"	阅读mobile-storage.md
11b, "background task", "battery", "on-device", "cloud routing"	阅读mobile-execution.md
11c, "model tier", "token budget", "cost-aware", "batch", "caching"	阅读mobile-cost.md
12, "test", "testing", "verify", "validate"	阅读agent-native-testing.md
13, "review", "refactor", "existing"	阅读refactoring-to-prompt-native.md
14, "anti-pattern", "mistake", "wrong"	阅读anti-patterns.md
15, "success", "criteria", "verify", "checklist"	阅读success-criteria.md
16, "hook", "hooks", "PreToolUse", "decision control", "async hook", "permissionDecision"	阅读hooks-patterns.md
0, "quick start", "getting started", "overview", "introduction"	阅读quick-start.md

阅读参考文档后，将这些模式应用到用户的具体场景中。

Architecture Review Checklist

架构评审清单

When designing an agent-native system, verify these before implementation:

设计Agent-Native系统时，请在实现前验证以下内容：

Core Principles

核心原则

Parity: Every UI action has a corresponding agent capability
Granularity: Tools are primitives; features are prompt-defined outcomes
Composability: New features can be added via prompts alone
Emergent Capability: Agent can handle open-ended requests in its domain

对等性（Parity）： 每个UI操作都有对应的Agent能力
粒度（Granularity）： 工具为基础组件；功能为提示词定义的结果
可组合性（Composability）： 仅通过提示词即可添加新功能
涌现能力（Emergent Capability）： Agent能处理其领域内的开放式请求

Tool Design

工具设计

Dynamic vs Static: For external APIs where agent should have full access, use Dynamic Capability Discovery
CRUD Completeness: Every entity has create, read, update, AND delete
Primitives over Workflows: Tools expose atomic capabilities; compose workflows in prompts
API as Validator: Use
```
z.string()
```
inputs when the API validates, not
```
z.enum()
```
Eval Gate: 10 Q/A pairs in CI (read-only, multi-hop, closed-data), 9/10 pass threshold. See mcp-tool-design.md Evaluation section.

动态 vs 静态： 对于Agent应拥有完全访问权限的外部API，使用动态能力发现（Dynamic Capability Discovery）
CRUD完整性： 每个实体都具备创建（create）、读取（read）、更新（update）和删除（delete）能力
优先基础组件而非工作流： 工具暴露原子能力；在提示词中组合工作流
API作为验证器： 当API进行验证时，使用
```
z.string()
```
输入而非
```
z.enum()
```
评估关卡： CI中包含10组问答对（只读、多跳、封闭数据），需达到9/10的通过率阈值。详情请参阅mcp-tool-design.md中的评估章节。

Files & Workspace

文件与工作区

Shared Workspace: Agent and user work in same data space
context.md Pattern: Agent reads/updates context file for accumulated knowledge
File Organization: Entity-scoped directories with consistent naming
Context Durability: Incremental progress writes (WAL pattern) so interrupted tasks resume from last checkpoint

共享工作区： Agent与用户在同一数据空间工作
context.md模式： Agent读取/更新上下文文件以积累知识
文件组织： 按实体划分目录，命名保持一致
上下文持久性： 采用增量进度写入（WAL模式），使中断的任务能从最后一个检查点恢复

Agent Execution

Agent执行

Completion Signals: Agent has explicit
```
complete_task
```
tool (not heuristic detection)
Partial Completion: Multi-step tasks track progress for resume
Context Limits: Designed for bounded context from the start
Validate-Before-Run: Agent previews planned actions before executing destructive operations

完成信号： Agent拥有明确的
```
complete_task
```
工具（而非启发式检测）
部分完成： 多步骤任务跟踪进度以便恢复
上下文限制： 从设计之初就考虑有限上下文
先验证再执行： Agent在执行破坏性操作前预览计划的动作

Context Injection

上下文注入

Available Resources: System prompt includes what exists (files, data, types)
Available Capabilities: System prompt documents tools with user vocabulary
Dynamic Context: Context refreshes for long sessions (or provide
```
refresh_context
```
tool)
Trust levels for loaded content: System prompt distinguishes trusted (developer-authored) from untrusted (user input, retrieved docs, tool outputs); untrusted text is data, never instructions. See dynamic-context-injection.md Trust Levels section for the prompt-injection defense details.

可用资源： 系统提示词包含现有资源（文件、数据、类型）
可用能力： 系统提示词用用户熟悉的词汇记录工具信息
动态上下文： 长会话中刷新上下文（或提供
```
refresh_context
```
工具）
加载内容的信任级别： 系统提示词区分可信内容（开发者编写）与不可信内容（用户输入、检索文档、工具输出）；不可信文本仅作为数据，绝不作为指令。详情请参阅dynamic-context-injection.md中的信任级别章节，了解提示词注入防御细节。

UI Integration

UI集成

Agent -> UI: Agent changes reflect in UI (shared service, file watching, or event bus)
No Silent Actions: Agent writes trigger UI updates immediately
Capability Discovery: Users can learn what agent can do

Agent -> UI： Agent的更改同步反映到UI中（共享服务、文件监听或事件总线）
无静默操作： Agent的写入操作立即触发UI更新
能力发现： 用户可了解Agent能执行的操作

Governance

治理

Approval Gates: Destructive or irreversible actions require user confirmation
Audit Trail: Agent actions logged with timestamp, tool, and outcome
Scope Boundaries: Agent cannot access resources outside its designated workspace

审批关卡： 破坏性或不可逆操作需用户确认
审计追踪： Agent操作记录包含时间戳、工具和结果
范围边界： Agent无法访问指定工作区外的资源

Hooks & Governance Automation

钩子与治理自动化

Mobile (if applicable)

移动端（如适用）

Checkpoint/Resume: Handle iOS app suspension gracefully
iCloud Storage: iCloud-first with local fallback for multi-device sync
Cost Awareness: Model tier selection (Haiku/Sonnet/Opus)

When designing architecture, explicitly address each checkbox in the plan.

检查点/恢复： 优雅处理iOS应用暂停情况
iCloud存储： 优先使用iCloud，本地存储作为多设备同步的 fallback
成本感知： 模型层级选择（Haiku/Sonnet/Opus）

设计架构时，请在方案中明确说明每个检查项的处理方式。