Agent 顶层架构设计模式¶
从 DeepSeek Harness 源码中提炼出的 10 个顶尖 Agent 架构设计原则。
通读 DeepSeek Harness 的源码，我们可以清晰地看到 DeepSeek 团队在构建生产级 Coding Agent 时深思熟虑的架构哲学。这些原则对于设计任何现代 AI Agent 系统都具有极其宝贵的指导价值。
10 大核心架构设计原则¶
原则 1：万物皆插件，消灭特权内核（No Privileged Kernel）¶
不要把 Agent 做成一团死板的单体大对象。将 LLM 适配、工具集、提示词、会话存储甚至循环驱动器本身都抽象为微内核插件。任何能力都可以被动态替换、扩展和声明式覆盖（Patch）。
原则 2：模型可见即已记录（What is Visible is Logged）¶
模型看到的上下文必须严格来自确定性的事件流投影（Event Sourcing）。永远不要在内存中临时拼接未落盘的 Prompt 片段，这是保证会话可重放（Replay）、状态可审计（Audit）与错误可复现的基础。
原则 3：严格区分 Turn 与 Step（Turn-Step Dual Level）¶
清晰界定外层业务闭环（Turn）与单次模型推理执行（Step）。Turn 负责与用户生命周期和任务完成度交互，Step 负责单次 Prompt 组装、流式推理与工具流水线。
原则 4：工具执行的三阶段防御流水线（Three-Phase Tool Pipeline）¶
工具调用绝不是直接调用函数，必须经过：
1. pre-execute：参数 Schema 校验、权限沙箱把关与用户交互审批；
2. execute：带超时中断与进程隔离的受控执行；
3. post-execute：敏感信息脱敏与巨型输出截流外溢（Spill）。
原则 5：操作系统级纵深防御沙箱（OS-Native Sandboxing）¶
不要寄希望于脆弱的应用层路径检查。在 OS 系统调用层使用 Linux Landlock 或 macOS sandbox-exec，结合三级权限模式（read-only / workspace-write / danger-full-access）和前置观察策略（Fs Observation Policy），构筑真正的安全护城河。
原则 6：代码编排优于复杂图配置（Script-as-Orchestration）¶
对于复杂的批量多 Agent 协作任务，不要让大模型在漫长的自然语言中迷失，也不要强求臃肿的 JSON 图配置。赋予 Agent 编写隔离 JavaScript 脚本（Workflow）的能力，利用 pipeline() 和 parallel() 高效调度多 Agent 集群。
原则 7：Fresh-Agent 零污染迭代飞轮（The Ralph Paradigm）¶
面对超大规模工程任务，上下文污染（Context Bleed）是 Agent 崩溃的头号杀手。采用 Ralph 范式：每一轮启用零历史负担的 Fresh-Agent，以磁盘物理工作区为唯一持久真理，以有界结构化报告作为轮次交接棒。
原则 8：主会话与子任务的上下文物理隔离（Context Isolation）¶
通过 subagent 将调研、审查等繁重工作委托到独立的子会话中执行，后台非阻塞运行并通过 Inbox 异步结算结果，保护主会话上下文始终聚焦核心主线。
原则 9：双向截流与智能压缩（Spill & Compaction）¶
在工具输出端使用 Spill 机制将大输出自动截流存盘并提供按需分页；在对话历史端使用 Compaction 机制进行滑动窗口智能摘要。双管齐下确保上下文窗口永远不爆。
原则 10：全栈强类型契约（End-to-End Type Safety）¶
从后端的 Cordis 模块扩展（Module Augmentation），到 Typert 跨端 RPC 协议，再到工具参数的 JSON Schema 严格校验，全链路强类型推导杜绝运行时低级错误。
结语：踏上你的 Agent 架构探索之旅¶
DeepSeek Harness 展示了生产级 Coding Agent 应当具备的工业标准与优雅美感。
希望这份伴读指南能成为你在 Agent 架构设计之路上的灯塔。现在，打开你的编辑器，对照源码，开始亲手构建属于你的下一代智能体系统吧！