Feat: 支持异步深度精读、图表派生资产管理及用户确认入库

[limin2199]

背景

Yuxi 当前可以通过 MinerU 等解析器提取文档正文、图片、表格和 Markdown，并形成基础分块用于检索。

但对于科研文献，仅检索原始分块仍存在以下不足：

1. 图片和复杂表格缺少可用于语义检索的准确描述。
2. 用户难以快速获得研究方法、关键结果、局限性和结论之间的结构化关系。
3. 深度精读产生的 Paper Card、图表解释、结构化表格等内容缺少统一的资产管理与来源回链。
4. 深度精读可能消耗较长时间，不适合阻塞当前对话。
5. 精读结果不应自动进入共享知识库，需要由用户确认保存位置和可见范围。

希望在 Yuxi 中增加一套由 Skill 触发、异步执行、结果可预览、用户确认后入库的深度精读能力。

目标

支持用户通过对话发起“深度精读这篇文献”。系统异步完成全文精读、图表解释和结构化结果生成，并在任务完成后通知用户选择：

• 查看精读结果
• 保存到个人知识库
• 保存到有权限的共享知识库
• 放弃本次结果

建议工作流

用户在对话中选择文献
  -> 调用 Deep Reading Skill
  -> 校验用户对原文的读取权限
  -> 创建 DeepReadingRun 异步任务
  -> 获取原始 PDF、MinerU Markdown、分块及图表资产
  -> 执行深度精读
  -> 生成 Paper Card、图表描述和结构化结果
  -> 结果以 DRAFT 状态暂存
  -> 向用户发送完成通知
  -> 用户预览并选择保存位置
  -> 校验目标知识库写入权限
  -> 建立索引并发布

任务状态建议：

REQUESTED -> QUEUED -> RUNNING -> READY_FOR_REVIEW
READY_FOR_REVIEW -> PUBLISHED | DISCARDED
RUNNING -> FAILED_RETRYABLE | FAILED_MANUAL

原始资产与派生资产

建议明确区分两类资产。

原始文档资产

由 MinerU 等解析器产生：原始图片、表格、公式、Markdown、结构化 JSON、页码、坐标、标题、原始文档分块和稳定的 asset_ref。原始资产是证据回溯的权威来源。

深度精读派生资产

由 Deep Reading Skill 或多模态模型产生：

• 图片语义描述和科研解读
• 表格结构化、翻译和字段标准化结果
• 图片局部裁剪或重点标注
• Paper Card
• 方法、结果、局限性和结论摘要
• 跨图表或跨文献比较结果

派生资产必须保存来源关系，不能替代原始资产。

DerivedAsset
  id
  document_id
  document_version_id
  derived_from_asset_ref
  supporting_segment_ids
  artifact_type
  content
  storage_ref
  generated_by
  model_version
  skill_version
  review_status
  visibility_scope
  created_by
  created_at

建议支持 DESCRIBES、DERIVED_FROM、CAPTION_OF、INTERPRETS、SUMMARIZES、REFERENCES 等关系。

相同资产应通过 SHA-256 或稳定 asset_ref 去重。只有裁剪图、翻译表、标注图等发生内容变化的结果，才保存为新的派生资产。

检索设计

MinerU 分块和深度精读结果不建议写入同一个无差别索引，建议抽象为两个独立的信息源：

DocumentSource
  原始分块、页码、图片、表格和 asset_ref

DeepReadingSource
  Paper Card、图表描述、方法、结果和局限性

统一检索入口可以根据查询意图路由：

• 查询原文、数值、页码或具体图表：优先检索 DocumentSource
• 查询论文结论、方法、局限性或图表含义：优先检索 DeepReadingSource
• 精读结果被召回后：必须通过 segment_id 或 asset_ref 回链原文

推荐返回结构：

{
  "content": "图表或精读内容",
  "source_type": "deep_reading",
  "document_id": "doc_xxx",
  "supporting_segment_ids": ["seg_xxx"],
  "supporting_asset_refs": ["asset://.../figure-3"],
  "page_numbers": [7],
  "review_status": "DRAFT"
}

如果 Agent 支持多模态输入，可以根据 asset_ref 获取短时授权链接，将原始图片与检索到的文字描述共同交给模型。

Skill 与后端职责

共享 Skill 负责识别用户选择的知识库和文档、发起精读任务、查询任务状态、展示结果并引导用户选择保存位置。

后端服务负责权限校验、异步任务调度、文件和解析资产读取、草稿暂存、幂等控制、发布、索引和审计日志。Skill 不应直接写 PostgreSQL、Milvus、MinIO 或 Neo4j。

建议提供受控工具或 API：

start_deep_reading
get_deep_reading_status
preview_deep_reading_result
publish_reading_artifacts
discard_deep_reading_result

幂等与缓存

建议用 document_version_id + reading_profile + skill_version + model_version + language 生成幂等键。同一版本文献使用相同配置重复精读时可以复用已有结果；用户明确要求重新生成时，再创建新的 DeepReadingRun。

权限要求

1. 用户必须拥有原文读取权限，才能发起精读。
2. 精读草稿默认只对任务发起人可见。
3. 保存到共享知识库前，必须校验用户的写入权限。
4. 派生资产继承原文档的访问边界，不能通过发布精读结果扩大原文权限。
5. 短时图片链接必须校验用户、知识库和有效期。
6. 任务、模型调用、预览和发布行为需要保留审计记录。
7. 删除或撤销原文权限后，相关精读内容也应停止提供原文回链。

MVP 建议范围

1. 从 Yuxi 知识库选择一篇已解析文档。
2. Skill 创建异步精读任务。
3. 读取原始 PDF、Markdown、分块和图表资产。
4. 生成 Paper Card、图表描述及来源映射。
5. 结果以 DRAFT 状态暂存。
6. 完成后通知用户预览。
7. 用户确认后保存到个人或共享知识库。
8. 检索结果能够回链至原始页码、分块和图表。

跨文献比较、知识图谱构建和正式知识发布可以放到后续阶段。

验收标准

• 用户可以通过对话对指定文献发起深度精读
• 对话不会被长时间任务阻塞
• 任务具有明确状态、进度和失败原因
• 精读结果在用户确认前不会进入共享检索
• 用户可以预览、发布或放弃结果
• 发布操作校验个人或共享知识库写入权限
• 图表描述可以被语义检索召回
• 每个图表解释能够回链到原始 asset_ref
• 每项精读结论能够回链到原始分块或页码
• 原始资产与派生资产不会被重复存储
• 重复任务支持幂等复用
• 全部生成、预览和发布行为具有审计记录

非目标

本 Feature 暂不要求：

• 自动把精读内容作为已验证事实发布
• 用派生图表替代原始图表
• 将所有历史文献自动执行高成本深度精读
• 强制绑定某一种 Deep Reading 工具
• 将原始分块与精读结果混入同一个无状态索引

相关设计

该功能可以作为 Yuxi InformationSource 抽象的扩展：原始文档与深度精读结果分别作为独立信息源，由 Agent 统一路由和编排。

Related:

• RFC: 关于知识库与信息源的架构设计 #697
• Feat: 知识库api的异步改写 #342

[limin2199]

Implementation constraints

为便于将该 Feature 拆分为可交付任务，建议 MVP 与后续实现遵守以下约束。

1. 不可变来源与版本

• 每个精读结果必须绑定不可变的 document_version_id，不得仅绑定逻辑文档 ID。
• DeepReadingRun 必须记录 skill_version、model_version、reading_profile、输入内容哈希和创建时间。
• 派生资产需具备 artifact_version、supersedes_artifact_id 与 source_hash；原文重新解析时不得静默覆盖既有结果。

2. 草稿、发布与撤回

• 默认检索仅返回 PUBLISHED 结果；DRAFT 仅可由任务发起人或被显式授权的审核者预览。
• 发布、撤回、删除和原文权限撤销必须作为状态机事件处理，并同步使对应检索投影和短时访问链接失效。
• 精读结果发布到共享知识库时，不能扩大源文档的可见范围。

3. 模型与数据边界

• 每个知识库应可配置允许使用的 LLM/VLM 提供商、模型和数据出境策略。
• 调用外部模型前必须执行知识库级策略校验，并记录模型、提供商、时间、输入资产范围和调用结果摘要。
• 对禁止外发的文献，任务只能路由到本地或已获批准的私有模型。

4. 异步任务治理

• 任务必须支持取消、超时、有限次数重试、失败原因、幂等复用和断点恢复。
• 应提供按用户或组织维度的并发上限、队列优先级及单任务成本或配额保护，避免大量精读任务相互挤占模型资源。

5. asset_ref 契约

• asset_ref 必须由解析资产层稳定生成，并能解析为经过权限校验的短时访问链接。
• 每条图表解释必须保留 asset_ref、页码、坐标或 segment_id 至少一种可验证回链；派生图不能替代原始资产。

6. 建议分期

1. P1：异步任务、草稿预览、个人知识库发布和基本审计。
2. P2：派生图表资产、稳定 asset_ref 和来源回链。
3. P3：双信息源路由、共享发布、多模态检索与跨文献能力。

[xerrors]

目前 Agent 的基础能力已经能够覆盖你的基础诉求。从知识库选择文档精读后形成资产保存到用户个人目录。

当前 Yuxi 已经支持从知识库下载文件，调用 OCR 工具，写入文件到工作区。