# 一起学习，共同进步！

**Repository Path**: sky_sky_up/learn-together--grow-together

## Basic Information

- **Project Name**: 一起学习，共同进步！
- **Description**: 夏令营项目开发，希望大家都能一起学到很多东西
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 5
- **Created**: 2026-07-15
- **Last Updated**: 2026-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BAN：Java 版 OpenClaw 微信 AI 聊天助手

BAN 是一个面向个人本地部署、基于 Java 21、Spring Boot 和微信 iLink 协议实现的 AI Agent 项目。项目参考 OpenClaw 的路由、Agent Loop、Tool Calling 和上下文工程思路，当前已经打通微信消息接入、模型调用、多模态工具、持久化与语义记忆链路。

本项目是学习和工程实践项目，不是 OpenClaw 官方 Java 移植版本。

每个安装实例由使用者在自己的设备上配置和运行，通过终端二维码绑定微信。项目不提供平台账号、多租户、云端托管机器人或 Web 用户控制台；数据库中的用户、机器人和会话 ID 仅作为本地运行时的数据作用域。

## 当前能力

| 能力 | 状态 | 说明 |
| --- | --- | --- |
| 微信 iLink 接入 | 已实现 | 扫码登录、Token、cursor、长轮询、消息去重和状态持久化 |
| Agent Runtime | 已实现 | 请求路由、Agent Loop、Tool Calling、多步执行、结果证据检查和异常兜底 |
| 文本对话 | 已实现 | 通过统一 `ModelGateway` 调用 DeepSeek 文本模型 |
| 图片能力 | 已实现 | 图片理解、文生图、多图上下文和图生图编辑 |
| 语音理解 | 已实现 | 微信语音下载、解密、语音模型理解和文本上下文增强 |
| 语音回复 | 已实现 | Agent 调用 TTS 工具生成 MP3，并以微信文件消息返回 |
| 天气查询 | 已实现 | Agent 调用高德天气工具查询实况天气和未来预报 |
| 网页搜索 | 已实现，可选 | Agent 调用 Tavily 按关键词返回候选网页及来源，不抓取整篇网页 |
| 网页爬取 | 已实现，可选 | Agent 调用 `web_fetch` 抓取公开网页正文，调用网页资产工具发现和下载公开文件资源 |
| SQLite 持久化 | 已实现，内置 | 保存本地身份映射、Agent、会话、消息、知识库、运行事件和模型调用记录 |
| 本地附件存储 | 已实现，内置 | 将用户上传和 Agent 生成的图片、音频及文件保存到应用数据目录 |
| 本地语义记忆 | 已实现，内置 | SQLite 向量登记与本地 Lucene 加速，对历史消息按当前问题召回相关上下文 |
| PDF 与历史查询 | 阶段性实现 | 接收 iLink 文件，提供受控 PDF 解析、PDF 生成和聊天记录查询工具；本次提交中 PDF 能力仍不完整 |

说明：当前语音回复通过 `file_item` 返回音频文件，不是微信原生气泡语音。PDF 相关功能仍待真实微信链路验收，P0 暂不支持扫描件 OCR、复杂表格结构恢复或密码破解。

## 项目结构

```text
ban/
├─ ilink-sdk/   # 独立的微信 iLink 协议 SDK
├─ ban-app/     # Spring Boot 应用、Agent Runtime 和业务能力
├─ docs/        # 中文分类文档、架构设计和开发方案
└─ pom.xml      # Maven 聚合与统一版本管理
```

### Maven 模块

| 模块 | 职责 |
| --- | --- |
| `ilink-sdk` | 封装扫码登录、Token、cursor、长轮询、去重、状态存储以及文本、图片、语音和文件协议；不依赖 Spring Boot 业务代码 |
| `ban-app` | 应用入口，包含微信渠道适配、Agent Runtime、模型网关、工具、上下文、本地持久化和语义记忆 |

依赖方向固定为：

```text
ban-app -> ilink-sdk
```

LLM、图片、语音、天气和存储暂时保留在 `ban-app`，不为单一实现额外拆分 Maven 模块。

### 应用包结构

```text
com.example.ban
├─ agent            # Agent Loop、上下文、工具定义与内置工具
│  ├─ runtime       # Agent Loop、事件和执行轨迹
│  ├─ session       # 短期上下文、持久化上下文恢复与压缩摘要
│  └─ tool          # Agent Tool 定义、注册和内置工具
├─ capability       # 可被 Agent 调用的业务能力实现
│  ├─ image         # 图片理解、生成和编辑
│  ├─ pdf           # 受控 PDF 解析与安全 Markdown 转 PDF
│  ├─ voice         # 语音理解与语音合成
│  ├─ weather       # 天气能力及高德实现
│  └─ webSearch     # 网页搜索能力及 Tavily 实现
├─ channel          # 外部渠道适配
│  └─ ilink         # iLink 渠道与 Agent 的适配层
├─ config           # Spring 配置和配置属性
├─ error            # 统一业务异常和错误记录
├─ infra            # 基础设施适配
│  ├─ persistence   # MyBatis-Plus、实体、Mapper 和运行数据持久化
│  └─ storage       # 本地附件存储
├─ memory           # 本地语义索引与召回
└─ model            # 统一模型请求、网关和供应商 Provider
```

## 核心链路

```text
微信用户
  -> iLink getupdates
  -> ilink-sdk
  -> IlinkGatewayHandler
  -> AgentService
  -> AgentDispatcher
  -> AgentRuntime / AgentLoop
  -> ModelGateway / AgentTool
  -> AgentReply
  -> iLink sendmessage
  -> 微信用户
```

持久化链路：

```text
结构化事实     -> SQLite
图片/音频/文件 -> 本地 Artifact 目录
语义检索索引   -> SQLite + 本地 Lucene 索引目录
```

SQLite 和本地 Artifact 目录是长期事实源；Lucene 索引目录只保存可重建的加速数据，索引不可用时会回退到 SQLite cosine 检索，不影响基础聊天链路。

## Agent 工具

当前已注册的内置工具：

| Tool | 用途 |
| --- | --- |
| `resolve_location` | 解析行政区、街道或小区等 POI，返回地址、坐标和 adcode，或返回主机当前城市 |
| `query_weather` | 查询城市/区县实况天气和未来预报 |
| `web_search` | 按关键词查询候选网页及来源，不抓取整篇网页 |
| `web_fetch` | 抓取公开网页正文，支持受控静态抓取和可选 HtmlUnit 动态兜底 |
| `web_asset_discover` | 从公开网页中发现 PDF、Word、Excel、PPT 等资源链接 |
| `web_asset_download` | 下载公开直链文件并作为附件 Artifact 写入上下文 |
| `generate_image` | 根据文本生成图片 |
| `understand_image` | 理解当前或历史图片 |
| `edit_image` | 根据指令编辑图片 |
| `generate_voice` | 根据文本和音色要求生成语音文件 |
| `parse_file` | 读取当前或历史文件附件，P0 支持 PDF / TXT / Markdown / CSV / DOC / DOCX / XLS / XLSX / PPT / PPTX / JSON / XML / YAML / 常见代码文件 |
| `render_document` | 将 Markdown 安全渲染为 PDF 文件 Artifact |
| `build_spreadsheet` | 将结构化表格渲染为 XLSX / CSV 文件 Artifact |
| `query_chat_history` | 在当前用户、机器人和会话内查询历史消息与附件引用 |

工具是否向模型暴露由当前会话范围和功能配置共同决定。例如图片工具只在存在可用图片上下文时暴露，语音生成工具只在 TTS Provider 配置完整时暴露。

## 多模态处理

### 图片

```text
发送图片
  -> 保存图片上下文
  -> 用户继续发送处理要求
  -> Agent 选择图片理解或编辑工具
  -> 返回文字或图片

发送“帮我生成一张海报”
  -> Agent 调用 generate_image
  -> 返回生成图片
```

### 语音

语音采用两层处理：

```text
Agent Loop 外侧
  -> 下载和解密微信语音
  -> 语音模型生成转写、语气等理解结果
  -> 增强当前用户消息

Agent Loop 内侧
  -> 用户提出语音生成需求
  -> Agent 调用 generate_voice
  -> TTS Provider 生成 MP3
  -> 通过 file_item 返回微信
```

语音理解当前支持硅基流动 Provider，语音合成支持硅基流动和阿里云百炼 Provider。

## 上下文与记忆

当前上下文分为三层：

1. `ConversationService` 保存最近几轮对话和当前可用媒体。
2. SQLite 与本地 Artifact 目录恢复持久化消息和媒体事实。
3. `SemanticMemoryService` 使用 Embedding + 本地向量检索召回相关历史片段。

普通聊天默认只加载有限轮次，避免把全部历史塞进模型。需要更早的内容时，Agent 可按需调用 `query_chat_history`，并通过稳定附件引用继续调用 `parse_file`；实现边界见 [上下文、记忆与数据持久化](docs/02-架构设计/上下文记忆与数据持久化.md) 和 [多模态工具能力说明](docs/03-能力方案/多模态工具能力说明.md)。

## 环境要求

- JDK 21
- Windows PowerShell、Linux 或 macOS 终端
- Maven Wrapper，仓库已包含，无需单独安装 Maven
- SQLite JDBC 已随应用打包，无需安装数据库服务

## 快速开始

### 1. 准备配置

在仓库根目录创建本地 `.env`：

```powershell
Copy-Item .env.example .env
```

Linux 或 macOS：

```bash
cp .env .env
```

真实 API Key 和 Token 只能写在本地 `.env` 或部署环境变量中，禁止提交到 Git。

### 2. 选择运行模式

项目现在不再提供本地交互入口；本地校验请直接跑单测或启动应用本身。微信相关联调主要看下面两种模式。

运行微信 AI Agent 机器人：

```properties
ILINK_ENABLED=true
DEEPSEEK_API_KEY=<本地密钥>
```

SQLite 持久化默认启用；需要指定独立数据目录时：

```properties
SPRING_PROFILES_ACTIVE=local
BAN_HOME=<本地数据目录>

```

启用语义记忆时，只需配置 Embedding 模型：

```properties
EMBEDDING_ENABLED=true
EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B
SEMANTIC_MEMORY_ENABLED=true
```

图片、语音和各模型 Provider 的完整配置见 [.env.example](.env)。

### 3. 构建与测试

Windows：

```powershell
.\mvnw.cmd -pl ban-app -am test
.\mvnw.cmd -pl ban-app -am package
```

Linux 或 macOS：

```bash
./mvnw -pl ban-app -am test
./mvnw -pl ban-app -am package
```

### 4. 启动应用

```powershell
java -jar .\ban-app\target\ban-app-0.0.1-SNAPSHOT.jar
```

也可以在 IDEA 中直接运行 `com.example.ban.BanApplication`，JDK 选择 21，Working directory 设置为仓库根目录。

首次启用 iLink 时，终端会输出二维码。扫码登录后，登录状态由 SDK 保存到本地状态目录；状态文件包含敏感凭据，不能提交。

## 配置开关

| 环境变量 | 默认值 | 用途 |
| --- | --- | --- |
| `ILINK_ENABLED` | `false` | 启用微信 iLink 机器人 |
| `IMAGE_ENABLED` | `false` | 启用图片理解、生成和编辑 |
| `VOICE_ENABLED` | `false` | 启用入站语音理解 |
| `VOICE_SYNTHESIS_ENABLED` | `false` | 启用语音生成 Tool |
| `SEMANTIC_MEMORY_ENABLED` | `false` | 启用本地语义记忆 |
| `TAVILY_API_KEY` | 空 | 配置后暴露 `web_search`，按关键词返回候选网页及来源 |
| `WEB_FETCH_ENABLED` | `false` | 启用公开网页正文抓取工具 `web_fetch` |
| `WEB_ASSET_ENABLED` | `false` | 启用网页资源发现和下载工具 `web_asset_discover` / `web_asset_download` |
| `DOCUMENT_RENDER_FONT_PATH` | 空 | `render_document(format=pdf)` 必填的本地 TTF/OTF 字体；未配置时不暴露文档生成工具，读取文件不受影响 |
| `SPRING_PROFILES_ACTIVE` | `local` | 启用 SQLite、Flyway、MyBatis-Plus 和本地控制台 |

配置入口为 [application.yml](ban-app/src/main/resources/application.yml)，SQLite Profile 位于 [application-local.yml](ban-app/src/main/resources/application-local.yml)。

## 数据安全

- 不提交 `.env`、API Key、Token、Cookie 和数据库密码。
- 不提交 iLink 登录状态、二维码、用户媒体和临时下载 URL。
- 日志中只记录脱敏后的消息 ID 和用户标识。
- Agent Tool 不应接受模型自行传入的用户、机器人、会话或本地存储路径。
- SQLite 保存结构化事实与向量登记，本地 Artifact 目录保存媒体原文件，Lucene 仅保存可重建加速索引。

## 开发计划

当前下一阶段重点：

1. 强化上下文压缩、历史召回、附件恢复和真实微信链路稳定性。
2. 完善 MCP 协议兼容、连接生命周期和外部能力扩展。
3. 改进本地安装、配置、运行诊断体验，并在底座稳定后推进 Subagent。

规划能力不会在 README 中描述为已经可用，具体边界以对应开发方案为准。

## 项目文档

### 快速入口

- [文档索引](docs/文档索引.md)
- [项目总览与能力边界](docs/01-项目总览/项目总览与能力边界.md)
- [整体架构与运行链路](docs/02-架构设计/整体架构与运行链路.md)
- [Agent Loop、工具系统与过程事件](docs/02-架构设计/AgentLoop工具与过程事件.md)
- [上下文、记忆与数据持久化](docs/02-架构设计/上下文记忆与数据持久化.md)
- [多模态工具能力说明](docs/03-能力方案/多模态工具能力说明.md)
- [iLink 协议接入与模型网关](docs/04-接入与模型/iLink协议与模型网关.md)
- [部署与配置说明](docs/05-部署运维/部署与配置说明.md)
- [后续演进与协作说明](docs/06-团队协作/后续演进与协作说明.md)

### 协作约定

- [协作开发约定](协作开发约定.md)

## 说明

项目仍处于快速迭代阶段。建议按“SQLite 基础链路 -> 文本 -> 图片 -> 语音 -> 本地附件 -> 本地语义记忆”的顺序逐步启用和联调。