模块知识持久化与上下文恢复两个 Codex Skills 的工程设计分析引言在长期软件开发中AI 编程助手面临一个很现实的问题一次对话能解决局部任务但很难天然保存一个模块的长期背景。一个复杂模块往往经历多轮讨论、设计取舍、代码修改和临时决策。如果这些上下文只存在于历史聊天中后续再继续开发时AI 需要重新阅读代码、重新推断设计意图甚至可能忘记之前已经确定过的约束。update-module-knowledge和load-module-context这两个 Skills正是围绕这个问题设计的。前者负责把当前对话中与某个模块有关的知识沉淀成结构化文档并维护全局索引后者负责根据用户提到的模块名、功能描述或文件路径从索引中找到对应模块文档并加载到当前上下文。这两个 Skill 不是传统意义上的业务代码也不是可直接运行的程序。它们更接近“面向 Agent 的操作规约”用 Markdown 和 YAML front matter 描述触发条件、适用场景、执行步骤和输出结构。换句话说它们把“如何记住模块知识”和“如何恢复模块上下文”这两件事从临时口头约定变成了可复用的工作流。本文基于以下两个文件进行分析\.codex\skills\update-module-knowledge\SKILL.md\.codex\skills\load-module-context\SKILL.md需要说明的是当前两个 Skill 目录下都仅有一个SKILL.md没有额外脚本、模板文件或测试文件。因此本文分析的是 Skill 规范本身而不是某段可执行代码的运行行为。背景为什么 Agent 需要模块级知识管理在传统软件工程中项目知识通常通过 README、设计文档、ADR、接口文档、代码注释、提交记录和 issue 管理系统沉淀。AI Agent 参与开发后知识管理出现了新的问题许多关键决策并不一定进入代码或正式文档而是散落在对话中。例如在一次模块开发中可能发生以下对话内容为什么选择某个数据结构。某个接口暂时不做兼容的原因。某个 bug 的根因和临时绕过方案。后续需要补测试或优化性能的待办。某些文件属于同一模块边界。如果这些内容不被整理下一次继续开发时Agent 只能从代码现状重新推断很容易遗漏历史约束。模块级知识管理要解决的不是“记住所有聊天记录”而是把对后续开发真正有用的信息压缩成结构化、可索引、可加载的知识资产。这两个 Skills 可以看作一个简化版的模块记忆系统update-module-knowledge负责写入。.ai_modules_index.json负责索引。docs/modules/模块名.md负责存储模块知识。load-module-context负责读取和恢复上下文。Skill 一update-module-knowledge 的职责update-module-knowledge的 front matter 如下---name:update-module-knowledgedescription:当完成一个模块的开发、讨论或决策后只要有对代码的修改则将本次会话中与该模块相关的关键信息功能设计、代码变更、架构决策、待办事项等压缩并持久化为结构化文档同时更新全局索引供后续使用 load-module-context 快速恢复上下文。---这段描述已经明确了三个核心语义。第一它不是在任意聊天后触发而是在“完成一个模块的开发、讨论或决策后”触发。特别是描述中强调“只要有对代码的修改”说明它的主要目标是保存代码变更相关上下文而不是泛泛保存聊天摘要。第二它保存的不是完整对话而是“关键信息”的压缩版本包括功能设计、代码变更、架构决策和待办事项。这符合长期记忆系统的基本原则长期记忆不应保存噪声而应保存后续任务需要恢复的高价值事实。第三它不仅写模块文档还要更新全局索引。这意味着文档存储和检索索引被视为一体。没有索引后续load-module-context很难根据用户输入找到正确文档。适用场景与触发方式该 Skill 的适用场景定义为## 适用场景 - 完成一个功能模块的开发或修复后保存当前状态 - 对话涉及重要设计决策希望未来不必重复解释 - 准备切换上下文前保存当前模块进展 - 多人协作时同步模块知识这些场景覆盖了模块知识沉淀的典型时机。最关键的是“切换上下文前”。AI Agent 的上下文窗口有限即使平台支持历史会话检索也无法保证每次都能准确恢复局部模块知识。因此在上下文切换前主动沉淀模块文档是降低后续恢复成本的一种方式。触发方式则设计为自然语言和命令两类## 触发方式 可通过自然语言或命令触发例如 - “保存当前负载均衡模块的讨论” - “/update-module 灰度发布” - “把刚才关于限流算法的决策记录下来” - “将当前会话中的路由转发设计写入文档” - 对话结束时自动询问是否需要保存可配置这里的设计比较符合 Agent 使用习惯用户不必记住严格命令也可以用自然语言表达保存意图。同时保留/update-module这类命令式触发适合高级用户快速操作。核心流程从对话到模块文档update-module-knowledge的执行步骤分为四段确认模块名称、分析当前会话、读取现有文档、生成或更新模块文档。1. 确认模块名称### 1. 确认模块名称 - 若用户直接提供模块名如“负载均衡模块”直接使用。 - 若未提供从当前对话中推断 - 根据讨论的主要文件路径 - 反复提及的功能名称 - 用户最近修改的代码区域 - 推断失败时询问“请提供要更新的模块名称建议使用简洁的中文名如 负载均衡、灰度发布以便后续快速加载。”这一步本质上是在建立“知识归属”。如果模块名不稳定同一个模块可能被写成多个文档例如“负载均衡”“loadbalance”“路由负载均衡”。长期看这会造成知识碎片化。规范中建议使用简洁中文名这是一个可用但仍需加强的约定。更稳妥的做法是让索引支持name、aliases、keywords三层命名name作为规范名称aliases保存常见别名keywords用于搜索匹配。2. 分析当前会话该 Skill 要求提取以下信息### 2. 分析当前会话 回顾对话历史提取与该模块相关的以下信息 - **核心功能**模块解决什么问题对外提供哪些能力。 - **关键代码**涉及的文件路径、核心类/函数、数据结构。 - **决策记录**为什么选择某种实现方式选型、架构权衡、问题解决方案。 - **接口定义**API 端点、输入输出、事件或消息格式。 - **依赖关系**依赖的外部服务、库或其他模块。 - **未竟事宜**已知的 bug、待优化点、临时方案。 - **变更历史**本次对话带来的主要改动。这组字段是整个 Skill 中最有价值的部分。它没有只要求“总结一下”而是把模块知识拆成几个稳定维度功能、代码、决策、接口、依赖、待办和变更历史。其中“决策记录”尤其重要。代码告诉我们“现在是什么样”但很难说明“为什么这样”。例如一个限流模块为什么选择令牌桶而不是滑动窗口一个检索模块为什么先做向量召回再 rerank这些都属于决策信息。后续维护者如果不了解原因可能会做出看似合理但破坏约束的修改。3. 增量更新已有文档### 3. 读取现有文档若存在 - 检查 docs/modules/模块名.md 是否存在。 - 若存在读取内容对比新旧信息确定是增量补充还是覆盖部分内容。 - 默认采用**增量更新**除非用户明确要求“覆盖”。默认增量更新是合理选择。模块知识文档通常是长期积累的如果每次保存都覆盖全文容易丢失历史决策。增量更新更接近开发日志或 ADR 的模式。不过增量更新也带来一个风险文档可能变得冗长、重复或过时。因此更成熟的设计应区分“稳定事实”和“变更日志”。稳定事实可以被改写变更日志则追加记录。否则旧结论和新结论可能同时存在后续加载时反而造成混淆。4. 文档模板和索引当前 Skill 给出的文档模板如下# 模块模块名 最后更新YYYY-MM-DD HH:MM 会话摘要本次对话的核心目标一行概括 ## 本次变更 - **新增**新增的功能或代码 - **修改**修改的逻辑或配置 - **删除**移除的内容 ## 决策记录 - **问题**要解决什么问题 - **方案**选择了什么方案 - **原因**为什么这么选这份模板简洁适合快速落地。但如果目标是长期模块知识库字段还可以进一步扩展例如模块边界关键文件对外接口数据结构依赖关系已知风险待办事项最近变更Skill 还要求更新.ai_modules_index.json并给出索引结构{name:模块名,keywords:[关键词1,关键词2,功能名],docPath:docs/modules/模块名.md,relatedPaths:[相关目录或文件路径]}索引设计是这套机制的关键。没有索引模块文档只是静态文件有了索引Agent 才能根据用户输入自动定位上下文。不过需要注意示例中的索引对象没有放在顶层modules数组中而load-module-context的示例使用的是{modules:[{name:负载均衡,keywords:[轮询,负载均衡,loadbalance],docPath:docs/modules/loadbalance.md,relatedPaths:[src/main/java/com/grace/gateway/core/filter/loadbalance/]}]}这说明两个 Skill 对索引结构的示例并不完全一致。虽然语义上可以理解但在实际使用中最好统一为一个明确 schema例如固定使用{modules:[{name:模块名,aliases:[别名1,别名2],keywords:[关键词1,关键词2],docPath:docs/modules/模块名.md,relatedPaths:[src/main/java/...],updatedAt:2026-05-29T22:49:0008:00}]}Skill 二load-module-context 的职责load-module-context的 front matter 如下---name:load-module-contextdescription:根据用户提及的模块名、功能描述或相关文件路径从模块索引中匹配并加载对应的模块文档到当前对话使 AI 能基于历史讨论、设计决策和代码变更进行后续开发或问题解答。---如果说update-module-knowledge是写入端那么load-module-context就是读取端。它的目标不是生成新知识而是根据用户当前任务恢复已有知识。其描述部分进一步说明## 描述 根据用户输入或当前任务从模块索引中匹配最相关的模块文档并将其内容加载到对话上下文中使 AI 能基于完整模块知识进行后续开发、优化或问题解答。这解决的是上下文冷启动问题。用户可能只说“介绍一下灰度策略的实现”Agent 就应该知道去找“灰度发布”模块文档而不是重新全局搜索代码。上下文加载的触发场景load-module-context的适用场景定义如下## 适用场景 - 开始新任务但之前已讨论过该模块 - 需要修改某模块但上下文已丢失 - 用户直接询问模块相关问题时自动加载背景信息 - 多人协作时快速恢复模块上下文这些场景和update-module-knowledge是互补的。一个强调“保存当前状态”一个强调“恢复历史状态”。如果二者配合得好就能形成一个闭环修改模块后保存知识。未来提到该模块时加载知识。新一轮修改后再更新知识。从长期协作角度看这类似轻量级的模块记忆数据库。它不替代代码仓库也不替代正式设计文档但能填补“对话决策”和“代码现状”之间的空白。定位线索从用户输入到模块候选load-module-context的第一步是提取模块定位线索### 1. 获取模块定位线索 从用户消息或当前任务中提取可能指向模块的线索优先级如下 - **明确的功能**如“负载均衡”、“限流” - **功能描述**如“负载均衡的算法实现” - **文件路径**如“src/main/java/com/grace/gateway/core/filter/gray/GrayFilter.java 对应的功能” - **历史提及**若最近对话中出现过功能名也可作为候选 若线索不足列出最近使用或最可能的 3~5 个模块供用户选择。这个优先级设计比较实用。模块定位通常有三类信号用户明确说出的功能名。用户描述的问题或行为。用户给出的文件路径。其中“文件路径”是很强的信号。因为同一个概念可能有多个叫法但代码路径通常稳定。例如用户提到GrayFilter.java即使没有说“灰度发布”系统也可以通过relatedPaths找到对应模块。不过当前规范还没有详细定义匹配算法。实际实现中可以考虑以下策略精确匹配模块名。匹配 aliases。匹配 keywords。判断文件路径是否以某个relatedPaths前缀开头。对描述文本做简单分词或模糊匹配。多候选时按匹配强度排序并让用户确认。查询索引.ai_modules_index.json的中心地位load-module-context的第二步是读取索引### 2. 查询索引 - 读取索引文件 .ai_modules_index.json若不存在提示用户先执行 update-module-knowledge 创建模块文档 - 索引结构示例 json { modules: [ { name: 负载均衡, keywords: [轮询, 负载均衡, loadbalance], docPath: docs/modules/loadbalance.md, relatedPaths: [src/main/java/com/grace/gateway/core/filter/loadbalance/] } ] }这段规范说明.ai_modules_index.json是整个系统的入口。模块文档可以很多但加载端不会盲目扫描所有文件而是先查索引。这种设计有几个好处定位速度快。模块名称和文件路径可以解耦。支持关键词和路径多维检索。便于后续扩展元数据例如更新时间、负责人、稳定性状态。但当前load-module-context的SKILL.md在索引示例后就结束了没有继续定义“读取文档”“加载到上下文”“输出摘要”“多候选冲突处理”等步骤。这不影响理解整体意图但从规范完整性看还不够。一个更完整的读取流程可以是读取.ai_modules_index.json。根据 name、keywords、relatedPaths 匹配候选模块。如果无候选提示先运行update-module-knowledge。如果一个候选明显最相关读取其docPath。如果多个候选相近列出 3 到 5 个选项让用户确认。加载模块文档内容。输出简短上下文摘要并说明已加载哪些文件或决策。两个 Skill 形成的知识闭环把两个 Skill 放在一起看可以得到一个明确的数据流当前对话与代码修改 | v update-module-knowledge | v docs/modules/模块名.md | v .ai_modules_index.json | v load-module-context | v 后续对话中的模块上下文恢复这个闭环和检索增强生成RAG有相似之处但粒度更偏工程化。普通 RAG 通常从大量文档中检索片段而这里是人为维护模块级文档并通过模块索引进行定位。它的优势是语义边界清晰。一个模块文档可以聚合该模块的功能、代码、接口、依赖、决策和待办。加载时Agent 得到的不是零散片段而是经过压缩的模块上下文。它的风险是依赖文档质量。如果update-module-knowledge保存的信息不准确或过期load-module-context会把错误上下文带入后续开发。因此模块知识系统必须重视更新时间、变更历史和过期信息处理。现有技术方案对比方案一只依赖聊天历史最简单的方式是不做额外文档直接依赖历史对话。优点是零成本不需要维护额外文件。缺点也很明显历史对话噪声多、上下文窗口有限、定位困难且跨会话恢复不稳定。对于短任务这种方式可以接受对于长期模块开发它会让 Agent 每次都重新“考古”。方案二手写模块文档开发者可以手动维护docs/modules下的模块文档。这种方式准确性较高也便于团队阅读。但它依赖人的主动性容易在快速迭代中滞后。update-module-knowledge的价值就在于降低手写成本让 Agent 在一次任务完成后自动把对话和代码变更压缩成文档草稿。方案三代码注释和 README代码注释适合解释局部实现README 适合描述项目整体。但模块级决策、变更背景和未竟事项不一定适合放入源码注释。过多背景信息写进代码反而会干扰阅读。模块知识文档可以作为中间层比 README 更细比代码注释更宏观。方案四ADR 和设计决策记录ADRArchitecture Decision Record用于记录重要架构决策适合保存“为什么选择某方案”。它比普通文档更正式也更强调决策背景、备选方案和后果。当前update-module-knowledge中的“决策记录”与 ADR 思路接近但模板更轻量。对于重要模块可以考虑把高影响决策单独沉淀为 ADR把模块文档作为索引和摘要入口。方案五向量化知识库或 RAG另一种方案是把代码、文档、对话摘要全部向量化查询时自动检索相关片段。这种方式适合大规模知识库但需要处理切片、召回、重排和权限问题。相比之下这两个 Skills 更轻量它们不依赖向量数据库而是通过结构化索引和模块文档解决可定位性问题。对于个人或小团队项目这是更容易落地的方式。实际应用中的权衡结构化程度与维护成本文档结构越丰富后续加载越有价值但每次更新成本也越高。当前update-module-knowledge的模板偏轻量适合快速保存但对于复杂模块可能信息不足。一个折中做法是区分必填字段和选填字段。必填字段包括模块名、摘要、关键文件、主要变更、决策记录选填字段包括接口、依赖、风险、待办、测试情况。增量追加与内容重写Skill 默认采用增量更新这是保守且安全的选择。但长期追加会导致文档膨胀。更合理的方式是“模块现状”保持最新可被重写。“决策记录”按时间追加。“变更历史”保留摘要。“已完成待办”定期清理或归档。自动推断与用户确认模块名和候选匹配可以自动推断但不应在不确定时强行写入。update-module-knowledge已经规定推断失败时询问用户load-module-context也规定线索不足时列出 3 到 5 个候选。这是合理的交互边界。对于 Agent 来说“宁可多问一次也不要把知识写错模块”因为错误归档会污染后续上下文。本地文件与团队协作这两个 Skill 默认把文档写入项目中的docs/modules和.ai_modules_index.json。如果这些文件纳入版本控制就可以服务团队协作如果只保存在个人环境中则更像个人 Agent 记忆。团队使用时需要额外约定文档是否提交到 Git。谁负责审核模块知识。冲突时如何合并。过期信息如何标记。当前规范的不足基于现有SKILL.md这两个 Skills 的方向清晰但仍存在一些工程化不足。第一两个文档都在示例代码块附近结束缺少完整收尾。update-module-knowledge没有定义索引更新后的校验步骤load-module-context没有定义读取模块文档后的输出格式。第二索引结构示例不完全一致。写入端展示的是单个模块对象读取端展示的是modules数组。实际使用中应统一 schema。第三缺少冲突处理规则。例如同一个模块名已存在但docPath不同或者多个模块 keywords 命中同一用户输入时应如何处理。第四缺少验证机制。写入后应检查文档是否存在、索引 JSON 是否可解析、docPath是否指向有效文件。第五缺少过期信息处理。模块文档可能随代码演进而失效应加入updatedAt、relatedCommit、status或“待验证”标记。这些问题并不否定当前设计。相反它们说明这两个 Skills 处于一个可用的雏形阶段核心思路已成立但要成为稳定工作流还需要 schema、校验和冲突处理。一个更完整的 schema 建议为了让两个 Skills 更好协作可以将.ai_modules_index.json统一为如下结构{version:1,modules:[{name:负载均衡,aliases:[loadbalance,负载均衡算法],keywords:[轮询,权重,一致性哈希],docPath:docs/modules/负载均衡.md,relatedPaths:[src/main/java/com/grace/gateway/core/filter/loadbalance/],updatedAt:2026-05-29T22:49:0008:00,status:active}]}模块文档也可以采用更稳定的模板# 模块负载均衡 最后更新2026-05-29 22:49 当前状态active 会话摘要补充负载均衡策略的实现说明和权重选择逻辑。 ## 模块边界 说明该模块解决什么问题不解决什么问题。 ## 关键文件 - src/main/java/.../LoadBalanceFilter.java - src/main/java/.../RoundRobinStrategy.java ## 核心功能 描述对外能力和主要流程。 ## 决策记录 ### 2026-05-29选择加权轮询 - 问题普通轮询无法体现实例权重差异。 - 方案使用加权轮询。 - 原因实现简单可解释性强适合当前流量规模。 ## 待办与风险 - 补充异常实例剔除策略。 - 增加并发场景下的单元测试。这种结构既适合人阅读也适合 Agent 加载后快速定位关键信息。未来方向第一可以加入自动变更摘要。Agent 在执行update-module-knowledge时可以结合git diff、已修改文件和测试结果生成更客观的变更记录。第二可以加入索引校验。每次更新.ai_modules_index.json后检查 JSON 格式、路径存在性和模块名唯一性。第三可以支持多模块更新。一些任务会同时影响多个模块例如认证模块和网关过滤器。此时应允许一次对话生成多个模块文档更新。第四可以引入轻量检索。当前索引依赖关键词和路径匹配后续可以对模块摘要做 embedding用语义方式匹配“用户想问的模块”。第五可以增加加载摘要。load-module-context读取文档后不一定要把全文都塞入上下文可以先输出“已加载模块、关键文件、最近决策、待办风险”再根据任务需要读取详细章节。总结update-module-knowledge和load-module-context构成了一套轻量的模块知识闭环前者负责把对话中的模块知识结构化、持久化并更新索引后者负责根据用户输入从索引中恢复模块上下文。这套设计的价值在于它把 AI 编程助手容易遗忘的“模块背景”和“历史决策”从聊天流中提取出来变成可复用的工程资产。它不替代代码、不替代 README也不替代正式 ADR而是补上了“对话中产生的模块知识”这一层。从当前文件看这两个 Skills 还不是完整成熟的模块记忆系统索引 schema 需要统一加载流程需要补全写入后的校验和冲突处理也需要明确。但它们已经具备一个正确方向以模块为单位保存知识以索引为入口恢复上下文让后续开发不必从零开始重新理解同一个模块。