# person-ai

**Repository Path**: pucong/person-ai

## Basic Information

- **Project Name**: person-ai
- **Description**: 🔥🔥🔥 Person-Ai是一个基于Java开发的本地AI智能助手系统，提供智能对话、技能管理和记忆管理等功能。
系统支持多种AI模型，采用ReactAgent架构实现智能对话，并提供完整的记忆管理系统，帮助用户高效地与AI进行交互。
- **Primary Language**: Java
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: https://personai.chat/
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-02-27
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: ai

**Tags**: 智能体, 个人助理, AI, 龙虾

## README

<div align="center">

**Person-Ai · AI 智能助手**

支持多模型接入与 ReactAgent（Think -> Act -> Observe）对话流程，
内置技能管理、记忆管理、备忘录、定时任务与多工作空间能力。

提供 Web 界面，并支持企业微信 Bot、微信扫码登录等多通道接入。

[![License](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-25-orange.svg)](https://openjdk.org/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-brightgreen.svg)](https://spring.io/projects/spring-boot)
</div>

# Person-Ai - AI智能助手

## 1. 项目概述

Person-Ai是一个基于Java开发的本地AI智能助手系统，提供智能对话、技能管理和记忆管理等功能。
系统支持多种AI模型，采用ReactAgent架构实现智能对话，并提供完整的记忆管理系统，帮助用户高效地与AI进行交互。

### 主要特性

- 🤖 **openAi标准模型支持**：集成豆包、GLM、Kimi等多种AI模型
- 💬 **智能对话**：基于ReactAgent架构（思考 -> 行动 -> 观察）的自然语言交互
- 🔌 **多通道接入**：支持 Web、企业微信 Bot、微信扫码登录等通道接入与消息处理
- 🛠️ **技能管理**：支持用户自定义技能和动态技能添加
- 🧠 **记忆管理**：多层次记忆系统，包括原始记忆、短期记忆、长期记忆（抽象内容、摘要内容）、知识图谱
- 🧩 **图谱驱动创新**：本体建模 + 知识图谱承载长期世界状态，支持可解释关联、检索与演化治理
- 📅 **定时任务**：支持心跳检测及AI自定义定时任务
- 📝 **备忘录管理**：AI自主维护备忘录，支持增删改查
- 🪶 **工具渐进式加载**：按需加载工具与 schema，最小化上下文注入，更加节省 Token
- 🔄 **工作空间切换**：支持多工作环境灵活切换
- ⚙️ **模型配置**：灵活的模型参数配置和管理

## 2. 系统架构

```text
┌──────────────────────────────────────┐   ┌──────────────────────────────────────┐
│      用户界面 (Web Interface)         │   │         通道 (Channel)                │
│   Vue 3 + Vite / 现代 Web 交互界面     │   │   Wecom AIBot / WechatClawBot        │
└───────────────────┬──────────────────┘   └───────────────────┬──────────────────┘
                    │                                          │
                    └────────────────────┬─────────────────────┘
                                         │
                                         ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                 本地运行模块 (person-ai-springboot)                            │
│  ┌───────────────┐  ┌────────────────────┐  ┌─────────────────────────────┐  │
│  │  Controller   │  │    Config 管理     │   │       Agent 构建器           │  │
│  │   (接口处理)   │  │  (本地配置持久化)    │   │ (PersonAgentEngineBuilder)  │  │
│  └───────────────┘  └────────────────────┘  └─────────────────────────────┘  │
└──────────────────────────────────────┬───────────────────────────────────────┘
                                       │
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                  智能体引擎模块 (person-ai-engine)                          │
│  ┌────────────────────────────────────────────────────────────────────────┐  │
│  │           ReactAgent 核心逻辑 (Think -> Act -> Observe)              │  │
│  └───────────────┬───────────────────┬───────────────────┬──────────────┘  │
│                  │                   │                   │                 │
│   ┌──────────────▼─────────────┐  ┌──▼─────┐  ┌──────────▼───────────┐     │
│   │        技能引擎            │  │ 备忘录 │  │       记忆引擎       │     │
│   │      (Skill Engine)        │  │ (Memo) │  │    (Memory Engine)   │     │
│   └──────────────┬─────────────┘  └──┬─────┘  └──────────┬───────────┘     │
│                  │                   │                   │                 │
│  ┌───────────────▼──────────────┐    │    ┌──────────────▼──────────────┐   │
│  │         技能插件库           │    │    │        多层记忆体系         │   │
│  │      内置技能 / 自定义技能    │    │    │   原始 / 短期 / 长期 / 图谱  │   │
│  └──────────────────────────────┘    │    └─────────────────────────────┘   │
│                                       │                                      │
│                          ┌────────────▼────────────┐                         │
│                          │       定时任务引擎      │                         │
│                          │     (AI维护 / 心跳等)   │                         │
│                          └─────────────────────────┘                         │
└──────────────────────────────────────┬───────────────────────────────────────┘
                                       │
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                     本地持久化层 (Data Storage)                             │
│    [Config] [Memory] [Skills] [Memorandum] [Schedule] [Workspaces]         │
└──────────────────────────────────────┬───────────────────────────────────────┘
                                       │
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                     外部大模型服务 (LLM Services)                           │
│             Doubao / GLM / Kimi / DeepSeek / OpenAI / etc.                 │
└──────────────────────────────────────────────────────────────────────────────┘
```

## 3. 核心功能

### 3.1 模型配置与管理

Person-Ai支持多种主流AI模型，提供统一的配置接口和管理功能：

#### 支持的模型

- **豆包（Doubao）**：字节跳动出品的大语言模型
- **GLM**：智谱AI开发的大语言模型
- **Kimi**：月之暗面开发的长上下文大模型
- **OpenAI**：支持兼容OpenAI标准接口的其他模型

### 3.2 ReactAgent对话功能

基于ReactAgent架构实现的智能对话系统，它实现了`思考 -> 行动 -> 观察`的经典思维链，并引入了`React + 评价`的新设计，支持更强大的自然语言理解和响应生成：

#### 核心特性

- **记忆管理**：基于当前模型生成自然、连贯的回复
- **技能管理**：根据用户需求自动调用相应技能
- **定时任务管理**：支持AI创建、查询、更新和删除定时任务，系统默认有心跳检测
- **备忘录管理**：支持AI创建、查询、更新和删除备忘录
- **新思维链设计**：支持AI根据用户需求自动调用工具，同时评估其执行结果，不断优化上下文

#### 新思维链设计

##### 经典三段式（Think -> Act -> Observe）

1.  **思考 (Think)**：AI 首先分析用户问题，拆解任务，并决定是否需要调用技能。
2.  **行动 (Act)**：如果需要，AI 会执行工具（如代码执行、文件读写）。
3.  **观察 (Observe)**：AI 观察技能执行结果，并利用该结果生成最终回复。

##### React + 评价（React + Evaluate）

为了优化 AI 上下文 ，我们引入了 `React + 评价` 机制。

1.  **评价 (Evaluate)**：AI 对上一步生成的计划进行自我评估，系统拿到评估结果，下一轮思维链时省略上一个行动结果。
2.  **评价结果**
   - **优 (Excellent)**：观察结果完美解决了预期目标，提供了准确且完整的信息。
   - **良 (Good)**：观察结果提供了部分有用信息，虽未完全解决，但有助于推进任务。
   - **差 (Poor)**：观察结果无效、错误或与目标无关，需要调整策略。

此设计使 AI 能够像人类一样进行深度思考和规划，从而提高复杂问题的解决成功率。

### 3.3 技能管理系统

技能是 AI 的能力扩展单元，通过专门的知识、工具和工作流程来增强其功能。

- **内置技能 (Built-in Skills)**：系统预置的核心管理功能（如文件操作、记忆检索、系统管理等）。
- **自定义技能 (Custom Skills)**：用户可通过编写 `SKILL.md` 和配套脚本，动态扩展 AI 的专业领域能力。
- **全生命周期管理**：支持技能的自动发现、按需触发、异步执行及在线更新。

详细内容请参考：[技能管理系统文档](doc/skill-management.md)

### 3.4 记忆管理系统

多层次记忆系统，支持不同类型和时效性的信息存储。

- **原始记忆 (Raw Memory)**：对话的完整原始记录，用于深度细节检索。
- **短期记忆 (Short-Term Memory)**：维护最近 10 次会话的上下文，自动进行截断和简化。
- **长期记忆 (Long-Term Memory)**：
    - **摘要记忆 (Summary)**：对话内容的精炼总结（至少 500 字）。
    - **抽象记忆 (Abstract)**：对话核心主题和事实的极简抽象（不超过 200 字）。
- **知识图谱 (Knowledge Graph)**：基于实体的永久结构化记忆。

详细内容请参考：[记忆管理系统文档](doc/memory-management.md)

### 3.5 定时任务管理

定时任务是系统的主动驱动机制。触发后，系统会自动发送指令给 AI 处理，实现包括但不限于以下功能：

- **心跳检测**：监控系统和服务状态。
- **备忘录提醒**：根据备忘录内容定时提醒待办事项。
- **记忆自动整理**：每天凌晨 1:20 自动执行过期记忆清理。
- **Skill 自动维护**：定期更新技能索引和资源。

### 3.6 备忘录管理

提供增删改查工具给AI，让AI自主维护备忘录。备忘录作为 AI 的“外挂存储”，用于记录跨会话的待办事项和关键笔记。

- **自主维护**：AI 可根据对话内容自动添加新任务、更新进度或删除已完成项。
- **任务追踪**：记录待办事项，确保任务不会因会话中断而丢失。
- **结构化存储**：每条记录包含唯一 ID、内容及时间戳，便于精确管理。
- **即时检索**：在处理复杂任务时，AI 可随时查询之前的关键笔记以辅助决策。

### 3.7 工作空间管理

工作空间是AI进行文件操作的目录，AI在处理任务时，可以在此目录生成临时脚本和文件，解决完问题后，就会进行删除。

### 3.8 图谱驱动创新设计说明

Person-Ai 在既有 ReactAgent（Think -> Act -> Observe）与多层记忆能力之上，引入“本体建模 + 知识图谱”的图谱驱动设计，用于承载长期世界状态与系统运行对象，让长期信息具备统一语义、可解释关联与可演化治理边界。

#### 3.8.1 总体路线

- **Ontology-first Modeling**：以本体（schema）作为统一语义模型
- **Graph-centric Long-term Memory**：长期信息与系统对象入图；原始记忆与短期记忆保持现有存储方式，不直接入图
- **Graph-driven Agent**：Agent 围绕图谱完成长期检索、推理、规划、更新与协同
- **Prompt-driven Ontology Evolution**：在固定治理边界内，通过提示词驱动本体 schema 的持续提议、对齐、收缩与演化

#### 3.8.2 图谱承载范围

- **入图（长期/结构化）**：长期记忆（摘要/抽象/画像等）、备忘录、定时任务、技能、通道配置、运行上下文等
- **不入图（原始/短期）**：原始对话记录与短期上下文（保留既有存储与访问方式，用于细节回放与近程上下文）

#### 3.8.3 固定节点与治理边界

图谱内置一组系统固定节点，提供稳定语义骨架。固定节点的 `id`/`名称`/`类型` 为保留字段，**不可修改、不可删除**；业务节点只能挂接在固定骨架之下进行扩展。

| id | 名称 | 类型 | 说明 |
| --- | --- | --- | --- |
| `0` | 根节点 | 根节点 | 图谱全局根，承载一级系统域入口 |
| `1` | 备忘录 | 备忘录 | 备忘录域根节点 |
| `2` | 多智能体协同工作 | 多智能体协同工作 | 多智能体协同工作域根节点 |
| `3` | 多通道 | 多通道 | 多通道域根节点 |
| `4` | 长期记忆 | 长期记忆 | 长期记忆域根节点 |
| `5` | 定时任务 | 定时任务 | 定时任务域根节点 |
| `6` | 技能 | 技能 | 技能域根节点 |
| `7` | 当前智能体 | 当前智能体 | 当前智能体域节点，与根节点直接相连 |
| `8` | 灵魂内容 | 灵魂内容 | 当前智能体域内置固定节点 |
| `9` | 智能体基本信息 | 智能体基本信息 | 当前智能体域内置固定节点 |
| `10` | 对话记录 | 对话记录 | 长期记忆域内置固定节点 |
| `11` | 用户画像 | 用户画像 | 长期记忆域内置固定节点 |

除固定节点外，其他业务节点建议统一具备以下治理字段（用于软删除与审计）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `是否删除` | `boolean` | 是否已逻辑删除，默认 `false` |
| `删除时间` | `datetime \| null` | 删除发生时间，未删除时为 `null` |
| `删除原因` | `string \| null` | 删除原因说明 |

#### 3.8.4 图谱工具与最小能力集

Agent 不直接操作底层图库，而是通过受控工具访问图谱，以确保治理约束可执行、结果可追溯。

建议最小工具集包括：

1. `graph_create`：新增节点/关系
2. `graph_delete_by_id`：按主键删除（默认软删除）
3. `graph_update_by_id`：按主键更新属性（禁止改写固定骨架）
4. `graph_get_by_id`：按主键查询并可展开邻域
5. `graph_semantic_search`：关键词 + 向量的语义检索（支持类型与域过滤）

工具层面建议内置治理约束：

- 禁止删除固定节点与固定关系
- 禁止修改固定节点的 `name`/`type`/层级与固定关系
- 禁止写入与固定节点冲突的保留 `id`
- 强制补齐并维护非固定节点的软删除字段
- 写操作记录审计信息与版本链，便于回溯与解释

#### 3.8.5 渐进式工具加载机制（更节省 Token）

在图谱驱动场景下，工具数量会随着系统能力增长而增多。为了避免在每轮对话中把完整工具清单与 schema 全量注入（导致提示词膨胀、Token 成本上升），可采用“渐进式工具加载”：

- **默认最小集合**：仅常驻加载与对话强相关、低风险的基础工具（如只读查询、少量通用工具）。
- **按需加载**：当 Agent 识别到明确意图（例如“写入图谱”“更新备忘录”“创建定时任务”）时，再动态加载对应域工具及其详细 schema。
- **先摘要后展开**：先向模型提供候选工具的简要描述与使用边界；当需要调用时，再补充该工具的完整参数 schema 与示例。
- **分级工具包**：按领域拆分工具包（图谱、备忘录、定时任务、技能、通道等），每轮只加载当前任务所需工具包。
- **结果压缩回写**：工具返回尽量结构化，Agent 将关键字段提炼为短摘要写回上下文，减少长结果在后续轮次的重复携带。

## 4. 快速开始

### 4.1 环境要求

- 源码构建需要 Java 25 或更高版本
- Maven 3.9.10 或更高版本
- 至少 2GB 可用内存
- 网络连接（用于AI模型API调用）

### 4.2 安装步骤

1. **克隆项目**
   ```bash
   git clone https://github.com/your-org/person-ai.git
   cd person-ai
   ```

2. **编译项目**
   ```bash
   mvn clean compile
   ```

3. **打包项目**
   ```bash
   mvn clean package
   ```

4. **运行后端项目**
   ```bash
   mvn spring-boot:run -pl person-ai-springboot
   ```

5. **运行前端项目**
   ```bash
   cd front
   npm install
   npm run dev
   ```

运行后，访问浏览器即可开始对话。

### 4.2.1 首次启动模型初始化配置（可选）

系统支持在配置文件中预置对话模型与嵌入模型参数，用于首次启动时自动写入 `system_config` 配置表，完成初始化。

- 仅首次初始化时生效；数据库中已有完整模型配置后，后续启动不再依赖该配置。
- 对话模型与嵌入模型可分别配置，按已提供的完整配置项进行写入。

默认开发环境可在 `person-ai-springboot/src/main/resources/config/application-dev.yml` 中配置：

```yaml
person:
  ai:
    chat:
      vendor: qwenPlan
      url: https://your-llm-endpoint/v1/chat/completions
      model-name: glm-5
      api-key: ${CHAT_API_KEY}
    embedding:
      vendor: qwen
      model-code: text-embedding-v3
      api-key: ${EMBEDDING_API_KEY}
      dimension: 1024
      custom-url: https://your-embedding-endpoint/v1/embeddings
```

字段说明：

- `person.ai.chat.*`：对话模型配置（`vendor`、`model-name`、`api-key`，其中 `openai/open_ai` 额外要求 `url`）。
- `person.ai.embedding.*`：嵌入模型配置（`vendor`、`model-code`、`api-key` 必填，`dimension` 默认 `1024`，`custom-url` 可选）。

对话模型可选值（`person.ai.chat.vendor` + `person.ai.chat.model-name`）：

| vendor | 默认接口地址（chat） | model-name（示例） | 说明 |
| --- | --- | --- | --- |
| `kimi` | `https://api.moonshot.cn/v1/chat/completions` | `kimi-k2.5` | kimi 接口 |
| `minimax` | `https://api.minimaxi.com/v1/text/chatcompletion_v2` | `MiniMax-M2.5` | minimax 接口 |
| `deepSeek` | `https://api.deepseek.com/chat/completions` | 按平台可用模型填写 | 深度求索接口 |
| `qwen` | `https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions` | `qwen3.5-plus` | 千问接口 |
| `qwenPlan` | `https://coding.dashscope.aliyuncs.com/v1/chat/completions` | `glm-5` | 千问 Plan 接口 |
| `openai` | 自定义 | 自定义 | OpenAI 标准接口 |
| `doubao` | `https://ark.cn-beijing.volces.com/api/v3/chat/completions` | 按平台可用模型填写 | 豆包接口 |
| `glm` | `https://open.bigmodel.cn/api/paas/v4/chat/completions` | `glm-5` | 智谱清言接口 |

嵌入模型可选值（`person.ai.embedding.vendor` + `person.ai.embedding.model-code`）：

| vendor | 默认接口地址（embedding） | model-code（默认值） | 说明 |
| --- | --- | --- | --- |
| `kimi` | `https://api.moonshot.cn/v1/embeddings` | `text-embedding-3-large` | kimi 嵌入接口 |
| `qwen` | `https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings` | `text-embedding-v3` | 千问嵌入接口 |
| `openai` | `https://api.openai.com/v1/embeddings` | `text-embedding-3-large` | OpenAI 标准嵌入接口 |
| `doubao` | `https://ark.cn-beijing.volces.com/api/v3/embeddings` | `doubao-embedding-large` | 豆包嵌入接口 |
| `glm` | `https://open.bigmodel.cn/api/paas/v4/embeddings` | `embedding-3` | 智谱清言嵌入接口 |

说明：嵌入模型厂商列表与默认 `model-code` 由后端接口 `/api/config/embedding/vendors` 实时返回，不同版本可能有差异。

### 4.3 使用脚本后台启动

将 `person-ai.jar` 放到 `docs/deploy/` 目录后，可直接使用脚本后台启动：

- Windows：
  ```bat
  cd docs\deploy
  start.bat
  ```
- Linux/macOS：
  ```bash
  cd docs/deploy
  chmod +x start.sh
  ./start.sh
  ```

可选环境变量：

- `PERSON_AI_PORT`：服务端口，默认 `8082`
- `PERSON_AI_JAVA_PATH`：Java 可执行文件路径，未配置时默认优先使用 `./jre/bin/java`（Windows 为 `jre\bin\java.exe`），找不到则回退到系统 `java`
- `PERSON_AI_RUNTIME_APP_HOME`：应用根目录，安装包场景默认跟随安装目录（即安装器中选择的目录）
- `PERSON_AI_RUNTIME_DATA_DIR`：数据目录，默认跟随应用根目录
- `PERSON_AI_RUNTIME_WORKSPACE_DIR`：工作空间目录，默认跟随应用根目录
- `PERSON_AI_RUNTIME_OPEN_BROWSER`：是否自动打开浏览器，默认 `true`
- `PERSON_AI_RUNTIME_RESIDENT_MODE`：桌面驻留模式，可选 `menubar` / `tray` / `none`，打包后的 macOS 应用默认 `menubar`，Windows 应用默认 `tray`
- `PERSON_AI_RUNTIME_SINGLE_INSTANCE`：是否启用单实例保护，默认 `true`

日志输出文件：

- `./person-ai.log`
- `./person-ai.pid`（仅 `start.sh` 生成）

### 4.4 构建自带运行时安装包 / App Image

项目根目录已提供 [Makefile](/Users/clouds3n/.codex/worktrees/4400/person-ai/Makefile)，建议优先通过 `make` 执行打包命令。
底层仍然是 `mvn package + jpackage`，但常用参数已经封装好了。

项目已提供 `jpackage` 构建脚本，默认只生成当前平台约定的正式安装包类型。
注意：`jpackage` 不能跨平台打包，必须在目标平台上执行。
安装包图标默认取自 `docs/logo/person-ai-logo.png`，脚本会在打包时自动转换成当前平台需要的图标格式。

#### 4.4.1 推荐：使用 Makefile

先看可用命令：

```bash
make help
```

最常用命令：

```bash
make package
make package-all
make jar
make mac-dmg
make linux
```

默认行为：

- `make package`
  - macOS：只生成 `dmg`
  - Windows：只生成 `exe`
  - Linux：生成 `deb` 和 `rpm`
- `make package-all`
  - 生成当前平台全部支持的包型
- `make jar`
  - 只打 jar，跳过安装包

Makefile 可覆盖变量：

- `MVN`
  - Maven 命令，默认 `mvn`
- `MODULE`
  - Maven 模块名，默认 `person-ai-springboot`
- `SKIP_TESTS`
  - 是否跳过测试，默认 `true`
- `SKIP_FRONTEND`
  - 是否跳过前端构建，默认 `false`

示例：

```bash
make package SKIP_FRONTEND=true
make jar SKIP_TESTS=false
make package MVN=/path/to/mvn
```

`make -n` 用来预览将要执行的命令，不真正执行。例如：

```bash
make -n package SKIP_FRONTEND=true
```

#### 4.4.2 直接使用 Maven

现在直接执行 `mvn package` 也会在 jar 打包成功后，自动触发当前平台的 `jpackage` 打包流程。

```bash
cd person-ai
mvn -pl person-ai-springboot -DskipTests package
```

常用覆盖参数：

- `-Djpackage.package.types=dmg`：只生成指定类型
- `-Djpackage.package.types=recommended`：生成当前平台推荐类型
- `-Djpackage.package.types=all`：生成当前平台全部支持类型
- `-Djpackage.skip=true`：只打 jar，跳过安装包阶段

1. **macOS 构建 `dmg`**
   ```bash
   cd person-ai
   chmod +x docs/deploy/build-jpackage.sh
   PACKAGE_TYPE=dmg docs/deploy/build-jpackage.sh
   ```

2. **Windows 构建 `exe`**
   ```bat
   cd person-ai
   docs\deploy\build-jpackage.bat exe
   ```
   说明：`exe/msi` 依赖 WiX Toolset，需先安装 WiX 3.0+ 并将其 `bin` 目录加入 `PATH`；仅构建 `app-image` 时不需要 WiX。Windows 下 `jpackage --app-version` 需要数字点分格式，脚本会优先复用 Maven 注入的 `APP_VERSION`，仅在缺失时才回退解析。打包脚本会优先使用 Spring Boot 的 `person-ai.jar.original`（thin jar）并自动复制 runtime 依赖，避免 JavaFX 在 jpackage/jlink 场景下丢失平台原生库。安装包默认会创建桌面快捷方式和开始菜单 `Person-Ai` 分组，并允许安装时自定义安装目录（可通过 `WIN_DIR_CHOOSER=false` 关闭）。

3. **Linux 构建 `deb`**
   ```bash
   cd person-ai
   PACKAGE_TYPE=deb docs/deploy/build-jpackage.sh
   ```

4. **构建全部当前平台支持的包**
   ```bash
   cd person-ai
   PACKAGE_TYPES=all docs/deploy/build-jpackage.sh
   ```

   Windows:
   ```bat
   cd person-ai
   docs\deploy\build-jpackage.bat all
   ```

5. **当前平台可选类型**

   - macOS：`app-image`、`dmg`、`pkg`
   - Windows：`app-image`、`exe`、`msi`
   - Linux：`app-image`、`deb`、`rpm`

6. **输出目录**
   ```text
   person-ai-springboot/target/jpackage/
   ```

说明：

- 包内运行时默认来自当前执行打包命令的 JDK 25。`jpackage` 会基于当前 `java.home` 调用 `jlink` 自动裁剪出一份 runtime image，再一起打进安装包。
- 如果你想固定使用某一份 runtime image，可以额外传入环境变量 `RUNTIME_IMAGE=/path/to/runtime-image`，脚本会直接使用这份运行时。
- 安装包会自动使用 `jlink/jpackage` 裁剪运行时，不需要用户执行 `java -jar`。
- 安装包默认会将运行数据写入安装目录下（即安装器中选择的目录）。
- 不同平台的数据目录位置（均为“安装目录/data”）：
  - macOS：`<安装目录>/data`
  - Linux：`<安装目录>/data`
  - Windows：`<安装目录>\data`
- 打包后的 macOS 应用会默认以菜单栏应用运行。关闭浏览器不会退出 Person-Ai，需要从菜单栏重新打开页面或主动退出。
- 应用默认启用单实例保护。再次双击应用时不会重复拉起后端，只会尝试重新打开现有页面。
- 该目录下通常会包含：
  - `data/`：数据库、日志、向量扩展等运行数据
  - `workspace/`：AI 工作空间目录
- 如果你要同时产出 `dmg / exe / deb`，需要分别在 macOS / Windows / Linux 上执行打包脚本，或者在 CI 里做三平台构建矩阵。
- macOS 会区分 Intel 与 Apple Silicon。Apple Silicon 机器上会强校验当前 JDK 或 `RUNTIME_IMAGE` 必须是 `arm64/aarch64`，否则直接报错，避免误打出 x86 包。

### 4.5 Docker 一键部署

使用仓库内的 `docs/deploy` 配置可以直接完成镜像构建与容器启动。

1. **环境准备**
   - Docker 24+（或兼容版本）
   - Docker Compose v2+

2. **启动服务**
   ```bash
   cd person-ai
   docker compose -f docs/deploy/docker-compose.yml up -d --build
   ```
   已在 Compose 中固定构建上下文为项目根目录，避免 `COPY front`、`COPY person-ai-springboot/...` 找不到路径。

3. **查看日志**
   ```bash
   docker compose -f docs/deploy/docker-compose.yml logs -f
   ```

4. **停止服务**
   ```bash
   docker compose -f docs/deploy/docker-compose.yml down
   ```

5. **使用 docker run 启动（不使用 Compose）**
   ```bash
   cd person-ai
   docker build -t person-ai:2.1.1 -f docs/deploy/Dockerfile .
   docker run -d \
     --name person-ai \
     --restart=always \
     -p 6543:8082 \
     -e TZ="${TZ:-Asia/Shanghai}" \
     -e JAVA_OPTS="-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 -Xms128m -Xmx256m -Duser.timezone=${TZ:-Asia/Shanghai}" \
     -v "$(pwd)/data:/root/.person-ai" \
     -v "$(pwd)/workspace:/app/workspace" \
     person-ai:2.1.1
   ```

6. **docker run 停止与删除容器**
   ```bash
   docker stop person-ai
   docker rm person-ai
   ```

默认访问地址：`http://127.0.0.1:8082/person-ai/person-ai-web/index.html`。

配置说明：

- `TZ`：容器时区，默认 `Asia/Shanghai`，建议与主机时区保持一致。
- `JAVA_OPTS`：JVM 启动参数，默认 `-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 -Xms128m -Xmx256m -Duser.timezone=${TZ:-Asia/Shanghai}`。
- `8082:8082`：主机端口到容器端口映射。
- `$(pwd)/data:/root/.person-ai`：持久化系统数据目录，包括数据库、日志、向量索引等运行时文件。
- `$(pwd)/workspace:/app/workspace`：持久化 AI 工作区目录。

## 5. 核心模块使用

### 5.1 ChatAgent 构建与使用

`ChatAgent` 是系统的核心对话代理，负责处理与 AI 模型的交互。以下是如何构建和使用 `ChatAgent` 的说明：

#### 1. 构建 ChatAgent

`ChatAgent` 的构建通过 `ChatAgentConfig` 类（位于 `person-ai-springboot` 模块）完成。该配置类使用 Builder 模式，根据系统配置自动构建 `ChatAgent` 实例。

主要配置项包括：

- **模型供应商 (Model Vendor)**：支持 OpenAI、豆包、GLM、Kimi 等。
- **模型地址 (Model URL)**：自定义模型接口地址。
- **模型名称 (Model Code)**：具体的模型版本，如 `gpt-4`。
- **API 密钥 (API Key)**：用于访问模型服务的密钥。
- **工作空间 (Workspace)**：AI 读写文件的根目录。

`ChatAgentConfig` 会自动从系统配置中读取这些值，并注入必要的处理器（如记忆处理器、技能处理器等），最终构建一个完整的 `ChatAgent` Bean。

#### 2. 使用 ChatAgent

`ChatAgent` 提供了 Builder 模式 (`ChatAgent.create()`)，可以链式调用设置参数，使构建过程更清晰、更灵活。

**示例：使用 Builder 模式构建和使用 `ChatAgent`**

```java
public class ChatAgentBuilderExample {

    public static void main(String[] args) {
        // 1. 实例化所有依赖处理器 (Handler)
        //    - 在实际应用中，这些 Handler 需要正确实现和配置
        SoulHandler soulHandler = new SoulHandlerImpl();
        MemoryOriHandler memoryOriHandler = new MemoryOriHandlerImpl();
        MemoryShortHandler memoryShortHandler = new MemoryShortHandlerImpl();
        MemoryLongHandler memoryLongHandler = new MemoryLongHandlerImpl();
        MemoryGraphHandler memoryGraphHandler = new MemoryGraphHandlerImpl();
        SkillOperationHandler skillOperationHandler = new SkillOperationHandlerImpl();
        ToolMemorandumExecHandler toolMemorandumExecHandler = new ToolMemorandumExecHandlerImpl();
        ToolScheduleExecHandler toolScheduleExecHandler = new ToolScheduleExecHandlerImpl();

        // 2. 使用 Builder 模式构建 ChatAgent
        ChatAgent chatAgent = ChatAgent.create()
                .modelVendor(AiModelVendor.OPEN_AI) // 设置模型供应商
                .modeUrl("https://api.openai.com/v1/chat/completions") // 设置模型 URL
                .modeCode("gpt-4") // 设置模型名称
                .apiKey("YOUR_API_KEY") // 设置 API Key
                .workSpace("data/workspaces/default") // 设置工作空间
                .soulHandler(soulHandler) // 注入 SoulHandler
                .memoryGraphHandler(memoryGraphHandler) // 注入记忆处理器
                .memoryInstanceHandler(memoryShortHandler)
                .memoryOriHandler(memoryOriHandler)
                .memoryShortHandler(memoryLongHandler)
                .skillOperationHandler(skillOperationHandler) // 注入技能处理器
                .memorandumToolHandler(toolMemorandumExecHandler) // 注入备忘录处理器
                .scheduleToolHandler(toolScheduleExecHandler) // 注入定时任务处理器
                .build(); // 构建实例

        // 3. 设置回调处理器 (可选)
        chatAgent.setThinkHandler(think -> System.out.println("思考: " + think));
        chatAgent.setMsgHandler((type, msg) -> System.out.println(type + ": " + msg));

        // 4. 执行对话
        String question = "你好，请介绍一下你自己。";
        String answer = chatAgent.run(question);

        System.out.println("AI 回答: " + answer);
    }
}
```

如上所示，使用 Builder 模式构建 `ChatAgent` 的步骤如下：
1.  实例化所有必需的 `Handler` 依赖。
2.  调用 `ChatAgent.create()` 开始构建过程。
3.  通过链式调用设置模型配置和注入 `Handler`。
4.  调用 `build()` 方法生成最终的 `ChatAgent` 实例。
5.  （可选）设置回调函数以接收中间过程信息。
6.  调用 `run` 方法开始对话。

## 6.扩展技能

https://github.com/zrt-ai-lab/opencode-skills
https://github.com/openclaw/skills
https://github.com/ComposioHQ/awesome-claude-skills