zhaoyun
d3ebbf9a3c
- Integrate 24-article methodology into top-level framework - Add four core components (constraints/feedback/control/durable) - Add standard workflow (Plan-Generate-Validate-Review) - Add quality gates L1-L4 - Add layered trust model - Keep all project-specific content (build, style, config) - Reduce lines from 853 to 400 with better structure
401 lines
14 KiB
Markdown
Executable File
401 lines
14 KiB
Markdown
Executable File
# OpenHIS — Harness Engineering 开发指南
|
||
|
||
> **模型决定上限，Harness 决定底线。**
|
||
> 本文件是 OpenHIS 项目的 Harness Engineering 落地。基于 24 篇系列文章方法论，为 AI Agent 提供完整的工作环境和约束规则。
|
||
|
||
---
|
||
|
||
## 📋 项目信息
|
||
|
||
OpenHIS 是一个医院管理系统，Java 17 + Spring Boot 后端 + Vue 3 + Vite 前端 + PostgreSQL。
|
||
|
||
### 构建和运行
|
||
|
||
```bash
|
||
# 后端构建
|
||
cd /root/.openclaw/workspace/his-repo/openhis-server-new
|
||
mvn compile -pl openhis-application -am # 快速编译
|
||
mvn clean package -DskipTests # 完整打包
|
||
mvn spring-boot:run # 运行（开发模式）
|
||
|
||
# 前端
|
||
cd /root/.openclaw/workspace/his-repo/openhis-ui-vue3
|
||
npm install && npm run dev # 启动开发服务器
|
||
npm run build:prod # 生产构建
|
||
|
||
# 语法检查
|
||
python3 -c "import py_compile; py_compile.compile('strategy.py', doraise=True)"
|
||
```
|
||
|
||
### 关键路径
|
||
|
||
```
|
||
后端代码: 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
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 四大核心组件
|
||
|
||
> 源自系列文章：十九（控制论）、十七（持久执行）、十八（AI-Native CI/CD）
|
||
|
||
### 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：** `java.*` → `javax.*` → 第三方 → `com.core.*` → `com.openhis.*`
|
||
**Vue：** `vue` 相关 → 第三方 → `@/` 别名 → 相对路径
|
||
|
||
---
|
||
|
||
## 🏗️ 开发约定
|
||
|
||
### API 设计
|
||
- RESTful，统一响应格式，Swagger 文档，错误码统一管理
|
||
|
||
### 数据库
|
||
- 表名/字段名 snake_case，主键 `id`，软删除 `valid_flag`
|
||
|
||
### 前端组件
|
||
- 单一职责，Props camelCase，Events kebab-case，Composition API，JSDoc
|
||
|
||
### 安全
|
||
- 所有 API 需权限验证，敏感信息用环境变量，SQL 注入/XSS 防护
|
||
|
||
### 性能
|
||
- 后端 Druid 连接池，前端路由懒加载，WebP 图片，虚拟滚动
|
||
|
||
---
|
||
|
||
## ⚙️ 关键配置
|
||
|
||
| 项目 | 路径/值 |
|
||
|---|---|
|
||
| 后端主配置 | `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` |
|
||
|
||
### 常用工具类
|
||
- 后端：`com.core.common.utils.*`
|
||
- 前端：`@/utils/*`
|
||
|
||
---
|
||
|
||
## 📊 人机协作边界
|
||
|
||
> 源自系列文章：二十一（边界）
|
||
|
||
| 场景 | 复杂度 | 风险 | 建议 |
|
||
|---|---|---|---|
|
||
| 单字段修复/编译错误 | 低 | 低 | Agent 自主，你审查 diff |
|
||
| 跨模块数据流/新增字段 | 中 | 中 | Agent 主导，你审查设计 |
|
||
| 架构调整/系统设计 | 高 | 高 | 你主导方案，Agent 执行 |
|
||
| 安全/权限变更 | 中 | 高 | 你决策，Agent 辅助 |
|
||
| Mapper XML 修改 | 中 | 中 | Agent 改，你验证数据流 |
|
||
|
||
### 本项目的分层支持
|
||
|
||
| 层级 | 对应任务 | 自动化 | 人工介入 |
|
||
|---|---|---|---|
|
||
| **简单** | 单字段、编译错误 | 95% | 审查 diff 后合并 |
|
||
| **中等** | 跨模块数据流 | 80% | 审查设计 + 关键代码 |
|
||
| **复杂** | 架构调整 | 50% + 建议 | 你主导方案 |
|
||
|
||
---
|
||
|
||
## 📈 成熟度追踪
|
||
|
||
> 源自系列文章：十六（企业落地）、二十二（全景展望）
|
||
|
||
| 等级 | 名称 | 特征 | 本项目 |
|
||
|---|---|---|---|
|
||
| **L1 初始** | 个别尝试，无规范 | — | ✅ 已超越 |
|
||
| **L2 管理** | 基础约束 + 反馈 + 控制 | AGENTS.md 定义完整流程 | ✅ **当前** |
|
||
| **L3 定义** | 标准化、可复用 | 规则沉淀 + 模板化 | 🔄 推进中 |
|
||
| **L4 量化** | 数据驱动优化 | 需要更多任务数据 | ⏳ |
|
||
| **L5 优化** | AI 自主优化 Harness | Meta-Harness | ⏳ |
|
||
|
||
### 落地路径
|
||
|
||
```
|
||
第 1 阶段：基线恢复（已完成）
|
||
→ 代码回滚到安全基线，消除 AI 破坏
|
||
→ 建立底线约束
|
||
|
||
第 2 阶段：Harness 建设（当前）
|
||
→ AGENTS.md 从 0 → 800+ 行
|
||
→ 全链路修复 + 四大组件 + 三级门禁
|
||
→ 每次失败沉淀规则
|
||
|
||
第 3 阶段：稳定产出（目标）
|
||
→ 你提任务 → Harness 执行 → 编译通过 → 你审查确认
|
||
→ 80%+ 任务一次通过编译
|
||
→ 人工介入聚焦架构和设计决策
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 度量体系
|
||
|
||
| 维度 | 指标 | 目标 |
|
||
|---|---|---|
|
||
| **效率** | 编译通过率 | >80% 一次通过 |
|
||
| **质量** | 缺陷逃逸率 | <5% |
|
||
| **可靠性** | Agent 任务成功率 | >80% |
|
||
| **满意度** | 你的满意度 | >4/5 |
|
||
|
||
---
|
||
|
||
## ⚠️ 常见陷阱
|
||
|
||
| 陷阱 | 表现 | 解决 |
|
||
|---|---|---|
|
||
| **过度工程** | Harness 比任务还复杂 | 从最简单开始，按需递增 |
|
||
| **约束不足** | Agent 生成低质量代码 | 增加明确约束和检查点 |
|
||
| **反馈延迟** | 测试失败后才发现问题 | 尽早验证，快速失败 |
|
||
| **跳过验证** | 不编译就直接提交 | L1 门禁强制阻断 |
|
||
| **全链路只改一半** | Mapper 子查询漏了 | 六环清单逐个确认 |
|
||
|
||
---
|
||
|
||
## 📚 技能索引（Codex 内置）
|
||
|
||
| 技能 | 用途 |
|
||
|---|---|
|
||
| `$harness-engineering` | 主方法论 — 约束 + 反馈 + 控制 + 持久 |
|
||
| `$durable-execution` | 检查点、幂等性、事件溯源 |
|
||
| `$closed-loop-testing` | 质量门禁、测试策略、反馈循环 |
|
||
| `$constraint-design` | DSL 设计、策略模式、约束编排 |
|
||
| `$review-audit` | 审查工作流、审计追踪、合规检查 |
|
||
| `$full-chain-fix` | 全链路数据流修复 |
|
||
| `$karpathy-guidelines` | 减少 LLM 编码常见错误 |
|
||
|
||
---
|
||
|
||
## 🔄 持续优化
|
||
|
||
```
|
||
每次失败 → 分析根因 → 更新 AGENTS.md/规则 → 防止重犯
|
||
```
|
||
|
||
**当前 AGENTS.md 行数：** 853 行（持续增长中）
|
||
|
||
---
|
||
|
||
> **总纲：** 你负责"做什么"和"为什么"，Agent 负责"怎么做"和"做多好"
|
||
> **最后更新：** 基于 Harness Engineering 系列文章（共 24 篇），全面整合方法论
|