前阵子听了一场关于 AI Agent 落地数据分析的分享。主题不算新，但讲者没怎么讲“Agent 有多聪明”，大部分时间都在讲工程细节，反而更对我胃口。趁笔记还没凉，整理一下。
背景
场景很具体：各场景的环比分析。取数、对齐口径、算同比环比、画图、写结论，一套流程重复很多次，人力投入不小。他们想用 Agent 把这条链路接过去。
讲者反复说的一句话是：Agent 的效果不只取决于模型，Skill 的工程化程度同样关键。模型负责理解和决策，Skill 负责把确定性的部分固定下来。这句话听起来像正确的废话，但后面所有设计几乎都是围绕它展开的。
Skill 不是一段提示词，更像一个项目目录
他们没把执行步骤全塞进 SKILL.md，而是拆成了几个部分：
1 | skills/ |
SKILL.md 只当索引用，不写执行逻辑。固定的 SQL、数据清洗、格式校验放到 scripts/；需要时再查的口径和案例放到 references/。这样模型不用每次都把整套知识读一遍，上下文压力小很多。
找 Skill 的方式也有意思。用户不会严格按 Skill 名字提问，同一个意思可能说成“看下这个月环比”“和上月比一下”“增长怎么样”。关键词硬匹很容易漏，他们用 embedding 做语义召回，先找候选，再让模型确认。
还有一个我很喜欢的细节：术语契约。文档、脚本、模板之间最容易各说各话，他们在 terminology.md 里定义一套占位符，比如 [SOURCE_FILE]、[TARGET_FILE]、[BASE_REPORT]，文档和代码只通过这些变量通信。变量名固定了，模型填空、脚本读取、校验器检查都有共同依据，幻觉会少很多。
执行层面是 Planner-Worker 模式。Planner 拆任务、定验收标准，Worker 执行并提交证据；Planner 不通过就带着意见重试，最多两次。两次这个上限挺关键，既不会无限循环，也不至于一次失败就放弃。
几个反直觉的点
能固化的就固化。 不要让模型每次现场生成代码。固定的取数 SQL、口径计算、格式转换都应该沉淀成脚本。现场生成成本高，而且同样的输入不一定得到同样的输出。讲者给了一个判断标准：任务越容易出错，自由度越低，用脚本锁死；任务越灵活、解法越多，自由度越高，用文字引导。
黑名单比白名单有效。 写清楚“不要做什么”，往往比写“要做什么”更能收窄模型的行为空间。比如不要自行修改口径、不要跳过数据校验、不要在缺证据时宣称完成。用 [MUST]、[MUST NOT]、[SHOULD] 标注，还能做静态校验。
输出用模板，不让模型自由发挥。 报表结构固定，模型只负责填空。图表也有硬约束：占比之和必须是 100%，图里的数字必须和表格一致，异常项必须能追溯到原始数据。这些约束放在模板和校验脚本里，而不是只写在提示词里。
三个坑
第一个坑是上下文。早期让模型一次性读所有数据，结果上下文爆炸，注意力丢失，开始编造；读取阶段一旦报错，错误信息还会继续污染上下文。他们的处理是任务上下文隔离、数据分片加载，Worker 只拿当前步骤需要的那一片。另外加了一层 Skill Bridge，把高频确定性操作、敏感信息过滤、权限控制和日志记录托管起来，尽量减少高熵信息直接进模型上下文。
第二个坑是输出格式。模型时而输出 markdown 包裹的 JSON，时而纯 JSON，中文标点、漏逗号都出现过。只靠提示词约束不够，他们在 orchestrator 里做了多层容错：先提取代码块，再修复非法字符，最后用正则和 JSON Schema 交叉校验。校验不过就退回重做，不把半成品交给下游。
第三个坑最有意思：AI 倾向于报喜。工具返回几个“成功”，模型就容易判断整个任务成功，哪怕关键指标其实没算出来。解决办法是把证据变成硬性要求。Worker 必须向 Planner 提供文件路径、关键行、校验输出；Planner 按验收标准逐项检查，不通过就带着意见重试；两次仍不通过，就明确报告失败，不粉饰。
SKILL.md 怎么写
这部分讲者给了几条实操建议，我觉得比架构图更有用：
- description 是触发器，不是摘要。用第三人称写清楚 WHAT + WHEN，覆盖用户可能用的各种说法。
- body 只写 Agent 不知道的、特定环境的信息，不重复通用概念。
- 改之前先备份，改完读一遍验证，别把触发条件或约束改丢。
最后
听完最大的感受是，Agent 落地不是“换个更聪明的模型”这么简单，而是把原本靠人记住的流程，翻译成 Skill、脚本、模板和校验规则。模型负责理解和决策，工程负责确定性和可验证性。两边各司其职，才有可能稳定地跑在真实业务里。
以上是分享笔记加上我自己的理解，具体实现细节可能因团队而异。