muse-agent-example/docs/系统架构/新版设计/模块设计/B09-上下文.md

B09 上下文

职责与对象

一次任务真正允许且实际使用的材料集合。

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

公开接口

用例	输入责任	输出与后果
authorize_scope	作者身份、任务目标、用途和选择	只能被收窄的读取范围
search	冻结范围和查询意图	合法候选及省略原因
assemble	必读、预算和固定绑定	角色所需材料
freeze	已执行探索、来源和投影	不可变快照和哈希
replay	快照、原读取身份和当前授权	可回读材料或明确失效
check_dependencies	来源、结构、策略和事务上下文	当前有效性及锁定依据

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

内部职责

文件	职责
接口.py	上下文公开用例和可导入合同
模型.py	上下文稳定对象、外壳及内部状态
存储.py	上下文快照、检索索引及台账的 SQL 与版本读写
任务范围.py	作品、用途、时点和来源权限
来源读取.py	按业务公开接口读取固定来源
声音材料.py	经B06读取已认可声音，冻结身份/用途投影并核逐键材料
混合检索.py	关键词与向量两路倒数排名融合
材料装配.py	必读、预算、取舍及字段投影
探索回放.py	按同一范围重放工具读取
冻结快照.py	来源、结构、投影和消费片段
依赖校验.py	授权、撤回、结构与数据版本变化
索引维护.py	切块、嵌入、重建与陈旧拒绝

完整路径及运行模板见目标文件清单。逐文件意图、边界与目标见文件合同。

当前检索底座

基础设施向量评分提供 Python 余弦相似打分，混合检索负责倒数排名融合。当前不依赖 pgvector 或外部嵌入服务；旧逐文件设计中的 pgvector 是历史目标，代码注释里的“裁决 A”因缺原文不作为现行决定依据。

实现约束

• 预组装、探索、回放和采纳复检使用一致范围，不能仅保护预组装。
• 来源数据经各业务公开接口取得，动态字段由 S04 投影；检索只能在已授权集合内缩小。
• 专名和数字有确定性检索路径，向量质量以中文样例验证。
• 方法索引指纹覆盖版本身份、实际文本、向量和嵌入器身份，并复检当前方法版本集合、确认提案语料及来源授权；不只比较行内自报哈希。检索复用本次核验的同一份载荷，不二次读入另一份索引。
• 索引及台账在同一事务替换，并发重建串行；来源经 B04 公开接口读取，不以方法列表页数量上限截断全集。重建不改正式方法，旧指纹或失效来源明确拒绝，不自动改写旧台账以冒充新鲜。
• 实际入选、省略、版本、片段和模型消费有记录；历史可重读不代表仍可用于新任务。消费登记复核派发回执的快照指纹与不可变逐键片段，和检查当前可发送性分开；新派发、恢复及采纳仍复检当前依据。
• 方法授权随任务范围的 methods 冻结，包含绑定身份、方法及版本身份、目标、材料键、材料哈希、有效结构哈希及 S04 投影版本；新绑定不能混入旧任务。两种用途取自冻结任务，不从材料反推。缺少结构或投影身份的旧方法范围不能继续使用，须重新授权。
• 快照复用 frozen_scope 与 source_bindings，只有预算入选的方法记入来源绑定。绑定的数据版本、有效结构哈希及真实 S04 投影版本必须与授权一致；逐键片段另按材料哈希核对，不用固定标签冒充投影版本。
• 方法材料的标题与证据取自绑定版本的确认提案，不混入后续提案。停用、释放、重绑、来源用途撤权或材料变化均阻断旧范围的回放与使用；当前版本指针前进不等于固定绑定自动升级。
• 装配记录保存逐键字符区间 [开始, 结束)；区间按入选顺序覆盖全文及分隔符。冻结按键取出方法全文精确比对，不以全文中包含某段文字代替材料归属校验。
• 模型发送保护在 S02 标记发送的同一短事务核对实际输入、冻结快照与方法依据；通过 B04/B03/S04 公开用例保护方法状态、原绑定、来源授权与字段策略，锁不跨模型调用。提交前的停用、释放、撤权或策略收紧与发送授权明确排序，不以早先只读检查代替发送关口。
• 模型候选采纳事务内按候选绑定的快照核对作者、作品与方法依据，并将依据保护到事务结束；依据失效则不写正文。方法状态采用当前有效性语义：同一绑定合法重新启用后可重新核验，但不会自动重跑失败任务；是否采纳仍需作者明确决定。

已确认作品声音的消费合同

写手任务通过B06公开接口冻结本书已确认声音，voice为固定声音身份或明确的null（尚无声音）；不读取未决提案，也不把新声音混入已冻结任务。声音绑定包含版本ID/revision、原内容哈希、有效结构哈希、当前S04投影版本及实际指导材料哈希，投影沿任务内容用途与执行用途计算。样张全文不进入写手请求，只发送投影后的叙述指导、已有字面依据的口癖和保护表达；声音指导不是人物事实、必须命中词表或规则已激活证明。

已有声音作为必读材料整项参与预算，放不下明确失败而非截断或静默省略；无声音不追加占位指导，不改变原写手材料。冻结时逐键核对真实材料与唯一来源绑定，不接受把指导搬到别的材料键或自报版本。声音变化、来源撤权或投影收紧使旧快照当前失效；null后首次确认同样要求重新授权。

回放、恢复、新发送和候选采纳均重验同一声音身份。新发送与采纳在短事务经B06保护当前指针、真实来源授权和S04策略，声音确认使用相同的作品级锁；包括首次确认与无声音发送之间的排序。锁不跨网络调用；已合法发送的历史快照及交付不因后来声音变化而被篡改，但旧候选不能跳过当前依据复检。

协作与失败

正文ABC回放资料由维护发布入口经B09封存，评测角色不直读正式业务表。封存输入只声明作品、目标章、历史文稿版本、连续基线数量和材料预算；B09经B01/B02/B05读取真实目录、已确认细纲、历史时点事实投影和原文，目标及未来章不能成为历史来源。目标正文只进入独立答案侧。S04投影明确使用evaluation/generation，剔除字段不能从其他载荷补回。

A使用连续历史基线及一般关键词补充原文，B仅使用时点卡片索引，C使用同一基线及卡片来源对应的补充原文，同时保留索引。A/C的补充码点预算相同且必须足额，C不得越过已声明历史集合回读卡来源；预算不足、缺连续基线或缺合法索引明确拒绝。检索的实际入选来源、片段和省略记录放封存依据，不将实验臂、内部身份或目标答案放入写手材料。封存是资料准备，不认证模型效果；执行仍核对封存哈希、字段策略和本次资料授权。

聚合 B01—B07 的查询和 S04 投影，S02 留痕；来源索引是派生物。

其他作品、未来章、未确认或撤回来源拒绝；必读不足返回具体缺项，不能补造材料。

验收行为

• 三阶段工具读取都拒绝越界。
• 结构用途收紧阻断旧范围的新派发与采纳，不改写已经合法派发的历史材料。
• 回放使用相同输入版本。
• 向量命中不绕过真实来源校验。

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

方法检索的空结果

混合检索只读取可用的新鲜方法索引，不自动写入规划选择。空白查询在读取索引前以CONTEXT_INPUT_INVALID拒绝。结果保留索引身份；索引无条目时empty_reason=empty_index，有索引但两路都无命中时empty_reason=no_match并给出作者可读说明。有命中时该字段为null。此合同不改变B04固定绑定材料的列表返回值。

读取前预算与摘要分页

新建任务在 source_scope 冻结 context_policy_version=2 和 context_read_budget。预算唯一默认值在 S02 上下文预算.py；输入字节与模型输出 token 分开核算。旧任务不补字段、不改回放哈希，超过部署硬上界返回 CONTEXT_POLICY_REAUTH_REQUIRED，由作者重新授权。

B09先通过 B01/B02/B05 公开元数据面检查目录数量、载荷字节和当前版本，再取得载荷。正文依赖复检不读取 document、不恢复草稿；事实当前依据检查只比正文版本与哈希，原文引文仍在事实确认入口验证。元数据大小在数据库侧计算，仅保证应用传输和物化上界，不代表数据库物理读取量相同。细纲和事实过大明确拒绝；事实工具可点名冻结范围内的有界对象集合，不把被省略材料冒充完整结果。

v2历史正文未指定结束位置时返回有界片段及 has_more/next_cursor/omitted_reason。游标绑定任务、冻结范围、正文版本及投影，不能跨任务或版本续用。S02在结果进入模型历史前分别检查单工具及累计工具字节；完整模型请求的系统提示、工具定义、输入、历史和序列化开销共同受 envelope 上界约束。读前预留和耗时使用现有工具事件持久化，恢复取该步骤最近累计量；失败读取与实际重复读取保留成本，不以进程重启清零。拒绝保留错误码、消费量和调用身份，不保存失败候选内容。

读取并核对快照 同时返回历史快照与当前依赖状态，消费入口无需重复整轮检查；发送、恢复、采纳仍分别复检当前授权。新 HTTP context-snapshots/page 使用绑定任务和用途的稳定游标，默认20、最多100条，只选择摘要字段而不读取装配正文，同页相同冻结范围与绑定只核验一次。旧无分页入口兼容保留，不静默截断。

离线机制回归见 test_上下文读取上界.py 的 NC-O07-* 用例；真实 PostgreSQL、生成合同与跨包端到端证据由集成验收记录。