prompts.chat Claude Code 插件深度解析：prompt-manager Agent 如何用 MCP 工具管理 AI Prompt 库

本文以 prompts.chat 官方 Claude Code 插件中的 prompt-manager Agent 定义文件为核心，完整拆解其“搜索 → 获取 → 保存 → 优化”四步 Prompt 管理工作流、四个 MCP 工具的参数契约，并结合 MCP 服务端源码 深入讲解变量填充（elicitation）、API Key 鉴权、隐私过滤与速率限制等底层机制。读完后你可以掌握该 Agent 的完整工作方式，理解每个工具参数背后的实现细节，并知道如何在 Claude Code 中安装、配置并使用这套 Prompt 库管理能力。

一、prompt-manager：插件中的 Prompt 管理专员

Agent 定义文件 位于 prompts.chat 仓库的 Claude 插件目录下，其 YAML frontmatter 声明了 Agent 的基本元信息：

---
name: prompt-manager
description: Agent for managing AI prompts on prompts.chat - search, save, improve, and organize your prompt library.
model: sonnet
---

从源码结构看，这个插件（plugins/claude/prompts.chat/）整体由四类能力组成，prompt-manager 属于其中的 Agents 层：

• MCP Server：连接 prompts.chat 的 MCP 端点，提供实时 Prompt 访问；
• Commands：/prompts.chat:prompts 与 /prompts.chat:skills 两个斜杠命令（见 commands/prompts.md）；
• Agents：prompt-manager（本文主角）与 skill-manager 两个 Agent；
• Skills：自动激活的 prompt-lookup 与 skill-lookup 技能，注册信息见 skills/index.json。

prompt-manager 的角色定位在定义文件中写得很明确：“You are a prompt management specialist that helps users discover, create, and improve AI prompts using the prompts.chat MCP server.” 即它是专门帮助用户发现、创建、改进 AI 提示词的管理专员，其全部能力都通过 prompts.chat 的 MCP 工具暴露。

二、四个核心 MCP 工具及其参数契约

定义文件的 “Available Tools” 一节列出了该 Agent 依赖的四个 MCP 工具。结合 MCP 服务端实现，每个工具的完整参数契约如下（参数定义来自服务端使用 zod 构建的 inputSchema，比 Agent 文档更精确，可视为实现事实）。

1. search_prompts：按关键词/类别/标签搜索

参数	类型	必填	默认值	说明
query	string	是	-	搜索关键词
limit	number	否	10	返回数量上限，范围 1–50
type	enum	否	-	过滤类型：TEXT、STRUCTURED、IMAGE、VIDEO、AUDIO
category	string	否	-	按类别 slug 过滤
tag	string	否	-	按标签 slug 过滤

工作流要求：调用后以“标题、描述、作者、标签”的形式向用户呈现结果。服务端实现上，搜索是在 title、description、content 三个字段上做不区分大小写的模糊匹配（contains + mode: "insensitive"），并强制过滤掉 isUnlisted: true 和已软删除（deletedAt 非空）的记录；已认证用户额外可见自己名下的私有 Prompt（见 search 工具注册与查询逻辑）。每条结果包含 contentPreview（内容前 300 字符）、votes 票数、createdAt 等字段，便于 Agent 挑选候选。

2. get_prompt：按 ID 获取并填充变量

Agent 文档声明该工具“supports variable filling”，服务端实际参数为：

参数	类型	必填	默认值	说明
id	string	是	-	Prompt 的 ID
fill_variables	boolean	否	false	为 true 且 Prompt 含模板变量时，触发交互式变量填充

变量语法支持两种形式：${variable} 与 ${variable:default}（带默认值）。服务端用正则 /\$\{([a-zA-Z_][a-zA-Z0-9_\s]*?)(?::([^}]*))?\}/g 从内容中提取变量名与默认值（见 extractVariables 实现）。两种调用模式的差异：

• 默认模式（fill_variables 为 false）：返回原始内容，附带 variables 元数据和提示 “Call get_prompt with fill_variables=true to fill them interactively.”，由 Agent 转述给用户填写。
• 交互模式（fill_variables 为 true）：服务端通过 MCP 协议的 elicitation/create 请求向客户端发起表单式变量收集——没有默认值的变量进入 required 列表，有默认值的为可选；并设置了 10 秒超时防止客户端不支持 elicitation 时挂起（见 elicitation 处理流程）。用户拒绝填写或客户端不支持时，会返回 variablesRequired 列表加原始内容，由 Agent 引导用户手动填写。

3. save_prompt：保存新 Prompt（需 API Key）

参数	类型	约束	说明
title	string	1–200 字符，必填	Prompt 标题，服务端会用其生成 slug
content	string	非空，必填	Prompt 内容，可含 ${variable} / ${variable:default}
description	string	最长 500，可选	描述
tags	string[]	最多 10 个，可选	标签名数组，不存在的标签会被自动创建
category	string	可选	类别 slug
isPrivate	boolean	可选	是否私有，默认采用账户级设置
type	enum	可选	TEXT / STRUCTURED / IMAGE / VIDEO / AUDIO，默认 TEXT
structuredFormat	enum	可选	JSON / YAML，仅 type 为 STRUCTURED 时生效，默认 JSON

关于 isPrivate 的“默认采用账户设置”：服务端逻辑为 isPrivate !== undefined ? isPrivate : !authenticatedUser.mcpPromptsPublicByDefault（见 save_prompt 实现）——即如果用户在账户设置中打开了 “MCP 保存的 Prompt 默认公开”，则不传 isPrivate 时保存为公开，否则默认私有。保存成功后，公开 Prompt 会返回页面链接，私有 Prompt 的 link 字段为 null。

4. improve_prompt：AI 增强 Prompt

参数	类型	取值	默认值
prompt	string	最长 10000 字符	-
outputType	enum	text、image、video、sound	text
outputFormat	enum	text、structured_json、structured_yaml	text

该工具将基础 Prompt 转换为结构更完整、表达更清晰的版本。服务端实现是直接调用项目内的 improvePrompt 函数（见 improve_prompt 工具实现），提示词模板为 improve-prompt.prompt.yml 与 query-translator.prompt.yml。注意：Agent 文档要求“Return the enhanced prompt with better structure and clarity”，即优化后要把增强版本连同改进说明一起返回给用户。

三、鉴权、速率限制与可见性：工具背后的实现约束

Agent 定义文件只说“save_prompt requires API key”，而仓库源码揭示了更完整的约束体系，理解它们才能正确使用该 Agent。

API Key 鉴权。服务端在 authenticateApiKey 中校验 Key 格式后查询用户表，并将结果缓存在内存中（5 分钟 TTL），避免每次工具调用都打数据库。配置方式有两种（见 CLAUDE-PLUGIN.md 的 Authentication 一节）：

# 方式一：环境变量
export PROMPTS_API_KEY=your_api_key_here

# 方式二：MCP 连接时添加请求头
PROMPTS_API_KEY: your_api_key_here

Key 需要在 prompts.chat 的设置页面（Settings）中生成。search_prompts 与 get_prompt 无需 Key 即可访问公开内容；save_prompt 与 improve_prompt 必须认证，否则返回 “Authentication required. Please provide an API key.” 错误。

分级速率限制。MCP 路由的限流逻辑 把工具分为两组采用不同配额：写操作工具集 WRITE_TOOLS（save_prompt、save_skill 等）使用 mcpWriteToolLimiter，AI 工具 AI_TOOLS（即 improve_prompt）使用 mcpAiToolLimiter，其余只读工具使用 mcpToolCallLimiter（限流器定义见 rate-limit.ts）。这意味着 improve_prompt 作为 AI 增强调用，拥有与只读搜索独立且通常更严格的频率约束。

可见性过滤。无论是否认证，查询结果都会过滤 unlisted 与已删除的 Prompt；认证用户的额外可见范围仅为“自己创建的私有 Prompt”，其他用户的私有内容不会泄露（见 buildPromptFilter）。这解释了为什么 Agent 在呈现结果时能安全地混排公开结果与用户自己的私有 Prompt。

四、四条工作流串起来的完整使用场景

把定义文件的 Process 一节与工具参数结合起来，prompt-manager 的典型工作流如下：

1. 搜索发现：用户提出需求（如“帮我找个代码审查 Prompt”）→ Agent 调用 search_prompts（query: "code review"，可按需加 --category coding 等过滤）→ 以标题/描述/作者/标签列表呈现候选。
2. 获取与变量填充：用户对某条结果满意 → Agent 用其 ID 调用 get_prompt → 若返回内容含 variables 元数据，Agent 引导用户提供值（或传 fill_variables: true 走交互式表单）→ 得到填好变量的完整 Prompt 及页面链接。
3. 保存入库：用户想沉淀自己的 Prompt → Agent 调用 save_prompt，并按 Guidelines 的建议“建议有意义的标签和类别”（服务端会自动创建不存在的标签，省去预建步骤）。
4. AI 优化：用户拿着一段粗糙的 Prompt 想改进 → Agent 调用 improve_prompt，按目标产物类型（text/image/video/sound）与格式（text/structured_json/structured_yaml）生成结构化增强版本。

定义文件末尾的四条 Guidelines 是该 Agent 的行为红线，值得单独强调：保存时主动建议有意义的 tags 和 category；可复用的 Prompt 必须用 ${variable} / ${variable:default} 参数化；结构化 Prompt 使用 JSON 或 YAML 格式；始终提供所保存/找到的 Prompt 在 prompts.chat 上的链接，方便用户回站内查看完整页面。

五、与其他插件组件的协作关系

prompt-manager 并非孤立存在，同一套 MCP 工具在插件内被多层复用：

• commands/prompts.md 定义的 /prompts.chat:prompts 斜杠命令，暴露了 search_prompts、get_prompt、save_prompt、improve_prompt 的命令行等价物，例如 /prompts.chat:prompts midjourney --type IMAGE；Agent 面向多轮复杂对话，命令面向一次性快捷操作。
• prompt-lookup 技能 定义了自动激活条件（用户索要 Prompt 模板、搜索 Prompt、提到 prompts.chat 等），其工具子集与 prompt-manager 一致，但额外强调一条行为准则：“Always search before suggesting the user write their own prompt”——先搜索再让用户自己写，这与 Agent 的“发现优先”定位一致。
• skill-manager 则负责多文件 Agent Skill 的搜索、获取、创建与管理，二者共享同一个 MCP Server，但工具集不同。

六、安装与配置

在 Claude Code 中启用 prompt-manager 需要两步（命令来自 CLAUDE-PLUGIN.md）：

/plugin marketplace add f/prompts.chat
/plugin install [e-mail]

之后配置 API Key（仅保存 Prompt 时需要）：

export PROMPTS_API_KEY=your_api_key_here

配置完成后，直接以自然语言触发即可，例如：“帮我找一个写作类 Prompt”会命中 prompt-lookup 技能 / prompt-manager Agent，进而调用 search_prompts；“把这个 Prompt 保存到我的账号”则触发 save_prompt。若自建（self-host）了 prompts.chat 实例，则 MCP 端点地址应指向自建实例，API Key 从自建实例的设置页获取。

七、小结

prompt-manager 用一份约 70 行的 Markdown 定义文件，就把 prompts.chat 的 Prompt 库能力封装成了一个可在 IDE 内直接对话调用的 Agent：四个 MCP 工具覆盖了 Prompt 生命周期的“找、取、存、优”四个环节，参数契约与服务端 zod schema 严格对齐。而真正支撑它可靠工作的，是 MCP 服务端 中的变量提取与 elicitation 填充、API Key 内存鉴权缓存、写操作与 AI 操作的分级限流，以及“公开 + 本人私有”的可见性过滤——这些源码级细节决定了 Agent 在真实使用中的行为边界与错误形态，也是评估和复用这套插件设计时最值得参考的部分。