# 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: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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)