WeaveMark 是一个面向可复用提示词reusable prompts的规范语言最近在技术社区里被不少人拿出来讨论。它的核心不是替你把提示词写得更华丽而是把提示词当作工程产物来管理有输入、有约束、有输出定义、有测试样例。也就是说当项目里不再只有一两条提示词而是有几十上百条需要维护的提示词时WeaveMark 提供了一种更接近代码管理的组织方式。如果你正在做 LLM 应用开发、提示词工程或者需要在项目里批量维护不同场景的 Prompt这篇文章值得看完。我会按实际落地的顺序拆它解决什么问题、一份可复用提示词需要哪些组成、怎么写一个最小示例、怎么从单条扩展成提示词库以及有哪些容易踩的坑。1. 先搞明白WeaveMark 到底管的是 Prompt 的哪一部分接触可复用提示词的人大多都经历过这几个阶段。第一版提示词写在一段字符串拼接里等新增场景后开始复制粘贴再等模型升级或提示词调整要改七八处最后是测试很难做回归基本靠感觉。WeaveMark 的位置就出现在这个阶段它把提示词从字符串升级成规格文件。它不负责决定你选哪个模型也不负责调用大模型 API。它更像是提示词层的 schema或者说是一种 DSL。你写一份类似 YAML、JSON 或自定义语法的文件里面声明这个提示词的输入、指令、约束、输出格式和测试样例然后由解析器把这份文件翻译成真正发给模型的 Prompt。1.1 普通模板字符串和提示词规格文件的差异很多项目里常见的做法是这样def build_prompt(user_content): return f 你是资深编辑请处理用户内容 {user_content} 要求输出中文不超过200字。 这种写法的问题不是不能跑而是当内容变复杂后很难维护。比如用户内容可能来自不同渠道有的需要带上业务背景有的需要限制输出为 JSON有的还要区分语气。于是你就会开始写第二个模板、第三个模板然后不可避免地出现复制粘贴。WeaveMark 想改变的是这一层不再把 Prompt 当成一个字符串函数而是当成一份带声明的规格文件。输入字段会被显式列出来指令和约束会被分开输出格式会被独立定义测试样例可以和提示词放在一起。这样一旦某个行为变更你可以清楚看到影响范围。对比维度普通模板字符串WeaveMark 这类规格文件维护单位一串拼接文本结构化文件参数管理靠命名约定显式声明类型、必填和默认值输出控制写在提示词里独立定义并支持校验版本管理靠文件名或注释文件内版本字段复用方式复制粘贴引用、组合、生成可测试性手工检查测试样例 回归检查这里不是说普通模板完全不能用。你只有一两处固定 Prompt用字符串拼接完全够。问题出现在“可复用”三个字出现之后复用意味着有多个调用方、多个版本、多种输入组合这时候字符串就不够用了。1.2 适合哪些人和项目如果只看形式WeaveMark 像一套配置文件但它更适合有工程化诉求的团队和项目。适合这样几个场景项目里有多个业务场景每个场景都有自己的用户提示词。提示词需要被前端、后端、批处理任务多个地方引用。团队需要更新一个 Prompt又不希望所有调用方都跟着改。需要验证“提示词改完之后输出是不是还稳定”。需要给不同模型、不同环境准备不同的 Prompt 版本但不想维护一堆散落字符串。反过来一次性的问答、实验性脚本、只写给自己临时用的 Prompt都暂时不需要上这种东西。这是边界不是缺点。很多人一看到 DSL 就觉得要全面铺开实际最稳妥的做法是先从重复出现最多的场景开始。2. 一份可复用 Prompt 应该包含哪些“规格”要理解 WeaveMark关键是先理解“规格”两个字。一份可复用的 Prompt 不应该只是提示词原文它至少应该有四个部分输入声明、指令、约束、输出定义。条件允许的话还应该有测试样例。2.1 输入声明别让变量藏在字符串里普通模板里的变量是隐式的。你写{user_content}阅读代码的人只能猜这个变量从哪里来、是什么类型、会不会为空。更麻烦的是如果调用方漏传字段f-string 直接报错如果传了错误类型模型可能基于错误的输入继续生成。规格文件的第一步就是把输入说清楚。比如哪些字段是必填的。哪些字段有默认值。字段是字符串、数字还是结构化的文本。字段长度或者格式有没有限制。有了显式输入声明之后解析器可以在调用模型之前做校验。字段缺失直接报错而不是让模型在信息不完整的情况下硬生成。这个动作虽然简单却省掉了很多调试时间。2.2 指令与约束分离很多人写提示词会把“要做什么”和“不要做什么”混在一起。结果就是模型对主要任务的理解变弱约束也容易被淹没。WeaveMark 这类规范语言通常会把两者分开指令模型应该完成的行为比如“分析这段代码的性能问题”。约束模型不应该做的事情比如“不要编造代码中不存在的函数”。分开之后收益很明显。当你发现模型开始编造内容你只需要调整约束块不需要重写整段提示词。当你想给某个场景增加新要求也只需要在指令块里增加一条而不是重新排布整个 Prompt。2.3 输出定义先定格式再让模型填内容可复用提示词最容易忽略的是输出格式。很多人把输出格式写在最后一句“请输出 JSON。”但如果你没有告诉模型 JSON 里有哪些字段、字段类型是什么、遇到没有数据时怎么处理模型还是会给出一堆不稳定结构。一份成熟的 Prompt 规格应该包含输出定义。常见做法是指定输出格式比如 markdown、JSON、纯文本。指定输出结构比如章节顺序、字段名、字段类型。指定长度或数量限制比如最多 5 条建议。指定异常情况比如无相关内容时输出什么。输出定义的好处是调用方不用再对模型结果做大量解析和猜逻辑。你甚至可以基于输出定义做校验发现结构不对就直接重试或报错。2.4 测试样例和验收标准这是规范语言和普通模板最本质的区别。普通模板只需要“能生成文本”而一份 Prompt 规格还需要满足测试样例。测试样例通常包含一组输入和期望结果。期望结果不一定要求模型输出完全相等但可以检查输出是否包含某些关键字段。输出是否不包含某些关键词。输出是否满足格式要求。输出长度是否在可控范围内。输出是否因输入变化而出现了明显不相关的内容。有了测试样例就可以在改 Prompt 之后跑一遍回归。比如原来指令要求输出中文某次升级改成英文测试样例就会立刻暴露这个问题。这个能力小项目用不上但团队协作时非常关键。3. 用类 WeaveMark 语法写一个最小可运行示例下面我写一个“代码审查助手”的示例。这里要说明一下下面的结构是演示用不是 WeaveMark 官方语法文档。不同项目的 DSL 细节会有差别但设计思路是通用的。你落地时一定要以你选择的解析器或项目文档为准。3.1 示例条件和目标假设我们要复用一个代码审查 Prompt。它需要接收两个输入代码语言和代码变更内容。目标是让模型输出一份结构化审查意见包含变更概要和问题列表。这个场景非常适合先试水因为代码审查在团队里使用频率高、输入输出相对固定、测试也容易写。3.2 一个类 WeaveMark 示例文件prompt: id: code_reviewer name: 代码审查助手 version: 1.2.0 inputs: language: type: string required: true description: 代码语言例如 python diff: type: text required: true description: 代码变更内容 system: | 你是一名资深代码审查员。请基于给定的代码变更进行审查。 instructions: - 先用一句话概括这次变更的意图。 - 分别从安全性、性能、可维护性三个维度列出问题。 - 每个问题给出建议修复方式。 constraints: - 只讨论提供的 diff 中出现的内容。 - 不要编造不存在的文件路径或函数。 - 如果某个维度没有问题直接写“无”不要强行扩展。 output: format: markdown sections: - summary - issues tests: - name: 正常审查 input: language: python diff: def add(a, b): return a b expect: output_has: - 可维护性 output_not_has: - 记忆这个例子看起来比 f-string 复杂但它的价值在于每个部分都可以独立修改。3.3 核心字段说明字段作用判断标准id / name标识这个 Prompt团队内唯一version版本号输出格式变化时升版本inputs声明输入字段必填项缺失时能报错system系统角色说明模型处于什么身份instructions模型要完成的任务每条指令可执行、可检查constraints模型不能做的事用否定语尽量具体output输出结构和格式调用方能按这个结构解析tests回归样例改 Prompt 后可以自动验证这里有一个容易被忽略的点不要把 instructions 写得太多。指令多的 Prompt 看起来覆盖全面实际上模型可能记不住最后几条。我的经验是核心指令保持在 5 条以内约束单独放输出结构用独立字段声明。3.4 从规格文件到最终 Prompt 的使用流程实际使用时流程大致是读取规格文件。校验输入字段是否完整。把输入渲染到 system、instructions 或对应上下文位置。按照 output 定义拼接最终的 Prompt。调用大模型 API。根据 output 定义校验返回结果。跑测试样例记录是否通过。这个流程可以直接写成一个函数也可以封成 CLI 工具。重点是调用方不需要关心 Prompt 内部怎么写它只负责传入 inputs然后拿到符合 output 定义的结果。我第一次跑这种流程的时候最明显的感受是改提示词不再像“改完然后祈祷”而是变成一次可视化变更。输出不对先看测试样例再做针对性修改。4. 从单条提示词到提示词库版本、组合、批量维护单条 Prompt 格式化只是第一步。WeaveMark 真正要解决的是提示词库的维护问题。4.1 版本管理改一个文件而不是改所有调用方普通字符串模板最痛苦的地方在于如果你改了指令所有复制过这段模板的调用方都不会同步。你可能在代码里搜fragment找到几十处然后手工替换改完还不知道有没有遗漏。规格文件的做法是把 Prompt 抽成一个独立文件。调用方通过 id 或命令行引用它而不是复制内容。这样当你修改 Prompt 时只需要改一个文件。调用方拿到的结果是新的但代码结构不需要变动。版本号在这种场景下很有用。如果只是调整措辞可以升小版本。如果改了输出格式调用方解析逻辑可能要做兼容这时候应该当成破坏性变更来处理明确通知相关方。4.2 组合把基础角色和业务任务拼起来很多 Prompt 有公共部分。比如所有审查类 Prompt 都需要“你是资深技术专家”这个角色而不同业务场景需要不同的审查维度。如果每个文件都重复写一遍依然会出现同步问题。比较好的做法是支持块级组合。你可以抽一个基础角色块然后让具体业务 Prompt 引用它。组合思路很像代码里的私有函数和公共函数重复出现的内容下沉变化的内容留在上层。需要提醒的是组合层级不要太深。两层通常已经足够比如基础角色层 业务任务层。如果继续嵌套Prompt 最终渲染出来的内容会很难排查因为你不知道某句话来自哪个文件。4.3 批量与多环境复用提示词库一旦多起来就需要考虑批量维护。多模型环境同一个 Prompt 可能需要适配不同模型的输出风格。多语言环境产品面向多语言用户时提示词可能需要按语言区分。多版本环境灰度阶段可能旧版新版同时存在。规格文件的好处是环境差异可以被参数化。语言、模型、输出长度、语气这些字段可以从 Prompt 正文里抽出来变成输入或配置项。这样你不需要为每个环境复制一整份 Prompt只需要在调用时传入不同参数。批量维护时还要注意输出目录和日志。如果一次生成几十条 Prompt最好把每次渲染后的最终文本和输入参数一起记录下来否则出了问题很难定位是哪个字段导致的。5. 落地时的判断标准和排查方法任何抽象都会引入复杂度WeaveMark 也一样。它能不能在项目里活下去取决于你能不能建立清晰的判断标准和排查链路。5.1 怎么判断一套 Prompt 规格写得好不好我会用下面几个问题来判断是否只改规格文件调用方代码不用变新增一个输入字段时是否需要动 Prompt 正文多处地方输出格式是否由独立字段定义而不是靠模型自动发挥每个 Prompt 是否有至少一条测试样例新成员看文件是否能在 5 分钟内理解这个 Prompt 的输入、输出和约束切换到另一个模型时是只需要调整配置还是需要重写 Prompt如果这些问题里有一大半答不上来说明规格文件只是换了一层皮并没有真正建立可复用能力。5.2 输出异常时按什么顺序排查遇到提示词改完后输出不对先不要急着调模型参数按下面的顺序查先看最终渲染出来的 Prompt。很多时候你以为传给模型的是规格文件里的原样实际可能是变量没有替换成功。再看输入字段。看看是不是某个字段为空或者字段内容超出了预期长度。再看输出定义。模型不听话时优先检查输出结构是否写得太靠后或者被其他指令淹没。再看约束。约束和指令如果相互冲突模型会优先满足更靠后的指令。最后看测试样例。如果样例里的输入和当前任务相差太大测试结果没有参考价值。另外一个常见问题是长文本输入。输入越长模型越容易丢失中间段信息。如果你发现新增上下文后输出变差先检查是不是 Prompt 过长而不是修改措辞。5.3 什么时候不要硬上这套东西我想强调一个边界没有多少 Prompt 的时候不要立刻引入规范语言。如果你只是写一个临时脚本或者只有两三条固定提示词用 f-string 反而更直观。这个时候硬上 DSL只会增加阅读成本和调试成本。只有当下面情况出现时再考虑提示词数量开始超过代码维护能力。同一个 Prompt 被多个地方引用。团队需要对 Prompt 做版本审查。输出格式经常变化导致调用方频繁改代码。还有一点如果团队没有版本控制或评审习惯规范语言的价值会打折扣。它本质上是一种团队协作工具而不是个人快捷键。6. 我建议的落地节奏如果你看完之后想在项目里用 WeaveMark我建议不要一开始就迁移所有 Prompt而是从最小范围开始。6.1 先拿一个重复频次最高的场景试水选一个最常出现的业务场景比如代码审查、内容总结、客服回复或者电商文案生成。只把这个场景做成规格文件写清楚 inputs、instructions、constraints、output 和 tests。先跑通单条任务确认渲染后的 Prompt 符合预期。然后跑测试样例看看模型输出是否稳定。稳定之后再把调用方从原来的字符串函数切换到规格文件。这一步的目的是验证“引入 WeaveMark 之后工作流是否真的变得更清晰”。如果连最核心的场景都没有变好那其他场景也不要迁移。6.2 把规格文件接入版本管理和自动校验当核心场景跑通后再把规范和 CI 流程连起来。每次修改 Prompt 不再是直接改代码或线上配置而是提交一个规格文件变更。跑一遍相关测试样例。检查输出变化是否在预期内。确认后再合入。这一步比任何文档都重要。因为 Prompt 的可复用不是“写一次用很多次”而是“每次改动都能被追溯、被验证”。只有做到这一点Prompt 才能算真正进入工程化管理。我个人更倾向于把 WeaveMark 这类东西看成“提示词工程里的结构化契约”。它的价值不在于语法有多强大而在于它逼你把“模型要做什么、不能做什么、输出什么、怎么验收”这些问题提前想清楚。很多提示词问题表面上是模型不听话实际是需求没有说清或者输入输出没有定义好。如果你正在被大量重复提示词困扰可以先不用关心完整语法而是把当前最痛的那条 Prompt 抽出来按输入、指令、约束、输出、测试这五个维度重新整理一遍。做完这一步你就会发现自己需要的是什么。