muse-agent-example/docs/系统架构/新版设计/文件设计/后端-S02-任务运行.md

后端-S02-任务运行：文件合同

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

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

本部分文件树

agent-example/
└── src/
    └── muse/
        └── 任务运行/
            ├── __init__.py  # Python 包身份
            ├── 事件记录.py  # 有序事件持久化与订阅依据
            ├── 任务领取.py  # 领取、租约、心跳和尝试身份
            ├── 作用域互斥.py  # 对同来源抽取等需要排他的任务范围登记互斥与持有者
            ├── 原文生命周期.py  # 原文授权、24 小时临时租约、归档和恢复状态机
            ├── 存储.py  # 任务运行所属记录的 SQL 与版本读写
            ├── 工具调用.py  # 工具允许集、参数和读取回执
            ├── 恢复控制.py  # 暂停、取消、重试和未知结果
            ├── 执行合同.py  # 宿主请求、标准事件及完成结果
            ├── 接口.py  # 任务运行公开用例和可导入合同
            ├── 模型.py  # 任务运行稳定对象、外壳及内部状态
            ├── 模型调用.py  # 固定角色、预算、明确终态与模型交付；从实际用户输入计算技术哈希，不另存临时原文
            ├── 步骤执行.py  # 已登记步骤及检查点写入
            ├── 角色会话.py  # 固定角色对话、派生回合与只读工具证据
            ├── 角色策略.py  # 角色能力、工具范围和版本冻结
            ├── 运行证据.py  # 证据关联、同哈希补交与技术元信息校验；公开同任务当前尝试的模型输入/响应交付依据
            ├── 配置版本.py  # 运行配置验证、启用及固定副本
            └── 预算管理.py  # 额度窗口、预留、结算及未知用量

逐文件合同

src/muse/任务运行/接口.py

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

src/muse/任务运行/模型.py

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

src/muse/任务运行/存储.py

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

src/muse/任务运行/执行合同.py

• 归属与种类：S02；源码。
• 意图：隔离宿主差异与业务执行。
• 职责：宿主请求、标准事件及完成结果。
• 边界：定义请求、标准事件和结果外壳；不含作品 SQL 和文学裁决。
• 目标：不同适配器输出同一可校验协议，未知终态不能算成功。
• 合同依据：专属业务职责。

src/muse/任务运行/任务领取.py

• 归属与种类：S02；源码。
• 意图：让多个执行者安全领取持久任务。
• 职责：领取、租约、心跳和尝试身份。
• 边界：短事务领取与租约，不覆盖别的尝试，不在调用期间持事务。
• 目标：同一步的有效持有者唯一，过期尝试不能提交。
• 合同依据：专属业务职责。

src/muse/任务运行/步骤执行.py

• 归属与种类：S02；源码。
• 意图：按已发布流程可靠推进任务。
• 职责：已登记步骤及检查点写入。
• 边界：只执行登记处理器与检查点；不自行决定故事采纳。
• 目标：步骤重启可辨认已完成结果，失败、等待与取消可恢复。
• 合同依据：专属业务职责。

src/muse/任务运行/恢复控制.py

• 归属与种类：S02；源码。
• 意图：避免重启或重试重复调用和重复写入。
• 职责：暂停、取消、重试和未知结果。
• 边界：重验原授权、来源和预算；未知外部结果先对账。
• 目标：已保存输出可复用，迟到结果只能留作历史。
• 合同依据：专属业务职责。

src/muse/任务运行/角色策略.py

• 归属与种类：S02；源码。
• 意图：让角色能力和工具边界不随调用方任意改变。
• 职责：角色能力、工具范围和版本冻结。
• 边界：选择已允许模型、模式与资源；不以题材配置绕过角色要求。
• 目标：任务保存明确策略版本，能力不足拒绝或等待合法替代。
• 合同依据：专属业务职责。

src/muse/任务运行/模型调用.py

• 归属与种类：S02；源码。
• 意图：把调用、终态和结构校验集中治理。
• 职责：统一调用、明确终态及结构校验。
• 边界：通过注入适配器执行；不写正式内容，不吞解析错误。
• 目标：缺完成信号、无效输出和未知用量有独立结果。
• 合同依据：专属业务职责。

src/muse/任务运行/预算管理.py

• 归属与种类：S02；源码。
• 意图：控制总消耗并保持成本记录诚实。
• 职责：额度窗口、预留、结算及未知用量。
• 边界：维护额度窗口、预留和结算；未知用量不记零，不改变角色授权。
• 目标：预算不足阻止新尝试，取消和失败仍保留实际或未知消耗。
• 合同依据：专属业务职责。

src/muse/任务运行/工具调用.py

• 归属与种类：S02；源码。
• 意图：为每次模型读取记录受控身份和证据。
• 职责：工具允许集、参数和读取回执。
• 边界：只能使用冻结工具集与任务参数范围；不开放任意 SQL 或脚本。
• 目标：读工具越界拒绝，结果保留实际来源和片段。
• 合同依据：专属业务职责。

src/muse/任务运行/事件记录.py

• 归属与种类：S02；源码。
• 意图：让断线后仍能恢复任务可观察进展。
• 职责：有序事件持久化与订阅依据。
• 边界：持久化有序事件；心跳和文本片段不能冒充完成。
• 目标：客户端按游标续接去重，未提交事件不被发送为成功。
• 合同依据：专属业务职责。

src/muse/任务运行/运行证据.py

• 归属与种类：S02；源码。
• 意图：把输入、调用、候选与失败关联为可靠证据。
• 职责：输入输出、脱敏、暂存补交和关联。
• 边界：脱敏后保存与补交；不为补日志重跑模型或伪造回执；临时敏感原文、持久证据和受控归档分别遵守原文生命周期合同，migrating 不能普通过期删除。
• 目标：缺证据时状态可见，暂存补交可验证且不重复调用；24 小时临时期限与归档恢复均可逐例验证。
• 合同依据：专属业务职责。

src/muse/任务运行/配置版本.py

• 归属与种类：S02；源码。
• 意图：区分配置编辑、验证和实际启用。
• 职责：运行配置验证、启用及固定副本。
• 边界：保存版本与回执；不从未审工作树热加载或回显凭据。
• 目标：任务冻结可回查配置，更新不会静默改变旧运行。
• 合同依据：专属业务职责。

src/muse/任务运行/__init__.py

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

src/muse/任务运行/作用域互斥.py

• 归属与种类：S02；源码。
• 意图：承接整书抽取等跨步骤共享数据的排他要求。
• 职责：对同来源抽取等需要排他的任务范围登记互斥与持有者。
• 边界：互斥范围由业务声明并经任务授权收窄；不把租约当跨域写权。
• 目标：同来源重叠归并不并行破坏数据，异常释放且旧持有者被拒绝。
• 合同依据：专属业务职责。

src/muse/任务运行/原文生命周期.py

• 归属与种类：S02；源码。
• 意图：保留完整原文的授权边界与可恢复生命周期。
• 职责：原文授权、24 小时临时租约、归档和恢复状态机。
• 边界：S02 管状态与权限；受控文件只做 IO；不能自动延长临时授权或删除迁移中唯一原文。
• 目标：先租约后字节；归档完整事务、失败保原文、未知结果可对账。
• 合同依据：专属合同。

src/muse/任务运行/角色会话.py

• 归属与种类：S02；源码。
• 意图：将角色会话与单次模型调用分开。
• 职责：固定角色对话、派生回合与只读工具证据。
• 边界：S02组装历史并限制派生；宿主不改变输入和权限，不写业务正典。
• 目标：Pi与直接循环消费同一批准、预算、来源与最终结构合同。
• 合同依据：任务运行、原文生命周期。