L6-48：项目知识积累 —— 让AI越用越懂你的业务和代码

学 gstack 的跨会话知识积累系统：不是每次做同样的操作时从头解释项目特有的命令、配置和约定，而是自动记录为 learnings——Agent 和人类共享的"项目记忆"。 预计时间：15 分钟

[!tip] 初学提示：操作型、技术型和模式型三种学习——建议先从操作型入手（最直观），再看技术型（理解代码约定），最后掌握模式型（需要经验积累）。

---

[!quote]- 原Skill精要 技能名称：learn 核心功能：管理项目 learnings（跨会话知识积累）。审查、搜索、修剪和导出 gstack 跨会话学到的内容。三种类型：操作型（项目特有命令）、技术型（代码约定与模式）、模式型（高频 bug 和经验）。Agent 和人类共享的"项目记忆"。 所属体系：gstack 虚拟工程团队 协作关系：被 [[L6-15-PR代码审查|review]] 的专家军团引用以增强审查上下文，与 [[L6-36-项目复盘大师|retro]] 的趋势分析互补

---

§1 白话小课堂：什么是"项目知识积累"？

我们前面学了 context-save/restore——它们解决的是"跨会话的工作进度"问题。但如果一个项目中反复出现相同的问题和模式呢？

比如：每次 Agent 操作支付相关代码，你都提醒它"微信支付的金额单位是分"。每次 Agent 写库存扣减逻辑，你都提醒它"秒杀场景必须用 Redis DECR，不能用数据库 UPDATE"。每次双11前，Agent 都不知道需要扩容 Redis。

这些不是"工作进度"——它们是项目特有的知识。如果你不在，新来的开发者（或新的 Agent 会话）不知道这些，就会重复踩坑。

learn 系统就是解决这个问题的：把项目特有的命令、约定、模式和坑记录下来，形成"项目记忆"。每次 Agent 操作相关代码时，自动检索到相关 learnings——就像一个资深开发者坐在新手旁边，在新手犯错误之前提醒他。

[!note] 类比：项目的"老兵手册" 每个公司都有一些"只有老员工知道"的东西：那个脚本要在部署前跑一下、那个 API 有个隐藏的参数、那个 bug 在每个月最后一天会因为时区问题出现。learn 系统就是把这些"口口相传"的知识显式化、结构化、可检索化。

context-save vs learn：两种不同的记忆

---

§2 结构拆解：learn 系统的完整架构

# learn Skill Template

## 触发词
/learn, "记住", "记录一下", "以后注意"

## 子命令
- /learn "<内容>" --type <operational|technical|pattern>: 记录新 learning
- /learn --search "<关键词>": 搜索已有 learnings
- /learn --list: 列出所有 learnings
- /learn --prune: 扫描并建议修剪过期 learnings
- /learn --verify <id>: 人类确认 learning 的准确性

## 工具列表
- Bash: 读取 learnings.jsonl
- Read: 读取项目文件以验证 learning 准确性
- Write: 写入 learnings.jsonl
- Glob: 扫描相关代码文件

## 核心特征
- **管理对象**：项目特有的隐性知识（命令、约定、模式、坑）
- **核心原则**：共享记忆而非私有笔记 —— Agent 自动记录 + 人类验证，双向共享
- **关键设计**：
  - 三类型分类：Operational（项目命令）、Technical（代码约定）、Pattern（高频 bug 模式）
  - 自动+手动双重记录：Agent 自动发现 + 用户手动 /learn
  - 检索限制：每次最多返回 3 条相关 learning（信噪比控制）
  - 生命周期管理：valid_until、seasonal 标签、active_window、prune 机制

## 通用架构
输入层：
  → 自动发现（Agent 在操作中发现的非通用知识）
  → 手动记录（/learn "<描述>" --type operational|technical|pattern）
  ├── 分类引擎
  │   ├── Operational: 项目特有命令、脚本、部署流程
  │   ├── Technical: 代码约定、API 格式、数据模型特定规则
  │   └── Pattern: 反复出现的 bug 模式、错误处理惯例
  ├── 存储层
  │   ├── ~/.gstack/projects/$SLUG/learnings.jsonl
  │   ├── 字段：type / content / created_by / source / verified / valid_until / seasonal
  │   └── 版本控制：learning 可被标记为 needs_review / deprecated
  ├── 检索层（每次 Skill 调用自动触发）
  │   ├── 关键词 + 上下文匹配
  │   ├── 季节性过滤（active_window 检查）
  │   ├── 验证状态过滤（unverified 不进入审查清单）
  │   └── 限制输出：最多 3 条最相关 learning
  └── 生命周期管理
      ├── 自动标记：长期未使用的 learning → prune 建议
      ├── 季节性学习：active_window 内自动激活
      └── 纠错机制：Agent 发现不一致 → needs_review → 人类确认
输出层：
  → 相关 learnings（注入到 Agent 操作上下文）
  → 审查清单补充检查项（Pattern 类型）
  → 自动化提醒（Operational 类型，如"大促前扩容 Redis"）

---

§3 三种 Learning 类型的深度解析

3.1 Operational（操作型）—— "这个项目怎么跑"

操作型 learning 记录的是项目特有的命令和操作流程。这些不是通用知识（"怎么用 git"），而是这个特定项目的特有操作。

为什么这很重要：如果 Agent 不知道"这个项目用 pnpm 而不是 npm"，它会在每一次安装依赖时犯同样的错误，直到你手动纠正。操作型 learning 让这个纠正只需要发生一次。更关键的是——这类错误通常不会在 CI 中被捕获（因为 CI 配置了正确的命令），只在本地开发时出现——这意味着每个新加入的开发者都会独立踩这个坑。learn 系统消除了这种"每个新人都要踩一遍"的隐性成本。

3.2 Technical（技术型）—— "这个项目的代码怎么写"

技术型 learning 记录的是代码约定、数据模型约定、API 规范。这些是"这个项目的代码应该长什么样"的知识。

为什么这很重要：如果 Agent 不知道"金额单位是分"，它会自然地写成 amount: 99.00（元）——这在微信支付 API 中意味着"99 分 = 0.99 元"，而非预期的"99 元"。这种 bug 不会导致编译错误或运行时崩溃——它会静默地产生错误结果，直到有人发现"为什么实际收的钱和预期不一样"。技术型 learning 防止这类"看起来对但实际上错"的隐形 bug。

3.3 Pattern（模式型）—— "这个项目有什么坑不能踩"

模式型 learning 记录的是反复出现的 bug 模式、架构教训、经验法则。这些是最高层次的知识——需要时间和经验才能识别。

为什么这很重要：模式型 learning 是"老兵的经验"。一个新 Agent（或新开发者）可能不知道"秒杀场景下数据库行锁会成为瓶颈"——他从教科书上学的是 UPDATE ... WHERE stock > 0。模式型 learning 让这个经验被记录和传递——不是"禁止使用数据库行锁"（过于武断），而是"在秒杀这种高并发场景下，数据库行锁会成为瓶颈，考虑使用 Redis DECR"。

3.4 类型对比与分类影响

[!warning] 类型标记错误是"沉默的失败" 将 Pattern 类型（"秒杀库存扣减必须用 Redis DECR"）错误地标记为 Technical 类型，不会产生任何报错或警告——但是 /review 的审查清单不会引用它，因为审查系统按类型索引 learnings，只有 Pattern 类型的 learnings 才会进入审查清单。类型不只是一个分类标签——它决定了谁在什么场景下使用这个 learning。

---

§4 Learning 生命周期：记录、检索、应用、维护

4.1 记录（Record）——知识入库

## 两条记录路径

自动记录：
  Agent 在操作中发现项目特有知识 → 自动记录为 unverified learning
  例：Agent 运行 npm test → 报错 → 发现项目用的是 bun test
    → Agent 自动记录: "此项目使用 bun test 而非 npm test" (operational, unverified)

手动记录：
  用户主动告诉系统项目特有的约定
  /learn "微信支付 API v3 的金额单位是分，不是元" --type technical
  /learn "秒杀库存扣减必须用 Redis DECR" --type pattern
  /learn "双11前需要手动扩容 Redis 到 16GB" --type operational

存储格式 (~/.gstack/projects/$SLUG/learnings.jsonl):
  {"id":"L042","type":"technical","content":"微信支付金额单位是分","created_by":"user:zhangsan","source":"manual","verified":true,"created":"2026-05-05","valid_until":null}
  {"id":"L043","type":"pattern","content":"秒杀库存扣减用Redis DECR","created_by":"agent","source":"session-abc123","verified":false,"created":"2026-05-05","valid_until":null}

4.2 检索（Retrieve）——在正确的时间找到正确的知识

检索逻辑是整个系统最精妙的设计：

检索时机：每次 gstack Skill 调用 → preamble 自动搜索相关 learnings

检索算法：
  Step 1: 从当前任务提取关键词
    例：Agent 正在写 src/payment/wechat.ts
    → 关键词：payment, wechat, 支付, 微信

  Step 2: 在 learnings.jsonl 中匹配
    → 内容匹配："金额单位是分"（命中 payment + 微信）
    → 内容匹配："支付回调必须幂等"（命中 payment）
    → 内容匹配："库存扣减用 Redis DECR"（不命中——与 payment/wechat 无关）

  Step 3: 季节性过滤
    → 检查 active_window：如"双11前扩容 Redis"的 active_window 是 10-01 to 11-12
    → 如果今天是 5 月 5 日 → 不检索（不相关）

  Step 4: 验证状态过滤
    → unverified learning：注入基础操作上下文
    → verified learning：注入基础操作上下文 + 进入审查清单

  Step 5: 相关性排序 → 取前 3 条

为什么是 3 条而非全部？
  → 不是技术限制（JSONL 搜索 200 条也很快）
  → 是"信号 vs 噪音"的设计决策
  → 3 条 = 最具相关性的 "信号"——Agent 能注意到并采纳
  → 超过 3 条 = 额外 learnings 变成 "噪音"——稀释注意力
  → 类比：Google 搜索结果——前 3 个最有价值，第 4-50 个越来越不相关

4.3 应用（Apply）——知识转化为行为

Learning 在系统中的三种应用路径：

路径 1：直接注入上下文
  Agent 操作支付代码 → 上下文中注入 "金额单位是分"、"支付回调必须幂等"
  → Agent 写 amount: 9900 而非 amount: 99.00
  → Agent 在回调处理器中添加去重逻辑

路径 2：审查清单引用
  /review 命令 → 审查专家军团检索相关 Pattern learnings
  → "秒杀库存扣减用 Redis DECR" → 加入 Security 专家的检查项
  → "退款金额计算必须在事务中" → 加入 Architecture 专家的检查项

路径 3：修复建议引用
  Agent 在 debug 时发现 bug → 检索相关 learnings
  → "这个 bug 很可能是 Redis 缓存和 DB 不一致引起的"
  → 修复建议中包含这条模式 → Agent 优先排查缓存更新时序

4.4 维护（Maintain）——知识的新陈代谢

---

§5 电商 Skill 案例：电商平台知识库自动沉淀——从3条到40+条的18个月生长

🛒 实战案例：某电商平台mega-shop运行18个月，经历了两轮双11大促。开发和运维过程中积累了大量项目特有知识——API的金额单位、库存扣减的并发约束、大促前的运维清单。这些知识如果只存在于几个老工程师的脑子里→新人(包括新AI Agent)会反复踩同样的坑。使用/learn将项目知识结构化沉淀——让知识从人的记忆变为系统的记忆。

• 第1个月（基础开发期，3条learning）：(1)/learn "微信支付API v3的金额单位是分不是元，数据库存储INTEGER类型，展示时/100转元" --type technical；(2)/learn "这个项目用pnpm不是npm，安装依赖必须用pnpm install" --type operational；(3)/learn "订单状态字段order_status是enum类型('PENDING'/'CONFIRMED'/'SHIPPED'/'DELIVERED'/'REFUNDED')不是string" --type technical。
• 第6个月（第一次双11后，"血的教训"期，+8条）：(1)/learn "秒杀库存扣减必须用Redis DECR原子操作，不能用DB UPDATE WHERE stock > 0——高并发下WHERE条件不足以防超卖" --type pattern；(2)/learn "双11前需要手动扩容Redis到16GB，默认4GB在大促流量下不够" --type operational --seasonal "10-01 to 11-12"；(3)/learn "大促期间CDN预热需要提前4小时完成，否则首页图片加载时间从1.2s飙升到8s" --type operational --seasonal "10-01 to 11-12"；(4)/learn "消息队列在双11峰值时可能积压超过10万条，需要配置积压告警阈值>5万条触发PagerDuty" --type operational --seasonal "10-01 to 11-12"；(5)/learn "支付回调签名的验签失败率突然从0.01%升到5%——不是代码bug，是微信支付升级了API证书，需要更新证书文件" --type pattern。
• 第12个月（第二次双11后，架构教训期，+12条）：(1)/learn "支付回调处理必须考虑通知可能重复发送——所有回调处理器必须是幂等的，使用transaction_id UNIQUE约束的去重表" --type pattern；(2)/learn "退款流程中的金额计算必须在数据库事务中进行——退款金额+退款手续费+(可能的)优惠券返还→三个数值的计算和写入不能在分开的事务中" --type pattern；(3)/learn "任何涉及多表写入的操作必须使用数据库事务或Saga模式——不能依赖‘先写A→成功→再写B’的假设" --type pattern。18个月累积到40+条learning。
• 检索效果——三次典型场景验证：场景一(新Agent写支付代码)——preamble自动检索learnings，关键词"payment/createOrder/支付/支付宝"→匹配3条("金额单位是分"+"支付回调必须幂等"+"退款金额计算必须在事务中")→注入上下文→Agent写的代码：amount用分存储9900=99.00元、回调处理器含transaction_id去重表、createOrder金额计算包裹在事务中→零错误，第一次就写对了。场景二(/review审查秒杀PR)→Security专家检索pattern learnings→匹配"秒杀库存扣减必须用Redis DECR"→审查清单增加"Verify stock deduction uses Redis DECR, not DB UPDATE WHERE stock>0"→如果PR中使用了DB UPDATE→WARNING并引用learning编号L043作为理由。场景三(双11前运维检查)→关键词"双11"+"seasonal active_window 10-01 to 11-12"→匹配Redis扩容/CDN预热/消息队列监控→Agent生成检查清单。

🔑 启示：Learnings的复合增长效应——第1个月3条learning帮助有限，第18个月40+条learning构成"项目老兵知识网络"。任何新Agent(或新开发者)第一次操作时就拥有18个月的经验积累——不是因为AI变聪明了，而是因为人类踩过的每一个坑都被转化成了结构化知识并持久化到了系统中。季节过滤(time-based relevance)是点睛之笔——"Redis扩容到16GB"在5月被检索到是噪音，在11月1日被检索到是救命稻草——时间上下文决定了知识的相关性。

[!info] 参考来源 知识积累与检索模式参考了 Retrieval Augmented Generation (RAG) 的检索增强理念和 Zettelkasten 的知识网络方法论。

§6 掌握检验

Q1：gstack learn 的三种 Learning 类型中，"微信支付 API v3 的金额单位是分，不是元"属于哪种类型？

• A) Operational（操作型）——项目特有的命令和工具
• B) Technical（技术型）——代码约定与模式（API 的字段格式、数据模型的特定约定）
• C) Pattern（模式型）——反复出现的 bug 模式和经验
• D) 不属于任何类型

Q2：learnings 检索时限制"最多返回 3 条相关 learning"——为什么是 3 条而非所有相关 learnings？

• A) 为了减少数据库查询次数
• B) 防止上下文过载——过多的 learnings 会稀释 Agent 对当前任务的注意力，3 条是最具相关性的"信号"，更多的变成"噪音"
• C) 法律要求限制为 3 条
• D) 系统硬编码了 3 条的临时限制

Q3：三种 Learning 类型（Operational / Technical / Pattern）的区分标准是什么？请各给一个电商场景下的例子（不是课程中已有的例子）。如果 Agent 错误地将一个 Pattern 类型（如"秒杀库存扣减必须用 Redis DECR"）记录为 Technical 类型——这会影响什么后续行为？

Q4：电商案例中记录了三条 learning："金额单位是分（Technical）"、"库存扣减用 Redis DECR（Pattern）"、"双11前扩容 Redis 到 16GB（Operational）"。当 Agent 在下一个双11前处理"秒杀功能开发"时，它会检索到哪些 learning？这些 learning 分别如何影响 Agent 的行为（写代码时的决策、审查时的检查清单、运维提醒）？

Q5：learnings.jsonl 文件随时间不断增长——一个活跃项目可能在 6 个月内积累 200+ 条 learning。但并非所有 learning 都永远有效——如"双11前扩容 Redis 到 16GB"在大促结束后就不再需要，但可能在下一次大促前又变得相关。learn 系统应该如何管理 learnings 的生命周期——如何标记"已过时"的学习？如何修剪（prune）不再相关的学习？如何让"季节性相关"的学习在正确的时间被检索到？

Q6：learn 系统的目标是成为"Agent 和人类共享的项目记忆"。但如果 learnings 中记录了一条错误的信息（如某个开发者错误地记录了"API 认证使用 API Key header"但实际已经改为 OAuth 2.0）——Agent 检索到这条错误 learning 后，会基于错误信息做决策。如何设计 learn 的"纠错机制"——让错误的学习可以被发现、标记、和修正？谁有权限修改 learnings（Agent 还是人类开发者）？

---

§7 答案

点击查看答案

Q1：B —— Technical 类型记录代码约定与模式——API 的字段格式、数据模型的特定约定、项目特有的编码规范。

Q2：B —— 3 条限制是"信号 vs 噪音"的权衡。

Q3：电商新例子：Operational——"部署到 staging 前必须先运行 ./scripts/seed-staging-db.sh 否则测试数据为空"。Technical——"订单状态字段 order_status 的类型是 enum ['PENDING', 'CONFIRMED', 'SHIPPED', 'DELIVERED', 'CANCELLED'] 不是任意 string"。Pattern——"任何对订单金额的计算必须在数据库事务中进行——非事务中的金额计算在并发退款场景下会导致金额不一致"。类型标记错误的影响：Pattern 被标记为 Technical → /review 的审查清单不会引用它 → 下次审查"秒杀功能"时 Security 专家可能不会检查"库存扣减是否使用了 Redis DECR"——因为这个检查项依赖于 Pattern 类型的索引。类型系统不只是分类——它决定了"谁会在什么场景下使用这个 learning"。

Q4：Agent 检索到的相关 learning：1. "库存扣减用 Redis DECR（Pattern）"——Agent 在写秒杀代码时 → 检索到这条 → 不会用 UPDATE ... WHERE stock > 0 而是用 Redis DECR。2. "双11前扩容 Redis 到 16GB（Operational）"——Agent 在审查时 → 检索到这条 → 在审查建议中提醒"请在双11前确认 Redis 容量 >= 16GB"。3. "金额单位是分（Technical）"——如果秒杀功能涉及支付 → 检索到这条 → Agent 写支付金额时使用"分"为单位（9900 = 99.00 元）。三种 learning 分别影响：写代码（Pattern → 架构选择）、审查检查（Operational → 运维提醒）、数据模型（Technical → 字段格式）。

Q5：生命周期管理：1. 标记过时——在 learning 中增加 valid_until 字段（如"扩容 Redis 到 16GB"可能设为"2026-11-12"即双11过后自动标记为"可能过时"）。2. 修剪不相关——Agent 定期（如 monthly retro）扫描 learnings.jsonl 中的 learning → 检查每条学习在过去 N 天是否被检索和使用 → 未被使用超过 90 天的 learning → 建议修剪（但人类确认后才删除）。3. 季节性相关——增加 seasonal 标签和 active_window 字段（如"双11前"→ active_window: "10-01 to 11-12"）→ 检索时根据当前日期过滤——11月1日检索到"扩容 Redis"，但1月15日不检索（不相关）。核心思想：learning 不是"永久的记忆"而是"有上下文的提醒"——上下文在，提醒在；上下文不在，提醒静默。

Q6：纠错机制设计：1. 来源标注——每条 learning 记录 created_by（Agent/用户名）和 source（哪个会话/命令生成的）→ 如果发现错误，可以追溯到来源。2. 使用反馈——Agent 在应用 learning 时如果发现"这条 learning 的描述与实际代码不一致"→ 自动标记为 needs_review → 下次人类运行 /learn 时提示"以下 learning 需要确认"。3. 人类审批——learning 分为 auto（Agent 自动生成，标记为 unverified）和 verified（人类确认过）→ 只有 verified learning 会进入审查清单等高影响力引用。4. 修改权限——Agent 可以建议修改（记录为 suggested_correction）但不能直接修改人类确认过的 learning——需要人类通过 /learn --verify <id> 确认修改。核心原则：learning 是"共享记忆"——共享意味着"信任但要验证"——Agent 贡献记忆的原始数据，人类验证记忆的准确性。

（6/6 通过）

---

延伸阅读

• [[L6-47-会话记忆恢复|上一课：会话记忆恢复]]
• [[L6-49-经验Skill化|下一课：经验Skill化]]
• [[L6-15-PR代码审查|相关：PR 代码审查]] —— learn 系统的 learnings 被 review 专家军团引用以增强审查上下文
• [[L6-36-项目复盘大师|相关：项目复盘大师]] —— retro 的趋势分析与 learn 的系统积累互补