Harnesskit 是一个以测试驱动为核心理念的智能体工作流脚手架，旨在为软件项目建立可验证、可复现的 AI 辅助开发流程。

Harnesskit：以测试驱动为核心的智能体工作流脚手架\n\n## AI 辅助开发的可靠性挑战\n\n随着 AI 编程助手在软件开发中的广泛应用，一个核心问题日益凸显：如何确保 AI 生成的代码是正确且可靠的？\n\n传统软件开发中，测试是质量保证的关键环节。然而，当 AI 介入代码生成后，测试的角色变得更加复杂。AI 生成的代码可能表面上通过了编译，但在边界条件、并发场景、安全漏洞等方面存在隐患。更糟糕的是，由于 AI 输出的不确定性，相同的提示词在不同时间可能产生不同的代码，这使得问题复现和调试变得困难。\n\nHarnesskit 项目正是为了应对这一挑战而诞生的。\n\n## 核心理念：Harness-First\n\nHarnesskit 的核心理念可以概括为"Harness-First"，即测试先行。这一理念借鉴了测试驱动开发（TDD）的思想，但将其扩展到了 AI 辅助开发的语境中：\n\n在生成代码之前，先定义验证标准。这些标准不仅包括传统的单元测试，还可以是类型检查、静态分析、性能基准、安全扫描等。AI 在生成代码时必须满足这些预定义的约束，否则生成结果将被拒绝。\n\n代码生成与验证形成闭环。不是先生成代码再测试，而是将测试作为生成过程的一部分。AI 智能体在生成代码的同时，不断运行验证检查，根据反馈迭代改进，直到所有约束都得到满足。\n\n可复现的确定性流程。通过将验证标准编码为配置，确保相同的输入总是产生满足相同标准的输出，消除 AI 生成的不确定性。\n\n## 系统架构\n\nHarnesskit 的架构设计体现了其核心理念，包含以下关键组件：\n\n### Harness 定义层\n\n这是系统的核心，开发者使用声明式配置定义验证标准。Harness 可以包含：\n\n测试套件：\n- 单元测试：验证函数和类的行为\n- 集成测试：验证模块间的交互\n- 端到端测试：验证完整用户流程\n- 模糊测试：发现边界条件和异常输入下的问题\n\n静态检查：\n- 类型检查：TypeScript、Python 类型注解等\n- 代码风格：ESLint、Black、Prettier 等\n- 代码复杂度：圈复杂度、认知复杂度阈值\n\n动态分析：\n- 性能基准：执行时间、内存使用上限\n- 覆盖率要求：语句覆盖、分支覆盖、路径覆盖\n- 资源限制：CPU 使用、I/O 操作次数\n\n安全扫描：\n- 依赖漏洞扫描\n- 密钥和敏感信息检测\n- 注入攻击防护检查\n\n### 智能体编排层\n\n负责协调 AI 智能体的工作流程：\n\n任务分解：将大型开发任务分解为可以通过单个 harness 验证的小步骤\n\n上下文管理：维护当前任务的状态、已生成的代码、验证结果等信息\n\n反馈循环：将验证失败的信息转化为具体的修复指令，指导 AI 进行修正\n\n多智能体协作：支持多个专业智能体协同工作，如一个负责代码生成，另一个负责测试编写\n\n### 执行引擎\n\n负责实际运行 harness 验证：\n\n沙箱环境：在隔离环境中运行测试，防止恶意或错误代码影响宿主系统\n\n并行执行：同时运行独立的验证任务，提高效率\n\n结果聚合：收集所有验证结果，生成结构化的报告\n\n缓存机制：缓存通过验证的中间结果，避免重复验证\n\n## 工作流程\n\n使用 Harnesskit 的典型工作流程如下：\n\n### 1. 定义 Harness\n\n开发者首先编写 harness 配置文件，描述期望的行为和验证标准。例如：\n\nyaml\nharness:\n name: user-authentication\n description: 用户认证模块的实现\n \n requirements:\n - 支持邮箱和密码登录\n - 密码必须加密存储\n - 实现速率限制防止暴力破解\n - JWT token 有效期为 24 小时\n \n tests:\n - path: tests/auth/*.test.js\n coverage: 90\n \n checks:\n - type: eslint\n - type: security-scan\n rules:\n - no-hardcoded-secrets\n - no-sql-injection\n \n benchmarks:\n - name: login-latency\n max_ms: 200\n\n\n### 2. 触发代码生成\n\n智能体接收到 harness 定义后，开始生成代码。生成过程不是一次性的，而是迭代式的：\n\n- 生成初始代码实现\n- 运行 harness 验证\n- 分析失败原因\n- 修正代码\n- 重复直到全部通过\n\n### 3. 验证与反馈\n\n每次代码变更后，系统自动运行完整的 harness 验证。失败的信息被结构化地反馈给智能体：\n\n\n[FAIL] test: login-with-valid-credentials\n Expected: 200 OK\n Actual: 401 Unauthorized\n \n[FAIL] security-scan: hardcoded-secret\n Found: API_KEY = \"sk-abc123\" in auth.js:15\n\n\n### 4. 结果交付\n\n当所有验证通过后，系统输出最终的代码和验证报告。开发者可以审查结果，选择接受或要求进一步修改。\n\n## 关键特性\n\n### 声明式配置\n\nHarness 完全使用声明式配置定义，无需编写复杂的脚本。这使得非技术人员也能参与定义验证标准，同时便于版本控制和协作。\n\n### 增量验证\n\n系统支持增量验证策略，只运行受变更影响的测试，大幅缩短验证时间。同时维护验证依赖图，确保增量验证的完整性。\n\n### 智能诊断\n\n当验证失败时，系统不仅报告错误，还尝试分析根本原因并提供修复建议。例如，如果测试因为数据库连接失败而超时，系统会建议检查连接配置而非修改业务逻辑。\n\n### 多语言支持\n\nHarnesskit 设计为语言无关的框架，通过插件机制支持不同的编程语言和生态系统。目前已支持 Python、JavaScript/TypeScript、Go、Rust 等主流语言。\n\n### CI/CD 集成\n\n提供与主流 CI/CD 平台的集成，包括 GitHub Actions、GitLab CI、Jenkins 等。Harness 验证可以作为流水线的一个阶段，阻止不符合标准的代码进入主分支。\n\n## 应用场景\n\n### 自动化代码生成\n\n在需要生成大量样板代码的场景中，Harnesskit 可以确保生成代码的质量。例如：\n\n- API 端点和数据模型的 CRUD 操作\n- 数据库迁移脚本\n- 配置文件和部署模板\n\n### 遗留代码重构\n\n重构遗留代码时，可以定义 harness 确保重构前后的行为一致性：\n\n- 为遗留代码编写特性测试\n- 使用 AI 辅助重构\n- 验证重构后的代码通过相同的测试\n\n### 代码审查辅助\n\n作为代码审查的预检查，在人工审查前自动验证代码是否符合项目标准：\n\n- 运行完整的 harness 验证\n- 生成合规性报告\n- 只将通过的代码提交给人工审查\n\n### 教育训练\n\n作为编程教育的工具，帮助学生理解测试的重要性：\n\n- 学生编写 harness 定义期望行为\n- 观察 AI 如何根据 harness 生成代码\n- 学习如何编写有效的测试用例\n\n## 与测试驱动开发（TDD）的关系\n\nHarnesskit 与 TDD 有许多相似之处，但也有重要区别：\n\n相同点：\n- 都强调测试先行\n- 都通过反馈循环驱动开发\n- 都追求可验证的正确性\n\n不同点：\n- TDD 是人类开发者编写测试和代码，Harnesskit 是人类定义测试、AI 生成代码\n- TDD 的测试通常由开发者编写，Harnesskit 的 harness 可以由非技术人员定义\n- TDD 关注单个功能点，Harnesskit 可以定义系统级的验证标准\n\n可以将 Harnesskit 视为 TDD 在 AI 时代的演进形态。\n\n## 技术实现要点\n\n### 沙箱技术\n\n安全地执行 AI 生成的代码是 Harnesskit 的关键技术挑战。项目采用多层沙箱策略：\n\n- 容器化隔离：使用 Docker 容器隔离执行环境\n- 资源限制：限制 CPU、内存、网络访问\n- 超时控制：防止无限循环或死锁\n- 只读文件系统：防止代码修改系统文件\n\n### 提示工程\n\n将 harness 定义转化为有效的 AI 提示是一门艺术。Harnesskit 使用模板化和上下文增强技术：\n\n- 将 harness 配置转换为结构化的提示指令\n- 提供相关代码示例作为少样本学习\n- 包含失败验证的详细错误信息作为反馈\n\n### 成本优化\n\nAI API 调用可能产生显著成本，Harnesskit 采用多种策略优化：\n\n- 缓存验证结果避免重复检查\n- 使用轻量级模型进行初步验证\n- 智能批处理减少 API 调用次数\n\n## 局限性与未来方向\n\n### 当前局限\n\nHarness 编写成本：定义全面的 harness 需要投入时间和精力，对于探索性项目可能显得过于繁琐。\n\n验证盲区：Harness 只能验证预定义的标准，可能遗漏未考虑到的质量问题。\n\n复杂场景支持：对于涉及复杂状态机或并发交互的系统，自动化的 harness 定义可能难以覆盖所有场景。\n\n### 未来方向\n\n自动生成 Harness：利用 AI 分析代码和需求，自动生成测试用例和验证规则。\n\n模糊测试集成：增强模糊测试能力，自动发现边界条件和异常行为。\n\n形式化验证：探索与形式化验证工具的集成，提供更强的正确性保证。\n\n可视化界面：提供图形化界面，降低 harness 编写的门槛。\n\n## 总结\n\nHarnesskit 代表了 AI 辅助开发向更加工程化、可验证方向发展的趋势。通过将测试驱动开发的理念与 AI 能力相结合，它为解决 AI 生成代码的可靠性问题提供了一个系统化的框架。\n\n对于追求代码质量的团队来说，Harnesskit 提供了一种新的工作模式：人类专注于定义"什么是正确的"，AI 负责实现"如何做到正确"。这种分工既发挥了人类的领域知识和判断力，又利用了 AI 的代码生成能力，有望显著提升软件开发的效率和质量。\n\n随着项目的成熟和生态的完善，Harnesskit 可能成为 AI 辅助开发工具链中的关键一环，推动行业建立新的质量标准和最佳实践。

Harnesskit：以测试驱动为核心的智能体工作流脚手架\n\nAI 辅助开发的可靠性挑战\n\n随着 AI 编程助手在软件开发中的广泛应用，一个核心问题日益凸显：如何确保 AI 生成的代码是正确且可靠的？\n\n传统软件开发中，测试是质量保证的关键环节。然而，当 AI 介入代码生成后，测试的角色变得更加复杂。AI 生成的代码可能表面上通过了编译，但在边界条件、并发场景、安全漏洞等方面存在隐患。更糟糕的是，由于 AI 输出的不确定性，相同的提示词在不同时间可能产生不同的代码，这使得问题复现和调试变得困难。\n\nHarnesskit 项目正是为了应对这一挑战而诞生的。\n\n核心理念：Harness-First\n\nHarnesskit 的核心理念可以概括为"Harness-First"，即测试先行。这一理念借鉴了测试驱动开发（TDD）的思想，但将其扩展到了 AI 辅助开发的语境中：\n\n在生成代码之前，先定义验证标准。这些标准不仅包括传统的单元测试，还可以是类型检查、静态分析、性能基准、安全扫描等。AI 在生成代码时必须满足这些预定义的约束，否则生成结果将被拒绝。\n\n代码生成与验证形成闭环。不是先生成代码再测试，而是将测试作为生成过程的一部分。AI 智能体在生成代码的同时，不断运行验证检查，根据反馈迭代改进，直到所有约束都得到满足。\n\n可复现的确定性流程。通过将验证标准编码为配置，确保相同的输入总是产生满足相同标准的输出，消除 AI 生成的不确定性。\n\n系统架构\n\nHarnesskit 的架构设计体现了其核心理念，包含以下关键组件：\n\nHarness 定义层\n\n这是系统的核心，开发者使用声明式配置定义验证标准。Harness 可以包含：\n\n测试套件：\n- 单元测试：验证函数和类的行为\n- 集成测试：验证模块间的交互\n- 端到端测试：验证完整用户流程\n- 模糊测试：发现边界条件和异常输入下的问题\n\n静态检查：\n- 类型检查：TypeScript、Python 类型注解等\n- 代码风格：ESLint、Black、Prettier 等\n- 代码复杂度：圈复杂度、认知复杂度阈值\n\n动态分析：\n- 性能基准：执行时间、内存使用上限\n- 覆盖率要求：语句覆盖、分支覆盖、路径覆盖\n- 资源限制：CPU 使用、I/O 操作次数\n\n安全扫描：\n- 依赖漏洞扫描\n- 密钥和敏感信息检测\n- 注入攻击防护检查\n\n智能体编排层\n\n负责协调 AI 智能体的工作流程：\n\n任务分解：将大型开发任务分解为可以通过单个 harness 验证的小步骤\n\n上下文管理：维护当前任务的状态、已生成的代码、验证结果等信息\n\n反馈循环：将验证失败的信息转化为具体的修复指令，指导 AI 进行修正\n\n多智能体协作：支持多个专业智能体协同工作，如一个负责代码生成，另一个负责测试编写\n\n执行引擎\n\n负责实际运行 harness 验证：\n\n沙箱环境：在隔离环境中运行测试，防止恶意或错误代码影响宿主系统\n\n并行执行：同时运行独立的验证任务，提高效率\n\n结果聚合：收集所有验证结果，生成结构化的报告\n\n缓存机制：缓存通过验证的中间结果，避免重复验证\n\n工作流程\n\n使用 Harnesskit 的典型工作流程如下：\n\n1. 定义 Harness\n\n开发者首先编写 harness 配置文件，描述期望的行为和验证标准。例如：\n\nyaml\nharness:\n name: user-authentication\n description: 用户认证模块的实现\n \n requirements:\n - 支持邮箱和密码登录\n - 密码必须加密存储\n - 实现速率限制防止暴力破解\n - JWT token 有效期为 24 小时\n \n tests:\n - path: tests/auth/*.test.js\n coverage: 90\n \n checks:\n - type: eslint\n - type: security-scan\n rules:\n - no-hardcoded-secrets\n - no-sql-injection\n \n benchmarks:\n - name: login-latency\n max_ms: 200\n\n\n2. 触发代码生成\n\n智能体接收到 harness 定义后，开始生成代码。生成过程不是一次性的，而是迭代式的：\n\n- 生成初始代码实现\n- 运行 harness 验证\n- 分析失败原因\n- 修正代码\n- 重复直到全部通过\n\n3. 验证与反馈\n\n每次代码变更后，系统自动运行完整的 harness 验证。失败的信息被结构化地反馈给智能体：\n\n\n[FAIL] test: login-with-valid-credentials\n Expected: 200 OK\n Actual: 401 Unauthorized\n \n[FAIL] security-scan: hardcoded-secret\n Found: API_KEY = \"sk-abc123\" in auth.js:15\n\n\n4. 结果交付\n\n当所有验证通过后，系统输出最终的代码和验证报告。开发者可以审查结果，选择接受或要求进一步修改。\n\n关键特性\n\n声明式配置\n\nHarness 完全使用声明式配置定义，无需编写复杂的脚本。这使得非技术人员也能参与定义验证标准，同时便于版本控制和协作。\n\n增量验证\n\n系统支持增量验证策略，只运行受变更影响的测试，大幅缩短验证时间。同时维护验证依赖图，确保增量验证的完整性。\n\n智能诊断\n\n当验证失败时，系统不仅报告错误，还尝试分析根本原因并提供修复建议。例如，如果测试因为数据库连接失败而超时，系统会建议检查连接配置而非修改业务逻辑。\n\n多语言支持\n\nHarnesskit 设计为语言无关的框架，通过插件机制支持不同的编程语言和生态系统。目前已支持 Python、JavaScript/TypeScript、Go、Rust 等主流语言。\n\nCI/CD 集成\n\n提供与主流 CI/CD 平台的集成，包括 GitHub Actions、GitLab CI、Jenkins 等。Harness 验证可以作为流水线的一个阶段，阻止不符合标准的代码进入主分支。\n\n应用场景\n\n自动化代码生成\n\n在需要生成大量样板代码的场景中，Harnesskit 可以确保生成代码的质量。例如：\n\n- API 端点和数据模型的 CRUD 操作\n- 数据库迁移脚本\n- 配置文件和部署模板\n\n遗留代码重构\n\n重构遗留代码时，可以定义 harness 确保重构前后的行为一致性：\n\n- 为遗留代码编写特性测试\n- 使用 AI 辅助重构\n- 验证重构后的代码通过相同的测试\n\n代码审查辅助\n\n作为代码审查的预检查，在人工审查前自动验证代码是否符合项目标准：\n\n- 运行完整的 harness 验证\n- 生成合规性报告\n- 只将通过的代码提交给人工审查\n\n教育训练\n\n作为编程教育的工具，帮助学生理解测试的重要性：\n\n- 学生编写 harness 定义期望行为\n- 观察 AI 如何根据 harness 生成代码\n- 学习如何编写有效的测试用例\n\n与测试驱动开发（TDD）的关系\n\nHarnesskit 与 TDD 有许多相似之处，但也有重要区别：\n\n相同点：\n- 都强调测试先行\n- 都通过反馈循环驱动开发\n- 都追求可验证的正确性\n\n不同点：\n- TDD 是人类开发者编写测试和代码，Harnesskit 是人类定义测试、AI 生成代码\n- TDD 的测试通常由开发者编写，Harnesskit 的 harness 可以由非技术人员定义\n- TDD 关注单个功能点，Harnesskit 可以定义系统级的验证标准\n\n可以将 Harnesskit 视为 TDD 在 AI 时代的演进形态。\n\n技术实现要点\n\n沙箱技术\n\n安全地执行 AI 生成的代码是 Harnesskit 的关键技术挑战。项目采用多层沙箱策略：\n\n- 容器化隔离：使用 Docker 容器隔离执行环境\n- 资源限制：限制 CPU、内存、网络访问\n- 超时控制：防止无限循环或死锁\n- 只读文件系统：防止代码修改系统文件\n\n提示工程\n\n将 harness 定义转化为有效的 AI 提示是一门艺术。Harnesskit 使用模板化和上下文增强技术：\n\n- 将 harness 配置转换为结构化的提示指令\n- 提供相关代码示例作为少样本学习\n- 包含失败验证的详细错误信息作为反馈\n\n成本优化\n\nAI API 调用可能产生显著成本，Harnesskit 采用多种策略优化：\n\n- 缓存验证结果避免重复检查\n- 使用轻量级模型进行初步验证\n- 智能批处理减少 API 调用次数\n\n局限性与未来方向\n\n当前局限\n\nHarness 编写成本：定义全面的 harness 需要投入时间和精力，对于探索性项目可能显得过于繁琐。\n\n验证盲区：Harness 只能验证预定义的标准，可能遗漏未考虑到的质量问题。\n\n复杂场景支持：对于涉及复杂状态机或并发交互的系统，自动化的 harness 定义可能难以覆盖所有场景。\n\n未来方向\n\n自动生成 Harness：利用 AI 分析代码和需求，自动生成测试用例和验证规则。\n\n模糊测试集成：增强模糊测试能力，自动发现边界条件和异常行为。\n\n形式化验证：探索与形式化验证工具的集成，提供更强的正确性保证。\n\n可视化界面：提供图形化界面，降低 harness 编写的门槛。\n\n总结\n\nHarnesskit 代表了 AI 辅助开发向更加工程化、可验证方向发展的趋势。通过将测试驱动开发的理念与 AI 能力相结合，它为解决 AI 生成代码的可靠性问题提供了一个系统化的框架。\n\n对于追求代码质量的团队来说，Harnesskit 提供了一种新的工作模式：人类专注于定义"什么是正确的"，AI 负责实现"如何做到正确"。这种分工既发挥了人类的领域知识和判断力，又利用了 AI 的代码生成能力，有望显著提升软件开发的效率和质量。\n\n随着项目的成熟和生态的完善，Harnesskit 可能成为 AI 辅助开发工具链中的关键一环，推动行业建立新的质量标准和最佳实践。