Superpowers 为 AI 编程智能体（如 Claude Code、Cursor、Codex、OpenCode）提供了一套完整的软件开发工作流程。它不是单一技能，而是由 20+ 个可组合 Skills 组成的系统化工作流，覆盖需求梳理、架构设计、测试驱动开发、代码审查和分支管理等开发环节。它的核心思路，是通过一组可组合的 Skills 和初始指令，让 AI 智能体在编写代码时自动遵循最佳实践，而不是随意生成代码。 上面的定义，有点抽象，一句话概括就是，帮你快速生成一个应用的skills，里面内置了软件开发的规约，确保生成的工程能够满足你的需求，并且易读易修改。
怎么用Superpowers？
step1:把插件加入市场
在 Claude Code 的终端中执行：/plugin marketplace add obra/superpowers-marketplace
step2:安装插件
/plugin install superpowers@superpowers-marketplace 安装完成后，重启 Claude Code，就可以使用了。
step3:用/superpowers:brainstorm 直接开聊
网上流传的经典案例是：/superpowers:brainstorm 我想开发一个简单的网页端 Todo 管理应用。 然后进行需求澄清，通过连续提问收集必要信息，包括采用什么技术栈、数据结构、数据持久化情况、UI展示、功能选择，均可以自定义，聊清楚了之后，会生成执行计划，待确认，最终确认后，可以生成你想要的应用。 最关键的点是，这些技能在内网环境下，也能用，只要你有类似Claude Code的开发工具，例如阿里灵犀，直接导入技能包，就能实现相同效果。 笔者是在内网环境验证的，所以就不po图了。
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
AgentScope Java is a reactive, agent-oriented programming framework for building LLM-powered applications. It's built on Project Reactor and follows reactive programming principles.
**Key Characteristics:** - **Reactive Architecture**: All asynchronous operations use Project Reactor's `Mono` and `Flux` - **ReAct Paradigm**: Agents autonomously reason and act using the ReAct (Reasoning-Acting) pattern - **Multi-Agent Collaboration**: Support for distributed agent communication via A2A protocol - **Production-Ready**: Includes tool sandboxing, observability with OpenTelemetry, and GraalVM native image support
## Module Structure
This is a multi-module Maven project with the following modules:
1. **agentscope-core** - Core framework containing: - Agent implementations (`ReActAgent`, `UserAgent`, etc.) - Model integrations (Anthropic, DashScope, Gemini) - Formatters and message converters - Tool system and MCP (Model Context Protocol) integration - Reactive stream handling with Project Reactor
2. **agentscope-extensions** - Optional extensions including: - RAG (Retrieval-Augmented Generation) with simple and advanced implementations - Skill repositories (MySQL, Redis session storage) - Scheduler integrations (Quartz, XXL-Job) - AGUI (Automated GUI interaction) - Nacos integration for service discovery and A2A protocol - Quarkus extensions
3. **agentscope-examples** - Example applications demonstrating: - Quickstart tutorials - Multi-agent patterns - Plan notebook system - Boba tea shop simulation - Werewolf game with human-in-the-loop
4. **agentscope-dependencies-bom** - BOM (Bill of Materials) for dependency management 5. **agentscope-distribution** - Distribution and packaging modules
## Development Commands
### Building and Testing ```bash # Build all modules mvn clean compile
# Run all tests mvn test
# Run specific test class mvn test -Dtest=YourTestClassName
# Build with tests and coverage (CI standard) mvn clean verify
# Build with Maven Daemon (faster, used in CI) mvnd -B -T1 clean verify ```
### Development Tools ```bash # Install mvnd (Maven Daemon) for faster builds curl -fsSL https://github.com/apache/maven-mvnd/releases/download/1.0.3/maven-mvnd-1.0.3-linux-amd64.tar.gz | tar xz mkdir -p ~/.mvnd mv maven-mvnd-1.0.3-linux-amd64/* ~/.mvnd/ ```
## Critical Coding Guidelines
### 🚫 ABSOLUTELY FORBIDDEN 1. **NEVER use `.block()` in library/agent code** - Only allowed in `main()` methods or test code 2. **NEVER use `Thread.sleep()`** - Use `Mono.delay()` for delays 3. **NEVER use `ThreadLocal`** - Use Reactor Context with `Mono.deferContextual()` 4. **NEVER hardcode API keys** - Always use `System.getenv()` or configuration 5. **NEVER ignore errors silently** - Always provide error handling with `.onErrorResume()` or `.onErrorReturn()`
### ✅ ALWAYS DO 1. **Use reactive patterns** - Chain operations with `.map()`, `.flatMap()`, `.then()` 2. **Use Builder pattern** for creating agents, models, and messages 3. **Add logging** with SLF4J for important operations 4. **Use correct imports**: `import io.agentscope.core.model.DashScopeChatModel;` (NOT `io.agentscope.model.*`) 5. **Follow API conventions** (see SKILL.md for detailed API mappings)
// ❌ WRONG - Blocking in agent logic (NEVER do this) String result = model.generate(messages, null, null).block();
// ✅ CORRECT - Only allowed in main() methods public static void main(String[] args) { // ⚠️ .block() is ONLY allowed here because this is a main() method Msg response = agent.call(userMsg).block(); System.out.println(response.getTextContent()); } ```
## Key Architectural Concepts
### Agents - **ReActAgent**: Primary agent implementation using Reasoning-Acting pattern - **UserAgent**: For human-in-the-loop interactions - **ObservableAgent**: Agents that can be observed via event streams - **StreamableAgent**: Support for streaming responses
### Messaging - **Msg**: Primary message class with content, metadata, and conversation history - **Content types**: Text, image, audio, tool calls, tool results - **Formatter system**: Convert between LLM provider formats and internal Msg representation
### Tools and Skills - **Tool system**: Register Java methods as tools with `@Tool` annotation - **Skill repository**: Persistent storage and retrieval of tools/skills - **MCP integration**: Connect to Model Context Protocol servers for external tool access - **Tool validation**: JSON schema validation for tool inputs
### Hooks and Observability - **StreamingHook**: Intercept and modify streaming responses - **StructuredOutputHook**: Handle structured output parsing and self-correction - **OpenTelemetry integration**: Distributed tracing across agent execution
## Configuration and Environment
### Required Environment Variables ```bash # Model API keys (examples) export DASHSCOPE_API_KEY="your-key" export ANTHROPIC_API_KEY="your-key" export GEMINI_API_KEY="your-key" ```
### Maven Dependency ```xml <dependency> <groupId>io.agentscope</groupId> <artifactId>agentscope</artifactId> <version>1.0.9</version> <!-- Check for latest version --> </dependency> ```
## Testing Strategy
- **Unit tests**: Use JUnit 5 with Project Reactor's `StepVerifier` for testing reactive streams - **Integration tests**: Mock external services with OkHttp's `MockWebServer` - **Coverage**: JaCoCo integration with `mvn verify` generating coverage reports - **Test isolation**: Each test should be independent and not rely on shared state
Examples: ```bash feat(agent): add support for Claude-3 model fix(memory): resolve memory leak in ReActAgent docs(readme): update installation instructions ```
## Resources - **Documentation**: https://java.agentscope.io/ - **GitHub Issues**: https://github.com/agentscope-ai/agentscope-java/issues - **SKILL.md**: Detailed API reference and coding guidelines in repository root - **Examples**: Comprehensive examples in `agentscope-examples/` directory
