Clarifyprompt Mcp

ClarifyPrompt MCP

一款上下文感知的 MCP 提示词编译器，可将含糊的提示词转换为针对 7 个类别中 60 多个 AI 平台优化的提示词，并以工作区信号（CLAUDE.md、AGENTS.md、.cursorrules、package.json）、已解析的意图以及目标模型的能力为依据。

发送原始提示词。ClarifyPrompt 会收集恰当的上下文，解析你的实际需求，并返回专为 Midjourney、GPT Image 2、Veo、Runway、Kling、Seedance、Higgsfield、ElevenLabs、Suno、Claude、ChatGPT、Cursor 或 61 个受支持平台中的任意一个优化的版本——包含恰当的语法、参数、结构和背景依据。

1.16.0 新增： 平台信息时效性版本。 所有内置包均已根据最新供应商文档（2026-10-05）核实事实——Midjourney V8.x、Runway Gen-4.5、Veo 3.1、Kling 3.0/Omni、Pika 2.2、Suno v6、ElevenLabs v3、gpt-4o-mini-tts、GPT Image 2——每个条目现在都包含 verifiedAt 日期。Sora 已全面退役（OpenAI 于 2026-09-24 关闭了 Videos API，且没有替代方案）；新增平台：Seedance、ElevenLabs Music v2.5、Lyria 3.5。此外还推出了方言时效性基准测试：让 Ollama Cloud 中最新的 12 个模型在没有提示的情况下编写平台提示词——12/13 会输出过时的 Midjourney 标志，12/12 会为已停用的 Sora 编写流畅的提示词，没有一个模型会表达不确定。注入知识包事实后，基于事实的模式会用相同的请求重新运行，得分随之反转。参见基准测试和CHANGELOG.md。

1.15.0 新增： Nano Banana（Google Gemini 2.5 Flash Image）现已成为内置图像平台——optimize_prompt(platform: "nano-banana") 会以其原生风格编译图像提示词（自然语言场景描述、摄影术语、保留身份特征的编辑措辞、图像内文字）。此外，所有供应商均已兼容最新模型：claude-sonnet-5、gpt-5/o 系列和 Gemini 会拒绝 temperature 和／或 max_tokens；客户端现在会发送正确的参数（对已知推理模型 ID 提前处理，并从 400 响应中学习其余情况）。已通过 Anthropic、OpenAI、Gemini 和 Ollama Cloud 的实时验证。参见CHANGELOG.md。

1.14.1 新增： 默认输出可移植的文本。 如果 chat/document/code 提示词没有指定平台，现在会保持平台中立，而不是悄悄默认采用 Claude 的表达习惯（XML 标签）；指定平台即可选择供应商专属调优。此外，MCP Apps 的撰写面板现在会显示 for <platform> 徽标，并以清晰的 你的提示词 → 优化结果 展示优化前后对比（可通过 show changes 切换），而非始终显示差异。参见CHANGELOG.md。

1.14.0 新增： 通过 MCP Apps 提供交互式撰写面板。 在支持 io.modelcontextprotocol/ui 扩展的宿主（Claude Desktop、ChatGPT、Cursor、VS Code，……）中，compose_prompt 会呈现实时面板，展示原始内容与优化内容的对比、全部六项评估分数、流水线阶段以及接受／修改操作——“接受”会将结果记录到 ClarifyPrompt 的记忆循环中，“修改”会将你的反馈发送回聊天中。它是一个独立的 ui:// 资源；不支持该扩展的宿主不会有任何变化。参见CHANGELOG.md。

1.13.0 新增： 改用通俗语言。 优化后的提示词现在会使用常见的日常用语，而不会偏向正式词汇（使用“use”，而不是“utilize”）——具体程度来自具体细节，而非更华丽的同义词。critique_prompt 新增了第六个默认维度，plain_language，因此 auto_revise 循环会自动纠正语体偏移。此外还修复了一项问题：在紧凑型系统提示词调整下，小型本地模型不再会静默丢弃显式指定的 mode（例如 simple）。参见CHANGELOG.md。

这为何重要——有数据为证，而非空口断言

这个项目为何存在？**因为“直接问模型”已经悄然过时，而我们对此进行了测量。**模型的知识冻结在训练时；平台却每月发布新版本（并淘汰旧版本）。结果就是，向现代模型询问平台提示词，等于向一本 2024 年的百科全书询问 2026 年的价格。

2026-10-05，我们开展了一项公开基准测试：让 12 个最新的 Ollama Cloud 模型为真实且当前的平台编写提示词，分为 两种条件，问题相同，模型相同：

• RAW — 仅使用模型，不提供帮助。也就是用户在普通聊天中会得到的结果。
• GROUNDED — 提出相同问题，但先注入已验证的平台事实——也就是 ClarifyPrompt 在每次 optimize_prompt 调用时注入的同一份资料包数据。（这就是“基于事实”的含义：模型读取参考卡片，而不是依赖冻结的记忆。）

每种条件下均有 132 个评分答案，并于当天对照供应商文档进行核实。所有原始回复的完整审计记录：evals/dialect-benchmark/out/final.json。

结果，一目了然：

	RAW（仅模型）	GROUNDED（注入资料包事实）
当前语法	36	117
过时	35	0
混杂 / 通用	7 / 54	1 / 14

模型相同，问题相同。35 个过时答案 → 0 个。

实际效果如下：

• **Sora 2，12 个中有 12 个。**OpenAI 于 2026-09-24 关闭了 Videos API（消费者应用于 4 月 26 日关闭）。11 天后，每个模型——包括 OpenAI 自家的开放权重模型 GPT-OSS——都为一个已不存在的产品写出了流畅、自信的提示词。没有一个模型指出这一点。没有一个答案有所保留，也没有一个答案声明知识截止日期。
• **Midjourney，13 个中有 12 个。**所有模型都选用了 --v 6.1。自 6 月以来，当前默认版本一直是 V8.2。所有模型都一致地落后了两个主要版本。
• **注入资料包事实后，所有模型的结果都发生了变化。**模型相同：12 个模型都表示 Sora 已停用；12 个模型都指定了 --v 8.2；原始表现最差的模型从当前 3 个 / 过时 5 个，变为 8 个 / 0 个。

**两种条件的总成本：$0.71。**测试工具 + 事实文件 + 评分脚本：evals/dialect-benchmark/ — 运行 node evals/dialect-benchmark/run.mjs 即可复现。

坦诚地说：模型并不了解当前语法——但有了持续维护的知识层，它们就能完美执行。**缺口在于知识；资料包层才是产品。**而这正是 optimize_prompt 的作用：每次调用都提供事实依据，并使用我们根据实时文档更新、以 verifiedAt 标注日期的资料包。

工作原理

ClarifyPrompt 能做到普通提示词模板做不到的两件事。以下每个输出都是对本仓库运行 optimize_prompt 后真实、未经编辑的捕获结果（参见本节末尾的来源说明）。

**1 — 它了解各个平台。**相同的原始提示词，面向不同目标，输出截然不同：

You write:    "a dragon flying over a castle at sunset"

→ Midjourney  A colossal, majestic dragon with shimmering scales soaring over a towering
              medieval stone castle, dramatic sunset sky with vibrant orange and deep purple
              hues, cinematic fantasy concept art, volumetric lighting, highly detailed
              --ar 16:9 --v 6.1 --s 250 --q 2

→ DALL-E      A majestic dragon with glowing crimson scales soars over a towering medieval
              stone castle, silhouetted against a vibrant orange and purple sunset sky.
              Rendered in a high-fantasy digital art style with dramatic, warm lighting and
              highly detailed textures, wide aspect ratio.

→ Nano Banana A majestic dragon with deep crimson scales and a leathery, bat-like wingspan
              glides through the warm, golden-hour sky just above a towering medieval castle
              made of weathered grey stone. ... Frame this as a wide cinematic landscape shot
              using a 24mm lens at f/8 for deep depth of field, camera positioned at a
              slightly elevated three-quarter angle... Aspect ratio 16:9.

Midjourney 会使用 --ar/--v/--s/--q 标志；DALL-E 和 Nano Banana 则使用不带标志的自然语言，而 Nano Banana 还会加入摄影指导（镜头、f 值、相机角度）和明确的情绪氛围，这是其文档中记载的风格。同一个想法，每个平台都使用自己的原生表达方式。

请注意上面 Midjourney 捕获结果中的 --v 6.1。这份捕获是真实的（2026-06-22）——模型给出的版本标志已经落后了两个主要版本；Midjourney 当前的默认版本是 V8.2。模型权重在训练时便已冻结；平台方言每月都在变化。ClarifyPrompt 的经过验证的平台包（带有 verifiedAt 日期，并根据当前文档刷新）正是为了弥合这一差距——参见过时情况说明。

2 — 它了解你正在处理的内容。这是模板无法伪造的部分。在编辑本仓库中的 src/transport.ts 时，随手输入一句含糊的短提示词，引擎便会以你实际的工作区为依据——包括 package.json、git 状态和当前文件——并在塑造输出之前确定意图：

You write:    "add a configurable request timeout to the http transport"
              · active file: src/transport.ts   · resolved intent: production-code
              · grounded in: active-file · workspace-meta · git-state · environment ·
                target-model · platform-hints

→ Cursor      Implement a configurable request timeout for the HTTP transport in
              `src/transport.ts`.
              Requirements:
              1. Add a new environment variable `CLARIFYPROMPT_HTTP_TIMEOUT` … (default 30000 ms)
              2. Apply this timeout to all incoming requests in the streamable-http transport
              …
              5. Preserve existing behavior for stdio and a2a transports
              …
              The implementation should be added to the streamable-http section of
              `startTransport()`.
              (excerpted — the full rewrite has 7 numbered requirement groups)

那条简短提示词没有提到 CLARIFYPROMPT_HTTP_* 命名约定、startTransport() 入口点，也没有提到必须保留的 stdio/a2a 传输方式——引擎从当前文件和 package.json 中读取这些信息，并将其融入输出。这就是改写提示词与结合上下文编译提示词的区别。

**3 — 它可以运行整个流程。**一次 compose_prompt 调用即可完成澄清 → 补充背景信息/优化 → 评议 → 修订——参见下文的 1.4.0 中的历史版本 — 可组合流程。

**来源说明。**图像输出通过 glm-5.2:cloud 捕获，结合上下文的代码输出通过 qwen3-coder:480b-cloud 捕获——两者都是通过 Ollama 的 OpenAI 兼容端点（LLM_API_URL=http://localhost:11434/v1）提供服务的 Ollama 云端模型。两者都于 2026-06-22 在本仓库上运行 optimize_prompt 后获得（Nano Banana 捕获于 2026-07-03 添加，使用相同的 glm-5.2:cloud 模型）。ClarifyPrompt 与模型无关（可使用任何 OpenAI 兼容 API，无论是本地还是托管）；输出取决于模型——你的输出措辞可能不同，但结构相同。

1.16.0 版更新内容

平台方言更新版。 各平台包的内容已经过时——Midjourney 仍然使用 --v 6.1，而当前默认版本是 V8.2；视频包仍在介绍“Runway Gen-3”和“Google Veo 2”；Higgsfield 条目仍指向已停用的模型。我们已于 2026-10-05 根据各供应商的最新文档核实所有内置包中的事实，并为每个经过核实的条目添加了 verifiedAt 日期，让过时情况清晰可见、可追踪，也可纳入 CI 检查。

全面移除 Sora。 OpenAI 于 2026-04-26 停止了 Sora 应用，并于 2026-09-24 关闭了 Videos API 和所有 sora-2 模型 ID，且未公布替代方案。我们已从平台包、策略指南、A2A 卡片、工具文档、README 和 npm 关键词中移除相关内容。新增的一等平台：seedance、eleven-music（ElevenLabs Music v2.5）、lyria（Google 3.5）。

方言时效性基准测试（evals/dialect-benchmark/）——证明了本项目存在的意义。我们让 12 个最新的 Ollama Cloud 模型在没有提示的情况下编写平台提示词，再根据同一套经过核实的事实对回答进行评分：

• 13 个回答模型中，有 12 个输出了过时的 Midjourney --v 6.x（V8.2 自 6 月起一直是默认版本）
• 12 个模型全部为 Sora 2 写出了流畅的提示词——而 OpenAI 在测试进行前 11 天就已关闭该产品。其中还包括 OpenAI 自己的开放权重模型 GPT-OSS。没有任何模型表示不确定或提及知识截止时间。
• 基于事实模式（BENCH_GROUNDED=1）会在系统提示词中注入平台包事实，并用相同的问题重新运行测试——同一组模型的前后差异，让产品理念变得可衡量：模型并不了解当前的平台方言，但借助持续维护的知识层，它们就能准确执行。
• 补充发现：两个基准测试对照模型在测试过程中返回了 HTTP 410（已停用）（qwen3.5:397b，2026-09-25）——模型也会更新换代，不只是方言会变。

1.15.0 版更新内容

内置 Nano Banana。 Google 的 Gemini 2.5 Flash Image（“Nano Banana”）现已成为一等图像平台——optimize_prompt(category: "image", platform: "nano-banana") 可将你的想法编译为其原生提示词风格：使用完整句子描述场景（而非堆砌关键词）、使用摄影术语描述相机／镜头／景深、明确说明光线、采用保留主体身份的编辑措辞、确保多参考图角色一致性，并可靠地处理图像内文字。与其他图像平台一样，ClarifyPrompt 负责编译提示词；你负责将其发送给模型。

兼容所有供应商的最新模型。 启用思考功能的模型会拒绝 clarifyprompt 一直发送的参数：claude-sonnet-5 和 OpenAI 推理模型会拒绝 temperature；gpt-5 / o 系列还会拒绝 max_tokens（它们要求使用 max_completion_tokens）。过去，对这些模型的所有调用都会失败，并降级为原始提示词。现在，客户端会发送正确的请求体——对于已知的推理模型 ID，会主动采用正确参数（避免无谓的往返请求）；对于提示信息无法识别的模型（包括未来推出的模型），则会从 400 错误中学习并重试。接受标准参数的模型，其请求字节完全不变。已通过 Anthropic（claude-sonnet-5）、OpenAI（gpt-5）、Gemini（gemini-flash-latest）和 Ollama Cloud（glm-5.2:cloud）的实时验证。推理模型需要大量思考时间——请调高 LLM_TIMEOUT_MS（默认的 30 秒通常太短）。

1.14.1 版本更新

默认采用可移植格式。 优化文本提示词（chat、document、code）时，如果未指定平台，ClarifyPrompt 现在会返回与平台无关的输出——结构清晰、可移植，适用于任何助手——而不是悄悄默认使用 Claude 的惯用格式（其 <task>/<context> XML 标签）。指定平台（platform: "claude"、"chatgpt"……60 个平台中的任意一个），即可启用该平台专属的调优。创意类别（图像／视频／语音／音乐）不变：其输出需要具体的平台格式，因此仍采用旗舰平台作为默认值（Midjourney、Runway……）。

更清晰的撰写面板。 MCP Apps 面板现在会显示 for <platform>（或 general purpose）徽章，在优化后的输出上方以带标签的 你的提示词 区块呈现原始提示词，并直接显示优化后的提示词——可通过 show changes 开关查看词级差异——而不再始终显示差异。

1.14.0 版本更新

compose_prompt 现在有了可视界面。 ClarifyPrompt 内置了一个 MCP Apps 面板（扩展 io.modelcontextprotocol/ui），支持该功能的宿主会在工具结果旁内嵌呈现：

• 原始内容与优化结果的词级差异 — 准确查看编译器做了哪些修改。
• 可视化评估结果 — 将全部六个维度（clarity、specificity、intent_alignment、format_fitness、length_appropriateness、plain_language）显示为评分条，并以徽章呈现评定结果及每次调用的 stages 审计记录。
• 接受 — 点击一次即可在面板中记录 save_outcome(accepted)，为少样本记忆循环提供数据，并悄悄告知模型提示词已被接受。
• 修改…… — 输入需要更改的内容；面板会将其发送回聊天，让模型重新撰写。
• 支持澄清流程 — 当预澄清阶段因提出问题而停止处理链时，面板会显示这些问题（并提供建议答案），而不是显示差异。

零风险推出：面板是一个独立的 HTML 资源（ui://clarifyprompt/compose-panel.html，包含内联 CSS/JS——扩展沙箱会阻止外部请求），通过 compose_prompt 的 _meta.ui 链接。没有该扩展的宿主会完全忽略面板；文本和 structuredContent 输出逐字节保持不变。基于现有 SDK ^1.29 运行。新增的确定性 npm run test:apps 测试套件会验证此连接配置。

另一项新增内容：评估测试框架新增 max_reading_grade 检查——一项确定性的 Flesch–Kincaid 上限检查，将 1.13.0 版本的通俗语言表现设为可量化的门槛（正式语体的冗余文本得分约为 20+；通俗改写约为 3–6）。

1.13.0 新增内容

端到端改用通俗易懂的表达。 与含义相同的正式同义词相比，大模型对常见日常用语的处理更加可靠，而 ClarifyPrompt 默认面向的小型本地模型受益最大。本次版本将这一原则融入影响输出措辞的每个阶段：

• 优化器优先使用常见词语。 共享系统提示词中新增了一项核心原则（“USE COMMON WORDS”），适用于全部 7 种类别策略，以及 optimize_prompt 和 ground_prompt：如果常见词语能表达相同含义，就不要换成更生僻的词。细节意味着提供更多信息，而不是使用更华丽的词语——具体性、结构和约束均保持不变。
• critique_prompt 新增第 6 个默认维度：plain_language。 如果简单词语就能表达意思，该维度会对不必要的正式或生僻用词进行扣分。由于改写阶段会采纳评分低于 7 的维度所提出的所有建议，auto_revise 循环现在也能自动修正语体偏差。自定义 criteria 覆盖项不受影响。
• 已修复：小型本地模型不再默默丢弃显式指定的 mode。 之前，精简系统提示词时会完全删掉模式指令，因此 mode: "simple" 对 3B 级模型不起作用。现在，所有模式都会以单行规则的形式保留在精简提示词中。
• 新增两个评估用例，用于验证这一行为：31-plain-language-vocabulary（优化后的输出不得包含正式语体用词）和 32-shape-compact-keeps-mode（模式行会传递给小型模型）。

1.12.1 新增内容

这是 issue #3 的真正修复：思考通道模型现在可以稳定生成优化后的提示词，不再间歇性地返回空内容。gpt-oss:20b-cloud 和 glm-5.2:cloud 的空内容返回率从约 40% 降至 0%。

从头重新调查后，已推翻文档中记录的根本原因。问题从来都不是“Ollama 的 /v1 适配层会丢弃 harmony final 通道”。这些模型会先将 max_tokens 预算用在思考通道上，始终无法到达 final 通道，因此 content 会返回 ""（推理强度越高，情况越严重）。我们结合使用了两种手段，因为不同模型系列会响应不同的设置：

• 为检测到的推理模型设置 max_tokens 下限（8192）——这是通用手段。它直接针对根本原因，因此无论模型系列遵循哪种思考设置都能奏效。这是上限，而非目标值：简短回答会提前完成，因此不会增加延迟。
• reasoning_effort: "low"——适用于支持此设置的模型系列（gpt-oss），同时还能降低延迟和成本。使用 LLM_REASONING_EFFORT（low | medium | high）进行调整。

这些手段确实因模型系列而异：gpt-oss 支持 reasoning_effort，但会忽略 Ollama 的 think；glm 则恰好相反——它会忽略 reasoning_effort，因此只有提高预算下限才能解决问题。

检测机制稳健，不依赖硬编码的模型列表（新模型不断发布，硬编码列表会逐渐过时）。“这是思考模型吗？”这一问题会按模型缓存，并通过以下方式作答：(1) 运行时自身——Ollama 的 /api/show 会报告 thinking 能力（minimax-m3:cloud 就是通过此方式检测的，无需匹配名称）；(2) 从响应中学习——任何推理记录，或含令牌却返回空内容的响应，都会将该模型标记为思考模型，此后持续生效（适用于任何提供方）；(3) 作为最后手段，使用简单的名称提示。非推理模型的字节级行为保持不变，而与名称无关的空内容重试则是最后一道保障。已在 gpt-oss:20b-cloud、glm-5.2:cloud 和 minimax-m3:cloud 上验证（首次调用的空内容率均为 0%）。

此前提出的“改用 Ollama 原生 /api/chat”方案是条死胡同——即使对 /api/chat 设置 think:false，gpt-oss 仍会返回空内容（它会忽略该设置），而且还会增加一条脆弱的独立代码路径。

1.12.0 版新增内容

MCP 现代化路线图的第 7 步——也是最后一步：ClarifyPrompt 现在支持 A2A（Agent 到 Agent），其他 Agent 可以调用它来编译提示词。stdio 仍为默认值；现有配置不会有任何变化。

设置 CLARIFYPROMPT_TRANSPORT=a2a 后，ClarifyPrompt 就会通过 Node 内置的 http 成为可发现的 A2A 对等端（唯一新增的依赖是官方的 @a2a-js/sdk，它本身只会引入 uuid）：

端点	用途
GET /.well-known/agent-card.json	Agent 卡片——发现信息：身份、能力、compile-prompt-for-platform 技能
POST /a2a	A2A JSON-RPC 2.0：message/send、message/stream（SSE）、tasks/get、tasks/cancel、…
GET /health	存活探测

CLARIFYPROMPT_TRANSPORT=a2a CLARIFYPROMPT_HTTP_PORT=3000 npx clarifyprompt-mcp
# → card:  http://127.0.0.1:3000/.well-known/agent-card.json
# → a2a:   POST http://127.0.0.1:3000/a2a   (message/send · message/stream)

整个路线图的成果在此汇聚——一条传入的 A2A 消息会经过同一套编排流程，而前面步骤中构建的基础功能也可直接映射为 A2A 语义：

• 编译——携带原始提示词的 message/send（纯文本，或 JSON { prompt, platform?, category?, … }）会返回一个任务，其 artifact 包含优化后的提示词（文本）以及完整的结构化编排结果（数据）。
• 流式传输（1.10.0 进度 → A2A）——message/stream 会在各个流程阶段运行时发送 status-update 事件，随后通过 SSE 发送 artifact。
• 取消（1.10.0 AbortSignal → A2A）——tasks/cancel 会在数毫秒内中止正在进行的编排，并报告终态 canceled。
• 澄清（1.9.0 elicitation → A2A）——对于单次调用的对等端，默认关闭澄清；使用 pre_clarify: 'auto' | 'always' 可选择启用。遇到含糊的提示词时，任务会暂停在 A2A 原生支持的 input-required 状态，并附上问题（可读文本 + 结构化数据）。在同一任务中回答后，即可继续编译。

使用 CLARIFYPROMPT_A2A_BASE_URL 配置卡片中公布的公共基础 URL（在代理后很有用）；端口和主机与 streamable-http 共用。新增的确定性 npm run test:a2a 测试套件会测试卡片发现、实时编译、澄清往返和 SSE 流式传输。

1.11.0 版新增内容

MCP 现代化路线图的第 6 步：可插拔的传输工厂——ClarifyPrompt 现在可通过 Streamable HTTP 提供服务，为支持 A2A 和远程 MCP 主机铺平道路。stdio 仍为默认值；现有配置不会有任何变化。

传输方式

设置 CLARIFYPROMPT_TRANSPORT：

值	行为
stdio（默认）	通过 stdin/stdout 提供单个服务——与之前完全相同
streamable-http	通过 Node 内置的 http 使用 MCP Streamable HTTP（无新增依赖）：有状态会话（mcp-session-id）、SSE 流式传输、/health 探测
a2a	作为 **A2A（Agent 到 Agent）**对等端提供服务——Agent 卡片、JSON-RPC + SSE（见上文 1.12.0）

HTTP 配置项（适用于 streamable-http / a2a 模式）：CLARIFYPROMPT_HTTP_PORT（3000）、CLARIFYPROMPT_HTTP_HOST（127.0.0.1——默认仅限 localhost）、CLARIFYPROMPT_HTTP_PATH（/mcp，仅适用于 streamable-http）。

CLARIFYPROMPT_TRANSPORT=streamable-http CLARIFYPROMPT_HTTP_PORT=3000 npx clarifyprompt-mcp
# → POST http://127.0.0.1:3000/mcp  ·  GET http://127.0.0.1:3000/health

工具和资源注册已移至导出的 createServer() 工厂：stdio 使用一个服务，streamable-http 每个会话使用一个服务（SDK 推荐且符合 GHSA 安全要求的模式——绝不会让多个 HTTP 客户端共用同一个服务）。新增的确定性 npm run test:http 测试套件会执行完整的 HTTP 会话测试。

1.10.0 版新增内容

MCP 现代化路线图的第 5 步，稳定核心：compose_prompt 支持取消，并会报告实时进度。与模型无关、可选启用，并完全向后兼容。

取消

AbortSignal 会贯穿整个 LLM 调用链（simpleGenerate → chat → fetch，并与单次调用超时结合），以及引擎的每个阶段。当客户端针对 compose_prompt 调用发送 notifications/cancelled 时，正在进行的模型请求会立即中止，修订循环也会在下一个阶段边界停止，而不是运行完所有迭代。无论配置了哪个模型或提供商，信号都会传递到 fetch。

进度

在 compose_prompt 请求的 _meta 中加入 progressToken，服务器便会在每个阶段（clarify / optimize / ground / critique）发送 notifications/progress，其中包含单调递增的计数器和类似 optimizing prompt [iter 2/3] 的提示信息。宿主可以显示多轮 compose 期间的实时状态。没有令牌 → 不发送通知，零开销。

为什么暂不使用 MCP tasks

路线图 #5 提到了 MCP tasks API。它仍位于 SDK 的 experimental/ 中（“可能随时更改，恕不另行通知”），其参考文档约有 600 行，而且当前没有客户端支持 tasks/* 协议，因此如今完整实现只会成为默认关闭、无法使用的代码。这里通过稳定的基础功能实现了真正有价值的部分（可取消且能报告进度的 compose）；实验性的异步任务封装将推迟到 #7（A2A）一并落地，而这里的 AbortSignal 基础工作已为此做好准备。新增的确定性 npm run test:cancel 测试套件会锁定这一行为。

1.9.0 新增内容

MCP 现代化路线图的第 #4 步：clarify_with_user 可以通过宿主的原生表单 UI 引导用户回答。可选择启用，并完全向后兼容。

交互式澄清

传入 elicit: true。在支持 MCP elicitation 的客户端上，澄清问题会变成真正的表单：

• 每个问题都是一个字段，options 会变成枚举下拉菜单，每个 suggestedAnswer 都是字段默认值（单击即可接受）；
• 用户可直接填写答案；引擎会返回 answers: [{ question, dimension, answer, usedSuggested }]，并设置 elicited: true。

未传入 elicit、客户端不支持此功能，或往返调用出错时，工具会返回与以往相同的原始问题 JSON，不会影响任何现有调用方。decline / cancel 会通过 elicitationAction 返回。

这让澄清从“这里有一段问题 JSON，由你来渲染”变成了 Claude Desktop 等宿主中的一等交互体验。映射逻辑位于小型纯模块（src/engine/clarification/elicit.ts）中，之后也可供 compose_prompt 的预澄清阶段复用。新增的确定性 npm run test:elicit 测试套件（纯辅助函数 + 实时模拟客户端往返调用）会锁定这一功能。

1.8.0 新增内容

MCP 现代化路线图的第 #3 步：引擎的读取接口变为可浏览的资源模板，并支持参数自动补全。工具或引擎行为均无变化。

资源模板

除静态的 clarifyprompt://categories 外，新增四个模板，每个都由现有的引擎 getter 提供数据：

URI 模板	读取内容
clarifyprompt://platforms/{category}/{id}	一个平台的完整配置 — resources/list 会将 60 多个平台逐一列为独立 URI
clarifyprompt://traces/{date}	某个 UTC 日期的优化追踪摘要索引
clarifyprompt://packs/{id}	一个已加载知识包的元数据
clarifyprompt://memory/facts/{scope}	某个范围下实时记忆的事实

支持资源浏览器的 MCP 宿主（Claude Desktop、Cursor）现在可以看到可导航的树状结构，而不再只有单个静态内容。

自动补全

completion/complete 会解析模板变量：{category} → 7 个类别 ID，{id} → 按所选 {category} 筛选的平台 ID，{date} → 有追踪记录的日期，以及知识包 ID、记忆范围。（MCP 自动补全仅适用于提示词参数和资源模板变量，不适用于工具输入；ClarifyPrompt 未注册提示词，因此自动补全适用于模板。）

功能

服务器现在会在 initialize 时公布 resources（含模板）和 completions。新增的确定性 npm run test:resources 测试套件锁定了这部分接口。

1.7.1 版本更新

修复 #3：对于答案未落入 content 的模型，可能出现优化后的提示词为空且不报错的问题。

• 读取三种思考通道字段名（reasoning / thinking / reasoning_content）——修复 DeepSeek / qwen-thinking 及类似模型的问题。
• 重试一次，然后在内容为空时明确报错，无论是否存在任何思考字段。这涵盖了 issue #3 中的真实情况：通过 Ollama 的 /v1 兼容层输出的 gpt-oss harmony 内容会生成 token（completion_tokens > 0），但返回 content: ""，且没有思考字段。现在引擎会退回原始提示词，并返回明确显示的 error，而不是返回空内容。
• 真正恢复 gpt-oss harmony 输出（通过 Ollama 原生 /api/chat）曾作为后续事项跟踪——已在 1.12.1 中解决。该版本证实 /api/chat 路径行不通，并修复了实际根因（为推理模型设置 max_tokens 下限和 reasoning_effort；见上文 1.12.1 说明）。
• 新增确定性 npm run test:thinking 测试套件，通过模拟响应锁定此回归测试（不依赖实时云服务）。

已验证：test:thinking、推理测试套件（gpt-oss 会明确降级；真正的推理模型 kimi-k2-thinking:cloud 仍会返回实际内容）、集成测试、day2、evals、wire。

1.7.0 版本更新

MCP 现代化路线图的第 2 步：整个工具接口已从已弃用的 server.tool() 简写（在 SDK 2.0 中移除）迁移到 server.registerTool()。引擎行为没有变化；完全向后兼容。

主机可获得的内容

• 标题——每个工具都有易于理解的显示名称（“忘记一条事实”，而不是 memory_forget）。
• 行为注解——全部 23 个工具都声明了 readOnlyHint / destructiveHint / idempotentHint / openWorldHint。三个具有破坏性的工具（memory_forget、unload_pack、unregister_platform）已标记为需要确认的操作；七个只读检查工具已标记为可安全自由调用；七个会访问网络的工具（LLM / 嵌入 / 网页搜索）带有 openWorldHint: true。
• 结构化输出——每个工具都声明了 outputSchema，并在返回 JSON 文本的同时返回 structuredContent。有意将架构设计得宽松（所有字段均可选、允许额外字段）——用于说明数据形状，但绝不会拒绝引擎输出。

向后兼容

每个工具的文本内容逐字节保持不变——包括三个返回数组的 list_* 工具，其文本仍为裸数组，而 structuredContent 则按照 MCP 规范将其包装在对象中。错误返回保持不变。已验证：wire 7/7、集成测试 9/9、day2、evals 26/27，且没有输出验证错误。

验证期间发现的问题

#3——云端 gpt-oss 的思考通道响应可能导致 optimizedPrompt 为空（远程 API 变更暴露了 client.ts 中原有的字段名缺失问题；计划在 1.7.1 中修复）。

1.6.8 版本更新

维护性版本，解决 1.6.5→1.6.7 连续版本中遗留的问题。不涉及引擎代码、MCP 工具接口、平台或环境变量的变更。

变更

• CI 矩阵现在会测试 Node 24（当前活跃的 LTS 版本，2028 年 4 月 EOL），并同时测试 18/20/22，覆盖 Ubuntu + macOS。此前矩阵测试了两个已 EOL 的 Node 版本，却完全没有测试当前 LTS 版本。合并前已在不含工具链的 node:24-slim 容器中验证原生依赖（better-sqlite3 + sqlite-vec）可在 Node 24.16.0 上加载并正常运行。engines 仍为 >=18——最大限度保证兼容性，并测试我们承诺支持的版本。
• 发布运行器从 Node 20 改为 Node 22，避免让已 EOL 的运行时处于发布关键路径上（与 Dockerfile 基础镜像保持一致）。

流程

• 新增发布检查 CP-13 — lockfile regeneration safety，总结了 1.6.5→1.6.6→1.6.7 连锁问题的教训：一次 npm install --package-lock-only 静默删除了 5 个 sqlite-vec 平台二进制文件中的 4 个（导致 Linux CI 失败），并且引入了一个符合 caret 范围的 better-sqlite3 升级，导致 Node 20 预构建版本被移除（导致 Docker 构建失败）。该检查要求依赖变更时执行完整的 npm install，检查 lockfile diff 中被删除的平台依赖和原生依赖版本跃迁，并在本地通过 slim-Docker 加载门禁。本次发布已实际采用该检查。

1.6.7 新增内容

Dockerfile 补丁。没有引擎代码、MCP 工具接口、平台或环境变量变更。

修复

• 1.6.6 中的 CI / docker build 失败，报错为 npm error gyp ERR! find Python。根本原因：[email protected]（发布于 2026-05）明确移除了 Node.js v20 和 v23 的预构建二进制文件，因为 Node 20 已于 2026 年 4 月结束生命周期。1.6.6 的 lockfile 重新生成在 ^12.9.0 caret 范围内引入了 12.10.0，而 node:20-slim 没有 Python 和 C++ 工具链，无法从源码编译。已将 Dockerfile 基础镜像升级为 node:22-slim——当前仍受支持的 LTS 版本，且仍有可用的预构建版本。
• 非 Docker CI 构建矩阵（macOS + Ubuntu 上的 Node 18 / 20 / 22）仍然通过，因为常规运行器可在必要时从源码编译。只有 slim Docker 镜像会遇到问题。

本地验证

docker build → 通过。容器可以正常执行 require('better-sqlite3') + require('sqlite-vec')。package-lock.json 中仍包含全部 5 个 sqlite-vec 平台二进制文件（1.6.6 的修复仍然有效）。

1.6.6 新增内容

继 1.6.5 之后的 lockfile 和测试框架补丁。**没有引擎代码、MCP 工具接口、平台或环境变量变更。**随版本发布 MCP 完整性审计文档。

修复

• **package-lock.json 在 1.6.5 SDK 升级期间丢失了 5 个 sqlite-vec 平台二进制文件中的 4 个。**我本地执行的 npm install --package-lock-only 只保留了维护者的 sqlite-vec-darwin-arm64 二进制文件。CI 的 Ubuntu 运行器上执行 npm ci 时失败，报错 no such module: vec0，因为 lock 中没有 sqlite-vec-linux-x64。终端用户执行 npm install [email protected] 完全不受影响（npm 压缩包不包含 lockfile；用户的安装过程会解析对应平台）。已通过完整的 npm install 重新生成，恢复了全部 5 个平台（darwin-arm64、darwin-x64、linux-arm64、linux-x64、windows-x64）。
• 评测框架的 HTML 报告写入器在遇到 ERRORED 条目时崩溃（evals/run.mjs:729）。此前的渲染器假设每个未跳过、未筛选的运行都有 evaluation.checks 字段，但出错的运行携带的是 error 字段。现已添加显式的出错状态分支——即使测试固件出错，框架也能平稳降级并正常退出。

随附文档

• docs/audits/mcp-completeness-2026-05.md — 对照当前 SDK 和规范，对引擎 MCP 接口进行的诊断性审计。内容包括逐工具注册表、资源缺口分析、SDK 功能差异（1.12 → 1.29 → 2.0-alpha）、能力声明、传输层重构草案、A2A 可行性说明，以及按顺序排列的 7 步现代化路线图。该文档为下一阶段规划提供依据。文中未要求进行引擎变更。

数据

• lockfile 中有 5 个 sqlite-vec 平台（此前为 1 个）。npm audit --production：0 个漏洞（未变）。工具：23 个（未变）。评测固件：30 个（未变）。

1.6.5 新增内容

安全补丁。没有引擎代码变更、MCP 工具接口变更、平台变更或环境变量变更。

已修复

• CVE-2026-0621 — @modelcontextprotocol/sdk 的 UriTemplate 正则表达式存在 ReDoS 漏洞（已在 SDK 1.25.2 中修复）。此前的最低版本 ^1.12.1 允许在过时的 npm 缓存中解析到存在漏洞的版本；现已升级至 ^1.29.0，确保最低版本本身已修复此问题。
• GHSA-345p-7cg4-v4c7 — 共享的服务端／传输实例会泄露不同客户端之间的响应数据（已在 SDK 1.26.0 中修复）。实际上，这无法利用来攻击 ClarifyPrompt（一个主机对应一个服务实例），但存在漏洞的代码现在已彻底从依赖关系图中移除。
• SDK 随附的 HTTP 传输依赖子栈中存在 7 个传递依赖漏洞（2 个中危，5 个高危），涉及 hono、express-rate-limit、fast-uri、ip-address、path-to-regexp、qs、@hono/node-server。已通过 npm audit fix 清除。这些漏洞从未影响运行时——ClarifyPrompt 仅使用 stdio，不会加载 HTTP 传输——但它们会干扰用户的 npm audit 报告，让安装看起来不安全。

数据

• npm audit --production → 0 个漏洞（此前有 2 个 SDK CVE + 7 个传递依赖漏洞）。
• package-lock.json：净减少 336 行（旧的插入符号范围会拉取体积庞大且未使用的 HTTP 传输辅助依赖；修复后改为使用更精简的替代项）。
• 工具：23 个（不变）。平台：60+ 个（不变）。评测样例：30 个（不变）。
• 使用本地 Ollama 对新版最低版本进行了线路测试、集成测试套件、day2、推理测试，以及 30 个评测中的 29 个，均通过。唯一未通过的评测（analyzer-creative-media）是先前就存在的 qwen-coder-7b 分类器偶发错误——通过暂存回退并重新运行，已确认与 SDK 无关。

为什么提高最低版本很重要

^1.12.1 是会误导人的文档——实际上，从 2026 年初开始，任何全新的 npm install 都会因插入符号范围解析到 SDK 1.27.1。提高最低版本，让声明的基准与 npm 已经为大多数用户安装的版本保持一致，同时确保使用过时缓存的用户也能获得不低于最低要求的版本。这也为将来迁移到 2.0.0-alpha 做好准备，待该版本线稳定后即可进行迁移（新版 SDK 弃用 .tool() / .prompt() / .resource() 简写注册方式，改用带有 title、outputSchema 和 annotations 的 registerTool() / registerPrompt() / registerResource()）。

1.6.4 新增内容

文档与流程修复。不涉及引擎、MCP 工具或平台变更——但对打包分发模式进行了有意义的整理。

Pack 注册表已并回引擎仓库

LumabyteCo/clarifyprompt-packs（在 1.3 中以正确的原则、但在不恰当的规模下创建的独立社区 Pack 注册表）现已归档。它的三个入门 Pack 原本就已存放在本仓库的 packs/ 文件夹中；注册表原本打算作为权威来源，但实际上所有内容一直都通过这里的 npm tarball 发布。后来两边出现了不同步：higgsfield-creative-handbook 在 1.6.2 中发布，却始终未加入注册表，尽管注册表自己的 README 还告诉用户从那里获取 Pack。

1.6.4 的最终结果：

• 单一事实来源。 packs/*.md 知识 Pack 和 packs/platforms/*.yaml 平台配置都存放在 clarifyprompt-mcp 中，并随 npm tarball 一同发布。
• 本 README 新增顶层 知识 Pack 部分，介绍加载模式（load_knowledge_pack({source: "<url-or-path>", scope: ...})）、三个入门 Pack 和 Higgsfield、作用域语义以及如何参与贡献。
• 新增 packs/README.md——Pack 编写指南（frontmatter 架构、分块边界、质量标准）。内容取自已归档的注册表，确保不会丢失。
• 已归档仓库中的存档说明和重定向。 访问 clarifyprompt-packs 的用户会看到一条指向此处的横幅。

何时会重新拆分？

当出现必须拆分的理由时：仅针对 Pack 的社区 PR 队列、Pack 数量超过 20 个，或许可证／治理方式出现分歧。在此之前，维护两个仓库并保持同步的成本并不值得；毕竟预期中的受众并未出现。

数字

• **工具：**23 个（不变）。
• **平台：**60+ 个（不变）。
• **捆绑的知识包：**4 个（anthropic-brand-voice、higgsfield-creative-handbook、nextjs-14-best-practices、sox-compliance）——与 1.6.2/1.6.3 相同，只是现在正式纳入。
• **评测夹具：**30 个（不变）。
• **Tarball 大小：**与 1.6.3 相同。

1.6.3 新增内容

补丁版本。1.6.2 的 CI 标签推送运行暴露了两个实际问题——已在此修复，未更改任何引擎代码。

修复

• evals/fixtures/28-context-includes-git-state.yaml 之前断言 git_branch_present: true，但 GitHub Actions 会以 detached-HEAD 模式检出代码，此时 bundle.git.branch 正确地为 undefined（只有 SHA + 最近提交会被填充）。现已放宽为只断言 bundle_has_git: true——这才是在本地和 CI 环境中都不变的条件。
• evals/fixtures/17-critique-strong-prompt-accepts.yaml 对一个强提示词断言了 verdict: accept + overall_score_min: 7。gpt-4o-mini 的裁判校准比 qwen2.5-coder:7b 更严格，而且偶尔会返回格式错误的 overall 字段，解析器会将其默认设为 0 → verdict=reject。该夹具的真正目的是验证引擎接线（5+ 个维度、包含标准维度名称、无测试框架错误）——而不是比较不同模型的裁判校准。已移除 verdict 和严格的分数断言；保留了接线级检查。
• README Glama 徽章已从内嵌 <img>（经 GitHub 的 camo 代理时有时会损坏）替换为 shields.io 文字链接徽章，在所有渲染界面中都更稳定。

说明

• 没有引擎代码变更。 没有新增 MCP 工具（仍为 23 个）。没有平台变更（仍为 60+ 个）。没有环境变量变更。
• 本地 Ollama 上的评测基线不变。 这是针对 CI 的加固——使用 qwen-coder-7b 进行的本地运行在前后得到的结果相同。
• v1.6.2 标签推送时出现的 CI 发布门禁失败 是由评测失败引起的下游问题（Wait for evals workflow 步骤阻止了发布）。现在底层夹具不会再因 gpt-4o-mini + detached-HEAD CI 而误报失败，发布门禁也能通过。

1.6.2 新增内容

补丁版本。新增了两项内容，从引擎角度看都没有代码变更：

Higgsfield 创意手册知识包

packs/higgsfield-creative-handbook.md——一份社区风格的 Markdown 知识包，记录 Higgsfield 的实际规范：模型选择规则（13 个模型分别适用于哪些用例）、Soul ID 角色训练工作流、镜头运动词汇、提示词结构模式（长篇描述，而非关键词标签）、多参考编辑、Marketing Studio 模式、常见陷阱（不要照搬 Midjourney 的参数）、输出规格。

明确加载：

load_knowledge_pack source="https://raw.githubusercontent.com/LumabyteCo/clarifyprompt-mcp/main/packs/higgsfield-creative-handbook.md"

……或者，由于它包含在 npm tarball 中，也可以指向已安装的副本。Context Curator 会通过语义检索自动使用此知识包中的内容，为面向 Higgsfield 的提示词提供依据。完整的加载和作用域模型请参见知识包部分。

npm run matrix——多模型评测矩阵运行器

evals/matrix.mjs 会依次对 N 个模型运行 npm run eval，并将结果整合到一个并排的 HTML 文件中（默认输出至 evals/matrix.html）。它会运行单模型评测会跳过的、按模型类别启用的夹具（shape-small-local-model / shape-mid-tier-model / shape-reasoning-model），并让你一眼看出诸如“qwen-7b 未通过 analyzer-creative-media，而 gpt-4o-mini 通过了”的差异。

npm run matrix -- --models qwen2.5-coder:7b-instruct-q4_K_M,gpt-oss:20b-cloud,glm-5.2:cloud

输出为深色主题表格——行代表夹具，列代表模型，单元格显示通过 / 失败 / 跳过 / 出错，并通过工具提示显示哪些检查未通过。

配套修复：evals/run.mjs 新增了 --json-out <path> 标志，用于写入结构化的单模型结果（matrix.mjs 会使用它；CI Agent 也可以使用）。

数字

• 工具接口没有变化。 仍为 23 个 MCP 工具。
• 平台数量没有变化。 60+ 个平台（packs/platforms/*.yaml 未变）。
• 30 → 30 个测试样例（没有新增测试样例；矩阵属于工具，而非覆盖范围）。
• 知识包的 tarball 增大约 10 KB。 evals/matrix.mjs 不在 tarball 中——它是供维护者/贡献者使用的工具，而非运行时产物。

1.6.1 的新增内容

补丁版本。在 image 和 video 两个类别中新增 Higgsfield 作为目标平台。没有代码变更——仅新增 YAML 平台包和一个评估测试样例。

Higgsfield 是一个多模型创意平台，通过 https://mcp.higgsfield.ai/mcp 提供自己的 MCP 服务。在一个连接中，你可以使用：

• 图像：Soul 2.0、Soul Cinema、Soul Cast（角色一致性）、Flux 2、Seedream 5、Nano Banana Pro、GPT Image 2
• 视频：Cinema Studio、Veo 3.1、Kling 3.0、WAN 2.6、Seedance 2.0（Sora 2 已于 2026-09-24 下线——OpenAI 关闭了 Videos API，且未提供替代方案）
• 工作流：Soul ID 角色训练、Lipsync Studio、UGC Factory、Marketing Studio、virality_predictor

1.6.1 中的 ClarifyPrompt 平台条目将 Higgsfield 的模型标识符和提示词风格惯例（长篇自然语言；构图 + 光线 + 纹理 + 氛围；最高支持 4K 图像 / 15 s 视频 / 用于角色一致性的 Soul ID）作为语法提示呈现给整理者。

**推荐用法：**在客户端（Claude Desktop / Cursor / AI Butler / Claude Code）中同时安装 clarifyprompt-mcp 和 Higgsfield 的 MCP。使用 optimize_prompt(platform: 'higgsfield', ...) 或 compose_prompt(platform: 'higgsfield', ...) 进行编译，然后将编译后的提示词传递给 Higgsfield 的 generate_image / generate_video 工具。MCP 在客户端组合；ClarifyPrompt 保持在“编译”层。

评估测试样例从 29 个增至 30 个。MCP 工具接口与 1.6.0 相同（23 个工具、1 个资源）。环境变量没有变化。

1.6.0 的新增内容

围绕引擎的四大支柱（记忆 / Agent 式能力 / 模型 / 上下文）进行了四项有针对性的新增，每项都配有真实评估测试样例。新增 3 个 MCP 工具（总计 23 个）。与 1.5.x 完全向后兼容——没有移除工具或字段，也没有必需的环境变量变更。

记忆——显式事实 CRUD（memory_remember、memory_forget、memory_list_facts）

在 1.6 之前，事实只能通过 对 save_outcome 进行反思 进入持久化记忆——这是隐式的、由大模型提取的事后过程。1.6 新增了显式路径：

• memory_remember——直接插入一个 (subject, predicate, object) 三元组，并显式指定置信度。来源标记为 user:explicit。自动嵌入，以便后续进行语义检索。
• memory_forget——通过 id 对事实进行软删除（双时间模型中的 invalidated_at）。具有幂等性：重复删除已失效的事实不会产生任何操作，并会正常返回 success: false。
• memory_list_facts——列出指定范围内的有效事实（默认范围为 user），可按谓词筛选。按最近观察时间排序。

这弥补了显而易见的用户体验缺口：引擎此前只能从 结果 中学习——现在用户可以直接说“记住我更喜欢 X”。

Agent 式能力——compose_prompt 新增 max_iterations 修订循环

以前，compose_prompt 只会修订 一次（如果判定结果不是 accept，批判环节的 improvedPrompt 会替换优化结果）。1.6 新增了一个循环：

{ "prompt": "...", "post_critique": true, "auto_revise": true, "max_iterations": 3 }

除第一次迭代外，每次迭代都会基于上一轮改进后的提示词重新运行 optimize + critique。当出现 verdict=accept、没有可反馈使用的 improvedPrompt，或达到上限时停止。pre_clarify 只运行一次（改写后没有必要再次询问）。响应中新增 iterations 字段，用于显示实际执行的迭代次数。硬性上限为 5 次，以防成本失控。

Models — 按阶段进行模型路由

现在，每个 compose 阶段都可以使用不同的模型：

{
  "prompt": "...",
  "clarify_model": "qwen2.5-coder:7b-instruct-q4_K_M",
  "optimize_model": "claude-sonnet-5",
  "critique_model": "gpt-4o-mini"
}

在便宜的本地模型上运行 clarify，在预算充足的前沿模型上运行 optimize，在便宜的评审模型上运行 critique。覆盖设置会贯穿每一层——响应中的 optimization.metadata.model 和 critique.judgeModel 会反映各阶段实际运行的模型。

Context — git 状态 + 环境信号

两个新的信号收集器会向 Context Curator 提供信息：

• bundle.git — 当前分支、短 SHA、未提交更改标记、最近 5 条提交标题。无需你明说，就能让引擎根据“你正在迭代的内容”构建提示词。通过 git rev-parse / git status / git log 检测；当当前工作目录不是 Git 仓库时会静默失败。
• bundle.environment — nowIso / weekday / timezone（通过 Intl.DateTimeFormat 获取 IANA 时区）。有助于处理与时间相关的提示词（例如“明天发送这封邮件”）。仅使用纯 JS，不会失败。

这两项在 Curator 中都是低效用候选项（不会占用过多预算），但在相关时会作为上下文来源提供。

评测覆盖范围

23 → 29 个夹具（新增 6 个）：

• 24 memory-remember-persists / 25 memory-forget-invalidates — Me1 CRUD 往返测试
• 26 compose-loop-iterates — A1 循环基础设施（新增 iterations_min / iterations_max 检查）
• 27 compose-per-stage-models-honored — M1 按阶段进行模型路由（新增 optimization_model_eq / critique_model_eq 检查）
• 28 context-includes-git-state / 29 context-includes-environment-time — C1 + C4 信号（新增 bundle_has_git / bundle_has_environment / git_branch_present 检查）

在 qwen2.5-coder:7b 上的本地基线：通过 25 项 / 失败 1 项 / 跳过 3 项 / 平均 97%。唯一失败项仍是持续存在的 analyzer-creative-media 模型类别信号（未改动）。

1.5.2 版本新增内容

这是首个由 CI 评测门禁（使用 gpt-4o-mini）驱动差异的版本。接入 OPENAI_API_KEY 密钥后，门禁立即发现了 3 个实际问题并促成修复：

• 记忆存储现已支持任意嵌入维度 (#2)。持久化向量表的维度被硬编码为 768（nomic-embed-text 的默认值），因此任何配置 EMBED_MODEL=text-embedding-3-small（1536）、voyage-3（1024）、embed-english-v3.0（1024）或其他非 768 维模型的用户，都会在首次调用 memory_search 时遇到 Dimension mismatch: expected 768, got N。现在，存储会根据嵌入器的实际维度生成表名，并在启动时创建对应维度的表。现有的 768 维安装不受影响。
• LLM 客户端新增 LLM_TIMEOUT_MS 环境变量覆盖设置。默认值仍为 30s；使用速度较慢的托管模型时，用户可以调高此值。评测工作流对 gpt-4o-mini 使用 120s。
• 加固评测框架 — 工具抛出异常时不再导致崩溃（SDK 会返回纯文本错误响应；此前评测框架会对其执行 JSON.parse 并崩溃）。单个夹具出错不再会导致整个运行失败。
• 实时评测徽章。 evals.yml 工作流会在每次推送到 main 时运行。本 README 顶部的 [![evals]](...) 徽章会显示其实时状态。目前在 gpt-4o-mini 上的状态为绿色：20/0/3 · 100%。

没有新增 MCP 工具。没有环境变量接口变更（仅新增可选的 LLM_TIMEOUT_MS）。完全兼容 1.5.x 版本。

1.5.1 的更新内容

基于 1.5.0 发布的补丁版本。仅改进文档和发布流程；运行时行为与 1.5.0 完全相同。

• 更新 README 中的宣传内容 — 1.5.0 发布时，README 中有三处仍显示 1.4.0（标题区块引用、“What's new in X”标题、“cumulative through X”注释）。其他所有版本信息位置（package.json、package-lock.json、server.json、src/index.ts、CHANGELOG）都是正确的，但由于没有自动化流程更新文案，内容出现了偏差。1.5.1 修正了这一问题。
• 新增两项发布检查审计 — CP-11（README 宣传内容一致性）会在上述三处任一处未引用当前 package.json#version 时直接失败。CP-12（平台包格式有效性）会解析每个 packs/platforms/*.yaml 文件并验证其是否符合架构。CP-11 同日被纳入用户级（跨项目）发布检查技能，因此未来的项目也能受益。
• 没有代码变更。 没有新增 MCP 工具。没有新增环境变量。tarball 结构与 1.5.0 相同，仅 CHANGELOG 增加了几百字节。

1.5.0 的更新内容

内置平台改为声明式配置。 58 个以上的硬编码 TypeScript 平台数组移至 packs/platforms/*.yaml — 现在添加内置平台只需编辑 YAML，无需修改 TS。TypeScript 层改为运行时加载器，并保留硬编码的回退表。格式错误的 YAML 永远不会导致服务软故障。

packs/platforms/
  chat.yaml       9 platforms
  code.yaml       9
  document.yaml   8
  image.yaml     10
  music.yaml      4
  video.yaml     11
  voice.yaml      7
  README.md      contributor docs

要添加新的内置平台：在相应的类别文件中添加一个条目，运行 npm run build，然后发起 PR。无需修改 TS。通过运行时注册自定义平台（register_platform）的方式对用户安装的平台仍然有效，且行为不变。

• 内存层评测覆盖。 评测测试框架现在支持 setup: [{tool, args}, ...] — 一个在主 input 之前执行的 MCP 工具调用列表。新增两个使用该功能的测试样例：一个内联加载知识包，并验证经过嵌入 → 存储 → 检索 → 整理 → grounding 流程后，分块内容会出现在 grounding.sources 中；另一个用于验证向量搜索的排序质量。共 23 个测试样例（1.4.0 时为 20 个）。
• 现代化测试基础设施。 集成测试和 Day-2 测试套件过去会断言字面版本字符串（1.3.0、16 tools），每次版本升级都会失败。现在它们会从 package.json 读取 EXPECTED_VERSION，并断言工具集合是否存在，而不是工具数量。今后的版本升级不会再导致测试失败。
• 推广材料。 docs/adoption/ 提供可直接复制粘贴的 Show HN 正文、Reddit 帖子、Twitter 讨论串、awesome-mcp-servers PR 模板，以及目录提交规范（mcp.so、Smithery、mcp-get、PulseMCP、modelcontextprotocol/servers）。
• 新增一项运行时依赖： 将 js-yaml 从 devDependency 提升为平台加载器的运行时依赖（约 200 KB）。
• MCP 工具界面与 1.4 相同。 20 个工具、1 个资源。没有新增工具；没有移除工具；结果结构保持不变。

1.4.0 之前的版本 — 可组合的流水线

四个核心操作作为一等 MCP 工具，可相互组合。可单独使用任意工具，也可一次调用运行完整链路：

  ┌─────────────┐     ┌─────────────────────┐     ┌──────────────┐
  │  clarify    │ →   │  ground OR optimize │ →   │   critique   │
  │  (optional) │     │       (core)        │     │  (optional)  │
  └─────────────┘     └─────────────────────┘     └──────────────┘

  one call = compose_prompt(prompt, [sources], post_critique, auto_revise, ...)

• clarify_with_user — 给定一份含糊的草稿，返回 1–3 个有针对性的澄清问题。每个问题都包含可原样接受的 suggested_answer、可选的 2–4 个快速选择 options，以及一个 dimension 标签（受众/范围/格式/长度/语气/约束/目标/平台）。对于明确且格式完善的提示词，会快速返回 clarificationNeeded: false，因此可以无缝置于 optimize_prompt 之前的流水线中，不会增加每次调用的延迟成本。
• ground_prompt — optimize_prompt 的严格检索增强变体。调用者提供的来源具有最高优先级，高于项目规则和固定指令，并会在追踪记录中分别标记为 user-source:N。严格模式：没有非空来源时会报错，不会静默回退。每个来源的正文上限为 4000 个字符，防止单次超长粘贴内容占用过多预算。
• critique_prompt — 由大模型充当评审。按 5 个默认维度（清晰度、具体性、意图契合度、格式适配度、长度适宜性）为候选提示词打 0–10 分，也可使用自定义标准；并针对每个维度提供评分理由和具体建议，同时给出总分和评定结果（accept / revise / reject）。分数低于 revise_threshold（默认 7.0）时，还会返回可直接替换使用的 improvedPrompt。可用于预检（“这个提示词足以交给昂贵的大模型吗？”）、事后分析（“问题是否出在提示词上？”），或对 N 个优化版本进行 A/B 选择。
• compose_prompt — 一次 MCP 调用即可运行标准流水线。根据是否传入 sources，自动选择 grounding 或 optimize 分支。pre_clarify: 'auto' | 'always' | 'never'。设置 post_critique: true 可增加一次评审。设置 auto_revise: true 时，若评定结果不是 accept，则用改写版本替换 final_prompt。返回按阶段记录的 stages 审计数组，让调用者准确了解运行了哪些步骤。
• 评测框架 v0 — evals/ 下的确定性回归测试。20 个 YAML 测试用例覆盖 analyzer、shape、intent-overlay、grounding、clarify、critique、ground 和 compose 接口。npm run eval 会生成控制台摘要和独立的深色主题 HTML 报告。多模型矩阵只需用 bash：针对每个模型运行 LLM_MODEL=... npm run eval -- --report-path evals/report-X.html。
• 由 CI 控制的评测（选择启用） — 将 OPENAI_API_KEY 设为仓库密钥后，评测框架会在 CI 中以 gpt-4o-mini 运行，作为发布门槛。默认关闭；未设置密钥时，不会有任何内容离开你的机器。
• 5 个新的 MCP 工具（共 20 个）。optimize_prompt 还新增了 userProvidedSources 注入点——ground_prompt 和 compose_prompt 都会在底层使用它；你也可以直接使用，以便在不启用严格模式验证的情况下进行明确控制。

延续自 1.3：持久化记忆、知识包和反思式学习。整理器会继续为 grounding 来源评分，并将其纳入目标模型的剩余上下文窗口。explain_last_curation 仍会按调用列出已选和已拒绝候选项及其原因。

包含内容（截至 1.16.0 的累计更新）

• Context Engine — 自动收集工作区规则（CLAUDE.md、AGENTS.md、.cursorrules、.clinerules、clarify.md），从 package.json 和同级清单文件中检测框架和语言，跟踪活动文件摘录，并维护每个会话的近期优化及其结果的环形缓冲区。
• 统一的 PromptAnalyzer — 一次 LLM 调用即可同时生成 { category, intent, recommendedMode, confidence }。包含 10 种意图：production-code、brand-voice、stakeholder-comm、data-extract、creative-media、technical-spec、analysis、quick-draft、exploration、unknown。存在歧义时，意图优先于表面关键词。
• 针对目标模型调整提示词 — 系统提示词、maxTokens 和 temperature 会根据下游大模型的上下文窗口和解析出的意图进行调整。小型本地模型使用精简提示词；Claude/GPT-4/Gemini 则使用完整内容。
• 上下文依据（统一、按优先级排序） — 用户固定指令 → 项目规则 → 活动文件 → 之前接受的示例 → 网络搜索 → 工作区元数据 → 目标模型提示 → 自定义平台指令 → 内置语法提示。不再存在并行的上下文孤岛。
• 会话检索（save_outcome） — 调用方针对每项优化反馈 accepted | edited | rejected；同一会话中相似的已接受输出会作为少样本示例注入后续相似提示词。由持久化记忆（SQLite + sqlite-vec）提供支持，因此已接受的结果在重启后仍会保留。
• 本地 JSONL 跟踪 — 每次优化都会向 $CLARIFYPROMPT_HOME/traces/YYYY-MM-DD.jsonl 写入一条结构化跟踪记录（现在包含 shape、groundingSources、error 字段）。不会上传任何内容。 可通过 CLARIFYPROMPT_TRACE=off 切换。
• 统一的 $CLARIFYPROMPT_HOME — 用一个环境变量管理 ClarifyPrompt 写入的所有内容。旧版 CLARIFYPROMPT_CONFIG_DIR / CLARIFYPROMPT_DATA_DIR 仍可使用（会提示弃用，可设为静默）。
• 三种传输方式 — stdio（默认）、streamable-http（通过 Node http 提供 MCP，支持有状态会话和 /health），以及 a2a（Agent-to-Agent 对等端：Agent 卡片、JSON-RPC message/send + SSE message/stream、任务取消、input-required 澄清）。使用一个 CLARIFYPROMPT_TRANSPORT 环境变量；stdio 行为与之前逐字节一致。
• 61 个平台、7 个类别、带 verifiedAt 日期的配置包、自定义平台 — 所有内置事实均已根据截至 2026-10-05 的供应商最新文档核实，并新增了 Seedance、ElevenLabs Music、Lyria 等平台，Sora 已退役。
• 适用于任何 LLM、任何提供商。 一套代码路径适用于任何兼容 OpenAI 的 API — Ollama（本地 + 云端）、LM Studio、vLLM、OpenAI、Google Gemini、xAI Grok、Groq、Mistral、DeepSeek、Cohere、Perplexity、Together、Fireworks、OpenRouter — 还可直接使用 Anthropic Claude。推理模型（o1/o3/o4、deepseek-reasoner、gpt-oss、*-thinking）会被自动检测，并分配更大的 token 预算，以确保其实际生成内容。查看下方 15 个以上的预配置提供商示例。
• Apache-2.0，永久免费。 核心开源，不会更换许可。

快速开始

使用 Docker

从 GitHub Container Registry 拉取已发布的镜像（多架构：amd64 + arm64，附带签名的来源证明 + SBOM）：

docker pull ghcr.io/lumabyteco/clarifyprompt-mcp:latest

所有配置都在运行时传入 — 镜像中不会预置任何内容，因此镜像可安全共享且不含机密：

# stdio (for MCP hosts that launch the container)
docker run --rm -i \
  -e LLM_API_URL=http://host.docker.internal:11434/v1 \
  -e LLM_MODEL=qwen2.5:7b \
  -e CLARIFYPROMPT_HOME=/data \
  -v clarifyprompt-data:/data \
  ghcr.io/lumabyteco/clarifyprompt-mcp:latest

# or serve over HTTP / A2A
docker run --rm -p 3000:3000 \
  -e CLARIFYPROMPT_TRANSPORT=a2a -e CLARIFYPROMPT_HTTP_HOST=0.0.0.0 \
  -e LLM_API_URL=http://host.docker.internal:11434/v1 -e LLM_MODEL=qwen2.5:7b \
  ghcr.io/lumabyteco/clarifyprompt-mcp:latest

在 CLARIFYPROMPT_HOME 挂载卷，以便在不同运行之间保留记忆、跟踪记录和配置包。在运行时通过 -e 环境变量（或 --env-file）传入 LLM_API_KEY / EMBED_API_KEY — 切勿将它们预置到镜像中。

使用 Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "clarifyprompt": {
      "command": "npx",
      "args": ["-y", "clarifyprompt-mcp"],
      "env": {
        "LLM_API_URL": "http://localhost:11434/v1",
        "LLM_MODEL": "qwen2.5:7b"
      }
    }
  }
}

使用 Claude Code

claude mcp add clarifyprompt -- npx -y clarifyprompt-mcp

启动前，在 Shell 中设置环境变量：

export LLM_API_URL=http://localhost:11434/v1
export LLM_MODEL=qwen2.5:7b

使用 Cursor

将以下内容添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "clarifyprompt": {
      "command": "npx",
      "args": ["-y", "clarifyprompt-mcp"],
      "env": {
        "LLM_API_URL": "http://localhost:11434/v1",
        "LLM_MODEL": "qwen2.5:7b"
      }
    }
  }
}

与 AI Butler 集成

AI Butler 是一个可自托管的个人 AI Agent 运行时——单个 Go 二进制文件、多渠道聊天、MCP 生态系统中心。将 ClarifyPrompt 添加到其 mcp.servers 配置中，Agent 就能将全部 23 个工具作为原生能力使用，可从任何渠道调用（网页聊天、终端、Telegram、Slack 等）。AI Butler 通过 MCP 的 tools/list 动态发现工具，因此在 ClarifyPrompt 中添加／移除工具后，Agent 的可用工具会自动更新——无需修改 Butler 端的配置。

编辑 ~/.aibutler/config.yaml：

configurations:
  mcp:
    servers:
      - name: clarifyprompt
        command: clarifyprompt-mcp
        env:
          LLM_API_URL: "http://localhost:11434/v1"
          LLM_MODEL: "qwen3-vl:8b"

重启 AI Butler。启动日志会确认工具已接入：

Agent 会根据请求列出完整的工具集——每个工具都带有 clarifyprompt. 前缀：

📸 以上截图来自 1.2 时代的集成（11 个工具）。 当前的 1.6.x 提供 23 个工具——optimize_prompt、 clarify_with_user、ground_prompt、critique_prompt、 compose_prompt，以及管理／检查／记忆工具（memory_search、memory_remember、memory_forget、 memory_list_facts、知识包工具、追踪记录、自定义平台等）。AI Butler 会通过 MCP tools/list 发现并自动获取这些工具；无需更改配置。

端到端驱动 Context Engine

你可以使用 inspect_context 预览引擎将会收集的内容（而不运行优化）：

然后，针对 60 多个受支持平台中的任意一个运行实际优化器：

每次优化都会在 ~/.clarifyprompt/traces/YYYY-MM-DD.jsonl 中生成一行 JSONL 记录——严格保存在本地，绝不上传。list_traces 工具会将这些记录整理成可查询的摘要，并通过 get_trace 支持回放：

完整的集成指南——包括通过聊天驱动全部 11 个工具、配置选项和自然语言使用示例——请参阅 AI Butler 文档： 集成 MCP 服务。

配置与组合面板

运行完整流水线，并在支持的宿主中查看交互式结果面板所需的一切配置。

执行工作的模型

ClarifyPrompt 会调用一个 OpenAI 兼容或 Anthropic 端点，通过环境变量设置：

LLM_API_URL=http://localhost:11434/v1     # Ollama shown; any OpenAI-compatible URL works
LLM_API_KEY=                              # empty for local Ollama; a key for hosted providers
LLM_MODEL=qwen2.5:7b                      # the model that rewrites and judges

输出取决于模型——结构（平台语法、评审维度）在不同模型间保持一致；具体措辞和评分则会因模型而异。

一次调用即可运行整个流程

compose_prompt({
  "prompt": "write a product update email about our new dashboard",
  "platform": "claude",     // target a platform's tuning; omit for portable, neutral output
  "pre_clarify": "never",   // "auto" | "always" | "never"
  "post_critique": true     // adds the LLM-as-judge pass (verdict + the six score dimensions)
})

返回 { optimization: { id, sessionId, originalPrompt, platform, … }, finalPrompt, critique: { verdict, overallScore, dimensions[] }, stages[] }。

指定平台

platform:（用于 optimize_prompt 或 compose_prompt）可选择平台专属调优方案，例如 midjourney、dall-e、veo、suno、claude、chatgpt、cursor（内置 61 个，带有 verifiedAt 日期的记录，另可注册任意平台）。对于聊天，平台就是模型（claude、chatgpt、gemini、llama、deepseek 等）。如果省略 platform，文本类别（chat/document/code）会生成可移植、与平台无关的输出；指定平台即可采用该平台特有的表达方式。

按阶段指定模型（例如，让更强的模型担任评审）

compose_prompt 可以将各阶段路由到不同的模型名称：

compose_prompt({
  "prompt": "…",
  "optimize_model": "qwen2.5:14b",   // rewrite on a cheaper model
  "critique_model": "gpt-4o",        // judge on a stronger one
  "clarify_model":  "qwen2.5:7b"
})

重要：所有按阶段指定的名称都指向同一个 LLM_API_URL——此项覆盖只会更改模型名称，不会更改端点。因此，如果 LLM_API_URL 指向 Ollama，所有按阶段指定的模型都必须是 Ollama 模型；如果指向 OpenAI，所有模型都必须是 OpenAI 模型。若要真正混用提供商（例如，用本地模型优化，再用 gpt-4o 进行评审），请将 LLM_API_URL 指向一个同时提供这两种名称的网关，例如 OpenRouter、LiteLLM 代理或任何兼容 OpenAI 的路由器。（optimize_prompt 本身不支持按调用覆盖模型；它使用 LLM_MODEL。）

交互式组合面板（MCP Apps）

在支持 io.modelcontextprotocol/ui 扩展的宿主中——Claude Desktop、Cursor、VS Code 等——compose_prompt 会在结果旁呈现实时面板：显示原始提示词、优化后的输出（带有显示更改差异切换开关）、for <platform> / general purpose 徽标、六个评审评分条，以及 接受 / 修改 操作。接受会通过 save_outcome 记录结果（为少样本记忆循环提供数据）；修改会将你的反馈发送回聊天。没有此扩展的宿主不受影响——它们会得到相同的文本和 structuredContent 结果，但不会显示面板。

支持的平台（内置 61 个，带 verifiedAt 日期记录，并支持无限自定义平台）

类别	平台	默认值
图像（12）	Midjourney (V8.x)、OpenAI image (GPT Image 2/DALL-E 3)、Stable Diffusion、Flux (2)、Ideogram、Leonardo AI、Adobe Firefly、Grok Aurora、Google Imagen (4)、Nano Banana、Recraft、Higgsfield	Midjourney
视频（12）	Runway (Gen-4.5)、Pika (2.2)、Kling (3.0/Omni)、Luma (Ray 2)、Minimax/Hailuo (2.3)、Google Veo (3.1)、Seedance (2.0/2.5)、Wan (2.6)、HeyGen、Synthesia、CogVideoX、Higgsfield	Runway
聊天（9）	Claude、ChatGPT、Gemini、Llama、DeepSeek、Qwen、Kimi、GLM、Minimax	Claude
代码（9）	Claude、ChatGPT、Cursor、GitHub Copilot、Windsurf、DeepSeek Coder、Qwen Coder、Codestral、Gemini	Claude
文档（8）	Claude、ChatGPT、Gemini、Jasper、Copy.ai、Notion AI、Grammarly、Writesonic	Claude
语音（7）	ElevenLabs (v3)、OpenAI TTS (gpt-4o-mini-tts)、Fish Audio、Sesame、Google TTS、PlayHT、Kokoro	ElevenLabs
音乐（6）	Suno (v6)、Udio、ElevenLabs Music (v2.5)、Google Lyria (3.5)、Stable Audio、MusicGen	Suno

工具

optimize_prompt

主要工具。为特定 AI 平台优化提示词。

{
  "prompt": "a cat sitting on a windowsill",
  "category": "image",
  "platform": "midjourney",
  "mode": "concise"
}

除 prompt 外，所有参数均为可选。 如果省略 category 和 platform，ClarifyPrompt 会根据提示词内容自动检测。

三种调用模式：

模式	示例
零配置	{ "prompt": "sunset over mountains" }
仅指定类别	{ "prompt": "...", "category": "image" }
完全显式指定	{ "prompt": "...", "category": "image", "platform": "dall-e" }

参数：

参数	必填	描述
prompt	是	要优化的提示词
category	否	chat、image、video、voice、music、code、document。省略时自动检测。
platform	否	平台 ID（例如 midjourney、dall-e、veo、claude）。省略时使用该类别的默认平台。
mode	否	输出风格：concise、detailed、structured、step-by-step、bullet-points、technical、simple。默认值：detailed。
enrich_context	否	设置为 true，以使用网络搜索丰富上下文。默认值：false。
session_id	否	将相关优化串联起来，使会话记忆能够影响后续调用。省略时自动生成。
file_path	否	当前文件路径——用于推断语言并调整平台提示。
file_language	否	当前文件的显式语言覆盖值。
file_excerpt	否	当前文件的简短摘录（≤2 KB），用于为改写提供依据。
cwd	否	要扫描 CLAUDE.md / AGENTS.md / .cursorrules / package.json 的工作目录。默认为服务端 cwd。
user_locale	否	用于设定语气和语言的区域设置提示（例如 en-US、ar-EG）。
user_pinned_instructions	否	固定且始终应用的用户指令（简短的核心记忆块）。
include_bundle	否	在响应中包含解析后的 ContextBundle 摘要。默认值：false。
skip_intent_resolution	否	跳过意图分类器 LLM 调用（速度更快，但会丢失意图信号）。默认值：false。

响应（1.2.0）：

{
  "id": "opt_mo9vlg9i_foohjx",
  "sessionId": "sess_mo9vlfn3_abc123",
  "originalPrompt": "a dragon flying over a castle at sunset",
  "optimizedPrompt": "a majestic dragon flying over a medieval castle at sunset --ar 16:9 --v 8.2 --style raw --q 2 --s 700",
  "category": "image",
  "platform": "midjourney",
  "mode": "concise",
  "modeSource": "analyzer",
  "analysis": {
    "category": "image",
    "intent": "creative-media",
    "recommendedMode": "detailed",
    "confidence": "high",
    "source": "llm"
  },
  "grounding": {
    "sources": ["project-rules", "workspace-meta", "target-model", "platform-hints"],
    "acceptedExamplesUsed": 0
  },
  "shape": {
    "systemPromptBudget": "standard",
    "maxTokens": 2048,
    "temperature": 0.9
  },
  "metadata": {
    "model": "qwen2.5:14b-instruct-q4_K_M",
    "processingTimeMs": 3911,
    "strategy": "ImageStrategy"
  },
  "detection": { "autoDetected": true, "detectedCategory": "image", "detectedPlatform": "midjourney", "confidence": "high" },
  "intent": { "detected": "creative-media", "confidence": "high" }
}

规范的分类字段为 analysis。detection 和 intent 字段是已弃用的别名，仅为兼容 1.x 而保留；它们将在 2.x 中移除。

modeSource 表示最终模式的判定方式（如果由你传入，则为 user；如果由意图驱动，则为 analyzer；两者都不是，则为 default）。

grounding.sources 按优先级顺序列出提供内容的 Grounding Context 部分。grounding.acceptedExamplesUsed 表示引擎从 save_outcome 历史记录中提取了多少个少样本示例。

shape 表示系统提示词针对目标模型调整后的大小。

clarify_with_user （1.4.0 新增）

对于含义不明确的草稿提示词，此工具会返回 1–3 个有针对性的澄清问题，而不是自行猜测。当你无法判断用户的请求能否生成高质量改写时，可在 optimize_prompt 之前将其作为预处理步骤。

{
  "prompt": "make it better",
  "force": true
}

响应：

{
  "clarificationNeeded": true,
  "reason": "Clarification recommended (analyzer confidence=low; intent=unknown; prompt is short (12 chars); caller passed force=true).",
  "questions": [
    {
      "question": "What outcome do you want from this prompt — what does success look like?",
      "reasoning": "The draft is ambiguous on the goal/audience dimension; pinning this typically resolves most downstream ambiguity.",
      "suggestedAnswer": "Make the email shorter, clearer, and more action-oriented.",
      "options": ["Make it shorter", "Make it more formal", "Make it more persuasive"],
      "dimension": "goal"
    }
  ],
  "analysis": { "category": "chat", "intent": "unknown", "confidence": "low" }
}

suggestedAnswer 始终会填充内容——调用方可以直接照用，无需停下来等待。options 是可选的；UI 客户端可以将其显示为快速选择按钮。dimension 标签用于对问题所针对的维度进行分类。

短路机制： 当分析器的置信度为 high 且提示词长度并非特别短时，此工具会返回 clarificationNeeded: false，且除分析器外不再调用 LLM。因此，你可以将其放在 optimize_prompt 前面作为流水线步骤，而不会让每次调用都增加延迟。传入 force: true 可禁用短路机制。

ground_prompt （在 1.4.0 中新增）

严格的检索增强版本 optimize_prompt。调用方提供的来源固定为最高优先级，高于项目规则和固定指令，确保改写以你提供的材料为依据，而非由整理器自行决定哪些内容相关。

{
  "prompt": "rewrite the launch announcement to match our voice",
  "category": "document",
  "platform": "claude",
  "sources": [
    {
      "label": "Brand Voice Rules",
      "body": "Tone: warm, plain-spoken, no jargon. Always lead with the user benefit. Avoid 'leverage', 'synergy', 'robust'. Max sentence length: 18 words.",
      "kind": "rules"
    },
    {
      "label": "Launch Draft",
      "body": "Today we're launching FlowSync Pro — a tool to leverage AI synergy for robust team coordination...",
      "kind": "draft"
    }
  ]
}

返回与 optimize_prompt 相同的结构，并额外包含 usedSources（实际纳入整理后依据内容的来源）和 droppedSources（内容为空或被丢弃的来源）。来源会在追踪记录中显示为 user-source:0、user-source:1 等。

**严格模式：**没有非空来源时会报错，不会静默回退。每个来源的正文上限为 4000 个字符，避免单次粘贴的大段内容占用过多预算。

critique_prompt （在 1.4.0 中新增）

由 LLM 担任评判者。对候选提示词按 6 个默认维度进行 0–10 分评分，并在低于阈值时返回改进后的改写版本。

{
  "prompt": "make it good",
  "revise_threshold": 7
}

响应：

{
  "overallScore": 2.0,
  "verdict": "reject",
  "summary": "Reject — substantial rewrite required.",
  "dimensions": [
    { "name": "clarity", "score": 1, "rationale": "...", "suggestions": ["Specify what 'it' refers to", "..."] },
    { "name": "specificity", "score": 0, "rationale": "...", "suggestions": [...] },
    { "name": "intent_alignment", "score": 3, "rationale": "...", "suggestions": [...] },
    { "name": "format_fitness", "score": 2, "rationale": "...", "suggestions": [...] },
    { "name": "length_appropriateness", "score": 1, "rationale": "...", "suggestions": [...] },
    { "name": "plain_language", "score": 4, "rationale": "...", "suggestions": [...] }
  ],
  "improvedPrompt": "Improve the README's getting-started section: shorten...",
  "improvements": ["Specified the artifact (README's getting-started section)", "Added concrete success criteria", "..."],
  "judgeModel": "qwen2.5-coder:7b-instruct-q4_K_M"
}

参数：

参数	默认值	说明
prompt	—	要评分的候选提示词。
original_prompt	—	评判优化版本时，用户最初提出的要求。用于 intent_alignment 维度。
criteria	6 个默认维度	自定义维度：[{ name, description }, ...]。最多约 8 个维度。
revise_threshold	7.0	总分低于此值时会触发改写流程。
skip_rewrite	false	完全跳过改写流程（速度更快；仅返回评分）。

**合理性检查：**如果评判者给出的 overall 比各维度平均分高出超过 2.5 分，引擎会对其进行修正。

compose_prompt （在 1.4.0 中新增）

规范的处理流水线。一次调用即可依次执行 clarify → ground/optimize → critique → 可选的自动修订。

{
  "prompt": "Write a TypeScript function that takes an array of email strings and returns only those that match RFC 5322 syntax. Include unit tests using Vitest with at least 6 test cases.",
  "pre_clarify": "auto",
  "post_critique": true,
  "auto_revise": true
}

响应（已截断）：

{
  "stages": [
    { "name": "clarify",  "ranAt": "...", "durationMs":  541, "summary": "no clarification needed (short-circuit)" },
    { "name": "optimize", "ranAt": "...", "durationMs": 3128, "summary": "5 grounding source(s) selected" },
    { "name": "critique", "ranAt": "...", "durationMs": 3422, "summary": "verdict=accept, score=8.4" }
  ],
  "finalPrompt": "Write a TypeScript function `validateEmails(emails: string[]): string[]` that...",
  "clarificationRequired": false,
  "clarification": { "clarificationNeeded": false, ... },
  "optimization": { "id": "opt_...", "optimizedPrompt": "...", ... },
  "critique": { "overallScore": 8.4, "verdict": "accept", ... }
}

finalPrompt 是应发送给下游的内容。除非 auto_revise: true、critique 判定结果不是 accept 且存在 improvedPrompt，否则它等于 optimization.optimizedPrompt（或 grounding.optimizedPrompt）；在这种情况下，finalPrompt 是改写后的提示词，且 revised: true。

分支：

输入	路径
没有 sources	optimize_prompt 分支（自动整理依据内容）
sources 非空	ground_prompt 分支（严格使用调用方提供且置顶的来源）
pre_clarify: "auto"（默认）	运行 clarify；对于置信度高的提示词，不显示问题便提前结束
pre_clarify: "always"	始终运行 clarify；若出现问题，则停止处理链
pre_clarify: "never"	完全跳过 clarify
post_critique: true	在 optimize/ground 后运行 critique
auto_revise: true（且 post_critique: true）	当判定结果 !== accept 且存在 improvedPrompt 时，替换 finalPrompt

**硬性停止：**如果 clarify 提出问题（仅在 pre_clarify: "always" 或低置信度提示词下使用 auto 时发生），处理链会停止并返回 clarificationRequired: true。调用方回答问题，将答案整合进提示词后重新调用（通常使用 pre_clarify: "never" 跳过第二轮 clarify）。

1.6.0 新增内容

• max_iterations（1–5，默认值为 1）——Agent 式修订循环。当 auto_revise: true 且 post_critique: true 时，每轮的 improvedPrompt 都会反馈至 optimize+critique，直到判定结果为 accept、没有可用的 improvedPrompt，或达到上限。Pre-clarify 只会运行一次。响应中包含 iterations，显示实际运行的轮数。

• clarify_model / optimize_model / critique_model——按阶段路由模型。每个参数都会覆盖该阶段的环境变量 LLM_MODEL。可用它在不同成本/质量档位之间路由 compose，例如：clarify 使用本地低成本模型，optimize 使用托管的前沿模型，critique 使用低成本模型：

  {
    "prompt": "...",
    "post_critique": true,
    "clarify_model":  "qwen2.5-coder:7b-instruct-q4_K_M",
    "optimize_model": "claude-sonnet-5",
    "critique_model": "gpt-4o-mini"
  }
  

  响应中的 optimization.metadata.model 和 critique.judgeModel 反映了各阶段实际运行的模型。

inspect_context （1.2.0 新增）

预览 ClarifyPrompt 针对给定提示词会组装的 ContextBundle，包括工作区规则、框架、目标模型能力、解析出的意图和会话历史，而无需运行完整的优化流程。适用于调试优化结果为何如此。

{
  "prompt": "Write an email to finance explaining the Q2 spend variance",
  "category": "document",
  "cwd": "/path/to/your/project"
}

以 JSON 格式返回完整的 ContextBundle。

list_traces （1.2.0 新增）

列出本地追踪器捕获的近期优化追踪摘要（当 CLARIFYPROMPT_TRACE=local 时启用，此为默认值）。

{ "day": "2026-04-22", "limit": 50 }

返回追踪 ID、输入预览、解析出的意图、目标系列和延迟信息，不会返回完整的系统提示词（如需查看，请使用 get_trace）。省略 day 可获取最近有数据的一天。

get_trace （1.2.0 新增）

按 ID 获取单次优化的完整追踪信息，包括确切的系统提示词、捆绑内容摘要和输出。

{ "id": "opt_xxx", "lookback_days": 7 }

save_outcome （1.2.0 新增）

告知 ClarifyPrompt 某次历史优化是 accepted、edited 还是 rejected。已接受的输出会成为同一会话中类似未来提示词的少样本示例。1.3 及更高版本还会将其用于持久化记忆层。IDE、Agent 或调用方应在用户对优化结果采取操作后调用此工具。

{
  "optimization_id": "opt_xxx",
  "session_id": "sess_yyy",
  "verdict": "accepted",
  "diff": "optional: the user's edited version or a patch"
}

list_categories

列出全部 7 个类别及其平台数量（内置和自定义）与默认值。

list_platforms

列出指定类别的可用平台，包括已注册的自定义平台。显示默认平台以及是否已配置自定义指令。

list_modes

列出全部 7 种输出模式及其说明。

register_platform

注册用于提示词优化的新自定义 AI 平台。

{
  "id": "my-llm",
  "category": "chat",
  "label": "My Custom LLM",
  "description": "Internal fine-tuned model",
  "syntax_hints": ["JSON mode", "max 2000 tokens"],
  "instructions": "Always use structured output format",
  "instructions_file": "my-llm.md"
}

参数	必填	说明
id	是	唯一 ID（小写字母、数字和连字符）
category	是	此平台所属的类别
label	是	易于理解的平台名称
description	是	简短说明
syntax_hints	否	平台专属语法提示
instructions	否	内联优化指令
instructions_file	否	包含详细指令的 .md 文件路径

update_platform

更新自定义平台，或为内置平台添加指令覆盖。

对于内置平台（例如 Midjourney、Claude），你可以添加自定义指令和额外的语法提示，而无需修改原始内容：

{
  "id": "midjourney",
  "category": "image",
  "instructions": "Always pin the current version (--v 8.2), prefer --style raw",
  "syntax_hints_append": ["--no plants", "--tile for patterns"]
}

对于自定义平台，可以更新所有字段。

unregister_platform

移除自定义平台，或清除内置平台的指令覆盖。

{
  "id": "my-llm",
  "category": "chat"
}

对于内置平台，使用 remove_override_only: true 可清除自定义指令，而不影响平台本身。

自定义平台与指令

ClarifyPrompt 支持注册自定义平台并提供优化指令，作用类似于 .cursorrules 或 CLAUDE.md 对 AI 行为的指导。

工作原理

1. 通过 register_platform 注册自定义平台
2. 以内联形式或 .md 文件提供指令
3. 针对自定义平台优化提示词——指令会注入优化流程

指令文件

可以将指令保存为 markdown 文件，并存放在 ~/.clarifyprompt/instructions/：

~/.clarifyprompt/
  config.json                    # custom platforms + overrides
  instructions/
    my-llm.md                   # instructions for custom platform
    midjourney-overrides.md     # extra instructions for built-in platform

指令文件示例（my-llm.md）：

# My Custom LLM Instructions

## Response Format
- Always output valid JSON
- Include a "reasoning" field before the answer

## Constraints
- Max 2000 tokens
- Temperature should be set low (0.1-0.3) for factual queries

## Style
- Be concise and technical
- Avoid filler phrases

覆盖内置平台

你可以使用 update_platform 为 61 个内置平台中的任意一个添加自定义指令。这样，你就能自定义 Midjourney、Claude 或 Veo 等平台的提示词优化方式，而无需修改默认设置。

配置目录

默认配置目录为 ~/.clarifyprompt/，可通过 CLARIFYPROMPT_CONFIG_DIR 环境变量更改。自定义平台和覆盖设置会在服务重启后保留。

知识包

知识包是一个可选用 YAML frontmatter 的 Markdown 文档，用于向 ClarifyPrompt 传授持久知识，例如品牌语调、编码规范、合规制度或特定领域的提示模式。知识包会在 H2 标题处分块、生成嵌入，并在此后每次调用 optimize_prompt / compose_prompt 时提供语义检索。Context Curator 会将知识包分块与工作区信号、指令文件和依据来源一同评分，然后将效用最高的内容放入目标模型剩余的 token 窗口。

随附的入门知识包

每个 npm 压缩包中都包含 packs/ 下的四个知识包：

知识包	内容
anthropic-brand-voice	Anthropic 面向公众的语调、语体和用词
higgsfield-creative-handbook	Higgsfield 模型选择、提示词结构、摄像机运动、Soul ID 工作流
nextjs-14-best-practices	服务器优先的 Next.js 14 App Router 规范
sox-compliance	AI 辅助财务工作的 Sarbanes-Oxley 404 防护规则

加载知识包

load_knowledge_pack({
  source: "https://raw.githubusercontent.com/LumabyteCo/clarifyprompt-mcp/main/packs/nextjs-14-best-practices.md",
  scope: "user"
})

也可以从本地加载：使用绝对路径，或相对于已安装的软件包指定路径：

load_knowledge_pack({ source: "/path/to/my-team-style-guide.md", scope: "project" })
load_knowledge_pack({ source: "./node_modules/clarifyprompt-mcp/packs/sox-compliance.md", scope: "session" })

作用域

• user — 保存在 $CLARIFYPROMPT_HOME 中，可供这台机器上的所有项目使用。
• project — 会持久保存，但仅限于当前工作树的身份范围（项目 ID 根据 cwd 和存在时的 git remote 派生）。
• session — 仅限当前 MCP 会话使用；服务重启后不会再检索到。

检索时会对这三种作用域的知识包一并评分；curator 会决定哪些分块能保留在 token 预算内。

编写与贡献

知识包编写规则（frontmatter 架构、分块边界指南、PR 合并所需的质量标准）见 packs/README.md。通过向此仓库提交 PR 贡献内容。除非 frontmatter 中采用双重许可，否则使用 Apache-2.0 许可。

为什么知识包放在引擎仓库中，而不是单独的注册表

简而言之：它们以前确实放在单独的注册表中。从 1.3 到 1.6.3，曾有一个独立的 LumabyteCo/clarifyprompt-packs 注册表。在 1.6.4 中，该注册表被归档，知识包重新整合到了 clarifyprompt-mcp/packs/，因为双仓库维护带来了成本，而外部贡献者群体却始终未能形成——higgsfield-creative-handbook 知识包在 1.6.2 发布，却从未进入注册表，就是这种脱节的典型例子。只有出现真正的推动因素时（社区 PR 队列、知识包数量超过 20 个、许可或治理分歧），拆分才有意义。在此之前，单仓库模式能让唯一事实来源保持单一且明确。

大模型配置

ClarifyPrompt 使用大模型来优化提示词。它兼容任何兼容 OpenAI 的 API，也可直接使用 Anthropic API。

环境变量

变量	必需	说明
LLM_API_URL	是	API 端点 URL
LLM_API_KEY	视情况而定	API 密钥（本地 Ollama 无需此项）
LLM_MODEL	是	模型名称/ID
LLM_TIMEOUT_MS	否	每次 LLM 请求的超时时间（毫秒）。默认值为 30000（30 秒）。大型本地模型需要调高此值——例如，50 GB 的 qwen3-next:80b 每次调用可能需要约 120 秒，超过默认值后会导致超时。对于大型本地模型，LLM_TIMEOUT_MS=180000 是一个安全值。
LLM_REASONING_EFFORT	否	（1.12.1+） 思考通道模型（gpt-oss、glm、*-thinking、deepseek-r、qwq）的推理级别：low | medium | high。默认值为 low。这些模型还会设置 max_tokens 下限，避免推理过程占用过多空间，导致最终答案无法生成（#3）。对非推理模型无效。
CLARIFYPROMPT_HOME	否	规范路径（1.2.0+），作为 ClarifyPrompt 所有写入内容的根目录，包括自定义平台、指令 .md 文件、追踪记录、记忆数据库和知识包。默认值：$XDG_DATA_HOME/clarifyprompt 或 ~/.clarifyprompt。
CLARIFYPROMPT_TRACE	否	off | local | otel。默认值为 local。追踪记录严格保存在本地 JSONL 文件中，不会上传任何内容。
EMBED_API_URL	否	（1.3.0+） 用于记忆和知识包检索的嵌入端点。可以是任何兼容 OpenAI 的 /v1/embeddings 端点。未设置时默认使用 LLM_API_URL——Ollama 用户无需额外配置即可使用。
EMBED_API_KEY	否	（1.3.0+） 嵌入 API 密钥。未设置时默认使用 LLM_API_KEY；本地 Ollama 无需此项。
EMBED_MODEL	否	（1.3.0+） 默认值：nomic-embed-text:v1.5（768 维，使用 ollama pull nomic-embed-text 拉取）。OpenAI 用户可换为 text-embedding-3-small，Voyage 用户可换为 voyage-3，Cohere 用户可换为 embed-english-v3.0。
EMBED_DIMENSION	否	（1.3.0+） 嵌入输出维度。默认值：768。必须与嵌入模型匹配（OpenAI text-embedding-3-small 为 1536，Voyage 为 1024，等等）。
SEARCH_PROVIDER	否	当 enrich_context: true 时可选的联网搜索增强提供方。可选值：tavily（默认）| brave | serper | serpapi | exa | searxng。
SEARCH_API_KEY	否	所配置的 SEARCH_PROVIDER 的 API 密钥。可自托管的 SearXNG 无需此项。
SEARCH_API_URL	否	搜索端点 URL。仅在使用可自托管的 SearXNG 时需要（指向你的实例）。
CLARIFYPROMPT_SUPPRESS_LEGACY_WARN	否	设为 1，可关闭使用 CLARIFYPROMPT_CONFIG_DIR / CLARIFYPROMPT_DATA_DIR 时显示的单行弃用提示。
CLARIFYPROMPT_CONFIG_DIR	否	旧版 CLARIFYPROMPT_HOME 的别名。仍可使用；将在 2.x 中移除。
CLARIFYPROMPT_DATA_DIR	否	旧版 CLARIFYPROMPT_HOME 的别名。仍可使用；将在 2.x 中移除。

Provider Examples

Ollama（本地，免费）：

LLM_API_URL=http://localhost:11434/v1
LLM_MODEL=qwen2.5:7b

Ollama — 通过本地转发使用云端模型（推荐）：

如果你的本地 Ollama 已登录 Ollama Cloud，任何 :cloud 模型都会通过它透明路由——使用相同的 URL，无需单独的 API 密钥。能力表会自动检测推理 / 思考变体（gpt-oss、kimi-k2-thinking、qwen3-thinking、deepseek-r1 等），并调高 maxTokens，让它们完成思考并实际生成内容。

LLM_API_URL=http://localhost:11434/v1
LLM_MODEL=gpt-oss:20b-cloud        # or kimi-k2.6:cloud, qwen3-next:80b-cloud, glm-4.6:cloud, etc.

Ollama — 直接使用云端端点（无需本地安装）：

LLM_API_URL=https://ollama.com/v1
LLM_API_KEY=your-ollama-cloud-key
LLM_MODEL=qwen2.5:7b

OpenAI：

LLM_API_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o

推理模型（gpt-5、o3、o4-mini）也可使用——客户端会自动处理它们对 max_completion_tokens 和 temperature 的要求。它们会进行大量思考，因此请调高 LLM_TIMEOUT_MS（例如 180000）；默认的 30s 通常太短。

Anthropic Claude：

LLM_API_URL=https://api.anthropic.com/v1
LLM_API_KEY=sk-ant-...
LLM_MODEL=claude-sonnet-5

Google Gemini：

LLM_API_URL=https://generativelanguage.googleapis.com/v1beta/openai
LLM_API_KEY=your-gemini-key
LLM_MODEL=gemini-flash-latest

使用你的密钥有权访问的模型——较旧的 ID（例如 gemini-2.0-flash、gemini-2.5-flash）在较新的密钥下会返回 404 "no longer available to new users"。gemini-flash-latest 会跟踪当前的 flash 模型。（注意：gemini-2.5-flash-image——“Nano Banana”——是图像模型；它不能用作 LLM_MODEL，因为该变量必须指定文本模型。应将它作为图像平台使用。）

Groq：

LLM_API_URL=https://api.groq.com/openai/v1
LLM_API_KEY=gsk_...
LLM_MODEL=llama-3.3-70b-versatile

DeepSeek：

LLM_API_URL=https://api.deepseek.com/v1
LLM_API_KEY=your-deepseek-key
LLM_MODEL=deepseek-chat

OpenRouter（任意模型）：

LLM_API_URL=https://openrouter.ai/api/v1
LLM_API_KEY=your-openrouter-key
LLM_MODEL=anthropic/claude-sonnet-4

请参阅 .env.example，了解完整的支持列表，其中包含 20 多家提供商，包括 Together AI、Fireworks、Mistral、xAI、Cohere、Perplexity、LM Studio、vLLM、LocalAI、Jan、GPT4All 等。

网页搜索（可选）

在 optimize_prompt 调用中设置 enrich_context: true，即可启用上下文增强。ClarifyPrompt 会在优化前搜索相关网页内容。

支持的搜索提供商：

提供商	变量	URL
Tavily（默认）	SEARCH_API_KEY	tavily.com
Brave Search	SEARCH_API_KEY	brave.com/search/api
Serper	SEARCH_API_KEY	serper.dev
SerpAPI	SEARCH_API_KEY	serpapi.com
Exa	SEARCH_API_KEY	exa.ai
SearXNG（可自托管）	—	github.com/searxng/searxng

SEARCH_PROVIDER=tavily
SEARCH_API_KEY=your-key

优化前后对比

图像（Midjourney）

Before: "a cat sitting on a windowsill"

After:  "a tabby cat sitting on a sunlit windowsill, warm golden hour
         lighting, shallow depth of field, dust particles in light beams,
         cozy interior background, shot on 35mm film, warm amber color
         palette --ar 16:9 --v 8.2 --style raw --q 2"

视频（Veo 3.1）

Before: "a timelapse of a city"

After:  "Cinematic timelapse of a sprawling metropolitan skyline
         transitioning from golden hour to blue hour to full night.
         Camera slowly dollies forward from an elevated vantage point.
         Light trails from traffic appear as the city illuminates.
         Clouds move rapidly overhead. Ambient city soundscape builds
         as the lights come on (native audio). Duration: 8s, extendable.
         Style: documentary cinematography, 4K, 16:9."

代码（Claude）

Before: "write a function to validate emails"

After:  "Write a TypeScript function `validateEmail(input: string): boolean`
         that validates email addresses against RFC 5322. Handle edge cases:
         quoted local parts, IP address domains, internationalized domain
         names. Return boolean, no exceptions. Include JSDoc with examples
         of valid and invalid inputs. No external dependencies."

音乐（Suno）

Before: "compose a chill lo-fi beat for studying"

After:  "Compose an instrumental chill lo-fi beat for studying.
         [Tempo: medium] [Genre: lo-fi] [Length: 2 minutes]"

上下文引擎（1.2.0）

每次优化都会经过五个集成处理阶段，让同一组上下文贯穿整个流程：

1. 分析 — 一次 analyzePrompt() 大模型调用会同时生成 category、intent 和 recommendedMode，避免三者彼此矛盾。意图与表面关键词冲突时，以意图为准（例如，"validate emails" → code，而非 document）。
2. 模式协调 — 用户显式指定的 mode 优先；否则采用分析器根据意图得出的建议；响应中的 modeSource 会告知你采用了哪种模式。
3. 提示词塑形 — 目标模型的能力信号决定 systemPromptBudget（小型本地模型使用精简版本，100K+ ctx 模型使用丰富版本）、maxTokens、temperature（感知意图）以及是否包含示例。
4. 意图叠加层 — 为每种意图添加简短叠加指令（production-code：要求错误处理和测试；data-extract：要求严格的架构；brand-voice：优先说明语气；等），并纳入策略的系统提示词。
5. 落地上下文 — 按优先级排列的单个区块，合并用户固定指令 → 项目规则 → 当前文件 → 会话少样本示例 → 网页搜索 → 工作区元数据 → 目标模型提示 → 自定义平台指令 → 内置语法提示。

收集的内容（ContextBundle）

• 项目 — 从 CLAUDE.md、AGENTS.md、.cursorrules、.clinerules、clarify.md、.clarify/rules.md 中选取第一个匹配的文件。package.json 及同级清单文件（pyproject.toml、Cargo.toml、go.mod、Gemfile、composer.json 等）用于检测框架和语言。
• 文件 — 可选的 file_path / file_language / file_excerpt 输入。
• 会话 — 环形缓冲区，保存每个会话最近的 20 次操作及其结果。已接受的输出会作为少样本示例检索，用于相似的后续提示词。
• 目标模型 — 执行改写的大模型，会与能力表进行匹配。
• 用户 — 区域设置、偏好模式、固定指令（最高优先级的依据）。

检查引擎看到的内容

使用 inspect_context 工具预览完整上下文包，而无需运行优化。其结构与设置 include_bundle: true 时 optimize_prompt 返回的内容相同。

扩展上下文

在项目根目录放置 AGENTS.md / clarify.md / CLAUDE.md。下一次优化时会自动读取。若要将已接受的输出用于后续改写，请在用户根据结果采取行动后调用 save_outcome。

追踪

$CLARIFYPROMPT_HOME/traces/YYYY-MM-DD.jsonl

每次优化都会写入一行 JSONL，记录 {id, ts, sessionId, category, platform, mode, input, bundleSummary, systemPrompt, output, model, strategy, latencyMs, shape, groundingSources, error}。使用 list_traces 查看摘要，使用 get_trace 查看完整记录。

隐私保护：

• 追踪记录严格保存在本地。不会向任何 ClarifyPrompt 自有基础设施发起出站网络调用。
• 仅会调用你配置的大模型端点（LLM_API_URL）和可选的搜索提供方（SEARCH_API_KEY）。
• 将 CLARIFYPROMPT_TRACE=off 设为可完全禁用追踪。
• 此版本不包含遥测。推出遥测选项时，该选项将采用选择加入方式、匿名，并会在构建版本包含它之前提供相关文档。

已知限制与路线图

内存持久化（已发布）

save_outcome + 少样本检索循环会将数据持久化到 $CLARIFYPROMPT_HOME 下的 SQLite + sqlite-vec 中，会话、优化、结果、事实和包块在重启后都会保留。内存环形缓冲区仅作为同一会话内的快速通道保留。会话范围内的条目以其会话 ID 为键，因此后续会话无法检索这些条目。

意图质量取决于运行分析器的模型

分析器与执行改写的模型使用同一个 LLM_MODEL。在集成测试套件中：

• Qwen 2.5 7B 和 14B → 对每个经过测试、格式良好的提示词均能正确判断。
• Llama 3.2 3B → 对含糊提示词偶尔会过度判断（例如将 "make it better" 标记为 brand-voice/high，而正确答案应为 unknown/low）。使用相同提示词时，较大的模型能正确返回 unknown/low。

建议：将 7B 及以上的本地模型（或任何前沿托管模型）用作 LLM_MODEL。对延迟敏感的调用方可设置 skip_intent_resolution: true，跳过分析器；引擎会回退到用户提示的类别和默认模式，因此会失去意图驱动的模式和叠加层，但保留依据和结构。随附的评估工具（evals/，npm run eval）提供了一组公开的测试样例，方便你根据自己的测试样例评估分析器，并检测模型或分类器变更带来的回归。

推荐模型

使用内置的矩阵运行器为模型打分：npm run matrix -- --models <a>,<b>,…。最近一次运行（2026-06，30 个测试用例，及格阈值 0.85，分数 = 测试用例平均分）：

模型	来源	套件分数	备注
glm-5.2:cloud	云端 · 推理	99%	综合排名第一。思考预算自动处理（1.12.1）。
gpt-oss:20b-cloud	云端 · 推理	98%	OpenAI 开放权重模型；reasoning_effort 自动应用（1.12.1）。
qwen2.5-coder:7b	本地	97%	小型本地模型就能应对几乎整个测试套件，是经过验证的本地优先默认选择。
gemma4:31b-cloud	云端	92%	均衡可靠的全能模型。

每次运行中未达标的少数测试用例，都是主观性较强的 analyzer-* 意图／模式分类和依据表述用例（内容因模型而异），而非流水线错误——确定性流水线测试用例（clarify、ground、critique、compose、memory、packs）在所有模型上都能通过。默认选择仍为本地优先（qwen2.5:7b）；如果希望获得更高的意图准确率，可以选用前沿／推理模型。推理模型（gpt-oss、glm、*-thinking 等）会自动调整（设置 max_tokens 下限 + reasoning_effort），避免返回空内容——请参阅 LLM_REASONING_EFFORT。

能力表并不完整

目前包含：Claude、GPT-4/o 系列、Gemini、Grok、DeepSeek（聊天 + 推理）、Qwen、Llama、Mistral/Codestral、Mixtral、Gemma、Phi、Cohere Command、Aya、Kimi、GLM、Minimax、GPT-OSS、Yi、Nemotron。未知模型会回退到 capabilities: {} 和 standard 提示词格式——仍然可用，只是不具备模型感知的尺寸调整功能。添加条目只需修改 src/engine/context/targetModelSignals.ts 中的数据。

推理／思维链模型

作为一类一等情况提供支持。引擎会在系列级别（o1/o3/o4、deepseek-reasoner、gpt-oss）和变体级别自动检测推理模型（ID 匹配 /\b(thinking|reasoner|reasoning)\b/ 或 /\br[12]\b/ 的模型：kimi-k2-thinking:cloud、qwen3-thinking:72b、qwen-r1-distill 等）。对于这些模型，maxTokens 会自动提升至 ≥ 8192，为模型留出思考并生成内容的空间。reasoning 字段不会作为优化后的提示词呈现——只会呈现 content。

架构

clarifyprompt-mcp/
  src/
    index.ts                           MCP server entry point (23 tools, 6 resources: 1 static + 4 templates + 1 ui panel)
    apps/                              MCP Apps compose panel (panel.html template + panel.ts, bundled at build time)
    engine/
      config/
        categories.ts                  CategoryConfig type + CATEGORIES const (loaded from YAML in 1.5.0)
        platformLoader.ts              (1.5.0) YAML pack loader — reads packs/platforms/*.yaml at boot
        paths.ts                       Unified $CLARIFYPROMPT_HOME resolver (1.2.0)
        persistence.ts                 ConfigStore — JSON config + .md file loading
        registry.ts                    PlatformRegistry — merges built-in + custom
      context/                         Context Engine (1.2.0)
        types.ts                       ContextBundle + signal types + AnalysisSignal
        projectSignals.ts              CLAUDE.md / AGENTS.md / .cursorrules / manifests scan
        fileSignals.ts                 Active-file path + language + excerpt
        sessionSignals.ts              In-memory per-session ring buffer + outcome retrieval
        targetModelSignals.ts          Model → capabilities mapping
        promptAnalyzer.ts              Unified analyzer: category + intent + recommendedMode
        gitSignals.ts                  (1.6.0) branch + HEAD + dirty + recent commits
        environmentSignals.ts          (1.6.0) nowIso + weekday + timezone
        bundle.ts                      Bundle orchestrator
      trace/                           Local tracing (1.2.0)
        types.ts                       TraceEntry schema (shape, groundingSources, error)
        writer.ts                      JSONL + OTel-stub writer, reader, lookup
      memory/                          Persistent memory + knowledge packs (1.3.0)
        store.ts                       SQLite + sqlite-vec; bi-temporal facts, outcomes, packs
        packs.ts                       Knowledge-pack loader (local / URL / inline)
        reflection.ts                  LLM fact extraction on save_outcome
      llm/client.ts                    Multi-provider LLM client (OpenAI + Anthropic)
      search/client.ts                 Web search (6 providers; results merge into Grounding Context)
      optimization/
        engine.ts                      Core orchestrator — analyzer, shape, grounding, retrieval, trace
        curator.ts                     Token-budget grounding curator (1.3.0)
        groundingContext.ts            Priority-ordered context assembly + mode/shape helpers
        types.ts                       OptimizationContext + result shape (UserProvidedSource)
        strategies/
          base.ts                      Bundle-aware base strategy (intent overlay + shape-aware sizing)
          chat.ts                      9 platforms
          image.ts                     12 platforms
          video.ts                     11 platforms
          voice.ts                     7 platforms
          music.ts                     4 platforms
          code.ts                      9 platforms
          document.ts                  8 platforms
      clarification/clarify.ts         (1.4.0) clarify_with_user — targeted questions w/ defaults
      grounding/ground.ts              (1.4.0) ground_prompt — strict caller-provided grounding
      critique/critique.ts             (1.4.0) critique_prompt — LLM-as-judge + optional rewrite
      composition/compose.ts           (1.4.0) compose_prompt — canonical clarify→ground/opt→critique pipeline
  evals/                                Eval harness v0 (1.3.0; setup: multi-call in 1.5.0)
    run.mjs                            YAML fixtures → MCP server → scored HTML report
    fixtures/*.yaml                    33 deterministic fixtures
    schema.json                        Fixture schema
  scripts/build-panel.mjs               (1.14.0) bundles the MCP Apps panel into dist/apps/
  packs/                                Knowledge packs + platform packs (single source of truth, 1.6.4+)
    README.md                          Pack authoring guide (frontmatter, chunks, quality bar)
    *.md                               Knowledge packs — 4 bundled, community-contributable via PR
    platforms/*.yaml                   (1.5.0) built-in AI platform declarations — 7 files, 58 platforms
  docs/adoption/                        (1.5.0) launch-post drafts + catalog submission specs

Docker

docker build -t clarifyprompt-mcp .
docker run -e LLM_API_URL=http://host.docker.internal:11434/v1 -e LLM_MODEL=qwen2.5:7b clarifyprompt-mcp

开发

git clone https://github.com/LumabyteCo/clarifyprompt-mcp.git
cd clarifyprompt-mcp
npm install
npm run build

使用 MCP Inspector 进行测试：

npx @modelcontextprotocol/inspector node dist/index.js

连接前，请在 Inspector 的“Environment Variables”部分设置环境变量。

测试与评估

命令	作用
npm run test:integration	第 1 天集成测试组（意图 + 依据 + 格式）
npm run test:day2	第 2 天记忆 + 策展 + 反思测试组
npm run test:reasoning	推理模型覆盖测试（思维链 maxTokens 提升）
npm run test:wire	MCP 线路冒烟测试（服务启动、工具列表、initialize 往返）
npm run test:all	按顺序运行全部四组测试
npm run eval	运行 20 个确定性评估测试用例 + 生成 evals/report.html
npm run eval -- --filter <name>	仅运行名称（或标签）匹配 <name> 的测试用例
npm run eval -- --quiet	仅输出退出码（适用于 CI）

评估框架详情、测试用例格式和多模型矩阵说明：evals/README.md。

CI / 质量门禁

该仓库提供了一个 GitHub Actions 工作流（.github/workflows/ci.yml），包含五个任务：

任务	运行时机	门禁检查内容
build	每次推送和 PR	在 Linux 和 macOS 上使用 Node 18/20/22 进行类型检查、构建和启动冒烟测试
secrets-audit	每次推送和 PR	使用 git-grep 检查已跟踪文件中是否存在已知的 API 密钥前缀
evals	每次推送和 PR（可选启用）	使用 gpt-4o-mini 运行 npm run eval。未设置 OPENAI_API_KEY 密钥时会跳过并报告成功；设置后，任何测试样例出现回归都会阻止发布
docker	每次推送和 PR	执行 docker build 和容器启动冒烟测试
publish	仅在推送标签时	当标签与 package.json#version 匹配时，运行 npm publish --provenance；须通过上述四个任务

要在你的分支中启用评测作为发布门禁：

1. 仓库 → Settings → Secrets and variables → Actions → New repository secret
2. 名称：OPENAI_API_KEY · 值：有权访问 gpt-4o-mini 的 OpenAI API 密钥
3. 推送代码或重新运行任意工作流

费用：每次 CI 运行约 $0.005（按 gpt-4o-mini 定价计算，17 个启用的测试样例 × 约 1500 个输入令牌 × 约 600 个输出令牌）。评测工具生成的 HTML 报告会作为构建产物上传（保留 30 天），因此无需在本地重新运行即可检查失败原因。

**要在推送标签时启用 npm 发布：**添加一个 NPM_TOKEN 密钥，其值为作用域限定于 clarifyprompt-mcp 的 Granular Access Token（启用 bypass-2FA）。设置步骤相同。

许可证

Apache-2.0