# harness

**Repository Path**: elfbobo_admin_admin/harness

## Basic Information

- **Project Name**: harness
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 7
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Harness 组件化演示工程

## 项目定位

**Harness** 是一个全栈组件化演示工程，是 AI 编程书籍《[Qoder 从入门到精通](https://qoder.jibao168.com/)》与《[Agent 从入门到精通](https://agent.jibao168.com/)》配套的落地实操项目。

项目以"记忆管理（Memory）+ 用户管理（User）"为核心业务载体，完整呈现了从数据库建表、后端组件化编排、前端四层架构到集成测试的**全生命周期工程实践**。它不仅是业务演示，更是一套可复用的**工程脚手架**，演示了如何在大型工程中通过合理的架构设计约束 AI 的行为边界，实现人机高效协同。

> `Harness` 一词源自大模型工程化中的"约束框架"概念——在大模型固有缺陷（偏好、无边界、迎合用户、一根筋、偷懒）之外，通过工程手段套上一层约束缰绳，让 AI 输出可控、可靠、可验证。

## 背景：为什么需要 Harness

在《Qoder 从入门到精通》中，我们提出了 AI 编码辅助的三个演进阶段：

| 阶段 | 核心问题 | 解决方案 |
|------|---------|---------|
| 提示词工程 | 模型听不懂 | 设计精确指令 |
| 上下文工程 | 模型记不住 | 管理对话历史 |
| **Harness 工程** | **模型管不住** | **约束行为边界** |

大模型有五个固有缺陷：有自己的编码偏好、没有边界意识、会迎合用户、会在错误方向死磕、会搭框架不写实现。这三个阶段不是替代关系，而是**叠加关系**——Harness 工程建立在提示词工程和上下文工程之上，用架构约束、规范覆盖、独立验证等手段，**驾驭** AI 而非仅仅**使用** AI。

这个工程就是 Harness 工程思想的具体实践。

## 技术栈

| 层 | 技术 | 版本 |
|----|------|------|
| 后端框架 | Java + Spring Boot | 17 / 3.2.0 |
| ORM | MyBatis（mybatis-spring-boot-starter） | 3.0.3 |
| 数据库 | MySQL | 8.0 |
| 前端框架 | React + TypeScript | 18 / 5.3 |
| UI 组件库 | Ant Design | 5.12 |
| 后端构建 | Maven | - |
| 前端构建 | Vite | 5.0 |
| HTTP 客户端 | Axios | 1.6 |
| 路由 | React Router DOM | 6.20 |

## 核心架构

### 后端：Maven 多模块 + 组件化架构

后端采用接口/实现分离的组件化设计，严格遵守单向依赖链：

```
api (Controller) ──→ business (BizService) ──→ component-*/interfaces
                                                    ↓
                                      domain (Entity + Mapper) ←── component-*/implementations
                                           ↑
                                      framework (基础工具类，零外部依赖)
```

| 模块 | 职责 | 依赖 |
|------|------|------|
| `harness-api` | Controller、Form、启动入口 | business + component interfaces |
| `harness-business` | BizService 业务编排 | domain + component implementations |
| `harness-domain` | Entity、Mapper、DO、分页对象 | framework（零外部依赖） |
| `harness-component-*` | 可插拔业务组件（接口+实现） | domain + framework |
| `harness-framework` | 统一响应、元组工具类 | 无外部依赖 |

### 前端：React 四层架构

```
ui/pages（页面组件）→ service（API 调用层）→ infra/http（HTTP 客户端）→ 后端 API
     ↑
app（路由 + 布局）
```

### 测试体系：三层隔离测试

项目包含完整的三层测试体系，覆盖单元测试、Service 层集成测试、API 层集成测试：

| 测试模块 | 类型 | 工具 |
|---------|------|------|
| `component-test` | 组件层单元测试 | JUnit + Mockito |
| `business-test` | Service 层集成测试 | Spring Boot Test + setup.sql/verify.sql |
| `backend-test` | API 层集成测试 | Spring Boot Test + MockMvc + setup.sql/verify.sql |

## Qoder AI 工程化集成

本项目深度集成了 [Qoder](https://qoder.jibao168.com/) AI 编程工具，通过 `.qoder/` 目录实现了完整的 AI 辅助开发体系：

```
.qoder/
├── agents/          # 自定义 SubAgent：代码审查、部署、集成测试、脚手架生成等
├── commands/        # 快捷命令：git-push、start-all、start-server 等
├── rules/           # 编码规则约束：API 规范、异常处理、分层依赖、ESLint 替代等
├── skills/          # AI Skill：CRUD 生成、测试生成、SQL 变更、Bug 修复等
└── AGENTS.md        # 项目上下文声明：架构、技术栈、依赖规则
```

这套配置让 AI 在编写代码时自动遵守项目规范，做到：

- **Rule 约束**：用项目规范覆盖大模型的编码偏好（禁止深层嵌套、禁止吞异常等）
- **边界控制**：在 AGENTS.md 中定义模块边界，AI 不会越界修改
- **独立验证**：CodeReview Agent 独立审查 AI 输出的质量
- **文档先行**：写代码前先生成需求分析文档，避免方向性错误
- **验证驱动**：自动化测试确保每段代码都可验证

## 快速开始

### 前置条件

- JDK 17+
- Maven 3.8+
- Node.js 18+
- MySQL 8.0

### 1. 初始化数据库

```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE harness DEFAULT CHARACTER SET utf8mb4;"

# 执行建表脚本（按顺序执行）
# Documents/Sql变更/2026-06-29/ 下的 SQL 文件
```

### 2. 启动后端

```bash
cd backend
mvn clean install -DskipTests
cd api
mvn spring-boot:run
```

后端默认启动在 `http://localhost:8080`

### 3. 启动前端

```bash
cd web
npm install
npm run dev
```

前端默认启动在 `http://localhost:3000`，自动代理 `/api` 请求到后端。

### 4. 访问系统

打开浏览器访问 `http://localhost:3000`，即可看到包含仪表盘、记忆管理、会话记忆、用户管理、技能管理的完整管理后台。

## 项目结构

```
Harness/
├── backend/                     # Spring Boot 多模块后端
│   ├── pom.xml                  # 父 POM 聚合
│   ├── api/                     # Controller + 启动入口
│   ├── business/                # BizService 业务编排
│   ├── domain/                  # Entity + Mapper + 分页
│   ├── framework/               # 基础工具模块
│   ├── component-memory/        # 记忆管理组件（接口+实现）
│   ├── component-user/          # 用户管理组件（接口+实现）
│   ├── component-skill/         # 技能管理组件（接口+实现）
│   ├── business-test/           # Service 集成测试
│   ├── component-test/          # 组件单元测试
│   └── backend-test/            # API 集成测试
│
├── web/                         # React 前端
│   ├── package.json
│   ├── vite.config.ts
│   └── src/
│       ├── app/                 # 路由 + 布局
│       ├── ui/                  # 页面组件
│       ├── service/             # API 调用层
│       └── infra/               # HTTP 客户端
│
├── Documents/                   # 全生命周期文档
│   ├── Sql变更/                 # 数据库迁移脚本
│   ├── 需求分析/                # 需求与方案文档
│   ├── 测试报告/                # 测试执行报告
│   ├── CodeReview/              # 代码审查记录
│   └── 提交记录/                # Git 提交记录
│
├── .qoder/                      # Qoder AI 工程化配置
│   ├── agents/                  # 自定义 SubAgent
│   ├── commands/                # 快捷命令
│   ├── rules/                   # 编码规范约束
│   └── skills/                  # AI Skill 包
│
├── .gitignore
└── README.md
```

## 相关资源

- **Qoder 从入门到精通**：[https://qoder.jibao168.com/](https://qoder.jibao168.com/) — 系统学习 Qoder AI 编程工具
- **Agent 从入门到精通**：[https://agent.jibao168.com/](https://agent.jibao168.com/) — 深入理解 Agent 原理与架构设计
- **Harness 工程**：本书第 3 章第 8 节详细阐述了 Harness 工程思想和本项目的设计理念

## 许可证

Copyright (c) 2020-06-29 Qoder. All rights reserved.