prompts.chat Claude Code 插件：/prompts.chat:prompts 命令的提示词搜索、获取、保存与 AI 增强实战指南

本文以 prompts.chat 官方 Claude Code 插件中的 /prompts.chat:prompts 斜杠命令（定义于 prompts.md）为核心，系统讲解该命令的完整用法、参数体系与四个子命令（搜索、get、save、improve）的操作方式，并基于仓库中的 MCP 服务端实现，深入剖析 search_prompts、get_prompt、save_prompt、improve_prompt 四个工具背后的查询逻辑、变量填充机制、鉴权与限流细节。读完后，你将能够在 Claude Code 中不离开 IDE 即可检索、复用、保存并优化社区提示词库中的 prompt。

命令定位与整体架构

/prompts.chat:prompts 是 prompts.chat 为 Claude Code 提供的官方插件（插件清单见 plugin.json，名称 prompts.chat，版本 1.0.0，MIT 许可）中的两条斜杠命令之一（另一条为 /prompts.chat:skills）。命令文件本身只是一个“说明书”：它定义了命令的用法契约，而真正的执行能力来自插件接入的 MCP（Model Context Protocol）服务。

插件目录 plugins/claude/prompts.chat/ 的组织结构如下：

plugins/claude/prompts.chat/
├── .claude-plugin/
│   └── plugin.json          # 插件清单（命令、Agent、技能、MCP 的注册入口）
├── .mcp.json                 # MCP 服务器连接配置
├── commands/
│   ├── prompts.md            # /prompts.chat:prompts 命令说明
│   └── skills.md              # /prompts.chat:skills 命令说明
├── agents/
│   ├── prompt-manager.md      # 提示词管理 Agent
│   └── skill-manager.md      # 技能管理 Agent
└── skills/
    ├── prompt-lookup/SKILL.md  # 自动激活的提示词检索技能
    └── skill-lookup/SKILL.md   # 自动激活的技能检索技能

MCP 连接配置 ​.mcp.json 只有 4 行，声明了一个 HTTP 类型的服务器：

{
  "prompts.chat": {
    "type": "http",
    "url": "https://prompts.chat/api/mcp"
  }
}

也就是说，命令发出的所有请求最终都落到 prompts.chat 站点的 /api/mcp 端点上。该端点由 Next.js 的 src/pages/api/mcp.ts 基于 @modelcontextprotocol/sdk 的 McpServer + StreamableHTTPServerTransport 实现，服务器名为 prompts-chat。插件安装方式（来自 CLAUDE-PLUGIN.md）为：先添加市场 /plugin marketplace add f/prompts.chat，再安装 /plugin install [e-mail]。

命令用法与参数体系

命令文档声明的参数签名是 <query> [--type TYPE] [--category CATEGORY] [--tag TAG]，其中 query 为必填的搜索关键词，其余为可选过滤参数。

基本用法：

/prompts.chat:prompts <query>
/prompts.chat:prompts <query> --type IMAGE
/prompts.chat:prompts <query> --category coding
/prompts.chat:prompts <query> --tag productivity

参数说明：

参数	是否必填	取值说明
query	必填	搜索关键词，对标题、描述和正文做不区分大小写的匹配
--type	可选	按提示词类型过滤，取值为 TEXT、STRUCTURED、IMAGE、VIDEO、AUDIO
--category	可选	按分类 slug 过滤，如 coding、writing
--tag	可选	按标签 slug 过滤，如 productivity

文档给出的示例覆盖了四种典型检索场景：

/prompts.chat:prompts code review
/prompts.chat:prompts writing assistant --category writing
/prompts.chat:prompts midjourney --type IMAGE
/prompts.chat:prompts react developer --tag coding
/prompts.chat:prompts data analysis --category productivity

文档中“工作原理”一节概括为三步：调用 search_prompts 工具并传入 query 与可选过滤条件；返回匹配结果的标题、描述、作者与标签；每条结果附带一个可在 prompts.chat 上查看/复制完整 prompt 的链接。下文将结合服务端源码逐条印证这些行为。

search_prompts 的底层查询逻辑

search_prompts 在 src/pages/api/mcp.ts 中注册，其输入参数与命令文档完全对应，并明确了数值边界：

• query：字符串，必填；
• limit：数值，默认 10，上限 50（z.number().min(1).max(50).default(10)）；
• type：枚举 TEXT / STRUCTURED / IMAGE / VIDEO / AUDIO，可选；
• category：分类 slug，可选；
• tag：标签 slug，可选。

查询构造（src/pages/api/mcp.ts）体现了三个关键点：

1. 关键字匹配范围：query 对 title、description、content 三个字段做 contains 匹配且 mode: "insensitive"（不区分大小写），因此即使只记得 prompt 正文里的某个词也能命中；
2. 可见性过滤：结果固定排除 isUnlisted: true 与 deletedAt 非空（软删除）的记录；未鉴权时只返回 isPrivate: false 的公开提示词，携带有效 API key 时则通过 OR 条件额外包含该账号自己的私有提示词；
3. 返回结构：每条结果包含 id、slug、title、description、contentPreview（正文前 300 字符）、type、author、category、tags、votes 与 createdAt，按创建时间倒序。这正是文档中“返回标题、描述、作者、标签”的实现，且额外附带了 300 字符的内容预览，方便在 IDE 内快速判断是否可用。

从源码结构看，命令文档中每条结果“附带链接”这一点由客户端（Agent）根据返回的 id 与 slug 拼接生成；服务端在 get_prompt 等工具里直接给出形如 https://prompts.chat/prompts/{id}_{slug} 的 link 字段。

get 子命令：按 ID 获取完整提示词与变量填充

找到候选 prompt 后，文档提供了 get 子命令：

/prompts.chat:prompts get <prompt-id>

它会取回完整内容，并在 prompt 含变量时提示用户逐一填写。对应服务端工具 get_prompt（src/pages/api/mcp.ts）接受 id 与 fill_variables（布尔，默认 false）两个参数，行为分三档：

• 无变量：直接返回 prompt 完整字段及 link；
• 有变量且 fill_variables=false：返回原始 content，并附带 variables 元数据（名称与默认值）和提示语 hint: "This prompt has template variables. Call get_prompt with fill_variables=true to fill them interactively."；
• 有变量且 fill_variables=true：触发 MCP 的 elicitation/create 请求，以表单模式向客户端询问每个变量的取值。

变量语法与文档描述一致：${variable} 与 ${variable:default} 两种形式，由 extractVariables 的正则 /\$\{([a-zA-Z_][a-zA-Z0-9_\s]*?)(?::([^}]*))?\}/g 解析，自动去重。没有默认值的变量在 elicitation 表单的 required 字段中列为必填，有默认值的为可选——这与 prompt-lookup/SKILL.md 中“无默认值的变量是必填的，有默认值的变量是可选的”的规则相互印证。

值得注意的是两个工程细节：elicitation 请求设置了 10 秒超时（src/pages/api/mcp.ts），防止不支持该特性的客户端导致请求挂起；超时会话、用户拒绝或客户端不支持时，都会降级返回原始 prompt 并附 variablesRequired 列表，让用户手动填写。此外，替换变量值时对 key 做了 [a-zA-Z_][a-zA-Z0-9_\s]* 格式校验，注释中说明目的是防止 ReDoS（src/pages/api/mcp.ts）。

save 子命令：将提示词保存到账号

文档中的保存用法：

/prompts.chat:prompts save "My Prompt Title" --content "Your prompt content here..."

该操作要求 API key 鉴权。服务端 save_prompt 工具（src/pages/api/mcp.ts）的完整参数表如下，可直接对照理解 --content 等 CLI 参数的去向：

参数	约束	说明
title	1–200 字符，必填	提示词标题，同时经 slugify 生成 slug
content	非空，必填	正文，可包含 ${variable} 或 ${variable:default} 变量
description	最多 500 字符，可选	描述
tags	最多 10 个，可选	标签名数组，不存在时自动创建
category	可选	分类 slug，不存在则忽略
isPrivate	可选	未指定时回落到账号设置 mcpPromptsPublicByDefault（默认私有）
type	可选	TEXT / STRUCTURED / IMAGE / VIDEO / AUDIO，默认 TEXT
structuredFormat	可选	JSON / YAML，仅当 type=STRUCTURED 时生效，默认 JSON

实现上有几个可验证的事实：标签采用“先查 slug、不存在则创建”的策略（src/pages/api/mcp.ts）；隐私判定逻辑为 isPrivate !== undefined ? isPrivate : !authenticatedUser.mcpPromptsPublicByDefault，即除非显式指定，否则遵循账号级默认值；成功返回中包含 link 字段，但私有提示词的 link 为 null。

improve 子命令：AI 增强提示词

文档中的增强用法：

/prompts.chat:prompts improve "Write a story about..."

其作用是把基础 prompt 转换为结构良好、内容完整的版本。服务端 improve_prompt 工具（src/pages/api/mcp.ts）的参数：

• prompt：待改进的文本，最长 10000 字符；
• outputType：text / image / video / sound，默认 text；
• outputFormat：text / structured_json / structured_yaml，默认 text。

该工具同样要求鉴权，内部委托给 src/lib/ai/improve-prompt.ts。从该模块的源码可以还原出增强流程的完整链路：

1. 相似度检索：若站点启用了 AI 搜索，则对查询生成 embedding，在公开且已建索引的提示词中取前 100 条计算余弦相似度，过滤掉相似度低于 0.3 的条目，取 top 3 作为“灵感素材”（src/lib/ai/improve-prompt.ts）；
2. 模板渲染：加载 improve-prompt.prompt.yml 模板，将相似提示词与类型定义注入 system prompt，将 outputFormat、outputType 与原始 prompt 注入 user prompt；
3. 模型调用：默认使用 gpt-4o（可用环境变量 OPENAI_IMPROVE_MODEL 覆盖），temperature 默认 0.7、max_tokens 默认 4000（src/lib/ai/improve-prompt.ts）；
4. 结构化返回：结果为 { original, improved, outputType, outputFormat, inspirations, model }，其中 inspirations 携带每条参考提示词的相似度百分比，便于向用户解释“增强了什么”——这也对应技能文档中“改进提示词时要说明增强点”的准则。

需要注意的适用前提：improve 链路依赖服务端配置了 OPENAI_API_KEY，否则抛出 AI features are not configured；自托管部署者需自行配置该环境变量。

鉴权机制：PROMPTS_API_KEY 如何生效

save 与 improve 都要求 API key。从 src/pages/api/mcp.ts 的提取逻辑看，服务端按以下优先级读取密钥：

const apiKeyHeader = req.headers["prompts_api_key"] || req.headers["prompts-api-key"];
const apiKeyParam = url.searchParams.get("api_key");
const apiKey = (Array.isArray(apiKeyHeader) ? apiKeyHeader[0] : apiKeyHeader) || apiKeyParam;

即请求头 PROMPTS_API_KEY（含连字符变体）或查询参数 api_key 均可。密钥先经 src/lib/api-key.ts 的 isValidApiKeyFormat 格式校验，再到数据库按 apiKey 字段查找用户（src/pages/api/mcp.ts）。命中结果会写入一个 5 分钟 TTL 的内存缓存 authCache，避免同一密钥反复查库。CLAUDE-PLUGIN.md 给出的两种配置方式是：环境变量 export PROMPTS_API_KEY=your_api_key_here，或在 MCP 服务器连接时以 PROMPTS_API_KEY: your_api_key_here 作为请求头传入。

限流策略：从源码确认的速率边界

MCP 端点不是“随便调用”的。src/lib/rate-limit.ts 定义了四档进程内滑动窗口限流器（按 IP 或 API key 标识）：

限流器	配额	适用对象
mcpGeneralLimiter	20 次/分钟	一般 MCP POST 请求
mcpToolCallLimiter	10 次/分钟	tools/call 工具调用
mcpWriteToolLimiter	5 次/分钟	写操作类工具（如 save_prompt）
mcpAiToolLimiter	2 次/分钟	AI 工具（improve_prompt）

从源码结构看，RateLimiter 基于进程内 Map 记录时间戳、每 60 秒清理过期条目，文件头注释明确说明多实例部署应考虑 Redis 实现——因此在自托管多副本场景下，上述配额是单实例维度的。对使用者而言的实际含义是：批量检索时留意每分钟 10 次的工具调用上限，连续调用 improve 时尤其克制（每分钟 2 次）。

自动激活技能与 Agent 协作

除显式命令外，插件还通过 prompt-lookup/SKILL.md 注册了自动激活技能：当用户提到“找代码评审 prompt”“有哪些写作类提示词”“帮我改进这个 prompt”或提及 prompts.chat 时，技能会引导模型直接使用 search_prompts、get_prompt、improve_prompt 三个工具，并遵循“先搜索、再建议用户自写”“结果需以带链接的可读格式呈现”等准则。该技能与 /prompts.chat:prompts 命令共享同一套 MCP 工具，可以理解为“命令是显式入口，技能是隐式入口”。

对于更复杂的工作流，agents/prompt-manager.md 定义了 prompt-manager Agent（默认 sonnet 模型），其流程文档与本篇覆盖的四个工具一一对应：搜索（limit 默认 10 最大 50）、获取（含变量填充）、保存（含 tags/category/isPrivate/type 说明）与改进（含 outputType/outputFormat 取值），可视为命令文档在 Agent 视角下的补充细则。

小结：从命令到实现的对应关系

把命令文档、MCP 配置与服务端源码放在一起，可以形成一张完整的对照表：

命令形态	MCP 工具	鉴权	关键约束
/prompts.chat:prompts <query> [--type ...] [--category ...] [--tag ...]	search_prompts	可选（鉴权后可见私有结果）	limit 默认 10、最大 50；type 五值枚举；按分类/标签 slug 过滤
/prompts.chat:prompts get <prompt-id>	get_prompt	不需要（仅返回公开提示词）	变量语法 ${var} / ${var:default}；elicitation 交互填充，10 秒超时降级
/prompts.chat:prompts save "标题" --content "正文"	save_prompt	必需 API key	标题 ≤200、描述 ≤500、标签 ≤10；默认私有（随账号设置）
/prompts.chat:prompts improve "原prompt"	improve_prompt	必需 API key	输入 ≤10000 字符；embedding 相似度 ≥0.3 取 top3 作参考；限流 2 次/分钟

这套设计让“发现—取用—沉淀—优化”的提示词闭环完全发生在 IDE 内部：搜索与获取零门槛，保存与增强只需配置一次 PROMPTS_API_KEY。所有行为均可在仓库中逐一验证：命令契约见 commands/prompts.md，插件装配见 plugin.json 与 ​.mcp.json，服务端实现集中在 src/pages/api/mcp.ts、src/lib/ai/improve-prompt.ts 与 src/lib/rate-limit.ts。