muse-agent-example/docs/系统架构/新版设计/文件设计/后端-基础设施.md

后端-基础设施：文件合同

本页从目标文件清单投影，共 29 个目标条目。测试用例的具体规格在独立用例清单；文件和目标合同不代表实现或验收已完成。

返回目录 · 完整项目树 · 用例重写

本部分文件树

agent-example/
└── src/
    └── muse/
        └── 基础设施/
            ├── __init__.py  # Python 包身份
            ├── 凭据读取.py  # 读取受控凭据引用
            ├── 受控文件.py  # 草稿、暂存、原子写入与路径约束
            ├── 可观测性.py  # 日志、关联身份、指标和脱敏
            ├── 备份恢复.py  # PG 和草稿备份、隔离恢复及核对
            ├── 宿主/
            │   ├── Pi.py  # Pi 适配
            │   ├── Pi事件归一.py  # 将 Pi 事件转为标准调用、工具、用量和错误，不裁决业务成功
            │   ├── Pi工具桥.ts  # 将宿主工具调用转给已安装只读工具入口，绑定任务身份
            │   ├── __init__.py  # Python 包身份
            │   └── 直接调用.py  # 无工具直接调用适配
            ├── 数据库/
            │   ├── __init__.py  # Python 包身份
            │   ├── 事务.py  # 事务上下文、提交和回滚
            │   ├── 用途隔离.py  # 生产、评测、维护权限隔离
            │   ├── 迁移.py  # 顺序、校验和与迁移锁
            │   └── 连接.py  # 连接池和生命周期
            ├── 数据归档.py  # 完整数据、关系及内容哈希
            ├── 文件保留.py  # 暂存和产物保留与清理
            ├── 检索/
            │   ├── __init__.py  # Python 包身份
            │   ├── 关键词.py  # 中文关键词及全文检索实现
            │   └── 向量.py  # pgvector 查询实现
            ├── 模型/
            │   ├── ChatCompletions.py  # 协议事件和明确终态
            │   ├── HTTP传输.py  # 连接、超时、取消和读取
            │   ├── Messages.py  # 协议事件和明确终态
            │   ├── Responses.py  # 协议事件和明确终态
            │   ├── __init__.py  # Python 包身份
            │   └── 嵌入.py  # 批次、用量和嵌入模型身份
            └── 资料来源/
                ├── __init__.py  # Python 包身份
                ├── 榜单读取.py  # 已登记榜单来源获取和解析
                └── 网页读取.py  # 地址、抓取时间、状态和原文

逐文件合同

src/muse/基础设施/数据库/连接.py

• 归属与种类：基础设施；源码。
• 意图：集中管理连接与生命周期。
• 职责：连接池和生命周期。
• 边界：仅构造受控连接池；不包含业务 SQL 或硬编码凭据。
• 目标：配置引用明确、资源释放可验证，导入模块不联网。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：muse/authority/evidence/skills/访问数据库/scripts/db.py；muse/platform/db/src/muse_db/init.py。

src/muse/基础设施/数据库/事务.py

• 归属与种类：基础设施；源码。
• 意图：让跨参与者操作共用提交与回滚。
• 职责：事务上下文、提交和回滚。
• 边界：只管理事务上下文；不选择业务写入、不自行跨库补偿。
• 目标：所有参与者使用同一事务，异常不留下半套正式结果。
• 合同依据：专属接口与副作用。

src/muse/基础设施/数据库/用途隔离.py

• 归属与种类：基础设施；源码。
• 意图：防止生产、评测和维护相互取得权限。
• 职责：生产、评测、维护权限隔离。
• 边界：选择固定数据库角色与用途；内容用途不能提升运行用途。
• 目标：生产看不到 oracle，评测不能通过生产采纳入口。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：muse/platform/db/src/muse_db/init.py。

src/muse/基础设施/数据库/迁移.py

• 归属与种类：基础设施；源码。
• 意图：让结构演进可排序和核对。
• 职责：顺序、校验和与迁移锁。
• 边界：仅执行已登记迁移并检查版本、校验和及锁；不隐式跑旧库修复。
• 目标：重复执行可判断版本，错误迁移不进入已完成状态。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：muse/authority/evidence/skills/访问数据库/scripts/db.py。

src/muse/基础设施/宿主/Pi.py

• 归属与种类：基础设施；源码。
• 意图：隔离 Pi 进程和协议细节。
• 职责：Pi 适配。
• 边界：只构造受控执行并转交标准事件；不裁决文学或业务采纳。
• 目标：实际模型、期限、取消、进程失败和事件可回查。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：framework/adapters/pi/init.py；framework/adapters/pi/runner.py。

src/muse/基础设施/宿主/直接调用.py

• 归属与种类：基础设施；源码。
• 意图：为无工具角色提供同一执行协议。
• 职责：无工具直接调用适配。
• 边界：只适配直接模型调用；不自行加探索工具或变更角色模型。
• 目标：直接调用与 Pi 共用预算、证据和终态合同。
• 合同依据：专属接口与副作用。

src/muse/基础设施/模型/HTTP传输.py

• 归属与种类：基础设施；源码。
• 意图：集中处理连接、超时与取消。
• 职责：连接、超时、取消和读取。
• 边界：仅网络传输；不选业务模型、不自行采纳或改变角色授权。
• 目标：中断、错误状态和取消明确返回，不把部分响应当完整结果。
• 合同依据：模型适配。
• 非测试旧文件承接：muse/platform/llm/src/muse_llm.py。

src/muse/基础设施/模型/Responses.py

• 归属与种类：基础设施；源码。
• 意图：归一 Responses 协议而不扩散到业务。
• 职责：协议事件和明确终态。
• 边界：解析该协议事件与终态；不写数据库、不判断文学质量。
• 目标：完成信号、结构错误和用量缺失分别输出，截断不会记成功。
• 合同依据：模型适配。

src/muse/基础设施/模型/ChatCompletions.py

• 归属与种类：基础设施；源码。
• 意图：归一 ChatCompletions 协议而不扩散到业务。
• 职责：协议事件和明确终态。
• 边界：解析该协议事件与终态；不写数据库、不判断文学质量。
• 目标：完成信号、结构错误和用量缺失分别输出，截断不会记成功。
• 合同依据：模型适配。

src/muse/基础设施/模型/Messages.py

• 归属与种类：基础设施；源码。
• 意图：归一 Messages 协议而不扩散到业务。
• 职责：协议事件和明确终态。
• 边界：解析该协议事件与终态；不写数据库、不判断文学质量。
• 目标：完成信号、结构错误和用量缺失分别输出，截断不会记成功。
• 合同依据：模型适配。

src/muse/基础设施/模型/嵌入.py

• 归属与种类：基础设施；源码。
• 意图：把向量服务差异隔离在传输适配中。
• 职责：批次、用量和嵌入模型身份。
• 边界：只执行嵌入并记录模型、维度和用量；不决定来源可用性。
• 目标：批次失败和未知用量可定位，结果能绑定输入哈希。
• 合同依据：模型适配。
• 非测试旧文件承接：muse/lifecycle/context/skills/生成知识向量/scripts/embed_drafts.py；muse/platform/embed/src/muse_embed.py。

src/muse/基础设施/检索/关键词.py

• 归属与种类：基础设施；源码。
• 意图：提供 中文关键词及全文检索实现 的可替换查询实现。
• 职责：中文关键词及全文检索实现。
• 边界：只执行给定允许集合中的检索；不做上层授权或成为独立知识权威。
• 目标：结果带来源和索引版本，空结果、过期与服务失败可区分。
• 合同依据：检索实现。

src/muse/基础设施/检索/向量.py

• 归属与种类：基础设施；源码。
• 意图：提供 pgvector 查询实现 的可替换查询实现。
• 职责：pgvector 查询实现。
• 边界：只执行给定允许集合中的检索；不做上层授权或成为独立知识权威。
• 目标：结果带来源和索引版本，空结果、过期与服务失败可区分。
• 合同依据：检索实现。

src/muse/基础设施/资料来源/网页读取.py

• 归属与种类：基础设施；源码。
• 意图：取得 地址、抓取时间、状态和原文 的可验证外部输入。
• 职责：地址、抓取时间、状态和原文。
• 边界：只读取已登记来源；不凭模型记忆补数据，不授予来源内容指令地位。
• 目标：来源地址、抓取时刻、原文与失败状态可回查。
• 合同依据：资料读取。

src/muse/基础设施/资料来源/榜单读取.py

• 归属与种类：基础设施；源码。
• 意图：取得 已登记榜单来源获取和解析 的可验证外部输入。
• 职责：已登记榜单来源获取和解析。
• 边界：只读取已登记来源；不凭模型记忆补数据，不授予来源内容指令地位。
• 目标：来源地址、抓取时刻、原文与失败状态可回查。
• 合同依据：资料读取。

src/muse/基础设施/受控文件.py

• 归属与种类：基础设施；源码。
• 意图：保护私人草稿和暂存的身份、范围与原子写入。
• 职责：草稿、暂存、原子写入与路径约束。
• 边界：仅在受控根解析对象 ID；不以文件充当正式正文权威。
• 目标：应用内并发有哈希检查，外部漂移可辨认，暂存可恢复和清理。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：framework/primitives/artifacts.py；muse/authority/evidence/skills/记录运行证据/scripts/file_cas.py；muse/authority/evidence/skills/记录运行证据/scripts/raw_vault.py；runtime/runs.py。

src/muse/基础设施/凭据读取.py

• 归属与种类：基础设施；源码。
• 意图：让凭据位置稳定且与共享配置分离。
• 职责：读取受控凭据引用。
• 边界：读取受控存储引用；不记录或返回凭据给普通日志和接口。
• 目标：缺失引用明确失败，真实凭据不进入代码或普通备份。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：muse/platform/db/src/muse_db/init.py。

src/muse/基础设施/数据归档.py

• 归属与种类：基础设施；源码。
• 意图：使完整数据可以被带走并保留关系。
• 职责：完整数据、关系及内容哈希。
• 边界：按各 owner 的版本数据组装归档；不混入凭据或随意丢原文。
• 目标：原文、结构、版本、关系和决策均有清单与校验和。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：muse/content/entity/skills/ingest/备份作品抽取结果/scripts/backup_upgrade_work.py；muse/content/entity/skills/ingest/检查拆书结果/scripts/parse_export.py。

src/muse/基础设施/备份恢复.py

• 归属与种类：基础设施；源码。
• 意图：证明备份包含可恢复内容。
• 职责：PG 和草稿备份、隔离恢复及核对。
• 边界：创建快照并在隔离目标恢复；不覆盖现行库，不以文稿导出代替备份。
• 目标：恢复后原文、动态字段和关系一致，关键旅程可执行。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：muse/content/entity/skills/ingest/备份作品抽取结果/SKILL.md；muse/content/entity/skills/ingest/备份作品抽取结果/scripts/backup_upgrade_work.py；muse/content/entity/skills/ingest/重置作品抽取结果/scripts/reset_upgrade_work.py。

src/muse/基础设施/文件保留.py

• 归属与种类：基础设施；源码。
• 意图：清理不再需要的暂存同时保留追溯与恢复依据。
• 职责：暂存和产物保留与清理。
• 边界：仅按保留策略清理已可靠入库或过期的暂存；不删除作者正文；临时敏感原文、持久证据和受控归档分别遵守原文生命周期合同，migrating 不能普通过期删除。
• 目标：清理可说明对象用途与条件，缺证据状态不会丢掉唯一副本；24 小时临时期限与归档恢复均可逐例验证。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：muse/authority/evidence/skills/记录运行证据/scripts/raw_vault.py。

src/muse/基础设施/可观测性.py

• 归属与种类：基础设施；源码。
• 意图：让故障可定位且不泄漏敏感信息。
• 职责：日志、关联身份、指标和脱敏。
• 边界：记录指标和关联身份；不裁决业务结果，不采集不可见思维链。
• 目标：错误与任务可关联，凭据在输出前脱敏。
• 合同依据：专属接口与副作用。

src/muse/基础设施/数据库/__init__.py

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

src/muse/基础设施/__init__.py

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

src/muse/基础设施/宿主/__init__.py

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

src/muse/基础设施/模型/__init__.py

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

src/muse/基础设施/检索/__init__.py

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

src/muse/基础设施/资料来源/__init__.py

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

src/muse/基础设施/宿主/Pi工具桥.ts

• 归属与种类：基础设施；源码。
• 意图：把宿主工具能力接到已安装的受限服务入口。
• 职责：将宿主工具调用转给已安装只读工具入口，绑定任务身份。
• 边界：只注册与转交工具；不自带 SQL，不接任意脚本路径，不扩大任务范围。
• 目标：需要工具的任务在桥接加载失败时拒绝；生成禁工具阶段不注册工具。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：framework/adapters/pi/mcp_bridge.ts。

src/muse/基础设施/宿主/Pi事件归一.py

• 归属与种类：基础设施；源码。
• 意图：防止上游事件格式扩散到业务模块。
• 职责：将 Pi 事件转为标准调用、工具、用量和错误，不裁决业务成功。
• 边界：纯归一和错误分类；不写数据库，不把流结束擅自判成功。
• 目标：调用、工具、用量和异常转为标准事件且不丢关键身份。
• 合同依据：专属接口与副作用。
• 非测试旧文件承接：framework/adapters/pi/normalization.py。