下载 Markdown

提示词资产化系统增强方案（v1.1）

文档日期：2026-02-17
适用系统：提示词资产化系统（已上线版本）
约束延续：所有存储访问必须经 cloud-data-proxy，禁止直连数据库。

1. 背景与问题

当前系统已具备“资产录入、结构拆解、模板/变量、渲染导出、评估发布”等基础能力，但在“可编辑的结构抽象”和“面向使用者的可理解性”上仍有明显缺口：

1. 使用者不知道哪些内容是固定公用、哪些可以替换。
2. 变量虽然存在，但模板结构与变量绑定关系不够直观。
3. 缺少“示例输入 -> 预期输出”的教学与验证面板，用户不容易判断模板质量与适用边界。
4. 宽屏场景下的编辑效率与信息密度仍可提升。
5. 已保存资产缺少系统内编辑入口，导致小改动也要新建资产，管理成本高。

2. 目标与收益

2.1 目标

1. 支持用户显式标记提示词结构块：公用固定、可替换变量、混合模板。
2. 支持填写变量后“一键生成 + 一键复制”最终提示词。
3. 支持为每个模板维护“示例 + 预期效果”，用于教学、验收与质量基线。
4. 构建从“结构设计 -> 变量配置 -> 示例验证 -> 复制使用”的完整闭环。
5. 支持对已保存资产进行修改、保存与审计追踪，避免重复新建。

2.2 预期收益

1. 模板复用率提升，减少重复编写。
2. 新用户上手时间降低。
3. 输出一致性增强，降低提示词质量波动。
4. 评审与发布有更可解释的依据。

3. 术语定义

1. 结构块（Block）：提示词中的语义分段（角色/目标/约束/输出格式等）。
2. 公用固定（STATIC）：不可替换，面向同场景复用。
3. 可替换变量（VARIABLE）：完全由变量填充值决定。
4. 混合模板（MIXED）：固定文本 + 变量占位符组合。
5. 示例（Example）：一组输入变量、渲染结果、预期输出与质量说明。

4. 范围定义

4.1 本期范围（In Scope）

1. 模板结构编辑器（块级模式配置）。
2. 变量管理增强（类型、必填、默认值、校验）。
3. 渲染预览与复制增强。
4. 示例与预期效果模块。
5. 对应后端 API、持久化模型、前端交互与测试。
6. 已保存资产编辑能力（内容、标签、类型、状态等）与审计留痕。

4.2 非本期范围（Out of Scope）

1. 自动 AI 拆分建议（可作为后续 v1.2）。
2. 模型在线评测回路（本期先支持人工预期输出与评分基线）。
3. 多租户权限系统重构。

v1.2 对应文档：

1. /Users/Zhuanz/work-space/hot-docs/content/docs/reference/prompt-asset-system-v1.2-ai-assisted-parsing-solution.md
2. /Users/Zhuanz/work-space/hot-docs/content/docs/reference/prompt-asset-system-v1.2-executable-development-plan.md
3. /Users/Zhuanz/work-space/hot-docs/content/docs/reference/prompt-asset-system-v1.2-development-tracker.md

5. 用户角色与核心场景

1. 模板设计者：配置结构块、变量和示例。
2. 模板使用者：输入变量、查看渲染结果、复制使用。
3. 审核者：查看示例与预期效果，判断是否可发布。

核心场景：

1. 设计者把原始提示词拆成结构块，并标注每块模式。
2. 设计者定义变量规则（必填、默认、枚举、校验）。
3. 设计者录入 1~N 条示例，形成“预期效果库”。
4. 使用者在实例页填变量，实时渲染并复制。
5. 审核者基于示例对照和评分结果做发布决策。
6. 设计者在资产详情页修改已保存资产并即时生效到后续结构拆分与模板流程。

6. 功能需求（FR）

7. 数据模型设计（逻辑字段）

7.1 模板结构块表 prompt_template_blocks

7.2 模板变量表 prompt_template_variables_v2

7.3 模板示例表 prompt_template_examples

7.4 资产主表增强 prompt_assets（增量字段）

8. API 契约（新增/增强）

统一前缀：/api/v1
统一响应：保留 request_id 与标准错误结构。

8.1 结构块

1. GET /templates/{id}/blocks
2. PUT /templates/{id}/blocks（批量覆盖保存）

PUT 请求示例：

{
  "items": [
    {
      "block_key": "role",
      "block_title": "角色",
      "block_order": 1,
      "mode": "STATIC",
      "content_template": "你是一名资深提示词工程师",
      "required": true
    },
    {
      "block_key": "goal",
      "block_title": "目标",
      "block_order": 2,
      "mode": "VARIABLE",
      "variable_name": "task_goal",
      "required": true
    },
    {
      "block_key": "output_schema",
      "block_title": "输出格式",
      "block_order": 3,
      "mode": "MIXED",
      "content_template": "请输出 JSON，字段包含：{{fields}}",
      "required": true
    }
  ]
}

8.2 变量

1. GET /templates/{id}/variables
2. PUT /templates/{id}/variables（批量保存）

8.3 示例

1. GET /templates/{id}/examples
2. POST /templates/{id}/examples
3. PATCH /templates/{id}/examples/{example_id}
4. DELETE /templates/{id}/examples/{example_id}（逻辑归档）

8.4 渲染与复制

1. POST /templates/{id}/render-preview
2. POST /templates/{id}/copy（返回标准文本，前端执行剪贴板复制）

render-preview 请求示例：

{
  "variables": {
    "task_goal": "为电商客服设计追问策略",
    "fields": "intent, confidence, next_action"
  }
}

8.5 资产编辑（已保存资产）

1. GET /assets/{id}（查询资产详情）
2. PATCH /assets/{id}（修改已保存资产）

PATCH 请求示例：

{
  "name": "客服追问策略模板（增强版）",
  "asset_type": "generic",
  "tags": ["analysis", "客服", "追问"],
  "content": "你是一名客服质检专家，请基于对话输出追问策略...",
  "status": "active",
  "update_reason": "补充输出格式要求",
  "version": 7
}

说明：

1. version 用于乐观锁防并发覆盖，版本不一致返回 CONFLICT。
2. 资产编辑成功后需写审计事件，并回写最新版本号。

9. 前端交互方案（事件驱动）

9.1 页面结构

建议新增模板工作台页签：

1. 结构拆分
2. 变量定义
3. 示例与预期
4. 渲染与复制
5. 资产编辑

9.2 交互原则

1. 所有加载/保存/渲染均由显式事件触发（按钮/提交/切换）。
2. 默认不使用 useEffect 拉取数据，保持事件驱动模型。
3. 宽屏采用双栏布局：左编辑、右预览/示例对照。
4. 已保存资产编辑页支持“当前版本信息 + 修改说明 + 保存并刷新”。

9.3 可用性要求

1. 结构块拖拽排序或显式上移下移。
2. 变量面板实时提示未使用变量/未定义变量。
3. 示例列表支持快速插入为当前渲染输入。

10. 校验与错误处理

1. VARIABLE 模式必须存在 variable_name 且该变量已定义。
2. MIXED 模式中的占位符必须全部可解析。
3. 渲染前进行必填与格式校验，不通过则返回 BAD_REQUEST。
4. 复制动作若渲染失败则阻断并提示具体变量错误。
5. 资产编辑请求必须校验 name/asset_type/content 基本合法性。
6. 资产编辑时 version 必填，版本冲突返回 CONFLICT 并给出最新版本。

11. 可观测与审计要求

1. 关键动作日志字段：request_id、operator、action、template_id、duration_ms、error_code。
2. 结构/变量/示例变更均写入审计事件。
3. 失败渲染写入失败链路，便于在观测面板追踪。
4. 资产编辑需记录修改前后摘要、update_reason 与版本号变化。

12. 验收标准

12.1 功能验收

1. 任意模板可完成结构块模式配置并保存成功。
2. 使用变量渲染后可稳定生成最终提示词并复制。
3. 每个模板至少支持维护 1 条示例及预期输出。
4. 示例可在页面中完成“输入/渲染/预期”对照展示。
5. 已保存资产可在详情页修改并保存成功，刷新后可见最新内容。
6. 资产并发修改发生版本冲突时，系统可正确阻断并提示重试。

12.2 质量验收

1. 渲染输出正确率（按用例）>= 95%。
2. 必填变量遗漏可被 100% 拦截。
3. 关键交互在宽屏（>=1600）下无明显可用性阻塞。

12.3 架构验收

1. 所有新增读写接口均通过 cloud-data-proxy。
2. 新增表结构变更通过 /v1/ddl 执行并记录 change_reason。
3. 无业务直连数据库依赖。

13. 开发任务拆解（建议）

14. 里程碑建议（M6）

1. M6-W1：E01~E04（数据模型与后端主干）。
2. M6-W2：E05~E09 + E13（前后端联调与资产编辑能力）。
3. M6-W3：E10~E12（宽屏优化、测试、发布门禁）。

15. 风险与应对

1. 风险：结构模式复杂导致学习成本上升。
   应对：默认模板提供推荐结构与示例引导。
2. 风险：变量规则配置不当导致渲染失败率升高。
   应对：引入预发布校验与示例回归。
3. 风险：示例内容质量不稳定影响评审一致性。
   应对：增加“正例/反例”并附质量备注模板。
4. 风险：多人同时编辑同一资产导致覆盖写。
   应对：引入乐观锁版本号与冲突提示机制。

16. 决策建议

1. 该增强应作为下一阶段 P0 项推进。
2. 建议先实现“结构块 + 变量 + 渲染复制”，再叠加“示例与预期”。
3. “已保存资产编辑”应与核心 CRUD 一并纳入 P0，避免重复建资产带来的治理成本。
4. 该方案与现有架构兼容，可在不推翻现有系统的前提下逐步落地。

17. 模板工作台使用案例（书法海报关键词替换）

17.1 原始提示词

纯白背景，“{关键词}”，苍劲有力的毛笔书法风格，真实笔触质感，字体笔画包含{关键词}地标建筑，著名景点完美结合填充，极繁主义，颜色鲜艳，3D效果，红色结印印章点缀。

该提示词中，关键词 是可替换部分，其余内容为固定公用部分。

17.2 在模板工作台中的配置方式

1) 结构拆分（Blocks）

建议配置为 6 个结构块：

{
  "items": [
    {
      "block_key": "bg",
      "block_title": "背景",
      "block_order": 1,
      "mode": "STATIC",
      "content_template": "纯白背景，",
      "required": true
    },
    {
      "block_key": "keyword_title",
      "block_title": "关键词标题",
      "block_order": 2,
      "mode": "MIXED",
      "content_template": "“{{keyword}}”，",
      "required": true
    },
    {
      "block_key": "style",
      "block_title": "书法风格",
      "block_order": 3,
      "mode": "STATIC",
      "content_template": "苍劲有力的毛笔书法风格，真实笔触质感，",
      "required": true
    },
    {
      "block_key": "landmark_fill",
      "block_title": "地标融合",
      "block_order": 4,
      "mode": "MIXED",
      "content_template": "字体笔画包含{{keyword}}地标建筑，著名景点完美结合填充，",
      "required": true
    },
    {
      "block_key": "visual",
      "block_title": "视觉效果",
      "block_order": 5,
      "mode": "STATIC",
      "content_template": "极繁主义，颜色鲜艳，3D效果，",
      "required": true
    },
    {
      "block_key": "seal",
      "block_title": "印章点缀",
      "block_order": 6,
      "mode": "STATIC",
      "content_template": "红色结印印章点缀。",
      "required": true
    }
  ]
}

2) 变量定义（Variables）

只需要定义一个变量 keyword：

{
  "items": [
    {
      "var_name": "keyword",
      "display_name": "关键词",
      "data_type": "string",
      "required": true,
      "min_len": 1,
      "max_len": 12,
      "help_text": "例如：杭州、西安、上海、黄山",
      "sort_order": 1
    }
  ]
}

3) 示例与预期（Examples）

建议至少维护 2 条示例（1 条正例 + 1 条反例）：

正例：

{
  "name": "城市地标正例-杭州",
  "scenario": "文生图-地标书法海报",
  "input_vars": {
    "keyword": "杭州"
  },
  "rendered_prompt": "纯白背景，“杭州”，苍劲有力的毛笔书法风格，真实笔触质感，字体笔画包含杭州地标建筑，著名景点完美结合填充，极繁主义，颜色鲜艳，3D效果，红色结印印章点缀。",
  "expected_output": "画面主体为“杭州”书法字形；笔画中可辨识地标元素（如西湖相关景点轮廓）；整体高饱和、3D 质感、附红色印章。",
  "quality_notes": "关键词清晰可读，地标融合自然，不出现背景杂色。",
  "example_type": "good"
}

反例：

{
  "name": "缺失关键词反例",
  "scenario": "变量校验",
  "input_vars": {},
  "rendered_prompt": "",
  "expected_output": "系统应阻断渲染并提示 missing required variable: keyword",
  "quality_notes": "用于验证必填变量拦截能力。",
  "example_type": "bad"
}

17.3 使用者实际操作路径

1. 进入 模板工作台 -> 结构拆分，保存上述 6 个块。
2. 切换到 变量定义，保存 keyword 规则。
3. 在 示例与预期 录入“杭州正例”和“缺失关键词反例”。
4. 切换到 渲染与复制，输入 keyword=西安 后点击“渲染预览”。
5. 预览无误后点击“复制”，得到可直接复用的最终提示词文本。

17.4 渲染结果示例（keyword=西安）

纯白背景，“西安”，苍劲有力的毛笔书法风格，真实笔触质感，字体笔画包含西安地标建筑，著名景点完美结合填充，极繁主义，颜色鲜艳，3D效果，红色结印印章点缀。