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

    下载 Markdown

    提示词资产化系统需求分析（统一经 cloud-data-proxy 存储）

    0. 文档目的与约束升级

    本文档用于定义“提示词资产化系统”的完整需求范围、架构约束、实施路径与验收标准。

    本版本新增并强化以下硬性约束：

    • 系统中所有持久化存储访问必须通过 /Users/Zhuanz/work-space/cloud-data-proxy 提供的代理能力实现。
    • 业务服务禁止直连 MySQL/SQLite 或其它关系型数据库。
    • 任何 DDL 变更必须通过代理的 DDL 接口执行并保留变更理由。

    1. 背景与问题定义

    当前提示词资产面临以下问题：

    • 高质量提示词分散在不同渠道，缺乏统一沉淀与可追踪管理。
    • 提示词结构不一致，难以复用，跨场景改造成本高。
    • 缺少模板化与参数化机制，同类需求往往重复编写。
    • 缺少评估标准，提示词“是否好用”主要依赖主观经验。

    目标是把“提示词”从零散文本升级为“可管理、可复用、可演进”的工程化资产。

    2. 项目目标

    1. 建立统一提示词资产库，支持集中收集、分类、检索与版本化管理。
    2. 将提示词拆解为标准模块，抽取同类场景的公共部分。
    3. 支持基于模板和变量快速生成场景化提示词实例。
    4. 建立质量评估、审计追踪、发布治理机制。
    5. 确保所有存储读写链路统一通过 cloud-data-proxy。

    3. 范围定义

    3.1 范围内（In Scope）

    • 提示词资产入库与元数据管理。
    • 提示词结构拆解与公共模块抽象。
    • 模板组装与参数化实例生成。
    • 评估、评分、评审、版本与发布状态管理。
    • 基于 cloud-data-proxy 的统一数据访问层与审计追踪。

    3.2 范围外（Out of Scope）

    • 模型微调、训练平台建设。
    • 通用 BI 平台和复杂权限中心。
    • 多云跨地域数据库容灾体系（后续阶段再规划）。

    4. 关键角色

    • 资产维护者：负责收集、拆解、抽象、发布模板。
    • 使用者：按任务类型检索并复用模板，生成可执行提示词。
    • 评审者：执行质量评估，决定是否进入标准模板库。
    • 系统管理员：管理 cloud-data-proxy 接入配置与访问策略。

    5. 硬性架构约束（必须满足）

    5.1 存储访问约束

    • ARCH-01：所有数据读操作必须经 proxy /v1/query。
    • ARCH-02：所有 DML 写操作必须经 proxy /v1/exec。
    • ARCH-03：所有 DDL 变更必须经 proxy /v1/ddl，并附带 ddl_ack=true 与 change_reason。
    • ARCH-04：服务代码不得出现数据库直连驱动初始化（如直接 DSN 建连）。
    • ARCH-05：业务配置中不得出现数据库明文账号密码，仅允许网关地址与 API Key。
    • ARCH-06：每次存储访问必须记录并透传 request_id，用于审计关联。

    5.2 异常与降级约束

    • ARCH-07：当 proxy 不可用时，系统应显式失败并返回可观测错误码，不允许隐式切换为直连数据库。
    • ARCH-08：关键写入接口失败时应保证幂等设计（至少在应用层避免重复提交造成脏数据）。

    6. 总体能力模型

    系统按四层能力建设：

    1. 原始资产层（Raw）：收集原始提示词与来源信息。
    2. 结构化层（Structured）：将提示词拆分为标准字段和模块。
    3. 模板层（Template）：抽取公共模块并参数化，形成可复用模板。
    4. 实例层（Instance）：按场景变量生成最终可执行提示词实例。

    7. 功能需求（FR）

    ID 功能 说明 优先级 验收标准
    FR-01 资产入库 支持新增/编辑/归档提示词资产，记录来源、作者、标签 P0 可完整创建并查询资产
    FR-02 分类标签 支持按类型、领域、任务、质量等级分类 P0 可多条件筛选
    FR-03 结构拆解 支持将提示词拆为角色/目标/上下文/约束/输出格式等模块 P0 拆解字段完整率 >= 95%
    FR-04 公共模块库 公共模块可独立维护与复用 P0 同类模板可共享模块
    FR-05 模板组装 支持按模块组装模板并定义变量 P0 可生成至少 3 类模板
    FR-06 实例生成 基于模板 + 参数生成场景化实例 P0 单次生成耗时可接受且结构正确
    FR-07 版本管理 记录模板/模块变更历史、版本号、变更原因 P1 可回溯任意版本
    FR-08 评估机制 支持多维评分与评审结论沉淀 P1 每条核心模板都有评分记录
    FR-09 检索能力 关键字、标签、质量等级、版本状态筛选 P1 检索结果可分页、可排序
    FR-10 审计追踪 记录关键操作行为与请求链路 ID P1 可按 request_id 回溯
    FR-11 导出能力 支持导出模板/实例为标准 Markdown 或 JSON P2 导出格式稳定

    8. 提示词标准结构规范

    每条结构化提示词至少包含以下模块：

    1. role：角色定位（模型应扮演的身份）。
    2. goal：任务目标（必须达成的结果）。
    3. context：业务背景与前置信息。
    4. input_spec：输入说明（参数定义、约束）。
    5. workflow：执行步骤（思考与处理流程）。
    6. constraints：边界条件（禁止项、风险限制）。
    7. output_schema：输出格式（字段、格式、长度要求）。
    8. quality_bar：质量标准（评判准则）。
    9. fallback：信息不足或冲突时的处理策略。

    9. 数据模型建议（逻辑模型）

    建议核心实体如下：

    • prompt_asset：原始与结构化提示词主体。
    • prompt_module：可复用模块定义。
    • prompt_template：模板定义（由多个模块组合）。
    • template_module_map：模板与模块关联关系。
    • prompt_instance：按参数渲染后的实例。
    • prompt_evaluation：质量评估结果与评分明细。
    • prompt_version：版本快照与发布记录。
    • audit_event：关键操作审计日志。

    关键字段建议：

    • 标识与归属：id, name, type, domain, tags, owner
    • 内容结构：content_raw, content_structured, variables, output_schema
    • 治理信息：status, version, change_reason, reviewer
    • 评估信息：score_accuracy, score_stability, score_safety, score_efficiency
    • 审计信息：created_at, updated_at, operator, request_id

    10. cloud-data-proxy 集成需求（SR）

    10.1 接入方式

    • SR-01：系统通过 HTTP 调用 cloud-data-proxy，不保留 DB 直连配置。
    • SR-02：应用凭据使用 proxy api_key，通过 Authorization: Bearer <api_key> 访问。
    • SR-03：管理类初始化动作（如应用创建、密钥轮换）通过 proxy 管理接口完成。

    10.2 读写与变更规则

    • SR-04：查询类访问统一走 /v1/query。
    • SR-05：新增/更新/删除统一走 /v1/exec。
    • SR-06：结构变更统一走 /v1/ddl，并记录变更理由与工单号（如有）。

    10.3 审计与可观测性

    • SR-07：每次 proxy 调用必须采集 request_id 并落入业务日志。
    • SR-08：失败请求必须记录错误码、耗时、重试次数与调用上下文。
    • SR-09：审计查询至少支持按 app_id、endpoint、error_code、时间窗口过滤。

    10.4 安全要求

    • SR-10：禁止在日志中输出明文 api_key。
    • SR-11：凭据由安全配置管理，不允许硬编码。
    • SR-12：高风险 DDL 在流程上必须经过评审确认后执行。

    11. 非功能需求（NFR）

    11.1 性能

    • NFR-01：常规检索接口 P95 响应时间 <= 300ms（不含大规模导出）。
    • NFR-02：模板实例生成接口 P95 响应时间 <= 500ms。
    • NFR-03：proxy 调用失败率应低于预设阈值，异常时具备可恢复重试策略。

    11.2 可用性与可靠性

    • NFR-04：关键写路径出现错误时，不得产生部分提交后不可追踪状态。
    • NFR-05：必须具备最小可用审计能力，支持问题回放与责任追踪。

    11.3 可维护性

    • NFR-06：模块命名、模板命名、标签体系需有统一规范。
    • NFR-07：版本变更需要附带原因与影响范围说明。

    12. 业务流程要求

    12.1 入库流程

    1. 提交原始提示词与来源信息。
    2. 系统完成结构化拆解并提示维护者确认。
    3. 抽取公共模块，归档到模块库。
    4. 生成模板并绑定变量定义。
    5. 触发评估与评审，合格后发布。

    12.2 复用流程

    1. 使用者按标签/场景检索模板。
    2. 输入业务参数，生成实例。
    3. 验证输出格式与质量标准。
    4. 若不足，提交优化并进入新版本流程。

    13. 验收标准（MVP）

    13.1 功能验收

    • 至少沉淀 30 条结构化提示词资产。
    • 至少产出 5 个可复用模板。
    • 至少 3 类高频场景可通过模板参数化生成。

    13.2 架构验收

    • 代码与配置层面不存在数据库直连路径。
    • 所有持久化调用均可追溯到 cloud-data-proxy 接口调用记录。
    • DDL 变更全部具备 change_reason 与审计记录。

    13.3 质量验收

    • 核心模板均具备评估记录与评分结果。
    • 使用者可在限定时间内完成“检索 -> 生成 -> 使用”的闭环。

    14. 里程碑建议

    1. M1（规范定义）：完成结构规范、标签体系、评分标准。
    2. M2（资产沉淀）：完成首批资产入库与结构化拆解。
    3. M3（模板抽象）：完成公共模块库与模板组装能力。
    4. M4（代理打通）：完成 cloud-data-proxy 全链路接入与审计联通。
    5. M5（评估治理）：完成评估流程、版本治理、发布策略。

    15. 风险与应对

    • 风险 1：模板抽象过度，导致业务可读性下降。
      应对：保留“模板定义 + 场景实例”双视图。

    • 风险 2：评估标准不稳定，导致发布口径不一致。
      应对：固定评分维度并建立基线样例。

    • 风险 3：proxy 异常影响核心流程。
      应对：加强熔断、重试、告警与可观测性，禁止降级为直连数据库。

    16. 实施建议（落地优先级）

    1. 先落地“结构化 + 模块化 + 参数化”三项 P0 能力。
    2. 同步建设 cloud-data-proxy 访问封装层，所有存储动作统一收口。
    3. 先做高频场景试点，形成可复用模板后再扩展规模。
    4. 从第一天开始记录版本与评估，不把资产库做成“纯收藏夹”。