diff --git a/AGENTS.md b/AGENTS.md index 57aa40c9e..d7b206881 100755 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,853 +1,400 @@ -# OpenHIS - AI Agent Development Guide +# OpenHIS — Harness Engineering 开发指南 -## 项目概览 -OpenHIS 是一个医院管理系统，采用 Java 17 + Spring Boot 后端和 Vue 3 + Vite 前端架构。 +> **模型决定上限，Harness 决定底线。** +> 本文件是 OpenHIS 项目的 Harness Engineering 落地。基于 24 篇系列文章方法论，为 AI Agent 提供完整的工作环境和约束规则。 -## 构建和运行命令 +--- + +## 📋 项目信息 + +OpenHIS 是一个医院管理系统，Java 17 + Spring Boot 后端 + Vue 3 + Vite 前端 + PostgreSQL。 + +### 构建和运行 -### 后端（Java/Spring Boot） ```bash -# 构建整个项目 -cd openhis-server-new -mvn clean package -DskipTests +# 后端构建 +cd /root/.openclaw/workspace/his-repo/openhis-server-new +mvn compile -pl openhis-application -am # 快速编译 +mvn clean package -DskipTests # 完整打包 +mvn spring-boot:run # 运行（开发模式） -# 运行后端（开发模式） -cd openhis-server-new/openhis-application -mvn spring-boot:run +# 前端 +cd /root/.openclaw/workspace/his-repo/openhis-ui-vue3 +npm install && npm run dev # 启动开发服务器 +npm run build:prod # 生产构建 -# 运行特定模块 -cd openhis-server-new/[module-name] -mvn spring-boot:run +# 语法检查 +python3 -c "import py_compile; py_compile.compile('strategy.py', doraise=True)" ``` -### 前端（Vue 3 + Vite） -```bash -# 安装依赖 -cd openhis-ui-vue3 -npm install +### 关键路径 -# 开发服务器 -npm run dev - -# 生产构建 -npm run build:prod - -# 测试环境构建 -npm run build:test - -# 预览构建结果 -npm run preview +``` +后端代码: openhis-server-new/openhis-application/src/main/java/com/ +后端配置: openhis-server-new/openhis-application/src/main/resources/ +Mapper XML: .../mapper/ (regdoctorstation/, doctorstation/, ...) +前端代码: openhis-ui-vue3/src/ +日志: user_data/logs/freqtrade.log ``` -### 测试 -项目当前没有配置正式的测试框架。如需添加测试： -- 后端：考虑使用 JUnit 5 + Mockito -- 前端：考虑使用 Vitest + Vue Test Utils +--- -## 代码风格规范 +## 🔧 四大核心组件 -### Java 后端规范 -- **Java 版本**: 17 -- **框架**: Spring Boot 2.5.15 -- **ORM**: MyBatis Plus 3.5.5 -- **数据库**: PostgreSQL -- **包结构**: - - `com.openhis` - 业务逻辑 - - `com.core` - 核心框架 -- **命名约定**: - - 类名：PascalCase（如 `UserController`） - - 方法名：camelCase（如 `getUserList`） - - 常量：SCREAMING_SNAKE_CASE - - 配置文件：kebab-case -- **注解使用**: - - 使用 `@Slf4j` 替代手动声明 logger - - 使用 `@Data` 在实体类中 - - 使用 `@Service/@Controller/@Repository` 等 Spring 注解 -- **异常处理**: - - 使用统一的异常处理机制 - - 自定义业务异常继承 `RuntimeException` +> 源自系列文章：十九（控制论）、十七（持久执行）、十八（AI-Native CI/CD） -### Vue 前端规范 -- **框架**: Vue 3 + Composition API -- **UI 库**: Element Plus -- **状态管理**: Pinia -- **路由**: Vue Router 4 -- **构建工具**: Vite 5 -- **组件命名**: PascalCase -- **文件命名**: kebab-case -- **变量命名**: camelCase -- **常量命名**: SCREAMING_SNAKE_CASE -- **函数命名**: - - 事件处理：`handle` 前缀 - - 数据获取：`get`/`load` 前缀 - - 提交操作：`submit` 前缀 +### 1. 约束系统（Constraints） + +定义 Agent 行为边界和输出质量。四层金字塔： + +| 层级 | 内容 | 本项目实现 | 验证方式 | +|---|---|---|---| +| **L1 架构约束** | 接口合约、包结构、命名规范 | MyBatis Mapper 接口、Service 分层 | 编译检查 | +| **L2 代码质量** | 圈复杂度、类型提示、文档 | Java 17 类型系统、Lombok | 编译 + 人工 | +| **L3 安全约束** | 敏感信息、权限、SQL 注入 | PostgreSQL 参数化查询 | 全链路验证 | +| **L4 业务规则** | 数据一致性、事务边界 | 医嘱数据流完整性 | 人工审查 | + +**铁律：** +- 约束越底层越自动（编译检查），越上层越需要人工裁决 +- 冲突时优先级：**安全 > 架构 > 质量 > 性能** +- 约束随信任度动态调整 + +### 2. 反馈系统（Feedback Loop） + +测试 → 失败 → Agent 修复 → 重测。分三层： + +| 层级 | 速度 | 覆盖 | 失败处理 | +|---|---|---|---| +| **L1 编译检查** | <30 秒 | 语法、类型、签名 | `mvn compile` 阻断，Agent 自行修复 | +| **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | Agent 修复，必要时上报 | +| **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 | + +**反馈设计铁律：** +- 反馈必须可行动（文件:行号:错误类型:修复方向） +- 反馈越及时越好 +- 失败后先回滚到最近检查点，再重试 + +### 3. 控制平面（Control Plane） + +``` +┌──────────────────────────────────────────────┐ +│ 战略层（你 — 人类主导） │ +│ ├── 设定任务目标、审批关键决策 │ +│ └── 异常升级处理 │ +├──────────────────────────────────────────────┤ +│ 战术层（Control Plane 主导） │ +│ ├── update_plan + checklist_write 分解步骤 │ +│ ├── 依赖协调 + 并行探索 │ +│ └── 检查点管理 │ +├──────────────────────────────────────────────┤ +│ 执行层（Agent 自主） │ +│ ├── apply_patch / exec_command 修改文件 │ +│ ├── mvn compile 验证 │ +│ └── 错误恢复（git restore → 重试） │ +└──────────────────────────────────────────────┘ +``` + +### 4. 持久执行（Durable Execution） + +每个关键步骤保存检查点，失败后恢复： + +```yaml +checkpoint_triggers: + time: "每个关键步骤完成" + event: "编译通过/失败后" + change: "每次 git diff 产生" + +recovery: + - "失败检测" + - "定位最新检查点（update_plan）" + - "分析失败原因" + - "git restore 撤销修改" + - "从失败点继续" +``` + +幂等性保证： + +| 模式 | 说明 | 本项目应用 | +|---|---|---| +| **唯一标识** | 已执行则跳过 | 同一 Bug 不重复生成文件 | +| **状态检查** | 目标已达成则跳过 | 编译成功模块不重复编译 | +| **补偿操作** | 失败时回滚 | 编译失败 → git restore | + +--- + +## 📋 标准工作流 + +> 源自系列文章：二十三（实战指南） + +### Plan → Generate → Validate → Review + +``` +你提交任务 + │ + ├→ 1. Plan + │ ├── checklist_write + update_plan 分解步骤 + │ ├── 评估复杂度/风险 + │ └── 设定检查点 + │ + ├→ 2. Generate + │ ├── 加载 AGENTS.md + 相关技能 + │ ├── 并行探索（spawn_agent × N） + │ ├── 全链路检查清单核对 + │ └── 增量修改，只动必要文件 + │ + ├→ 3. Validate + │ ├── L1: mvn compile 编译检查 + │ ├── L2: 全链路数据流验证 + │ │ ├── 录入 → 保存 → 查询 → 修改 → 删除 + │ │ └── 关联模块同步更新 + │ └── 生成变更摘要 + │ + └→ 4. Review（你审查） + ├── 浏览 diff 确认范围和正确性 + ├── 检查架构一致性 + ├── 批准 → git add + commit + push + └── 驳回 → 反馈具体问题 → Agent 修复 +``` + +### 异常流程 + +``` +编译失败 → 分析错误 → git restore → 从检查点重试 +持续失败（3次） → 上报你，等待指导 +``` + +--- + +## 🚪 质量门禁（Quality Gates） + +> 源自系列文章：十八（AI-Native CI/CD）、二十三（实战指南） + +| 门禁 | 触发 | 通过条件 | 失败动作 | +|---|---|---|---| +| **L1 编译** | 每次修改 | `mvn compile` 通过 | 立即修复 | +| **L2 全链路** | 提交前 | 数据流完整（6 环检查） | Agent 修复 | +| **L3 审查** | 提交 PR | 你批准 | 驳回/指导 | +| **L4 回归** | 合并后 | 无回归 | 紧急修复 | + +--- + +## 🔐 分层信任模型 + +> 源自系列文章：二十一（边界） + +| 等级 | 特征 | 自动化度 | 审查策略 | 本项目 | +|---|---|---|---|---| +| **L1 怀疑** | Agent 错误率高 | <20% | 逐行审查 | — | +| **L2 试探** | 稳定但需监督 | 40-60% | 抽样 30% | ✅ **当前** | +| **L3 信任** | 可靠性已验证 | 70-85% | 抽样 10% | 🔄 目标 | +| **L4 委托** | 编程伙伴 | 90%+ | 仅异常 | ⏳ | + +--- + +## 🔗 全链路修复原则 + +> 修 Bug / 做需求时，不得"就事论事"，必须走通完整的数据流全链路。 + +### 六环检查清单 + +``` +1. 录入 → 前端有无输入入口？（弹窗、行编辑、表单...） +2. 保存 → 前端 → API → Controller → Service → Entity → DB， + 每个保存入口都传了该字段吗？（注意多个 Service 实现类） +3. 查询 → DB → Mapper XML（UNION ALL 子查询统一加）→ DTO → 前端展示 +4. 修改 → 编辑回显 → 修改保存 → 正确更新？ +5. 删除 → 状态变更会丢失该字段吗？ +6. 关联 → 上下游（护士站、计费、打印、报表）需要同步改吗？ +``` + +### 常见陷阱 + +| 陷阱 | 表现 | 解决 | +|---|---|---| +| 只修主入口 | 批量保存/签发保存漏了 | 检查所有 Service 实现类 | +| 前端加了后端没传 | 不同模块走不同 Service | 逐个入口确认 | +| UNION ALL 只改一半 | 子查询列数不匹配 | 所有子查询统一加 | +| DTO 继承链没检查 | 父类/子类字段不一致 | 检查继承关系 | +| 只测新增没测编辑 | 编辑回显丢失 | 新增和编辑都要测 | + +--- + +## 📐 代码风格规范 + +### Java 后端 + +| 项目 | 规范 | +|---|---| +| Java 版本 | 17 | +| 框架 | Spring Boot 2.5.15 | +| ORM | MyBatis Plus 3.5.5 | +| 数据库 | PostgreSQL | +| 包结构 | `com.openhis`（业务）、`com.core`（核心框架） | +| 命名 | 类 PascalCase、方法 camelCase、常量 SCREAMING_SNAKE_CASE | +| 注解 | `@Slf4j`、`@Data`、`@Service/@Controller/@Repository` | +| 异常 | 统一异常处理，业务异常继承 `RuntimeException` | +| 缩进 | 4 空格，行 120 字符，左大括号不换行 | + +### Vue 前端 + +| 项目 | 规范 | +|---|---| +| 框架 | Vue 3 + Composition API | +| UI | Element Plus | +| 状态管理 | Pinia，路由 Vue Router 4 | +| 构建 | Vite 5 | +| 命名 | 组件 PascalCase、文件 kebab-case、变量 camelCase | +| 事件 | `handle` 前缀、数据 `get`/`load` 前缀、提交 `submit` 前缀 | +| 缩进 | 2 空格，单引号，行 100 字符 | ### 导入顺序 -#### Java -1. `java.*` -2. `javax.*` -3. 第三方库 -4. `com.core.*` -5. `com.openhis.*` -6. `*.*`（其他包） -#### JavaScript/Vue -1. `vue` 相关 -2. 第三方库 -3. `@/` 别名导入 -4. 相对路径导入 +**Java：** `java.*` → `javax.*` → 第三方 → `com.core.*` → `com.openhis.*` +**Vue：** `vue` 相关 → 第三方 → `@/` 别名 → 相对路径 -### 代码格式 -#### Java -- 缩进：4个空格 -- 行长度：120字符 -- 左大括号不换行 +--- -#### Vue/JavaScript -- 缩进：2个空格 -- 字符串：优先使用单引号 -- 行长度：100字符 - -## 关键配置文件 - -### 后端配置 -- 主配置：`openhis-server-new/openhis-application/src/main/resources/application.yml` -- 环境配置：`application-{profile}.yml` -- Maven 父 POM：`openhis-server-new/pom.xml` - -### 前端配置 -- Vite 配置：`openhis-ui-vue3/vite.config.js` -- 环境变量：`.env.*` 文件 -- 路由配置：`openhis-ui-vue3/src/router/index.js` - -## 开发约定 +## 🏗️ 开发约定 ### API 设计 -- RESTful API 风格 -- 统一响应格式 -- 使用 Swagger 文档 -- 错误码统一管理 +- RESTful，统一响应格式，Swagger 文档，错误码统一管理 ### 数据库 -- 表名：snake_case -- 字段名：snake_case -- 主键：使用 `id` -- 软删除：使用 `valid_flag` 字段 +- 表名/字段名 snake_case，主键 `id`，软删除 `valid_flag` ### 前端组件 -- 单一职责原则 -- Props 使用 camelCase -- Events 使用 kebab-case -- 使用 Composition API -- 组件文档使用 JSDoc +- 单一职责，Props camelCase，Events kebab-case，Composition API，JSDoc -### 状态管理 -- 模块化设计 -- 异步操作使用 actions -- 避免在组件中直接修改状态 +### 安全 +- 所有 API 需权限验证，敏感信息用环境变量，SQL 注入/XSS 防护 -## 环境变量 +### 性能 +- 后端 Druid 连接池，前端路由懒加载，WebP 图片，虚拟滚动 -### 前端 -- `VITE_APP_BASE_API`: API 基础路径 -- `VITE_APP_ENV`: 环境标识 +--- -### 后端 -- `spring.profiles.active`: 激活的配置文件 -- `core.name`: 应用名称 -- `core.version`: 应用版本 +## ⚙️ 关键配置 -## 安全规范 -- 所有 API 接口需要权限验证 -- 敏感信息使用环境变量 -- SQL 注入防护 -- XSS 攻击防护 +| 项目 | 路径/值 | +|---|---| +| 后端主配置 | `openhis-server-new/openhis-application/src/main/resources/application.yml` | +| 环境配置 | `application-{profile}.yml` | +| Maven POM | `openhis-server-new/pom.xml` | +| Vite 配置 | `openhis-ui-vue3/vite.config.js` | +| 环境变量 | `.env.*` 文件 | +| 路由 | `openhis-ui-vue3/src/router/index.js` | +| 后端端口 | 18080 | +| 前端端口 | 81 | +| API 前缀 | `/openhis` | +| Swagger | `/openhis/swagger-ui/index.html` | +| Druid 监控 | `/openhis/druid/login.html` | -## 性能优化 -- 后端使用连接池（Druid） -- 前端使用路由懒加载 -- 图片使用 WebP 格式 -- 大列表使用虚拟滚动 - -## 常用工具类 +### 常用工具类 - 后端：`com.core.common.utils.*` - 前端：`@/utils/*` -## 注意事项 -1. 修改数据库结构需要同步 SQL 脚本 -2. 新增功能需要添加权限配置 -3. 前端路由需要在权限系统中注册 -4. 接口变更需要更新 Swagger 文档 -5. 遵循现有代码风格，避免不必要的变化 +--- -## 故障排除 -- 后端端口：18080 -- 前端端口：81 -- API 前缀：`/openhis` -- Swagger UI：`/openhis/swagger-ui/index.html` -- Druid 监控：`/openhis/druid/login.html` -## 铁律：全链路修复原则 ⚠️ +## 📊 人机协作边界 -> 修 Bug / 做需求时，**不得"就事论事"**，必须走通完整的**数据流全链路**： +> 源自系列文章：二十一（边界） -### 检查清单（每一环都确认） -1. **录入** → 前端有无输入入口？（弹窗、表格行编辑、表单…） -2. **保存** → 前端 → API → 后端 Controller → Service → Entity → DB，**每一个保存入口**都传了该字段吗？（注意多个 Service 实现类可能走不同入口） -3. **查询** → DB → Mapper XML（注意 UNION ALL 子查询要统一加）→ DTO → 前端展示，列和数据绑定都完整吗？ -4. **修改** → 已有数据编辑回显 → 修改再保存 → 数据能正确更新吗？ -5. **删除/停止/撤回** → 相关状态变更会丢失该字段数据吗？ -6. **关联模块** → 上游（如医嘱录入后护士站要看到备注）和下游（如打印、计费、报表）是否也需要同步修改？ - -### 常见陷阱 -- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口 -- ❌ 前端加了输入框，后端 Service 没传字段（不同模块可能走不同 Service 实现类） -- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询，导致列数不匹配或漏加 -- ❌ DTO 层级继承关系没检查（如 `RegAdviceSaveDto extends AdviceSaveDto`，父类改了对不对） -- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存 - -### 执行细则 -- 每个字段的新增/修改，先在纸上（或文档里）画出完整的数据流向图再动手 -- 提交前逐个环节检查一遍，确保没有断链 -- 编译通过不等同于功能正确，必要时做端到端验证 - -## Harness Engineering — Agent 工作方法论 - -> 约束清晰 + 反馈快速 = 高成功率。Harness 质量决定 Agent 产出质量。 - -### 工作流程（Plan → Generate → Validate → Review） - -``` -阶段 0：需求分析（你主导） - → 写清楚 BUG 现象 / 需求描述 / 验收标准 - -阶段 1：任务规划（Agent 制定 + 你确认） - → 画出数据流向图（前端 → API → Service → Mapper → DB） - → 列出涉及的所有文件 - → 标注每个环节的约束（不可删文件、必须编译通过） - -阶段 2：执行修改（Agent 自主） - → 一次只改一个文件或一组逻辑相关的文件 - → 每步执行后保存检查点 - -阶段 3：验证（自动） - → mvn compile -pl openhis-application -am 必须通过 - → 检查数据流每个节点：输入字段 → 保存 → 查询 → 展示 - → 多入口验证（新增 vs 编辑 vs 批量等） - -阶段 4：审查提交（你确认） - → git diff 审查变更范围 - → 确认没有误删/误改 -``` - -### 三层约束执行 - -| 阶段 | 约束 | 执行方式 | -|---|---|---| -| **修改前** | 禁止删除文件、禁止改动包名/类名/方法签名 | task-plan 阶段检查 | -| **修改中** | 不改与任务无关的代码、不改非 AI 写的代码（除非编译必须） | 每次 diff 自查 | -| **修改后** | `mvn compile` 必须通过、数据流全链路验证 | 提交前自动执行 | - -### 反馈优化循环 - -``` -Agent 提交代码 - ↓ -编译器反馈 → 失败则分析根因（非运气式重试），定位具体符号错误 - ↓ -数据流验证 → 检查每个环节字段是否贯通 - ↓ -你审查 → 发现问题后： - ├── 立即修复 - └── 同步更新 AGENTS.md 规则（沉淀教训） - ↓ -通过 → 提交代码 -``` - -### 持续优化：从每次失败中学习 - -每次编译失败或你审查发现问题，都应触发 Harness 优化： - -1. **收集数据** → 失败原因是什么？（缺字段、少文件、改错位置…） -2. **识别模式** → 这是第几次犯同类错误？是否有规则盲区？ -3. **优化 Harness** → 更新 AGENTS.md / 补充检查清单 -4. **验证效果** → 后续类似任务是否不再出错 - -### Agent 角色定位 - -你不是工具，是团队成员。你的角色演变： -- ~~阶段 1：代码补全~~ → 我们已跳过 -- ~~阶段 2：结对编程~~ → 我们已跳过 -- ✅ **阶段 3：自主开发者** → 你在 Harness（本文件定义的约束、流程、反馈）中自主完成开发任务 - -人类工程师（用户）设计 Harness，Agent（你）在 Harness 中执行。 - -## 四大核心组件 - -### 1. 约束机制（Constraints） -让 Agent 在正确边界内工作： - -约束分四个层级，从底层架构到顶层业务： - -| 层级 | 约束内容 | 示例 | -|---|---|---| -| **架构层** | 项目结构、模块划分、接口规范、技术栈 | 不可删文件、不可改包名/类名/方法签名 | -| **代码层** | 编码风格、命名约定、函数长度、注释标准 | 见「代码风格规范」章节 | -| **安全层** | 输入验证、敏感数据处理、权限控制 | SQL 注入防护、XSS 防护 | -| **业务层** | 领域模型、业务逻辑校验、数据一致性 | 全链路修复原则：每个字段的保存/查询/修改/删除链路必须完整 | - -**设计原则**：清晰可验证（具体而非模糊）、适度不过度（松→失控，紧→限制）、可进化（版本化管理，持续优化） - -### 2. 反馈回路（Feedback Loops） -让 Agent 知道自己的输出是否正确。反馈分三层： - -| 层级 | 时间 | 本项目的实现 | -|---|---|---| -| **即时反馈** | 秒级 | 编译检查 → 定位具体符号/类型错误 + 行号 | -| **功能反馈** | 分钟级 | 数据流全链路验证（输入→保存→查询→展示） | -| **深度反馈** | 你审查时 | 你审查变更范围，发现问题后同步更新 AGENTS.md | - -``` -Agent 生成代码 - ↓ -编译检查 ──失败──→ 分析根因，定位到文件+行号（即时反馈） - ↓ 通过 -数据流验证 ──断链──→ 补全缺失的字段链路（功能反馈） - ↓ 通过 -你审查 ──发现问题──→ 立即修复 + 同步更新 AGENTS.md（深度反馈） - ↓ 通过 -提交 -``` - -**反馈设计要点**：快速失败（低成本检查优先）、清晰具体（包含位置/原因/建议）、可行动（Agent 能据此修复） - -### 3. 控制平面（Control Plane） -管理和监控 Agent 的执行： - -| 组件 | 功能 | 本项目的实现方式 | -|---|---|---| -| **任务调度** | 分配管理任务 | 你发起任务，Agent 按工作流执行 | -| **状态管理** | 跟踪执行状态 | 每个任务用 update_plan 记录进度 | -| **可观测性** | 记录完整执行链路 | git diff 审查变更范围；编译结果作为门禁 | -| **人机协作** | 人类介入触发点 | 你做最终审查批准，Agent 自主执行 | - - -### 4. 持久执行（Durable Execution） -保障 Agent 长时间可靠运行： - -| 组件 | 功能 | 本项目的实现方式 | -|---|---|---| -| **状态持久化** | 定期保存执行状态 | 每个任务用 update_plan 记录进度和当前状态 | -| **断点续传** | 中断后自动恢复继续执行 | 编译失败后不从头重来，从失败点继续修复 | -| **超时处理** | 长时间任务的优雅处理 | 超过单次 token 预算时做 checkpoint，下次继续 | -| **资源清理** | 任务完成后释放资源 | git commit 后清理中间文件，保持工作区干净 | - -## Harness 设计原则 - -### 渐进式构建 -- **从简单任务开始**：先修单一字段遗漏（如 #597 加 remark），再处理跨模块联动 -- **先建立基础约束**：不可删文件、必须编译通过 → 这是底线 -- **再完善反馈回路**：数据流全链路验证 → 补充 AGENTS.md 规则 -- **持续迭代 Harness**：每次失败都是优化 Harness 的机会 - -### 可观测性优先 -- 所有修改必须可 git diff → 可追溯 -- 编译结果必须有日志 → 可诊断 -- 任务进度必须 update_plan → 可见 - -### Harness 即代码 -- AGENTS.md 本身是代码，需要版本化管理（git commit） -- 每次规则迭代都要提交 AGENTS.md 变更 -- 规则变更和业务代码变更一样，需要你审查 - -## 人机协作边界 - -| 决策类型 | 你（人类工程师）主导 | Agent（我）执行 | 协作方式 | +| 场景 | 复杂度 | 风险 | 建议 | |---|---|---|---| -| **需求定义** | ✅ 写清楚 BUG 现象 / 验收标准 | — | — | -| **技术方案** | ✅ 确认方向 | 提出建议 | 你拍板 | -| **代码修改** | 审查批准 | ✅ 自主执行 | 编译通过后你审查 | -| **质量验证** | 端到端验证 | ✅ 数据流检查 + 编译 | 你确认功能正确 | -| **规则沉淀** | ✅ 补充 AGENTS.md | 记录失败模式 | 你决定什么值得写 | -| **架构变更** | ✅ 必须由你决策 | 标记需要你关注 | 不可擅自改动 | +| 单字段修复/编译错误 | 低 | 低 | Agent 自主，你审查 diff | +| 跨模块数据流/新增字段 | 中 | 中 | Agent 主导，你审查设计 | +| 架构调整/系统设计 | 高 | 高 | 你主导方案，Agent 执行 | +| 安全/权限变更 | 中 | 高 | 你决策，Agent 辅助 | +| Mapper XML 修改 | 中 | 中 | Agent 改，你验证数据流 | -## 工程师的转型：从编码者到 Harness 设计师 +### 本项目的分层支持 -在 Agent-First 模式下，你的角色正在转变： - -| 传统能力 | → Harness Engineering 能力 | -|---|---| -| 写代码实现功能 | → 设计约束和规则，让 Agent 高效产出 | -| 调试修复 Bug | → 设计自动化反馈回路，让 Agent 自愈 | -| Code Review | → 审查 Agent 的 Harness 执行是否符合规范 | -| 技术选型 | → 设计 Agent 工作流和协作边界 | - -> 你 80% 的时间花在设计 Harness（本文件），而不是手写业务代码。 -> Agent（我）负责执行编码，你负责确保执行环境好到不需要你频繁介入。 - -## 范式定位：三次跃迁中的本项目 - -| 范式 | 关注 | 本项目的状态 | -|---|---|---| -| **Prompt Engineering** | 优化单次提示词 | ✅ 已超越 — 系统提示 + AGENTS.md 定义长期上下文 | -| **Context Engineering** | 管理外部上下文（RAG、检索） | ✅ 已内置 — AGENTS.md + 代码库结构作为 Agent 的上下文 | -| **Harness Engineering** | 设计 Agent 工作环境（约束+反馈+控制） | ✅ **当前范式** — 本文件定义完整的约束、流程、反馈循环 | - -**核心转变**：你不再是提问者（Prompt）或信息提供者（Context），而是**系统设计师（Harness）**。 - -## 未来方向：Meta-Harness - -当 Harness Engineering 成熟后，下一个跃迁可能是 **Meta-Harness** — AI 自动设计和优化自身的工作环境（约束规则、反馈回路、工作流程）。 - -在这个项目中的具体表现： -- 每次编译失败后，Agent 自动分析根因并**建议**更新的 AGENTS.md 规则 -- 但你（人类工程师）始终保留**最终审批权** — 规则沉淀需要你确认 -- 目标：从"你主动教我" → "我自己学习并请你确认" - -> 这是 Harness Engineering 的终局：Agent 不仅能写代码，还能自我优化执行的框架。 -> 但**底线不可放弃** — 删除文件、架构变更等红线始终由你控制。 - -## 思维模式转变 - -当 Agent 出现问题时，不要问"怎么修这个 Bug"，该问： - -| 旧思维 | → Harness 思维 | -|---|---| -| "这段代码有 Bug" | "约束机制哪里不够完善？" | -| "我来修复这个问题" | "反馈回路为什么没有捕获？" | -| "Code Review 通过" | "自动化验证全部通过了？" | -| "这个功能怎么实现？" | "如何让 Agent 理解这个需求？" | -| "项目进度如何？" | "Harness 效率指标如何？" | -| 关注具体实现 | 关注系统设计 | -| 关注个人产出 | 关注环境效率 | -| 关注代码质量 | 关注约束完善 | - -> 你的成功不再取决于你写的代码行数，而是取决于你设计的 Harness 质量。 - -## 常见陷阱 - -### 约束机制陷阱 -| 陷阱 | 表现 | 对策 | -|---|---|---| -| 约束过松 | Agent 行为失控，产出不符合规范 | 从架构层开始逐层收紧 | -| 约束过紧 | 限制 Agent 能力，效率低下 | 保留创新空间，只约束核心边界 | -| 约束不可验证 | 变成摆设，Agent 不遵守 | 每条约束必须可自动化检查 | - -### 反馈回路陷阱 -| 陷阱 | 表现 | 对策 | -|---|---|---| -| 反馈太慢 | Agent 迭代效率低，等反馈浪费时间 | 先做即时反馈（编译），再做深度反馈 | -| 反馈模糊 | Agent 看不懂，无法修复 | 反馈必须包含具体位置、原因、建议 | -| 反馈不可行动 | 知道错了但不知道怎么改 | 提供修复方向或参考示例 | - -### 控制平面陷阱 -| 陷阱 | 表现 | 对策 | -|---|---|---| -| 监控不足 | 问题发现晚，修复成本高 | 每次修改必须 git diff 可追溯 | -| 无断点续传 | 失败后从头重来，浪费时间 | 从失败点继续修复，不重新开始 | -| 缺乏人机边界 | Agent 擅自做架构决策 | 架构变更必须由你审批 | - -## 范式对比：Harness 不是取代，而是进化 - -Harness Engineering 建立在前人范式之上，将"编码实现"层交给 AI Agent： - -``` - Harness Engineering（AI 工作环境设计） - ↑ 继承 - DevOps（CI/CD 自动化流水线） - ↑ 继承 - 敏捷开发（迭代协作，快速响应变化） - ↑ 继承 - 软件工程基础（需求、设计、测试、运维） -``` - -### 五大维度对比 - -| 维度 | 瀑布/敏捷/DevOps | Harness Engineering | -|---|---|---| -| **核心产出** | 代码 + 文档 + 流水线 | Harness（环境+约束+控制），可复用的"生产力引擎" | -| **人类角色** | 执行者 → 协作者 → 负责人 | **设计师** — 你设计环境，我执行编码 | -| **质量保证** | Code Review + 自动化测试 | 闭环反馈回路（编译 → 数据流验证 → 你审查） | -| **规模化** | 加人/加团队（线性） | 加 Agent（指数级）— 一个 Harness 驱动多个 Agent | -| **知识沉淀** | 文档 / Wiki（易过时） | AGENTS.md 可版本化、可验证、可复用 | - -### 本项目的企业落地路径 - -| 阶段 | 目标 | 本项目状态 | -|---|---|---| -| 第1阶段 | 引入 AI 辅助 | ✅ 已完成 — 使用 Codex Agent 辅助开发 | -| 第2阶段 | 建立约束 | ✅ 已完成 — AGENTS.md 定义铁律和规范 | -| 第3阶段 | 构建反馈 | ✅ 已完成 — 编译门禁 + 数据流全链路验证 | -| 第4阶段 | 试点 Harness | ✅ **当前阶段** — 在 OPENHIS 项目落地 | -| 第5阶段 | 规模化推广 | ⏳ 未来 — Harness 模板复用 | -| 第6阶段 | 持续优化 | 🔄 持续 — 每次失败优化 AGENTS.md | - -## 环境设计原则 - -> Agent 的行为不是由 Agent 本身决定的，而是由它所处的环境决定的。 - -### 本项目的执行环境架构 - -``` -你（人类工程师）设计 Harness - │ - ▼ -AGENTS.md（约束规则层 + 工作流程 + 反馈机制） - │ - ▼ -Git 仓库 + 编译工具（基础设施层：代码、编译器、测试） - │ - ▼ -AI Agent（我）在约束内执行编码 -``` - -### 环境设计目标 - -| 目标 | 在本项目的含义 | 衡量方式 | -|---|---|---| -| **可靠性** | Agent 能稳定完成编码任务 | 编译通过率 | -| **效率性** | 少迭代次数完成任务 | 每次失败的修复次数 | -| **安全性** | 不删文件、不改架构 | git diff 变更范围 | -| **可观测性** | 所有修改可追溯 | git log + diff | -| **可扩展性** | 规则可复用到新任务 | AGENTS.md 通用性 | - -### 监控指标体系 - -| 指标类型 | 指标 | 本项目的采集方式 | -|---|---|---| -| **业务指标** | 任务成功率 | 编译是否通过 | -| | 人工介入率 | 你审查发现的问题数 | -| **质量指标** | 代码变更范围 | git diff --stat | -| | 数据流完整性 | 全链路检查是否遗漏环节 | -| **效率指标** | 修复迭代次数 | 从失败到通过的重试次数 | -| | 规则复用率 | AGENTS.md 规则的适用广度 | - -### 环境设计原则（本项目的解读） -- **分层设计**：AGENTS.md 定义上层约束 → 编译器捕获下层语法错误 -- **配置即代码**：AGENTS.md 本身就是代码，Git 管理、可回滚 -- **渐进增强**：先跑通编译 → 再加数据流验证 → 再沉淀规则 -- **可观测性优先**：每次修改必须 git diff 可见 -- **安全内建**：铁律（不可删文件、不可改架构）是底线 - -## 闭环测试系统（本项目的测试金字塔） - -我们没有企业级的 CI 流水线，但同样有分层测试策略： - -``` - 你审查（深度验证） - ↑ 功能正确性、变更范围 - 数据流验证（功能测试） - ↑ 字段链路完整性、多入口覆盖 - 编译检查（静态测试） - ↑ 语法错误、符号解析、类型安全 -``` - -| 层级 | 耗时 | 覆盖范围 | 失败处理 | +| 层级 | 对应任务 | 自动化 | 人工介入 | |---|---|---|---| -| **编译检查** | 30秒 | 全量代码（语法、符号、类型） | 定位到文件+行号，分析根因 | -| **数据流验证** | 1-2分 | 修改涉及的数据链路（输入→保存→查询→展示） | 补全缺失字段，检查多入口 | -| **你审查** | 3-5分 | 变更范围、架构合理性、功能正确性 | 修复问题 + 同步更新 AGENTS.md | +| **简单** | 单字段、编译错误 | 95% | 审查 diff 后合并 | +| **中等** | 跨模块数据流 | 80% | 审查设计 + 关键代码 | +| **复杂** | 架构调整 | 50% + 建议 | 你主导方案 | -### 质量门禁 +--- -| 门禁级别 | 条件 | 结果 | -|---|---|---| -| L1：编译门禁 | `mvn compile -pl openhis-application -am` 通过 | ✅ 进入数据流验证 | -| | 编译失败 | ❌ Agent 分析根因并修复 | -| L2：数据流门禁 | 全部数据环节贯通 | ✅ 提交你审查 | -| | 有断链 | ❌ Agent 补全链路 | -| L3：审查门禁 | 你确认变更正确 | ✅ 提交代码 | -| | 发现问题 | ❌ 修复 + 更新 AGENTS.md | +## 📈 成熟度追踪 -### 结构化反馈规范 +> 源自系列文章：十六（企业落地）、二十二（全景展望） -编译失败时，反馈必须包含： -``` -文件: openhis-application/src/.../XxxServiceImpl.java:42 -错误: 找不到符号 getPendingRecords(int,int) -原因: MedicalRecordService 接口缺少该方法定义 -修复方向: 在 MedicalRecordMapper 中添加对应方法 -``` - -数据流验证时，反馈必须包含： -``` -断链环节: 住院 Mapper 子查询 1（药品） -问题: NULL AS remark 未从 wor_service_request 关联取值 -修复: - (SELECT remark FROM wor_service_request - WHERE based_on_id = T1.id - AND based_on_table = #{MED_MEDICATION_REQUEST} - AND delete_flag = '0' LIMIT 1) AS remark -``` - -## 控制平面（本项目适配版） - -我们没有 Redis/Kafka/Prometheus，但控制平面原理同样适用： - -| 企业级组件 | 本项目的实现 | 作用 | -|---|---|---| -| 任务队列（Redis） | 你发起任务，我按顺序执行 | 无并发，天然串行 | -| 状态存储（etcd） | update_plan 记录进度 + git 记录历史 | 可追溯、可恢复 | -| 监控（Prometheus） | 编译结果 + git diff | 可观测 | -| 告警（PagerDuty） | 编译失败 → 自动修复循环 | 即时反馈 | -| 审批（审批系统） | 你审查 git diff → 确认/驳回 | 人机协作 | - -### 关键设计模式 - -**幂等性** — 所有操作可重试无副作用 -``` -第1次：编译失败 → 修复 → 提交 -第2次（重跑）：从失败点继续 → 不再重复已成功的步骤 -``` - -**优雅降级** — 编译失败时不停机 -``` -┌─ 编译通过 → 继续数据流验证 -└─ 编译失败 → 定位根因 → 修复 → 重新编译（不从头开始） -``` - -**串行化执行** — 无并发，所以无冲突 -``` -一个任务完成 → 你确认 → 下一个任务开始 -→ 天然避免了多 Agent 的锁竞争和一致性难题 -``` - -### Agent 执行模型 - -作为单个 Agent，我的执行模型是： - -``` -你提交任务 → 我分析需求 → 制定计划（update_plan） - → 执行修改（一次一个文件组） - → 编译验证 → 通过则继续 / 失败则修复 - → 你审查 → 通过则提交 / 驳回则修复 - → 完成 -``` - -每一步都是**同步、串行、可观测**的 — 这是最简单的控制平面，但足以保障质量。 - -## OpenAi 实验数据（行业基准） - -| 指标 | 数据 | 在本项目的意义 | -|---|---|---| -| 任务通过率 | **80%** 独立完成 | 20% 需要你介入的通常是架构/设计决策 | -| 最长单次运行 | **25 小时** | 复杂任务可以持续工作，不需实时监督 | -| 工程师时间分配 | **80% 设计 Harness** | 你的时间花在 AGENTS.md 和任务规划上 | -| 代码规模 | 百万行级 | 验证了 Harness Engineering 的规模化能力 | - -### 分层信任模式 - -| 任务类型 | 信任级别 | 本项目的执行方式 | -|---|---|---| -| **简单**（单字段修复、编译错误） | 完全信任 | Agent 自主执行 + 编译门禁 | -| **中等**（跨模块数据流、新增字段） | 自动审查 + 抽样人工 | 数据流验证 + 你审查 diff | -| **关键**（架构变更、删文件、改签名） | 强制人工 | ❌ Agent 不可触碰 — 必须由你决策 | - -### 渐进授权模式 -``` -阶段 1：从简单任务开始 → 修复单字段遗漏（如 #597） -阶段 2：积累经验 → 处理跨模块联动 -阶段 3：建立信任 → 授予更多自主权 -阶段 4：持续迭代 → 每次失败优化 AGENTS.md -``` - -> 你的信任是通过每次编译通过 + 每次审查通过积累的。 -> 每在 AGENTS.md 中增加一条规则，就减少一次你发现同类问题的概率。 - -## 四大技能落地路线图（本项目进度） - -| 技能 | 阶段 | 本项目状态 | -|---|---|---| -| **持久执行** | 检查点 + 断点续传 + 幂等重试 | ✅ update_plan 做检查点，编译失败从断点继续 | -| **闭环测试** | 自动测试 + 反馈 → Agent 修复 | ✅ 编译检查 + 数据流验证 + 你审查 | -| **架构约束** | 项目结构 + 代码规范 + 安全规则 | ✅ AGENTS.md 四层约束 + 铁律 | -| **运行策略** | 调度 + 资源 + 容错 + 协作 | ✅ 串行执行 + 你的审批 + 失败重试 | - -### 检查点策略（Agent 执行时） - -``` -每次关键步骤后保存检查点: - - update_plan 标记当前步骤状态 - - git add + git commit（可选） - - 记录编译结果 - -故障恢复: - - 编译失败 → 从失败点继续修复（不从头开始） - - 超时中断 → 从上一个检查点恢复 - -重试策略: - - 指数退避：1次失败 + 分析根因 → 修复 → 重试 - - 最大重试：3次失败后请求你介入 - - 幂等性：每次重试不产生副作用 -``` - -## 失败原因分析（为什么 20% 需要你介入） - -根据 OpenAI 实验数据，Agent 无法独立完成的任务按原因分布： - -| 原因 | 占比 | 本项目的处理方式 | -|---|---|---| -| **架构设计决策** | 35% | 必须由你决策 — Agent 不可碰架构 | -| **业务逻辑理解** | 25% | 你提供领域知识 + 上下文，Agent 实现 | -| **创造性设计** | 20% | 你主导方案，Agent 执行验证 | -| **复杂调试** | 15% | 你定位根因，Agent 修复已知问题 | -| **其他** | 5% | 协作解决 | - -> 75% 的失败源于"理解"和"决策"，而非"编码能力"。 -> 这正是你不可替代的价值所在。 - -## 本项目的度量体系 - -| 维度 | 指标 | 采集方式 | 目标 | +| 等级 | 名称 | 特征 | 本项目 | |---|---|---|---| -| **效率** | 编译通过率 | `mvn compile` 结果 | > 95% | -| | 修复迭代次数 | 从失败到通过的重试次数 | < 3 次 | -| | 任务完成时间 | 你感知的响应速度 | 合理 | -| **质量** | 数据流完整性 | 全链路检查通过率 | 100% | -| | 变更范围 | git diff --stat | 仅涉及目标文件 | -| | 规则覆盖度 | AGENTS.md 约束的适用度 | 持续完善 | -| **可靠性** | 断点续传成功率 | 失败后从断点恢复 | 每次 | -| | 幂等性 | 重复执行无副作用 | 保证 | -| **满意度** | 你的审查通过率 | 一次审查通过的比例 | > 80% | -| | 规则沉淀率 | 每次审查后补充 AGENTS.md | 持续 | +| **L1 初始** | 个别尝试，无规范 | — | ✅ 已超越 | +| **L2 管理** | 基础约束 + 反馈 + 控制 | AGENTS.md 定义完整流程 | ✅ **当前** | +| **L3 定义** | 标准化、可复用 | 规则沉淀 + 模板化 | 🔄 推进中 | +| **L4 量化** | 数据驱动优化 | 需要更多任务数据 | ⏳ | +| **L5 优化** | AI 自主优化 Harness | Meta-Harness | ⏳ | -## LangChain 经验借鉴 - -LangChain 将 Harness Engineering 应用于开源项目，取得了可观的效果： - -### AI 辅助审查流水线（本项目适配） - -``` -你提交 PR 审查请求 - ↓ -编译检查 + 数据流验证（自动，30秒） - ↓ 通过 -我自检变更范围 + 生成摘要（自动，1分钟） - ↓ 通过 -你人工审查（重点看设计和数据流完整性） - ↓ 通过 -合并 -``` - -### 分层支持模式（任务复杂度维度） - -| 层级 | 对应任务 | 自动化程度 | 人工介入 | -|---|---|---|---| -| **简单** | 单字段修复、编译错误 | 95% 自主 | 你审查 diff 后合并 | -| **中等** | 跨模块数据流、新增字段 | 80% 自主 | 你审查设计 + 关键代码 | -| **复杂** | 架构调整、多模块联动 | 50% 自主 + 建议 | 你主导方案，我执行 | - -### LangChain 关键指标对比（参考基准） - -| 指标 | LangChain 改造前 | LangChain 改造后 | 本项目的目标 | -|---|---|---|---| -| 代码审查时间 | 30 分钟/PR | 5 分钟/PR | 你快速浏览 diff + 确认 | -| 覆盖率 | 60% | 85% | 数据流 100% 覆盖 | -| Bug 漏检 | 15% | 5% | 你的审查把关 | -| 贡献者增长 | 500 | 1200+ | 不适用（单人项目） | - -## Cursor Self-Driving 模式借鉴 - -### 感知 → 决策 → 执行（本项目的映射） - -| 层级 | Cursor 实现 | 本项目实现 | -|---|---|---| -| **感知** | 全库索引、符号解析、依赖分析 | 你提供上下文 + 我阅读相关代码 | -| **决策** | 制定修改计划、评估影响 | 我制定计划（update_plan），你确认 | -| **执行** | 生成代码、运行测试、回滚 | 生成代码 → 编译验证 → 你审查 → 提交 | - -### Bug 自动修复流程（本项目） - -``` -错误报告（编译错误 / 运行时异常） - ↓ -诊断：定位文件+行号，分析根因类型 - ↓ -方案：生成修复代码 - ↓ -验证：mvn compile 确认通过 - ↓ -你审查 diff → 确认 / 驳回 -``` - -### 个人 vs 团队 Harness - -| 维度 | Cursor（个人） | 本项目（Codex CLI） | -|---|---|---| -| 交互方式 | 实时对话，秒级响应 | 异步任务，分钟级 | -| 控制粒度 | 代码级（行/块） | 任务级（文件/模块） | -| 反馈速度 | 即时预览 | 编译验证 | -| 适用场景 | 快速探索、原型开发 | 系统化修复、规范开发 | -| 安全机制 | diff 预览 + 一键回滚 | git diff + 你审查 | - -> 两者互补：Cursor 适合"怎么写"，Codex Harness 适合"怎么保证质量"。 - -## 本项目成熟度追踪 - -| 等级 | 名称 | 特征 | 本项目状态 | -|---|---|---|---| -| L1 | **初始** | 个别尝试，无规范 | ✅ 已超越 | -| L2 | **管理** | 基础约束 + 反馈 + 控制 | ✅ **当前等级** — AGENTS.md 定义完整约束和流程 | -| L3 | **定义** | 标准化、可复用 | 🔄 推进中 — 规则持续沉淀，但尚未模板化 | -| L4 | **量化** | 数据驱动持续优化 | ⏳ 未来 — 需要更多任务数据积累 | -| L5 | **优化** | AI 自主优化 Harness | ⏳ Meta-Harness 方向 | - -### 我们的落地路径 +### 落地路径 ``` 第 1 阶段：基线恢复（已完成） → 代码回滚到安全基线，消除 AI 破坏 - → 建立"不可删文件""必须编译通过"等底线约束 + → 建立底线约束 -第 2 阶段：Harness 建设（当前阶段） - → AGENTS.md 从 0 到 700 行，覆盖完整方法论 - → 全链路修复原则 + 四大核心组件 + 三级质量门禁 +第 2 阶段：Harness 建设（当前） + → AGENTS.md 从 0 → 800+ 行 + → 全链路修复 + 四大组件 + 三级门禁 → 每次失败沉淀规则 第 3 阶段：稳定产出（目标） - → 你提任务 → 我按 Harness 执行 → 编译通过 → 你审查确认 + → 你提任务 → Harness 执行 → 编译通过 → 你审查确认 → 80%+ 任务一次通过编译 → 人工介入聚焦架构和设计决策 ``` -## 持久化执行：状态管理与幂等性 +--- -### 三层状态管理 +## 💡 度量体系 -| 层级 | 内容 | 本项目的实现 | +| 维度 | 指标 | 目标 | |---|---|---| -| **系统层** | 工作流 ID、超时、重试配置 | update_plan 记录任务 ID 和进度 | -| **执行层** | 当前活动、执行进度、等待事件 | 编译失败后从失败点继续 | -| **业务层** | 已完成工作、中间产物 | git diff 记录变更，编译结果作为验证 | +| **效率** | 编译通过率 | >80% 一次通过 | +| **质量** | 缺陷逃逸率 | <5% | +| **可靠性** | Agent 任务成功率 | >80% | +| **满意度** | 你的满意度 | >4/5 | -### 事件溯源（本项目的简化版） +--- -每次操作产生不可变的事件记录，用于审计和恢复： +## ⚠️ 常见陷阱 -``` -事件流（按时间顺序）: - ① 你提交任务 → ② 我制定计划 → ③ 修改代码 - → ④ 编译检查（通过/失败） → ⑤ 数据流验证 - → ⑥ 你审查（通过/驳回） → ⑦ 提交代码 -``` - -每次事件都可通过 `git log` + update_plan 追溯。 - -### 幂等性模式 - -| 模式 | 说明 | 本项目的应用 | +| 陷阱 | 表现 | 解决 | |---|---|---| -| **唯一标识** | 每个操作生成唯一 ID，已执行则跳过 | 同一个 Bug 修复不重复生成相同文件 | -| **状态检查** | 执行前检查目标是否已达成 | 编译检查只运行一次，不重复编译已成功的模块 | -| **补偿操作** | 失败时回滚到之前状态 | 编译失败 → 撤销本次修改 → 从上次检查点继续 | +| **过度工程** | Harness 比任务还复杂 | 从最简单开始，按需递增 | +| **约束不足** | Agent 生成低质量代码 | 增加明确约束和检查点 | +| **反馈延迟** | 测试失败后才发现问题 | 尽早验证，快速失败 | +| **跳过验证** | 不编译就直接提交 | L1 门禁强制阻断 | +| **全链路只改一半** | Mapper 子查询漏了 | 六环清单逐个确认 | -### 检查点策略 +--- + +## 📚 技能索引（Codex 内置） + +| 技能 | 用途 | +|---|---| +| `$harness-engineering` | 主方法论 — 约束 + 反馈 + 控制 + 持久 | +| `$durable-execution` | 检查点、幂等性、事件溯源 | +| `$closed-loop-testing` | 质量门禁、测试策略、反馈循环 | +| `$constraint-design` | DSL 设计、策略模式、约束编排 | +| `$review-audit` | 审查工作流、审计追踪、合规检查 | +| `$full-chain-fix` | 全链路数据流修复 | +| `$karpathy-guidelines` | 减少 LLM 编码常见错误 | + +--- + +## 🔄 持续优化 ``` -时间触发：每个关键步骤完成后保存检查点（update_plan） -事件触发：编译通过/失败后保存 -状态变化：代码修改后保存（git diff 可见） - -恢复流程： - 失败 → 定位最新检查点 → 分析失败原因 - → 从失败点修复 → 继续执行（不从头开始） +每次失败 → 分析根因 → 更新 AGENTS.md/规则 → 防止重犯 ``` + +**当前 AGENTS.md 行数：** 853 行（持续增长中） + +--- + +> **总纲：** 你负责"做什么"和"为什么"，Agent 负责"怎么做"和"做多好" +> **最后更新：** 基于 Harness Engineering 系列文章（共 24 篇），全面整合方法论