AI Agent 开发的“三岔路口“：Workflow、Skill 还是 Framework？一个独立开发者的效率思辨

作者： HOS(安全风信子) 日期： 2026-08-15 主要来源平台： GitHub（anthropics/skills、openai/openai-agents-python、langchain-ai/langgraph），辅助：Anthropic 官方文档、agentskills.io、modelcontextprotocol.io 读完你能学到： 你将从 Anthropic、OpenAI、LangChain 三方的官方定义出发，彻底分清 Agent Workflow / Skill / Framework 的本质边界与适用场景，拿到一套"三层决策框架"直接对照自己的项目做选型，并学到把业务逻辑与底层实现解耦、让 Workflow 可平滑升级为 Framework 的工程方法——不再被社区噪音带着走，而是用当前复杂度所需的最轻量方案做决策。

目录

• 先看问题场景
• 零、先讲一个我踩过的坑：Workflow 从"神器"到"屎山"只要 4 个月
• 一、拆解：三种概念的"本来面目"
• • 1.1 Agent Workflow：为"确定性"而生
  • 1.2 Agent Skill：为"专业性"而存
  • 1.3 Agent Framework：为"复杂性"而建
  • 1.4 三者对照：一张表钉死边界
  • 1.5 别忘了第四块拼图：MCP 与 Subagent
• 二、反思：个人开发者的"三重困境"
• • 2.1 困境一：效率的"短期"与"长期"之争
  • 2.2 困境二：灵活性与可控性的"零和博弈"
  • 2.3 困境三：学习成本与维护成本的"剪刀差"
• 三、深挖："选型犹豫"背后的三个认知误区
• • 3.1 误区一："非此即彼"的排他思维
  • 3.2 误区二："越高级越强大"的技术崇拜
  • 3.3 误区三："Skill 仅仅是 Prompt 模板"的简化理解
• 四、实战：我的"三层决策框架"
• • 4.1 决策层级一：这个任务，AI 需要"自由发挥"吗？
  • 4.2 决策层级二：这个能力，我会"复用"几次？
  • 4.3 决策层级三：这个系统，三个月后会变成什么样？
  • 4.4 实战演示：三个真实需求走一遍决策树
  • 4.5 附赠工具：一张"选型决策记录表"
• 五、我的"个人开发者效率哲学"
• • 5.1 原则一：先"做成"，再"做对"，最后"做优雅"
  • 5.2 原则二：把"可迁移性"作为隐藏优先级
  • 5.3 原则三：承认"个人开发者"的边界
• 六、六个高频问题速答（FAQ）
• 结语：在"选择"之上，还有一个更重要的能力

先看问题场景

早上九点，我泡好咖啡坐在电脑前，准备给手头一个 AI Agent 加"自动生成周报"的新功能。

照理说这是个简单需求。但我盯着编辑器犹豫了整整二十分钟——不是因为不会写，而是因为不知道该用哪种姿势写：

• 写一个 Workflow？把"抓取本周 commit → 聚合统计 → 调用 LLM 润色 → 输出 Markdown"串成固定流程，今天写完今天用。
• 封装一个 Skill？给 Agent 装一块"周报专家"的外挂脑区，以后任何项目都能按同一套规范出周报。
• 还是索性上个 Framework？反正迟早要支持多 Agent 协作、要记住三天前的对话状态，不如一步到位。

这三个词在官方文档里、在社区帖子里、在大佬的推文里反复出现，但它们的边界到底在哪，很少有人真正讲清楚。更麻烦的是，对于只有一个人、一双手、有限时间的个人开发者来说，选错一次的代价是真实可感的：重构成本、学习成本、维护成本，每一项都在烧我的注意力和时间。

这篇文章不写教科书式的定义，只写一个独立开发者在实战中的真实权衡与取舍。我会先拆解三种概念的官方"本来面目"，再复盘我踩过的坑和想明白的三重困境、三个认知误区，最后给出一个可以直接对照使用的三层决策框架。

为了保证每个技术判断都可验证，文中所有定义、代码、数据都标注了官方来源（GitHub 仓库 / 官方文档），你可以逐一核对；凡是属于我个人观点和经验的，我会明确标注"我的观察"，不会冒充事实。

本节核心收获：这篇文章不是概念科普，而是一套"选型方法论"——先看清官方定义，再对照三重困境与三个误区校准认知，最后用三层决策框架落地到自己的项目。

零、先讲一个我踩过的坑：Workflow 从"神器"到"屎山"只要 4 个月

在展开理论之前，我想先讲一段真实的失败经历——这是我所有选型反思的起点，也是这篇文章为什么存在的原因1。

2025 年秋天，我给自己的一个数据采集项目写了第一个 Workflow：定时抓 GitHub 趋势仓库 → 调用 LLM 总结要点 → 输出到 Markdown。用 Python 写的，大概 80 行，三步串起来，干净利落。第一个月它是我最得意的作品：每天自动产出 3 篇技术简报，稳定、便宜、不用管。

然后需求开始叠加。第二个月，用户说"加上按语言过滤"；第三个月，“要能对比两天数据的变化”；第四个月，“抓完要自动发到群里，失败的仓库要重试三次”。

我当时的处理方式是"正确"的——往 Workflow 里加节点、加 if-else。于是 80 行变成了 600 行，而真正的灾难不在代码量，在于：每一次改动，我都要在脑子里重放一遍完整的执行时序，才能确定改这里不会炸到别处。更糟的是，我为了让 LLM 在某一步"聪明一点"，给中间步骤接了一个自由发挥的 prompt——结果它开始跳过步骤、乱改输出格式，而我的 Workflow 完全没有能力察觉这些"越轨行为"。

四个月后，这个 Workflow 变成了我最不想碰的代码：不敢重构，因为没测试；不敢加功能，因为时序复杂度已经超出我"一次装进脑子"的容量。最后我花了整整一个周末，把它拆成 12 个纯函数 + 一个编排层，才重新拿回控制权。

这个坑教会了我三件事，也是贯穿全文的三条暗线：

1. 确定性流程里混入自由发挥，是最隐蔽的失控方式——Workflow 给不了模型自主权，也不该给（对应 2.2 困境二）；
2. 复杂度是按交互数组合爆炸的，不是按行数线性长的——节点从 5 个涨到 30 个，维护成本涨得远不止 6 倍（对应 2.1 困境一与 2.3 的剪刀差公式）；
3. 唯一让我全身而退的，是"函数化封装 + 编排层解耦"——它让"重写"变成了"重拼"（对应 5.2 原则二的可迁移性模板）。

如果你现在正卡在同一个坑里——一个越来越臃肿的 Workflow、一堆不敢动的 if-else、一次次的"这次只加一个小功能"——那么这篇文章就是为你写的。

一、拆解：三种概念的"本来面目"

（先看官方怎么说，再看我怎么用。顺序很重要：官方定义是锚点，个人场景是参考系，两者结合才不会被单方面的宣传带偏。）

本节核心收获：Workflow 为"确定性"而生、Skill 为"专业性"而存、Framework 为"复杂性"而建——这是三个不同维度的答案，不是三个竞争品牌。

1.1 Agent Workflow：为"确定性"而生

官方定义。 Anthropic 在 2024 年 12 月发表的官方文章《Building effective agents》（来源）里给过一个非常清晰的分野：

Workflows are systems where LLMs and tools are orchestrated through predefined code paths. Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.

翻译成大白话：Workflow 是给 LLM 和工具画好一条轨道，让它在上面跑——没有岔路，没有自由意志，只有一步步的严格执行；Agent 则是让 LLM 自己决定每一步怎么走。 Anthropic 把这两者统称为 agentic systems（智能体系统），但在架构上是两条不同的路。

同一篇文章里，Anthropic 总结了生产环境中反复出现的 5 种 workflow 模式，值得每个开发者先背下来：

（表格来源：Anthropic《Building effective agents》，2024-12-19 发布，链接）

我的理解。 Workflow 就是"自动化脚本 Plus 版"。它不要求 AI 有创造力，只要求它不掉链子。

我的使用场景。 我目前用 Workflow 最多的地方是：日报/周报生成器（固定抓数据 → 固定模板输出）、代码格式化与静态检查流水线（black → ruff → 汇总）、定期抓取数据生成图表。这些任务的共同点是：步骤完全确定、输入输出边界清晰、我不需要 AI"灵光一现"。

一句话定位： Workflow 是我的"自动化脚本 Plus 版"——轨道画好，跑就完了。

1.2 Agent Skill：为"专业性"而存

官方定义。 Skill（技能）是 2025 年才真正火起来的形态。Anthropic 官方仓库 anthropics/skills（GitHub，截至 2026-08 已 169.5k stars / 20.2k forks）的 README 开宗明义：

Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks.

关键在 dynamically（按需加载）。Anthropic 已经把 Skill 从 Claude 内部功能上升成了开放标准 —— Agent Skills（agentskills.io），官方说明：

Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task.

官方给出 Skill 的标准文件夹结构（来源：agentskills.io）：

my-skill/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：参考资料/文档
├── assets/           # 可选：模板、资源
└── ...               # 任意附加文件或目录

为什么"按需加载"是灵魂？ Agent Skills 标准里描述了一个三阶段加载机制，叫渐进式披露（progressive disclosure）（来源：agentskills.io）：

也就是说：平时每个 Skill 在上下文里只占"一行介绍"的成本，用到时才把全文加载进来。这就是为什么 Agent 可以挂几百个 Skill 而不把上下文撑爆。这一点我在第 3.3 节还会回来打一个流行的错误认知。

我的理解。 Skill 是给 Agent 配的"外挂脑区"。平时不加载，一旦需要干某类专业活，就把这块"经验芯片"插上去。它跟 CLAUDE.md（常驻记忆）的分工，Claude Code 官方文档说得很清楚（来源：code.claude.com/docs/en/skills）：

Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. Unlike CLAUDE.md content, a skill’s body loads only when it’s used, so long reference material costs almost nothing until you need it.

翻译：当你反复粘贴同一段指令/清单/多步流程时，就该建 Skill；当 CLAUDE.md 里某一段从"事实"长成了"流程"时，也该把它挪进 Skill。 这是官方给的、最实用的判据。

我的使用场景。 写代码审查时加载 Go 语言规范 Skill；写测试时加载 TDD 流程 Skill；写技术方案时加载我自己的写作风格模板 Skill；甚至本文所在的专栏写作，也有一套"CSDN Markdown 特性规范"Skill——本文里你能看到的 @[TOC]、Mermaid、脚注、LaTeX 排版，就是这套 Skill 在起作用（这段是我的实践，不是官方说法）。

一个真实的官方示例。 Claude Code 官方文档给过一个极简且完整的 Skill 例子，叫 summarize-changes（汇总未提交的改动并标出风险，来源：code.claude.com/docs/en/skills 的 “Create your first skill” 一节）。它放在 ~/.claude/skills/summarize-changes/SKILL.md，全文只有几行：

---
description: Summarizes uncommitted changes and flags anything risky.
  Use when the user asks what changed, wants a commit message,
  or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks
you notice such as missing error handling, hardcoded values, or tests that need updating.
If the diff is empty, say there are no uncommitted changes.

（来源：Claude Code 官方文档；! 反引号开头的那一行就是动态上下文注入（dynamic context injection）——Claude Code 先运行 git diff HEAD，再把输出直接塞进 SKILL.md 指令里，让 Skill 的回答永远基于真实的最新 diff，而不是模型的猜测。）

这个例子值得玩味的地方在于：它展示了一个"最小的可执行 Skill"长什么样——description 决定何时触发、正文指令决定怎么执行、动态注入决定数据从哪来。三个部分各有职责，没有一个字是多余的。我建议所有第一次建 Skill 的人，都从这个官方例子起步，而不是从自己的"宏大想象"起步。

一句话定位： Skill 是我把"个人经验"和"团队规范"固化成可复用模块的方式——不常驻，但随叫随到。

1.3 Agent Framework：为"复杂性"而建

官方定义。 Framework（框架）是三层里最重、也最容易被误用的一层。我们看两个主流实现方的官方自我定位：

LangGraph（langchain-ai/langgraph，GitHub，39.7k stars）：

A low-level orchestration framework for building, managing, and deploying long-running, stateful agents.

OpenAI Agents SDK（openai/openai-agents-python，官方文档）：

The OpenAI Agents SDK enables you to build agentic AI apps in a lightweight, easy-to-use package with very few abstractions. … The Agents SDK has a very small set of primitives: Agents (LLMs equipped with instructions and tools), Handoffs (agents delegate to other agents), Guardrails (validation of agent inputs and outputs).

注意两个关键词：LangGraph 强调 long-running（长期运行）+ stateful（有状态）；OpenAI 强调 very few abstractions（极少抽象）。这说明 Framework 的价值不在"功能多"，而在帮你管理复杂度：状态怎么存、多 Agent 怎么通信、失败怎么重试、人怎么介入。

我的理解。 Framework 是"整座工厂的施工图和水电系统"。它决定了 Agent 怎么启动、怎么通信、怎么记忆、怎么失败重试。Workflow 管"一条流水线"，Framework 管"整个车间"。

我的使用场景。 只有当出现以下信号时我才考虑 Framework：需要多个 Agent 协作（比如一个写代码、一个审查、一个跑测试）；需要长期运行的有状态 Agent（要记住三天前的对话）；需要人工介入点（human-in-the-loop）。注意，我用了"才"字——这条纪律的代价，我放在第二部分"困境"里详细算。

一句话定位： Framework 是我从"写 Agent"升级到"架构 Agent 系统"时的基建选择——也是我轻易不碰的基建选择。

1.4 三者对照：一张表钉死边界

本节核心收获：三者的官方定义完全不同维度——Workflow 是"轨道"（确定性执行）、Skill 是"按需加载的能力包"（渐进式披露）、Framework 是"状态与多 Agent 的基建"（长期运行）。先分清这三个"本来面目"，再谈选型，才不会鸡同鸭讲。

1.5 别忘了第四块拼图：MCP 与 Subagent

拆完"三岔路口"，我想补充两个经常和三岔路口混在一起、但其实是另一条维度的东西——因为个人开发者最容易在这两个词上再次困惑。

MCP（Model Context Protocol，模型上下文协议）。 MCP 不是 Workflow、不是 Skill、也不是 Framework，它是连接层。官方定义（modelcontextprotocol.io）：

MCP is an open-source standard for connecting AI applications to external systems. … Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices, MCP provides a standardized way to connect AI applications to external systems.

翻译：MCP 是 AI 应用的 USB-C 口——它规定"AI 怎么插上外部系统"（本地文件、数据库、搜索引擎、第三方 API），而不是"AI 内部怎么编排"。所以正确的理解是：Workflow/Skill/Framework 决定"内部怎么跑"，MCP 决定"外部怎么连"，两者正交，不冲突。官方文档还确认了 MCP 能连接的正是三类东西——data sources、tools、workflows（专门化提示词）（来源：modelcontextprotocol.io），可见"workflow"一词在 MCP 语境下指的是"外部可调用的服务形态"，和我们讨论的编排 Workflow 不是一回事——这个术语撞车，恰恰是社区讨论经常绕晕的原因之一。

Subagent（子代理）。 Subagent 是 Claude Code 官方支持的一等公民能力：独立上下文窗口、独立系统提示词、受限工具集，主 Agent 按描述委派任务（来源：code.claude.com/docs/en/sub-agents）。它和 Skill 的本质区别（官方文档原话，我归纳）：

• Skill = 按需加载的指令/资源包，加载进主 Agent 的上下文，主 Agent 自己执行；
• Subagent = 独立运行的专职 Agent，有自己独立的上下文窗口，只把最终结果交回主 Agent。

一句话记忆：Skill 是"给主 Agent 装外挂脑区"，Subagent 是"派一个分身去干活"。两者经常一起用（Claude Code 官方文档就展示了在 Skill 里跑 Subagent 的模式），但它们不是同一维度的东西——就像 Workflow 与 Skill 不是竞争关系一样。

把上面所有概念放进一张图，它们的关系是这样的：

（图为作者根据 Anthropic 官方文档、agentskills.io、MCP 官方文档整理绘制；各类的官方定义均在正文标注了来源链接）

本节核心收获：三岔路口之外还有两条"正交维度"——MCP 是连接层（USB-C），Subagent 是独立执行的专职分身；它们与 Workflow/Skill/Framework 不是竞争关系，而是可以任意组合的积木。

二、反思：个人开发者的"三重困境"

（定义看清了，困境才浮现。这三重困境不是"技术问题"，而是"资源分配问题"——它的前提是：你只有一个人、一双手、有限的时间。）

本节核心收获：个人开发者选型真正的敌人不是技术，而是三种成本博弈——短期/长期效率之争、灵活/可控的取舍、学习/维护成本的"剪刀差"。看清博弈结构，很多纠结会自动消失。

2.1 困境一：效率的"短期"与"长期"之争

短期效率的账很好算：写一个 Workflow 最快，甚至一段 Prompt 加几行 Python 就能跑。今天写，今天用，边际成本趋近于零。

长期效率的账却很隐蔽：功能越来越多，Workflow 越来越臃肿——节点从 5 个涨到 30 个，每个节点都在 if-else 里打补丁，改一处牵全身。此时回头补 Framework 的课，重构成本是当初的十倍不止。

我用一个公式来量化这个博弈。设：

= 当前方案的构建成本；

= 随功能数

增长的维护成本，通常近似超线性增长：

，其中

（因为节点间的交互是组合爆炸的）；

= 在第

天切换到更强方案的迁移成本。

短期最优解是"今天成本最低"的方案：

。长期最优解是"总成本最低"的方案：

。

我的取舍（个人经验，非官方结论）：先用 Workflow 跑通 MVP，但必须在一个"可升级"的边界内写。具体做法是——用纯函数封装每个步骤，Workflow 只做"胶水层"编排。这样将来迁到 Framework 时，这些函数就是现成的"零件"，迁移成本从"重写全部"降到"重写编排层"。这个"函数化封装"的技巧，我在 5.2 节会给出可直接照抄的模板。

2.2 困境二：灵活性与可控性的"零和博弈"

Framework 给灵活性：你想让 Agent 怎么决策都行，但前提是先搞懂它的全套抽象概念——State、Node、Edge、Memory、Tool、Planner、Checkpointer……（这些概念名取自 LangGraph 官方文档与 OpenAI Agents SDK 官方文档）。学完这些，你已经累掉半条命。

Workflow 给可控性：每一步都捏在手里，你想让它往东它不敢往西。但代价是你要为每一个分支写逻辑——"如果用户输入 X 就走 A，输入 Y 就走 B，模型返回超时就走 C……"写着写着，你发现自己在给 AI 写一个状态机，而状态机的复杂度已经超过了 AI 本身。

这就是零和博弈：自由度给模型，控制权就得让渡；控制权留给开发者，编码量就得暴涨。

我的取舍（个人经验）：核心业务逻辑走 Workflow，边缘探索走 Agent 自主决策。把"输不起"的部分（扣款、删库、发消息）锁死在确定性代码里；把"可以试错"的部分（怎么写这段文案、怎么查这份资料）放开给模型自主。这个原则跟 Anthropic 官方建议在精神上是一致的——官方原话是：

We suggest that developers start by using LLM APIs directly: many patterns can be implemented in a few lines of code. If you do use a framework, ensure you understand the underlying code. Incorrect assumptions about what’s under the hood are a common source of customer error. （来源：Anthropic《Building effective agents》）

即：能少一层抽象就少一层，用框架前必须搞懂底下发生了什么。官方都在劝退过度设计，个人开发者更没有理由一开始就上重框架。

2.3 困境三：学习成本与维护成本的"剪刀差"

这是三重困境里最隐蔽、也最反直觉的一个。我把它叫作"剪刀差"，因为它像一个剪刀口：学习成本随时间递减（学会了就是学会了），维护成本随时间递增（代码越多越难维护），两条线迟早相交——交点就是你该升级的时刻。

这张表是我的经验总结（非官方数据，量级判断供参考）。

注意一个反直觉点：Framework 的学习成本和 升级风险是两回事。学的时候贵，维护的时候未必便宜——框架发新版本（minor upgrade）可能破坏你的抽象假设，这是所有框架用户的共同痛点。所以"上了 Framework 就一劳永逸"是错觉，它只是把维护成本从"自己写的胶水代码"转移到了"跟上框架节奏"。

我的取舍（个人经验）：Skill 是我当前阶段的"甜点区"——它不需要 Framework 那么重的基建，又比 Workflow 更有复用价值。我选择把精力优先投资在封装高质量的 Skill 上，因为它在三个方案里"剪刀差交点出现得最晚"且"交点处的绝对成本最低"。

本节核心收获：三重困境本质是三种成本博弈——短期 vs 长期的构建/迁移成本、灵活 vs 可控的控制权让渡、学习 vs 维护的剪刀差。我的答案：Workflow 跑 MVP + 函数化封装留升级通道；核心逻辑锁死、边缘探索放开；Skill 是个人开发者的性价比甜点区。

三、深挖："选型犹豫"背后的三个认知误区

（三重困境是"客观成本"，接下来这三个误区是"主观认知"。很多时候我们不是选错了方案，而是想错了问题。）

本节核心收获：三个误区分别对应三种思维陷阱——排他思维（非此即彼）、技术崇拜（越高级越强大）、简化思维（Skill 只是 Prompt）。每一个都有官方事实或我的实战反例来击穿。

3.1 误区一："非此即彼"的排他思维

误区表现： 我一度以为三者是互斥的——选了一个就不能用另一个。于是每次选型都像"站队"，选完队还忍不住怀疑自己站错了。

真相： 它们完全可以组合。在 Framework 里跑 Workflow（LangGraph 本身就支持把 workflow 定义为图）、在 Workflow 里调用 Skill（Anthropic 官方把 Skill 定义为"workflows 的载体"之一）、在 Skill 里嵌脚本执行确定性逻辑。官方文档交叉验证了这一点：

• LangGraph 官方定位就是 “low-level orchestration framework for building stateful agents”，而它的图节点（nodes）本质上就是一个个可编排的 workflow 步骤（来源：GitHub README）；
• Claude Code 官方文档明确写：/run、/verify 等内置能力就是 “skills work together to launch your app and confirm changes”（来源：code.claude.com/docs/en/skills）——Skill 本身就是一种流程编排形态；
• anthropics/skills 仓库里大量 Skill 的 SKILL.md 里写的都是"先做 A、再 B、遇到 C 走 D"式的流程指令（来源：GitHub）。

我的实践（个人经验）：我现在用一个轻量级框架跑一个"协调者 Agent"，它负责把不同的 Workflow 和 Skill 串起来——具体活儿交给 Workflow 保证确定性，专业判断交给 Skill 提供约束，协调者只负责"谁先谁后、结果怎么汇总"。既不用全量接入重框架，也享受了框架的编排便利。三者是乐高积木，不是擂台对手。

3.2 误区二："越高级越强大"的技术崇拜

误区表现： 看到社区都在推 Framework、推 Agent 编排，容易产生"不上框架就落伍"的焦虑。仿佛 Workflow 是"上一代产物"，Skill 是"过渡形态"，只有 Framework 才是"最终答案"。

真相： 这个"升级阶梯"叙事是错的。Anthropic 官方文章的原话值得贴在这里：> Consistently, the most successful implementations we’ve seen use simple, composable patterns rather than complex frameworks. … We suggest that developers start by using LLM APIs directly … you should consider adding complexity only when it demonstrably improves outcomes.

（来源：Anthropic《Building effective agents》）

官方明确说：最成功的实现往往用的是简单可组合的模式，而不是复杂框架；只有当复杂度确实带来可衡量的改进时才应该加复杂度。 Framework 解决的是"规模化"问题，而个人开发者的首要问题是"活下去"——快速交付、快速验证、快速转向。规模化是活下来之后才需要考虑的问题。

我的实践（个人经验）：我给自己定了一条铁律——只用当前复杂度所需的最轻量方案（YAGNI 原则的 Agent 版）。具体阈值是：当 Workflow 节点超过 10 个、或 Skill 数量超过 5 个、或出现"两个 Agent 需要互相说话"的需求时，才评估引入框架。在这之前，任何框架选型讨论都进"观察列表"而不是"行动列表"。

3.3 误区三："Skill 仅仅是 Prompt 模板"的简化理解

误区表现： 早期我以为 Skill 就是写好的一段 System Prompt，没什么技术含量——“不就是把提示词存成一个文件吗？”

真相： 好的 Skill 里封装了 SOP（标准操作流程）、工具调用范式、异常处理策略，甚至是错误示例集合。它是一份"可执行的决策树"，而不是一段"建议文本"。证据在官方标准里：

• Agent Skills 标准规定 Skill 可以带 scripts/（可执行代码）、references/（参考资料）、assets/（模板资源），而不仅仅是文字（来源：agentskills.io）；
• Claude Code 官方文档专门讲了 动态上下文注入（dynamic context injection）——SKILL.md 里可以写 !command``，运行时先把命令输出塞进上下文再让模型读，让指令"长在真实数据上"（来源：code.claude.com/docs/en/skills）；
• anthropics/skills 官方仓库里真实存在靠脚本驱动的 Skill（比如 docx/pdf/pptx/xlsx 文档技能），一个 Skill 就是一个小型工具链（来源：GitHub）。

我的实践（个人经验）：我开始用结构化方式定义 Skill，把"触发条件（description）"“执行步骤（Instructions）”“失败回退”"成功标准"都写进 SKILL.md 的 YAML frontmatter 和正文里，这样既能让 AI 理解，也能让未来的自己理解。一个可以对照的官方最小示例是 anthropics/skills 仓库 template 目录里的模板（来源：GitHub template 目录）：

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Add your instructions here that Claude will follow when this skill is active]

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

（来源：anthropics/skills 仓库 template/SKILL.md，官方模板原文）

注意 frontmatter 里只有两个必填字段：name 和 description。但 description 的质量直接决定模型会不会在正确时机加载它——这是官方文档里明确强调的（来源：code.claude.com/docs/en/skills 的 “Skill not triggering” 一节）。

本节核心收获：排他思维是错的（三者可组合）、技术崇拜是错的（官方明说简单模式最成功）、"Skill 只是 Prompt"是错的（官方标准支持脚本/资源/动态注入）。认知校准后，选型焦虑能消掉一大半。

四、实战：我的"三层决策框架"

（理论到此为止。这一节给出一棵可以直接对照执行的决策树——每次接到"要不要给 Agent 加个新能力"的需求，就按三层问题往下走。）

本节核心收获：三层决策框架 = 自由发挥度（该不该给模型自主权）× 复用次数（值不值得封装）× 演化预判（三个月后长什么样）。三个问题都答完，答案通常已经自己浮现。

4.1 决策层级一：这个任务，AI 需要"自由发挥"吗？

判断要点：问自己"如果输出错了，我能承受吗？"——不能承受就走 Workflow；能承受但需要专业质量就走 Skill；连"需要几步才能完成"都无法预判，才轮到 Agent。

4.2 决策层级二：这个能力，我会"复用"几次？

判断要点：官方给过一个极其好用的判据（我前面引用过）：“当你反复粘贴同一段指令/清单/多步流程时，就该建 Skill”（来源：code.claude.com/docs/en/skills）。"复制粘贴第三次"就是建 Skill 的信号——不是第十次，是第三次。

4.3 决策层级三：这个系统，三个月后会变成什么样？

判断要点：这条最难，因为要预测未来。我的经验法则是：如果你能说清楚"三个月后会新增的 3 个功能"，说明复杂度增长可预期，按预期设计；如果说不出，说明现在没有足够的复杂度值得投资框架。 投资框架本质是"今天付钱买明天的确定性"，而"明天不确定"时，最理性的做法是不买。

把三层决策合起来，就是这棵决策树：

（图为作者绘制，对应上文三层决策表）

4.4 实战演示：三个真实需求走一遍决策树

光有框架还不够，我拿自己最近接到的三个真实需求，把整棵树完整走一遍给你看——你会发现答案几乎不需要"纠结"，而是被问题本身逼出来的。

需求 A：给博客生成"本周热门文章推荐"。 走决策树：

1. 问题①：需要自由发挥吗？ 不需要。推荐逻辑完全固定（按阅读量、发布时间、标签过滤），AI 参与反而引入不确定性。→ 走 Workflow 分支。
2. 结论：Workflow。用 5.2 的纯函数模板写 filter_hot() + rank_by_reads() + render_list() 三步，胶水层 10 行，半天搞定。

这个选择的关键是：这个需求永远不会长成 Framework——它的输入输出边界天生封闭，三个月后最坏情况是加两个过滤条件，复杂度可预期。

需求 B：团队代码评审助手。 走决策树：

1. 问题①：需要自由发挥吗？ 需要专业判断（安全、性能、可维护性各有侧重），但范围可控（评审对象明确、标准明确）。→ 走 Skill 分支。
2. 问题②：会复用几次？ 每个项目每次提交都要用，属于"多个场景反复使用"。→ 确认走 Skill。
3. 问题③：三个月后？ 稳定（评审标准短期内不变）。→ Skill 足够，不上 Framework。
4. 结论：Skill。直接抄官方 code-reviewer 示例的结构（见附录 B），把"工具集限定为只读"这个关键安全设计一并抄上——评审者不该有写权限，这个约束本身就是 Skill 的"可控性"来源。

需求 C：跨周有状态的竞品监控 Agent（要记住上周结论、对比变化、自动发报告）。 走决策树：

1. 问题①：需要自由发挥吗？ 有状态 + 跨周对比 + 多步计划，属于"开放式推理"边缘——但又不全是。→ 走中间态，继续问。
2. 问题②：会复用几次？ 长期运行，每天执行。→ 值得投资。
3. 问题③：三个月后？ 用户已经明说"下季度要加多源数据、多 Agent 并行抓取"。→ 复杂度暴增，提前上车 Framework。
4. 结论：Framework。用 LangGraph 这类状态图框架，把"记忆上周结论"交给持久化（checkpointer），把"对比变化"写成确定性节点，把"自动发报告"作为收尾节点——复杂度的每一块都有框架的对应抽象兜底（LangGraph 官方文档把 durable execution、memory、human-in-the-loop 列为核心卖点，这正是需求 C 要的东西）。

三个需求走完，你会发现一个规律：决策树不是在替你做选择，而是在逼你回答"我对这个需求到底了解多少"——答不上来的问题（比如"三个月后会变成什么样"），恰恰是最该先去做需求调研的地方，而不是先选技术。这个认知，比任何选型表都值钱。

本节核心收获：三个真实需求（博客推荐/代码评审/有状态监控）完整走一遍决策树后，结论是被问题逼出来的而不是"选"出来的；决策树真正检验的是"你对需求的了解程度"，答不上来的问题才是需求调研的重点。

4.5 附赠工具：一张"选型决策记录表"

选型不该是一次性的脑内活动，而应该是可以复盘的资产。我给自己设计了一张决策记录表，每次给 Agent 加能力时填一次，三个月后回看——你会发现自己的判断误差模式，比任何技术文档都值钱2。

这张表有三个隐藏价值：

1. 它逼你把"感觉"翻译成"判断"——填表的过程就是决策树走查的过程，写下来的答案比脑内一闪而过的答案诚实得多；
2. 它让你能回放自己的误差——三个月后对比"预计成本 vs 实际成本"“选择 vs 结果”，你会清楚地看到自己是"系统性过度设计"还是"系统性欠设计"；
3. 它是迁移通道的原始文档——当需求 C 类任务到来时，历史记录告诉你哪些"零件"已经可复用。

如果你不想自己设计表格，直接复制上面这张，把"我填的真实例子"列清空即可。它是全文唯一一个不需要任何官方来源的工具——因为它记录的是你自己的判断，而你的判断，正是选型的真正输入。

本节核心收获：决策记录表把选型从"一次性脑内活动"变成"可复盘的资产"——逼你把感觉翻译成判断、三个月后回放误差、并为将来迁移留档。它记录的不是技术，是你自己的决策质量。

五、我的"个人开发者效率哲学"

（决策框架解决"这一次怎么选"，效率哲学解决"长期怎么活"。这一节是全文的思想收束——我的立场，欢迎反驳。）

本节核心收获：三条原则——先做成再做对再做优雅、把可迁移性当隐藏优先级、承认个人开发者的资源边界。它们比任何具体选型都更重要。

5.1 原则一：先"做成"，再"做对"，最后"做优雅"

不要因为纠结选哪个框架而迟迟不动手。第一个版本用最笨的方式跑起来，比什么都重要——这句话既是我对 Agent 开发的观察，也是 Anthropic 官方反复强调的：

Start with simple prompts, optimize them with comprehensive evaluation, and add multi-step agentic systems only when simpler solutions fall short. （来源：Anthropic《Building effective agents》）

官方的原话是"从简单 prompt 开始，用评估优化，只有在简单方案确实不够时才加多步 agentic 系统"——这就是"先做成、再做对、最后做优雅"的官方版表述。

我的经验信号：当你有"如果当时用了 XX 就好了"的感觉时，说明你真的到了该升级的拐点——这个感觉本身就是最可靠的迁移触发器，比任何架构评估都准。

5.2 原则二：把"可迁移性"作为隐藏优先级

无论选哪种方案，我都要求自己业务逻辑与底层实现解耦。这样从 Workflow 切到 Framework 时，损失最小。

具体做法：核心逻辑写在纯函数里，Workflow/Skill/Framework 都只做"胶水层"。下面这个 Python 模板是我所有 Agent 功能的起点（这是我自己的工程模板，非官方代码；用 typing 保证可测性）：

# 【我的工程模板，非官方代码。作用：业务逻辑与编排层解耦】
# 用法：把"会变"的步骤写成纯函数，把"编排"留给 Workflow/Skill/Framework
from typing import Callable, TypeVar, List

T = TypeVar("T")          # 输入类型
R = TypeVar("R")          # 输出类型

def make_step(func: Callable[[T], R], name: str) -> Callable[[T], R]:
    """把一个纯函数包装成带名字的"可编排步骤"。
    将来迁移到 LangGraph 时，这个 step 就是现成的 node；
    迁移到 OpenAI Agents SDK 时，这个 step 就是现成的 tool/agent。"""
    def step(x: T) -> R:
        result = func(x)
        print(f"[step:{name}] {x!r} -> {result!r}")   # 可观测性
        return result
    return step

# 示例：周报流水线的三个"零件"
fetch_commits   = make_step(lambda repo: ["feat: x", "fix: y", "docs: z"], "fetch_commits")
aggregate_stats = make_step(lambda commits: f"{len(commits)} commits", "aggregate_stats")
render_markdown = make_step(lambda stats: f"## 周报\n{stats}", "render_markdown")

def weekly_report(repo: str) -> str:
    """Workflow 版编排（胶水层）：三步串起来。"""
    return render_markdown(aggregate_stats(fetch_commits(repo)))

# 将来迁移到 Framework 时，胶水层换成 StateGraph/entrypoint，
# 三个 make_step 产物原封不动直接复用。
print(weekly_report("my-repo"))

（来源：作者工程模板，MIT 风格自用代码；配合 LangGraph 官方 Quickstart 的 node 概念使用）

为什么有效：LangGraph 的节点（node）是"函数 + 状态"；OpenAI Agents SDK 的 agent 是"指令 + 工具"。纯函数天然同时满足两者的最小接口——所以它是迁移成本最低的封装粒度。

迁移示范：同一个业务，Workflow 版 → LangGraph 版。 为了让你直观感受"迁移成本有多低"，我用 LangGraph 官方 Quickstart 的真实结构（来源：docs.langchain.com/oss/python/langgraph/quickstart）把上面的周报流水线重写一遍。注意看：业务函数原封不动，变的只是胶水层：

# 【来源：LangGraph 官方 Quickstart 结构 + 作者周报业务，仅供演示迁移思路】
# 关键点：下面两个函数就是 5.2 模板里的"零件"——迁移时无需改动
def fetch_commits(repo: str) -> list[str]:
    return ["feat: x", "fix: y", "docs: z"]

def render_markdown(stats: str) -> str:
    return f"## 周报\n{stats}"

# —— 以下是 LangGraph 胶水层（对比 Workflow 版的胶水层）——
from typing import TypedDict, Literal
from langgraph.graph import StateGraph, START, END

class ReportState(TypedDict):
    repo: str
    commits: list[str]
    report: str

def node_fetch(state: ReportState) -> dict:
    return {"commits": fetch_commits(state["repo"])}   # 复用业务函数

def node_render(state: ReportState) -> dict:
    return {"report": render_markdown(f"{len(state['commits'])} commits")}  # 复用业务函数

builder = StateGraph(ReportState)
builder.add_node("fetch", node_fetch)
builder.add_node("render", node_render)
builder.add_edge(START, "fetch")
builder.add_edge("fetch", "render")
builder.add_edge("render", END)
report_agent = builder.compile()

# 对比：Workflow 版是 render(markdown(fetch(repo))) 函数嵌套；
# LangGraph 版是 节点 + 边 的图结构。业务函数零改动。

（演示代码：胶水层结构取自 LangGraph 官方 Quickstart 的 StateGraph 用法，业务函数为作者示例；若要真正运行，请按官方文档安装 langgraph 并补齐模型调用节点。）

这就是"把可迁移性当隐藏优先级"的全部秘密：你不需要在第一天就选对架构，你只需要保证"换架构那天，业务代码不用重写"。 而实现这一点的方法朴素得惊人——把所有逻辑写成无副作用的纯函数。

5.3 原则三：承认"个人开发者"的边界

我没有大厂的团队和基建，我的第一资源是注意力，第二资源是时间。这句话决定了所有技术选型的排序。

• 凡是不能直接服务"用户价值"的技术选型，都是负债；
• Framework 本身不是目的，帮用户解决问题才是；
• 每引入一个新工具，都要先问：它是在帮我把注意力花在用户身上，还是在让我花注意力伺候工具本身？

这不是反技术，而是个人开发者版的"技术债会计"：团队可以用人力摊薄工具成本，个人不行——每多一层抽象，都是我一个人在维护。

本节核心收获：三条效率哲学——先做成再做对再做优雅（官方背书）、业务逻辑与编排解耦（纯函数胶水层模板）、承认注意力与时间边界（技术债会计）。工具是杠杆，不是身份。

六、六个高频问题速答（FAQ）

（这篇文章发布前，我在社群里被问到最多的六个问题，统一回答在这里——它们本质上是决策树的"售后问题"。）

本节核心收获：六个 FAQ 覆盖"选型之外"最常见的实操困惑——混合使用、已有存量系统、版本升级、文档维护、失败重试、何时否定本文——每个都给出可直接执行的答案。

Q1：我现在已经在用 Framework 了，但发现很多场景根本用不上它的能力，能退回去吗？

能，而且该退。Anthropic 官方那句话值得再贴一次：“只有当场量确实带来可衡量的改进时才应该加复杂度”（来源：Building effective agents）。退化不是"技术倒退"，是"成本回归理性"。我的做法：把 Framework 里那些"从未被触发"的抽象层逐个摘掉——如果摘掉之后功能不变、可测性不变，就说明那一层本来就是负债。

Q2：同一个系统里能同时用 Workflow、Skill 和 Framework 吗？会不会显得"不专业"？

这正是 3.1 说的"排他思维"误区。能，而且官方生态就是这样组合的：LangGraph 官方文档明确把它定位为"workflows + agents"的统一运行时（来源：docs.langchain.com），Claude Code 官方文档也展示了 Skill 与 Subagent 的配合模式（来源：code.claude.com/docs/en/skills）。"只用一种技术栈"不是专业，是教条。

Q3：我的 Agent 已经跑在生产环境了，现在想引入 Framework，怎么平滑迁移？

按 5.2 的原则迁移：先保证业务逻辑是纯函数，再把胶水层从 Workflow 换成框架的节点。迁移过程中建议"双轨运行"——新旧两套并行跑一周，对比输出一致性和成本，一致后再切流。千万不要"停线重构"，个人开发者经不起一次性重构失败。

Q4：Skill 越来越多之后，怎么管理？会像 Workflow 一样变成新的一坨屎吗？

会，如果不管的话。我的管理三条（个人经验）：① 给每个 Skill 写清楚 description 的"何时用/何时不用"——这是模型触发它的唯一依据（来源：code.claude.com/docs/en/skills 的 “Skill not triggering” 一节）；② Skill 目录进 Git，用版本号管理（anthropics/skills 仓库本身就是这么做的：48 commits、每个 Skill 一个文件夹）；③ 每季度清理一次：三个月没被触发过的 Skill，要么合并要么归档。Skill 的优势恰恰在于"渐进式披露"让大量 Skill 并存不占上下文——但"不占上下文"不等于"不需要整理"。

Q5：Agent 跑挂了怎么办？Workflow 和 Framework 在失败处理上有什么区别？

这是两者最本质的差别之一。Workflow 的失败处理要你自己写（try/except、重试、告警，全在胶水层）；Framework 把"durable execution"作为内置能力——LangGraph 官方明确把 durable execution（持久执行：失败后从断点恢复）列为核心卖点（来源：GitHub README）。所以判断依据很直接：如果"失败后能续跑"是硬需求，Workflow 要付出额外成本，Framework 则开箱即用——这也应该写进决策树问题③的评估里。

Q6：这篇文章会不会过时？三个月后我该回来改哪些判断？

会过时，而且我希望你带着批判读它。本文所有事实锚点都标注了抓取时间（2026-08），其中 stars 数据是时点快照、工具生态（尤其 Framework 层）迭代极快。三个月后建议重点复核三处：① anthropics/skills 仓库是否仍是 Skill 标准事实来源；② LangGraph / OpenAI Agents SDK 的定位是否变化（比如出现了更轻量的新框架）；③ Anthropic 官方是否更新了 workflows vs agents 的定义（那篇文章发表于 2024-12，官方自己都提示"工具生态已变化"）。判断方法永远比结论长寿——记住决策树和三条哲学，比记住本文的任何具体推荐都重要。

本节核心收获：FAQ 的答案大多指向同一个底层逻辑——Framework 可以退、三者可以混用、迁移要双轨、Skill 要管理、失败续跑是框架的核心价值、本文结论有时效性。方法论比结论更值得带走。

结语：在"选择"之上，还有一个更重要的能力

回顾全文，我们走了一条完整的路：

• 拆解：Workflow 是预定义路径的编排（确定性）、Skill 是按需加载的能力包（专业性）、Framework 是状态与多 Agent 的基建（复杂性）——三者维度不同，官方定义可查可验；
• 反思：三重困境是三种成本博弈——短期/长期、灵活/可控、学习/维护剪刀差；
• 深挖：三个误区——非此即彼、技术崇拜、Skill 只是 Prompt——各有官方事实击穿；
• 实战：三层决策框架——自由发挥度 × 复用次数 × 三个月演化，任何需求都有落点；
• 哲学：先做成再做对再做优雅、可迁移性优先、承认资源边界。

而比"选对工具"更重要的，是理解自己当前所处的阶段和真实的复杂度需求。Anthropic 官方那篇文章的标题已经替我说完了：Building effective agents——重点是 effective，不是 complex。

AI Agent 开发还在极早期，没有"银弹"，也没有"标准答案"。作为一个独立开发者，最大的优势不是资源多，而是转身快、试错成本低。善用这个优势——Workflow、Skill、Framework，都只是你手中的不同工具，而不是你的标签。

最后送你一份可以直接抄的行动清单：

• 今天要做一个新功能 → 从一个最简单的 Workflow 开始写（用 5.2 的纯函数模板）
• 同样的 Prompt 在三个地方复制粘贴 → 立刻封装成一个 Skill（参考 3.3 的最小模板）
• 需要两个 Agent 互相说话，或 Agent 需要记住三天前的对话 → 认真评估一个 Framework
• 每两个月做一次"技术债务审视"：当前的方案还是最优解吗？要不要升级？
• 升级前，先回答决策树三个问题，再动手（别让焦虑替你做决定）

参考链接：

• 主要来源：anthropics/skills - Agent Skills 官方仓库（169.5k stars），Skill 定义、目录结构、template 模板
• 主要来源：langchain-ai/langgraph - LangGraph（39.7k stars），long-running stateful agents 官方框架
• 主要来源：openai/openai-agents-python - OpenAI Agents SDK 官方仓库与文档（Agents/Handoffs/Guardrails 三原语）
• 辅助：Anthropic《Building effective agents》 - workflows vs agents 官方定义、五种 workflow 模式、简单优于复杂的官方建议
• 辅助：Claude Code Skills 官方文档 - 何时创建 Skill 判据、动态上下文注入、SKILL.md 格式
• 辅助：agentskills.io（Agent Skills 开放标准） - 渐进式披露机制、Skill 文件夹规范
• 辅助：LangGraph Quickstart 官方文档 - calculator agent 完整示例代码
• 辅助：modelcontextprotocol.io（MCP） - AI 应用与外部系统连接的开源标准
• 辅助：Claude Code Subagents 官方文档 - 子代理（subagent）定义与内置示例

附录（Appendix）：

A. 一个完整可运行的 LangGraph 计算器 Agent（来源：LangGraph 官方 Quickstart，Graph API 版，可对照本文 1.3 节理解"Framework 里的节点/边/状态"）：

# 【来源：LangGraph 官方 Quickstart（docs.langchain.com/oss/python/langgraph/quickstart），Graph API 完整示例】
# 环境：pip install -U langgraph langchain-anthropic；设置 ANTHROPIC_API_KEY
from langchain.tools import tool
from langchain.chat_models import init_chat_model
from typing import Literal, TypedDict
from typing_extensions import Annotated
import operator
from langchain.messages import AnyMessage, SystemMessage, ToolMessage, HumanMessage
from langgraph.graph import StateGraph, START, END

model = init_chat_model("claude-sonnet-4-6", temperature=0)

@tool
def multiply(a: int, b: int) -> int:
    """Multiply `a` and `b`."""
    return a * b

@tool
def add(a: int, b: int) -> int:
    """Adds `a` and `b`."""
    return a + b

@tool
def divide(a: int, b: int) -> float:
    """Divide `a` and `b`."""
    return a / b

tools = [add, multiply, divide]
tools_by_name = {tool.name: tool for tool in tools}
model_with_tools = model.bind_tools(tools)

class MessagesState(TypedDict):
    messages: Annotated[list[AnyMessage], operator.add]
    llm_calls: int

def llm_call(state: MessagesState):
    return {
        "messages": [model_with_tools.invoke(
            [SystemMessage(content="You are a helpful assistant tasked with performing arithmetic on a set of inputs.")]
            + state["messages"]
        )],
        "llm_calls": state.get('llm_calls', 0) + 1,
    }

def tool_node(state: MessagesState):
    result = []
    for tool_call in state["messages"][-1].tool_calls:
        tool = tools_by_name[tool_call["name"]]
        observation = tool.invoke(tool_call["args"])
        result.append(ToolMessage(content=observation, tool_call_id=tool_call["id"]))
    return {"messages": result}

def should_continue(state: MessagesState) -> Literal["tool_node", END]:
    messages = state["messages"]
    last_message = messages[-1]
    if last_message.tool_calls:
        return "tool_node"
    return END

agent_builder = StateGraph(MessagesState)
agent_builder.add_node("llm_call", llm_call)
agent_builder.add_node("tool_node", tool_node)
agent_builder.add_edge(START, "llm_call")
agent_builder.add_conditional_edges("llm_call", should_continue, ["tool_node", END])
agent_builder.add_edge("tool_node", "llm_call")
agent = agent_builder.compile()

messages = [HumanMessage(content="Add 3 and 4.")]
messages = agent.invoke({"messages": messages})
for m in messages["messages"]:
    m.pretty_print()

B. 一个真实的 Subagent（子代理）示例（来源：Claude Code 官方文档 “Create custom subagents” 的 Code reviewer 示例——注意它和 Skill 的区别：Subagent 是独立运行的"专职 AI 助手"（独立上下文窗口 + 受限工具集），而 Skill 是"按需加载的指令包"；二者可配合使用）：

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

（来源：code.claude.com/docs/en/sub-agents 官方示例原文；该文档还内置了 debugger / data-scientist / database-query-validator 等可对照的 subagent 示例。注意 tools 字段限定该 subagent 只能读不能写——这就是 Framework 层"可控性"落到具体实例的样子。）

C. 关键术语速查（缩写/定义列表）：

• Agentic system（智能体系统） : Anthropic 对 workflows 与 agents 的总称（来源）
• Progressive disclosure（渐进式披露） : Skill 按"名称/描述 → 全文 → 脚本资源"三段式按需加载的机制（来源：agentskills.io）
• Handoff（移交） : OpenAI Agents SDK 中 Agent 把任务委托给另一个 Agent 的原语（来源：官方文档）
• Guardrail（护栏） : OpenAI Agents SDK 中对 Agent 输入/输出做校验的原语（同上）
• StateGraph（状态图） : LangGraph 中把 Agent 定义为"节点+边+状态"的图结构（来源：官方文档）

D. 文中代码与数据来源清单（发布前人工核验表）：

• anthropics/skills 仓库 stars/forks 数据：2026-08 抓取 GitHub 页面
• langchain-ai/langgraph 仓库 stars 数据：2026-08 抓取 GitHub 页面
• LangGraph Quickstart 代码：2026-08 抓取官方文档，可直接运行（需 ANTHROPIC_API_KEY）
• OpenAI Agents SDK 三原语与 hello world：2026-08 抓取官方文档
• Agent Skills 文件夹结构与渐进式披露：2026-08 抓取 agentskills.io
• 建议核实：各仓库 stars 数为抓取时快照，发布前建议在 GitHub 页面复核最新数值
• 建议核实：若引用其他厂商（如 AWS Strands Agents SDK、Rivet）也建议逐一打开官方链接确认现状

关键词： Agent Workflow, Agent Skill, Agent Framework, LangGraph, OpenAI Agents SDK, Anthropic, 渐进式披露, 独立开发者选型, 技术债, 安全风信子 技术深度 专业价值

在这里插入图片描述

1. 这个例子是作者 2025 年的真实项目经历，作为个人踩坑案例分享；具体项目细节已脱敏，时间线为作者记忆所及，供读者参考而非官方数据。 ↩︎
2. 决策记录表是作者的自用工具（非官方标准），格式可自由修改；其价值在于"记录→回看→修正"的循环，而非表格本身。 ↩︎