muse-agent-example/docs/系统架构/新版设计/模块设计/S02-任务运行.md

S02 任务运行

职责与对象

可靠执行与证据，不承担文学裁决。

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

公开接口

用例	输入责任	输出与后果
create_task	已授权任务合同和流程版本	持久化任务
claim_step	执行器用途和能力；点名时同时指定作者与任务ID	同一领取SQL按作者/任务过滤后申请租约，不领取其他任务；未点名的工作器沿用队列领取
设置计划提供者	装配期固定的具名执行计划提供者	仅登记来源，不读资源、不连库；任务明确创建且数据库尚无该版本时才按需发布
execute_role	冻结角色请求和预算	标准结果、终态及证据
append_event	当前尝试和有类型事件	持久化序列
control_task	作者范围、动作和预期状态	暂停、取消、恢复或新尝试
read_task	任务身份和用途	当前状态、产物和恢复依据
读取任务于	调用方同库同用途受控连接、认证作者、任务ID	不取FOR UPDATE锁的只读快照与作者核验，不提交/回滚或改变调用方隔离级别；登记写入仍用核对领取于
读取运行观察依据于	调用方受控连接、执行用途、认证作者、任务与指定尝试	单次查询返回具名技术摘要、事件/证据引用及版本哈希；核验连接角色与用途，不读取原始字节，不认证业务结果
核对领取于	调用方同库同用途受控连接、领取凭证	在短事务中锁并核任务/尝试/作用域，返回持有者快照，不改变租约或扩大范围
核对结构化交付于	当前领取、调用ID、实际用户输入、固定输出合同与待保存结构值	同事务核完整派发及最终结构化响应哈希；缺失/错调用/篡改/过期领取拒绝，不代替业务语义校验
原文服务.读取会话历史	任务、作者、父会话授权、初始请求哈希与阶段	核对固定任务与父授权，读取实际模型/工具原字节及回执；撤销、缺失、费用未决或超预算拒绝。历史读取不延长批准有效期，不创建调用

所有接口在本模块的接口.py 暴露。输入输出类型由同一公开表面导出，外部不导入私有模型或 SQL。

内部职责

运行配置的公开“列出摘要”按当前用途读取版本和实际启用指针，并复核保存哈希。结果只含宿主、版本及角色的provider/model/thinking，不回传凭据、提供方URL或本机路径。该查询和保存草案不产生启用批准。

文件	职责
接口.py	任务运行公开用例和可导入合同
模型.py	任务运行稳定对象、外壳及内部状态
存储.py	任务运行所属记录的 SQL 与版本读写
执行合同.py	宿主请求、标准事件及完成结果
任务领取.py	领取、租约、心跳和尝试身份
作用域互斥.py	同作品或来源的排他任务范围、持有者和过期写入保护
步骤执行.py	已登记步骤及检查点写入
恢复控制.py	暂停、取消、重试和未知结果
角色策略.py	角色能力、工具范围和版本冻结
模型调用.py	统一调用、明确终态及结构校验
角色会话.py	固定角色对话、会话批准下的派生回合、已存证据重放和最终结构校验
预算管理.py	额度窗口、预留、结算及未知用量
工具调用.py	工具允许集、参数和读取回执
事件记录.py	有序事件持久化与订阅依据
运行证据.py	输入输出、脱敏、暂存补交和关联
原文生命周期.py	原文授权、临时租约、完整归档、清理及中断恢复
配置版本.py	运行配置验证、启用及固定副本

完整路径及运行模板见目标文件清单，逐文件意图、边界与目标见任务运行文件设计。

实现约束

Pi 直接使用系统安装（当前版本 0.85.1），不另装旧版副本。运行配置启用时记录实际系统版本与 Node/Pi 包位置；系统升级不静默改变已有任务的冻结版本。

运行配置版本同时固定角色参数、具名提供方协议/地址、凭据引用、预算账户、计价实现版本及宿主版本；Pi另固定Node与包位置。保存草案、验证和启用分开，未装配验证器不能生成验证回执。离线合同证据只用于隔离评测配置，不能启用生产配置。

作者点名推进只接收作者与任务身份，处理器、版本和能力从任务冻结计划取得，每次最多领取一个步骤。模型步骤在领取前只读核对任务预算已登记、未停止、未过期且覆盖该角色；该预检不预留费用，不替代发送前的账户、窗口和逐调用原子复检。缺预算时拒绝推进并保留原步骤状态。

读取作者预算从任务冻结配置取得账户及实际模型角色，只读核对账户策略和已存计划的内容哈希。批准作者预算在同一任务事务中保护作者、任务状态与精确角色集合，调用登记任务预算于写入不可变计划；不另开任务写连接，不因网页刷新或同请求重放重复批准。账户的窗口政策、逐调用预留和结算继续由预算管理维护，任务批准本身不授予发送或内容采纳权限。

创建受控任务及调用方事务形式创建受控任务于同时保存任务、实际启用配置和可选预算。创建时复核预先固定的配置版本/哈希、任务角色及预算覆盖；评测模型任务必须提供预算。任何前置或预算登记失败都回滚任务、绑定及事件；不留下可领取的孤儿任务。生产生成入口也经此用例绑定配置，既有生产预算批准流程继续负责提供预算。底层登记任务预算于只参与调用方事务，不另行提交。

任务从已启用版本取得不可变绑定，绑定时核对任务角色策略和资源构建。启动装配按这一绑定创建模型执行器和角色循环；后续启用新版本不改变旧任务。请求中的提供方、模型、推理等级和工具必须与固定角色配置一致；可选输入输出合同引用须匹配已登记步骤，业务动态字段仍由任务固定Schema生成。证据保存运行配置哈希与计价版本，不保存凭据值。无凭据模板见提供方配置。

• 模型调用期间不持有领取长事务，完成写入受尝试身份和租约保护。
• 恢复复用已持久化的输出；调用未知先对账，再决定是否建立新尝试。
• 工具范围、角色模型要求和额度窗口来自冻结策略；失败不能绕过能力要求。judge 按角色合同的 judge-fixed 独立精确白名单冻结单次模型，writer/planner 保持原单模型策略；blind_judge 禁工具，实际响应模型须通过本次冻结身份校验。策略更新产生新版本，不改旧任务的冻结记录。
• 任务、检查、证据、作者决定和采纳分别记录。

运行观察读口将当前任务/步骤状态与指定历史尝试状态分列；任务重试后成功不改变旧尝试归属。摘要包含冻结流程、处理器、资源发布和角色策略版本、实际配置绑定身份/哈希，以及证据种类、结果、修订号、逐调用保存确认和事件哈希。缺配置保持空，证据中的已知资源/策略/配置哈希与任务绑定冲突时拒绝。事件只返回类型与载荷哈希，不返回文本事件载荷；输入和派发回执不充作模型响应、消费或文学效果。该读口不锁领取、不改变事务边界、不调用模型、不确认或延长raw保留。

模型发送分为准备与执行。通过角色、领取及原文授权检查后，宿主先核对协议能力、地址和凭据，并固定可序列化请求；此阶段不访问模型、不占用调用次数。准备成功后，S02 保存输入证据并预留预算；标记发送的短事务调用业务 owner 的发送复检，保存 model_dispatch 技术回执并更新发送状态，任一步失败则整笔回滚。输入证据本身不证明已发送。锁等待后重新核对租约与预算期限，事务提交后才执行已准备的请求。

标记发送事务提交是派发授权分界；此前已失效的依据拒绝发送，之后的变更不能撤销已经在途的调用。标记后发生故障时不能仅因没拿到响应就认定未发送，必须按已有对账规则处理。派发回执只保存实际请求哈希、用户输入哈希及业务 owner 返回的快照身份/哈希，不保存原文、不替代有效交付或作者采纳；历史调用没有派发回执时不补造授权。宿主不自行决定预算或绕过发送关口。

评测单元由B10在发送事务重验后提供成对的evaluation_unit_id/evaluation_unit_hash，S02仅在evaluation用途保存这两个技术字段；它们不冒充B09上下文快照，也不含答案。B10保存产物前核对这些字段与当前单元、用户输入及实际结构化交付一致。

标定比较可额外绑定calibration_gold_hash，必须与完整评测单元身份同时出现且是有效SHA-256；仍限evaluation用途。标签本身不进入派发元信息或模型请求。B10历史消费按实际S02派发中的该哈希复检原金标准。维护封存标签时可经S02的读取评测任务于在同事务只读固定evaluation用途任务，并核对作者及完成状态；不允许任意schema或绕过数据库权限。

角色会话和模型回合分开：直接角色执行通常只有一回合，Pi可根据允许工具继续有限回合。每个模型回合都走同一发送、额度、费用及证据保护；工具调用结果不是最终角色产物。角色收尾另校验固定输出结构、来源和必需回执。Pi的agent_end可能只是底层一轮结束，必须等到agent_settled并核对最终消息与S02已确认回合；不能从Pi自报模型名或SDK费用反推真实计费。

对话历史由S02从批准的初始请求、已核对模型结果和具名工具结果组装。Pi通过进程内提供方回调请求下一轮，不持有提供方凭据；内置文件/终端工具、目录自动发现、自动重试和压缩关闭。直接循环与Pi消费同一组S02回调。角色职责和动态输出合同在原文批准前固定，安装资源的代码哈希同时包含Python与Pi工具桥。

新尝试先调用登记owner的来源与结构重验，再从同一会话的完整证据重建对话。已结算模型回合和已保存工具结果只重放，不再次外发、读取或计费；旧证据保留原尝试归属，新回合引用前序回执。每轮消费继续重验当前来源和保留批准。已有派生缺完整响应、费用未决或超出原批准预算时，不以空历史重跑掩盖缺口。

同作品抽取与归并使用独立于步骤领取的作用域租约。作用域键由业务用例登记，包含用途、作品或来源和需要互斥的操作族；持有者为任务，持有代次由服务端递增。窗口步骤还须持有各自的有效尝试身份。续租、转交和释放均核对持有者与代次，旧持有者不能释放新租约。

归并写入在短事务内锁定并复核作用域持有代次、有效期和当前步骤身份，然后经B03提交完整分析版本；S02保窗口执行证据及分析引用/摘要，不作为分析业务本体的另一读取路径。接管会更改代次，旧执行器的迟到写入必须拒绝。模型调用期间不保持数据库长事务。正常结束、取消与异常过期分别有释放或接管路径；此机制保留原作品抽取互斥的行为，不以“同一步只有一个 worker”代替整个作品范围的互斥。

模型执行器从实际请求的用户输入和系统提示UTF-8字节计算user_input_hash与system_prompt_hash（SHA-256），在输入、响应和派发证据中保存；不使用调用方自报值，也不另存原文。发送事务可选择既有来源回调发送复检，或收到真实模型请求的请求复检，两者不能同时配置。后者让业务owner在外发前核对完整冻结条件，避免仅校验闭包中的预期输入。

当前交付核验要求有效领取及当前尝试。恢复和历史报告可经核对历史结构化交付于按作者、任务、原尝试与调用核验已保存的结构化交付，无须伪造当前领取；仍要求输入、派发、响应均完整，输入及输出合同/内容哈希一致。V0037在完整响应字节/临时租约复核之后，将具名调用、响应证据ID及哈希的不可变保存确认与尝试状态一起提交。历史核验不依赖尝试当前最后调用指针，后续回合在途也不使早前已保存回合失效；未确认回合仍拒绝。旧记录没有此确认时只接受原尝试最后一次已保存调用，不补造早前交付。该入口只读技术证据，不重新授权消费原文。配置验证模式从原任务绑定及实际验证回执读取；任务费用汇总覆盖所有预算预留与尝试，未知或未结算时总额为空，已有失败费用保留。哈希证据不替代原文保留授权或效果评测。

最终结构化输出只有通过固定输出合同校验时才在响应证据中保存structured_output_hash及output_schema_hash；均按排序键、无多余空白、UTF-8且拒NaN的JSON序列化计算SHA256。工具回合、仅终态检查、结构错误不带结构化完成凭据。原始响应哈希仍独立保留，结构哈希不替代原文授权。

业务登记结构化产物时经核对结构化交付于同时核当前有效领取、该尝试当前已可靠保存的调用、实际输入/派发/响应三者、输出合同哈希和结构值哈希。裸字典、普通成功终态或旧证据无此哈希都不能冒充可登记产物；不为历史调用补造结构化认证。该接缝只保护单次交付，业务模块仍负责全文覆盖、来源、位置、声音和报告版本。

协作与失败

编排定义步骤，本模块执行；基础设施注入 Pi、直接模型、文件和连接实现。

断流无终态、结构错误、预算不足或证据未落库都不能记为成功；取消后的结果不能更新当前业务。

临时敏感原文与持久证据分别处理，最长 24 小时临时租约不能自动变成长期归档。授权、归档事务与 migrating 恢复以原文证据生命周期为唯一合同；具体反例见现行用例清单，各执行环境独立取证。

验收行为

• 断流。
• 租约过期。
• 重启。
• 取消。
• 未知用量。
• 证据补交。
• 无仓库安装运行。

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

作者任务的点名推进还接受evaluation用途中的三个固定评测单元流程（执行评测.writer/judge/detector）。进程重启后，在明确推进该单元时按原评测owner装配处理器和包内计划；不在服务构建时访问数据库。生产用途拒绝评测单元。装配注入的计价供同一运行入口消费，未提供时仍使用与配置版本对应的未知计价，不把未知金额记成零。