Harness Engineering

Purpose

本 skill 是构建规范，不是学习材料。当 AI 通过编程方式构建一个 harness agent 时，读取本 skill 作为参考标准，确保产出的 agent 符合 harness 工程架构。

典型使用场景：用户说"帮我写一个 coding agent / 自动化 agent / 长时运行 agent"，AI 在编码前加载本 skill，按规范构建。

What is an Agent Harness

包裹 LLM 的运行时编排层——管工具调用、上下文、记忆、权限、交付，让模型从"一次性问答"变成"能干活的自主系统"。

"A harness is not 'a loop that calls a model'. It is a context-management system with a loop at its centre."

Harness != Framework != Runtime

叠加关系：Framework（定义逻辑） -> Runtime（管执行） -> Harness（包一切，给用户用）

Architecture: The Loop + 7 Rings

一个 harness 就是以 agent loop 为中心，向外扩展七层"环"（ring）。每层解决一个独立问题，可单独理解和替换。

核心文件索引

Core Principles

1. Prompts 是软引导，Extensions 是硬护栏 —— 安全关键逻辑必须用 extension，不能用 prompt
2. Skills 扩展 prompt，Extensions 扩展 loop —— 对称性：一个在 prompt 层，一个在 loop 层
3. Append-only，不原地改写 —— Session 树、Compaction entry 都是追加，原始数据不丢
4. Catalogue vs Body 分离 —— Skill 只注目录进 prompt，body 按需 read
5. Neutral Hook Boundary —— Runtime 提供中性 hook，不内置 sub-agents / MCP / plan-mode

Build Checklist

构建前（必须完成）

• 确认目标：coding agent / 自动化 agent / 长时运行 agent
• 选择 provider 策略：深度绑定 vs 多 provider（见 design-decisions.md D4）
• 选择 session 策略：不可变树 vs 扁平 list（见 design-decisions.md D15）
• 选择扩展策略：内置一切 vs 全推给扩展（见 design-decisions.md D28）
• 读取 references/architecture.md 理解 7 Rings 架构
• 读取 references/design-decisions.md 做完所有技术选型

构建中（按阶段）

• Phase 1 MVP：Agent loop + 1 个 provider + 3 个核心工具（read/write/bash）+ 基础 CLI
• Phase 2 可用：完整 7 件套工具 + Pydantic 校验 + Session 持久化 + 流式输出 + 取消机制
• Phase 3 生产可用：Session 树 + Compaction + 权限 hook + Extension API + TUI
• Phase 4 进阶：Sub-agents + Plan mode + MCP adapter + 长时运行模式 + 多 provider

构建后（验证）

• 每个 tool 都有 Pydantic schema + 参数校验
• max_iterations 安全阀存在
• cancel_event 取消机制存在
• compaction 80% 阈值触发
• 权限 hook（authorize + process_result）存在
• extension API 三动词（on / register_tool / register_command）存在
• 至少一种 delivery shell（TUI / CLI / Web）

Build Phases（分阶段实施）

每阶段都可独立使用。先跑通再优化。

Scope

This skill ONLY:

• 提供 harness agent 的构建规范、设计决策、代码模板
• 对比主流 harness 的架构选择供参考
• 引导 AI 按标准构建符合工程规范的 harness agent

This skill NEVER:

• 执行代码或调用 LLM
• 访问网络或外部服务
• 自动修改用户项目文件
• 替代真正的 harness 实现（需 AI 根据模板编码）