build-agent

构建 Agent

把业主每周都会做的事情，变成他们可以直接按名称调用的能力。

这样插件就不必预先内置每个行业的工作流。没有任何目录能覆盖化粪池承包商的许可证例行流程，或保险代理机构的承运商佣金对账。这些业主自己可以构建它们。

第一步：观察实际操作，或听他们描述

有两种起点，其中第一种好得多。

最佳方式：他们刚刚就在这段对话中完成过。 如果业主已经带你完整走过这项任务，比如调取了文件、做出了决定、还纠正过你两次，那么这份对话记录就是规格说明。直接提取它，而不是重新访谈。业主做出的纠正最有价值，因为它们编码了业主自己未必会想到要说明的判断。

否则：请他们描述。 请他们具体讲讲上一次做这件事的过程。真实的细节远胜于抽象的描述。"上周二我调出承运商文件，和我们已登记的订单做了比对，然后追查了六处差异"，比"我对账佣金"能告诉你多得多的信息。

如需在不进行审问式访谈的情况下获得完整信息，请阅读 reference/capture.md。

第二步：区分变化的部分与固定的部分

这是本步骤的核心要领。如果一项技能硬编码了上周二的具体细节，那它只能在上周二有效。

对于任务的每个部分，请判断：

• 固定：流程顺序、数据来源、输出格式、规则
• 可变：日期、名称、金额、所用文件、客户
• 判断：由业主做决定的部分，这些部分将成为审批关口

业主在演示过程中做出的纠正通常标示出了判断点。当有人说"不，不是那个，我们跳过低于 50 美元的项目"，这就是一条规则。当他们说"嗯，要看情况"，这就是审批关口。

第三步：找出审批关口

任何发送、花费、发布或删除的步骤都需要设置关口。业主犹豫过的每个步骤同样需要。

但不要对所有环节都设关口。一项每次都要求许可九次的技能，还不如手动操作。只对重要和模糊的环节设置关口，其余环节让其自动运行。

如需了解关口应设在何处以及如何措辞，请阅读 reference/skill_authoring.md。

第四步：编写技能

产出一项真正的技能，其结构与本插件中的其他技能保持一致：包含带有 frontmatter 和编号步骤的 SKILL.md；如果细节足够多，再加上 reference/ 文件夹。

它必须满足的要求与所有已发布的技能相同：

• 名称与文件夹名一致，使用小写字母加连字符
• 描述需说明它做什么以及何时触发，使用第三人称
• 在连接器缺失时提供真实可行的备选方案
• 对任何重要操作设置审批关口
• 绝不编造数字；缺失的数据应明确报告为缺失

请使用业主的术语来编写，而不是通用的商业语言。 如果他们称之为"承运商文件"，技能中就写承运商文件。充满陌生词汇的技能，业主不会信任它在无人值守的情况下运行。

第五步：用真实案例测试，然后再让业主依赖它

用业主已经知道答案的案例来运行新技能，最好正是他们亲自演示过的那个案例。把输出结果与他们手工得出的结果并排展示。

这一步决定了该技能是否会被真正使用。业主看到它复现了已知正确的结果后，才会去安排它定时运行。如果没有看到，他们就会继续手动运行并每次都要核对，那就毫无节省可言。

如果结果不一致，就修改技能并重新运行。不要让业主接受一个接近但不准确的结果。

第六步：注册并设定运行节奏

将其添加到 smb-router，使日常用语的请求能够路由到它，并记录业主实际使用的触发短语。

如果这是一项周期性任务，主动提出为其设置定时运行。定时运行正是把"一个我可以运行的技能"变成"无需我操心、自动发生的事情"的关键，而这正是业主想要的结果。

第 7 步：经批准后分享

询问是否要与团队分享。说明分享意味着什么：谁能获得它、它能访问哪些数据，以及它在无人值守时能做什么。

当 Skill 会发送、花费或写入内容时，要明确说明风险。 如果一个 Skill 会给客户发邮件，而运行它的人并非其创建者，也不了解其前提假设，这就是实际存在的隐患。对于会发送任何内容的共享 Skill，建议仅允许生成草稿。

不要做的事

• 不要就用户刚刚演示过的任务重新访谈。 演示过程记录就是规格说明。
• 不要把示例硬编码进去。 名称、日期和金额会变化；流程顺序不会变。
• 不要为每一步都设置审批关卡。 九次审批比手动完成还糟糕。
• 不要跳过测试运行。 未经测试的 Skill 会永远需要人工检查，那就等于什么都没节省。
• 不要使用泛泛的商业术语来写。 要用用户自己的语言，否则他们不会信任它。
• 不要构建在没有审批关卡的情况下发送或花费资金的 Skill。 无论所有者提出什么要求，都绝对不要这样做。

构建之后

所有者现在拥有一个有名称的 Skill，可以手动触发或定时运行。如果新 Skill 调用了一个尚未连接的工具，"连接我的 ERP"（build-connector）就是自然的下一步，它能把缺失的系统变成可用的数据源。另外可以考虑的相关选项包括："简报我"，用于把新输出纳入每日概览；以及"周一简报"，用于让该 Skill 为周报提供数据。最多提供三个建议，并跳过所有者在本次会话中已经拒绝过的建议。

参考文件

• reference/capture.md：在不进行盘问的情况下全面掌握任务
• reference/skill_authoring.md：结构、前置元数据，以及审批关卡应放置的位置
• reference/gotchas.md：导致 Skill 无人使用的各种失败模式