企业官网建设流程全解析

1. 为什么“给 AI Agent 配工作流”是个真问题

1.1 从“会聊天”到“能干活”的鸿沟

过去一年，我身边不少做开发的朋友都在折腾 AI Agent。大家最初的兴奋点都差不多：模型能理解自然语言，能调用工具，能写代码，感觉离“全自动干活”只差一步。但真正把 Agent 放进一个实际项目里跑上几天，几乎所有人都会撞上同一堵墙——它不稳定，不可控，不可复现。

举个我亲身踩过的例子。我让一个 Agent 帮我处理一批日志文件：读取目录、过滤错误行、按模块归类、生成一份汇总报告。第一次跑，它干得挺漂亮；第二次跑，它换了一种过滤逻辑；第三次跑，它干脆把某个目录跳过了，理由是“看起来不重要”。你问它为什么，它给你一段听起来很有道理的解释，但那段解释和它实际做的事对不上。

这就是问题的核心：大模型擅长的是“生成”，而工程需要的是“确定性”。生成意味着每次都可能不一样，而工程流程要求同样的输入必须得到同样的输出，至少要在可接受的范围内稳定。Agent 本身没有“工程纪律”，它有的是概率和联想。所以，想让 Agent 真正参与生产，就必须在它外面套一层东西——这层东西，就是工作流。

1.2 工作流到底给 Agent 补了什么

我习惯把 Agent 比作一个能力很强但没上过班的实习生。他聪明、学得快、什么都能聊，但你不敢把关键任务直接交给他，因为他不知道公司的规矩：文件放哪、命名怎么起、什么情况要请示、什么情况必须停下来。工作流就是那本《员工手册》加上一套打卡和审批系统。

具体来说，一套工程工作流给 Agent 补的是四样东西：

• 边界：明确哪些事能做、哪些不能做、做到什么程度算完成。没有边界的 Agent 会无限发散，你让它写个函数，它顺手把整个模块重构了。
• 顺序：先做什么、后做什么、什么必须等什么。工程任务大多有依赖关系，Agent 天然倾向于“想到哪做到哪”。
• 校验：每一步的产出怎么检查、不合格怎么办。Agent 自己不会怀疑自己，它生成什么就信什么。
• 记录：做了什么、为什么这么做、中间状态是什么。出了问题要能回溯，不然排查就是玄学。

这四样东西，单靠提示词是补不齐的。提示词能约束一次对话，但约束不了跨会话、跨任务的长期行为。你需要的是结构化的、可执行的、能落地的流程定义。这就是“Skills”这个概念要解决的问题——把工程工作流拆成一个个可复用的技能单元，让 Agent 按需加载、按规执行。

1.3 这套东西适合谁

如果你只是拿 Agent 聊聊天、写写文案、做做头脑风暴，那确实不需要这么重的工作流，提示词写好一点就够了。但如果你符合下面任意一条，这套思路就值得认真看：

• 你在用 Agent 处理多步骤任务，比如数据清洗、代码生成、文档处理、自动化测试。
• 你希望 Agent 的产出可复现，今天跑和明天跑结果要一致。
• 你需要多个 Agent 协作，或者一个 Agent 在多个任务间切换而不混乱。
• 你打算把 Agent 接入已有的工程体系，比如 CI、代码仓库、任务管理系统。

我自己的判断标准很简单：当你会因为 Agent 的一次“发挥”而需要手动返工时，就该上工作流了。返工一次是偶然，返工三次就是流程缺失。

2. 拆解“Skills”这套工作流的核心设计

2.1 为什么是“技能”而不是“流程”

这里有个设计上的关键选择，值得说清楚。很多人第一反应是设计一套“大流程”：从任务开始到结束，一条龙定义好。但实际用下来，这种大流程非常脆弱——任务稍微变一点，整条流程就得改，改完还要重新测，维护成本极高。

“Skills”的思路不一样。它把工作流拆成一个个独立的、自包含的技能单元。每个技能只负责一件事，有自己的输入、输出、执行规则和校验标准。Agent 面对一个任务时，不是走一条固定流水线，而是根据任务需要，组合调用不同的技能。

这个选择背后的逻辑是：工程任务的多样性远大于共性。你没法用一条流程覆盖所有情况，但你可以用一组技能拼出大多数情况。就像乐高，你不设计“一辆车”，你设计轮子、底盘、座椅，然后按需拼装。

我实测下来，这种拆法有三个明显好处：

• 可测试：每个技能单独测，输入输出明确，坏了容易定位。
• 可复用：一个“读取并解析配置文件”的技能，在十个任务里都能用。
• 可演进：改一个技能不影响其他技能，迭代风险低。

2.2 一个技能单元应该包含什么

我参考了几个开源 Agent 框架的设计，也结合自己踩坑的经验，总结出一个技能单元至少要有下面这几个部分。缺了任何一个，实际跑起来都会出问题。

我特别想强调校验规则和失败处理这两块。大多数人在设计技能时只关注“怎么做”，忽略了“怎么知道做对了”和“做错了怎么办”。结果就是 Agent 一路狂奔，产出一堆看似合理实则错误的东西，等到最后才发现，中间过程已经没法回溯了。

提示：校验规则要尽量具体、可执行。不要写“检查结果是否合理”，要写“检查输出行数是否等于输入行数”“检查每个字段是否非空”“检查数值是否在预期范围内”。模糊的校验等于没有校验。

2.3 技能之间怎么衔接

技能拆开了，下一个问题就是怎么串起来。这里有两种常见模式，我两种都用过，各有适用场景。

第一种是显式编排：你提前定义好技能的执行顺序，Agent 按顺序调用。比如“先解析配置，再读取数据，再清洗，再汇总”。这种模式适合流程固定、步骤明确的任务，可控性最强，但灵活性差。

第二种是动态选择：你只给 Agent 一组技能和任务目标，让它自己决定用哪些、按什么顺序。这种模式灵活，能处理你没预料到的情况，但可控性弱，容易跑偏。

我的经验是：核心链路用显式编排，边缘情况用动态选择。也就是说，任务的主干流程固定死，保证稳定性；主干之外的异常处理、补充操作，允许 Agent 灵活调用技能。这样既稳又不死板。

具体实现上，我通常会在工作流里加一个“调度层”。调度层不干活，只负责判断当前处于哪个阶段、下一步该调哪个技能、上一个技能的产出是否合格。调度层本身也可以是一个技能，但它的规则要写得非常明确，不能有歧义。

3. 核心技能模块的实操拆解

3.1 任务解析技能：把模糊需求变成明确指令

这是整条工作流的入口，也是最容易被低估的一环。用户给的需求往往是模糊的：“帮我处理一下这批数据”“把这个模块优化一下”。Agent 如果直接拿这种需求去干活，结果基本不可控。

任务解析技能要做的，是把模糊需求翻译成结构化的任务描述。我一般让它输出这么几个字段：

• 任务类型：属于哪类操作（读取、转换、生成、校验等）。
• 目标对象：操作什么（哪个文件、哪个目录、哪个模块）。
• 预期产出：最终要得到什么（一份报告、一个文件、一段代码）。
• 约束条件：有什么限制（不能改哪些东西、必须用什么格式）。
• 完成标准：怎么算做完了。

这个技能的难点在于追问。用户给的信息往往不全，Agent 需要主动识别缺失项并追问。但追问不能无限进行，我一般设一个上限：最多追问两轮，两轮后还没说清，就按最保守的默认值执行，并在产出里标注假设。

# 任务解析技能的输出结构示例（伪代码） task_spec = { "task_type": "data_transform", "target": {"path": "./logs", "pattern": "*.log"}, "expected_output": {"format": "markdown", "path": "./report.md"}, "constraints": ["不修改原始文件", "只处理最近7天的日志"], "completion_criteria": ["报告包含错误统计", "报告包含模块分布"], "assumptions": ["未指定时区，按本地时间处理"] }

注意：假设一定要显式写出来。Agent 默默做的假设，是后期排查问题的最大障碍。写出来，用户能看到，错了也能改。

3.2 执行规划技能：把任务拆成可执行的步骤

拿到结构化任务描述后，下一步是规划。这个技能负责把任务拆成一个个具体步骤，并标注每步用哪个技能、依赖什么、产出什么。

我踩过的一个坑是：规划太粗。比如“处理数据”算一步，结果执行时 Agent 不知道从哪下手，又得临时想，等于没规划。后来我要求规划必须细到每个步骤都能对应到一个具体技能，不能有“然后处理一下”这种模糊步骤。

规划技能的另一个要点是依赖标注。哪些步骤可以并行、哪些必须串行、哪些步骤的产出是下一步的输入，都要标清楚。这样执行时才能知道什么时候可以等，什么时候必须等。

这张表看起来简单，但它是整个工作流的骨架。有了它，执行层就不用“思考”，只管按表干活，稳定性大幅提升。

3.3 执行技能：真正干活的那一层

执行技能是具体操作的封装。每个执行技能应该是一个纯函数式的存在：给定确定的输入，产出确定的输出，不依赖外部状态，不产生副作用（或者副作用被严格限定）。

我写执行技能时有个习惯：先写校验，再写逻辑。也就是说，先想清楚“怎么判断这个技能做对了”，再去实现“怎么做”。这个顺序反过来，很容易写出“能跑但不知道对不对”的代码。

以“解析日志行”这个技能为例，我的实现顺序是：

1. 定义输入格式：一行原始日志文本。
2. 定义输出格式：包含时间戳、级别、模块、消息的结构化对象。
3. 定义校验规则：时间戳能解析、级别在枚举范围内、模块非空。
4. 实现解析逻辑。
5. 写测试用例：正常行、缺字段行、格式错误行。

import re from datetime import datetime LOG_PATTERN = re.compile( r'(?P<ts>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) ' r'\[(?P<level>\w+)\] ' r'(?P<module>[\w\.]+): ' r'(?P<msg>.+)' ) VALID_LEVELS = {"DEBUG", "INFO", "WARN", "ERROR"} def parse_log_line(line: str) -> dict: m = LOG_PATTERN.match(line.strip()) if not m: raise ValueError(f"日志行格式不匹配: {line[:50]}") result = m.groupdict() # 校验时间戳 datetime.strptime(result["ts"], "%Y-%m-%d %H:%M:%S") # 校验级别 if result["level"] not in VALID_LEVELS: raise ValueError(f"未知日志级别: {result['level']}") # 校验模块非空 if not result["module"]: raise ValueError("模块名为空") return result

这段代码不长，但包含了执行技能该有的所有要素：明确的输入输出、前置校验、失败时抛异常而不是返回 None。抛异常比返回 None 好，因为 None 会被下游当成合法值继续传递，异常会立刻中断流程，让问题暴露在发生的地方。

3.4 校验技能：别让错误悄悄溜过去

校验技能是工作流里的“质检员”。它的职责是在每个关键步骤后检查产出，不合格就拦截。

我见过太多 Agent 项目，前面干得热火朝天，最后产出一份报告，人一看全是错的。问题就出在中间没有校验，错误一路传递，越滚越大。

校验技能的设计要点是分层。我一般分三层：

• 格式校验：产出是不是符合约定的格式（JSON 能不能解析、字段全不全）。
• 逻辑校验：产出在逻辑上是否自洽（统计数字加起来对不对、引用关系是否成立）。
• 业务校验：产出是否符合业务规则（数值是否在合理范围、是否满足特定约束）。

三层校验的成本递增，但收益也递增。格式校验几乎零成本，逻辑校验需要写一些规则，业务校验需要领域知识。我的建议是：格式校验必须做，逻辑校验尽量做，业务校验按需做。

提示：校验失败时，不要只报“校验失败”，要报“哪个字段、期望什么、实际什么”。这样排查时能直接定位，不用重新跑一遍。

3.5 记录与回溯技能：让每一步都有据可查

这个技能经常被忽略，但它是工作流能否长期维护的关键。记录技能负责把每个步骤的输入、输出、耗时、状态、异常都存下来。

我一般会记录这么几类信息：

• 执行日志：什么时间、执行了哪个技能、输入是什么、输出是什么、耗时多久。
• 决策记录：Agent 在动态选择时，为什么选了这个技能而不是那个。
• 异常记录：哪里出错了、错误信息是什么、当时的状态是什么。
• 版本信息：用的哪个版本的技能定义、哪个版本的模型。

这些记录平时看着没用，一旦出问题，就是救命稻草。我经历过一次线上任务失败，靠记录发现是某个技能的定义被改过但没重新测试，五分钟定位，十分钟修复。没有记录的话，这种问题能查一整天。

记录技能的实现可以很简单，写文件、写数据库、发消息队列都行。关键是结构化，别写成一堆自由文本，不然查的时候还得再解析一遍。

4. 把技能串成工作流的完整实操

4.1 环境与依赖准备

动手之前，先把环境理清楚。我用的技术栈比较朴素，因为工作流这东西，越简单越稳。

• 运行环境：Python 3.10+，主要是看中它的类型提示和异步支持。
• 模型接入：任意支持函数调用的模型接口，我用的是通用的对话补全接口。
• 存储：本地文件系统存日志和中间产物，简单任务够用；复杂任务上 SQLite。
• 配置：YAML 文件定义技能和流程，改配置不用改代码。

目录结构我习惯这么组织：

agent_workflow/ ├── skills/ # 技能定义 │ ├── task_parse.py │ ├── plan.py │ ├── execute.py │ ├── validate.py │ └── record.py ├── flows/ # 流程定义 │ └── log_process.yaml ├── runtime/ # 运行时 │ ├── scheduler.py │ └── context.py ├── logs/ # 执行记录 └── tests/ # 测试用例

这个结构的好处是技能和流程分离。技能是通用的，流程是具体的。同一个技能可以在多个流程里复用，改流程不影响技能。

4.2 定义第一个技能：从 YAML 开始

我倾向于用 YAML 定义技能，因为可读性好，非开发人员也能看懂。一个技能定义大概长这样：

name: parse_log_line description: 解析单行日志文本为结构化对象 trigger: when: 输入为原始日志文本行 input: type: string description: 一行原始日志 output: type: object fields: - ts: string - level: string - module: string - msg: string steps: - 用正则匹配日志格式 - 提取各字段 - 校验时间戳可解析 - 校验级别在允许范围内 validation: - 时间戳格式为 YYYY-MM-DD HH:MM:SS - level 属于 [DEBUG, INFO, WARN, ERROR] - module 非空 on_failure: action: raise message: 日志行解析失败，请检查格式

这个定义里，steps是给人看的，validation是给机器执行的。实际运行时，执行层会按 steps 调用对应的代码，按 validation 做检查。

注意：YAML 里的步骤描述要具体到“能对应到一段代码”，不能写“处理一下数据”这种。我一般要求每个步骤都能映射到一个函数。

4.3 编排流程：把技能连起来

流程定义就是把技能按顺序连起来，加上分支和循环。我用的是最朴素的顺序加条件判断，没上复杂的工作流引擎，因为大多数任务用不上。

name: log_process_flow description: 处理日志文件并生成报告 steps: - skill: task_parse input: ${user_input} output: task_spec - skill: plan input: ${task_spec} output: plan - skill: read_files input: ${task_spec.target} output: raw_lines - skill: parse_log_line input: ${raw_lines} output: parsed_records loop: true - skill: filter_errors input: ${parsed_records} output: error_records - skill: group_by_module input: ${error_records} output: module_map - skill: generate_report input: ${module_map} output: report - skill: validate_report input: ${report} output: validation_result - skill: save_report input: ${report} output: saved_path

这个流程里，loop: true表示对列表里的每一项都执行一次。${}是变量引用，指向前一步的产出。整个流程读下来，逻辑一目了然。

实际运行时，调度器会按顺序执行，每步执行完做校验，校验不过就按on_failure处理。如果某步是动态选择，调度器会把候选技能列表和当前上下文交给模型，让模型选一个。

4.4 跑起来：一次完整的执行记录

我拿一批模拟日志跑了一遍，记录一下关键节点。

输入：一个包含 500 行日志的目录，日志格式统一。

第一步，任务解析。Agent 识别出这是“日志处理”类任务，目标目录是./logs，预期产出是 Markdown 报告，约束是“不修改原始文件”。这里它追问了一次：“报告需要包含哪些统计维度？”我回复“错误数、模块分布、时间趋势”。追问一次后信息够了，继续。

第二步，规划。Agent 输出了 9 个步骤，和上面流程定义基本一致。我检查了一下，没有遗漏，继续。

第三步到第五步，读取和解析。500 行日志，解析成功 498 行，2 行格式异常。异常行被记录到parse_errors.log，没有中断流程。这里校验技能起作用了：它检查了解析成功率，发现 99.6%，在可接受范围内（我设的阈值是 95%），放行。

第六步到第八步，过滤、归类、生成报告。错误行 47 条，分布在 6 个模块。报告生成后，校验技能检查了报告结构：包含三个必需章节，数字加总一致，通过。

第九步，保存。报告写入./report.md，同时执行记录写入./logs/run_20240115_143022.json。

整个流程跑了大概 40 秒，其中模型调用占了大头。如果纯脚本跑，可能 2 秒就完了，但 Agent 的价值在于它能处理格式变化、能追问、能在异常时做判断。这个 trade-off 我觉得值。

4.5 参数选择与调优经验

跑了几十次之后，我总结出几个关键参数的调优经验，都是踩坑换来的。

解析成功率阈值：我一开始设的 99%，结果稍微有点格式差异就中断。后来降到 95%，配合异常记录，既不会因为个别坏行卡死，又能保证整体质量。如果你的日志格式很规范，可以设高一点；如果来源杂，设低一点。

追问轮数上限：设成 2 轮。1 轮往往不够，3 轮用户会烦。2 轮是个平衡点，大部分情况能问清楚，问不清的就按默认值走。

校验层级：格式校验全开，逻辑校验开关键项，业务校验按任务重要性开。全开的话，小任务也会变得很重，没必要。

记录详细程度：我分三档。调试时全量记录，包括每步的完整输入输出；正常运行时只记摘要和异常；批量任务时只记最终结果和统计。全量记录很占空间，别一直开着。

5. 常见问题与排查实录

5.1 Agent 不按流程走怎么办

这是最常见的问题。表现是：明明定义了流程，Agent 却跳步、乱序、或者自己发明步骤。

原因通常有三个：一是流程定义太模糊，Agent 理解不了；二是技能描述不清楚，Agent 不知道什么时候该用；三是模型本身倾向于“自由发挥”，约束不够强。

我的解决办法是加硬约束。在调度层里，每一步执行前都检查“当前状态是否允许执行这个技能”，不允许就直接拒绝，不给模型商量的余地。同时，把流程定义写得非常具体，每个步骤的输入输出都明确，减少模型的解释空间。

还有一个技巧：在提示词里明确说“你只能从以下技能中选择，不能自己发明”。这句话看着简单，但很管用。模型有时候就是需要被明确告知边界。

5.2 技能之间传参出错怎么排查

传参错误的表现是：技能 A 产出的东西，技能 B 接不住。常见原因是格式不匹配、字段名不一致、或者 A 的产出是 B 不支持的变体。

排查思路是从后往前查。先看 B 期望什么输入，再看 A 实际产出了什么，对比差异。我一般会在每个技能的入口加一个参数校验，不匹配就直接报错，报错信息里带上期望格式和实际格式。

def validate_input(data, expected_schema): for field, field_type in expected_schema.items(): if field not in data: raise ValueError(f"缺少字段: {field}，期望类型: {field_type}") if not isinstance(data[field], field_type): raise TypeError( f"字段 {field} 类型错误: " f"期望 {field_type}, 实际 {type(data[field])}" )

这个校验函数我每个技能入口都调一次，虽然有点啰嗦，但省下的排查时间远超这点开销。

5.3 校验太严导致流程频繁中断

校验是好事，但太严会适得其反。我一开始把校验写得很死，结果稍微有点偏差就中断，任务成功率很低。

后来我改成分级处理：严重问题中断，轻微问题记录并继续。比如解析日志时，个别行格式不对，记录到异常文件，继续处理其他行；但如果解析成功率低于阈值，才中断。

分级的关键是定义清楚什么算严重。我的标准是：影响最终结果正确性的算严重，只影响完整性的算轻微。错误统计数字算错了，严重；少统计了一两条边缘日志，轻微。

5.4 常见问题速查表

5.5 几个我踩过的坑

坑一：技能定义和实现不同步。我改过技能的实现，但忘了更新 YAML 定义，结果校验规则还是旧的，跑出来的结果和预期对不上。后来我加了一个检查：启动时对比技能定义和实现，不一致就报警。

坑二：过度依赖模型做判断。我一开始让模型决定“这步做完了没”，结果它经常说“做完了”但实际没完。后来改成用明确的完成标准来判断，模型只负责执行，不负责判断完成。

坑三：记录写太多导致磁盘满。全量记录跑批量任务，一天写了 20G 日志。后来改成滚动记录，只保留最近 7 天，老记录归档压缩。

坑四：技能粒度太细。拆得太细，技能之间调用开销比干活还大。后来合并了一些简单技能，比如“读取文件”和“解析内容”合成一个，减少调用次数。

提示：技能粒度没有标准答案，我的经验是“一个技能对应一个可独立测试的单元”。如果两个技能总是一起出现、从不分开用，那它们可能就该合并。

6. 技能库的维护与演进

6.1 技能版本管理

技能是会变的。今天写的解析逻辑，明天日志格式变了就得改。改的时候怎么保证不影响正在跑的任务，是个实际问题。

我的做法是给技能加版本号，流程定义里引用具体版本。新任务用新版本，老任务继续用老版本，跑完为止。这样改技能不会影响存量任务，风险可控。

版本号我一般用语义化版本：主版本号变表示不兼容，次版本号变表示新增功能，修订号变表示修 bug。流程定义里写parse_log_line@1.2.0，明确到修订号，保证可复现。

6.2 技能复用与组合

技能库大了之后，复用就成了关键。我一般会定期整理技能库，把功能重叠的合并，把没人用的归档，把常用的标记出来。

复用还有一个技巧：把技能分成基础技能和组合技能。基础技能是最小单元，比如“读文件”“解析行”“写文件”；组合技能是基础技能的组合，比如“处理日志文件”就是“读文件+解析行+过滤+写文件”。组合技能让流程定义更简洁，基础技能保证灵活性。

6.3 从单 Agent 到多 Agent 协作

单个 Agent 跑工作流，能力有上限。任务复杂到一定程度，就需要多个 Agent 分工。我的做法是按技能域拆分 Agent：一个 Agent 负责解析类技能，一个负责生成类技能，一个负责校验类技能。

Agent 之间通过工作流调度层通信，不直接对话。调度层负责把任务分给合适的 Agent，收集结果，决定下一步。这样每个 Agent 的职责清晰，提示词可以针对性地优化，整体稳定性比一个大而全的 Agent 高。

多 Agent 的代价是复杂度上升，调试更难。我的建议是：单 Agent 能搞定就别上多 Agent。只有当单 Agent 的提示词长到难以维护、或者不同任务的技能需求冲突严重时，才考虑拆分。

6.4 持续改进的节奏

工作流不是写完就完了，得持续改进。我的节奏是：每周看一次执行记录，找出失败率高的技能和步骤；每月做一次技能库整理，合并、归档、优化；每季度做一次大版本回顾，看整体架构有没有需要调整的。

改进的依据是数据，不是感觉。执行记录里有什么技能失败率高、什么步骤耗时长、什么校验经常不过，一目了然。根据数据改，比拍脑袋改靠谱得多。

我个人在实际操作中的体会是，这套东西最大的价值不在于让 Agent 变聪明，而在于让 Agent 变可管理。聪明是模型的事，可管理是工程的事。模型会越来越聪明，但可管理这件事，得靠工作流来兜底。把技能拆清楚、把流程定明白、把校验做扎实、把记录留完整，Agent 才能真正从“玩具”变成“工具”。

最后分享一个小技巧：如果你刚开始搭这套东西，别一上来就追求完整。先挑一个最痛的任务，把它的流程跑通，跑顺了再往其他任务上扩展。我见过太多人一上来就设计大而全的框架，结果框架没搭完，热情先耗完了。小步快跑，跑通一个是一个，这才是工程化的正确打开方式。