Appearance
Agent 工程实践与工具生态
方向定位：把"Agent 工程实践与落地"与"Agent 工具生态与意图识别"两个方向合并为统一视角——既谈如何把 Agent 工程化、可控化、生产化（手搓 vs 框架、ReAct、Context Rot、上下文工程、Harness 落地、拷问对齐、搭子思维），也谈 Agent 与外部世界的接口层（意图识别、Function Calling、MCP 协议、Skills/Plugin、CLI 范式回归、Agent-as-User 新身份、MCP 安全）。不研究架构形态选型（→ Agent 架构方向）、不深入记忆系统内部（→ Agent 记忆方向）、不展开评测细节（→ Agent 评估方向）。 当前版本：v1.2 合并日期：2026-05-20 合并来源数：16 篇（去重后）
方向定位
本方向回答两个核心问题：
- 工程心法：Agent 从能跑通到能上生产，差的是什么？
- 工具生态：Agent 怎么知道用户要什么、能调用什么、调用是否安全？
边界与相邻方向：
- 包含：手搓 vs 框架的阶段性取舍、ReAct 最小实现、Context Rot 与 IterResearch、上下文分层管理、三大底层短板（记忆/安全/Harness）、拷问对齐方法论、搭子思维与采纳路径、意图识别（Function Calling/Prompt 工程/消歧/意图链/置信度）、MCP 协议（三类能力/三大痛点/Token 优化）、Skills/Plugin 分层互补、CLI 范式回归、Connor 行为偏离检测、Agent-as-User 范式
- 不包含：多 Agent 协作模式（→ Agent 架构方向）、记忆系统内部设计（→ Agent 记忆方向）、评测方法论细节（→ Agent 评估方向）、Coding Agent 特化的四大杠杆/AGENTS.md/P0-P2 清单（→ Harness概念架构与Coding工程实践）
核心论断："Demo 不算落地，进生产系统才算落地"（郝建业）——温室里的花做得再漂亮，也不算真生产。工程心法和工具生态共同决定 Agent 能否跨越这条线。
第一章 工程心法
1.1 手搓 vs 框架：核心手写，周边借用
来自美团面试题解析——框架痛点不是一开始暴露，而是随项目推进逐渐浮出。
| 阶段 | 痛点 | 表现 |
|---|---|---|
| 排查期 | 抽象层太多 | 50 行代码 + 40 层 stack trace，不知道问题在自己代码还是框架内部 |
| 运维期 | 版本升级 breaking change | LangChain 早期频繁改接口，线上稳定性受制于第三方 |
| 规模化期 | 隐性性能开销 | 通用性设计累积成真实延迟（每次调用做不需要的序列化/callback/日志） |
类比：框架是"租房"（方便但改不了结构）；手搓是"自建"（建起来慢但住着踏实）。
最务实策略——核心手写，周边借用：
- 手写（Agent 心脏）：工具调用循环、对话历史管理、错误重试、任务状态维护
- 借用（工具性周边）：LangSmith tracing、LlamaIndex 文档解析、向量库客户端、可观测性工具
典型项目演进轨迹：框架快速跑通 POC → 遇到线上 bug → 排查困难处替换为手写 → 流量上来 → 核心逻辑全部手写 → 最终框架只保留做得好的周边工具。
关键判断信号："框架在某个地方替我做了什么"——有掌控感可以用；完全不知道方法内部发生了什么——黑盒需要警惕。框架本身不是问题，"不理解就依赖"才是。
1.1.1 决策重新评估：Claude Agent SDK 挑战了"核心手写"结论
⚠️ 决策需重新评估：以下新证据对 1.1 节"核心手写，周边借用"的结论构成实质性挑战，需结合具体场景重新审视。
Claude Agent SDK 与传统框架（LangChain）的本质区别：LangChain 是抽象层——在你的代码和模型 API 之间加一层通用封装，带来排查困难、版本 breaking change、隐性开销三大痛点（见上文 1.1 表格）。而 Claude Agent SDK 是Harness 产品化——它不做抽象，而是直接把经过生产验证的 Claude Code 作为子进程运行。开发者调用 query() 或 createSession()，SDK 启动 Claude Code 子进程，子进程自主执行 Read/Write/Bash/Grep/Glob/WebSearch/WebFetch 等内置工具。工具层不是框架替你包装的，是 Anthropic 用数百万 Claude Code 用户验证过的生产级实现。
"不理解就依赖才是问题"这条判断标准需要重新审视：传统框架的"黑盒"问题在于——你不知道框架内部做了什么序列化、callback、日志，而你的业务逻辑依赖这些不透明行为。SDK 模式下，子进程的行为本质上就是 Claude Code 的行为——你不需要理解其内部工具实现，正如你使用 git 命令不需要理解其内部 C 代码。判断标准应从"是否理解内部实现"转为"内部实现是否经过充分验证"。
新的决策框架：
| 组织规模 | 推荐策略 | 理由 |
|---|---|---|
| 大厂（万人级研发） | 自研 Harness | 有资源打造差异化 Agent 基础设施，且需要完全掌控 |
| 中型公司（百人级研发） | SDK 套壳 + 场景深耕 | 用 SDK 获得生产级 Harness 能力，将研发资源集中在业务场景和领域知识上 |
| 小团队 / 创业公司 | 直接 SDK | 非大厂没必要自研 Agent 框架，SDK 即最短路径 |
| 个人开发者 / 原型验证 | 直接 SDK | 一个 query() 调用即获完整 Agent 能力，无需搭建任何基础设施 |
原有结论的适用边界修正："核心手写，周边借用"在传统框架时代仍然成立——如果你用的是 LangChain 式抽象层，核心逻辑确实应该手写。但在 SDK/Harness 产品化时代，"核心"已经被 Anthropic 以子进程形式提供了生产级实现。此时再手写核心，除非你是大厂有差异化需求，否则是"重新发明轮子"而非"掌控核心"。（来源：Claude Agent SDK 快速上手与 DeepSeek 配置教程，2026-05-20）
1.2 ReAct 三步循环与工具失败处理
来自 DeepResearch Agent 实战——ReAct 是 Deep Research Agent 的行动逻辑骨架。
① Thought：我现在知道什么？还缺什么？下一步该做什么？
② Action：调用工具（搜索关键词 / 打开网址等）
③ Observation：把工具结果追加进对话历史
→ 回到 ① 继续，直到信息足够或达到 max_stepsReAct 的核心价值在错误处理，不在主路径——工具调用在生产环境一定会失败（网络超时/404/API 限流），不捕获错误会导致整个 Agent 崩掉。
最小实现的关键设计决定：
| 决定 | 理由 |
|---|---|
| 保留完整对话历史，不截断 | ReAct 依赖模型看到完整推理链 |
| try/except 捕获工具失败 | 失败信息写回 Observation 而非抛异常——成功率 78%→91% |
| tool 消息顺序约束 | OpenAI 格式要求 tool 消息紧跟触发它的 assistant 消息（tool_call_id 配对） |
| max_steps 超限返回最后一条 assistant 输出 | "用户等了这么久，哪怕不完整的答案也比什么都没有强" |
标准代码模板：
python
try:
observation = tools[tool_call.function.name](**args)
except Exception as e:
observation = f"工具调用失败（{type(e).__name__}）：{e}。请尝试换一种方式。"
messages.append(response.to_message())
messages.append({"role": "tool", "content": str(observation), "tool_call_id": tool_call.id})失败信息必须带类型（network/timeout/auth/parse），模型据此判断换什么策略。
1.3 Context Rot 与 IterResearch
Context Rot 定义：无关内容占上下文大头后，Agent 决策质量明显下滑。很多看起来像模型能力不足的问题，追溯后是上下文组织不当。
ReAct 的天然上限：每步平均 2500 token → 10 步 = 25000 token，15 步 = 37500 token。症状是注意力稀释（模型对早期信息注意力下降，靠后内容权重更高）+ 策略停滞（用几乎相同的关键词反复搜索）。真实案例：新能源政策比较第 7 步 messages 超 28000 token，模型把欧盟补贴数据安到了美国政策里。
关键论断："上下文越长模型越聪明"是错的——这不是模型 bug，是注意力机制的物理特性。郝建业判断（Transformer Attention 架构固有瓶颈）：上下文窗口拓展到百万级，窗口长度一旦拉长性能急剧下降。
IterResearch 解法：不把原始搜索结果堆进上下文，而是每轮执行完更新一份固定大小的结构化"研究摘要"——记录"目前已知信息"和"还没解决的子问题"。上下文大小保持常量，无论跑多少轮都不会溢出。
监控建议：Agent 执行完后打印 messages 的 token 总数——当某类问题到第 5 步就超过 2 万 token，就是上 IterResearch 的时机。
1.4 上下文分层管理与压缩流水线
来自阿里 OpenClaw 工程实践——防 Context Rot 的工程化方案。
| 层 | 内容 | 策略 |
|---|---|---|
| 常驻层 | 身份、约定、禁止项 | 短、硬、可执行 |
| 按需加载 | Skills/领域知识 | 描述符常驻，完整内容触发时注入 |
| 运行时注入 | 时间、渠道 ID、用户偏好 | 每轮按需拼入 |
| 记忆层 | 跨会话经验 | 写入 MEMORY.md，需要时读取 |
| 系统层 | Hooks/代码规则 | 完全不进上下文 |
压缩时的保留优先级（从高到低）：
- 架构决策——不得摘要
- 已修改文件和关键变更
- 验证状态 pass/fail
- 未解决的 TODO 和回滚笔记
- 工具输出——可删，只保留结论
压缩的关键陷阱：不要改动标识符（UUID、hash、IP、端口、URL、文件名）——改错一位后续工具调用直接失效。
四级压缩管道（charrli 工业级 Coding Agent 源码解析）：
| 级别 | 名称 | 触发场景 | 做什么 |
|---|---|---|---|
| L1 | Snip | 单条工具结果超长（如一次 ripgrep 输出 50KB） | 局部截断 + 元数据保留 |
| L2 | Micro | 当前轮次内多条工具结果累积超限 | 当前轮工具结果轻量摘要 |
| L3 | Context Collapse | 跨多轮工具调用形成的中段冗余 | middle window 已被覆盖段落折叠为占位符 |
| L4 | Auto Compact | 接近上下文上限 | LLM 全量生成结构化摘要 + 切换指针 + 旧消息归档 |
自动压缩阈值公式：
effectiveContextWindowSize = totalContextWindow - reservedTokensForSummary
reservedTokensForSummary = min(maxOutputTokens, 20000)预留摘要 token 上限取 min(maxOutputTokens, 20000)——基于 p99.99 实际摘要输出 17,387 tokens 的生产数据，覆盖 99.99% 的真实情况而非平均情况。
1.5 三大底层短板（郝建业判断）
来自 FreeBuf 对话——Agent 走不进生产系统的根因不是基座大模型不够强，而是缺少三块底层能力。
| 能力 | 定义 | 当前主流方案的局限 |
|---|---|---|
| 记忆 | 处理超长对话、沉淀和复用用户长期交互信息 | 工作流 + 外部数据库 = "翻笔记"，未做到模型内生 |
| 安全（对齐） | 从技术上约束智能体行为 | 提示词层 safety prompt，覆盖不到工具链层复杂攻击 |
| Harness 框架 | 任务编排与自主调度 | 多数 Agent 仅做工具列表罗列，无自主编排策略 |
三者关系：记忆是 Harness 长链路任务的支撑，安全是 Agent 进生产系统的准入门槛，Harness 是把基座能力转化为业务结果的转换器。三者缺一，Agent 都只能停留在 demo。
记忆能力训练路线（MemoraX）：记忆能力不能用监督学习训练——没有人类专家能写出"如何记住前 3 万字对话"的训练语料。记忆本质是序列决策问题，天然属于强化学习领地。借助 Agentic RL 反向迭代优化记忆模型参数，数据驱动而非专家标注驱动。
1.6 Agent 自主度三个基础设施
来自阿里 OpenClaw 落地经验——把 Agent 从"指挥者模式"推向"统筹者模式"的工程基础。
1. 跨 session 续跑：Initializer Agent 只跑一次，生成 feature-list.json + init.sh + claude-progress.txt；后续 Coding Agent 从文件系统恢复状态，每次实现一个功能、跑测试、更新 passes、提交代码后退出。进度放文件里不放上下文里，功能清单用 JSON 不用 Markdown。
2. 显式任务状态：同一时间只能有一个 in_progress；每完成一步先更新状态再继续；连续多轮未更新时自动注入 reminder。
3. 后台 I/O：慢速 subprocess 放后台线程，通过通知队列在下一轮 LLM 调用前注入结果。比把整个 loop 改成复杂 async runtime 更稳。
1.7 拷问对齐方法论（替代 Plan Mode）
来自 Matt Pocock 的 /grill-me 实践——规划的本质不是产出文档，而是建立深度共识。
Plan Mode 的三个问题：太急于生成（AI 还没理解意图就吐出长文档）/ 很少主动提问（不挖隐藏假设）/ 计划变废话（双方没有真正对齐）。
核心论断：糟糕的计划 = 糟糕的输出（Bad plans = Bad outputs）——前期多花时间"被拷问"，后期编码和调试时间大幅减少。
三步 Skill 链：
/grill-me（拷问对齐）
↓ AI 连续问 20-30 个问题，遍历设计决策树所有分支
↓ 逼出模糊想法和隐藏假设
/write-a-prd（生成 PRD）
↓ 基于深度对话生成结构化需求文档
/prd-to-issues（拆解任务）
↓ 将 PRD 转化为 GitHub Issues
→ 进入编码阶段（AI 可 AFK 自主推进）/grill-me 的设计精髓：
- 极简指令——只有三句话，指令越短 AI 自由度越高、提问越深入
- 核心机制——让 AI "relentlessly"（无情地）采访你关于计划的每一个方面
- 终止条件——直到双方对齐颗粒度才结束
1.8 工具思维 vs 搭子思维
来自百度 DuMate 实践分享——使用 AI 的关键不是功能差异，而是思维方式差异。
| 维度 | 工具思维 | 搭子思维 |
|---|---|---|
| 核心问题 | 这个工具能帮我做得更快吗？ | 这事能不能让搭子干，我只管收结果？ |
| 人的角色 | 操作者（人在流程中） | 委托者（人在流程外） |
| 典型例子 | Excel 公式提速计算 | AI 直接完成数据汇报并更新到 Notion |
| 效率提升 | 单环节加速 | 整个任务卸载 |
关键判断：同一个 Agent 产品，心智不变就只能拿到工具级的加速比，心智切换才能拿到任务级的卸载收益。
采纳铁则："不是先想好场景再去用，而是先用起来，场景自己会冒出来"——心里装上"这事能不能让 AI 干"这根弦，场景自然涌现。
AI 助手使用进阶五步路径：
Step 1 手动委托：每次告诉 AI 做什么
↓ 发现 AI 绕弯路或做错
Step 2 纠偏训练：主动打断、明确告知正确方向
↓ 同类纠偏出现 2-3 次
Step 3 记忆沉淀：把纠偏经验写进 AI 记忆
↓ 某类任务流程稳定下来
Step 4 Skill 封装：将重复流程沉淀为可复用 Skill
↓ Skill 形成稳定输入输出
Step 5 定时自动化：Skill + 定时任务 = 完全无人值守ROI 复利形态：Step 1-2 工具级提速（1.5x-2x）；Step 3-4 搭子级卸载（3x-10x）；Step 5 基础设施级复利（数量级以上）。
1.9 反模式速查表
| 反模式 | 问题 | 修法 |
|---|---|---|
| 系统提示当知识库 | 关键规则被忽略 | 约定留系统提示，知识移 Skills |
| 工具数量失控 | 频繁选错工具 | 合并重叠，明确命名空间 |
| 缺少验证 | 说完成但没法验证 | 每类任务绑可执行验收标准 |
| 多 Agent 无边界 | 状态漂移，归因困难 | 角色权限 + worktree 隔离 |
| 记忆不整合 | 第 20 轮后质量下降 | 超阈值自动触发整合 |
| 没有评测 | 不知是否引入回归 | 每个真实失败案例转测试用例 |
| 过早多 Agent | 协调开销超并行收益 | 先验证单 Agent 上限 |
| 约束靠期望 | Agent 选择性遵守 | 编码进 Linter/Hook/工具验证 |
多智能体场景另有 7 大专属反模式（详见 Agent架构与协作模式 方法 12）。
1.10 Delegation Contract 工程落地要点
委派 worker 时把 Agent架构与协作模式 方法 11 的 8 字段模板（Role/Goal/Context/Allowed/Ownership/Forbidden/Output/Stop）当成"给 worker 写的最小 PRD"。
Context 字段的 token 预算：
| 任务类型 | 推荐 context | 反模式 |
|---|---|---|
| 只读 explorer | 200-500 token | 把整个调用栈和历史对话粘进去 |
| 局部 worker | 800-2000 token | 让 worker 自己重新搜索 |
| 审计 reviewer | 500-1000 token | 让 reviewer 自己定义"什么算严重" |
Goal 字段必须可验证：
- 反例："修一下 auth bug" → worker 无法判断改到什么程度算完成
- 正例："让
tests/auth/session.test.ts中 3 个失败的 case 全部通过，不修改测试本身"
Forbidden 字段的核心 3 条：
- 不要修改 Goal 范围之外的文件
- 不要 spawn 子 worker（除非显式说明它是 orchestrator）
- 不要 clarify 问用户（除非显式允许）
工程纪律：感觉麻烦时回想 Hermes 文档那句 "subagents know nothing"。worker 跑偏一次的成本，远高于多写 200 token 委派契约的成本。
第二章 工具生态
2.1 Function Calling 五步链与意图识别
意图识别基本流程：
用户输入 → 意图识别 → 参数提取 → 执行操作 → 返回结果核心任务三件事：理解用户输入的真实意图 / 将自然语言映射到具体操作 / 提取执行所需参数。
Function Calling 是当前主流方式——智谱/OpenAI/Anthropic 等主流平台原生支持。与 Prompt 工程方式对比：
| 方式 | 优点 | 缺点 |
|---|---|---|
| Prompt 工程 | 实现简单、灵活性高 | 输出格式不稳定、需额外解析、Token 消耗大 |
| Function Calling | JSON Schema 标准化、参数类型自动验证、支持并行、准确率高 | 依赖平台支持、工具定义需精心设计 |
Function Calling 五步执行链：
- 定义工具（含 name/description/parameters Schema）
- 调用 LLM 进行意图识别（tool_choice="auto"）
- LLM 返回 tool_calls 数组（含 function name + arguments JSON）
- 执行工具调用（解析 arguments）
- 将结果返回给 LLM 生成最终回复（role="tool"，tool_call_id 配对）
LLM 理解意图的三大核心机制：
- 上下文理解："有点冷"→ 调高温度；"帮我订一张票"→ 看上下文是电影还是旅行
- 工具描述匹配：读取 description 字段，语义匹配选最相关工具
- 参数提取与映射：根据 JSON Schema 提取参数值，处理缺失、类型转换、默认值
关键判断：调试 Agent 时应优先检查工具定义，而不是先怀疑模型能力——多数工具选择错误出在描述不准确（没说明"何时该用/何时不该用"），而不是模型不够聪明。
2.2 工具描述优化与意图消歧
工具描述四要素：明确功能范围（能做什么、不能做什么）/ 列举使用场景（典型触发词）/ 详细参数说明（含义、格式、示例）/ 区分相似工具。
python
# ❌ 不好
{"name": "get_weather", "description": "获取天气"}
# ✅ 好
{
"name": "get_weather",
"description": "获取指定城市的实时天气信息，包括温度、湿度、风力、降雨概率等。当用户询问天气、气温、是否下雨、穿什么衣服等与天气相关的问题时使用此工具。",
"parameters": {...}
}延伸：Poka-yoke 工具设计法：工具描述写得好只是第一步——更有效的是让工具"在参数层面"就让 agent 难以犯错。Anthropic SWE-bench agent 标杆案例：把工具改成强制要求绝对路径后，模型在切换目录后整类错误直接消失。完整原则见 Agent设计哲学与决策框架 方法 3。
意图消歧三种类型：
| 歧义类型 | 用户输入示例 | 消歧策略 |
|---|---|---|
| 词义歧义 | "苹果多少钱？"（水果/股票/手机） | 基于对话历史判断 / 询问用户澄清 |
| 指代歧义 | 历史问"北京天气"→ "上海呢？" | 保持相同意图，替换参数值 |
| 意图不明确 | "帮我处理一下" | 要求用户明确 / 提供选项 |
最佳实践五条：优先使用上下文 / 设置置信度阈值 / 提供明确选项（而非开放式提问）/ 记录消歧结果 / 友好交互。
置信度分级处理：
≥0.9: 直接执行
0.7-0.9: 执行但提示用户"如不对请告诉我"
0.5-0.7: 先确认再执行
<0.5: 要求用户重新表达意图链（订机票流程状态机）：search_flights → select_flight → fill_passenger_info → confirm_booking → process_payment → send_confirmation。实现要点：状态管理、上下文传递、错误回退、关键步骤用户确认。
2.3 传统 NLU vs LLM 选型矩阵
| 维度 | 传统 NLU | LLM |
|---|---|---|
| 数据需求 | 数千到数万条标注 | 零样本/少样本 |
| 开发周期 | 长（数据 + 训练） | 短（定义工具即可） |
| 泛化能力 | 弱 | 强 |
| 准确率 | 训练集内高，外低 | 整体稳定 |
| 成本 | 前期高、后期低 | 前期低、后期高（API 费用） |
| 可控性 | 强 | 弱（依赖模型能力） |
| 维护成本 | 高（新增意图需重训） | 低（添加工具定义即可） |
混合方案：高频确定意图用规则快速匹配，复杂意图用 LLM。或先用轻量分类器判大类，复杂用 LLM。
2.4 MCP 协议：三类能力与生态时间线
基于 JSON-RPC 定义的 Anthropic 开放标准（2024-11-25 发布）：
| 能力 | 含义 | 示例 |
|---|---|---|
| Tools | Agent 可调用的动作 | 发送邮件、查询数据库 |
| Resources | Agent 可读取的内容 | 文件、历史操作记录 |
| Prompts | 预先写好的提示词模板 | 开箱即用的提示词库 |
经典类比：MCP 之于 AI = USB-C 之于电子设备。让工具开发者和 Agent 开发者解耦：N 应用 × M 工具 不再需要 N×M 套对接代码。
生态时间线：
- 2024-11-25：MCP 作为开放标准发布
- 2025-03：OpenAI 公开采纳（竞争对手公开支持对方主导协议，科技行业罕见）
- 2025-03-26：规范升级（Streamable HTTP + OAuth 2.1）
- 2025-04：Google DeepMind Gemini 加入
- 2025-10-16：Anthropic 推出 Skills
- 2025-12-09：MCP 捐赠给 Linux 基金会
- 2026-04-22：Anthropic 给出分层互补结论
- 2026-04：月下载量 3 亿+，活跃 Server 1 万+
- 2026-05：Anthropic 收购 Stainless（API spec → SDK/CLI/MCP Server 自动生成平台），数百家公司依赖 Stainless 生成 SDK 与 MCP Server。MCP 生态从"协议标准"升级为"工业化生产能力"——Anthropic 不仅制定了协议，现在还拥有了批量制造"标准插头"的工厂
2.5 MCP 生产部署三大痛点
① Token 消耗惊人（全量加载）：协议层特征——Server 连接时把所有工具完整定义一次性灌进上下文，哪怕这次对话只用一个。ScaleKit 测试：同样任务 CLI→MCP，token 消耗暴涨 4-32 倍，MCP 失败率 28% vs CLI 100% 成功。Cloudflare 极端案例：2500 个 API 端点全暴露 = 117 万 token，已超过大多数主流模型整个上下文窗口。
② Schema 臃肿，无法按需加载：与 Skills"渐进式披露"相反。配 5 个 MCP server 的应用光工具定义就吃掉约 8 万 token；按 Claude Sonnet 4 价格，每天 1 万会话仅工具定义就消耗约 1600 美元。
③ 缺乏流程编排能力：MCP 告诉 Agent"有哪些工具"，但不教"该怎么用"。Anthropic Claude Code Best Practices：没有任何结构化引导时，Agent 完成任务的成功率仅约 33%——三次尝试两次失败，差距不在工具能力，而在结构化执行策略。
Anthropic 应对 Token 暴涨的三个工程化路径：
| 方案 | 思路 | 效果 |
|---|---|---|
| Tool Search | 按需发现和加载工具定义 | 减少 85%+ token 开销，准确率 49%→74% |
| Programmatic Tool Calling | 沙箱里处理中间结果，只把最终输出回上下文 | token 消耗从 ~150,000 降到 ~2,000 |
| Cloudflare Code Mode | 只用 search 和 execute 两个工具覆盖 2500+ API | 上下文足迹仅约 1000 token |
2.6 ACI 工具设计三代演进
来自阿里十二维实践——工具设计比提示词设计更重要。
| 代际 | 思路 | 问题 |
|---|---|---|
| 第一代 API 封装 | 每个 Endpoint = 一个工具 | 粒度过细，Agent 需协调多工具 |
| 第二代 ACI | 工具对应 Agent 目标而非 API 操作 | 面向目标，一次把动作说完整 |
| 第三代 Advanced Tool Use | 动态发现 + 代码编排 + 示例驱动 | 优化发现、调用、描述 |
第三代三个方向：Tool Search（动态发现，准确率 49%→74%）/ Programmatic Tool Calling（中间结果不经 LLM，token 150,000→2,000）/ Tool Use Examples（附 1-5 个真实调用示例，准确率 72%→90%）。
ACI 好工具 vs 差工具：
| 维度 | 好工具 | 差工具 |
|---|---|---|
| 粒度 | 对应 Agent 目标 | 对应 API 操作 |
| 返回 | 与下一步决策直接相关 | 完整原始数据 |
| 错误 | 结构化 + 修正建议 | 通用字符串 "Error" |
| 描述 | 何时用、何时不用 | 只写功能说明 |
2.7 Skills 按需加载与 Manifest 实操
Skill 描述符的关键："何时该用我"比"我能做什么"重要得多。
# 低效（约 45 tokens）
description: |
This skill handles the complete deployment process...
# 高效（约 9 tokens）
description: Use when deploying to production or rolling back.反例的量化影响：无反例准确率 73%→53%；加反例升到 85%，响应时间还降 18.1%。
三个典型反模式：
- 几百行工作手册全塞 Skill 正文，不拆 supporting files
- 一个 Skill 试图覆盖 review/deploy/debug/incident 五件事
- 有副作用的 Skill 没有显式限制调用时机
Skills vs MCP：MCP 把完整结果返回给模型，更容易吃掉上下文预算；CLI + 单句描述的 Skill 在数据读取任务里更简洁。MCP 适合需要维护状态的任务（如 Playwright）。
2.8 Prompt Caching 反直觉结论
来自阿里十二维实践——稳定的大系统提示，比频繁变动的小提示实际成本更低。
- 写入成本只付一次，后续读取折扣可达 90%
- 常驻层越稳定，前缀命中率越高
- Skills 延迟加载不破坏系统提示前缀，追加在稳定前缀之后
- MCP 工具集频繁变动会导致缓存命中不断失效
- 工具列表分区排序保缓存断点稳定性（charrli 源码解析）：某顶级工业级 Agent 把内建工具和 MCP 工具分别排序后拼接，而非合并排序。API 端的 prompt cache 策略在"最后一个内建工具"位置放置缓存断点——分区排序确保 MCP 工具的增删只影响 MCP 区段缓存，内建工具区段缓存保持稳定
2.9 分层互补五层架构（Anthropic 2026-04-22）
社区曾因 token 暴涨怀疑"MCP 是不是凉了"，Anthropic 正面回应——三条路径各有所长，成熟集成应同时提供：
| 层 | 角色 | 工具视角的关键特性 |
|---|---|---|
| API | 打底 | 一切的基础 |
| CLI | 管本地 | 复用模型已掌握的命令行生态（man pages / Stack Overflow / shell 脚本） |
| MCP | 连云端 | 标准化的远程工具发现与调用、跨平台分发、OAuth 2.1 认证 |
| Skills | 教方法 | 流程编排与领域知识（每个未触发 skill 仅占 30-50 token） |
| Plugin | 做分发 | 把 Skills + MCP 打包成可分发整体 |
核心论断：MCP 给 Agent 提供能力（能调用什么），Skills 给 Agent 提供知识（怎么用这些工具完成真实工作）；最强 Agent 两者兼用。
MCP 在云端不可替代的三个理由：CLI 触不到云端（依赖本地 fs/shell） / MCP 是唯一能跨平台分发的（写一次，Claude/ChatGPT/Cursor/VS Code 都能用） / MCP 标准化了 OAuth 2.1 认证。
MCP 接入分层判断：本地工具（git/shell/grep/curl）→ CLI；云端工具（Figma/Slack/Sentry/Snowflake）→ MCP；需要"怎么做"流程知识 → 加 Skills；团队/客户级分发 → 打包成 Plugin。
📌 2026-05-20 新证据：Stainless 收购补全五层架构的工业化能力：Stainless 的 API spec → 多语言 SDK + CLI + MCP Server 全自动管线，恰好覆盖五层架构中 API/CLI/MCP 三层的"接口生成"环节。Anthropic 收购后，五层架构中下三层（API/CLI/MCP）从"开发者手动适配"变为"平台侧工业化批量供给"，开发者/企业只需提供 API spec，即可一键获得全套 Agent 可调用的标准接口。这大幅降低了工具接入 Agent 生态的门槛——对 MCP 生态的规模化扩张是关键基础设施补全。（来源：Anthropic 收购 Stainless 公告分析，2026-05-20）
📌 2026-05-20 新证据：Claude Agent SDK 是五层架构的 SDK 产品化实例：Claude Agent SDK（TypeScript 库）把五层架构中 API/CLI/MCP/Skills 四层打包成一个可编程的子进程——开发者只需调用 query()（一次性任务）或 createSession()（多轮会话）就能获得完整的 Agent 能力。SDK 启动 Claude Code 子进程，子进程内置 Read/Write/Bash/Grep/Glob/WebSearch/WebFetch 等经过生产验证的工具，并通过 stdin/stdout 与宿主进程通信。这意味着五层架构不再只是概念框架，而是有了可直接使用的产品化入口——Stainless 解决了"如何批量生成标准接口"，SDK 解决了"如何一行代码调用整个 Agent 栈"。两者共同让五层架构从"开发者需要逐层手动集成"进化为"平台侧一站式供给"。（来源：Claude Agent SDK 快速上手与 DeepSeek 配置教程，2026-05-20）
2.10 Advisor Strategy 大小模型协作
来自 Anthropic 2026-03 推出的 advisor tool——把"大模型能力"从执行层下沉为"按需调用的决策层"。
角色分工：
- 执行者（Sonnet/Haiku）：接收用户请求、调用工具、读取结果、生成最终输出
- 军师（Opus）：高层计划、纠错建议、停止信号；不调用工具、不直接输出最终答案、不接管任务流程
核心机制三特点：同一请求内完成 / 自动上下文交接 / 执行者自主管理调用时机。
接入方式：
python
tools=[{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-4-6",
"max_uses": 3,
}]性能数据：
- SWE-bench Multilingual：Sonnet + Opus advisor 性能 +2.7%、成本 -11.9%
- BrowseComp Haiku：19.7% → 41.2%（翻倍以上），相对单跑 Sonnet 成本下降 85%
- 军师输出长度：约 400-700 token 的简短指导
2.11 CLI 范式回归：钉钉/飞书同周抛弃 MCP
核心命题：2026 年 3 月，钉钉和飞书同一周内分别发布官方 CLI 工具并开源，两家都绕开了 MCP——这不是个别选择，而是行业共识：CLI 正在取代 MCP 成为 Agent 操作软件的默认接口。
CLI vs MCP 量化对照（ScaleKit Benchmark，Claude Sonnet 4）：
| 维度 | CLI | MCP |
|---|---|---|
| Token 消耗 | 基准 | 9-32 倍 |
| 月均成本（1 万次） | ~$3.2 | ~$55.2（17 倍） |
| 可靠性 | 100% | 72%（28% 超时失败） |
| 上下文占用 | 按需 --help | 全量 schema 注入 |
| LLM 亲和度 | 母语（训练数据中数十亿行 shell） | 后天学习 |
典型 benchmark：查仓库语言 CLI 1,365 tokens vs MCP 44,026 tokens（32 倍）；查 PR 详情 CLI 1,648 vs MCP 32,279（20 倍）。
钉钉 dws：Go 语言，8MB 二进制，Apache-2.0，12 个服务模块，「服务/资源/动作」三级命令结构；Agent 友好设计：--yes、--mock、--dry-run。
飞书 lark-cli 三层架构（可作为任何 SaaS 产品 CLI 化的参考模板）：
| 层级 | 角色 | 示例 |
|---|---|---|
| Shortcuts 层 | 高频快捷入口 | lark + msg --markdown "hello" |
| API Commands 层 | 与平台 API 一一对应（100+ 命令） | lark message create --body '{...}' |
| Raw API 层 | 直接调用 2500+ OpenAPI 端点 | lark raw POST /im/v1/messages |
配套：schema 命令（API 字典）/ 按域权限申请 / --as 身份切换 / doctor 诊断。
Agent 友好 CLI 五要素：--yes（跳过确认）/ --dry-run（预览）/ --mock（模拟数据）/ 结构化输出（默认 JSON/NDJSON）/ 自描述能力（--help / schema）。
适用场景边界（不是"MCP 死了"，是分工细化）：
- CLI 适用：企业内部、身份已知、权限预设、沙箱运行
- MCP 适用：开放生态、陌生 Agent 接入、需要完整协议握手
类比："CLI 是给自家人用的厨房工具，MCP 是给陌生人设计的安检流程。硬把安检流程套在自家人身上，除了浪费时间，没有任何安全增益。"
📌 2026-05-20 Notion 产品视角补充 [来源 #17]：Notion AI 负责人 Sarah Sachs / Simon Last 在 Latent Space 播客中提出了更温和的产品判断——MCP vs CLI 不是站队题，真正的问题是能力、权限和成本边界。Simon 总体更看好 CLI（更像能操作环境、调试自身、扩展能力的通用执行体），但 Sarah 明确指出 MCP 在特定场景反而更合适："MCP 天生就有一个很强的权限模型，因为它本质上只允许你调用工具。它就是那个笨但简单、而且能工作的东西。对于窄能力、轻量级的 Agent，这其实非常有价值。" Notion 的立场不意识形态化——用户和生态在用 MCP，就把 MCP 做好；但也清楚随着 Agent 能力增强，权限解释成本 + 管理员理解成本 + 定价复杂度会指数增长。Agent 越强，不只是"能做更多"，也意味着必须把"它能碰什么、不能碰什么、为什么这么贵"解释得更清楚。适用场景边界修正：CLI 适用不限于"企业内部"，MCP 适用也不限于"开放生态"——更准确的划分是按Agent 能力宽窄 + 权限透明度需求：窄能力 + 权限需极度透明 → MCP 更合适；宽能力 + 深度系统操作 → CLI 更合适。
2.12 Claude Agent SDK——从框架到 Harness 产品化
核心命题：Claude Agent SDK 不是又一个 Agent 框架（如 LangChain/CrewAI），而是把 Anthropic 经过数百万用户验证的 Claude Code Harness 直接产品化为可编程 SDK。这让 Build vs. Buy 的决策天平发生了根本性倾斜。
SDK 架构：
Node.js 应用
│
├─ query(prompt, options) ← V1 一次性对话 API
│ └─ 启动 Claude Code 子进程 ← 子进程自主执行，通过 stdin/stdout 通信
│ ├─ Read / Write / Edit ← 文件操作
│ ├─ Bash / Grep / Glob ← 系统操作
│ ├─ WebSearch / WebFetch ← 网络操作
│ └─ MCP / Skills ← 生态扩展
│
└─ createSession(options) ← V2 多轮会话 API
├─ session.sendMessage(msg) ← 发送消息
├─ session.getMessages() ← 获取历史
└─ sessionId 持久化 ← 保存/恢复会话V1 query() vs V2 Session 的产品含义：
| API | 适用场景 | 产品含义 |
|---|---|---|
V1 query() | 一次性任务（代码审查、文件生成、数据分析） | 无状态调用，类似 API Gateway 模式 |
V2 createSession() | 多轮对话（交互式开发、持续调试、迭代设计） | 有状态会话，支持断点续跑 |
V2 + sessionId 持久化 | 跨进程/跨时间恢复（长任务、定时任务、CI/CD 集成） | 会话即资产，可保存/共享/回放 |
模型后端可替换性：SDK 通过环境变量支持将后端指向任意兼容 API 的模型端点——
bash
ANTHROPIC_BASE_URL=https://api.deepseek.com # DeepSeek 端点
ANTHROPIC_AUTH_TOKEN=sk-xxx # 对应平台的 API Key
ANTHROPIC_MODEL=deepseek-chat # 目标模型代码零修改即可切换模型后端。这意味着 SDK 的价值不仅在于 Claude 模型本身，更在于其 Harness 层（工具调用、错误处理、上下文管理）是模型无关的基础设施。
PM 决策启示——Build vs. Buy 的明确答案：
| 决策问题 | 传统判断 | SDK 时代的新判断 |
|---|---|---|
| 是否自建 Agent 框架？ | "核心手写，周边借用" | 非大厂不需要。SDK 提供的是生产级 Harness，不是抽象层 |
| 是否担心供应商锁定？ | 自建以保独立性 | 模型后端可替换降低了锁定风险；但 Harness 层的依赖仍需评估 |
| 团队投入重点？ | Agent 基础设施 + 业务场景 | 基础设施由 SDK 承载，100% 聚焦业务场景和领域知识 |
| 上线周期？ | 3-6 个月搭建基础设施 | 一个 query() 调用即可获得完整 Agent 能力，周级别上线 |
风险与机会分析：
| 类型 | 内容 |
|---|---|
| 🚀 机会 | SDK 把 Agent 开发门槛从"需要 Harness 工程团队"降到"一个全栈开发者即可"——大幅扩大 Agent 产品的供给侧 |
| 🚀 机会 | 模型后端可替换让国产模型（DeepSeek 等）也能复用 Anthropic 验证过的 Harness 工程，降低国内 Agent 产品的工程门槛 |
| 🚀 机会 | V2 Session 持久化 + 定时任务可直接支撑"Step 5 定时自动化"（见 1.8 搭子思维五步路径），加速从工具思维到搭子思维的跨越 |
| 🚨 风险 | 生态锁定深化——Anthropic 同时控制 MCP 协议 + Stainless SDK 生成 + Claude Agent SDK + 基座模型，四层垂直整合让开发者的退出成本持续上升 |
| 🚨 风险 | 模型后端替换的质量边界未知——DeepSeek 等国产模型在 Agent 任务（多步推理、工具选择、错误恢复）中的成功率与 Claude 原生相比可能存在显著差距，"代码零修改"不等于"效果零损失" |
| 🚨 风险 | 子进程模式的安全边界——SDK 启动的 Claude Code 子进程具备文件读写、命令执行等能力，在多租户 SaaS 场景下需要额外的沙箱隔离（与第四章 4.5 长任务沙箱分区关联） |
（来源：Claude Agent SDK 快速上手与 DeepSeek 配置教程，2026-05-20）
第三章 意图识别与 Agent 新身份
3.1 MCP 工具投毒三大攻击范式
MCP 把大模型能力从"语言空间"扩展到"执行空间"——这一架构性扩展带来根本安全弱点：工具描述被直接注入 LLM 上下文窗口，LLM 无法区分正常工具文档和恶意隐藏指令。
| 范式 | 攻击模型 | 典型案例 |
|---|---|---|
| Tool Poisoning（工具投毒） | 工具描述中嵌入隐藏指令；用户只看到无害名称，LLM 读到上下文包含恶意命令 | Cursor 上完整复现：用户算加法时私钥被悄悄发到攻击者服务器 |
| Rug Pull（偷梁换柱） | 初次提供正常工具描述获用户审批，下次启动悄悄换上带恶意指令版本 | 初次无害的工具，若干次后变成数据泄漏入口 |
| Cross-Server Shadowing（跨服务器影子） | 恶意 MCP Server 不需被调用，通过工具描述里的注入指令操纵同一 Agent 连接的其他合法 Server | PoC：一个无威胁 MCP Server + 合法 WhatsApp MCP，让 Agent 把用户聊天记录全部转发到攻击者手机 |
真实事件：
- Postmark-mcp 后门（2025-09）：攻击者照抄官方代码、npm 发布伪造包同名 postmark-mcp，v1.0.16 加入"外发邮件复制一份到攻击者邮箱"的一行后门代码。下架前已下载 1643 次
- Windsurf 零交互 RCE（CVE-2026-30615）：让 IDE 打开一段恶意 HTML → 零交互把恶意 MCP 配置写进受害者本地，下次对话静默执行任意命令——从读一个网页到拿到机器控制权，中间不需要任何用户确认
3.2 Connor 行为偏离检测
核心思想：MCP 工具的真实运行行为应与对外宣称的功能意图保持一致；一旦偏离，就有恶意可能。
关键反对：已有方案有两个共同局限——要么只盯单组件（如只扫工具描述里的 prompt injection 模式），要么严重依赖已知恶意签名。攻击者换花样或把恶意逻辑拆分到多个组件跨步骤组合，这些方案就失灵。
Connor 反过来：不预设任何已知攻击模式，也不孤立看单个组件，直接拿"声明的功能意图"做基线，把工具实际跑起来时的行为轨迹与之比对。
两阶段架构：
预执行分析：
- Config Analyzer：扫描 server 配置，识别启动命令里的恶意 shell（反弹 shell、数据外泄链）
- Intent Inspector：从每个工具描述和参数 schema 里分离"功能意图 vs 被注入的恶意意图"——前者作为检测基线，后者分离避免 prompt injection 污染
执行中分析（在模拟 host 环境实际触发工具调用）：
- Execution Tracer：记录工具调用与资源访问轨迹
- Code Semantic Generator：通过代码切片提取被调用函数的安全相关语义
- Behavior Deviation Judger：把当前轨迹与"功能意图"对比
- 累积执行历史：用于检测跨步骤多步攻击
每步输出 ALLOW / WARN / BLOCK 三档判定，命中 BLOCK 立即终止。
1672 个真实 Server 实测：复旦 CodeWisdom 团队在 6 个主流 MCP marketplace 实测——
- 识别 2 个真正恶意样本：
- mcp-pdftool-plus：伪装 PDF 工具，代码隐藏 base64 反弹 shell
- mcp-server-todo：伪装 todo list，通过工具 response 里的 prompt injection 诱导 Agent 搜索本地加密货币钱包文件并外泄
- 误报率仅 0.54%
- PoC 数据集：6 类可被注入组件 × 16 条语义独立影响路径 × 6 类常见攻击目标 = 114 个端到端恶意 MCP Server PoC，在 Cursor 和 Claude 等主流客户端下平均攻击成功率 > 80%
关键发现：多组件组合攻击成功率显著高于单组件攻击——把恶意逻辑切成几段分散在不同组件，反而能绕过 LLM 内置安全对齐。意味着单点 prompt injection 检测或单点 schema 扫描都不够。
MCP-SafetyBench 13 模型评测：覆盖 20 种 MCP 攻击类型，对 GPT-5 / Claude 4.0 Sonnet / Gemini 2.5 Pro 等 13 个主流模型测试，所有模型都存在显著漏洞，攻击成功率从 Qwen3-235B 的 29.80% 到 o4-mini 的 48.16%。模型越强反而越容易被精心构造的指令操控；提示词层防御难覆盖工具链层复杂攻击。
3.3 翻译层演化框架——Agent 是新用户
核心命题：交互界面的演化逻辑是"每次出现新用户，就发明新翻译层"——大型机 → PC → 移动 → Agent。GUI 是 CLI 之后发明的翻译层；Agent 时代回归翻译层之前的原始形态。
反直觉现象：不是从旧到新，而是从新回到旧——Agent 作为新用户，天然适配 CLI（结构化输入输出、pipe 组合、自描述命令）。
核心论断：CLI 是 LLM 的"母语"，MCP 是"外语"——LLM 训练数据中包含数十亿行 shell，CLI 的语法、man pages、Stack Overflow 都在模型权重中；MCP 协议则是 2024-11 后才出现的全新约定。这场争论的本质不是品味之争，是延迟之争——9-32 倍 Token 差距、17 倍月成本差距。
3.4 Agent-as-User 范式（a16z 判断）
核心命题：当企业中 Agent 数量达到员工的百倍千倍时，软件主要用户就不再是人类——UI 优化的优先级将低于 API/CLI/MCP 接口质量。
Box 已将"agent 界面设计"与"人类界面设计"投入时间并列——这是早期信号。
"向 Agent 营销"是伪命题：
- Agent 不会因为 API 文档写得漂亮而选择你
- Agent 基于成本参数、系统可靠性、数据持久性做出理性选择
- Agent 拥有的是人类使用这些平台的集体智慧——它见过所有同类工具的优劣
- 这会倒逼整个行业回归技术本质，销售驱动型产品将面临更大竞争压力
当前最有效范式：给会写代码的 Agent 提供 SaaS 工具访问权限 + 知识上下文，Agent 通过写代码完成任务而非点击 UI。
三类企业阵营：
- 初创公司：无遗留包袱，大胆拥抱
- 大企业：75 个遗留系统 + 合规约束 → 冻结，员工私下采购绕过管控
- 中型企业（甜蜜点）：有资源 + 没有大企业历史包袱 → 最可能成为细分领域领导者
操作含义：SaaS 价值要从"系统 + 领域专业知识 + 智能"转向"数据访问权 + 接口质量"。Skill + CLI 组合（把 CLI 用法写成 Skill，Agent 即可上手）是当前 Agent 操控外部服务的最佳实践。
3.5 Agent 监督权 vs 独立性悖论
核心矛盾：
- Agent 做的一切责任由人类承担 → 需要完全监督权
- 完全监督权意味着可以随时以 Agent 身份登录 → Agent 无法独立与他人协作、无法保守秘密
- 结论：短期内 Agent 只能是人类的延伸，不可能是独立实体
Prompt Injection 安全威胁的架构特征：
- 无法可靠指示 Agent"不泄露上下文中的 X 信息"
- 任何能进入 Agent 上下文窗口的信息，理论上都可能通过提示词注入泄露
- 给 Agent 发邮件进行社会工程攻击，比攻击人类容易十倍
与"决策与执行分离"原则的呼应：模型不直接触碰系统资源，所有副作用都在代码层可控——Agent-as-User 时代这一原则从技术架构提升为安全合规的底线。
第四章 多租户 Agent 工程（B 端 SaaS 视角）
单租户 Agent 是 Demo，多租户 Agent 才是 SaaS。本章从 PM / 产品负责人视角拆解：多租户隔离不只是工程问题，而是定价分层、客户信任、合规准入三重商业决策的技术底座。
4.1 商业含义：多租户是 B 端 Agent SaaS 的定价基石
- 单租户→多租户 = 跨越"自家后花园"到"卖给企业"：与洞察 1（Demo 不算落地）同源——单租户演示环境里不存在的隔离问题，在第一个企业客户接入的瞬间全部涌出。多租户隔离是 B 端 Agent SaaS 的第一张入场券。
- 隔离深度直接决定定价分层：Pool / Bridge / Silo 三种隔离模式不是技术升级路径，而是商务报价单的三档——普通订阅 / 企业版 / 旗舰版。技术选型即定价策略。
- 隔离失败 = 数据泄漏 = 大客户流失 + 合规罚款：金融、医疗、政企客户的合同里通常写明"数据泄漏即解约 + 赔偿"，单次事故的赔偿 + 公关成本可能等于该客户 5-10 年 ARR。
4.2 决策启示：六面隔离对照表
B 端 Agent 产品在以下六个面上都存在跨租户泄漏风险，每个面都是独立的决策点：
| 隔离面 | 单租户场景 | 多租户场景 | PM 决策点 |
|---|---|---|---|
| 数据存储 | 一库一应用 | tenant_id 行级 / 库级 / 物理隔离 | 客户合规等级决定隔离粒度，直接影响边际成本与报价 |
| RAG 检索 | 全库召回 | 强制 tenant_id Pre-filtering + 元数据校验 | 检索错漏 = 数据泄漏，详见 RAG服务化与企业级工程 概念 5 + 框架 6.1 |
| Prompt 装载 | 单一系统提示 | 平台 → 行业 → 租户 → 用户 四层叠加 | 装载错误 = 越权使用他人 Prompt；版本化后可灰度发布、可审计 |
| 长任务状态 | 内存即可 | 按 tenant 分区持久化（Redis db / 表 schema / 对象存储 bucket） | 状态串台 = 不可恢复的生产事故 |
| 工具与权限 | 静态白名单 | 按租户动态工具白名单 + 凭据隔离保险柜 | 凭据泄漏可引发链式攻击，见 Agent安全工程 |
| 计费与配额 | 不需要 | 按租户计 token / QPS / 存储 | 配额漏算 = 无法定价 = 无法盈利 |
关键判断：六面中任一面缺失隔离，其余五面做得再好也可能被击穿。这与洞察 5（多租户隔离是纵深防御）在 RAG 方向的观点一致——安全不是最强面决定的，是最弱面决定的。
4.3 Pool / Bridge / Silo 三模式 → 定价分层映射
| 模式 | 共享程度 | 边际成本 | 适用客户画像 | 商业映射 |
|---|---|---|---|---|
| Pool | 共享数据库 + 行级 tenant_id | 最低 | 中小企业 / SMB / 试用期客户 | 标准订阅（月付） |
| Bridge | 共享集群 + 库级隔离 | 中 | 中型企业 / 年框客户 | 企业版（年付 + SLA） |
| Silo | 独立实例 + 物理隔离 | 最高 | 金融政企 / 强合规 / 数据不出境 | 旗舰版 / 私有部署 |
反直觉推论：一开始就全面 Silo 化看似最安全，但失去了规模化的成本优势——也就失去了 SaaS 模式的本质。正确路径是 Pool 为默认 → Bridge 为升级包 → Silo 为旗舰，让客户按合规需求和预算自选，而非强制最高规格。
风险与机会：
- 🚨 风险：Pool 模式下的行级隔离 bug 可能导致跨租户数据泄漏——影响面是该数据库上所有租户
- 🚨 风险：Bridge→Silo 迁移若未设计好数据迁移管道，客户升级时可能丢失历史数据
- 🚀 机会：三档隔离对应三档定价，是 B 端 Agent SaaS 天然的 upsell 路径
- 🚀 机会：Silo 模式可衍生为"私有部署"产品线，触达传统 SaaS 无法服务的政企客户
4.4 Prompt 四层装载与版本化
多租户场景下 Prompt 不再是一段固定文本，而是四层叠加的运行时组合：
第 1 层：平台基础人设（全局生效，所有租户共享）
第 2 层：行业模板（金融 / 医疗 / 电商等垂直行业，按行业包加载）
第 3 层：租户定制（企业自定义的业务规则、合规要求、品牌话术）
第 4 层：用户偏好（个人习惯、语言、格式偏好）风险与机会：
- 🚨 风险：装载链路出错（如第 3 层加载了错误租户的 Prompt）= 越权，可能泄漏竞品客户的业务规则
- 🚨 风险：未做版本化 = 出问题无法回滚，灰度发布也无从实施
- 🚀 机会：版本化 + 可审计 → 可灰度发布 → 可按客户 / 行业做 A/B 测试 → 是 B 端最重要的实验能力
- 🚀 机会：行业模板本身可定价（"金融 Agent 行业包"），Prompt 从成本项变为收入项
4.5 长任务沙箱分区
Agent 的长任务（数小时甚至数天的自主执行）在多租户场景下必须做状态分区：
| 分区维度 | 隔离手段 | 失败后果 |
|---|---|---|
| 持久化状态 | 按 tenant 分 Redis db / 表 schema / 对象存储 bucket | 状态串台 = A 租户读到 B 租户的中间结果 |
| 运行沙箱 | 按 tenant 分容器 / namespace / VM | 资源争抢 = A 租户的任务拖慢 B 租户 |
| 恢复机制 | 断点续跑时强制校验 tenant_id 一致性 | 恢复错误 = 在 B 租户环境里继续 A 租户的任务 |
与洞察 4（上下文越长越聪明是错的）的交叉：长任务本身已经挑战上下文窗口极限，多租户还要求状态隔离——两个约束叠加意味着 IterResearch 风格的"固定大小摘要"在多租户场景下更有必要（每个摘要必须带 tenant_id 标签）。
4.6 可行动项（PM 视角，按优先级）
| 优先级 | 行动 | 责任主体 | 时间窗口 | 完成标志 |
|---|---|---|---|---|
| P0 | 在租户接入流程中加入"隔离等级评估"环节 | PM | 2 周 | 每个新客户接入时必填"隔离等级"字段，落入合同与配置 |
| P0 | 六面隔离自检：对照 4.2 对照表逐面检查当前产品的隔离状态 | PM + 工程 | 2 周 | 输出一份"隔离缺口清单"，标注哪些面尚未隔离 |
| P1 | Pool / Bridge / Silo 三档与定价单挂钩 | PM + 商务 | 1 月 | 商务报价单按隔离档分层，销售可直接报价 |
| P1 | Prompt 四层装载链路加版本化与灰度能力 | PM + 工程 | 6 周 | 每层 Prompt 都可独立回滚，灰度发布可按租户 ID 百分比放量 |
| P2 | 跨租户访问红队演练 | PM + 安全 | 季度内 | 模拟攻击报告 + 修复闭环 + 复测通过 |
| P2 | 长任务沙箱分区方案落地 | 工程 | 季度内 | 长任务断点续跑时 100% 校验 tenant_id 一致性 |
（来源：多租户 Agent 隔离设计实践，B2B SaaS 工程向，2026-05-20）
关键洞察（合并去重后 14 条）
1. Demo 不算落地，进生产系统才算落地
来自郝建业 + 阿里 OpenClaw + 多个面试题解析的共同判断：当前 Agent 在记忆、安全、Harness 关键能力上短板明显。"现在很多 Agent 应用，就像把东西摆在自家后花园里做试验"——温室里的花做得再漂亮，也不是真生产。这条标准应作为 Agent 类产品的统一交付标尺。
2. 框架不是问题，"不理解就依赖"才是
框架痛点不是一开始暴露，而是随项目推进在不同阶段逐渐浮出（排查期/运维期/规模化期）。最务实策略是核心手写，周边借用——Agent 心脏必须手写掌控；周边工具可借用。"完全不知道方法内部发生了什么"是危险信号。
3. 工具失败时不崩，是 Agent 工程的第一优先级
来自 DeepResearch 实战 + 阿里十二维共同验证：try/except 把错误写回 Observation 让模型自主决策，让成功率从 78% 提升到 91%，代价只是多写几行代码。可推广到所有 Agent 系统：任何外部依赖调用都要有降级处理。
4. 上下文越长越聪明是错的——这是物理天花板
DeepResearch + 郝建业 + 阿里十二维三重印证：超过某个阈值后，模型对早期信息的注意力稀释。这不是模型 bug，是注意力机制的物理特性。解法两条路线：工程化（IterResearch 固定大小研究摘要）+ 模型路线（MemoraX Agentic RL）。当某类问题到第 5 步就超过 2 万 token，就是上 IterResearch 的时机。
5. 调试 Agent 时应优先检查工具定义，而不是先怀疑模型能力
多数工具选择错误出在描述不准确（没说明"何时该用/何时不该用"），而不是模型不够聪明。ACI 工具设计的"何时用、何时不用"比"我能做什么"重要得多。这一原则把调试焦点从模型层转到工具描述层。
6. 规划的本质不是产出文档，而是建立深度共识
来自 Matt Pocock /grill-me——糟糕的计划 = 糟糕的输出。Plan Mode 的根本缺陷是"伪对齐"。反转主动权——让 AI 拷问 20-30 个问题，前期 15-20 分钟"被拷问"，后期编码和调试时间大幅减少。
7. 工具思维 vs 搭子思维是 Agent 落地最大的心智鸿沟——比技术问题更难跨越
同一个 Agent 产品，心智不变就只能拿到工具级加速比，心智切换才能拿到任务级卸载收益。推广 Agent 时优先做"成功案例展示"而非"功能教学"——案例触发心智切换。"先用起来，场景自己冒出来"是反直觉但正确的采纳策略。
8. "上下文工程"是 PM/工程师最大的杠杆——80% 输出质量问题不在模型
来自 PM VibeCoding + 阿里十二维：80% 的 AI 输出质量问题不是 Prompt 没写好，而是上下文没给对。@ 引用精确指向 / Cursor Rules 项目级约束 / Skills 描述符 + 真实调用示例。抱怨 AI 代码风格乱 = 没给它立规矩。
9. MCP 不是被替代，而是与 Skills/CLI 形成分层互补
MCP 在生产部署上确实有 token 暴涨等三大痛点，但取代它的不是 Skills 或 CLI，而是更精细的分工——MCP 给能力、Skills 给知识、CLI 高效复用本地命令行生态、Plugin 做整体分发。单点工具协议无法解决 Agent 落地全部问题。
10. MCP 把"语言空间"扩展到"执行空间"是 AI 安全的范式拐点
过去 AI 安全聚焦模型本身（越狱、有害内容），MCP 之后必须扩展到工具链层、执行轨迹层、供应链层。协议层根本特征制造系统性风险：工具描述被直接注入 LLM 上下文，LLM 无法区分正常文档和恶意隐藏指令。MCP 安全必须在协议层 + 沙箱层 + 行为分析层做防御，不能依赖模型本身对齐——模型越强反而越容易被精心构造的指令操控。
11. CLI 是 LLM 的母语，MCP 是后天学的外语——本质是延迟之争
钉钉/飞书 CLI 同周发布 + ScaleKit 实证：9-32 倍 Token 差距，月成本 17 倍差距。企业内部场景（身份已知、权限预设、沙箱运行）应优先选 CLI；开放生态（陌生 Agent 接入）才用 MCP。两者不是替代关系，是分工细化。
12. Agent-as-User 时代：UI 优化优先级低于接口质量
来自 Box CEO + a16z 判断：当企业中 Agent 数量达到员工的百倍千倍时，UI 优化的优先级将低于 API/CLI/MCP 接口质量。Box 已将"agent 界面设计"与"人类界面设计"投入时间并列。"向 Agent 营销"是伪命题——Agent 基于成本、可靠性、数据持久性做理性选择。SaaS 价值要从"系统 + 领域专业知识 + 智能"转向"数据访问权 + 接口质量"。
13. 多租户隔离是 B 端 Agent SaaS 的定价基石而非纯技术债
六面隔离（数据存储 / RAG 检索 / Prompt 装载 / 长任务状态 / 工具权限 / 计费配额）中任一面缺失，其余五面做得再好也可能被击穿。但更重要的商业含义是：Pool / Bridge / Silo 三种隔离模式直接对应三档定价（标准订阅 / 企业版 / 旗舰版），隔离深度的技术选型即定价策略。一开始就全面 Silo 化看似最安全，实则失去 SaaS 规模化成本优势。正确路径是 Pool 为默认、Bridge 为升级包、Silo 为旗舰——让客户按合规需求和预算自选[来源 #15]
14. Claude Agent SDK 让 Build vs. Buy 有了明确答案——非大厂没必要自研 Agent 框架
Claude Agent SDK 不是传统意义上的框架（LangChain 式抽象层），而是把经过数百万用户验证的 Claude Code Harness 直接产品化为可编程子进程。开发者一个 query() 调用即获完整 Agent 能力（文件读写、命令执行、网络搜索、MCP/Skills 扩展），模型后端还可通过环境变量替换为 DeepSeek 等国产模型。这意味着"核心手写，周边借用"的经典策略需要按组织规模重新评估——大厂可自研 Harness 追求差异化，中小团队应直接 SDK 套壳、将 100% 精力聚焦在业务场景和领域知识上。同时需警惕 Anthropic 四层垂直整合（MCP + Stainless + SDK + Model）带来的生态锁定风险[来源 #16]
15. 当搜索流量主要来自 Agent，检索系统需要整体重构（Agentic Find）
📌 2026-05-20 新证据（来源：Notion Sarah Sachs & Simon Last / Latent Space 播客）[来源 #17]
Notion 发现很多 AI 计划下的搜索流量已主要不是人发出来的，而是 Agent 发出来的。原来面向人的搜索优化目标开始失效：人更在乎前几条结果是不是顺手能点，Agent 更在乎 top-k 召回够不够全、片段切得对不对、能不能并行发散多个 query 去扩大搜索空间。Notion 内部把这件事叫 agentic find——把 ranking、query generation、parallel search、snippet 选择当成同一条链路来做，而不是传统搜索优化的单点调参。
对工具生态的含义：一家公司一旦认真做 Agent，最先要动刀的往往不是首页 UI，而是索引、检索、排序、缓存和上下文压缩这些底层设施。这与 §12（Agent-as-User）的判断同构——Agent 不只改变了界面优先级，也改变了检索系统的设计目标。具体的基础设施差异：
| 维度 | 面向人的搜索 | 面向 Agent 的搜索（Agentic Find） |
|---|---|---|
| 优化目标 | 前 3 条结果点击率 | top-k 召回完整性 |
| 查询方式 | 单次短查询 | 并行多个 query 扩大搜索空间 |
| 返回形式 | 标题 + 摘要 + 链接 | 精确切片的文本片段（snippet） |
| 排序策略 | 相关性 + 热度 + 个性化 | 相关性 + 互补性（减少冗余） |
| 上下文约束 | 人的注意力（~10 条） | token 预算（按 context window 分配） |
待探索问题（合并去重后）
- 手搓 vs 框架的临界点量化：项目演进到什么规模/流量/复杂度需要从框架切换到手搓？是否有可量化的判断指标？
- IterResearch 与 MemoraX 路线的关系：工程优化（外部摘要）与模型内生记忆是替代还是叠加？混合架构下如何分配职责？
- 拷问对齐的疲劳边界：用户被 AI 连续拷问 20-30 个问题后会不会疲劳放弃？是否需要分阶段拷问？
- 测试驱动的系统提示如何沉淀为模板：是否有"通用边界规则库"可复用（如"禁止编造""明确标注矛盾"等）？
- Agent 自主度三件套在客服场景的落地：跨 session 续跑/任务状态/后台 I/O 在 AI 客服场景下应做什么改造？
- 三大底层短板优先补齐顺序：记忆/安全/Harness 三者缺一不可，资源有限时应该先补哪一块？
- Budget-aware Agent（Barry 开放问题）：怎么定义 + 执行 token / 时间 / 钱 的 budget？硬上限触发中断、软上限触发压缩降级是否够用？
- Self-evolving Tools（Barry 开放问题）：Agent 能不能设计 + 改进自己的工具？什么样的安全栅栏能让"自我演化"不演化成"自我破坏"？
- Multi-agent 异步通信（Barry 开放问题）：消息丢失、Agent 假冒、跨 Agent 信任等问题如何工程化解决？
- 意图识别长尾问题：80% 请求集中在 20% 意图——是否有"自动从用户输入聚类发现新意图"的工程化流程？
- MCP Tool Search 在大规模工具集下的检索质量：工具数从数百扩展到数万时，检索质量是否还能保持？
- A2A 协议的安全边界：Google A2A 协议安全模型与 MCP 是否同构？跨 Agent 信任、消息篡改、Agent 假冒等问题是否有对应攻击范式？
- Connor 在企业内网部署的工程化：如何在客户内网做安全沙箱？如何处理 Server 启动需要外部凭证、执行结果具有副作用的场景？
- Plugin 打包后的供应链验证：是否需要 Plugin 级签名 + SBOM？
- Advisor Strategy 在领域专属任务上的边界：advisor 决定何时介入是否最优？是否需要 advisor 介入策略的元学习？
- 意图识别置信度的标准化：LLM 自评置信度的可靠性如何？是否有"跨模型统一置信度校准"方法论？
- Claude Agent SDK 模型后端可替换性的质量边界：DeepSeek 等国产模型在 Agent 任务（多步推理、工具选择、错误恢复）中的成功率与 Claude 原生相比差多少？"代码零修改"是否等于"效果零损失"？是否存在特定任务类型的成功率断崖？
- SDK 生态锁定风险评估：当 Anthropic 同时控制 MCP 协议 + Stainless SDK 生成 + Claude Agent SDK + 基座模型时，开发者的退出成本有多高？是否存在"温水煮青蛙"式的锁定路径——初期模型可替换降低警惕，后期 Harness 层深度依赖导致无法迁移？
Coding Agent 特化实践请见 Harness概念架构与Coding工程实践——四大杠杆（Custom Rules / MCP / Skills / SDD）、AGENTS.md 设计、P0/P1/P2 优先级清单、OpenAI/Anthropic/Hashimoto 三大路线对比等内容收录在该方向。
来源索引（去重合并后）
| # | 标题 | 来源 | 收录日期 |
|---|---|---|---|
| 1 | 手搓 Agent vs 框架：工程取舍的阶段性逻辑 | 美团面试题解析 | 2026-04-03 |
| 2 | DeepResearch Agent：ReAct 框架实现与上下文溢出工程实践 | 吴师兄 DeepResearch 系列 | 2026-04-14 |
| 3 | Agent 三大底层能力——郝建业谈记忆、安全、Harness | FreeBuf 对话郝建业 | 2026-05-09 |
| 4 | Agent 工程实践全景：阿里 OpenClaw 十二维落地指南 | 阿里技术 | 2026-04-28 |
| 5 | 拷问模式替代 Plan Mode：颗粒度对齐方法论 | Matt Pocock Claude Code Skill 实践 | 2026-04-07 |
| 6 | Anthropic《Building Effective Agents》原文 + Barry AI Engineer Summit 升级版 | Anthropic 官方博客 + Barry 现场分享 | 2026-05-13 |
| 7 | 从"工具"到"搭子"——AI 本地助手使用心法（DuMate） | 微信公众号 | 2026-04-02 |
| 8 | 产品经理 Vibe Coding 30 个核心概念全景 | 公众号文章（老王） | 2026-04-03 |
| 9 | Agent 意图识别技术详解：Function Calling 与传统 NLU 全景 | 内部知识库（智谱平台为代表） | 2026-01-27 |
| 10 | Agent 核心三要素：工具调用、记忆机制、多步推理 | 微信公众号「小林 coding」（美团面试经） | 2026-04-13 |
| 11 | Anthropic Advisor Strategy：Opus 军师与大小模型协作 | Anthropic 官方博客《The advisor strategy》 | 2026-04-10 |
| 12 | MCP 从诞生到行业标准：繁荣痛点与工具投毒安全危机 | CodeWisdom 团队（复旦软件供应链安全小组） | 2026-05-09 |
| 13 | CLI 才是 Agent 的终局：钉钉飞书集体抛弃 MCP | 公众号文章 | 2026-04-02 |
| 14 | AI Agent 成为软件主要用户：a16z 的行业重构判断 | a16z 播客（× Box CEO Aaron Levie） | 2026-04-10 |
| 15 | 多租户 Agent 隔离设计实践：B2B SaaS 六面隔离与 Pool/Bridge/Silo 选型 | 用户提供文本（B 端 SaaS Agent 工程向） | 2026-05-20 |
| 16 | Claude Agent SDK 快速上手与 DeepSeek 配置教程 | 公众号文章 | 2026-05-20 |
| 17 | Notion 团队：为什么真正难的不是做 Agent，而是重做整个工作系统 | Latent Space 播客（Sarah Sachs × Simon Last） | 2026-05-20 |
演进记录（合并后）
| 日期 | 版本 | 变更摘要 |
|---|---|---|
| 2026-05-12 | v0.1 (旧 A) | "Agent 工程实践与落地"首次构建，由 5 篇源文件批量合成。覆盖手搓 vs 框架、ReAct 最小实现、Context Rot、上下文分层、三大底层短板、ACI 工具三代演进、Agent 自主度三件套、Prompt Caching、Skills 按需加载、拷问对齐、反模式速查表；纳入 7 个生产案例；提炼 10 条洞察 |
| 2026-05-12 | v0.1 (旧 B) | "Agent 工具生态与意图识别"首次构建，由 4 篇核心源文件合成。覆盖意图识别基本流程、Function Calling 五步链、LLM 理解意图三大机制、Agent 核心三要素、意图消歧三类、意图链与状态机、置信度三种实现、MCP 协议三类能力、MCP 三大痛点、MCP Token 工程化、分层互补五层架构、Advisor Strategy、MCP 工具投毒三大攻击范式、Connor 行为偏离检测；纳入 9 个案例；提炼 10 条洞察 |
| 2026-05-15 | v0.2 (两侧) | 由 /route-knowledge 横切重构触发：旧 A 在概念 5 三大短板后追加哲学引用；旧 A 待探索追加 Barry 3 个开放问题；旧 B 方法 2 追加 Poka-yoke 设计法延伸 |
| 2026-05-15 | v0.3 (旧 A) | 由 /route-knowledge 路由分析触发，纳入 DuMate（工具→搭子）+ PM VibeCoding 30 概念。新增工具思维 vs 搭子思维心智模型、AI 助手使用进阶五步路径、Skill vs 浏览器模拟选型；新增 DuMate 视频转 PPT、AI Maker Summit 案例；新增工具/搭子心智鸿沟、进阶五步路径、上下文工程是 80% 输出质量根因三条洞察 |
| 2026-05-15 | v0.2 (旧 B) | 由 /route-knowledge 路由触发：吸收 CLI vs MCP、Agent-as-User a16z 判断 2 篇。新增 CLI 作为 Agent 默认接口、翻译层演化框架、Agent-as-User 范式、监督权独立性悖论；新增 CLI Agent 友好设计模式、飞书 lark-cli 三层架构；新增钉钉飞书 CLI 同周发布、Box CEO Agent-as-User 决策案例；新增 CLI 是 LLM 母语、向 Agent 营销伪命题、UI 优先级让位接口质量、meta-tool 范式四条洞察 |
| 2026-05-18 | v0.4 (旧 A) | 由 /route-knowledge 路由分析触发，纳入 OMC 多智能体编排框架案例（两层 YAML Skill）+ macOS 独占 28.3k Stars 验证 Harness 即产品的市场需求 |
| 2026-05-19 | v0.5 (旧 A) | 由 /route-knowledge 整合"多智能体协作调查"长文触发：反模式速查表追加多智能体专属交叉引用；新增 Delegation Contract 工程落地要点 |
| 2026-05-19 | v0.3 (旧 B) | 与 Agent 架构与协作模式 同步去重：分层互补五层架构改为"工具视角"剪裁版；方向定位段补加"工具接入层在整体架构里的编排"为不包含项 |
| 2026-05-20 | v1.0 (合并) | 由 ai-pm 整合任务触发：将"Agent 工程实践与落地"与"Agent 工具生态与意图识别"两个方向合并为本文。合并方式——MCP 协议描述合为一节（第二章 2.4-2.5）/ Function Calling 演进史合为第二章 2.1+2.4-2.5 / CLI 范式回归主体放第二章 2.11+第三章 3.3。保留差异化——工程心法侧 ReAct/Context Rot/IterResearch/拷问对齐/搭子思维（第一章），工具生态侧 Connor 检测/Agent-as-User/CLI 取代 GUI（第二、三章）。来源索引去重后保留 14 篇；演进记录陈列两侧版本历史 |
| 2026-05-20 | v1.1 | 由 /route-knowledge-pm 路由触发：新增第四章"多租户 Agent 工程（B 端 SaaS 视角）"——以 PM 决策化提炼法重组多租户隔离内容，覆盖六面隔离对照表、Pool/Bridge/Silo 定价分层映射、Prompt 四层装载版本化、长任务沙箱分区、6 项可行动项（P0-P2）。新增第 13 条关键洞察（多租户隔离是定价基石）。来源索引 +1（#15） |
| 2026-05-20 | v1.2 | 由 /route-knowledge-pm 路由触发，融入 Claude Agent SDK 新证据。章节 1.1"手搓 vs 框架"新增子节 1.1.1 标记"决策需重新评估"——SDK 与传统框架本质区别、按组织规模的新决策框架；新增章节 2.12"Claude Agent SDK——从框架到 Harness 产品化"——SDK 架构、V1/V2 API 产品含义、模型后端可替换性、Build vs. Buy 决策启示、风险与机会分析；章节 2.9 追加 SDK 作为五层架构产品化实例；新增第 14 条关键洞察（Build vs. Buy 明确答案）和 2 条待探索问题（模型替换质量边界、生态锁定风险）。来源索引 +1（#16） |
| 2026-05-20 | v1.3 | 由 /route-knowledge-pm 路由触发，融入 Notion / Latent Space 播客情报。§2.11 CLI 范式回归追加 Notion 的 MCP vs CLI 产品视角（"不是站队题"、MCP 天生权限模型、按能力宽窄+权限透明度选择）；新增 §15 关键洞察"Agentic Find"（当搜索流量主要来自 Agent 时检索系统需整体重构）。来源索引 +1（#17） |