mcp-harness-repo-maintainer

操作契约与 Harness 仓库维护者

构建和维护仓库本地的操作契约与 Harness，让 Agent 在其中执行，让人类在其中引导。历史上的 mcp- 名称仍予保留，因为许多采用者是通过 MCP 工作接触到它的，但此技能并非仅限于 MCP。对于通用应用、库、工具、插件或元仓库的维护基线，请先使用 repo-quality-system-lifecycle；仅当涉及类型化操作、探针、基准测试或 CLI/MCP 一致性时，才使用此技能。

核心原则（操作契约与 Harness 仓库）

MCP 和 CLI 是轻量接口——供 Agent 和 CI 使用的 API。 Core 包含真正的逻辑、架构和注册表。适配器解析线协议（argv、MCP JSON-RPC），并立即委托处理。

Agents / CI  →  CLI ──┐
                      ├──► Core (logic, contracts, tests)
Agents / chat →  MCP ──┘

完整分层：core-and-interfaces.md。**一致性：**每个 MCP 工具都必须调用与其 CLI 对应项相同的 Core 入口点。

**渐进式自动化（Agent 驱动的工作流）：**Harness 应让 Agent 能将反复出现的阻碍转化为经过审查、持久可靠的能力。如果 Agent 发现复杂的修复方案或命令序列，应记录一个未知案例或类型化操作候选项，并注明负责人、风险类别、输入、输出、效果、来源和验证方式。对 steward.yaml 的永久更改必须经过审查，并以差异形式呈现且通过验证；不要教 Agent 从 MCP 永久保存原始 bash。

**目标优先的采用方式：**原始用户目标仍是验收标准。修复工具、安装、封装、操作候选项、评估和重构都只是绕行，除非它们能直接解决该目标或保留可复用经验。两次修复或设置尝试失败后，停止恢复工具；如可行，改用类型原生命令或可移植的回退方案，记录遇到的阻碍，然后回到原任务；不要从同一次绕行中提升能力。

**产品实验归属：**如果目标涉及视觉质量、着色器行为、加载器正确性、渲染器吞吐量或性能，高吞吐量实验运行器和判定依据应由产品仓库负责。产品循环生成捕获数据/指标后，Steward 可以验证或总结 experiment-campaign-summary/v1 工件。除非产品实验明确指出发生变化或得到直接验证的表面，否则不要将 Steward 操作、基准测试或 MCP 工具提升为产品加速手段。

**提升之前先质疑：**只有在较小层级都无法解决时，缺少的能力才算 Harness 缺口。首先判断修复是否应放在原生命令、错误消息、FAQ、文档索引、公共 API、架构/代码生成中，或通过删除/合并解决。只有当 Steward 操作、MCP 工具或基准测试能改进真实的验证路径，并且提供可证伪条件时，才予以提升。

**接口的渐进式简化：**当归属、验证、效果、迭代节奏或受众出现分歧时，拆分 Core 入口点。当用户或 CI 的意图仍为单一目标时，精简 CLI/MCP/帮助界面；但要保留结构化的子项结果，避免封装层抹平验证、效果或非声明内容。

核心信念与文化

1. 能力缺失 → 可能存在 Harness 缺口 — Agent 失败时，应思考哪些内容不够清晰可见或可强制执行，然后选择最小的实用层级：原生命令、错误消息、文档/FAQ、架构、代码检查器、技能、操作或删除。对于接口形态，遵循渐进式简化：当验证、效果或负责人出现分歧时拆分内部实现；当用户意图仍为单一目标且子项结果保持结构化时，精简 CLI/MCP/帮助封装层。
2. 设计存在歧义 → 决策检查点 — 编写不同方案的代码前，使用 repository-governance-lifecycle；达成一致后，记录一份已采纳的 ADR。
3. 机械化强制执行 — 使用代码检查器、验证命令和边界处的架构验证；错误消息应指导 Agent 如何修复。使用结构化解析（YAML、JSON 或 AST）。
4. 渐进式披露 — 路由器 → ADR / DESIGN_FAQ（原因）→ DX_FAQ（方法）→ 技能（流程）→ 代码（行为的 SSOT）。

要构建的 Harness 层

Human intent (prompt, plan, review)
        │
        ▼
┌───────────────────┐
│ Skills + AGENTS   │  Map & procedures (when to do what)
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ CLI               │  doctor, exec, validate, contracts (deterministic)
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ MCP server        │  fmt_* / tools for chat agents (same schemas)
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ App / runtime     │  Legible UI, logs, metrics per worktree (optional)
└───────────────────┘

专家分工（选择一个主责专家）

如果仓库属于 harness 或操作契约类型，按主要产物分工。对于更广泛的应用／库／工具分类，请使用 repo-quality-system-lifecycle。

专家视角	仓库示例	负责范围	不负责范围
插件／MCP	<plugin_repo>	plugin/mcp.json、工具前缀、初始化实用工具	Harness 脚本、视觉对比
库	<library_repo>	平台包／模块、适配器	可发布的插件树、内部试用应用
Harness／CLI	<harness_repo>	Harness 引擎、应用注册表、fixture lint	MCP 服务二进制文件、市场清单
D — 视觉辅助模块	<visual_sidecar>	配置文件、比较／解构 CLI	VM／MCP、动态注册表
元治理	skill_steward	skills/、plugins/、验证器 CLI、文档	产品 MCP、领域工具
F — 安全／运维	所有远程服务	OAuth 网关、令牌中介	功能代码

通用维护者主干（适用于所有架构类型）

1. 章程与架构类型 — docs/NORTH_STAR.mdx（或根目录指引）；AGENTS.md 仅作索引。
2. 行为单一事实来源 — 代码与架构；文档说明原因和方法。
3. 适配器轻薄，核心厚实 — 在核心中实现一次；CLI 与 MCP 仅作封装。
4. 机械化门禁 — 合并前执行契约检查／validate 命令／单元测试。
5. 计划清理 — 将内容提取到 ADR／FAQ／代码／技能中，然后删除计划文件。
6. 版本信息准确 — 使用单一 VERSION 或 release-please 清单。
7. 分发与通用翻译 — 按渠道（npx skills、git 市场）记录。避免被专有生态锁定。确保 CLI 工具可将治理配置原生编译为上游 IDE 格式（例如，由 steward bundle 生成 .cursor/rules 和 .clinerules）。

工作流：添加 Agent 优先的能力

1. 明确意图 — 用一句话描述结果，并提供验收检查。
2. 执行怀疑者／代际检查 — 是否反复出现？能否由更底层的层解决？删除或合并代码能否降低维护负担？什么证伪条件可以防止工具循环偏离？
3. 选择接口
   • CI／脚本／门禁 → 优先使用 CLI
   • 对话式调试循环 → 使用 MCP 工具（复用 CLI 核心）
   • 一次性指导 → 使用 skills/ 中的 技能
   • 事件约束 → 使用 插件钩子
4. 让行为清晰可读 — 提供 JSON 架构、--json 输出、稳定的错误代码、操作效果、限制和脱敏策略；记录在 DX_FAQ 中。
5. 说明原因 — 使用 ADR 或 DESIGN_FAQ 问答。
6. 接入索引 — 在 AGENTS.md／docs_map 中添加条目。
7. 验证 — 执行 pnpm run validate 或项目契约测试。
8. 与人类协作 — PR 中说明 Harness 变更。

冷启动本地 Harness 验证循环

在声称仓库已准备好用于 Harness，或诊断仓库特定症状之前，先运行此循环。新仓库尚无有意义的症状目录；首先要验证 Agent 能否发现并安全执行已声明的契约。

可移植的 Steward 调用方式

只有在安装已发布的 CLI，或将本地克隆激活为全局命令后，才能使用 steward <command>。不要将绝对本地路径、私有 SDK 路径或同级检出路径作为采用指南。

建议顺序：

1. 已发布的用户或 CI 路径：运行 curl -fsSL https://raw.githubusercontent.com/Arenukvern/skill_steward/main/install.sh | bash，然后运行 steward <command>。
2. 从 Skill Steward 克隆运行的 Dart 维护者路径：cd packages/steward_cli && dart run :steward <command>。
3. 本地克隆全局激活：运行 dart pub global activate --source path packages/steward_cli，然后运行 steward <command>。

原始的 dart --packages=... bin/steward.dart 命令仅用于说明本地来源。如需提供这些命令作为依据，请同时附上可移植的命令块，并注明机器专属路径不可直接复制。

1. 声明一份小型契约 — 添加或更新 steward.yaml，包含一个快速安全操作。第一个操作应检查状态，而不是对其进行修改。

2. 公开该操作 — 只有通过快速策略的操作才放在 probes.quick.actions 下：default_policy: auto、无需确认、不使用 shell、不涉及网络、密钥或破坏性影响、不修改仓库、不使用 fs_write。

3. 添加场景清单 — 将已提交的场景放在 steward/scenarios/*.yaml 下；在场景证明能够导航或诊断问题之前，使用 contract-status-smoke 这类精确名称。

4. 运行验证循环：

   steward doctor --json
   steward schema check-outputs --json
   steward schema drift --json
   steward actions list --json
   steward action inspect <action-id> --json
   steward probe --profile quick --json
   steward benchmark --scenario <scenario-id> --strict --output .steward/benchmark-summaries/<scenario-id>.json --json
   

5. 如实解读 — doctor/actions list 证明已发现相关内容；schema check-outputs 可捕获机器可读输出漂移；schema drift 可捕获生成的契约/架构漂移；action inspect 证明可执行边界；probe 证明首次安全观察；只有 benchmark 返回 result: "pass" 时，才证明执行具有持久性。当严格基准测试输入被修改或处于未跟踪状态时，durability_blocked 是如实的受阻证据，但不属于 H2 证明。

   • 如果新鲜的控制台 JSON 受到阻止，请将其通过管道传递给 steward blocked explain --stdin --json，以选择修复配置、捕获未知用例或重新运行同一基准测试。只有针对现有持久化摘要时，才使用 steward blocked explain --input <result.json> --json。
   • 将持久化的基准测试摘要视为针对其所注明提交和输入的机器证据。将仅在控制台显示的 JSON 视为会话证据，除非使用 --output 重新运行。当前账本或重运行路径决定历史摘要是否仍是当前证明。
   • 对于具名输入，首先将基准测试通过视为本地或仓库自有的证明。只有当源可获取、目标提交是已解析的 SHA、命令具有可移植性，并且保留的产物带有 CI 产物名称或哈希值时，才能将其视为公开的可复现性证明。
   • 先通过对应的责任界面处理无效的 steward.yaml、声明的输入处于脏状态、架构/输出漂移或原生启动失败，再考虑基于同一绕行过程添加新操作、基准测试场景、PDSA 说明或证据包。

6. 保护本地状态 — 执行前，严格基准测试输入必须已跟踪且干净：steward.yaml、基于文件的场景清单，以及基准测试读取的任何已声明操作输入。.steward/benchmark-summaries/*.json 等本地运行输出、观察记录、未知用例和操作候选项应保留在本地，除非审查有意提升某个已脱敏的产物。如果仓库中有必须保留的临时脏文件，请写明禁止触碰该文件的例外，并将其排除在操作输入之外。受保护的本地状态不会阻止基准测试，除非它被声明为契约或场景输入。

7. 基于证据逐步扩展 — 如果探测暴露了未知故障，请先捕获未知用例。只有在负责人、影响、限制、脱敏方式、验证命令和基准测试证据均已明确后，才提升类型化操作候选项。不要提升发现它们的同一次运行中产生的诊断信息。

   • 将证据提升到文档中时，使用 docs/core/evidence-artifacts.mdx 中的 status、evidence_type、claim_tested、proof_level、limitations、non_claims、next_disposition 和 current_status_pointer 信封。不要将原始日志、密钥或私密关系记忆作为证据保留。

原生确定性门禁晋级

优先采用有用的原生门禁，而不是只让 Steward 负责记分。当现有的确定性脚本、测试或验证命令满足以下条件时，仓库可以将其晋级为 Steward action：

• 对当前状态有正向证明
• 有能够捕获该类回归的反例测试或 fixture
• 明确记录负责人、风险类别、影响、限制和脱敏策略
• 有严格的基准测试或评估，使该能力易于发现
• 有留出基准测试或未来 Agent 的重复验证，证明能力可迁移
• 明确声明不涉及产品运行时正确性和整体 H5 成熟度

对于视觉／性能 campaign 工作，如果产品技术栈允许，原生门禁必须能够在无需针对每个假设重新构建的情况下运行不同变体；在运行时扫描期间保留预热的浏览器／服务端状态；并输出胜出证据，而不是堆积原始截图。如果两轮 harness 循环都没有推动产品判定标准或指标，就停止 harness 工作，转而进行产品原生实验。

这是将证据转化为工具改进方案的途径。如果结果无法教会后续 Agent 如何维护或改进仓库的真实工具界面，就将其保留为观察结果或未知案例，而不要晋级。

采用运行分类

在提出 S/H 声明前，使用 adoption-run/v2 证据格式。记录：

• user_goal：原始提示词、请求的结果、验收检查、状态和证据。
• capability：id、类别、范围、用户价值和原生负责人。
• direct_problem_path：声明的界面，以及在原始 shell 探索之前使用的原生门禁。
• tool_detour：原因、尝试、产物、停止规则和返回目标的步骤。
• generational_architecture_check：重复模式、考虑过的更小层、删除／合并选项、选定的模式层、维护增量和晋级保护条件。
• outcome：继续、重构、停止、放弃或晋级。
• hot_path_claim：问题类别、创建的界面、反例、正向证明、观察到的影响、留出任务或未来任务，以及不包含的声明。

不要因为一次完善的证明就称仓库为“完全采用”。应称为“能力级 H5”或“能力级 S5/H5”，并明确指出该能力。仓库成熟度仍是独立且范围更广的声明。

采用成熟度阶梯

在证明阶段与声明相符之前，不要称仓库已准备好用于 harness。

阶段	名称	证明
H0	已安装 Skills	Agent 能发现相关的 Skill Steward skills。
H1	已声明本地契约	steward.yaml 存在，其中有一个快速安全的 action，文档也指向该 action。
H2	已证明冒烟循环	冷启动证明循环会生成持久的基准测试摘要，且 result: "pass"；在干净地重新运行之前，durability_blocked 会使仓库无法达到 H2。
H3	仓库反馈循环	基准测试摘要、未知案例和 action 候选项会从实际工作中不断积累。
H4	新 Agent 工作流	一个新 Agent 无需深入探索原始 shell，即可完成一项仓库工作流。
H5	已晋级的 harness 能力	重复证据（包括至少一项留出基准测试或未来 Agent 的重复验证）会将诊断、action、eval 或本地 harness 功能晋级。

原型详情

• 原型 A（产品 MCP）： plugin/ 是 SSOT。交付自定义服务，不要为产品逻辑修改社区服务。
• 原型 B（平台库）： 仅包含核心模块和线协议适配器；不要分叉领域逻辑。
• 原型 C（CLI Harness）： 不使用 MCP。依赖产品 MCP 核心模块。
• 原型 D（视觉 sidecar）： 不使用 MCP。SSOT：profiles/*.yaml。
• 原型 E（Meta Steward）： 核心验证器和精简的 CLI 检查。不使用 mcp.json。
• 原型 F（生产环境 MCP）： 只读操作使用资源；变更操作使用工具。长时间运行的任务返回作业 ID。使用 OAuth。

同级目录布局

<workspace>/
  <plugin_repo>/               # toolkit + MCP/plugin init
  <library_repo>/              # SDK platform/library packages
  <harness_repo>/              # CLI/harness runner
  <visual_sidecar>/            # D — comparison sidecar
  <meta_governance_repo>/      # meta skills & validation

声明“已准备好供 harness 使用”前的检查清单

常见证明：

• Agent 仅凭仓库内的文档就能发现要运行什么
• 仓库在采用成熟度阶梯上至少达到 H2
• 失败消息会说明如何修复
• 设计分支已设置检查点（repository-governance-lifecycle）
• 契约门禁或验证脚本通过

特定架构类型的证明：

架构类型	所需证明
产品 MCP	MCP 工具和 CLI 命令共用相同的核心架构／验证入口。
平台库	协议适配器保持轻量，核心测试覆盖相关行为，且未内嵌特定产品的分支。
CLI harness	存在用于 CI／门禁的 CLI 命令；除非仓库公开 MCP，否则不要求与 MCP 保持一致。
可视化 sidecar	配置档案／配置架构以及比较／解构命令均通过验证；不要求与 MCP 保持一致。
元治理者	技能／插件／验证器接口通过技能验证和 T1 行为关键路由用例；未捆绑任何产品运行时。
安全／运维	变更接口必须明确风险类别、脱敏方式和授权策略。

安装

npx skills add arenukvern/skill_steward --skill mcp-harness-repo-maintainer

参考资料

• core-and-interfaces.md
• repo-archetypes.md
• maintainer-checklists.md
• mcp-production-practices.md
• sibling-layout.md
• harness-principles.md
• cli-mcp-pattern.md
• steward-composition.md
• preferred-tooling.md

来源

请参阅 references/sources.md。研究时，请遵循 skill-source-citations。