提示：AI 结果必须带引用；若证据不足会提示“未找到可靠证据”。

提示词资产化系统增强方案（v1.2：AI 辅助解析与多提供方接入）

文档版本：v1.2
文档日期：2026-02-17
适用仓库：/Users/Zhuanz/work-space/pe-list
文档目录：/Users/Zhuanz/work-space/hot-docs/content/docs/reference
架构约束：所有存储读写必须通过 cloud-data-proxy，禁止业务直连数据库。

1. 背景与目标

当前 v1.1 已支持“结构拆分、变量定义、示例与预期、渲染复制、资产编辑”，但拆分过程仍依赖人工配置与规则解析。为提升效率与一致性，需要引入 AI 辅助解析能力。

本期目标：

支持三种 AI 接入方式：
- Gemini Key 填入
- GPT Key 填入
- GPT 登录授权（登录后获取可用凭证，不在前端暴露长期 API Key）
输出“可审核、可编辑、可回退”的结构化建议稿，而非直接覆盖正式模板。
在安全、审计、成本可控前提下落地，保证生产可运维。

2. 范围定义

2.1 In Scope

资产级 AI 解析预览：asset -> blocks/variables/examples 建议稿。
多提供方路由与统一响应规范。
凭证管理（保存/校验/掩码展示/临时使用）。
GPT 登录授权链路（服务端换取短期可用凭证）。
解析结果人工确认后应用到模板工作台。
调用审计、成本统计、失败可观测与降级策略。

2.2 Out of Scope

自动发布模板（仍需人工审核）。
复杂多轮 Agent 自主改写（本期以单次解析建议为主）。
跨系统统一 IAM 重构（只预留授权接口）。

3.1 模式 A：Gemini Key 填入（BYOK）

用户在系统中输入 Gemini Key（可选择“仅本次使用”或“加密保存”）。
后端调用 Gemini 解析模型，返回结构化建议。
系统仅展示掩码与元信息，不回显明文密钥。

3.2 模式 B：GPT Key 填入（BYOK）

用户输入 GPT Key，流程与 Gemini BYOK 一致。
后端通过 OpenAI 兼容适配层发起请求。

3.3 模式 C：GPT 登录授权（推荐）

用户点击“GPT 登录授权”。
前端跳转授权页，后端通过 OAuth/授权回调拿到短期访问凭证。
系统保存的是可续期/可撤销的授权令牌或会话引用，而不是长期 API Key 明文。

说明：

本系统不做“从 ChatGPT 页面自动抓取 API Key”的实现。
“登录获取 key”在产品语义上定义为“登录授权获取可调用能力”。

4. 业务流程

用户在资产详情页点击“AI 辅助解析”。
选择提供方与凭证来源（Gemini/GPT/登录授权）。
点击“生成建议稿”。
后端生成异步解析任务，返回 job_id。
前端轮询任务状态，拿到建议结果。
用户可编辑建议结果并点击“应用到模板工作台”。
系统将结果写入 blocks/variables/examples，写审计并保留解析快照。

flowchart LR U["用户"] --> FE["Prompt Console 前端"] FE --> BE["pe-list API (Go)"] BE --> AI["AI Provider Adapter\nGemini / OpenAI / GPT-Login-Auth"] BE --> PXY["cloud-data-proxy"] PXY --> DB[(MySQL)] BE --> OBS["Audit + Metrics + Failure Trace"]

flowchart LR
  U["用户"] --> FE["Prompt Console 前端"]
  FE --> BE["pe-list API (Go)"]
  BE --> AI["AI Provider Adapter\nGemini / OpenAI / GPT-Login-Auth"]
  BE --> PXY["cloud-data-proxy"]
  PXY --> DB[(MySQL)]
  BE --> OBS["Audit + Metrics + Failure Trace"]

分层职责：

前端：提供方选择、凭证输入、任务状态、结果对比、人工确认。
应用层（Go Service）：任务编排、提供方路由、JSON 规范化、降级策略。
基础设施层：Provider Client、加密器、Proxy Repository、审计与指标。

6. 数据模型（通过 cloud-data-proxy 落库）

建议新增表：

prompt_ai_credentials
- id, owner_id, provider, credential_type, ciphertext, mask, status, created_at, updated_at
prompt_ai_parse_jobs
- id, asset_id, template_id, provider, model, status, input_hash, result_json, error_message, token_in, token_out, cost_usd, created_at, updated_at
prompt_ai_provider_accounts
- id, owner_id, provider, auth_type, refresh_ciphertext, expires_at, status, created_at, updated_at

字段约束：

密钥/令牌仅存密文，不存明文。
result_json 使用统一结构，支持回放与审计。
对 asset_id/status/created_at 建索引支持查询与排障。

7. API 设计（建议）

统一前缀：/api/v1/ai

POST /credentials/validate
- 入参：provider, credential_payload
- 出参：valid, model_options, message
POST /credentials
- 保存加密凭证（可选）
GET /credentials
- 列表返回掩码与状态
POST /providers/gpt/oauth/start
- 启动登录授权
GET /providers/gpt/oauth/callback
- 授权回调
POST /assets/{id}/parse-preview
- 触发解析任务，返回 job_id
GET /jobs/{job_id}
- 查询任务状态与结果
POST /jobs/{job_id}/apply
- 应用建议稿到模板工作台

8. 统一结果 Schema

{
  "blocks": [
    {
      "block_key": "goal",
      "block_title": "目标",
      "block_order": 1,
      "mode": "MIXED",
      "content_template": "请围绕{{keyword}}生成...",
      "required": true
    }
  ],
  "variables": [
    {
      "var_name": "keyword",
      "display_name": "关键词",
      "data_type": "string",
      "required": true,
      "min_len": 1,
      "max_len": 32,
      "sort_order": 1
    }
  ],
  "examples": [
    {
      "name": "正例-城市关键词",
      "input_vars": {"keyword": "西安"},
      "rendered_prompt": "...",
      "expected_output": "...",
      "example_type": "good"
    }
  ],
  "warnings": ["变量 quality 未被任何 block 使用"],
  "confidence": 0.86
}