交流群
Agent 工程方法论
所有 Skill、MCP、工作流仅供个人学习测试，功能、计费、权限以 workbuddy.cn 官方为准。文中凡涉及 WorkBuddy 具体版本号、功能入口与配置项处，均标注「待核验（以 workbuddy.cn 官方为准）」。
本栏目不绑定任何单一 Agent 工具，讲的是可以迁移到任意 Agent 平台的通用工程方法论：怎么把一个复杂任务交给 AI 还能收得住、怎么给输出加一道关、怎么在 Prompt / Skill / MCP 之间做选型、怎么把权限压到最小、怎么让自动化跑得能看见、怎么让模板改了不炸老流程。六篇逐篇给出正文方法、可运行示例、截图计划、配套模板与引流文案。
复杂任务标准拆解模型：分阶段确认 + 断点 Checkpoint
正文：原理与分步骤方法
把一个大任务一口气丢给 Agent 跑完，常见后果有三个：长上下文导致后半程漂移、第一步的错误被后面每一步放大、跑完才发现方向错了却无法回滚。分阶段确认 + 断点 Checkpoint 就是为了把"一口气跑到底"改成"走一段、停一下、验一次"。
核心原理有两条：其一，每完成一个可交付的最小片段就主动停下，而不是把整段做完；其二，每个断点都对照事先写好的完成标准自检，不通过就回滚到最近一个可信状态，而不是带着错误继续。
复述目标与交付物：先用一句话向用户确认"我要交付什么、什么格式、给谁用"，口径不一致先停。
列出假设与疑问：把不确定的点显式列出来，能自行合理假设的标注假设，不能假设的先问。
拆成有序子任务：每个子任务写清输入、输出和完成标准，子任务之间尽量弱耦合。
逐段执行并落盘：每段产出写成中间文件或中间结论，不留在对话记忆里。
Checkpoint 自检：对照完成标准逐项过，发现越权、编造、格式错就停。
回滚或人工确认：不通过则回到上一个可信状态重跑，或把判断交回用户。
汇总与终检：全部子任务完成后统一口径、去重，再对照原始目标逐条验收。
示例
以通用示例场景"整理一份行业调研并产出一篇结构化文档"为例（非真实公司案例，仅示范拆解方式）：
| 阶段 | 子任务 | 输出物 | Checkpoint 标准 |
|---|---|---|---|
| 澄清 | 确认调研范围、读者、篇幅 | 一句话需求确认 | 用户未确认前不动笔 |
| 段1 | 收集公开资料并标注来源 | 带链接的素材清单 | 每条结论可回溯到来源，无编造数字 |
| 段2 | 提炼核心观点与结构 | 提纲 | 提纲能回答读者核心问题，无空章节 |
| 段3 | 撰写正文 | 正文初稿 | 事实可溯源、敏感处标注待核验 |
| 终检 | 对照原始目标逐条验收 | 成稿 + 自检结论 | 缺口显式列出，不掩盖 |
截图脚本（待补：需在真实客户端按此清单截图）
| 序号 | 页面/位置 | 要展示的动作或元素 | 标注说明 |
|---|---|---|---|
| 图1-1 | 新建任务对话框（待核验入口） | 输入一个多步任务，展示 Agent 先复述需求 | 框出"复述目标"这一步 |
| 图1-2 | 任务执行过程视图（待核验入口） | 展示 Agent 在第一段完成后主动停下、列出待确认点 | 框出"断点 Checkpoint"位置 |
| 图1-3 | 中间产物/记录面板（待核验入口） | 展示已落盘的中间结果与完成标准对照 | 标注"每段可回滚" |
配套模板
任务拆解模板（适配版本：待核验（以 workbuddy.cn 官方为准））：
| 字段 | 填写说明 | 示例占位 |
|---|---|---|
| 最终交付物 | 一句话写清形态、格式、读者 | 一份可直接阅读的调研文档 |
| 已知约束 | 字数、时间、不可触碰的范围 | 不涉及未公开数据 |
| 子任务 N | 动作 + 输入 + 输出 | 收集资料 → 带链接素材清单 |
| 完成标准 | 可逐条打勾的验收条件 | 每条结论可溯源 |
| 回滚点 | 出错时回到哪个中间状态 | 回到素材清单阶段 |
Checkpoint 四问清单（每个断点必过）：
这一段的输出是否满足事先写好的完成标准？
里面的事实、数字、引用是否都有来源，有没有编造？
有没有越权——做了用户没要求、或超出授权范围的事？
现在停在这里，下一段能否仅凭这份中间结果继续，不需要翻前面全部对话？
把大任务拆成"走一段验一段"，Agent 才不会一路自信地跑偏——这是把 AI 从玩具变成生产力工具的第一课。
怎么给 Agent 加校验层，降低幻觉和错误输出
正文：原理与方法
幻觉不是偶发故障，而是生成式模型的固有属性：它擅长"读起来合理"，不擅长"保证正确"。校验层的思路不是让模型一次写对，而是在它产出之后、交付或执行之前，加一道独立的判断关卡。关键在于：校验者尽量不与生产者是同一个上下文，否则它会顺着自己前面的错误继续圆。
常见校验分五类：
事实校验：数字、名称、日期、引用是否有来源、是否与来源一致。
格式校验：是否符合约定的结构、字段、长度、语言。
越权校验：是否执行了超出授权范围的动作（删、改、发消息、花钱）。
完整性校验：用户要的每一项是否都覆盖，有没有漏答。
一致性校验：前后说法是否矛盾，同一对象命名是否统一。
落地手段由轻到重：① 自检 Prompt（让模型按清单自审）；② 规则脚本（对结构化输出做确定性检查，如必填字段、数值范围）；③ 二次模型评审（换一段独立上下文挑错）；④ 人工抽检（对高风险输出保留人确认）。越危险的动作，越要往后端手段压。
示例
一段可直接复用的校验层 Prompt（放在主任务产出之后、交付之前）：
text
你现在是独立的质检员，不是刚才写这段内容的助手。
请只根据下面这份【待检内容】和【用户原始要求】作答，不要替它润色。
逐项判断并给出"通过/不通过 + 一句话理由"：
1. 事实：内容中的数字、名称、日期是否都有可核验来源？有无编造？
2. 完整：用户要求的每一条是否都被回答？列出遗漏项。
3. 一致：前后是否矛盾？同一对象命名是否统一？
4. 越权：是否出现了用户未要求、或需要人工确认才应做的动作？
5. 格式：是否符合约定结构？
最后只输出：总体结论（可交付 / 需返工）+ 必须修改的条目清单。
待检内容：{待检内容}
用户原始要求：{用户原始要求}截图脚本（待补：需在真实客户端按此清单截图）
| 序号 | 页面/位置 | 要展示的动作或元素 | 标注说明 |
|---|---|---|---|
| 图2-1 | 提示词/Skill 编辑区（待核验入口） | 展示把校验层 Prompt 作为独立一段接在主任务后 | 框出"生产"与"质检"两段分离 |
| 图2-2 | 校验结果输出（待核验入口） | 展示"需返工 + 必须修改条目清单"的返回 | 标注"不直接交付" |
| 图2-3 | 规则校验/脚本节点（待核验入口） | 展示对结构化输出做必填字段检查 | 标注"确定性检查不靠模型" |
配套模板
校验规则表（适配版本：待核验（以 workbuddy.cn 官方为准））：
| 校验类型 | 检查什么 | 不通过时怎么办 | 手段 |
|---|---|---|---|
| 事实 | 数字/名称/引用有无来源 | 删除或标注"待核验" | 二次模型评审 |
| 格式 | 必填字段、结构、长度 | 打回重写该段 | 规则脚本 |
| 越权 | 是否执行高风险动作 | 暂停并请人工确认 | 规则 + 人工 |
| 完整 | 是否逐条覆盖用户要求 | 补写遗漏项 | 自检 Prompt |
| 一致 | 前后矛盾、命名统一 | 统一口径后再交付 | 自检 Prompt |
别指望 AI 一次写对，给它配个"挑错的人"——校验层是让输出从"读着像对"变成"真的敢用"。
选型决策：原生 Prompt / Skill / MCP 分别适合什么
正文：原理与判断轴
三种实现方式不是替代关系，而是封装层级的递进：
原生 Prompt：直接在对话里写要求，用完即弃，零维护成本。
Skill（技能）：把固定流程、提示词、检查清单沉淀成可复用的封装，适合高频、纯语言推理类任务。
MCP（工具服务）：让 Agent 连到外部系统——数据库、API、文件、工具，适合高频且需要受控外部能力的场景。
选型只问两个问题：这件事会不会重复用？它要不要 Agent 之外的工具或数据？能不封装就不封装——封装带来复用，也带来维护、权限和版本成本。只有当"重复出现"或"需要受控外部能力"时，才值得升级。WorkBuddy 中三者的具体入口、能力边界与配置项以 workbuddy.cn 官方为准。
示例
对一个常见需求做选型走查（通用示例，非真实案例）：
| 需求 | 会复用吗 | 要外部能力吗 | 结论 |
|---|---|---|---|
| 把一段文字改写成小红书风格 | 高频 | 否 | 做成 Skill，固定结构与违禁词检查 |
| 临时查一次某公开资料并总结 | 低频 | 是（联网） | 临时 Prompt + 联网，不封装 |
| 每天固定从某接口拉数并出日报 | 高频 | 是 | 走 MCP/工具服务，权限与日志集中管 |
| 一次性写封邮件 | 低频 | 否 | 原生 Prompt，写完即走 |
截图脚本（待补：需在真实客户端按此清单截图）
| 序号 | 页面/位置 | 要展示的动作或元素 | 标注说明 |
|---|---|---|---|
| 图3-1 | 对话新建页（待核验入口） | 展示一次性 Prompt 直接对话完成 | 标注"原生 Prompt：零封装" |
| 图3-2 | Skill 列表/编辑页（待核验入口） | 展示一个已沉淀技能的固定流程与检查项 | 标注"Skill：高频纯推理" |
| 图3-3 | MCP/工具配置页（待核验入口） | 展示一个外部工具的接入与权限范围 | 标注"MCP：受控外部能力" |
配套模板
选型决策检查表（适配版本：待核验（以 workbuddy.cn 官方为准））：
这件事预计一周内会重复出现 3 次以上吗？否 → 先用原生 Prompt。
它需要读写外部系统/数据，还是纯语言推理？纯推理 → 不要急着接工具。
固定格式、固定检查清单已经稳定下来了吗？是 → 考虑沉淀为 Skill。
外部能力是否需要集中管控权限、密钥与日志？是 → 走 MCP/工具服务。
如果现在封装，两周后它会不会就不再用了？会 → 别封装。
能一句话解决的事别做成工程——Prompt、Skill、MCP 不是越高级越好，是越合身越好。
权限最小化设计思路（代理自动化安全核心）
正文：原理与方法
人操作电脑时手会停、会犹豫；Agent 是自主按目标连续调用工具的，权限给多大，出错时的爆炸半径就有多大。最小权限不是一句口号，而是一组可执行的设计约束：
默认拒绝：不预先开放权限，用到哪个申请哪个，用完收回。
最小够用：只读就不给写，单日只跑这个动作就不开其它动作。
按职责拆分身份：不同任务用不同的工具账号/密钥，一个泄露不波及全局。
可吊销、有期限：凭证能立刻停用，尽量设有效期。
密钥不落盘、不进提示词：令牌只从环境变量/密钥管理处读取，禁止写进 Prompt、Skill 文本或聊天记录。
判断标准很简单：问一句"这个 Agent 被错误指令或被诱导时，最多能造成多大损失？"把这个损失压到可接受范围，就是权限设计到位了。
示例
一张最小权限矩阵示范（资源 × 动作，√=允许，×=拒绝；通用示例）：
| 资源 \ 动作 | 读取 | 写入 | 删除 | 对外发送 |
|---|---|---|---|---|
| 公开资料/网页 | √ | × | × | × |
| 工作目录草稿 | √ | √ | ×（需人工确认） | × |
| 线上正式文档 | √ | ×（需人工确认） | × | × |
| 消息/邮箱/支付 | × | × | × | ×（默认关闭） |
截图脚本（待补：需在真实客户端按此清单截图）
| 序号 | 页面/位置 | 要展示的动作或元素 | 标注说明 |
|---|---|---|---|
| 图4-1 | 工具/授权管理页（待核验入口） | 展示只勾选了"读取"未勾选"写入/删除" | 框出最小够用原则 |
| 图4-2 | 凭证/密钥配置处（待核验入口） | 展示从密钥位填入，而非写在提示词里 | 标注"密钥禁止明文写进 Prompt" |
| 图4-3 | 高风险动作拦截提示（待核验入口） | 展示删除/发送前弹人工确认 | 标注"危险动作要人点头" |
配套模板
权限矩阵模板（适配版本：待核验（以 workbuddy.cn 官方为准））：
| 资源 | 读 | 写 | 删 | 对外发送 |
|---|---|---|---|---|
| （填资源名） | √/× | √/×/确认 | √/×/确认 | √/×/确认 |
密钥管理红线：
text
# 正确：只引用，不写真值
API_TOKEN = ${WORKBUDDY_API_TOKEN} # 从环境变量/密钥管理读取
# 占位符示例（禁止替换成真实值后提交）
# YOUR_API_TOKEN_HERE
# 红线：
# 1. 密钥/令牌一律不得写进 Prompt、Skill 文本、文档或聊天记录
# 2. 禁止明文存储；提交与分享前检查是否误带
# 3. 一个任务一个凭证，泄露后可单独吊销给 Agent 的权限，就像给陌生人一把钥匙——只开他今天要用的那扇门，其余门连钥匙都别配。
自动化系统的可观测性：日志、结果自检、告警设计
正文：原理与方法
自动化一旦半夜跑错、且没人知道，小错就会滚成大事故。可观测性回答三个问题：它做过什么（日志）、它做得对不对（结果自检）、出了问题谁知道（告警）。
结构化日志：每条日志带时间、任务名、步骤、输入摘要、结果、耗时，固定字段便于排查，不写散文。
结果自检：每次运行后自动跑一遍验收（字段齐不齐、数值在不在合理区间、产物是否生成），把"成功/失败/可疑"写进日志。
告警分级：失败即重试的不打扰；连续失败、越权尝试、产物为空这类必须立刻叫人。
原则：能自动判的不靠人盯，必须人知道的绝不静默。日志里不要记录密钥、令牌和敏感个人数据。
示例
一条结构化日志的样子（通用示例，字段名按实际工具调整）：
json
{
"ts": "2026-10-31T08:00:00+08:00",
"task": "daily_report",
"step": "fetch_and_summarize",
"input_summary": "date=2026-10-30, source=public",
"result": "success",
"self_check": {
"output_exists": true,
"required_fields_present": true,
"value_in_range": true,
"note": ""
},
"duration_ms": 42000,
"alert_level": "none"
}截图脚本（待补：需在真实客户端按此清单截图）
| 序号 | 页面/位置 | 要展示的动作或元素 | 标注说明 |
|---|---|---|---|
| 图5-1 | 运行历史/日志页（待核验入口） | 展示一次任务的步骤与结果记录 | 框出结构化字段 |
| 图5-2 | 自检结果视图（待核验入口） | 展示"成功/可疑/失败"标签 | 标注"不靠人盯，自动判" |
| 图5-3 | 告警通知（待核验入口） | 展示一次连续失败后的提醒 | 标注"高等级不静默" |
配套模板
可观测性指标表（适配版本：待核验（以 workbuddy.cn 官方为准））：
| 指标 | 看什么 | 正常标准 | 告警条件 |
|---|---|---|---|
| 成功率 | 任务成功次数 / 总次数 | 稳定在预期区间 | 连续 N 次失败 |
| 产物完整性 | 必填字段/文件是否生成 | 齐全 | 产物为空或缺字段 |
| 越权尝试 | 是否请求超出授权的动作 | 无 | 出现即告警并暂停 |
| 耗时 | 单步/整体运行时长 | 历史基线内 | 远超基线（可能卡死） |
自动化最怕的不是出错，是出错了没人知道——把日志、自检、告警配齐，半夜睡觉才踏实。
长期维护策略：模板版本化、变更兼容管理
正文：原理与方法
Skill、Prompt 模板、MCP 配置一旦沉淀下来，就会被多个任务反复引用。改一版模板，最容易踩的坑是：新任务用了新格式，老任务还按旧格式跑，悄悄对不上。版本化就是给每份模板一个可追溯的身份，并约束"改它的时候不炸到老用户"。
语义化版本号：主版本.次版本.补丁（如 1.2.0）。改兼容的小修是补丁，加可选能力是次版本，改了输入输出约定是主版本。
向后兼容优先：新增字段做成可选，不改老字段含义；必须破坏兼容时升主版本并保留旧版一段时间。
变更日志：每次改动写清楚改了什么、影响谁、怎么迁移。
灰度与回滚：新模板先在一个任务上验证，出问题能一键切回旧版。
示例
一段变更日志示范（通用示例）：
text
## v1.2.0（次版本，向后兼容）
- 新增：输出可选带"自检结论"字段，缺省时按旧行为
- 修复：日期格式统一为 YYYY-MM-DD
- 影响：无强制迁移；老任务可不改直接跑
## v2.0.0（主版本，破坏兼容）
- 变更：必填字段由"标题"改为"标题+读者"
- 影响：老任务需补"读者"字段，否则校验不通过
- 迁移：保留 v1.x 一个版本周期后下线截图脚本（待补：需在真实客户端按此清单截图）
| 序号 | 页面/位置 | 要展示的动作或元素 | 标注说明 |
|---|---|---|---|
| 图6-1 | Skill/模板详情页（待核验入口） | 展示版本号与更新时间 | 框出版本号 |
| 图6-2 | 历史版本/回滚入口（待核验入口） | 展示可查看旧版、可切回 | 标注"改坏了能退" |
| 图6-3 | 变更说明处（待核验入口） | 展示本次改动与迁移提示 | 标注"破坏性变更要写清" |
配套模板
版本管理模板（适配版本：待核验（以 workbuddy.cn 官方为准））：
| 版本号 | 日期 | 改了什么 | 是否破坏兼容 | 迁移/回滚方式 |
|---|---|---|---|---|
| 1.0.0 | YYYY-MM-DD | 首版 | — | — |
| 1.1.0 | YYYY-MM-DD | 新增可选字段 | 否 | 无需迁移 |
| 2.0.0 | YYYY-MM-DD | 必填字段变更 | 是 | 补字段；可回退 1.x |
模板不是写完就完事——给它版本号、写清变更，老任务才不会被一次"顺手优化"悄悄带歪。
本栏目为通用 Agent 工程方法论，可迁移到任意 Agent 工具；文中 WorkBuddy 具体功能、入口与配置均以 workbuddy.cn 官方为准，截图待在真实客户端按各篇清单补齐。
（注：部分内容由豆包工作 AI 生成）