老吴搭建教程

728电玩全套源码

Sun, 14 Jun 2026 00:41:58 +0800

728全套源码的后端好像跟电玩63游戏源码后端一样的，前端UI不一样，用Cocos简单看了一下源码，这一套是仿官方的728。内含多种玩法，支持Cocoscreator开发，完整前端代码一键部署，适合有二开需求的用户。

搭建环境

运行环境：linux CentOS7X
源码后端：mysql+php
前端：cocos dashboard 2.4.5

服务器要求

硬件	测试要求	运营要求
CPU	CPU4核	CPU8核
内存	内存8G	内存16G
带宽	5Mbp以上	20Mbp以上
硬盘	D盘50G以上	D盘100G以上

附件截图

附件地址

附件为源码，无教程！

MCP 原理及 Java 开发指南

Wed, 10 Jun 2026 13:25:52 +0800

目的：帮助 Java / Spring Boot 开发者快速理解 MCP 的设计动机、协议细节、以及如何在 Spring AI 中落地。

为什么需要 MCP？

MCP 助力开发者在 LLM 之上构建智能体和复杂工作流。由于 LLM 需要频繁与外部数据和工具集成，MCP 提供了以下核心价值：

开箱即用的集成能力：提供丰富的预置集成方案，LLM 可直接接入使用

灵活的供应商切换：支持在不同 LLM 服务商之间无缝迁移

安全最佳实践：内置数据安全防护机制，确保基础设施安全可控

MCP 用 JSON‑RPC 2.0 + 能力发现 的模式，把「模型 ↔ 应用 ↔ 工具」之间的交互标准化，实现 一次接入，多处复用。

MCP 协议就好比 USB 接口，USB 设备可以通过 USB Hub 连接到不同的计算机上，而不需要重新设计接口。
- 我们在电脑上可以同时使用多个 USB 设备（鼠标、键盘、硬盘、游戏手柄），这些 USB 设备有不同的功能，只要实现了标准的 USB 接口协议即可。
- 电脑可以类比成 LLM，USB Hub 可以类比成 MCP Server，USB 设备可以类比成 Tool、Resource、Prompt 等。
- 通过 MCP 协议，LLM 可以通过 USB Hub 访问不同的 USB 设备，从而扩展出各种各样的能力（发邮件、打电话、地图旅行规划、订票）。

从某种程度上说，MCP 就像是设计模式中的命令（Command）模式 + 外观（Facade）模式。

基本概念

关键术语

MCP 主机：需要通过 MCP 访问数据的程序，如 Claude Desktop、IDE 或 AI 工具

MCP 客户端：与服务器保持 1:1 连接的协议客户端

MCP 服务器：通过标准化的模型上下文协议暴露特定能力的轻量级程序

本地数据源：MCP 服务器可以安全访问的计算机文件、数据库和服务

远程服务：MCP 服务器可以通过互联网连接的外部系统（例如通过 API）

分层架构

┌────────────────────────────┐

│  Client / Server API 层    │ ← McpClient / McpServer

├────────────────────────────┤

│  Session 会话层            │ ← 会话 & 状态管理

├────────────────────────────┤

│  Transport 传输层          │ ← Stdio / SSE / WebSocket / gRPC

└────────────────────────────┘

MCP 采用分层架构设计，每一层都有其特定的职责：

1. Client / Server API 层

提供 McpClient 和 McpServer 接口

处理高层业务逻辑和协议交互

负责能力发现和工具调用

2. Session 会话层

管理客户端和服务器之间的会话状态

处理会话的生命周期（初始化、运行、关闭）

维护会话上下文和状态信息

3. Transport 传输层

提供多种传输机制支持：

Stdio：标准输入输出，适合本地进程间通信

SSE (Server-Sent Events)：单向服务器推送

WebSocket：全双工通信

gRPC：高性能 RPC 框架

处理底层通信细节和协议转换

这种分层设计使得 MCP 具有：

良好的可扩展性：可以轻松添加新的传输机制

清晰的职责分离：各层专注于自己的功能

灵活的部署方式：支持多种通信场景

传输机制

| 传输 | 场景 | 特点 |
|------|------|------|
| Stdio | 本地 CLI / 子进程 | 零网络开销，启动快 |
| HTTP + SSE | 微服务 / Web 应用 | POST 请求 + SSE 推流，部署友好 |
| 自定义 | WebSocket / gRPC | 只需实现 Transport 接口即可 |

Java Spring AI 集成实践

使用 Spring AI 开发，详细说明可以参考官网文档。

MCP 分为 Stdio 和 SSE 两种传输方式，下面的例子使用 SSE 方式，最简化开发一个发票助手 MCP，并展示如何通过模型自动调用这个 MCP。

POM 依赖

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

配置示例 `application.properties`

spring.main.banner-mode=off
# logging.pattern.console=
spring.ai.mcp.server.name=my-invoice-server
spring.ai.mcp.server.version=0.0.1

详细的配置参数及默认值可以参考官方文档：Spring AI / Model Context Protocol (MCP) / MCP Server Boot Starters)。

暴露 Tool

这里就模拟一个非常简单的功能，仅拼装对应参数，返回发票链接。

@Service
public class InvoiceService {

    @Tool(description = "获取发票链接")
    public String getInvoiceUrl(@ToolParam(required = true, description = "发票 id") String invoiceId) {
        return "https://www.example.com/invoice/" + invoiceId;
    }
}

@SpringBootApplication
public class McpServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

    @Bean
    public ToolCallbackProvider invoiceTools(InvoiceService invoiceService) {
        return MethodToolCallbackProvider.builder().toolObjects(invoiceService).build();
    }
}

启动服务

执行 java -jar mcp-server.jar 启动服务，默认监听 8080 端口。

在 MCP client 中配置 mcp.setting

cursor、VS code 中的 cline 插件都算是 MCP client。本文展示 cline 插件如何配置。

cline_mcp_setting.json 增加如下配置：

{
  "mcpServers": {
    "invoice-local": {
      "url": "http://localhost:8080/sse",
      "autoApprove": [
        "getInvoiceUrl"
      ]
    }
  }
}

我们可以看到对应的 getInvoiceUrl 方法已经被自动注册到 MCP Server 中。

使用 MCP！

在 cline 中输入问题：“我有一个发票 id 是 123456，发票链接是多少？”，可以看到模型会自动判断是否需要调用 MCP Server 中的 getInvoiceUrl 方法，并拼装参数，获取结果。

说明

1. JDK 版本必须 >= 17
2. Spring Boot 版本必须 >= 3.2
3. Spring AI 底层使用 modelcontextprotocol / java-sdk)
4. MCP 协议等都在快速发展中，上面的代码示例仅供参考，具体实现可能会有所不同

完整配置示例

Application.java：

package com.example.mcp;

import org.springframework.ai.mcp.server.tool.ToolCallbackProvider;
import org.springframework.ai.mcp.server.tool.MethodToolCallbackProvider;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.web.reactive.function.client.WebClient;

@SpringBootApplication
public class McpServerApplication {
    
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }
    
    /**
     * 注册所有 Tools
     */
    @Bean
    public ToolCallbackProvider toolCallbackProvider(
            DatabaseTools databaseTools,
            FileTools fileTools,
            HttpTools httpTools
    ) {
        return MethodToolCallbackProvider.builder()
            .toolObjects(databaseTools, fileTools, httpTools)
            .build();
    }
    
    /**
     * WebClient for HTTP tools
     */
    @Bean
    public WebClient webClient() {
        return WebClient.builder()
            .defaultHeader("User-Agent", "MCP-Server/1.0")
            .build();
    }
}

application.yml：

spring:
  application:
    name: mcp-server-demo
  
  ai:
    mcp:
      server:
        name: "Enterprise MCP Server"
        version: "1.0.0"
        description: "Comprehensive MCP server with database, file, and HTTP capabilities"
        
server:
  port: 8080
  
logging:
  level:
    org.springframework.ai.mcp: DEBUG
    com.example.mcp: DEBUG

MCP Client 配置与使用

Claude Desktop 配置

Claude Desktop 是最早支持 MCP 的应用之一。配置文件位置：

macOS：

~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows：

%APPDATA%\Claude\claude_desktop_config.json

配置示例：

{
  "mcpServers": {
    "enterprise-server": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/mcp-server.jar"
      ],
      "env": {
        "SERVER_PORT": "8080"
      }
    },
    "database-server": {
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Cursor IDE 配置

Cursor 通过 .cursor/mcp.json 文件配置 MCP 服务器：

{
  "mcpServers": {
    "local-dev": {
      "command": "java",
      "args": ["-jar", "mcp-server.jar"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}"
      }
    },
    "remote-api": {
      "url": "https://api.example.com/mcp/sse",
      "autoApprove": ["read_file", "list_directory"]
    }
  }
}

Cline/Continue 配置

VS Code 插件 Cline 的配置文件：~/.cline/mcp_settings.json

{
  "mcpServers": {
    "development": {
      "url": "http://localhost:8080/sse",
      "autoApprove": [
        "query_database",
        "read_file",
        "list_directory"
      ],
      "alwaysAllow": ["get_table_schema"]
    }
  }
}

实际使用示例

场景 1：数据库查询

用户: 查询用户表中所有活跃用户的数量

AI: 我会帮你查询数据库。
[调用 query_database]
参数: sql = "SELECT COUNT(*) as count FROM users WHERE status = 'active'"

结果: {"rowCount": 1, "rows": [{"count": 1234}]}

AI: 当前有 1,234 个活跃用户。

场景 2：文件操作

用户: 帮我创建一个 README.md 文件,包含项目介绍

AI: 好的,我会创建 README 文件。
[调用 write_file]
参数:
  path = "README.md"
  content = "# Project Name\n\nThis is a comprehensive guide..."
  create_dirs = true

AI: README.md 文件已创建成功!

场景 3：代码审查

用户: 使用 code-review prompt 审查这段代码

AI: 我会使用专业的代码审查模板。
[调用 code-review prompt]
参数:
  language = "Java"
  code = "public class User { ... }"
  focus_areas = "安全性和性能"

AI: [提供详细的代码审查反馈...]

最佳实践

安全考虑

1. 输入验证

public class SecurityValidator {
    
    public static void validateSqlQuery(String sql) {
        // 防止 SQL 注入
        String lowerSql = sql.toLowerCase();
        String[] dangerousKeywords = {
            "drop", "delete", "update", "insert", 
            "truncate", "alter", "create"
        };
        
        for (String keyword : dangerousKeywords) {
            if (lowerSql.contains(keyword)) {
                throw new SecurityException(
                    "不允许的 SQL 操作: " + keyword
                );
            }
        }
    }
    
    public static Path validatePath(Path basePath, String userPath) {
        Path resolved = basePath.resolve(userPath).normalize();
        
        // 防止路径遍历攻击
        if (!resolved.startsWith(basePath)) {
            throw new SecurityException(
                "路径超出允许范围: " + userPath
            );
        }
        
        return resolved;
    }
}

2. 权限控制

@Configuration
public class McpSecurityConfig {
    
    @Bean
    public McpAuthorizationManager authorizationManager() {
        return new McpAuthorizationManager() {
            @Override
            public boolean canExecuteTool(String toolName, Principal user) {
                // 基于用户角色的权限控制
                return switch (toolName) {
                    case "query_database" -> 
                        user.hasRole("DATA_ANALYST");
                    case "write_file" -> 
                        user.hasRole("DEVELOPER");
                    default -> true;
                };
            }
        };
    }
}

3. API 速率限制

@Aspect
@Component
public class RateLimitAspect {
    
    private final RateLimiter rateLimiter = 
        RateLimiter.create(10.0); // 每秒 10 个请求
    
    @Around("@annotation(Tool)")
    public Object rateLimit(ProceedingJoinPoint joinPoint) 
            throws Throwable {
        if (!rateLimiter.tryAcquire()) {
            throw new RateLimitException(
                "请求过于频繁,请稍后再试"
            );
        }
        return joinPoint.proceed();
    }
}

性能优化

1. 结果缓存

@Service
public class CachedDatabaseTools {
    
    @Cacheable(value = "tableSchema", key = "#tableName")
    public TableSchema getTableSchema(String tableName) {
        // 缓存表结构,避免重复查询
        return databaseService.getSchema(tableName);
    }
    
    @Cacheable(
        value = "queryResults",
        key = "#sql",
        condition = "#sql.toLowerCase().startsWith('select')"
    )
    public QueryResult executeQuery(String sql) {
        return databaseService.execute(sql);
    }
}

2. 异步处理

@Service
public class AsyncFileTools {
    
    @Tool(description = "异步搜索文件")
    public CompletableFuture<List<String>> searchFilesAsync(
            @ToolParam(name = "pattern") String pattern
    ) {
        return CompletableFuture.supplyAsync(() -> {
            // 耗时的文件搜索操作
            return fileService.search(pattern);
        });
    }
}

3. 连接池管理

@Configuration
public class DatabaseConfig {
    
    @Bean
    public DataSource dataSource() {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl(jdbcUrl);
        config.setUsername(username);
        config.setPassword(password);
        
        // 优化连接池配置
        config.setMaximumPoolSize(20);
        config.setMinimumIdle(5);
        config.setConnectionTimeout(30000);
        config.setIdleTimeout(600000);
        
        return new HikariDataSource(config);
    }
}

错误处理

统一异常处理：

@ControllerAdvice
public class McpExceptionHandler {
    
    @ExceptionHandler(SecurityException.class)
    public ResponseEntity<ErrorResponse> handleSecurityException(
            SecurityException ex
    ) {
        return ResponseEntity
            .status(HttpStatus.FORBIDDEN)
            .body(new ErrorResponse(
                "SECURITY_ERROR",
                ex.getMessage()
            ));
    }
    
    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<ErrorResponse> handleValidationException(
            IllegalArgumentException ex
    ) {
        return ResponseEntity
            .status(HttpStatus.BAD_REQUEST)
            .body(new ErrorResponse(
                "VALIDATION_ERROR",
                ex.getMessage()
            ));
    }
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGenericException(
            Exception ex
    ) {
        log.error("Unexpected error", ex);
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ErrorResponse(
                "INTERNAL_ERROR",
                "服务暂时不可用,请稍后重试"
            ));
    }
}

record ErrorResponse(
    String code,
    String message
) {}

监控与日志

@Aspect
@Component
public class McpMonitoringAspect {
    
    @Around("@annotation(tool)")
    public Object monitorToolExecution(
            ProceedingJoinPoint joinPoint,
            Tool tool
    ) throws Throwable {
        String toolName = tool.name();
        long startTime = System.currentTimeMillis();
        
        try {
            Object result = joinPoint.proceed();
            long duration = System.currentTimeMillis() - startTime;
            
            // 记录成功的工具调用
            log.info(
                "Tool executed: {} | Duration: {}ms",
                toolName, duration
            );
            
            // 发送指标到监控系统
            metricsService.recordToolExecution(
                toolName, duration, "success"
            );
            
            return result;
            
        } catch (Exception ex) {
            long duration = System.currentTimeMillis() - startTime;
            
            // 记录失败的工具调用
            log.error(
                "Tool failed: {} | Duration: {}ms | Error: {}",
                toolName, duration, ex.getMessage()
            );
            
            metricsService.recordToolExecution(
                toolName, duration, "failure"
            );
            
            throw ex;
        }
    }
}

典型应用场景

1. IDE 智能助手

功能描述： 在 IDE 中提供代码生成、重构、调试等智能辅助功能。

实现示例：

@Service
public class IdeTools {
    
    @Tool(description = "生成单元测试")
    public String generateUnitTest(
            @ToolParam(name = "source_code") String sourceCode,
            @ToolParam(name = "test_framework") String framework
    ) {
        // 分析源代码
        CodeAnalysis analysis = codeAnalyzer.analyze(sourceCode);
        
        // 生成测试代码
        return testGenerator.generate(analysis, framework);
    }
    
    @Tool(description = "代码重构建议")
    public List<RefactoringSuggestion> suggestRefactoring(
            @ToolParam(name = "code") String code
    ) {
        return refactoringService.analyzePotentialImprovements(code);
    }
}

2. 企业数据分析

功能描述： 提供自然语言到 SQL 的转换,支持数据可视化。

@Service
public class DataAnalyticsTools {
    
    @Tool(description = "自然语言查询")
    public QueryResult nlQuery(
            @ToolParam(name = "question") String question
    ) {
        // 将自然语言转换为 SQL
        String sql = nlToSqlConverter.convert(question);
        
        log.info("Generated SQL: {}", sql);
        
        // 执行查询
        return databaseService.executeQuery(sql);
    }
    
    @Tool(description = "生成数据可视化")
    public ChartConfig generateChart(
            @ToolParam(name = "data") List<Map<String, Object>> data,
            @ToolParam(name = "chart_type") String chartType
    ) {
        return chartGenerator.generate(data, chartType);
    }
}

3. 文档生成与管理

@Service
public class DocumentationTools {
    
    @Tool(description = "生成 API 文档")
    public String generateApiDocs(
            @ToolParam(name = "swagger_spec") String swaggerSpec
    ) {
        return apiDocGenerator.generate(swaggerSpec);
    }
    
    @Tool(description = "更新用户手册")
    public UpdateResult updateUserManual(
            @ToolParam(name = "section") String section,
            @ToolParam(name = "content") String content
    ) {
        Path manualPath = docsPath.resolve("user-manual.md");
        return documentService.updateSection(manualPath, section, content);
    }
}

4. DevOps 自动化

@Service
public class DevOpsTools {
    
    @Tool(description = "部署应用")
    public DeploymentResult deploy(
            @ToolParam(name = "environment") String environment,
            @ToolParam(name = "version") String version
    ) {
        return deploymentService.deploy(environment, version);
    }
    
    @Tool(description = "查看日志")
    public List<LogEntry> getLogs(
            @ToolParam(name = "service") String service,
            @ToolParam(name = "lines") int lines
    ) {
        return logService.getTailLogs(service, lines);
    }
    
    @Tool(description = "检查服务健康状态")
    public HealthStatus checkHealth(
            @ToolParam(name = "service") String service
    ) {
        return healthCheckService.check(service);
    }
}

生态系统与工具

官方工具

1. MCP Inspector - 调试和测试 MCP 服务器

网址: inspector
功能: 实时查看工具调用、测试 prompts、监控资源

2. MCP CLI - 命令行工具
``bash npm install -g @modelcontextprotocol/cli mcp test http://localhost:8080/sse``

社区服务器

访问 mcp.so 浏览 1000+ 社区 MCP 服务器:

数据库: PostgreSQL, MySQL, MongoDB, Redis

云服务: AWS, Azure, GCP

开发工具: GitHub, GitLab, Jira

通信: Slack, Discord, Email

数据处理: Pandas, NumPy, Excel

客户端支持

| 客户端 | 支持程度 | 配置方式 |
|--------|---------|----------|
| Claude Desktop | ✅ 完整支持 | JSON 配置文件 |
| Cursor | ✅ 完整支持 | .cursor/mcp.json |
| Cline (VS Code) | ✅ 完整支持 | 插件配置 |
| Continue | ✅ 完整支持 | config.json |
| Zed | ✅ 实验性支持 | 内置配置 |

常见问题

Q: MCP 与 OpenAI Function Calling 有什么区别？

A: MCP 是一个开放协议,不绑定特定 AI 提供商。Function Calling 是 OpenAI 特定的实现。MCP 支持更丰富的能力(Tools, Resources, Prompts),而 Function Calling 主要聚焦于函数调用。

Q: stdio 和 SSE 传输方式如何选择？

stdio: 适合本地命令行工具,零网络开销,启动快

SSE: 适合 Web 服务,支持远程访问,易于部署和扩展

Q: MCP 服务器如何处理长时间运行的任务？

A: 建议使用异步模式:

@Tool(description = "异步任务")
public TaskId startAsyncTask(
        @ToolParam(name = "input") String input
) {
    // 返回任务 ID
    return taskService.submit(input);
}

@Tool(description = "查询任务状态")
public TaskStatus getTaskStatus(
        @ToolParam(name = "task_id") String taskId
) {
    return taskService.getStatus(taskId);
}

Q: 如何调试 MCP 服务器？

A:
1. 使用 MCP Inspector 工具
2. 启用详细日志: logging.level.org.springframework.ai.mcp=DEBUG
3. 使用 Postman 测试 SSE 端点
4. 添加监控和追踪

Q: MCP 服务器的性能瓶颈在哪里？

A: 常见瓶颈:

数据库连接池不足

未使用缓存

同步阻塞操作

大数据传输

优化建议见"性能优化"章节。

未来展望

即将到来的特性

1. 细粒度权限控制

基于工具的 ACL

资源级别的访问控制

审计日志

2. 多模态支持

图像分析工具

音频处理

视频内容理解

3. 增强的上下文管理

会话状态持久化

跨工具上下文共享

智能缓存策略

4. 更好的可观测性

内置追踪和指标

性能分析工具

实时监控面板

技术演进方向

协议版本 2.0: 更高效的二进制传输

边缘计算: 在浏览器中运行 MCP 服务器

联邦学习: 跨服务器的知识共享

AI Agent 框架: 与 LangChain, AutoGPT 等深度集成

生态发展

企业采用: 更多企业级 MCP 服务器

标准化: 行业标准和最佳实践

认证体系: MCP 服务器质量认证

市场生态: MCP 服务器市场和交易平台

参考资源

官方资源

MCP 官方网站: modelcontextprotocol
MCP 规范: modelcontextprotocol
MCP GitHub: modelcontextprotocol
MCP 服务器目录: mcp

Spring AI 相关

Spring AI 文档: reference
MCP 集成指南: mcp
示例仓库: spring-ai-examples
Spring AI MCP Server Starter: mcp-server-boot-starter-docs.html

技术规范

JSON-RPC 2.0: specification
Server-Sent Events: Server-sent_events
OpenAPI 3.0: specification

社区资源

MCP Discord: modelcontextprotocol
MCP Reddit: reddit
Stack Overflow: 标签 model-context-protocol
YouTube 教程: 搜索 "MCP Tutorial"

Agent 原理

Tue, 09 Jun 2026 14:30:34 +0800

引言：从 ChatGPT 到 Agent

近几年，大模型（如 ChatGPT）已经很好用了：能聊天、能写代码、能总结资料。
但如果你仔细观察，会发现它仍然更像一个「超强的函数」而不是一个真正的「智能体」：

你给它一个提示（prompt），它给你一次性输出；

它不会主动拆解长任务，也不会自己决定「先查资料再算账、最后再写总结」；

它不会持久记住你的目标，也不会自行规划步骤或调用外部系统。

Agent（智能体），就是在大模型的基础上，加上目标、记忆、工具调用、环境交互和长期规划能力，让它从一个「问答机器」进化为一个能在复杂环境中自主完成任务的执行者。

agent-all-in-one 项目，就是一个用来演示各种 Agent 范式的教学/实验仓库：

ReAct 范式

Plan-and-Execute 范式

Supervisor Multi-Agent 范式

Reflection 范式

下面这篇文章，会围绕这几个问题展开：

Agent 是什么？
1. 为什么需要 Agent？
2. Agent 的通用架构和运行循环是什么样？
3. Agent 都有哪些典型范式？agent-all-in-one 中各自对应什么实现？
4. Agent 相关有哪些经典论文/代表性工作值得一看？

一、什么是 Agent？

先给一个工程视角的定义：

Agent 是一个能够围绕给定目标，持续感知环境、做出决策、调用工具并更新自身状态的智能程序。

拆开看，一个典型的 LLM Agent 至少包含几个关键要素：

目标（Goal）

例如：「帮我规划 7 天日本旅行」「写一篇技术博客」「做一轮代码 Review」。

目标可以是一次性的，也可以被长期持有、拆解为子目标。

感知（Perception / Observation）

Agent 需要感知外部世界：搜索结果、数据库查询、API 响应、用户的追加指令等。

在 agent-all-in-one 里，这就是工具返回值（Observation）。

记忆（Memory）

短期：本轮对话历史、当前任务上下文。

长期：过往项目、用户偏好、历史工具调用结果等（更高级的系统才有）。

推理与决策（Reasoning & Decision Making）

决定「下一步该干什么」：是继续问用户、调用搜索工具、还是直接给出答案？

ReAct、Plan-and-Execute、Reflection 等范式，本质上都是在设计不同的决策流程。

行动（Action / Tool Use）

调用工具：搜索引擎、计算器、数据库、HTTP API、本地代码执行环境等。

在 agent-all-in-one 中，对应 search、calculator、get_current_time 等工具。

环境（Environment）

包括互联网、文件系统、业务系统、游戏世界（如 Minecraft）、机器人控制系统等。

Agent 通过工具与环境交互，从环境中获得新的 Observation。

用一个简单的框图来表示：

flowchart LR
  U[用户 / 上层系统] -->|任务/指令| A[Agent]
  A -->|调用| T[工具 / API / 子系统]
  T -->|结果| A
  A -->|中间结果 / 最终答案| U
  A -->|读写| M[记忆 / 状态]

在 agent-all-in-one 里，Agent 本身往往被实现为一个「图（Graph）」，其中每个节点代表一个步骤（如 Planner、Executor、Supervisor、Worker、Reflector 等），这些节点一起实现了上图中的「感知 → 决策 → 行动 → 更新状态」循环。

二、为什么需要 Agent？

如果我们只用「普通 ChatGPT 模式」，会遇到几个典型问题：

无法可靠完成复杂多步骤任务

示例：「帮我调研 3 篇最新的 LangGraph 相关技术文章，提取要点，做一个对比表格」

这背后其实需要：搜索 → 逐篇阅读 → 提取关键信息 → 汇总成结构化结果 → 写总结。

单轮大模型回答，很容易「跳步骤」「幻觉」或遗漏细节。

缺乏与真实世界系统的连接

例如：「帮我查当前汇率，并按今天价格估个机票预算」

大模型本身看不到实时数据，一定要通过「工具」连接真实世界。

缺少可观测、可调试的执行流程

单次回答你很难知道：

它有没有去查资料？

它是怎么做中间推理的？

Agent + 流程图（如 LangGraph）让整个过程变得可视化、可调试。

无法持续执行长任务

比如「帮我持续监控某股票的新闻，重要消息发通知」。

这类任务需要长期运行的 Loop，而不仅仅是一次性输出。

因此，Agent 的价值可以概括为：

从「大模型 = 强函数」升级到「大模型 = 可编排的智能子系统」；

让大模型能主动拆解任务、选择工具、调用环境，并在过程中自我修正；

让开发者可以像搭积木一样，将 ReAct / Plan-and-Execute / Multi-Agent / Reflection 等模式组合起来。

三、通用 Agent 架构与运行循环

无论是哪种范式（ReAct / Plan-and-Execute / 等），背后都有一个类似的「总循环」：

接收任务 → 解析任务 → 规划/决策下一步 → 行动（调用工具/子 Agent）→ 观察结果 → 更新状态与计划 → 判断是否结束。

可以用一个伪代码式的循环来描述：

while not done:
  1. 读取当前目标 + 状态 + 观察结果
  2. 大模型做推理（思考）：下一步该干什么？
  3. 得到决策：
     - 直接给出最终回答？ -> done = True
     - 调用某个工具？ -> 调用工具，获取新 Observation
     - 拆分为子任务？ -> 生成子计划 or 分配给其他 Agent
  4. 更新内部状态 / 记忆

简单的流程图示意：

flowchart TD
  S[开始: 接收用户任务] --> P[解析任务 / 理解意图]
  P --> D[决策: 下一步做什么?]
  D -->|调用工具| A1[执行 Action 工具调用]
  A1 --> O[观察 Observation]
  D -->|直接回答| R[生成最终回答]
  O --> U[更新状态 / 记忆]
  U --> D
  R --> E[结束]

在 agent-all-in-one 中，这个循环被用不同方式具体化：

react_agent/agent.py：在思考（Thought）— 行动（Action）— 观察（Observation）的循环中实现；

plan_execute_agent/：把「规划」「执行」拆到不同节点（Planner / Executor）；

multi_agent/graph.py：通过 Supervisor 调度不同 Worker，在图结构中走不同路径；

reflection_agent/：在 Generator ↔ Reflector 之间形成一个「改写—评价—再改写」的闭环。

四、Agent 常见范式总览

围绕 LLM 构造 Agent，目前比较常见的几类范式是：

ReAct 范式：

Thought（思考） + Action（行动） + Observation（观察）循环。

适合工具有限、任务较短的场景。

Plan-and-Execute 范式：

先由 Planner 生成一个完整计划/任务分解，再由 Executor 逐步执行。

适合复杂、多步骤、可清晰拆解的任务。

Supervisor Multi-Agent 范式：

有一个负责「任务分配」的 Supervisor，底下挂多个专长不同的 Worker。

适合需要多技能并行协作的场景，如「搜索 + 计算 + 写作」。

Reflection 范式：

Agent 会「审视自己之前的输出」，根据评审反馈做迭代改写。

适合对输出质量要求极高的任务，如技术文章、复杂分析报告。

agent-all-in-one 恰好分别实现了这四种范式，对应目录为：

react_agent/

plan_execute_agent/

multi_agent/

reflection_agent/

五、`agent-all-in-one` 中的四种典型 Agent 范式

5.1 ReAct 范式：推理 + 行动

核心思想：
把大模型的自然语言推理能力（Reasoning）和工具调用能力（Acting）交替结合起来，在「思考—行动—观察」的循环中逐步解决问题。

一个典型的 ReAct 交互日志大概是这样的（简化版）：

Question: 计算 123 * 456 等于多少？

Thought: 这是一个乘法计算，我应该调用计算器工具。
Action: calculator("123 * 456")
Observation: 56088

Thought: 已经得到结果，可以回答用户了。
Final Answer: 123 * 456 = 56088。

ReAct 的通用流程图：

sequenceDiagram
  participant U as 用户
  participant A as Agent (ReAct)
  participant T as 工具

  U->>A: 问题/任务
  loop Thought-Action-Observation
    A->>A: Thought: 推理下一步
    A->>T: Action: 调用工具
    T-->>A: Observation: 工具结果
  end
  A-->>U: Final Answer

在 agent-all-in-one 中：

实现位置：react_agent/agent.py

工具定义：react_agent/tools.py

特点：

实现简单、灵活；

把中间推理过程暴露为可观察的「Thought」文本，很好调试；

更适合「一次性问题」或「工具数量不太多」的场景。

5.2 Plan-and-Execute 范式：先规划，再执行

当任务很复杂时，直接用 ReAct 可能会「想到哪做到哪」，缺乏全局视角。
Plan-and-Execute 范式把整个过程拆为两层：

1. Planner（规划器）：一次性生成一个较完整的任务计划；
2. Executor（执行器）：顺着计划一步步执行，每一步内部可以再用 ReAct/工具等。

示意流程：

flowchart TD
  U[用户任务] --> P[Planner: 生成计划 Step 1..N]
  P --> E[Executor: 逐步执行每个 Step]
  E --> R[执行结果 & 总结]
  R --> U2[返回给用户]

一个典型例子：

用户任务：帮我规划一次去日本的 7 天旅行，包括：
  - 机票预估预算
  - 每天的城市安排
  - 必去景点和大致价格区间

Planner 可能生成类似的计划：
  Step 1: 通过搜索获取从用户城市飞往东京/大阪的往返机票平均价格
  Step 2: 估算 7 天的住宿预算，按中档酒店标准
  Step 3: 设计 Day 1-7 的城市和景点安排
  Step 4: 输出包含预算和行程表的总结文档

Executor 按 Step 1 -> 2 -> 3 -> 4 顺序执行，每一步都可以用工具/子 Agent。

在 agent-all-in-one 中：

规划相关代码：plan_execute_agent/planner.py

执行相关代码：plan_execute_agent/executor.py

Agent 入口：plan_execute_agent/agent.py

适用场景：

长任务、结构比较清晰的任务（旅行规划、项目 Roadmap 设计、调研报告等）；

需要先看整体再细化的情况；

便于在 LangGraph Studio 中可视化：你能看到 Planner 节点出一个计划，Executor 节点按计划一步步跑。

5.3 Supervisor Multi-Agent 范式：多智能体协作

有些任务「内含多种技能」，比如：

「搜索今天的天气，计算 256 * 789，然后写一份总结。」

如果全部交给一个 Agent 来做，它当然也能完成，但会变得「又要查资料，又要算，又要写」，逻辑混杂。
多智能体范式把不同职责拆开，让多个专长不同的 Agent 协同工作，由一个上层 Supervisor 负责调度。

在 agent-all-in-one 中，多智能体结构大致是：

Supervisor（主管）：

在 multi_agent/supervisor.py

负责理解全局任务，决定「什么时候让哪个 Worker 出场」。

Workers（工作者）：在 multi_agent/workers.py 中定义，例如：

Researcher：使用搜索工具获取信息；

Calculator：负责准确计算（数学/逻辑计算）；

Writer：负责用自然语言输出总结/报告。

可以画成这样的结构：

flowchart TD
  U[用户任务] --> S[Supervisor]
  S --> R[Worker: Researcher]
  S --> C[Worker: Calculator]
  S --> W[Worker: Writer]
  R --> S
  C --> S
  W --> S
  S --> U2[最终回答]

一个典型的执行流程可能是：

1. 用户给出复合任务（搜索 + 计算 + 写作）
2. Supervisor 分析任务，先调用 Researcher 搜集事实
3. Researcher 用 search 工具查资料，返回 Observation
4. Supervisor 根据 Observation 调用 Calculator 完成数值计算
5. 最后 Supervisor 把数据交给 Writer 生成自然语言总结
6. 返回综合结果给用户

这种范式的优点：

职责清晰：每个 Worker 专精一类任务，更易于调试和扩展；

容易并行化：多个 Worker 可以并行执行子任务；

贴合现实团队协作：Supervisor 就像项目经理，Workers 像不同专业的工程师。

5.4 Reflection 范式：反思与自我改进

当你希望 Agent 产出高质量内容（比如技术文章、方案设计、代码优化建议），一次性输出往往不够。
Reflection 范式的核心，是让 Agent 拥有「自我审阅、反思并改写」的能力。

在 agent-all-in-one 中，典型角色和流程：

Generator（生成器）：reflection_agent/generator.py

根据任务和历史反馈，生成当前版本的答案。

Reflector（反思器）：reflection_agent/reflector.py

给当前答案做 Review：指出问题、不足、改进方向。

反馈可以从多个维度考虑：准确性、完整性、清晰度、结构等。

迭代闭环：

flowchart TD
  U[任务说明] --> G[Generator: 生成答案 V1]
  G --> R[Reflector: 评审 V1, 给出改进建议]
  R --> G2[Generator: 生成答案 V2]
  G2 --> R2[Reflector: 再次评审]
  R2 -->|直到质量合格或达到最大轮数| F[最终答案]

一个简单例子（写技术文章）：

Round 1:
  Generator 输出一篇「LangGraph 简介」文章
  Reflector 评审：指出缺少使用示例、对比传统流程编排方式、没有提到可视化调试

Round 2:
  Generator 根据反馈扩展：加入代码示例、小项目 demo、图示
  Reflector 再次评审：结构有点松散，可以重构为「概念 -> 使用 -> 示例 -> 总结」

Round 3:
  Generator 重构结构，增加小结和实践建议
  Reflector 认为已达到质量要求 -> 输出最终稿

优点：

易于反复打磨输出质量，尤其适合：技术博客、API 文档、系统设计说明；

天然适配「人类在回路中」的场景：Reflector 也可以是人，而不是模型；

在 LangGraph Studio 中，你能看到每一轮 Generator / Reflector 的中间版本，非常利于调试。

六、Agent 相关经典论文 / 代表性工作

下面按主题列出一些与 Agent、工具增强 LLM、多智能体协作相关的经典或代表性工作，你可以根据兴趣和需要选择阅读。

6.1 工具增强与推理（Tool-augmented Reasoning）

ReAct: Synergizing Reasoning and Acting in Language Models

Yao et al., 2022

提出了 ReAct 范式：将「自然语言推理（Thought）」与「行动（Action）」交替结合，用于工具调用和环境交互。

对应 agent-all-in-one 中的 react_agent/ 实现。

Toolformer: Language Models Can Teach Themselves to Use Tools

Schick et al., 2023

研究如何让大模型通过自监督方式，在预训练阶段就「学会插入合适的工具调用」，而不是只在推理阶段硬编码；

更偏向「模型训练策略」，但对实际 Agent 设计有启发：工具调用可以是训练出来的模式，而不是完全手工 Prompt。

PAL: Program-Aided Language Models

Chen et al., 2022

提出让模型生成可执行代码片段（如 Python）来完成复杂推理任务，再执行代码获得结果；

在 Agent 语境下，可以看作是「把工具 = 代码执行环境」，通过代码而不是纯文本进行严谨推理。

Chain-of-Thought Prompting Elicits Reasoning in Large Language Models

Wei et al., 2022

不直接讲 Agent，但给出了让模型显式写出中间推理步骤（思维链）的技巧；

ReAct 可以看作是在 CoT 基础上，再接了一层「工具行动」。

6.2 反思与自我改进（Reflection / Self-Refine）

Reflexion: Language Agents with Verbal Reinforcement Learning

Shinn et al., 2023

倡导让 Agent 对自己的行为结果做「语言化反思」，并利用反思来改进后续策略；

与 agent-all-in-one 中的 Reflection 范式高度契合：Generator + Reflector 的闭环。

Self-Refine: Iterative Refinement with Self-Feedback

Madaan et al., 2023

让模型对自己的回答生成反馈（例如指出模糊、不准确之处），再根据反馈改写答案；

对写作、代码生成、翻译等任务非常实用，是很多 Reflection 型 Agent 的灵感来源。

6.3 规划、搜索与决策（Planning / Search）

Tree of Thoughts: Deliberate Problem Solving with Large Language Models

Yao et al., 2023

把大模型的推理过程看作在「思维树」上进行搜索，而不是一条线性的思维链；

为更复杂的规划型 Agent 提供了搜索框架：可以保留多条候选思路，做回溯和评估。

Plan-and-Solve Prompting（可查阅相关工作）

思想与 Plan-and-Execute 很接近：先让模型显式写出计划，再按计划解决任务；

在 agent-all-in-one 中，plan_execute_agent/ 其实就是这种思想的工程化实现。

6.4 多智能体与长期任务（Multi-Agent / Long-horizon Agents）

Voyager: An Open-Ended Embodied Agent with Large Language Models

Wang et al., 2023

在 Minecraft 环境中构建了一个「会自己探索、记忆、学习技能」的长期 Agent；

关键点在于：技能库（技能程序的记忆）、长期目标、与环境的持续交互。

对于理解「真正意义上的 Agent（不仅是 QA 机器人）」非常有启发。

Auto-GPT / BabyAGI 等开源项目（虽然不都是论文）

把 LLM 装上「目标管理、任务分解、任务队列、执行器、记忆」等模块，形成较完整的 Agent 系统；

是许多工程实践中「多轮自动执行、反复调用工具」范式的早期样板。

七、如何选择和实践这些 Agent 范式？

结合 agent-all-in-one，可以给出一个简单的「学习和实践路径」：

1. 从 ReAct 入门

先理解 Thought / Action / Observation 循环；

在 react_agent/ 中观察：

模型是如何决定「该用哪个工具」的？

工具输入/输出是如何以文本形式被包装起来的？

2. 向 Plan-and-Execute 过渡

在 plan_execute_agent/ 里理解 Planner / Executor 拆分后的好处：

Planner 只考虑「做什么」和「顺序」；

Executor 只负责「一步步把事情做完」。

在 LangGraph Studio 中查看这两类节点的执行路径。

3. 尝试 Multi-Agent 协作

打开 multi_agent/graph.py 和 workers.py，看看：

Supervisor 是根据什么信息决定调用哪个 Worker？

Worker 之间有没有共享状态 / 记忆？

尝试给系统增加一个新 Worker（比如「翻译专家」），体会可扩展性。

4. 最后玩转 Reflection 范式

在 reflection_agent/ 中观察 Generator 和 Reflector 的反复交互；

尝试调高/调低「迭代轮数」，看看输出质量和时间的权衡；

把你正在写的技术文章交给这个 Agent 打磨试试。

小结

Agent 是什么：在大模型之上，加入目标、记忆、工具和环境交互的「智能执行体」。

为什么需要 Agent：为了解决复杂任务、多工具协同、长时运行以及可观测调试的问题。

常见范式：ReAct、Plan-and-Execute、Supervisor Multi-Agent、Reflection 等，各有适用场景。

agent-all-in-one 的价值：它把这些范式都做了一个最小但完整的工程实现，配合 LangGraph Studio，可以清楚看到 Agent 的内部思考和工具调用链路，非常适合作为你在笔记库《Agent 原理》中的「理论 + 实战」桥梁。

下载文档

Skill：让 Agent 变得可复用、可控、可演进

Mon, 08 Jun 2026 15:36:24 +0800

为什么要把“提示词经验”升级成 `Skill`

如果你只是偶尔问问 ChatGPT，一个“写得不错的 Prompt”已经足够。

但只要你开始用 Agent 做事（写代码、跑脚本、查资料、写文档、对接系统），很快会撞上三个工程层面的老问题：

不稳定：同一个任务，今天能做对，明天换点上下文就跑偏。

不可控：你知道它“可能会做”，但你说不清它“应该怎么做”，更别提调试。

难复用：每次都要靠“临场发挥”去改提示词，经验沉淀不下来。

我倾向于把这类问题归因到一句话：你把一段“工作方法”塞进了对话上下文，但它并不是一个“可调用的能力单元”。

而 Skill 的目标很朴素：把“会做”变成“可调用”，把“经验”变成“资产”。

一、`Skill` 是什么

1.1 一句话定义：`Skill` 解决了什么问题

Skill 是对某类任务的“稳定做法”的封装：它把你希望 Agent 遵循的步骤、校验点、输入输出规范、以及可用工具边界，做成一个可以复用的能力单元。

你可以把它理解成：

在软件工程里，它更像一个“模块 / 函数”，而不是“临时写在控制台里的命令”；

在团队协作里，它更像一份“可执行的 SOP”，而不是“某个人脑子里的诀窍”。

1.2 `Skill` 的组成：说明、契约、边界、失败处理

一个最小可用的 Skill，建议至少回答四个问题：

它能做什么：适用场景与目标（以及 Non-Goals：明确“不做什么”）。

怎么用它：输入是什么、输出长什么样（可被下游消费）。

它怎么做：步骤、关键决策点、每步的校验标准。

它在什么边界里做：能调用哪些工具，能读写哪些资源，遇到失败怎么处理（重试/降级/请求用户补充信息）。

这里面最“反直觉”的，是 输入输出契约。

很多人写提示词只关注“你要做什么”，但忽略“你要输出什么结构”。结果就是：看起来像在执行，但产物不可用、不可组合、不可验证。

1.3 一张图看懂：`Skill` 的“可验收执行链”

如果只看文字，Skill 很容易被误解成“更长的 Prompt”。其实它更像一条可中断、可回退、可验收的执行链：

flowchart TB
  A[Inputs 输入<br/>必填/选填] --> B[Steps 执行步骤<br/>可拆分/可复用]
  B --> C[Checks 校验点<br/>格式/范围/关键字段]
  C -->|通过| D[Outputs 产物<br/>结构固定/可被下游消费]
  C -->|失败| E[Failure Modes 失败处理<br/>补信息/重试/降级/停止]
  E --> B

1.4 `Skill` 的颗粒度：什么时候拆，什么时候合

我的经验是：把 Skill 的颗粒度控制在“一次对话里可以讲清楚、一次执行里可以验收”。

一个粗糙但好用的判断方式：

该拆的信号：

一个 Skill 里出现了多种完全不同的决策路径；

产物形态差异很大（时而写报告、时而写代码、时而查数据）；

你发现自己想给它加越来越多的“如果……就……否则……”。

该合的信号：

拆开后每个 Skill 都依赖前一个 Skill 的半成品；

你需要用户频繁“手动串联”多个 Skill 才能完成一个最小任务。

二、为什么需要 `Skill`

2.1 复用：把个人经验变成团队资产

在没有 Skill 的世界里，经验往往以三种形式存在：

某个“写得不错”的聊天记录；

某个人脑子里的“手感”；

一个越写越长、越改越乱的系统提示词。

Skill 的价值在于：它让经验具备可复制性。

一旦你把能力写成 Skill，它就可以：

被别的 Agent 复用；

被同一个 Agent 在不同项目复用；

被团队评审、迭代、版本化。

2.2 可控：让结果稳定，过程可解释

“可控”不是指让模型不犯错，而是指：

你能明确它“应该按哪些步骤做”；

你能定位它“在哪一步偏了”；

你能以最小代价修复（改 Skill 的某个步骤/校验点），而不是重写整段提示词。

这其实就是把 Agent 从“玄学”拉回“工程”的核心手段。

2.3 降低上下文膨胀：按需注入，而不是永久塞进系统提示词

当你把所有经验都塞进系统提示词时，你会得到一个“看起来无所不能”的 Agent，但代价是：

上下文越来越大，模型注意力被稀释；

规则之间开始互相打架；

修改任何一处都可能引入连锁反应。

Skill 的思路是：默认轻装上阵，需要某项能力时再加载该能力的说明与约束。

2.4 团队协作视角：写 `Skill` 像写 `SOP`，用 `Skill` 像调用函数

当你把 Skill 当成团队资产后，很多工程问题会自然出现一套“正确做法”：

需要 review（否则每个人都会写出一套不兼容的输出格式）；

需要版本号（否则你不知道线上用的是哪一版）；

需要验收标准（否则你只是在写“更长的文字”）。

三、`Skill` 和 `MCP` 的区别

一句话概括：

Skill 解决“怎么做”：方法、流程、校验、产物。

MCP 解决“能做什么”：把外部工具/资源用标准协议接进来，让 Agent 可调用。

你可以把它理解成两层：

工具层（MCP）：提供可调用的 Tool / 可读取的 Resource / 可复用的 Prompt。

方法层（Skill）：把工具按某种可靠流程组织起来，形成稳定产物。

graph TD
    User[用户 User] -->|自然语言指令| Agent
    
    subgraph Agent Runtime
        SystemPrompt[System Prompt<br/>(人设、基础约束)]
        Router[决策/路由层]
    end
    
    Agent --> SystemPrompt
    SystemPrompt --> Router
    
    subgraph Skill Layer [Skill 层 (怎么做)]
        S_Write[写作 Skill<br/>(SOP、校验、格式)]
        S_Code[代码 Skill<br/>(重构、测试、Review)]
        S_Search[搜索 Skill<br/>(关键词优化、总结)]
    end
    
    Router -->|匹配场景| S_Write
    Router -->|匹配场景| S_Code
    
    subgraph MCP Layer [MCP 工具层 (能做什么)]
        T_File[文件读写 Tool]
        T_DB[数据库 Tool]
        T_Web[联网搜索 Tool]
    end
    
    S_Write -->|调用| T_File
    S_Code -->|调用| T_File
    S_Search -->|调用| T_Web

3.1 典型误区：把 `Skill` 当 `Tool`，或把 `MCP` 当工作流引擎

常见的两个走偏方式：

把 Skill 当 Tool：把 Skill 写成“调用某个接口的说明书”，最后得到的是一个脆弱的、只在某个项目里能跑通的流程。

把 MCP 当工作流引擎：以为“把工具接进来”就等于“事情能做好”，但缺少 Skill 的校验点与产物标准，最后输出仍然不可控。

真正的组合方式通常是：Skill 调用 MCP Tool。

3.2 一个直观类比：`Skill` 是“代码结构”，`MCP` 是“依赖注入”

如果把 Agent 当作一个软件系统：

MCP 更像依赖注入：我把数据库、文件系统、内网 API 这些能力“接进来”；

Skill 更像业务代码：我规定“什么时候查库”“什么时候读文件”“什么时候让用户确认”，并把产物结构固定下来。

再用一张图表达“谁依赖谁”会更直观：

flowchart TB
  subgraph L2[方法层：`Skill`]
    S1[Workflow / SOP<br/>步骤编排]
    S2[Contracts<br/>输入输出契约]
    S3[Checks<br/>验收与中断点]
    S2 --> S1
    S3 --> S1
  end

  subgraph L1[工具层：`MCP`]
    T1[Tool<br/>File/DB/API]
    T2[Resource<br/>Docs/KB]
    T3[Prompt<br/>模板/片段]
  end

  S1 --> T1
  S1 --> T2
  S1 --> T3

四、如何设计一个“好用”的 `Skill`

这一节更偏方法论：你不需要任何框架，也不需要先写代码，只要把它当成“写给未来自己的 SOP”。

4.1 先写 `Non-Goals`：不做什么，比做什么更重要

一个 Skill 最容易失控的地方是“贪多”。

建议在开头直接写清楚：

这个 Skill 不处理哪些情况；

这些情况应该交给哪个 Skill / 交给用户补充什么信息；

失败时允许的降级方案是什么。

这会显著减少 Agent 的“自作主张”。

4.2 再写校验点：每一步都可验证、可中断、可回退

好 Skill 的关键不是“步骤多”，而是“每步可验收”：

可验证：每一步输出都能用简单规则检查（格式、范围、关键字段齐全）。

可中断：发现不满足前置条件时，立即停下来问用户，而不是硬编。

可回退：如果某一步失败，有明确的替代路径（例如改用另一种数据源，或先输出 TODO 列表）。

这类“校验点”越明确，Agent 越像工程系统，而不是聊天机器人。

把 4.1～4.2 合起来，其实就是一个“从目标到验收”的设计流：

flowchart LR
  A[Goal 目标] --> B[Non-Goals 不做什么]
  B --> C[Inputs/Outputs 输入输出契约]
  C --> D[Steps 步骤编排]
  D --> E[Checks 校验点]
  E --> F[Failure Modes 失败处理]
  F --> G[Examples & Version 示例与版本化]

4.3 最后写触发条件：什么时候该用这个 `Skill`

一个 Skill 如果没有“触发条件”，最终会变成“每次都想用，但每次都要解释一遍”。

建议写成三段：

适用场景：满足哪些条件时，优先使用它。

不适用场景：哪些情况不要用。

快速自检：用户只要回答 2～3 个问题，你就能判断该不该启用。

4.4 一个可复用的 `Skill` 模板（推荐）

你可以把下面这个模板当成写 Skill 的骨架（放在 SKILL.md 里也好，放在内部文档里也好）：

Skill 名称：

目标（Goal）：

不做什么（Non-Goals）：

输入（Inputs）：
- 必填：
- 选填：

输出（Outputs）：
- 产物格式：
- 验收标准：

工具边界（Tooling Boundaries）：
- 允许调用：
- 禁止调用：
- 权限与安全要求：

执行步骤（Steps）：
1)
2)
3)

校验点（Checks）：
- Step 1 校验：
- Step 2 校验：

失败处理（Failure Modes）：
- 缺信息：
- 工具失败：
- 结果不可信：

4.5 实战案例：Java 代码审查 Skill

这是一个真实的 Skill 定义示例，你可以直接存为 .cursor/rules/java-review.mdc：

---
description: 当用户要求 Review Java 代码时触发
globs: *.java
---

# Java Code Review Skill

## 目标
找出代码中的 NPE 风险、并发问题及不符合阿里巴巴规范的命名。

## Non-Goals
- 不负责重写整个架构
- 不关注缩进和空格（交给 Formatter）

## 审查步骤 (Steps)
1. **安全性检查**：扫描所有入参，检查是否有 `@Nullable` 或未判空的使用。
2. **性能检查**：检查循环中是否有数据库调用或 RPC。
3. **规范检查**：对比变量命名是否符合驼峰，常量是否大写。

## 校验点 (Checkpoints)
- [ ] 每一个指出的问题必须引用具体行号。
- [ ] 每一个修改建议必须提供 `Before` 和 `After` 代码对比。

## 失败处理
- 如果代码依赖缺失导致无法判断类型，请输出 "⚠️ 缺少上下文，假设为..."

五、在 `Claude Code` 和 `Cursor` 上落地 `Skill`

这一节我会尽量给你“可操作”的路径，但不同产品对 Skill 的实现细节会随版本变化：文件放哪里、如何 reload，以你当前环境为准。

5.1 `Claude Code`：把 `Skill` 当成“可发现的能力包”

概念上，你可以把 Claude Code 的 Skill 当成一个目录（一个能力包）：

目录名：skill 的名字（也是它被发现/调用时的标识）

SKILL.md：这项能力的说明与执行规范（建议按上面的模板写）

其他文件：脚本、示例输入输出、测试用例（可选）

一个推荐的组织方式是把它们放进项目内的 skills/ 目录，形如：

your-repo/
  skills/
    blog-writer/
      SKILL.md
      examples/
        input.md
        output.md

当你需要启用某个 Skill 时，核心不是“神秘指令”，而是两件事：

让 Agent 知道这个 Skill 存在（可发现）

让 Agent 按 SKILL.md 的契约输出（可验收）

如果你用的是 Claude Code 自带的 Skill 管理/重载能力（有的版本会提供类似 /reload 的命令），建议把它当成“开发态便利功能”，而不是系统设计的前提：真正重要的是目录结构与契约文本本身。

5.2 `Cursor`：用 `.cursor/rules/*.mdc` 组织“类 `Skill`”

Cursor 当前更偏“Rules 驱动”：你把一套稳定做法写进 .cursor/rules/*.mdc，它就能在对话/改代码时持续遵循这套约束。

你仓库里已经有一个规则文件：.cursor/rules/yano-blog-writer.mdc，它本质上就是一个非常标准的“写作类 Skill”：

明确流程：先大纲，再正文（强制交互确认）

明确风格：中文与 English 空格、术语用反引号

明确自检清单：输出前过一遍

如果你要在 Cursor 里继续扩展 Skill，我建议的做法是：

一个 Skill 一个 .mdc 文件：命名体现用途（例如 agent-skill-design.mdc）

默认 alwaysApply: false：避免所有对话都被“规则污染”

需要长期生效时再开启：把 alwaysApply 改为 true，或把关键规则复制到当前任务上下文里

5.3 与 `MCP` 的配合：用 `.cursor/mcp.json` 把工具接入作为能力底座

如果你的 Skill 需要“调用外部能力”（读文件、查数据库、访问内网 API），那就让 MCP 来解决“接入工具”。示例：

{
  "mcpServers": {
    "local-dev": {
      "command": "java",
      "args": ["-jar", "mcp-server.jar"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

我更推荐的组合方式是：

Skill（规则/流程）写在 .cursor/rules/.mdc 或 skills//SKILL.md

能力（工具/资源）通过 .cursor/mcp.json 接入

让 Skill 去“调用工具并验收产物”，而不是让工具去“替你决定做法”

5.4 `Skill` 的测试与调试

Skill 既然是工程化的，就必须可测试。建议的测试策略：

黄金数据集：保留一组 Input 和期望的 Output。

回归测试：当你修改 Skill 的步骤时，用上面的 Input 跑一遍，看 Output 格式是否崩坏。

调试技巧：在 Skill 中显式要求 Agent 输出 <thinking> 标签，打印它执行每一步时的决策过程。

六、结尾：`Skill` 的本质，是把“工作方法”产品化

我对 Skill 的最短总结是：

把“工作方法”写成可复用的能力单元，让 Agent 从“会聊”走向“会做”，从“能做”走向“稳定地做”。

如果你已经在写 Prompt、写 Rules、接 MCP 工具，那你其实已经走在 Skill 的路上了：接下来只差把它们“模块化、契约化、可验收化”。

下载文档

获取闲鱼Cookie的方法

Wed, 03 Jun 2026 17:17:48 +0800

闲鱼客服对接方法？要搭建闲鱼客服，要用到闲鱼Cookie，那来接下来说一下获取闲鱼Cookie的方法！

获取闲鱼Cookie

1、打开Chrome浏览器

访问闲鱼网页版

2、登录你的闲鱼账号

3、打开开发者工具

按F12打开开发者工具，切换到"网络/Network"标签页，选择Fetch/XHR

4、刷新页面

找到任意一个请求

5、复制Cookie

在请求头中找到"Cookie"字段，复制其完整内容作为COOKIES_STR的值

6、填入COOKIES_STR值

找到代码里“COOKIES_STR=”如.env文件，最终显示内容应该类似如下

闲鱼自动回复管理系统开源版

Wed, 27 May 2026 16:41:14 +0800

挺不错的一套闲鱼客服智能自动回复管理系统，代码开源可二开。没深入研究里面功能，只是简单搭建测试了下，功能齐全，却只有3M大小。

闲鱼自动回复管理系统是一个基于 Python + FastAPI 开发的自动化客服系统，专为闲鱼平台设计。系统通过 WebSocket 连接闲鱼服务器，实时接收和处理消息，提供智能化的自动回复服务。

系统要求

开发环境

Python 3.11+
Node.js 18+
MySQL 8.0+
Redis 6+
Chromium / Chrome（Playwright 相关功能）

生产环境

Docker 20.10+
Docker Compose 2.0+
最低 2 核 CPU / 4GB 内存
推荐 4 核 CPU / 8GB 内存

项目结构

xianyu-auto-reply/
├── backend-web/          # 主 Web API 服务（端口 8089）
├── websocket/            # 闲鱼连接与消息处理服务（端口 8090）
├── scheduler/            # 定时任务服务（端口 8091）
├── common/               # 主系统与返佣系统共享模块
├── frontend/             # 主系统前端（端口 9000）
├── launcher/             # Windows 桌面启动器（Nuitka 打包为 EXE）
├── promotion/
│   ├── backend/          # 返佣后端（端口 8092）
│   └── frontend/         # 返佣前端（端口 9001）
├── scripts/              # CI/CD 与工具脚本
├── docker/frontend/      # 前端 Dockerfile 与 Nginx 配置
├── docker-compose.yml    # 本地源码构建编排
├── deploy.sh             # 一键部署脚本（自动生成远程镜像版 compose）
├── update.sh             # 一键更新脚本（拉取最新远程镜像）
├── build.sh              # 本地源码全量构建脚本
├── build_frontend.sh     # 单独构建并重启 Frontend
├── build_backend_web.sh  # 单独构建并重启 Backend-Web
├── build_websocket.sh    # 单独构建并重启 WebSocket
├── build_scheduler.sh    # 单独构建并重启 Scheduler
├── EXE打包构建.bat       # Windows 桌面启动器打包脚本
├── 离线依赖打包.bat      # Windows 离线依赖打包脚本
└── README.md

搭建教程

本地源码 Docker 构建，附件获取源码，上传到服务器解压，在文件根目录执行一键安装：

bash build.sh rebuild

安装时间有点长，老编好像等了十来分钟，如果安装报错通常是缺环境依懒，复制报错问AI就可以。

安装成功：

常用命令：

命令	说明
`bash build.sh rebuild`	删除旧容器与镜像，重新构建并启动
`bash build.sh start`	启动服务
`bash build.sh stop`	停止服务
`bash build.sh restart`	重启服务
`bash build.sh logs`	查看实时日志
`bash build.sh status`	查看服务状态

登陆后台

http://你的IP:9000/login（需要使用域名的，自行设置反向代理即可）

默认账号: admin / admin123

常见问题

根目录 Docker Compose 没有启动返佣系统？

当前 docker-compose.yml 只覆盖主系统。返佣系统需要单独启动。

登录或发布时报浏览器缺失？

在对应 Python 环境执行：python -m playwright install chromium。Docker 环境依赖各服务 Dockerfile 内已安装的浏览器。

Docker 部署端口冲突？

修改根目录 .env 中的端口配置后重新部署。

执行脚本报 `/bin/bash^M: 坏的解释器`？

脚本文件包含 Windows 换行符（CRLF），Linux 无法识别。解决方法：

# 方法一：用 sed 去除 \r 后执行 sed -i 's/\r$//' deploy.sh bash deploy.sh 
# 方法二：通过管道执行（推荐远程脚本使用） curl -fsSL https://xy-update.zhinianboke.com/deploy.sh | sed 's/\r$//' | bash

附件地址

附件为源码，详细文档请看源码里说明。

[CommShow]

通过网盘分享的文件：闲鱼自动回复管理系统.zip
链接: https://pan.baidu.com/s/1DiUuzSGlwKhZDFAnJZ9ITQ?pwd=s8ve 提取码: s8ve 复制这段内容后打开百度网盘手机App，操作更方便哦

[/CommShow]

海螺系列云上城搭建教程（海螺系列通用教程）

Tue, 26 May 2026 16:28:02 +0800

海螺系列云上城视频搭建教程，海螺系列通用，同时也适用于海螺369源码搭建。

一、搭建要求

1.环境要求

1-1、系统Windows Server 2008 R2 x64位；
1-2、MYSQL
1-3、NET4.5；
1-4、IIS7；

2.服务器要求

硬件	测试要求	运营要求
CPU	CPU4核	CPU8核
内存	内存8G	内存16G
带宽	5Mbp以上	20Mbp以上
硬盘	D盘50G以上	D盘100G以上

3.使用工具

3-1、数据库管理工具（Navicat premium）；
3-2、常用运行库（MSVBCRT.AIO）；
3-3、文本编辑工具（notepad++）；
3-4、Visual Studio 2017；

注意事项：关闭服务器防火墙或服务器有安全组的端口全开。

二、搭建教程：

三、海螺源码：

海螺电玩全套源码

四、附件截图：

五、教程参数

教程名称：	海螺系列云上城搭建教程（海螺系列通用教程）
文件格式：	mp4
视频时长:	00:45:17
文件大小:	600M
视频截图:	有
搭建难度：	⭐⭐⭐⭐

六、附件地址

附件为搬砖教程，勿信广告!

Z-Blog博客侧边栏显示分类排行榜插件

Thu, 21 May 2026 13:58:00 +0800

Z-Blog ZBLOG应用中心没有这种排行榜插件，所以老编写了一个，独一份，分享给有SEO优化需求的人。

侧边栏分类排行榜特点

针对非首页，显示当前文章页所属分类的文章排行榜。（如文章所属分类为搭建教程，就在侧边栏指定位置显示搭建教程阅读量前10的文章排行）
根据当前页面文章分类不同，显示不同排行榜，增加页面多样性，对SEO友好。
安装简单，三步就可完成。

安装方法：

１、文件上传

文件上传解压到Z-Blog博客插件指定安装目录/zb_users/plugin

２、安装启动

在你的网站后台启动插件即可

３、放置模块

把生成的老吴排行榜模块拖动到指定的分类目录下，就可以了，正常默认第一个是首页的，下面那些全拖进去

使用说明：

1. 安装插件后，请到 后台 -> 模块管理 中找到"分类排行榜"模块

2. 将模块拖拽到右侧的侧边栏位置，点击"保存设置"

3. 访问文章页面或分类页面，模块会自动显示当前分类下的阅读量排行

总结

具体效果看本站即可，本Z-Blog PHP插件插件开源无加密，可自行二开。

插件地址：

附件为插件源码，目前版本：老吴文章分类排行榜V3.0

仿来客PHP在线客服系统源码（H5网页客服）

Mon, 18 May 2026 16:40:02 +0800

PHP在线客服系统源码（H5网页客服源码），这个是仿来客二开版本，不需要一键安装，改数据库密码就能用，开源去后门，小编一直在用的运营级客服系统！

独家版本：

修复已读和头像显示在线问题
重新整理，已经全部改好参数，替换域名、IP就能用。
完美去授权后门

站长亲自打包，演示地址：在线客服

后台地址：

1、客服、主席接待地址

用来接待聊天的
http://你域名/admin/login/index/business_id/1.html
账号：customer
密码：aa112233

2、客服管理地址

用户管理客服的不是聊天的，可以新增客服
http://你域名/platform/passport/login.html
账号：adminsup
密码：aa112233

搭建方法：

1、替换域名IP

源码不需要安装
源码批量替换123.com为自己域名就可以
再改一次数据库参数就行，其它不需要修改
数据库替换118.195.136.80为自己IP

２、站点配置添加：

location /app{
proxy_pass http://127.0.0.1:456;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header X-Real-IP $remote_addr;
}

３、宝塔防火墙配置

开启2080，9090和456端口

4、修改数据库参数

址址：kefu\config\database.php

5、加入到计划任务

网站根目录下：

crontab -e

回车，输入

:wq

回车

6、执行开机启动计划

网站根目录下：

sh init.sh

7、启动服务

ymwl_pusher目录下：

php start.php restart -d

完整教程：

PHP在线客服源码网站在线客服系统，支持APP小程序公众号二维码聊天(来客DIY6.0.3)

功能强大，总体不错，很多人在找的源码，内附详细搭建教程

源码地址：

防止 SSH 暴力破解之宝塔篇

Fri, 15 May 2026 15:53:34 +0800

什么是 SSH 暴力破解？

SSH 暴力破解是一种网络攻击方式，说白了就是网络上的那些坏蛋，专门用那种全自动的脚本程序，搁那儿不停的瞎猜你的服务器账号和密码。他就是想瞎猫碰上死耗子，一旦要是把密码给蒙对了，完了，你家服务器的控制权直接就变成他的了。

安全加固方法

建议加装：fail2ba，以下是部署方法！

1、登陆宝塔面板

在宝塔面板左边菜单栏点开“终端”：

2、安装 fail2ban

yum install -y fail2ban

3、配置 SSH 防护（全部复制）

cat > /etc/fail2ban/jail.local << 'EOF'
[sshd]
enabled = true
port = ssh
filter = sshd
logpath = /var/log/secure
maxretry = 3
bantime = 3600
findtime = 600
EOF

参数解释：

监控 /var/log/secure 日志文件；
发现同一个 IP 在 600 秒（10分钟）内失败 3 次；
自动用防火墙封锁该 IP 3600 秒（1小时）；

这样攻击者尝试 3 次失败后就会被封，无法继续爆破。

4、启动并设置开机自启

systemctl enable --now fail2ban

提示：

查看运行状态

fail2ban-client status sshd

总结

fail2ban只推荐Nginx CentOS系统，理论上和宝塔的防火墙安全工具不冲突，因为工作原理不同，如果有冲突！

卸载fail2ban：

1、停止fail2ban

sudo systemctl stop fail2ban

2、禁止开机自启

sudo systemctl disable fail2ban

3、卸载fail2ban

sudo yum remove fail2ban

4、检查服务状态（应显示未找到）

sudo systemctl status fail2ban

如果卸载后 SSH 还是无法连接，可能是防火墙规则残留导致，重启一下防火墙就可以。

END！！！

老吴搭建教程

728电玩全套源码

搭建环境

服务器要求

附件截图

附件地址

MCP 原理及 Java 开发指南

为什么需要 MCP？

基本概念

关键术语

分层架构

传输机制

Java Spring AI 集成实践

POM 依赖

配置示例 `application.properties`

暴露 Tool

启动服务

在 MCP client 中配置 mcp.setting

使用 MCP！

说明

完整配置示例

MCP Client 配置与使用

Claude Desktop 配置

Cursor IDE 配置

Cline/Continue 配置

实际使用示例

最佳实践

安全考虑

性能优化

错误处理

监控与日志

典型应用场景

1. IDE 智能助手

2. 企业数据分析

3. 文档生成与管理

4. DevOps 自动化

生态系统与工具

官方工具

社区服务器

客户端支持

常见问题

未来展望

即将到来的特性

技术演进方向

生态发展

参考资源

官方资源

Spring AI 相关

技术规范

社区资源

相关项目

Agent 原理

引言：从 ChatGPT 到 Agent

一、什么是 Agent？

二、为什么需要 Agent？

三、通用 Agent 架构与运行循环

四、Agent 常见范式总览

五、`agent-all-in-one` 中的四种典型 Agent 范式

5.1 ReAct 范式：推理 + 行动

5.2 Plan-and-Execute 范式：先规划，再执行

5.3 Supervisor Multi-Agent 范式：多智能体协作

5.4 Reflection 范式：反思与自我改进

六、Agent 相关经典论文 / 代表性工作

6.1 工具增强与推理（Tool-augmented Reasoning）

6.2 反思与自我改进（Reflection / Self-Refine）

6.3 规划、搜索与决策（Planning / Search）

6.4 多智能体与长期任务（Multi-Agent / Long-horizon Agents）

七、如何选择和实践这些 Agent 范式？

小结

Skill：让 Agent 变得可复用、可控、可演进

为什么要把“提示词经验”升级成 `Skill`

一、`Skill` 是什么

1.1 一句话定义：`Skill` 解决了什么问题

1.2 `Skill` 的组成：说明、契约、边界、失败处理

1.3 一张图看懂：`Skill` 的“可验收执行链”

1.4 `Skill` 的颗粒度：什么时候拆，什么时候合

二、为什么需要 `Skill`

2.1 复用：把个人经验变成团队资产

2.2 可控：让结果稳定，过程可解释

2.3 降低上下文膨胀：按需注入，而不是永久塞进系统提示词

执行脚本报 `/bin/bash^M: 坏的解释器`？