我正在开发 DocFlow，它是一个完整的 AI 全栈协同文档平台。该项目融合了多个技术栈，包括基于 Tiptap 的富文本编辑器、NestJs 后端服务、AI 集成功能和实时协作。在开发过程中，我积累了丰富的实战经验，涵盖了 Tiptap 的深度定制、性能优化和协作功能的实现等核心难点。

如果你对 AI 全栈开发、Tiptap 富文本编辑器定制或 DocFlow 项目的完整技术方案感兴趣，欢迎加我微信 yunmz777 进行私聊咨询，获取详细的技术分享和最佳实践。 很多人第一次打开 OpenClaw，会下意识把它当成"接在微信或 Slack 上的聊天机器人"。这种理解只对了一半。从架构上看，OpenClaw 更像一个网关：它站在你和一堆能力之间，负责路由、鉴权、记忆和工具调用。真正决定你能做多少事的，不是对话框有多好看，而是背后接了多少"身体"——也就是 Skills。

MinIO 的开源仓库已经被正式归档，不再维护。

一个时代结束了，但开源不会那么容易死去。

我创建了一个 MinIO 分支，恢复管理控制台，重建二进制分发管道，让它重新活过来。

如果你正在运行 MinIO，只需要将 minio/minio 替换为 pgsty/minio 即可。

其他一切保持不变（CVE 已修复，管理控制台 GUI 也回来了）。

死亡证明

2025 年 12 月 3 日，MinIO 在 GitHub 上宣布进入 "维护模式"。我在 MinIO 已死 一文中写过这件事。

2026 年 2 月 12 日，MinIO 又把仓库状态从 "维护模式" 更新为 "不再维护"，随后直接将仓库归档。

仓库被设为只读，不再接受 PR、Issue 或任何形式的贡献。一个拥有 6 万星标、超过 10 亿次 Docker 拉取的项目，就这样变成了一块数字墓碑。

如果说 2025 年 12 月是临床死亡，那么 2026 年 2 月的这次提交就是正式的死亡证明。

2026 年 2 月 14 日，一篇广为流传的文章《MinIO 如何从开源宠儿变成警示故事》给出了完整的时间线：MinIO如何从开源宠儿变成警示故事。

Percona 创始人 Peter Zaitsev 也在 LinkedIn 上，对开源基础设施的可持续性提出了担忧。

国际社区的共识很明确：

MinIO 完了。

回顾过去几年的时间线，这并不是一次突然的事故，而是一个缓慢、有意、循序渐进的关停过程：

日期	事件	性质
2021-05	Apache 2.0 → AGPL v3	许可证变更
2022-07	对 Nutanix 采取法律行动	许可证执行
2023-03	对 Weka 采取法律行动	许可证执行
2025-05	从 CE 中移除管理控制台	功能限制
2025-10	停止二进制和 Docker 分发	供应链切断
2025-12	宣布维护模式	生命周期结束信号
2026-02	仓库归档，不再维护	项目结束

一家估值 10 亿美元、共融资 1.26 亿美元的公司，用了整整五年时间，有条不紊地拆解了自己一手建立的开源生态系统。

但开源永存

通常到这里，故事就结束了，大家集体叹口气，然后继续各奔东西。

但我想讲一个不太一样的故事。这不是讣告，而是复活。

MinIO 公司可以归档一个仓库，但他们无法归档 AGPL 授予社区的权利。

讽刺的是，AGPL 本来是 MinIO 自己选的。他们从 Apache 2.0 切换到 AGPL，是为了在和 Nutanix、Weka 的纠纷中增加筹码，在保留 "开源" 标签的同时，把许可证当成法律武器。但开源许可证是一把双刃剑，同样的许可证也确保了社区有权分叉。

一旦代码以 AGPL 形式发布，许可证就不可撤销。你可以把仓库设成只读，但不能收回已经授予社区的权利。

这正是开源许可证设计的精妙之处，公司可以放弃一个项目，但不能带走那份代码。

所以，MinIO 已死，但 MinIO 也可以重生。

当然，分叉本身是最简单的部分。任何人都可以点一下 Fork 按钮。

真正的问题不是 "能不能分叉"，而是 "有没有人愿意、也有能力，把它当作生产系统的一部分长期维护下去"。

我为什么要这么做？

一开始，我并没有打算接下这个担子。MinIO 进入维护模式之后，我等了几周，希望能看到有社区成员站出来。

但我始终没有等到那个人，于是只好自己上。

先说一点背景，我在维护 Pigsty，这是一个带电池的 PostgreSQL 发行版，内置了 460 多个扩展，并为 14 个 Linux 发行版 做了交叉构建。我还维护了 290 个 PG 扩展、若干 PG 分支 和数十个 Go 项目（Victoria、Prometheus 等）在所有主流平台上的打包。在这样一条流水线上再接一个项目，说实话压力不算太大。

我对 MinIO 也很熟。早在 2018 年，我们就在探探内部运行了一个 MinIO 分支（当时还是 Apache 2.0），托管了大约 25 PB 的数据，是当时中国最早、规模也最大的一批 MinIO 部署之一。

更重要的是，MinIO 也是 Pigsty 中的一个可选模块，很多用户在生产环境里，把它作为 PostgreSQL 的默认备份仓库。

我们确实认真评估过几个替代方案，但没有任何一个，能在现有工作流上做到对 MinIO 的平滑替换。

更多配置细节可以参考：pigsty.io/docs/minio/…

我们自己就在用 MinIO，所以让这条供应链活下去，对我们来说根本不是选项，而是硬性要求。

早在 2025 年 12 月，MinIO 刚宣布进入维护模式时，我就已经构建了包含 CVE 修复 的二进制包，并第一时间在生产中完成了切换。

我们已经做了什么

截至今天，我们已经完成了三件事。

1. 恢复管理控制台

这大概是最让社区糟心的一次改动。

2025 年 5 月，MinIO 从社区版中移除了完整的管理控制台，只留下一款简陋的对象浏览器。

用户管理、存储桶策略、访问控制、生命周期管理，这些东西是一夜之间统统消失的。想要它们回来？唯一途径是买企业版（大约十万美元起步）。

我们把它完整地带回来了。

更有意思的是，这甚至不需要任何逆向工程。

你只需要把 minio/console 子模块恢复到之前的版本。

他们当时的做法，是通过替换依赖版本，用一个阉割版控制台替换了完整版。真正的代码始终都还在那儿。

可以在这里看到具体的改动： github.com/pgsty/minio…

我们现在已经把完整控制台放回来了。

2. 重建二进制分发

2025 年 10 月，MinIO 停止分发预构建的二进制文件和 Docker 镜像，只保留源码。对用户的官方回答只有一句："使用 go install 自己构建"。

但对于绝大多数用户来说，开源软件的价值远远不止是一份源码副本，真正关键的是稳定可靠的供应链。

你需要的是可以直接塞进 Dockerfile、Ansible playbook 或 CI 流水线里的稳定工件，而不是在每次部署前，都被迫先装一套 Go 编译器。

所以我们重建了分发体系：

项目	说明
Docker 镜像	pgsty/minio 已在 Docker Hub 上线，直接运行 docker pull pgsty/minio 即可使用。
RPM、DEB 包	为主流 Linux 发行版构建，遵循 MinIO 原本的打包规范。
自动化构建流水线	在 GitHub 上提供完全自动化的构建流程，持续产出稳定的构建工件。

如果你现在使用的是 Docker，只需要把 minio/minio 换成 pgsty/minio。

对于原生 Linux 安装，可以从 GitHub Release 页面获取 RPM、DEB 包。

你也可以使用 pig（PG 扩展包管理器）进行一键安装，或者配置 pigsty-infra APT、DNF 仓库，从中直接安装：

curl https://repo.pigsty.io/pig | bash
pig repo add infra -u
pig install minio

装完之后，它就像你熟悉的那份 MinIO 一样工作。

3. 恢复社区版文档

MinIO 的官方文档同样在慢慢 "消失"。不少旧链接已经开始被重定向到它们的新商业产品 AIStor。

我们分叉了 minio/docs，修复了损坏的链接，恢复了被删掉的控制台文档，并把整个站点部署在 这里。

文档仍然沿用原始项目的 CC Attribution 4.0 许可证，并在此基础上持续维护。

承诺

有几件事值得提前说清楚，以免大家产生不必要的期待。

没有新功能，只保证供应链连续性

作为一款 S3 兼容的对象存储，MinIO 已经算是功能完整了，它更像是一款 "写完了" 的软件。

它现在不缺新功能，真正缺的是一个稳定、可靠、长期可用的构建。

我这边已经有 PostgreSQL 来承担那些更复杂的活儿，所以我并不需要什么 S3 表、S3 向量之类的附加功能。一个稳定扎实的 S3 核心，就是我全部的诉求。

我们现在做的事情很简单：让你始终能拿到一份可用、完整的 MinIO 二进制，其中既包含管理控制台，也包含最新的安全修复。

RPM、DEB、Docker 镜像，都会通过自动化流水线持续构建出来，并与现有的 MinIO 部署保持兼容。

在法律和技术允许的边界内，我们会最大程度保留原有的 MinIO 命名和行为。

这是生产构建，不是归档镜像

我们自己就在生产环境中运行这些构建，而且已经 "吃狗粮" 吃了三个月。

一旦有东西出问题，我们会第一时间感受到，并尽快修复。

我搭建这套东西，首要目的是为了 Pigsty 和我们自己的使用，但我也很希望它能顺带帮到更多人。

我会跟踪 CVE，也会修 Bug

如果你在使用过程中遇到问题，欢迎到 pgsty/minio 反馈。

我会尽力修复这些问题，不过请不要把它当成商业 SLA。

考虑到 AI 编码工具大大降低了修复 Bug 的成本，而且我们明确不会往里加新功能，我相信整体维护工作量是可控的。

（你上一次见到新的 MinIO 功能更新是什么时候？）

商标确实麻烦，但有问题再一起解决

免责声明

商标声明：MinIO® 是 MinIO, Inc. 的注册商标。

本项目（pgsty/minio）是在 AGPL 许可证下独立维护的社区分支。

它与 MinIO, Inc. 没有任何关联、背书或商业关系。

本文中 "MinIO" 的使用仅指这款开源软件本身，并不暗示任何形式的商业合作。

AGPLv3 明确赋予我们分叉和分发的权利，但商标法又是另一套体系。

我们已经在各处清晰标注，这是一份由社区独立维护的构建。

如果 MinIO 公司对商标使用提出异议，我们会积极配合，完成重命名（也许会叫 "silo" 或 "stow" 之类的名字）。

在那之前，我们认为在 AGPL 分支中以描述性方式使用原始名称，是合理且有利于用户理解的。此时强行把所有 MinIO 引用全部改名，反而只会让用户更困惑。

AI 已经改变了游戏规则

你可能会问：一个人真的能扛得住这么大的项目吗？

现在已经是 2026 年了，情况和过去不一样。

AI 编码工具正在彻底改变开源维护的经济学。

借助 Claude Code、Codex 之类的工具，在复杂的 Go 项目里定位和修复 Bug 的成本，已经降低了一个数量级。

很多过去需要专职团队才能维护的大型基础设施项目，现在完全可以交给一位有经验的工程师，加上一位靠谱的 AI 副驾驶来共同完成。

在不引入新功能的前提下，维护一份 MinIO 构建，是一项可管理的工作。

真正的关键在于测试和验证。而我们已经有了完整的生产场景，可以在真实流量下持续验证它的兼容性、可靠性和安全性。

想一想，Elon 把 X（原 Twitter）的工程团队缩减到了大约 30 人，这个平台到现在还在运转。 相比之下，维护一个不再加新功能的 MinIO 分支，远没有想象中那么可怕。

这对你意味着什么

如果你只是远远围观 MinIO 的兴衰，这个故事听起来可能像一篇行业八卦。但如果你属于下面几类用户，这个分支和上面这些工作，其实都和你的日常生产环境直接相关。

• 在自建数据中心里，用 MinIO 做数据库备份和归档的团队
• 把 MinIO 部署在私有云，用来存放用户上传文件、审计日志、模型权重的 SaaS 团队
• 在多云环境里，把 MinIO 当作 S3 兼容层，用来屏蔽底层对象存储差异的基础设施平台
• 需要在离线环境、内网环境中部署 S3 存储，但又无法直接使用公有云服务的企业

对这些场景来说，MinIO 不只是一个组件名字，而是一条埋在系统最底层的供应链。一旦这条链路断掉，影响到的就不仅仅是对象存储本身，而是所有依赖它的备份、恢复、扩缩容、容灾和审计流程。

社区分支的目标，就是让这条链不断掉，让你可以像过去一样，用同一套命令行、同一套配置文件、同一套控制台，继续运转你的业务。

当然，如果你的团队已经在大规模使用公有云原生对象存储服务，或者可以轻松把工作负载迁移回 AWS S3、GCS、Azure Blob，那你完全可以把这篇文章当作一段开源史料。真正急需一条可持续供应链的，是那些长期押注在 MinIO 上、又没有简单退路的用户。

如何开始使用 pgsty/minio

如果你已经在生产里跑 MinIO，想要最小代价切换到社区分支，可以从下面几步入手。

1. 先在测试环境里起一套新的 pgsty/minio 集群，版本尽量与现网保持一致。
2. 把现有 MinIO 集群的配置文件完整复制过来，重点检查访问密钥、端点地址、挂载路径、证书配置是否一致。
3. 使用同一套客户端脚本、备份流程，在测试环境里完整跑一遍你现在依赖的关键工作流，例如数据库全量备份和增量备份、静态资源读写、日志归档等。
4. 如果你使用 Docker 或 Kubernetes，优先从镜像名入手，把 minio/minio 替换为 pgsty/minio，其余参数保持不变，验证容器生命周期和探针是否工作正常。
5. 确认测试环境跑通之后，再在生产环境采用渐进式方式替换，可以先切一小部分流量，观察一段时间，再逐步扩大范围。

整个过程中最重要的一点，是保留好回滚路径。无论是通过流量切换、还是通过 Helm 回滚，只要你能在短时间内切回旧版本，就可以放心在真实业务场景中验证新的构建。

直接分叉它

MinIO 公司可以归档一个 GitHub 仓库，但他们无法归档 6 万颗星标背后的真实需求，也无法归档 10 亿次 Docker 拉取背后的依赖拓扑。这些需求不会凭空消失，它们只会自己找到出口。

HashiCorp 的 Terraform 已经被社区分叉成 OpenTofu，而且运行得很好。相比之下，MinIO 的处境甚至更有利，因为 AGPL 对分叉比 BSL 更友好，社区分叉几乎不存在法律灰区。

公司可以放弃一个项目，但开源许可证本来就是为了确保代码不会因此一同消失。

分叉，是开源世界里最强力的咒语之一。当一家公司选择关门时，社区只需要说出那两个字，

分叉它。

参考

• MinIO已死
• MinIO已死，有替代品吗？
• 从AGPL到Apache：对Pigsty许可证变更的思考

免责声明：本文最初由 Claude 从中文版本润色并翻译成英文，此处为在中文版基础上的再整理与更新。

我正在开发 DocFlow，它是一个完整的 AI 全栈协同文档平台。该项目融合了多个技术栈，包括基于 Tiptap 的富文本编辑器、NestJs 后端服务、AI 集成功能和实时协作。在开发过程中，我积累了丰富的实战经验，涵盖了 Tiptap 的深度定制、性能优化和协作功能的实现等核心难点。

如果你对 AI 全栈开发、Tiptap 富文本编辑器定制或 DocFlow 项目的完整技术方案感兴趣，欢迎加我微信 yunmz777 进行私聊咨询，获取详细的技术分享和最佳实践。 很多人第一次打开 OpenClaw，会下意识把它当成"接在微信或 Slack 上的聊天机器人"。这种理解只对了一半。从架构上看，OpenClaw 更像一个网关：它站在你和一堆能力之间，负责路由、鉴权、记忆和工具调用。真正决定你能做多少事的，不是对话框有多好看，而是背后接了多少"身体"——也就是 Skills。

3月7日消息，腾讯面向个人用户开放了 QQ 开放平台的机器人创建权限。此前这项能力仅对企业开放，现在任何持有 QQ 账号的个人开发者都可以注册并创建自己的 QQ 机器人。配合 AI 智能体框架 OpenClaw，整个绑定流程只需不到五分钟。

注册与创建只需几分钟

打开 QQ 开放平台官网，用手机 QQ 扫码就能完成开发者账号注册，不需要填写任何企业资质或繁琐表单。

扫码登录后，点击一次"创建机器人"按钮，平台会立即为你生成一个专属的 AppID 和 AppSecret，这两个凭据就是后续与 OpenClaw 绑定的钥匙。

三条命令完成绑定

拿到 AppID 和 AppSecret 之后，切到 OpenClaw 控制台，依次执行以下三条命令：

openclaw plugins install @llvera/qqbot@latest
openclaw channels add --channel qqbot --token <你的 token>
openclaw gateway restart

第一条安装 QQ Bot 插件，第二条把你的 token 写入频道配置，第三条重启网关让配置生效。整个过程不超过五分钟。

真实上手效果

配置完成后，打开手机 QQ 直接和机器人说话就行，和普通聊天窗口没有任何区别。

问它"我现在有什么 agent"，它会把 openclaw.json 里登记的所有 Agent 及其当前状态一次列出来，还会告知各 Agent 之间的通信是否已启用。

更有意思的是，它能直接操作你本机的文件系统。让它列出桌面 video 目录里有什么文件，它会按时间分组整理成一张表格返回给你——比如 32 个 .MOV 原始视频文件，按 2024 年、2025 年 1 月……逐年分组，每个文件名和体积一目了然，总计约 51.5 GB。

如果你进一步说"帮我截第 1 秒、第 5 秒、第 10 秒、第 14 秒的画面"，它会直接调用本地工具提取视频帧，以 4K 原始分辨率（3840×2160）输出截图，保存到桌面的 frames 文件夹，然后把截图一张一张发回给你。

你说"把图片发给我，我要看"，它就把文件复制到桌面再通过 QQ 直接发送过来，不需要你去文件管理器里翻。

这些操作全程没有打开任何 App，只是在 QQ 聊天框里说了几句话。

OpenClaw 是什么

OpenClaw（曾用名 Clawdbot、Moltbot）是一款开源 AI 智能体框架，由程序员彼得·斯坦伯格（Peter Steinberger）开发，核心语言为 TypeScript，采用标志性的"蓝色龙虾"图标设计。它的 slogan 是 "The AI that actually does things"，意思是真正能干活的 AI。

与传统对话式 AI 不同，OpenClaw 不是只能回答问题的聊天机器人，而是能够执行任务的数字员工。它通过自然语言指令驱动，可在本地或私有云环境中完成文件管理、代码执行、网页抓取、API 调用等操作。

用一句话概括，它实现的是从"建议"到"执行"的跨越。

几个值得关注的细节

一个 QQ 号最多可以创建 5 个独立的 QQ 机器人。

绑定至 OpenClaw 环境后，机器人支持接收和发送 Markdown、图片、语音、文件等多种格式的消息，手机端 QQ 和桌面端 QQ 均可正常使用，不限终端。

另外，OpenClaw 的工具调用具备一定的容错能力。当某个工具不可用时，它会自动降级切换到备用工具。例如搜索插件不可用时，它会调用浏览器工具直接打开网站抓取内容，整理好再返回给你，整个过程无需人工干预。

OpenClaw 能帮自媒体人做什么

对自媒体从业者来说，OpenClaw 能覆盖的场景远不止联网搜索。从内容生产到数据复盘，它可以接管那些重复、耗时却省不了的环节。

目前能直接上手的场景包括：

• 公众号写作，从选题调研到完整初稿，按模板排版，两小时内从灵感到成品
• 小红书爆款，自动学习你的语气风格，一次给出 5 个备选标题
• 视频内容拆解，转写文字稿、提取金句字幕、生成话题标签和简介文案，自动适配多个平台
• 素材批量处理，一次处理 50 个文件，批量改名、自动归类
• 品牌合作跟进，整理合作邀约信息，不让 offer 漏掉
• 数据复盘报告，汇总阅读量和互动率，告诉你本周内容的表现和下一步方向

这些事情放在以前，要么手动一件一件做，要么需要在多个独立工具之间来回切换。现在通过自然语言指令，交给 OpenClaw 统一处理就行。

目前我正在组建 OpenClaw 中文社区，如果你也在探索用 AI 工具提效、或者想一起玩转这套工作流，欢迎添加我的微信 yunmz777，拉你进群交流。

我正在开发 DocFlow，它是一个完整的 AI 全栈协同文档平台。该项目融合了多个技术栈，包括基于 Tiptap 的富文本编辑器、NestJs 后端服务、AI 集成功能和实时协作。在开发过程中，我积累了丰富的实战经验，涵盖了 Tiptap 的深度定制、性能优化和协作功能的实现等核心难点。

如果你对 AI 全栈开发、Tiptap 富文本编辑器定制或 DocFlow 项目的完整技术方案感兴趣，欢迎加我微信 yunmz777 进行私聊咨询，获取详细的技术分享和最佳实践。 很多人第一次打开 OpenClaw，会下意识把它当成"接在微信或 Slack 上的聊天机器人"。这种理解只对了一半。从架构上看，OpenClaw 更像一个网关：它站在你和一堆能力之间，负责路由、鉴权、记忆和工具调用。真正决定你能做多少事的，不是对话框有多好看，而是背后接了多少"身体"——也就是 Skills。

在使用 Cursor 时，你会看到很多向 AI 发指令的方式：AGENTS.md、.cursor/rules/、.cursor/commands/、.cursor/skills/、.cursor/agents/（子代理）。每种方式适用场景不同，不少人会问："该用哪一个？怎么区分？" 这篇文章把它们的用法和适用场景做个对比，并给出选择思路和组合建议，方便你按需搭配。

读完后你可以做到三件事：快速判断新需求该用哪种方式、避免把规则写错位置、用一套合理的目录结构起步。

为什么需要多种指令方式

当你希望 Cursor 用 Next.js、TypeScript 做 Web 应用时，往往会加上一堆约定，比如：

• API 路由必须用 zod 做校验
• 数据库访问用 Prisma 的类型安全写法
• 错误统一成固定格式返回

这些规则在一次对话里 AI 还能记住，但新开一个会话又要重新说一遍。原因在于 LLM 本身的限制：

• 无状态：不会跨会话记忆
• Token 有限：上下文窗口有上限
• 成本：上下文越长，调用成本越高

所以我们需要把"要说什么"沉淀成文件，并在合适的时机让 AI 读到。不同文件类型对应不同的触发时机和复用范围，这就是五种方式存在的理由。其中 Skills 专门针对"知识很多但不想一次全塞进上下文"的问题，用渐进式披露来平衡信息量和 Token。

渐进式披露（Progressive Disclosure）的意思是：需要的时候再把相关知识装进上下文，信息分阶段给出去，既够用又不占满上下文。Skills 的三级加载大致如下。

这部分原本用流程图展示三个级别之间的关系，下面是可以直接复制到文生图应用里的提示语。

• 级别 1（元数据）：所有已安装技能的 name、description 会预先放进系统提示，让代理知道有哪些技能、大概干什么，从而判断和当前任务是否相关。
• 级别 2（说明）：一旦判定相关，再把该技能的 SKILL.md 全文载入，看清具体步骤和指示。
• 级别 3（资源）：若执行任务还需要更多信息，再按 SKILL.md 里的引用去打开其他文件、脚本或资料。

这样可以把大量信息收进技能里，又不会一次性占满 Token，这就是 Skills 的设计思路。

5 种方法概览

下面用几张表把五种方式的基本信息、适用时机和主要用途捋一遍。

基本信息

项目	AGENTS.md	Rules	Commands	Skills	Subagents
保存位置	项目根目录	.cursor/rules/	.cursor/commands/	.cursor/skills/	.cursor/agents/
文件格式	AGENTS.md	.mdc、.md	.md	文件夹内 SKILL.md	.md
运营重要性	推荐	强烈推荐	任意	推荐	任意
利用频率	较高	极高	中等	中等	较低

适用时机与上下文

项目	AGENTS.md	Rules	Commands	Skills	Subagents
适用时机	始终自动	条件、常时或手动	仅手动、通过命令名	AI 自动判断或手动、技能名	AI 自动判断或手动
上下文	与父共享	与父共享	与父共享	与父共享	独立上下文
并行执行	不可	不可	不可	不可	可（多子代理同时跑）

再利用性

项目	AGENTS.md	Rules	Commands	Skills	Subagents
再利用性	项目内（单体仓库可在子目录各配一份）	项目内	项目内	可跨项目（可全局配置）	可跨项目（可全局配置）

主要用途

项目	AGENTS.md	Rules	Commands	Skills	Subagents
主要目的	项目整体方针	对 AI 的持续指示	特定作业的一键启动	专业能力扩展	任务委托与并行
适合场景	简单、整体的指示	需要按条件生效的规则	人工触发的固定流程	通用领域知识	长时间调研、并行处理
示例	编码风格、架构原则	某目录下的规则	/code-review	GraphQL 设计最佳实践	安全审查、验证作业

如何快速选：一张流程图

遇到新需求时，可以按一张决策流程图先判断用哪种方式，再去看对应章节的细节。下面是给文生图应用使用的提示语。

若一个需求同时符合多种方式（例如既有"始终生效的简略约定"又有"按目录生效的细则"），可以组合使用，例如根目录 AGENTS.md 写总纲，再用 Rules 针对 src/components/ 写组件规范。

AGENTS.md：项目的「README 式总纲」

AGENTS.md 是五种方式里最省事、门槛最低的一种，可以理解成「写给 Cursor 看的项目 README」。只要在项目根目录放一个 AGENTS.md，当你在这个项目里向 Cursor 提问时，它会自动把这里的内容当成项目的默认约定和背景信息。

在 Cursor 里的效果大致如下：

上面这张图对应的实际配置非常简单：我只是在项目根目录新建了一个 AGENTS.md，里面写清楚「开发或调试前要先跑哪几个命令」：

## 项目开发指令（AGENTS.md）

每次开发或调试前，请按顺序执行以下三个命令：

1. `pnpm dev`：启动开发服务器。
2. `pnpm build`：打包生产环境构建，确保构建无误。
3. `pnpm view react version`：查看当前 npm 注册表中的 React 最新版本号。

之后在这个项目里，只要我随手问一句「帮我优化一下这段代码」之类的问题，Cursor 在后台都会先读取这个 AGENTS.md，于是你在右侧看到的，就是「先按这三个步骤来」这种带项目语境的回答——相当于让 AGENTS.md 帮你把团队约定自动说了一遍。

特点：

• 零配置：根目录放一个文件即可生效，不需要再写任何额外设置
• 可读性好：纯 Markdown，适合写简洁、叙事化的项目方针和协作约定
• 可分区：单体仓库可以在子目录各放一份（例如 frontend/AGENTS.md、backend/AGENTS.md），分别约束前端、后端
• 始终生效：对整个项目长期生效，适合放「总纲型」规则，而不是细碎的按场景说明
• 易维护：内容有变更时，直接编辑本文件即可，无需动其他配置

下面是一个简化示例，用来说明"项目指令"长什么样、一般会写哪些内容：

# Project Instructions

## Code Style

- 使用 TypeScript
- 优先函数型组件

## Architecture

- 使用 Repository 模式
- 业务逻辑放在服务层而不是组件里

适合用 AGENTS.md 的情况：只需要一份项目级总纲，不强调按条件生效，也暂时不考虑跨项目复用，只想用最少配置写清楚项目整体约定和团队共识。一旦要"某些情况才生效"、"手动触发一套流程"或"多个项目共用同一套知识"，就该考虑 Rules、Commands 或 Skills。

另外要注意：AGENTS.md 的内容会在每次相关对话里加载，写得太长会一直占用上下文。更细碎、按场景区分的规则，更适合拆到 Rules 或 Skills 里去。

规则（Rules）：细一点、灵活一点的背景指令

当规则变多、需要按条件生效，或者想针对某些文件、目录单独约定时，就用 Rules。它可以按路径、glob 或"是否常驻"来选什么时候生效，还能在规则里用 @filename 引用具体文件。

特点：

• 适用条件可配置：常时、特定文件、由 AI 判断或手动选
• 支持在规则里引用代码，例如 @component-template.tsx
• 多个规则文件放在 .cursor/rules/ 里，便于分类
• 团队可在仪表板统一管理

Rules 的 frontmatter 里常用字段有：description（规则说明，供 AI 或人工识别）、globs（匹配哪些路径）、alwaysApply（是否常驻）。不写 globs 且 alwaysApply: true 时，规则会在所有对话里生效。

例如给 React 组件单独定一套规则，只在编辑 src/components/ 下的 .tsx 时生效。在 .cursor/rules/react-components.mdc 里写 frontmatter 和正文。下面先给出 YAML 头，用于指定描述和匹配范围：

---
description: "React 组件开发的规则"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

同一文件内，frontmatter 后面接 Markdown 正文，写具体规则内容并引用模板文件：

# React Component Rules

## 组件创建时

- 必须定义 Props 接口
- 避免默认 export
- 参考 @component-template.tsx

这样在编辑 src/components/ 下文件时，这条规则才会被应用。若希望某条规则在任意对话里都生效（例如全局编码风格），可设 alwaysApply: true 且不设 globs。

命令（Commands）：一键跑完的流程

Commands 用来把"一串固定操作"打包成一个命令，由你手动触发，比如跑测试、做 code review、建 PR。每个命令对应一个文件，通过 /命令名 调用。

特点：

• 通过 / 即调即执行
• 可以带参数，例如 /commit、/pr for DX-523
• 团队可在仪表板共享同一套命令
• 把多步操作写在一个命令里，减少重复说明

例如 /code-review：在 .cursor/commands/code-review.md 里定义步骤，之后在聊天里输入 /code-review 就会按这些步骤执行。下面给出该文件的示例内容，用于说明"命令文件"如何写步骤：

# /code-review

## 步骤

1. 确认变更的文件
2. 检查安全问题
3. 确认是否符合编码规范
4. 列出 3 个改进提案

使用方式：在输入框输入 /code-review，必要时加一句说明，例如："请审查这个 PR"。

Commands 适合：测试、代码审查、建 PR 这类需要人工点一下才跑的固定流程。不适合：希望自动生效、一直挂在上下文里、或由 AI 自己决定何时用的规则与知识，那些更适合 AGENTS.md、Rules 或 Skills。

和子代理的区别：Commands 是在当前对话里"插入一段预设步骤"，上下文还是主对话；子代理是另开一个独立对话去执行，结果再回传，适合耗时长或需要并行的任务。

技能（Agent Skills）：可复用的专业知识包

Agent Skills 把某一类专业知识打成一个个「能力模块」，用开放标准格式（含 SKILL.md 和 YAML 头）描述。AI 先只知道有哪些技能（name / description），真正需要时再把对应技能的全文与资源加载进来，这就是 Skills 的渐进式、模块化加载。

特点（和 Rules 的区别可以顺便看出来）：

• 按知识主题模块化：每个 Skill 代表一块专业能力（如组件命名规范、GraphQL 设计），可以在多个项目里复用
• 按需加载：所有技能只先加载元数据，只有和当前任务相关的那几个才会把 SKILL.md 正文装进上下文，后续再按需加载引用资源
• 规则 vs 技能：Rules 是按「当前在哪个文件 / 路径」选出要生效的规则，一旦命中就整条规则全文进上下文；Skills 则是先全局感知有哪些技能，再对当前任务只挑相关的那几块知识细化加载
• 可组合脚本：Skill 里还可以挂脚本，把 LLM 不擅长的步骤交给代码执行

实现上，每个技能是一个文件夹，里面至少有一个 SKILL.md，并在文件开头用 YAML 定义 name 和 description。Cursor 启动时会扫描技能目录（例如 .cursor/skills/），先把所有技能的元数据提供给代理，之后在具体任务里再决定要不要加载某个技能的正文。

下面直接用本文正在使用的真实示例来说明 Skill 的长相：我在这个项目里新建了 .cursor/skills/moment-component-prefix/SKILL.md，约定所有 React 组件的名字都以 Moment 开头（例如 MomentButton、MomentCard）。完整内容如下：

---
name: Moment 组件命名规范
description: 要求本项目中所有 React 组件名称都以 Moment 开头，例如 MomentButton、MomentCard。
---

# Moment 组件命名技能

## 何时使用

- 在创建新的 React 组件时
- 在重命名或抽取组件时

## 指示

- 所有导出的 React 组件名称必须以 `Moment` 开头，例如 `MomentHeader`、`MomentFooter`。
- 若根据文件名生成组件，组件名也应以 `Moment` 开头，例如文件 `header.tsx` 中的组件名为 `MomentHeader`。
- 执行重构时，如遇不符合该前缀的组件，应优先建议重命名为带 `Moment` 前缀的版本。

配置好这个 Skill 之后，当我在项目里请求「优化组件」「重构组件名」时，Cursor 就会自动参考这份规则，优先给出带 Moment 前缀的组件名称。下图展示的是这个 Skill 实际生效时的效果：

子代理（Subagents）：只干一件事的副手

子代理可以理解成「由主代理派出的专职小助手」。每个子代理都有独立上下文，专注处理某一类任务，做完以后把结果打包交回主代理；主代理再根据这些结果继续和你对话或接着修改代码。

模块化的角度看，子代理不是按「路径」或「知识主题」来拆，而是按任务角色来拆：比如「验证助手」「安全审查助手」「UI 回归助手」等，让每个子代理只干一件事、长期保持同一种工作风格。

特点：

• 上下文隔离：子代理有自己的对话历史，不会把长时间验证 / 调研的细节塞进你的主对话里
• 可并行：可以同时开多个子代理，让它们各自跑不同任务，再统一收结果
• 可定制：每个子代理可以配自己的提示词、工具组合和模型类型
• 可复用：同一子代理配置可以在多个项目共享，比如统一的安全审查或验证流程

调度方式大致有两种：

模式	行为	适合场景
Foreground	主代理等子代理跑完再继续对话	需要按顺序拿到输出的任务（例如「先验证再继续开发」）
Background	立刻把控制权还给你，子代理在后台慢慢跑	耗时长或希望并行多任务时（例如「一边写代码，一边让子代理做全面安全审查」）

需要注意的是：子代理从「空上下文」开始，看不到主对话历史。所以主代理在派活时，必须把当前任务描述、涉及的文件、期望的检查点等一起打包进提示，否则子代理只好猜，很容易跑偏。

下面是本文当前项目里真实在用的一个「验证」子代理配置，文件路径是 .cursor/agents/verifier.md，主要负责在改动完成后帮忙做一次系统性的检查与建议：

---
name: verifier
description: 验证已完成的工作，检查实现是否按预期运作，并结合本项目约定给出测试与改进建议。
---

# Verifier 子代理

你是本项目的验证助手，专门在实现完成后进行检查与验证。你有独立上下文，不会看到主对话历史，所有必要信息会由主代理在派发任务时提供给你。

## 目标

- 确认实现是否满足用户需求与设计意图。
- 检查是否存在明显的类型错误、运行时错误或边界情况缺失。
- 结合本项目使用的工具链（pnpm、React、TypeScript）给出合理的测试与改进建议。

## 使用背景

- 本项目使用 pnpm 作为包管理工具。
- 运行开发与构建相关的典型命令包括但不限于：
  - `pnpm dev`
  - `pnpm build`
  - （如存在）`pnpm test`、`pnpm lint`

## 验证步骤

1. **理解需求与范围**
   - 阅读主代理提供的任务描述与变更说明。
   - 弄清楚本次改动的功能边界与非目标范围。

2. **审查代码与结构**
   - 聚焦主代理列出的关键文件和模块。
   - 检查是否遵循项目的技术栈约定（React + TypeScript 等）。
   - 粗略评估实现是否过于复杂，是否可以简化。

3. **测试与构建建议**
   - 若主代理提供了命令输出（如 `pnpm build`、`pnpm test`），分析其中的错误、警告与提示。
   - 若尚未执行相关命令，明确建议主代理或用户执行：
     - 至少运行 `pnpm build` 以确认生产构建是否通过。
     - 若项目配置了测试与 Lint，建议运行 `pnpm test` 与 `pnpm lint`。

4. **边界条件与错误处理检查**
   - 思考与本次改动相关的典型边界情况（空数据、错误响应、慢网路、异常输入等），检查代码中是否有所体现。
   - 指出潜在的未处理情况或容易出错的分支，并给出改进方向。

5. **输出结构化报告**
   - 列出：
     - ✅ 已验证通过的项目（功能点、测试或构建检查）。
     - ⚠️ 发现的问题（含严重程度说明）与改进建议。
     - ❓ 需要主代理或用户补充的信息（例如缺失的日志、命令输出、接口约定等）。
   - 报告尽量简洁、条理清晰，便于主代理直接据此继续修改或补充验证。

## 与主代理的协作约定

- 若信息不足以完成可靠验证，请明确说明缺口，并请求主代理补充必要上下文，而不是进行过度臆测。
- 在可能的情况下，优先给出可操作的、一步步的改进建议，而不是泛泛而谈。

实际使用时，你可以在主对话里完成一轮实现，然后让主代理把相关改动、运行命令和期望行为打包交给 verifier 子代理，让它在独立上下文里跑完整套验证，并把结果以结构化报告的形式带回主对话。这样既不污染主对话的上下文，又把「验证这件事」模块化成了一个可以在多个项目反复复用的助手。

实际使用示例：React 项目里的五种用法

同一个需求"在 React 项目里统一组件开发方式"，可以分别用五种方式实现。下面按"从简到繁、从项目内到可复用"的顺序各给一个写法，便于对比同一诉求在不同方式下的形态。

方式 1：AGENTS.md（最简）

在项目根目录的 AGENTS.md 里写一段即可，适合小项目或只做简单约定时使用。

# Project Instructions

## React 组件开发

- 使用 TypeScript
- 优先函数型组件
- Props 必须进行类型定义

方式 2：Rules（按目录生效）

希望规则只在改 src/components/ 时生效，可以用 Rules。在 .cursor/rules/react-components.mdc 里写 frontmatter 和正文，例如引用模板文件：

---
description: "React 组件开发的规则"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

# React 组件规则

## 组件创建时

- 必须定义 Props 接口
- 避免默认 export
- 参考 @component-template.tsx

方式 3：Commands（手动执行一套步骤）

把"创建组件"拆成固定步骤，做成命令 /create-component。在 .cursor/commands/create-component.md 里写：

# /create-component

# 步骤

1. 创建组件文件
2. 定义 Props 接口
3. 创建测试文件

使用：输入 /create-component Button，即可按步骤生成组件并带测试。

方式 4：Skills（可复用的最佳实践）

把 React 组件的最佳实践打成技能，AI 在写组件或做 code review 时会按需加载。例如 .cursor/skills/react-best-practices/SKILL.md：

---
name: React Best Practices
description: React 组件开发的最佳实践。重视性能优化、重渲染防止、Hooks 的适当使用。
---

# React Best Practices 技能

## 何时使用

- 创建或修正 React 组件时
- 需要性能优化时
- 使用 Hooks 时
- 解决重渲染问题时

## 指示

### 组件设计

- 自定义 Hook 使用 `use` 前缀
- Props 接口必须进行类型定义
- 组件遵循单一责任原则

### 性能优化

- `useMemo` 和 `useCallback` 仅在必要时使用
- `useEffect` 的依赖数组必须明确指定
- 对于大型列表，考虑使用虚拟化

### 重渲染防止

- `memo` 仅在必要时使用（避免过度优化）
- Context 的值适当进行 Memoization
- 识别不必要重渲染的原因

适合：希望按"行业常见实践"自动参与编写和审查，且可能多个项目共用时。

方式 5：子代理（独立验证）

验证和测试单独交给子代理，不占用主对话上下文。例如 .cursor/agents/verifier-reviewer.md：

---
name: verifier
description: 验证已完成的工作，确认实现是否正常运作，并执行测试
---

# Verifier 子代理

此子代理验证已完成的工作，确认实现是否正常运作，执行测试，并报告成功和未完成的部分。

## 验证步骤

1. 确认已实现的代码
2. 执行单元测试
3. 执行集成测试
4. 检查错误或警告
5. 报告结果

适合：做完一坨改动后，希望单独跑一轮验证或测试，而不把主对话拉得很长时。

小结：若只做"项目内、始终生效的简单约定"用方式 1；若希望"只在改组件目录时生效"用方式 2；若希望"人工点一下才按步骤生成组件"用方式 3；若希望"多项目共用、且 AI 写组件或审查时自动参考"用方式 4；若希望"验证和测试在独立上下文里跑"用方式 5。实际项目中往往组合使用，例如 1 + 2 + 4，或 1 + 3 + 5。

再举一个安全审查子代理的例子，放在 .cursor/agents/security-reviewer.md：

---
name: security-reviewer
description: 检查代码中的注入、XSS、硬编码秘密等常见漏洞
---

# Security Reviewer 子代理

您是安全专家。执行代码的安全审查，识别潜在漏洞。

## 检查项目

1. SQL 注入
2. XSS（跨站脚本攻击）
3. 硬编码秘密
4. 认证和授权问题
5. 遵守安全的编码实践

从零开始的建议顺序

如果项目里还没用过这些方式，可以按这个顺序逐步加，避免一次堆太多导致维护成本高：

1. 先写一个根目录的 AGENTS.md，把项目技术栈、编码风格、目录约定等总纲写清楚，控制在几十行以内。
2. 再按目录或文件类型加 Rules，例如 src/components/ 用组件规则、src/api/ 用 API 规则，每条规则保持单一职责。
3. 把经常重复的"多步操作"抽成 Commands，例如 /code-review、/run-tests，方便团队统一流程。
4. 若有跨项目共用的领域知识（如 GraphQL、无障碍、K8s），再做成 Skills，安装到 .cursor/skills/ 或全局技能目录。
5. 子代理用在"需要独立上下文或并行"的场景即可，不必每个项目都配。

一个常用的项目配置结构

下面是一套常见的组合方式，按目录列出来，方便你直接套用或裁剪。如果希望用图来展示整个项目结构，可以使用下面这段提示语生成信息图。

手绘风格教育科普信息图海报，竖版 3:4 比例，白色或浅米色背景，彩色铅笔与素描线条质感，温暖柔和蓝黄粉绿橙配色，整体风格类似儿童编程科普图。顶部标题「一个典型 Cursor 项目的配置结构」，副标题「AGENTS、Rules、Commands、Skills、Subagents 分布一图看懂」。
画面中央是一棵抽象的项目目录「树」或卡片式结构：最上方是大文件夹「项目根目录」，内部画 `AGENTS.md` 文件卡片，旁边小标签「项目整体方针」。向下分出两条分支，分别是 `frontend/AGENTS.md` 和 `backend/AGENTS.md`，用不同颜色表示前端与后端，旁边写「前端指令」「后端指令」。
根目录下画 `.cursor` 大文件夹，内部再分为四个子文件夹：`rules`、`commands`、`skills`、`agents`，每个子文件夹用不同颜色和图标表示：
rules 区块下有 `api-design.mdc`、`database-schema.mdc`、`deployment-flow.mdc` 三个文件卡片，配注释「API 设计规则」「数据库设计规则」「部署流程」；
commands 区块下有 `code-review.md`、`create-pr.md`、`run-tests.md` 三个文件卡片，标注「代码审查命令」「创建 PR」「运行测试」；
skills 区块下有 `react-best-practices/` 文件夹和若干 `SKILL.md` 文件，如 `graphql-best-practices/SKILL.md`、`kubernetes-ops/SKILL.md`、`accessibility/SKILL.md`，配小图标代表前端、后端与运维知识，旁边写「可复用技能包」；
agents 区块下有 `verifier.md` 和 `security-reviewer.md` 两个文件卡片，配放大镜与盾牌图标，分别标注「验证子代理」「安全审查子代理」。
用细虚线或颜色分区轻轻框出「项目总纲（AGENTS）」「项目内规则（Rules）」「一键流程（Commands）」「领域技能（Skills）」「子代理（Agents）」五块区域，每块区域顶部有小标题和简短说明，整体布局紧凑清晰，方便一眼看懂各类文件放在哪里、负责什么。

常见误区和组合建议

• 把本该"按条件生效"的细则写进 AGENTS.md，导致上下文总是很长。这类内容更适合放到 Rules（按路径）或 Skills（按任务类型）。
• 把"希望 AI 自动用到"的领域知识只写在 Commands 里。Commands 只有你输入 /xxx 时才会执行，不会自动参与编写或审查，这类知识应放在 Rules（项目内）或 Skills（可复用）。
• 同一件事既写 Rules 又写 Skills，内容重复且可能冲突。约定好边界：和本项目、本目录强相关的用 Rules，通用且要复用的用 Skills。
• 子代理的提示里没带够上下文。子代理看不到主对话，主代理在派活时必须把"当前改了哪些文件、期望验证什么"等写进提示，否则子代理容易做无用功。

组合建议：多数项目用"根目录 AGENTS.md + 若干 Rules"就能覆盖大部分需求；Commands 按团队实际工作流补几条即可；Skills 和 Subagents 按是否有跨项目知识、是否有并行或独立验证需求再加。这样既不会漏掉该用的方式，也不会堆得难以维护。

总结一下选择思路：要"项目总纲"用 AGENTS.md；要"按文件或条件生效"用 Rules；要"人工一键跑流程"用 Commands；要"可复用的领域知识"用 Skills；要"独立上下文、并行或专门验证"用 Subagents。按需求组合这五样，就能把 Cursor 的指令体系用得比较顺手。