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

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

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

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

本部分文件树

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  # 批次、用量和嵌入模型身份
            │   ├── 角色探针.py  # 运行配置的真实角色最小调用与资源/策略身份核对
            │   └── 计价.py  # 按部署费率文件计算已登记模型调用的美元金额
            ├── 系统运行.py  # 实际代码、资源和迁移账本兼容性核对
            └── 资料来源/
                ├── __init__.py  # Python 包身份
                ├── 榜单读取.py  # 已登记榜单来源获取和解析
                └── 网页读取.py  # 地址、抓取时间、状态和原文

逐文件合同

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

• 归属与种类：基础设施；源码。
• 意图：集中管理连接与生命周期。
• 职责：连接池和生命周期。
• 边界：仅构造受控连接池；不包含业务 SQL 或硬编码凭据。
• 目标：配置引用明确、资源释放可验证，导入模块不联网。
• 合同依据：专属接口与副作用。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

src/muse/基础设施/模型/计价.py

• 归属与种类：基础设施；源码。
• 意图：把网关费率与计费口径固定为可核对实现，不散落在业务。
• 职责：按部署费率文件计算已登记模型调用的美元金额。
• 边界：只读费率文件并按已登记协议计量；缺用量或未知协议返回未知，不推定免费、不写库。
• 目标：含缓存与独立缓存协议的用量分别计价，未知成本显式暴露。
• 合同依据：模型适配。

src/muse/基础设施/模型/角色探针.py

• 归属与种类：基础设施；源码。
• 意图：生产配置必须先有真实调用证据才允许验证启用。
• 职责：运行配置的真实角色最小调用与资源/策略身份核对。
• 边界：只发起声明角色的最小真实调用并产证据；不改配置、不替代作者批准、不生成业务内容。
• 目标：声明关闭推理却仍返回推理等不一致在验证阶段被机械拒绝。
• 合同依据：模型适配。

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

• 归属与种类：基础设施；源码。
• 意图：把向量服务差异隔离在传输适配中。
• 职责：批次、用量和嵌入模型身份。
• 边界：只执行嵌入并记录模型、维度和用量；不决定来源可用性。
• 目标：批次失败和未知用量可定位，结果能绑定输入哈希。
• 合同依据：模型适配。

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

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

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

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

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

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

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

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

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

• 归属与种类：基础设施；源码。
• 意图：保护私人草稿和暂存的身份、范围与原子写入。
• 职责：草稿、暂存、原子写入与路径约束。
• 边界：仅在受控根解析对象 ID；不以文件充当正式正文权威。
• 目标：应用内并发有哈希检查，外部漂移可辨认，暂存可恢复和清理。
• 合同依据：专属接口与副作用。

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

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

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

• 归属与种类：基础设施；源码。
• 意图：使完整数据可以被带走并保留关系。
• 职责：受控原文与草稿的字节、目录与哈希归档；数据库部分由备份恢复共同组装。
• 边界：仅恢复明确的新文件根，不混入凭据、不丢原字节；不将文件归档冒充完整数据库备份。
• 目标：原文、结构、版本、关系和决策均有清单与校验和。
• 合同依据：专属接口与副作用。

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

• 归属与种类：基础设施；源码。
• 意图：证明备份包含可恢复内容。
• 职责：PG 和草稿备份、隔离恢复及核对。
• 边界：创建快照并在隔离目标恢复；不覆盖现行库，不以文稿导出代替备份。
• 目标：恢复后原文、动态字段和关系一致，关键旅程可执行。
• 合同依据：专属接口与副作用。

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

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

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，不接任意脚本路径，不扩大任务范围。
• 目标：需要工具的任务在桥接加载失败时拒绝；生成禁工具阶段不注册工具。
• 合同依据：专属接口与副作用。

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

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

src/muse/基础设施/系统运行.py

• 归属：基础设施。
• 职责：实际代码、资源和迁移账本兼容性核对。
• 边界：不默认迁移、启用或读取私人原文；失败返回可核对原因。
• 验证：真实安装、隔离PG和浏览器证据。