agent-native

Agent 原生

Agent 原生应用将 Agent 视为一等用户。人类通过 UI 能完成的任何操作，Agent 都可以通过工具实现。功能是通过提示词描述的结果，由 Agent 使用原子工具实现，并循环执行直到完成。

参考文件

文件	阅读时机
references/core-principles.md	默认：理解对等性、粒度、可组合性和涌现能力
references/tool-design.md	设计工具——原子基元、CRUD、领域工具、动态发现
references/files-and-context.md	状态管理——实体目录、context.md、上下文注入、文件与数据库
references/agent-ui-communication.md	构建 Agent 反馈——完成信号、部分完成、事件类型
references/mobile-specifics.md	iOS/移动端——检查点/恢复、iCloud 存储、后台执行

核心原则

• 对等性 — Agent 能实现用户通过 UI 可以完成的任何操作。构建能力映射；弥补每一处差距。
• 粒度 — 工具是原子基元。判断和决策逻辑应放在提示词中，而非工具实现中。要改变行为，就修改文字描述，而不是代码。

  # Anti-pattern: workflow-shaped tool
  analyze_and_organize(folder)  # bundles judgment into code
  
  # Agent-native: atomic primitives
  list_files(folder) → read_file(path) → move_file(src, dst) → write_file(path, content)
  # The agent decides what to move and where — judgment stays in the prompt
  

• 可组合性 — 新功能 = 新提示词。借助原子工具和对等性，只需描述结果，Agent 就会循环执行直到实现目标。
• 涌现能力 — Agent 能处理你未专门设计的请求。观察用户的需求；将涌现的模式整理成规范。
• 持续改进 — 状态通过上下文文件持久化。更新提示词即可惠及所有用户，无需发布代码。

设计工作流

1. 能力审计 — 将每个 UI 操作映射到对应的 Agent 操作。弥补任何差距。阅读 core-principles.md。
2. 工具面设计 — 为每个实体定义原子基元（CRUD）。只有在词汇、护栏或效率方面确有需要时，才添加领域工具。阅读 tool-design.md。
3. 上下文和状态规划 — 设计 context.md 文件、实体目录结构和系统提示词注入。阅读 files-and-context.md。
4. Agent-UI 反馈设计 — 定义完成信号、事件类型、共享工作区和审批关卡。阅读 agent-ui-communication.md。
5. 验证 — 执行下方的清单。描述一个尚未构建的结果，并测试 Agent 能否自行找到实现方法。

设计清单

设计期间复制并跟踪：

Agent-native design progress:
- [ ] Capability map: every UI action has an agent equivalent
- [ ] Tools are atomic primitives (judgment in prompts, not tools)
- [ ] Every entity has full CRUD tool coverage
- [ ] System prompt injects available resources and capabilities
- [ ] Agents and users share the same data space
- [ ] Agent actions reflect immediately in UI
- [ ] Completion is signaled explicitly (no heuristic detection)
- [ ] External APIs use dynamic capability discovery where possible
- [ ] Approval model matches stakes and reversibility
- [ ] Ultimate test: describe an unbuilt outcome — can the agent figure it out?

验证循环

发布前，确认：

1. 能力覆盖 — 随机选择 5 个 UI 操作；确认 Agent 无需修改代码就能逐一完成。
2. 工具原子性 — 检查每个工具；如果其中包含 if/else 决策逻辑，就将其拆分。
3. 上下文完整性 — 清除 Agent 的上下文并启动会话；它是否仍然知道有哪些内容？
4. 端到端场景 — 给 Agent 一个你从未明确构建过的结果。它能否组合工具来实现？

反模式

• 将 Agent 当作路由器 — Agent 将请求路由到你的代码，而不是自行判断并采取行动；你构建的是调度器，而非 Agent。
• 工作流形状的工具 — analyze_and_organize 将决策逻辑打包进工具；应拆分为 read_file、move_file、write_file。
• 孤立的 UI 操作 — 用户能做某事，但 Agent 做不到；这会破坏对等性。
• 上下文匮乏 — Agent 不知道有哪些内容；在每个系统提示词中注入资源和能力信息。
• 毫无缘由的关卡 — 原子基元本应也能完成操作，却只有领域工具这一条路径；默认开放。
• 启发式完成检测 — 通过连续的空闲迭代判断任务已完成；应要求显式调用完成工具。
• 静态 API 映射 — 50 个端点对应 50 个工具；应使用发现 + 访问。

相关技能

• define-architecture — 在转向 Agent 原生之前，规划仓库结构和模块边界
• agents-md — 审查 CLAUDE.md / AGENTS.md 中 Agent 指令的质量