# agent-scope-dev-skill
**Repository Path**: HillYoungGit/agent-scope-dev-skill
## Basic Information
- **Project Name**: agent-scope-dev-skill
- **Description**: AgentScope Java 2.0 智能体框架开发指南(AI Coding Agent Skill)
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-09-15
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# AgentScope Java 2.0 开发指南(AI Agent Skill)
> 面向 **企业级、分布式、生产环境** 的 AgentScope Java 2.0 智能体框架开发技能包,为 AI 编码助手提供权威、可验证的开发指引。
[](LICENSE)
简体中文 | [English](README_EN.md)
---
## 项目简介
`agent-scope-dev` 是一个为 AI 编码 Agent(如 Claude Code / OpenCode / Codex 等)设计的中文技能包(Skill),完整覆盖 AgentScope Java 2.0 框架的**核心概念、开发模式、工程化部署与生产实践**。
技能包整合了三大知识来源,并强制在回答任何问题时**同时引用**,确保输出信息与真实源码一致:
1. **官方文档**:AgentScope Java 2.0 官方在线文档
2. **框架源码**:本地完整源码副本(`source-code/agentscope-java-main/`)
3. **离线参考**:`references/` 下的架构说明、API 细节与最佳实践
> 环境要求:JDK 17+,Maven 3.9+
---
## 功能特性
- ✅ **覆盖完整开发链路**:Agent 开发 → HarnessAgent 工程化底座 → 模型集成 → Tool/MCP → 权限系统 → 沙箱/文件系统/记忆 → 多 Agent 编排 → 生产部署
- ✅ **源码级验证**:内置 AgentScope Java 2.0 完整源码,查询时自动核对真实 API 签名与内部实现
- ✅ **中文本地化**:全部参考文档为中文,降低阅读门槛
- ✅ **生产实践导向**:包含单机→分布式迁移、常见坑位、V1→V2 迁移要点
- ✅ **离线可用**:文档与源码全部本地化,不依赖网络
## 快速导航
| 场景 | 入口 |
|------|------|
| 初次使用 | [快速开始](#快速开始) |
| 构建基础 Agent | [Agent 开发](#agent-开发) |
| 工程化部署 | [HarnessAgent](#harnessagent-工程化底座) |
| 模型接入 | [模型集成](#模型集成) |
| 工具开发 | [Tool 与 MCP](#tool-与-mcp) |
| 权限管控 | [权限系统](#权限系统) |
| 上生产环境 | [生产部署](#生产部署) |
完整目录见 [SKILL.md](SKILL.md)。
---
## 快速开始
### 1. 安装技能
将本仓库克隆或复制到你的 AI 编码助手技能目录(以 Claude Code 为例):
```bash
# 方式一:直接克隆
git clone https://gitee.com/HillYoungGit/agent-scope-dev-skill.git \
~/.claude/skills/agent-scope-dev
# 方式二:GitHub
git clone https://github.com/HillYoungs/agent-scope-dev-skill.git \
~/.claude/skills/agent-scope-dev
```
> 不同 AI 助手的技能目录不同(如 OpenCode 为 `~/.config/opencode/skills/`),请按需调整。
### 2. 使用
在任何涉及 AgentScope Java 框架的对话中,直接向你的 AI 编码助手描述需求即可,技能会自动触发并遵循 `SKILL.md` 中的强制规则。
### 3. Maven 依赖(你的项目侧)
```xml
io.agentscope
agentscope-harness
${agentscope.version}
io.agentscope
agentscope-extensions-model-dashscope
${agentscope.version}
```
### 4. 第一个 HarnessAgent
```java
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.agent.HarnessAgent;
import io.agentscope.harness.agent.memory.compaction.CompactionConfig;
import java.nio.file.Paths;
public class FirstAgent {
public static void main(String[] args) {
// 见 SKILL.md「快速开始」章节的完整示例
}
}
```
---
## 目录结构
```
agent-scope-dev/
├── SKILL.md # 技能主文件:完整开发指南(1270+ 行)
├── README.md # 本文件
├── .gitignore # 忽略 source-code/(体积大且有独立 git 历史)
├── references/ # 离线参考文档(中文)
│ ├── index.md # 索引
│ ├── quickstart.md # 快速入门
│ ├── building-blocks/ # 核心构件:agent/context/message/model/tool/middleware/permission
│ ├── harness/ # Harness 子系统:workspace/memory/filesystem/sandbox/skill/subagent/plan-mode/channel/compaction
│ ├── integration/ # 生态集成
│ │ ├── model/ # 模型:OpenAI / DashScope / Anthropic / Gemini / Ollama
│ │ ├── channel/ # 渠道:钉钉 / 飞书 / 企业微信 / GitHub / GitLab
│ │ ├── memory/ # 记忆:Bailian / Mem0 / Reme
│ │ ├── rag/ # RAG:Dify / RAGFlow / Haystack / Bailian
│ │ ├── session/ # 会话存储:MySQL / Redis / OSS
│ │ ├── skill/ # 技能仓库:Git / MySQL / PostgreSQL
│ │ ├── distributed/ # 分布式:MySQL / Redis / OSS
│ │ ├── infrastructure/ # 基础设施:Nacos / Higress / Scheduler
│ │ ├── ecosystem/ # 生态:Studio / Training / Chat-Completions-Web
│ │ └── protocol/ # 协议:A2A / Agent Protocol / AGUI
│ ├── blogs/ # 官方博客翻译与解读
│ └── others/ # FAQ / 生产实践 / 版本发布说明
└── source-code/ # 【git 忽略】AgentScope Java 2.0 完整源码(本地验证用)
```
---
## 内容覆盖(目录速查)
| 模块 | 说明 | 文档位置 |
|------|------|---------|
| 核心架构 | ReActAgent vs HarnessAgent、能力叠加、无状态引擎 | `SKILL.md` §核心架构 |
| Agent 开发 | 配置参数、三种调用方式、结构化输出、RuntimeContext | `SKILL.md` §Agent 开发 |
| 消息与事件 | 消息结构、事件类型 | `SKILL.md` §消息与事件 |
| 模型集成 | 扩展模块、Model 创建、Formatter、自定义提供商 | `SKILL.md` §模型集成 |
| Middleware | 五个 Hook、内置/自定义 Middleware、执行顺序 | `SKILL.md` §Middleware |
| Tool 与 MCP | 注解式 Tool、ToolBase、MCP 集成、Tool Group | `SKILL.md` §Tool 与 MCP |
| 权限系统 | 三种决策、Permission Mode、HITL 工作流 | `SKILL.md` §权限系统 |
| HarnessAgent | Builder 入口、关闭子系统 | `SKILL.md` §HarnessAgent |
| 工作区/文件系统/沙箱 | 目录布局、三种模式、Docker 沙箱、快照恢复 | `SKILL.md` §工作区/文件系统/沙箱 |
| 记忆系统 | 两层记忆、Compaction、大工具结果卸载 | `SKILL.md` §记忆系统 |
| 技能/子 Agent/Plan Mode | 四层合成、ISOLATED vs SHARED、Plan 工作流 | `SKILL.md` §技能系统/子 Agent/Plan Mode |
| Channel 路由 | 快速开始、多 Agent 路由、内置适配器 | `SKILL.md` §Channel 路由 |
| 生产部署 | 单机→分布式、组件替换、常见坑位、V1→V2 迁移 | `SKILL.md` §生产部署 |
---
## 官方资源
| 资源 | 链接 | 用途 |
|------|------|------|
| GitHub 主仓库 | https://github.com/agentscope-ai/agentscope-java | 源码阅读、Issue 追踪、最新特性、示例代码 |
| 官方文档 | https://agentscope-ai.github.io/agentscope-java/ | 完整 API 文档、架构说明、最佳实践 |
| GitHub Issues | https://github.com/agentscope-ai/agentscope-java/issues | 已知问题、讨论、Roadmap |
| GitHub Releases | https://github.com/agentscope-ai/agentscope-java/releases | 版本发布说明、Changelog |
| Maven Central | `io.agentscope:agentscope-harness` | 最新版本坐标、依赖管理 |
---
## 常见问题
**Q:为什么 `source-code/` 目录在仓库里看不到?**
A:`source-code/` 包含完整的 AgentScope Java 2.0 源码副本(体积约 40+ MB,且自带独立 git 历史),因此被 `.gitignore` 排除,不随仓库推送。使用时可按需从官方仓库克隆后放置到该路径:
```bash
git clone https://github.com/agentscope-ai/agentscope-java source-code/agentscope-java-main
```
(中国境内网络建议使用镜像或加速代理。)
**Q:技能如何触发?**
A:任何对话中提及 AgentScope、agentscope、ReActAgent、HarnessAgent、MCP 集成、多 Agent 编排等关键词时,AI 编码助手会自动加载本技能。
---
## 许可证
[MIT](LICENSE)