cf0f4fb985
接续 88dd570，保存 W20–W24 已实现的共享接口、业务入口、迁移、工作台、测试与文档。 W20/W22/W23 保持 in_progress，W21/W24 保持 verified；此提交不宣称方法或规则正式启用、多轮返修、真实角色评测完成。 W25 新增实验、标定、逐调用交付与角色执行及其迁移/测试/索引留在实施工作树，原有私人和旧实现保留项不纳入。 验证：离线 571、前端 33 通过；PG 469 项通过、2 项浏览器未启用，2 项误带入的 W25 用例已移出本提交；最终任务与交付边界 37 项通过。make 检查、最终类型、84 项资源及 diff 检查通过。未重跑浏览器或 Pi 宿主，不以合成调用认证外部模型效果。 独立整体审查四维通过；证据保存在 R2-20260909/提交W20-W24。
88 lines
7.3 KiB
Markdown
88 lines
7.3 KiB
Markdown
# B03 资料研究
|
||
|
||
## 案例证据与参考作品归属
|
||
|
||
参考来源可在导入时登记稳定的reference_work_ref，保存于不可变版本导入元信息。它是作者对来源作品的明确归属声明；同一来源已登记后不能改成另一作品，同内容重放不能改元信息，新版本默认承接既有归属。没有归属的旧资料保持未知，不凭文件数或片段数认定跨书。
|
||
|
||
读取案例证据由B03核对版本导入者、analysis或sample用途、完整内容哈希及码点范围；只有当前具备sample用途才返回原文片段，否则只返回实际定位、哈希及未知/已登记作品归属。B06不直读B03私表，也不凭请求中的许可标记扩权。同来源导入在调用方事务内串行核对身份与元信息，拒绝前不更新授权，合并用途不会因竞争丢失。
|
||
|
||
## 职责与对象
|
||
|
||
外部与私人资料、榜单观察、原文和参考作品分析。
|
||
|
||
实例归属以[总体架构](../总体架构.md)为准；结构、状态和公开外壳分别引用数据模型与接口契约。
|
||
|
||
## 公开接口
|
||
|
||
| 用例 | 输入责任 | 输出与后果 |
|
||
|------|----------|------------|
|
||
| import_source | 来源身份、内容、用途和导入选项 | 原文版本与处理任务 |
|
||
| capture_ranking | 登记来源、榜种和采集请求 | 带采集时刻及质量状态的快照 |
|
||
| start_analysis | 固定原文、范围、结构和预算 | 可恢复拆书任务 |
|
||
| read_evidence | 来源版本与位置 | 原文片段及校验信息 |
|
||
| select_analysis | 分析版本和作者用途 | 选用记录及方法或设定交接 |
|
||
| 提出参考分析 | 认证作者、稳定命令、固定来源/结构、旧源身份及内容 | S01人工保存未决分析版本，不创建研究任务或作者事实 |
|
||
| 登记模型分析 | 当前S02领取凭证 | 同事务核租约、真实任务及完整窗口后登记B03分析，检查点保存版本引用/摘要 |
|
||
| 承接历史分析 | 认证作者、既存已完成研究任务ID | 核旧检查点并原样转存B03；不修改旧检查点，不重演模型或决定 |
|
||
| 读取分析 / 列出分析 | 作者、分析ID或来源ID | 从B03唯一版本表回读完整分析及内容哈希，运行状态仍读S02 |
|
||
|
||
所有接口在本模块的接口.py 暴露。输入输出类型由同一公开表面导出，外部不导入私有模型或 SQL。
|
||
|
||
## 内部职责
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| 接口.py | 资料研究公开用例和可导入合同 |
|
||
| 模型.py | 资料研究稳定对象、外壳及内部状态 |
|
||
| 存储.py | 资料研究所属记录的 SQL 与版本读写 |
|
||
| 来源导入.py | 文件、网页、笔记和灵感导入 |
|
||
| 原文版本.py | 原文保留、来源位置及不可变版本 |
|
||
| 文本清理.py | 噪声清理候选和原文保护 |
|
||
| 分章切窗.py | 分章、窗口划分及输入漂移 |
|
||
| 榜单快照.py | 来源、时间、质量、排名及观察差异 |
|
||
| 样本选题.py | 样本比较、选题依据及选书交接 |
|
||
| 拆书分析.py | 章节、阶段、实体与写法分析 |
|
||
| 实体归并.py | 参考作品内专名、别名及歧义 |
|
||
| 分析版本.py | 完整模型成果登记、旧检查点承接及运行摘要 |
|
||
| 分析保存.py | 分析不可变存储合同、S04校验与S01未决旧卡写入 |
|
||
| 提示词/分析参考作品.md | 参考作品分析任务模板 |
|
||
| 提示词/核对实体歧义.md | 疑似同名和别名核对模板 |
|
||
|
||
完整路径及运行模板见[目标文件清单](../项目目录与文件职责.md)。逐文件意图、边界与目标见[文件合同](../文件设计/后端-B03-资料研究.md)。
|
||
|
||
## 实现约束
|
||
|
||
- 原文与分析分开版本化，清理产生对照结果而不抹掉旧原文。
|
||
- 分窗任务绑定固定输入；输入漂移不得接着向旧分析版本写结果。
|
||
- 名称与别名归并保留歧义及证据，同名不能直接合并。
|
||
- 榜单失败保留失败状态，不能让模型记忆补成实时事实；榜单名次不直接归因到最近一次 run。
|
||
|
||
## 分析持久化合同
|
||
|
||
`muse_source_analysis`是完整分析结果的唯一业务权威，版本只追加、禁止更新/删除。analysis_id全局唯一、读取按作者隔离；模型结果以真实task_id为分析ID，旧卡使用显式映射ID。原`版本ID`由来源版本及窗计划派生，只是输入基准身份，不能充唯一结果主键；同输入不同任务结果分别保留。源版本、源内容哈希、origin、完整payload及其content_hash固定，所有读取复核哈希。
|
||
|
||
origin恰为model、checkpoint_history、legacy_import。model的payload保完整窗口结果、归并和原版本摘要；只有当前分析登记步骤的合法领取可写，B03/S02同事务核租约。checkpoint_history只承接真实已完成研究任务的完整旧检查点，核窗口集合、版本摘要与来源哈希；有B03结果时只比内容后返回，不改变其origin。它是对原执行记录的承接，不认证历史模型调用符合当前策略。新旧模型结果均是参考分析，不产生作者Canonical。
|
||
|
||
legacy_import的payload保经过S04 reference_entity族校验的type/schema/content、名称/描述、旧源key/hash及明确来源定位；状态固定proposed、model_verified=false、canonical_written=false。创建和真实S01回执同事务，目标analysis_id不按内容改键。相同作者/ID异请求拒绝，不替换旧版；不生成研究任务、模型证据或确认记录。来源必须有analysis授权，版本真实且导入归属匹配；动态引用按S04完整引用需求（含嵌套字段）在同作者/同来源/同版本的真实参考分析中核目标类型和声明状态；未决卡不能充当confirmed引用。不冒充B02世界引用或已确认事实，缺引用前置时明确拒绝，不扩大确认能力。
|
||
|
||
业务回查读取原分析及其存储哈希；表单/列表和导出必须分别传uiVisible/exportable，以固定结构及当前策略投影，收紧不删除原值。返回的content_hash指未投影的存储版本，不能由裁剪视图重算；本读取入口不接受aiContext用途，不授予写手消费资格。legacy_source保留旧源身份声明，迁移对账另核PG原行，不用声明本身证明原行已迁。
|
||
|
||
CLI入口为`muse 研究 <配置> 分析 <analysis_id>`及`muse 研究 <配置> 承接 <task_id>`；检查和进度区分recorded/history_not_imported/in_progress。合法登记后任务若失败/取消，已登记结果可历史回查，但登记不等于任务完成或当前消费授权。
|
||
|
||
S02检查点是执行证据而非第二分析读取路径。运行中的完成窗/失败窗可由S02汇总；已完成分析正文从B03读取。没有B03结果的旧已完成任务显示history_not_imported，由明确的历史承接入口处理，读请求不隐式写库。已有S02窗口及摘要保持原字节语义供恢复和追溯，不用新B03内容覆盖历史检查点。
|
||
|
||
## 协作与失败
|
||
|
||
来源读取实现由基础设施注入；任务归 S02，方法候选转 B04，本书设定候选转 B02，统一检索交 B09。
|
||
|
||
来源不可用、分章歧义、窗失败和部分完成分别可见；修复仅重做选定失败范围。
|
||
|
||
## 验收行为
|
||
|
||
- 原文版本改变不覆盖旧引文。
|
||
- 分窗失败可续跑且不重复出卡。
|
||
- 同名实体不误合并。
|
||
- 选题依据与资料来源可回查。
|
||
|
||
验收入口和替换条件见[迁移与验收](../迁移与验收.md)；这些条目是目标行为，不是已通过测试的声明。
|