# wolfking-agent-scope

**Repository Path**: wolfking/wolfking-agent-scope

## Basic Information

- **Project Name**: wolfking-agent-scope
- **Description**: 基于阿里巴巴 agent-scope 2.0的 智能体脚手架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WolfKing Agent 工程分析

> 自动生成于 2026-08-07 | 基于 wolfking-agent-scop (v1.0-SNAPSHOT)

---

## 1. 技术栈

| 层级      | 技术                                          |
|-----------|-----------------------------------------------|
| 语言      | Java 17                                       |
| 框架      | Spring Boot 3.5.3                             |
| 构建      | Maven 多模块                                  |
| AI 框架   | AgentScope 2.0.0 (HarnessAgent + MCP + Skill) |
| ORM       | MyBatis-Plus 3.5.17 + mybatis-plus-join 1.5.9 |
| 数据库    | MySQL 8.x (Druid 1.2.28 连接池)               |
| 动态生成  | Javassist 3.29.2-GA                           |
| 模板引擎  | FreeMarker (SQL 模板渲染)                     |
| 调度器    | Quartz 2.4.0                                  |
| 即时通信  | WebSocket (JSR 356)                           |
| 文档处理  | iText 9.7.0, docx4j 17.0.2, flexmark 0.64.8   |
| 初始用户  | admin/admin                                   |
| 访问地址  | http://127.0.0.1:9111/                        |
| 初始化SQL | ./agent-web/src/main/resources/agentscope.sql |

---

## 2. 模块结构

```
wolfking-agent-scop
├── agent-toolkit-base         基础工具抽象 (系统工具注解、Context、文件服务)
├── agent-core                 核心业务层 (Agent 管理、对话编排、数据层)
├── agent-web                  Spring Boot 入口 + REST 控制器 + Thymeleaf 模板
├── agent-toolkit-extend
│   ├── agent-image-tool       OCR 识别、HTML→图片
│   ├── agent-doc-tool         MD/HTML/DOCX/PDF/Excel 互转
│   ├── agent-system-tool      文件/HTTP/证书/ZIP/Python/Node 脚本
│   ├── agent-es-tool          ES 日志查询 (拓扑/链路/成本/异常分析)
│   ├── agent-git-tool         GitLab API 操作
│   └── agent-push-tool        企微机器人推送
└── agent-channel
    ├── agent-channel-websocket WebSocket 对话通道 (/ws/chat)
    └── agent-channel-wxcom    企微通道
```

---

## 3. 核心架构

### 3.1 请求链路 (一次对话的完整路径)

```
客户端 → WebSocket /ws/chat → ChatWebSocketEndpoint.onMessage()
  → 解析 WsRequestMessage (JSON, 含 action 路由码)
  → SPI 代理选择 WsMessageDeal 实现 (AskMessageDeal)
  → WsAgentChatService.askAgent()
    → 线程池提交异步任务:
       [push 线程] pushSocket() → 阻塞消费 pushQueue → 推送到 WS
       [ask 线程]  AgentChatService.askAgent()
         → Token 校验 (AgentUserTokenPackageService)
         → 借出 HarnessAgent (HarnessAgentService.borrowHarnessAgent)
         → agent.streamEvents(userMsg, ctx)  ← Flux<AgentEvent>
         → AskingCallback (内部回调类)
           → 事件分类: Thinking / Tool / Text / Data / Model / Agent
           → 持久化: ChatProcess / ChatAnswer / ChatModelTokens
           → 推送: WsPusher → pushQueue → WS 客户端
         → blockLast() 等待流结束
         → 归还 HarnessAgent
```

### 3.2 Agent 生命周期管理

```
HarnessAgentService
  └── ConcurrentHashMap<String, AgentConfig> harnessAgentMap
       ├── borrowHarnessAgent(configKey) → 引用计数+1
       ├── returnAgent(configKey, agent)  → 引用计数-1
       ├── scheduledRefresh() [10s 定时]
       │    ├── 扫描 config_agent 表 (仅 enabled=true)
       │    ├── 对比 updateTime (含关联的 MCP/Skill/SQLTool/SysTool/Rule)
       │    ├── 有变更 → buildHarnessAgent → 设为 newHarnessAgent
       │    └── 旧 Agent 引用归零 → closeAndSwap → 异步队列关闭
       └── agentCloseQueue (LinkedBlockingDeque)
            → closeAgentThread 消费者 (daemon)
            → closeHarnessAgent() → 注销 SQL 工具类 → agent.close()
```

### 3.3 SPI 路由机制

```
@SpiScan("com.wolfking") [WolfkingAgentDriver]
  → SpiSelectorRegister (ImportBeanDefinitionRegistrar)
    → SpiSelectorScanner: 扫描所有 @SpiInterface 接口
      → 替换 BeanDefinition → SpiSelectorProxyFactory (SmartFactoryBean)
        → 收集 Spring 容器中所有该接口的实现 Bean
        → 构建 code → bean 映射表
        → getObject() 返回 Javassist/JDK 动态代理
          → 代理从 SpiApplicationContext ThreadLocal 读取当前 code
          → 路由到对应 bean

使用方式:
  SpiApplicationContext.setSpiCode("ask");
  SpringContext.getBean(WsMessageDeal.class).dealMessage(session, msg);
  SpiApplicationContext.cleanCode();
```

---

## 4. WebSocket 消息协议

### 4.1 请求格式

```json
{
  "action": "ask|create_session|delete_session|list_sessions|load_messages|rename_session|stop_ask|clear_messages",
  "userId":  123,
  "sessionId": "uuid",
  "agentId":  "config_key",
  "askId":     "uuid (可选, 服务端自动生成)",
  "content":  "用户输入文本",
  "name":     "会话名 (create/rename 使用)",
  "files":    [{"name": "...", "base64": "..."}]
}
```

### 4.2 响应消息类型

| type | 消息类 | 用途 |
|---|---|---|
| `process` | ProcessReplyMessage | 流式过程事件 (thinking/tool/text/data) |
| `complete` | CompleteReplyMessage | 一次对话结束信号 |
| `error` | ErrorReplyMessage | 错误通知 |
| `messages` | MessagesReply | 历史消息列表 (分页) |
| `sessions` | SessionListReply | 会话列表 |
| `session_created` | SessionCreatedReply | 新会话创建 |
| `session_renamed` | SessionRenamedReply | 会话重命名 |
| `session_deleted` | SessionDeletedReply | 会话删除 |
| `session_cleared` | SessionClearedReply | 清空会话消息 |

---

## 5. REST API 总览

### 5.1 控制器一览

| 路径前缀 | 控制器 | 功能 |
|---|---|---|
| `/api` | LoginController | 登录/登出/校验 (LDAP + 本地) |
| `/config/agent` | ConfigAgentController | Agent 配置 CRUD + 多对多关联管理 |
| `/config/model` | ConfigModelController | 模型配置 CRUD |
| `/config/mcp` | ConfigMcpController | MCP 服务端配置 CRUD |
| `/config/datasource` | ConfigDataSourceController | JDBC 数据源配置 CRUD |
| `/config/dict` | ConfigDictController | 字典/键值对配置 CRUD |
| `/config/rule` | ConfigRuleController | 规则配置 CRUD |
| `/config/skill` | ConfigSkillController | 技能 (MD/ZIP) 上传管理 |
| `/config/sys-tool` | ConfigSysToolController | 系统工具 CRUD |
| `/config/sys-tool` | ConfigSysToolTestController | 系统工具运行时测试 |
| `/config/sql-tool` | ConfigSqlToolController | SQL 工具 CRUD |
| `/config/task` | ConfigTaskController | 定时任务 (Quartz) CRUD + 手动触发 |
| `/config/token` | TokenConsumeController | Token 消耗记录查询 |
| `/config/user` | AgentUserController | 用户管理 + Token 充值 |
| `/process/askanswer` | AskAnswerController | 对话记录查询/删除 |
| `/process/task-instance` | TaskInstanceController | 任务实例列表 |
| `/process/session` | SessionController | 会话管理 |
| `/file` | FileController | 文件上传/下载 |
| `/mcp-test` | McpTestController | MCP 工具连接测试 |
| `/sql-tool-test` | SqlToolTestController | SQL 工具预览测试 |
| `/mybatis-log` | MybatisLogController | MyBatis SQL 日志开关 |

---

## 6. 数据模型

### 6.1 核心实体关系

```
ConfigAgent ──多对多── ConfigMcp       (via config_agent_mcp_relation)
ConfigAgent ──多对多── ConfigSkill     (via config_agent_skill_relation)
ConfigAgent ──多对多── ConfigRule      (via config_agent_rule_relation)
ConfigAgent ──多对多── ConfigSqlTool   (via config_agent_sql_tool_relation)
ConfigAgent ──多对多── ConfigSysTool   (via config_agent_sys_tool_relation)
ConfigAgent ──多对1──  ConfigModel     (via model_key)
ConfigAgent ──多对多── AgentUser       (via agent_user_relation)
ConfigSqlTool ──1对多── ConfigSqlToolParam (sql_tool_id FK)
```

### 6.2 核心实体字段摘要

**config_agent** — 智能体定义

| 字段 | 类型 | 说明 |
|---|---|---|
| code / config_key | VARCHAR | 唯一标识 |
| name / desc | VARCHAR | 名称/描述 |
| model_key / fallback_model_key | VARCHAR | 主/备模型 |
| system_prompt | TEXT | 系统提示词 |
| workspace | VARCHAR | 工作目录路径 |
| local_agent | BOOLEAN | 本地智能体模式 |
| enabled / token_limit | BOOLEAN | 启用/Token 限制 |
| check_permission | BOOLEAN | 权限校验 (默认 true) |
| enable_plan_mode / enable_task_list / enable_skill_learning / enable_subagent | BOOLEAN | 功能开关 |
| enable_filesystem_tool / enable_shell_tool | BOOLEAN | 文件/Shell 工具 |
| max_iters | INT | 最大模型请求次数 (默认 100) |
| exe_tool_timeout | INT | 工具超时秒数 (默认 120) |
| exe_tool_max_attempts | INT | 工具最大重试 (默认 3) |
| compact_trigger_messages | INT | 压缩触发阈值 (默认 200) |
| compact_keep_messages | INT | 压缩保留数 (默认 100) |
| isolation_scope | VARCHAR | SESSION/USER/AGENT/GLOBAL |

---

## 7. 工具系统

### 7.1 系统工具 (System Tool)

Spring Bean 标注 `@SystemToolkit(code, description, group)` + 方法标注 AgentScope 的 `@Tool`。

```
启动时: ConfigSysToolService.afterPropertiesSet()
  → 扫描 Spring 容器中所有 @SystemToolkit bean
  → 自动写入 config_sys_tool 表

Agent 构建时: HarnessAgentService.buildToolkit()
  → SystemToolkitCreator.createSystemAgentTool()
  → 反射获取 @Tool 方法 → 包装为 SystemToolkitReflectiveFunctionTool
  → toolkit.registerAgentTool()
```

### 7.2 SQL 工具 (SQL Tool)

数据库配置 `config_sql_tool` + 参数表 `config_sql_tool_param`，运行时 Javassist 动态生成实现类。

```
Agent 构建时: HarnessAgentService.buildToolkit()
  → SqlToolCreator.create(SqlToolDefine)
    → Javassist 生成 AbstractSqlQueryTool 的子类
    → 根据 defineKey 拼装类名, 每 SQL 一个 @Tool 方法
    → 运行时: 渲染 SQL 模板 (FreeMarker) → JdbcTemplateService 执行
  → 实例化 → toolkit.registerTool(instance)

Agent 关闭时: SqlToolCreator.unUseClass()
  → 引用计数归零 20s 后清理 ClassLoader
```

---

## 8. 定时任务

基于 Quartz，通过 `TaskExecuteJob` (prototype scope, DisallowConcurrentExecution) 执行。

```
ConfigTaskController
  → save/update → 同步 Quartz Scheduler (JobDetail + CronTrigger)
  → execute/{id} → 手动触发一次

TaskExecuteJob.execute()
  → 创建 TaskInstance → 调用 AgentChatService.askAgent()
  → 通过回调更新 taskInstance 状态 (成功/失败/输出)
```

---

## 9. 已知问题清单

| # | 严重度 | 问题 | 状态 |
|---|---|---|---|
| 1 | P0 | 零测试覆盖 | 待处理 |
| 2 | P0 | AskingCallback 240 行 God Object | 待处理 |
| 3 | P1 | `SynchronousQueue` + `AbortPolicy` 高并发拒绝 | 待处理 |
| 4 | P1 | Agent 借还不均衡时引用计数无泄漏检测 | 待处理 |
| 5 | P1 | `blockLast()` 同步阻塞浪费线程 | 待处理 |
| 6 | P1 | `configKey.intern()` 全局字符串池锁 | 待处理 |
| 7 | P2 | 配置 10s 全表轮询 | 待处理 |
| 8 | P2 | shutdownNow 粗暴中断丢数据 | 待处理 |
| 9 | P2 | 缺少可观测性 (无 metrics) | 待处理 |
| 10 | P3 | 无 API 限流 | 待处理 |
| 11 | P3 | ConfigSysToolController / ConfigSysToolTestController 路径冲突 | 待处理 |

### 已修复问题

| # | 问题 | 修复 |
|---|---|---|
| 3 | extractReplyId 15 个 instanceof 级联 | 已分组 + Javadoc |
| 4 | pushSocket poll(100ms) 忙等 | 已改为 take() + 毒丸 |
| 30 | 规则列表纵向堆叠 + 滚动 | 已改为横向平铺 |
| 31 | checkPermission 字段未暴露到 UI | 已添加下拉框 + save 链路 |