# OpenHIS - AI Agent Development Guide

## 项目概览
OpenHIS 是一个医院管理系统，采用 Java 17 + Spring Boot 后端和 Vue 3 + Vite 前端架构。

## 构建和运行命令

### 后端（Java/Spring Boot）
```bash
# 构建整个项目
cd openhis-server-new
mvn clean package -DskipTests

# 运行后端（开发模式）
cd openhis-server-new/openhis-application
mvn spring-boot:run

# 运行特定模块
cd openhis-server-new/[module-name]
mvn spring-boot:run
```

### 前端（Vue 3 + Vite）
```bash
# 安装依赖
cd openhis-ui-vue3
npm install

# 开发服务器
npm run dev

# 生产构建
npm run build:prod

# 测试环境构建
npm run build:test

# 预览构建结果
npm run preview
```

### 测试
项目当前没有配置正式的测试框架。如需添加测试：
- 后端：考虑使用 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`

### 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` 前缀

### 导入顺序
#### Java
1. `java.*`
2. `javax.*`
3. 第三方库
4. `com.core.*`
5. `com.openhis.*`
6. `*.*`（其他包）

#### JavaScript/Vue
1. `vue` 相关
2. 第三方库
3. `@/` 别名导入
4. 相对路径导入

### 代码格式
#### 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 文档
- 错误码统一管理

### 数据库
- 表名：snake_case
- 字段名：snake_case
- 主键：使用 `id`
- 软删除：使用 `valid_flag` 字段

### 前端组件
- 单一职责原则
- Props 使用 camelCase
- Events 使用 kebab-case
- 使用 Composition API
- 组件文档使用 JSDoc

### 状态管理
- 模块化设计
- 异步操作使用 actions
- 避免在组件中直接修改状态

## 环境变量

### 前端
- `VITE_APP_BASE_API`: API 基础路径
- `VITE_APP_ENV`: 环境标识

### 后端
- `spring.profiles.active`: 激活的配置文件
- `core.name`: 应用名称
- `core.version`: 应用版本

## 安全规范
- 所有 API 接口需要权限验证
- 敏感信息使用环境变量
- SQL 注入防护
- XSS 攻击防护

## 性能优化
- 后端使用连接池（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 | 记录失败模式 | 你决定什么值得写 |
| **架构变更** | ✅ 必须由你决策 | 标记需要你关注 | 不可擅自改动 |

## 工程师的转型：从编码者到 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 |

### 质量门禁

| 门禁级别 | 条件 | 结果 |
|---|---|---|
| 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 | 持续 |

## 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 行，覆盖完整方法论
  → 全链路修复原则 + 四大核心组件 + 三级质量门禁
  → 每次失败沉淀规则

第 3 阶段：稳定产出（目标）
  → 你提任务 → 我按 Harness 执行 → 编译通过 → 你审查确认
  → 80%+ 任务一次通过编译
  → 人工介入聚焦架构和设计决策
```