把 prompt 当代码管：Git 原生 registry 与自托管平台两条落地路线

Prompt 管理落到具体工具上会分成两类：一类把 prompt 塞进 Git，用仓库本身当 registry；一类起一个自托管服务，把版本、评审、协作放进 Web UI。下面分别用 PromptTree 和 Clarive 说明这两条路线的实际形态。

A. PromptTree：prompt 是 Git 里的 first-class artifact

仓库：yedhuk/PromptTree，MIT，Python 3.10+。

定位是把 prompt 纳入 git 工作流，当作 first-class artifact，可 review / audit / rollback / deploy。

Registry 结构上，每个 prompt 版本是 .prompttree/registry/nodes/ 下的一个 YAML 文件（node），字段含 content、model、temperature、parent_id，节点之间构成 DAG。节点文件名是稳定 UUID，多人并行改不产生 merge conflict；仓库里唯一需要共享的文件是 labels.json。

Labels 是人类可读别名，指向某 family 内特定 node，作用域按 family 隔离，两个 family 可以各自有 prod：

{"Summariser":{"prod":"a1b2c3...","staging":"d4e5f6..."}}

解析有三条路径：get_prompt("Summariser", label="prod") 取该 family 带 prod 标签的 node；get_prompt("Summariser") 取最新 node；get_prompt(node_id, by="id") 精确取。content 支持 Jinja2 模板 {{ variable }}，在 get_prompt 时注入。

回滚就是 git revert，历史是 git log，责任归属是 git blame，不需要外部服务。

加密用：

prompttree lock --key $PT_KEY

原地加密所有 node 的 content 字段，算法 AES-256-GCM，随机 nonce，key 先做 SHA-256 所以接受任意长度；unlock 解密。解密在内存中于 render 时进行；metadata / name / parent_id 保持可读，以保留 git 历史和 DAG。

CI（GitHub Actions）里：

- name: Lock prompt registry
  run: prompttree lock --key ${{ secrets.PT_KEY }}

本地开发用 prompttree unlock --key $PT_KEY。

环境晋级靠多 label：

{"Summariser":{"prod":"a1b2c3...","staging":"d4e5f6...","canary":"g7h8i9..."}}

按 PROMPT_ENV 注入解析。

安装 pip install prompttree，UI 用 pip install "prompttree[ui]"。prompttree ui 打开 http://localhost:8501（Streamlit），可视化 DAG、node 详情、分支、打 label；CLI 子命令有 init / list / lock / unlock / delete-family / reset / ui --port。

v1.0 明确不覆盖 runtime tracing、LLM 调用日志、eval dashboard。受限环境可另配自托管 Langfuse 或 OpenTelemetry + 自有 APM，两者分层不重叠。

企业落地：Git host（GitHub Enterprise / GitLab 自管）存 .prompttree/registry/（nodes/ + labels.json）；CI 里 prompttree lock 后构建产物；生产运行时 PromptTree(key=...).get_prompt(label="prod") 内存解密，磁盘无明文；PT_KEY 放 Vault / AWS SSM / Azure Key Vault，仓库只存密文，二者单独都不足以读取。

B. Clarive：单容器自托管的 prompt 管理平台

仓库：pinkroosterai/Clarive，MIT，单容器。

定位是给要交付的团队做 prompt 管理：版本控制、AI 精炼、质量评分、团队工作区。它要解决的问题是 prompt 散落在代码库 / Notion / Slack / 表格，改动破坏生产时无版本可回滚，非技术同事改文案要提工单等部署，以及没人说得清上周那次「小改进」是变好还是变差。

部署：

cp .env.example .env
docker compose up -d

填 3 个 secret 后打开 http://localhost:8080，镜像来自 Docker Hub 预构建的 pinkrooster/clarive。

架构是单容器：nginx 服务前端并把 /api/ 代理到 .NET 10 API，supervisor 管理，监听 8080；PostgreSQL 16 与 Valkey 8（cache）是独立的 Docker 服务。环境变量里 POSTGRES_PASSWORD、JWT_SECRET（≥32 字符）、CONFIG_ENCRYPTION_KEY 必填；CORS_ORIGINS、CLARIVE_PORT（默认 8080）、CLARIVE_VERSION（默认 latest）可选。

版本控制上每个 prompt 走 Draft → Published → Historical；提供逐词彩色 diff、一键回滚任意版本、undo/redo 快照，以及并发保护（两人同改不会静默覆盖）。

AI 侧是多轮对话式精炼（不是一次性生成），质量评分随轮次变化，可用 Tavily 联网取实时上下文，也能自动生成 system message 或把单体 prompt 拆成多步 chain；兼容任意 OpenAI 兼容 API。Playground 支持流式输出、填 {{variables}}、选模型、调 temperature / max tokens；推理模型（o1/o3）给 chain-of-thought；多 prompt 显示 chain 步骤；保留最近 20 次执行对比。编辑器是 Tiptap v3 WYSIWYG Markdown，{{like_this}} 内联高亮，单个 entry 可含多 prompt 并拖拽排序，独立 system message 区。

分享方面，published prompt 有单 URL，无需账号，可加密码 / 过期，也可以重新生成使旧 URL 失效，或直接撤销。团队侧有 Admin / Editor / Viewer 角色、多工作区、邮件邀请、完整审计日志、嵌套文件夹、tags（AND/OR 过滤）、收藏、全文搜索。

API 用 X-Api-Key 头认证，key 在 Settings > API Keys 生成：

curl -H "X-Api-Key: cl_your_key_here" http://localhost:8080/public/v1/entries/{entryId}

curl -X POST -H "X-Api-Key: ..." -H "Content-Type: application/json" \
  -d '{"fields":{"topic":"AI safety","tone":"professional"}}' \
  http://localhost:8080/public/v1/entries/{entryId}/generate

第一个返回 published 版本及其 system message 与 prompts；第二个替换 {{topic}} / {{tone}} 返回渲染结果。OpenAPI 定义在 docs/api-reference.yaml，开发模式下有 /api-docs。

邮箱默认关闭，新用户自动验证；可配 Resend 或 SMTP，改动 30 秒内生效。Google 登录可选。

对照表

前提、边界与失败时的表现

PromptTree 的前提是团队已经有 Git host 和 CI，并且愿意让 prompt 跟代码待在同一个仓库里：.prompttree/registry/ 的评审、分支、权限全部复用 Git 那一套，访问控制就是你的 Git host，成本为零（MIT，无遥测）。代价是它不是给非工程角色准备的产品，且 runtime tracing、LLM 调用日志、eval dashboard 都不在 v1.0 范围内——要做可观测性得另接 Langfuse 或 OpenTelemetry + 自有 APM。

它最典型的失败模式是把 label 改错：labels.json 里 prod 指向了错误的 node，线上 get_prompt("Summariser", label="prod") 会直接渲染错版本，而且不会有任何运行时告警。好在改动是一次 commit，git revert 能回退，git blame 能定位到人。另一个边界是 PT_KEY：仓库只存密文、key 存在 Vault / AWS SSM / Azure Key Vault，两者单独都不足以读取内容；但如果 key 泄露而 lock 又没跑，磁盘上就是明文。

Clarive 的前提是能跑 Docker Compose，并且接受它成为 prompt 的唯一写入入口——POSTGRES_PASSWORD、JWT_SECRET、CONFIG_ENCRYPTION_KEY 三个 secret 必须先填好。它适合需要非技术同事直接改文案、又要保留版本和审计的团队；不适合只想在代码仓库里管 prompt、不想再维护一套服务的团队，也不适合需要 LLM 可观测与追踪的场景——Clarive 本身没有 tracing，要配 Langfuse。运维上它是单容器入口，nginx、API、supervisor 都在一个容器里，这个容器挂掉就等于管理面不可用；X-Api-Key 泄露则等于把 published prompt 的读取和 generate 能力一起交出去，需要轮换 key。

项目信息

• PromptTree 仓库：https://github.com/yedhuk/PromptTree
• Clarive 仓库：https://github.com/pinkroosterai/Clarive
• Clarive OpenAPI：docs/api-reference.yaml，开发模式 /api-docs