# agent

**Repository Path**: lmatch/agent

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-25
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FundFlow Agent（基金生命周期智能助手）

FundFlow Agent 是一个面向 Java 后端岗位的 Agent 开发练习项目。项目以“基金生命周期管理”为业务背景，最终会逐步实现一个能够基于材料证据进行审阅、分析和任务编排的智能助手。

> 本项目只使用虚构数据。请勿提交任何真实的客户、投资者、交易、法律、税务或投资数据。

## 我们要做什么

很多 Agent 示例只有一段提示词和一次模型调用，不容易体现 Java 后端开发能力。这个项目会把传统后端与 AI 能力结合起来：

- 用 Java 代码处理确定性的业务规则；
- 用 PostgreSQL 保存基金、阶段和流程数据；
- 用 pgvector 保存文档的语义向量；
- 用大模型理解材料、检索证据并提出建议；
- 对敏感操作保留人工审批，避免让模型直接做最终决定。

目前的第一个里程碑包含：

- Java 21 与 Spring Boot REST API；
- PostgreSQL 业务数据和 Flyway 数据库迁移；
- pgvector 环境和 Spring AI `VectorStore` 接口；
- 基金生命周期领域模型；
- 确定性、可测试的流程检查清单；
- 敏感步骤的人工审批标记；
- 可选的 `ai` 配置，用于文档索引和语义检索。

下一个里程碑会加入文档解析、证据搜索工具、结构化分析报告和 Agent 效果评测。

## 项目结构

```text
HTTP API
  |
  +-- 基金服务 -------------- PostgreSQL 关系表
  |
  +-- 生命周期工作流 -------- 确定性的 Java 业务规则
  |
  `-- 知识服务 -------------- Spring AI VectorStore ------ pgvector
                                      |
                                      `-- Embedding 模型（ai 配置）
```

可以先这样理解两种数据库能力：

- **PostgreSQL** 保存“确定的事实和关系”，例如基金名称、币种、当前阶段。
- **pgvector** 保存文档内容转换成的向量，让系统能够按照语义查找相近内容，而不只是匹配完全相同的关键词。
- 搜索时仍然可以使用 `fundId`、`documentType` 等字段过滤，防止检索到其他基金的材料。

## 环境要求

- JDK 21；
- Docker 与 Docker Compose；
- 只有启用真实 AI 功能时才需要模型 API Key。

## 本地启动

### 1. 进入项目

```bash
cd /Users/liuchang/workspace/gitee/fundflow-agent
```

### 2. 切换到 Java 21

下面的设置只影响当前终端，不会修改整台电脑的默认 Java 版本：

```bash
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH="$JAVA_HOME/bin:$PATH"
java -version
```

### 3. 启动 PostgreSQL + pgvector

```bash
docker compose up -d postgres
```

数据库连接信息：

```text
地址：localhost:5432
数据库：fundflow
用户名：fundflow
密码：fundflow
```

### 4. 启动后端

不调用大模型也可以启动和体验基础业务功能：

```bash
./mvnw spring-boot:run
```

启动成功后，可以访问健康检查：

```bash
curl http://localhost:8080/actuator/health
```

### 5. 创建一只虚构基金

```bash
curl -X POST http://localhost:8080/api/funds \
  -H 'Content-Type: application/json' \
  -d '{
    "referenceCode": "DEMO-FUND-001",
    "name": "小溪成长基金一期",
    "domicile": "虚构司法辖区",
    "baseCurrency": "USD",
    "stage": "DISTRIBUTION"
  }'
```

接口会返回一个基金 `id`。把下面的 `{fundId}` 替换成这个值，就可以生成该阶段的流程检查清单：

```bash
curl http://localhost:8080/api/funds/{fundId}/checklist
```

## 启用语义检索

这一部分会真正调用 Embedding 模型，因此需要 API Key。先设置环境变量并启用 `ai` 配置：

```bash
export OPENAI_API_KEY='你的 API Key'
./mvnw spring-boot:run -Dspring-boot.run.profiles=ai
```

向指定基金的知识库写入一段虚构材料：

```bash
curl -X POST http://localhost:8080/api/funds/{fundId}/knowledge \
  -H 'Content-Type: application/json' \
  -d '{
    "documentType": "GOVERNING_AGREEMENT",
    "sourceName": "synthetic-fund-agreement.txt",
    "content": "执行收益分配前，需要取得审批记录，并完成虚构的对账检查清单。"
  }'
```

然后不用输入材料里的原句，也可以按照含义提问：

```bash
curl --get http://localhost:8080/api/funds/{fundId}/knowledge/search \
  --data-urlencode 'query=分钱之前需要完成什么？'
```

## 设计原则

1. 大模型负责检索、理解和提出建议；关键事实仍由确定性的 Java 代码校验。
2. 每一个重要结论都必须能够指向对应证据。
3. 找不到证据时明确返回“未知”，不能由模型编造答案。
4. 基金生命周期中的敏感操作必须经过人工确认。
5. 使用可重复的测试用例评估 Agent，而不是只展示一次看起来很惊艳的回答。

## 开发路线

- [x] 基金生命周期模型和 CRUD API
- [x] 确定性的生命周期检查清单
- [x] PostgreSQL + pgvector 本地开发环境
- [x] 语义索引和检索适配层
- [ ] 虚构的基金文档数据集
- [ ] PDF / 文本文档解析与分块
- [ ] 用于证据搜索和规则校验的 Agent 工具
- [ ] 结构化的生命周期审阅报告
- [ ] 评测数据集和调用轨迹检查
- [ ] 简单的审阅界面

## 常用命令

```bash
# 运行测试
./mvnw test

# 查看数据库容器状态
docker compose ps

# 停止容器，但保留数据库数据
docker compose down
```

> `docker compose down -v` 会连同数据库数据卷一起删除。除非确定要清空数据，否则不要加 `-v`。