第7章 上下文工程框架（一）：11 模块与优先级链
如果说 D2E 与 HDS 解决"知识从哪来、存哪去"，上下文工程框架则解决"用的时候怎么装"。它是四支柱中直接面向运行时、决定模型实际表现的相位。
7.1 模块化的必要性
把整个项目知识一股脑塞进上下文窗口，已被证明是低效甚至有害的。上下文工程框架主张"分而治之"：把上下文切成语义独立的模块，每个模块负责一类信息（如角色设定、项目约束、近期变更、相关代码、测试约定）。运行时按场景挑选模块组合，而非搬运全文。
7.2 十一模块（M1--M11）
框架定义十一个标准模块，覆盖一次典型研发会话所需的全部上下文维度：
- M1 角色与身份：定义消费主体的角色（dev/test/ops/architect）与目标。
- M2 项目概览：一句话定位、关键约束、当前阶段。
- M3 架构与边界：系统边界、核心组件、禁止触碰区。
- M4 命名与约定：命名规范、目录结构、代码风格。
- M5 依赖与版本：内外部依赖、版本锁、已知兼容坑。
- M6 近期变更：最近 N 次提交/决策，建立"短期记忆"。
- M7 历史决策（ADR）：已被决议且仍有效的架构决策。
- M8 风险与陷阱：已知故障模式、易错点。
- M9 测试与质量门：测试策略、必过门禁。
- M10 领域知识：业务规则、领域术语。
- M11 待办与缺口：当前 gaps、未决项，供前瞻相位使用。
7.3 规范表与装配约束
每个模块有规范表，规定：必填/选填、最大 token 预算、刷新频率、适用角色。规范表是投放侧的"宪法"------装配器必须在其约束内组合模块，超出预算即触发淘汰。
7.4 优先级链
当窗口预算不足时，必须决定"先保谁"。优先级链是一组有序规则，例如：M8（风险陷阱）> M4（命名约定）> M6（近期变更）> ...。优先级并非固定，而由角色与场景参数化：测试角色下 M9 升权，运维角色下 M5 升权。优先级链把"保什么、弃什么"从拍脑袋变成可解释的策略。
第8章 上下文工程框架（二）：冲突消解、淘汰与版本
8.1 冲突消解三级裁决
上下文来自多个知识单元，彼此可能矛盾。框架定义三级裁决：
- 字段级 ：同一模块内某字段冲突，以
source_ref时效性与权威性裁定（新且权威者优先）。 - 模块级：跨模块冲突（如 M7 决策与 M6 变更矛盾），以"变更优先于旧决策，但须记入 conflicts"处理。
- 全局级：涉及体系级原则冲突（如两条不可兼得的约束），升级至人在回路裁决，并写入缺口表。
三级裁决保证"矛盾不被静默覆盖"，同时把绝大多数冲突在本级内自动闭环，只在真正不可解时打扰人。
8.2 窗口淘汰策略
当所选模块总预算超过窗口上限，淘汰策略介入。它结合"LRU（最近最少使用）+ 重要度"双因子：先用 LRU 识别长期未被命中的模块，再用重要度（由优先级链给出）保命。淘汰不是删除知识，只是本次不投放，知识仍在 HDS 中可被按需召回。
8.3 版本控制（SemVer）
上下文装配本身受版本管理。模块内容变更、优先级链调整均走 SemVer：破坏性变更升主版本，向后兼容的增改升次版本，修正升修订号。版本化使"为什么这次模型表现不同"可被追溯------因为装配配方是可版本化的。
8.4 装配器（Assembler）
装配器是框架的运行时引擎：读角色与场景 → 查 HDS 拉取候选模块 → 按优先级链排序 → 按预算淘汰 → 产出 Context Pack。它是连接 HDS（沉淀）与消费主体（人/模型）的最后一厘米。
8.5 长上下文范式的冲击与回应
长上下文窗口的出现曾让人怀疑模块化的必要。但框架的立场是：窗口变长只降低了"装得下"的难度，却抬高了"装得对"的难度。噪声随窗口线性增长，信噪比随窗口恶化。因此模块化、优先级、淘汰在长上下文时代不是过时，而是更关键。装配器从"能不能放下"转向"该放哪些才最优"。
8.6 认知科学基础
框架的设计暗合认知负载理论：人的工作记忆有限，模型的"有效上下文"亦有限。把上下文模块化、按优先级投放，本质是为模型的有限认知带宽做"外部记忆管理"，使其把珍贵带宽留给真正相关的信息。这也是为何"少而准"优于"多而全"。
7.5 模块规范的字段详表（示意）
每个模块的规范表至少包含：必填项、token 预算上限、刷新频率、适用角色、冲突处理策略。例如 M8（风险与陷阱）规范：必填"触发条件 + 后果 + 规避动作"三段；预算 400 token；刷新频率"每次相关代码变更"；适用全部角色；冲突时以"最新验证者"为准。规范表的意义在于把"好的上下文长什么样"从个人经验，变成可机器执行的约束。
7.6 优先级链的实例推演
假设一次编码会话窗口预算仅容 3 个模块。角色=dev，场景=修复登录Bug。优先级链在 dev 场景下展开为：M8（陷阱）> M4（命名约定）> M6（近期变更）> M3（边界）> ...。装配器据此排序并截取前 3：M8、M4、M6。结果，与"修 Bug 最相关"的陷阱库、命名约定、近期变更被优先投放，而架构边界等被暂存。若场景换成"新功能设计"，architect 角色下 M7（决策）、M3（边界）升权，投放组合随之改变。同一知识库，因角色场景不同而呈现不同切面------这正是模块化投放相较于"整篇搬运"的本质优势。
7.7 模块间冗余与去重
模块化易引发冗余：M7（历史决策）与 M3（架构边界）可能都提及同一约束。框架要求"单一事实只在一处权威定义，他处仅引用 doc_id"，即 M3 描述边界时，对其中蕴含的决策只放 doc_id 链接，详情指向 M7。这避免了一处更新、他处失同步的经典文档病。去重规则是 front matter 之外，框架维护知识单一性的第二道防线。
8.7 冲突消解三级裁决的实例
实例：M7 记录"采用单连接超时 30s"（旧决策），M6 记录"近期改为分块上传以绕开超时"（新变更），二者在"连接模型"上矛盾。裁决过程：字段级先比对 source_ref 时效------M6 更新，故本次以 M6 为准；但模块级要求"旧决策被新变更推翻须记入 conflicts 并知会 owner"；全局级检查是否触及"不得破坏旧客户端"这条不可兼得约束------若分块破坏旧客户端，则升级人在回路。三级裁决让多数矛盾自动闭环，仅真正的硬冲突打扰人，避免了"要么全人工、要么全忽略"的二元困境。
8.8 淘汰策略的量化实例
设窗口预算 8000 token，候选模块总预算 14000。淘汰算法：先按 LRU 标记长期未被命中的模块（如 M10 领域知识近 20 次会话未引用），再按重要度（优先级链）保命。若 M10 重要度低且 LRU 命中，首批淘汰；若仍超预算，继续淘汰次低重要度模块，直至达标。关键点：被淘汰模块仅"本次不投放"，仍在 HDS，下次场景变化可即时召回。淘汰是"临时隐身"而非"销毁"，保证仓库完整性与窗口精简性的解耦。
8.9 装配器算法轮廓
装配器伪流程：输入(角色, 场景) → 查 HDS 拉取候选模块及其版本 → 套用该角色场景的优先级链排序 → 累加预算，超限触发淘汰 → 生成 Context Pack（含模块集合、版本快照、冲突处置记录、优先级链快照）→ 输出。装配器是纯函数式设计：相同输入必得相同 Pack，这使得"为什么这次模型表现不同"可被完全复现与归因------可复现性在此从知识生产延伸到了知识消费。
8.10 认知带宽的外部化管理
把上下文模块化并按优先级投放，实质是把模型的有限认知带宽当成一个需要精心管理的稀缺资源。这呼应认知心理学中的"外部记忆"概念：与其把一切塞进工作记忆，不如把可检索的外部知识作为记忆延伸。框架的工程贡献，正是为模型的外部记忆提供了一套标准化的"拣货 + 排序 + 淘汰"机制，使其把宝贵带宽留给真正相关的信息，而非与噪声搏斗。
7.8 模块粒度的权衡
模块粒度是框架的关键设计变量：太粗（如"把整个项目知识当一个模块"）则失去筛选能力，回到整篇搬运；太细（如每条约束一个模块）则装配复杂度与元数据的维护成本飙升。经验法则：模块粒度对齐"一类决策所需的最小信息集"------M8 陷阱对应"规避一类错误所需的信息"，M7 决策对应"理解一类架构选择所需的信息"。粒度合理时，装配器能以最少模块数覆盖当前场景，既精简又完整。粒度是可在实践中调参的旋钮，而非一次定死。
7.9 场景识别机制
优先级链依赖"场景"参数，场景如何识别？两类来源：显式（用户在请求中声明"我在修登录 Bug"）与隐式（由当前改动的文件、当前分支、近期提交推断）。隐式识别借助 HDS 的 deps------若本次改动落在 login 模块节点附近，场景权重自动向 M8/M6 倾斜。场景识别不必完美，只需"足够好"：宁可偶尔多投，不可关键少投。框架对场景误判的容错，来自优先级链的排序余量------即便场景识别偏差，高重要度模块仍在前列。
8.11 预算分配的优化视角
窗口预算分配可视为一个背包问题：在总预算 B 约束下，选择模块子集使"决策相关信息量"之和最大。优先级链提供的权重即各模块的信息量估值。淘汰策略本质是贪心求解：按权重降序装入，超预算则弃最末。贪心在"模块间独立"假设下近最优；当模块间有依赖（如 M7 依赖 M3），框架要求依赖模块同进同出，退化为带约束的背包。把淘汰建模为优化问题，使"保什么弃什么"从艺术变为可解释的工程决策。
8.12 装配器的可观测性
装配器不只是产出 Pack，还应产出"决策日志"：本次为何选这些模块、为何淘汰那些、冲突如何裁。日志使装配过程可观测、可复盘、可改进。当某次会话模型表现异常，第一反应是调出对应日志，而非猜测。可观测性是体系可靠性的基石------你无法改进你无法观测的东西。框架把可观测性作为装配器的内建属性，而非事后补丁，体现了对工程纪律的坚持。
8.13 与提示词工程的边界
须明确：上下文工程框架 ≠ 提示词工程。提示词工程优化单次 prompt 的措辞与结构；上下文框架优化"系统级、跨会话、按角色"的上下文供给。二者互补：框架决定"给模型喂什么背景"，提示词决定"就这次任务怎么问"。混淆二者会导致要么忽视系统级供给（只调 prompt 却喂错背景），要么过度工程化（为每个 prompt 都重搭框架）。正确关系：框架是底层供给管线，提示词是上层交互语言。
8.14 长上下文下的再定位
重申一个常被误读的点：长上下文窗口的普及，不削弱框架价值，反而强化它。原因有三：①窗口越长，噪声越易灌入，越需模块化筛选；②窗口越长，成本越高，越需淘汰保精简；③窗口越长，模型越易"顾此失彼"，越需优先级链引导注意力。框架从"能不能放下"转向"该放哪些最优"，任务不仅没消失，反而更精细。这是体系对技术演进的稳健姿态：锚定不变的原理（信噪比、带宽管理），灵活适配变化的实现（窗口大小）。
8.15 一个完整的装配推演
把框架的各机制串成一次完整推演。场景：dev 角色修复"支付回调超时"Bug，窗口预算 6000 token。装配器流程：①读 role=dev、scene=fix_payment_timeout；②沿 HDS deps 定位 payment 模块相关单元；③按 dev 场景优先级链排序：M8（陷阱：回调幂等性）> M4（命名约定）> M6（近期变更：上周改了超时配置）> M3（边界）> M5（依赖）...；④累加预算，M8(800)+M4(600)+M6(700)=2100，继续加 M3(900)=3000、M5(1100)=4100、M7(700)=4800、M10(500)=5300，再加 M2(500)=5800 接近上限，停止；⑤冲突检查：M6 近期变更与 M7 旧决策无矛盾，放行；⑥产出 Pack 含上述模块及版本快照。最终模型拿到的是"恰好覆盖当前 Bug 修复所需"的精简上下文，无一处冗余、无关键缺失。
8.16 优先级链的参数化设计
优先级链不是写死的列表，而是一组可参数化的规则。参数包括：角色权重（dev/ops/test/architect 各自提升哪些模块）、场景权重（fix_bug 提升 M8、new_feature 提升 M7）、时效权重（近期变更自动加权）。参数化使同一知识库能"因时因地"呈现不同切面，且调整只需改参数而非改架构。参数本身存于 front matter 或独立配置，受版本管理------优先级链的演化也被追溯，回答"为何这次投放组合不同"同样可归因。
8.17 淘汰策略的人因考量
淘汰虽是算法，但涉及人因：被淘汰的模块若恰是某人习惯依赖的，会产生"模型这次怎么没给我看那个"的困惑。缓解：Pack 中附带"本次未投放模块清单及原因"，让人知晓缺失而非疑惑；同时保留"一键召回某模块"的交互，使人能在会话中主动拉取被淘汰内容。淘汰是"默认精简"，而非"强制剥夺"------给人留后路，是框架务实性的体现，也避免了"全自动"带来的失控感。
8.18 冲突消解的审计价值
三级裁决留下的处置记录，本身是高价值的审计资产。当事后追问"当时为何采用新变更而非旧决策"，只需查 conflicts 表的处置说明，无需翻聊天记录。冲突处置记录使"决策演变"可被审阅，这在强监管或高后果场景（金融、医疗）尤为关键。框架把冲突从"麻烦"变为"可追溯的决策日志"，再次体现"把原则写入流程"的复利------每一次正确的冲突处理，都在积累组织的可审计性。
8.19 装配器的版本与可复现
装配器自身及其优先级链配置均受 SemVer 管理。一次会话的 Pack 同时记录装配器版本与配置版本，使"同一知识库、不同时间投放结果不同"可被完全解释。可复现性的意义超越调试：它使 A/B 比较不同装配策略的效果成为可能------固定其他变量，仅换装配器版本，观察命中率变化，从而科学调参。框架把"上下文投放"从手艺升级为可实验的工程活动。
8.20 框架的采纳门槛与渐进路径
框架看似庞大，但采纳可渐进：最小可用是先定义 M1--M3 三模块（角色、概览、边界），手工维护，验证价值；再补 M4--M8 自动化；最后上优先级链与淘汰。不必一步到位。采纳门槛低，是因为框架的核心是"思想"（模块化、优先级、可信标注），工具只是思想的载体。组织可先用最简手段（甚至 Excel 管模块）实践思想，再随痛点升级工具------思想的先行，是框架对"过度工程"批评的最好回应。
8.21 模块内容的来源治理
模块内容不是凭空生成，而来自 HDS 的知识单元。因此模块的"质量天花板"由 HDS 决定------框架只负责"选与排"，不负责"造"。这一分工的启示：若投放效果不佳，先查 HDS 是否失真（源问题），再查框架是否选错（装配问题），莫要本末倒置。框架与 HDS 是上下游责任清晰的协作，而非互相甩锅的灰色地带。来源治理的明确，使"上下文不好"的归因有迹可循，避免盲目调参。
8.22 多场景叠加的处理
真实会话常叠加多场景（"在修复登录 Bug 的同时，顺带做次重构"）。框架处理叠加：对各场景分别生成优先级链，再做加权合并（如 fix_bug 的 M8 权重 + refactor 的 M7 权重），形成复合排序。叠加处理逻辑使框架贴近真实工作的复杂性，而非假定每次会话单一目标。复合排序的权重可调，使"主次场景"的偏好被显式表达，而非被模型自行猜测。
8.23 装配器的失败降级
装配器可能失败（如 HDS 不可达、角色未定义）。框架规定失败降级而非崩溃：HDS 不可达时，回退到最近缓存的 Pack；角色未定义时，用通用默认链。降级保证"至少给点上下文"，而非"一点不给"。降级记录进日志供后续修复。优雅降级是系统可靠性的体现------局部故障不应演变为整体失能，这一原则在上下文供给这种关键路径上尤为重要。
8.24 与长上下文的成本权衡
长上下文降低了"装得下"的门槛，却抬高了"用得起"的成本。框架的淘汰策略在成本维度更有价值：即便窗口容得下全量，主动淘汰低价值模块仍可省下推理 token 与延迟。成本权衡使框架在"效果"与"开销"间提供可调旋钮，而非无脑灌满。在按 token 计费的商业模型下，这一节省直接转化为真金白银，使框架的"精简"从工程美德变为经济理性。
8.25 优先级链的可解释性红利
优先级链不仅指导装配，还产出"为何如此装配"的解释。当人质疑"为何没给我看那条约束"，链上的权重与排序即答案。可解释性在审计、教学、调试场景价值巨大------它把装配从黑箱变为白箱。框架把可解释性作为内建属性，而非事后补丁，再次体现"把原则写入流程"的复利。可解释的上下文供给，才是可被信任的上下文供给。
8.26 框架的局限性诚实声明
框架有其局限，须诚实声明：①它假设 HDS 知识是结构化、带元数据的，若知识仍是散乱文档，框架无用武之地（须先有 D2E+HDS）；②场景识别再好也有误，误判可能漏投关键模块；③优先级链的权重需持续调参，初始配置未必优。承认这些，框架才不被神化。局限声明不是退让，而是可信优先在元层面的自律------连对工具自身的描述，也保持诚实。一个敢亮短板的框架，更值得托付。
8.27 框架与提示词库的协同
框架与提示词库可协同：框架决定"系统级背景供给"（角色、边界、陷阱），提示词库决定"具体任务的措辞模板"。二者分层，框架管"喂什么背景"，提示词管"怎么问"。协同使团队既享有系统级一致性（框架），又不失任务级灵活性（提示词）。混淆二者会导致要么忽视系统供给、要么过度工程化每个 prompt。正确关系：框架是底座，提示词是上层建筑，底座稳，上层才灵活。
8.28 装配器的配置即代码
优先级链与场景权重作为配置，应"配置即代码"------存于版本库、走评审、可回滚。配置即代码使装配策略的演化可追溯、可协作，避免"某人在某处偷偷改了权重导致全员投放变化"的失控。配置即代码是 DevOps 常识在上下文供给上的应用，也体现体系"把关键决策版本化"的一贯立场。装配策略不是黑箱调参，而是可被团队审查的工程资产。
8.29 框架的度量的反向校准
框架自身也需度量反向校准：投放命中率低，提示优先级链或场景识别失准；回退率高，提示模块内容或冲突消解有误。度量反向校准使框架不是"设完即忘"，而是随使用持续调优。校准记录进 HDS 的 M8 陷阱，使"框架如何被调好"也成为组织知识。反向校准把框架从静态配置变为动态进化的有机部分，呼应体系"演化"的哲学。
8.30 框架章节的再收束
再收束：上下文工程框架解决的是"用的时候怎么装"------以十一模块切分知识，以优先级链决定保谁，以冲突消解三级裁决决定矛盾如何处理，以淘汰策略决定窗口装得下，以装配器完成最后一公里。它把"上下文"从整篇搬运升级为模块化、可解释、可演化的供给。框架是四支柱中离模型最近的一相，其效果直接决定 AI 辅助研发的体验------装得对，模型才帮得上忙；装得错，再强的模型也白搭。
8.31 框架的"最小可用"切分建议
为降低采纳门槛，框架提供最小可用切分：先只定义 M1（角色）、M2（概览）、M3（边界）三模块，手工维护，验证"按角色供给"的价值；再补 M4--M8（约定、依赖、变更、决策、陷阱）以覆盖日常；最后上优先级链与淘汰，实现自动精简。不必一步到位------思想是核心，工具是载体。最小可用切分使小团队也能先尝甜头，再随痛点升级，避免"全套体系吓退人"的早熟失败。这是框架对"过度工程"批评的务实回应。
8.32 框架与模型能力的互补边界
须清醒：框架优化的是"供给什么上下文"，不改变模型本身的推理上限。若模型能力不足以处理所供上下文，框架无能为力；若模型很强但供给错乱，框架价值最大。二者互补边界提示：在弱模型上过度投资框架收益有限，应先升级模型；在强模型上疏于供给则是浪费------框架的价值随模型变强而更显，因为强模型更"吃"上下文质量。理解互补边界，才能把投入放在杠杆最大处。
8.33 框架章节的最终收束
最终收束：上下文工程框架以模块化、优先级、冲突消解、淘汰、装配器，把"上下文"这一模糊概念工程化为可解释、可演化、可复现的供给体系。它是四支柱中离模型最近的一相，直接决定 AI 辅助研发的体验上限。框架不追求"喂最多"，而追求"喂最对"------在信噪比与认知带宽的约束下，把珍贵窗口留给真正相关的信息。这一追求，与认知科学对有限工作记忆的洞察同构，也是长上下文时代反而更关键的原因。
8.34 框架与"认知负荷管理"的呼应
框架的所有机制（模块化、优先级、淘汰）最终都服务于"认知负荷管理"------把模型有限的注意力预算，分配给最高价值的信息。这呼应认知心理学：外部记忆与选择性注意是人类应对有限带宽的策略，框架把它工程化到 AI 上下文供给。呼应认知科学，使框架不只是经验 heuristics，而有理论根基；也使得"为何这样设计"可被理性辩护，而非"我们试出来有效"。理论呼应，是专业深度的标志，也是框架经得起质疑的底气。
8.35 框架章节的封笔
封笔框架章：它以十一模块切分知识，以优先级链决定保谁弃谁，以冲突消解三级裁决处理矛盾，以淘汰策略守住窗口，以装配器完成最后一公里，以 SemVer 与可观测性保障可复现。框架是四支柱中离模型最近的一相，直接决定 AI 辅助研发的体验上限------装得对，模型才帮得上忙。封笔之际重申：框架不追求喂最多，而追求喂最对；在信噪比与认知带宽约束下，把珍贵窗口留给真正相关的信息。这，便是上下文工程框架的全部意义。