Name	Name	Last commit message	Last commit date
parent directory ..
docs	docs
scripts	scripts
src	src
.gitignore	.gitignore
CLAUDE.md	CLAUDE.md
README.md	README.md
pom.xml	pom.xml

assistant-agent

主智能体运行时，基于 AgentScope Java 框架构建，通过 MCP 协议接入知识库能力。

核心特性

Skill 按需加载：根据用户请求动态加载技能包和专属工具
流式响应：支持 SSE 实时输出推理过程和结果
多会话隔离：每个会话独立 Memory，支持上下文记忆
响应式架构：基于 WebFlux + Reactor，禁止阻塞调用
HiClaw 集成：支持 Matrix 消息通信和 MinIO 文件同步，可作为远程 Worker 接入分布式协作系统

技术栈

组件	技术
Agent 框架	AgentScope Java 1.0.8
LLM 模型	OpenAI 兼容 API（可配置）
MCP 协议	Streamable HTTP
Web 框架	Spring Boot 3.4.3 + WebFlux
响应式	Project Reactor
Java 版本	Java 21

快速开始

1. 配置

配置文件位于 xiaoyu-workspace/config/ 目录：

config/
├── application.yml   # Spring 应用配置
├── agent.yml         # Agent 业务配置
└── .env              # 敏感信息（仅 API Key）

.env (敏感信息):

OPENAI_API_KEY=sk-xxx
ASSISTANT_ZHIPU_MCP_URL=https://open.bigmodel.cn/api/mcp-broker/proxy/web-search/mcp?Authorization=xxx

agent.yml (业务配置，硬编码):

openai:
  api-key: ${OPENAI_API_KEY}
  base-url: https://coding.dashscope.aliyuncs.com/v1
  model-name: qwen3.5-plus

assistant:
  working-directory: /path/to/xiaoyu-workspace
  skill:
    enabled: true
  mcp:
    servers:
      knowledge-base:
        enabled: false
      zhipu-search:
        enabled: true

2. 启动服务

支持开发态和运行态两种模式，通过 --workspace 指定不同的配置目录：

# 开发态（使用 xiaoyu-workspace-dev，端口 8080）
./scripts/start.sh --dev

# 运行态（使用 xiaoyu-workspace，端口 28080）
./scripts/start.sh --prod

# 自定义 workspace
./scripts/start.sh --workspace /path/to/custom-workspace

# 覆盖端口
./scripts/start.sh --dev --port 9000

# 查看帮助
./scripts/start.sh --help

模式	默认 Workspace	默认端口	启动方式
dev	`xiaoyu-workspace-dev/`	8080	`mvn spring-boot:run`
prod	`xiaoyu-workspace/`	28080	`java -jar`

Workspace 结构：

<workspace>/
├── config/
│   ├── application.yml   # Spring 应用配置
│   ├── agent.yml         # Agent 业务配置
│   └── .env              # 敏感信息（API Key）
├── logs/                 # 日志目录
├── memory/               # 记忆文件
├── sessions/             # 会话数据
└── skills/               # Skill 定义

3. 测试 API

# 非流式对话（根据启动模式调整端口）
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"question": "你好"}'

# 流式对话
curl -X POST http://localhost:8080/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"question": "今天做什么"}'

核心架构

Skill 按需加载

Skill 是技能包，包含提示词模板和专属工具。Agent 启动时只注册默认工具，当用户请求匹配 Skill 触发条件时，动态加载专属工具。

┌─────────────────────────────────────────────────────┐
│                    ToolRegistry                      │
│  ┌─────────────────┐  ┌─────────────────────────┐  │
│  │   默认工具       │  │    Skill 专属工具        │  │
│  │  (始终可用)      │  │    (按需加载)           │  │
│  │                 │  │                         │  │
│  │  • read/write   │  │  • task_context        │  │
│  │  • edit/bash    │  │  • task_write          │  │
│  │  • glob/grep    │  │  • knowledge_search    │  │
│  │  • webSearchPro │  │  • knowledge_write     │  │
│  └─────────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────┘

配置示例：

assistant:
  skill:
    default-tools:
      local: [read, write, edit, bash, glob, grep]
      mcp:
        - name: webSearchPro
          server: zhipu-search
    tool-mapping:
      daily-kickoff:
        mcp:
          - {name: task_context, server: knowledge-base}
          - {name: task_write, server: knowledge-base}

消息流转

用户请求 → Skill 匹配 → 加载专属工具 → Agent 推理 → 流式输出
                ↓
          Prompt 构建
          (基础 + 记忆 + Skill)

Studio 接入

启用 assistant.studio.enabled=true 后，应用会在启动阶段调用 StudioManager.initialize()，自动完成三件事：

向 AgentScope Studio 注册当前 run
注册 StudioMessageHook，把系统消息推送到 Studio
注册 TelemetryTracer，把 Agent / Model / Tool / Formatter 的 tracing 数据通过 OTLP 发到 Studio

默认关闭，原因是该能力会开启 AgentScope 的 Reactor 全局 tracing hook。只有在需要观察链路时才建议打开。

API 文档

POST /api/chat

非流式对话接口。

请求：

{
  "question": "什么是 WebFlux？",
  "sessionId": "可选，不传则自动创建"
}

响应：

{
  "code": "SUCCESS",
  "data": {
    "sessionId": "会话ID",
    "answer": "WebFlux 是...",
    "latencyMs": 1234
  }
}

POST /api/chat/stream

流式对话接口，返回 SSE 事件流。

事件类型：

EventType	说明	对应 ContentBlock
`SESSION`	当前会话信息（含自动生成的 sessionId）	-
`REASONING`	模型推理过程	ThinkingBlock
`TOOL_USE`	工具开始执行	ToolUseBlock
`AGENT_RESULT`	最终回答	TextBlock
`TOOL_RESULT`	工具调用结果	ToolResultBlock
`DONE`	本轮对话完成	-
`ERROR`	本轮对话失败	-
`METRICS`	请求指标	-

示例：

data: {"type":"SESSION","sessionId":"uuid","isLast":false}
data: {"type":"REASONING","content":"用户想要...","isLast":false}
data: {"type":"TOOL_USE","toolName":"read","toolInput":{"path":"pom.xml"},"isLast":false}
data: {"type":"AGENT_RESULT","content":"这是我的回答...","isLast":false}
data: {"type":"METRICS","success":true,"latencyMs":1234,"isLast":false}
data: {"type":"DONE","sessionId":"uuid","isLast":true}

GET /api/sessions

列出所有会话。

GET /api/sessions/{sessionId}/history

获取会话历史消息，返回完整 Msg 结构（包含 thinking、tool_use、tool_result）。

DELETE /api/sessions/{sessionId}

删除会话。

工具列表

本地工具（始终可用）

工具	功能
`read`	读取文件内容
`write`	写入文件
`edit`	编辑文件（字符串替换）
`glob`	按模式查找文件
`grep`	搜索文件内容
`bash`	执行 shell 命令

MCP 工具（按需加载）

工具	服务	所属 Skill
`knowledge_search`	knowledge-base	knowledge-card, xiaoyu-dev
`knowledge_write`	knowledge-base	knowledge-card
`task_context`	knowledge-base	daily-kickoff
`task_write`	knowledge-base	daily-kickoff
`index_list`	knowledge-base	xiaoyu-dev, index-management
`webSearchPro`	zhipu-search	默认工具

项目结构

src/main/java/com/assistant/agent/
├── config/               # 配置
│   ├── OpenApiConfig.java
│   ├── RequestIdFilter.java
│   └── SessionConfig.java
├── controller/           # 接口层
│   ├── ChatController.java
│   ├── SessionController.java
│   └── GlobalExceptionHandler.java
├── dto/                  # 数据传输对象
│   ├── request/
│   │   └── ChatRequest.java
│   └── response/
│       ├── ApiResponse.java
│       ├── ChatData.java
│       ├── ErrorCode.java
│       ├── ErrorResponse.java
│       ├── SessionMeta.java
│       ├── SessionMessage.java
│       └── StreamEvent.java
├── service/              # 应用服务
│   ├── ChatService.java
│   └── SessionService.java
├── prompt/               # 提示词构建
│   ├── PromptProperties.java
│   └── PromptBuilder.java
├── tool/                 # 本地工具
│   ├── ToolRegistry.java
│   ├── AgentTool.java
│   ├── BashTool.java
│   ├── ReadTool.java
│   ├── WriteTool.java
│   ├── EditTool.java
│   ├── GlobTool.java
│   └── GrepTool.java
├── skill/                # Skill 加载
│   ├── SkillProperties.java
│   ├── SkillToolConfig.java
│   └── SkillLoader.java
├── mcp/                  # MCP 集成
│   ├── McpProperties.java
│   ├── McpServerConfig.java
│   └── McpClientFactory.java
├── util/                 # 工具类
│   └── McpResponseParser.java
└── AssistantApplication.java

配置说明

配置与代码分离，运行态配置放在 xiaoyu-workspace/config/ 目录。

配置文件结构

xiaoyu-workspace/config/
├── application.yml   # Spring 应用配置（server, logging）
├── agent.yml         # Agent 业务配置（openai, assistant, prompt）
└── .env              # 敏感信息（API Key）

application.yml

server:
  port: 28080

spring:
  application:
    name: assistant-agent
  config:
    import: file:/path/to/xiaoyu-workspace/config/agent.yml

logging:
  level:
    com.assistant: INFO

agent.yml

openai:
  api-key: ${OPENAI_API_KEY}
  base-url: https://coding.dashscope.aliyuncs.com/v1
  model-name: qwen3.5-plus

assistant:
  working-directory: /path/to/xiaoyu-workspace
  skill:
    enabled: true
    base-path: ${assistant.working-directory}/skills/
    default-tools:
      local: [read, write, edit, bash, glob, grep]
      mcp:
        - name: webSearchPro
          server: zhipu-search
  mcp:
    servers:
      zhipu-search:
        enabled: true
        url: ${ASSISTANT_ZHIPU_MCP_URL}

prompt:
  base: |-
    你是一个有帮助的 AI 助手...
  memory-dir: ${assistant.working-directory}/memory

.env（敏感信息）

OPENAI_API_KEY=sk-xxx
ASSISTANT_ZHIPU_MCP_URL=https://open.bigmodel.cn/api/mcp-broker/proxy/xxx

HiClaw 配置

HiClaw 是分布式 Agent 协作系统，通过 Matrix 进行消息通信，MinIO 进行文件同步。

配置结构：

assistant:
  hiclaw:
    enabled: true
    worker-name: xiaoyu
    workspace: ${assistant.working-directory}/hiclaw
    history-limit: 50

    matrix:
      homeserver: "http://matrix-server:18080"
      access-token: ${HICLAW_MATRIX_TOKEN}
      user-id: "@xiaoyu:matrix-server"
      display-name: "xiaoyu"

    minio:
      endpoint: "http://minio-server:9000"
      access-key: ${HICLAW_MINIO_ACCESS_KEY}
      secret-key: ${HICLAW_MINIO_SECRET_KEY}
      bucket: hiclaw-storage-dev  # dev 环境用 -dev 后缀

环境隔离：

环境	MinIO Bucket	说明
dev	`hiclaw-storage-dev`	开发环境
prod	`hiclaw-storage`	生产环境

目录结构：

MinIO bucket/
├── agents/
│   └── {worker-name}/   # Worker 私有目录
│       ├── skills/
│       └── credentials/
└── shared/              # 共享目录（所有 Worker）
    └── tasks/           # 任务文件

本地 hiclaw/
├── {worker-name}/       # Worker 私有目录
└── shared/              # 共享目录（与 MinIO 同步）
    └── tasks/

同步策略：

文件同步由 Skill 层定义，MinioSyncService 只提供通用 push/pull 能力
Skill 定义具体的目录映射（本地什么 → MinIO 哪里）
通过不同的 bucket 实现环境隔离，Skill 代码完全复用

测试配置

测试使用 src/test/resources/ 下的配置：

src/test/resources/
├── application.yml      # 测试基础配置
├── application-test.yml # test profile
└── agent-test.yml       # 测试用 Agent 配置

测试时从 assistant-agent/.env 加载 OPENAI_API_KEY。

开发说明

关键约束

禁止在 Agent 逻辑中使用 .block()
所有异步操作使用 Mono/Flux
错误必须有降级处理
会话每个 sessionId 拥有独立 Memory

测试

# 运行所有测试
mvn test

# 运行单元测试
mvn test -Dtest=*UnitTest

# 运行特定测试
mvn test -Dtest=ChatServiceUnitTest

License

Apache-2.0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

assistant-agent

核心特性

技术栈

快速开始

1. 配置

2. 启动服务

3. 测试 API

核心架构

Skill 按需加载

消息流转

Studio 接入

API 文档

POST /api/chat

POST /api/chat/stream

GET /api/sessions

GET /api/sessions/{sessionId}/history

DELETE /api/sessions/{sessionId}

工具列表

本地工具（始终可用）

MCP 工具（按需加载）

项目结构

配置说明

配置文件结构

application.yml

agent.yml

.env（敏感信息）

HiClaw 配置

测试配置

开发说明

关键约束

测试

相关文档

License

FilesExpand file tree

assistant-agent

Directory actions

More options

Directory actions

More options

Latest commit

History

assistant-agent

Folders and files

parent directory

README.md

assistant-agent

核心特性

技术栈

快速开始

1. 配置

2. 启动服务

3. 测试 API

核心架构

Skill 按需加载

消息流转

Studio 接入

API 文档

POST /api/chat

POST /api/chat/stream

GET /api/sessions

GET /api/sessions/{sessionId}/history

DELETE /api/sessions/{sessionId}

工具列表

本地工具（始终可用）

MCP 工具（按需加载）

项目结构

配置说明

配置文件结构

application.yml

agent.yml

.env（敏感信息）

HiClaw 配置

测试配置

开发说明

关键约束

测试

相关文档

License