promptledger

这是什么？适合谁？

PromptLedger 是一个开源的提示词版本控制与确定性评测工具。它解决一个很实际的痛点：提示词模板改一个词，整个评测集的输出质量就可能被拉高或拉崩，但如果没有任何持久化记录，你根本说不出「哪个版本产出了哪个结果」。PromptLedger 把提示词当成代码来管理——每个模板都有一个基于内容的 SHA-256 指纹，每次对比都是一次可重复的快照，每个快照都能渲染成一份 JSON 报告和一份对应的 Markdown 报告。

它与大多数 LLM 评测工具的关键区别在于：完全离线、完全确定。评分是输入的纯函数，同一实验跑两遍会得到字节级完全一致的报告；ledgerctl diff 昨天基线和今天候选之间的差异，变成一个机械的回归信号，而不是靠人工判断。

核心价值：给「提示词工程」补上版本控制、可复现实验和可 diff 报告三件套，让提示词优化从玄学体验变成可审计的工程实践。

适合人群：

• 做 RAG / Agent / 生成式应用，需要系统化 A/B 对比提示词模板的工程师
• 希望把提示词评测纳入 CI 回归门禁（diff 作为机械信号）的团队
• 追求可复现、拒绝「黑盒评分」与不可复现时间戳的评测研究者

使用前提：本机 Python 3.11+ 与 Go 1.24+ 双工具链；不需要任何第三方包、不需要网络、不需要 LLM API key。

准备工作

1. 克隆仓库：git clone https://github.com/cyptnpassira/PromptLedger.git && cd PromptLedger
2. 环境：Python 3.11+（Python 核心与 CLI）与 Go 1.24+（伴生 CLI ledgerctl）
3. 依赖：无——标准库 only，不下载任何第三方包
4. 成本：Apache-2.0 开源免费，纯本地运行、无网络调用、无 API 计费
5. 时间：编译两个工具链约 1 分钟；跑通示例 make sample 约 1 分钟

快速上手（3 步）

第一步：编译

# 字节编译 Python 包
python -m compileall -q promptledger

# 编译 Go 包与伴生二进制
cd ledger && go build ./... && go build -o ledgerctl ./cmd/ledgerctl && cd ..

也可以直接用 Makefile：make compile、make build。

第二步：记录模板修订 + 跑一次对比快照

# 1. 把示例模板的修订写入账本（ledger）
python -m promptledger commit \
  --templates examples/templates.json \
  --ledger ledger.json

# 2. 跑一次对比快照，同时输出 JSON 与 Markdown 两种报告
python -m promptledger snapshot \
  --experiment examples/experiment.json \
  --out reports --format both

第三步：用 Go 工具独立校验

ledger/ledgerctl verify -ledger ledger.json -templates examples/templates.json

正常输出 ledger integrity verified。三条命令的一站式等价物是 python examples/end_to_end.py。

成功判定：reports/ 目录下生成了 .report.json 与 .report.md 两份报告，且 ledgerctl verify 返回 0（账本无漂移）。

初级用法

记录模板修订

python -m promptledger commit --templates templates.json --ledger ledger.json

按指纹幂等写入，输出形如 rev 1 ace9443... summarize.v1。修一版提示词再 commit，就得到 rev 2 0f413e... summarize.v2。

单次候选评分

python -m promptledger score \
  --candidate answer.txt --reference gold.txt \
  --keyword Perseverance --keyword Jezero --target-words 18

对单个候选响应打出四信号分数卡，JSON 输出到 stdout。

查看账本

python -m promptledger show --ledger ledger.json

列出每个账本条目及其变量。

高级玩法

用 ledgerctl diff 做回归门禁

ledgerctl diff -before baseline.report.json -after candidate.report.json

对比两份报告产出排行榜差异，配合 verify 可组合成 CI 里的「提示词回归检查」。

补一个自定义评分信号

在 promptledger/scoring.py 里写一个返回 [0,1] 浮点的纯函数（无时钟、无随机），把它加进 ScoreCard 并更新权重即可。四条内置信号为 lexical（词汇）、coverage（关键词覆盖）、length（长度）、penalty（结构惩罚）。

从报告自建渲染器

报告有稳定的 promptledger.report/1 JSON schema（详见 docs/report-schema.md）。基于 Snapshot 写一个 render_html(snapshot)，复用内置 _leaderboard(...) 即可生成 HTML 版报告。

小技巧

1. 先跑 python examples/end_to_end.py 看一遍完整链路，再替换成自己的模板与用例
2. 报告以 JSON 为权威（Markdown 只是其投影），两者不一致时以 JSON 为准
3. 修改提示词 body 或 name 都会改变指纹——把「改名」也当作一次实质修订来理解
4. 用小写 + 语义名（如 summarize.v1）命名模板，方便 diff 时追踪版本链
5. 所有浮点数序列化前统一四舍五入到 6 位小数，保证跨运行 byte 级一致

常见踩坑

踩坑 1：Python 或 Go 版本过低

• 现象：import 失败或 go build 报语法错误
• 原因：项目要求 Python 3.11+ 与 Go 1.24+，旧版本工具链不兼容
• 解决：升级到满足要求的两套工具链（python --version、go version 自查）

踩坑 2：占位符变量缺失导致渲染报错

• 现象：snapshot/commit 报 missing placeholder value
• 原因：PromptLedger 是「严格渲染」——模板里某个 {{ placeholder }} 在 variables 里没有对应值会被当作 error，而非告警
• 解决：检查 experiment.json 里每个 case 的 variables 是否覆盖了模板全部占位符；多余的未使用变量同样会报错

踩坑 3：误以为它会自己调用大模型

• 现象：跑 snapshot 后没有「AI 生成的答案」
• 原因：PromptLedger 是离线评测工具，不调用任何 LLM provider——候选响应需要在 experiment.json 的 cases[].candidates 里由你自己提供
• 解决：把待比较的候选文本放进 experiment 的 candidates 字段，再跑快照

踩坑 4：ledgerctl verify 报 MISMATCH / UNMATCHED

• 现象：校验非零退出，出现 MISMATCH 或 UNMATCHED 行
• 原因：账本记录与当前 templates.json 不一致（提示词在账本之外被改了）
• 解决：要么重新 commit 记录新修订，要么回退 templates.json——正是这个检查在守护「账本无漂移」的不变量

踩坑 5：报告 JSON 与 Markdown「对不上」

• 现象：两份报告字段看起来不一致
• 原因：Markdown 是 JSON 的投影，字段取舍不同
• 解决：以 promptledger.report/1 JSON 为权威源，参照 docs/report-schema.md 核对字段

常见问题 FAQ

Q: PromptLedger 是做什么的？

A: 给提示词模板做版本控制、跑确定性对比快照、给候选响应打分，并输出可 diff 的 JSON + Markdown 实验报告，让提示词优化可复现、可审计。

Q: 它会调用大模型吗？需要 API key 吗？

A: 不调用任何 LLM provider、不需要 API key、也不需要联网。候选响应由你自己在实验文件里提供，工具只负责版本化、评分和报告。

Q: 免费吗？开源吗？

A: Apache-2.0 开源免费。Python + Go 双实现都是标准库 only，无第三方依赖。

Q: 需要会什么语言？

A: 需要 Python 3.11+ 与 Go 1.24+ 两套工具链。Python 侧负责「写模板 + 报告」，Go 侧的 ledgerctl 负责「独立校验 + diff」，两者靠同一套指纹算法对齐。

Q: 和 Promptfoo / Langfuse 的区别？

A: Promptfoo 侧重接 LLM provider 做端到端评测，Langfuse 侧重线上 LLM 可观测与追踪；PromptLedger 侧重「离线、确定、可版本化」的提示词实验与报告，不接 provider、不产生网络调用，定位是回归门禁而非观测平台。

进阶学习建议

掌握三步快速上手指令后，建议深入学习：

1. 读 promptledger/scoring.py 四条信号（lexical / coverage / length / penalty）的权重重分配逻辑，理解 broken、repetitive 候选为何会因结构惩罚而永远无法胜出
2. 把 ledgerctl verify + diff 接到 CI，配合 git 的版本化，建立「提示词回归门禁」流水线
3. 参照 docs/report-schema.md 的 canonical JSON，自己实现一个 render_html(snapshot)，或给 ledgerctl 加一个 history 子命令走模板修订链
4. 若要改指纹算法，需在 promptledger/template.py 与 ledger/ledgerkit/verify.go 两处同步修改，再用 ledgerctl verify 确认两套语言实现仍一致

参考链接

• 官方仓库
• README（快速上手与命令）
• 报告 schema 文档
• 评分模型文档

最后更新：2026-09-05 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成