Agent 插件如何走向工程化：Better Harness 的五个实践
内容提要
本文探讨如何将Agent插件能力从“写出来能用”提升为可验证、可维护的软件资产，核心在于五个工程环节：规格驱动定义契约、上下文编排组织知识、确定性验证守住边界、行为评测确认执行、证据闭环证明效果。通过Better Harness实践，强调用证据链支撑结论，确保插件可持续演进。
延伸解读
规格驱动的边界
规格驱动强调在实现前定义可验证的契约，但验收条件过细可能导致AI逐字匹配文本而非验证真实行为，降低测试稳定性。因此，规格应约束可观察行为，而非锁死具体措辞。实践中，Better Harness通过稳定编号（如AC-01）关联实现、测试和评审证据，确保规格真正指导开发，而非流于形式。
上下文编排的工程化
上下文编排不仅是知识拆分，更需保证知识路由有效。Better Harness通过将Markdown引用作为事实来源，使文档结构可验证，避免重构后路径失效。这体现了上下文工程的核心：让正确知识在正确时机通过有效路径进入上下文，而非简单增加阅读量。
确定性验证与模型分工
确定性验证用于守住可判定边界，如检查副作用，而模型负责理解与规划。Better Harness对--help路径的测试验证了入口的允许行为，而非文案内容。这种分工避免了模型猜测，将边界约束自动化，确保插件行为稳定可回归。
证据闭环防止假使用
行为评测确认执行，证据闭环证明效果。Better Harness通过三组对照（无Skill/当前/候选）评估结果，并警惕“已路由但未执行”的假使用。证据链遵循“已存在→已接入→已执行→有效果证据”，强调结论必须与证据匹配，防止未经验证的Skill演进。
Q&A
Agent插件工程化的核心目标是什么？
核心目标是将插件中的能力当作软件资产来维护，通过规格约束行为、上下文编排知识、确定性验证边界、行为评测确认执行、证据闭环判断效果，使插件从“写出来能用”走向“可验证、可维护、可持续演进”。
Better Harness在规格驱动实践中，规格需要回答哪些问题？
规格需要回答：什么请求应该触发，哪些相似请求不应该触发；需要读取什么信息，允许调用哪些工具；哪些行为明确禁止；证据不足时应该停止、降级还是交回给人；最终用什么证据证明实现符合预期。
在上下文编排中，Better Harness如何保证知识路由的有效性？
通过三个方面：一是将Markdown引用作为事实来源，使文档移动或链接断裂时能被机器发现；二是将知识按需渐进式披露，入口保持短小，详细判断放入references，稳定逻辑放入scripts，模板放入assets；三是确保引用路径在重构后仍然有效，避免文件存在但Agent找不到。
确定性验证在Better Harness中主要处理哪些问题？
确定性验证用于处理边界明确、结果可判定的问题，如元数据、目录结构、断链、数据格式、废弃名称和权限声明。它通过三层机制守住边界，例如测试--help路径时验证不应有副作用，确保入口被允许做什么、不允许做什么。
行为评测中，Better Harness如何设计测试场景？
Better Harness准备三类场景：应该触发的正例、不应该触发的负例、措辞相似但意图不同的边界用例。执行时重点观察四件事，并重复运行同一场景以验证稳定性。此外，还会通过真实Qoder CLI和插件加载链路做端到端验证，从中立目录发起测试以避免借用当前仓库配置。
什么是“routed-but-not-applied”？如何避免？
“routed-but-not-applied”指Agent找到了Skill并读取了SKILL.md，但没有真正执行其中要求的步骤。避免方法是建立证据链，判断Skill是否已存在、已接入、已执行、有效果证据，并遵循“证据走到哪一步，结论就只能说到哪一步”的原则。
证据闭环中，Better Harness如何设计对照实验？
在任务、模型、工具、权限和测试环境保持一致时，进行三组对照：无Skill、当前版本Skill、候选版本Skill。评测不只看最终成功率，还要观察关键步骤是否执行、验证是否完整、时间与Token成本，以及有没有额外副作用。
