wangyizhe/his

Fork 0

Files

zhaoyun ebf6d803a9 docs: add maturity tracker L1-L5 and adoption path for this project

2026-05-28 14:45:57 +08:00

31 KiB

Executable File

Raw Blame History

OpenHIS - AI Agent Development Guide

项目概览

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

构建和运行命令

后端（Java/Spring Boot）

# 构建整个项目
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）

# 安装依赖
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

java.*
javax.*
第三方库
com.core.*
com.openhis.*
*.*（其他包）

JavaScript/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 文档
错误码统一管理

数据库

表名：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/*

注意事项

修改数据库结构需要同步 SQL 脚本
新增功能需要添加权限配置
前端路由需要在权限系统中注册
接口变更需要更新 Swagger 文档
遵循现有代码风格，避免不必要的变化

故障排除

后端端口：18080
前端端口：81
API 前缀：/openhis
Swagger UI：/openhis/swagger-ui/index.html
Druid 监控：/openhis/druid/login.html

铁律：全链路修复原则 ⚠️

修 Bug / 做需求时，不得"就事论事"，必须走通完整的数据流全链路：

检查清单（每一环都确认）

录入 → 前端有无输入入口？（弹窗、表格行编辑、表单…）
保存 → 前端 → API → 后端 Controller → Service → Entity → DB，每一个保存入口都传了该字段吗？（注意多个 Service 实现类可能走不同入口）
查询 → DB → Mapper XML（注意 UNION ALL 子查询要统一加）→ DTO → 前端展示，列和数据绑定都完整吗？
修改 → 已有数据编辑回显 → 修改再保存 → 数据能正确更新吗？
删除/停止/撤回 → 相关状态变更会丢失该字段数据吗？
关联模块 → 上游（如医嘱录入后护士站要看到备注）和下游（如打印、计费、报表）是否也需要同步修改？

常见陷阱

❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
❌ 前端加了输入框，后端 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 优化：

收集数据 → 失败原因是什么？（缺字段、少文件、改错位置…）
识别模式 → 这是第几次犯同类错误？是否有规则盲区？
优化 Harness → 更新 AGENTS.md / 补充检查清单
验证效果 → 后续类似任务是否不再出错

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%+ 任务一次通过编译
  → 人工介入聚焦架构和设计决策

31 KiB Executable File Raw Blame History Unescape Escape

OpenHIS - AI Agent Development Guide

项目概览

构建和运行命令

后端（Java/Spring Boot）

前端（Vue 3 + Vite）

测试

代码风格规范

Java 后端规范

Vue 前端规范

导入顺序

Java

JavaScript/Vue

代码格式

Java

Vue/JavaScript

关键配置文件

后端配置

前端配置

开发约定

API 设计

数据库

前端组件

状态管理

环境变量

前端

后端

安全规范

性能优化

常用工具类

注意事项

故障排除

铁律：全链路修复原则 ⚠️

检查清单（每一环都确认）

常见陷阱

执行细则

Harness Engineering — Agent 工作方法论

工作流程（Plan → Generate → Validate → Review）

三层约束执行

反馈优化循环

持续优化：从每次失败中学习

Agent 角色定位

四大核心组件

1. 约束机制（Constraints）

2. 反馈回路（Feedback Loops）

3. 控制平面（Control Plane）

4. 持久执行（Durable Execution）

Harness 设计原则

渐进式构建

可观测性优先

Harness 即代码

人机协作边界

工程师的转型：从编码者到 Harness 设计师

范式定位：三次跃迁中的本项目

未来方向：Meta-Harness

思维模式转变

常见陷阱

约束机制陷阱

反馈回路陷阱

控制平面陷阱

范式对比：Harness 不是取代，而是进化

五大维度对比

本项目的企业落地路径

环境设计原则

本项目的执行环境架构

环境设计目标

监控指标体系

环境设计原则（本项目的解读）

闭环测试系统（本项目的测试金字塔）

质量门禁

结构化反馈规范

控制平面（本项目适配版）

关键设计模式

Agent 执行模型

OpenAi 实验数据（行业基准）

分层信任模式

渐进授权模式

四大技能落地路线图（本项目进度）

检查点策略（Agent 执行时）

失败原因分析（为什么 20% 需要你介入）

31 KiB

Executable File

Raw Blame History