第 37 章详细 Outline：Memory 与 Skill Design Patterns

写作契约

本章要完成的学习目标

读者完成本章后应能：

1. 区分会话历史、任务范围记忆、项目记忆、事件记录与决策记录的职责，不将保存位置或检索命中误作可复用事实。
2. 用来源、范围、新鲜度、读取触发与审查状态设计记忆候选的读写边界，并把写入候选与已进入长期记录的结论分开。
3. 用技能契约（Skill Contract）区分只读 Skill 与提议写入 Skill，说明后者何时只能提交候选、何时必须停在人工或独立审查前。
4. 为记忆与 Skill 的组合声明版本、兼容性、替代和弃用信息，避免让旧记录或旧契约静默参与新任务。
5. 为一个虚构事实核验场景选择最小的 Memory／Skill Pattern Card 组合，并指出它不能证明的权限、检索、同步或外部执行事实。

读者、前置与明确边界

• 读者： 能阅读 Markdown、结构化记录与简单 JavaScript 对象，且需要在长期项目中让上下文、可复用能力和变更责任保持可审查的工程读者。
• 前置： 第 07 章的 Working Memory、Long-term Memory 与读写闸门；第 08 章的 Skill Contract；第 13 章的检索候选；第 16、17 章的经验与评估；第 33 章的项目记忆层；第 34 章的团队级 Skill Library；第 36 章的模式选择语言。
• 本章负责： 把记忆记录和 Skill 契约抽象为可组合的 Pattern Card，解释读取、提议写入、审查、版本、替代和弃用之间的责任断点。
• 本章不负责： 部署 Session、数据库、向量检索、嵌入、文件同步、权限系统、运行时加载器、真实 Skill、产品配置、网络、文件 I/O、模型、账户、凭证、审批或外部系统执行。

来源与本书模型的分层

使用位置	可归因材料	本章允许的有限陈述	本书原创内容
第 1、2 节	CH37-REF-01 / REF-020	OpenAI Agents SDK 的特定 Session 可在多次 run 间维护对话历史，并有其读取、写入和服务端延续的产品边界。	会话、任务、项目和事件四类记录的责任表，以及“会话连续性不等于项目记忆”的判断。
第 1 至 4 节	CH37-REF-02 / REF-022	LangChain 在自身语境区分 thread 内短期记忆与跨 session 的长期数据，并以 namespace 与 key 组织存储文档。	任务范围、证据、新鲜度、读取触发和写入候选的接口字段及其停止规则。
第 5、6 节	CH37-REF-03 / REF-024	Agent Skills 规范描述 SKILL.md、frontmatter、指令正文与可选资源的分层加载结构。	只读与提议写入的 Pattern Card、项目适配层和“格式不等于写入许可”的审查问题。
第 5、6 节	CH37-REF-04 / REF-025	Claude Code 在其产品语境中区分按需加载的 Skill 与常驻项目指令；路径、覆盖和调用控制均属产品实现。	Skill 与项目记忆的分层选择、按需过程说明与常驻项目事实的边界。

正文必须用“OpenAI Agents SDK 文档说明”“LangChain 文档说明”“Agent Skills 规范说明”“Claude Code 文档说明”“本书工程模型”或“虚构教学输入”标明层次。不得把上述材料写成跨产品记忆架构、自动发现、数据隔离、读取授权、写入成功、事实正确性或安全保证。

章节叙事与逐节蓝图

1. 从一份上下文到四类责任：连续对话不等于可复用知识

• 要回答的问题： 为什么把消息历史、任务观察、项目约定和一次失败事件混在一起，会使下一位读者无法判断哪条内容可以使用？
• 场景输入： 一个虚构事实核验任务同时拿到当前待核验句子、上一轮对话摘要、项目引用卡和一条过期的失败记录。所有文本均为注入的教学材料。
• 来源事实： CH37-REF-01 只用于说明 OpenAI Agents SDK 的特定 Session 跨 run 历史语境；CH37-REF-02 只用于说明 LangChain 对 thread 内与跨 session 数据的区分。
• 本书模型： 用“会话历史、任务范围记忆、项目记忆、事件记录”四列表标出各自的产生者、读取条件、失效信号和不能承担的结论；物理上同处一份文件不改变责任。
• 最小证据： 比较“上一轮摘要”“当前来源片段”“已审项目决策”“失败日志”在来源、范围和新鲜度字段上的差异，要求读者选出应先复核而非直接复用的项。
• 失败与停止： 缺来源、主体不明、时效未知或把事件当作根因时，只能保留为候选或未知项；不得用“系统保存过”作为读取许可。
• 过渡： 区分记录种类后，下一节把“能被检索到”同“可进入项目记忆”拆开。

2. 证据卡与写入门：检索命中只产生候选

• 要回答的问题： 如何避免模型摘要、检索片段或一次观察直接污染项目记忆？
• 来源事实： CH37-REF-02 仅提供长期数据可跨会话保存、按 namespace 与 key 组织的框架背景；它不规定本章的证据卡字段或写入策略。
• 本书 Evidence Card： 一张候选卡至少说明来源位置、可支持的陈述、适用范围、访问或观察日期、反例／限制、提出者和审查状态。它能被读取为候选，不等于内容为真、完整、当前或获准写入。
• 本书写入门： 依次检查来源能否定位、范围是否匹配、新鲜度是否可判断、是否与当前直接证据冲突、以及谁负责审查。结果只能是保留为任务材料、提出写入候选、补证、拒绝或升级。
• 最小证据： 将三条虚构材料分别路由：有范围但过期的资料进入 needs_refresh；无来源的模型摘要进入 needs_evidence；带来源且待审的结论进入 proposed_write。
• 失败与停止： 相似度、URL、标签、引用格式或成功的摘要都不能替代范围与审查。来源不可定位或冲突未解释时，停止进入项目记忆。
• 过渡： 候选通过写入门仍需决定何时读取；下一节将读取限制为与当前任务有关的选择。

3. 读取门与项目适配层：旧记录只能重回候选队列

• 要回答的问题： 可跨任务保存的内容如何在下一次任务中保持可解释，而不成为每次调用的默认上下文负担？
• 来源事实： CH37-REF-01 的 Session 读写语义只说明该 SDK 的会话历史；CH37-REF-02 的 namespace／key 语境只说明该框架组织数据的方式。
• 本书读取门： 当前任务先声明对象、范围、问题、预算和停止条件，再用记录的读取触发、来源、新鲜度、冲突状态和最小所需片段决定是否纳入候选 Context Packet。项目适配层提供具体路径或资源，本章模式卡不内嵌私有路径。
• 最小证据： 为虚构事实核验任务列出“只读取当前句子有关的两张证据卡”“保留一个过期决策指针但要求刷新”“拒绝另一项目的经验记录”三项结果。
• 失败与停止： 读取条件未写明、范围跨项目、冲突未处理或资料已经弃用时，返回 not_applicable、needs_refresh 或 needs_review；不静默注入完整历史。
• 过渡： 读取控制的是信息选择，下一节处理这些记录如何修订、替代与退出。

4. 生命周期、版本与弃用：记录不会因旧而自动失效

• 要回答的问题： 旧的项目结论和旧的 Skill 契约怎样退出，才能既不被误用也不丢失为何变化的线索？
• 本书生命周期记录： 对记忆候选或项目记录保留 under_review、stable、superseded、archived 等教学状态，并关联复核条件、替代指针、责任人和下一步。字段值描述状态，不自动删除、迁移或通知。
• 本书兼容性声明： 每次变更分别比较可读取的记忆类别、触发条件、输入、输出、允许副作用、所需证据和退役路径；版本号只索引变更，不能自行证明兼容或迁移完成。
• 本书弃用记录： 说明停止推荐的原因、受影响版本、替代项、迁移期限、维护终点和未覆盖范围，明确“停止推荐”“停止维护”“停止执行”和“删除数据”不是同一动作。
• 最小证据： 比较一条被替代的引用策略和一个收紧来源范围的核验 Skill：前者需要替代关系与刷新入口，后者需要重新审查触发、输入和既有候选；两者均不表示真实迁移已执行。
• 失败与停止： superseded 缺替代目标、兼容范围未知、维护者不明或旧 Skill 仍试图提议写入时，停在 needs_human_review。
• 过渡： 生命周期给出记录如何退出，下一节再说明 Skill 应如何声明它与这些记录的互动。

5. 两类 Skill：只读结论与提议写入不能混为一条能力

• 要回答的问题： 为什么同样是“查资料并整理”，一个 Skill 可能只应报告证据，另一个却需要额外审查才能提出记忆写入？
• 来源事实： CH37-REF-03 仅用于说明 Skill 的 metadata、正文和可选资源可分层；CH37-REF-04 仅用于说明 Claude Code 的按需加载与常驻项目指令的产品特定区别。
• 本书只读 Skill： 契约声明允许读取的记忆类别、任务输入、可产生的证据包、禁止写入和停止条件。只读不保证所读材料正确、完整、可访问或可用于当前结论。
• 本书提议写入 Skill： 契约额外声明候选目标类别、必须保留的来源与范围、变更理由、审查状态、拒绝出口和允许的项目适配输入。它只产出提议，不写入项目记忆、不更新引用、不改变正文。
• 最小证据： 用一张契约字段归属表将“读取来源范围”归入两类 Skill，将“候选写入理由与审查状态”归入提议写入 Skill，将“真实写权限”归为本章外的环境问题。
• 失败与停止： 不含来源字段、写入目标不明、禁止条件缺失、带外部副作用、或以 SKILL.md 格式替代审批的候选一律阻塞或升级。
• 过渡： 两类契约界定了单一 Skill 的边界；下一节讨论它们如何与项目记忆组合，而不让项目私有状态泄漏到可复用资产中。

6. 组合模式：让 Skill 读取公共契约，而非私有项目状态

• 要回答的问题： 如何让同一个 Skill 在不同项目中复用，而不把一次项目的路径、猜测或写入步骤固化为通用指令？
• 来源事实： CH37-REF-03 的渐进加载仅说明规范中的目录与资源层次；CH37-REF-04 的按需加载仅适用于 Claude Code 文档所述行为。两者均不表示资源自动隔离或拥有权限。
• 本书组合规则： Skill Contract 声明所需的记录类别、最小字段、允许的证据输出和禁止的动作；项目适配层在调用前提供符合契约的注入资料。Skill 不拥有项目路径、账户、密钥、同步渠道、真实写入策略或全局记忆。
• 模式对比：

组合	适用条件	最小工件	不能主张
任务范围读取	当前任务只需近期观察。	任务锚点、只读输入、过期条件。	已形成跨任务知识。
证据卡复核	待核验陈述可定位到来源候选。	Evidence Card、范围、刷新条件。	来源已支持最终结论。
决策记录查询	已有项目决策可能适用。	决策、所有者、适用条件、替代关系。	历史决定自动适用。
提议写入	新结论有来源并需要人工或独立审查。	候选、变更理由、审查门、拒绝出口。	项目记忆已经更新。

• 最小证据： 要求读者为每种组合写出“所需输入”“允许输出”“谁审查”“何时停止”四项，不以目录位置或名称相似代替契约。
• 失败与停止： Skill 需要私有路径、隐式写入、跨主体资料或无法解释的上下文时，拒绝复用并要求项目侧单独适配或人工评估。
• 过渡： 组合图需要落在具体但无副作用的教学场景中，下一节将用事实核验 Skill 检验这些断点。

7. 完整教学案例：事实核验 Skill 只形成可审查候选

• 要回答的问题： 一个“核验事实”的自动化步骤怎样提供帮助，又为何不能自己宣布项目记忆已更新？
• 教学输入： 虚构项目收到一句待核验陈述及三张候选 Evidence Card：一张来源范围匹配、一张已过期、一张没有可定位来源。另有一个只读事实核验 Skill 和一个提议写入 Skill 的契约对象。材料不对应真实 URL、文件、用户、审查人或运行结果。
• 处理路径： 只读 Skill 先把候选与当前陈述、范围和新鲜度比较，输出 evidence_candidate、needs_refresh 或 needs_evidence；提议写入 Skill 仅能为第一类生成带来源、范围和审查状态的 proposed_write 记录。
• 责任断点： evidence_candidate ≠ fact_verified、proposed_write ≠ memory_updated、review_approved ≠ external_action_executed。若存在冲突、过期、缺来源或范围扩大，则返回人工复核或停止。
• 最小证据： 一张“输入记录 → 契约检查 → 输出状态 → 不能主张”的表，覆盖三种候选与拒绝出口；不引用任何真实仓库、模型、文件、网络或审查日志。
• 预期验证： 读者可以指出哪一个字段使提议可追溯、哪一个条件阻止自动写入，以及为什么通过审查仍不代表外部系统发生变化。
• 过渡： 案例能用表格解释责任，但需要一个纯内存接口和图示将分支变得可检验。

8. 最小示例：纯内存的 Memory／Skill 边界评估器

• 要回答的问题： 如何将模式卡的停止规则写成可反驳的最小接口，而不创建任何记忆存储或运行 Skill？
• 示例边界： Example Implementation 阶段才决定函数名、文件路径、测试数量和 npm 入口。实现只检查注入的任务范围、Evidence Card、记忆候选、Skill Contract、审查状态和生命周期摘要；不得读取真实项目文件、调用模型、启动 Skill、请求网络、访问数据库、写入存储、同步、调用 Git、使用账户或凭证。
• 计划路由： 完整的只读证据包可进入“在隔离示例中实现”的教学状态；缺来源、范围不匹配、过期资料、未定义写入边界、已弃用契约或声称外部执行的输入分别返回具名停止原因。
• 计划测试： 覆盖一个完整只读路径、一个可提出但未审查的写入候选、缺来源、跨项目范围、过期卡片、已弃用 Skill、隐式写入、以及输入声称已经执行外部系统的场景。断言只检查公开返回对象。
• 预期验证： 提纲阶段不运行测试、演示、Skill、记忆系统或外部工具；后续只有实际执行后才能记录红灯、绿灯、命令和输出。
• 过渡： 纯函数表达的是路由约束，下一节的图要让记录、契约和人工门之间的箭头同样清楚。

9. 图示：记忆层与 Skill 层之间的责任断点

• 要回答的问题： 一张图如何同时说明候选资料、只读 Skill、提议写入、审查门和生命周期，又避免画出“读取即相信”或“提交即写入”？
• 图示内容： Task Anchor → Candidate Evidence Card → Read-Only Skill → Proposed Write → Independent / Human Review → Project Memory 为主链；过期、范围冲突、缺来源与弃用分别导向 needs_refresh、needs_review 或 stopped。项目适配层只向 Skill 提供符合契约的输入。
• 关键箭头解释： 没有“Session → 长期项目记忆”“检索命中 → 事实成立”“Skill 被发现 → 已执行”“Proposed Write → 已更新”“Approval → 外部效果已发生”的箭头。所有节点均为本书模型或虚构教学输入。
• 工件与验收： 后续 Mermaid 源暂定为 diagrams/mermaid/chapter-37-memory-skill-boundaries.mmd；正文图块、源文件、SVG/PNG、替代描述和视觉检查只能在 Diagram Review 阶段产生并互相核对。
• 最小证据： 图后为每个停止节点写出所缺字段、责任人和可恢复动作，并说明“通过审查”在图中只代表本书记录状态。
• 预期验证： 读者能够为每条关键箭头指出输入、输出、责任和不能由箭头推导的外部事实。
• 过渡： 图给出当前最小组合；下一节说明从教学对象走向真实项目时哪些控制必须逐层增加。

10. 逐步增强、反模式、总结与后续连接

• 要回答的问题： 何时必须离开纯内存模式卡，以及哪些看似方便的捷径会重新制造记忆污染和 Skill 耦合？
• 渐进表：

新需求	必须新增的控制	升级触发	本章为何不实现
读取真实项目记忆	获批范围、敏感信息规则、读取记录、新鲜度复核和失败处理。	教学输入不足以判断当前项目。	示例不读取文件或数据库。
写入或迁移项目记忆	最小写权限、变更预览、来源复核、回读、审查和恢复路径。	候选需要改变共享资料。	提议写入不是写入。
运行真实 Skill	已核验的运行环境、工具契约、权限、超时、观察和独立验证。	需要产生外部效果。	Contract 不授予执行能力。
跨项目复用与分发	兼容性声明、项目适配、依赖治理、弃用与迁移记录。	同一能力面对不同私有上下文。	模式卡不含私有状态。
企业级治理	身份、隔离、保留、审计、预算、策略和人工升级。	资料跨主体或触及受控系统。	留给第 35、41、42 章及具体组织制度。

• 反模式： 把会话摘要永久升级、以 URL 证明来源已核验、将 SKILL.md 当作授权、让提议写入跳过审查、以版本号代替兼容性说明、让弃用条目静默读取。
• 总结回收： 本章的模式库不要求更多存储或更多 Skill；它要求每一次读取、提议写入、审查、替代和退役都保留范围与责任。产品的会话、记忆和加载机制只能提供局部背景，不能替代本书的工程判断。
• 练习：
  1. 将一条“上次部署失败”的记录拆成事件记录、Evidence Card 和项目决策候选，指出哪些字段不能从日志标题推出。
  2. 为一个只读来源检索 Skill 写出三个禁止动作，并说明何时应升级为提议写入 Skill。
  3. 为一条收紧读取范围的契约改动写出 Compatibility Declaration，列出两项需要重新审查的旧候选。
  4. 设计一个弃用中的核验 Skill 的停止输出，区分停止推荐、停止维护和停止执行。
• 后续连接： 第 38 章把候选改进、独立评估与批准模式连接为决策闭环；第 43 至 45 章将把项目记忆、可复用能力与跨工具接力放入技术书工厂和长期项目语境。后续章节不得把本章的教学路由倒写为真实权限、同步或执行证明。

后续阶段的交付与验证契约

阶段	计划产物	本阶段不应提前声称的事实
First Draft	原创正文、事实核验教学案例、Pattern Card、表格和跨章节过渡。	Session、记忆、Skill、检索、写入、审批或同步已经在真实系统运行。
Technical Review	来源范围、模式术语、案例边界和相邻章节不重复的审查记录。	产品文档保证项目记忆正确、Skill 可发现或契约可执行。
Example Implementation	无 I/O 的纯内存评估器、红灯记录、Node 测试和演示。	真实文件、数据库、网络、模型、Skill、存储、账户、凭证或审批已被调用。
Diagram Review	Mermaid 源、导出图、替代描述、图文一致性与视觉检查记录。	图中的候选、审查或项目记忆存在于真实系统。
Fact Check	REF-020、REF-022、REF-024、REF-025 的逐项允许陈述、外推禁区、访问日期与动态复核记录。	动态 SDK、框架、规范或 Claude Code 行为适用于其他产品或版本。
Language Editing / Final Review	术语首现、主体、时态、来源、图示、示例、状态与交叉引用的一致性记录。	后续项目记忆治理、真实协作或外部副作用已经完成。

提纲完成检查

• [x] 每一节均给出读者问题、允许来源、本书模型、最小证据、停止边界和过渡。
• [x] 会话历史、任务范围记忆、项目记忆、事件记录、Evidence Card 与决策记录的责任已经分开。
• [x] 只读与提议写入 Skill 的契约、审查、项目适配和外部权限边界已经分开。
• [x] 虚构事实核验案例、纯内存示例和真实存储／检索／同步／权限／执行边界已经明确。
• [x] 与第 07、08、13、16、17、33、34、36、38、43 至 45 章的接口和不重复范围已经说明。
• [x] 后续阶段不会把 Pattern Card、候选、目录格式、按需加载或图示箭头写成真实运行、授权、写入、事实成立或外部效果证明。