老吴搭建教程

AIKE智能PHP在线客服系统

Tue, 28 Jul 2026 16:38:46 +0800

AIKE 智能客服系统是一款面向全行业的企业级在线客服平台，系统由PHP Web 应用、实时推送、知识库与可选向量检索组成，支持 Nginx 反代与 HTTPS/WSS。

一、产品定位

AIKE 是面向全行业的企业级 AI 在线客服平台，融合大模型、知识库与实时通讯，支持私有化部署与 SaaS 多商户、多客服模式，支持售前意向咨询、售后工单及插件市场功能扩展。

适用对象：

适合所有行业，独立部署对服务器要求不高，尤其适合预算有限小微企业及超级个体
需要 7x24 智能接待、及要求多语言自动翻译聊天信息的海外独立站团队
需要PHP开源客服系统做二次开发的技术个人及工作室

二、核心能力

基础能力：

AI 智能回复 - 7*24小时在线
可接入第三方Agent智能体
多语言自动翻译
自动进化
支持后台多语言
可嵌入任意网站 - 同时支持桌面与移动端
系统支持私有化部署与多商户模式
多行业AI预设包 - 开箱即用

能力扩展：

插件市场-能力扩展，可定制功能插件

三、源码地址

附件为标准版（单域名），演示地址：AIKE 智能客服 — 产品白皮书

AIKE智能PHP在线客服系统安装教程

Thu, 23 Jul 2026 17:27:15 +0800

本AIKE智能PHP在线客服系统安装教程从零部署本系统所需的**环境要求**、**Web 安装向导**、**安装后必改配置文件**、**相关服务启动**及**验收检查**。演示地址：AIKE智能PHP在线客服系统

## 一、系统组成

PHP Web 应用：public/` 为网站根目录
实时推送服务：`aike_pusher/`（Workerman，WebSocket + HTTP API）
数据库结构：install/data.sql`（安装向导自动导入）
向量检索（可选）：知识库导入插件依赖 Qdrant；**一键安装：`bash install_qdrant.sh`**

## 二、环境要求

### 2.1 服务器

- **操作系统**：Linux（推荐）
- **PHP**：推荐 7.3+
- **MySQL**：5.6+，字符集 **utf8mb4**

### 2.2 PHP 扩展（安装向导会检测）

扩展名	主要用途
mbstring	多字节字符串
gd	图片处理
curl	HTTP 请求、AI 接口
pdo_mysql	数据库

建议额外启用：`json`、`openssl`、`fileinfo`、`zip`。

### 2.3 目录写权限

以下目录需对 Web 运行用户可写：

```
config/
application/extra/
public/
public/upload/
runtime/
public/assets/front/
public/assets/layer/
```

### 2.4 端口规划

端口	默认值	说明
HTTP/HTTPS	80 / 443	网站访问
WebSocket（`wport`）	456	访客端 / 客服端实时消息（`aike_pusher` 监听）
Pusher API（`aport`）	2080	PHP 后端与推送服务通讯（建议仅本机或内网）
Qdrant HTTP	6333	向量检索（可选）
Qdrant gRPC	6334	向量检索（可选，SDK 直连时用）

> **HTTPS 站点**：`whost` 建议填 `wss://你的域名`，由 Nginx 反代到本机 `456`；`wport` 填 **443**（对外）或 **456**（直连），须与 Nginx / 防火墙配置一致。

## 三、部署教程

### 3.1 上传代码

将项目上传到服务器，例如：

/www/wwwroot/your-domain.com/

网站根目录指向 **`public`**，不要将整个项目根目录直接暴露给外网。

### 3.2 创建数据库

宝塔创建数据库

安装向导也可自动创建数据库。

### 3.3 开始安装

- 若 `public/index.php` **已存在**，安装向导会提示「已经安装成功」。

重新安装：https://你的域名/install.php

修改数据库参数和管理账号即可，其它不懂的建议默认。

### 3.4 安装成功：

### 3.5总后台

https://你的域名/platform/passport/login.html

账号：安装时创建

密码：安装时创建

### 3.6 客服后台

总后台创建客服账号：

登陆客服后台：

https://你的域名/admin/login/index/business_id/1.html

## 四、Web 服务器配置

### Nginx配置

站点配置文件后面加上：

    access_log  /dev/null;
    error_log  /www/wwwlogs/ai.lw50.com.error.log;
        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;
        proxy_read_timeout 3600s;
        }

若前端直连 `ws://IP:456`，需在安全组放行 **456** 端口。

### Linux伪静态

# ========== ThinkPHP 5 短期加固 + 原有静态规则 ==========

# 1. 禁止访问敏感目录（在原 runtime|application 基础上扩展）
location ~* ^/(runtime|application|config|thinkphp|vendor|extend)/ {
    return 403;
}

# 2. 禁止访问示例/调试目录
location ~* ^/assets/libs/myeditor/examples/ {
    return 403;
}

# 3. 禁止 uploads、assets 下直接执行 PHP
location ~* ^/upload/.*\.php$ {
    return 403;
}
location ~* ^/assets/.*\.php$ {
    return 403;
}

# 4. 拦截 ThinkPHP 5 常见 exploit 查询串
# 只拦截 s= 路由参数中的 exploit，勿扫描整段 query_string（会误伤 ?code= token）
if ($arg_s ~* "(invokefunction|call_user_func|call_user_func_array|pearcmd|config-create)") {
    return 403;
}
if ($arg_s ~* "think(%2f|%5c|/)") {
    return 403;
}
if ($arg_s ~* "(php://|phar://)") {
    return 403;
}
if ($arg_s ~* "(\.\.|%2e%2e)") {
    return 403;
}

# 5. 原有伪静态（保持不变）
location / {
    if (!-e $request_filename) {
        rewrite ^(.*)$ /index.php?s=$1 last;
    }
}

## 五、服务启动说明

### 禁用函数

在宝塔：软件商店 → PHP 7.3 → 禁用函数，删掉与进程控制相关的项，至少包括：

pcntl_fork、pcntl_waitpid、pcntl_wait、pcntl_signal、pcntl_signal_dispatch、pcntl_alarm、pcntl_exec 以及列表里其它 pcntl_*

### 修改app_secrets.php

看图修改WSS、http、端口

### 实时推送 `aike_pusher`（必须）

cd /www/wwwroot/你的目录/aike_pusher

php start.php restart -d

常用指令：

php start.php start # 前台调试
php start.php start -d # 后台守护
php start.php stop # 停止
php start.php reload # 平滑重启
php start.php status # 状态

### 进程守护

`run.sh` 每分钟检测 Workerman，未运行则启动：

cd /www/wwwroot/你的目录/
sudo bash run.sh

###添加计划任务

cd /www/wwwroot/你的目录/
sudo bash init.sh

### 前端验证

### 安装 Qdrant 向量数据库

启用知识库**语义检索 / 向量化**时需要。项目已提供**一键安装脚本**，请在**项目根目录**执行（与 `public/` 同级）：

cd /www/wwwroot/你的目录
sudo bash install_qdrant.sh

> 若系统尚未安装 Docker，脚本会先自动安装 Docker，再部署 Qdrant；Docker 已就绪则直接进入 Qdrant 安装。

### 前置条件

**Linux** 服务器（脚本不支持 Windows 直接运行）
2. 未安装 Docker 时，脚本会**自动安装并启动 Docker**（需 **root**：`sudo bash install_qdrant.sh`）
3. 已安装且 Docker 服务正常时，**跳过 Docker 步骤**，直接安装 Qdrant
4. 本机可访问 `curl`（健康检查用；安装 Docker 时脚本会尝试自动安装 curl）

### 安装后验证

bash scripts/qdrant/status.sh

或手动检查：

curl http://127.0.0.1:6333/
curl http://127.0.0.1:6333/readyz
docker ps | grep wolive-qdrant

输出 `Qdrant installed successfully` 且 REST API 为 `http://127.0.0.1:6333` 即表示就绪：

### 安装失败：Docker iptables 问题

部分云服务器 / CentOS 会出现端口映射失败，脚本会自动尝试 **host 网络模式**。若仍失败，以 root 执行修复后重试：

```bash
bash scripts/qdrant/fix_docker_iptables.sh
bash install_qdrant.sh
```

### 在系统中启用向量检索

确认 `bash scripts/qdrant/status.sh` 显示 **Health : OK**
1. 登录商户后台 → **知识库导入 / 向量设置**：
- 开启 **向量检索**
- `qdrant_url`：`http://127.0.0.1:6333`
- 填写 Embedding API（URL、Key、模型）
2. 导入 FAQ 或页面后执行向量化
3. 在 **AI 智能回复设置** 中确认已启用知识库召回

### Qdrant 常见问题

现象	处理
`Docker not found`	使用 `sudo bash install_qdrant.sh` 以自动安装 Docker
`Docker auto-install requires root`	加 `sudo` 后重试
`Docker daemon not running`	脚本会尝试 `systemctl start docker`；失败则手动检查 Docker 服务
健康检查超时	`docker logs wolive-qdrant`，或执行 `fix_docker_iptables.sh` 后重装
向量化失败	检查后台 Embedding API Key，与 Qdrant 无关时先排除 API 问题

### 手动执行（调试）

```bash
cd /www/wwwroot/your-domain.com
# 指定商户 business_id=1；-f 忽略后台「蒸馏开关=关」
php think ai:distill-human -b 1
php think ai:distill-human -b 1 -f
# 增量同步（页面 QA + 向量）
php think ai:auto-sync -b 1
php think ai:auto-sync -b 1 -f
```
成功时终端会输出 `scanned` / `pairs` / `inserted` 等统计。

### 后台开关（必配）

Cron 只负责**按时触发**；各商户是否在任务内真正执行，由后台 **AI 智能回复设置 → 知识进化与定时任务** 控制：

开关	建议	作用
人工聊天蒸馏	开	写入「AI进化池 → 人工聊天学习候选」
仅人工回复	开	排除 AI 自动回复与常见问题预设
定时增量同步	按需	从已同步页面抽 QA、维护向量
同步向量库	开（若已装 Qdrant）	FAQ 增量写入 Qdrant
同步含蒸馏	关	auto-sync 内再跑蒸馏（与 hourly 重复，一般关）

阈值（质量分、出现次数、更新 FAQ 次数等）也在同一区块配置，保存后写入 `wolive_ai_config.distill_config_json` / `auto_sync_json`。

> **注意：** 仅注册 cron、未在后台开启对应开关时，任务会跳过该商户。向量 FAQ 直答依赖 **7.2 Qdrant** 与后台 Embedding 配置。

## 六、自动化说明

“自动 vs 人工”环节：

环节	是否自动
cron 扫描聊天、写候选	✅
cron 页面 QA、向量同步	✅（需开开关）
高质量新问题自动入 FAQ	✅（进化池开关 + 阈值）
同问不同答更新已有 FAQ	❌ 需人工点「更新 FAQ」
意图关键词应用	❌ 需人工勾选并选意图
未命中 → 加 FAQ	❌ 需人工确认

## 七、常见问题

### Q1：SQL 导入失败？

检查 MySQL 版本、账号权限、`install/data.sql` 是否完整，查看安装页报错详情。

### Q2：消息不实时？

`php start.php status` 确认 pusher 运行
2. `app_secrets.php` 中 `app_key` / `app_secret` / `aport` / `websocket_port` 正确（改完需重启 pusher）
3. `whost`、`wport`（对外）与 `websocket_port`（监听，默认 456）与 Nginx / 防火墙一致
4. 浏览器控制台查看 WebSocket 连接

###Q3：`Missing application/extra/app_secrets.php`？

重新安装，或从 `app_secrets.example.php` 复制并填写（含 `websocket_port`、`aport`）。

### Q4：HTTPS 下 WebSocket 失败？

`whost` 用 `wss://域名`，Nginx `/app` 反代到 `127.0.0.1:456`，或配置 **6.4** SSL 直连

### Q5：向量检索无结果？

确认已执行 `bash install_qdrant.sh` 且 `status.sh` 正常，后台 `qdrant_url` 为 `http://127.0.0.1:6333`，Embedding API 可用并已执行向量化。

### Q6：AI 进化 cron 不跑？

`crontab -l` 是否含 `ai:distill-human`、`ai:auto-sync`（无则 `sudo bash init.sh`）
2. 后台 **知识进化与定时任务** 对应开关是否开启
3. 查看 `runtime/log/ai_distill_cron.log`、`ai_auto_sync.log` 是否有 PHP 报错
4. 手动 `php think ai:distill-human -b 商户ID -f` 验证 CLI 是否正常

### Q7：蒸馏有候选但不会自动进 FAQ？

自动入库仅针对 **FAQ 中尚不存在的新问题**，且需同时满足：进化池开启 **高质量自动入 FAQ**、质量分 ≥ 阈值、出现次数 ≥ 阈值。同问不同答只会标「可更新 FAQ」，须人工确认。

END！！！

12条规则能将AI编程错误率降至3%

Tue, 14 Jul 2026 22:49:01 +0800

四大原则

四大原则说是能将AI编程错误率从41%降至11%。原文地址：AI 编程的“紧箍咒”：CLAUDE.md 霸榜 GitHub，7万程序员疯抄作业

减少LLM编码常见错误的行为准则。根据需要与项目特定说明合并。

权衡：这些指导原则倾向于谨慎而非速度。对于琐碎的任务，请自行判断。

1. 编码前先思考

不要妄下断言。不要掩饰困惑。坦诚地权衡利弊。

实施前：

请明确陈述您的假设。如有疑问，请提出。
如果存在多种解释，请将它们提出来——不要默默地做出选择。
如果存在更简单的方法，请提出来。必要时要坚持己见。
如果有什么不清楚的地方，停下来。说出让你困惑的地方。然后提问。

2. 简单至上

用最少的代码解决问题。不要进行任何推测。

没有超出要求的功能。
不为一次性代码进行抽象。
没有提供任何未要求的“灵活性”或“可配置性”。
对于不可能出现的情况，不进行错误处理。
如果你写了 200 行，而 50 行就可以写完，那就重写。

问问自己：“一位资深工程师会认为这过于复杂吗？” 如果答案是肯定的，那就简化它。

3. 手术改变

只碰你必须碰的东西。只收拾你自己的烂摊子。

编辑现有代码时：

不要“改进”相邻的代码、注释或格式。
不要重构没有损坏的代码。
即使你的做法不同，也要保持与现有风格一致。
如果你发现无关的死代码，请指出来——不要删除它。

当你的更改创建了孤立文件时：

删除因您的修改而不再使用的导入项/变量/函数。
除非被要求，否则不要删除已有的无效代码。

测试要求：每一行修改后的代码都应该直接追溯到用户的请求。

4. 目标驱动型执行

定义成功标准。循环直至验证通过。

将任务转化为可验证的目标：

“添加验证”→“编写针对无效输入的测试，并确保它们都能通过”
“修复漏洞”→“编写一个能够重现该漏洞的测试，然后使其通过”。
“重构 X” → “确保重构前后测试均通过”

对于多步骤任务，请简要说明计划：

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

明确的成功标准能让你独立循环迭代。而模糊的标准（“只要能行就行”）则需要不断澄清。

如果以下情况发生，则这些指导原则是有效的：差异中不必要的更改减少，由于过于复杂而导致的重写减少，并且在实施之前而不是在出错之后提出澄清问题。

下载原文档

8条进阶规则

在4条核心法则的基础上，开发者通过实测又增加了8条进阶规则，进一步提升了AI编程可靠性，号称能将错误率降至3%。

法则：	核心要求：
只做判断，不写死逻辑	避免硬编码，保持代码灵活性。
严格控制Token消耗	用最精炼的方式完成任务。
代码冲突时不妥协	遇到冲突应提示，而非擅自修改。
先读懂源码再动手	确保理解现有代码结构
拒绝假测试	测试用例必须能真正验证功能。
分步设置检查点	将大任务分解，逐步验证。
严格遵守代码风格	保持与现有代码风格一致。
遇到问题绝不隐瞒	发现无法解决的问题时必须报告。

...

本地pdf、Word、ppt文档转MarkItDown格式工具：MarkItDown

Wed, 08 Jul 2026 08:46:03 +0800

MarkItDown 原是微软官方的一个轻量级的 Python 工具，用于将各种本地文档转换为 Markdown 格式，以便在 LLM 和结构化知识提取中使用，侧重于保留文档的重要结构和内容（包括标题、列表、表格、链接等）。主要用于方便文本分析工具，主流语言学习模型（LLM），如 OpenAI、deepseek，能够很好原生“理解”Markdown这种格式。

支持格式：

PDF
PowerPoint
Word
Excel
Images (EXIF metadata and OCR)
Audio (EXIF metadata and speech transcription)
HTML
Text-based formats (CSV, JSON, XML)
ZIP files (iterates over contents)
Youtube URLs
EPubs

工具说明

本MarkItDown工具是老吴站修改过的版本，并增加了图形操作面板，看下图，可以手动选择要转换的文档及选择保存目录，对新手友好！

本地安装方法

1、进入项目目录

文章附件获取源码，解压后打开CMD窗口，CD到文件根目录。

2、可编辑模式（Editable Mode）安装

pip install -e 'packages/markitdown[all]'

-e 参数表示以“可编辑模式”安装，这意味着你在源码中所做的任何修改都会立即反映到你的环境中，非常适合开发调试。
[all] 表示安装所有处理格式（如 PDF、Word、PPT 等）所需的完整依赖。如：pip install 'markitdown[pdf, docx, pptx]'

使用方法

安装好后，双击启动转换器.bat即可。

工具地址

[CommShow]

原版本地址：https://github.com/microsoft/markitdown

老吴站版本：https://pan.baidu.com/s/1ZfKrsBUgcOprEv7nCWG1RQ?pwd=vsc4

[/CommShow]

MySQL 8.0.46部署工具

Thu, 25 Jun 2026 14:40:52 +0800

windows下单独安装MySQL到新手可能不太友好，有了这个MySQL 8.0.46安装工具就方便多了。MySQL 8.0.46是8.0 系列的最后一个维护版本(于 2026 年 4 月 21 日发布)，所以这个版本应该是比较稳定的。

工具功能：

调整配置文件my. ini
初始化MySQL(会清空数据)
安装系统服务(默认类型自动)
系统服务：启动、停止、卸载

该程序需要以管理员身份执行。

工具参数：

工具名称：	MySQL 8.0.46部署工具
运行系统：	windows
文件格式：	exe
文件大小:	1M
工具截图:	有

工具地址：

[CommShow]

MySQL8.0.46官方下载链接：https://dev.mysql.com/get/Downloads/MySQL-8.0/mysql-8.0.46-winx64.zip
MySQL自制部署工具下载：https://liyitong.lanzout.com/i46C23sx3yuh

[/CommShow]

Graphify：如何将代码库与文档一键转化为可查询的知识图谱？

Mon, 22 Jun 2026 08:44:12 +0800

这是一个代码知识图谱生成工具（AI 编程助手）。该工具在GitHub上有70+K星标，这玩意能将项目中任何包含代码、SQL模式、R脚本、shell脚本、文档、论文、图像或视频的文件夹转换为可查询的知识图谱，自动发现模块间的依赖关系和隐藏连接。

如何让 AI 更好地阅读我的项目？

它能把你项目里的代码整成一份能点能拽的知识图谱。并且自动扒拉出模块之间的依赖关系、隐藏连接。
它不光告诉你这段代码是“干哈的”，还能给你解释“为啥非得这么设计”。
这基本就相当于给AI装了个“项目大脑”，属于是降维打击了。
让AI理解项目的时候，不再跟没头苍蝇似的瞎翻文件。
只要瞅一眼那个图谱，整个项目的结构立马就门儿清。
同时它跟Claude Code、Codex这些主流工具都能搭上线，兼容性挺到位。

总结

对程序员来说，不管是刚接手一个陌生项目，还是想快速摸清老项目的底细，Graphify能帮助 AI 更好地理解复杂代码中的逻辑关系，这玩意儿都贼拉实用。

项目地址

Github项目：graphify

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 的路上了：接下来只差把它们“模块化、契约化、可验收化”。

下载文档