GEOAgentArticleOptimizer/docs/superpowers/specs/2026-07-08-long-term-optimization-case-storage-design.md

长期优化案例存储设计

目标

建立一套长期存储机制，把运行过程中的原始输入、关键约束、正式产物、过程摘要、LLM 审计摘要和发布后的效果反馈沉淀为可回看、可复用、可学习的优化案例库。

这套机制第一版覆盖两类案例：

• 文章优化案例：GEO 文章优化主流程产生的案例。
• 人味文案优化案例：普通文案人味优化产生的案例。

案例库不仅是历史记录，也是效果学习库。它要能解释“当时为什么这样生成”，也要能继续记录“发布后表现如何”。

背景

当前项目已经有一部分长期数据能力：

• 文章优化会保存 article_jobs、事实卡、优化稿、QA 报告和导出路径。
• 文章导出在本地写入 data/exports/<jobId>/，Cloudflare 路径写入私有 R2。
• 发布表现校准已有发布记录、效果快照、评分 run 和校准事件模型。
• 人味文案优化当前是一次性 API，返回优化后文案、修改说明和 AI 味检查，但不落库。

现有结构能支撑文章优化，但缺少统一案例入口、跨类型列表、案例元数据、失败案例保留、LLM 审计摘要和人味文案长期记录。

范围

第一版包含：

• 统一优化案例库。
• 文章优化案例和人味文案优化案例两种案例类型。
• 优化时自动保存案例。
• 成功和失败案例都保存。
• 结果版本化，重新运行优化生成新版本。
• 案例列表和案例详情页。
• 客户、品牌、项目标签、备注等可选归属信息。
• 基础关键词搜索和常用筛选。
• 发布记录、效果快照和效果学习入口。
• 两类案例各自一套评分口径，但共用发布记录和效果快照结构。

第一版不包含：

• 用户账号、团队权限或多租户隔离。
• 平台 API 自动采集效果数据。
• 完整全文搜索引擎和搜索高亮。
• 案例硬删除。
• 人味文案优化导出文件快照。
• 默认长期保存完整 prompt/response。

核心决策

统一案例库

文章优化和人味文案优化都进入同一个优化案例库，通过案例类型筛选。

理由：

• 两类案例都包含原始输入、优化结果、LLM 审计摘要、归属信息和发布表现。
• 用户需要从一个地方检索和复用历史成果。
• 详情内容按类型拆分即可，不需要拆成两个入口。

自动保存

案例在优化流程中自动保存，不要求用户优化完成后再手动点击保存。

运行开始时创建案例记录，后续持续补充过程摘要、结果版本、审计摘要和错误状态。用户可以在完成后补标题、客户、品牌、项目标签和备注。

失败案例保留

失败的优化也保存为失败案例。

失败案例不进入正式产物区，但详情页展示：

• 原始输入。
• 失败阶段。
• 错误摘要。
• LLM 审计摘要。
• 已产生的过程摘要。

结果版本

同一案例重新运行优化时生成新的结果版本，不覆盖旧结果。

发布记录绑定结果版本，而不是绑定整个案例。效果快照继续绑定发布记录。

关系是：

优化案例 -> 结果版本 -> 发布记录 -> 效果快照 -> 校准结论

LLM 审计边界

默认长期保存 LLM 审计摘要，不保存完整 prompt/response。

审计摘要包含：

• provider。
• model。
• task。
• duration_ms。
• schema 校验状态。
• 错误摘要。
• 输入内容 hash。
• 输出内容 hash。

完整 prompt/response 只作为调试证据临时保留，并应有过期时间。第一版可以先不实现完整调试证据存储，但不能把完整 prompt/response 默认写入长期库。

数据保留边界

文章优化案例

长期保存：

• 原文标题和正文。
• 图片说明或链接。
• 目标发布平台。
• 用户补充要求。
• 事实卡。
• 最终优化稿。
• QA 报告。
• 评分结果。
• 导出文件快照。
• 过程摘要。
• LLM 审计摘要。
• 发布记录、效果快照和校准结论。

默认不长期保存：

• 每一轮草稿和 rewrite 全文。
• 完整 prompt/response。
• 前端流式事件原始流。

人味文案优化案例

长期保存：

• 原始文案。
• 优化目标。
• 修改强度。
• 补充要求。
• 发布目标。
• 优化后文案。
• 修改说明。
• AI 味检查。
• warnings。
• 过程摘要。
• LLM 审计摘要。
• 发布记录、效果快照和校准结论。

第一版不保存：

• Markdown/DOCX 导出文件快照。
• 完整 prompt/response。

过程摘要

过程摘要只保存可复盘的轻量信息：

• 阶段名。
• 开始和结束时间。
• 耗时。
• 状态。
• 失败规则或错误摘要。
• rewrite 轮次。
• 是否产出正式版本。

中间稿全文默认不保存。特殊样本保留更多过程内容可以作为后续能力。

概念模型

优化案例

统一案例库中的顶层记录。

公共字段：

• id
• case_type: article 或 human_copy
• title
• summary
• status: running、optimized、failed、archived
• customer_name
• brand_name
• project_tags
• notes
• created_at
• updated_at
• archived_at

customer_name、brand_name、project_tags 和 notes 第一版都可选，允许优化完成后补录和编辑。

案例输入

保存每个案例的原始输入和约束信息。

文章优化输入包含：

• source_title
• source_body
• image_inputs
• publish_platform
• user_instructions
• fact_card

人味文案输入包含：

• source_text
• goal
• intensity
• user_instructions
• publish_target

结果版本

一次成功优化产出的正式产物版本。

公共字段：

• id
• case_id
• version
• status
• result_summary
• process_summary
• created_at

文章优化版本包含：

• 优化稿结构化结果。
• QA 报告。
• 评分 run。
• 导出文件快照引用。

人味文案版本包含：

• optimized_text
• change_notes
• ai_taste_checks
• warnings
• 人味文案评分 run。

发布记录

发布记录绑定到某个结果版本。

字段包含：

• result_version_id
• publish_target
• url
• published_at
• status
• notes

文章优化和人味文案优化共用这套概念。

效果快照

效果快照绑定发布记录。

第一版以手动表现录入为主，保留来源字段：

• source: manual 或未来的 adapter:<name>
• window_label
• metrics
• feedback_summary
• raw_reference
• snapshot_at

与现有模型的关系

文章优化

现有 article_jobs、fact_cards、optimized_articles、qa_reports 和导出存储仍可作为文章优化的底层实现。

第一版实现时建议引入统一案例元数据层，并让文章优化创建案例时关联现有 article job：

• 新增统一案例记录。
• article_jobs 关联 case_id。
• optimized_articles.revision 对应文章案例的结果版本号。
• qa_reports 继续按文章结果版本保存。
• 现有导出路径继续作为文章结果版本的导出文件快照。

这样可以避免一次性重写文章优化主链路。

人味文案优化

人味文案优化当前接口可以保留技术路由名 POST /api/copy/renwei-optimize，但产品文案统一使用“人味文案优化”。

第一版要把一次性 API 改为自动创建案例：

• 请求开始时创建 human_copy 案例。
• 保存原始文案、优化目标、强度、补充要求和发布目标。
• 成功后保存结果版本，包含优化后文案、修改说明、AI 味检查和 warnings。
• 失败时保存失败案例和错误摘要。

发布和效果

当前发布记录以文章 job 和 revision 为核心。统一案例库需要把发布记录的业务语义提升为“绑定结果版本”。

实现可以选择兼容迁移路径：

• 为发布记录增加统一结果版本引用。
• 文章旧字段保留兼容，逐步迁移到结果版本引用。
• 新的人味文案发布记录直接绑定结果版本。

效果快照继续绑定发布记录。

页面设计

入口

新增 案例库 入口。

案例库是一个工作台页面，不是营销页。默认展示案例列表。

案例列表

默认列：

• 标题/摘要。
• 案例类型。
• 客户/品牌。
• 项目标签。
• 发布目标。
• 状态。
• 创建时间。
• 最近更新时间。

默认隐藏归档案例。

搜索和筛选：

• 关键词搜索：标题、原文摘要、结果摘要、客户、品牌、备注。
• 筛选：案例类型、状态、发布目标、项目标签、创建时间。
• 第一版不做完整全文搜索引擎和高亮。

案例详情

详情页采用共享头部 + 类型专属模块。

共享头部：

• 标题。
• 案例类型。
• 状态。
• 客户/品牌。
• 项目标签。
• 备注。
• 创建和更新时间。
• 最新结果版本。
• LLM 审计摘要概览。
• 归档/恢复操作。

共享区域：

• 结果版本列表。
• 发布记录。
• 效果快照。
• 校准结论。
• 重新运行优化。

文章优化专属模块：

• 原文标题和正文。
• 图片输入。
• 目标平台和补充要求。
• 事实卡。
• 当前版本优化稿。
• QA 报告。
• 导出链接。

人味文案专属模块：

• 原始文案。
• 优化目标。
• 修改强度。
• 补充要求。
• 发布目标。
• 优化后文案。
• 修改说明。
• AI 味检查。
• warnings。

失败案例详情：

• 显示失败状态。
• 显示失败阶段和错误摘要。
• 显示原始输入和 LLM 审计摘要。
• 不展示正式产物区。
• 允许从失败案例重新运行优化，成功后生成新结果版本。

API 设计

新增案例库 API：

GET /api/cases
GET /api/cases/:caseId
PATCH /api/cases/:caseId
POST /api/cases/:caseId/archive
POST /api/cases/:caseId/restore
POST /api/cases/:caseId/rerun

发布和效果 API：

POST /api/cases/:caseId/versions/:versionId/publications
GET /api/cases/:caseId/versions/:versionId/publications
POST /api/publications/:publicationId/performance

现有文章优化接口继续保留，但需要在运行过程中自动创建和更新案例：

POST /api/jobs/optimize-stream
POST /api/jobs
POST /api/jobs/:jobId/optimize

现有人味文案接口保留技术路径，但响应中增加案例信息：

POST /api/copy/renwei-optimize

成功响应应包含：

{
  "case": {
    "id": "case_xxx",
    "case_type": "human_copy"
  },
  "result_version": {
    "id": "ver_xxx",
    "version": 1
  },
  "result": {}
}

失败响应仍返回明确错误，同时案例库中留下失败案例。

状态规则

案例状态：

• running：优化已开始但尚未完成。
• optimized：至少有一个成功结果版本。
• failed：当前运行失败且没有成功结果版本，或最近一次运行失败。
• archived：从默认列表隐藏但仍保留记录。

结果版本状态：

• optimized：成功产出正式产物。
• failed：本次运行失败，没有正式产物。

如果一个已有成功版本的案例重新运行失败，案例仍保留历史成功版本；详情页提示最近一次运行失败。

评分口径

文章优化和人味文案优化使用不同评分口径。

文章优化评分继续关注：

• 事实一致性。
• 平台适配。
• 搜索意图匹配。
• 答案密度。
• 信任信号质量。
• 可读性。

人味文案优化评分新增独立口径，建议关注：

• 改动克制。
• 原意保真。
• 语气自然度。
• 目标匹配。
• AI 味风险。
• 互动或转化表现。

发布记录和效果快照共用结构，但评分 run 必须记录自己的 rubric 版本。

错误处理

• API 访问密钥继续沿用现有 x-api-key 规则。
• 案例创建失败时，本次优化应返回明确错误，不继续产生孤立结果。
• LLM 失败时保存失败阶段和错误摘要。
• schema 校验失败时保存校验摘要，不保存完整 response。
• 导出文件写入失败时，文章案例可以保存结构化结果并标记导出失败。
• 发布记录必须绑定存在的结果版本，否则返回 409 或 404。
• 效果快照必须绑定存在的发布记录，否则返回 404。

测试计划

单元测试：

• 案例类型校验接受 article 和 human_copy。
• 案例元数据允许客户、品牌、项目标签和备注为空。
• 人味文案结果校验包含优化后文案、修改说明、AI 味检查和 warnings。
• LLM 审计摘要不包含完整 prompt/response。
• 结果版本号重新运行时递增。

Repository 测试：

• 可以创建文章优化案例。
• 可以创建人味文案优化案例。
• 可以保存失败案例。
• 可以保存多个结果版本并按版本倒序读取。
• 发布记录绑定结果版本。
• 效果快照绑定发布记录。
• 归档案例默认不出现在普通列表。

API 测试：

• 文章优化成功后可以在案例列表查到。
• 人味文案优化成功后可以在案例列表查到。
• LLM 失败后可以查到失败案例。
• PATCH /api/cases/:caseId 可以补录客户、品牌、项目标签和备注。
• POST /api/cases/:caseId/archive 后默认列表隐藏该案例。
• POST /api/cases/:caseId/rerun 生成新结果版本，不覆盖旧版本。

组件测试：

• 案例列表展示默认列。
• 案例列表支持类型、状态、发布目标、项目标签和时间筛选。
• 文章案例详情展示事实卡、QA、导出链接和效果学习入口。
• 人味文案案例详情展示修改说明、AI 味检查和效果学习入口。
• 失败案例详情展示失败阶段和错误摘要，不展示正式产物区。

E2E 测试：

• 完成一次文章优化后进入案例库，能打开详情并下载文章导出文件。
• 完成一次人味文案优化后进入案例库，能打开详情并查看修改说明。
• 给案例补项目标签和备注后，列表可搜索或筛选到。
• 从详情页重新运行优化后出现新结果版本。
• 为某个结果版本录入发布记录和手动效果快照后，详情页显示效果学习信息。

验证命令：

npm run lint
npm test
npm run build

迁移策略

第一步先服务新产生的案例，不要求立即迁移所有旧数据。

推荐顺序：

1. 增加统一案例元数据和结果版本能力。
2. 让文章优化新请求自动创建案例，并关联现有 article job。
3. 让人味文案优化新请求自动创建案例和结果版本。
4. 增加案例列表和详情页。
5. 将发布记录和效果快照入口接到结果版本。
6. 再评估是否需要把历史 article_jobs 批量补成案例。

历史数据迁移可以延后，因为当前主要目标是让后续运行不再丢失长期资产。

不做范围

• 不做账号、角色和权限。
• 不做平台 API 自动采集。
• 不做人味文案导出文件快照。
• 不默认保存完整 prompt/response。
• 不做全文搜索引擎。
• 不做硬删除。
• 不把失败案例当作正式产物。
• 不把两类案例强行合并为同一套评分口径。