v0.dev 完全指南
LLM 应用最容易被低估的资产是提示词。它们常以字符串形式散落在 TypeScript 服务、Python notebook 和配置文件中。起初这很方便；但一旦提示词的变量名、消息结构或 JSON 输出被业务逻辑依赖，它就已经是接口契约。一次看似无害的修改，可能让生产环境收到缺字段、格式改变或无法解析的输出。Git 能记录模板文本，却不能直接回答“这个服务构建时究竟解析到了哪个版本”。
Sufleur 把提示词处理成类似包依赖的对象。团队在平台中编写、版本化并发布提示词；项目通过 CLI 声明要使用的名称和版本范围；CLI 解析依赖、写入锁文件，并生成 TypeScript 或 Python 的本地调用代码。运行时不需要向 Sufleur 拉取模板：生成文件已经内联内容。因此它属于构建阶段的提示词供应链，而不是放在模型调用路径上的代理。
把草稿与已发布版本分开
在 Sufleur 中，提示词可用稳定的命名空间名称引用，例如 @team/code-review。真正不可变的是已发布的语义化版本，例如 1.2.0。团队可以继续编辑草稿中的模板文件、输出 Schema 和模型配置，但已发布版本不能原地改写；下一次变更需要创建新版本。
这个规则解决了提示词协作中最麻烦的一类问题：开发人员在网页端优化语气时，不应立即改变所有应用的行为。项目的 sufleur-lock.yaml 记录解析后的版本与哈希。即使清单允许 ^1.0.0，新版本也不会无声进入构建产物；团队必须显式更新锁文件，并把变化作为一次可审查的提交。
对提示词而言，语义化版本不是装饰。把输入变量 diff 改为 patch、删除一个可渲染入口点，或把输出字段从字符串换成对象，都可能破坏调用方，应作为 major 变更。只调整不影响输入输出形状的说明，才更适合兼容版本；即便如此，兼容的 Schema 也不保证模型输出的行为分布不变，关键流程仍应先在测试或灰度环境验证。
接入一个公开提示词
公开提示词不要求 API key。Sufleur 的 README 给出了如下流程，示例使用其公开的 @sufleur/ticket-triage：
npm i -g @sufleur/cli sufleur init sufleur add @sufleur/ticket-triage sufleur generate npm i mustache zod
init 创建 sufleur.yaml，add 解析和获取提示词并更新锁文件，generate 依据锁文件产生 TypeScript 或 Python 文件。npm registry 当前标记的 @sufleur/cli 版本为 0.6.0，包声明 Node.js 16 及以上；生成的 TypeScript 运行时依赖 mustache，有输出 Schema 的提示词还需要 zod。
项目清单可以固定生成位置并声明版本范围：
prompts: "@team/code-review": "^1.0.0" output: language: typescript file: ./generated/prompts.ts
私有工作区的 API key 可通过环境变量引用，不能直接写入清单。应至少提交 sufleur.yaml 和 sufleur-lock.yaml：前者是意图，后者是实际解析结果。没有锁文件，排查线上提示词行为时又会退回到“本地似乎能复现”的猜测。
在应用中获得明确的输入输出边界
生成后，业务代码导入本地模块，而不是再拼接自由文本：
import { getPrompt } from './generated/prompts';
const review = getPrompt('@team/code-review');
const { prompt } = review.render('userPrompt', {
diff: patchText,
language: 'typescript',
});
const raw = await callModel(prompt);
const parsed = review.parseOutput(raw);
if (!parsed.success) throw new Error(String(parsed.error));
console.log(parsed.data);
render() 的入口点和输入字段来自模板推导的 Schema，让 IDE 能发现调用错误。若版本声明了输出 Schema，生成的 parseOutput() 会清理代码围栏、解析 JSON，并用生成的 Zod Schema 校验。它不能保证模型回答的事实正确，却能把“下游某处 JSON 解析崩溃”前移成明确的契约失败；调用方仍需有重试、降级或人工处理策略。
用冻结安装把变更挡在 CI 之前
本地开发在计划升级时执行 sufleur update；CI 应验证锁文件，而非擅自更新它：
sufleur install --frozen sufleur generate npm test
--frozen 会在清单与锁文件不一致时失败，类似锁定安装。它避免开发人员改了范围却遗漏锁文件更新，也使部署可复现。建议把提示词升级视为依赖升级 PR：审查锁文件差异、重新生成代码，并运行覆盖正常输出、缺字段、额外字段和非 JSON 响应的契约测试。Sufleur 的 eval 与数据集能力可用于评测，但评测通过不能替代应用侧的边界测试。
失败模式：不要把锁文件当成唯一安全网
锁文件解决的是“使用哪一版模板”，而不是“这一版模板是否适合当前业务”。实践中至少有四类失败模式仍要单独处理。
第一类是输出契约过宽。若 Schema 只要求一个任意字符串字段，模型即使遗漏关键风险等级也可能通过校验。应让 Schema 表达下游真正需要的最小边界，例如枚举、必填字段和对象层级；但也不要为了限制模型而制造根本无法满足的超复杂 Schema。第二类是模板和调用代码的升级顺序不一致。某个服务升级 lockfile 后，另一个消费者还停留在旧版，跨服务传递的 JSON 可能出现形状差异。可为对外事件定义稳定的应用 DTO，把提示词输出先转换到 DTO，再交给消息队列或数据库。
第三类是把 parseOutput() 当成内容审核。它只能验证数据是否符合定义的形状，不能验证“高风险”判断是否准确、引用是否真实或模型是否受到了上下文注入影响。对高影响自动化，应把解析成功与业务批准分开：先记录原始输出、提示词版本和解析结果，再由规则、人工审批或独立验证器决定是否执行动作。第四类是开发者只提交了生成文件，却遗漏清单或锁文件。生成文件方便阅读，却不是可靠的解析来源；CI 应从清单和锁文件重新生成，并在生成后检查工作区无差异。
一套可操作的发布约定
工具本身不能替团队制定版本规则，因此建议先写下简单约定。每个提示词名称对应一个明确业务动作，例如 @team/code-review 或 @team/ticket-triage；不要把互不相关的任务塞进同一模板，再靠大量条件分支区分。每次发布都记录输入变量、入口点、输出 Schema、模型建议和评测用例的变化。模板本身采用 Mustache，公共片段可以作为 partial 复用；直接可调用的文件则作为 entrypoint。这样既减少重复指令，也不会把“能被应用渲染”和“只是被其他模板包含”混为一谈。
升级时可以遵循一个小闭环：创建草稿并调整模板；用代表性案例验证渲染结果；发布新版本；在测试项目执行 sufleur update、检查锁文件；重新生成并跑契约测试；最后才让生产项目提高版本范围。发现问题时，消费端可回退到已知的锁文件提交，而不必在生产环境临时编辑 prompt。对于公开提示词，还应假定模板会被不同团队以未知方式使用，发布重大变化前提供迁移说明比“悄悄修正”更可靠。
与常见替代方案的取舍
把提示词存在 Git 仓库是合理的起点，尤其适合单一服务、单一语言和低频变更。它的优点是没有额外平台，缺点是跨仓库复用、版本解析和运行时类型接口需自行实现。数据库或远程配置适合需要即时开关与实验分流的场景，但要额外处理缓存、回滚、审计和线上可用性。Sufleur 的取舍在于偏向可复现构建：它把模板在构建时固定下来，降低远程读取的运行风险；代价是想让变更生效必须走一次依赖升级与部署。
因此，不要将它用于需要秒级切换的应急文案；也不要因为引入了版本工具就放弃日志、评测和权限控制。它更适合把已进入工程化生命周期的提示词，从“代码里的一段文本”提升为可被依赖、验证与审查的构件。
适用边界
只有一两个稳定的实验性模板时，普通模块常量已经够用。多个服务复用提示词、输出要进入自动化业务流程、团队需要公开共享，或曾因改 prompt 导致解析失败时，版本、锁定和代码生成会明显降低风险。它并不管理模型调用、密钥、重试、观测或内容安全；这些仍属于应用职责。
最小迁移不必一次覆盖所有模板：先为一个结构化输出提示词建立命名与发布规则，让一个服务通过锁文件接入，再把 --frozen 放进 CI。目标不是增加一个提示词编辑器，而是形成可审查、可复现且能回滚的提示词交付链路。