docs/workspace/prompt-data-standardization/02-收藏提示词(含测试结果)后续阶段任务.md
本文是《01-提示词数据格式标准化设计》的分阶段落地清单,不对应单个 Trellis 任务。到 2026-05-02 为止,相关 Trellis 任务已经全部归档,当前没有未关闭的 active task。
已经随最近一轮归档任务完成并校订的范围:
仍保留为后续范围、且目前未绑定 active Trellis 任务的主要事项:
createSession / switchSession / archiveSession 等显式会话操作。本任务基于《01-提示词数据格式标准化设计》展开。后续工作不再只围绕“收藏提示词”打补丁,而是建立一个可复用的 Prompt Asset(提示词资产)模型,让工作区、收藏、测试结果、Prompt Garden 导入、导入导出、资产清理等路径共享同一套领域对象。
当前工程里,FavoritePrompt 仍然是已经落地的持久化容器和服务接口。新模型的第一阶段目标不是直接替换收藏服务,而是在收藏数据之上建立稳定的规范化视图与新写入结构:
PromptAsset。metadata.promptAsset,同时保留旧字段作为兼容展示和回滚路径。PromptAsset 或由 PromptAsset 派生出的展示视图。Prompt Garden 目前尚未作为用户可见能力公开,因此 Garden 兼容路径可以调整。更重要的是让项目自己的提示词模型足够通用、可演化,并且不把外部来源快照当成内部主模型。
建立统一的提示词资产产品行为:
basic / pro / image 三类模式使用同一套 PromptContract 识别能力边界。metadata.promptAsset 并行兼容。早期方案曾让工作区普通收藏自动生成类似 workspace-current 的可复现示例。当前实现已经收敛为新的合同:普通工作区保存只保存提示词正文和变量定义,不自动写入 example。只有用户在测试结果卡片里点击“保存为示例”时,才把真实 PromptTestRun 转换为 PromptExample / reproducibility example。
workspace-current 可以继续被读取和展示。metadata.reproducibility 表达用户可编辑的变量/示例草稿,由 FavoriteManager / metadata helper 刷新 metadata.promptAsset,UI 表单不直接手写 promptAsset。当前会话和历史链也已经有部分实现:
session/v1/basic-system、session/v1/pro-variable、session/v1/pro-multi、session/v1/image-* 保存工作区运行态。chainId/versionId 指向当前优化历史链。PromptRecordChain 保存一条优化链,链内 versions 是 PromptRecord[]。messageChainMap 保存消息到优化链的映射。testVariants、testVariantResults、testVariantLastRunFingerprint 保存当前测试运行态。assetBinding / origin,从收藏或 PromptAsset 加载工作区后可以记录来源资产和版本。useSessionManager.getPromptSession() / hydrated session 已能把当前 session、优化链、测试 run、asset binding、origin 投影到标准模型。因此目标态可以继续使用“会话”概念,但要把它定义为 Prompt Asset 的运行态容器,而不是和收藏资产、历史链、测试示例混为一体。
同时,当前实现还没有用户可见的“新建会话 / 切换会话 / 关闭会话”产品概念。useSessionManager 现在主要按 SubModeKey 保存和恢复固定快照,这更像“每个模式一个自动草稿”。后续如果要让用户显式管理多个会话,还需要引入 session registry 的产品交互;在此之前,session 作为无感来源坐标即可。
目标模型应把 PromptRecordChain 视为兼容来源,而不是最终主模型。最终主模型是 PromptOptimizationChain:一个 session 有且只有一条主优化链,链有 root,records 可以为空。这样“只有原始提示词、还没有优化结果,但可以直接测试”就是合法状态。
FavoritePrompt 持久化接口。工作区保存的语义是:把当前工作区正文沉淀为提示词资产正文。
工作区点击收藏/保存
→ 新建提示词资产或更新已有提示词资产
→ 新建:正文 = 当前工作区正文
→ 更新:若正文变化,创建新的 content version
→ 可选:提取变量定义
→ 不默认生成真实测试 example
规则:
testContent、testVariantResults、reasoning、模型输出等执行运行态。workspace-current 示例在兼容层保留,但不作为目标态新增合同。测试结果保存的语义是:把某次真实执行运行态沉淀为 PromptExample,并挂到某个提示词资产上。
测试结果区域点击收藏/保存
→ 选择一个或多个测试结果
→ 新建提示词资产或追加到已有提示词资产
→ 新建:正文默认取该测试结果实际使用的提示词正文
→ 更新:默认只追加 example
→ 如需创建或切换正文版本,走独立的显式版本管理动作
规则:
basedOnVersionId 或 metadata,但不能要求 workspace 正文与目标资产当前版本正文一致。外部来源导入的语义是:把外部提示词转换为项目自己的提示词资产,同时保留来源快照用于追溯。
规则:
ExternalSourceSnapshot。PromptAsset / metadata.promptAsset。packages/core/src/services/prompt-model@prompt-optimizer/core 导出 prompt-model 公共 APIPromptModeKey、PromptContract、PromptContent、PromptAsset、PromptSession、PromptOptimizationChain、PromptTestRunSetresolvePromptModeKey(),支持 legacy context 和当前 pro-multi 到标准模式的映射promptModeKeyToFavoriteMode(),保留 FavoritePrompt 当前兼容分类promptAssetFromFavorite(),提供 FavoritePrompt -> PromptAsset 只读投影promptRecordChainToOptimizationChain(),提供 PromptRecordChain -> PromptOptimizationChain 兼容投影createRootOnlyPromptOptimizationChain(),支持未优化原始提示词直接测试PromptAssetPromptContentVersionPromptContractPromptExamplePromptTestRun / PromptTestRunSetPromptImageRefPromptSourceRef这些类型已经下沉到 packages/core/src/services/prompt-model。UI 后续不再新建平行领域类型,应该从 @prompt-optimizer/core 引入或在 UI 侧仅做展示视图派生。
FavoritePrompt -> PromptAsset 适配器metadata.promptAsset.schemaVersion === 'prompt-model/v1'FavoritePrompt.content 合成最小资产视图metadata.promptAsset / reproducibility 派生视图,并保留旧结构降级展示pro-conversation messages 应用到工作区时恢复为现有 pro-multi 消息卡片读取优先级建议:
metadata.promptAssetFavoritePrompt 基础字段basic-system / basic-user 解析测试pro-variable / pro-conversation 解析测试image-text2image / image-image2image / image-multiimage 解析测试PromptSessionRegistry / PromptSessionSummary 类型createPromptSessionRegistry() 纯函数,记录 activeSessionIdactiveSessionIdByModesession/v1/{modeKey} 映射成 implicit session 的标准视图implicit:basic-systemPromptSession normalized viewpromptSessionFromLegacySnapshot(),可从现有 session/v1/* 快照合成 PromptSessionsessionIdlifecycle: implicit/active/background/closed/archivedorigin: blank/workspace/asset/favorite/history/garden/import/externalassetBinding:未保存时为空,保存/收藏后可绑定 assetIdoptimization: PromptOptimizationChainchainId/versionId 适配进 optimization.metadata 和 session metadatamessageChainMap 作为旧消息级链兼容来源session.uiassetBinding / originmetadata.promptAssetassetBinding.assetId 指向持久化资产createSession({ mode, subMode, origin })switchSession(sessionId)openAssetSession(assetId)openHistorySession(chainId, recordId?)forkSession(sessionId)archiveSession(sessionId)discardDraftSession(sessionId)startOptimizationSession(rootContent)appendIteration(sessionId, iterationInput)PromptOptimizationChainPromptRootSnapshotPromptOptimizationRecordPromptOptimizationChainoptimize recorditerate recordPromptRecordChain 适配到 PromptOptimizationChainPromptContentVersionPromptRecordChain.versions 自动迁移为资产 contentVersionspromptTestRunSetsFromLegacySessionSnapshot(),从 testVariants / testVariantResults 合成 PromptTestRunSetPromptTestRunPromptTestRun.revision 记录 session、optimization chain、revisionrevision.kind = root,用于原始提示词直接测试revision.kind = record,用于某次优化/迭代结果测试revision.kind = workspace,用于当前未保存编辑器内容测试PromptExamplerevision.kind = workspace,asset/favorite 来源放入 metadata,不伪装成 asset-versionmetadata.promptAssetmetadata.promptAssetmetadata.promptAssetFavoritePrompt.content 作为旧服务和旧 UI 的正文 fallbackPromptContentVersionexamplessourcePromptImageRef.kind = 'asset'workspace-current 新示例workspace-current 可以继续读取PromptAsset / reproducibility 投影中的正文、变量和示例PromptTestRunPromptTestRun 生成 PromptExample| 模式 | 子模式 | 示例输入 | 示例输出 |
|---|---|---|---|
| basic | system | input.text | output.text |
| basic | user | parameters? | output.text |
| pro | variable | parameters | output.text |
| pro | conversation | messages + parameters? | output.text |
| image | text2image | parameters? | output.images |
| image | image2image | input.images + parameters? | output.images |
| image | multiimage | input.images[] + parameters? | output.images |
说明:
parameters 是示例运行输入,不等于资产变量定义。messages 只属于 pro-conversation 或未来对话类能力。PromptImageRef 引用,不直接塞入模型主体。promptExampleFromTestRun():成功且有输出的 run 可以生成 example;失败或无输出返回 null。PromptExample.basedOnVersionId 优先表达实际测试 revision:record -> recordId,root -> root id,asset-version -> versionId,workspace draft -> ${session.id}:draft。这是追溯线索,不是示例追加到已有收藏前的正文匹配条件。PromptAsset / reproducibility 派生展示视图PromptExample / FavoriteReproducibilityExample 兼容投影pro-conversation 当前映射到既有 pro-multi,并恢复 messages 到消息卡片metadata.promptAssetmetadata.promptAssetmetadata.promptAsset| 模式 | 子模式 | 工作区保存 | 测试结果保存 | 关键结构 |
|---|---|---|---|---|
| basic | system | 支持 | 支持 | system prompt + input/output text |
| basic | user | 支持 | 支持 | user prompt + output text |
| pro | variable | 支持 | 支持 | variables + rendered output |
| pro | conversation | 支持 | 支持 | messages + variables + output |
| image | text2image | 支持 | 支持 | prompt + output images |
| image | image2image | 支持 | 支持 | prompt + input images + output images |
| image | multiimage | 支持 | 支持 | prompt + multiple input images + output images |
历史字段映射:
| 历史字段 | 目标概念 |
|---|---|
optimizationMode: system | contract.family = basic, subMode = system |
optimizationMode: user | contract.family = basic, subMode = user |
functionMode: context | contract.family = pro |
旧 pro-multi 命名 | contract.family = pro, subMode = conversation |
imageSubMode | contract.family = image, subMode = text2image/image2image/multiimage |
目标关系:
PromptSession
├─ assetBinding.assetId? // 已保存资产;未保存为空
├─ draft // 当前工作区资产草稿
├─ optimization // 一条主优化链,可 root-only
└─ testRuns[] // 当前测试链
PromptAsset
├─ contentVersions[] // 正式资产正文版本
└─ examples[] // 从测试运行沉淀出来的示例
PromptOptimizationChain
├─ root // 原始提示词
└─ records[] // 优化/迭代输出,可为空
产品语义:
会话操作语义:
| 操作 | 语义 |
|---|---|
| 新建会话 | 创建新的运行态 draft,不覆盖当前会话 |
| 点击优化 | 创建新的会话和优化链,root 为点击时的原始提示词 |
| 点击迭代 | 在当前会话的当前优化链追加 record |
| 切换会话 | 保存当前会话,恢复目标会话,并切换到目标模式 |
| 打开资产 | 优先恢复绑定该资产的会话;没有则从资产创建会话 |
| 从历史继续 | 从历史链记录创建会话,保留来源 chain/record |
| 保存资产 | 将 session draft 沉淀为资产或资产正文版本 |
| 关闭会话 | 归档/丢弃运行态,不删除已保存资产 |
兼容策略:
session/v1/{modeKey} 先作为 implicit session 使用。useSessionManager.switchMode/switchSubMode 继续负责模式级自动保存恢复。switchSession(sessionId) 在内部复用现有保存/恢复能力,但选择的是具体 session,而不是固定 mode key。FavoritePrompt -> PromptAsset normalize 覆盖session/v1/* -> PromptSession normalize 覆盖PromptTestRun -> PromptExample 转换覆盖PromptOptimizationChain.root -> PromptContentVersion 显式保存转换覆盖PromptOptimizationRecord -> PromptContentVersion 显式保存转换覆盖PromptRecordChain -> PromptOptimizationChain 兼容转换覆盖PromptImageRef.kind = 'asset' 引用统计覆盖pro-conversation messages 恢复当前已经完成的基础顺序:
PromptAsset 类型与 core normalize 适配器。metadata.promptAsset / reproducibility 派生视图。PromptSessionRegistry 和 PromptSession normalized view 的 core 纯适配层,可把现有 session/history/test state 纳入模型。metadata.promptAsset,并保留旧可复现字段作为兼容。workspace-current 伪 example。pro-conversation messages 恢复到现有 pro-multi 工作区。下一阶段建议顺序:
pro-conversation 的完整消息编辑器和历史链可视化单独设计,不和资产应用适配层继续耦合。这样可以继续沿着“资产边界先稳住,显式 session 后置”的路径推进,避免一次性重构收藏服务、Prompt Garden、工作区和测试结果四条链路。