Files

zhaoyun d3ebbf9a3c refactor(AGENTS.md): restructure under Harness Engineering framework

- 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

2026-05-28 14:58:22 +08:00

14 KiB

Executable File

Raw Blame History

OpenHIS — Harness Engineering 开发指南

模型决定上限，Harness 决定底线。 本文件是 OpenHIS 项目的 Harness Engineering 落地。基于 24 篇系列文章方法论，为 AI Agent 提供完整的工作环境和约束规则。

📋 项目信息

OpenHIS 是一个医院管理系统，Java 17 + Spring Boot 后端 + Vue 3 + Vite 前端 + PostgreSQL。

构建和运行

# 后端构建
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）

每个关键步骤保存检查点，失败后恢复：

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/*

📊 人机协作边界