From 0b9cd227d980adfa52a85e58f927a4e8f75a8a33 Mon Sep 17 00:00:00 2001 From: linshen <32978552+linshenkx@users.noreply.github.com> Date: Sat, 2 May 2026 20:16:38 +0800 Subject: [PATCH] docs(prompt-model): consolidate standardization status --- .../01-提示词数据格式标准化设计.md | 18 +++-- ...02-收藏提示词（含测试结果）后续阶段任务.md | 72 +++++++++++++------ 2 files changed, 63 insertions(+), 27 deletions(-) diff --git a/docs/workspace/prompt-data-standardization/01-提示词数据格式标准化设计.md b/docs/workspace/prompt-data-standardization/01-提示词数据格式标准化设计.md index e8b53d48..c9ea3344 100644 --- a/docs/workspace/prompt-data-standardization/01-提示词数据格式标准化设计.md +++ b/docs/workspace/prompt-data-standardization/01-提示词数据格式标准化设计.md @@ -49,9 +49,9 @@ PromptOptimizationChain - 资产正文版本链只记录用户明确保存的资产正文，不自动等于优化历史。 - 测试运行不是资产示例；只有用户明确保存测试结果时，才转成 `PromptExample`。 -### 2.3 当前落地状态（2026-04-29） +### 2.3 当前落地状态（2026-05-02） -截至 2026-04-29，标准模型已经进入“底层模型与兼容适配层已落地，显式 session 产品形态尚未落地”的阶段： +截至 2026-05-02，标准模型已经进入“底层模型、兼容适配层、收藏资产写入、示例保存、来源坐标和媒体资产维护已落地，显式多 session 产品形态尚未落地”的阶段： - `@prompt-optimizer/core` 已新增并导出 `services/prompt-model`，包含 mode、content、favorite、history、session、example 等纯类型和转换函数。 - `FavoritePrompt` 仍是收藏服务的持久化容器；`metadata.promptAsset` 是标准资产快照；`metadata.reproducibility` 是用户可编辑的变量/示例草稿；`metadata.gardenSnapshot` 只读保留来源快照。 @@ -59,14 +59,19 @@ PromptOptimizationChain - 测试结果只有在用户点击“保存为示例”时，才从 `PromptTestRun` 转成 `PromptExample` / reproducibility example。 - 现有 `session/v1/*` 仍作为隐式 session 使用，但已经能携带 `assetBinding` 和 `origin`，并通过 `useSessionManager.getPromptSession()` / hydrated session 投影到标准 `PromptSession`。 - 从收藏或 PromptAsset 应用到工作区时，会写入隐式 session 的来源和资产版本绑定；重新优化、分析、清空内容时会清理旧绑定。 +- 工作区保存、测试结果保存和更新已有收藏都通过显式保存目标面板确认；已有来源坐标只用于默认选择目标，不代表可以静默写回旧收藏。 +- 保存测试结果为示例时，示例绑定提示词资产 / 收藏；`basedOnVersionId` 和来源坐标只用于追溯，不要求当前 workspace 正文与目标资产当前正文严格一致。 +- 收藏创建 / 编辑会通过 FavoriteManager 刷新 `metadata.promptAsset`；显式更新正文时，正文变化会创建新的 content version；只追加示例时不会修改正文版本链。 - `pro-conversation` 在标准层使用 `messages`；当前 UI 仍复用既有 `pro-multi` store key，并已支持把收藏中的 messages 恢复为多消息会话。文本拼接只作为兼容降级。 +- 导入导出和媒体资产清理已经扫描 `metadata.promptAsset`、当前 reproducibility、Garden snapshot 和 legacy 结构中的图片引用。 仍未落地的部分： - 用户可见的“新建 / 切换 / 关闭 session”入口和多 session 列表。 -- 资产正文版本的完整新增、差异、冲突策略。 -- 把测试结果追加到已有资产时的正文冲突确认。 -- 媒体资产导入导出与 GC 的完整 PromptAsset 扫描。 +- 独立的资产正文版本管理 UI，例如版本差异、冲突提示、手动切换 / 合并策略。 +- 测试结果示例的更完整批量管理体验；单个测试结果保存和追加语义已落地，批量选择多个结果保存为多个 example 尚未落地。 +- 收藏详情来源分区、Garden 来源展示层级、完整会话消息可视化编辑体验仍需单独设计。 +- 当前没有未关闭的 active Trellis 任务承接这些后续项；需要继续推进时应先拆分新的 Trellis 任务。 --- @@ -289,7 +294,7 @@ type PromptRunOutput = { 约束： - example 是长期可复现示例，不是一次临时测试运行。 -- example 必须引用 `basedOnVersionId`。 +- `basedOnVersionId` 是兼容当前模型的来源 / revision 线索，不表示示例必须绑定到当前资产正文版本，也不能作为追加示例前的正文一致性门禁。 - example 可以记录输入输出，但不参与资产正文版本链。 --- @@ -519,6 +524,7 @@ type ExternalSourceSnapshot = { - 从收藏 / PromptAsset 加载工作区时，记录 `assetBinding` 和 `origin`。 - workspace 测试仍标记为 `revision.kind = 'workspace'`；如果工作区来自某个 asset/version，则把绑定信息放在 run/example metadata 中，而不是把它伪装成不可变 asset version 测试。 - 保存测试结果为示例时，通过 `reproducibilityDraft` 走收藏保存链路，不在 UI 表单里手写 `metadata.promptAsset`。 +- 测试结果保存为示例时，目标是提示词资产 / 收藏；来源坐标只用于默认选择和追溯，不要求当前 workspace 正文与目标资产当前版本正文严格一致。 | 操作 | 标准语义 | |---|---| diff --git a/docs/workspace/prompt-data-standardization/02-收藏提示词（含测试结果）后续阶段任务.md b/docs/workspace/prompt-data-standardization/02-收藏提示词（含测试结果）后续阶段任务.md index df90f380..f28c803c 100644 --- a/docs/workspace/prompt-data-standardization/02-收藏提示词（含测试结果）后续阶段任务.md +++ b/docs/workspace/prompt-data-standardization/02-收藏提示词（含测试结果）后续阶段任务.md @@ -1,5 +1,29 @@ # 通用提示词资产模型落地任务 +## 0. 校订状态（2026-05-02） + +本文是《01-提示词数据格式标准化设计》的分阶段落地清单，不对应单个 Trellis 任务。到 2026-05-02 为止，相关 Trellis 任务已经全部归档，当前没有未关闭的 active task。 + +已经随最近一轮归档任务完成并校订的范围： + +- 测试结果示例保存走显式保存目标面板，绑定来源只用于默认目标选择和追溯。 +- 示例保存是资产 / 收藏级动作，不绑定具体正文版本，也不以 workspace 正文和目标资产当前正文一致作为追加门禁。 +- 追加示例默认不修改 favorite 正文、function mode 或正文版本链。 +- 用户显式选择保存 / 更新提示词正文时，正文变化可以通过 FavoriteManager 形成新的 content version。 +- 保存目标面板已经覆盖 bound / unbound 默认模式和 create / update 切换测试。 +- PromptAsset 媒体引用的导入、导出和 GC 扫描已经覆盖新旧结构。 + +仍保留为后续范围、且目前未绑定 active Trellis 任务的主要事项： + +- 用户可见的多 session UI 与 `createSession` / `switchSession` / `archiveSession` 等显式会话操作。 +- 点击优化即创建新 normalized session / optimization chain 的运行时改造。 +- 多测试结果批量保存为多个 example。 +- 独立的正文版本管理 UI，例如版本差异、冲突提示、手动切换或合并。 +- 收藏详情来源分区、Garden 来源展示层级和完整会话消息可视化编辑体验。 +- 模式不匹配时的明确用户提示，以及部分 E2E / 回归覆盖。 + +--- + ## 1. 任务背景 本任务基于《01-提示词数据格式标准化设计》展开。后续工作不再只围绕“收藏提示词”打补丁，而是建立一个可复用的 **Prompt Asset（提示词资产）模型**，让工作区、收藏、测试结果、Prompt Garden 导入、导入导出、资产清理等路径共享同一套领域对象。 @@ -21,7 +45,7 @@ Prompt Garden 目前尚未作为用户可见能力公开，因此 Garden 兼容 1. 工作区可以保存提示词资产正文。 2. 测试结果可以保存为一个或多个真实示例。 3. 提示词资产正文有独立版本链。 -4. 示例引用正文版本，但不进入正文版本链。 +4. 示例挂在提示词资产 / 收藏下，但不进入正文版本链，也不要求和当前正文版本严格绑定。 5. `basic / pro / image` 三类模式使用同一套 `PromptContract` 识别能力边界。 6. 旧收藏、当前 workspace 可复现元数据、Garden 导入、新 `metadata.promptAsset` 并行兼容。 @@ -95,15 +119,15 @@ Prompt Garden 目前尚未作为用户可见能力公开，因此 Garden 兼容 → 新建提示词资产或追加到已有提示词资产 → 新建：正文默认取该测试结果实际使用的提示词正文 → 更新：默认只追加 example -→ 如需同步更新正文，由用户显式确认 +→ 如需创建或切换正文版本，走独立的显式版本管理动作 ``` 规则： - 新建资产时，可以同时创建正文版本和第一个示例。 - 更新资产时，默认只追加示例，不静默更新正文。 -- 每个示例都记录自己基于哪个 `contentVersionId`。 -- 多个测试结果可以一次保存为多个示例。 +- 示例保存目标是资产 / 收藏；来源 revision 可以作为追溯信息进入 `basedOnVersionId` 或 metadata，但不能要求 workspace 正文与目标资产当前版本正文一致。 +- 目标态支持多个测试结果一次保存为多个示例；当前实现已支持单个结果保存，批量选择仍是后续范围。 ### 4.3 外部来源导入 @@ -186,7 +210,7 @@ Prompt Garden 目前尚未作为用户可见能力公开，因此 Garden 兼容 - [x] 记录 session summary 列表 - [x] 把现有 `session/v1/{modeKey}` 映射成 implicit session 的标准视图 - [x] 为 implicit session 合成稳定 ID，例如 `implicit:basic-system` -- [ ] 暂不要求第一阶段暴露完整多会话 UI +- [x] 第一阶段明确不暴露完整多会话 UI；当前只把 session 作为无感来源坐标和 normalized view ### A+2. 建立 `PromptSession` normalized view @@ -210,7 +234,7 @@ Prompt Garden 目前尚未作为用户可见能力公开，因此 Garden 兼容 - [x] 保存/收藏时通过 FavoriteManager 将当前收藏刷新为 `metadata.promptAsset` - [x] 保存后 session 继续存在，并通过 `assetBinding.assetId` 指向持久化资产 - [ ] 显式 session registry 场景下创建或恢复绑定 asset 的 session -- [ ] 切换模式时仍由 session manager 负责保存/恢复运行态 +- [x] 当前隐式 session 场景下，切换模式仍由 session manager 负责保存/恢复运行态 ### A+4. 设计新建/切换/关闭会话操作 @@ -238,8 +262,8 @@ Prompt Garden 目前尚未作为用户可见能力公开，因此 Garden 兼容 - [ ] 优化成功后写入第一条 `optimize` record - [ ] 点击“迭代/继续优化”追加 `iterate` record - [x] 从现有 `PromptRecordChain` 适配到 `PromptOptimizationChain` -- [ ] 只有用户明确保存资产正文时，才从 root 或当前 record 生成 `PromptContentVersion` -- [ ] 不把旧 `PromptRecordChain.versions` 自动迁移为资产 `contentVersions` +- [x] 只有用户明确保存 / 更新资产正文时才生成或追加 `PromptContentVersion` +- [x] 不把旧 `PromptRecordChain.versions` 自动迁移为资产 `contentVersions` ### A+6. 建立测试链模型 @@ -337,26 +361,26 @@ Prompt Garden 目前尚未作为用户可见能力公开，因此 Garden 兼容 - `messages` 只属于 `pro-conversation` 或未来对话类能力。 - 图片统一通过 `PromptImageRef` 引用，不直接塞入模型主体。 - 当前已落地 `promptExampleFromTestRun()`：成功且有输出的 run 可以生成 example；失败或无输出返回 `null`。 -- `PromptExample.basedOnVersionId` 优先表达实际测试 revision：record -> recordId，root -> root id，asset-version -> versionId，workspace draft -> `${session.id}:draft`。 +- `PromptExample.basedOnVersionId` 优先表达实际测试 revision：record -> recordId，root -> root id，asset-version -> versionId，workspace draft -> `${session.id}:draft`。这是追溯线索，不是示例追加到已有收藏前的正文匹配条件。 - 如果 workspace draft 来自 asset/favorite，asset/version/favorite 来源保留在 source metadata 中，不把 workspace 测试伪装成不可变 asset-version 测试。 --- -## 阶段 E：更新已有资产时的冲突策略 +## 阶段 E：更新已有资产时的示例追加策略 -### E1. 正文一致性检查 +### E1. 示例追加确认 -- [x] 如果测试结果使用的正文与目标资产当前正文一致：直接追加 example -- [x] 如果不同：不直接追加，提示并打开保存弹窗 -- [ ] 如果测试结果来自旧版本正文：允许 example 关联旧 `contentVersionId` +- [x] 如果测试结果来自已绑定的 favorite / asset：打开保存目标弹窗并默认选中该收藏，用户确认后追加 example - [x] 如果测试结果来自未保存 session draft：以 draft-derived example 进入保存弹窗，不伪装成当前资产版本 +- [x] 不使用 workspace 正文与目标资产当前正文的严格比较来决定是否允许追加 example +- [x] 追加 example 时保留 favorite 正文、function mode 和正文版本链 ### E2. 用户选择策略 -- [ ] 默认：只追加 example，不更新正文 -- [ ] 可选：同时用测试结果正文创建新 content version -- [ ] 可选：另存为新资产 -- [ ] 禁止静默替换目标资产正文 +- [x] 默认：只追加 example，不更新正文 +- [x] 可选：通过显式保存 / 更新正文动作创建新 content version；这和示例追加是独立动作 +- [x] 可选：另存为新资产 +- [x] 禁止静默替换目标资产正文 --- @@ -516,6 +540,7 @@ PromptOptimizationChain - [x] 图片 `PromptImageRef.kind = 'asset'` 引用统计覆盖 - [x] 保存测试结果时的 asset binding / revision based-on fallback 覆盖 - [x] 收藏应用到工作区时的 PromptAsset draft、变量、图片、messages 覆盖 +- [x] 保存目标面板 bound / unbound 默认模式和 create / update 切换覆盖 ### E2E 测试 @@ -559,11 +584,16 @@ PromptOptimizationChain 6. 已收敛工作区保存语义，停止新增 `workspace-current` 伪 example。 7. 已实现测试结果保存为 example、追加到 linked favorite、刷新收藏列表、应用 example 到工作区。 8. 已实现 PromptAsset 应用适配层，并支持 `pro-conversation` messages 恢复到现有 `pro-multi` 工作区。 +9. 已实现显式保存目标面板：bound session 默认更新关联收藏，unbound session 默认新建，用户可在 create / update 之间切换。 +10. 已明确并测试：测试结果示例保存不以正文一致性作为追加门禁，只追加示例时不修改正文版本链。 +11. 已实现 PromptAsset 媒体引用的导入、导出和 GC 扫描覆盖。 下一阶段建议顺序： -1. 补完整 example 冲突选择：正文不一致时允许用户选择另存、创建新版本后追加，或只保存为新收藏。 -2. 显式 session UI 放后：当前无感 session 已能承载来源坐标，只有当产品需要多草稿切换时再做新建/切换/关闭入口。 -3. `pro-conversation` 的完整消息编辑器和历史链可视化单独设计，不和资产应用适配层继续耦合。 +1. 批量 example 管理：支持一次选择多个测试结果保存为多个 example，并补齐对应交互和测试。 +2. 独立正文版本管理：补版本差异、冲突提示、手动切换 / 合并等 UI；注意它和“保存测试结果为示例”仍是两个动作。 +3. 显式 session UI 放后：当前无感 session 已能承载来源坐标，只有当产品需要多草稿切换时再做新建/切换/关闭入口。 +4. `pro-conversation` 的完整消息编辑器和历史链可视化单独设计，不和资产应用适配层继续耦合。 +5. 收藏详情来源分区、Garden 来源展示层级、模式不匹配提示和剩余 E2E / 回归覆盖可拆成独立 Trellis 任务。 这样可以继续沿着“资产边界先稳住，显式 session 后置”的路径推进，避免一次性重构收藏服务、Prompt Garden、工作区和测试结果四条链路。