Agent 应用工程架构：模块、挑战与传统工程迁移

一、总览：Agent 应用的 12 个模块

Agent 应用本质上是一个以模型为决策核心、以工具为行动边界、以上下文和状态为运行记忆、以权限和评估为治理闭环的工程系统。模块划分不是为了"功能多"，而是为了把不确定模型放进可治理的软件边界：输入要归一，状态要可恢复，工具要可审计，权限要可证明，质量要可回放。

先给全文结论（主轴）。 Agent 应用和传统软件的差别只在两个根因 ：决策核心从确定性代码变成概率模型 、输入面从结构化字段变成自然语言 ；除此之外，它仍是一套要管状态、重试、权限、可观测、发布的普通分布式软件系统。由此得到一张贯穿全文的判断表------拿到任何 Agent 问题先归类：

• 旧问题换皮（约 80%）：传统工程早有成熟解，复用心智模型即可，重新发明只会更差；
• 真正新维度（少数）：只有回溯到那两个根因的问题，传统模式才失效、机制必须重做（且"维度新"不等于"机制从零造"，多半能借自 ML / 分布式 / CI）。

误判双向昂贵：把新问题当旧的，会用拦不住的传统机制兜底；把旧问题当新的，会为一个 Redux 就能解的事发明"Agent 专用"轮子。后文 §2--§3 按 12 模块展开挑战与落地，§4 用 12 张传统对照表把这张判断表逐格量化，并收敛出 4 个真·新增维度。

claude code 相关内容可以参考：https://blog.csdn.net/qq_40369829/article/details/160119051

1.1 分层架构图

#mermaid-svg-lU3XU9vi9C9GQE2d{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-lU3XU9vi9C9GQE2d .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-lU3XU9vi9C9GQE2d .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-lU3XU9vi9C9GQE2d .error-icon{fill:#552222;}#mermaid-svg-lU3XU9vi9C9GQE2d .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-lU3XU9vi9C9GQE2d .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-lU3XU9vi9C9GQE2d .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-lU3XU9vi9C9GQE2d .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-lU3XU9vi9C9GQE2d .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-lU3XU9vi9C9GQE2d .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-lU3XU9vi9C9GQE2d .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-lU3XU9vi9C9GQE2d .marker{fill:#333333;stroke:#333333;}#mermaid-svg-lU3XU9vi9C9GQE2d .marker.cross{stroke:#333333;}#mermaid-svg-lU3XU9vi9C9GQE2d svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-lU3XU9vi9C9GQE2d p{margin:0;}#mermaid-svg-lU3XU9vi9C9GQE2d .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-lU3XU9vi9C9GQE2d .cluster-label text{fill:#333;}#mermaid-svg-lU3XU9vi9C9GQE2d .cluster-label span{color:#333;}#mermaid-svg-lU3XU9vi9C9GQE2d .cluster-label span p{background-color:transparent;}#mermaid-svg-lU3XU9vi9C9GQE2d .label text,#mermaid-svg-lU3XU9vi9C9GQE2d span{fill:#333;color:#333;}#mermaid-svg-lU3XU9vi9C9GQE2d .node rect,#mermaid-svg-lU3XU9vi9C9GQE2d .node circle,#mermaid-svg-lU3XU9vi9C9GQE2d .node ellipse,#mermaid-svg-lU3XU9vi9C9GQE2d .node polygon,#mermaid-svg-lU3XU9vi9C9GQE2d .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-lU3XU9vi9C9GQE2d .rough-node .label text,#mermaid-svg-lU3XU9vi9C9GQE2d .node .label text,#mermaid-svg-lU3XU9vi9C9GQE2d .image-shape .label,#mermaid-svg-lU3XU9vi9C9GQE2d .icon-shape .label{text-anchor:middle;}#mermaid-svg-lU3XU9vi9C9GQE2d .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-lU3XU9vi9C9GQE2d .rough-node .label,#mermaid-svg-lU3XU9vi9C9GQE2d .node .label,#mermaid-svg-lU3XU9vi9C9GQE2d .image-shape .label,#mermaid-svg-lU3XU9vi9C9GQE2d .icon-shape .label{text-align:center;}#mermaid-svg-lU3XU9vi9C9GQE2d .node.clickable{cursor:pointer;}#mermaid-svg-lU3XU9vi9C9GQE2d .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-lU3XU9vi9C9GQE2d .arrowheadPath{fill:#333333;}#mermaid-svg-lU3XU9vi9C9GQE2d .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-lU3XU9vi9C9GQE2d .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-lU3XU9vi9C9GQE2d .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-lU3XU9vi9C9GQE2d .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-lU3XU9vi9C9GQE2d .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-lU3XU9vi9C9GQE2d .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-lU3XU9vi9C9GQE2d .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-lU3XU9vi9C9GQE2d .cluster text{fill:#333;}#mermaid-svg-lU3XU9vi9C9GQE2d .cluster span{color:#333;}#mermaid-svg-lU3XU9vi9C9GQE2d div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-lU3XU9vi9C9GQE2d .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-lU3XU9vi9C9GQE2d rect.text{fill:none;stroke-width:0;}#mermaid-svg-lU3XU9vi9C9GQE2d .icon-shape,#mermaid-svg-lU3XU9vi9C9GQE2d .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-lU3XU9vi9C9GQE2d .icon-shape p,#mermaid-svg-lU3XU9vi9C9GQE2d .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-lU3XU9vi9C9GQE2d .icon-shape .label rect,#mermaid-svg-lU3XU9vi9C9GQE2d .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-lU3XU9vi9C9GQE2d .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-lU3XU9vi9C9GQE2d .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-lU3XU9vi9C9GQE2d :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 横切治理层 / 控制面
运行执行层
认知决策层
策略 / 权限 / 审批 / 沙箱
工具权限 / 执行边界
trace / metrics / eval
经验 / 数据集 / 版本回流
能力演进
用户 / 外部事件
Entry / Ingress

入口与接入
Profile / Perception

角色与感知
Context / Memory

上下文与记忆
Planning / Reasoning

规划与推理
Orchestration / Lifecycle

编排与生命周期
Multi-Agent Collaboration

多 Agent 协作
Extension / Capability

扩展与能力接入
Tool / Action Execution

工具与动作执行
Environment / State

环境与状态
Safety / Governance

安全与治理
Evaluation / Observability

评估与可观测性
Learning / Evolution

学习与演化
外部系统 / 工具 / 文件 / API / 人工审批

1.2 模块分层、命名与依据

层	模块	关注点	边界说明	命名依据
接入层	Entry / Ingress / 入口与接入	请求归一、运行模式、接入协议	直接对接用户和外部事件；只做归一化和准入，不承载认知决策。它更接近 DDD / 六边形架构里的 inbound adapter，不是外部能力接口层。	architecture.md §3 入口 / 初始化层；gpt-deep-research-report.md「模块对照总表 / 集成/接口层」
认知决策层	Profile / Perception / 角色与感知	输入解释、角色约束	处理本轮输入语义和行为锚点；不负责长期信息生命周期。	2308.11432.md §2.1.1 Profiling Module；2309.07864.md §3.2 Perception；gemini-deep-research-report.md 第二章
认知决策层	Context / Memory / 上下文与记忆	模型可见信息、记忆生命周期	Context 是面向模型的投影；State 是系统事实源。这里定义信息选择、压缩、检索和写入策略。	2512.13564.md §2.2 Agent Memory Systems；architecture.md §10 Context 体系；gemini-deep-research-report.md 第三章
认知决策层	Planning / Reasoning / 规划与推理	任务拆解、推理策略、下一步意图	由 LLM / planner / critic 产生决策意图；不负责运行时推进和副作用。	2308.11432.md §2.1.3 Planning Module；2503.21460.md §2.1.3 Planning Capability；gpt-deep-research-report.md「决策/规划」
运行执行层	Orchestration / Lifecycle / 编排与生命周期	回合推进、LLM/工具/Agent 路由、停止与恢复	把计划推进为可执行回合；负责路由、compact 触发、hooks、停止和恢复。	architecture.md §4 引擎层、§9 Command、§10 Context；gpt-deep-research-report.md「对话管理/交互」「Anthropic workflow patterns」
运行执行层	Tool / Action Execution / 工具与动作执行	工具协议、副作用执行	工具是模型产生真实副作用的边界，必须有 schema、权限、审批、执行、审计的统一流水线。	2308.11432.md §2.1.4 Action Module；2309.07864.md §3.3 Action；architecture.md §6 工具子层
运行执行层	Environment / State / 环境与状态	系统事实源、运行态、恢复点	维护系统真实运行态；给模型看的状态摘要应通过 Context 投影。	2512.13564.md §2.1 LLM-based Agent Systems；2412.17481.md §2.2 Environment；architecture.md §11 状态体系
运行执行层	Extension / Capability / 扩展与能力接入	外部能力注册与注入	MCP、Plugin、Skill、子 Agent、外部 API 需要统一注册、隔离和版本治理。	architecture.md §7 能力子层；gpt-deep-research-report.md「集成/接口层」
运行执行层	Multi-Agent Collaboration / 多 Agent 协作	多 Agent 分工、通信、裁决	多 Agent 是横向扩展认知和执行能力的方式，但本质是分布式协作问题。	2501.06322.md §4 Methodology；2412.17481.md §3-§6；gemini-deep-research-report.md 第六章
横切治理层	Safety / Governance / 安全与治理	策略、权限、审批、沙箱	横切接入、认知和执行链路；安全不是最终输出过滤。	2507.21504.md §3.4 Safety and Alignment；2601.01743.md §6.6 Safety and Compliance、§7.1 Verification and Trustworthy Tool Execution；architecture.md §2.2.1、§6.4、§8.4
横切治理层	Evaluation / Observability / 评估与可观测性	trace、指标、评估、回放	贯穿每个回合和工具调用；Agent 质量存在于轨迹中，而不是只在最终文本里。	2507.21504.md §2 Taxonomy、§3 Evaluation Objectives、§4 Evaluation Process；2601.01743.md §6；gpt-deep-research-report.md「监控与可观测性」「指标体系与故障排查」
横切治理层	Learning / Evolution / 学习与演化	经验沉淀、版本迭代	从观测和评估回流到认知、能力和数据集；必须受版本和发布门禁约束。	2308.11432.md §2.2 Agent Capability Acquisition；2503.21460.md §2.3 Agent Evolution；2512.13564.md §5 Memory Evolution

二、模块挑战、解决方案与依据

2.1 Entry / Ingress / 入口与接入

作用：把 CLI、UI、SDK、headless、后台任务、子 Agent、远程 bridge 等入口统一成内部可执行的会话与运行模式。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
多入口导致同一请求在上下文、权限、输出协议上表现不一致。	建立 canonical request / session / run mode；入口只做归一化和分发，业务语义下沉到主循环。	architecture.md §3.1-§3.3；gpt-deep-research-report.md「集成/接口层」	architecture.md §3.4.3、§5.4.2、§9.4.3	Commander preAction/action 分层复用初始化；UI/headless/remote 输入统一归一为 message / command / event；remote/headless 命令在命令层裁剪。
启动链路重、首响慢，用户感知会先于模型质量变差。	区分快速路径和完整主循环；延迟加载非必要模块；入口阶段只做必须的信任、配置和模式判断。	architecture.md §3.4；gpt-deep-research-report.md「感知/输入」	architecture.md §3.4.1、§3.4.2	cli.tsx 先处理 --version、daemon、remote-control 等 fast path；keychain/MDM fire-and-forget 预取；信任前只应用安全环境变量，信任后再启用完整项目配置。
SDK / remote bridge / headless / 外部事件等接入通道增加后，请求 schema、认证身份、租户 / 会话边界容易不一致。	用统一 inbound adapter 承接输入协议；做请求契约校验、来源标记、run mode / session 归一、允许列表和背压。外部能力 schema 与认证治理下沉到 Extension / Capability。	gpt-deep-research-report.md「集成/接口层」	architecture.md §5.4.2、§9.4.3；外部能力侧见 §7.4.5、§8.4.1	入口侧把 UI / headless / remote 输入归一为 message / command / event；remote/headless 命令在命令层裁剪。外部能力侧再落到 Tool / Command / AgentDefinition / AppState，并由 MCP schema 刷新、re-auth、命名空间和护栏控制漂移。

2.2 Profile / Perception / 角色与感知

作用：定义 Agent 的身份、行为边界、沟通风格和任务优先级，同时把文本、文件、图像、音频、UI 事件等输入转成模型可处理的结构化信号。它解决的是"这次输入应该如何被解释"，不是"历史信息如何被长期保存"。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
长会话中角色漂移，模型逐渐忘记身份、风格和限制。	角色配置结构化、版本化，并在关键推理节点重新注入；把角色约束和任务上下文分层。	2308.11432.md §2.1.1；2503.21460.md §2.1.1；gemini-deep-research-report.md §2.2-§2.3	architecture.md §10.4.7	按 system / project / Skill / Agent / mode 划分规则作用域；compact、resume、Agent 调用时补回必要规则，避免 Skill、plan mode、子 Agent 规则漂移。
多模态输入存在噪声、延迟、时间对齐和解析失败。	做流式输入归一、模态解析、置信度降级；复杂多模态任务引入 planner-critic 或专用解析器。	2309.07864.md §3.2；gemini-deep-research-report.md §2.1-§2.3；gpt-deep-research-report.md「感知/输入」	architecture.md §5.4.2、§10.4.6	终端输入、粘贴、文件、图片、remote / bridge 事件先归一为 message / attachment / command / event，并保留来源和信任边界。
外部输入可能同时携带用户数据、恶意指令和上下文污染。	在入口即区分指令、数据和环境描述；敏感字段分级，外部数据标记为不可信。	architecture.md §10.4；gpt-deep-research-report.md「安全与权限」	architecture.md §10.4.6、§8.4.1	用 tool_result、<system-reminder>、LOCAL_COMMAND_CAVEAT、isMeta/[id] 区分真实用户意图、工具资料、本地命令输出和系统注入资料。
容易和 Context / Memory 混淆。	角色与感知只负责输入解释和行为锚点；上下文与记忆负责信息选择、压缩、检索、写入和过期。	2308.11432.md §2.1.1-§2.1.2；2512.13564.md §2.2	architecture.md §10.4.7、§11.4.4	规则作用域由 §10.4.7 管，模型可见 Context 是请求快照；AppState 是系统事实源，不把完整运行态直接塞进模型。

2.3 Context / Memory / 上下文与记忆

作用：管理当前回合上下文、历史消息、工具结果、用户偏好、长期事实、任务状态和可恢复检查点。它负责"信息资产和信息预算"，包括压缩策略、摘要形态、缓存层级和记忆写入规则。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
上下文持续膨胀，噪声、日志和中间步骤挤占有效信息。	分层记忆与主动压缩：短期上下文、工作记忆、长期事实、工具结果引用分开管理。	2512.13564.md §2.2、§3、§5；architecture.md §10.4；gemini-deep-research-report.md §3.2-§3.3	architecture.md §10.4.5	成本阶梯处理：prompt cache 稳定前缀、超大工具结果外置、旧工具结果清理、context collapse / autocompact 摘要，长期记忆另走来源与作用域管理。
长期记忆检索可能召回陈旧、错误或跨租户污染的信息。	写入前做事实抽取、清洗、命名空间隔离、TTL、版本和完整性校验；检索后做重排和来源校验。	2512.13564.md §5.3；gpt-deep-research-report.md「记忆/状态管理」；gemini-deep-research-report.md §3.3	architecture.md §10.4.8	路径和作用域隔离污染半径；读回时保留来源与 mtime；发现与当前事实或用户纠正冲突时，由 Agent 用工具修正或移除。
主循环、compact、子 Agent、后台摘要看到的上下文不一致。	复用统一 context 构建协议；缓存层级显式化，避免各路径自行拼装系统提示词。	architecture.md §10.3-§10.4	architecture.md §10.4.3、§10.4.4	context.ts 统一生成 userContext/systemContext；主循环、Agent、compact、analyzeContext 复用同一套注入协议；缓存按失效频率分层。
和 Orchestration 都会提到 compact / 压缩，边界容易不清。	Context / Memory 定义压缩什么、压成什么、如何缓存和失效；Orchestration 只决定何时触发、触发后如何回到主循环。	architecture.md §4.4、§10.4	architecture.md §4.4.1、§10.4.4、§10.4.5	§10 定义压缩对象、成本阶梯和缓存边界；§4 主循环只负责按预算和生命周期触发，并把结果带回下一轮。

2.4 Planning / Reasoning / 规划与推理

作用：把目标拆成可执行步骤，并在每一步产出下一步意图，例如继续推理、调用工具、澄清、分派或停止。它负责"想清楚下一步是什么"，不负责驱动整个运行时状态机。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
长链任务中错误会逐步放大，计划抖动、工具空转和成本失控。	计划对象显式化，设置步骤、时间、token、并发和停止预算；planner 与 executor 分离。	2308.11432.md §2.1.3；2601.01743.md §4.1、§7.3；gpt-deep-research-report.md「决策/规划」	architecture.md §4.4.4、§10.4.5	模型只产出下一步意图；主循环负责状态推进、权限、工具执行、Stop hooks、token budget 和恢复。显式 planner / executor 服务仍是演进方向。
单线 CoT / ReAct 容易短视，遇到坏观察后难以恢复。	对复杂任务使用 ToT / GoT / MCTS、自我反思、critic、外部 planner 或 evaluator-optimizer。	2308.11432.md §2.1.3；gemini-deep-research-report.md §4.1-§4.3；2601.01743.md §5.7	architecture.md §4.4.2、§4.4.3、§4.4.4	主要靠 max_output_tokens 截断恢复、Stop hooks / 外部检查和状态机边界处理坏观察；没有宣称实现通用多分支 planner。
过早追求自由自治，会把不确定性放大到生产系统。	工作流优先，自治增量引入；先让固定流程、路由、并行、评审闭环稳定，再开放动态规划。	gpt-deep-research-report.md「执行摘要」「实施优先级与依赖」	architecture.md §4.4.4、§4.4.5、§12.1	先固定主循环、路由边界、工具并发、Stop hook / 回归闭环；动态 planner、多模型路由等放到 §12.1 演进问题。
和 Orchestration 都涉及"下一步"，容易被看成同一件事。	Planning / Reasoning 产出候选计划和决策依据；Orchestration / Lifecycle 负责执行路由、状态推进、停止、恢复和副作用边界。	architecture.md §4.1-§4.4；gpt-deep-research-report.md「决策/规划」「对话管理/交互」	architecture.md §4.4.4	文档明确边界：模型提出意图，编排层裁决和落地；tool_use、end_turn 都必须经过系统边界。

2.5 Tool / Action Execution / 工具与动作执行

作用：把模型意图转为真实动作，包括 API 调用、搜索、文件读写、命令执行、浏览器操作、数据库查询、代码执行和外部系统更新。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
工具参数非确定，JSON 破损、schema 不匹配和参数幻觉会中断流程。	严格 schema、值级校验、repair、默认值策略、错误回灌和契约测试。	2309.07864.md §3.3.2；gemini-deep-research-report.md §5.1-§5.3；architecture.md §6.2-§6.4	architecture.md §6.4.1、§6.4.2	统一 Tool 契约、schema parse、validateInput()、权限前置检查；失败收敛为错误型 tool_result。
工具调用会产生真实副作用，误调用、重复调用、越权调用的代价高。	工具可见性、权限决策、审批门、幂等键、补偿动作、审计记录必须进入统一执行流水线。	2308.11432.md §2.1.4；architecture.md §6.4；gpt-deep-research-report.md「执行/动作」	architecture.md §6.4.5	工具可见性、权限规则、Pre/PostToolUse hooks、审批门、模式收紧和 transcript / telemetry 统一进入执行链；幂等和补偿由具体业务工具补齐。
外部系统不稳定会触发重试风暴和成本燃烧。	超时、退避、断路器、重试预算、失败分类和快速失败；trace 中保留 tool span。	gemini-deep-research-report.md §5.2-§5.3；gpt-deep-research-report.md「执行/动作」	architecture.md §6.4.6、§7.4.5	工具失败先结构化回灌，不在工具层静默自旋；用超时 / 取消、有界 API retry、快速失败、认证重连和 tool span 定位问题。

2.6 Environment / State / 环境与状态

作用：维护 Agent 所在世界的状态，包括会话、权限、工具连接、任务队列、后台任务、MCP 连接、UI 状态、外部环境观察和恢复点。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
多处可写状态会导致副作用散落、恢复困难和并发冲突。	单一状态变更入口，状态变更与副作用解耦；关键状态建立 checkpoint 和事件日志。	architecture.md §11.1-§11.4；2512.13564.md §2.1	architecture.md §11.4.1、§11.4.3	AppStateStore 承载会话级事实；调用点只提交状态变更；外部同步统一收敛到 onChangeAppState()。
环境不是静态 prompt，工具执行会改变外部世界和内部状态。	显式建模 state / observation / action / transition；工具结果回写时带来源、时间和版本。	2308.11432.md §2.1.4；2412.17481.md §2.2；2512.13564.md §2.1	architecture.md §11.4.4、§6.4.4	区分系统事实源 AppState 与模型可见 Context；工具结果用同一条 tool_result 同时回流 UI / SDK / 下一轮模型，并保留来源字段。
中断、恢复、后台任务和多 Agent 并发会造成状态错位。	用持久化状态机、锁或版本冲突解决；恢复路径必须和正常路径共享状态协议。	architecture.md §11.4；gemini-deep-research-report.md §6.2-§6.3	architecture.md §11.4.1、§11.4.4、§7.4.4、§7.4.6	进程内用 AppState、task state、transcript 和资源所有权清理维持一致；分布式锁、版本冲突解决是跨进程 Agent 的演进方向。

2.7 Orchestration / Lifecycle / 编排与生命周期

作用：主持完整请求生命周期，把模型调用、LLM/工具/Agent 路由、工具执行、hooks、权限、context、compact 触发、UI、后台任务和停止条件组织成可推进、可恢复的主循环。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
Agent 回合不是一次模型调用，而是多轮推理、动作、观察和状态更新。	建立统一回合推进器；每一步收敛为 continue、return、error、handoff 或 ask user。	architecture.md §4.1-§4.4；gpt-deep-research-report.md「对话管理/交互」	architecture.md §4.4.1、§4.4.2、§4.4.3、§4.4.4、§6.4.3	主循环把模型输出、工具结果、Stop hooks、错误恢复和 token budget 收敛为继续下一轮、返回用户或失败退出。
模型、工具、Agent 的选择权如果各模块各自解释，会形成隐式路由网，导致成本、权限和行为不可治理。	把模型、工具、Agent 和辅助调用的选择权收敛到固定边界，避免隐式路由。	architecture.md §4.2-§4.4、§7；gpt-deep-research-report.md「决策/规划」「对话管理/交互」	architecture.md §4.4.5、§7.4.2、§7.4.4	入口确定主模型初值；主循环维护本轮决策快照和 fallback；API 层做请求能力投影；Agent 边界解析子 Agent 模型、工具池和权限收窄。
生命周期钩子既要可扩展，又不能破坏主循环语义。	明确 blocking 与 non-blocking hook 边界；同步决策点必须收敛为 continue / return / error。	architecture.md §4.4、§6.4、§8.4	architecture.md §4.4.3、§8.4.1	Stop hooks 是 blocking 决策点；Pre/PostToolUse hooks 进入工具执行链；普通系统收尾任务不冒充模型可见工具。
用户打断、澄清、计划模式、后台摘要、compact 和子任务会交织。	用状态机、任务队列、预算和人工确认点表达流程；压缩策略由 Context 层定义，编排层决定触发时机。	architecture.md §4、§9、§10；gpt-deep-research-report.md「对话管理/交互」	architecture.md §4.4.1、§4.4.4、§10.4.4、§10.4.5、§11.4.4	主循环阶段、任务队列、权限审批和 Context 压缩策略分别承接这些事件；编排层只决定何时触发和如何回到主循环。

2.8 Extension / Capability / 扩展与能力接入

作用：把 MCP、Plugin、Skill、自定义 Agent、OAuth、LSP、远程 bridge、模型 API、上下文压缩服务等外部能力接入运行时。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
能力来源多，命名、版本、权限、可见性和生命周期容易冲突。	统一注册表、命名空间、签名去重、禁用状态例外、按轮次刷新可见能力快照。	architecture.md §7.1-§7.4	architecture.md §7.4.1、§7.4.3、§7.4.5	MCP 用 key 命名空间 + 内容签名去重；Skill / Agent 用固定来源优先级和同名覆盖；能力进入下一轮可见快照。
能力加载不能阻塞启动，但模型看到的工具列表必须一致。	异步发现能力，回合开始时冻结工具快照；新能力下一轮生效。	architecture.md §7.4	architecture.md §7.4.2	MCP 先 pending 后异步连接，16ms 批量 flush；refreshTools() 在轮次边界取新工具池，当前轮不 retroactively 改 schema。
外部能力接入会扩大攻击面和故障面。	允许列表、权限声明、最小暴露、连接健康检查、契约测试和审计。	architecture.md §7、§8.4；gpt-deep-research-report.md「集成/接口层」「安全与权限」	architecture.md §7.4.5、§8.4.1	外部 schema、认证和租户身份先收敛到 Tool / Command / Agent / AppState，再叠加最小暴露、显式 re-auth、连接健康、权限护栏和可观测记录。

2.9 Multi-Agent Collaboration / 多 Agent 协作

作用：让多个 Agent 通过分工、通信、评审、投票、辩论、handoff 或 supervisor-worker 模式完成单体 Agent 难以稳定完成的复杂任务。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
Agent 数量增加后，通信成本、上下文复制和延迟呈倍数增长。	只在任务需要分工、并行或独立校验时启用；用 supervisor、DAG 或共享状态替代全连接聊天。	2501.06322.md §4.6；2412.17481.md §3.1、§6.2；gpt-deep-research-report.md「实施优先级与依赖」	architecture.md §7.4.4、§7.4.6、§10.4.5	子 Agent 复用执行框架但收窄工具、权限和上下文；后台 Agent 用 task / notification 回流；teammate 有独立 task state。
多 Agent 会产生信息孤岛、角色冲突和结论不一致。	明确角色、输入输出契约、共享记忆、冲突合并策略和最终裁决者。	2501.06322.md §3-§4；gemini-deep-research-report.md §6.1-§6.3	architecture.md §7.4.6	Claude Code 当前重点是区分普通子 Agent、后台 Agent、teammate 的创建、寻址、结果回流和清理；未实现通用语义冲突自动裁决。
恶意或错误信息可能在 Agent 网络内传播。	对跨 Agent 消息做来源标记、权限隔离、内容过滤和传播范围限制；高风险协作引入 HITL。	2503.21460.md §4.2.2；gemini-deep-research-report.md §6.3；2601.01743.md §7.5	architecture.md §7.4.6、§10.4.6、§10.4.8	跨 Agent / 工具 / 文件内容保留来源边界；子 Agent 权限只能收窄；长期记忆读回降信任并允许修复。

2.10 Safety / Governance / 安全与治理

作用：控制 Agent 的风险边界，包括提示注入、权限越界、工具副作用、数据外泄、记忆投毒、审计、合规和人工接管。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
安全风险贯穿输入、上下文、工具和输出，不是最终回答过滤能解决。	输入/输出/工具/记忆分别建策略；外部数据默认不可信；策略结果进入主循环决策。	2507.21504.md §3.4；2601.01743.md §6.6；gpt-deep-research-report.md「安全与权限」	architecture.md §8.4.1、§10.4.6、§10.4.8	输入资料做来源和信任分层；工具执行统一走权限 / hook / sandbox；记忆写入与读回降信任；横切安全逻辑收敛到基础设施原语。
工具越权、命令执行、文件写入和外部 API 调用会产生真实损害。	最小权限、RBAC/IAM、审批门、沙箱、危险动作硬拦截、可审计执行日志。	architecture.md §6.4、§8.4、§10.4；2601.01743.md §7.1；gemini-deep-research-report.md §5.3	architecture.md §6.4.5、§8.4.1	工具可见性、权限规则、审批门、危险路径硬拦截、模式收紧、sandbox / helper 封装和 transcript / telemetry 审计共同约束副作用。
记忆、prompt、模型行为和多 Agent 通信都可能被攻击或泄露。	记忆写入清洗、命名空间隔离、敏感信息脱敏、反注入、红队集和版本化治理。	2512.13564.md §7 Trustworthy Memory；2503.21460.md §4.2-§4.3；architecture.md §10.4	architecture.md §10.4.6、§10.4.8、§7.4.6、§8.4.2	上下文标签区分指令与资料；记忆路径隔离和可修复；多 Agent 权限收窄；anti-distillation、telemetry redaction、非必要网络开关控制泄露面。

2.11 Evaluation / Observability / 评估与可观测性

作用：回答 Agent 是否可靠完成任务，并让每一轮输入、规划、工具、状态、权限、成本、错误和最终输出都可回放、可定位。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
评估口径不完整：只看最终文本会掩盖规划错误、工具错误和安全绕过。	先定义"评什么"：按 outcome、trajectory、tool correctness、memory retention、safety、cost、latency 建多维评估。	2507.21504.md §2-§4；2601.01743.md §6.1-§6.7	architecture.md §8.4.3	先把 trajectory、tool result、权限决策、cost、latency、安全事件记录成可解释轨迹；outcome evaluator 和切片评测是增强项。
排障证据链断裂：失败常跨模型、工具、上下文和外部系统，黑盒排障成本高。	再解决"怎么定位"：全链路 trace、span 级指标、结构化日志、版本标签、输入输出样本和 tool span 互链。	gpt-deep-research-report.md「监控与可观测性」「指标体系与故障排查」；architecture.md §8	architecture.md §8.4.3、§6.4.6	queryChainId / queryDepth、tool span、OTel / analytics、debug log、Perfetto trace、transcript 和 sourceToolAssistantUUID 串起模型、工具、UI / SDK 事件。
变更回归不可控：Prompt、模型、工具、数据集一改就可能产生隐性退化。	最后解决"怎么发布"：建立离线回放集、切片评测、shadow/canary、发布门禁和在线 trace 回流。	gpt-deep-research-report.md「数据与模型管理」；2507.21504.md §4.4	architecture.md §8.4.4	VCR fixture、token count fixture、transcript replay 和轨迹断言构成回归底座；shadow / canary 和在线 trace 回流属于通用发布流程增强。

2.12 Learning / Evolution / 学习与演化

作用：从历史轨迹、失败案例、用户反馈、工具结果和多 Agent 交互中沉淀改进资产，包括 prompt、skill、记忆、数据集、评估器和模型版本。

挑战	通用解决方案	依据	Claude Code 对应难点	Claude Code 落地方案
线上自我学习如果无约束，容易把错误经验、攻击样本和偶然成功固化。	人工或评估器审核后再写入长期资产；区分候选经验、已验证知识和可发布能力。	2308.11432.md §2.2；2512.13564.md §5；gpt-deep-research-report.md「数据与模型管理」	architecture.md §10.4.8	写入前降低权限和污染半径；读回时保留来源与新鲜度；发现冲突后通过工具修正或移除。
经验沉淀形式多，prompt、记忆、skill、模型和数据集容易割裂。	把 Prompt / Model / Dataset / Eval / Trace 绑定成发布单元，支持回滚和对比。	gpt-deep-research-report.md「数据与模型管理」；2507.21504.md §4	architecture.md §8.4.4	当前主要把 trace、transcript、VCR fixture 和 token fixture 作为可回放资产沉淀；完整发布单元属于更高阶方法论。
自我演化机制难以验证，可能提升局部指标却伤害整体可靠性。	先做离线学习和评测驱动迭代，再逐步引入受控在线优化；关键能力必须有回归门禁。	2503.21460.md §2.3；gemini-deep-research-report.md §4.3、§7	architecture.md §8.4.4	先用离线回放、轨迹断言和回归底座验证变化；当前文档覆盖的是回放底座，不是完整在线学习闭环。

三、和 Claude Code 架构的对应关系

Agent 应用模块	Claude Code 对应位置	对应关系
Entry / Ingress / 入口与接入	architecture.md §3 入口 / 初始化层	把命令、运行模式、信任检查和输出形态归一。
Profile / Perception / 角色与感知	architecture.md §10 Context 体系、§8 基础设施层	通过系统上下文、项目上下文、用户上下文和输入过滤影响模型行为。
Context / Memory / 上下文与记忆	architecture.md §10 Context 体系	管理 prompt 构建、缓存、压缩、工具结果引用和上下文安全。
Planning / Reasoning / 规划与推理	architecture.md §4 引擎层	形成候选计划、下一步意图和决策依据，供主循环执行。
Tool / Action Execution / 工具与动作执行	architecture.md §6 工具子层	统一工具协议、schema 校验、权限、hooks、执行和结果回灌。
Environment / State / 环境与状态	architecture.md §11 状态体系	会话、权限、桥接、后台任务和 UI 状态从统一状态口收敛。
Orchestration / Lifecycle / 编排与生命周期	architecture.md §4 引擎层、§9 Command、§10 Context	负责回合生命周期、命令调度、LLM/工具/Agent 路由、compact 触发、hook、stop 和恢复。
Extension / Capability / 扩展与能力接入	architecture.md §7 能力子层	MCP、Plugin、Skill、Agent、OAuth、LSP 等能力统一发现和注入。
Multi-Agent Collaboration / 多 Agent 协作	architecture.md §7.2 Agent、§7.4.4、§7.4.6	子 Agent 的上下文、工具、hooks 和消息需要隔离与可回收。
Safety / Governance / 安全与治理	architecture.md §2.2.1、§6.4、§8.4、§10.4	安全横跨权限、工具、上下文、外发、沙箱和遥测。
Evaluation / Observability / 评估与可观测性	architecture.md §8 基础设施层、agent_design_methodology_migration.md §1 方法论	Telemetry、日志、trace、指标和任务轨迹支撑排障与评估。
Learning / Evolution / 学习与演化	architecture.md §10 Context、§12 架构演进	通过上下文压缩、经验抽取、能力扩展和架构热点治理形成演进闭环。

四、传统工程对照与可迁移性

4.1 为什么要做这个对照

§1 的判断表（旧问题换皮 vs 真正新维度）要逐格落到模块才好用------这一章就做这件事：把每个模块的 Agent 挑战对到传统工程的同类问题与解法，用可迁移度 ★ 标出是"能整套搬"还是"机制会断"。读法上先用传统成熟解把工程底座兜稳（§4.3 的 8 个模式可整套搬），再只在真正新增的维度上叠加 Agent 专属机制（§4.4），别用旧机制硬扛新问题。

4.2 12 模块的传统工程对照

每张子表按"Agent 挑战 → 传统工程同类问题 → 传统工程典型解法 → 可迁移度"四列对照。可迁移度 ★ 就是上面那张分类表的量化：★★★★★ = 旧问题换皮，传统机制可整套搬；★★★☆ 及以下 = 只有框架能借、机制会断，而断点几乎都落在 §4.4 的新维度上。读一张表先看星级，低星行才是真正值得细读的地方。

两点统一说明，下表不再逐格重复：一是"传统工程典型解法"列写的是成熟形态，Claude Code 落地的多是其子集，差距集中在 §4.4 和演进问题里讨论；二是凡可迁移度未达 ★★★★★，原因都归在"机制会断"，不再每格补一句"尚未完整实现"。

4.2.1 Entry / Ingress --- 入口与接入

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
多入口（CLI / SDK / headless / 子 Agent / Bridge）共享同一套核心逻辑时表现不一致	同一应用支持多种调用入口的一致性问题	分层架构：薄入口层只做协议归一，业务逻辑下沉到核心层共享（典型例子：Git/libgit2、Docker CLI/Engine API、kubectl/client-go）	★★★★★
启动链路重、首响慢	Cold start 优化、首屏白屏问题	并行加载与预取（Promise.all 并行 await、浏览器 preload/preconnect、子进程 fire-and-forget 与 CPU-bound 任务重叠）、Lazy import / code splitting、serverless 预热、CDN edge cache、fast path vs full bootstrap	★★★★★
接入协议 / 请求 schema 漂移	API Gateway / BFF / Adapter 层收拢多端协议差异	统一 ingress router + adapter：不同入口先路由到对应适配器，再归一成 canonical request / session / run mode；配合契约测试、版本标记、能力允许列表和降级策略	★★★★☆（入口收拢心智可直接迁移；但 MCP / Tool 等外部能力 schema 漂移属于 Extension / Capability，不在本层解决）

4.2.2 Profile / Perception --- 角色与感知

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
长会话角色漂移	（无强对应）最接近的是"周期性 health check + reload" / 关键节点重新校验身份	思路可借：在关键推理节点重新注入角色约束（类似 JWT 在关键边界重新校验、配置中心定时刷新）；但根因不同------传统是状态过期，Agent 是模型注意力随上下文增长衰减，工程层面只能缓解不能根治	★☆☆☆☆（机制不能照搬，根因在模型层而非工程层）
多模态输入噪声 / 解析失败	ETL pipeline 中脏数据处理、多媒体解码	信号处理 filter chain、置信度降级、解析失败 fallback、专用解析器外置	★★★★☆
输入数据 / 指令混合污染	SQL injection、XSS、CSRF 防御	信任分级（trusted vs untrusted source）、参数化查询、输出转义、入口分流标记	★★★★★
与 Context/Memory 边界混淆	MVC 中 Controller 与 Model 职责重叠	关注点分离（SRP）、边界即纪律：解释当前输入 vs 管理长期信息	★★★★★

4.2.3 Context / Memory --- 上下文与记忆

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
上下文膨胀	日志保留膨胀、事件流长期累积、缓存占用失控	保留窗口、事件摘要、冷热分层、按用途分桶、超大对象外置引用；重点是控制"哪些信息继续进请求"，不是 GC 回收对象内存	★★★★★
陈旧记忆 / 错误记忆 / 跨租户污染	缓存过期、配置污染、多租户数据串读	陈旧用版本号 / mtime / TTL / invalidate；错误写入用审核、来源记录和回滚；跨租户用 namespace、ACL 和读写边界校验	★★★★☆
多路径上下文不一致	多副本一致性、状态分叉	Single Source of Truth、CQRS、Redux 单 store、数据库主从同步协议	★★★★★
与 Orchestration 压缩边界不清	业务规则 vs 调度策略	关注点分离：策略层定义"压什么 / 怎么压"，调度层决定"何时触发"	★★★★★

4.2.4 Planning / Reasoning --- 规划与推理

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
长链错误放大 / 成本失控	长事务超时、分布式作业失败放大	工作流引擎（Temporal/Airflow）的超时与重试预算、Saga 模式、分布式事务补偿	★★★★☆
单线 CoT 短视、坏观察难恢复	局部最优陷阱	搜索算法（A* / MCTS，Monte Carlo Tree Search，蒙特卡洛树搜索）、分支限界、回溯、剪枝；Agent 侧可借 ToT（Tree of Thoughts，思维树）、GoT（Graph of Thoughts，思维图）、MCTS、critic 等多分支思路	★★★☆☆（Agent 侧更概率化，传统搜索算法只能借鉴框架，不能直接复用）
过早追求自由自治	自动化爆炸式上线导致回滚困难	自动化阶梯：手动 → 半自动 → 全自动、HITL（Human in the Loop）、工作流优先	★★★★★
与 Orchestration 边界（"下一步"歧义）	MVC：Model 不该知道 Controller；Planner vs Scheduler	计划者只产出意图，调度者负责推进------Airflow DAG 定义 vs Scheduler 运行	★★★★★

4.2.5 Tool / Action Execution --- 工具与动作执行

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
参数非确定 / JSON 破损	弱类型 JSON API、ETL 脏数据、前后端契约漂移导致字段缺失或语义不合法	protobuf strict typing、JSON schema 校验、defensive deserialization、业务语义校验、repair 默认值、契约测试	★★★★★
副作用代价高（误调、重复、越权）	重复扣款、并发写丢失、越权 API 调用	幂等键、Saga 补偿、事务边界、optimistic locking、审批门、audit log、最小权限	★★★★★
外部系统不稳定 → 重试风暴	微服务雪崩、依赖故障级联	超时、取消、断路器（circuit breaker）、有界重试预算、快速失败、错误结构化回灌、trace span	★★★★★

4.2.6 Environment / State --- 环境与状态

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
多处可写状态 → 副作用散落	领域状态被多个入口直接改写，领域事件缺失或事件发布分散	领域事件、Event sourcing、CQRS、单写者模型、统一变更入口；状态变化先沉淀为事件，再由订阅者处理副作用	★★★★★
动态环境建模	业务流程状态、订单生命周期	有限状态机（FSM）、Event sourcing、CDC（Change Data Capture）、state machine library	★★★★★
中断 / 并发恢复错位	进程崩溃后状态恢复、分布式作业断点续传	WAL（write-ahead log）、transcript、checkpoint、版本化恢复、任务状态机、saga 持久化	★★★★☆

4.2.7 Orchestration / Lifecycle --- 编排与生命周期

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
多轮交互（不是一次请求）	长事务编排、长会话 stateful 协议	工作流引擎（Temporal / Cadence / Airflow）、Actor 模型、状态机驱动	★★★★★
模型 / 工具 / Agent 路由分散	控制面规则分散、各模块自己解释能力边界	明确每个边界的决策责任：入口决定运行模式和主模型初值；主循环冻结本轮工具快照并处理 fallback；API 层只投影本次请求可见能力；Agent 边界再收窄子 Agent 的模型、工具和权限。它不是一个全局中心化 Router，而是多处固定边界各管一段	★★★★☆
Hook 与扩展不破坏主循环	拦截器扩展性 vs 性能 / 语义	AOP（面向切面）、Middleware chain（Express / Koa）、Spring Interceptor、React useEffect 边界	★★★★★
用户打断 / 后台任务交织	前台请求与后台 job 共享会话生命周期，用户取消后仍可能有结果返回或资源未释放	cancellation token / AbortController、job id、任务状态机、结果 mailbox、finally 清理和 orphan job 回收；关键是让"取消、完成、回收、展示"都有明确归属	★★★★★

4.2.8 Extension / Capability --- 扩展与能力接入

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
命名 / 版本 / 权限冲突	包管理依赖地狱、命名空间冲突	npm / Maven / Cargo、SemVer、namespace、来源优先级、签名校验、SBOM、插件市场供应链治理	★★★★★
异步加载但模型可见性需一致	服务发现 / 配置中心动态刷新，但单次请求不能中途换实例列表或配置版本	service registry + request-scoped snapshot、feature flag evaluation snapshot、配置版本号；新能力异步刷新，当前请求继续使用进入请求时冻结的能力快照	★★★★★
扩展面 = 攻击面	第三方插件安全 / 供应链攻击	允许列表、最小暴露、权限声明、健康检查、契约测试、schema 刷新	★★★★★

4.2.9 Multi-Agent Collaboration --- 多 Agent 协作

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
通信成本爆炸	微服务过度拆分、聊天式 RPC	Conway's Law、避免过度拆分、Pub-Sub 解耦、共享状态替代全连接消息	★★★★★
信息孤岛 / 冲突	多 worker 结果聚合、任务状态分叉	supervisor-worker、任务队列、result aggregation、显式最终裁决者；不要让 worker 之间互相覆盖最终事实	★★★★☆
恶意 / 错误信息传播	网络中信息传播失控、僵尸节点	拜占庭容错、消息认证（mTLS）、零信任网络、来源标记、传播范围限制	★★★★☆

4.2.10 Safety / Governance --- 安全与治理

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
多维安全（输入/上下文/工具/输出）	Web 应用安全（OWASP Top 10）	防御纵深（defense in depth）、Zero Trust、4A（认证 / 授权 / 审计 / 账号）、入口 + 业务 + 数据三层防护	★★★★★
工具越权 / 命令执行 / 文件写入	进程权限滥用、容器逃逸	最小权限、RBAC / ABAC、IAM、Linux capabilities、seccomp、AppArmor、危险动作硬拦截、沙箱	★★★★★
记忆 / Prompt 投毒 / 数据泄露	DLP 数据防泄漏、缓存投毒	加密传输 / 存储、tokenization、敏感字段脱敏、WAF、反注入红队、版本化治理	★★★★☆（"记忆投毒"是 Agent 特有变体，但脱敏 / 反注入框架可借用）

4.2.11 Evaluation / Observability --- 评估与可观测性

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
多维评估（不能只评最终文本）	测试金字塔：单元 → 集成 → E2E	测试金字塔、Quality gates、SLO、多指标看板；Agent 增加 trajectory / cost / safety 维度	★★★★☆（轨迹评估是新增维度）
黑盒排障跨模型 / 工具 / 外部	分布式系统全链路排障	OpenTelemetry / Jaeger / Tempo trace、Prometheus metrics、ELK 日志聚合、span 互链	★★★★★
Prompt / 模型 / 工具改动隐性回归	任何配置变更都可能引发线上回归	离线回放、VCR fixture、轨迹断言、发布门禁、灰度观察、失败自动回退	★★★★★

4.2.12 Learning / Evolution --- 学习与演化

Agent 挑战	传统工程同类问题	传统工程典型解法	可迁移度
在线自学习固化错误经验	A/B test 显著性误判、根据偶发线上数据下结论	数据质量门、显著性校验、code review、候选 / 已验证 / 可发布三级分级	★★★★☆
资产割裂（Prompt/Model/Dataset/Eval/Trace）	配置 / 代码 / 数据 / 基础设施分别管理导致回滚困难	Git tag bundled release、IaC（基础设施即代码）、版本绑定、配置 + 代码 + 数据一起回滚	★★★★☆
自演化难验证	自动调参 / 自动扩缩容的稳定性	CI/CD pipeline、Staged rollout、SRE 错误预算、离线回放和回归门禁	★★★★★

4.3 提炼：8 个高频可迁移模式

把 12 张子表里反复出现的高★（★★★★★）模式提炼出来------这些就是"旧问题换皮"的核心，可以整套搬过来，是工程师从已有经验直接切入 Agent 的"捷径"：

模块	传统工程模式	在 Agent 中的形态	关键收益
上下文与记忆	多层缓存 + 失效协议（CDN / L1-L2-L3）	Context memoize + 依赖失效（架构 §10.4.3）	性能 + 一致性双赢
工具与动作执行	Schema 即合同（protobuf / OpenAPI / Pact）	Tool.inputSchema + 工具协议（架构 §6.2）	防止参数 hallucination、契约可测
工具与动作执行	超时 / 取消 / 有界重试 / 错误回灌（Resilience4j 思路）	工具失败结构化回灌、abortController、有界 API retry、token budget（架构 §6.4.6）	防雪崩、防长阻塞
环境与状态	单一事实源 + 副作用收敛（Redux / CQRS）	AppState + onChangeAppState（架构 §11）	防止状态分叉、可恢复
编排与生命周期	状态机 + 工作流（Temporal / FSM）	主循环 query() 回合推进 + Stop hooks（架构 §4.3）	多轮交互可恢复、可暂停
安全与治理	最小权限 + 沙箱（Linux caps / seccomp）	工具可见性 + 4 道权限关 + DANGEROUS_DIRECTORIES（架构 §6.4.5）	边界即纪律
评估与可观测性	Trace + Span 互链（OpenTelemetry）	queryChainId + tool span + sourceToolAssistantUUID（架构 §8.4.3）	黑盒排障、轨迹回放
评估与可观测性	回放夹具 + 轨迹断言 + 发布门禁（CI/CD 思路）	VCR fixture + transcript replay + 回归底座（架构 §8.4.4）	隐性回归早发现

把这 8 个模式当成"Agent 工程师的最小必备工具箱"。

4.4 真正新增的维度：回溯到两个根因

§4.2 的高★行可以直接复用，低★行才是 Agent 的真问题。但这些"新维度"不是彼此独立的 4 件事------它们全部回溯到两个根因：决策核心从确定性代码变成概率模型 ，输入面从结构化字段变成自然语言。传统软件模式在这两个根因上失效，必须补上这几个维度（机制能借相邻领域则借，见小结）。

模块	新增维度	根因	传统机制为什么失效
上下文与记忆	上下文即资源 + 注意力衰减	概率核心	不只是容量预算（何时压缩），还有早期约束随上下文增长被稀释、需在关键节点重注入；后者是 LLM 内在特性，工程只能缓解不能根治
多 Agent 协作	自主体协作（vs 被动服务）	概率核心	各 Agent 有自己的目标、计划和决策，"调用方 → 被调用方"心智失效，要参考分布式多智能体协作
安全与治理	自然语言不可信输入面：prompt injection	语言 I/O	指令、数据、环境描述混在同一句话里，只能从"语义"层面分流，"字符"层面过滤拦不住
评估与可观测性	统计驱动评估：outcome / trajectory / cost / safety 多维分布	概率核心	同输入→不同输出，exact-match / pass-fail 断言失效：评判对象从单个结果变成输出分布（N 次通过率、方差），评判方式从相等比较变成语义评分（rubric / LLM-as-judge）。回放底座是旧的（§4.3），新的是对非确定系统做统计 + 语义评判（传统软件测试没有，借自 ML）

这 4 项是真·新增 ------问题本身传统软件没有（行为从确定变概率、输入从结构化变自然语言），且内在、不随生态成熟消失。但**"维度新"不等于"机制从零造"：评估借 ML 的分布 + 语义评分，多 Agent 借分布式协作，回放底座直接复用 §4.3------新的是"必须做这件事"，解法尽量借。这也划出和伪新增**的界：伪新增是连问题都旧，比如"能力动态发现"其实就是服务发现 + 请求级快照（Dubbo / Nacos / Consul 那套，§4.2.8 已 ★★★★★），把它当新增就会为很快被标准淘汰的东西造私有轮子。