团队内部 · Prompt 协作 · MCP

用 Claude Code 控制 Langfuse

在你自己的 Mac 上跑 Claude Code，直接对话操作 Akke 线上 prompt：查看、改稿、发新 version、灰度、回滚——不用 clone Akke 仓库，也不用 dashboard 点点点。

更新于 2026-05-09 路径：Claude Code + Langfuse 官方 MCP 预计 15 分钟接入

📌

这是给谁看的？ 已经被加进 Akke Langfuse 项目（akke-prod）、要直接编辑线上 prompt 的同事（PM / 文案运营）。读完后你能在自己 Mac 的 Claude Code 里说「列出 prompt」「把这段存为新 version」「转 production 标签」，全程自然语言对话。

读完前请准备：一台已装好 Claude Code 的 Mac（claude --version 能输出版本号即可）、Langfuse 邀请邮件已接受能登录 jp.cloud.langfuse.com。

🤖

为什么要用 MCP 而不只在 dashboard 改？ dashboard 改 prompt 是手动复制粘贴；MCP 让 Claude Code 直接调 Langfuse API，你能用一句中文完成「拉旧版 + 改三处 + 存新版 + 打 staging + 跑两条样本验证 + 转 production」全链路。最大的好处是协作留痕——每次改稿都有 Claude Code 会话作为上下文，比聊天里干说"我改了 A 和 B"清晰得多。

📖 目录

① 这条链路在干什么 ② 一次性接入（5 步约 15 分钟） ③ 5 个可用工具 ④ 日常 SOP（改一次 prompt 的标准动作） ⑤ 常用对话模板（直接复制） ⑥ 故障排查 ⑦ 红线 · 不要踩 ⑧ 一页速查卡

1这条链路在干什么

Akke 的 LLM 调用（评论意向分析、DM 文案、反向钩评）都通过一个叫 Langfuse 的 SaaS 做两件事：

Observability：每条 LLM 调用都被记录成 trace，包括输入、输出、耗时、成本，dashboard 可查
Prompt 管理：把 prompt 文案从代码里抽出来托管，PM 改稿不用工程师改代码、不用重新部署

本文档只讲第二件事 —— 你怎么用 Claude Code 操作 prompt。

你在 Claude Code 说「列出所有 prompt」
   ↓
Claude Code 调用 mcp__langfuse__listPrompts 工具
   ↓
工具向 jp.cloud.langfuse.com/api/public/mcp 发请求（带你的 BasicAuth）
   ↓
Langfuse 返回 prompt 列表
   ↓
Claude Code 把结果翻译成中文回你

————————————————————————

你在 dashboard 看到的 prompt v3
        =
Akke 代码里实际命中的 prompt v3
        =
Claude Code 通过 MCP 拿到的 prompt v3
（同一份数据的三种界面）

关键认知：

Prompt 是带版本的：每次保存生成新 version（v1 → v2 → v3...），老版本永不删，回滚只是把 production 这个标签转过去
Akke 代码 fetch 的是带 production 标签的版本，不是最新版本
30 秒缓存：你转完 production 标签后，生产环境最多 30 秒内全部命中新 prompt，不需要任何代码部署
有 fallback 兜底：即使 Langfuse 整个挂了，Akke 代码里还存着 prompt 的硬编码副本，业务不会因 Langfuse 故障停摆

2一次性接入

STEP 1

登录 Langfuse 拿你自己的 API Key

打开 https://jp.cloud.langfuse.com（注意是 jp. 子域，日本机房），左上角切到 akke-prod 项目。

然后 Settings（齿轮图标）→ API Keys → Create new API keys，会弹出一对：

Public Key:  pk-lf-xxxxxxxx
Secret Key:  sk-lf-xxxxxxxx   ← 只显示一次，立刻复制存到 1Password

🚫

不要找 Owner 要他的 key 共用。你建你自己的，操作日志才能追到具体是谁干的；事故复盘也好定位。

STEP 2

把两段 key 拼成 BasicAuth token（base64）

在 Mac 终端跑（把两个 pk-lf-xxx / sk-lf-xxx 替换成你自己的）：

echo -n "pk-lf-xxx:sk-lf-xxx" | base64

会输出一串字符如 cGstbGYteHh4OnNrLWxmLXh4eA==，这就是 BasicAuth token，下一步要用。

💡

为什么是 base64？HTTP BasicAuth 标准要求把 用户名:密码 用 base64 编码后塞进 Authorization 头。这不是加密，只是编码——所以这串字符仍然要严格保密，等价于明文 key。

STEP 3

一行命令注册 MCP 到 Claude Code

在 Mac 终端跑（把 YOUR_BASE64_TOKEN 换成上一步的输出）：

claude mcp add --transport http langfuse https://jp.cloud.langfuse.com/api/public/mcp \
  --header "Authorization: Basic YOUR_BASE64_TOKEN"

成功的话会输出类似 Added MCP server "langfuse"。

⚠️

必须是 jp.cloud.langfuse.com。Langfuse 有三个区独立部署，写错会全 401：

EU: cloud.langfuse.com ❌ 不是 Akke 用的
US: us.cloud.langfuse.com ❌ 不是 Akke 用的
Japan: jp.cloud.langfuse.com ✅ Akke 在这

STEP 4

验证装上了

开一个新的 Claude Code 会话（任意目录都行，不需要 cd 到 Akke 仓库），输入：

列一下 Langfuse 里现有的 prompt 和它们的最新 version

预期 Claude Code 会调用 mcp__langfuse__listPrompts 工具，返回至少这一条：

comment.reverse-comment-system（v1，标签 production）

如果看到了 prompt 列表 = 接入成功，可以开始日常使用。如果报错看第 ⑥ 章故障排查。

STEP 5

（可选）确认你在 dashboard 也有相应权限

MCP 用的 API key 决定了你能改什么：

Project-level OWNER / ADMIN / MEMBER ：能 create/update prompt + 打 label（包括 production），这是日常协作所需的最低权限
Project-level VIEWER：只读，create/update 会 403

如果你 dashboard 显示是 VIEWER，去找现任 Owner 改成 MEMBER 即可。

35 个可用工具

Langfuse 官方 MCP server 当前只暴露 5 个 prompt 相关工具，scope 故意做窄了避免误删生产数据。

工具名	用途	触发关键词举例
`listPrompts`	列出项目所有 prompt + 最新 version + 标签	"列出/有哪些/盘点 prompt"
`getPrompt`	拿某个 prompt 的具体内容（指定 version 或标签）	"把 X 当前 production 拉出来给我看"
`createTextPrompt`	新建文本类 prompt，或为已存在的 prompt 创建新 version	"把这段存为 X 的新 version"
`createChatPrompt`	同上，但是多轮对话格式（system + user + assistant 数组）	"把这套对话样本存为 X 的新 version"
`updatePromptLabels`	把标签（如 `production` / `staging`）转移到指定 version	"把 production 转到 v3"、"回滚到 v2"

💡

没有"删除 prompt"工具是好事。真要删只能去 dashboard 手动删，多一道关卡防止把生产配置误删。版本永远是单调递增的（v1 → v2 → v3...），删除一个 prompt 也不会回收 version 编号。

4日常 SOP

下面这 6 步是改一次 prompt 的标准动作，每一步都直接对 Claude Code 说中文，不需要写代码。

SOP 1

拉当前 production 版本

对 Claude Code 说：

把 comment.reverse-comment-system 当前 production version 的内容拉出来给我看

Claude Code 会调 getPrompt，把全文 + 占位符 + 当前 version 号贴出来。

SOP 2

描述你要改什么（自然语言即可）

不需要自己写完整新版本。可以直接说：

把第三段「角色锁定」里"自建房 / 地基"那一段扩展成 5 个具体场景，
其他保持不变。给我新版本预览，我确认后再上传。

Claude Code 会把改好的全文贴给你预览。你点头之前不要让它直接 create。

SOP 3

存为新 version（先打 staging，不要直接打 production）

预览没问题后，对 Claude Code 说：

把这版存为 comment.reverse-comment-system 的新 version，标签打 staging。
不要碰 production 标签。

Claude Code 会调 createTextPrompt，返回新 version 号（比如 v3），并确认 staging 标签已打上、production 仍在 v2。

⚠️

占位符（{{xxx}}）必须保留全部原有名字。当前 reverse-comment 用了这 4 个，删任何一个会让代码端 compile 出空字段：

{{sourceCommentText}}
{{targetVideoTitle}}
{{skeletonBlock}}
{{noTitleClause}}

改稿时让 Claude Code「保持占位符不变」，验证一下输出里这 4 个字符串都还在。

SOP 4

用 staging 跑两条样本验证

找现任工程师在测试环境临时把 fetch 标签从 production 切成 staging，跑 2-3 条真实评论看输出，或者直接拿这条 prompt 喂给 Claude Code 自己模拟跑：

用刚存的 staging 版本，模拟跑一条样本：
sourceCommentText="想问下你家的实木衣柜板材是哪种"
targetVideoTitle="衣帽间收纳改造"
skeletonBlock=（任意一种骨架文本）
noTitleClause=""
看输出符不符合预期。

SOP 5

一键上线（转 production 标签）

验证通过后：

把 comment.reverse-comment-system 的 production 标签从 v2 转到 v3

Claude Code 调 updatePromptLabels，瞬间完成。30 秒内生产环境全部命中新 prompt。

SOP 6

出问题 → 回滚（同样一句话）

如果上线后发现新版有问题（比如同行触发率涨了 / 输出变怪）：

把 comment.reverse-comment-system 的 production 标签转回 v2

30 秒内复原。这就是无缝回滚机制 ——没有"撤销发布"按钮，但因为老版本永不删，转标签就够了。

5常用对话模板

直接复制贴给 Claude Code，把尖括号里的内容换成你的：

📦 盘点 / 查询

列出 Langfuse 里所有 prompt，按最近改动时间排序

把 <prompt-name> 当前 production version 拉出来全文给我

把 <prompt-name> 的 v1 和 v2 内容做个 diff，告诉我改了什么

✏️ 改稿 / 上线

基于 <prompt-name> 的当前 production 版本，做以下修改：
  1. <改动 1>
  2. <改动 2>
保持所有占位符不变。给我预览，确认后存为新 version 并打 staging 标签。

把刚存的 v<N> 的 production 标签转过去，把 staging 标签清掉

🔙 回滚 / 紧急

把 <prompt-name> 的 production 标签从 v<X> 回滚到 v<Y>

列出 <prompt-name> 所有历史 version 的最早 100 字预览，帮我找一个看起来正常的版本回滚到

🧪 试跑 / 验证

用 <prompt-name> 的 staging 版本，模拟跑下面这组输入，看输出是否符合「30-80 字 / 中文 / 钩私信」要求：
<粘贴一组真实输入>

6故障排查

装完 MCP，问 Claude Code "列出 prompt" 它说没有 langfuse 工具

退出当前会话重开（MCP 装在某些版本下需要重启 Claude Code）
跑 claude mcp list，确认 langfuse 在列表里且 status 是 ✓ connected
不在 → 重新跑第 ② 章 STEP 3，仔细核对 URL 的 jp. 子域
在但 status 红 → 大概率是 base64 拼错，重新跑第 ② 章 STEP 2

调用工具时报 401 Unauthorized

API key 过期/被撤销 → dashboard 重新建一对，重跑 STEP 2 / 3
在错误的 Langfuse 区域 → 确认 URL 是 jp.cloud.langfuse.com，不是 cloud.langfuse.com 或 us.cloud.langfuse.com
base64 编码时把回车一起 base64 了 → 必须用 echo -n（带 -n 不输出换行），不能用普通 echo

调用 createTextPrompt 报 403 Forbidden

你在 project 里只有 VIEWER 权限。dashboard → akke-prod → Settings → Members 找你的条目，让 Owner 改成 MEMBER 或 ADMIN。

转完 production 标签 30 秒了，生产怎么还是老 prompt？

30 秒是单台 Vercel function 实例的缓存上限。如果 Akke 流量低、function 实例可能存活几分钟没收新流量自然不刷新
等下一次 cron 触发（如 /api/cron/analyze */15min）就会用新 prompt
急着验证 → 找工程师在 Vercel dashboard 重新部署一次（强制冷启动）

不小心把 production 标签转到了一个有 bug 的 version

不要慌。立刻说「把 <prompt-name> 的 production 标签转回 v<上一个正常版本>」即可。30 秒内复原。如果你不记得上一个版本号，让 Claude Code 列出所有 version + 时间顺序帮你定位。

占位符（{{xxx}}）改没了 / 改名了 → 生产 prompt 输出乱套

Akke 代码端用占位符名字注入数据，名字对不上 Claude 收到的 prompt 就会出现 {{sourceCommentText}} 字面字符串、或者关键字段为空。立刻回滚到上一个 version。下次让 Claude Code 改稿时明确说"保留所有 {{xxx}} 名字不变"。

7红线 · 不要踩

🚫

1. 不要把 API key 共用 / 提交到 git / 截图发群
Secret Key 等价于密码。漏了立刻去 dashboard Revoke 这对 key 重新建。

🚫

2. 不要直接给新 version 打 production 标签跳过 staging
新 prompt 30 秒内打到所有线上请求。先 staging → 至少跑 2-3 条样本 → 再转 production，别图省事。

🚫

3. 不要删占位符 / 改占位符名字
{{sourceCommentText}} 这种是代码注入数据的接口，删一个 = 那个字段在 prompt 里彻底消失，输出会乱掉。改稿前先记下当前 prompt 用了哪几个占位符，改完检查是不是都还在。

🚫

4. 不要在 prompt 里写客户隐私 / API key / 内部 ID
Langfuse Cloud 是 SaaS，prompt 内容会持久化在 Langfuse 服务器（日本机房）。任何 Akke 客户姓名、抖音 sec_uid、内部 org_id 都不要写进 prompt 文本——这些用占位符在调用时注入。

🚫

5. 不要新建 prompt 不打招呼
新建一个 prompt 在 Langfuse 里很容易（一句话搞定），但代码端不会自动 fetch 没注册的 prompt，得工程师改 src/lib/llm.ts 配 fallback。要新建之前在 Lark 群里说一声让工程师配套上。

8一页速查卡

🔧 一次性安装

# 1. dashboard 拿 key（akke-prod → Settings → API Keys）
# 2. 终端 base64
echo -n "pk-lf-xxx:sk-lf-xxx" | base64
# 3. 终端注册 MCP
claude mcp add --transport http langfuse https://jp.cloud.langfuse.com/api/public/mcp \
  --header "Authorization: Basic <上一步输出>"
# 4. 重开 Claude Code 会话验证
# 在 Claude Code 里说："列出 Langfuse 所有 prompt"

📋 改一次 prompt 的 6 步

"把 <name> 当前 production 拉出来"
描述要改什么 → Claude Code 给预览
"存为新 version，打 staging"
跑 2-3 条样本验证
"把 production 标签转到 v<N>"
出问题 → "production 转回 v<N-1>"

📚 关键事实

Langfuse 区域：jp.cloud.langfuse.com（日本，不是 EU/US）
项目：akke-prod
当前在线 prompt：comment.reverse-comment-system（v1）
占位符（reverse-comment）：sourceCommentText / targetVideoTitle / skeletonBlock / noTitleClause
生产生效延迟：≤ 30 秒
fallback 兜底：src/lib/reverseComment.ts:REVERSE_COMMENT_SYSTEM_FALLBACK
MCP 工具：5 个（list / get / createText / createChat / updateLabels）
权限：project-level MEMBER 起步即可改 prompt