阅读视图

发现新文章,点击刷新页面。

AI辅助开发实战:会问问题比会写代码更重要

AI辅助开发实战:会问问题比会写代码更重要

系列第二篇。我想聊聊怎么用好 AI 这个工具。不是教你怎么敲代码,而是教你,怎么真正用好AI辅助开发工具。


原文地址

墨渊书肆/AI辅助开发实战:会问问题比会写代码更重要


你有没有过这样的经历?

打开Cursor(或者TraeCopilot),对着空白编辑器发了半天呆,不知道该让AI帮你干什么。

或者你问了一句「帮我写个登录功能」,AI 噼里啪啦写了一大堆代码,你看都看不懂,最后只能硬着头皮复制粘贴。

再或者,你问 AI:「这个报错是什么意思?」它回了一堆你看不懂的术语,你更迷茫了。

如果你有以上任何一种经历,这篇文章就是写给你的。


会问问题,比会写代码更重要

这是我最近一年用 AI 辅助开发最大的感悟。

以前我觉得,AI 嘛,就是个更聪明的搜索引擎。我不会的代码问它,它告诉我怎么写呗。

后来发现不是这么回事。

同样一个问题,不同的问法,AI 给出的答案质量可以差十倍。

AI 不会读心术。你得把自己的需求翻译成 AI 能理解的语言。

举两个例子感受一下:

第一种问法:「帮我写个登录功能。」

AI给你一个标准答案:用户名密码输入框、提交按钮、后端接口、数据库查询。看起来很全,但放到你的项目里可能完全不适用。你要改吧,改到猴年马月。不要吧,扔掉又可惜。

第二种问法:「我的项目用Next.jsPrisma,用户表字段是 email 和 passwordHash。请帮我写一个登录API,要支持邮箱密码登录,密码用 bcrypt 加密,返回 JWT token,7天有效期。」

AI给你的代码,直接就能用。稍微调一下就能跑。

这就是差距。好的 Prompt 不是更长的Prompt,而是更精确的 Prompt。


几个基本概念

在开始讲技巧之前,先简单说几个你经常会遇到的术语:

LLM:Large Language Model,大语言模型。你可以把LLM理解为"大脑",GPT、Claude、DeepSeek 都是 LLM。ChatGPT、Cursor背后的 AI 都是LLM在驱动。

Prompt:提示词,你给AI说的话。「帮我写个登录功能」就是一个Prompt。

Agent:你可以理解为"能自己干活"的AI。传统AI是你问一句它答一句,Agent 是你告诉它一个目标,它自己规划步骤去执行。Cursor 的 Agent 模式就是这个原理。

MCP:Model Context Protocol,模型上下文协议。这是 2024 年出来的一个标准,让 AI 能统一地访问外部工具和数据。比如 AI 可以通过 MCP 直接读取你电脑上的文件、查询你的数据库、控制浏览器。2026年的 Cursor 已经支持 MCP,用起来很方便。

Token:你可以理解为 AI 处理文字的"计量单位"。英文约4个字符=1个 Token,中文约1-2个汉字=1个 Token。

为什么要注意 Token?因为 AI API 是按 Token 收费的。你输入的文字要花钱,AI输出的文字也要花钱。知道这些就够了,继续往下看。


我的AI辅助开发经验

2026年了,AI辅助开发工具已经成为程序员的标配。CursorTraeCopilotOpenCode……不管你用哪个,核心技巧都是互通的。

我用了一年多,从一开始的「这有啥」到现在的「真香」,总结了一些真正有用的经验。

1. 搞清楚什么时候用什么模式

Cursor 有两个核心模式:AgentChat。用对了,效率翻倍;用错了,就是折磨。

Chat模式:你问一句,它答一句。像跟人聊天一样。

我一般用来:

  • 问具体问题:「这个报错是什么意思?」
  • 查知识点:「PostgreSQL的索引类型有哪些?」
  • 解释代码:「这个函数做了什么?」
  • 帮我想名字:「帮我给这个函数起个名字」

Agent模式:你描述一个任务,它自己去分析和改代码。威力更大,但需要把需求说清楚。

我一般用来:

  • 帮我重构整个模块:「把这个登录从JWT改成Session」
  • 帮我修bug:「登录一直返回401,帮我看看是什么原因」
  • 帮我转换代码:「把这个JavaScript文件改成TypeScript」
  • 帮我实现一个功能:「帮我实现用户注册功能,包含表单验证、数据库存储、发送欢迎邮件」

简单说:小问题用Chat,大任务用Agent。

2. 喂上下文是有技巧的

Cursor 最强的地方是它能理解你的整个项目。你打开一个文件,问它这个组件是做什么的,它能根据文件名、代码内容、项目结构给你答案。

但有时候它也会犯傻——给你一些牛头不对马嘴的回答。

这时候,你得学会喂上下文

我犯过的错误:

「怎么优化这个查询?」

AI回了半天,什么加索引、分页、缓存讲了一套,我根本不知道它说的是什么,因为我连我的表结构都没告诉它。

后来我学乖了:

「我的Prisma查询是这样的:prisma const users = await prisma.user.findMany() 数据量大概10万条,现在查询要3秒,请问怎么优化?」

这次AI直接告诉我:1. 加索引 2. 用select只查需要的字段 3. 考虑分页。

我的习惯是:至少告诉AI三件事

  1. 我用的技术栈是什么(Next.js + Prisma + PostgreSQL)
  2. 当前代码长什么样(贴上代码)
  3. 遇到了什么问题(查询慢、报错、不知道怎么做)

3. Tab键补全真的好用

大部分 AI 辅助开发工具都有代码补全功能,会预测你下一行要写什么。按 Tab 键直接采纳预测。

刚开始我还不太信这个功能,觉得 AI 哪有那么聪明。后来真香了。

我经常这样用:

  • 写TypeScript类型定义,AI能猜到我要的类型
  • 写React组件props,AI能帮我补全大部分
  • 写数据库schema,AI知道我想要什么字段
  • 写import语句,AI知道我要导入什么

10次有8次是准的,能省很多打字的时间。

4. 选中代码让AI帮你改(核心技巧)

选中一段代码,让AI帮你修改。这是一个通用技巧,大部分工具都支持,只是快捷键不太一样。

这是我最常用的功能,没有之一。

比如我选中一个函数,这样用:

「请帮我添加错误处理和类型定义」

AI直接在原代码基础上帮我改好了,我只需要确认一下就行。

比让它生成一段新代码然后我再替换,效率高很多。

再举几个我常用的场景:

  • 选中一段面条式代码:「请帮我重构这段代码」
  • 选中一个API接口:「请帮我添加参数校验」
  • 选中一个组件:「请把这个组件改成响应式」

5. 打开对话窗口做复杂任务

有时候你想让AI帮你做比较复杂的任务,比如生成一个完整的组件。

选中代码后打开对话窗口,可以详细描述你的需求。

我经常这样用:

  1. 选中一段代码
  2. 打开对话窗口
  3. 详细描述我要做什么
  4. AI生成代码,我可以逐行确认

这个功能特别适合:

  • 生成一个新组件
  • 实现一个复杂功能
  • 写测试用例

6. @符号引用文件

@符号引用特定内容。

  • @File :引用当前打开的文件
  • @components/UserCard.tsx :直接引用某个文件
  • @Folder :引用整个文件夹
  • @Docs :引用官方文档
  • @Search :搜索项目内的代码

最常用的场景:

@components/UserCard.tsx 请帮我在这个组件里添加一个编辑用户信息的功能

AI直接读取文件内容,在正确的位置帮我添加代码。

@Docs 请帮我查一下Next.js的metadata怎么用来做SEO

AI直接读官方文档,给我准确的答案。

7. 设置好项目规范

我在每个项目都会设置Rules。这是Cursor的一个特色功能,其他工具类似功能还在发展中。

在项目根目录创建.cursor/rules/目录,放.mdc文件:

---
name: 项目规范
description: Next.js 15 App Router 项目规范
---

# 技术栈
- 框架:Next.js 15 App Router
- 语言:TypeScript strict
- 样式:Tailwind CSS
- 数据库:PostgreSQL + Prisma

# 目录结构
- app/:页面
- components/:组件
- lib/:工具函数
- prisma/:数据库schema

# 代码规范
1. 默认使用 Server Components
2. 客户端用 'use client' 标记
3. API错误格式:{ success: boolean, error?: string }

设置好之后,Cursor每次生成代码都会自动遵循这些规范。

举个例子:我不用每次都说「API错误要返回success和error字段」,Cursor自己就知道。

而且Rules是可以复用的。我做了几个模板:

  • Next.js项目规范
  • NestJS项目规范
  • React组件规范

每次建新项目,直接复制过来改一下就行。

8. 用好Skills,让AI更专业

如果说Rules是「项目规范」,那Skills就是「专业能力」。

你可以在.cursor/skills/目录放一些专业技能文件:

# .cursor/skills/database.md

你是一个数据库专家,精通 PostgreSQL 和 Prisma。

在回答数据库相关问题时:
1. 优先考虑查询性能,避免 N+1 问题
2. 合理使用索引,解释为什么加这个索引
3. 更新用 update,删除用 delete,别用 updateMany

回答时先解释原理,再给代码示例。

用的时候告诉AI:「请用数据库专家的角度,帮我审查以下Prisma查询...」

它回答的专业度明显比普通模式高。

我目前积累了几个Skills:

  • database.md:数据库专家
  • security.md:安全专家
  • performance.md:性能优化专家
  • typescript.md:TypeScript专家

9. MCP让AI更强大

前面提到了MCP,这是2026年特别值得关注的特性。

简单说,MCP 让 AI 能从"只懂训练数据"变成"能操作真实世界":

  • MCP + 文件系统:AI 可以直接读取、修改你本地项目的代码
  • MCP + 数据库:AI 可以直接查询你的数据库
  • MCP + 浏览器:AI 可以控制浏览器,帮你填表单、截图
  • MCP + 搜索:AI 可以帮你搜Google、搜文档

Cursor、Trae 等新一代工具已经开始支持 MCP,装好对应的插件就能用。

装好 MCP 插件后,我可以直接问AI:「帮我查询数据库里最近注册的10个用户」

AI真的会去查数据库,然后给我结果。

这个功能还在快速进化中,未来能做的事情会越来越多。

10. 节省Token是有技巧的

前面提到了 Token 的概念。Token 是 AI 处理文字的计量单位,AI API 是按 Token 收费的。

这是我总结的节省 Token 经验:

  1. 别一上来就贴全栈代码:只贴和问题相关的代码片段,AI不需要看你的整个项目才能回答问题。

  2. 问完一个问题可以开新会话:如果新问题和上一个问题不相关,别在同一个会话里继续聊。AI需要记住之前对话的内容,这些也会算Token。

  3. 让AI一次性完成:比如你要写一个组件,别分开问「先帮我写HTML」「再帮我写样式」「再加个交互」。直接说「帮我写一个登录组件,包含表单验证、错误提示、暗色模式支持」,一次搞定。

  4. 精简你的Prompt:Prompt不是越长越好,是越精确越好。把无关的废话去掉,AI能更专注,Token也花得值。

  5. 用@引用代替复制粘贴:用@File引用文件,AI会自己去读,比你复制粘贴一长串代码省Token。


这些场景我天天用AI

1. 读报错信息

以前遇到报错,我要把错误信息复制到Google搜半天。

现在直接问Cursor:「这个报错是什么意思?TypeError: Cannot read properties of undefined (reading 'map')」

它会告诉我:错误原因是什么、最可能出在哪个地方、怎么修复。

80%的情况下,它能帮我省掉搜索的时间。

有时候我甚至直接截图给它看,它也能分析个大概。

2. 代码Review

以前代码Review都是同事做。现在我先让AI Review一遍,发现低级问题,再交给同事。

效率高很多,而且有些话AI说得,我作为开发者反而不好开口。

「请审查以下代码,指出:1. 潜在安全问题 2. 性能问题 3. 代码规范问题」

它会从安全性、性能、代码规范等角度帮我分析一遍。

3. 重构代码

觉得某段代码写得烂,但不知道怎么改?

问AI:「请帮我重构以下代码,要求:1. 使用TypeScript类型 2. 提取可复用逻辑 3. 增加错误处理」

AI会给一个全新的版本,我可以参考它的思路自己改,也能学到东西。

有时候我还会让它用不同的方式重构,让我对比学习。

4. 帮我想名字

我经常让AI帮我给变量、函数起名字。

「我有一个函数,接受用户ID,返回用户名、邮箱、头像、最后登录时间。请帮我想一个合适的函数名」

AI会给三四个建议:

  • getUserById
  • fetchUserDetails
  • getUserProfile

我会选一个最合适的。

比自己想半天强多了。而且AI起的名字通常都比较规范,符合命名习惯。

5. 写测试

写测试很枯燥,但很重要。

我会让AI帮我:

「请为以下函数编写单元测试,覆盖:正常情况、空输入、错误输入」

AI生成测试代码,我再根据需要调整。能省不少时间。

有时候我还会让它帮我补充边界情况的测试。

6. 查文档

以前遇到问题,我先去 Google 搜,然后看 Stack Overflow,最后实在不行才去翻文档。

现在我直接问 Cursor:

`@Docs 请帮我查一下Next.js 15怎么做密码重置」

或者

`@Docs Vercel AI SDK怎么实现流式响应」

AI直接从文档里给我准确的答案,比我自己搜快多了。

7. 帮我写SQL

有时候我需要写一些复杂的SQL查询,直接问AI:

「帮我写一个SQL,查询过去7天每天的新增用户数,按日期排序」

AI会给我SQL,我稍微改改就能用。

8. 帮我理解别人的代码

接手别人的项目,看不懂代码怎么办?

问AI:

`@components/OldCode.tsx 请帮我解释这个组件做了什么」

AI会把代码逻辑梳理一遍,比我自己看快多了。


积累自己的Prompt模板库

这是我想聊的最后一个话题。

有些 Prompt 我会反复使用,慢慢就积累了一套模板:

// 解释代码
请用三句话解释以下代码做了什么

// 解释报错
这个报错是什么意思?{报错信息}

// 生成类型
请为以下接口生成 TypeScript 类型定义

// 代码审查
请审查以下代码,指出:1. 潜在问题 2. 性能优化点 3. 代码规范问题

// 重构
请重构以下代码,要求:{你的要求}

// 写测试
请为以下函数编写测试用例,覆盖:{场景1}、{场景2}、{场景3}

// 查文档
@Docs {你的问题}

我保存在一个markdown文件里,用的时候直接复制粘贴,稍微改改就能用。

我的经验总结

用多了,你会发现有些规律:

  • 1. 模板要简单通用

    我的模板都很简单,就是一个开头。比如「请用三句话解释」,这个模板可以用在任何代码上。

    不要把模板写得太具体,比如「帮我写一个登录表单要包含用户名、密码、验证码」。这样反而不好复用。

  • 2. 遇到好的Prompt就保存下来

    有时候你会发现,同样的问题,不同的问法,AI回答的质量差很多。

    遇到好的Prompt,就把它保存下来。下次遇到类似的问题,直接用或者改改再用。

  • 3. Rules模板可以复用

    Rules模板也是一样的道理。

    我做了几个模板:

    • Next.js项目规范
    • NestJS项目规范
    • React组件规范

    每次建新项目,直接复制过来改一下就能用。做到第三个项目,你会发现很多规范是可以复用的。

  • 4. 定期整理和迭代

    我的模板库每个月会整理一次。把不用的删掉,好的留下来。

    有时候会发现之前写的模板不够好,就改改。

    这是一个持续迭代的过程,不用急。


写在最后

回到开头的问题:会问问题,为什么比会写代码更重要?

因为 AI 时代,写代码的门槛会越来越低。但提问的能力——把模糊的需求翻译成精确的描述——这个能力反而越来越值钱。

你能不能清楚地描述你想要什么?能不能给 AI 足够的上下文?能不能判断 AI 给出的答案对不对?

这些才是 AI 时代真正的核心竞争力。

AI 辅助开发工具会越来越好用,Cursor、Trae、Copilot、OpenCode……不管你用哪个,核心技巧都是互通的。用好工具的人,永远是那些懂得思考的人。

下一篇文章,我们会开始真正的技术内容:《全栈开发环境搭建:Git + monorepo + 开发工具链》。

感兴趣的话,下一篇见。

为什么2026年还要学全栈?

为什么2026年还要学全栈?

系列开篇,写给想要真正做事的人。


原文地址

墨渊书肆/为什么2026年还要学全栈


你有没有过这样的经历?

做了一套很酷的前端界面,发到群里求赞。朋友问:「能线上访问吗?」你愣了一下:「还在本地跑着呢。」

搭建了一个API接口,测试数据跑得好好的。放到线上就开始报错,你对着日志看了半天,不知道是数据库连接问题还是CORS没配好。

买了个云服务器,SSH连上后对着黑屏发呆——接下来该干什么?域名怎么绑定?HTTPS怎么配置?

如果你有过类似的经历,说明你和我一样,曾经被困在某个技术边界里。

前端会一点,后端也懂一点,但真的要把一个想法变成线上能用的东西,总是差了那么一口气。

我想聊聊这件事。


全栈这件事,被误解了很多年

一提到「全栈工程师」,很多人脑海里浮现的是这样一个形象:什么框架都会,什么语言都能写,数据库也能碰,服务器也能捣鼓。

换句话说,「什么都会一点」。

这种理解,在五年前或许还能成立。那时候做Web开发,确实需要前后端都懂一点才能混得下去。

但2026年了,这种理解该过时了。

真正的全栈,不是「什么都会一点」,而是「能独立交付一个完整的、可运行的互联网产品」。

这两个定义有本质区别。

「什么都会一点」说的是技术广度,你掌握了ABCDE各种技术。 「能交付完整产品」说的是能力深度,你能够从0到1,把想法变成现实。

前者是堆砌,后者是整合。

这十年,全栈经历了什么

让我简单回顾一下这段历史,你可能会更有感触。

  • 2010-2015年:全栈的黄金时代

那时候,一个创业者想要做个网站,真的需要一个人搞定所有事情。PHP就是最典型的全栈语言——一个文件,从数据库到HTML全写了。

没有选择,只能全栈。

  • 2015-2020年:前后端分离,全栈「衰落」

前端技术越来越复杂,React、Vue、Angular各自一套生态。后端技术也在深化,微服务、容器化、云原生,一个领域比一个领域深。

很多人开始专注于一个方向。全栈这个词渐渐变成了「什么都会一点,什么都不精」的代名词。

我见过很多前端工程师,后端代码一行都不敢改。也见过很多后端工程师,写个表单样式就头皮发麻。

技术栈在变宽,人在变窄。

  • 2020年至今:AI时代,全栈复兴

转折来自两个力量:

一是Serverless和全栈框架的成熟。Next.jsSupabase让一个人能覆盖的场景越来越广。

二是AI的爆发。代码可以自动生成了,一个人能做的事情边界再次扩大。

但这次不一样。

这次的全栈,不是回到过去那种「什么都会一点」的状态,而是有了AI的辅助,你可以更专注于「整合」而非「实现」

你不需要记住每个API的用法,AI可以帮你查。但你需要知道一个系统需要哪些模块、它们怎么配合。

这才是2026年「全栈」的真正含义。


我见过太多「会技术」但「做不出东西」的人

我自己也是这么走过来的。

刚学编程的那几年,我痴迷于学新东西。React出来了,学React。Vue火了,学Vue。Node.js流行,学Node。Docker热门,学Docker。

感觉自己越来越厉害,简历上技术栈越来越长。

但有一次,我做一个个人博客系统,前前后后做了俩个月。

不是技术难,而是我在每个环节都卡住:

  • 前端写到一半,发现后端API设计不合理,推倒重来
  • 数据库表结构改了三版,每次都要改前端对应的字段
  • 好不容易做完了,部署上线又折腾了一周
  • 刚上线就被别人注册了一堆垃圾数据,才发现自己没做接口限流

一个看似简单的博客系统,真正从零做到上线,才发现之前学的那些技术都是散的,根本连不起来。

后来我反思:不是我技术不够,而是我从来没有站在「完整产品」的角度去规划一个系统。

这就是问题所在。

但现在,在春节前,我使用 AI 辅助开发和腾讯云的轻量服务器,3天就成功上线了我的个人博客站。

————墨渊书肆

后面,也会根据这个博客站,和我在开发的另一个出海产品,分享我的实战经验。


全栈到底学什么?

说了这么多,你可能想问:所以全栈到底要学什么?

我的回答是:不是学更多技术,而是理解技术之间的关系。

举两个例子。

第一个例子。

你想实现「用户登录后可以评论」这个功能。你需要懂:

  • 前端表单验证
  • 后端接口设计
  • 数据库表结构
  • 密码怎么加密存储
  • Token怎么验证
  • HTTPS怎么配
  • Rate Limiting怎么加

每一项单拎出来都不难。但如果你不懂它们之间的关系,就会出现:前端验证了后端没验证、密码存明文了、Token没过期时间、接口被人刷爆等各种问题。

第二个例子。

你做一个博客系统。要发文章、要看文章、要评论、要搜索、要做SEO、要做推荐。

每个功能你都能找到对应的技术方案。但关键问题是:

  • 先做哪个后做哪个?
  • 数据库表之间怎么关联?
  • 哪些数据要缓存哪些不用?
  • 搜索要做全文检索还是简单like查询?

这些问题没有标准答案,需要你根据实际需求去权衡去决策。

全栈的核心能力,就是理解这些技术怎么配合,然后做出合理的决策。


2026年的全栈技术图谱

既然说到全栈,我把一个现代 Web 应用涉及到的技术领域整理一下。不用全部记住,但需要知道大概有哪些东西,以及每个部分是干嘛的。


前端部分 —— 用户能看到的一切

前端就是用户打开浏览器能看到的所有东西。按钮能不能点、页面好不好看、表单能不能提交,这些都归前端管。

框架:用来构建用户界面。React是现在最主流的选择,Vue在国内用得也比较多,Next.js比较特殊,它既是前端框架,又自带后端能力,属于「全栈框架」。

样式:让界面好看。Tailwind CSS是现在的主流,因为它不用写单独的CSS文件,直接在HTML里写样式,很方便。

状态管理:管理页面数据。比如用户登录了,他的信息存在哪里?购物车有几件商品?这些数据的变化需要统一管理,Zustandmobx是轻量级的选择,Redux功能更全但也 更重。

UI组件:现成的界面零件。shadcn/ui现在特别火,它不是传统意义上的组件库,而是提供代码让你自己修改,这样你可以完全控制样式。


后端部分 —— 用户看不到但每天在用的

后端是服务器上运行的代码,你看不见它,但它在默默处理各种请求。用户登录、提交订单、查询数据——这些都需要后端来处理。

运行时:JS 可以在服务器上运行了,这就是Node.js,目前最成熟。Bun更快,Deno更现代(Node.js的原作者重新写的)。

框架:写后端代码的工具。Next.js API Routes是前后端一起写的方式,适合小项目。Hono非常轻量,而且天然支持 Edge 部署(边缘计算,后面会讲)。NestJS是企业级的,结构更严谨,适合大项目。

数据库:存数据的地方。PostgreSQL是目前最强悍的关系型数据库,MySQL是老牌稳定选手。简单理解:重要数据放数据库。

ORM:数据库和代码之间的翻译官。Prisma用起来很舒服,Drizzle更快且更轻, typeORM 功能更全。它们让你用 JS 的语法去操作数据库,不用写原始SQL。


基础设施 —— 让你的应用能跑起来

这部分是很多前端开发者最头疼的——代码写完了,怎么让它能被所有人访问?这就是基础设施要解决的问题。

服务器:一台24小时开机的电脑。国内的阿里云腾讯云,国外的VercelNetlify,都是提供服务器的服务商。

容器:把应用和它依赖的所有东西打包,这样在任何环境下都能跑。Docker是标配,Docker Compose用来在本机编排多个服务。

CDN:让用户访问更快。CDN就是一堆分布在世界各地的服务器,用户访问时从最近的服务器拿资源,速度会快很多。国际首选Cloudflare,国内用阿里云CDN

域名和SSL:域名是网站的地址,SSL是让访问变成https://的那个加密协议。Let's Encrypt提供免费SSL,Cloudflare可以自动帮你处理HTTPS。


运维监控 —— 保障服务稳定运行

应用上线了,怎么知道用户访问快不快?出错了怎么知道?这些就是运维监控要做的。

日志:记录系统发生了什么。ELK(Elasticsearch + Logstash + Kibana)是经典方案,Loki更轻量。现在很多云服务也自带日志功能。

监控:看系统健康不健康。Sentry专门追踪错误,谁的代码出错了第一时间知道。Prometheus + Grafana是看指标的,比如服务器CPU用了多少、数据库响应多快。

CI/CD:自动化部署。代码提交后自动测试、自动部署到服务器。GitHub Actions最常用,国内有阿里云效腾讯云CODING


安全 —— 保护你的应用

不做安全防护的应用,就像没装门的房子,谁都能进来。

前端安全:XSS是别人在你的页面里注入恶意脚本,CSRF是别人伪造你的身份发请求,CSP是限制页面能加载哪些资源。

后端安全:SQL注入是通过输入框往数据库里塞恶意代码,参数校验是确保用户传的数据是你期望的,Rate Limiting是限制一个人1分钟内只能发10次请求,防止被刷。

数据安全:HTTPS加密传输是最基本的,敏感数据(比如密码)要加密存储,密钥不要写在代码里。


AI能力 —— 新时代的必备技能

2026年了,如果你说自己是全栈但不懂 AI 用法,就像做前端不会用Git一样说不过去。

集成框架Vercel AI SDK是最流行的AI功能集成框架,支持流式响应(就是 ChatGPT 那种一个字一个字蹦出来的效果),对接各种模型很方便。

模型提供商:国外用OpenAI(GPT)、Anthropic(Claude),国内用硅基流动DeepSeek。国内外使用体验和成本差异很大,后面实战会分别讲。

向量数据库:AI场景专用。传统数据库存文字,向量数据库存「意思」。比如你搜「苹果」,它不仅能匹配到「苹果」,还能匹配到「iPhone」、「水果」,因为它理解「苹果」的含义。PineconeMilvus是代表。


这就是现代全栈的完整图谱。你不需要每样都精通,但需要知道它们各自负责什么,以及什么时候该用什么。


AI时代,全栈反而更重要了

我知道你可能会有疑问:现在AI这么强,Cursor敲几下代码就出来了,我还需要学全栈吗?

我的答案是:恰恰相反。

AI可以帮你写一个登录API,但它不知道:

  • 你的产品需不需要短信验证码登录
  • 你的用户数据存储在哪里
  • 你要不要支持微信登录
  • 登录失败几次要锁号
  • Token过期时间设多长

AI可以帮你写一个数据库查询,但它不知道:

  • 你的数据量级需要什么索引
  • 哪些查询需要加缓存
  • 读写分离怎么做

AI可以帮你部署上线,但它不知道:

  • 选择Vercel还是阿里云
  • 国内用户访问慢怎么办
  • 怎么做成本优化

AI擅长的是「点」,你需要的是「面」。

你告诉AI「帮我写个用户登录」,它会给你写一个标准答案。但具体怎么设计,这是你需要决策的事情。

而且,只有当你真正理解一个系统是怎么运转的,你才能:

  • 准确描述你想要什么(而不是永远在改需求)
  • 发现AI写的代码哪里有问题(而不是全盘接受)
  • 把不同模块组合在一起(而不是拼都拼不起来)

这才是整合能力的价值。

AI不是取代你,而是放大你。你原本只能做前端,AI帮你写了后端,你就能做全栈。但前提是,你本来就具备全栈思维,知道一个完整的产品需要什么。


怎么学?T型发展

说了这么多,到底怎么学?我的建议是「T型发展」:

先广度,后深度。

首先,对全栈技术有个整体认知。前端、后端、数据库、运维、安全……每个领域都了解一下,知道它们各自负责什么、解决什么问题。

这个阶段不需要深入,掌握概念就够了。

然后,选择一个方向深挖。

如果你对前端感兴趣,就深入React/Next.js。如果你对后端感兴趣,就深入Node.js/PostgreSQL。深入到能独立完成一个完整项目的程度。

最后,按需补充。

在实际项目中遇到什么问题,就去学什么。需要做支付,就去学Stripe。需要做搜索,就去学Elasticsearch。需要做 AI 功能,就去学Vercel AI SDK

这种「实战驱动」的学习方式,效率最高。


这个系列想带你做什么

市面上不缺技术教程。React入门、Node.js实战、Docker部署——这种内容一搜一大把。

但我发现很多人学完这些教程,还是做不出东西。

因为技术是散的,需要一条线把它们串起来。

这个系列我想带你做的事情很简单:从零开始,构建一个真正能上线的产品。

不是demo,不是练习,而是真实的、可访问的、能在生产环境跑的系统。

我会分成这几个阶段:

  • 第一阶段:认知重建

先理解全栈到底要学什么,怎么学(就是这篇)。

  • 第二阶段:基础设施

服务器、域名、CDN、Docker、日志、监控——那些「不太技术」但非常重要的东西。

  • 第三阶段:前端开发

React、Next.js、TypeScript、UI体系。

  • 第四阶段:后端开发

API设计、数据库、认证、缓存。

  • 第五阶段:AI集成

Vercel AI SDK、流式响应。

  • 第六阶段:部署上线

国内(阿里云)和国外(Vercel)两套方案。

  • 第七阶段:安全与性能

生产环境必须注意的那些事。

  • 第八阶段:实战

两个完整项目,从0到上线的全过程。

在这个过程中,你会看到我踩过的坑、做过的错误决策、总结出的经验。我不是为了告诉你「这个技术怎么用」,而是告诉你「这个系统该怎么搭」。


写在最后

回到开头的问题。

你是不是经常感觉学了很多技术,但真正要用的时候还是不知道从哪里开始?

这很正常。

技术本身不是目的,产品才是。

2026年了,AI 可以帮你写代码,但不能帮你交付产品。能做到这一点的人,永远有市场。

而这,就是我们这个系列要一起做的事情。

下一篇文章,我会讲讲AI辅助开发这件事——怎么用好CursorTraeOpenCode,以及一个更重要的道理:会问问题比会写代码更重要。

感兴趣的话,下一篇见。

AI 写代码总是半途而废?试试这个免费的工作流工具

作为一个用过多种 IDE 的开发者,我想分享一个让我效率 up up 的小工具。

你有没有遇到过这种情况?

  • 跟 AI 聊了半天需求,代码写了一半,上下文满了,AI "失忆"了
  • 项目做到一半搁置,一周后回来完全忘了做到哪了
  • 想加一个功能,结果 AI 把之前的代码改坏了

这些问题都有一个共同原因:上下文衰减(Context Rot)

简单来说,AI 的"记忆"是有限的。当对话太长时,它会慢慢忘掉之前说过的话,导致代码质量下降。

GSD 是什么?

GSD = Get Shit Done(把事做完)

它是一个开源的 AI 编程工作流框架,核心思路很简单:

把项目信息存到文件里,而不是全部塞给 AI。

就像你写代码会用 Git 做版本控制一样,GSD 帮你做"AI 对话的版本控制"。

GSD for Trae

原版 GSD 是为 Claude Code 设计的。因为我日常用 Trae,所以做了这个适配版本。

安装只需一行命令:

npx gsd-trae

或者:

bash <(curl -s https://raw.githubusercontent.com/Lionad-Morotar/get-shit-done-trae/main/install.sh)

它能帮你做什么?

1. 新项目规划

输入 /gsd:new-project,它会:

  • 问你一系列问题,搞清楚你要做什么
  • 自动研究技术方案(可选)
  • 生成项目路线图

2. 阶段式开发

大项目拆成小阶段:

  • /gsd:plan-phase 1 - 规划第一阶段
  • /gsd:execute-phase 1 - 执行第一阶段
  • /gsd:verify-work - 验证做得对不对

每完成一个阶段,进度都会被记录,随时可以接着做。

3. “断点续传”

关掉电脑、明天再来,输入 /gsd:progress,AI 马上知道:

  • 项目做到哪了
  • 接下来该做什么
  • 之前的决策是什么

实际使用感受

我用了一个月,相比 Trae 的 Plan Build 模式最明显的变化:

以前:一个功能聊到一半,AI 开始"胡言乱语",只能新开对话重来

现在:每个阶段都有清晰的目标和验收标准,AI 一直保持在正确的方向上

以前:同时开多个功能,代码互相冲突

现在:按阶段来,做完一个再做下一个,井井有条(进阶用户也可以选择 Worktree 模式)

以前:Plan 文档随意仍在 .trae 的文档目录,没有管理,很难查找

现在:结构化的目录,GSD 和开发者都能轻松阅读

适合谁用?

  • 用 Trae/Gemini/Claude 写代码的开发者
  • 做独立项目、 side project 的人
  • 觉得 AI 编程"聊不动"的新手

相比其他工具的优势

市面上有不少 AI 编程工作流工具,比如 GitHub 的 Spec Kit、OpenSpec、BMAD 等。GSD 的定位不太一样:

工具 特点 GSD 的区别
Spec Kit 企业级、严格阶段门控、30分钟启动 GSD 更轻量,5分钟上手,没有繁琐的仪式
OpenSpec 灵活快速、Node.js 运行 GSD 额外解决了 Context Rot 问题,支持断点续传
BMAD 21个 AI Agent、完整敏捷流程 GSD 不模拟团队,而是聚焦"让开发者高效完成项目"

简单说:如果你期待快速而结构化的流程,又不想被复杂的企业开发规范束缚的同时,确保 AI 编程能稳定输出,GSD 可能是目前最合适的选择。

它是免费的

开源项目,GitHub 地址: github.com/Lionad-Moro…

MIT 协议,可以随便用、随便改。

最后说一句

AI 编程工具越来越强大,但工具只是工具。

好的工作流能让你事半功倍,而 GSD 就是这样一套经过验证的工作流。

不需要改变你现有的开发习惯,安装后输入 /gsd:new-project 试试看。


如果你试过觉得好用,欢迎点个 Star ⭐

如果发现问题,也欢迎提 Issue

微信小程序自动化的 AI 新时代:wechat-devtools-mcp 智能方案

FliPPeDround

前端工程师 · 开源爱好者 · 正在找工作

对我的项目感兴趣?查看我的简历 · resume

如果你曾尝试配合 AI 代理(如 Claude、Cursor 编写微信小程序,你大概率会遇到这样的困境:测试工具与 AI 代理集成困难、缺乏统一的自动化框架支持、无法充分利用 AI 的智能分析能力。更糟糕的是,当你想要使用 Claude、Cursor 等 AI 辅助工具来提升测试效率时,却发现没有合适的微信小程序自动化集成方案。

为了解决这些痛点,wechat-devtools-mcp 应运而生。作为一款基于 MCP(Model Context Protocol)协议的微信开发者工具自动化服务,它让小程序的自动化测试与 AI 智能分析变得前所未有的简单和高效。

📖 介绍

📚 官方文档:更多详细的安装和配置说明,请参考 GitHub 仓库

wechat-devtools-mcp 是一个专门为微信小程序设计的 MCP 服务,通过 MCP 协议与 AI 代理(如 Claude、Cursor)深度集成。它基于微信官方的 miniprogram-automator 库,提供了完整的小程序自动化能力,让你能够在 AI 的辅助下,高效地完成小程序的自动化测试和调试。

这个工具的出现,填补了小程序自动化测试与 AI 智能分析之间的空白。它不仅保持了与微信开发者工具的完全兼容性,还充分发挥了 MCP 协议的标准化优势,为开发者提供了一个更智能、更高效的自动化测试解决方案。

🚀 核心功能与技术优势

1. 无缝集成 MCP 协议生态

wechat-devtools-mcp 完全兼容 MCP 协议,可以轻松集成到支持 MCP 的 AI 代理中:

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "wechat-devtools-mcp",
        "--projectPath=/path/to/your/miniprogram"
      ]
    }
  }
}

2. 全面的页面导航支持

工具提供了丰富的 API 来操作小程序页面导航:

  • 保留当前页面跳转:通过 navigateTo 跳转到非 tabBar 页面
  • 关闭当前页面跳转:通过 redirectTo 关闭当前页面并跳转
  • 返回上一页:通过 navigateBack 返回上一页面或多级页面
  • 重新加载页面:通过 reLaunch 关闭所有页面并重新打开
  • 切换 TabBar:通过 switchTab 跳转到 tabBar 页面
  • 获取页面栈:通过 pageStack 获取当前页面栈列表

3. 强大的元素操作能力

工具提供了完整的元素操作 API,支持各种用户交互模拟:

  • 元素获取:通过 getElementgetElements 获取页面元素
  • 用户交互:支持点击、长按、触摸、输入等操作
  • 元素信息:获取元素尺寸、位置、文本、属性、样式等信息
  • 组件方法:调用自定义组件的方法和数据操作

4. 智能日志和异常监听

工具内部实现了智能的日志和异常监听机制:

  • 自动监听控制台日志(console.log、console.info、console.warn、console.error)
  • 自动捕获运行时异常,包括错误名称、堆栈跟踪和发生时间
  • 支持日志和异常的查询和过滤
  • 内置日志数量限制,避免内存溢出

5. 灵活的配置选项

支持丰富的配置选项,满足不同测试场景的需求:

  • 自定义小程序项目路径
  • 微信开发者工具 CLI 路径配置
  • 连接超时时间设置
  • WebSocket 端口配置
  • 用户账号和登录票据支持
  • 项目配置文件覆盖

6. 微信 API 模拟与调用

工具提供了强大的微信 API 操作能力:

  • 调用微信 API:通过 callWxMethod 调用 wx 对象上的任意方法
  • Mock 微信 API:通过 mockWxMethod 模拟 API 返回值,便于测试
  • 恢复微信 API:通过 restoreWxMethod 恢复被 Mock 的方法

🧪 为什么 E2E 测试如此重要

在软件开发中,单元测试固然重要,但 E2E(End-to-End)测试在构建高质量代码过程中扮演着不可替代的角色。

提升代码可靠性

E2E 测试模拟真实用户的使用场景,从用户界面到后端服务的完整流程进行验证。与单元测试不同,E2E 测试能够发现:

  • 页面间的导航和状态传递问题
  • 用户交互与业务逻辑的集成异常
  • 微信 API 调用的错误处理
  • 不同设备和系统版本的兼容性问题

对于微信小程序这种运行在特殊环境中的应用,E2E 测试尤为重要。它能够确保你的小程序在不同设备、不同微信版本、不同网络环境下都能正常运行,避免出现"在开发环境正常,上线后出问题"的尴尬情况。

降低维护成本

虽然编写 E2E 测试 需要投入一定的时间成本,但从长远来看,它能显著降低维护成本:

  • 减少回归测试时间:自动化测试可以在几分钟内完成原本需要数小时的手动测试
  • 快速定位问题:当出现 bug 时,E2E 测试能够快速定位问题所在
  • 增强重构信心:有了完善的测试覆盖,你可以放心地进行代码重构,而不必担心破坏现有功能
  • 文档化业务逻辑:测试代码本身就是最好的业务逻辑文档

提升团队协作效率

E2E 测试作为项目质量的"守门员",能够:

  • 统一团队对功能实现的理解
  • 减少 code review 时的争议
  • 让新成员快速理解项目功能
  • 建立持续集成的质量保障体系

📦 快速上手

安装依赖

wechat-devtools-mcp 是一个 npm 包,可以直接通过 npx 运行,无需额外安装:

npx -y wechat-devtools-mcp --projectPath=/path/to/your/miniprogram

配置 MCP 服务器

在你的 AI 代理(如 Claude、Cursor)的配置文件中添加 MCP 服务器配置:

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "wechat-devtools-mcp",
        "--projectPath=/path/to/your/miniprogram"
      ]
    }
  }
}

命令行参数说明

参数 类型 说明
--projectPath string 小程序项目路径(必填)
--cliPath string 微信开发者工具 CLI 路径
--timeout number 连接超时时间(毫秒),默认 30000
--port number WebSocket 端口号,默认 9420
--account string 用户 openid
--ticket string 开发者工具登录票据
--projectConfig string 覆盖 project.config.json 中的配置

使用示例

配置完成后,你就可以在 AI 代理中使用 wechat-devtools-mcp 提供的工具了。以下是一些典型的使用场景:

1. 启动小程序

// 使用 launch 工具启动微信开发者工具并连接小程序
await launch()

2. 页面导航测试

// 跳转到指定页面
await navigateTo({ url: '/pages/detail/detail?id=123' })

// 获取当前页面信息
const currentPage = await currentPage()

// 返回上一页
await navigateBack({ delta: 1 })

3. 元素操作测试

// 获取页面元素
const element = await getElement({ selector: '.submit-button' })

// 点击元素
await tapElement({ selector: '.submit-button' })

// 输入文本
await inputElement({ selector: '#username', value: 'testuser' })

// 获取元素文本
const text = await getElementText({ selector: '.welcome-text' })

4. 页面数据操作

// 获取页面数据
const pageData = await getPageData({ path: 'userInfo.name' })

// 设置页面数据
await setPageData({ data: { count: 10, status: 'active' } })

5. 日志和异常监听

// 获取控制台日志
const logs = await getlogs({ type: 'error', limit: 10 })

// 获取异常信息
const exceptions = await getexceptions({ limit: 5 })

6. 微信 API 调用和 Mock

// 调用微信登录 API
const loginResult = await callWxMethod({ method: 'login', args: [] })

// Mock 用户信息 API
await mockWxMethod({ method: 'getUserInfo', result: { nickName: '测试用户' } })

// 恢复 API
await restoreWxMethod({ method: 'getUserInfo' })

🎯 高级功能详解

截图功能

工具支持对小程序当前页面进行截图,返回 Base64 编码的图片数据:

const screenshot = await screenshot()

系统信息获取

获取小程序运行所在的系统信息,包括手机品牌、型号、屏幕尺寸、操作系统版本、微信版本等:

const systemInfo = await systemInfo()

体验评分

支持微信小程序体验评分(Audits)功能,可以获取性能最佳实践、Accessibility 可访问性等方面的评分和建议:

// 停止体验评分并获取报告
const auditResult = await stopAudits({ path: './audits.json' })

测试账号管理

支持获取微信开发者工具多账号调试中添加的测试用户列表,可用于模拟不同用户登录场景的测试:

const accounts = await testAccounts()

🔧 技术实现细节

wechat-devtools-mcp 的实现基于 MCP 协议和微信官方的 miniprogram-automator 库,核心架构包括以下几个部分:

  1. Automator 类:负责微信开发者工具的启动、连接和生命周期管理
  2. MiniProgram 工具类:提供小程序级别的操作,如页面导航、API 调用、系统信息获取等
  3. Page 工具类:提供页面级别的操作,如元素获取、数据操作、方法调用等
  4. Element 工具类:提供元素级别的操作,如点击、输入、属性获取等

工具内部还实现了智能的状态管理和错误处理机制,确保自动化测试的稳定性和可靠性。

🌟 总结

wechat-devtools-mcp 为微信小程序开发者提供了一个现代化、智能化的自动化测试解决方案。它不仅解决了传统测试工具与 AI 代理集成困难的问题,还充分发挥了 MCP 协议和 miniprogram-automator 的技术优势。

通过完善的 E2E 测试和 AI 智能分析,你可以:

  • 提升代码质量和可靠性
  • 降低长期维护成本
  • 增强团队协作效率
  • 建立持续集成的质量保障体系
  • 充分利用 AI 的智能分析能力

如果你正在开发微信小程序项目,并且想要建立完善的自动化测试体系,wechat-devtools-mcp 绝对值得一试。它会让你的测试工作变得前所未有的简单和高效。

📚 相关资源


最后

wechat-devtools-mcp 是一个免费的开源软件,遵循MIT协议,社区的赞助使其能够有更好的发展。

你的赞助会帮助我更好的维护项目,如果对你有帮助,请考虑赞助一下😊

你的star🌟也是对我的很大鼓励,Github

欢迎反馈问题和提pr共建

2025前端技术趋势:从智能到沉浸的新时代

引言

前端技术正处于一个前所未有的快速发展阶段。从早期的静态网页到如今的复杂单页应用,前端开发已经经历了多次重大变革。随着WebAssembly、人工智能、虚拟现实等技术的不断成熟,2025年的前端技术将进入一个全新的时代。在这个新时代,前端开发者需要掌握的技能不再局限于HTML、CSS和JavaScript。他们需要了解WebAssembly、机器学习、3D渲染等跨领域技术,并能够将这些技术有机地结合,创造出前所未有的用户体验。

1. WebAssembly 3.0:突破Web性能极限

WebAssembly(Wasm)自2017年推出以来,已经成为前端性能优化的重要工具。2025年,WebAssembly 3.0将带来一系列重大改进,进一步突破Web应用的性能极限。

1.1 架构演进

image.png

1.2 WebAssembly 3.0 核心特性

WebAssembly 3.0将引入以下核心特性:

  • 增强的垃圾回收支持:更高效的内存管理,减少内存泄漏和性能问题

  • 原生DOM访问:直接操作DOM,消除JavaScript桥接开销

  • 多线程与并行计算:更强大的并行处理能力,支持复杂计算任务

  • WASI 2.0:更完善的WebAssembly系统接口,支持更多系统级功能

1.3 性能对比

WebAssembly 3.0在性能方面将有显著提升:

image.png

1.4 应用场景

WebAssembly 3.0将在以下场景中发挥重要作用:

  1. 复杂数据可视化:处理大规模数据并实时渲染

  2. 游戏开发:创建接近原生性能的Web游戏

  3. 音视频处理:实时编解码和特效处理

  4. 科学计算:在浏览器中运行复杂算法

  5. 3D建模 与渲染:支持复杂的3D场景和模型

2. AI原生前端框架:智能交互的新范式

2025年,前端框架将深度集成人工智能技术,形成AI原生前端框架。这些框架将能够理解用户意图,自动优化性能,并提供更加智能的用户体验。

2.1 AI原生框架核心特性

AI原生前端框架将具备以下核心特性:

  • 智能组件:能够根据用户行为自动调整UI和功能

  • 预测渲染:预测用户下一步操作并提前渲染

  • 自适应布局:根据设备、用户偏好和上下文自动调整布局

  • 智能性能优化:自动识别和优化性能瓶颈

  • 自然语言交互:支持语音和文本的自然语言界面

2.2 架构设计

image.png

2.3 智能组件示例

以下是一个AI原生前端框架中的智能组件示例:

// AI原生组件示例
import { SmartComponent } from 'ai-frontend-framework';

class AdaptiveButton extends SmartComponent {
  constructor(props) {
    super(props);
    this.state = {
      variant: 'primary',
      size: 'medium'
    };
  }
  
  // AI驱动的自适应逻辑
  async adaptToUserContext() {
    const userBehavior = await this.aiContext.getUserBehavior();
    const deviceInfo = await this.aiContext.getDeviceInfo();
    
    // 根据用户行为调整按钮样式
    if (userBehavior.clickSpeed > 5) {
      this.setState({ size: 'large' });
    }
    
    // 根据设备类型调整按钮变体
    if (deviceInfo.type === 'mobile') {
      this.setState({ variant: 'secondary' });
    }
    
    // 预测用户操作并提前加载资源
    if (userBehavior.predictedAction === 'submit') {
      this.aiContext.preloadResource('/api/submit');
    }
  }
  
  render() {
    return (
      <button 
        variant={this.state.variant}
        size={this.state.size}
        onClick={this.props.onClick}
        onMouseEnter={this.adaptToUserContext}
      >
        {this.props.children}
      </button>
    );
  }
}

2.4 应用场景

AI原生前端框架将在以下场景中得到广泛应用:

  1. 个性化用户体验:根据用户行为和偏好自动调整界面

  2. 智能表单:自动填充、验证和优化表单流程

  3. 预测性加载:预测用户下一步操作并提前加载内容

  4. 无障碍设计:自动适配不同用户的无障碍需求

  5. 实时数据可视化:智能分析和展示数据趋势

3. 沉浸式Web体验:从2D到3D的转变

2025年,Web将从平面的2D体验向沉浸式的3D体验转变。随着WebXR、WebGL 2.0和WebGPU的不断成熟,浏览器将能够提供接近原生的3D和虚拟现实体验。

3.1 核心技术栈

沉浸式Web体验的核心技术栈包括:

  • WebXRAPI:支持虚拟现实(VR)和增强现实(AR)体验

  • WebGL 2.0:高性能3D图形渲染

  • WebGPU:下一代图形API,提供更好的性能和功能

  • Three.js/Rapier.js:成熟的3D库和物理引擎

3.2 架构设计

image.png

3.3 应用场景

沉浸式Web体验将在以下场景中得到广泛应用:

  1. 虚拟会议与协作:创建沉浸式的远程会议空间

  2. 在线教育:提供交互式的3D学习体验

  3. 虚拟购物:允许用户在虚拟环境中试穿和体验产品

  4. 虚拟旅游:提供沉浸式的虚拟旅游体验

  5. 工业设计与原型:在浏览器中进行3D设计和原型开发

4. 去中心化前端架构:Web3的新范式

随着Web3技术的不断发展,2025年将出现去中心化前端架构,彻底改变前端应用的部署和运行方式。

4.1 核心概念

去中心化前端架构的核心概念包括:

  • 去中心化存储:使用IPFS、Arweave等去中心化存储协议

  • 智能合约集成:直接与区块链上的智能合约交互

  • 去中心化身份(DID) :用户控制自己的身份和数据

  • 零信任安全:基于区块链的安全模型

4.2 架构设计

image.png

4.3 开发示例

以下是一个基于去中心化前端架构的应用示例:

// 去中心化前端应用示例
import { createDApp } from 'decentralized-frontend-framework';
import { ethers } from 'ethers';
import { create } from 'ipfs-http-client';

// 连接到IPFS
const ipfs = create('https://ipfs.infura.io:5001/api/v0');

// 连接到以太坊区块链
const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();

// 初始化DApp
const dapp = createDApp({
  ipfs,
  provider,
  signer,
  contracts: {
    myContract: {
      address: '0x1234567890abcdef1234567890abcdef12345678',
      abi: [...]
    }
  }
});

// 从IPFS加载内容
async function loadContent(cid) {
  const content = await dapp.ipfs.get(cid);
  return content;
}

// 与智能合约交互
async function interactWithContract() {
  const contract = dapp.contracts.myContract;
  const result = await contract.functions.myFunction();
  return result;
}

// 保存数据到IPFS并记录到区块链
async function saveData(data) {
  const { cid } = await dapp.ipfs.add(data);
  const transaction = await dapp.contracts.myContract.functions.saveData(cid.toString());
  await transaction.wait();
  return cid;
}

// 渲染应用
function renderApp() {
  return (
    <DAppProvider dapp={dapp}>
      <App />
    </DAppProvider>
  );
}

4.4 应用场景

去中心化前端架构将在以下场景中得到广泛应用:

  1. 去中心化金融(DeFi) :构建安全、透明的金融应用

  2. 数字身份管理:用户控制自己的身份和数据

  3. 内容创作与分发:消除中间商,直接连接创作者和用户

  4. 供应链管理:构建透明、可追溯的供应链系统

  5. 去中心化社交网络:用户控制自己的社交数据和关系

5. 量子计算在前端的初步应用

随着量子计算技术的不断发展,2025年量子计算将开始在前端领域得到初步应用,为前端开发带来新的可能性。

5.1 核心概念

量子计算在前端的应用基于以下核心概念:

  • 量子算法:利用量子力学特性解决复杂问题

  • 量子机器学习:结合量子计算和机器学习

  • 量子安全:基于量子力学的安全加密

  • 量子云服务:通过云服务访问量子计算机

5.2 应用示例

以下是一个使用量子计算的前端应用示例:

// 量子计算前端应用示例
import { QuantumSDK } from 'quantum-frontend-sdk';
import { QuantumMachineLearning } from 'quantum-ml';

// 初始化量子SDK
const quantumSDK = new QuantumSDK({
  apiKey: 'your-quantum-cloud-api-key',
  provider: 'ibm-quantum'
});

// 创建量子机器学习模型
const qml = new QuantumMachineLearning(quantumSDK);

// 训练量子模型
async function trainQuantumModel(data) {
  // 准备量子数据
  const quantumData = await qml.prepareData(data);
  
  // 选择量子算法
  const algorithm = qml.selectAlgorithm('quantum-kernel');
  
  // 训练模型
  const model = await qml.train(quantumData, algorithm);
  
  return model;
}

// 使用量子模型进行预测
async function predictWithQuantumModel(model, input) {
  // 准备输入数据
  const quantumInput = await qml.prepareData(input);
  
  // 进行量子预测
  const result = await qml.predict(model, quantumInput);
  
  // 转换结果为经典数据
  const classicResult = qml.toClassic(result);
  
  return classicResult;
}

// 量子安全加密
async function encryptDataWithQuantumSecurity(data, publicKey) {
  // 使用量子密钥分发生成安全密钥
  const secureKey = await quantumSDK.generateQuantumKey();
  
  // 使用安全密钥加密数据
  const encryptedData = quantumSDK.encrypt(data, secureKey);
  
  // 使用公钥加密安全密钥
  const encryptedKey = quantumSDK.encrypt(secureKey, publicKey);
  
  return { encryptedData, encryptedKey };
}

// 渲染应用
function renderApp() {
  return (
    <QuantumProvider sdk={quantumSDK}>
      <App 
        trainModel={trainQuantumModel}
        predict={predictWithQuantumModel}
        encryptData={encryptDataWithQuantumSecurity}
      />
    </QuantumProvider>
  );
}

5.3 应用场景

量子计算在前端的初步应用将包括:

  1. 量子机器学习:处理复杂的机器学习任务,如图像识别、自然语言处理

  2. 量子安全:提供更安全的加密和认证机制

  3. 优化问题:解决复杂的优化问题,如路径规划、资源分配

  4. 模拟与仿真:进行复杂的物理、化学模拟

  5. 数据分析:处理大规模数据集

6. 总结

2025年的前端技术进入一个全新的时代,从智能到沉浸,从中心化到去中心化,从经典计算到量子计算。这些技术的发展将彻底改变前端开发的方式和前端应用的能力。作为前端开发者,我们需要不断学习和适应这些变化,掌握新的技术和工具,以创造出更加智能、沉浸、安全和高效的用户体验。只有这样,我们才能在未来的前端开发领域保持竞争力,为用户创造出真正有价值的产品和服务。

未来的前端世界充满了无限可能,让我们一起拥抱这个新时代,共同创造更加美好的数字未来!

7. 参考文献

  1. WebAssembly 3.0 官方文档
  2. AI原生前端框架白皮书
  3. WebXR API 规范
  4. IPFS 官方文档
  5. 量子计算在前端的应用
  6. Web3 前端开发指南
  7. Three.js 文档
  8. 前端性能优化最佳实践

8. 团队介绍

智慧家技术平台-应用软件框架开发」主要负责设计工具的研发,包括营销设计工具、家电VR设计和展示、水电暖通前置设计能力,研发并沉淀素材库,构建家居家装素材库,集成户型库、全品类产品库、设计方案库、生产工艺模型,打造基于户型和风格的AI设计能力,快速生成算量和报价;同时研发了门店设计师中心和项目中心,包括设计师管理能力和项目经理管理能力。实现了场景全生命周期管理,同时为水,空气,厨房等产业提供商机管理工具,从而实现了以场景贯穿的B端C端全流程系统。

Claude Code 构建完全指南:十大核心功能深度解析

一、创建自定义子代理(Subagents)

1. 是什么

子代理是运行在独立上下文窗口中的专用 AI 助手。每个子代理拥有自己的系统提示、工具访问权限和权限设置。当 Claude 遇到与某个子代理描述匹配的任务时,会自动将任务委派给该子代理,子代理独立工作并返回结果。Claude Code 内置了 Explore(只读代码搜索,使用 Haiku 模型)、Plan(计划模式研究代理)和 general-purpose(全工具通用代理)等子代理,用户也可以创建自定义子代理。

2. 怎么用

创建子代理最简单的方式是在 Claude Code 中运行 /agents 命令,进入交互式界面选择"Create new agent",然后选择作用域(用户级或项目级),输入描述后由 Claude 自动生成配置。也可以手动创建 Markdown 文件,放在 .claude/agents/(项目级)或 ~/.claude/agents/(用户级)目录中:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Analyze the code and provide actionable feedback.

还可以通过 CLI 标志以 JSON 传递临时子代理:

claude --agents '{ "code-reviewer": { "description": "Expert code reviewer.", "prompt": "Focus on code quality and security.", "tools": ["Read","Grep","Glob","Bash"], "model": "sonnet" } }'

3. 使用场景与痛点

子代理解决的核心痛点是主对话上下文膨胀和工具权限失控。典型场景包括:运行测试套件时大量输出占用上下文(委派给子代理后只返回摘要)、需要对代码库进行并行研究(多个子代理同时探索不同模块)、需要强制只读权限(如代码审查只允许读不允许写)、多步骤工作流的链式委派(先审查再优化),以及通过路由到 Haiku 模型来控制 Token 成本。

4. 使用示例

入门示例——只读代码审查器:

---
name: code-reviewer
description: Expert code review specialist. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. Run git diff, focus on modified files, check for readability, error handling, security, and test coverage. Organize feedback by priority: Critical, Warnings, Suggestions.

使用时只需说:"Use the code-reviewer subagent to look at my recent changes."

进阶示例——带持久化记忆的调试器:

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
memory: user
---
You are an expert debugger. Capture error messages, identify reproduction steps, isolate failure location, implement minimal fix, verify solution. Before starting, consult your memory for patterns you've seen before. After fixing, save what you learned.

记忆功能使调试器跨会话积累知识——它会记住之前遇到的 bug 模式和修复策略,随着使用越来越高效。

高级最佳实践——带 Hook 验证的数据库查询代理:

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---
You are a database analyst with read-only access. Execute SELECT queries only.

配合验证脚本,通过 Hook 在每个 Bash 命令执行前检查是否包含 INSERT/UPDATE/DELETE 等写操作,退出码 2 阻止执行。这是"工具级允许、操作级限制"的精细控制模式。其他高级实践包括:使用 skills 字段预加载团队编码规范、用 isolation: worktree 在独立 git worktree 中运行子代理避免影响主分支、用 Task(worker, researcher) 语法限制主代理只能生成特定子代理。

5. 适用角色

个人开发者: 创建用户级子代理(~/.claude/agents/)用于个人常用任务,如代码审查、调试、日志分析。推荐从 /agents 交互式界面入手,用 Haiku 模型的 Explore 子代理快速搜索代码库以节省成本。

团队开发者: 创建项目级子代理(.claude/agents/)并提交到版本控制。统一团队的代码审查标准、API 开发规范。使用 skills 字段预加载团队编码规范,确保每个成员使用的子代理行为一致。

Tech Lead / 架构师: 设计子代理体系——为不同任务领域(前端、后端、数据库、安全)创建专门的子代理,使用权限模式和工具限制确保安全边界。利用 memory: project 让子代理积累项目架构知识。

DevOps / CI 工程师: 通过 --agents CLI 标志在自动化脚本和 CI/CD 流水线中动态定义子代理,用于自动化测试、代码扫描、构建验证等。结合 bypassPermissions 模式实现全自动化执行。


二、运行代理团队(Agent Teams)

1. 是什么

代理团队是一项实验性功能,允许多个独立的 Claude Code 实例协同工作。一个会话充当"团队负责人"(Lead),协调工作、分配任务和综合结果;其他"团队成员"(Teammates)各自拥有独立的上下文窗口,可以直接相互通信、挑战彼此的发现。与子代理的关键区别是:子代理只能向主代理报告结果,而代理团队成员之间可以直接发送消息和协作。

2. 怎么用

首先需要启用实验性功能,在 settings.json 中添加:

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

然后用自然语言告诉 Claude 创建团队:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

Claude 会创建团队、生成共享任务列表、生成成员并协调工作。在进程内模式中用 Shift+Down 切换成员;在分屏模式中(需 tmux 或 iTerm2)每个成员有独立窗格。用 Ctrl+T 切换任务列表视图。

3. 使用场景与痛点

代理团队解决的核心痛点是单一会话的线性工作模式无法高效处理需要并行探索的复杂任务。最强场景包括:并行代码审查(安全、性能、测试覆盖各一个审查员,避免单个审查员的视角偏见)、竞争假设调试(多个成员调查不同理论并相互辩论反驳,避免锚定效应)、新功能多模块开发(每个成员负责一个独立模块不会冲突)以及跨层协调(前端、后端、测试各由不同成员负责)。

不适合的场景:顺序任务、同文件编辑、依赖关系多的工作——这些情况下单会话或子代理更高效。

4. 使用示例

入门示例——并行代码审查:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

每个审查员从不同角度审查同一个 PR,Lead 综合所有发现。

进阶示例——竞争假设调试:

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses.
Have them talk to each other to try to disprove each other's theories,
like a scientific debate. Update the findings doc with whatever consensus emerges.

辩论式结构是关键——多个独立调查者主动尝试推翻对方的理论,幸存的理论更可能是真正的根因。

高级最佳实践:

要求成员在实施前提交计划审批:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

成员以只读计划模式工作,提交计划后由 Lead 审批或驳回。可以通过提示影响 Lead 的判断标准,如"只批准包含测试覆盖的计划"。其他高级实践包括:使用 TeammateIdle 和 TaskCompleted Hook 实施质量门禁、保持 3-5 个成员和每人 5-6 个任务的最佳比例、给成员充足的上下文(spawn 提示中包含具体的任务细节而非依赖继承)。

5. 适用角色

个人开发者: 从研究和审查任务开始尝试——审查一个 PR、研究一个库、调查一个 bug。这些任务展示并行探索的价值,又没有并行实施的协调挑战。

团队 Lead / 项目经理: 用代理团队进行全方位的代码审查、架构评估和技术方案论证。通过设定审批流程(require plan approval)控制实施质量。

高级工程师: 用于复杂调试(竞争假设模式)、跨模块重构(每个成员负责一个模块)和大规模代码迁移(并行处理不同组件)。注意 Token 消耗——代理团队的成本随成员数线性增长。

注意: 代理团队目前是实验性功能,不建议在关键生产流程中使用。已知限制包括不支持进程内成员的会话恢复、任务状态可能滞后、每个会话只能管理一个团队。


三、创建插件(Plugins)

1. 是什么

插件是 Claude Code 的打包扩展机制,将技能、代理、钩子、MCP 服务器和 LSP 服务器封装成可分发的单元。每个插件有一个 .claude-plugin/plugin.json 清单文件定义元数据,以及按功能组织的目录结构。插件的技能使用命名空间(/plugin-name:skill-name)来避免多插件之间的冲突。

与独立配置(.claude/ 目录中的文件)相比,插件更适合需要跨项目、跨团队共享的场景——独立配置适合个人实验和项目专属定制,插件适合版本化发布和市场分发。

2. 怎么用

创建插件的步骤:

# 1. 创建插件目录和清单
mkdir -p my-plugin/.claude-plugin
# 2. 编写 plugin.json
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{ "name": "my-plugin", "description": "My extension", "version": "1.0.0" }
EOF
# 3. 添加技能
mkdir -p my-plugin/skills/hello
cat > my-plugin/skills/hello/SKILL.md << 'EOF'
---
description: Greet the user with a friendly message
---
Greet the user warmly and ask how you can help.
EOF
# 4. 本地测试
claude --plugin-dir ./my-plugin

在 Claude Code 中运行 /my-plugin:hello 即可使用。可以用 --plugin-dir 标志同时加载多个插件进行测试。

3. 使用场景与痛点

插件解决的核心痛点是扩展功能的碎片化和不可共享。典型场景包括:团队统一工具链(所有成员通过安装同一插件获得相同的代码审查代理、提交工作流和格式化钩子)、社区分享(将自己开发的有用扩展发布到市场让其他人安装)、跨项目复用(一套检查规则不需要在每个项目中重新配置)、以及版本化管理(通过语义化版本号追踪发布和更新)。

4. 使用示例

入门示例——包含一个技能的插件:

创建一个 greeting 插件,包含一个 hello 技能。目录结构:greeting/.claude-plugin/plugin.json + greeting/skills/hello/SKILL.md。使用 claude --plugin-dir ./greeting 加载,然后运行 /greeting:hello Alex 测试。

进阶示例——包含代理、钩子和 LSP 的完整插件:

my-team-plugin/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── security-reviewer.md      # 安全审查代理
├── skills/
│   └── code-review/
│       └── SKILL.md               # 代码审查技能
├── hooks/
│   └── hooks.json                 # PostToolUse 自动格式化
├── .mcp.json                      # 集成 GitHub MCP 服务器
├── .lsp.json                      # TypeScript LSP 配置
└── settings.json                  # 默认设置 {"agent": "security-reviewer"}

设置 settings.json 中的 agent 字段可以让插件在启用时自动激活指定代理作为默认行为。

高级最佳实践:

从独立配置迁移到插件:将 .claude/commands/.claude/agents/.claude/skills/ 的文件复制到插件目录,将 settings.json 中的 hooks 迁移到 hooks/hooks.json,然后用 --plugin-dir 验证一切正常。发布前为插件添加 README.md,使用语义化版本号。注意:不要把 commands/agents/ 等目录放在 .claude-plugin/ 里面——只有 plugin.json 放在 .claude-plugin/ 中,其他目录在插件根目录。

5. 适用角色

个人开发者: 先用 .claude/ 目录中的独立配置快速实验,等稳定后再转为插件以跨项目复用。适合创建个人的提交工作流、代码模板等。

团队 Lead / 平台工程师: 为团队创建统一的插件,包含编码规范技能、代码审查代理和自动格式化钩子。通过项目的 .claude/settings.json 配置团队市场,让新成员加入时自动获取团队插件。

开源 / 社区贡献者: 创建通用插件(如 commit-commands、pr-review-toolkit)并发布到市场,供社区使用。遵循清晰的目录结构和版本号规范。

企业 IT 管理员: 通过托管设置(managed settings)部署组织级插件,确保合规性审查工具和安全检查在所有项目中强制启用。


四、发现和安装预构建插件

1. 是什么

插件市场(Marketplace)是帮助用户发现和安装 Claude Code 扩展的目录。市场本质上是一个包含 .claude-plugin/marketplace.json 的仓库或文件,列出了可供安装的插件集合。Anthropic 官方市场(claude-plugins-official)自动可用,包含代码智能(LSP)、外部集成(GitHub/Slack/Jira 等)、开发工作流和输出风格等类别的插件。用户也可以添加第三方市场或创建团队私有市场。

2. 怎么用

# 浏览官方市场
/plugin                             # 打开插件管理器,进入 Discover 标签

# 安装插件
/plugin install typescript-lsp@claude-plugins-official

# 添加第三方市场
/plugin marketplace add anthropics/claude-code        # GitHub 仓库
/plugin marketplace add https://gitlab.com/company/plugins.git  # Git URL
/plugin marketplace add ./my-marketplace              # 本地路径

# 管理插件
/plugin disable plugin-name@marketplace-name          # 禁用
/plugin enable plugin-name@marketplace-name           # 启用
/plugin uninstall plugin-name@marketplace-name        # 卸载

# 管理市场
/plugin marketplace list                              # 列出所有市场
/plugin marketplace update marketplace-name           # 刷新
/plugin marketplace remove marketplace-name           # 移除(会卸载其中的插件)

插件安装有三种作用域:用户(跨所有项目)、项目(通过 .claude/settings.json 共享给协作者)和本地(仅当前用户当前仓库)。

3. 使用场景与痛点

插件市场解决的核心痛点是手动配置外部工具的复杂性和团队配置不一致。安装代码智能插件后,Claude 在每次编辑后自动获得类型错误、缺失导入等诊断反馈,无需手动运行编译器。安装外部集成插件(GitHub、Jira、Slack)后,Claude 可以直接与这些服务交互,无需手动配置 MCP 服务器。团队管理员可以在 .claude/settings.json 中配置 extraKnownMarketplacesenabledPlugins,让团队成员信任仓库后自动安装指定市场和插件。

4. 使用示例

入门示例——安装代码智能插件:

/plugin install typescript-lsp@claude-plugins-official

安装后,Claude 在编辑 TypeScript 文件时自动获得类型检查——如果引入错误会立即发现并在同一轮修复。按 Ctrl+O 可以内联查看诊断信息。前提:系统需安装对应的语言服务器二进制文件(如 typescript-language-server)。

进阶示例——添加外部集成和工作流插件:

# 安装 GitHub 集成
/plugin install github@claude-plugins-official
# 安装提交工作流
/plugin install commit-commands@claude-plugins-official

之后可以直接说"Review PR #456 and suggest improvements"或使用 /commit-commands:commit 一键暂存、生成消息、创建提交。

高级最佳实践:

配置团队市场自动安装:在项目的 .claude/settings.json 中添加 extraKnownMarketplacesenabledPlugins,让团队成员加入项目时自动获取。启用自动更新以保持插件版本最新(官方市场默认启用,第三方默认禁用)。如果需要禁用 Claude Code 自动更新但保持插件更新,可设置 DISABLE_AUTOUPDATER=trueFORCE_AUTOUPDATE_PLUGINS=true

5. 适用角色

所有开发者: 安装代码智能插件是最基础的增强——给 Claude 实时的类型错误和语法问题反馈,减少编辑后需要手动编译验证的次数。

全栈开发者: 安装外部集成插件(GitHub、Slack、Figma、数据库),让 Claude 能直接从 issue 描述实现功能、集成设计稿、查询数据库。

团队管理员: 配置团队市场,确保所有成员使用相同的插件和版本。通过项目级安装(--scope project)将插件配置提交到版本控制。

初学者: 从 Discover 标签浏览可用插件,安装 learning-output-style 或 explanatory-output-style 获得更好的学习体验。


五、使用技能扩展 Claude(Skills)

1. 是什么

技能(Skills)是通过 SKILL.md 文件为 Claude 添加的指令和能力扩展。技能遵循 Agent Skills 开放标准,可以是参考知识(编码规范、API 文档),也可以是具体任务(部署流程、提交规范)。Claude 可以根据任务上下文自动加载相关技能,用户也可以通过 /skill-name 直接调用。

技能与子代理的区别:技能默认在主对话上下文中运行(共享上下文),子代理在隔离的上下文中运行。技能适合需要共享对话历史的场景,子代理适合需要隔离的场景。

2. 怎么用

创建技能目录和 SKILL.md 文件:

mkdir -p ~/.claude/skills/explain-code

编写 ~/.claude/skills/explain-code/SKILL.md

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works.
---
When explaining code, always include:
1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow
3. **Walk through the code**: Explain step-by-step
4. **Highlight a gotcha**: What's a common mistake?

两种使用方式:让 Claude 自动识别("How does this code work?")或直接调用(/explain-code src/auth/login.ts)。

3. 使用场景与痛点

技能解决的核心痛点是重复的指令输入和行为不一致。没有技能时,每次需要 Claude 按特定方式工作都要重新描述需求;有了技能,一次编写,反复使用。典型场景包括:团队编码规范强制执行(API 设计模式、错误处理模式作为参考技能自动加载)、标准化操作流程(部署、提交、PR 创建作为任务技能由用户触发)、自定义代码生成模板(组件创建、测试编写遵循固定结构),以及跨项目知识复用(个人级技能在所有项目中可用)。

4. 使用示例

入门示例——参考型技能(API 规范):

---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats: { "error": { "code": "...", "message": "..." } }
- Include request validation with Zod schemas
- Always add rate limiting middleware

Claude 在实现 API 时会自动加载这个技能,确保遵循团队约定。

进阶示例——带参数和动态上下文的任务技能:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.

## Issue context
- Issue details: !`gh issue view $0 --json title,body,labels`
- Recent commits: !`git log --oneline -5`

## Steps
1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

使用 /fix-issue 123 时,!command 语法预先执行 shell 命令获取实时数据,$0 替换为第一个参数。disable-model-invocation: true 确保只有用户手动触发。

高级最佳实践——在子代理中运行技能 + 可视化输出:

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

context: fork 使技能在隔离的 Explore 子代理中运行,不影响主对话。另一个强大模式是生成可视化输出——技能中捆绑 Python 脚本生成交互式 HTML 文件用于数据探索。其他高级实践:使用 allowed-tools 限制技能中 Claude 可用的工具、用 Skill(commit) / Skill(deploy *) 权限规则精细控制哪些技能 Claude 可以自动调用、SKILL.md 控制在 500 行内并将详细参考材料拆分到辅助文件中。

5. 适用角色

个人开发者: 创建用户级技能(~/.claude/skills/)封装个人工作习惯——自定义提交格式、代码解释风格、调试流程。用 disable-model-invocation: true 保护有副作用的操作(如部署)。

团队开发者: 创建项目级技能(.claude/skills/)并提交到版本控制,统一团队的 API 设计模式、错误处理方式、测试编写规范。新成员无需阅读长篇文档,Claude 自动遵循。

技术培训师 / 导师: 创建教学型技能(如 explain-code),让 Claude 始终用类比、图表和分步讲解的方式解释代码,帮助初级开发者学习。

平台工程师: 通过插件分发技能、通过企业托管设置强制加载组织级技能,确保合规性检查和安全扫描在所有项目中自动执行。


六、输出风格(Output Styles)

1. 是什么

输出风格直接修改 Claude Code 的系统提示,改变 Claude 的响应方式——包括格式、语调和结构。与 CLAUDE.md(作为附加的用户消息)和 --append-system-prompt(追加到系统提示末尾)不同,输出风格会关闭 Claude Code 默认系统提示中与软件工程相关的部分,用自定义指令替代。Claude Code 内置三种风格:默认(高效完成软件工程任务)、解释性(在工作中穿插教育性"洞察")、学习(协作式学做模式,用 TODO(human) 标记让用户自己写代码)。

2. 怎么用

# 交互式选择
/output-style

# 直接切换到指定风格
/output-style explanatory
/output-style learning

创建自定义输出风格,保存为 Markdown 文件到 ~/.claude/output-styles/(用户级)或 .claude/output-styles/(项目级):

---
name: My Custom Style
description: A brief description
keep-coding-instructions: false
---
# Custom Style Instructions
You are an interactive CLI tool that helps users with software engineering tasks.
[Your custom instructions...]

keep-coding-instructions: true 可以保留 Claude Code 默认的编码相关系统提示(如"用测试验证代码")。

3. 使用场景与痛点

输出风格解决的核心痛点是 Claude 的响应方式与用户需求不匹配。有些人需要简洁的执行结果,有些人需要详细的解释以学习。典型场景包括:初学者学习模式(learning 风格让 Claude 不仅写代码还要求你自己实践)、教学演示(explanatory 风格在每个实现决策后插入背景知识)、非软件工程任务(关闭默认的编码指令,让 Claude 专注于写作、分析等)、团队统一输出格式(通过项目级输出风格确保所有人看到相同格式的响应)。

4. 使用示例

入门示例——切换到学习模式:

/output-style learning

切换后,Claude 在帮你完成任务时会添加 TODO(human) 标记,要求你自己实现关键部分,同时分享"洞察"帮助你理解为什么这样做。

进阶示例——创建自定义架构师风格:

---
name: architect
description: Respond with architecture-first thinking. Always discuss trade-offs before implementing.
keep-coding-instructions: true
---
# Architect Mode
Before writing any code:
1. Identify the architectural implications
2. List alternative approaches with trade-offs
3. Recommend an approach with justification
4. Only implement after the user approves

Always think about: scalability, maintainability, testability, and security.
Use diagrams (ASCII art) to illustrate architecture decisions.

高级最佳实践:

理解输出风格与其他扩展机制的区别非常重要:输出风格修改系统提示、始终生效;技能是按需加载的任务指令;CLAUDE.md 是始终存在的上下文补充。最佳实践是用输出风格控制"Claude 如何说",用技能控制"Claude 做什么",用 CLAUDE.md 提供"Claude 需要知道什么"。变更保存在 .claude/settings.local.json,也可直接编辑其他级别设置文件中的 outputStyle 字段。

5. 适用角色

初学者 / 学生: 使用 learning 风格,让 Claude 变成交互式编程导师——不仅帮你写代码,还要求你自己实践关键部分,加速学习。

经验开发者: 使用默认风格或创建极简自定义风格,获得简洁高效的输出,减少冗余解释。

技术 Lead / 导师: 使用 explanatory 风格或创建架构师风格,在代码审查和设计讨论时获得详细的决策背景和权衡分析。

非工程人员(产品、设计): 创建自定义输出风格关闭编码指令,让 Claude 专注于文档编写、数据分析或项目管理任务。


七、使用钩子自动化工作流(Hooks)

1. 是什么

钩子(Hooks)是在 Claude Code 生命周期特定节点执行的用户定义 shell 命令,提供确定性的行为控制——确保某些操作始终发生,而非依赖 LLM 的判断。钩子支持丰富的事件类型:SessionStart(会话开始/恢复/压缩后)、PreToolUse(工具执行前,可阻止)、PostToolUse(工具执行后)、Notification(通知时)、Stop(Claude 完成响应时)、ConfigChange(配置变更时)等。除了命令型钩子外,还有提示型(type: "prompt",使用 Claude 模型判断)和代理型(type: "agent",生成子代理验证条件)。

2. 怎么用

最快的方式是运行 /hooks 进入交互式菜单,选择事件、配置匹配器和命令。也可以直接在配置文件中编写:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

钩子通过 stdin 接收 JSON 事件数据,通过退出码控制行为:0 = 继续,2 = 阻止(stderr 内容反馈给 Claude),其他 = 继续但记录。配置文件位置:~/.claude/settings.json(所有项目)、.claude/settings.json(单项目共享)、.claude/settings.local.json(单项目私有)。

3. 使用场景与痛点

钩子解决的核心痛点是手动重复操作和依赖 LLM 判断的不可靠性。典型场景包括:每次编辑后自动格式化(PostToolUse + Edit|Write 匹配器 + Prettier)、保护敏感文件不被修改(PreToolUse 检查文件路径拒绝 .env、package-lock.json)、桌面通知(Notification 事件触发 osascript/notify-send)、压缩后重新注入关键上下文(SessionStart + compact 匹配器)、审计配置变更(ConfigChange 事件记录到日志文件)。

4. 使用示例

入门示例——桌面通知:

macOS:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

保存到 ~/.claude/settings.json,之后每次 Claude 等待输入时都会收到系统通知。

进阶示例——保护敏感文件 + 自动格式化:

创建 .claude/hooks/protect-files.sh 脚本,从 stdin 读取 JSON,用 jq 提取 tool_input.file_path,检查是否匹配 .envpackage-lock.json.git/ 等受保护模式,匹配则 exit 2 阻止。同时配置 PostToolUse 钩子在每次 Edit/Write 后自动运行 Prettier。这样实现了"阻止 + 后处理"的双层自动化。

高级最佳实践——提示型和代理型钩子:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains\"}."
          }

Skill Seekers 全面指南:让 AI 真正"读懂"你的技术文档

从零基础入门到架构原理深度剖析——一份写给所有 AI 从业者的渐进式技术博客


写在最前面:这篇文章适合谁?

这篇文章按照由浅入深的结构组织,不同读者可以选择适合自己的起始章节。

如果你是对 AI 工具好奇的普通开发者,从第一章开始读,你将在 15 分钟内理解 Skill Seekers 是什么,并完成第一个实际操作。如果你是正在搭建 RAG 管线的 AI 工程师,可以直接跳到第四章和第五章,那里有针对 LangChain、LlamaIndex、向量数据库等场景的最佳实践。如果你是架构师或技术负责人,第六、七、八章从源码层面深入分析了项目的设计哲学、模块架构和工程体系。如果你是想参与开源贡献的开发者,第九章介绍了项目的工程规范与贡献流程。

开源项目地址:https://github.com/yusufkaraaslan/Skill_Seekers/tree/development


第一章:三分钟理解 Skill Seekers

1.1 一个故事开始

假设你是一名前端开发者,刚加入团队,团队技术栈基于 React。你希望让 Claude Code 成为你的"React 专家搭档"——不是那种只知道泛泛基础知识的通用 AI,而是真正了解 React 最新 API、Hooks 最佳实践、Server Components 细节的领域专家。

你面临一个尴尬的处境:React 官方文档有数百个页面,散布在 react.dev 网站上。你总不能一页一页复制粘贴到 Claude 的对话框里吧?即使你这么做了,Claude 的上下文窗口也装不下这么多内容。

Skill Seekers 做的事情,就是帮你把这几百页文档,在 15 分钟之内变成一个 Claude 能直接加载和使用的"技能包"。

打开终端,三条命令:

# 第 1 步:安装
pip install skill-seekers

# 第 2 步:一键抓取 React 文档并生成知识资产
skill-seekers create https://docs.react.dev/

# 第 3 步:打包为 Claude 能用的格式
skill-seekers package output/react --target claude

完成后你的 output/ 目录里会出现一个 react-claude.zip,上传到 Claude 就行了。从此 Claude 就是你的 React 领域专家。

但这只是冰山一角——同一份知识资产还可以导出为 Gemini、OpenAI、LangChain、Cursor 等十多个平台的格式,做一次就够了。

1.2 用一句话定义 Skill Seekers

Skill Seekers 是 AI 系统的"数据层"(Data Layer)——它将散落在文档网站、GitHub 仓库、PDF 文件中的非结构化技术知识,自动转化为各类 AI 系统可以直接消费的结构化知识资产。

你可以把它理解成一个"AI 的翻译官":一边读懂人类的文档,一边把知识翻译成 AI 能高效理解的格式。

1.3 它支持哪些输入和输出?

输入端,Skill Seekers 能从三种来源获取知识。第一种是文档网站——任意在线技术文档,如 React、Django、Godot 等官网文档。第二种是 GitHub 仓库——通过 owner/repo 格式指定,系统会分析代码结构、README、Issues 等。第三种是 PDF 文件——技术手册、API 文档、论文等。

输出端则覆盖了当前 AI 生态中几乎所有主流的消费方。包括 Claude AI(ZIP + YAML)、Google Gemini(tar.gz)、OpenAI / Custom GPT(ZIP)、LangChain Documents(JSON)、LlamaIndex TextNodes(JSON)、Haystack Documents、Pinecone / ChromaDB / FAISS / Qdrant 等向量数据库就绪格式,以及 Cursor / Windsurf / Cline / Continue.dev 等 IDE AI 助手的规则文件。

一次预处理,十六个目标平台,这是 Skill Seekers 最核心的价值主张。


第二章:手把手入门——从安装到创建第一个 Skill

这一章面向完全没有用过 Skill Seekers 的读者,按照实际操作步骤逐一展开。

2.1 环境准备

你需要准备的东西非常少:Python 3.10 或更高版本,Git,以及一台能联网的电脑(macOS、Linux 或 Windows 均可)。

检查 Python 版本:

python3 --version
# 看到 Python 3.10.x 或更高即可

检查 Git:

git --version
# 看到 git version 2.x.x 即可

如果 Python 未安装,macOS 用户可以用 brew install python3,Ubuntu/Debian 用户用 sudo apt install python3 python3-pip,Windows 用户从 python.org 下载安装器(注意勾选"Add Python to PATH")。

2.2 安装 Skill Seekers

最简单的安装方式只需一行命令:

pip install skill-seekers

这会安装核心功能:文档抓取、GitHub 分析、PDF 处理和所有平台的打包能力。如果你需要额外能力,可以按需安装可选组件:

# 如果你需要 Google Gemini 支持
pip install skill-seekers[gemini]

# 如果你需要 OpenAI 支持
pip install skill-seekers[openai]

# 如果你需要 MCP 服务器(与 Claude Code 集成)
pip install skill-seekers[mcp]

# 全部安装
pip install skill-seekers[all]

安装完成后,验证一下:

skill-seekers --help

看到帮助信息就说明安装成功了。

2.3 你的第一个 Skill:5 分钟搞定

我们用一个小型示例开始,避免第一次就等待太长时间。来抓取 Tailwind CSS 的文档,限制为 5 个页面:

skill-seekers scrape \
  --name tailwind-test \
  --url https://tailwindcss.com/docs/installation \
  --description "Tailwind CSS quick reference" \
  --max-pages 5

大约 30 秒后,你会看到类似这样的输出:

Scraping: https://tailwindcss.com/docs/installation
Page 1/5: Installation
Page 2/5: Editor Setup
...
 Skill created at: output/tailwind-test/

看看生成了什么:

ls output/tailwind-test/
# SKILL.md  references/  scripts/  assets/

其中 SKILL.md 是核心知识文件,references/ 目录下是按主题分类的参考文档。

2.4 打包与上传

# 打包为 Claude 格式
skill-seekers package output/tailwind-test/
# ✅ Created: output/tailwind-test.zip

# 或者打包为其他平台格式
skill-seekers package output/tailwind-test/ --target gemini
skill-seekers package output/tailwind-test/ --target langchain

如果你配置了 Anthropic API Key,还可以一步到位自动上传:

export ANTHROPIC_API_KEY=sk-ant-...
skill-seekers package output/tailwind-test/ --upload

没有 API Key 也没关系——拿着生成的 .zip 文件去 claude.ai 的 Skills 页面手动上传即可。

2.5 使用预设配置:更省心的方式

Skill Seekers 内置了 24+ 个框架的预设配置,覆盖了 React、Vue、Angular、Django、FastAPI、Godot 等主流框架。用预设配置更加省心:

# 查看所有可用预设
skill-seekers list-configs

# 直接用预设抓取
skill-seekers scrape --config configs/godot.json

你也可以用交互式模式,系统会引导你一步步完成配置:

skill-seekers scrape --interactive

2.6 create 命令:最智能的入口

skill-seekers create 是项目提供的最便捷命令——它会自动识别你给的是什么来源,并选择对应的处理方式:

# 给一个 URL,自动走文档抓取
skill-seekers create https://docs.django.com/

# 给一个 owner/repo,自动走 GitHub 分析
skill-seekers create facebook/react

# 给一个本地路径,自动分析本地项目
skill-seekers create ./my-project

# 给一个 PDF 文件,自动走 PDF 提取
skill-seekers create manual.pdf

这种"零配置"体验大幅降低了上手门槛——你不需要记住不同的子命令,一个 create 就够了。


第三章:Skill Seekers 解决了什么问题?谁需要它?

理解了基本用法之后,我们退后一步,从更宏观的视角审视这个工具为什么存在。

3.1 AI 时代的"知识注入"难题

大语言模型的能力已经毋庸置疑,但模型本身有一个固有限制:训练数据的时效性。无论是 Claude、GPT-4 还是 Gemini,它们的知识都有一个截止日期。对于快速迭代的技术框架来说,官方文档可能每周都在更新,而模型的训练数据可能已经是半年前的了。

解决这个问题的主流方案有两种。第一种是 AI Skills / Knowledge:将结构化知识直接注入 AI 的上下文(如 Claude Skills、Custom GPTs),让 AI 在回答时能参考这些外挂知识。第二种是 RAG(检索增强生成):将知识向量化存储在数据库中,用户提问时检索最相关的文档片段,拼入上下文后让模型回答。

无论哪种方案,数据预处理都是第一步,也是最脏最累的一步。你需要从各种来源抓取内容、清洗 HTML、提取代码块、识别语言、分类组织、生成元数据……而且每换一个目标平台,格式要求就不一样。

Skill Seekers 将这整个预处理流程自动化了,并且做到了"一次处理、多目标导出"。

3.2 四类核心用户群体

经过对项目功能和文档的深入分析,Skill Seekers 的用户群体可以清晰地分为四类。

第一类:AI Skill 构建者。 这是使用 Claude Skills、Gemini Extensions、Custom GPTs 的开发者或技术写作者。他们的核心诉求是把特定领域的知识"教"给 AI,让 AI 成为该领域的专家助手。痛点在于手动整理文档耗时巨大,且不同 AI 平台要求的格式各异。

第二类:RAG 工程师。 这些是搭建企业级知识问答系统、智能客服、文档检索等 RAG 应用的工程师。他们的核心诉求是获得高质量、带元数据、分块合理的文档数据。痛点在于数据预处理流程繁琐,分块策略难以兼顾精度和上下文。

第三类:AI 编程助手用户。 这些是使用 Cursor、Windsurf、Cline 等 AI 辅助编程工具的开发者。他们的核心诉求是让 IDE 中的 AI 助手深度理解特定框架的最新用法。痛点在于 AI 助手的通用知识不够深入,需要手动维护上下文规则文件。

第四类:技术团队和企业。 这些团队需要将内部文档、私有 API 文档、跨项目知识等统一管理,构建团队级别的 AI 知识资产。痛点在于知识散落在多个系统中,且缺乏统一的预处理和分发管道。

3.3 适用场景全景

根据用户群体,Skill Seekers 的典型使用场景包括以下几类:

框架学习加速: 新入职开发者快速将团队使用的技术栈文档转化为 AI Skill,让 AI 成为"老员工"一样的带教导师。

文档智能检索: 将公司内部文档库转化为 RAG 数据集,搭建内部知识问答系统。

代码助手增强: 为 Cursor/Windsurf 生成精确的框架规则文件,让代码建议更准确。

文档质量审计: 利用冲突检测功能,发现文档与实际代码实现之间的不一致之处。

多源知识融合: 将文档网站 + GitHub 代码 + PDF 手册合并为一个统一的知识资产,消除信息孤岛。


第四章:面向不同用户的最佳实践与示例

这一章按用户群体分别给出详细的最佳实践方案和操作示例。

4.1 AI Skill 构建者的最佳实践

场景:为 Claude 创建一个 Django 专家技能

这是最基础也最常见的使用场景。完整工作流如下:

# 步骤 1:从文档创建知识资产
skill-seekers create https://docs.djangoproject.com/

# 步骤 2:AI 增强——将基础文档升级为专家级技能文件
skill-seekers enhance output/django/ --mode local
# 如果有 API Key,也可以用 API 模式:
# skill-seekers enhance output/django/ --mode api

# 步骤 3:打包并上传
skill-seekers package output/django/ --upload

增强步骤是关键——不经过增强的 SKILL.md 只是文档的简单组织,增强之后的 SKILL.md 会包含 500+ 行的内容,涵盖代码示例、最佳实践模式、快速参考指南和错误排查建议。

进阶:使用工作流预设做专项增强

如果你的 Django 项目对安全性有特殊要求,可以叠加安全增强工作流:

skill-seekers create https://docs.djangoproject.com/ \
  --enhance-workflow security-focus \
  --enhance-workflow api-documentation

这条命令会先执行安全聚焦的增强(审查 OWASP Top 10、认证授权模式等),然后再执行 API 文档增强。两个工作流链式执行,后续工作流会引用前序工作流的分析结果。

项目内置了 64 个工作流预设,覆盖了从 defaultminimalkubernetes-deploymentgraphql-schemacompliance-gdprmlops-pipeline 等极为广泛的领域。你还可以创建自定义预设放到 ~/.config/skill-seekers/workflows/ 目录下。

进阶:多平台批量导出

一次处理,导出到所有平台:

# 批量导出到 Claude、Gemini、OpenAI、Markdown 四个平台
for platform in claude gemini openai markdown; do
  skill-seekers package output/django --target $platform
done

4.2 RAG 工程师的最佳实践

场景:搭建一个基于 LangChain 的框架文档问答系统

RAG 工程师最关心的是数据质量——分块是否合理、元数据是否丰富、代码块是否保持完整。

# 步骤 1:抓取文档
skill-seekers create https://docs.react.dev/

# 步骤 2:导出为 LangChain Documents 格式
skill-seekers package output/react --target langchain
# 生成:output/react-langchain.json

导出的 JSON 文件中,每个 Document 都包含 page_content(文档内容)和 metadata(元数据,包括来源 URL、分类、内容类型等)。你可以直接将其加载到 LangChain 的检索链中。

项目的 examples/langchain-rag-pipeline/ 目录提供了完整的端到端示例。类似地,examples/llama-index-query-engine/ 提供了 LlamaIndex 的集成示例,examples/pinecone-upsert/ 提供了 Pinecone 向量数据库的写入示例。

进阶:使用 Docker Compose 搭建完整 RAG 基础设施

Skill Seekers 的 docker-compose.yml 已经预置了一个完整的 RAG 基础设施:

# 一键启动:CLI 工具 + MCP 服务器 + Weaviate + Qdrant + ChromaDB
docker-compose up -d

这会启动五个容器化服务。skill-seekers 容器是主 CLI 工具。mcp-server 在 8765 端口提供 MCP HTTP 服务。weaviate 在 8080 端口提供 Weaviate 向量数据库。qdrant 在 6333/6334 端口提供 Qdrant 向量数据库。chroma 在 8000 端口提供 ChromaDB。

所有服务通过内部 bridge 网络互联,向量数据库配置了持久化卷。你可以把文档抓取、增强、向量化入库的全流程在容器环境中完成。

进阶:处理超大型文档(10K-40K+ 页面)

对于 Godot、Unity 这类超大型文档,直接抓取会产生巨大的单一文件。Skill Seekers 提供了文档拆分和路由机制:

# 先评估文档规模
skill-seekers estimate --config configs/godot.json
# 📊 Estimated pages: 40,000
# ⚠️ Large documentation detected!

# 使用 router 策略拆分
skill-seekers split --config configs/godot.json --strategy router --target-pages 5000
# 会生成多个子配置:godot-scripting.json, godot-2d.json, godot-3d.json 等

# 并行抓取所有子技能
# (每个子技能独立抓取,可以并行执行)

# 最后生成路由器技能
skill-seekers generate-router --config-pattern "configs/godot-*.json"

路由器技能的 SKILL.md 包含智能路由逻辑——当用户提问时,路由器会根据关键词将问题导向合适的子技能。比如问到"physics"就路由到 godot-physics,问到"shader"就路由到 godot-shaders。

4.3 AI 编程助手用户的最佳实践

场景:让 Cursor IDE 的 AI 深度理解 React

Cursor、Windsurf 等 IDE 的 AI 助手支持加载上下文规则文件,让 AI 在生成代码时参考特定框架的最佳实践。

# 创建 React 技能
skill-seekers create https://docs.react.dev/

# 打包为 Claude 格式(Cursor 使用相同格式)
skill-seekers package output/react --target claude

# 复制到你的项目中
cp output/react-claude/SKILL.md my-react-project/.cursorrules

对于 Windsurf:

cp output/react-claude/SKILL.md my-project/.windsurf/rules/react.md

对于 Cline(VS Code 扩展):

cp output/react-claude/SKILL.md my-project/.clinerules

项目的 examples/ 目录提供了多个真实示例:cursor-react-skill/ 展示了 Cursor + React 的集成方式,windsurf-fastapi-context/ 展示了 Windsurf + FastAPI 的场景,cline-django-assistant/ 展示了 Cline + Django 的用法。

进阶:使用 install-agent 命令一键安装到所有 IDE

# 一键安装到 Cursor
skill-seekers install-agent output/react/ --agent cursor

# 或者安装到所有支持的 AI 编程助手
skill-seekers install-agent output/react/ --agent all

# 预览安装效果但不实际执行
skill-seekers install-agent output/react/ --agent cursor --dry-run

这条命令会自动将 Skill 文件复制到对应 IDE 的配置目录。支持的 Agent 包括 Claude Code(~/.claude/skills/)、Cursor(.cursor/skills/)、VS Code / Copilot(.github/skills/)、Amp(~/.amp/skills/)、Goose、OpenCode、Windsurf 等。

4.4 团队协作者的最佳实践

场景:在 5 人团队中共享内部 API 文档的 AI 技能

Skill Seekers 支持从私有 Git 仓库获取配置文件,实现团队级别的技能共享:

# 注册团队的私有配置仓库
# (通过 MCP 工具,在 Claude Code 中以自然语言操作更为便利)
skill-seekers config --add-source \
  --name team \
  --git-url https://github.com/mycompany/skill-configs.git

# 从团队仓库获取配置
skill-seekers config --fetch --source team --config internal-api

# 正常使用
skill-seekers scrape --config internal-api.json

支持 GitHub、GitLab、Gitea、Bitbucket 四种 Git 托管平台,通过对应的环境变量(GITHUB_TOKENGITLAB_TOKEN 等)进行认证。

场景:多源知识融合——将文档 + 代码 + PDF 合并为单一知识资产

这是企业场景中最有价值的能力之一。以 Godot 引擎为例,其预设配置展示了如何融合文档和代码两个来源:

配置中定义了 merge_mode: "claude-enhanced",然后在 sources 数组中分别配置了两个来源。第一个来源类型为 documentation,指向 Godot 官方文档网站,配置了 CSS 选择器、URL 过滤规则和内容分类。第二个来源类型为 github,指向 godotengine/godot 仓库,启用了深度代码分析、Issue 获取、Changelog 和 Release 信息抓取,以及特定的文件匹配模式(core/**/*.hscene/**/*.cpp 等)。

运行统一抓取后,系统会自动执行冲突检测——发现文档中描述但代码中不存在的 API,或者代码中实现但文档中未记录的功能,并在最终输出中以醒目标注呈现。


第五章:核心功能全景透视

在理解了"谁在用"和"怎么用"之后,让我们系统性地审视 Skill Seekers 的功能全景。

5.1 llms.txt 优先检测:10 倍速度提升的秘密

llms.txt 是一个新兴的约定标准——越来越多的技术文档网站开始提供专门为 LLM 消费优化的纯文本文件。Skill Seekers 在正式爬取之前,会依次检查目标域名下是否存在 llms-full.txtllms.txtllms-small.txt

如果检测到这些文件,系统直接下载解析即可——完全跳过了逐页爬取、HTML 解析、内容提取等耗时步骤。这在实际效果上意味着:原本需要 15 分钟的抓取任务,可能 1-2 分钟就完成了。

这个功能由三个模块协同实现:llms_txt_detector.py 负责探测文件是否存在,llms_txt_downloader.py 负责高效下载,llms_txt_parser.py 负责解析内容结构。

5.2 异步模式:2-3 倍的爬取加速

对于不支持 llms.txt 的网站,Skill Seekers 提供了基于 httpx 异步引擎的加速模式:

skill-seekers scrape --config configs/react.json --async --workers 8

--async 标志启用异步爬取(底层使用 httpx 的 async/await),--workers 指定并发工作者数量。在实际测试中,同步模式需要 15-45 分钟的任务,异步模式只需 5-15 分钟。

5.3 AI 增强工作流:从 75 行到 500+ 行的质变

基础的文档抓取只能生成结构化的参考文件。AI 增强步骤是将"数据"转化为"知识"的关键。

增强过程由 LLM 驱动——系统将抓取到的文档内容作为上下文,让 LLM 分析后生成一份综合性的 SKILL.md 文件。这份文件不是简单的摘要或合并,而是包含了以下几个维度的内容:核心概念和设计理念的阐述、带注释的代码示例和最佳实践、常见错误和解决方案、快速参考索引、以及从基础到进阶的导航建议。

系统支持三个 LLM 平台执行增强——Claude Sonnet 4(通过 Anthropic API 或 LOCAL 模式)、Gemini 2.0 Flash(通过 Google API)、GPT-4o(通过 OpenAI API)。LOCAL 模式的独特之处在于它利用 Claude Code Max 的本地执行能力,无需 API Key 也无需额外费用。

此外,通过 ANTHROPIC_BASE_URL 环境变量,中国大陆用户可以配置 GLM-4.7 等兼容 Claude 协议的国产 API 端点来完成增强。

5.4 冲突检测:文档与代码的一致性审计

当同时从文档和代码两个来源获取信息时,Skill Seekers 的冲突检测引擎会自动识别四类不一致。

红色:Missing in code(高优先级)。 文档中描述了某个 API 或功能,但在代码中找不到对应实现。这通常意味着文档描述了尚未实现的特性,或者该功能已被移除但文档未更新。

黄色:Missing in docs(中优先级)。 代码中实现了某个功能,但文档中完全没有提及。这是最常见的文档欠缺类型。

橙色:Signature mismatch(警告级别)。 同一个函数在文档和代码中有不同的参数列表、类型定义或返回值。

灰色:Description mismatch(信息级别)。 文档描述与代码注释对同一功能给出了不同的解释文字。

这个能力不仅提升了生成技能的可靠性,本身也是一个独立的文档质量审计工具。

5.5 MCP 集成:用自然语言驱动整个工作流

MCP(Model Context Protocol)是 Anthropic 推出的协议标准,用于让 AI 助手与外部工具交互。Skill Seekers 的 MCP 服务器暴露了 26 个工具,分为四类。

核心工具(9 个):list_configs, generate_config, validate_config, estimate_pages, scrape_docs, package_skill, upload_skill, enhance_skill, install_skill。

扩展工具(10 个):scrape_github, scrape_pdf, unified_scrape, merge_sources, detect_conflicts, add_config_source, fetch_config, list_config_sources, remove_config_source, split_config。

向量数据库工具(4 个):export_to_chroma, export_to_weaviate, export_to_faiss, export_to_qdrant。

云存储工具(3 个):cloud_upload, cloud_download, cloud_list。

配置好 MCP 后,你可以在 Claude Code 中直接用自然语言完成一切:

用户:帮我抓取 Svelte 文档并打包为 Claude Skill
Claude Code[调用 generate_config][调用 scrape_docs][调用 enhance_skill][调用 package_skill]
✅ 已创建 output/svelte.zip,可以上传到 Claude

MCP 服务器支持两种传输模式——stdio 模式(用于 Claude Code、VS Code + Cline 的本地集成)和 HTTP 模式(用于 Cursor、Windsurf、IntelliJ 的网络集成,默认端口 8765)。

5.6 断点续传:永不丢失进度

考虑到大型文档的抓取可能需要数十分钟甚至数小时,Skill Seekers 实现了作业恢复机制。系统以可配置的间隔(默认 60 秒)自动保存进度。如果中途意外中断,可以查看并恢复:

# 查看所有可恢复的作业
skill-seekers resume --list

# 从中断处继续
skill-seekers resume github_react_20260117_143022

旧作业会在 7 天后自动清理,不会无限占用磁盘。


第六章:架构原理深度剖析

从这一章开始,我们深入到项目的内部设计中。

6.1 项目代码结构解析

Skill Seekers v3.1.3 的 development 分支采用 src 布局(即源码位于 src/skill_seekers/ 而非项目根目录),这是 Python 社区推荐的现代项目结构,通过 pyproject.toml[tool.setuptools] package-dir = {"" = "src"} 配置实现。

核心源码分为六个子包。cli/ 是最庞大的模块,包含约 75 个 Python 文件和 5 个子目录(adaptors、arguments、parsers、presets、storage),承载了几乎所有的业务逻辑——从爬虫到分析到增强到打包。mcp/ 实现 MCP 协议服务器,将 CLI 能力暴露为 26 个可通过自然语言调用的工具。embedding/ 包含嵌入向量相关的模型(models.py)、生成器(generator.py)、缓存(cache.py)和服务器(server.py)四个模块。workflows/ 存放 64 个 YAML 格式的增强工作流预设。sync/ 处理同步监控逻辑,基于 schedule 库实现定时更新。benchmark/ 提供性能基准测试工具。

6.2 五阶段数据处理管线

Skill Seekers 的数据流遵循一条清晰的五阶段管线:Ingest → Analyze → Structure → Enhance → Export

Ingest(摄取)阶段: 这是整个管线的入口,由三个专用爬取器负责。doc_scraper.py 处理文档网站,内部通过 llms_txt_detector.py 优先检测 llms.txt 快速通道,未命中时退回到基于 BeautifulSoup4 的 HTML 解析模式,markdown_cleaner.py 负责将 HTML 转化为干净的 Markdown。github_scraper.py 处理 GitHub 仓库,采用三流架构(Code / Docs / Insights),其中 Code 流使用 unified_codebase_analyzer.py 进行 AST 级别的深度代码分析,Docs 流提取 README 和文档文件,Insights 流通过 PyGithub 调用 GitHub API 获取 Issues、Labels、Stars 等社区数据。pdf_scraper.py 处理 PDF 文件,底层基于 PyMuPDF 引擎,叠加了三种互补的代码检测方法(字体特征、缩进模式、模式匹配)和支持 19+ 种语言的识别能力。

Analyze(分析)阶段: 这一阶段对原始内容进行深度语义分析。code_analyzer.py 执行 AST 解析(支持 Python、JavaScript、TypeScript、Java、C++、Go),提取函数签名、类结构、方法参数和类型信息。architectural_pattern_detector.py 识别工厂模式、单例模式、观察者模式等设计模式。dependency_analyzer.py 基于 networkx 构建依赖关系图谱。conflict_detector.py 执行前文描述的四级冲突检测。signal_flow_analyzer.py 分析代码中的信号和事件流。config_extractor.py

让 AI 学会"组队打怪"——聊聊微软的 AutoGen 框架

你有没有想过,一个 AI 助手再聪明,终究也是一个人在战斗。它写完代码没人 review,它做完分析没人挑刺,它回答问题也没人帮忙查漏补缺。

但如果让好几个 AI 坐在一起,各管一摊,一个写、一个审、一个改,会怎样?

这就是微软开源的 AutoGen 在做的事情。

一句话说清楚它是什么

AutoGen 是一个用 Python 搭建多智能体应用的框架。说白了,它让你可以创建多个各有分工的 AI 角色,让它们自己聊着把活儿干了。

比如你可以安排一个"写手"负责起草文案,再安排一个"编辑"负责提修改意见,写手改完再让编辑看,来回几轮直到编辑满意为止。整个过程不需要你盯着,它们自己就能协商完成。

这不是什么遥远的概念,装两个包就能跑起来。

怎么装?怎么用?

环境要求很简单:Python 3.10 以上就行。打开终端敲一行命令:

pip install -U "autogen-agentchat" "autogen-ext[openai]"

装好之后,最基础的用法是创建一个带工具的 AI 助手。举个例子,做一个能查天气的智能体:

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def get_weather(city: str) -> str:
    return f"{city}今天 25°C,晴。"

model_client = OpenAIChatCompletionClient(model="gpt-4o")
agent = AssistantAgent(
    name="weather_agent",
    model_client=model_client,
    tools=[get_weather],
)

async def main():
    result = await agent.run(task="北京今天天气怎么样?")
    print(result.messages[-1].content)

asyncio.run(main())

你定义一个普通的 Python 函数,把它扔进 tools 参数里,AI 就自动知道什么时候该调用它。函数签名和注释会被自动转成工具描述,不需要你手动写 JSON schema。

真正有意思的部分:多个 AI 协作

单个智能体只是开胃菜。AutoGen 真正的看家本领是让多个智能体组队工作。

框架内置了几种编排模式,最常用的是 RoundRobinGroupChat——大家轮流发言。你可以设一个终止条件,比如当某个角色说出"通过"这个词就停下来:

from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import TextMentionTermination

team = RoundRobinGroupChat(
    [writer_agent, reviewer_agent],
    termination_condition=TextMentionTermination("通过"),
)
result = await team.run(task="写一段产品介绍文案")

除了轮流发言,还有 SelectorGroupChat,由一个 LLM 来判断下一个该谁说话,适合角色更多、分工更复杂的场景。还有 Swarm 模式,智能体之间可以主动"转交"任务,像客服系统的分级处理一样。

它的架构长什么样

AutoGen 分三层。最底下的 Core 层负责消息传递和运行时调度,属于基础设施。中间的 AgentChat 层是大多数人打交道的地方,预设智能体、团队编排、终止条件都在这一层。最外面的 Extensions 层负责对接各种外部服务,比如 OpenAI 的模型、Docker 代码执行器,以及通过 MCP 协议接入 Jira、Slack 等工具。

这种分层的好处是,你可以只用上层 API 快速出原型,也可以深入底层做精细控制。

还有个不用写代码的选项

如果你不想写代码,AutoGen 还提供了一个叫 AutoGen Studio 的可视化工具。装好之后一行命令启动:

pip install -U autogenstudio
autogenstudio ui --port 8080

打开浏览器就能拖拖拽拽搭建多智能体工作流,适合做快速验证和演示。

适合什么场景

说实话,不是所有任务都需要多智能体。一个简单的问答,一个 AI 就够了,上多智能体反而是大炮打蚊子。

但有些场景确实适合:需要反复打磨的内容创作、多角度的分析研判、有明确流程的任务处理(比如先分类再路由再执行),以及需要调用多种外部工具协同完成的复杂工作流。

核心判断标准就一个:如果你发现自己在不断地把一个 AI 的输出复制粘贴给另一个 AI 让它接着处理,那多半可以用 AutoGen 把这个链路自动化掉。


AutoGen 当前稳定版本为 v0.7.5,项目地址:github.com/microsoft/autogen

OpenClaw Memory 模块完整分析

OpenClaw Memory 模块完整分析

一、项目背景

OpenClaw 是一个本地优先的个人 AI 助手,支持多种消息通道(WhatsApp、Telegram、Slack 等)。Memory 模块为 AI Agent 提供语义记忆搜索能力——Agent 可以在 Markdown 记忆文件和历史会话中进行向量 + 关键词的混合检索。

二、整体架构

┌─────────────────────────────────────────────────┐
│                  入口层 (index.ts)               │
│  getMemorySearchManager() → 选择后端策略          │
├────────────┬────────────────────────┬───────────┤
│  QMD 后端   │  FallbackManager      │ Builtin 后端│
│ (外部CLI)   │  (主备自动切换)        │ (核心实现)   │
├─────────────┴───────────────────────┴───────────┤
│               MemoryIndexManager                │
│   ┌──────────┬──────────┬──────────┐            │
│   │ SyncOps  │Embedding │ Search   │            │
│   │(文件监听) │ Ops(索引) │(混合搜索) │             │
│   └──────────┴──────────┴──────────┘            │
├─────────────────────────────────────────────────┤
│            存储层: SQLite + FTS5 + sqlite-vec    │
├─────────────────────────────────────────────────┤
│  Embedding Providers: OpenAI|Gemini|Voyage|     │
│  Mistral|Local(node-llama-cpp)                  │
└──────────────────────────────────────────────────┘

三、核心设计详解

1. 统一接口 (MemorySearchManager)

export type MemorySource = "memory" | "sessions";

export type MemorySearchResult = {
  path: string;
  startLine: number;
  endLine: number;
  score: number;
  snippet: string;
  source: MemorySource;
  citation?: string;
};
// ...
export interface MemorySearchManager {
  search(query, opts?): Promise<MemorySearchResult[]>;
  readFile(params): Promise<{ text: string; path: string }>;
  status(): MemoryProviderStatus;
  sync?(params?): Promise<void>;
  probeEmbeddingAvailability(): Promise<MemoryEmbeddingProbeResult>;
  probeVectorAvailability(): Promise<boolean>;
  close?(): Promise<void>;
}

这是整个模块的核心抽象——无论底层用什么后端(builtin SQLite 还是外部 QMD CLI),对上层暴露统一接口。

2. 后端策略选择 (search-manager.ts)

export async function getMemorySearchManager(params: {
  cfg: OpenClawConfig;
  agentId: string;
  purpose?: "default" | "status";
}): Promise<MemorySearchManagerResult> {
  const resolved = resolveMemoryBackendConfig(params);
  if (resolved.backend === "qmd" && resolved.qmd) {
    // ... 尝试 QMD 后端,失败则 fallback 到 builtin
    const wrapper = new FallbackMemoryManager({
      primary,
      fallbackFactory: async () => {
        const { MemoryIndexManager } = await import("./manager.js");
        return await MemoryIndexManager.get(params);
      },
    }, () => QMD_MANAGER_CACHE.delete(cacheKey));
    // ...
  }
  // 默认使用 builtin
  const manager = await MemoryIndexManager.get(params);
  return { manager };
}

设计亮点:

  • 策略模式 + 懒加载:通过 dynamic import 延迟加载后端实现
  • FallbackMemoryManager:代理模式,主后端失败自动切换到备用后端,对上层透明
  • 缓存驱逐:失败时自动从缓存中移除,下次请求可以重试

3. 混合搜索引擎 (hybrid.ts)

export async function mergeHybridResults(params: {
  vector: HybridVectorResult[];
  keyword: HybridKeywordResult[];
  vectorWeight: number;
  textWeight: number;
  mmr?: Partial<MMRConfig>;
  temporalDecay?: Partial<TemporalDecayConfig>;
}): Promise<Array<{ path; startLine; endLine; score; snippet; source }>> {
  // 1. 按 ID 合并向量和关键词结果
  // 2. 加权融合分数: score = vectorWeight * vectorScore + textWeight * textScore
  // 3. 时间衰减: 旧记忆分数降低
  // 4. MMR 重排序: 增加结果多样性
}

这是搜索的核心——三层融合管线:

阶段 算法 作用
加权融合 score = w_v × vectorScore + w_t × textScore 平衡语义相似度和关键词匹配
时间衰减 指数衰减 e^(-λ × age) 让近期记忆权重更高
MMR 重排序 λ × relevance - (1-λ) × max_similarity 增加结果多样性,避免重复

4. 时间衰减机制 (temporal-decay.ts)

export function toDecayLambda(halfLifeDays: number): number {
  return Math.LN2 / halfLifeDays;
}

export function calculateTemporalDecayMultiplier(params: {
  ageInDays: number;
  halfLifeDays: number;
}): number {
  const lambda = toDecayLambda(params.halfLifeDays);
  return Math.exp(-lambda * clampedAge);
}

核心设计:

  • 日期命名文件 memory/2024-01-15.md 自动从文件名提取时间
  • 常青文件 MEMORY.md 和非日期命名的 memory/*.md 不衰减(核心知识)
  • fallback 到 mtime:无法从文件名解析日期时,使用文件修改时间

5. MMR 多样性重排序 (mmr.ts)

export function computeMMRScore(relevance: number, maxSimilarity: number, lambda: number): number {
  return lambda * relevance - (1 - lambda) * maxSimilarity;
}

使用 Jaccard 相似度(基于 token 集合的交集/并集)来衡量结果间的相似程度,避免返回大量重复内容。比起用向量余弦相似度做 MMR,Jaccard 更轻量且无需额外嵌入计算。

6. Markdown 分块策略 (internal.ts)

export function chunkMarkdown(
  content: string,
  chunking: { tokens: number; overlap: number },
): MemoryChunk[] {
  const maxChars = Math.max(32, chunking.tokens * 4);
  const overlapChars = Math.max(0, chunking.overlap * 4);
  // 按行扫描,达到 maxChars 时 flush
  // flush 后保留尾部 overlapChars 作为重叠区
}

设计要点:

  • token 估算tokens × 4 转为字符数(粗略但高效)
  • 滑动窗口重叠:chunk 之间有 overlap,避免语义在边界处被截断
  • 超长行切割:单行超过 maxChars 时自动分段
  • 每个 chunk 记录 startLine/endLine,支持精确引用

7. Embedding Provider 工厂 (embeddings.ts)

export async function createEmbeddingProvider(
  options: EmbeddingProviderOptions,
): Promise<EmbeddingProviderResult> {
  // auto 模式: local → openai → gemini → voyage → mistral
  // 指定模式: primary → fallback
  // 所有 API key 缺失: 返回 null provider (FTS-only mode)
}

三层降级策略:

  1. auto 模式:依次尝试 local → openai → gemini → voyage → mistral
  2. 指定 + fallback:用户指定的 provider 失败时切换到 fallback
  3. 全部失败 → FTS-only:纯关键词搜索,仍可用但质量降低

8. 数据库 Schema (memory-schema.ts)

// meta: 索引元信息 (model/provider/版本)
// files: 文件记录 (path, hash, mtime, source)
// chunks: 文本块 (id, path, text, embedding, model)
// embedding_cache: 嵌入缓存 (provider+model+hash → embedding)
// chunks_fts: FTS5 全文搜索虚拟表
// chunks_vec: sqlite-vec 向量搜索虚拟表

9. 同步机制 (manager-sync-ops.ts)

同步有多种触发方式:

触发方式 场景
watch chokidar 文件监听,debounce 后触发
session-start 新会话开始时预热
session-delta 会话文件增长超过阈值(字节/消息数)
search 搜索时如果 dirty 则先同步
interval 定时同步(可配置分钟数)

重建索引采用安全替换策略:先写入临时 DB,完成后原子交换,失败则回滚。

10. 实例缓存 + 单例

const INDEX_CACHE = new Map<string, MemoryIndexManager>();
static async get(params): Promise<MemoryIndexManager | null> {
  const key = `${agentId}:${workspaceDir}:${JSON.stringify(settings)}`;
  const existing = INDEX_CACHE.get(key);
  if (existing) return existing;
  // ... 创建新实例
  INDEX_CACHE.set(key, manager);
  return manager;
}

agentId + workspaceDir + settings 作为缓存 key,保证同一配置只有一个 Manager 实例,避免重复打开数据库和文件监听器。

四、参考价值总结

如果你想在自己的项目中实现类似的记忆/知识检索系统,这个模块有以下核心参考价值:

维度 设计模式 参考价值
接口抽象 MemorySearchManager 接口 将搜索、同步、状态查询统一抽象,后端可替换
混合搜索 Vector + BM25 加权融合 兼顾语义理解和精确匹配,比单纯向量搜索更鲁棒
结果优化 MMR + 时间衰减 解决结果重复和旧信息权重过高的问题
降级策略 Provider 三层 fallback + FTS-only 无 API key 也能用,极大提升了可用性
主备切换 FallbackMemoryManager 代理模式 QMD 后端失败自动切到 builtin,对上层透明
增量同步 hash 对比 + 文件监听 + delta 阈值 只重新索引变化的文件,会话增量基于字节/消息数阈值
安全重建 临时 DB → 原子交换 → 失败回滚 全量重建索引时不影响在线查询
嵌入缓存 SQLite embedding_cache 表 避免重复调用 API,重建索引时可复用历史嵌入
分块策略 行级滑动窗口 + overlap 保留行号信息,支持精确引用,overlap 防止语义断裂
实例管理 缓存 Map + 复合 key 避免重复实例,正确处理 close 和缓存驱逐

这套架构特别适合以下场景复用:

  1. RAG 系统——需要在本地文档上做语义搜索
  2. 知识库检索——混合搜索 + 时间衰减适合持续更新的知识
  3. Agent 工具——作为 AI Agent 的长期记忆组件
  4. 离线优先应用——SQLite 本地存储 + 可选远程 Embedding 的架构

Speckit、OpenSpec、Superpowers 和 everything-claude-code AI辅助编程工具对比分析

1. 概述

随着AI编码能力(如 Claude Code、Cursor 等)的普及,软件开发领域正从“Vibe Coding”(随心灵感编码)向更工程化的方向演进。为了应对AI生成代码的不确定性、上下文丢失以及协作一致性等问题,社区涌现了多种规范驱动开发(Spec-Driven Development, SDD)框架和工作流方法论

选取了目前最具代表性的四个项目进行对比:

  • Speckit:GitHub官方出品的结构化规范驱动工具包

  • OpenSpec:专注于增量变更和棕地项目的轻量级框架

  • Superpowers:强调强制流程和TDD的代理技能框架

  • everything-claude-code:黑客松冠军开源的综合性 Claude Code 方法论

2. 核心属性速览

维度 Speckit OpenSpec Superpowers everything-claude-code
核心理念 规范即代码,通过严格的结构化流程实现工业级控制 增量即真相,通过Delta机制管理现有项目的演进 强制方法论,通过不可跳过的“技能”约束AI行为 CLI+Skills替代MCP,通过编排与并行化榨干模型性能
目标场景 绿地项目 (0→1) ,复杂且需要严格文档的团队协作 棕地项目 (1→n) ,在已有代码库上进行频繁修改和功能迭代 从0到1的需求探索,对代码质量、测试覆盖有极高要求的项目 重度Claude Code用户,追求极致Token效率和复杂任务并行处理的场景
工作流程 五阶段线性流程:Constitution → Specify → Plan → Tasks → Implement 四阶段循环流程:Draft Proposal → Review → Apply → Archive 三阶段严格流程:Brainstorm → Write Plan → Execute Plan (含TDD) 五阶段Agent编排:Research → Plan → Implement → Review → Verify
关键机制 9条不可变架构原则、7层LLM输出约束、ADR决策记录 Specs/与Changes/隔离、Delta增量存储、Fail-Fast冲突检测 强制技能调用、Red-Green-Refactor TDD、子代理审查 多Agent编排、并行化(Git Worktrees)、动态系统提示、记忆钩子

3. 详细维度对比

3.1 核心理念与哲学

  • Speckit:秉持“规范优先”的哲学。它假设需求在编码前可以被完全定义,通过类似于法律的“宪章”来约束AI的每一次产出。它将开发视为一个严谨的、逐层分解的工程过程,试图通过结构的确定性来对抗AI的随机性

  • OpenSpec:秉持“演进优先”的哲学。它承认需求是动态变化的,特别是在维护老项目时。其核心理念是将“当前稳定状态”(Specs)与“提议变更”(Changes)分离,每次只处理增量,最终将验证后的增量合并回主干,实现系统的平滑演进

  • Superpowers:秉持“流程即法律”的哲学。它不信任AI的自由发挥,通过一套不可跳过的“技能”(Skills)来强制AI遵循人类软件工程的最佳实践(如必须先写测试)。它像一名“教官”,强制AI按照TDD、Code Review等严谨流程行动

  • everything-claude-code:秉持“效率与编排”的哲学。它将AI视为一个可编排的智能体集群,通过精细化的工程手段(如用CLI替代MCP省Token、多实例并行)来最大化模型性能,降低成本,实现复杂的、多步骤的研发任务

3.2 目标用户与适用项目

  • Speckit:适合中大型团队,特别是需要严格合规、文档齐全的企业级项目。它明确了产品经理、技术负责人、开发者之间的交接点(如Spec、Plan),适合角色分工明确的团队

  • OpenSpec:适合全栈开发者或小型团队,尤其是在维护复杂老系统的团队。对于经常需要跨多个服务或模块进行小范围修改的场景,它的轻量级和高效增量特性极具吸引力

  • Superpowers:适合任何追求代码质量的开发者,尤其是从0到1启动项目时。它的头脑风暴模式对需求不明确的项目非常友好,强制TDD则确保了代码的健壮性

  • everything-claude-code:适合Claude Code的重度用户和技术极客。适合需要处理复杂、多步骤、多文件任务的场景,或是希望在API调用成本上精打细算的开发者

3.3 工作流与落地实践

  • Speckit:流程线性且严格

    • Constitution:定义开发原则和不可变规则

    • Specify:详细描述需求(What & Why)

    • Plan:基于技术栈制定架构方案

    • Tasks:分解为可执行的任务列表

    • Implement:逐一执行任务

      实践发现,若前期需求或设计有误,后期返工成本极高。在动态变化的企业环境中,这种线性流程常面临“理想很丰满,现实很骨感”的挑战

  • OpenSpec:流程循环且隔离

    • Proposal:在 changes/ 目录下创建变更提案、任务和Spec增量

    • Review:人与AI审查、对齐提案,可利用 openspec validate 进行冲突检测

    • Apply:AI严格根据 tasks.md 和增量Spec实施编码

    • Archive:将验证通过的变更合并(归档)到 specs/ 目录,更新“真相源”

      这种模式确保了主分支的Spec始终反映最新状态,且归档动作实现了知识的持续沉淀

  • Superpowers:流程强制且循环

    • Brainstorm:AI通过多轮问答帮助用户精炼需求,探索方案,输出设计文档

    • Write Plan:将设计拆解为极小的任务(2-5分钟),每个任务包含精确的文件路径、代码片段和测试命令

    • Execute Plan:通过子代理或批量模式执行计划,强制遵循 TDD(Red-Green-Refactor) ,并进行代码审查

      任何跳过步骤(如先写代码)的行为都会被AI视为违规

  • everything-claude-code:流程编排且并行

    • 编排:通过 Research AgentPlanner AgentTDD-guide AgentReviewer AgentResolver Agent 的有序协作完成任务。每个Agent输入输出清晰,中间用 /clear 清理上下文

    • 并行:利用 Git Worktrees 创建多个工作目录,同时运行多个Claude实例处理不同任务,互不干扰。采用 Two-Instance Kickoff(一个搭骨架,一个做调研)启动新项目

3.4 优缺点分析

工具/方法论 优点 缺点/挑战
Speckit 结构最严谨,文档最完善,适合大型项目治理;通过ADR记录决策,可追溯性强 。 太重、太理想化。对动态需求适应性差,流程僵化;生成文档冗长(相较OpenSpec多出数倍),上下文窗口易爆,返工成本高 。
OpenSpec 轻量、Token效率高。增量模式对老项目友好;archive机制能反向构建知识库;学习曲线平缓 。 对命名敏感,Delta机制依赖稳定的命名进行匹配;冲突解决依赖人工介入,对认知负担有一定挑战 ;不适合需要顶层宏观设计的0→1项目 。
Superpowers 质量保障最强。通过强制TDD和Code Review,产出代码可靠性高;头脑风暴功能极佳,能深度挖掘模糊需求 。 流程强制带来的“笨重感” 。即使是修个小Bug,也可能触发全套流程(TDD),对于追求快速验证的场景可能显得繁琐 。
everything-claude-code 极致的技术效率。Token优化策略显著降本;并行化和Agent编排极大提升复杂任务吞吐量;开源且模块化,扩展性强 。 上手门槛较高。需要理解其Agent编排、Hooks、Worktrees等整套哲学,对新手不够友好;部分技巧(如记忆钩子)需要手动配置 。

4. 选型建议

根据不同的团队类型和项目阶段,可以遵循以下建议进行选型

  • 如果你是维护复杂老系统的“单人开发者”或“小型团队”

    • 首选 OpenSpec。它的增量哲学能让你在不扰乱现有架构的前提下,安全地嵌入新功能。归档机制能帮你逐步梳理出混乱系统的“隐形文档”
  • 如果你正在启动一个全新的、复杂度较高的项目,且有明确的架构要求

    • 如果你是严谨派,追求工业级的代码质量:可以尝试 Speckit,但要做好前期投入大量时间编写规范的准备

    • 如果你是敏捷派,需求尚在演变中:强烈推荐 Superpowers。先利用其 Brainstorm 功能理清思路,再利用强制TDD构建稳固的核心,体验会非常流畅

  • 如果你是重度AI用户(特别是 Claude Code),追求极致的开发效率和成本控制

    • everything-claude-code 是你的不二之选。学习并采用它的CLI+Skills思想、Agent编排和并行化策略,你将能驾驭AI完成以往需要一个小团队才能完成的复杂任务
  • 如果你在大型团队中协作,需要明确的产品与开发交接流程

    • Speckit 的结构化文档(Constitution, Spec, Plan)可以作为团队协作的契约,明确各方职责,减少沟通误差。但需确保项目需求相对稳定,以避免因变更导致的巨大返工成本

5. 总结

AI编程正从“无序的 vibe coding”走向“有序的工程化”。这四种工具代表了不同的工程化路径

  • Speckit 走的是“计划经济的道路”,通过周密的计划来控制生产

  • OpenSpec 走的是“改革的道路”,在保持系统稳定的前提下,通过小步快跑实现演进

  • Superpowers 走的是“素质教育的道路”,通过严格的训练(流程)让AI养成良好的编码习惯

  • everything-claude-code 走的是“科技强军的道路”,通过先进的装备(编排、并行)和战术配合来发挥AI的最大战斗力

最终的选择没有绝对的对错,关键在于你的项目痛点、团队文化以及对AI协作的期望。希望这份报告能帮助你在这个快速发展的领域中找到最适合自己的方向

别让 AI 骗了:这些状态管理工具真的适合你吗?

某天,你让 Claude 帮你写个购物车功能,它给你生成了一套完整的 Redux。你看着满屏的 action、reducer、selector,心想:真的需要这么复杂吗?

AI 工具确实能快速生成状态管理代码,但它生成的方案,真的适合你的项目吗?这篇文章是我在 AI 辅助开发中,重新思考"状态管理选择"的过程。我想搞清楚:哪些工具是 AI 擅长的,哪些是我真正需要的。

从一个计数器开始:状态管理的起点

最简单的需求

让我们从最基础的开始。

// Environment: React
// Scenario: A simple counter

function Counter() {
  const [count, setCount] = useState(0);
  
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>+1</button>
    </div>
  );
}

这里的"状态"是什么?

  • count 这个数字
  • 它会随着用户点击而变化
  • 只在这个组件内部使用

AI 友好度:⭐⭐⭐⭐⭐

为什么 AI 在这里表现完美?

  • useState 是最基础的模式,训练数据充足
  • 模式简单统一,不容易出错
  • 生成的代码几乎不需要修改

结论:如果状态只在单个组件内使用,useState 就够了,不需要其他工具。

需求升级:父子组件通信

当状态需要在多个组件间共享时,事情开始变复杂。

// Environment: React
// Scenario: State lifting to parent component

function Parent() {
  const [count, setCount] = useState(0);
  
  return (
    <div>
      <Display count={count} />
      <Controls count={count} setCount={setCount} />
    </div>
  );
}

function Display({ count }) {
  return <h1>{count}</h1>;
}

function Controls({ count, setCount }) {
  return (
    <>
      <button onClick={() => setCount(count + 1)}>+1</button>
      <button onClick={() => setCount(count - 1)}>-1</button>
    </>
  );
}

思考点

  • 状态"提升"到父组件
  • 通过 props 传递给子组件
  • 这样做的问题是什么?

AI 友好度:⭐⭐⭐⭐

AI 能正确生成状态提升的代码,Props 传递逻辑清晰。但如果层级更深,AI 可能生成冗长的代码——它会"老实地"逐层传递,不会主动建议更好的方案。

第一层复杂度:Props Drilling 让人崩溃

问题场景:深层嵌套的组件树

想象一下存在这样的组件结构:

// Scenario: User info needed in multiple deeply nested components

<App>
  <Layout>
    <Header>
      <Navigation>
        <UserMenu />  {/* needs user info */}
      </Navigation>
    </Header>
    <Sidebar>
      <UserProfile />  {/* needs user info */}
    </Sidebar>
    <Main>
      <Content>
        <Article>
          <AuthorInfo />  {/* needs user info */}
        </Article>
      </Content>
    </Main>
  </Layout>
</App>

Props Drilling 的痛苦

// Environment: React
// Scenario: Props drilling problem

// Every layer must pass user prop
function App() {
  const [user, setUser] = useState(null);
  return <Layout user={user} />;
}

function Layout({ user }) {
  return (
    <>
      <Header user={user} />
      <Sidebar user={user} />
      <Main user={user} />
    </>
  );
}

function Header({ user }) {
  return <Navigation user={user} />;
}

function Navigation({ user }) {
  return <UserMenu user={user} />;
}

function UserMenu({ user }) {
  // Finally used here!
  return <div>{user.name}</div>;
}

问题分析

  • Layout、Header、Navigation 都不需要 user
  • 但为了传递给深层组件,它们都要接收这个 prop
  • 代码冗余,维护困难

AI 生成这种代码时的特点

  • ⚠️ AI 会"老实地"逐层传递 props
  • ⚠️ 不会主动建议使用 Context 或状态管理
  • ⚠️ 生成的代码"能用",但不优雅

解决方案1:Context API

// Environment: React
// Scenario: Use Context to avoid props drilling

// Create Context
const UserContext = createContext();

// Wrap root with Provider
function App() {
  const [user, setUser] = useState(null);
  
  return (
    <UserContext.Provider value={{ user, setUser }}>
      <Layout />
    </UserContext.Provider>
  );
}

// Deep component directly consumes
function UserMenu() {
  const { user } = useContext(UserContext);
  return <div>{user?.name}</div>;
}

// Middle components don't need to know about user
function Layout() {
  return (
    <>
      <Header />
      <Sidebar />
      <Main />
    </>
  );
}

Context 的优势

  • ✅ 解决了 Props Drilling
  • ✅ 中间组件不需要关心数据传递
  • ✅ React 原生 API,无需额外依赖

Context 的问题

// Environment: React
// Scenario: Performance issue with Context

function UserProvider({ children }) {
  const [user, setUser] = useState(null);
  const [theme, setTheme] = useState('light');
  
  // ❌ Every time user or theme changes, all consumers re-render
  return (
    <UserContext.Provider value={{ user, setUser, theme, setTheme }}>
      {children}
    </UserContext.Provider>
  );
}

// Even if component only needs theme, it re-renders when user changes
function ThemeToggle() {
  const { theme, setTheme } = useContext(UserContext);
  // Re-renders when user changes!
}

AI 友好度:⭐⭐⭐

AI 生成 Context 代码的特点

  • ✅ AI 能正确生成 Context 的基本用法
  • ⚠️ AI 经常忽略性能优化(split context、useMemo)
  • ⚠️ AI 可能把所有状态都放在一个 Context 里
  • ❌ AI 生成的代码需要人工审查性能问题

我的经验是:让 AI 生成 Context 代码后,需要手动检查:

  • 是否需要拆分成多个 Context?
  • value 对象是否需要 useMemo?
  • 是否有不必要的重渲染?

Context 的适用场景

  • ✅ 数据变化不频繁(主题、语言、用户信息)
  • ✅ 只需要跨 2-3 层组件
  • ✅ 简单项目,不想引入额外依赖
  • ❌ 数据频繁变化(表单输入、动画)
  • ❌ 需要复杂的状态更新逻辑

第二层复杂度:状态更新逻辑变复杂

问题场景:购物车的复杂状态

// Environment: React
// Scenario: Shopping cart with complex operations

function Cart() {
  const [items, setItems] = useState([]);
  
  // Add item
  const addItem = (product) => {
    const existing = items.find(item => item.id === product.id);
    if (existing) {
      setItems(items.map(item =>
        item.id === product.id
          ? { ...item, quantity: item.quantity + 1 }
          : item
      ));
    } else {
      setItems([...items, { ...product, quantity: 1 }]);
    }
  };
  
  // Remove item
  const removeItem = (id) => {
    setItems(items.filter(item => item.id !== id));
  };
  
  // Update quantity
  const updateQuantity = (id, quantity) => {
    setItems(items.map(item =>
      item.id === id ? { ...item, quantity } : item
    ));
  };
  
  // Clear cart
  const clearCart = () => {
    setItems([]);
  };
  
  // Calculate total
  const total = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  
  // ... component render logic
}

问题分析

  • setState 逻辑散落在各个函数中
  • 每个函数都要处理不可变更新
  • 复杂的条件判断和数组操作
  • 难以追踪状态变化

解决方案2:useReducer

// Environment: React
// Scenario: Manage complex state with Reducer

// Define Action Types
const ACTIONS = {
  ADD_ITEM: 'ADD_ITEM',
  REMOVE_ITEM: 'REMOVE_ITEM',
  UPDATE_QUANTITY: 'UPDATE_QUANTITY',
  CLEAR_CART: 'CLEAR_CART'
};

// Reducer: Centralized state change logic
function cartReducer(state, action) {
  switch (action.type) {
    case ACTIONS.ADD_ITEM: {
      const existing = state.items.find(item => item.id === action.payload.id);
      if (existing) {
        return {
          ...state,
          items: state.items.map(item =>
            item.id === action.payload.id
              ? { ...item, quantity: item.quantity + 1 }
              : item
          )
        };
      }
      return {
        ...state,
        items: [...state.items, { ...action.payload, quantity: 1 }]
      };
    }
    
    case ACTIONS.REMOVE_ITEM:
      return {
        ...state,
        items: state.items.filter(item => item.id !== action.payload)
      };
    
    case ACTIONS.UPDATE_QUANTITY:
      return {
        ...state,
        items: state.items.map(item =>
          item.id === action.payload.id
            ? { ...item, quantity: action.payload.quantity }
            : item
        )
      };
    
    case ACTIONS.CLEAR_CART:
      return { ...state, items: [] };
    
    default:
      return state;
  }
}

// Use in component
function Cart() {
  const [state, dispatch] = useReducer(cartReducer, { items: [] });
  
  const addItem = (product) => {
    dispatch({ type: ACTIONS.ADD_ITEM, payload: product });
  };
  
  const removeItem = (id) => {
    dispatch({ type: ACTIONS.REMOVE_ITEM, payload: id });
  };
  
  // State update logic centralized in reducer
  // Component only dispatches actions
}

useReducer 的优势

  • ✅ 状态更新逻辑集中,易于维护
  • ✅ Action 类型明确,易于追踪
  • ✅ 测试友好(Reducer 是纯函数)
  • ✅ 适合复杂的状态转换

AI 友好度:⭐⭐⭐⭐

AI 能生成结构清晰的 Reducer,Switch-case 模式是 AI 熟悉的。但 AI 可能生成过于冗长的代码,Action types 和 actions 的组织方式可能不够优雅。

我的经验是:AI 生成的 Reducer 代码通常可用,但需要人工优化:

  • 提取重复的逻辑
  • 简化不可变更新(考虑 Immer)
  • 优化 Action 的组织方式

解决方案3:Zustand(AI 最爱)

// Environment: React + Zustand
// Scenario: More concise global state management

import { create } from 'zustand';

// Everything visible in one file
const useCartStore = create((set, get) => ({
  items: [],
  
  addItem: (product) => set((state) => {
    const existing = state.items.find(item => item.id === product.id);
    if (existing) {
      return {
        items: state.items.map(item =>
          item.id === product.id
            ? { ...item, quantity: item.quantity + 1 }
            : item
        )
      };
    }
    return {
      items: [...state.items, { ...product, quantity: 1 }]
    };
  }),
  
  removeItem: (id) => set((state) => ({
    items: state.items.filter(item => item.id !== id)
  })),
  
  updateQuantity: (id, quantity) => set((state) => ({
    items: state.items.map(item =>
      item.id === id ? { ...item, quantity } : item
    )
  })),
  
  clearCart: () => set({ items: [] }),
  
  // Derived state (auto-calculated)
  get total() {
    return get().items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  }
}));

// Use in component (very concise)
function Cart() {
  const { items, addItem, removeItem, total } = useCartStore();
  
  return (
    <div>
      {items.map(item => (
        <CartItem key={item.id} item={item} onRemove={removeItem} />
      ))}
      <p>Total: ${total}</p>
    </div>
  );
}

// Other components can easily access
function CartBadge() {
  const itemCount = useCartStore(state => state.items.length);
  return <span>{itemCount}</span>;
}

Zustand 的优势

  • ✅ 无需 Provider 包裹
  • ✅ 代码量少,一个文件搞定
  • ✅ 性能好(组件级别的精确订阅)
  • ✅ API 简单,学习成本低
  • ✅ TypeScript 支持好

与 useReducer 对比

特性 useReducer Zustand
样板代码 较多 很少
跨组件共享 需要 Context 原生支持
学习曲线 中等
DevTools 需要自己实现 内置支持

AI 友好度:⭐⭐⭐⭐⭐(最高)

为什么 AI 最爱 Zustand?

  • ✅ 单文件可见全貌,AI 容易理解上下文
  • ✅ 模式统一,生成代码质量高
  • ✅ 没有跨文件引用,不会遗漏关联
  • ✅ TypeScript 类型推断友好,AI 生成的类型也准确

我的实际体验

我:帮我用 Zustand 写个购物车状态管理
Claude:[生成完整、可用的代码]
我:几乎不需要修改,直接能用 ✅

我:帮我用 Redux 写个购物车
Claude:[生成 actions、reducers、types...]
我:需要检查各个文件的关联,修改不一致的地方 ⚠️

Zustand 的适用场景

  • ✅ 中小型项目
  • ✅ 需要全局状态,但不想写太多代码
  • ✅ 与 AI 协作开发(AI 生成质量高)
  • ✅ 团队成员 React 经验参差不齐
  • ⚠️ 超大型项目可能需要更严格的规范(考虑 Redux)

第三层复杂度:服务端数据的特殊性

问题场景:数据同步的困境

// Environment: React
// Scenario: Product list + product detail
// Problem: How to keep data consistent?

function ProductList() {
  const [products, setProducts] = useState([]);
  const [loading, setLoading] = useState(false);
  
  useEffect(() => {
    setLoading(true);
    fetchProducts()
      .then(setProducts)
      .finally(() => setLoading(false));
  }, []);
  
  // Problem 1: Data may be stale when returning from detail page
  // Problem 2: Other users modified product, I see old data
  // Problem 3: Same product may show different data in list vs detail
}

function ProductDetail({ id }) {
  const [product, setProduct] = useState(null);
  
  useEffect(() => {
    fetchProduct(id).then(setProduct);
  }, [id]);
  
  const updateProduct = async (data) => {
    await updateProductAPI(id, data);
    setProduct(data); // Update detail page
    // Problem: What about the list page data?
  };
}

传统方案的问题

  • 数据缓存:什么时候重新请求?
  • 数据同步:多个组件如何共享同一份数据?
  • 加载状态:每个组件都要写 loading/error 逻辑
  • 数据过期:如何判断数据需要刷新?

解决方案4:React Query

// Environment: React + React Query
// Scenario: Elegantly manage server state

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

// List page
function ProductList() {
  const { data: products, isLoading, error } = useQuery({
    queryKey: ['products'],
    queryFn: fetchProducts,
    staleTime: 5 * 60 * 1000, // Consider data fresh for 5 minutes
  });
  
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <div>
      {products.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  );
}

// Detail page
function ProductDetail({ id }) {
  const queryClient = useQueryClient();
  
  const { data: product } = useQuery({
    queryKey: ['product', id],
    queryFn: () => fetchProduct(id),
  });
  
  const updateMutation = useMutation({
    mutationFn: (data) => updateProductAPI(id, data),
    onSuccess: (updatedProduct) => {
      // Update detail cache
      queryClient.setQueryData(['product', id], updatedProduct);
      
      // Invalidate list, trigger refetch
      queryClient.invalidateQueries(['products']);
      
      // Data auto synced!
    },
  });
  
  return (
    <div>
      <h1>{product.name}</h1>
      <button onClick={() => updateMutation.mutate(newData)}>
        Update
      </button>
    </div>
  );
}

React Query 的优势

  • ✅ 自动管理缓存
  • ✅ 自动重新获取(窗口获得焦点时、网络恢复时)
  • ✅ 自动去重(多个组件请求同一数据时只发一次请求)
  • ✅ 乐观更新、失败回滚
  • ✅ 分页、无限滚动支持
  • ✅ 内置 loading/error 状态

与 Zustand 的分工

状态类型 工具选择 示例
客户端状态 Zustand/Context Modal switch, theme, form draft
服务端状态 React Query User info, product list, order data

重要的认知转变

  • React Query 不是"状态管理库"
  • 它是"服务端状态同步工具"
  • 服务端数据有特殊的生命周期(获取、缓存、失效、重新获取)

AI 友好度:⭐⭐⭐⭐

AI 生成 React Query 代码的特点

  • ✅ AI 能生成标准的 useQuery/useMutation 代码
  • ✅ 常见模式(loading、error、success)AI 很熟悉
  • ⚠️ 复杂的缓存策略 AI 可能生成不当
  • ⚠️ optimistic updates 的逻辑 AI 容易出错

我的经验是:

  • 让 AI 生成基础的 useQuery 代码:质量很高 ✅
  • 涉及复杂的 cache invalidation:需要人工审查 ⚠️
  • Mutation 的 onSuccess/onError 逻辑:AI 可能不够完善 ⚠️

SWR vs React Query

// Environment: React + SWR
// Scenario: SWR syntax (more concise)

import useSWR from 'swr';

function ProductList() {
  const { data, error } = useSWR('/api/products', fetcher);
  // Simpler, but slightly less powerful
}

对比

特性 React Query SWR
功能完整度 更强大 够用
API 复杂度 稍复杂 更简洁
社区规模 更大 较小
AI 生成质量 ⭐⭐⭐⭐ ⭐⭐⭐⭐

AI 对两者的支持

  • 两者都是声明式 API,AI 都能生成好
  • SWR 更简单,AI 生成的代码更"干净"
  • React Query 功能更强,但 AI 可能用不到高级特性

第四层复杂度:Redux 真的需要吗?

Redux 的定位

// Environment: React + Redux Toolkit
// Scenario: Modern Redux (already much simpler)

import { createSlice, configureStore } from '@reduxjs/toolkit';

// Slice: combines actions and reducer
const cartSlice = createSlice({
  name: 'cart',
  initialState: { items: [] },
  reducers: {
    addItem: (state, action) => {
      // Redux Toolkit supports "mutable" syntax (uses Immer internally)
      const existing = state.items.find(item => item.id === action.payload.id);
      if (existing) {
        existing.quantity += 1;
      } else {
        state.items.push({ ...action.payload, quantity: 1 });
      }
    },
    removeItem: (state, action) => {
      state.items = state.items.filter(item => item.id !== action.payload);
    },
  },
});

// Store
const store = configureStore({
  reducer: {
    cart: cartSlice.reducer,
  },
});

// Use in component
function Cart() {
  const items = useSelector(state => state.cart.items);
  const dispatch = useDispatch();
  
  return (
    <button onClick={() => dispatch(cartSlice.actions.addItem(product))}>
      Add to Cart
    </button>
  );
}

Redux 的优势

  • ✅ 强大的 DevTools(时间旅行调试)
  • ✅ 严格的状态管理规范(适合大团队)
  • ✅ 中间件生态丰富(redux-saga、redux-thunk)
  • ✅ 社区最大,资源最多

Redux 的问题

  • ❌ 即使用了 Toolkit,代码量仍然多
  • ❌ 学习曲线陡峭
  • ❌ 简单功能也需要完整的流程

AI 友好度:⭐⭐⭐(中等)

AI 生成 Redux 代码的特点

  • ✅ Redux Toolkit 的 createSlice AI 能正确生成
  • ⚠️ 但跨文件的关联(types、actions、selectors)容易出问题
  • ⚠️ 中间件、异步 action 的逻辑 AI 容易生成过时的写法
  • ❌ 大型项目的文件组织 AI 可能不够合理

我的实际体验

我:用 Redux Toolkit 写个购物车
Claude:[生成 slice、store 配置...]
我:代码能用,但需要检查:
    - 是否遵循了项目的文件组织规范?
    - Selector 是否需要用 reselect 优化?
    - 异步逻辑是否应该用 createAsyncThunk?

何时真正需要 Redux?

我的思考(不一定准确):

✅ 适合 Redux 的场景

  • 超大型项目(100+ 组件,10+ 开发者)
  • 需要严格的代码规范和审查
  • 需要时间旅行调试
  • 复杂的状态依赖关系
  • 需要中间件(日志、埋点、权限控制)

❌ 不需要 Redux 的场景

  • 中小型项目(Zustand 够用)
  • 快速迭代(Redux 太重)
  • 团队 React 经验不足(学习成本高)
  • 主要是服务端数据(React Query 更合适)

一个判断标准

如果你不确定是否需要 Redux,那你可能不需要它。 — Dan Abramov(Redux 作者)

AI 协作的建议

  • 与 AI 协作时,Zustand 的开发效率更高
  • Redux 需要更多人工审查和调整
  • 除非项目确实需要 Redux 的严格性,否则优先 Zustand

决策树:如何选择状态管理方案

完整的决策流程

graph TD
    A[需要管理状态?] --> B{状态类型?}
    
    B --> |服务端数据| C[React Query / SWR]
    
    B --> |客户端状态| D{使用范围?}
    
    D --> |单个组件| E[useState / useReducer]
    
    D --> |多个组件| F{层级关系?}
    
    F --> |父子2层内| G[Props传递]
    
    F --> |跨3层以上| H{项目规模?}
    
    H --> |小型| I{数据变化频率?}
    I --> |低| J[Context]
    I --> |高| K[Zustand]
    
    H --> |中型| K[Zustand]
    
    H --> |大型| L{团队规模?}
    L --> |小于5人| K
    L --> |大于5人| M[Redux]
    
    style C fill:#e1f5dd
    style E fill:#e1f5dd
    style G fill:#e1f5dd
    style J fill:#fff4cc
    style K fill:#d4edff
    style M fill:#ffe0e0

方案对比表

方案 学习成本 代码量 性能 AI友好度 适用场景
useState 最少 ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐⭐ 单组件状态
Context ⭐⭐ ⭐⭐⭐ ⭐⭐⭐ 跨层级、低频变化
useReducer ⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐⭐ 复杂状态逻辑
Zustand ⭐⭐ ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐⭐ 全局状态(推荐)
React Query ⭐⭐⭐ ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐ 服务端数据(必选)
Redux ⭐⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐ 大型项目、严格规范

我的推荐组合

小型项目(个人项目、demo):

useState + Context + React Query

中型项目(几人小团队):

Zustand (client state) + React Query (server data)

大型项目(跨团队协作):

Redux (complex logic) + React Query (server data)

AI 协作优先

Zustand (most efficient) + React Query

延伸与发散:AI 时代的状态管理思考

AI 生成代码的特点总结

通过前面的分析,我发现 AI 在状态管理方面有明显的倾向:

AI 擅长的

  • ✅ 模式统一的代码(Zustand、React Query)
  • ✅ 单文件可见全貌(不需要跨文件理解)
  • ✅ 声明式 API(useQuery、useState)
  • ✅ 结构清晰的 Reducer

AI 不擅长的

  • ❌ 跨文件的依赖关系(Redux 的 actions/reducers 分离)
  • ❌ 性能优化细节(Context 的 split、memo)
  • ❌ 复杂的缓存策略
  • ❌ 架构级别的决策(该用哪个工具)

AI 会"骗"你什么?

问题1:AI 可能推荐过于复杂的方案

你:帮我做个 todo list
AI:[生成完整的 Redux 方案]
实际:useState 就够了

为什么?

  • AI 的训练数据中,Redux 的示例很多
  • AI 倾向生成"完整"的解决方案
  • 但不一定考虑你的项目规模

问题2:AI 可能忽略性能问题

// Environment: React + Context
// Scenario: AI generated Context code

const AppContext = createContext();

function AppProvider({ children }) {
  const [user, setUser] = useState(null);
  const [theme, setTheme] = useState('light');
  const [cart, setCart] = useState([]);
  
  // ❌ AI may not tell you: this causes all consumers to re-render
  return (
    <AppContext.Provider value={{ user, theme, cart, setUser, setTheme, setCart }}>
      {children}
    </AppContext.Provider>
  );
}

应该做的

// Split into multiple Contexts
const UserContext = createContext();
const ThemeContext = createContext();
const CartContext = createContext();

问题3:AI 可能生成过时的写法

// AI may generate old Redux pattern
const ADD_TODO = 'ADD_TODO';

function addTodo(text) {
  return { type: ADD_TODO, text };
}

function todoReducer(state = [], action) {
  switch (action.type) {
    case ADD_TODO:
      return [...state, { text: action.text }];
    default:
      return state;
  }
}

// Actually Redux Toolkit's createSlice is more concise

如何与 AI 更好地协作

策略1:明确告诉 AI 项目规模

❌ Not good: Help me with state management
✅ Better: I'm building a medium-sized project (20 components), 
          need to manage user info and cart, use Zustand

策略2:要求 AI 说明选择理由

你:为什么选择 Redux 而不是 Zustand?
AI:因为你提到了需要时间旅行调试和中间件...
你:哦我不需要这些,那用 Zustand 吧

策略3:分步骤验证

  1. 让 AI 生成基础代码

  2. 自行检查性能和安全性

  3. 让 AI 优化特定部分(而非完全重写)

策略4:建立自己的代码模板

  1. 将已验证的优秀代码保存为模板

  2. 下次让 AI “基于此模板生成代码”

  3. AI 将模仿你的模板,而不是使用其默认模式

未来的思考

问题:AI 时代,状态管理会如何演进?

我的一些猜想(不一定对):

  1. 更简洁的 API

    • AI 友好的工具会越来越流行(Zustand、Jotai)
    • 复杂的样板代码工具可能被淘汰
  2. 智能化的状态管理

    • AI 能否自动判断何时需要状态管理?
    • AI 能否自动优化性能问题?
  3. 本地优先(Local-first)架构

    • 离线优先的应用越来越多
    • 状态同步会变得更复杂
    • 需要新的工具和模式
  4. AI 原生的状态设计

    • 如果从一开始就考虑 AI 协作
    • 状态管理工具会如何设计?

待探索的问题

  • Signals(SolidJS)会成为主流吗?
  • 服务端组件(RSC)如何改变状态管理?
  • AI Agent 执行多步骤任务的状态如何设计?

小结

这篇文章更多是我在 AI 协作开发中的思考和实践。

核心收获

  • 状态管理不是"选库",而是"理解需求 → 选择合适方案"
  • AI 擅长生成简洁、统一的代码(Zustand、React Query)
  • AI 不擅长架构决策和性能优化
  • 与 AI 协作时,人类需要把控方向,AI 负责执行

实用建议

  • 优先选择 AI 友好的工具(Zustand + React Query)
  • 明确告诉 AI 项目规模和具体需求
  • 审查 AI 生成的代码(尤其是性能和架构)
  • 建立自己的代码模板,让 AI 模仿

开放性问题

  • 你在 AI 协作开发中遇到过哪些坑?
  • AI 生成的状态管理代码,你会直接用还是会修改?
  • 如果让你设计一个"AI 友好"的状态管理库,你会怎么做?

参考资料

2026 技术风向:为什么在 AI 时代,PostgreSQL 彻底成为了全栈工程师的首选数据库

在 Web 开发的黄金十年里,LAMP 架构(Linux, Apache, MySQL, PHP)奠定了 MySQL 不可撼动的霸主地位。那是互联网的草莽时代,业务逻辑相对简单,读多写少,开发者对数据库的诉求仅仅是“稳定存储”。

然而,时间来到 2026 年。随着 Node.js 与 TypeScript 生态的统治级渗透,以 Next.js、NestJS 为代表的现代全栈框架(Modern Stack)彻底改变了应用开发的范式。在这个由 Serverless、Edge Computing 和 AI 驱动的新时代,MySQL 逐渐显得力不从心。与此同时,PostgreSQL(下文简称 PG)凭借其惊人的演进速度,成为了全栈工程师事实上的“默认选项”。

这不仅仅是技术偏好的转移,更是架构复杂性倒逼下的必然选择。

建筑学的视角:预制板房 vs 模块化摩天大楼

要理解为什么 PG 在现代架构中胜出,我们必须从底层设计哲学说起。如果把数据库比作建筑:

MySQL 像是一栋“预制板搭建的经济适用房”。
它结构紧凑,开箱即用,对于标准的居住需求(基础 CRUD、简单事务)来说,它表现优异且成本低廉。但是,它的结构是固化的。如果你想在顶楼加建一个停机坪(向量搜索),或者把承重墙打通做成开放式空间(非结构化数据存储),你会发现极其困难。它的存储引擎(InnoDB)虽然优秀,但与上层逻辑耦合较紧,扩展性受限。

PostgreSQL 像是一座“钢结构模块化摩天大楼”。
它的底座(存储与事务引擎)极其坚固,严格遵循 SQL 标准与 ACID 原则。但它最核心的竞争力在于其可插拔的模块化设计(Extensibility)

  • 你需要处理地理空间数据?插入 PostGIS 模块,它立刻变成专业的 GIS 数据库。
  • 你需要做高频时序分析?插入 TimescaleDB 模块。
  • 你需要 AI 向量搜索?插入 pgvector 模块。

PG 不仅仅是一个数据库,它是一个数据平台内核。这种“无限生长”的能力,完美契合了 2026 年复杂多变的业务需求。

全栈工程师偏爱 PG 的三大理由

在 Next.js/NestJS 的全栈生态中,Prisma 和 Drizzle ORM 的流行进一步抹平了数据库的方言差异,让开发者更能关注数据库的功能特性。以下是 PG 胜出的三个关键维度。

1. JSONB:终结 NoSQL 的伪需求

在电商系统中,我们经常面临一个棘手的问题:商品(SKU)属性的非结构化。

  • 衣服:颜色、尺码、材质。
  • 手机:屏幕分辨率、CPU型号、内存大小。
  • 图书:作者、ISBN、出版社。

在 MySQL 时代,为了处理这些动态字段,开发者通常有两种痛苦的选择:要么设计极其复杂的 EAV(实体-属性-值)模型,要么引入 MongoDB 专门存储商品详情,导致需要维护两个数据库,并在应用层处理数据同步(Distributed Transaction 问题)。

MySQL 虽然支持 JSON 类型,但在索引机制和查询性能上一直存在短板。

PG 的解法是 JSONB(Binary JSON)。
PG 不仅仅是将 JSON 作为文本存储,而是在写入时将其解析为二进制格式。这意味着:

  1. 解析速度极快:读取时无需重新解析。
  2. 强大的索引支持:你可以利用 GIN(Generalized Inverted Index,通用倒排索引)对 JSON 内部的任意字段建立索引。

场景示例:
不需要引入 MongoDB,你可以直接在 PG 中查询:“查找所有红色且内存大于 8GB 的手机”。

SQL

-- 利用 @> 操作符利用 GIN 索引进行极速查询
SELECT * FROM products 
WHERE attributes @> '{"color": "red"}' 
AND (attributes->>'ram')::int > 8;

对于全栈工程师而言,这意味着架构的极度简化:One Database, All Data Types.

2. pgvector:AI 时代的“降维打击”

AI 应用的爆发,特别是 RAG(检索增强生成)技术的普及,催生了向量数据库(Vector Database)的需求。

传统的 AI 架构通常是割裂的:

  • MySQL:存储用户、订单等元数据。
  • Pinecone/Milvus:存储向量数据(Embeddings)。
  • Redis:做缓存。

这种架构对全栈团队简直是噩梦。你需要维护三套基础设施,处理数据一致性,还要编写复杂的胶水代码来聚合查询结果。

PG 的解法是 pgvector 插件。
通过安装这个插件,PG 瞬间具备了存储高维向量和进行相似度搜索(Cosine Similarity, L2 Distance)的能力。更重要的是,它支持 HNSW(Hierarchical Navigable Small World)索引,查询性能足以应对绝大多数生产场景。

实战场景:AI 电商系统的“以图搜图”
用户上传一张图片,系统需要推荐相似商品,但同时必须满足“价格低于 1000 元”且“有库存”的硬性条件。

在 PG 中,这只是一个 SQL 查询

SQL

SELECT id, name, price, attributes
FROM products
WHERE stock > 0                       -- 关系型过滤
  AND price < 1000                    -- 关系型过滤
ORDER BY embedding <=> $1             -- 向量相似度排序($1 为用户上传图片的向量)
LIMIT 10;

这种混合查询(Hybrid Search)能力是 PG 对专用向量数据库的降维打击。它消除了数据搬运的成本,保证了事务的一致性(你肯定不希望搜出来的商品其实已经下架了)。

3. 生态与插件:长期主义的选择

MySQL 的功能迭代主要依赖于 Oracle 官方的发版节奏。而 PG 的插件机制允许社区在不修改核心代码的前提下扩展数据库功能。

在 Node.js 全栈项目中,我们经常会用到:

  • pg_cron:直接在数据库层面运行定时任务,无需在 NestJS 里写 cron job。
  • PostGIS:处理配送范围、地理围栏,这是目前地球上最强大的开源 GIS 引擎。
  • zombodb:将 Elasticsearch 的搜索能力集成到 PG 索引中。

对于全栈工程师来说,PG 就像是一个拥有海量 npm 包的运行时环境,你总能找到解决特定问题的插件。

实战架构图谱:构建 Next-Gen AI 电商

基于上述分析,一个典型的 2026 年现代化全栈电商系统的后端架构可以被压缩得极其精简。我们不再需要“全家桶”式的中间件,一个 PostgreSQL 集群足矣。

架构设计

  • 技术栈:Next.js (App Router) + Prisma ORM + PostgreSQL.
  • 数据模型设计

TypeScript

// Prisma Schema 示例
model Product {
  id          Int      @id @default(autoincrement())
  name        String
  price       Decimal
  stock       Int
  // 核心特性 1: 结构化数据与非结构化数据同表
  attributes  Json     // 存储颜色、尺码等动态属性
  
  // 核心特性 2: 原生向量支持 (通过 Prisma Unsupported 类型)
  embedding   Unsupported("vector(1536)") 
  
  // 核心特性 3: 强一致性关系
  orders      OrderItem[]
  
  @@index([attributes(ops: JsonbPathOps)], type: Gin) // GIN 索引加速 JSON 查询
  @@index([embedding], type: Hnsw) // HNSW 索引加速向量搜索
}

业务流转

  1. 商品录入:结构化字段存入 Column,非结构化规格存入 attributes (JSONB),同时调用 OpenAI API 生成 Embedding 存入 embedding 字段。
  2. 交易环节:利用 PG 成熟的 MVCC(多版本并发控制)和 ACID 事务处理高并发订单写入,无需担心锁竞争(相比 MySQL 的 Gap Lock,PG 在高并发写入下往往表现更优)。
  3. 搜索推荐:利用 pgvector 实现基于语义或图片的推荐,同时结合 attributes 中的 JSON 字段进行精准过滤。

结论:Simplicity is Scalability(简单即是扩展)。少维护一个 MongoDB 和一个 Pinecone,意味着系统故障点减少了 66%,开发效率提升了 100%。

结语:数据库的终局

在 2026 年的今天,我们讨论 PostgreSQL 时,已经不再仅仅是在讨论一个关系型数据库(RDBMS)。

PostgreSQL 已经演变成了一个通用多模态数据平台(General-Purpose Multi-Model Data Platform) 。它既是关系型数据库,也是文档数据库,更是向量数据库和时序数据库。

对于追求效率与掌控力的全栈工程师而言,MySQL 依然是 Web 1.0/2.0 时代的丰碑,但在构建 AI 驱动的复杂应用时,PostgreSQL 提供了更广阔的自由度和更坚实的底层支撑。

拥抱 PostgreSQL,不仅是选择了一个数据库,更是选择了一种“做减法”的架构哲学。

我写了个 code-review 的 Agent Skill, 没想到火了

前两天随手写了个 Claude Code 的 Skill,专门做 Code Review 的,发了条推之后就没太在意。

结果第二天醒来一看,GitHub Star 刷刷往上涨,评论区也炸了,不少人说"终于有个靠谱的 Code Review 工具了"。

image.png

说实话,有点意外。

倒不是说这个 Skill 有多了不起,而是它戳中了一个很真实的痛点——大部分团队的 Code Review,要么走过场,要么全靠人肉。

先说说为什么要做这个

做这个 Skill 的起因其实很简单。

我自己平时写代码,改完了之后经常想让 Claude Code 帮我 review 一下。直接跟它说"帮我看看代码有没有问题",它确实会给你一些反馈,但说实话,质量参差不齐。

这就跟新来的实习生做 Code Review 一样,不是他不想认真看,是他不知道该看什么、怎么看、按什么优先级来。

所以问题的本质是:模型需要一套结构化的 Review 框架,告诉它该检查什么、怎么分级、用什么格式输出。

这不就是 Skill 最擅长干的事吗?

code-review-expert 是什么

一句话概括:一个让 AI 用资深工程师的视角帮你做 Code Review 的 Skill。

安装方式就一行:

npx skills add sanyuan0704/code-review-expert

装好之后在 Claude Code 里输入 /code-review-expert,它就会自动 review 你当前的 git changes。

整个 review 流程我是精心设计过的,分成这么几步:

第一步:Preflight(了解改动范围)

它会先跑 git diff 看看你改了哪些文件、改了多少行。如果改动量超过 500 行,它会先按模块分批 review,不会一口气全看完然后给你一堆乱七八糟的反馈。

第二步:SOLID + 架构检查

这一步是我花了最多时间打磨的。我写了一份详细的 SOLID checklist,把每个原则对应的"坏味道"都列出来了。

比如检查 SRP(单一职责),它不会只是泛泛地说"这个文件职责太多了",而是会问一个很具体的问题:"这个模块有几个不同的修改理由?" 如果一个文件既管 HTTP 请求,又管数据库操作,还管业务逻辑,那它大概率违反了 SRP。

第三步:发现可以删掉的代码

这步其实挺有意思的。很多项目里都有一堆死代码——feature flag 关掉的、被废弃的 API、没人用的工具函数。它会帮你找出来,并且区分"可以直接删"和"需要制定计划再删"两种情况。

第四步:安全扫描

XSS、SQL 注入、SSRF、路径穿越、竞态条件、密钥泄露……这些它都会检查。

其中竞态条件(Race Condition)这块我写的特别详细,因为这是很多人在 review 时最容易忽略的。它会专门去找 check-then-act 模式、读-改-写操作、并发数据库访问这些容易出问题的场景。

第五步:代码质量扫描

错误处理有没有吞掉异常?有没有数据库的 N+1 查询?空值检查到不到位?这些"小问题"在生产环境里都可能变成大事故或者性能问题。

最后:结构化输出 + 确认

所有发现按严重程度分成四个等级:

等级 含义 怎么处理
P0 严重 必须 block merge
P1 高危 应该在合并前修复
P2 中等 这个 PR 修或者建个 follow-up
P3 低优 可选优化

输出之后,它不会自作主张去改代码。而是先问你:要修全部,还是只修 P0/P1,或者修指定的。

这个"先 review 再确认"的设计是我特意做的——Code Review 的价值不只是发现问题,更重要的是让你理解问题。如果 AI 直接帮你改了,你连有什么问题都不知道,那这个 review 就没意义了。

为什么我觉得它火了

发完推之后,仓库几天内涨到了 460+ Star,40+ Fork。

评论区和私信里,大家反馈最多的是两点:

第一,"终于有个体系化的 Review 方案了"

很多独立开发者和小团队,根本没有 Code Review 的流程。不是不想做,是没人帮你 review。有了这个 Skill,相当于随时有个资深工程师帮你把关。

这个需求其实比我想象的要大。我之前以为 Code Review 主要是大厂的需求,没想到独立开发者和小团队对这块的渴求更强烈——因为他们更没有犯错的资本。

第二,"终于不是 AI 味十足的泛泛建议了"

image.png

这要归功于那几份 checklist。我把 security-checklist、solid-checklist、code-quality-checklist 都放在了 references/ 目录下,每份都是实打实的检查清单,不是那种"注意安全问题"之类的废话。

比如安全检查那份,光竞态条件就列了四个子类:共享状态访问、TOCTOU(检查后使用)、数据库并发、分布式系统。每个子类下面都有具体的代码模式和需要问的问题。

这就是 Skill 的魅力——你把专业知识结构化地喂给模型,它的输出质量会有质的提升。

怎么做到的?聊聊 Skill 的设计思路

这个 Skill 的结构很简单:

code-review-expert/
├── SKILL.md                  # 主文件,定义整个 review 流程
├── agents/
│   └── agent.yaml            # Agent 配置
└── references/
    ├── solid-checklist.md    # SOLID 原则检查清单
    ├── security-checklist.md # 安全检查清单
    ├── code-quality-checklist.md # 代码质量检查清单
    └── removal-plan.md       # 代码清理计划模板

核心设计有几个关键点:

1. references 实现按需加载

这是 Skill 体系最优雅的地方。

四份 checklist 的内容加起来好几千字,如果全塞进 SKILL.md,一上来就会吃掉大量上下文窗口。所以我把它们放在 references/ 里,SKILL.md 里只在需要的步骤写 Load references/xxx.md

模型执行到那个步骤时才会去读对应的文件,用完就可以"忘掉"了。这就是之前文章里讲过的 Progressive Disclosure(渐进式加载),Skills 最精妙的设计之一。

2. Workflow 要设计得有节奏感

我试过把所有检查点平铺在一起,效果很差——模型会东一榔头西一棒子,安全问题和命名规范混在一起说。

最后我按照真实的 Code Review 流程来编排:先看改动范围,再看架构设计,然后看安全,最后看代码质量。每一步之间是递进关系,从宏观到微观。

这个设计借鉴了人来做 Code Review 的习惯——好的 reviewer 不会上来就抠细节,而是先理解整体改动的意图和影响范围。

写在最后

你猜我写这个 skill 花了多久?

3,2,1,揭晓答案。

我只花了 10 分钟。不可思议吧。

怎么做到的?现在 claude 官方有一个叫 skill-creator 的 skill,帮你来写 skill,然后基于它可以很快搭出骨架来。后续,就是基于我的专业经验,引导 agent 帮我把一些关键的原则拆分为各个 checklist 文档,聊个几轮,这个高质量的 skill 就完工了。

回头看这件事,我觉得这也是 Skills 生态最让人兴奋的地方:每个有专业积累的开发者,都可以很快把自己的经验沉淀成一个 Skill,让 AI 帮更多人受益。

你不需要会写 MCP Server,不需要懂协议,不需要搞 OAuth 鉴权。就是一个 Markdown 文件 + 几份参考文档,仅此而已。

仓库在这里,欢迎 Star 和提 PR:

GitHub: sanyuan0704/code-review-expert

安装:npx skills add sanyuan0704/code-review-expert

如果你也在做 Skill 开发,或者有什么好用的 Skill 推荐,评论区欢迎来聊。

AI Agent开发之向量检索:一篇讲清「稀疏 + 稠密 + Hybrid Search」怎么落地

AI Agent开发之向量检索:一篇讲清「稀疏 + 稠密 + Hybrid Search」怎么落地

核心结论

在 AI 搜索和知识库场景中,混合检索(Hybrid Search)是当前最优解:

  • 稠密向量(Dense):擅长处理语义相似的查询,能够理解同义词、口语化表达
  • 稀疏向量(Sparse):擅长精确匹配关键词,如产品名称、接口名、错误码等专有术语
  • 混合检索(Hybrid):通过 RRF(Reciprocal Rank Fusion)算法融合两者优势,在生产环境中表现最稳定

单独使用稠密向量会导致专有名词召回不准确,而仅使用稀疏向量则无法理解语义相近的不同表述。混合检索能够同时规避这两个问题。

应用场景与痛点分析

典型应用场景

混合检索方案特别适用于以下前端场景:

  • 站内搜索:用户使用自然语言或关键词检索站内内容
  • 帮助中心问答:智能匹配用户问题与知识库文档
  • 聊天助手上下文召回:为 AI 助手提供相关上下文信息

单一检索方案的局限性

仅使用稠密向量检索时的问题:

  • 专有名词召回不稳定:如 "ERR_CONNECTION_RESET" 等错误码可能无法准确匹配
  • 短查询偏移:当用户输入 2~6 个词的短查询时,容易产生语义偏移

仅使用 BM25/关键词检索时的问题:

  • 语义理解缺失:"登录失败" 和 "无法完成认证" 虽然语义相近,但因关键词不同导致召回效果差

技术架构

flowchart LR
  A["文档内容"] --> B["生成稠密向量<br/>Embedding"]
  A --> C["生成稀疏向量<br/>分词+词频"]
  B --> D["写入向量库(dense)"]
  C --> E["写入向量库(sparse)"]

  Q["用户Query"] --> Q1["Query Embedding"]
  Q --> Q2["Query Sparse Vector"]

  Q1 --> S1["Dense Search"]
  Q2 --> S2["Sparse Search"]
  S1 --> F["RRF 融合排序"]
  S2 --> F
  F --> R["TopK 返回前端"]

稀疏向量与稠密向量的本质区别

稀疏向量(Sparse)

  • 来源:分词 + 词频(TF),可叠加 IDF/BM25
  • 特征:高维稀疏(大部分是 0)
  • 长处:关键词强匹配、可解释

示例文本:我是好学生,每天8点起床

分词后:

["我", "是", "好", "学生", "每天", "8", "点", "起床"]

稀疏结构(示意):

{
  indices: [102, 1552, 30091],
  values: [1, 1, 1]
}

稠密向量(Dense)

  • 来源:Embedding 模型(如 text-embedding-3-small
  • 特征:低维连续浮点向量
  • 长处:语义理解强(能懂同义改写)

核心实现

以下代码采用通用写法,不依赖特定项目结构,可直接迁移到任意 TypeScript 项目中

文档入库:双向量写入策略

async function addDocument(content: string, metadata?: Record<string, any>) {
  const dense = await embedText(content) // number[]
  const sparse = textToSparseVector(content) // { indices, values }

  await qdrant.upsert('documents', {
    points: [
      {
        id: crypto.randomUUID(),
        vector: {
          dense,
          bm25: sparse,
        },
        payload: { content, metadata },
      },
    ],
  })
}

稀疏向量生成:分词 + 哈希 + 词频统计

import { createRequire } from 'node:module'
import { Jieba } from '@node-rs/jieba'

type SparseVector = { indices: number[]; values: number[] }

const require = createRequire(import.meta.url)
const { dict } = require('@node-rs/jieba/dict') as { dict: Uint8Array }
const jieba = Jieba.withDict(dict)

function fnv1aHash(str: string): number {
  let hash = 0x811c9dc5
  for (let i = 0; i < str.length; i++) {
    hash ^= str.charCodeAt(i)
    hash = Math.imul(hash, 0x01000193)
  }
  return hash >>> 0
}

function textToSparseVector(text: string): SparseVector {
  const tokens = jieba
    .cutForSearch(text, true)
    .map((t) => t.trim().toLowerCase())
    .filter(Boolean)
    .filter((t) => !/^[\p{P}\p{S}\p{Z}]+$/u.test(t))

  const tf = new Map<number, number>()
  for (const token of tokens) {
    const idx = fnv1aHash(token)
    tf.set(idx, (tf.get(idx) ?? 0) + 1)
  }

  const entries = [...tf.entries()].sort((a, b) => a[0] - b[0])
  return {
    indices: entries.map(([i]) => i),
    values: entries.map(([, v]) => v),
  }
}

向量数据库配置:双向量索引声明

await qdrant.createCollection('documents', {
  vectors: {
    dense: { size: 512, distance: 'Cosine' },
  },
  sparse_vectors: {
    bm25: { modifier: 'idf' },
  },
})

说明:

  • 稀疏向量通常先传 TF(词频)
  • IDF 在向量库侧处理(这里是 modifier: 'idf'

查询实现:三种检索模式

type SearchMode = 'dense' | 'sparse' | 'hybrid'

async function search(query: string, topK = 5, mode: SearchMode = 'hybrid') {
  const querySparse = textToSparseVector(query)
  const queryDense = mode === 'sparse' ? null : await embedText(query)

  if (mode === 'dense') return searchDense(queryDense!, topK)
  if (mode === 'sparse') return searchSparse(querySparse, topK)

  const [denseRes, sparseRes] = await Promise.all([
    searchDense(queryDense!, topK),
    searchSparse(querySparse, topK),
  ])
  return fuseByRRF(denseRes, sparseRes, topK)
}

RRF 融合算法:工程化的最佳选择

const RRF_K = 60
const rrf = (rank: number) => 1 / (RRF_K + rank + 1)

RRF(Reciprocal Rank Fusion)算法的核心思想是基于排名而非分数进行融合。当同一文档在稠密检索和稀疏检索的结果中排名都靠前时,其最终融合分数会更高。

相比于传统的加权融合方法,RRF 的优势在于:

  • 无需手动调整稠密向量和稀疏向量的权重比例
  • 对不同业务场景的适应性更强
  • 实现简单且效果稳定

实施路径

基于上述技术方案,完整的实施流程包括以下步骤:

  1. 选择 Embedding 模型:初期可选择 512 维的轻量级模型,平衡性能与成本
  2. 实现双向量生成:在文本入库时同时生成稠密向量和稀疏向量
  3. 配置向量数据库:创建包含 vectorssparse_vectors 的集合
  4. 实现混合检索:搜索接口默认使用 hybrid 模式
  5. 提供模式切换:为前端提供检索模式切换能力,支持关键词优先场景(sparse 模式)

常见问题与最佳实践

稀疏查询向量为空的处理

当查询文本全是标点符号或停用词时,稀疏向量可能为空。此时应返回空数组或降级到纯稠密检索,避免出现异常。

稠密向量的必要性检查

在稠密检索分支中,必须确保 embedding 已成功生成。空向量应直接抛出错误,而非静默返回不可靠的结果。

向量维度变更与数据迁移

当 embedding 模型的向量维度发生变化(如从 512 维升级到 1536 维)时,现有的向量集合通常无法直接复用,需要重新生成所有文档的向量并迁移数据。

中文分词词典的重要性

业务专有术语如果未被包含在分词词典中,会显著影响稀疏向量的召回效果。建议根据业务场景定制分词词典,加入领域特定术语。

总结

混合检索方案将向量检索技术从算法研究转化为可落地的搜索体验工程实践:

  • 稠密向量负责语义理解,解决同义词和口语化表达问题
  • 稀疏向量负责关键词精确匹配,确保专有名词召回准确性
  • 混合检索通过 RRF 算法融合两者优势,保证生产环境的稳定性

手把手从 0 诠释大模型 API 的本质: Tools + MCP + Skills

本文写于 2026 年 02 月 15 日.

如今 AI Agent 的各种新概念层出不穷:

  • Tools
  • MCP
  • Skills

许多人都会有这样的疑问: Tools 和 MCP 有什么区别? 我用了 MCP 还需要 Tools 吗? Skills 是取代 MCP 的吗? 本文会从 LLM API 的底层设计开始, 一步步介绍 Tools 和 MCP 的区别, 手动实现一个非常简易的 MCP (简易到你会觉得"就这?"), 最后简单提一下 Skills.

几个重要事实

  • 大模型是无状态的, 它对你们的过往对话一点都没有记忆. 每次调用 LLM API, 都是一次全新的请求, 就像换了一个完全陌生的人说话.
  • 大模型本身的开发(或许)很难, 需要很强的数学知识. 但是大模型应用开发不难, 做纯工程开发的传统程序员也可以很快上手.
  • MCP 和 Skills 都是纯工程层面的设施, 和 AI 毫无关系. 也就是说, 在这两个概念出现以前, 你完全可以自己实现一套类似的机制, 不需要 LLM API 支持.

基于以上几个事实, 本文会选择 Anthropic API 来解释. 因为 OpenAI 的 Responses API 提供了一个叫做 previous_response_id 的参数, 很容易误导人以为 LLM 本身有记忆功能. 但实际上 LLM 是没有记忆的, 这个 previous_response_id 并不会给 LLM 使用, 而是 OpenAI 的服务层面的工程设施, 相当于 OpenAI 帮我们存了历史记录, 然后发给 LLM. Conversations API 同理.

相比之下, Anthropic API 就原生了许多, 更容易感受到 LLM API 的本质.

技术栈

请注意区分 @anthropic-ai/sdk@anthropic-ai/claude-agent-sdk. 前者是 Anthropic API 的封装, 本质上是一个 HTTP Client, 封装了大量的调用 API 的方法; 后者是对 Claude Code (Claude CLI) 的封装, 封装了大量调用 claude 命令行的方法.

本文会使用 GLM-4.7-flash 这个兼容 Anthropic API 的免费模型来节约成本, 毕竟 LLM 应用开发最大的痛点就是每次调试运行都需要花钱.

const client = new Anthropic({
  baseURL: 'https://api.z.ai/api/anthropic', // 国际版, 你也可以使用国内版, 国内版认证方式是 apiKey
  authToken: ZAI_API_KEY,
});

Hello World

首先从一个最简单的请求开始:

const resp = await client.messages.create({
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: '英国的首都是哪里',
    },
  ],
  model: 'glm-4.7-flash',
});

console.log(resp);

Output (省略掉不重要的字段):

{
  "id": "msg_202602151117137d34660397a4418d",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7-flash",
  "content": [
    {
      "type": "text",
      "text": "英国的首都是**伦敦**(London)。"
    }
  ],
  "stop_reason": "end_turn"
}

多轮对话

正如上面反复提到的, LLM 是无状态的, 每次调用都像是一个全新的完全陌生的人对话. 想象一下, 如果你要和一个人聊天, 每聊完一句, 对面都会换一个人, 那么对方换的人应该如何继续和你的聊天? 当然就是把你之前的聊天历史全部看一遍. 所以调用 LLM 的时候, 每次都需要把历史记录全部传过去.

// 用一个 messages 数组来维护历史记录
const messages: MessageParam[] = [
  {
    role: 'user',
    content: '英国的首都是哪里',
  },
];

const resp = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
});

// 重点: 将 LLM 的第一次回复放到数组里
messages.push({
  role: 'assistant',
  content: resp.content,
});

// 再加入第二次对话内容
messages.push({
  role: 'user',
  content: '介绍一下这个城市的污染情况',
});

console.log(inspect(messages));

const resp2 = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
});

console.log(resp2);

可以看看第二次调用 API 传入的 messages 内容是:

[
  {
    "role": "user",
    "content": "英国的首都是哪里"
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "英国的首都是**伦敦**。"
      }
    ]
  },
  {
    "role": "user",
    "content": "介绍一下这个城市的污染情况"
  }
]

而 resp2 成功返回了伦敦的污染情况, 说明 LLM 确实感知到了上一次对话内容的城市是伦敦.

{
  "id": "msg_20260215115536fd125b1bca954cf6",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7-flash",
  "content": [
    {
      "type": "text",
      "text": "伦敦作为全球国际化大都市和前工业革命中心,其污染历史可以追溯到维多利亚时代,且至今仍是全球空气质量治理的“典型样本”..." // 我手动省略, 减少篇幅, 并非 LLM 省略
    }
  ],
  "stop_reason": "end_turn"
}

所以你应该也知道了, 所谓的 context windows, 其实可以简单理解为 messages 数组的文本长度, 而不是单条消息的长度.

Tools

原始方法

LLM 就像一个很聪明(虽然有时候会很蠢, 但是我们先假定 LLM 很聪明)的大脑, 但是它只有大脑, 没有眼睛 - 意味着它无法接收外界的信息(除了手动传入的 messages), 比如读一个文件; 没有手 - 意味着它无法做出任何行为, 比如修改一个文件. (可以把 LLM 想象成一个遮住眼睛的霍金).

Tools 就相当于给一个大脑安装了外置眼睛和手. 我们先用最朴素的方式让 LLM 调用工具: 直接在 prompt 里写, 有哪些工具, params 分别是什么, 然后让 LLM 选择一个使用, 并提供 params.

const messages: MessageParam[] = [
  {
    role: 'user',
    content: `写一句话介绍中国农历马年.
      你有以下 tools 可以调用:
      1. { name: "write", description: "write content to a file", params: 
        { "content": {"type": "string", description: "content"} },
        { "path": {"type": "string", description: "the path of the file to write"} },
       }

      2. { name: "read", description: "read content of a file", params: 
        { "path": {"type": "string", description: "the path of the file to read"} }
       }

       请你选择一个工具使用, 并且提供正确的 params. 你需要输出一个 JSON
    `,
  },
];

Output:

{
  "id": "msg_202602151218464370b8983c6c474d",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7-flash",
  "content": [
    {
      "type": "text",
      "text": "```json\n{\n  \"tool\": \"write\",\n  \"params\": {\n    \"content\": \"中国农历马年象征着奔腾不息的活力与豪迈,寓意着奋进、自由与驰骋。\",\n    \"path\": \"/马年介绍.txt\"\n  }\n}\n```"
    }
  ],
  "stop_reason": "end_turn"
}

可以看到, LLM 做到了选择正确的工具, 提供的参数内容倒是没问题, 但是存在以下几个巨大的问题:

  1. 返回的 text 本质上是个字符串. 虽然在 prompt 里明确要求了需要返回一个 JSON, 但是 LLM 依然返回了一个 JSON markdown, 而不是纯 JSON 字符串.
  2. prompt 并不可靠. LLM 无法做到 100% 遵循 prompt, 尤其是能力比较差的模型, 它可能会输出"好的, 下面是我调用工具的 JSON: xxx". 也就是说, 并不能保证输出一定是一个 JSON markdown.
  3. 就算输出是一个 JSON markdown, 我们还需要去解析这个 markdown, 一旦涉及到嵌套, 也就是 params 里也包含反引号, 会更加复杂.
  4. 无法保证输出的 JSON 100% 遵循了 prompt 里的格式, 比如我在调用的时候就出现过返回了 arguments 字段, 而不是 params.

基于以上问题, Tool Use (或者叫 Tool Call, Function Call, 一个意思. Anthropic 的官方术语是 Tool Use) 被内置进了 LLM, 成为了 LLM 自身的一个能力. 也就是说, 如果一个 LLM 不支持 Tool Use, 那么我们基本是没法在工程层面去做 polyfill, 也就无法实现调用 tool.

标准方法

上面的例子, 换标准的 Tool Use 方法:

const messages: MessageParam[] = [
  {
    role: 'user',
    content: `写一个关于中国农历马年的一句话介绍, 写入 test.txt 里`,
  },
];

const resp = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
  tools: [
    {
      name: 'write',
      description: 'write content to a file',
      input_schema: {
        type: 'object',
        properties: {
          content: {
            type: 'string',
            description: 'content',
          },
          path: {
            type: 'string',
            description: 'the path of the file to write',
          },
        },
      },
    },
    // read 同理, 省略掉
  ],
});

Output:

{
  "id": "msg_20260215123307fffbbd1b9fd84652",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7-flash",
  "content": [
    {
      "type": "text",
      "text": "我来写一句关于中国农历马年的介绍并保存到文件中。"
    },
    {
      "type": "tool_use",
      "id": "call_49f0c1dbe920406192ce9347",
      "name": "write",
      "input": {
        "content": "中国农历马年象征着活力、热情与自由,是充满朝气与拼搏精神的吉祥年份。",
        "path": "test.txt"
      }
    }
  ],
  "stop_reason": "tool_use"
}

可以看到这次的 content 里多了一个 tool_use 的 block, 里面写明了需要调用的 tool 的名字和参数. 这个 block 的类型是结构化的, 也就是说可以 100% 保证格式是正确, 符合预期的 (但是不能保证 100% 有这个 block, 取决于 LLM 的能力, 太蠢的 LLM 可能无法决策到底用哪个 tool). 这样我们就可以根据这个结构化的 tool_use block, 去执行对于的函数调用.

结果回传

考虑一个场景: 让 LLM 阅读一个文件并分析内容. 经过上面的内容, 你应该知道具体的流程是:

  1. User 要求 LLM 阅读某个文件并分析内容, 并且传入 read tool schema
  2. LLM 决定使用 read tool, 参数是文件路径
  3. User 根据路径读取文件内容, 然后传给 LLM
  4. LLM 成功输出分析结果
const tools: ToolUnion[] = [
  // 本文省略具体内容, read 和 write 两个 tools
];

const messages: MessageParam[] = [
  {
    role: 'user',
    content: `分析一下 package.json`,
  },
];

// 初始请求
const resp = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
  tools,
});

// 把 LLM 的第一次返回加入到 messages 里
messages.push({
  role: 'assistant',
  content: resp.content,
});

// 第一次返回大概率会包含 tool_use block
// content 是一个数组, 可能额外包含一个 text, 也可能直接就是一个 tool_use
// content 可能包含多个 tool_use, 用户需要把所有的都调用, 然后根据 tool_use_id 去匹配结果
const toolUseResults: ContentBlockParam[] = [];
for (const block of resp.content) {
  if (block.type === 'tool_use') {
    switch (block.name) {
      case 'read':
        try {
          const content = await readFile(block.input.path, 'utf-8');
          toolUseResults.push({ tool_use_id: block.id, type: 'tool_result', content, is_error: false }); // is_error 告诉 LLM 这个调用是否成功
        } catch (err) {
          toolUseResults.push({
            tool_use_id: block.id,
            type: 'tool_result',
            content: JSON.stringify(err),
            is_error: true,
          });
        }

        break;

      case 'write':
        try {
          await writeFile(block.input.path, block.input.content);

          toolUseResults.push({ tool_use_id: block.id, type: 'tool_result', content: 'success', is_error: false });
        } catch (err) {
          toolUseResults.push({
            tool_use_id: block.id,
            type: 'tool_result',
            content: JSON.stringify(err),
            is_error: true,
          });
        }
        break;
    }
  }
}
// 将 tool use results 传给 LLM
messages.push({ role: 'user', content: toolUseResults });

console.log(inspect(messages));

const resp2 = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
  tools,
});
console.log(resp2);

第二次传给 LLM 的 messages 为:

[
  {
    "role": "user",
    "content": "分析一下 package.json"
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "我来帮你分析 package.json 文件。首先,我需要读取这个文件来查看它的内容。"
      },
      {
        "type": "tool_use",
        "id": "call_eeb390dfe8f345269ff95f42",
        "name": "read",
        "input": {
          "path": "package.json"
        }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "tool_use_id": "call_eeb390dfe8f345269ff95f42",
        "type": "tool_result",
        "content": "{\n  \"name\": \"gh-scout\",\n  \"module\": \"index.tsx\",\n  \"type\": \"module\",\n  \"private\": true,\n  \"devDependencies\": {\n    \"@types/bun\": \"latest\"\n  },\n  \"peerDependencies\": {\n    \"typescript\": \"^5\"\n  },\n  \"dependencies\": {\n    \"@anthropic-ai/sdk\": \"^0.74.0\"\n  }\n}\n",
        "is_error": false
      }
    ]
  }
]

第二次从 LLM 返回的结果为:

{
  "id": "msg_2026021512452122fcf4da65474784",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7-flash",
  "content": [
    {
      "type": "text",
      "text": "## 📦 `package.json` 文件分析\n\n### 基本信息\n\n| 字段 | 值 | 说明 |\n|------|-----|------|\n| **name** | `\"gh-scout\"` | 项目名称,用于 npm 包标识 |\n| **module** | `\"index.tsx\"` | ES 模块入口文件 |\n| **type** | `\"module\"` | 使用 ES6 模块语法 |\n| **private** | `true` | 标记为私有项目,防止误发布到 npm |\n\n### 依赖管理\n\n#### 🔧 开发依赖 (`devDependencies`)\n```json\n\"@types/bun\": \"latest\"\n```\n- 类型定义包,用于 Bun 运行时的 TypeScript 类型支持\n- `\"latest\"` 表示使用最新版本\n\n#### 🤝 对等依赖 (`peerDependencies`)\n```json\n\"typescript\": \"^5\"\n```\n- **关键点**:`typescript` 被标记为对等依赖\n- 这意味着**项目不直接依赖 TypeScript**,而是期望用户环境中已安装 TypeScript\n- 适用于插件/工具类项目,让用户自己选择 TS 版本\n\n#### ⚡ 运行时依赖 (`dependencies`)\n```json\n\"@anthropic-ai/sdk\": \"^0.74.0\"\n```\n- Anthropic AI 的官方 SDK\n- 版本范围 `^0.74.0` 表示安装 0.74.0 或更高版本(不超过主版本号)\n\n---\n\n### 📝 总结\n\n这是一个**轻量级的 TypeScript 工具项目**(`gh-scout`),主要特点:\n\n1. **无运行时依赖**:除了 Anthropic SDK 外,没有其他运行时依赖\n2. **依赖 TypeScript**:用户自己提供 TS 环境\n3. **使用 Bun**:通过 `@types/bun` 表明使用 Bun 运行环境\n4. **模块化设计**:ES 模块类型,入口为 `index.tsx`\n\n项目看起来是一个与 GitHub 相关的工具(从名字 \"gh-scout\" 推测),可能用于分析或监控 GitHub 相关的操作。"
    }
  ],
  "stop_reason": "end_turn"
}

可以看到, LLM 第一次告诉我们需要调用 read tool 来读取文件内容. 我们调用完毕后把结果传给 LLM, LLM 第二次就成功分析出了内容.

插个题外话: 看到这里, 你应该也觉得原生 LLM 的方式实在是太繁琐了.

  • messages 要手动维护
  • tool_use 要手动解析 LLM 的返回, 手动调用, 然后手动把结果传到 messages 数组里
  • 如果 LLM 后续还要调用其他 tools, 还需要手动写一个循环

这正是现在各种 AI Agent 框架的意义, 比如 LangChain, LangGraph, Agno 等, 它们底层其实也都是做这种事情, 和传统领域的框架一样, 把繁琐的步骤都封装好了, 就像写 React 就不需要手动去操作 DOM 一样.

MCP

上面的方式虽然繁琐, 但也完全覆盖了所有场景了. 任何 tool use 都可以用上面的方式去实现. 那么为什么还需要 MCP 呢?

MCP 是什么

MCP (model context protocol) 是一个协议, 定义了 MCP Client 和 MCP Server 的通信方式. MCP 的原理和 AI/LLM 没有任何关系, 只是定义了 tools/resources/prompt 三种信息的通信格式.

MCP 解决了什么问题

假设现在没有 MCP 这个概念.

众所周知, LLM 非常擅长写文档类的东西, 比如 PR description. 所以现在你想让 LLM 帮你在 github 提一个 PR. 你需要先定义一个 tool:

const tools: ToolUnion[] = [
  {
    name: 'github_create_pr',
    description: 'create a PR on github',
    input_schema: {
      type: 'object',
      properties: {
        repo: {
          type: 'string',
          description: 'The repo name. Format: {owner}/{repo_name}',
        },
        source_branch: {
          type: 'string',
          description: 'The source branch name',
        },
        target_branch: {
          type: 'string',
          description: 'The target branch name',
        },
        title: {
          type: 'string',
          description: 'The title of the PR',
        },
        description: {
          type: 'string',
          description: 'The description body of the PR',
        },
      },
    },
  },
];

然后实现这个 tool 的调用过程:

case 'github_create_pr':
  const { repo, source_branch, target_branch, title, description } = block.input;
  const [owner_name, repo_name] = repo.split('/');

  try {
    // 也可以用 gh cli
    const resp = await fetch(`https://api.github.com/repos/${owner_name}/${repo_name}/pulls`, {
      method: 'post',
      headers: {
        accept: 'application/vnd.github+json',
        authorization: 'Bearer GITHUB_TOKEN',
      },
      body: JSON.stringify({
        title,
        body: description,
        base: source_branch,
        head: target_branch,
      }),
    });

    toolUseResults.push({
      tool_use_id: block.id,
      type: 'tool_result',
      content: await resp.text(),
      is_error: false,
    });
  } catch (err) {
    toolUseResults.push({
      tool_use_id: block.id,
      type: 'tool_result',
      content: JSON.stringify(err),
      is_error: true,
    });
  }
  break;

每加一个这样的 tool, 都需要花费大量的精力. 但实际上这些 tools 是高度通用的, 调用 github 是一个很普遍的需求.

此时你可能想到, 那我封装一个 github_tools 不就可以了?

于是你行动力拉满, 自己(或者让 AI)封装了一个 github_tools, 发布到了 npm 上, 其他用户可以像这样使用你的库:

import { tools as githubTools, callTool } from '@arc/github_tools';

const tools = [...myTools, ...githubTools];

for (const block of resp.content) {
  if (block.type === 'tool_use') {
    if (block.name.startsWith('github')) {
      const result = await callTool(block);
    }
  }
}

但是此时又有了两个新的问题:

  1. 你的新项目使用了 Go/Rust, 用不了 npm 包.
  2. 由于 Anthropic API 太贵, 你决定迁移到 DeepSeek API, 但是 DeepSeek 对 Anthropic 的兼容性不是很好(假设), 有些格式不匹配, 导致你的库调用失败.

MCP 的出现就是为了解决上面的问题. MCP 本质上是把 tools 的定义和执行都外置出去了. MCP 分为 Client 和 Server, 其中 Server 就是外置出去的部分, 负责 tools 的定义和执行. 而 Client 就是留在 AI 应用的部分, 负责和 Server 通信:

  • Hi Server, 告诉我有哪些 tools 可以用?
  • Hi Server, 我现在要调用 github_create_pr 这个 tool, 参数是 { xxx }

最简易的 MCP 实现

知道了 MCP 的设计思想, 那么我们完全可以写一个最简易的实现:

const server = async ({ type, body }: { type: string; body?: any }): Promise<string> => {
  if (type === 'list_tools') {
    return JSON.stringify([
      {
        name: 'github_create_pr',
        description: 'create a PR on github',
        input_schema: {
          type: 'object',
          properties: {
            repo: {
              type: 'string',
              description: 'The repo name. Format: {owner}/{repo_name}',
            },
            source_branch: {
              type: 'string',
              description: 'The source branch name',
            },
            target_branch: {
              type: 'string',
              description: 'The target branch name',
            },
            title: {
              type: 'string',
              description: 'The title of the PR',
            },
            description: {
              type: 'string',
              description: 'The description body of the PR',
            },
          },
        },
      },
    ]);
  }

  if (type === 'call_tool') {
    switch (body.name) {
      case 'github_create_pr':
        const { repo, source_branch, target_branch, title, description } = body.input;
        const [owner_name, repo_name] = repo.split('/');
        try {
          const resp = await fetch(`https://api.github.com/repos/${owner_name}/${repo_name}/pulls`, {
            method: 'post',
            headers: {
              accept: 'application/vnd.github+json',
              authorization: 'Bearer GITHUB_TOKEN',
            },
            body: JSON.stringify({
              title,
              body: description,
              base: source_branch,
              head: target_branch,
            }),
          });
          return await resp.text();
        } catch (err) {
          return JSON.stringify(err);
        }
    }
  }

  return 'Unknown type';
};

为了简单起见, 我直接写的是一个函数. 你完全可以将其做成一个 HTTP server, 因为反正这个函数的返回类型是 string, 可以作为 HTTP Response.

然后再写一个 client:

class McpClient {
  async listTools() {
    const tools = await server({ type: 'list_tools' });
    return JSON.parse(tools) as ToolUnion[];
  }

  async callTool(name: string, params: any) {
    const res = await server({ type: 'call_tool', body: params });
    return res;
  }
}

发现了吗? 上面的代码和 LLM 一点关系都没有, 这也是我一直在强调的重点: MCP 是工程设计, 不是 LLM 自身能力. 你完全可以脱离 AI, 直接使用 github 的官方 mcp server, 手动调用里面提供的方法. AI 在这里面唯一做的事情只是帮你决定调用的 tool_name + params.

用我们自己实现的 MCP Client 和 Server 改写上面的代码:

const messages: MessageParam[] = [
  {
    role: 'user',
    content: `分析一下 package.json`,
  },
];

const mcpClient = new McpClient();
const resp = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
  tools: await mcpClient.listTools(),
});

const toolUseResults: ContentBlockParam[] = [];
for (const block of resp.content) {
  if (block.type === 'tool_use') {
    if (block.name.startsWith('github')) {
      try {
        const result = await mcpClient.callTool(block.name, block.input);
        toolUseResults.push({ tool_use_id: block.id, type: 'tool_result', content: result, is_error: false });
      } catch (err) {
        toolUseResults.push({
          tool_use_id: block.id,
          type: 'tool_result',
          content: JSON.stringify(err),
          is_error: true,
        });
      }
    }
  }
}
messages.push({ role: 'user', content: toolUseResults });

const resp2 = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
  tools,
});
console.log(resp2);

瞬间简洁了不少. github 相关的 tools 定义和实现都外置到了 MCP Server 上, 这样就做了两层解耦:

  1. 具体语言解耦 - 你可以用任何语言实现 MCP Server, 只要它能处理字符串.
  2. LLM 解耦 - 你可以用任何支持 tool use 的 LLM, MCP 协议里单独定义了字段, 和 LLM 自己的字段无关.

Skills

现在你已经了解到了:

  1. Tool Use 是 LLM 自身的能力.
  2. MCP 不是 LLM 自身的能力, 而是工程设计, 辅助 Tool Use 用的.

那么最近很火的 Skills 又是什么呢? 是取代 MCP 的吗? 当然不是.

LLM 的 context 是非常宝贵的. 如果在系统提示词里放入太多的内容, 会导致系统提示词本身就占据大量 context. 举个例子, 假设你在开发一个 Coding Agent, 你集成了 github MCP Server, 那么每次 LLM API 调用, 都会把完整的 github MCP 相关的 tools 定义全部发给 LLM. 如果绝大部分用户根本就不会用 github 的能力, 那你就平白无故浪费了大量 context.

这就是 Skills 解决的问题: 渐进式披露, 或者叫按需加载.

我个人猜测 Skills 应该也是工程设计, 也不是 LLM 的能力, 因为我们完全可以自己实现一套机制, 用下面的系统提示词:

你是一个全能专家. 你拥有以下技能:

1. 做饭: 川菜, 粤菜, 日料, 英国美食.
2. 旅游: 规划旅游路线, 选择最佳景点, 解说历史遗迹.
3. 写代码: Typescript, Rust, Go, Python.
...
99. 视频制作: 制作爆款视频, 通过制造各种对立吸引流量.
100. Slides 制作: 制作精美的, 吸引领导眼光的 Slides.

所有的技能都被单独放到了 .skills 目录里. 当用户的问题与某个技能相关时, 你需要使用 Read tool 来读取对应技能的全部文档.

看到了吗? 系统提示词里只放了最基本的技能名字和简介(也就是 SKILL.md 开头的 name + description), 没有放具体技能的内容 (比如具体怎么做菜, 具体怎么写代码, 具体制造哪种对立更符合当下的热点), 大幅节约了 context.

如果此时用户问"帮我用 Rust 写个基本的 HTTP Server", 那么 LLM 第一条返回的消息应该就包含一个 read 的 tool_use, 读取 .skills/coding 里所有的内容, 里面就会包含具体的细节, 比如 "不要用 unwrap", "优先使用 axum 框架" 等. 用户把这些内容通过 tool_use_result 发给 LLM 后, LLM 再去写最终的代码给用户.

所以 Skills 也并不是什么神奇的事情, 并不是说 Skills 赋予了 AI 大量额外的能力, 只是单纯地通过按需加载, 节约了 context, 从而可以放大量的 Skills 在目录里. 毕竟在 Skills 出现之前, 你完全也可以把具体的写代码能力写到系统提示词里, LLM 照样会拥有完整的写代码的能力.

总结

本文从 0 开始一步步讲述了 LLM API 的设计, 多轮对话, 原生 Tool Use 的方式, MCP 的原理, Skills 的思想. 让我们回顾一下几个核心要点:

Tool Use - LLM 的核心能力

Tool Use 是 LLM 模型本身的能力, 需要模型在训练时就支持. 它让 LLM 能够:

  • 理解工具的定义和参数
  • 根据用户意图决策应该调用哪个工具
  • 结构化的格式输出工具调用信息

如果一个 LLM 不支持 Tool Use, 我们几乎无法通过工程手段来弥补, 因为用 prompt 的方式既不可靠, 又难以解析.

MCP - 工程层面的协议

MCP 是纯粹的工程设计, 和 AI 完全无关. 它解决的是工程问题:

  • 跨语言: 用任何语言都可以实现 MCP Server, 不局限于某个生态
  • 解耦: tools 的定义和实现从应用代码中分离出去
  • 复用: 同一个 MCP Server 可以被多个应用、多个 LLM 使用
  • 标准化: 统一了工具的通信协议, 避免了各自为政

MCP 的价值在于降低了集成成本, 让开发者可以专注于业务逻辑, 而不是重复造轮子.

Skills - 优化 Context 的策略

Skills 同样是工程层面的优化, 核心思想是:

  • 按需加载: 不把所有能力都塞进系统提示词
  • 渐进式披露: 需要什么能力才加载什么内容
  • 节约 Context: 让有限的 context window 发挥更大价值

Skills 不是新技术, 而是一种最佳实践模式, 在 Skills 概念出现之前我们就可以自己实现类似机制.

三者的关系

Tool Use, MCP, Skills 并不是互相取代的关系, 而是相辅相成:

┌─────────────────────────────────────────┐
│          AI Application                 │
│  ┌────────────────────────────────┐     │
│  │  Skills (按需加载能力)          │     │
│  │  - 系统提示词优化                │     │
│  │  - Context 管理                 │     │
│  └────────────────────────────────┘     │
│                                         │
│  ┌────────────────────────────────┐     │
│  │  MCP Client (工具集成层)        │     │
│  │  - 从 MCP Server 获取工具定义    │     │
│  │  - 调用 MCP Server 执行工具     │     │
│  └────────────────────────────────┘     │
│                    ↓                    │
│  ┌────────────────────────────────┐     │
│  │  LLM with Tool Use (AI 能力层) │     │
│  │  - 理解工具                      │     │
│  │  - 决策调用                      │     │
│  └────────────────────────────────┘     │
└─────────────────────────────────────────┘
                    ↕
        ┌──────────────────────┐
        │   MCP Server (外部)   │
        │   - github tools      │
        │   - filesystem tools  │
        │   - database tools    │
        └──────────────────────┘
  • Tool Use 是基础, 没有它其他都无从谈起
  • MCP 让工具的集成变得简单和标准化
  • Skills 让能力的组织变得高效

实践建议

在实际开发 AI 应用时:

  1. 选择支持 Tool Use 的 LLM: 这是硬性要求, 没有商量余地
  2. 优先使用现有的 MCP Server: 不要重复造轮子, github/filesystem 等常用工具都有官方 MCP Server
  3. 合理组织 Skills: 如果你的系统提示词超过几千 tokens, 考虑用 Skills 模式进行按需加载
  4. 理解工程本质: MCP 和 Skills 都是工程问题, 理解其原理后完全可以根据需求自己实现或调整

最后

希望本文帮助你厘清了 Tool Use, MCP, Skills 三者的关系. 记住核心观点: Tool Use 是 AI 能力, MCP 和 Skills 是工程设计. 它们各司其职, 共同构建了现代 AI Agent 的能力体系.

当你在开发 AI 应用时遇到问题, 先问自己: 这是 LLM 能力的问题, 还是工程设计的问题? 如果是 LLM 能力的问题, 我们就没法自己解决了, 只能换 LLM; 如果是工程设计的问题, 在这个极高速发展的行业, 如果还没有解决方案, 那我们是完全有能力去解决的.

目前属于 LLM 能力(需要训练支持)的概念:

  • Tool Use
  • Thinking
  • Structured Output
  • Multimodal

属于工程设计, 但是很难去 polyfill, 需要服务提供方支持的概念:

  • Streaming
  • Cache
  • Batch API

属于工程设计, 并且比较容易 polyfill 的概念:

  • MCP
  • Skills
  • SubAgent
❌