# dsh-java-plugins

**Repository Path**: zhougaoping/dsh-java-plugins

## Basic Information

- **Project Name**: dsh-java-plugins
- **Description**: 基于Harness Java的基础支撑插件、示例插件、mysql数据库插件、mall插件，定义插件的开发规范，给出参考
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-10-11
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dsh-java-plugins

基于 [dsh-java](https://gitee.com/howai/dsh-java) 的插件集合：MySQL 数据库插件、虚拟商城插件，定义插件的开发规范并给出参考实现。

## 功能特性

- **dsh-java-mysql**：可独立运行的 MySQL 轻量管理后台（端口 8091），附带 Harness 只读插件（5 个工具：连接列表、只读查询、EXPLAIN、性能快照、SQL 审计）
- **dsh-java-mall**：PC 端虚拟商城（端口 18080），商品搜索 → 购物车 → 下单 → 支付 → 物流闭环，附带 Harness 智能客服插件（11 个工具）
- **统一规范**：所有插件依赖 `com.howai:dsh-java-types`（provided），通过 SPI 服务文件注册，包路径统一采用 `com.howai.dsh.*`

## 架构

```text
dsh-java-plugins/
├── dsh-java-mysql/
│   ├── dsh-java-mysql-app/        Spring Boot 管理后台（Admin UI + Admin API，端口 8091）
│   └── dsh-java-mysql-plugin/     Harness 只读 MySQL 插件（5 个工具）
└── dsh-java-mall/
    ├── dsh-java-mall-app/         Spring Boot 商城服务（REST API + UI，端口 18080）
    └── dsh-java-mall-plugin/      Harness 智能客服插件（11 个工具）
```

```text
浏览器 ──► Admin UI ──► Admin API ──► 数据源
               │
               └─ AI 对话 ──► dsh-java (8090)
                                 └─► dsh-java-*-plugin ──► Admin API ──► 数据源
```

- **Admin UI**：原生 HTML/CSS/JS，无前端构建链
- **Plugin**：通过 Admin API 访问数据，不直接持有凭证
- **命名规范**：`{项目名}-app`（Spring Boot 应用）+ `{项目名}-plugin`（Harness 插件）

## 环境要求

- JDK 17+
- Maven 3.6+
- dsh-java 0.1.8（提供 `dsh-java-types` 契约包）
- 可选：MySQL 5.7+ / 8.x（dsh-java-mysql 被管理的目标实例）

## 快速开始

### 1. 构建

```bash
git clone <dsh-java-plugins-repo-url>
cd dsh-java-plugins
mvn package -DskipTests
```

### 2. 启动 MySQL 管理后台

```bash
java -jar dsh-java-mysql/dsh-java-mysql-app/target/dsh-java-mysql-app-0.1.0-SNAPSHOT.jar
```

打开 <http://127.0.0.1:8091>，添加数据库连接后即可使用 SQL 控制台和 AI 对话。

### 3. 启动虚拟商城

```bash
java -jar dsh-java-mall/dsh-java-mall-app/target/dsh-java-mall-app-0.1.0-SNAPSHOT.jar
```

打开 <http://127.0.0.1:18080>，默认演示用户 `customer-1`。

### 4. 安装 Harness 插件

先启动 `dsh-java`（端口 8090），然后安装插件：

```bash
# MySQL 插件
JAR="$PWD/dsh-java-mysql/dsh-java-mysql-plugin/target/dsh-java-mysql-plugin-0.1.0-SNAPSHOT.jar"
curl -X POST http://localhost:8090/api/harness/plugins/install \
  -H 'Content-Type: application/json' \
  -d "{\"pluginId\":\"dsh-java-mysql-plugin\",\"displayName\":\"DSH MySQL Plugin\",\"pluginVersion\":\"0.1.0\",\"runtimeType\":\"JAVA_NATIVE\",\"sourcePath\":\"$JAR\",\"entrypoint\":\"dsh-java-mysql-plugin-0.1.0-SNAPSHOT.jar\"}"
curl -X POST http://localhost:8090/api/harness/plugins/activate \
  -H 'Content-Type: application/json' -d '{"pluginId":"dsh-java-mysql-plugin"}'

# Mall 插件
JAR="$PWD/dsh-java-mall/dsh-java-mall-plugin/target/dsh-java-mall-plugin-0.1.0-SNAPSHOT.jar"
curl -X POST http://localhost:8090/api/harness/plugins/install \
  -H 'Content-Type: application/json' \
  -d "{\"pluginId\":\"mall-weekend-assistant\",\"displayName\":\"DSH Mall Plugin\",\"pluginVersion\":\"0.1.0\",\"runtimeType\":\"JAVA_NATIVE\",\"sourcePath\":\"$JAR\",\"entrypoint\":\"dsh-java-mall-plugin-0.1.0-SNAPSHOT.jar\"}"
curl -X POST http://localhost:8090/api/harness/plugins/activate \
  -H 'Content-Type: application/json' -d '{"pluginId":"mall-weekend-assistant"}'
```

## Agent 可用工具

### dsh-java-mysql-plugin（5 个只读工具）

| 工具 | 说明 |
| --- | --- |
| `plugin__dsh-java-mysql-plugin__mysql_list_connections` | 列出本地已配置连接 |
| `plugin__dsh-java-mysql-plugin__mysql_read_query` | 执行只读查询（SELECT/SHOW/DESC） |
| `plugin__dsh-java-mysql-plugin__mysql_explain_query` | 执行 EXPLAIN 执行计划 |
| `plugin__dsh-java-mysql-plugin__mysql_performance_snapshot` | 获取性能快照 |
| `plugin__dsh-java-mysql-plugin__mysql_sql_review` | 本地 SQL 风险审计（不连库） |

### mall-weekend-assistant（11 个工具）

| 工具 | 说明 |
| --- | --- |
| `plugin__mall-weekend-assistant__search_products` | 搜索商品 |
| `plugin__mall-weekend-assistant__get_product` | 查看商品详情 |
| `plugin__mall-weekend-assistant__add_to_cart` | 加入购物车 |
| `plugin__mall-weekend-assistant__place_order` | 下单 |
| `plugin__mall-weekend-assistant__pay_order` | 支付订单 |
| `plugin__mall-weekend-assistant__get_order` | 查看订单详情 |
| `plugin__mall-weekend-assistant__query_orders` | 查询订单列表 |
| `plugin__mall-weekend-assistant__cancel_order` | 取消订单 |
| `plugin__mall-weekend-assistant__query_logistics` | 查询物流 |

## 插件开发规范

1. **目录命名**：`{项目名}-app`（Spring Boot 应用）+ `{项目名}-plugin`（Harness 插件）
2. **包路径**：`com.howai.dsh.{业务域}`，底层契约包 `com.howai.dsh.domain.*`
3. **groupId**：`com.howai.dsh`
4. **types 依赖**：`com.howai:dsh-java-types:0.1.8`，scope=provided
5. **SPI 注册**：`META-INF/services/com.howai.dsh.domain.spi.JavaHarnessPlugin` 文件内写入插件入口类全限定名
6. **plugin.yaml**：`META-INF/plugin.yaml` 声明插件 id、name、version、entrypoint
7. **工具实现**：继承 `AbstractTool`，实现 `name()`/`description()`/`parameters()`/`run()`，通过 `objectSchema()`/`stringSchema()` 构建参数 schema

## 配置项

### dsh-java-mysql

| 配置 | 默认值 | 说明 |
| --- | --- | --- |
| `server.port` | `8091` | 管理后台端口 |
| `dsh.mysql.data-directory` | `~/.dsh-java-mysql` | 连接配置存储目录 |
| `dsh.mysql.harness.base-url` | `http://127.0.0.1:8090` | Harness 地址 |

### dsh-java-mall

| 配置 | 默认值 | 说明 |
| --- | --- | --- |
| `server.port` | `18080` | 商城端口 |
| `mall.harness.base-url` | `http://127.0.0.1:8090` | Harness 地址 |

## 安全边界

- **MySQL 插件全程只读**：不提供写 SQL 执行能力，服务端二次校验非只读语句直接拒绝
- **Mall 插件**：通过 Admin API 操作，不直接持有数据库凭证
- 两个后台默认面向本机使用；生产部署前必须补充登录鉴权、CORS/CSRF 策略和集中审计