muse-agent-example/docs/系统架构/新版设计/文件设计/后端-B03-资料研究.md

后端-B03-资料研究：文件合同

本页从目标文件清单投影，共 16 个目标条目。测试身份与行为合同在现行用例清单；文件和目标合同不代表实现或验收已完成。

返回目录 · 完整项目树 · 现行用例清单

本部分文件树

agent-example/
└── src/
    └── muse/
        └── 资料研究/
            ├── __init__.py  # Python 包身份
            ├── 分析保存.py  # 分析不可变保存、S04校验/投影与S01未决旧卡写入
            ├── 分析版本.py  # 完整模型分析登记、旧检查点承接与运行摘要
            ├── 分章切窗.py  # 分章、窗口划分及输入漂移
            ├── 原文版本.py  # 原文保留、来源位置及不可变版本
            ├── 存储.py  # 资料研究所属记录的 SQL 与版本读写
            ├── 实体归并.py  # 参考作品内专名、别名及歧义
            ├── 拆书分析.py  # 章节、阶段、实体与写法分析
            ├── 接口.py  # 资料研究公开用例和可导入合同
            ├── 提示词/
            │   ├── 分析参考作品.md  # 参考作品分析任务模板
            │   └── 核对实体歧义.md  # 疑似同名和别名核对模板
            ├── 文本清理.py  # 噪声清理候选和原文保护
            ├── 来源导入.py  # 文件、网页、笔记和灵感导入
            ├── 样本选题.py  # 样本比较、选题依据及选书交接
            ├── 榜单快照.py  # 来源、时间、质量、排名及观察差异
            └── 模型.py  # 资料研究稳定对象、外壳及内部状态

逐文件合同

src/muse/资料研究/接口.py

• 归属与种类：B03；源码。
• 意图：让调用方通过稳定用例操作资料研究，隐藏模块内部组织。
• 职责：资料研究公开用例和可导入合同。
• 边界：唯一跨模块表面；导出输入输出合同，不暴露私有 SQL 或任意处理器。
• 目标：HTTP、CLI 和编排对相同用例得到一致验证、失败与结果。
• 合同依据：业务公开接口。

src/muse/资料研究/模型.py

• 归属与种类：B03；源码。
• 意图：把资料研究的稳定数据骨架与执行实现分开。
• 职责：资料研究稳定对象、外壳及内部状态。
• 边界：纯模型和状态合同；不联网或写库，不把题材属性写死为类字段。
• 目标：稳定外壳可校验，动态内容携带结构绑定并在所属校验链验证。
• 合同依据：稳定模型。

src/muse/资料研究/存储.py

• 归属与种类：B03；源码。
• 意图：将资料研究的数据访问与版本写入局限在本模块。
• 职责：资料研究所属记录的 SQL 与版本读写。
• 边界：只操作本模块记录并使用调用方事务；不跨 owner 写表或调用模型。
• 目标：版本读写及回滚可验证，不产生第二个独立事务结果。
• 合同依据：模块存储。

src/muse/资料研究/来源导入.py

• 归属与种类：B03；源码。
• 意图：将外部资料保存为有出处的可重读输入。
• 职责：文件、网页、笔记和灵感导入。
• 边界：只保存资料及原文版本；不确认本书事实，不改写输入冒充原文。
• 目标：文件、网页和笔记保留原始来源、哈希和导入结果。
• 合同依据：专属业务职责。

src/muse/资料研究/原文版本.py

• 归属与种类：B03；源码。
• 意图：保留分析结论所依据的原始文本。
• 职责：原文保留、来源位置及不可变版本。
• 边界：版本不可覆盖；清理和分析结果另建关系，不代替原文。
• 目标：任何旧引文仍能回到当时原文及位置。
• 合同依据：专属业务职责。

src/muse/资料研究/文本清理.py

• 归属与种类：B03；源码。
• 意图：清除可识别噪声同时保护原文语义。
• 职责：噪声清理候选和原文保护。
• 边界：输出清理候选和对照；不重写情节，不覆盖原文历史。
• 目标：合法内容和有意表达不被误删，删除项可以定位和回退。
• 合同依据：专属业务职责。

src/muse/资料研究/分章切窗.py

• 归属与种类：B03；源码。
• 意图：使长文分析可分批、可恢复且不漏范围。
• 职责：分章、窗口划分及输入漂移。
• 边界：处理确定性边界与覆盖；不把窗口号当真实章号，不调用模型补猜缺失原文。
• 目标：窗口覆盖和重叠可检查，输入漂移不能写入旧分析版本。
• 合同依据：专属业务职责。

src/muse/资料研究/榜单快照.py

• 归属与种类：B03；源码。
• 意图：把时点观察与效果推断分开。
• 职责：来源、时间、质量、排名及观察差异。
• 边界：保存来源、时刻和质量；不按最近一次 run 归因，不用模型记忆填当日数据。
• 目标：每个排名和指标可定位实际快照，获取失败明确存在。
• 合同依据：专属业务职责。

src/muse/资料研究/样本选题.py

• 归属与种类：B03；源码。
• 意图：让选题和选书有可复核依据。
• 职责：样本比较、选题依据及选书交接。
• 边界：分析样本及理由；不把相关性当因果，不自动形成正式设定。
• 目标：选择能回查样本和取舍，交接给拆书的原文身份明确。
• 合同依据：专属业务职责。

src/muse/资料研究/拆书分析.py

• 归属与种类：B03；源码。
• 意图：将长作品分析拆为可核对的版本化成果。
• 职责：章节、阶段、实体与写法分析。
• 边界：处理来源范围内的分析；模型调用走 S02，字段结构走 S04。
• 目标：新类型和字段可参与分析，分窗成果能恢复并定位原文。
• 合同依据：专属业务职责。

src/muse/资料研究/实体归并.py

• 归属与种类：B03；源码。
• 意图：降低同名、别名与关系误合并。
• 职责：参考作品内专名、别名及歧义。
• 边界：只处理参考作品内部身份判定；歧义保留，不越作品合并。
• 目标：可疑同名不会直接覆盖已有实体，归并有证据与冲突结果。
• 合同依据：专属业务职责。

src/muse/资料研究/分析版本.py

• 归属与种类：B03；源码。
• 意图：局部修复或重算分析而不抹掉旧结论。
• 职责：分窗成果、修复、重算与版本选用。
• 边界：只操作分析版本和恢复状态；不删除参考原文或暗改本书事实。
• 目标：失败窗口可单独重试，当前选用版本明确且可回查。
• 合同依据：专属业务职责。

src/muse/资料研究/提示词/分析参考作品.md

• 归属与种类：B03；源码。
• 意图：为资料研究的“分析参考作品”任务提供可版本化表达。
• 职责：参考作品分析任务模板。
• 边界：仅定义本任务提示；角色身份、字段结构、权限和预算从各自权威装配。
• 目标：模板可随发布包加载且记录哈希，不含固定作品内容或测试答案。
• 合同依据：业务提示资源。

src/muse/资料研究/提示词/核对实体歧义.md

• 归属与种类：B03；源码。
• 意图：为资料研究的“核对实体歧义”任务提供可版本化表达。
• 职责：疑似同名和别名核对模板。
• 边界：仅定义本任务提示；角色身份、字段结构、权限和预算从各自权威装配。
• 目标：模板可随发布包加载且记录哈希，不含固定作品内容或测试答案。
• 合同依据：业务提示资源。

src/muse/资料研究/__init__.py

• 归属与种类：工程；源码。
• 意图：明确安装包和模块的导入身份。
• 职责：Python 包身份。
• 边界：只声明包及必要公开导出；不读取运行数据、连接网络或启动任务。
• 目标：正常安装后可从任意 cwd 导入，导入无运行副作用。
• 合同依据：Python 包身份。

src/muse/资料研究/分析保存.py

职责：分析不可变保存、S04校验/投影与S01未决旧卡写入。

合同依据：模块设计/B03-资料研究.md。机械范围与用例绑定见目标文件清单中同路径条目。