# dsh-java-ontology

**Repository Path**: howai/dsh-java-ontology

## Basic Information

- **Project Name**: dsh-java-ontology
- **Description**: 基于Deepseek Harness JAVA 版本的本体库插件和维护工程
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dsh-java-ontology

一个可独立运行的本体库管理后台（Ontology Studio），并附带 `dsh-java` 的 Java Native Plugin，让 AI Agent 可以安全地以**只读**方式查询、检索你的本体知识库。

## 功能特性

- **本体库管理**：多本体库配置，支持新建、删除、列表查看（`~/.dsh-java-ontology/`）
- **AI 对话助手**：自然语言查询本体库，流式输出思考过程 → 工具调用 → 最终结论
- **概念查询**：按本体 ID 和查询表达式检索概念定义、层级关系、实体属性
- **模糊搜索**：按关键词快速定位概念和实体
- **Harness 插件**：3 个只读工具注册到 dsh-java，供 Agent 调用

## 架构

```text
dsh-java-ontology/
├── dsh-java-ontology-app/      Spring Boot 管理后台（Admin UI + Admin API）
└── dsh-java-ontology-plugin/   Harness 只读本体检索插件（JAVA_NATIVE）
```

```text
浏览器 ──► Admin UI (8092) ──► Admin API ──► Ontology Store
               │
               └─ AI 对话 ──► dsh-java (8090)
                                 └─► dsh-java-ontology-plugin ──► Admin API ──► Ontology Store
```

- **Admin UI**：原生 HTML/CSS/JS，无前端构建链
- **Plugin**：通过 `http://127.0.0.1:8092` 访问 Admin API，不直接持有本体库凭证

## 环境要求

- JDK 17+
- Maven 3.6+
- 可选：dsh-java（AI 对话能力依赖它提供 Agent 运行时）

## 快速开始

### 1. 构建

```bash
git clone git@gitee.com:howai/dsh-java-ontology.git
cd dsh-java-ontology
mvn package -DskipTests
```

### 2. 启动管理后台

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

或开发模式：

```bash
mvn spring-boot:run -pl dsh-java-ontology-app
```

打开 <http://127.0.0.1:8092>。

### 3. 新建本体库

点击「新建本体」，填写名称、描述、来源，保存。

### 4. 使用 AI 助手（可选）

AI 对话依赖 `dsh-java`（默认 `http://127.0.0.1:8090`）提供 Agent 运行时，并需要安装本仓库的插件（见下文）。选中本体库后，在输入框用自然语言提问，例如：

- `列出所有可用的本体库`
- `查询"人"这个概念的层级关系`
- `搜索包含"组织"的概念`

## 安装 Harness 插件

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

```bash
JAR="$PWD/dsh-java-ontology-plugin/target/dsh-java-ontology-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-ontology-plugin\",\"displayName\":\"DSH Ontology Plugin\",\"pluginVersion\":\"0.1.0\",\"runtimeType\":\"JAVA_NATIVE\",\"sourcePath\":\"$JAR\",\"entrypoint\":\"dsh-java-ontology-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-ontology-plugin"}'
```

Agent 可用工具：

| 工具 | 说明 |
| --- | --- |
| `plugin__dsh-java-ontology-plugin__ontology_list` | 列出已配置的本体库 |
| `plugin__dsh-java-ontology-plugin__ontology_query` | 查询概念定义、层级关系、实体属性 |
| `plugin__dsh-java-ontology-plugin__ontology_search` | 按关键词模糊搜索概念和实体 |

## 配置项

| 配置 | 环境变量 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `server.port` | — | `8092` | 管理后台端口 |
| `dsh.ontology.data-directory` | — | `~/.dsh-java-ontology` | 本体库配置存储目录 |
| `dsh.ontology.query-timeout-seconds` | — | `15` | 查询执行超时 |
| `dsh.ontology.max-results` | — | `100` | 查询最大返回结果数 |
| `dsh.ontology.harness.base-url` | `DSH_HARNESS_BASE_URL` | `http://127.0.0.1:8090` | Harness 地址 |

## 安全边界

- **AI 链路全程只读**：插件只注册列表、查询、搜索工具，不提供写操作能力。
- 查询默认 15 秒超时、最多返回 100 条结果。
- 该后台默认面向本机使用；生产部署前必须补充登录鉴权、CORS/CSRF 策略和集中审计。