Agent智能体架构设计-知识整理

skywsp2026-10-20 18:51

Agent智能体架构设计-知识整理

  • Agent智能体架构设计-知识整理
    • 目录
    • [第 0 章 一图看懂全文结构](#第 0 章 一图看懂全文结构)
    • [第 1 章 智能体的分类：控制权归属 × 自主程度](#第 1 章 智能体的分类：控制权归属 × 自主程度)
      • [1.1 三类智能体对照](#1.1 三类智能体对照)
      • [1.2 通用型智能体 vs 对话式机器人](#1.2 通用型智能体 vs 对话式机器人)
    • [第 2 章 Agent 工程方法论](#第 2 章 Agent 工程方法论)
      • [2.1 五个 Engineering](#2.1 五个 Engineering)
      • [2.2 智能体能力构成：Agent 七件套](#2.2 智能体能力构成：Agent 七件套)
      • [2.3 概念边界：Loop / Harness / Skill / Tool / MCP](#2.3 概念边界：Loop / Harness / Skill / Tool / MCP)
      • [2.4 循环停止条件（Loop 的收敛协议）](#2.4 循环停止条件（Loop 的收敛协议）)
      • [2.5 中间件 vs 插件](#2.5 中间件 vs 插件)
      • [2.6 三层数据格式约束](#2.6 三层数据格式约束)
      • [2.7 LLM模态选型原则](#2.7 LLM模态选型原则)
    • [第 3 章 通用智能体架构设计](#第 3 章 通用智能体架构设计)
      • [3.1 四个设计原则](#3.1 四个设计原则)
      • [3.2 三层架构全景](#3.2 三层架构全景)
      • [3.3 L1 模型协议层](#3.3 L1 模型协议层)
      • [3.4 L2 通用编排层](#3.4 L2 通用编排层)
      • [3.5 L3 产品能力层](#3.5 L3 产品能力层)
    • [第 4 章 智能体核心执行流程](#第 4 章 智能体核心执行流程)
      • [4.1 七层链路](#4.1 七层链路)
      • [4.2 运行流程（以 Codex 类系统为例）](#4.2 运行流程（以 Codex 类系统为例）)
    • [第 5 章 框架对比与选型](#第 5 章 框架对比与选型)
      • [5.1 主流框架能力对比](#5.1 主流框架能力对比)
      • [5.2 LangChain 标准化模型接口的价值（避免供应商锁定）](#5.2 LangChain 标准化模型接口的价值（避免供应商锁定）)
      • [5.3 LangChain vs LangGraph 选型逻辑](#5.3 LangChain vs LangGraph 选型逻辑)
      • [5.4 可解耦、可演进的 Agent 分层架构（支撑团队业务）](#5.4 可解耦、可演进的 Agent 分层架构（支撑团队业务）)
    • [第 6 章 智能体执行指标体系](#第 6 章 智能体执行指标体系)
      • [6.1 核心效率指标](#6.1 核心效率指标)
      • [6.2 质量指标](#6.2 质量指标)
      • [6.3 成本指标](#6.3 成本指标)
      • [6.4 风险指标](#6.4 风险指标)
      • [6.5 指标使用原则](#6.5 指标使用原则)
    • [第 7 章 常见问题](#第 7 章 常见问题)
      • [7.1 初中级](#7.1 初中级)
        • [Q1（TS 基础）你 TypeScript 掌握怎么样？TypeScript 与 Zod 为什么会在 AI Agent 开发中应用广泛？你认为前端往 Agent 能有哪些沉淀？](#Q1（TS 基础）你 TypeScript 掌握怎么样？TypeScript 与 Zod 为什么会在 AI Agent 开发中应用广泛？你认为前端往 Agent 能有哪些沉淀？)
        • [Q2（通用智能体）你知道怎么搭建一个通用型智能体吗？说说类似 OpenClaw、Codex 智能体的全栈设计思路](#Q2（通用智能体）你知道怎么搭建一个通用型智能体吗？说说类似 OpenClaw、Codex 智能体的全栈设计思路)
        • [Q3（前端视角）作为前端开发，请说说你对于 AI 提效工具的理解，Codex、Trae、OpenClaw 这些工具听过吗？说说你的看法](#Q3（前端视角）作为前端开发，请说说你对于 AI 提效工具的理解，Codex、Trae、OpenClaw 这些工具听过吗？说说你的看法)
        • [Q4（Harness 入门）有没有了解过 Harness？为什么需要 Harness？在你的 Agent 产品中如何设计 Harness 体系？](#Q4（Harness 入门）有没有了解过 Harness？为什么需要 Harness？在你的 Agent 产品中如何设计 Harness 体系？)
        • [Q5（认知）前端为什么要学全栈 Agent？跟传统前端工程有什么区别？Harness 和 Loop 这些概念到底是什么？](#Q5（认知）前端为什么要学全栈 Agent？跟传统前端工程有什么区别？Harness 和 Loop 这些概念到底是什么？)
      • [7.2 中高级](#7.2 中高级)
        • [Q6（TS 框架）基于 TypeScript 搭建 AI Agents 基础框架（参考 LangGraph 核心能力），说说你的核心设计思路与关键代码实现逻辑](#Q6（TS 框架）基于 TypeScript 搭建 AI Agents 基础框架（参考 LangGraph 核心能力），说说你的核心设计思路与关键代码实现逻辑)
        • [Q7（LangChain 选型）聊聊 LangChain 标准化模型接口对避免供应商锁定的价值，以及如何根据业务复杂度在 LangChain 和 LangGraph 之间做选型？如何设计可解耦、可演进的 Agent 分层架构来支撑团队业务？](#Q7（LangChain 选型）聊聊 LangChain 标准化模型接口对避免供应商锁定的价值，以及如何根据业务复杂度在 LangChain 和 LangGraph 之间做选型？如何设计可解耦、可演进的 Agent 分层架构来支撑团队业务？)
        • Q8（模型与智能体）请站在前端角度深刻聊聊模型和智能体的关系，如何选择模型、如何开发智能体来支撑团队或者公司业务？
        • [Q9（工程链路）实现"从 Vite 构建到 Agent 自动修复 Bug"的功能，完整工程链路是怎么设计的？](#Q9（工程链路）实现"从 Vite 构建到 Agent 自动修复 Bug"的功能，完整工程链路是怎么设计的？)
        • [Q10（Harness / 术语辨析）DeepSeek Harness 的体系设计为什么会引起关注？背后的插件机制原理你有了解过吗？](#Q10（Harness / 术语辨析）DeepSeek Harness 的体系设计为什么会引起关注？背后的插件机制原理你有了解过吗？)
      • [7.3 专家级](#7.3 专家级)
        • [Q11（自研框架）如果让你实现对标 LangGraph 的 TypeScript AI Agents 框架，说说你的整体架构设计、核心模块划分与底层源码实现的关键难点突破](#Q11（自研框架）如果让你实现对标 LangGraph 的 TypeScript AI Agents 框架，说说你的整体架构设计、核心模块划分与底层源码实现的关键难点突破)
        • [Q12（系统设计）如果让你基于 DeepAgents 设计完整类似 OpenClaw、Codex 系统及操作 AI Agent，请给出你的设计方案和核心代码实现](#Q12（系统设计）如果让你基于 DeepAgents 设计完整类似 OpenClaw、Codex 系统及操作 AI Agent，请给出你的设计方案和核心代码实现)
        • [Q13（Coding Agent）如果让你开发类似 Codex 的 Coding AI 智能体，有没有明确的实现方案和思路？请实现一个核心功能版本 Codex](#Q13（Coding Agent）如果让你开发类似 Codex 的 Coding AI 智能体，有没有明确的实现方案和思路？请实现一个核心功能版本 Codex)
        • [Q14（架构 Leader）假如你是 Leader，来负责高可用低耦合的 Agent 产品，请说一说你的完整架构与落地思路（微内核 / 插件化机制设计）](#Q14（架构 Leader）假如你是 Leader，来负责高可用低耦合的 Agent 产品，请说一说你的完整架构与落地思路（微内核 / 插件化机制设计）)
        • [Q15（数据结构）State Schema、Graph Schema 与业务 DSL 分别约束什么？](#Q15（数据结构）State Schema、Graph Schema 与业务 DSL 分别约束什么？)
        • Q16（指标体系）如何定义和评估智能体执行指标？
        • [Q17（架构治理）作为架构师，如何让多产品线共享同一套 Agent 内核？](#Q17（架构治理）作为架构师，如何让多产品线共享同一套 Agent 内核？)
        • [Q18（Coding Agent 模块）类似 Codex 的 Coding Agent 应该划分哪些模块？](#Q18（Coding Agent 模块）类似 Codex 的 Coding Agent 应该划分哪些模块？)
    • [附录 A：术语速查表](#附录 A：术语速查表)
    • [附录 B：思考作答模板与一句话主线](#附录 B：思考作答模板与一句话主线)
      • [B.1 五步作答模板](#B.1 五步作答模板)
      • [B.2 一句话主线](#B.2 一句话主线)

Agent智能体架构设计-知识整理

本文档范围：智能体分类 → 工程方法论 → 架构设计 → 执行流程 → 框架选型 → 指标体系 → 常见问题。

目录

章节 内容 回答什么问题
[第 1 章](#章节 内容 回答什么问题 第 1 章 智能体的分类 有哪几类 Agent，区别在哪 第 2 章 Agent 工程方法论 五个 Engineering 管什么、概念边界怎么切 第 3 章 通用智能体架构设计 四条设计原则 + L1/L2/L3 三层架构 第 4 章 智能体核心执行流程 一次任务从入口到落盘怎么走 第 5 章 框架对比与选型 LangChain / LangGraph / DeepAgents 怎么选 第 6 章 执行指标体系 怎么衡量一个 Agent 好不好 第 7 章 常见问题（初中级 / 中高级 / 专家级） 作答思路与骨架 附录 A 术语速查表 名词快速对照 附录 B 作答模板与一句话主线 组织解题思路) 智能体的分类 有哪几类 Agent，区别在哪
[第 2 章](#章节 内容 回答什么问题 第 1 章 智能体的分类 有哪几类 Agent，区别在哪 第 2 章 Agent 工程方法论 五个 Engineering 管什么、概念边界怎么切 第 3 章 通用智能体架构设计 四条设计原则 + L1/L2/L3 三层架构 第 4 章 智能体核心执行流程 一次任务从入口到落盘怎么走 第 5 章 框架对比与选型 LangChain / LangGraph / DeepAgents 怎么选 第 6 章 执行指标体系 怎么衡量一个 Agent 好不好 第 7 章 常见问题（初中级 / 中高级 / 专家级） 作答思路与骨架 附录 A 术语速查表 名词快速对照 附录 B 作答模板与一句话主线 组织解题思路) Agent 工程方法论 五个 Engineering 管什么、概念边界怎么切
[第 3 章](#章节 内容 回答什么问题 第 1 章 智能体的分类 有哪几类 Agent，区别在哪 第 2 章 Agent 工程方法论 五个 Engineering 管什么、概念边界怎么切 第 3 章 通用智能体架构设计 四条设计原则 + L1/L2/L3 三层架构 第 4 章 智能体核心执行流程 一次任务从入口到落盘怎么走 第 5 章 框架对比与选型 LangChain / LangGraph / DeepAgents 怎么选 第 6 章 执行指标体系 怎么衡量一个 Agent 好不好 第 7 章 常见问题（初中级 / 中高级 / 专家级） 作答思路与骨架 附录 A 术语速查表 名词快速对照 附录 B 作答模板与一句话主线 组织解题思路) 通用智能体架构设计 四条设计原则 + L1/L2/L3 三层架构
[第 4 章](#章节 内容 回答什么问题 第 1 章 智能体的分类 有哪几类 Agent，区别在哪 第 2 章 Agent 工程方法论 五个 Engineering 管什么、概念边界怎么切 第 3 章 通用智能体架构设计 四条设计原则 + L1/L2/L3 三层架构 第 4 章 智能体核心执行流程 一次任务从入口到落盘怎么走 第 5 章 框架对比与选型 LangChain / LangGraph / DeepAgents 怎么选 第 6 章 执行指标体系 怎么衡量一个 Agent 好不好 第 7 章 常见问题（初中级 / 中高级 / 专家级） 作答思路与骨架 附录 A 术语速查表 名词快速对照 附录 B 作答模板与一句话主线 组织解题思路) 智能体核心执行流程 一次任务从入口到落盘怎么走
[第 5 章](#章节 内容 回答什么问题 第 1 章 智能体的分类 有哪几类 Agent，区别在哪 第 2 章 Agent 工程方法论 五个 Engineering 管什么、概念边界怎么切 第 3 章 通用智能体架构设计 四条设计原则 + L1/L2/L3 三层架构 第 4 章 智能体核心执行流程 一次任务从入口到落盘怎么走 第 5 章 框架对比与选型 LangChain / LangGraph / DeepAgents 怎么选 第 6 章 执行指标体系 怎么衡量一个 Agent 好不好 第 7 章 常见问题（初中级 / 中高级 / 专家级） 作答思路与骨架 附录 A 术语速查表 名词快速对照 附录 B 作答模板与一句话主线 组织解题思路) 框架对比与选型 LangChain / LangGraph / DeepAgents 怎么选
[第 6 章](#章节 内容 回答什么问题 第 1 章 智能体的分类 有哪几类 Agent，区别在哪 第 2 章 Agent 工程方法论 五个 Engineering 管什么、概念边界怎么切 第 3 章 通用智能体架构设计 四条设计原则 + L1/L2/L3 三层架构 第 4 章 智能体核心执行流程 一次任务从入口到落盘怎么走 第 5 章 框架对比与选型 LangChain / LangGraph / DeepAgents 怎么选 第 6 章 执行指标体系 怎么衡量一个 Agent 好不好 第 7 章 常见问题（初中级 / 中高级 / 专家级） 作答思路与骨架 附录 A 术语速查表 名词快速对照 附录 B 作答模板与一句话主线 组织解题思路) 执行指标体系 怎么衡量一个 Agent 好不好
[第 7 章](#章节 内容 回答什么问题 第 1 章 智能体的分类 有哪几类 Agent，区别在哪 第 2 章 Agent 工程方法论 五个 Engineering 管什么、概念边界怎么切 第 3 章 通用智能体架构设计 四条设计原则 + L1/L2/L3 三层架构 第 4 章 智能体核心执行流程 一次任务从入口到落盘怎么走 第 5 章 框架对比与选型 LangChain / LangGraph / DeepAgents 怎么选 第 6 章 执行指标体系 怎么衡量一个 Agent 好不好 第 7 章 常见问题（初中级 / 中高级 / 专家级） 作答思路与骨架 附录 A 术语速查表 名词快速对照 附录 B 作答模板与一句话主线 组织解题思路) 常见问题（初中级 / 中高级 / 专家级） 作答思路与骨架
[附录 A](#章节 内容 回答什么问题 第 1 章 智能体的分类 有哪几类 Agent，区别在哪 第 2 章 Agent 工程方法论 五个 Engineering 管什么、概念边界怎么切 第 3 章 通用智能体架构设计 四条设计原则 + L1/L2/L3 三层架构 第 4 章 智能体核心执行流程 一次任务从入口到落盘怎么走 第 5 章 框架对比与选型 LangChain / LangGraph / DeepAgents 怎么选 第 6 章 执行指标体系 怎么衡量一个 Agent 好不好 第 7 章 常见问题（初中级 / 中高级 / 专家级） 作答思路与骨架 附录 A 术语速查表 名词快速对照 附录 B 作答模板与一句话主线 组织解题思路) 术语速查表 名词快速对照
[附录 B](#章节 内容 回答什么问题 第 1 章 智能体的分类 有哪几类 Agent，区别在哪 第 2 章 Agent 工程方法论 五个 Engineering 管什么、概念边界怎么切 第 3 章 通用智能体架构设计 四条设计原则 + L1/L2/L3 三层架构 第 4 章 智能体核心执行流程 一次任务从入口到落盘怎么走 第 5 章 框架对比与选型 LangChain / LangGraph / DeepAgents 怎么选 第 6 章 执行指标体系 怎么衡量一个 Agent 好不好 第 7 章 常见问题（初中级 / 中高级 / 专家级） 作答思路与骨架 附录 A 术语速查表 名词快速对照 附录 B 作答模板与一句话主线 组织解题思路) 作答模板与一句话主线 组织解题思路

第 0 章 一图看懂全文结构

text 复制代码 
认知层   智能体分类（工作流 / 通用 / 垂直场景）
              ↓
方法层   Prompt / Context / Harness / Loop / Graph Engineering + 概念边界
              ↓
约束层   架构四原则（依赖倒置 · 协议先行 · 核心精简 · 扩展开放）
              ↓
结构层   L1 模型协议层 → L2 通用编排层 → L3 产品能力层
              ↓
流程层   目标解析 → 规划(DAG) → 编排调度 → 子智能体 → 技能(SOP) → 工具 → 持久化
              ↓
选型层   LangChain / LangGraph / DeepAgents / Spring AI / AgentScope-Java
              ↓
度量层   效率 · 质量 · 成本 · 风险
              ↓
实战层   常见问题（初中级 / 中高级 / 专家级）+ 作答模板

阅读建议：第 2 章（概念边界）和第 3 章（分层架构）是全文的地基，常见问题都在引用这两章。

第 1 章 智能体的分类：控制权归属 × 自主程度

分类的两个维度：控制权归属（人/规则 vs 模型） 与 自主程度（路径是否预先定义）。

1.1 三类智能体对照

类型 控制权归属 路径特征 可预测性 典型产品
通用智能体 模型（Model-in-the-loop） 只给目标，模型自己决定分几步、用什么工具、何时调整策略 低（ emergent，需 Harness 兜底） Codex、Cursor、Claude Code、OpenClaw
工作流智能体 代码/规则（开发者） 路径预先定义、显式编排 高（可预测） 开发平台：Coze（字节）、Dify； 一些成品办公智能体已经内嵌了工作流，如：WorkBuddy、豆包Worker、千问Worker
垂直业务场景智能体 领域规则 + 轻量模型决策 场景固定、能力收敛 中-高 剪映（智能剪辑）、Figma AI（设计）、智能客服

关键区别一句话：工作流智能体是"人写流程图，模型填空"；通用智能体是"人给目标，模型写流程图"。

1.2 通用型智能体 vs 对话式机器人

维度 对话式机器人 通用型智能体
定位 单轮/多轮问答交互 目标导向，自动化任务规划与执行，拆解为子智能体并发执行
能力 内容生成、轻量工具调用 任务分解（Planning）、多轮执行循环、多工具协同、文件操作、操作系统级命令、Skill 调用
状态 会话上下文为主，无长期任务态 任务态 + 会话态 + 文件系统外化记忆
终止条件 用户停止提问 达成目标契约或触发停止协议（maxTurns / 验证器通过 / 人工介入）

第 2 章 Agent 工程方法论

2.1 五个 Engineering

范式 回答的问题 性质 核心抓手
Prompt Engineering 单轮交互中如何表达：措辞、角色设定、示例、输出格式约束，让模型这一次答对 静态 few-shot、角色设定、输出格式约束（JSON Schema）
Context Engineering 模型做每个决策时，上下文窗口里装什么、以什么结构装、什么时候装、什么时候撤掉、超限时如何压缩 动态 上下文组装顺序、外化到文件、检索注入、压缩与裁剪策略
Harness Engineering 定边界、供环境：工具权限、沙箱隔离、状态持久化（崩溃可恢复）、验证检查（test/lint） 静态配置 解决输出不稳定、幻觉等问题的环境侧方案：安全、可观测、可恢复
Loop Engineering 何时继续、何时停止：执行 → 外部验证 → 决定重试 / 回滚 / 停止 / 交给人 动态执行流程 设计带验证器 和停止协议 的循环；每一次执行都是一次 ReAct：Thought → Action → Observation，循环往复直到得出最终答案
Graph Engineering 定分工、管交接 ：写代码的节点与检查代码的节点分离，检查者用干净上下文、只看结果；并行节点处理无依赖任务 静态结构 + 动态调度 避免线性等待；节点拆分 + 条件边 + 循环边

ReAct 是 Loop 的原子 ：Thought（推理）→ Action（行动）→ Observation（观察）→ 循环。

五个 Engineering 的层次关系：Prompt 管一次对话的表达，Context 管窗口的内容，Harness 管环境边界，Loop 管执行节奏，Graph 管多人分工。

2.2 智能体能力构成：Agent 七件套

text 复制代码 
Agent = LLM + Planning + Memory + Tool Use + Verifier + Guardrail + Telemetry
组成 作用 缺失后的典型问题
LLM 理解、推理、生成、选择下一步动作 没有智能决策能力
Planning 任务分解、排序、制定执行计划 只会单轮回答，无法完成复杂任务
Memory 短期上下文、长期知识、任务状态 多轮断片、无法恢复、无法积累经验
Tool Use 检索、文件、代码、API、系统命令 只能"说"，不能"做"
Verifier 测试、lint、类型检查、规则校验 幻觉无法被拦截，错误结果直接交付
Guardrail 护栏 权限、沙箱、审批、内容安全 越权操作、数据泄露、不可控副作用
Telemetry 遥测 日志、链路、Token、成本、指标 出问题无法定位，无法评估与优化

记忆口诀：模型决定上限，Harness 决定下限，Verifier 决定结果可不可信。

2.3 概念边界：Loop / Harness / Skill / Tool / MCP

概念 本质 解决的问题 典型内容
Loop 最小执行闭环 何时调用模型、何时执行工具、何时停止 模型调用、工具执行、结果回灌、停止条件
Harness 执行环境与约束外壳 如何让 Agent 安全、稳定、可观测、可恢复 权限、沙箱、持久化、验证、审批、遥测
Skill 行为规范包 在特定场景下如何规范地使用工具 SOP、提示词、参数约束、重试策略
Tool 原子能力 如何与外部世界交互 读文件、写文件、执行命令、检索、调 API
MCP 工具接入协议 如何标准化接入外部能力 Server 提供 Tool/Resource/Prompt，Client 消费

一句话记忆：

Loop 决定"继续还是停止"，Harness 决定"在什么边界内执行"，Skill 决定"怎么做才规范"，Tool 决定"具体做什么"，MCP 决定"能力如何接进来"。

2.4 循环停止条件（Loop 的收敛协议）

没有停止协议的 Loop 等于没有出口。必须显式设计以下条件，并明确优先级：

  • 正常收敛：模型不再请求工具调用，产出最终答复。
  • 预算上限 ：达到 maxTurns、Token 或成本预算上限。
  • 外部中断 ：用户取消、超时或 AbortSignal 触发。
  • 验证失败：验证器连续失败达到阈值，回滚并转人工处理。
  • 风险拦截：命中高危操作，暂停循环等待人工确认。

反例：把"模型自称任务已完成"当作唯一停止条件 ------ 模型的自我判断不能替代外部验证。

2.5 中间件 vs 插件

维度 中间件（Middleware） 插件（Plugin / Extension）
本质 流程中的拦截器，控制或修改执行流程 能力的安装包，把一组相关能力（可含中间件、工具）打包接入
典型用途 日志记录、权限校验、敏感信息过滤、提示词转换、错误重试 一键安装/启用：工具集 + 技能 + 中间件 + MCP 服务的组合
工作方式 以链 的形式工作：请求依次穿过多个中间件，每个都可在调用下一环节之前/之后 执行操作，甚至短路（阻断）流程 声明式注册，安装即生效，可整体启用/禁用
归属层 运行时基础设施：不增加"新技能"，而是改变已有流程的行为 / 增加横切关注点（安全、可观测） 分发与集成层：解决"如何把一堆相关能力方便地装进系统"
在 DeepAgents 中的体现 TodoList / Filesystem / SubAgent / Summarization / PromptCaching / PatchToolCalls 等 Middleware Skills 包、MCP Server、Extensions

一句话区分：中间件改的是"流程怎么走"，插件装的是"系统能干什么"。 插件通常内部包含若干中间件。

2.6 三层数据格式约束

概念 定位 约束对象 作用
State Schema（状态模式） 「状态模式」 整个多智能体系统的数据结构 规定图中各节点（智能体）之间传递的共享状态包含哪些字段、每个字段是什么类型
Graph Schema（协作契约） 「协作的契约」 系统架构 ，定义多智能体中的数据流转规则 谁产出什么、谁消费什么、流转顺序与分支条件
业务 DSL（输出模具） 「输出的模具」 单次模型调用，收敛输出 把模型自由散漫的文本强制规范为结构化数据（如 JSON），大幅提升输出的语法有效性与可解析性

三者是从宏观到微观的三道闸门：State Schema 管"共享什么"，Graph Schema 管"怎么流动"，业务 DSL 管"单次产出是否合格"。

2.7 LLM模态选型原则

模态 方向 说明
文本内容 内容生成 通用文本生成、摘要、改写、翻译
图片内容 文生图 / 图生图 设计稿生成、UI 草图转图
音频内容 文生音频（TTS） 播报、配音
视频内容 文生视频 / 图生视频 Seedance 等视频生成模型

选型原则：按步骤分模------规划与编码用强推理模型，摘要与格式化用低成本小模型，多模态任务才上多模态模型。

第 3 章 通用智能体架构设计

3.1 四个设计原则

定位：作为通用智能体架构负责人，在项目启动时确立四条不可妥协的设计原则，所有技术决策必须通过这四条原则的检验。

原则 核心表述 落地判据（如何检验一条新需求是否合规）
原则一：依赖倒置 核心 Loop 依赖抽象协议，不依赖具体模型 SDK 与工具实现 Model 接口是唯一模型接入点，Tool 接口是唯一工具接入点。切换供应商、新增工具，核心 Loop 一行代码都不改
原则二：协议先行 Message / Tool / Model / AgentEvent 是系统宪法，先锁协议再写实现 协议变更必须走架构评审；协议稳定 → 各模块可并行开发、独立测试（可 mock 协议做单测）
原则三：核心精简 Loop 内核保持最小正确闭环（约 100 行有效代码），复杂能力通过 Harness 外壳与钩子系统扩展 若某功能需 >120 行才能塞进核心 → 它应该被抽到扩展层
原则四：扩展开放 对扩展开放（钩子 / 插件 / 技能 / MCP），对修改关闭（核心 Loop 稳定） 产品层差异化需求通过配置 + 扩展点实现，而不是 fork 核心代码；多产品线共享同一内核

四条原则的内在关系：原则一/二保证可替换 （不锁定供应商），原则三保证可维护 （内核小 ⇒ bug 少、可测），原则四保证可规模化复用（一套内核 N 个产品线）。

3.2 三层架构全景

关于分层编号（先看这张表，后文所有编号以此为准）：本文档有三处出现分层视角，编号不同、含义不同，不要混用。

视角 编号 含义
第 3 章 · 运行时三层（本章） L1 / L2 / L3 L1 模型协议层 · L2 通用编排层 · L3 产品能力层
5.4 节 · 团队分层 L1 ~ L4 在运行时三层之上，把 L3 再拆为「L3 能力层（可复用）+ L4 业务层（差异化）」
Q11 · 自研框架五层 E0 ~ E4 工程落地视角：E0 适配层 / E1 协议层 / E2 内核层 / E3 编排层 / E4 生态层

对应关系：E1 ≈ L1，E2 + E3 ≈ L2，E4 ≈ L3，E0 是 L1 中 Provider 适配的下沉。

  • L1 模型协议层：唯一职责就是把不同模型供应商的 API 统一成内部 Model 接口 。核心包零 LLM SDK 依赖，所有 Provider 作为独立包实现。
  • L2 通用编排层：Agent 的运行时内核 ，包含 Loop 与 Harness 外壳，Loop 负责最小闭环，Harness 负责生产级能力。
  • L3 产品能力层：面向具体产品场景，在共享内核之上构建差异化能力。

3.3 L1 模型协议层

能力 说明
统一多 Provider API OpenAI / Anthropic / Google / Bedrock / 本地模型（Ollama、vLLM、llama.cpp），每个 Provider 独立包、独立发版
流式 EventStream 统一流式响应协议，支持三种增量事件：text_delta、thinking_delta、tool_call_delta
消息协议转换 内部 Message → 各 Provider API 格式，自动处理 tool_calls、tool_call_id 等协议差异
Model Catalog（模型目录服务） 按能力 （推理/编码/多模态）、成本 、延迟 动态选型；配合 prepareNextTurn 钩子实现"简单任务用小模型、复杂任务用大模型"

设计要点：Provider 独立发版 ⇒ 某家 API 变更不影响其他家；Model Catalog 是成本治理的抓手（同一 Agent 内按步骤分级用模）。

3.4 L2 通用编排层

模块 关键设计
Agent Loop 内核 约 100 行，实现「模型调用 → 工具执行 → 结果回灌 → 再推理」最小闭环；含并行工具、maxTurns、AbortSignal、事件生命周期
流式响应 partial message 不变量，逐 token 推送 UI；首字等待从秒级降到百毫秒级
会话管理 会话持久化（JSONL 文件或 SQLite）、会话树（分支 / 回溯 / 时间旅行）、状态管理
上下文压缩 消息历史超 token 预算时，自动用模型摘要旧消息并保留关键信息，防止上下文窗口溢出
技能系统 可加载的指令包，在特定场景注入 system prompt 或工具，类似「专家模式」切换
钩子系统 8 个生命周期钩子（见下表），产品层零修改核心代码即可定制行为
遥测与状态归约 token 用量统计、工具调用追踪、性能指标采集；AgentEvent 流归约为不可变 UI 状态，支持时间旅行调试
Sandbox 沙箱 工具执行沙箱化、文件系统隔离、网络访问白名单、高危操作人工确认

8 个生命周期钩子：

复制代码 
beforeToolCall   → 工具调用前：权限校验、参数改写、危险命令拦截
afterToolCall    → 工具调用后：输出截断、敏感信息脱敏、结果入库
prepareNextTurn  → 下一轮前：上下文组装、模型动态选型（大小模型切换）
shouldStopAfterTurn → 停止判定：是否达到 maxTurns / 目标契约 / 预算上限
getSteeringMessages → 注入转向消息（用户中途插话、优先级调整）
getFollowUpMessages → 注入追问消息（子任务完成后自动续接）
transformContext → 上下文转换：压缩、裁剪、重排、外化到文件
convertToLlm    → 最终 LLM 请求格式转换（消息 → Provider 格式；部分框架文档写作 convertToLLM）

3.5 L3 产品能力层

方向 内容
领域工具集 编码工具（bash / read / write / edit / grep / find / ls）、浏览器自动化（Playwright）、知识库检索（RAG 工具）、企业内部系统工具
多端交互界面 TUI 终端（差分渲染、键盘绑定）；Electron 桌面端（Local Daemon + IPC）；Web/H5（SSE 流式渲染、多模态消息）；移动端（React Native + 双向信令）
扩展系统 Extensions 第三方插件、MCP 服务接入、斜杠命令（/clear、/model、/help）

三层之间的依赖方向严格向下：L3 → L2 → L1 ，禁止反向依赖；跨层通信一律走协议（L2 只认 Model 接口，不认 OpenAI）。

第 4 章 智能体核心执行流程

4.1 七层链路

复制代码 
① 入口与目标解析（目标契约化）
        ↓
② 模型层：决策与规划（产出子任务 DAG）
        ↓
③ 执行编排层：调度 + 异常回退（控制平面）
        ↓
④ 子智能体层：角色化能力切片
        ↓
⑤ 技能层：行为规范与执行标准（SOP）
        ↓
⑥ 工具层：实际执行
        ↓
⑦ 持久化层：结果落盘 + 安全校验（横切）
层 职责 关键设计
① 入口与目标解析 目标契约化 ，而非直接调用模型。把模糊指令转化为可验证的完成标准与终止条件，产出结构化任务描述 契约 = 完成标准（DoD）+ 终止条件 + 验收方式。没有契约就没有"完成"，循环无法收敛
② 模型层：决策与规划 意图理解、任务分解、下一步动作选择 复杂场景下模型不直接执行 ，而是生成子任务 DAG------这是编排层能调度和回退的前提
③ 执行编排层 整个流程的控制平面。读取子任务 DAG，按依赖关系把就绪任务分发给子智能体，监控每个节点状态 支持并行分发、依赖门控、失败重试、局部回滚、人工接管
④ 子智能体层 接收子任务、调用技能层、回传结果（检索智能体 / 代码智能体 / 分析智能体） 角色化切片 ⇒ 每个子智能体上下文干净、职责单一；上下文隔离是最有效的 token 经济手段
⑤ 技能层 子智能体与工具之间的中间规范层 。把通用工具封装为带约束的 SOP 定义：参数校验规则、输出格式要求、失败重试策略、安全边界。⇒ 同一套工具可被不同子智能体复用，但遵循各自的场景行为规范
⑥ 工具层 真实执行：检索、文件读写、代码执行、API 调用 向技能层返回原始结果，由技能层完成格式化与初步校验后再交给子智能体
⑦ 持久化层 横切全链路：中间结果、工具调用记录、模型决策轨迹落盘 用途：断点恢复、审计追踪、安全校验 （输出内容过滤、权限裁剪）。⚠️ 不是流程终点才触发，而是编排层每调度一步就同步写入，否则异常回退时无可恢复状态

一句话总结架构哲学：模型负责"想"，编排层负责"管"，技能层负责"规范"，工具层负责"做"，持久化层负责"记住"。

4.2 运行流程（以 Codex 类系统为例）

复制代码 
 1. 智能体加载        → 读取 Agent 配置（AGENT.md、权限、模型、技能清单）
 2. 模型初始化        → 实例化 Provider、注入 Model Catalog 选型结果
 3. Skill 加载        → 按需/全量加载技能包，注入 system prompt 与工具集
 4. Workspace 映射    → 工作区挂载 + 沙箱初始化（文件系统隔离、网络白名单）
 5. 提示词层面处理    → 目标契约化、上下文组装、System/User/Tool 消息分层
 6. 工具识别          → Tool / MCP / Skill 三层工具发现与注册
 7. 搜索引擎调用      → Tavily（AI 优化的检索 API）等外部检索
 8. 获取搜索结果      → 原始结果返回 + 去重/截断
 9. 结果用 LLM 加工   → 摘要、结构化、与任务目标对齐
10. 文件操作与落盘    → 写入本地文件系统（沙箱内），同步写持久化层
11. 验证与交付        → 跑测试 / lint / 类型检查，输出改动说明、风险提示与回滚方案

第 5 章 框架对比与选型

5.1 主流框架能力对比

框架 语言 定位 核心价值
LangChain Python / TS 组件抽象层 统一封装模型、提示词、工具、检索等核心组件，降低 LLM 应用入门门槛与跨平台迁移成本
LangGraph Python / TS 有状态图运行时 基于节点、边、状态的图模型，支持循环、分支、人机协同、断点续跑；是生产级复杂工作流的核心载体
DeepAgents Python / TS 开箱即用的 Agent Harness 在 LangChain/LangGraph 之上封装通用智能体高频能力（文件系统沙箱、子智能体、技能体系、输出收敛、路径安全），是快速落地 Claude Code / Codex / OpenClaw 类系统的最省路径
Spring AI Java Java 生态集成 面向 Spring 生态的模型/向量/工具抽象，适合 Java 存量系统内嵌 AI 能力
AgentScope-Java Java 多智能体编排 阿里开源的 Java 多智能体框架，适合 Java 团队做多 Agent 协作

5.2 LangChain 标准化模型接口的价值（避免供应商锁定）

LangChain 基于 BaseLLM / ChatModel 等核心抽象定义标准化模型接口，是破解供应商锁定的关键：

  • 抹平协议差异 ：统一 Ollama（@langchain/ollama）、OpenAI、云厂商模型等不同供应商的调用协议、参数格式、返回结构。
  • 切换成本归零 ：当前用本地 Ollama，后续切云端大模型，只需替换模型实例化逻辑（OllamaChatModel → ChatOpenAI），无需修改 提示工程、工具调用（如 d3-dsv 数据解析、PostgreSQL 交互）、Agent 编排等核心业务代码。
  • 统一横切逻辑：错误处理、上下文管理、流式输出等通用逻辑统一，降低切换成本。
  • 支持混合调用 ：核心场景用云端模型、低成本场景用本地 Ollama ------ 规避单一供应商的定价、稳定性、合规风险。

5.3 LangChain vs LangGraph 选型逻辑

选型锚点：业务复杂度与流程特性。

场景 选择 理由
轻量场景 ：线性流程、单轮/简单多轮交互（如基于 PostgreSQL 数据的问答、d3-dsv 解析后直接返回结果） LangChain AgentExecutor、PromptTemplate 等组件开箱即用，开发效率高，适配中小规模、无复杂状态管理的业务
复杂场景 ：非线性流程、多角色协作、状态持久化/容错重试（如「数据拆分（@langchain/textsplitters）→ 入库 → 推理 → 纠错」闭环） LangGraph 基于 LangChain 核心扩展，主打有状态的推理图 ，支持节点拆分、条件分支、循环执行，能精准描述复杂 Agent 的状态流转；且可嵌套复用 LangChain 的工具/提示组件，适配需可解释、可干预的复杂决策场景

三层关系一句话：LangGraph 是运行时（图），LangChain create_agent 是轻量 Harness，DeepAgents 是重 Harness。 三层可组合：任何 LangGraph CompiledStateGraph 都可以作为子智能体传入 Deep Agent。

5.4 可解耦、可演进的 Agent 分层架构（支撑团队业务）

本图沿用 L1~L4 编号：在[第 3 章](#第 3 章)运行时三层的基础上，把 L3 产品能力层拆为「L3 能力层（可复用）+ L4 业务层（差异化）」，编号对照见 [3.2 节](#3.2 节)。

复制代码 
┌─────────────────────────────────────────────────┐
│ L4 业务层：产品差异化配置 + 业务 DSL + 领域工具集   │  ← 各业务线独立演进
├─────────────────────────────────────────────────┤
│ L3 能力层：Skill / Plugin / MCP / 中间件链         │  ← 可插拔，热插拔式扩展
├─────────────────────────────────────────────────┤
│ L2 编排层：Agent Loop + Harness + 钩子系统         │  ← 团队共享内核，极少变更
├─────────────────────────────────────────────────┤
│ L1 协议层：Message / Tool / Model / AgentEvent     │  ← 系统宪法，变更需架构评审
└─────────────────────────────────────────────────┘

解耦三板斧：

  1. 协议先行：层与层之间只认协议，不认实现 ⇒ 可并行开发、可 mock 测试。
  2. 配置驱动：业务差异走配置（模型选型、工具白名单、系统提示词、钩子开关），不改代码。
  3. 扩展点收敛 ：所有差异化需求必须落到扩展点（钩子/插件/Skill/MCP），禁止 fork 内核。

第 6 章 智能体执行指标体系

6.1 核心效率指标

  • 任务是否成功完成
  • 是否首轮执行无返工并通过校验
  • 总执行步骤
  • 人工复核时长

6.2 质量指标

  • 代码规范合规率
  • 类型安全率
  • 测试覆盖率
  • 上线后回归缺陷数量
  • 缺陷率 = 回归缺陷数量 / 总改动代码行数

6.3 成本指标

  • 总 Token 消耗
  • 输入 Token 量
  • 输出 Token 量
  • 总执行成本

6.4 风险指标

  • 权限拦截次数
  • 风险预警次数
  • 回滚次数
  • 是否通过审计

指标间的制衡关系 ：压缩执行步骤（效率）往往抬高缺陷率（质量）；加大上下文（质量）直接推高 Token 成本（成本）；放宽权限拦截（效率）会抬升风险指标。架构调优本质是在四象限指标间找平衡点。

6.5 指标使用原则

  • 效率看任务闭环，不只看生成速度。
  • 质量看外部验证，不只看模型自评。
  • 成本看单位成功任务成本，不只看单次调用价格。
  • 风险看拦截与恢复能力，不只看是否出事。

第 7 章 常见问题

7.1 初中级

Q1（TS 基础）你 TypeScript 掌握怎么样？TypeScript 与 Zod 为什么会在 AI Agent 开发中应用广泛？你认为前端往 Agent 能有哪些沉淀？

作答骨架：

  1. TS 能力自评维度 ：类型系统（泛型、条件类型、映射类型、模板字面量类型）、类型收窄与判别联合、声明合并、工程化（tsconfig strict 配置、声明文件、monorepo 构建）。
  2. 为什么 TS 适合 Agent ：
    • Agent 是事件流驱动 的：AgentEvent 天然适合用**判别联合（Discriminated Union）**表达，配合 switch + 穷尽性检查（never）保证事件处理的完备性 ------ 新增一种事件类型时，未处理的地方会直接编译报错。
    • Agent 要对接 N 个模型 Provider，接口契约是这个领域的核心资产，TS 的接口/类型本身就是文档。
    • 流式与异步密集：AsyncIterable / AsyncGenerator 在 TS 中表达流式响应非常自然。
  3. 为什么 Zod 在 Agent 中无处不在 （核心论点）：
    • 工具入参校验：LLM 输出的参数是"不可信输入"，必须在执行前用 Schema 校验，并把结构化错误信息回灌给它重试。
    • 一份 Schema 三处生效 ：z.infer 给编译期类型、schema.parse 给运行时校验、zodToJsonSchema 转成 JSON Schema 下发给模型做 Structured Output ------ 写一次，三处复用，避免"类型说一套、运行时是另一套"。
    • 错误可回灌：Zod 的错误是结构化的（path + message），可直接拼成消息回给模型让它自我修正 ------ 这就是 Loop 里的 Observation。
ts 复制代码 
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ReadFileInput = z.object({
  path: z.string().describe("文件绝对路径"),
  offset: z.number().int().nonnegative().optional(),
  limit: z.number().int().positive().optional(),
});
type ReadFileInput = z.infer<typeof ReadFileInput>;   // ① 编译期类型

export const readFileTool: Tool<ReadFileInput, string> = {
  name: "read_file",
  description: "读取文件内容",
  schema: ReadFileInput,                              // ② 运行时校验
  jsonSchema: zodToJsonSchema(ReadFileInput),         // ③ 下发给模型的工具定义
  async execute(input, ctx) {
    const safePath = ctx.sandbox.resolve(input.path); // 沙箱路径校验，防止越权读取
    return ctx.fs.readRange(safePath, input.offset, input.limit);
  },
};
  1. 前端往 Agent 沉淀的四块能力 ：
    • 流式渲染与体验工程：SSE/WebSocket 流式、增量 DOM 更新、首字延迟（TTFT）优化 ------ 这是 Agent 产品体验的护城河（首字从秒级降到百毫秒级）。
    • 状态管理：Agent 的不可变状态归约（Event → State）本质就是 Redux 模型的复用，前端天然熟悉。
    • 工具与 UI 的桥梁：MCP、插件市场、可视化编排画布 ------ 都是前端的主场。
    • 工程化与质量保障 ：构建、lint、测试、类型安全 ------ 直接对应 Agent 的 Verifier 环节。

一句话收尾：TS 的价值是把"Agent 的协议"变成编译期可检查的事实；Zod 的价值是把"LLM 的不可信输出"变成可校验的数据。

Q2（通用智能体）你知道怎么搭建一个通用型智能体吗？说说类似 OpenClaw、Codex 智能体的全栈设计思路

作答骨架：按"定位 → 能力 → 分层实现"展开。

  1. 定位与能力 ：见 [1.2 节表格](#1.2 节表格)（目标导向、任务分解、子智能体并发、多工具协同、文件/OS 级操作、Skill 调用）。

  2. 全栈分层设计：

    接入层 多渠道入口（CLI / TUI / 聊天渠道 / IDE 插件）→ 统一收敛到 Agent Runtime
    ↓
    执行层 Harness：权限、沙箱、持久化、审批(HITL)、观测
    ↓
    内核层 Agent Loop：模型调用 → 工具执行 → 结果回灌 → 再推理（含 maxTurns / Abort）
    ↓
    能力层 Planning（TodoList）· SubAgent（上下文隔离）· Filesystem（大结果外化）· Compaction（上下文压缩）· Skills
    ↓
    协议层 统一 Model 接口（多 Provider）+ 统一 Tool 接口（本地/MCP）
    ↓
    模型层 Model Catalog：按能力/成本/延迟动态选型

  3. 最小可跑版本（MVP）路径 ：

    • 第一步：跑通「模型 + 一个工具 + Loop」的闭环（约 100 行核心）。
    • 第二步：加 Harness ------ 权限白名单 + 工作区隔离 + 事件落盘。
    • 第三步：加 Planning 与 SubAgent ------ 撑住长任务。
    • 第四步：加压缩与外化 ------ 撑住超长任务。
    • 第五步：加多渠道接入与 HITL ------ 产品化。
Q3（前端视角）作为前端开发，请说说你对于 AI 提效工具的理解，Codex、Trae、OpenClaw 这些工具听过吗？说说你的看法

作答骨架 ：核心论点 ------ AI 提效工具的演进主线是"代码生成 → 工程链路闭环（端到端交付）"。

四个层次递进：

  1. 上下文深度理解 ：不只是读当前文件，而是理解旧代码、代码风格、代码约束 ------ 载体就是 AGENT.md / .cursorrules 这类仓库级约定文件 。仓库有没有写好约束文件，直接决定工具效果上限。
  2. 全链路调用执行 ：模型 ≠ 智能体。Agent = LLM + Planning + Memory + Tool Use。关键是把 Agent 内各组件的调用、流程、步骤、计划都用统一 Schema 规范描述出来（计划可执行、步骤可回退）。
  3. 反思优化（结果自动校验）：不是生成完就结束，而是自动跑 lint / 类型检查 / 单测，把失败信息回灌给模型重试 ------ 这就是 Loop Engineering 的验证器。
  4. 交付物完整性 ：不仅给 diff，还要给出改动说明、测试结果、风险提示。

工具对比看法：

工具 形态 特点
Codex / Claude Code CLI + IDE 通用智能体，OS 级能力，适合工程链路闭环；模型能力强、可控性高
Trae AI IDE 面向开发者的集成环境，强调中文场景与工程内闭环
OpenClaw 本地开源个人助手（Node ≥ 22，MIT） 多渠道入口（WhatsApp/Telegram/Discord/企微等）+ Browser/Exec/Web 工具 + Gateway 安全边界；强调本地运行、数据自主、持久记忆、可自建 Skill

判断标准：从"能不能生成代码"升级为"能不能在真实仓库里跑完测试并交付 "，以及"出问题时我能不能审计和回滚"。

Q4（Harness 入门）有没有了解过 Harness？为什么需要 Harness？在你的 Agent 产品中如何设计 Harness 体系？

作答骨架：

  1. Harness 是什么 ：包裹在「模型 + 工具调用循环」之外的一整套脚手架 ------ 系统提示词、计划与步骤追踪、中间结果存放处、子任务委派机制、上下文防溢出策略。Agent ≠ 模型，Agent = 模型 + Harness。
  2. 为什么需要（解决四个真实痛点）：
痛点 Harness 的解法
长任务跑飞、丢失目标 Planning：显式的 TodoList，能从二十次工具调用后找回位置
大工具结果污染上下文 Filesystem：40K token 的抓取结果写文件，按需 grep 取片段
上下文窗口撑爆 Compaction：摘要压缩；大结果外化（offloading）
输出不稳定、有幻觉、不可控 Verifier（测试/lint）+ Guardrail（沙箱/权限/审批）+ 可观测

  1. 如何设计自己的 Harness 体系（五件套）：

    ① 权限与沙箱层 工具白名单、路径沙箱、网络白名单、高危操作人工确认
    ② 状态与持久化层 JSONL/SQLite 落盘、Checkpoint、崩溃可恢复、可审计
    ③ 验证与检查层 每轮执行后自动 lint / typecheck / test，失败信息回灌重试
    ④ 上下文管理层 预算监控、压缩策略、外化策略、检索注入
    ⑤ 可观测层 事件流、token 统计、轨迹追踪、时间旅行调试

落地形态：Harness 不是写进 Loop 里，而是以**中间件（Middleware）**形式挂载 ------ 可插拔、可替换、可禁用（这正是 DeepAgents 的做法）。

Q5（认知）前端为什么要学全栈 Agent？跟传统前端工程有什么区别？Harness 和 Loop 这些概念到底是什么？

作答骨架：

  1. 为什么前端要学全栈 Agent ：
    • 交付物形态变了：从"交付页面"变成"交付能自动完成任务的程序"。
    • 前端是 Agent 的体验主战场：流式渲染、多端界面、工具可视化、插件市场。
    • 前端的工程化能力（构建、测试、类型、CI）直接就是 Agent 的 Verifier 环节。
  2. 与传统前端工程的区别：
维度 传统前端工程 Agent 工程
控制流 确定性代码分支 模型决定的非确定性分支
状态 可枚举的 UI 状态 对话/任务态 + 上下文窗口（有限资源）
错误处理 try/catch + 边界分支 把错误回灌给模型让它自我修复
调试 断点、DevTools 轨迹回放 / 时间旅行调试
测试 单测 + E2E（确定性断言） 评测集 + 指标（成功率、返工率、成本）
成本 运行时性能 Token 成本 + 延迟
  1. Harness 与 Loop 的通俗解释 ：
    • Loop = 心跳/引擎：执行 → 观察 → 再决策，并回答"何时继续、何时停"。
    • Harness = 底盘/驾驶舱：权限、沙箱、持久化、验证检查 ------ 回答"在什么环境里跑、边界在哪"。
    • 类比：Loop 是发动机循环，Harness 是整车底盘 + 仪表盘 + 安全带。

7.2 中高级

Q6（TS 框架）基于 TypeScript 搭建 AI Agents 基础框架（参考 LangGraph 核心能力），说说你的核心设计思路与关键代码实现逻辑

作答骨架：先讲设计思路（4 点），再给关键代码（3 段）。

设计思路：

  1. 协议先行 ：先定义 Message / Tool / Model / AgentEvent 四个协议，再写实现。
  2. State 用不可变 + Reducer ：每个节点的输出是 Partial<State>，由框架做归约，天然支持 Checkpoint 与时间旅行。
  3. 图是编译期的产物 ：StateGraph 声明节点与边 → compile() 得到可执行对象（LangGraph 的核心思想），编译期可校验边引用的节点是否存在。
  4. 流式与持久化正交：流式只是"把事件往外 emit"，持久化只是"把 Checkpoint 存下来"，两者都不侵入节点逻辑。

关键代码 ①：协议层（系统宪法）

ts 复制代码 
// ------ 消息协议 ------
export type Role = "system" | "user" | "assistant" | "tool";
export interface Message {
  id: string;
  role: Role;
  content: string | ContentPart[];
  toolCalls?: ToolCall[];
  toolCallId?: string;
}

// ------ 模型事件流（统一流式协议）------
export type ModelEvent =
  | { type: "text_delta"; delta: string }
  | { type: "thinking_delta"; delta: string }
  | { type: "tool_call_delta"; index: number; name?: string; argsDelta?: string }
  | { type: "done"; finishReason: "stop" | "tool_calls" | "length" };

// ------ 模型接口：唯一接入点（依赖倒置）------
export interface Model {
  readonly id: string;
  stream(req: ChatRequest, signal?: AbortSignal): AsyncIterable<ModelEvent>;
}

// ------ 工具接口：唯一接入点（Zod 同时用于校验与 JSON Schema 下发）------
export interface Tool<I = unknown, O = unknown> {
  name: string;
  description: string;
  schema: z.ZodType<I>;
  execute(input: I, ctx: ToolContext): Promise<O>;
}

关键代码 ②：Loop 内核（最小正确闭环，约 100 行）

ts 复制代码 
export async function* runLoop(
  model: Model, tools: ToolRegistry, state: AgentState, hooks: Hooks, signal?: AbortSignal
): AsyncGenerator<AgentEvent> {
  for (let turn = 0; turn < state.maxTurns; turn++) {
    // ① 中断检查：用户 Esc / 超时 / 上层取消
    if (signal?.aborted) { yield { type: "aborted" }; return; }

    // ② 钩子：转向消息（中途插话）→ 上下文组装 → 模型动态选型 → 请求格式转换
    const steering = (await hooks.getSteeringMessages?.(state)) ?? [];
    const ctxMessages = await hooks.transformContext(state);
    const chosen = hooks.prepareNextTurn?.(state) ?? model;
    const request = hooks.convertToLlm?.({ messages: [...ctxMessages, ...steering], tools: tools.defs })
      ?? { messages: [...ctxMessages, ...steering], tools: tools.defs };

    // ③ 模型调用 + 流式增量下发
    const acc = createStreamAccumulator();
    for await (const ev of chosen.stream(request, signal)) {
      acc.push(ev);
      yield toAgentEvent(ev);          // partial message 不变量：逐 token 推 UI
    }
    state.messages.push(acc.toMessage());

    // ④ 无工具调用 → 先判停止；未停且有追问依据才续接，否则跳出（否则会空转到 maxTurns）
    if (acc.toolCalls.length === 0) {
      if (await hooks.shouldStopAfterTurn?.(state)) break;
      const followUp = (await hooks.getFollowUpMessages?.(state)) ?? [];
      if (followUp.length === 0) break;      // 没有新信息 → 停止
      state.messages.push(...followUp);
      continue;
    }

    // ⑤ 并行执行工具：allSettled ⇒ 单个工具失败不炸整个 Loop，失败也作为 Observation 回灌
    const settled = await Promise.allSettled(acc.toolCalls.map(async (call) => {
      const input = await hooks.beforeToolCall(call);            // 可短路 / 抛错
      if (input.blocked) return { call, output: `blocked: ${input.reason}` };
      const out = await tools.invoke(call, input.args, signal);  // signal 透传，长命令可中断
      return { call, output: await hooks.afterToolCall(call, out) };  // 截断/脱敏
    }));
    const results = settled.map(coerceToolResult);               // rejected → 转错误 Observation

    // ⑥ 结果回灌 + 落盘（持久化是横切的，每步同步写）
    state.messages.push(...results.map(toToolMessage));
    await state.persistence.append(results);

    // ⑦ 停止判定
    if (await hooks.shouldStopAfterTurn?.(state)) break;
  }
}

关键代码 ③：Graph 层（状态机 + 条件边）

ts 复制代码 
// 示意代码：START / END / reduce / route / NodeFn / Checkpointer 定义在 core/state 模块，此处省略
type Edge<S> = { to?: string; router?: (s: S) => string };

export class StateGraph<S> {
  #nodes = new Map<string, NodeFn<S>>();
  #edges = new Map<string, Edge<S>[]>();
  #entry?: string;
  #maxSteps = 100;                                   // 环路保护：条件边允许成环，必须设上限

  addNode(id: string, fn: NodeFn<S>) { this.#nodes.set(id, fn); return this; }

  addEdge(from: string, to: string) {
    const list = this.#edges.get(from) ?? [];
    list.push({ to });
    this.#edges.set(from, list);
    if (from === START) this.#entry = to;             // 记录入口节点
    return this;
  }

  addConditionalEdge(from: string, router: (s: S) => string) {
    const list = this.#edges.get(from) ?? [];
    list.push({ router });
    this.#edges.set(from, list);
    return this;
  }

  compile(checkpointer?: Checkpointer<S>) {
    // 编译期校验：静态边指向的节点必须存在（把"边指向不存在节点"提前到编译期）
    for (const [from, edges] of this.#edges)
      for (const e of edges)
        if (e.to && e.to !== END && !this.#nodes.has(e.to))
          throw new Error(`edge ${from} -> ${e.to}: unknown node`);
    if (!this.#entry) throw new Error("graph has no entry node: addEdge(START, '<node>')");

    return {
      invoke: async (input: S) => {
        let state = input;
        let cursor: string = this.#entry!;            // 从真实入口节点开始，而不是 START 本身
        let steps = 0;

        while (cursor !== END) {
          if (++steps > this.#maxSteps)
            throw new Error(`graph exceeded maxSteps=${this.#maxSteps}`);

          const node = this.#nodes.get(cursor);
          if (!node) throw new Error(`unknown node: ${cursor}`);

          state = reduce(state, await node(state));   // 不可变归约
          await checkpointer?.save(state);            // Checkpoint：断点续跑
          cursor = route(this.#edges, cursor, state);
        }
        return state;
      },
    };
  }
}

加分点 ：说明 reduce 的 Delta Channel 设计 ------ 消息列表若每次全量 Checkpoint 是 O(N²)，LangGraph 用 DeepAgentState 的 DeltaChannel 降到 O(N)。

Q7（LangChain 选型）聊聊 LangChain 标准化模型接口对避免供应商锁定的价值，以及如何根据业务复杂度在 LangChain 和 LangGraph 之间做选型？如何设计可解耦、可演进的 Agent 分层架构来支撑团队业务？

原题自带完整答案，已整理至 [5.2 节](#5.2 节)、[5.3 节](#5.3 节)、[5.4 节](#5.4 节)。

补充三条重要论点：

  1. 避免锁定的真正落点不是"换模型"，而是"换模型后行为不变" ------ 需要统一的流式协议、错误处理语义、tool_call_id 关联规则，否则换供应商后 Loop 逻辑要重写。
  2. 混合调用是更现实的收益：核心步骤用强模型、批量格式化用小模型，成本可降一个量级。
  3. 解耦的验收标准：新接一个业务线，是否需要改动内核仓库的代码？若答案是"只需新增配置 + 一个插件包"，架构才算成立。
Q8（模型与智能体）请站在前端角度深刻聊聊模型和智能体的关系，如何选择模型、如何开发智能体来支撑团队或者公司业务？

作答骨架：

  1. 关系一句话 ：模型是"大脑"（单次推理），智能体是"人"（目标 + 规划 + 记忆 + 工具 + 验证 + 安全 + 观测）。模型能力的上限决定智能体的上限，但智能体的实际表现由 Harness 决定。

    智能体 = LLM + Planning + Memory + Tool Use + Verifier + Guardrail + Telemetry

类比：模型是发动机，智能体是整车。同一个发动机，装在不同底盘上，能跑的路完全不同。

  1. 如何选择模型（四个维度 + 分层策略）：
维度 考察点
能力 推理 / 编码 / 长上下文 / 多模态 / 工具调用稳定性
成本 输入输出单价、是否有 Prompt Caching、批处理折扣
延迟 首字延迟（TTFT）、吞吐 ------ 直接决定交互体验
合规 数据出境、私有化部署（本地 Ollama / vLLM）要求

分层选型策略（Model Catalog）：

  • 规划 / 复杂编码 / 关键决策 → 强推理模型
  • 摘要 / 格式化 / 分类 / 路由 → 低成本小模型
  • 多模态任务（文生图、图生视频、TTS）→ 专用模型（如 Seedance 类）
  • 数据敏感场景 → 本地/私有化模型
  1. 如何开发智能体支撑团队业务（落地四步） ：
    • Step 1 · 选场景：高频、有明确完成标准、可验证（能跑测试/能对账）------ 例如"自动修复 CI 失败"、"需求文档生成代码骨架 + 测试"。
    • Step 2 · 沉淀仓库约束 ：AGENT.md（代码风格、目录约定、禁止事项）------ 这是投入产出比最高的一件事。
    • Step 3 · 搭 Harness ：权限白名单 + 沙箱 + 测试验证器 + 轨迹落盘。先有护栏，再放开能力。
    • Step 4 · 建度量 ：用[第 6 章](#第 6 章)四象限指标（效率/质量/成本/风险）持续调优，而不是凭感觉。
Q9（工程链路）实现"从 Vite 构建到 Agent 自动修复 Bug"的功能，完整工程链路是怎么设计的？

作答骨架（自顶向下）：

复制代码 
负责的功能 → 架构设计 → 任务计划 → 开发测试 → 验证完成 → 交付实施培训

架构设计拆分（三层技术栈）：

层 技术栈 关键内容
应用层 Web / PC / 移动端 结果展示（diff、测试报告、风险提示）、人工审批入口、回滚按钮
服务层 Node / BFF / 任务队列 构建日志采集、任务编排、Webhook 触发、状态持久化、权限与审计
Agent 层 LLM + 五个 Engineering Prompt（修复规范）/ Context（错误上下文组装）/ Harness（沙箱+分支隔离）/ Loop（修复→验证→重试）/ Graph（生成节点 vs 检查节点分离）

执行链路（闭环设计）：

复制代码 
① 触发      CI / Vite build 失败 → Webhook → 服务层创建修复任务
② 上下文    采集：错误日志栈、相关源码、git diff、仓库约束（AGENT.md）
③ 契约化    定义完成标准：构建通过 + lint 通过 + 测试通过 + 无新增告警
④ 规划      模型产出修复计划（子任务 DAG：定位 → 修改 → 补测 → 验证）
⑤ 执行      Agent 在隔离分支/沙箱中改代码，每步落盘
⑥ 验证      自动跑 build / lint / test（Verifier），失败信息回灌重试
⑦ 收敛      达到 maxTurns 或连续 N 轮无进展 → 停止并转人工（停止协议）
⑧ 交付      PR + 改动说明 + 测试结果 + 风险提示 + 一键回滚
⑨ 度量      记录：返工轮次、token 成本、缺陷率、人工复核时长

关键难点：

  1. 上下文组装 ------ 错误日志要精准（不是全量 build 日志），要能反查源码位置。
  2. 验证器可信 ------ Verifier 必须独立、不可被模型绕过（Graph Engineering：写代码的节点与检查的节点分离，检查者用干净上下文、只看结果）。
  3. 安全边界 ------ Agent 只能在隔离分支操作，禁止直接推主干。
Q10（Harness / 术语辨析）DeepSeek Harness 的体系设计为什么会引起关注？背后的插件机制原理你有了解过吗？

术语辨析 ：原题写作 DeepSeekHarness。结合上下文（LangChain / LangGraph / DeepAgent 体系）与公开资料，更可能指 LangChain 的 deepagents Harness；若确实指 DeepSeek 官方发布的某个 Harness 实现，机制框架基本一致，具体细节应以官方文档为准。以下按"通用 Harness 体系 + DeepAgents 插件机制"作答。

作答骨架：

  1. 为什么引起关注 ：
    • 这类 Harness 把"Claude Code 之所以强大"的原因显式拆成了可复用的中间件 ，证明了Agent 的竞争力不只在模型，也在 Harness（脚手架）。
    • 模型无关：任何支持 tool calling 的模型（前沿 / 开源权重 / 本地 Ollama）都能用 ------ 打破模型锁定。
    • 开箱即用 + 完全可替换 ：create_deep_agent() 一行拿到完整能力，但每个中间件都可 inspect / 替换 / 禁用。
  2. 插件机制原理（核心：Harness 由 Middleware 组装而成）：
Middleware 提供的能力 解决的问题
TodoListMiddleware write_todos 规划工具，状态持久化在 agent state（pending/in_progress/completed） 长任务中不丢失目标；计划能存活于上下文压缩之后
SubAgentMiddleware task 工具，派生一次性、无状态子智能体，隔离上下文，只回传精简总结 最有效的上下文控制手段：子任务的"噪音中间过程"不污染父上下文
FilesystemMiddleware ls / read_file / write_file / edit_file / glob / grep（后端可为内存 / LangGraph Store / 真实磁盘） 大结果外化（offloading）：4 万 token 的抓取写文件后按路径引用
SummarizationMiddleware 上下文压缩：保留近期消息，早期消息替换为摘要 防止长任务"掉崖"；避免从头部粗暴截断导致丢失原始指令
AnthropicPromptCachingMiddleware 自动命中 Prompt Cache 长任务中 system prompt + 工具定义每步重发 ⇒ 直接省钱
PatchToolCallsMiddleware 修复被中断/取消的工具调用造成的消息历史破损 否则中途会抛 Provider 侧校验错误
SkillsMiddleware 按需加载可复用行为包 类似「专家模式」切换
  1. 底层机制原理 （一句话）：每个 Middleware = 「挂一批工具 + 注入一段 system prompt + 可选包一层调用拦截」的统一扩展单元 。create_deep_agent() 只是把默认中间件按序组装并 compile() 成一个 LangGraph 图。
python 复制代码 
from deepagents import create_deep_agent
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[web_search],
    system_prompt="You are an expert researcher.",
)   # 返回值：一个已编译的 LangGraph CompiledStateGraph
  1. 自主压缩（Autonomous Compaction）值得单独提 ：把"何时压缩"的决定权从 Harness 交给模型 ------ 给模型一个 compact_conversation 工具，让它在任务边界自行决定压缩时机（有门控：约在自动摘要触发点的一半才允许触发，保留最后约 10% 上下文）。这是从"Harness 决定"到"模型自管记忆"的范式转变。

补充：异步子智能体 通过 Agent Protocol 派发，立即返回 task id，父智能体继续工作；task id 持久化在 state 的 async_tasks 中，可存活于上下文压缩与外化。

7.3 专家级

Q11（自研框架）如果让你实现对标 LangGraph 的 TypeScript AI Agents 框架，说说你的整体架构设计、核心模块划分与底层源码实现的关键难点突破

作答骨架：按"整体架构 → 模块划分 → 难点突破"三段式。

一、整体架构（五层，严格单向依赖）

此处用 E0~E4 编号，避免与第 3 章的 L1~L3、5.4 节的 L1~L4 混淆。对应关系：E1 ≈ L1，E2 + E3 ≈ L2，E4 ≈ L3，E0 是 L1 Provider 适配的下沉（详见 [3.2 节](#3.2 节)）。

复制代码 
┌ E4 生态层  CLI / DevTools / 评测集 / 可视化编排 / 插件市场
├ E3 编排层  StateGraph · Node · Edge · Router · Checkpointer · SubAgent
├ E2 内核层  Agent Loop · Harness(中间件链) · 钩子系统(8个) · 事件总线
├ E1 协议层  Message · Tool · Model · AgentEvent · StateSchema（系统宪法）
└ E0 适配层  Provider 包（OpenAI/Anthropic/Google/Bedrock/Ollama）· MCP 客户端

二、核心模块划分

模块 职责 关键接口
core/protocol 协议定义（零依赖，最先锁定） Message、Tool、Model、AgentEvent
core/loop 最小闭环（≤120 行） runLoop(model, tools, state, hooks)
core/harness 中间件链、沙箱、审批、遥测 Middleware、use(mw)、Sandbox
core/graph 图定义与编译 StateGraph、compile(checkpointer)
core/state 不可变归约、Delta Channel、Checkpoint reduce()、Checkpointer
core/context 预算计算、压缩、外化、检索注入 ContextManager
providers/* 各供应商适配（独立包、独立发版） implements Model
tools/* 内置工具 + MCP 桥接 implements Tool

三、底层源码实现的 6 个关键难点与突破

# 难点 突破方案
1 流式增量与消息完整性（边推 token 边保证最终消息一致） 引入 partial message 不变量 + StreamAccumulator：增量事件只用于渲染，done 时产出唯一权威 message；tool_call_delta 按 index 分片累积后再解析 JSON（避免半截 JSON 无法 parse）
2 中断与取消（用户 Esc、超时、切模型） 全链路透传 AbortSignal；中断处必须写 PatchToolCallsMiddleware 补齐"孤儿 tool_call"（否则 Provider 校验报错）；中断状态落 Checkpoint 以便续跑
3 状态归约与 Checkpoint 的 O(N²) 问题 消息字段用 Delta Channel（只存增量 patch，读取时归并），把 Checkpoint 增长从 O(N²) 降到 O(N)
4 并行工具的确定性与错误隔离 Promise.allSettled + 每个工具独立超时与重试；失败结果也作为 Observation 回灌（让模型看到失败，而不是整个 Loop 崩溃）；结果顺序按 tool_call_id 对齐
5 上下文压缩的时机与无损性 双策略：阈值压缩 （兜底）+ 自主压缩（模型在任务边界自触发）；压缩前先把大结果外化到文件，压缩时保留原始指令与计划（TodoList 单独存 state，天然不丢）
6 图编译期的静态校验与类型推导 用 TS 模板字面量类型 + const 泛型让节点名成为字面量类型，addEdge(from, to) 的 to 只能填已注册节点名 ------ 把"边指向不存在节点"从运行期错误提前到编译期

四、可测试性设计（体现架构师素养）

  • Loop 只依赖 Model 接口 ⇒ 单测用 FakeModel 回放脚本化事件流，断言完整轨迹，不联网、不花钱、可重复。
  • 图用纯函数节点 ⇒ 节点级单测无需启动运行时。
  • 中间件链可单独装配 ⇒ 权限、截断、压缩各自独立测试。
Q12（系统设计）如果让你基于 DeepAgents 设计完整类似 OpenClaw、Codex 系统及操作 AI Agent，请给出你的设计方案和核心代码实现

作答骨架：按"三层资产划分"作答 ------ 这是本题的核心考点。

一、三层资产划分（题目给定，需展开）

层 需要做的事 选型
核心实现（从 0 开发） Skill + Tool + MCP ------ 这是业务差异化的真正所在 自研
框架（按业务组织、编排） 模型接入、任务调度、权限、持久化、可观测 LangChain / LangGraph / DeepAgents
大模型（评测、选型） 任务拆解与规划 + 内容生成 Model Catalog + 评测集驱动选型

二、总体架构

复制代码 
渠道接入层  WhatsApp / Telegram / 企微 / 钉钉 / CLI / Web
     ↓  （多渠道收敛到统一执行面）
Gateway 层  认证、限流、审计、路由、安全边界（对应 OpenClaw 的 Gateway）
     ↓
Harness 层  DeepAgents：Planning + Filesystem + SubAgent + Compaction + Skills + HITL 审批
     ↓
能力层      自研 Tool / 自研 Skill / 外部 MCP Server
     ↓
执行环境    沙箱（文件系统隔离、网络白名单、高危操作人工确认）
     ↓
持久化层    JSONL/SQLite + Checkpoint + 长期记忆（跨会话）
     ↓
可观测层    事件流、Token 统计、轨迹回放、四象限指标看板

三、核心代码（TypeScript / DeepAgents JS 风格示意）

ts 复制代码 
import { createDeepAgent } from "deepagents";
import { ChatAnthropic } from "@langchain/anthropic";
import { MultiServerMCPClient } from "@langchain/mcp-adapters";

// ① 接入外部 MCP 服务（能力来源之一）
const mcp = new MultiServerMCPClient({
  filesystem: { command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", workspace] },
  postgres:   { command: "npx", args: ["-y", "@modelcontextprotocol/server-postgres"], env: { PG_URL } },
});

// ② 自研 Tool（带沙箱与权限校验）
const bashTool = defineTool({
  name: "bash",
  description: "在沙箱中执行命令",
  schema: z.object({ cmd: z.string(), cwd: z.string().optional() }),
  async execute({ cmd }, ctx) {
    assertAllowed(cmd, ctx.policy.allowedCommands);   // 白名单 + 高危命令拦截
    return ctx.sandbox.exec(cmd, { cwd: ctx.sandbox.resolve(cwd ?? "."), timeoutMs: 30_000 });
  },
});

// ③ 自研 Skill（SOP：行为规范 + 输出格式 + 重试策略）
const bugfixSkill = defineSkill({
  name: "bugfix",
  triggers: ["修复", "fix", "CI 失败"],
  instructions: `
    1. 先复现：读取错误日志，定位到具体文件与行号
    2. 最小修改：只改动必要代码，禁止顺手重构
    3. 必须补测试：每个修复至少一条回归用例
    4. 自检：运行 build + lint + test，任一项失败则回到步骤 1
    5. 输出 JSON：{ files: string[], cause: string, tests: string[], risk: string }
  `,
  outputSchema: BugfixReport,          // 业务 DSL：收敛输出
  maxRetries: 3,
});

// ④ 组装 Agent（Harness 提供规划/文件系统/子智能体/压缩）
const agent = createDeepAgent({
  model: new ChatAnthropic({ model: "claude-sonnet-4-6" }),
  tools: [bashTool, ...(await mcp.getTools())],
  skills: [bugfixSkill],
  subagents: [{ name: "researcher", systemPrompt: "...", tools: [webSearch] }],
  middleware: [
    approvalGuard({ dangerous: ["rm -rf", "git push --force", "DROP TABLE"] }),  // HITL
    telemetry({ onEvent: (e) => metrics.record(e) }),                            // 可观测
  ],
  checkpointer: new SqliteCheckpointer("./.agent/state.db"),                     // 断点续跑
});

// ⑤ 流式执行 + 事件流归约为 UI 状态
for await (const ev of agent.stream({ messages: [{ role: "user", content: "修复 CI 失败" }] })) {
  uiState = reduceEvent(uiState, ev);   // 不可变归约，支持时间旅行调试
}

四、关键设计取舍（体现专家判断）

  1. 为什么用 DeepAgents 而不是裸 LangGraph ：规划、文件系统外化、子智能体、压缩这四件事是每个长任务 Agent 都要重写一遍 的，且极易写错（尤其是压缩丢指令）。用成熟 Harness 把团队精力集中在 Skill + Tool + MCP 上。
  2. 为什么 Skill 层必须独立 ：工具是"能力"，Skill 是"规范"。同一套文件工具，在 bugfix 里要求最小改动，在 refactor 里允许重排 ------ 规范差异放在 Skill，工具保持通用，这是复用与收敛的关键。
  3. MCP 的定位 ：MCP 解决"外部能力如何标准化接入"，是工具生态的 USB 接口；但 MCP 不解决"行为规范" ------ 仍需 Skill 层包装。
  4. 安全边界的落点 ：DeepAgents 官方明确"trust the LLM"模型 ------ Agent 能做工具允许的任何事。边界必须在工具/沙箱层强制，不能指望模型自律。
Q13（Coding Agent）如果让你开发类似 Codex 的 Coding AI 智能体，有没有明确的实现方案和思路？请实现一个核心功能版本 Codex

作答骨架：方案 + 最小可跑内核。

一、实现方案（七个模块）

模块 内容
1. 仓库理解 AGENT.md 约束、目录结构索引、依赖关系图；不是全量塞上下文，而是按需检索
2. 规划 TodoList 化任务（Planning），显式追踪 pending/in_progress/completed
3. 工具集 bash / read / write / edit / grep / find / ls，全部走沙箱路径解析
4. 上下文管理 大结果外化到文件、阈值 + 自主压缩、检索注入
5. 验证器 build / lint / typecheck / test，失败信息回灌重试（Loop 的核心）
6. 安全 命令白名单、路径沙箱、写操作 diff 预览、高危操作人工确认
7. 交付 变更清单 + 测试结果 + 风险提示 + 一键回滚（git stash / 分支隔离）

二、核心功能版本（最小可跑内核，TS 伪实现）

ts 复制代码 
// ------ 1. 最小 Loop：模型 → 工具 → 回灌 ------
async function codexLoop(goal: string, ctx: CodexContext) {
  const todos = await plan(goal);                 // ① 规划
  const state: State = { goal, todos, messages: [], turns: 0 };

  while (state.turns++ < ctx.maxTurns) {
    const resp = await ctx.model.chat({
      system: renderSystemPrompt(ctx.agentMd, todos),   // ② 仓库约束 + 计划注入
      messages: state.messages,
      tools: ctx.tools.defs,
    });

    if (resp.toolCalls.length === 0) break;             // ③ 无工具调用 → 收敛

    for (const call of resp.toolCalls) {
      const args = call.schema.parse(call.args);        // ④ Zod 校验（不可信输入）
      const out  = await ctx.tools.run(call.name, args, ctx.sandbox); // ⑤ 沙箱执行
      state.messages.push(toolMessage(call.id, truncate(out, ctx.budget))); // ⑥ 截断回灌
    }

    // ⑦ 验证器：外部事实优先于模型自述
    const verify = await ctx.verifier.run();            // build + lint + test
    if (verify.ok) return finalize(state);
    state.messages.push(userMessage(`验证失败：\n${verify.report}\n请修复后重试。`));
  }
  return handoffToHuman(state);                         // ⑧ 停止协议：转人工
}

三、三个决定成败的细节

  1. 编辑工具要"定位驱动"而非"全文重写" ：edit 用 old_string/new_string 精确替换，避免模型重写整个文件引入无关 diff。
  2. 验证器必须独立于模型：检查节点用干净上下文、只看 diff 和测试结果（Graph Engineering）。
  3. 工具输出必须截断 ：一次 cat 几万行会直接撑爆上下文 ------ 大结果一律写文件返回路径。
Q14（架构 Leader）假如你是 Leader，来负责高可用低耦合的 Agent 产品，请说一说你的完整架构与落地思路（微内核 / 插件化机制设计）

作答骨架 ：Leader 视角要回答四件事 ------ 架构、机制、落地节奏、治理。

一、架构：微内核 + 插件化

复制代码 
                 ┌──────────────────────────────────────┐
                 │        微内核（Microkernel）           │
                 │  ① 协议层：Message/Tool/Model/Event    │
                 │  ② Loop：≤120 行最小闭环                │
                 │  ③ 插件总线：注册 / 发现 / 生命周期      │
                 │  ④ 事件总线：emit → 归约 → UI State     │
                 └──────────────┬───────────────────────┘
                                │ 只能通过扩展点接入
   ┌──────────┬──────────┬──────┴──────┬──────────┬──────────┐
   │ Provider │   Tool   │ Middleware  │  Skill   │   MCP    │  ← 插件
   │  插件    │   插件    │    插件      │   插件    │  桥接插件 │
   └──────────┴──────────┴─────────────┴──────────┴──────────┘
                                │
                    ┌───────────┴───────────┐
                    │  Harness：沙箱/审批/观测 │  ← 由 Middleware 组装
                    └───────────────────────┘

微内核的边界（什么在内核，什么在插件）：

在内核（极少变更） 在插件（自由演进）
协议定义 模型 Provider
Loop 最小闭环 工具实现
插件注册与生命周期 中间件（权限/截断/压缩/缓存）
事件归约与 Checkpoint Skill、MCP 服务
停止协议与预算控制 渠道接入、UI 呈现

二、插件化机制设计（五个要素）

  1. 统一扩展点契约 ：所有插件实现同一个 Plugin 接口（name、version、capabilities、install(ctx)、dispose()）。
  2. 显式依赖声明 ：插件声明依赖的协议版本与能力（如 needs: ["fs.write", "net.outbound"]），内核做能力校验与冲突检测。
  3. 生命周期隔离：插件崩溃不影响内核 ------ 工具执行包在独立超时与错误边界内，失败转为 Observation 回灌。
  4. 权限随插件走 ：插件自带权限清单（白名单命令、可访问路径、网络域名），由 Harness 强制执行 ------ 不信任模型，也不信任插件。
  5. 热插拔与灰度：插件可运行时启用/禁用，支持按租户、按业务线灰度。

三、高可用设计（四道防线）

防线 措施
模型高可用 多 Provider 自动故障转移（fallback 链）、超时重试、降级到小模型
执行高可用 Checkpoint 断点续跑、幂等工具设计、超时与熔断
状态高可用 持久化写入优先于内存态；事件流可重放重建状态
成本高可用 Token 预算硬上限、单任务熔断、按步骤分级选模、Prompt Cache

四、落地节奏（避免"大爆炸重构"）

复制代码 
阶段一（0-1）：跑通最小闭环 ------ 一个模型 + 三个工具 + Loop + 事件落盘
阶段二（1-10）：补 Harness ------ 沙箱、权限、验证器、观测；此时才敢放开工具范围
阶段三（10-50）：抽出微内核 ------ 把协议与 Loop 固化为独立包，业务全部插件化
阶段四（50+）  ：多产品线复用内核 ------ 差异化 100% 走配置 + 插件；建评测与指标体系

五、治理机制（Leader 必须立的规矩）

  • 协议变更评审制：协议是宪法，变更必须评审 + 版本化（语义化版本 + 兼容期）。
  • 内核代码冻结：内核 PR 需架构组双人评审；业务方提需求一律走扩展点。
  • 插件准入清单：第三方插件需安全评审 + 权限最小化。
  • 指标驱动迭代：以第 6 章四象限指标为迭代依据（成功率、返工率、成本、风险拦截数）。
Q15（数据结构）State Schema、Graph Schema 与业务 DSL 分别约束什么？

作答骨架：

  • State Schema：约束共享状态，规定字段、类型与归并方式。
  • Graph Schema：约束协作结构，规定节点、边、条件分支与数据流转规则。
  • 业务 DSL：约束单次模型输出，把自由文本收敛为结构化、可校验的 JSON 或领域对象。
  • 一句话：State 管"共享什么"，Graph 管"怎么流动"，DSL 管"单次产出是否合格"。
Q16（指标体系）如何定义和评估智能体执行指标？

作答骨架：

  • 效率：任务成功率、首轮通过率、总执行步骤、人工复核时长。
  • 质量：代码规范合规率、类型安全率、测试覆盖率、回归缺陷数、缺陷率。
  • 成本：总 Token、输入/输出 Token、总执行成本、单位成功任务成本。
  • 风险：权限拦截、风险预警、回滚次数、审计通过情况。
  • 原则：以"单位成功任务"为口径，效率、质量、成本、风险四者平衡，不能只看单点最优。
Q17（架构治理）作为架构师，如何让多产品线共享同一套 Agent 内核？

作答骨架：

  • 内核只保留协议、Loop、状态与事件总线，保证稳定、极小、可测试。
  • 产品差异通过配置、Skill、工具、插件、钩子实现，不 fork 核心代码。
  • 建立协议版本管理、插件兼容性测试、灰度发布与快速回滚机制。
  • 平台团队维护内核与扩展点契约，产品团队只做扩展与场景化编排。
  • 用统一指标与评测集衡量各产品线效果，反哺内核演进。
Q18（Coding Agent 模块）类似 Codex 的 Coding Agent 应该划分哪些模块？

作答骨架：

模块 职责
Interface CLI/IDE 入口，接收任务、展示流式输出与 diff
Session/Runtime 会话生命周期、消息历史、状态与中断管理
Agent Loop 模型调用 → 工具执行 → 结果回灌 → 停止判断
Context Manager 上下文装配、文件检索、历史压缩、Token 预算
Tool Registry 注册、校验、执行 read/write/edit/bash/grep 等工具
Sandbox 文件系统与命令隔离、网络白名单、高危操作审批
Verifier 测试、lint、类型检查、结果断言
Memory/State 会话树、检查点、断点恢复
Policy 权限策略、审批流、操作边界
Telemetry 日志、链路追踪、Token 与成本统计

验收标准：能完成"定位 Bug → 修改代码 → 跑测试 → 输出 diff 与风险说明"的最小闭环。

附录 A：术语速查表

术语 含义
ReAct Reasoning + Acting，智能体的原子循环：Thought → Action → Observation
DAG 有向无环图，子任务依赖关系的表达方式，是编排层调度与回退的前提
Harness 包裹在模型+工具循环外的脚手架：系统提示、计划追踪、中间结果存放、子任务委派、上下文防溢出
Loop 最小执行闭环：模型调用 → 工具执行 → 结果回灌 → 再推理，含 maxTurns / AbortSignal
HITL Human-in-the-Loop，高危操作人工确认/审批
Checkpoint 状态快照，用于断点续跑与时间旅行调试
时间旅行调试 基于不可变事件流重放到任意历史时刻的状态
Offloading（外化） 把大工具结果写入文件、以路径引用，避免污染上下文窗口
Compaction（压缩） 上下文超预算时摘要旧消息；分阈值压缩与自主压缩两种
Delta Channel 状态字段只存增量 patch，把 Checkpoint 增长从 O(N²) 降到 O(N)
MCP Model Context Protocol，工具/能力标准化接入协议（"工具的 USB 接口"）
A2A / Agent Protocol 智能体间通信协议，支持异步子智能体派发与 task id 追踪
Skill 可加载的指令包，在特定场景注入 system prompt 或工具（"专家模式"切换）
SubAgent 子智能体，拥有隔离上下文，只向父智能体回传精简结论
Model Catalog 模型目录服务，按能力/成本/延迟动态选型
业务 DSL 约束单次模型输出的结构化模具（如 Zod Schema + Structured Output）
Verifier 外部验证器（build / lint / test），Loop 中决定是否重试的权威来源
Guardrail 安全护栏：权限、沙箱、审批、内容过滤
Telemetry 观测：Token 统计、工具追踪、性能指标、轨迹回放
TTFT Time To First Token，首字延迟 ------ Agent 体验的关键指标
JSONL 行式 JSON，常用的会话持久化格式（另一个选择是 SQLite）

附录 B：思考作答模板与一句话主线

B.1 五步作答模板

  1. 先说结论：一句话给出核心判断，直击重点。
  2. 再讲分层：从模型层、编排层、能力层、基础设施层展开。
  3. 强调边界：Loop、Harness、Skill、Tool、MCP 各管什么。
  4. 给验证方式：如何测试、如何回滚、如何观测、如何控制成本。
  5. 补落地经验：一个最小闭环案例，再说明如何扩展到生产。

B.2 一句话主线

text 复制代码 
控制权决定智能体形态，
协议决定系统能否协作，
Loop 决定任务能否闭环，
Harness 决定执行是否安全可控，
Skill 与 Tool 决定能力边界，
Verifier 决定结果是否可信，
Telemetry 决定系统能否持续优化。

最后一句 ：整套体系的收敛点可以概括为 ------ 用协议锁住变化，用 Harness 兜住不确定性，用 Loop 驱动收敛，用 Graph 组织分工，用指标衡量成败。

相关推荐
IT_陈寒1 小时前
Vue动态组件缓存的坑你踩过了吗？
前端·人工智能·后端
彩虹洋葱1 小时前
system_prompt 设为空、goal 设为 None，Claude 在虚拟荒岛跑了 30 小时：它开始给自己设目
人工智能
点PY1 小时前
《VLM-FO1》论文精读
人工智能
starzy19901 小时前
KafkaProducer 加载元数据：一条 MetadataRequest 的完整旅程
大数据·kafka
BSD_CGQ1 小时前
人形机器人触觉放量，柔性压力传感器采购该核验什么？
人工智能·机器人·压力传感器·源头工厂·柔性薄膜压力传感器
内容营销专家刘鑫炜1 小时前
AI搜索实战专家刘鑫炜：做AI搜索第一步，首先得让 AI 看到你
大数据·人工智能
鬼手爱剪辑1 小时前
短剧AI 配音技术的难点、原理、开源和闭源软件汇总-2026 年
人工智能
田里的水稻1 小时前
PyTorch_Dataloader\TensorBoard---数据加载与可视化
人工智能·pytorch·python·神经网络·机器学习
卿卿的产品经理日记2 小时前
【AI产品经理实战】Day 38｜try-except 踩坑实录：报错是数据
人工智能·笔记·python·学习·产品经理
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02如何新建文件夹？ 电脑新建文件夹的4种方法03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点05「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会06几个好用的ip纯净度检测网站07苹果iPA游戏软件资源下载网站08昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战09乙二醇水溶液物性参数10Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）