muse-agent-example/docs/系统架构/新版设计/模块设计/B03-资料研究.md

B03 资料研究

案例证据与参考作品归属

参考来源可在导入时登记稳定的reference_work_ref，保存于不可变版本导入元信息。它是作者对来源作品的明确归属声明；同一来源已登记后不能改成另一作品，同内容重放不能改元信息，新版本默认承接既有归属。没有归属的旧资料保持未知，不凭文件数或片段数认定跨书。

读取案例证据由B03核对版本导入者、analysis或sample用途、完整内容哈希及码点范围；只有当前具备sample用途才返回原文片段，否则只返回实际定位、哈希及未知/已登记作品归属。B06不直读B03私表，也不凭请求中的许可标记扩权。同来源导入在调用方事务内串行核对身份与元信息，拒绝前不更新授权；已有来源重导入的用途集合须与当前一致，不允许隐式增减。

职责与对象

外部与私人资料、榜单观察、原文和参考作品分析。

实例归属以总体架构为准；结构、状态和公开外壳分别引用数据模型与接口契约。

公开接口

用例	输入责任	输出与后果
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	逐窗分析的任务模板（发布包登记）、输出合同与执行；提取章节、阶段、实体及写法
提示词/拆书分析.md	逐窗拆书分析任务模板；随发布包登记加载，不含身份句
实体归并.py	参考作品内专名、别名及歧义
分析版本.py	完整模型成果登记、旧检查点承接及运行摘要
分析保存.py	分析不可变存储合同、S04校验与S01未决旧卡写入

当前文件以资料研究源码为准；原目标文件清单及文件合同保留历史设计目标，未消费的分析模板与人工歧义核对说明（核对实体歧义.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内容覆盖历史检查点。

协作与失败

当前仅提供 B03 榜单读取器注入协议，没有内置真实网页或榜单抓取实现；未注入读取器时 HTTP 采集端点返回 503。任务归 S02，方法候选转 B04，本书设定候选转 B02，统一检索交 B09。

来源不可用、分章歧义、窗失败和部分完成分别可见；修复仅重做选定失败范围。

验收行为

• 原文版本改变不覆盖旧引文。
• 分窗失败可续跑且不重复出卡。
• 同名实体不误合并。
• 选题依据与资料来源可回查。

验收入口和替换条件见迁移与验收；这些条目是目标行为，不是已通过测试的声明。

场景片段切片与索引

参考书原文可确定性切片入检索池，为参考改写提供场景原文语料。切片是纯函数：按段落边界聚合至目标窗长（1200～2400 字符，不足并入邻窗），切片参数与窗口清单记入窗计划哈希；同一来源版本只认一个窗计划，重算不一致即拒绝为陈旧。切片与索引是可全量重建的派生缓存（原文以 muse_source_version 为权威），禁原地改写，重建走整批替换；代次守卫随事务变更递增。

片段向量索引与方法索引同构：哈希 bigram embedder（零模型成本、确定性）、代次台账 active 唯一、检索时对不上即拒绝为陈旧。索引构建是显式命令（CLI/HTTP），不耦合导入入口；构建入口按当前具备 reference_reading 用途的来源版本全量对账，来源版本更新或用途撤回后重算。切片身份与授权解耦：授权变化只影响检索候选与材料读取，不删历史切片。

读取授权：只有来源当前具备 reference_reading 用途，其切片才进入检索候选与参考材料读取；B03 经既有 核对来源授权 核验。片段材料必须逐字取自冻结时声明的来源版本内容哈希；版本漂移即失效，不默换新版本。

用例	输入责任	输出与后果
构建场景索引	认证作者	当前授权来源的全量切片与向量索引，代次台账更新
读取场景切片	作者、slice 身份清单	切片定位、检索文本与来源版本哈希；核对 reference_reading 用途

当前用途授权

变更来源用途经S01命令回执、作者归属和来源行锁更新当前用途集合；接受空集合。请求包含source_id、expected_authorization_revision、uses和reason；授权版本独立于内容revision，无变化命令保留回执且不增加授权版本。HTTP为POST /api/v1/sources/{source_id}/authorized-uses，CLI为muse 研究 <配置> 授权 <请求JSON>。

已存在来源重导入不能增减用途，旧请求无法复活撤回的sample或analysis。返回原文须当前用途：浏览原文使用reference_reading；研究和证据读取使用analysis；案例原文只在sample允许时返回。拆书逐窗派发、恢复及分析最终登记重验授权；已外发调用保留原证据，不重发。撤回不删除来源版本、既有分析或作者决定。发生真实撤权后不得回退到只增不减授权的旧写程序。

榜单地址与读取边界

登记与采集旧登记项之前均核 URL 形状：只接受 http/https、合法主机与端口，不接受内嵌凭据、片段、控制字符或反斜杠。登记本身不解析 DNS、不访问网络，也不等于允许访问该目标。未来真实读取器必须接入受控 HTTP 出口，另行明确目标授权、重定向、DNS/目标核验、超时、退避、编码与抓取礼貌合同；当前不引入空实现或自行直连。

基础设施旧 资料来源/网页读取.py 和 榜单读取.py 两份未消费协议已移除，唯一现用榜单协议是 资料研究/榜单快照.py 的 榜单读取器。采集成功或失败时刻均取数据库 captured_at，失败不由模型或旧榜单补造。

旧 Python 辅助符号的兼容范围

分析版本.待重试窗口 和 分析版本.基准引用 已列在旧子模块 __all__，但不在域 接口.py 公开面，仓内也没有调用者。当前保留这些已可从安装包直接导入的符号及原输出，供旧 Python 调用兼容；没有证据证明存在外部使用者，也没有证据证明可以无损删除。

待重试窗口 只按冻结窗计划排出未记录结果的窗口，或读取旧 输入.拆书.重跑窗；不会检查产物哈希和漂移。当前生产恢复读取顶层 输入.重跑窗 并核 漂移重建，二者不等价，不能用该兼容函数替换生产恢复。基准引用 仅组装旧 基准版本 字典并转换 revision 为整数；不验证来源、当前许可或分析存在。当前实际消费必须通过域入口核 analysis_id、analysis_hash 和当前授权，不能以此旧字典充当证明。

实体归并.归并哈希 同样保留旧子模块导出及原摘要算法，仓内没有消费者；只摘要合并组名/类型及歧义名，不涵盖别名、窗口或证据，并截断中间摘要。它只能保持旧调用返回兼容，不得用作完整性或授权证明。当前分析登记实际用完整归并结果的 固定哈希 复检。三个符号的执行状态均为“保留”，不是“已消除”；删除重开须先核已发布 Python API 范围和外部使用方，再按具体符号确认删除及迁移方式。