产物智能推荐功能设计

背景

系统已有发布中心和案例库能力，但需要用户主动创建发布页、选择产物并决定是否公开。很多会话中生成的 HTML 或 Markdown 业务产物具备沉淀价值，但用户不一定意识到，也不愿意手动整理发布。

本方案在会话完成后的工作区导出阶段，自动分析 .html / .md 产物，发现最多一个高价值成果，并在产物面板中提供一键发布到案例库的入口。

产品边界

首版只分析会话工作区中的 .html / .md 文件。
每个会话同一时间最多展示一个主推荐卡片。
推荐分析只判断业务价值，不做敏感信息或隐私风险扫描。
用户侧不展示评分数字，不展示风险提示文案。
推荐分析不生成标签，标签继续由发布中心现有标签生成逻辑处理。
不改变 Agent 的提示词和生成行为，推荐是后处理能力。
为避免模板化产物反复推荐和污染公开案例库，首版按产物结构计算模板族指纹，并在 AI 分析前过滤已推荐或已公开的同模板族候选。
案例库定位是企业业务案例库；游戏、娱乐页、纯个人内容、通用无业务指向工具、纯技术 demo、代码项目说明、README、API 文档等不推荐。
定时任务和外部接口类型对话不启用产物推荐。

用户触达

推荐卡片放在右侧或移动端「产物」Tab 顶部，位于文件统计和文件列表上方。

会话运行中默认展示电脑面板；会话完成后，如果用户没有手动切换面板，系统会自动切到「产物」Tab。因此推荐卡片会出现在用户查看产物的第一视野内。

卡片状态：

recommended：展示推荐标题、文件路径、描述、分类、推荐理由，提供「预览」「发布到案例库」「忽略」。
published：展示「已发布到案例库」「自动更新中」、最近发布时间和版本数，提供「打开案例」「撤回公开」。
retracted：展示「已撤回公开」，提供「重新公开」。
pending / failed：不展示，避免打扰用户。

「产物」Tab 可展示轻量数量标识，例如 产物 · 1。

发布与多轮更新

用户第一次点击「发布到案例库」后，系统直接创建发布中心并发布，无二次确认、无发布前编辑。

发布中心字段：

source_type=existing_session
source_session_id=当前会话
default_entry_path=推荐文件路径
auto_publish_enabled=true
public_to_board_enabled=true
name/description/category 使用推荐分析结果
publish_key 复用现有自动生成逻辑

发布后，用户后续继续同一会话时，同一路径产物自动更新案例库：

使用 source_session_id + default_entry_path 作为确定性身份。
不再调用 AI 判断主题或用途是否一致。
文件内容 hash 不变则跳过。
hash 变化则追加发布中心版本，并更新案例库最新版本。

撤回公开时：

设置 public_to_board_enabled=false
设置 auto_publish_enabled=false
保留发布中心和历史版本

重新公开时：

恢复 public_to_board_enabled=true
恢复 auto_publish_enabled=true
立即发布当前同路径最新版本

忽略规则

用户忽略某一路径后，同一会话同一路径不再推荐。
如果后续出现不同路径且达到推荐阈值的高价值产物，可以展示新的推荐。
用户撤回公开不等于忽略，只保留原卡片的重新公开入口。

模板族去重

为解决同一 Skill 或同一能力组合在多个新会话中反复生成类似产物的问题，推荐分析在候选预筛之后、AI 分析之前计算产物模板族指纹 artifact_family_hash。

模板族指纹只描述产物结构，不描述业务正文：

HTML：使用标准库解析标签结构、标题层级、主要组件数量和布局骨架，忽略正文、数字、时间、URL、文件名等变化内容。
Markdown：扫描标题层级、表格、列表、代码块、图片、链接等文档骨架，忽略正文、数字、时间、路径和标题具体文本。
HTML 与 Markdown 使用不同算法和类型前缀，例如 html:<hash>、md:<hash>。
指纹算法首版偏宽松，优先减少重复推荐；同模板下不同业务主题可能不再自动推荐，用户仍可手动发布。
指纹计算失败时降级为 null，该候选不参与模板族去重，但仍可进入 AI 分析。

候选过滤规则：

同一次分析中，多个候选属于同一模板族时，只保留预筛排序最高的候选。
用户级去重：同一用户只要曾经展示过同 artifact_family_hash 的推荐，后续不再自动推荐该模板族。
全站级去重：如果同 artifact_family_hash 当前已有推荐来源创建且仍公开到案例库的发布中心，后续所有用户都不再自动推荐该模板族。
全站级去重只压制当前仍公开的模板族；公开案例撤回或删除后，压制自然解除。
过滤发生在 AI 分析之前；如果过滤后没有候选，直接结束，不调用 AI。

计入用户级“已展示”的状态：

recommended
published
dismissed
retracted

不计入：

pending
failed
AI 分析后未达推荐阈值、未展示给用户的内部丢弃记录

artifact_family_hash 只保存在 artifact_recommendations 表，不进入前端 API 响应，不写入发布中心表。历史记录不回填；旧记录为空时不参与模板族去重。

数据模型

新增 artifact_recommendations 表，同时作为轻量 job 表。

核心字段：

user_id
session_id
run_id
workspace_manifest_key
candidate_fingerprint
entry_path
entry_sha256
suggested_title
suggested_description
suggested_category
reasons
candidate_paths
artifact_family_hash
analysis_status
recommendation_status
analysis_model
analysis_result
publish_center_id
attempt_count
max_attempts
available_at
locked_at
locked_by
last_error
analyzed_at

去重粒度为 session_id + candidate_fingerprint。candidate_fingerprint 由当前 manifest 中可推荐候选文件的路径、大小、内容摘要元数据和修改时间计算；无 .html / .md 候选时不创建推荐记录，避免早期空导出阻断后续产物推荐。推荐表保存 manifest key、候选指纹和必要摘要，不复制完整 manifest。

推荐状态：

pending
recommended
published
dismissed
retracted

后端模块

新增模块：

ArtifactRecommendationService：负责分析、发布、忽略、撤回、重新公开。
ArtifactRecommendationWorker：在 Backend 进程内轮询处理 pending 记录。
artifact_recommendations API：提供当前会话推荐查询和状态动作接口。

触发方式：

callback_service 收到 workspace_export_status=ready。
后端根据系统配置开关入队推荐分析。
Worker 读取 manifest，确定性预筛 .html / .md 候选。
AI 读取内容摘要，输出推荐结果。
前端在产物面板查询并展示推荐状态。

候选预筛：

.html 优先于 .md
最近生成或修改优先
根目录或浅层目录优先
文件名包含 report、final、summary、analysis、dashboard、index、报告、总结、分析、看板、复盘、方案 加权
排除 README、CHANGELOG、TODO、node_modules、dist、assets、components、test、demo 等明显非成果文件
最多提交 12 个候选给模型

模型输出：

{
  "recommend": true,
  "confidence": "high",
  "entry_path": "/report.html",
  "suggested_title": "能源消耗分析报告",
  "suggested_description": "围绕重点工序能耗异常给出分析和建议。",
  "suggested_category": "能源",
  "reasons": ["有完整指标和结论", "页面层次清楚，适合公开阅读"]
}

展示规则：

recommend=true
confidence 为 medium 或 high
entry_path 必须存在于候选文件内

medium 表示满足推荐门槛但亮点一般，high 表示内容和呈现都有明显亮点。只要企业业务价值、内容质量、呈现质量、完整度任一门槛不满足，必须 recommend=false。

AI 可在 recommend=false 时返回内部字段 reject_reason，后端只保存到 analysis_result，不返回前端。

分类只允许取现有发布中心分类集合，无法判断则为空或「其它」。

接口

GET /api/v1/artifact-recommendations/session/{session_id}
POST /api/v1/artifact-recommendations/{id}/publish
POST /api/v1/artifact-recommendations/{id}/dismiss
POST /api/v1/artifact-recommendations/{id}/retract
POST /api/v1/artifact-recommendations/{id}/republish

查询接口返回最多一条主推荐；没有可展示推荐时返回 null。

模型配置与开关

后台模型配置新增字段：

artifact_recommendation_model
默认值：使用后台默认轻量模型配置

推荐分析按用户有效模型配置读取该字段。

系统配置新增开关：

artifact_recommendation_enabled
默认开启

不新增环境变量，不更新 Docker Compose 配置。

前端改动

ArtifactsPanel 顶部增加推荐卡片。
桌面端和移动端复用同一组件。
发布中心列表展示推荐创建的发布中心，并带来源标识「智能推荐」。
首版不增加发布中心来源筛选。
发布、忽略、撤回、重新公开不写入聊天消息流。