enterprise-pinned-registry

企业级固定注册表

面向 AI 生成的锁文件概念。模型版本、提示词、品牌标记和种子都会固定到清单中，以便在六个月、一年或三年后重新生成完全相同的营销活动。专为需要可复现性的企业打造，适用于法律保全、品牌营销活动连续性、合规抗辩和逐年可比性。

---

适用场景

• 多团队部署：20+ 名设计师 / 项目经理 / 代理机构使用同一品牌生成内容，需要确保所有人的输出完全一致
• 逐年延续的营销活动（年度报告、季度财报图表）必须与上一年的视觉效果完全一致
• 受监管行业将“可复现”视为合规要求，而非偏好
• 法律保全——为诉讼支持，可能需要完全一致地重新生成特定素材
• 模型提供方变更管理——新版本每周发布；你需要明确且经过审核的升级，而不是悄然变化
• 审计追踪：每项发布的素材都必须能追溯到特定模型版本、提示词和品牌标记集

不要用于：一次性探索、草稿 / 构思阶段、消费者项目。

---

前提条件

编写注册表之前：

1. 范围——哪些模型、提示词和品牌标记属于范围？从小范围开始（仅主视觉图），然后再扩展。
2. 升级频率——每季度一次？仅按需升级？由谁批准升级？
3. 回归测试语料库——批准升级前必须重新运行哪些提示词？（通常为 10–20 个有代表性的提示词。）
4. 存储——将注册表放在营销活动仓库、专用的 brand-registry 仓库，还是中央治理仓库中？
5. 回滚计划——如果升级造成不可接受的变化，该如何回退？（如果注册表在 git 中，通常只需执行 git revert。）
6. 审计保留期限——注册表和生成的输出必须保留多久？SOX 相关内容为 7 年，制药行业为 10 年，商标抗辩则为永久。

---

运行方法

分为五个步骤。注册表就是契约；所有生成操作都以它为依据。

1. 编写 registry.json——设置模型别名、提示词模板、品牌标记和默认参数。每个别名都固定到明确的 model@version。
2. 为提示词生成指纹——每个提示词模板都会生成一个 SHA256 哈希并与之一起存储。如果提示词字符串发生变化，指纹也会变化，这就属于一次版本升级。
3. 配置 CLI——gen-ai config set registry <path> 会将此计算机上的所有调用指向该注册表。团队将注册表提交到 git，并通过 clone/pull 同步。
4. 根据别名生成——设计师使用 flux（别名），而不是 [email protected]（原始 ID）。别名解析由注册表负责。
5. 每季度升级——使用候选新版本运行回归语料库，对输出进行差异比较，获得批准后升级注册表，并为版本发布打标签（brand-registry-v2026.2）。

快速参考

注册表本身就是清单。将它提交并打标签，每次升级时都比较差异。

{
  "registry_version": "2026.2.0",
  "locked_at": "2026-04-01T00:00:00Z",
  "locked_by": "[email protected]",
  "previous_version": "2026.1.0",
  "regression_run_id": "REG-2026Q2-APPROVED",
  "models": {
    "flux":     { "id": "[email protected]",          "commercial_use": true,  "notes": "Hero, editorial" },
    "kontext":  { "id": "[email protected]",    "commercial_use": true,  "notes": "Product edit-mode" },
    "upscale":  { "id": "[email protected]", "commercial_use": true,  "notes": "Print prep" },
    "kling":    { "id": "[email protected]",       "commercial_use": true,  "notes": "I2V broadcast" },
    "portrait": { "id": "[email protected]",  "commercial_use": true,  "notes": "Portrait, verify license" }
  },
  "prompt_templates": {
    "hero_launch": {
      "text": "Editorial hero, {subject}, {environment}, brand palette, natural light",
      "fingerprint": "sha256:7b4f2a...c8e1"
    }
  },
  "brand_tokens": {
    "palette": { "primary": "#FF006E", "ink": "#0D0A1F", "accent": "#FFBE0B" },
    "aspect_ratios_allowed": ["16:9", "9:16", "1:1", "3:2"],
    "seed_default": 42
  },
  "audit_id": "REGISTRY-2026.2"
}

每项生成素材的 results.json 条目都应包含 registry_version，以便只需一条命令即可复现。

---

快速参考

注册表负责固定模型，不负责选择模型。选择模型请参阅各工作流的技能。典型的企业级注册表包含：

别名	固定到	用途
flux	[email protected]	主要的照片级真实感主视觉图
kontext	[email protected]	编辑模式，保留产品准确性
portrait	[email protected]	人像，适用于商业用途（请核实许可证）
upscale	[email protected]	印刷 / 有线电视素材准备
remove-bg	[email protected]	透明 PNG 衍生图
change-bg	[email protected]	更换目录图背景
kling	[email protected]	用于广播的图像转视频

升级时使用 gen-ai models info <id> 确认商业用途许可和区域可用性。提供方条款会变化；固定版本不等于获得许可。

---

流程

• 在所有地方使用别名，不要使用原始 ID。 设计师不应在提示词中看到 [email protected]，只能看到 flux。
• 注册表存放在 git 中。 提交、打标签、比较差异、审查、回滚。免费获得完整的审计跟踪。
• 每次升级前准备回归语料。 准备 10–20 个典型提示词，分别使用旧版本和新版本运行，并由品牌负责人审核视觉差异。
• 模型支持时，固定种子以确保可复现。 --seed 42 可确定性地重新生成相同输出。
• 为提示词模板生成指纹。 模板中的任何字符串更改都必须作为有版本记录的升级，而不能静默修改。
• 以类似 semver 的方式标记注册表版本（2026.2.0 = 年-季度-补丁）。拼写修正用补丁版本；新增别名用次版本；更换模型用主版本。
• 弃用，不要删除。 删除别名会破坏历史重跑。将其标记为已弃用，保留固定版本，并在 CLI 输出中提示。
• 记录升级信息。 每次版本升级都应附带变更日志：使用了哪个模型、升级原因、回归结果、审批人。
• 每季度使用相应的注册表版本重新运行一次历史活动，以验证仍可复现。 如果失败，说明提供商已弃用该版本，应规划迁移。

---

常见问题

• 清单中混用别名和原始 ID——团队会无意中偏离注册表。在 PR 中检查原始 ID。
• 没有回归语料——升级发布后，偏差可能一直不可见，直到一年后被传播负责人发现。
• 提供商弃用了固定版本——这迟早会发生。每季度运行注册表中的历史版本，在需要出于法律原因重新生成内容之前发现问题。
• 编辑提示词却未更新指纹——有人“修正了模板中的拼写错误”，结果输出发生变化。应更新指纹并升级版本。
• 未固定种子——不固定种子就无法完全复现。设置注册表默认种子。
• 注册表存放在个人仓库中——会失去组织层面的访问权限。注册表必须存放在由治理团队管理的仓库中。

---

验证

运行 gen-ai whoami 确认身份验证状态，然后使用 --debug 重新运行失败的命令。

命令

# Point the CLI at the registry
gen-ai config set registry.path ./brand-registry/registry.json

# Pin a model alias
gen-ai config set registry.flux [email protected]
gen-ai config set registry.kontext [email protected]
gen-ai config set registry.kling [email protected]
gen-ai config set registry.upscale [email protected]

# Verify a given alias resolves to the pinned version
gen-ai config get registry.flux
# → [email protected]

# Generate using the alias (reproducible)
gen-ai generate --model flux --prompt-file prompts/hero-launch.txt \
  --seed 42

# Batch resolves all aliases against the registry
gen-ai batch run campaign.json

每个清单都引用别名，而非原始模型 ID。注册表是唯一将别名映射到版本的地方。

---

成本与时间

注册表操作成本低廉，其价值在于避免问题。

活动	成本	时间
编写初始注册表	0	1 个工程师工作日
季度回归语料（20 个提示词）	~200 个积分	~1 小时生成 + ~2 小时审核
版本升级 + 打标签	0	~30 分钟
重现 1 年前的活动	与原活动相同的积分	与原活动相同的实际用时
提供商弃用版本后的迁移	~500 个积分	1–2 个工程师工作日

团队规模越大，成本节省越明显：20 人的设计团队偶尔进行升级，因偏差产生的成本远高于每季度审核一次后再升级。

---

另请参阅

• enterprise-brand-governor — 通过 brand.md 实施门控；与注册表搭配，实现完整的策略即代码
• product-photo-studio — 批量目录运行（重拍模式）；使用注册表别名
• enterprise-press-batch — 考虑禁发期的流水线，固定版本以确保年度一致性
• gen-ai-use — CLI 参考