# myapboa

**Repository Path**: dingyi1399/myapboa

## Basic Information

- **Project Name**: myapboa
- **Description**: 仿照 apboa 架构、基于 AgentScope Java 2.x 从零重构的企业级 AI 智能体平台（HarnessAgent + AG-UI + Vue3 管理台）
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-09-26
- **Last Updated**: 2026-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Myapboa

> 仿照 [apboa](https://github.com/huxuehao/apboa) 架构、基于 **AgentScope Java 2.x** 从零重构的
> 企业级 AI 智能体平台。

> 📋 进展 / 风险 / 规划以 **[docs/project-log.md](docs/project-log.md)** 为准。

## 与 apboa 的对应关系

| 项 | apboa（AgentScope 1.0.12） | Myapboa（AgentScope 2.0.3-SNAPSHOT） |
|---|---|---|
| Agent 形态 | `ReActAgent` | `ReActAgent`（2.x builder 直装；未用 `HarnessAgent`，因其不迁移 knowledge/hook） |
| 装配层 | `ReActAgentHelper` | `ReActAgentHelper`（2.x 适配：stateStore / middleware / skillRepository） |
| 模型 | core.model.*ChatModel | extensions-model-*（DashScope / OpenAI / Anthropic / Gemini / Ollama） |
| 会话记忆 | Session + StatePersistence | `AgentStateStore`（memory / redis / mysql，运行时默认 mysql） |
| 钩子 | Hook / HookEvent | `MiddlewareBase`（`IAgentHook` + 工作空间 / Groovy / RequestLog / Studio） |
| 技能 | SkillBox | 分层 `AgentSkillRepository`（文件系统打底 + 库内内存仓库优先） |
| 规划 | PlanNotebook | `enableTaskList()`（plan mode 预留，见 P3.2） |
| 对话执行 | console shadow 11 个 io.agentscope 类 | 官方 agui-spring-boot-starter |
| 执行模型 | `agent.stream` → Flux\<Event\> | `agent.streamEvents` → Flux\<AgentEvent\> |

## 项目结构

```
myapboa
├── pom.xml                 # Spring Boot 4.0.4 + agentscope-bom 2.0.3-SNAPSHOT
├── common/                 # 实体 / DTO / 工具 / JWT
├── core/                   # Agent 装配（ReActAgentHelper）+ 模型/工具/中间件/RAG/MCP
│   └── …/core/agent|model|tool|hook|skill|state|rag|mcp|memory|agui|studio
├── biz/                    # 16 个子模块：agent/model/tool/mcp/skill/knowledge/…
├── cluster/ websocket/ job/
├── security/script-security/
├── console/                # 入口，端口 3060
├── ui/                     # Vue3 管理端，端口 3000
└── docs/                   # project-log.md 为全景文档
```

## 快速开始

### 1. 环境要求
- JDK 21+
- Maven 3.9+（本机：`E:\Tools\maven\apache-maven-3.9.16`）
- 构建时使用工作区 settings：`-s E:\code\maven-settings.xml`（本地仓库 `E:\code\.m2-repo` + 阿里云镜像）

### 2. 安装 AgentScope 2.0.3-SNAPSHOT 到本地仓库

```powershell
cd E:\code\agentscope_java
& 'E:\Tools\maven\apache-maven-3.9.16\bin\mvn.cmd' -s E:\code\maven-settings.xml `
    -DskipTests "-Dspotless.check.skip=true" "-Dspotless.apply.skip=true" install
```

### 3. 构建并启动 Myapboa

```powershell
cd E:\code\myapboa
$env:DASHSCOPE_API_KEY = "sk-xxxx"
& 'E:\Tools\maven\apache-maven-3.9.16\bin\mvn.cmd' -s E:\code\maven-settings.xml install
& 'E:\Tools\maven\apache-maven-3.9.16\bin\mvn.cmd' -s E:\code\maven-settings.xml `
    -pl console spring-boot:run `
    "-Dspring-boot.run.arguments=--spring.config.location=classpath:/application.yml"
```

### 4. 验证

- 对话页：http://localhost:3060/（静态页由官方 agui 示例提供，endpoint 已改为 `/myapboa/agui/run`）
- AG-UI API：`POST http://localhost:3060/myapboa/agui/run/myapboa-assistant`

```powershell
curl.exe -N -X POST http://localhost:3060/myapboa/agui/run/myapboa-assistant `
  -H "Content-Type: application/json" `
  -d '{"threadId":"t1","runId":"r1","messages":[{"id":"m1","role":"user","content":"北京天气怎么样？"}]}'
```

## 配置说明

| 配置键 | 默认值 | 说明 |
|---|---|---|
| `myapboa.model.dashscope.api-key` | 环境变量 `DASHSCOPE_API_KEY` | DashScope API Key |
| `myapboa.model.dashscope.model-name` | `qwen-plus` | 模型名 |
| `myapboa.model.mock-enabled` | `false` | `true` 时使用 MockChatModel（无 Key 端到端验证 ReAct 循环） |
| `myapboa.skill.repository-dir` | `./myapboa-skills` | 文件系统技能仓库目录 |
| `jwt.secret` / `JWT_SECRET` | 见 yml | 必须是合法 Base64（标准或 URL-safe），解码后 ≥32 字节，否则登录失败。**失败时 HTTP 仍返回 200**，真实错误码 500 在响应体 `code` 字段，前端提示为「jwt.secret 不是合法 Base64」。生成：`[Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(48))` |
| `myapboa.state-store.type` | `mysql` | 会话状态持久化：`memory`（重启丢失）/ `redis`（复用 spring.data.redis）/ `mysql`（复用主 DataSource） |
| `myapboa.state-store.database` / `table-name` | `myapboa` / `agentscope_sessions` | mysql 模式的库表 |
| `myapboa.state-store.create-if-not-exist` | `true` | mysql 模式库/表不存在时自动创建 |
| `myapboa.state-store.key-prefix` | `myapboa:state:` | redis 模式的 key 前缀 |
| `agentscope.agui.path-prefix` | `/myapboa/agui` | AG-UI 端点前缀 |

## 后续规划（Roadmap）

完整条目与完成标准见 [docs/project-log.md](docs/project-log.md) 第五节。当前重心：

1. docker-compose / CI / 部署形态
2. RAG/LTM 跟进 2.x 新 API（旧 API 仍可用、已标弃用；P3.4 阻塞）
3. ui 前端 e2e / 多实例部署验证

### 已完成的迁移适配（对照 apboa 1.x）

| apboa 1.x | Myapboa 2.x | 状态 |
|---|---|---|
| `ReActAgentHelper`（builder 装配） | `ReActAgentHelper`（2.x `ReActAgent.builder` 直装） | ✅ |
| `ChatModelFactory`（core.model.*ChatModel） | `ChatModelFactory`（extensions-model-dashscope） | ✅ |
| `ToolkitFactory` + @Tool 工具 | 同构保留（2.x Toolkit/registerTool） | ✅ |
| `HooksFactory` + Hook/HookEvent | `MiddlewareBase`（IAgentHook / 工作空间 / Groovy / RequestLog / Studio） | ✅ |
| `SkillBoxFactory` + SkillBox | `SkillBoxFactory`→内存 `AgentSkillRepository` + `SkillRepositoryFactory` 文件系统仓库 | ✅ |
| `AutoContextMemory/AutoContextHook` | `MemoryConfig` + `CompactionConfig`（harness） | ✅ |
| console shadow 11 个 io.agentscope 类 | 官方 agui starter（无需 shadow） | ✅ |
| `MysqlSession/InMemorySession` 会话池 | `ThreadSessionManager`（starter 官方）+ AgentStateStore | ✅ |
| `PlanNotebook` | `enableTaskList()`（`TaskListFlowIT`；完整 plan mode 在 HarnessAgent，未切） | ✅ |
| MCP（`tool.mcp.McpClientBuilder`） | stdio echo 闭环（`McpEchoFlowIT`：`TOOL_CALL_START` + `echo:ping`） | ✅ |
| `StudioManager` | agentscope-extensions-studio | 📋 预留 |

## License

MIT

## 完整平台功能（对齐 apboa）

### 已迁移模块（25 个 Maven 模块全部编译通过）
- common（实体/DTO/工具/安全）· cluster（Redis 集群）· websocket · script-security（Groovy 脚本安全）
- 16 个 biz 子模块：model/prompt/tool/mcp/skill/knowledge/hook/sensitive/agent/account/resource/params/a2a/studio/sk/rag
- core（Agent 装配，2.x 适配）+ job（Quartz）+ console + ui（Vue3）

### 核心能力（全部经真实模型端到端验证）
| 能力 | 状态 |
|---|---|
| 登录认证（JWT + Redis） | ✅ admin/Admin@123.com |
| 模型供应商/配置管理（DashScope/OpenAI/Anthropic/Gemini/Ollama） | ✅ |
| 智能体定义管理（CUSTOM/A2A + 工具/技能/知识库/钩子关联） | ✅ |
| AG-UI 对话（qwen-plus 真实流式 + 工具调用闭环） | ✅ 时间/计算工具验证 |
| Tool（内置 @Tool + 在线 Groovy + MCP 预留） | ✅ 3 工具入库 |
| Skill（AgentSkillRepository + Git/本地导入） | ✅ |
| RAG（本地/百炼/Dify/RagFlow + 向量存储） | ✅ 迁移完成 |
| Hook/Middleware（内置 + 在线 Groovy） | ✅ |
| 长期记忆（Mem0/ReMe/Bailian） | ✅ 3 类型注册 |
| 定时任务（Quartz + 分布式锁） | ✅ |
| 集群（Redis 发布订阅 + 会话管理） | ✅ |
| 前端管理界面（Vue3 + AntDV） | ✅ 3000 端口 |

### 启动方式（本机必读）
```powershell
# 后端（注意 config.location 参数！）
$env:DASHSCOPE_API_KEY = "sk-xxx"; $env:JWT_SECRET = "<合法Base64>"
java -jar console\target\myapboa-console-1.0-SNAPSHOT.jar --spring.config.location=classpath:/application.yml
# 前端
cd ui; pnpm dev   # http://localhost:3000
# 基础设施
docker run -d --name myapboa-redis -p 6379:6379 redis:7   # Redis
# MySQL：导入 docs\once_db_init\db_init.sql（myapboa 库 41 表）
```

### 自动化测试

4 条 IT（MySQL 主路径 / Redis 加测 / MCP echo 闭环 / Task list）。MockChatModel 免 API Key。
前提：本机 MySQL(3306) 与 Redis(6379) 在线，否则自动跳过。

```powershell
& 'E:\Tools\maven\apache-maven-3.9.16\bin\mvn.cmd' -s E:\code\maven-settings.xml -pl console -am test
```

登录协议说明：客户端须先对明文密码做一次 MD5 摘要再提交（与 ui 端 js-md5 行为一致，
服务端以 SHA-256 加盐存储）。`verify-full.ps1` 已同步该协议。

### 已知限制（迁移遗留，详见 docs/migration-log.md）
1. Spring Boot 4 需显式 `--spring.config.location`（SB4 默认不加载 fat jar 内 yml）
2. AutoContext 记忆压缩、PlanNotebook 在 2.x 移除 → stateStore/enableTaskList 替代
3. RAG/LTM 的 2.x API 标记弃用（迁移完成，待官方 2.x 新 API 稳定后切换）
4. druid-spring-boot-3-starter 在 SB4 运行时已实测可用（连接池正常）