Spec Coding 与 Harness Engineering：AI 驱动开发的双引擎

Spec Coding（规格编程） 与 Harness Engineering（驾驭工程） 是AI驱动开发的两个核心范式，前者聚焦“写清楚做什么”，后者聚焦“搭好让AI可靠执行的环境”，二者互补，共同构成AI Agent工程化的基础。

一、Spec Coding（规格驱动开发）

1. 核心定义

先写精确、结构化的规格（Spec），再让AI按规格生成代码并验证，强调“规格先行、契约驱动”，是AI时代的规范驱动开发（SDD） 。

2. 核心理念与原则

• No Spec, No Code：无规格，不编码
• Spec is Truth：规格是唯一真理，代码与规格冲突时，以规格为准
• Reverse Sync：发现Bug先修规格，再同步修改代码

3. 规格（Spec）内容

• 功能需求：明确“做什么”，如API接口、页面逻辑、业务规则
• 技术约束：技术栈、框架、语言、依赖版本
• 输入输出：参数类型、格式、边界条件、返回值、状态码
• 质量标准：测试覆盖率、性能指标、错误处理、安全要求
• 验收规则：可自动化验证的测试用例

4. 适用场景

• 需求明确、需长期维护的企业级项目
• API开发、微服务、复杂业务逻辑
• 多人协作、需可审计、可追溯的工程场景

5. 典型流程

1. 编写并评审结构化Spec（Markdown/YAML/OpenAPI）
2. AI按Spec生成代码与测试
3. 自动验证代码是否符合Spec
4. 迭代优化Spec与代码

---

二、Harness Engineering（驾驭工程）

1. 核心定义

为AI Agent构建一套可运行、可观测、可验证、可修复的执行环境与约束系统，让AI在受控框架内自主、可靠地完成长周期任务，核心是人设计环境，AI执行任务。

2. 核心理念

• Agent = Model + Harness：模型能力决定下限，Harness决定上限
• Humans steer. Agents execute：人类掌舵，AI执行
• 工程重心从“写代码”转向“构建让AI可靠工作的脚手架”

3. Harness的核心组件

• 执行环境：沙箱、权限、资源隔离、工具链（如代码执行、测试、部署）
• 状态管理：任务上下文、进度追踪、断点恢复、失败重试
• 验证机制：自动测试、验收检查、质量门禁、合规审计
• 反馈闭环：结果评估、错误诊断、自动修复、迭代优化
• 安全控制：权限边界、数据隔离、防止幻觉与越权行为

4. 适用场景

• AI Agent长周期、复杂任务（如项目开发、系统运维、数据 pipeline）
• 需高可靠性、可治理、可审计的AI自动化流程
• 多Agent协作、跨工具链的复杂工作流

5. 价值

• 同一模型，Harness不同，效果可差10倍以上
• 解决AI的幻觉、连续性中断、不可控、不可恢复等问题
• 让AI从“片段生成”升级为端到端、可持续的工程交付

---

三、Spec Coding vs Harness Engineering：核心对比

维度	Spec Coding	Harness Engineering
核心定位	定义“做什么”（意图/契约）	构建“怎么可靠执行”（环境/约束）
关注重点	规格文档、需求对齐、代码一致性	执行框架、状态管理、验证、安全、恢复
人类角色	写Spec、评审、验收	设计Harness、定义规则、监控治理
AI角色	按Spec生成代码、验证	在Harness内自主执行、迭代、修复
产出物	符合Spec的代码、测试、文档	可自治、可观测、可治理的Agent运行体系
解决问题	需求模糊、输出不稳定、不可审计	幻觉、中断、不可控、长任务不可靠
关系	内容层：提供执行的“蓝图”	执行层：提供运行的“马具/脚手架”

---

四、’Spec Coding三层模板 + Harness核心组件清单

一、可直接套用的Spec Coding模板（三层文档结构）

核心逻辑：三层递进（顶层需求→中层设计→底层验收），覆盖“做什么、怎么做、怎么算合格”，适配API、微服务、业务逻辑、工具类等所有开发场景，可直接替换占位符使用。

第一层：顶层规格（需求层，Spec-Level 1）

核心：明确“为什么做、做什么、约束是什么”，面向产品、开发、AI三方对齐，无技术细节，只定边界和目标。

# 顶层规格：Hermes模型配置自动化功能
## 1. 功能概述
- 用途：实现Hermes模型参数的自动化配置，替代手动执行hermes config命令，减少手动输入失误，提升AI Agent部署效率
- 适用场景：AI Agent部署前的Hermes模型参数初始化、模型切换时的参数重新配置、批量环境下的Hermes统一配置
- 不做什么：不处理Hermes软件本身的安装与升级、不涉及用户权限校验、不修改Hermes模型本身的核心配置（仅配置model相关参数）

## 2. 核心约束
- 技术栈约束：JavaScript/Node.js ≥ 16.x，依赖child_process模块、util模块（用于promisify处理异步）
- 性能约束：单条hermes config命令执行耗时≤1s，单轮配置（4条命令）总耗时≤5s，命令执行失败重试≤3次
- 安全约束：API Key需加密存储（优先使用环境变量），禁止在日志中明文打印apiKey等敏感信息
- 兼容性约束：兼容Windows/Linux/MacOS三大系统，适配Hermes v1.0+版本，支持hermes config命令正常执行

## 3. 输入输出
### 3.1 输入（入参/依赖）
| 输入项 | 类型 | 必选 | 描述 | 示例 |
|--------|------|------|------|------|
| hermesModel.model | 字符串 | 是 | Hermes模型名称，用于拼接model.default参数值 | "gpt-4" |
| hermesModel.provider | 字符串 | 否 | 模型提供商，默认值为"ctyuncustom" | "openai" |
| hermesModel.baseUrl | 字符串 | 是 | 模型请求基础地址，用于配置model.base_url | "https://api.hermes.com/v1" |
| hermesModel.apiKey | 字符串 | 是 | 模型访问密钥，用于配置model.api_key，敏感信息 | "sk_xxxxxxxxxxxxxx" |

### 3.2 输出（返回值/结果）
| 输出项 | 类型 | 描述 | 成功示例 | 失败示例 |
|--------|------|------|----------|----------|
| 配置日志 | 字符串 | 记录4条配置命令的执行过程与结果 | "Hermes 配置完成: hermes config set model.default..." | "Hermes 配置失败: hermes命令不存在" |
| 执行状态 | 布尔值 | 整个Hermes配置流程是否成功 | true | false |

## 4. 异常场景
- 场景1：必选参数缺失（apiKey为空或baseUrl为空） → 处理方式：抛出错误，提示“apiKey和baseUrl为必选参数，不能为空”，不执行任何配置命令
- 场景2：命令执行失败（hermes命令不存在或未配置环境变量） → 处理方式：打印错误日志，重试2次，仍失败则抛出异常，提示“Hermes配置失败: hermes命令无法执行，请检查Hermes安装与环境变量配置”
- 场景3：参数格式错误（baseUrl不是合法URL格式） → 处理方式：抛出错误，提示“baseUrl格式不合法，请输入正确的URL地址”，终止配置流程
- 场景4：命令执行超时（单条命令执行超过3s） → 处理方式：判定为执行失败，进入重试流程，重试3次后仍超时则抛出异常

第二层：中层规格（设计层，Spec-Level 2）

核心：明确“怎么做”，面向开发和AI，给出技术实现思路、核心逻辑，不涉及具体代码，只定设计标准。

# 中层规格：Hermes模型配置自动化功能实现设计
## 1. 核心逻辑流程
1. 参数校验：校验输入的hermesModel对象中必选参数（model、baseUrl、apiKey）是否存在且格式合法（如baseUrl校验URL格式）
2. 命令拼接：按hermes config命令格式，动态拼接4条配置命令，使用转义函数处理变量，避免命令注入风险
3. 命令执行：使用child_process.exec异步执行拼接后的命令（可选择用&&拼接执行或逐行执行），捕获执行过程中的日志
4. 结果校验：判断每条命令的执行结果，查看日志中是否包含命令执行成功标识，同时校验配置是否生效
5. 结果返回：执行成功则返回执行状态true和配置日志；执行失败则捕获错误信息，触发重试机制，重试失败后抛出异常

## 2. 核心模块设计
| 模块名称 | 职责 | 依赖 | 设计标准 |
|----------|------|------|----------|
| 参数校验模块 | 校验hermesModel对象的必选参数、参数格式，输出校验结果 | 无额外依赖，原生JS实现 | 参数校验需覆盖所有必选字段，格式校验精准（如URL、字符串非空），错误提示清晰易懂，明确指出错误参数与原因 |
| 命令拼接模块 | 拼接4条hermes config配置命令，处理变量转义，避免注入风险 | 自定义escapeShell转义函数 | 命令拼接格式正确，变量转义彻底，支持provider参数为空时使用默认值，无硬编码内容 |
| 命令执行模块 | 异步执行拼接后的命令，捕获执行日志与错误信息，实现重试逻辑 | child_process模块、util模块（promisify） | 命令执行异步无阻塞，日志记录完整，重试策略合理（指数退避），失败时能精准捕获错误原因 |
| 结果校验模块 | 校验命令执行结果，确认配置是否生效，返回最终执行状态 | 无额外依赖 | 结果校验全面，既校验日志中的成功标识，也可 optional 校验Hermes配置文件，确保配置真正生效 |

## 3. 关键技术点
- 技术点1：命令拼接的安全处理，避免特殊字符注入 → 实现要求：使用自定义escapeShell转义函数处理所有变量（model、provider、baseUrl、apiKey），将变量用双引号包裹，转义变量中的双引号等特殊字符，防止破坏命令语法
- 技术点2：异步命令执行的错误捕获与重试 → 实现要求：用try/catch捕获exec异步执行的异常，打印详细错误信息（包含执行的命令、错误原因）；重试机制采用指数退避策略（1s、2s、4s），最多重试3次，可配置重试场景（超时、命令不存在等可恢复错误）
- 技术点3：参数格式校验 → 实现要求：baseUrl需通过正则表达式校验URL格式（如匹配http/https开头），apiKey校验非空且长度符合常规密钥格式，model校验非空字符串，避免无效参数导致配置失败
- 技术点4：敏感信息保护 → 实现要求：拼接命令时不直接打印apiKey，日志中屏蔽apiKey（用****替代），优先从环境变量中获取apiKey，不硬编码敏感信息

## 4. 接口/方法定义（若有）
### 方法1：setHermesConfig
- 用途：执行Hermes模型参数自动化配置，接收hermesModel参数，完成4条配置命令的执行与结果校验
- 参数：hermesModel（对象），包含model（字符串，必选）、provider（字符串，可选）、baseUrl（字符串，必选）、apiKey（字符串，必选）
- 返回值：对象，包含status（布尔值，执行状态）、log（字符串，配置日志）
- 异常：抛出Error，包含错误信息（如参数缺失、命令执行失败、超时等），便于上层捕获处理

第三层：底层规格（验收层，Spec-Level 3）

核心：明确“怎么算合格”，面向测试、AI，可自动化验证，给出具体测试用例、验收标准，确保代码符合顶层/中层规格。

# 底层规格：Hermes模型配置自动化功能验收标准
## 1. 验收总则
- 所有测试用例需100%通过，无失败用例
- 执行性能需满足顶层规格中的性能约束（单条命令≤1s，单轮总耗时≤5s，重试≤3次）
- 异常场景处理需符合顶层规格中的要求，错误提示清晰，处理逻辑合理
- 代码需符合中层规格中的设计标准，无命令注入风险，敏感信息保护到位

## 2. 自动化测试用例（可直接转化为代码测试）
### 2.1 正常场景用例
| 用例ID | 测试场景 | 输入参数 | 预期输出 | 验证方式 |
|--------|----------|----------|----------|----------|
| TC-001 | 所有参数正常，配置成功 | hermesModel: {model: "gpt-4", provider: "openai", baseUrl: "https://api.hermes.com/v1", apiKey: "sk_123456"} | 执行状态=true，日志含“Hermes 配置完成”，4条命令均执行成功 | 1. 查看执行日志；2. 执行hermes config get命令，校验model.default、model.provider等4个参数与输入一致；3. 确认无敏感信息明文打印 |
| TC-002 | 可选参数（provider）为空，使用默认值 | hermesModel: {model: "gpt-3.5", provider: "", baseUrl: "https://api.hermes.com/v1", apiKey: "sk_654321"} | 执行状态=true，provider默认设为“ctyuncustom”，其他参数与输入一致 | 1. 查看执行日志，确认provider使用默认值；2. 执行hermes config get model.provider，校验结果为“ctyuncustom” |
| TC-003 | provider参数正常，其他参数合法 | hermesModel: {model: "claude-2", provider: "anthropic", baseUrl: "https://api.anthropic.com/hermes", apiKey: "sk_abcdef"} | 执行状态=true，4条配置命令均生效，参数与输入完全一致 | 1. 查看执行日志；2. 校验Hermes配置文件中的4个model相关参数；3. 确认命令执行耗时≤5s |

### 2.2 异常场景用例
| 用例ID | 测试场景 | 输入参数 | 预期输出 | 验证方式 |
|--------|----------|----------|----------|----------|
| TC-004 | 必选参数（apiKey）为空 | hermesModel: {model: "gpt-4", provider: "openai", baseUrl: "https://api.hermes.com/v1", apiKey: ""} | 抛出错误，提示“apiKey和baseUrl为必选参数，不能为空”，未执行任何配置命令 | 1. 捕获异常信息，确认错误提示正确；2. 查看日志，无任何hermes config命令执行记录；3. 校验Hermes配置无变化 |
| TC-005 | 命令执行失败（hermes未安装） | hermesModel: {model: "gpt-4", provider: "openai", baseUrl: "https://api.hermes.com/v1", apiKey: "sk_123456"} | 重试2次后抛出异常，提示“Hermes配置失败: hermes命令无法执行，请检查Hermes安装与环境变量配置” | 1. 查看日志，确认重试2次；2. 捕获异常信息，确认错误提示正确；3. 校验Hermes配置无变化 |
| TC-006 | baseUrl格式错误 | hermesModel: {model: "gpt-4", provider: "openai", baseUrl: "api.hermes.com", apiKey: "sk_123456"} | 抛出错误，提示“baseUrl格式不合法，请输入正确的URL地址”，终止配置流程 | 1. 捕获异常信息，确认错误提示正确；2. 查看日志，无命令执行记录；3. 校验Hermes配置无变化 |
| TC-007 | 命令执行超时 | hermesModel: {model: "gpt-4", provider: "openai", baseUrl: "https://api.hermes.com/v1", apiKey: "sk_123456"}（模拟命令执行超时） | 重试3次后抛出异常，提示“Hermes配置失败: 命令执行超时” | 1. 查看日志，确认重试3次；2. 捕获异常信息，确认错误提示正确；3. 校验Hermes配置无变化 |

## 3. 代码质量验收标准
- 代码覆盖率：≥80%（核心逻辑100%覆盖，包括参数校验、命令拼接、命令执行、错误捕获、重试逻辑）
- 代码规范：符合ESLint规范，无语法错误、无冗余代码，变量命名规范（语义化），函数职责单一
- 可维护性：关键逻辑（如转义函数、重试逻辑、参数校验逻辑）添加清晰注释，无硬编码内容，可灵活适配不同Hermes版本
- 安全性：无命令注入风险，敏感信息（apiKey）不打印、不硬编码，优先从环境变量获取，变量转义彻底

## 4. 验收方式
1. 自动化测试：编写Jest测试脚本，执行所有测试用例，查看通过率（需100%通过），校验执行性能是否达标
2. 手动验证：模拟真实场景，输入不同参数（正常参数、异常参数），执行配置函数，查看执行结果与日志，校验Hermes配置是否生效
3. 日志校验：查看执行日志，确认日志完整、无敏感信息明文、错误提示清晰、重试逻辑执行正确
4. 代码审查：检查代码是否符合中层规格设计标准，重点审查命令转义、敏感信息保护、错误处理逻辑

二、Harness核心组件清单（可直接落地，适配AI Agent执行）

核心：覆盖“执行、监控、验证、安全、恢复”全流程，每个组件给出“核心职责+落地要点”，可根据需求选择性启用，适配AI Agent长周期、可靠执行场景（如你之前的Hermes配置任务）。

1. 执行环境组件（基础核心）

• 沙箱环境（Sandbox）

  • 核心职责：隔离AI执行环境与生产环境，防止误操作、越权，避免影响现有系统
  • 落地要点：① 基于Docker构建轻量沙箱，仅开放必要工具（如hermes、node.js）；② 限制沙箱资源（CPU、内存），防止资源耗尽；③ 执行完成后自动清理沙箱，避免残留。

• 工具链管理（Toolchain Manager）

  • 核心职责：统一管理AI可调用的工具、命令、依赖，确保工具可用、版本一致
  • 落地要点：① 维护工具清单（如hermes、child_process、exec等），明确版本要求；② 工具缺失时自动安装，版本不匹配时提示升级；③ 禁止AI调用清单外的工具，防止越权。

• 权限控制（Permission Controller）

  • 核心职责：控制AI的操作权限，防止敏感操作（如删除文件、修改系统配置）
  • 落地要点：① 基于角色分配权限（如AI仅拥有“执行hermes命令”“读取配置文件”权限）；② 禁止AI执行高危命令（如rm、sudo）；③ 敏感操作（如修改apiKey）需二次校验。

2. 状态管理组件（保障连续性）

• 上下文管理（Context Manager）

  • 核心职责：保存任务执行过程中的上下文（输入参数、执行步骤、中间结果），支持断点恢复
  • 落地要点：① 用JSON格式存储上下文，包含任务ID、当前步骤、参数信息；② 每完成一个步骤，自动更新上下文；③ 任务中断后，可通过上下文恢复执行，无需重新开始。

• 进度追踪（Progress Tracker）

  • 核心职责：实时追踪任务执行进度，明确当前所处步骤、执行状态
  • 落地要点：① 定义步骤状态（初始化→参数校验→命令执行→结果验证→完成/失败）；② 实时打印进度日志（如“当前步骤：命令执行，进度50%”）；③ 支持查询任务进度（通过任务ID）。

• 断点恢复（Breakpoint Recovery）

  • 核心职责：任务中断（如系统崩溃、网络异常）后，可从断点处继续执行，避免重复工作
  • 落地要点：① 每完成一个关键步骤，自动保存断点（关联上下文）；② 任务启动时，先检查是否有未完成的断点，有则恢复；③ 断点保留时间可配置（如24小时），超时自动清理。

3. 验证机制组件（保障可靠性）

• 自动验证器（Auto Validator）

  • 核心职责：自动校验AI执行结果是否符合Spec规格，无需人工干预
  • 落地要点：① 关联Spec底层验收用例，执行完成后自动运行验证脚本；② 验证维度：结果正确性、性能、日志完整性；③ 验证失败时，触发错误处理流程。

• 质量门禁（Quality Gate）

  • 核心职责：设置质量阈值，不符合阈值的结果直接拦截，不进入下一个步骤
  • 落地要点：① 阈值配置（如“命令执行耗时≤1s”“测试用例通过率100%”）；② 触发门禁后，自动重试（最多3次），仍不通过则抛出异常；③ 记录门禁拦截日志，便于排查问题。

• 合规审计（Compliance Auditor）

  • 核心职责：记录AI执行的所有操作，确保可追溯、可审计，符合安全规范
  • 落地要点：① 审计日志包含：操作时间、任务ID、执行命令、输入输出、执行结果；② 日志不可篡改，保存时间≥7天；③ 支持按任务ID、时间范围查询审计日志。

4. 反馈与恢复组件（保障鲁棒性）

• 错误诊断器（Error Diagnoser）

  • 核心职责：AI执行失败时，自动诊断错误原因，给出修复建议
  • 落地要点：① 关联常见错误库（如“hermes命令不存在”“apiKey错误”）；② 诊断维度：日志分析、参数校验、环境检查；③ 输出清晰的错误原因和修复步骤（如“错误：hermes未安装 → 修复：执行npm install hermes -g”）。

• 自动重试（Auto Retryer）

  • 核心职责：针对可恢复的错误（如网络波动、命令执行超时），自动重试，减少人工干预
  • 落地要点：① 配置重试场景（如“命令执行超时”“网络连接失败”）；② 重试策略：指数退避（1s、2s、4s），最多重试3次；③ 重试失败后，触发错误反馈流程。

• 反馈闭环（Feedback Loop）

  • 核心职责：将执行结果、错误信息反馈给AI和人类，迭代优化执行逻辑
  • 落地要点：① 成功时，反馈“执行完成”及关键结果；② 失败时，反馈错误原因、修复建议；③ 收集人类反馈（如“修复后重新执行”），同步更新AI执行逻辑和Spec规格。

5. 安全控制组件（保障安全性）

• 敏感信息防护（Sensitive Data Protector）

  • 核心职责：保护敏感信息（如apiKey、密码），防止泄露
  • 落地要点：① 敏感信息加密存储（如使用环境变量、加密配置文件）；② 日志中屏蔽敏感信息（如apiKey显示为****）；③ 禁止AI将敏感信息输出到公共渠道。

• 幻觉拦截（Hallucination Interceptor）

  • 核心职责：拦截AI的幻觉行为（如生成不存在的命令、错误的配置参数）
  • 落地要点：① 校验AI生成的命令/参数是否符合Spec规格；② 拦截不符合规格的操作，提示AI重新生成；③ 记录幻觉行为，用于优化AI提示词。

• 操作审计（Operation Auditor）

  • 核心职责：监控AI的所有操作，及时发现异常行为（如越权、恶意操作）
  • 落地要点：① 实时监控AI执行的命令、访问的文件；② 配置异常行为规则（如“访问系统根目录”“执行高危命令”）；③ 触发异常时，立即终止AI执行，通知人类管理员。

补充：Harness组件落地优先级（按重要性排序）

1. 基础优先级（必选）：执行环境组件（沙箱+工具链+权限）+ 状态管理组件（上下文+进度）

2. 进阶优先级（推荐）：验证机制组件（自动验证+质量门禁）+ 反馈与恢复组件（自动重试+错误诊断）

3. 高阶优先级（可选）：安全控制组件（敏感信息防护+幻觉拦截）+ 合规审计

五、二者关系：互补而非竞争

• Spec是Harness的“输入与目标” ：Harness按Spec约束AI行为、验证结果
• Harness是Spec的“执行放大器” ：Harness越强，Spec的价值越能被放大
• 最佳实践：先写清晰Spec，再构建强大Harness，让AI在受控环境中严格按规格交付

---

六、一句话总结

• Spec Coding：把需求写成机器可执行的精确说明书，让AI“按图施工”。
• Harness Engineering：给AI搭好安全、可靠、可观测的执行框架，让AI“自主跑完全程”。