# OriginHome

**Repository Path**: koujiang/origin-home

## Basic Information

- **Project Name**: OriginHome
- **Description**: 随着家族结构日益分散、人口流动增强，传统纸质族谱难以维护、更新成本高、传承困难。同时，AI 技术的发展为复杂关系建模、自然语言理解、内容生成提供了新的可能。

本产品旨在构建一款 数字化、智能化、可持续演化的族谱 App，帮助用户便捷地记录、维护和传承家族成员信息及家族文化。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-16
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Origin Home

**项目定位**  
origin-home 是一个"以族谱为核心的长期记忆型 AI Agent 系统"，  
目标是通过自然语言构建、维护和推理家族关系，同时学习 Agent 的核心能力。

## 技术栈

- **JDK**: 21
- **Spring Boot**: 3.3.0
- **数据库**: PostgreSQL 14
- **ORM**: Spring Data JPA + QueryDSL 5.1.0
- **构建工具**: Maven

## 项目结构

```
origin-home
├── agent/              # Agent 核心层
│   ├── OriginHomeAgent.java      # Agent 主入口
│   └── AgentContext.java         # 会话上下文
├── planner/           # 规划层
│   ├── Intent.java               # 意图枚举
│   ├── IntentParser.java         # 意图识别（规则匹配 + 参数提取）
│   └── TaskPlanner.java          # 行为规划
├── tool/              # 工具层
│   ├── Tool.java                 # 工具接口
│   ├── AddPersonTool.java        # 添加人物工具
│   ├── AddRelationTool.java      # 添加关系工具
│   ├── QueryRelationTool.java    # 查询关系工具
│   └── InferRelationTool.java    # 关系推理工具
├── domain/            # 领域模型
│   ├── Person.java               # 人物实体
│   ├── Relation.java             # 关系实体
│   ├── Family.java               # 家族实体
│   └── RelationType.java         # 关系类型枚举
├── repository/        # 数据访问层
│   ├── PersonRepository.java
│   ├── RelationRepository.java
│   └── FamilyRepository.java
├── memory/            # 记忆层
│   ├── FamilyMemory.java         # 族谱记忆接口
│   └── impl/
│       └── FamilyMemoryImpl.java # 族谱记忆实现
├── controller/        # 控制器层
│   └── AgentController.java      # Agent API 控制器
└── static/            # 静态资源
    └── index.html                # Web 聊天界面
```

## 核心功能

### 1. Agent 核心流程

```
自然语言输入 → 意图解析 → 参数提取 → 任务规划 → 工具执行 → 记忆存储 → 输出结果
```

### 2. 支持的操作

- **添加人物**: 在家族中添加新人物
  - 示例：`添加人物，叫张三，男性，1990年1月1日出生`
- **添加关系**: 在两个人物之间建立关系（父子、母子、配偶等）
  - 示例：`张三是李四的父亲`、`建立关系，张三和李四是夫妻`
- **查询关系**: 查询某个人物的所有关系
  - 示例：`查询张三的关系`、`查看李四的父亲`
- **推理关系**: 通过多步关系推理，找到两个人物之间的间接关系
  - 示例：`推理张三和李四的关系`、`他们是什么关系`

### 3. 自然语言理解

系统支持从自然语言中自动提取参数：
- **人物姓名**: 自动识别中文姓名和英文姓名
- **性别**: 识别"男"、"女"等关键词
- **日期**: 识别"1990年1月1日"等日期格式
- **关系类型**: 识别"父亲"、"母亲"、"配偶"等关系关键词

### 3. 关系类型

- `FATHER_CHILD`: 父子关系（有向）
- `MOTHER_CHILD`: 母子关系（有向）
- `SPOUSE`: 配偶关系（无向）
- `ADOPTED_CHILD`: 养子关系（有向）

## 快速开始

### 1. 环境准备

- JDK 21
- Maven 3.8+
- PostgreSQL 14

### 2. 数据库配置

创建数据库：

```sql
CREATE DATABASE origin_home;
```

修改 `src/main/resources/application.yml` 中的数据库连接信息：

```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/origin_home
    username: postgres
    password: postgres
```

### 3. 运行方式

#### 方式 A：本地运行（推荐用于开发）

```bash
# 编译项目
mvn clean compile

# 运行应用
mvn spring-boot:run
```

#### 方式 B：Docker 部署（推荐用于演示）

```bash
# 启动所有服务（PostgreSQL + LocalAI + Family Service）
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f family-service

# 停止服务
docker-compose down
```

> **Docker 配置说明**:
> - 所有数据存储在 `./docker-data/` 目录
> - 数据库：`family_db`，用户名：`family`，密码：`family123`
> - 服务端口：`9000`（访问地址：http://localhost:9000）
> - LocalAI 模型文件放在：`./docker-data/localai/models/`
> - 详细说明请查看 `docker/QUICKSTART.md`

### 4. 使用方式

#### 方式一：Web 聊天界面（推荐）

启动应用后，在浏览器中访问：

```
http://localhost:8081
```

> **注意**: 如果使用 Docker 部署，端口为 `9000`，访问地址为 `http://localhost:9000`

即可打开聊天界面，与 AI Agent 进行交互。

**使用示例**：
- 添加人物：`添加人物，叫张三，男性，1990年1月1日出生`
- 建立关系：`张三是李四的父亲`
- 查询关系：`查询张三的关系`
- 推理关系：`张三和李四是什么关系`

#### 方式二：REST API

> **注意**: 如果使用 Docker 部署，将端口 `8080` 改为 `9000`

##### 添加人物

```bash
curl -X POST http://localhost:8081/api/v1/agent/process \
  -H "Content-Type: application/json" \
  -d '{
    "input": "添加人物，叫张三，男性，1990年1月1日出生",
    "familyId": 1,
    "sessionId": "session-001"
  }'
```

##### 查询关系

```bash
curl -X POST http://localhost:8081/api/v1/agent/process \
  -H "Content-Type: application/json" \
  -d '{
    "input": "查询张三的关系",
    "familyId": 1,
    "sessionId": "session-001"
  }'
```

## 开发说明

### QueryDSL 代码生成

项目使用 QueryDSL 进行类型安全的查询。编译时会自动生成 Q 类：

```bash
mvn clean compile
```

生成的 Q 类位于 `target/generated-sources/annotations` 目录。

### 扩展意图解析

当前使用规则匹配进行意图解析，后续可以扩展为 LLM 解析：

1. 修改 `IntentParser` 类
2. 集成 LLM API（如 OpenAI、Claude 等）
3. 实现更复杂的参数提取逻辑

### 添加新工具

1. 实现 `Tool` 接口
2. 在 `Intent` 枚举中添加新意图
3. 在 `IntentParser` 中添加匹配规则
4. 使用 `@Component` 注解注册为 Spring Bean

## 后续计划

- [ ] 集成 LLM 进行自然语言理解
- [ ] 实现更复杂的关系推理算法
- [ ] 支持批量操作
- [ ] 添加数据校验规则
- [ ] 实现关系确认机制
- [ ] 支持导出族谱数据

## 许可证

MIT License