Agent-Native 架构

核心原则

五大原则指导 Agent-Native 的设计。详细说明、示例及测试标准请参阅 core-principles.md。

关注领域选择

1. 架构设计 —— 从零开始规划全新的 Agent-Native 系统
2. 文件与工作区 —— 将文件作为通用接口，采用共享工作区模式
3. 工具设计 —— 构建基础工具（primitives）、动态能力发现机制、CRUD 完备性
4. 领域专用工具 —— 明确何时应引入领域专用工具，何时应坚持使用 primitives
5. 执行模式 —— 完成信号、部分完成、上下文长度限制
6. 系统 prompt —— 在 prompt 中定义 Agent 行为与判断准则
7. 上下文注入 —— 将运行时应用状态注入 Agent 的 prompt
8. 操作对等（Action Parity） —— 确保 Agent 能执行用户所能进行的所有操作
9. 自我修改 —— 支持 Agent 安全地演进自身
10. 产品设计 —— 渐进式披露、潜在需求识别、审批流程模式
11. 移动端模式 —— iOS 存储机制、后台执行、断点续传（checkpoint/resume）
12. 测试 —— 针对能力完备性与操作对等性测试 Agent-Native 应用
13. 重构 —— 将现有代码改造为更符合 Agent-Native 的形态
14. 反模式 —— 常见错误及其规避方法
15. 成功标准 —— 验证你的架构是否真正符合 Agent-Native 要求
16. Hook 模式 —— 事件 Hook、决策控制、MCP 匹配器、异步 Hook

请等待响应后再继续下一步。

参考路由表

阅读完对应参考文档后，请将其中的模式适配到用户的特定上下文中。

架构审查清单

在设计 Agent-Native 系统时，请在**实施前**逐一确认以下各项：

核心原则

• 能力对等（Parity）：每个 UI 操作均有对应的 Agent 能力支撑
• 细粒度（Granularity）：工具为 primitives；功能由 prompt 定义并驱动结果
• 可组合性（Composability）：新功能可通过 prompt 单独添加，无需新增代码
• 涌现能力（Emergent Capability）：Agent 可在其所属领域内处理开放性请求

工具设计

• 动态 vs 静态：对于需赋予 Agent 全面访问权限的外部 API，应采用动态能力发现（Dynamic Capability Discovery）
• CRUD 完备性：每个实体均支持 create、read、update 和 delete 四种操作
• 优先 primitives，而非预设工作流：工具暴露原子级能力；工作流逻辑应在 prompt 中组合
• API 作为校验器：当 API 自身具备字段校验能力时，使用 z.string() 输入类型，而非 z.enum()
• 评估门控（Eval Gate）：CI 中配置 10 组问答对（只读、多跳、封闭数据），通过率不低于 9/10。详见 mcp-tool-design.md 中“评估”章节。

文件与工作区

• 共享工作区：Agent 与用户在同一数据空间中协作
• context.md 模式：Agent 通过读写 context 文件来累积和维护知识
• 文件组织结构：按实体划分目录，命名规范统一
• 上下文持久性：采用增量式写入（WAL 模式），确保中断任务可在最近检查点恢复

Agent 执行

• 完成信号：Agent 提供显式的 complete_task 工具（而非启发式检测）
• 部分完成：多步骤任务需跟踪进度，以支持断点续传
• 上下文长度限制：自设计之初即面向有界上下文进行优化
• 执行前校验（Validate-Before-Run）：Agent 在执行可能造成破坏的操作前，须预览拟执行动作

上下文注入

• 可用资源声明：系统 prompt 明确列出当前存在的资源（如文件、数据、类型）
• 可用能力说明：系统 prompt 使用用户易懂的语言描述各工具能力
• 动态上下文更新：长会话期间定期刷新上下文（或提供 refresh_context 工具）
• 加载内容的信任等级：系统 prompt 需区分可信内容（开发者编写）与不可信内容（用户输入、检索文档、工具输出）；不可信文本仅作为数据使用，绝不可视为指令。具体防御机制参见 dynamic-context-injection.md 中“信任等级”章节。

UI 集成

• Agent → UI 同步：Agent 的变更需实时反映在 UI 上（通过共享服务、文件监听或事件总线实现）
• 无静默操作：Agent 的写入操作必须立即触发 UI 更新
• 能力发现机制：用户可便捷了解 Agent 当前支持哪些能力

治理机制

• 审批门控：所有具有破坏性或不可逆性的操作均需用户显式确认
• 审计日志：Agent 的每项操作均记录时间戳、所用工具及执行结果
• 作用域边界：Agent 不得访问其指定工作区以外的任何资源

Hook 与治理自动化

• 事件覆盖范围：Agent 上下文中仅定义 6 类 Hook 事件（PreToolUse、PostToolUse、PermissionRequest、PostToolUseFailure、Stop / SubagentStop）；会话生命周期逻辑应由 orchestrator 统一管理
• 决策门控：PreToolUse Hook 应用于实施工具级策略（允许 / 拒绝 / 请求确认 / 推迟），避免硬编码校验逻辑
• 完成门控：SubagentStop Hook 可阻止在仍有待验证步骤时过早结束子任务
• MCP 匹配器：通过正则表达式按 server 和 operation 匹配工具，实现基于能力的安全管控
• 双层配置：共享策略提交至版本库，个人覆盖配置被 git 忽略，各 Hook 可独立启用/禁用

移动端（如适用）

• 断点续传（Checkpoint/Resume）：优雅处理 iOS 应用挂起场景
• iCloud 存储：默认优先使用 iCloud，并提供本地存储兜底方案，保障多设备同步
• 成本感知：根据模型层级（Haiku / Sonnet / Opus）智能选择推理模型

在进行架构设计时，须在设计方案中显式回应每一项复选框所列要求。