# Agent 工作台 - 技术方案文档

> 版本: v0.3 | 更新时间: 2026-05-20
> 关联文档: [requirement.md](./requirement.md)

> **文档状态（2026-07）**：本文档为早期技术方案，部分模块已变更。产品说明、部署与使用手册以 [skills/mao-cli/SKILL.md](../skills/mao-cli/SKILL.md) 为准；架构概览亦见 [project.md](../skills/mao-cli/reference/project.md)。源码与下列差异：
> - **Hub 模块**已删除（`V017__remove_hub.sql`）
> - 前端流式通道为 **WebSocket**（`StreamingWsHandler`），LLM 内部仍通过 OkHttp SSE 拉流；**0.0.82 起 WS 改为首帧鉴权**（`auth` 帧携带 token，URL 不再传 token）
> - 对象存储支持 **本地文件系统** 与 **阿里云 OSS**
> - **集成配置（LDAP/飞书登录/上传/Tavily·TinyFish 搜索/OSS）0.0.82 起迁入 `system_setting` 表**，管理后台可视化编辑、热生效；新增 `settings:read`/`settings:write` 权限与 `SETTINGS_SECRET` 加密主密钥
> - Flyway 迁移脚本现为 **46 个**（非文档初稿中的 24 个）
> - 开源协议：**MIT**，仅提供自部署

---

## 1. 技术选型明细

### 1.1 后端技术栈

| 组件 | 选型 | 版本建议 | 选型理由 |
|------|------|---------|---------|
| 语言 | Java | 17+ (LTS) | 虚拟线程支持，企业级生态成熟 |
| 框架 | Spring Boot | 3.x | 自动配置、生态丰富、社区活跃 |
| Web 框架 | **Spring MVC** | - | 团队熟悉，SSE 通过 `SseEmitter` 实现 |
| ORM | MyBatis-Plus | 3.5.x | 灵活的 SQL 控制，适合复杂查询 |
| 认证 | Spring Security | - | LDAP / OAuth2 开箱即用 |
| HTTP 客户端 | OkHttp / Apache HttpClient | - | LLM API 调用，支持 SSE 流式读取 |
| 对象存储 | MinIO (S3 兼容) | - | 私有化部署，S3 协议标准 |
| LLM 客户端 | 自研 OpenAI 协议适配层 | - | 统一协议，流式 SSE 解析 |
| MCP 客户端 | 自研 MCP SDK (Java) | - | MCP 协议规范实现 |
| API 文档 | SpringDoc (OpenAPI 3) | 2.x | 自动生成 API 文档 |
| 工具库 | Hutool / Guava | - | 常用工具方法 |

### 1.2 前端技术栈

| 组件 | 选型 | 版本建议 | 选型理由 |
|------|------|---------|---------|
| 框架 | Vue 3 | 3.4+ | Composition API、更好的 TS 支持 |
| 构建工具 | Vite | 5.x | 快速构建、HMR |
| 状态管理 | Pinia | 2.x | Vue 3 官方推荐，轻量 |
| UI 组件库 | **Element Plus** | 2.x | 企业级 UI 组件丰富，中文文档完善 |
| HTTP 客户端 | Axios | 1.x | 拦截器机制适合 Token 注入 |
| 路由 | Vue Router | 4.x | Vue 3 配套 |
| 国际化 | Vue I18n | 9.x | 多语言支持（可选） |
| Markdown 渲染 | markdown-it | - | Agent 对话内容渲染 |
| 代码高亮 | highlight.js / Shiki | - | 代码块语法高亮 |

### 1.3 桌面客户端技术栈

| 组件 | 选型 | 版本建议 | 选型理由 |
|------|------|---------|---------|
| 框架 | Electron | 30+ | 跨平台成熟方案 |
| 前端 | Vue 3 + Vite | - | 独立工程，与管理后台独立维护 |
| 窗口管理 | electron-window-state | - | 窗口位置/大小记忆 |
| 自动更新 | electron-updater | - | 应用内自动更新 |
| 安全 | contextIsolation + sandbox | - | Electron 安全最佳实践 |
| IPC 通信 | electron IPC + 预加载脚本 | - | 主进程与渲染进程安全通信 |

### 1.4 基础设施

| 组件 | 选型 | 备注 |
|------|------|------|
| 数据库 | MySQL 8.x | 主数据存储 |
| 对象存储 | MinIO | 文件存储（私有化） |
| 反向代理 | Nginx | 负载均衡 + HTTPS 终结 |
| 日志 | SLF4J + Logback | 应用日志，可选接 ELK |

---

## 2. 工程结构

### 2.1 Monorepo 目录规划

```
mao/
├── backend/                        # 后端 Java 服务
│   ├── pom.xml
│   └── src/
│       └── main/
│           ├── java/cn/etarch/mao/
│           │   ├── WorkbenchApplication.java
│           │   ├── config/                 # 配置类
│           │   │   ├── SecurityConfig.java
│           │   │   ├── WebMvcConfig.java
│           │   │   └── LlmConfig.java
│           │   ├── common/                 # 公共模块
│           │   │   ├── result/             # 统一响应
│           │   │   ├── exception/          # 全局异常
│           │   │   ├── constant/           # 常量
│           │   │   └── util/
│           │   ├── auth/                   # 认证模块
│           │   │   ├── controller/
│           │   │   ├── service/
│           │   │   ├── ldap/               # LDAP 集成
│           │   │   └── feishu/             # 飞书 OAuth
│           │   ├── user/                   # 用户模块
│           │   │   ├── controller/
│           │   │   ├── service/
│           │   │   ├── mapper/
│           │   │   └── entity/
│           │   ├── agent/                  # Agent 管理模块
│           │   │   ├── controller/
│           │   │   ├── service/
│           │   │   ├── mapper/
│           │   │   └── entity/
│           │   ├── harness/                # Agent Harness 核心
│           │   │   ├── core/               # 核心引擎
│           │   │   │   ├── AgentLoop.java
│           │   │   │   ├── PromptEngine.java
│           │   │   │   ├── ContextManager.java
│           │   │   │   └── ExecutionPipeline.java
│           │   │   ├── llm/                # LLM 适配层
│           │   │   │   ├── LlmAdapter.java
│           │   │   │   ├── LlmClient.java
│           │   │   │   ├── OpenAiProtocol.java
│           │   │   │   └── model/
│           │   │   ├── skill/              # Skills 体系
│           │   │   │   ├── SkillRegistry.java
│           │   │   │   ├── SkillDispatcher.java
│           │   │   │   ├── SkillExecutor.java
│           │   │   │   └── builtin/        # 内置 Skills
│           │   │   ├── mcp/                # MCP 协议
│           │   │   │   ├── McpClient.java
│           │   │   │   ├── McpServerManager.java
│           │   │   │   └── McpToolAdapter.java
│           │   │   └── safety/             # 安全沙箱
│           │   │       ├── SafetyGuard.java
│           │   │       └── PermissionChecker.java
│           │   ├── session/                # 会话模块
│           │   │   ├── controller/
│           │   │   ├── service/
│           │   │   ├── mapper/
│           │   │   └── entity/
│           │   ├── hub/                    # Hub 模块
│           │   │   ├── controller/
│           │   │   ├── service/
│           │   │   └── entity/
│           │   ├── audit/                  # 审计模块
│           │   │   ├── interceptor/        # 审计拦截器
│           │   │   ├── service/
│           │   │   └── entity/
│           │   └── file/                   # 文件模块
│           │       ├── controller/
│           │       └── service/
│           └── resources/
│               ├── application.yml
│               ├── application-dev.yml
│               └── db/migration/           # 数据库迁移脚本
│
├── admin/                          # 管理后台 (Vue 3)
│   ├── package.json
│   ├── vite.config.ts
│   └── src/
│       ├── main.ts
│       ├── App.vue
│       ├── router/
│       ├── stores/                 # Pinia stores
│       ├── views/
│       │   ├── auth/               # 登录
│       │   ├── user/               # 用户管理
│       │   ├── model/              # 模型管理
│       │   ├── agent/              # Agent 管理
│       │   ├── skill/              # Skills 管理
│       │   ├── hub/                # Hub 管理
│       │   ├── audit/              # 审计日志
│       │   └── system/             # 系统配置
│       ├── components/
│       ├── composables/
│       ├── api/                    # API 接口层
│       └── utils/
│
├── desktop/                        # 桌面客户端 (Electron + Vue 3)
│   ├── package.json
│   ├── electron/
│   │   ├── main.ts                 # Electron 主进程
│   │   ├── preload.ts              # 预加载脚本
│   │   └── ipc/                    # IPC 处理
│   ├── src/                        # Vue 3 渲染进程
│   │   ├── main.ts
│   │   ├── App.vue
│   │   ├── router/
│   │   ├── stores/
│   │   ├── views/
│   │   │   ├── auth/               # 登录
│   │   │   ├── workbench/          # 工作台主页
│   │   │   ├── chat/               # Agent 对话
│   │   │   ├── hub/                # Agent Hub
│   │   │   ├── agent-create/       # 创建 Agent
│   │   │   └── settings/           # 设置
│   │   ├── components/
│   │   │   ├── chat/               # 对话组件
│   │   │   ├── agent/              # Agent 相关组件
│   │   │   └── common/
│   │   ├── composables/
│   │   ├── api/
│   │   └── utils/
│   └── resources/                  # 应用图标等资源
│
└── docs/                           # 文档
    ├── requirement.md
    └── 2026-05-20-technical-design.md
```

---

## 3. 数据库设计

### 3.1 核心表结构

```sql
-- ========== 用户与权限 ==========

CREATE TABLE `user` (
    `id`              BIGINT PRIMARY KEY AUTO_INCREMENT,
    `username`        VARCHAR(64) NOT NULL UNIQUE,
    `display_name`    VARCHAR(128) NOT NULL,
    `email`           VARCHAR(128),
    `avatar_url`      VARCHAR(512),
    `auth_type`       VARCHAR(20) NOT NULL COMMENT 'LDAP / FEISHU',
    `password_hash`   VARCHAR(128) COMMENT 'LDAP 用户可为空',
    `feishu_user_id`  VARCHAR(64) COMMENT '飞书用户 ID',
    `department_id`   BIGINT,
    `status`          TINYINT DEFAULT 1 COMMENT '1-启用 0-禁用',
    `last_login_at`   DATETIME,
    `created_at`      DATETIME DEFAULT CURRENT_TIMESTAMP,
    `updated_at`      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `role` (
    `id`          BIGINT PRIMARY KEY AUTO_INCREMENT,
    `name`        VARCHAR(64) NOT NULL UNIQUE COMMENT '角色名称',
    `code`        VARCHAR(64) NOT NULL UNIQUE COMMENT '角色编码',
    `description` VARCHAR(256),
    `created_at`  DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `user_role` (
    `id`      BIGINT PRIMARY KEY AUTO_INCREMENT,
    `user_id` BIGINT NOT NULL,
    `role_id` BIGINT NOT NULL,
    UNIQUE KEY `uk_user_role` (`user_id`, `role_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `permission` (
    `id`          BIGINT PRIMARY KEY AUTO_INCREMENT,
    `name`        VARCHAR(128) NOT NULL,
    `code`        VARCHAR(128) NOT NULL UNIQUE COMMENT '权限编码，如 agent:read, agent:write',
    `description` VARCHAR(256),
    `created_at`  DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `role_permission` (
    `id`            BIGINT PRIMARY KEY AUTO_INCREMENT,
    `role_id`       BIGINT NOT NULL,
    `permission_id` BIGINT NOT NULL,
    UNIQUE KEY `uk_role_perm` (`role_id`, `permission_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `department` (
    `id`        BIGINT PRIMARY KEY AUTO_INCREMENT,
    `name`      VARCHAR(128) NOT NULL,
    `parent_id` BIGINT DEFAULT 0,
    `sort_order` INT DEFAULT 0,
    `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- ========== AI 模型配置 ==========

CREATE TABLE `llm_model` (
    `id`              BIGINT PRIMARY KEY AUTO_INCREMENT,
    `name`            VARCHAR(128) NOT NULL COMMENT '模型显示名称',
    `provider`        VARCHAR(64) COMMENT '供应商标识',
    `base_url`        VARCHAR(512) NOT NULL COMMENT 'API 地址',
    `api_key`         VARCHAR(512) NOT NULL COMMENT '加密存储的 API Key',
    `model_id`        VARCHAR(128) NOT NULL COMMENT '模型标识，如 gpt-4o',
    `max_tokens`      INT DEFAULT 4096,
    `temperature_max` DECIMAL(3,2) DEFAULT 2.00,
    `status`          TINYINT DEFAULT 1 COMMENT '1-启用 0-禁用',
    `created_at`      DATETIME DEFAULT CURRENT_TIMESTAMP,
    `updated_at`      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- ========== Agent ==========

CREATE TABLE `agent` (
    `id`              BIGINT PRIMARY KEY AUTO_INCREMENT,
    `name`            VARCHAR(128) NOT NULL,
    `description`     TEXT,
    `icon_url`        VARCHAR(512),
    `system_prompt`   TEXT NOT NULL COMMENT '系统提示词（人格设定）',
    `model_id`        BIGINT NOT NULL COMMENT '关联的 LLM 模型',
    `creator_id`      BIGINT NOT NULL COMMENT '创建者用户 ID',
    `type`            VARCHAR(20) NOT NULL COMMENT 'SYSTEM-系统级 PERSONAL-个人',
    `visibility`      VARCHAR(20) DEFAULT 'PRIVATE' COMMENT 'PRIVATE / HUB / SPECIFIC',
    `status`          VARCHAR(20) DEFAULT 'DRAFT' COMMENT 'DRAFT/PUBLISHED/ARCHIVED',
    `token_limit`     INT DEFAULT 0 COMMENT '单次对话 Token 限额，0-不限',
    `max_rounds`      INT DEFAULT 0 COMMENT '单次对话最大轮数，0-不限',
    `config_json`     JSON COMMENT '扩展配置',
    `published_at`    DATETIME COMMENT '发布到 Hub 的时间',
    `created_at`      DATETIME DEFAULT CURRENT_TIMESTAMP,
    `updated_at`      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `agent_tag` (
    `id`       BIGINT PRIMARY KEY AUTO_INCREMENT,
    `agent_id` BIGINT NOT NULL,
    `tag`      VARCHAR(64) NOT NULL,
    INDEX `idx_agent_tag` (`agent_id`, `tag`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `agent_skill` (
    `id`       BIGINT PRIMARY KEY AUTO_INCREMENT,
    `agent_id` BIGINT NOT NULL,
    `skill_id` BIGINT NOT NULL COMMENT '关联 skill 表',
    `config`   JSON COMMENT '该 Agent 对此 Skill 的定制配置',
    UNIQUE KEY `uk_agent_skill` (`agent_id`, `skill_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `agent_mcp_config` (
    `id`         BIGINT PRIMARY KEY AUTO_INCREMENT,
    `agent_id`   BIGINT NOT NULL,
    `server_url` VARCHAR(512) NOT NULL COMMENT 'MCP Server 地址',
    `transport`  VARCHAR(20) DEFAULT 'SSE' COMMENT 'SSE / STDIO',
    `config`     JSON COMMENT '额外配置',
    `status`     TINYINT DEFAULT 1,
    INDEX `idx_agent` (`agent_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `agent_permission` (
    `id`              BIGINT PRIMARY KEY AUTO_INCREMENT,
    `agent_id`        BIGINT NOT NULL,
    `permission_type` VARCHAR(20) NOT NULL COMMENT 'ROLE / DEPARTMENT / USER',
    `permission_value` BIGINT NOT NULL COMMENT '对应 role_id / department_id / user_id',
    UNIQUE KEY `uk_agent_perm` (`agent_id`, `permission_type`, `permission_value`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- ========== Skills ==========

CREATE TABLE `skill` (
    `id`          BIGINT PRIMARY KEY AUTO_INCREMENT,
    `name`        VARCHAR(128) NOT NULL,
    `description` TEXT,
    `type`        VARCHAR(20) NOT NULL COMMENT 'BUILTIN-内置',
    `input_schema`  JSON COMMENT '输入参数 JSON Schema',
    `output_schema` JSON COMMENT '输出参数 JSON Schema',
    `impl_class`  VARCHAR(256) COMMENT '内置 Skill 的 Java 实现类全限定名',
    `creator_id`  BIGINT,
    `status`      VARCHAR(20) DEFAULT 'ACTIVE' COMMENT 'ACTIVE/DISABLED',
    `created_at`  DATETIME DEFAULT CURRENT_TIMESTAMP,
    `updated_at`  DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- ========== 会话与消息 ==========

CREATE TABLE `session` (
    `id`          BIGINT PRIMARY KEY AUTO_INCREMENT,
    `user_id`     BIGINT NOT NULL,
    `agent_id`    BIGINT NOT NULL,
    `title`       VARCHAR(256) COMMENT '会话标题，可自动生成',
    `status`      VARCHAR(20) DEFAULT 'ACTIVE' COMMENT 'ACTIVE/ARCHIVED',
    `is_pinned`   TINYINT DEFAULT 0,
    `is_favorite` TINYINT DEFAULT 0,
    `created_at`  DATETIME DEFAULT CURRENT_TIMESTAMP,
    `updated_at`  DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX `idx_user` (`user_id`),
    INDEX `idx_agent` (`agent_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `message` (
    `id`            BIGINT PRIMARY KEY AUTO_INCREMENT,
    `session_id`    BIGINT NOT NULL,
    `role`          VARCHAR(20) NOT NULL COMMENT 'USER / ASSISTANT / SYSTEM / TOOL',
    `content`       MEDIUMTEXT COMMENT '消息内容',
    `tool_call_id`  VARCHAR(128) COMMENT '工具调用 ID（tool role 消息时使用）',
    `tool_calls`    JSON COMMENT '工具调用列表（assistant 消息中的 function_call）',
    `token_count`   INT DEFAULT 0 COMMENT '本条消息的 Token 消耗',
    `model_id`      BIGINT COMMENT '使用的模型',
    `metadata`      JSON COMMENT '扩展元数据',
    `created_at`    DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX `idx_session` (`session_id`),
    INDEX `idx_created` (`created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- ========== Hub ==========

CREATE TABLE `hub_installation` (
    `id`         BIGINT PRIMARY KEY AUTO_INCREMENT,
    `user_id`    BIGINT NOT NULL,
    `agent_id`   BIGINT NOT NULL COMMENT 'Hub 中的 Agent',
    `installed_at` DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY `uk_user_agent` (`user_id`, `agent_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- ========== 审计日志 ==========

CREATE TABLE `audit_log` (
    `id`            BIGINT PRIMARY KEY AUTO_INCREMENT,
    `user_id`       BIGINT,
    `username`      VARCHAR(64),
    `action`        VARCHAR(64) NOT NULL COMMENT '操作类型',
    `resource_type` VARCHAR(64) COMMENT '资源类型',
    `resource_id`   VARCHAR(64) COMMENT '资源 ID',
    `detail`        JSON COMMENT '操作详情',
    `ip`            VARCHAR(45),
    `user_agent`    VARCHAR(512),
    `created_at`    DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX `idx_user` (`user_id`),
    INDEX `idx_action` (`action`),
    INDEX `idx_created` (`created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `api_call_log` (
    `id`            BIGINT PRIMARY KEY AUTO_INCREMENT,
    `user_id`       BIGINT,
    `session_id`    BIGINT,
    `agent_id`      BIGINT,
    `endpoint`      VARCHAR(256) NOT NULL,
    `method`        VARCHAR(10),
    `request_body`  MEDIUMTEXT,
    `response_code` INT,
    `latency_ms`    INT,
    `llm_model`     VARCHAR(128),
    `llm_tokens_in` INT DEFAULT 0,
    `llm_tokens_out` INT DEFAULT 0,
    `created_at`    DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX `idx_session` (`session_id`),
    INDEX `idx_created` (`created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

---

## 4. API 设计

### 4.1 API 总览

| 模块 | 方法 | 路径 | 说明 |
|------|------|------|------|
| **认证** | POST | `/api/v1/auth/login` | 统一登录入口 |
| | POST | `/api/v1/auth/feishu/qrcode` | 获取飞书扫码二维码 |
| | POST | `/api/v1/auth/feishu/callback` | 飞书扫码回调 |
| | POST | `/api/v1/auth/refresh` | 刷新 Token |
| | POST | `/api/v1/auth/logout` | 退出登录 |
| **用户** | GET | `/api/v1/users/me` | 获取当前用户信息 |
| | GET | `/api/v1/users` | 用户列表（管理员） |
| | PUT | `/api/v1/users/{id}/status` | 启用/禁用用户 |
| **模型** | GET | `/api/v1/models` | 模型列表 |
| | POST | `/api/v1/models` | 创建模型配置 |
| | PUT | `/api/v1/models/{id}` | 更新模型配置 |
| | POST | `/api/v1/models/{id}/test` | 测试模型连通性 |
| **Agent** | GET | `/api/v1/agents` | 用户可用的 Agent 列表 |
| | GET | `/api/v1/agents/{id}` | Agent 详情 |
| | POST | `/api/v1/agents` | 创建 Agent |
| | PUT | `/api/v1/agents/{id}` | 更新 Agent |
| | DELETE | `/api/v1/agents/{id}` | 删除 Agent |
| | POST | `/api/v1/agents/{id}/publish` | 发布到 Hub |
| **会话** | POST | `/api/v1/sessions` | 创建会话 |
| | GET | `/api/v1/sessions` | 会话列表 |
| | GET | `/api/v1/sessions/{id}` | 会话详情 |
| | DELETE | `/api/v1/sessions/{id}` | 删除会话 |
| | PUT | `/api/v1/sessions/{id}/pin` | 置顶/取消置顶 |
| **对话** | POST | `/api/v1/sessions/{id}/messages` | 发送消息（触发 Agent） |
| | GET | `/api/v1/sessions/{id}/messages` | 历史消息列表 |
| | GET | `/api/v1/sessions/{id}/stream` | SSE 流式输出 |
| **Hub** | GET | `/api/v1/hub/agents` | Hub Agent 列表 |
| | POST | `/api/v1/hub/agents/{id}/install` | 安装 Agent |
| | DELETE | `/api/v1/hub/agents/{id}/install` | 卸载 Agent |
| **Skills** | GET | `/api/v1/skills` | Skills 列表 |
| | POST | `/api/v1/skills` | 创建/上传 Skill |
| | PUT | `/api/v1/skills/{id}` | 更新 Skill |
| **文件** | POST | `/api/v1/files/upload` | 上传文件 |
| | GET | `/api/v1/files/{id}/download` | 下载文件 |
| **审计** | GET | `/api/v1/audit/logs` | 审计日志查询 |
| | GET | `/api/v1/audit/api-logs` | API 调用日志查询 |

### 4.2 统一响应格式

```json
{
  "code": 0,
  "message": "success",
  "data": { ... },
  "timestamp": 1716105600000
}
```

错误码规范：
| 范围 | 含义 |
|------|------|
| 0 | 成功 |
| 1001-1999 | 认证/授权错误 |
| 2001-2999 | 参数校验错误 |
| 3001-3999 | 业务逻辑错误 |
| 5001-5999 | 服务端内部错误 |

### 4.3 SSE 流式输出协议

对话采用 SSE（Server-Sent Events）实现流式输出：

```
GET /api/v1/sessions/{id}/stream
Authorization: Bearer <token>
Accept: text/event-stream

# 事件类型
event: message_start
data: {"message_id": "msg_123", "model": "gpt-4o"}

event: content_delta
data: {"delta": "你好"}

event: content_delta
data: {"delta": "，有什么"}

event: tool_call_start
data: {"tool_call_id": "tc_456", "tool_name": "web_search", "arguments": "{"query":"..."}"}

event: tool_call_result
data: {"tool_call_id": "tc_456", "result": "..."}

event: message_end
data: {"message_id": "msg_123", "usage": {"prompt_tokens": 120, "completion_tokens": 85}}

event: error
data: {"code": 5001, "message": "LLM 调用超时"}
```

---

## 5. 技术难点与解决方案

### 5.1 Agent Harness 核心引擎设计

**难点：** Harness 是整个系统的核心，需要统一处理不同 Agent 的人格、工具、上下文，同时保持可扩展性。

**方案：** 采用 Pipeline + 插件化架构

```
┌─────────────────────────────────────────────────────────────┐
│                    Execution Pipeline                        │
│                                                             │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐│
│  │  Prompt   │──▶│   LLM    │──▶│ Response │──▶│  Output  ││
│  │  Compose  │   │   Call   │   │  Parse   │   │  Render  ││
│  └──────────┘   └──────────┘   └────┬─────┘   └──────────┘│
│                                     │                       │
│                              ┌──────▼──────┐                │
│                              │ Tool Call?  │                │
│                              └──────┬──────┘                │
│                                Yes  │  No → Output          │
│                                     ▼                       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                 Tool Dispatch Layer                    │  │
│  │  ┌────────────┐  ┌────────────┐                      │  │
│  │  │   Skill    │  │    MCP     │                      │  │
│  │  │  Executor  │  │   Client   │                      │  │
│  │  └────────────┘  └────────────┘                      │  │
│  └──────────────────────────────────────────────────────┘  │
│                              │                              │
│                              ▼                              │
│                        Result Feedback                      │
│                        (回到 LLM Call)                       │
└─────────────────────────────────────────────────────────────┘
```

**关键设计决策：**

1. **Agent Loop 作为核心循环**：借鉴 Codex/ChatGPT 的 Agent Loop 模式，LLM 输出 → 解析 → 执行工具 → 结果反馈 → 再次 LLM 调用，直到 LLM 返回纯文本结果或达到最大轮次。

2. **统一的 Tool 接口**：所有工具（内置 Skill、MCP 工具）实现统一的 `Tool` 接口：

```java
public interface Tool {
    String getName();
    String getDescription();
    JsonSchema getInputSchema();
    ToolResult execute(JsonObject arguments, ExecutionContext context);
}
```

3. **异步执行 + 流式反馈**：工具执行异步化，执行过程中通过 SSE 实时推送进度给客户端。

### 5.2 LLM 统一协议适配

**难点：** 需要对接不同厂商的 LLM 服务，虽然都声称兼容 OpenAI 协议，但实际上各家有细微差异。

**方案：** 三层适配架构

```
┌───────────────────────────────────────┐
│          LlmAdapter (接口层)           │
│  定义统一的调用接口：chat() / stream()  │
└───────────────┬───────────────────────┘
                │
┌───────────────▼───────────────────────┐
│      OpenAiProtocol (协议层)           │
│  OpenAI 兼容格式的请求/响应构建与解析    │
│  - ChatCompletion 请求构建             │
│  - SSE 流式响应解析                    │
│  - function_call / tool_calls 解析     │
└───────────────┬───────────────────────┘
                │
┌───────────────▼───────────────────────┐
│     ProviderAdapter (供应商适配层)      │
│  处理各厂商的协议差异：                 │
│  - 请求头差异（认证方式）               │
│  - 响应格式微调（字段映射）             │
│  - 特有参数（如 Claude 的 system）      │
└───────────────────────────────────────┘
```

核心类设计：

```java
// 统一适配接口
public interface LlmAdapter {
    ChatResponse chat(ChatRequest request, LlmModelConfig config);
    void stream(ChatRequest request, LlmModelConfig config, StreamCallback callback);
}

// Stream 回调接口
public interface StreamCallback {
    void onChunk(StreamChunk chunk);
    void onComplete(ChatUsage usage);
    void onError(Throwable t);
}

// OpenAI 协议实现（默认，基于 OkHttp）
public class OpenAiLlmAdapter implements LlmAdapter {
    private final OkHttpClient httpClient;

    @Override
    public void stream(ChatRequest request, LlmModelConfig config, StreamCallback callback) {
        RequestBody body = RequestBody.create(
            buildRequestBody(request), MediaType.parse("application/json"));
        Request httpRequest = new Request.Builder()
            .url(config.getBaseUrl() + "/chat/completions")
            .header("Authorization", "Bearer " + config.getApiKey())
            .post(body)
            .build();

        try (Response response = httpClient.newCall(httpRequest).execute()) {
            BufferedSource source = response.body().source();
            while (!source.exhausted()) {
                String line = source.readUtf8Line();
                if (line != null && line.startsWith("data: ")) {
                    StreamChunk chunk = parseStreamChunk(line.substring(6));
                    callback.onChunk(chunk);
                }
            }
            callback.onComplete(extractUsage(response));
        } catch (Exception e) {
            callback.onError(e);
        }
    }
}
```

### 5.3 MCP 协议对接

**难点：** MCP (Model Context Protocol) 是 Anthropic 提出的开放协议，Java 生态缺乏成熟 SDK，需要自研。MCP 支持 SSE 和 STDIO 两种传输方式。

**方案：** 自研轻量 MCP Java Client

```
┌─────────────────────────────────────────┐
│              MCP Client                  │
│                                         │
│  ┌─────────────────────────────────┐    │
│  │      McpServerManager           │    │
│  │  - 服务器连接池管理               │    │
│  │  - 健康检查 / 自动重连            │    │
│  └────────────┬────────────────────┘    │
│               │                          │
│  ┌────────────▼────────────────────┐    │
│  │      Transport Layer            │    │
│  │  ┌──────────┐  ┌──────────┐    │    │
│  │  │  SSE      │  │  STDIO   │    │    │
│  │  │ Transport │  │ Transport│    │    │
│  │  └──────────┘  └──────────┘    │    │
│  └────────────┬────────────────────┘    │
│               │                          │
│  ┌────────────▼────────────────────┐    │
│  │      Protocol Layer             │    │
│  │  - initialize / initialized     │    │
│  │  - tools/list                   │    │
│  │  - tools/call                   │    │
│  │  - resources/list               │    │
│  │  - resources/read               │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
```

**核心流程：**

1. **连接阶段**：Agent 初始化时，根据 `agent_mcp_config` 表中的配置，建立与 MCP Server 的连接
2. **工具发现**：调用 `tools/list` 获取该 MCP Server 提供的所有工具，自动转换为 Harness 内部的 `Tool` 接口
3. **工具调用**：当 LLM 返回 tool_call 且目标工具属于 MCP 时，通过 MCP 协议转发调用
4. **生命周期管理**：连接池管理、心跳检测、断线重连

### 5.4 用户上传 Skills（暂缓）

**当前策略：** MVP 阶段仅支持管理后台注册的**内置 Skills** + **MCP Server 工具**两种来源。用户上传自定义脚本的能力预留设计，Phase 2 再实现。

**预留设计：**
- `skill` 表保留 `type` 字段，未来扩展 `USER_UPLOAD` 类型
- `Tool` 接口设计已考虑动态加载，未来可增加 `ScriptTool` 实现类
- Phase 2 实现时需引入 Docker 沙箱 + 代码审核流程

### 5.5 Agent 对话的流式输出

**难点：** 整个链路（客户端 → 后端 → LLM → 后端 → 客户端）都需要保持流式，任何一环阻塞都会影响体验。

**方案：** 全链路 SSE 流式管道（Spring MVC + SseEmitter）

```
客户端 (Electron)          服务端 (Spring MVC)              LLM API
     │                           │                            │
     │  POST /messages           │                            │
     │ ──────────────────────▶   │                            │
     │                           │  POST /chat/completions    │
     │                           │  (stream: true)            │
     │                           │ ────────────────────────▶  │
     │                           │                            │
     │  GET /stream (SSE)        │  ◀── SSE chunks ────────── │
     │ ──────────────────────▶   │                            │
     │                           │                            │
     │  ◀── content_delta ─────  │  ◀── data: {...} ───────── │
     │  ◀── content_delta ─────  │  ◀── data: {...} ───────── │
     │  ◀── tool_call_start ───  │  ◀── data: {...} ───────── │
     │  ◀── tool_call_result ──  │  (内部执行工具)              │
     │  ◀── content_delta ─────  │  ◀── 第二轮 LLM 调用 ────── │
     │  ◀── message_end ───────  │                            │
     │                           │                            │
```

**技术实现要点：**

1. **后端使用 Spring MVC + `SseEmitter`**：Servlet 异步机制实现 SSE，无需切换到 WebFlux
2. **LLM 调用使用 OkHttp**：通过 `ResponseBody.source()` 逐行读取 SSE 流，回调推送到 `SseEmitter`
3. **客户端使用 EventSource API**：Electron 渲染进程中标准的 SSE 消费方式
4. **Agent Loop 运行在独立线程池**：避免阻塞 Servlet 线程，通过 `SseEmitter` 跨线程推送事件

```java
// 后端核心流式处理
@GetMapping(value = "/api/v1/sessions/{sessionId}/stream",
            produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter stream(@PathVariable Long sessionId,
                         @RequestParam String eventId) {
    SseEmitter emitter = new SseEmitter(5 * 60 * 1000L); // 5 分钟超时

    // 提交到独立线程池执行 Agent Loop
    agentExecutor.submit(() -> {
        try {
            harnessService.execute(sessionId, eventId, new AgentEventListener() {
                @Override
                public void onContentDelta(String delta) {
                    emitter.send(SseEmitter.event()
                        .name("content_delta")
                        .data(Map.of("delta", delta)));
                }
                @Override
                public void onToolCallStart(ToolCall call) {
                    emitter.send(SseEmitter.event()
                        .name("tool_call_start")
                        .data(call));
                }
                @Override
                public void onMessageEnd(Usage usage) {
                    emitter.send(SseEmitter.event()
                        .name("message_end")
                        .data(usage));
                    emitter.complete();
                }
                @Override
                public void onError(Throwable t) {
                    emitter.send(SseEmitter.event()
                        .name("error")
                        .data(Map.of("message", t.getMessage())));
                    emitter.completeWithError(t);
                }
            });
        } catch (Exception e) {
            emitter.completeWithError(e);
        }
    });

    emitter.onTimeout(() -> emitter.complete());
    emitter.onError(e -> log.warn("SSE connection error", e));

    return emitter;
}

// Harness 内部 - 使用 OkHttp 读取 LLM SSE 流
public void execute(Long sessionId, String eventId, AgentEventListener listener) {
    // 1. 加载 Agent 配置 + 构建 Prompt
    // 2. 进入 Agent Loop
    AgentContext context = buildContext(sessionId, eventId);
    while (context.hasNextRound()) {
        // OkHttp 同步请求，逐行读取 SSE
        try (Response response = llmClient.stream(context.buildRequest())) {
            BufferedSource source = response.body().source();
            while (!source.exhausted()) {
                String line = source.readUtf8Line();
                StreamChunk chunk = parseSSE(line);
                switch (chunk.getType()) {
                    case DELTA -> listener.onContentDelta(chunk.getDelta());
                    case TOOL_CALL -> handleToolCall(chunk, context, listener);
                }
            }
        }
        // 如果有工具调用，执行后继续下一轮
        if (context.hasPendingToolCalls()) {
            executeToolCalls(context, listener);
        } else {
            break; // 纯文本回复，结束循环
        }
    }
    listener.onMessageEnd(context.getUsage());
}
```

### 5.6 上下文窗口管理

**难点：** LLM 有 Token 上下文限制，长对话会超出窗口。需要智能管理上下文，保证对话连贯性。

**方案：** 三级上下文策略

```
┌─────────────────────────────────────────────────────┐
│                  Context Manager                     │
│                                                     │
│  Level 1: 系统提示词（固定，始终保留）                 │
│  ┌─────────────────────────────────────────────┐    │
│  │ System Prompt + Agent 人格 + 工具描述         │    │
│  └─────────────────────────────────────────────┘    │
│                                                     │
│  Level 2: 近期对话（滑动窗口，优先保留）               │
│  ┌─────────────────────────────────────────────┐    │
│  │ 最近 N 轮完整对话（user + assistant + tool）   │    │
│  │ N 由 max_context_rounds 配置决定              │    │
│  └─────────────────────────────────────────────┘    │
│                                                     │
│  Level 3: 历史摘要（压缩旧对话）                      │
│  ┌─────────────────────────────────────────────┐    │
│  │ 对超出窗口的旧对话生成摘要，作为 context 注入    │    │
│  │ 摘要可由 LLM 自动生成或规则截断                │    │
│  └─────────────────────────────────────────────┘    │
│                                                     │
│  ┌─────────────────────────────────────────────┐    │
│  │ Token 预算分配：                              │    │
│  │   系统提示词: ~15%                            │    │
│  │   工具描述:   ~10%                            │    │
│  │   历史摘要:   ~10%                            │    │
│  │   近期对话:   ~50%                            │    │
│  │   预留输出:   ~15%                            │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘
```

**摘要生成策略：**
- 当对话轮数超过 `max_context_rounds` 时，将最早的对话批次送入 LLM 生成摘要
- 摘要格式：`[对话摘要] 用户询问了XX，助手完成了XX，关键结论：XX`
- 摘要随对话推进持续更新（增量摘要）

### 5.7 并发控制与限流

**难点：** 多用户并发使用 Agent，LLM API 有速率限制，需要合理控制并发。

**方案：** 多级限流 + 线程池控制

```
请求进入
    │
    ▼
┌──────────────┐
│  用户级限流   │  应用内滑动窗口
│  (每用户 QPS) │  例：10 次/分钟
└──────┬───────┘
       ▼
┌──────────────┐
│  Agent 级限流 │  应用内计数器
│  (并发会话数) │  例：同一 Agent 最多 50 并发
└──────┬───────┘
       ▼
┌──────────────┐
│  模型级限流   │  应用内令牌桶
│  (API 调用速率)│  例：60 次/分钟
└──────┬───────┘
       ▼
┌──────────────┐
│  线程池调度   │  ThreadPoolExecutor
│  (并发控制)   │  核心线程 / 最大线程 / 队列
└──────────────┘
```

**实现细节：**
- 用户级限流：应用内滑动窗口计数
- 模型级限流：读取 `llm_model` 配置中的速率限制参数
- 并发控制：Agent 执行提交到专用线程池，通过有界队列 + CallerRunsPolicy 背压
- 客户端体验：线程池满时返回 `event: queue_position` 告知用户排队位置
- 线程池配置建议：核心线程 20，最大线程 100，队列容量 200

### 5.8 Electron 安全与性能

**难点：** Electron 应用需要兼顾安全性和性能，避免常见安全漏洞。

**方案：**

```
┌─────────────────────────────────────────────────────┐
│                Electron 安全架构                      │
│                                                     │
│  ┌──────────────┐        ┌──────────────┐          │
│  │  主进程       │◀─IPC──▶│  渲染进程     │          │
│  │  (Node.js)   │        │  (Vue 3)     │          │
│  │              │        │              │          │
│  │  - 窗口管理   │        │  - UI 渲染    │          │
│  │  - 系统交互   │        │  - 用户交互   │          │
│  │  - 自动更新   │        │  - API 调用   │          │
│  │  - 文件操作   │        │              │          │
│  └──────────────┘        └──────────────┘          │
│                                                     │
│  安全配置：                                          │
│  - contextIsolation: true                           │
│  - nodeIntegration: false                           │
│  - sandbox: true                                    │
│  - preload.ts 白名单暴露 IPC 接口                    │
└─────────────────────────────────────────────────────┘
```

**性能优化：**
- Vue 3 组件懒加载 + 路由懒加载
- 对话列表虚拟滚动（大量消息时）
- Markdown 渲染结果缓存
- 主进程与渲染进程职责分离，避免阻塞 UI

---

## 6. 安全架构

### 6.1 认证流程

```
LDAP 登录:
用户 ──▶ 输入账号密码 ──▶ 后端 ──▶ LDAP Server 验证
                                      │
                              成功 ◀───┘
                                │
                          生成 JWT Token
                                │
                          返回给客户端

飞书扫码登录:
用户 ──▶ 点击飞书登录 ──▶ 后端生成二维码 URL
                              │
用户 ◀── 展示二维码           │
                              │
用户手机扫码 ──▶ 飞书 ──▶ 回调后端 /auth/feishu/callback
                              │
                        验证授权码 ──▶ 获取用户信息
                              │
                        匹配/创建用户 ──▶ 生成 JWT Token
                              │
                        返回给客户端
```

### 6.2 权限模型

```
User ──▶ UserRole ──▶ Role ──▶ RolePermission ──▶ Permission
                                                    │
                                          ┌─────────┼─────────┐
                                          ▼         ▼         ▼
                                     agent:read  agent:write  ...
                                          │
                                          ▼
                              AgentPermission (Agent 级权限)
                                          │
                              ┌───────────┼───────────┐
                              ▼           ▼           ▼
                           ROLE       DEPARTMENT    USER
                        (角色可见)    (部门可见)   (指定用户)
```

**权限校验流程：**
1. API 请求进入 → JWT 解析 → 获取用户 ID
2. 查询用户角色 → 获取权限列表
3. 检查是否有对应 API 的权限编码
4. 如果是 Agent 操作，额外检查 AgentPermission（该用户是否有权访问此 Agent）

### 6.3 数据安全

| 数据类型 | 保护措施 |
|---------|---------|
| 用户密码 | bcrypt 哈希存储 |
| API Key | AES-256 加密存储，仅服务端使用 |
| 对话内容 | 传输加密 (HTTPS) + 存储访问控制 |
| 审计日志 | 仅管理员可查，不可修改/删除 |

---

## 7. 部署架构

### 7.1 私有化部署拓扑

```
┌─────────────────────────────────────────────────────────────┐
│                    企业内网 / 私有云                           │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                    Nginx (反向代理)                     │  │
│  │              HTTPS 终结 + 负载均衡                      │  │
│  └────────────┬──────────────┬──────────────┬────────────┘  │
│               │              │              │               │
│  ┌────────────▼───┐  ┌──────▼──────┐  ┌───▼────────────┐  │
│  │   Backend      │  │   Admin     │  │   MinIO        │  │
│  │   (Spring Boot)│  │   (Vue 3)   │  │   (文件存储)    │  │
│  │   x N 实例     │  │   静态资源   │  │                │  │
│  └────────┬───────┘  └─────────────┘  └────────────────┘  │
│           │                                                 │
│  ┌────────▼──────────────────────────────────────────────┐  │
│  │                    内部网络                             │  │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐               │  │
│  │  │  MySQL   │  │  LDAP   │                            │  │
│  │  │  8.x    │  │ Server  │                            │  │
│  │  └─────────┘  └─────────┘                            │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  外部依赖：                                                  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  LLM API (OpenAI / Claude / 自部署模型)                 │  │
│  │  飞书开放平台 (扫码登录)                                 │  │
│  │  MCP Server (外部工具服务)                               │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

---

## 8. 关键依赖与风险评估

| 风险项 | 影响 | 等级 | 应对措施 |
|--------|------|------|---------|
| LLM API 稳定性 | 对话功能不可用 | 高 | 多模型备份、降级策略、超时重试 |
| MCP 协议演进 | 需要持续适配 | 中 | 抽象协议层，隔离变化影响 |
| Electron 包体大小 | 用户下载体验 | 低 | asar 打包 + 按需分发 |
| 长对话 Token 超限 | 对话截断 | 中 | 智能上下文管理 + 摘要压缩 |
| 并发压力 | 响应变慢 | 中 | 多级限流 + 线程池背压 + 水平扩展 |

---

## 9. 已确认决策

| 问题 | 决策 |
|------|------|
| Spring WebFlux vs Spring MVC | **Spring MVC** + `SseEmitter` 实现 SSE |
| 消息队列选型 | **暂不引入 MQ**，使用线程池控制并发 |
| 用户上传 Skills | **MVP 跳过**，仅支持内置 Skills + MCP |
| 前端代码共享 | **独立维护**，管理后台与桌面端各自独立 |

> 暂无待讨论问题，可继续补充新需求或进入工程初始化阶段。