prompts

使用 LangWatch Prompts CLI 为提示词进行版本管理

确定范围

如果用户的请求较为宽泛（“设置提示词版本管理”“为我的提示词进行版本管理”）：

• 阅读完整代码库，查找所有硬编码的提示词字符串
• 研究 Git 历史记录，了解发生了哪些变化及其原因：重点关注 Agent 行为变化、提示词调整和错误修复。阅读提交消息以了解上下文。
• 设置 Prompts CLI，并为每个硬编码的提示词创建托管提示词
• 更新所有应用代码，以使用 langwatch.prompts.get()

如果用户的请求较为具体（“为这个提示词进行版本管理”“创建新的提示词版本”）：

• 专注于指定的提示词
• 创建或更新托管提示词
• 更新相关代码，以使用 langwatch.prompts.get()

在 Langy 中，不要打印供用户手动应用的代码更改：调用 code_access，并遵循 code-changes 技能，在用户的机器上或通过 GitHub 完成更改。

计划限制

LangWatch 免费计划对提示词、场景、评估器、实验和数据集设有数量限制。达到限制时，API 会返回 "Free plan limit of N reached..."，并附带升级链接。

处理方式：

• 在限制范围内操作。如果相关类型允许创建 3 个资源，就创建 3 个有意义的资源，而不是 10 个。
• 让每次创建都有价值：每个资源都应体现明确的用途。
• **先展示可用成果。**如果遇到限制，请总结已完成的工作，并说明升级计划可以提高限制。引导用户前往平台的订阅设置；如果 CLI 指向可自托管端点，则引导用户前往许可证设置。读取 CLI 实际使用的端点，该端点可能来自 .env、进程环境或已保存的 CLI 配置。
• 不要删除现有资源来腾出空间，也不要挪用现有资源以规避限制。

第 1 步：阅读 Prompts CLI 文档

使用 langwatch docs <path> 以 Markdown 格式阅读文档。以下是一些实用的入口：

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

使用 langwatch --help 和 langwatch <subcommand> --help 查找命令。列表和获取命令支持使用 --format json 输出机器可读结果。每个列表命令都支持 --limit <n> 限制行数，支持 --jq <expr> 读取部分结果。分页列表会返回一个封装对象，因此应通过行数组统计行数（--jq '.traces | length'），并通过 .pagination.total 查看总数。单独使用 --jq length 统计的是封装对象的字段数，而不是行数。请先阅读文档，不要猜测 SDK API 或 CLI 标志。

如果没有可用的 shell，可以通过普通 HTTP 获取相同的 Markdown。在任意文档路径后追加 .md（例如 https://langwatch.ai/docs/integration/python/guide.md）。索引：https://langwatch.ai/docs/llms.txt。场景索引：https://langwatch.ai/scenario/llms.txt

如果遵循此技能时遇到任何故障或疑惑（命令失效、文档与实际情况不符、需要绕过的错误），请征求用户许可，然后运行 npx --yes langwatch report --user-approved，并提供 --title 和 --summary（或 --session <transcript.jsonl>），将问题发送给 LangWatch 团队。这会直接影响后续修复内容。无需登录或 API 密钥。只有使用 --user-approved 才会发送内容；--dry-run 会打印准确的待发送内容，但不会发送。标题、摘要和转录记录会先在本地按模式进行脱敏：包括机密信息和 API 密钥，以及电子邮件地址、电话号码、卡号和公共 IPv4 地址。不符合任何模式的内容都会原样发送，包括通过 --email 传入的联系地址。使用 --session 时，务必先运行 --dry-run 并让用户查看待发送内容，因为转录记录可能包含用户从未审阅过的内容。npx --yes langwatch report --help 会说明相关选项。

项目和 API 密钥：目标应为真实项目，而不是个人项目。

LangWatch 有两种类型的项目：

• 团队 / 共享项目：组织内的真实项目。评估、实验、提示词、数据集、模拟和监控都必须始终以其中一个为目标。
• 个人项目：与单个用户关联的私有“我的工作区”临时空间。切勿将用户的评估、实验或生产追踪发送到这里：它仅用于个人探索，而且很容易被误认为是真实项目。

还有两种身份验证方式：

• .env 中的项目 API 密钥（LANGWATCH_API_KEY）：这些技能中所有操作使用的凭据。它的作用范围限定为一个真实项目。这是默认方式；除非用户明确要求其他方式，否则优先使用它。
• langwatch login --device（AI 工具 / SSO）：用于封装编码助手（langwatch claude、langwatch codex 等）的个人设备会话。它不适用于评估、提示词、数据集、场景或 SDK 监控，并且会指向个人工作区。请勿运行它来设置这些技能中的工作。

因此，对于这些技能中任何会读取或写入项目的操作，都要确保 CLI 可以使用真实共享项目的 LANGWATCH_API_KEY。在本地，该密钥位于项目的 .env 中；在 CI 中，运行器会将其注入进程环境，CLI 可从任一位置读取。询问新密钥前，先检查该变量是否已设置，并让 CLI 读取其值：绝不要打印、复制或发送它。不要运行 langwatch login 来选择项目，也绝不要默认使用个人项目。同时在相同位置查找 LANGWATCH_ENDPOINT：如果已设置，说明项目位于可自托管实例上，CLI 会针对该端点而非 app.langwatch.ai 执行操作。

你读取的内容不等于你要说的内容。 这些技能是供你使用的工作笔记，不是面向读者的文案。读取项目自身 .env 中的 LANGWATCH_API_KEY 和 LANGWATCH_ENDPOINT，以此了解应该在哪里工作。不要读取该文件中的其他内容：它包含与你无关的数据库、云服务和提供商凭据，而你读取的每个值都可能进入上下文和命令输出。回答中不得包含任何描述你运行所在机器的信息：工作区路径、容器端口、此工作器连接的地址。这些信息描述的是工作方式，而非工作成果；我们的主机对读者毫无意义。请说明你做了什么，以及可以在 LangWatch 中的哪里找到成果。

然后，具体阅读 Prompts CLI 指南：

langwatch docs prompt-management/cli

重要：不要猜测如何使用 Prompts CLI。先阅读文档。

步骤 2：在项目中初始化 Prompts

langwatch prompt init

这会在项目根目录中创建 prompts.json 配置文件和 prompts/ 目录。

步骤 3：为每个硬编码提示词创建托管提示词

扫描代码库，查找硬编码的提示词字符串（系统消息、指令）。针对每个字符串：

langwatch prompt create <name>

编辑生成的 .prompt.yaml 文件，使其与原始提示词内容一致。

**模型：**保留生成的 model，并使用当前模型。存储别名 openai/latest，不要存储版本号：LangWatch 会在运行时将其解析为当前旗舰模型，因此提示词不会在每次发布后迅速过时。不要默认将新提示词设为 gpt-4o-mini 这类旧模型；只有当用户有意牺牲质量来换取成本或延迟优势时，才选择这类模型。

**Temperature：**gpt-5 系列不接受自定义 temperature，因此不要为这些模型添加 modelParameters.temperature。create 会有意省略该参数。

**结构化输出：**如果提示词必须返回严格的 JSON，请添加 response_format 块，而不是在文字中要求返回 JSON：

response_format:
  name: product_category
  schema:
    type: object
    properties:
      category: { type: string }
      reasoning: { type: string }
    required: [category, reasoning]
    additionalProperties: false

response_format 可以通过 sync/pull 无损往返。完整格式请参阅 langwatch docs prompt-management/cli。

第 4 步：更新应用代码

将每个硬编码的提示词字符串替换为对 langwatch.prompts.get() 的调用。

Python（错误 → 正确）：

agent = Agent(instructions="You are a helpful assistant.")

import langwatch
prompt = langwatch.prompts.get("my-agent")
agent = Agent(instructions=prompt.compile().messages[0]["content"])

TypeScript（错误 → 正确）：

const systemPrompt = "You are a helpful assistant.";

const langwatch = new LangWatch();
const prompt = await langwatch.prompts.get("my-agent");

重要：不要在 try/catch 中包装 langwatch.prompts.get()，并添加硬编码的回退字符串。提示词版本管理的核心是由外部管理提示词。回退会悄悄恢复为过时的硬编码副本，从而破坏这一机制。

第 5 步：同步到平台

langwatch prompt sync

第 6 步：为部署标记版本

内置了 3 个标签：latest（自动分配）、production、staging。更新代码，按标签获取：

prompt = langwatch.prompts.get("my-agent", tag="production")

const prompt = await langwatch.prompts.get("my-agent", { tag: "production" });

通过 CLI（或 LangWatch UI 中的 Deploy 对话框）分配标签：

langwatch prompt tag assign my-agent production

对于金丝雀或蓝绿部署，可使用 langwatch prompt tag create 创建自定义标签。

第 7 步：验证

运行 langwatch prompt list 确认所有内容均已同步，或在 LangWatch 应用中打开 Prompts 部分。

常见错误

• 不要硬编码提示词。始终通过 langwatch.prompts.get() 获取
• 不要在 try/catch 中添加硬编码的回退字符串；这会悄悄破坏版本管理
• 不要手动编辑 prompts.json。请使用 CLI
• 创建提示词后，不要跳过 langwatch prompt sync
• 优先使用旗舰别名 openai/latest（快速档可使用 openai/latest-mini）。仅当提示词针对特定版本调优时才固定版本；仅在有意优化成本或延迟时，才选择 gpt-4o-mini 等较旧模型
• 不要在 gpt-5 系列模型上设置 modelParameters.temperature；该系列不支持此参数
• 如果输出必须为结构化格式，不要在提示词文本中要求 JSON。请使用 response_format 块