harness-engineering-lifecycle

Harness 工程生命周期

将经过验证的仓库本地契约发展为通用、高性能的声明式 Harness 系统，然后安全地在生产者与消费者的仓库边界之间进行自我试用。只有在目标仓库已有 steward.yaml 契约且至少有一项 H2 冒烟验证后，才从此处开始；在此之前请使用 mcp-harness-repo-maintainer。

适用场景

• 将自定义验证脚本发展为集中式 Linter 引擎。
• 为大型多包仓库扩展 steward CLI 功能。
• 针对相邻仓库测试本地 CLI／Harness 构建，以发现路径解析崩溃或集成摩擦。
• 将反复出现的本地基准测试／探测结果转化为可复用的 Harness 功能。

不适用场景

• 首次采用 steward.yaml，或在单个仓库中进行首次快速探测——请使用 mcp-harness-repo-maintainer。
• 创建 Skill、更新注册表或打包 Marketplace——请使用 skill-authoring-lifecycle 或 plugin-marketplace-setup。
• 在尚无冷启动契约时进行特定于产品的诊断——先在目标仓库中添加有界操作、探测和场景。

第 1 部分：级联 Agent 表面（架构与通用化）

在将 Harness 扩展到单个本地契约之外时，请遵循级联 Agent 表面指南。当仓库工作流跨越多个包、适配器或使用方时，严格区分工具与 Skill 可能行不通。应通过与领域无关的抽象将它们连接起来：

1. 第 0 层（嵌入式 Agent 表面）：目标应用或引擎必须通过显式钩子（例如 RPC 或内存探针）原生公开其内部状态。不要依赖脆弱的 UI 抓取或黑盒测试。
2. 第 1 层（协议适配器）：构建通用 MCP 服务或协议适配器，以连接第 0 层。这些工具提供原始可见性和操控能力（例如截屏、读取内存），但不得包含任何业务逻辑。
3. 第 2 层（编排器）：构建专用 Harness CLI，使用自己的自动化／脚本将多个第 1 层操作串联起来。编排器的首要任务是快速反馈循环：必须输出结构化的诊断 JSON，以准确定位跨边界故障。
4. 第 3 层（AI 封装层）：按照 agentskills.io 规范，Skill 可以也应该包含轻量封装工具（脚本）。Skill 充当 AI 的大脑：教会 AI 如何触发第 2 层、解读其复杂的 JSON 启发式结果，并安全地执行特定领域的恢复工具。

通用化原则

1. **将传输与引擎解耦：**命令接口（CLI）和 JSON-RPC（MCP）都只是轻量封装。所有逻辑都放在可复用的核心包中。
2. **声明式配置：**使用配置文件（如 steward.yaml）指定：
   • **品牌信息：**Harness 的名称和描述。
   • **操作：**带类型且有界的仓库本地命令，并定义其影响、限制、输出和证据策略。
   • **文档格：**将标签映射到特定文档文件的映射关系。
3. **剪枝遍历：**未经剪枝就对文件进行递归遍历（list(recursive: true)）是禁止的；应尽早排除标准构建目录／VCS 文件夹。
4. **通用检查：**不要硬编码 Linter。应使用参数化的声明式引擎（例如 disallowed-substrings）。

第 2 部分：跨仓库修复（测试）

修改测试框架（生产方）时，必须针对依赖它的下游项目（使用方）进行验证。

1. 建立使用方基线： 定位使用方仓库（例如 ../<consumer-repo-name>）。运行其测试，确认初始状态通过。暂时不要修改它。
2. 部署本地生产方： 构建并安装测试框架的本地开发版本。
3. 记录采用过程中的阻碍： 使用本地生产方构建版本运行使用方的验证套件。在便笺中记录路径崩溃或脆弱规则。
4. 核心修复： 在生产方代码库中修复根本原因。让修复具有通用性；不要编写仅适用于使用方的变通方案。
5. 修复使用方配置： 更新使用方仓库，以便利用新的通用功能（例如更新其 steward.yaml）。
6. 双重验证： 确认使用方套件和生产方套件均通过。
7. 沉淀持久知识： 使用 repository-governance-lifecycle 技能将经验提炼到 ADR 或 FAQ 中。

绕道停止规则： 如果本地生产方构建版本的安装、激活或接入配置连续失败两次，请停止还原，记录阻碍；在可行时使用使用方的原生门禁或可移植回退方案，然后返回原始验收检查。不要根据同一次绕道推广通用测试框架功能；先记录观察结果或未知情况。

生产方／使用方证明材料

推广通用测试框架变更前，必须收集两端的证明材料。

一方	所需材料	用途
生产方	经测试或验证器输出证明的已变更架构／操作／规则	证明通用功能在源测试框架中有效。
使用方	更新后的 steward.yaml 或场景清单	证明采用该功能不需要本地路径技巧。
使用方	基准测试摘要或真实的 durability_blocked 输出	证明全新的 Agent 能看出哪些内容已获证明、哪些内容受阻。
双方	验证命令和版本	使跨仓库故障可复现。
文档	边界发生变化时更新 ADR／FAQ	避免后续 Agent 再次发现相同的分歧。

如果唯一消费者只是通过私有路径变通方案解决问题，不要将本地修复推广到通用测试框架。应先保留为本地修复，直到该契约、架构或规则形成可复用模式，并且至少有一个留出验证或后续 Agent 重复验证证明它可以迁移。

安装

npx skills add arenukvern/skill_steward --skill harness-engineering-lifecycle

来源

请参阅 references/sources.md。