@netpilot/skills 0.3.2 → 0.6.0

package/skills/tdd/SKILL.md

@@ -1,71 +1,55 @@
 ---
 name: tdd
-description: 当实现可观察的行为变更、核心业务逻辑、复杂条件、bug 回归或需要安全重构时使用。它严格执行红灯、绿灯、重构的小步循环并保留证据；纯文档、机械配置或没有可测试行为的改动不强制使用。
+description: 当用户要求 test-first、TDD、red-green-refactor、integration tests，或要为功能和 bug regression test 构建可观察行为时使用。它在预先确认的 Seam 上执行一次一个 test → minimal implementation 的垂直切片；纯文档、机械配置或只需事后补覆盖率时不使用。
 ---
 
 # Test-Driven Development
 
-测试驱动开发（TDD）用失败测试定义下一个行为，再用最小实现满足它。测试不是事后装饰，而是实现边界和回归证据。
+TDD 是 **red → green** 循环。本 skill 说明什么测试值得保留、测试应放在哪个 Seam、循环中的反模式和每轮规则。每个 cycle 都要在执行前和执行中遵守，而不是实现结束后回看。
 
-## 开始前
+探索代码库时读取相关 `CONTEXT.md` 与 ADR，使测试名和 Interface 词汇符合项目领域语言。Bug 的真实根因未知时，先用 `diagnosing-bugs` 建立最小复现。
 
-1. 读取项目测试约定和相邻测试，使用现有框架与命令。
-2. 把需求转成一个可观察行为，包括输入、结果和失败条件。
-3. 选择能证明行为的最低测试层级。业务规则优先单元或集成测试，跨边界行为才使用端到端测试。
-4. bugfix 先用 `diagnosing-bugs` 确认根因和复现路径，再把复现转成回归测试。
+## 好测试是什么
 
-## 循环
+测试通过 public Interface 验证 behavior，而不是 Implementation details。代码内部可以完全重写；只要外部 behavior 不变，测试就不应变化。
 
-### 1. Red：建立可信失败
+好测试读起来像 specification，例如：
 
-- 一次只写一个最小测试。
-- 运行测试并确认它因“目标行为尚未实现”而失败。
-- 若测试意外通过，说明它没有覆盖新行为，先修正测试。
-- 若因环境、语法或夹具错误失败，先修复测试基础，不能把它算作红灯证据。
+> user can checkout with valid cart
 
-### 2. Green：最小实现
+它准确说明系统提供的能力。例子见 [tests.md](references/tests.md)，mock 指南见 [mocking.md](references/mocking.md)。
 
-- 只写让当前失败测试通过所需的生产代码。
-- 不顺手实现下一项行为，不提前抽象。
-- 运行目标测试，再运行受影响范围的相关测试。
+## Seam：测试放在哪里
 
-### 3. Refactor：在绿色状态整理
+**Seam** 是测试观察 behavior 的 public Interface。测试位于 Seam，不伸进 internals。
 
-- 消除重复、改善命名和结构，但不改变外部行为。
-- 每个小改动后重跑相关测试。
-- 只有观察到真实重复或职责边界后才抽象。
+只在预先确认的 Seams 上测试。写测试前列出 public Interface 与本次要测试的 Seams，并取得用户确认，或确认它们已在批准的 spec/plan 中明确；不要在每个 cycle 重复询问已批准的同一 Seam。
 
-然后为下一个行为重复循环。
+核心问题：
 
-## 测试质量
+> Public Interface 是什么？哪些 Seams 值得测试？
 
-- 测试公共行为和业务结果，避免绑定私有实现细节。
-- 测试名表达场景与结果，不只重复函数名。
-- 每个失败应能指出哪个规则被破坏。
-- 覆盖正常路径、关键边界和有业务意义的失败路径。
-- mock 只用于真实外部边界；能用稳定的内存实现或集成测试时，不滥用交互断言。
-- 时间、随机、并发等非确定因素应显式控制。
+## 反模式
 
-## 验证记录
+- **Implementation-coupled**：mock 内部 collaborators、测试 private methods，或通过 side channel 验证，例如绕过 Interface 直接查询数据库。判断信号是：behavior 没变，内部重构却让测试失败。
+- **Tautological**：断言用与 Implementation 相同的方式重新计算 expected value，例如 `expect(add(a, b)).toBe(a + b)`。它按构造就无法反驳代码。Expected value 必须来自独立事实：known-good literal、手工演算例子或 spec。
+- **Horizontal slicing**：先写完所有测试，再写全部实现。批量测试验证的是想象中的 behavior，过早锁定测试结构，也无法利用上一轮实现带来的信息。改用 **vertical slices**：一个 test → 一个 implementation → 重复；每个 test 都是响应上一轮事实的 **tracer bullet**。
 
-交付时记录：
+## 循环规则
 
-- 首个失败测试和失败原因；
-- 使它通过的行为实现；
-- 执行过的定向测试与更广验证；
-- 未执行的验证及原因。
+### 先红后绿
 
-## 完成标准
+先写一个失败测试并运行它。必须确认失败原因是目标 behavior 尚未实现：
 
-- 每个新增或修复行为都有先失败、后通过的测试证据。
-- 目标测试和相关回归测试通过。
-- 重构没有改变范围外行为。
-- 未通过删除测试、弱化断言、跳过类型检查或隐藏失败来获得绿色结果。
+- 意外通过：测试没有覆盖新行为；
+- 因 syntax、fixture 或 environment 失败：先修复测试基础，这不算 red。
 
-## 反模式
+随后只写让当前 test 通过所需的 production code，不预测后续 tests，也不提前加入 speculative features。
+
+### 一次一个垂直切片
+
+每个 cycle 只有一个 Seam、一个 test、一个 minimal implementation。运行目标 test，再运行受影响范围的相关 tests，确认 green 后才进入下一轮。
+
+### 重构不在循环内
 
-- 不要先写完整实现再补一个会通过的测试并称为 TDD。
-- 不要一次写大量测试后才运行。
-- 不要测试框架本身或私有调用顺序。
-- 不要为了容易测试而改变正确的业务契约。
-- 不要把当前环境无法运行的测试报告为已通过。
+本循环是 red → green。结构整理属于完整 diff 可见后的 review 阶段，交给 `code-review`；不要在 cycle 中混入与当前 behavior 无关的重构。

package/skills/tdd/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "TDD"
-  short_description: "以失败测试驱动行为实现、回归保护以及安全的小步重构"
-  default_prompt: "请使用 $tdd 先建立可观察的失败测试，再用最小实现使其通过并安全重构。"
+  short_description: "在已确认 Seam 上按垂直切片严格执行 red → green 循环"
+  default_prompt: "请使用 $tdd 在已确认的测试 Seam 上一次写一个失败测试和最小实现。"
 policy:
   allow_implicit_invocation: true

package/skills/tdd/references/mocking.md

@@ -0,0 +1,70 @@
+# 何时使用 Mock
+
+只在真实 system boundaries 使用 mock：
+
+- 外部 API，例如 payment、email；
+- database，且没有合适 test database 时；
+- time 与 randomness；
+- filesystem，且真实临时 filesystem 不合适时。
+
+不要 mock：
+
+- 自有 classes/modules；
+- internal collaborators；
+- 团队完全控制且可直接运行的行为。
+
+## 为可 mock 性设计
+
+### 依赖注入
+
+把外部依赖传入，不在 Module 内创建：
+
+```ts
+// 易 mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// 难 mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+### 优先使用 SDK-style Interfaces
+
+为每项外部操作提供具体函数，不用一个带条件分支的 generic fetcher：
+
+```ts
+// GOOD
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) =>
+    fetch("/orders", { method: "POST", body: data }),
+};
+
+// BAD
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+SDK-style Interface 的收益：
+
+- 每个 mock 返回单一明确 shape；
+- test setup 不需要 conditional logic；
+- 能直接看出测试使用哪些 endpoint；
+- 每项 operation 都有独立 type safety。
+
+## 使用 Mock 前的门禁
+
+使用 mock 前必须能回答：
+
+- 这是团队无法直接控制的真实 system boundary 吗？
+- 是否有更可靠的 local substitute 或 test instance？
+- 测试断言的是业务结果，还是 mock interaction？
+- 更换内部 Implementation 时，该测试是否仍应成立？
+
+任一答案暴露内部耦合时，重新选择 Seam，不要继续堆 mock。

package/skills/tdd/references/tests.md

@@ -0,0 +1,95 @@
+# 好测试与坏测试
+
+## 好测试
+
+**Integration-style**：通过真实 public Interface 测试可观察行为，而不是 mock 内部部分。
+
+```ts
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+
+  const result = await checkout(cart, paymentMethod);
+
+  expect(result.status).toBe("confirmed");
+});
+```
+
+特点：
+
+- 验证用户或调用者关心的 behavior；
+- 只使用 public Interface；
+- 内部重构后仍成立；
+- 描述 WHAT，不描述 HOW；
+- 每个 test 聚焦一个逻辑结果。
+
+## 坏测试
+
+**Implementation-detail tests**：与内部结构耦合。
+
+```ts
+// BAD：绑定内部 collaborator
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+
+  await checkout(cart, payment);
+
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags：
+
+- mock 内部 collaborator；
+- 测试 private method；
+- 断言 call count 或 call order；
+- 外部 behavior 未变但重构会破坏测试；
+- test name 描述 HOW；
+- 绕过 Interface 从 side channel 验证。
+
+```ts
+// BAD：绕过 Interface 查询数据库
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+
+  const row = await db.query(
+    "SELECT * FROM users WHERE name = ?",
+    ["Alice"],
+  );
+
+  expect(row).toBeDefined();
+});
+
+// GOOD：仍通过 Interface 观察行为
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**：expected value 重述 Implementation，使测试按构造就会通过。
+
+Expected value 以与 Implementation 相同的方式重新计算，因此 test 天生无法反驳代码：
+
+```ts
+// BAD
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, item) => sum + item.price, 0);
+
+  expect(calculateTotal(items)).toBe(expected);
+});
+```
+
+Expected value 应来自 independent source of truth，例如已知 literal、手工演算示例或 spec：
+
+```ts
+// GOOD
+test("calculateTotal sums line items", () => {
+  expect(
+    calculateTotal([{ price: 10 }, { price: 5 }]),
+  ).toBe(15);
+});
+```

package/skills/teach/SKILL.md

@@ -1,68 +1,136 @@
 ---
 name: teach
-description: 当用户明确要在专用目录中开始或继续一个跨会话学习项目，并希望用可信资料、短课程、练习和学习记录持续提升时使用。一次性解释、普通技术调研、代码库熟悉或直接项目实现不使用。
+description: 在一个状态化教学工作区中跨会话教授用户新的技能或概念。
+argument-hint: "你想学习什么？"
+disable-model-invocation: true
 ---
 
 # Teach
 
-把一个经用户确认的目录作为长期学习工作区。围绕具体目标安排小步课程、练习、反馈和间隔复习，并用文件保存跨会话状态。
+用户要求的不只是一次解释，而是围绕一个主题持续学习。把用户确认的目录视为状态化教学工作区，让后续会话可以从真实学习证据继续。
 
-## 权限与边界
+## 教学工作区
 
-- 只有用户明确表达长期学习意图，或明确调用 `$teach` 时才启动。
-- 写入前确认教学工作区路径。当前目录是业务代码仓库且尚无教学状态时，推荐建立独立目录，不要直接污染项目根目录。
-- 明确调用只授权在已确认工作区内维护下列教学文件，不授权修改业务代码、项目配置、宿主设置、Git 状态或远程资源。
-- 一次性概念解释直接回答；需要核验技术事实但不建立学习工作区时使用 `research`；要完成工程任务时返回相应工程工作流。
+写入前确认工作区路径。如果当前目录是业务代码仓库、又没有既有教学状态，建议使用独立目录并等待用户确认。一个工作区只服务一个主学习目标；不相关主题使用另一个工作区。
 
-## 教学工作区
+按需创建以下状态，不预建空目录：
+
+- `MISSION.md`：用户为什么学习、可观察的成功标准、约束和非目标。创建或修订时读取 [mission-format.md](references/mission-format.md)。
+- `RESOURCES.md`：用于获取 Knowledge 与 Wisdom 的高可信资料和实践共同体。创建或修订时读取 [resources-format.md](references/resources-format.md)。
+- `GLOSSARY.md`：本工作区的 canonical language，只收录用户已经理解并能正确使用的术语。维护时读取 [glossary-format.md](references/glossary-format.md)。
+- `reference/*.html`：从课程中压缩出的速查表、算法、语法、动作序列和其他可反复查阅的原始学习单元。页面应美观、可打印且适合快速查询。
+- `learning-records/NNNN-*.md`：有证据支持的非显然学习成果、既有基础、已纠正误解和目标变化。写入时读取 [learning-record-format.md](references/learning-record-format.md)。
+- `lessons/NNNN-*.html`：每份只教授一个紧凑目标的自包含课程，是本工作区的主要教学单元。
+- `assets/*`：课程间复用的样式表、测验组件、模拟器和图示工具。
+- `NOTES.md`：稳定的教学偏好、约束和必要工作笔记，不是逐次会话日志。
+
+用户显式调用本 skill，只授权在已确认的教学工作区内维护这些教学资产。不修改业务代码、项目配置、Git 状态、宿主设置或远程系统。
+
+## 教学哲学
+
+深层学习需要三样东西：
+
+- **Knowledge**：来自高质量、高可信资料的知识；
+- **Skills**：通过与你设计的、高度相关且可交互的课程练习获得的技能；
+- **Wisdom**：在学习环境之外与其他学习者和实践者互动后形成的判断力。
+
+在 `RESOURCES.md` 尚未拥有足够可靠资料前，优先补齐资料。不要把参数化记忆当作事实来源。不同主题的重心不同：理论主题可能更依赖 Knowledge；身体、表演或操作性主题可能更依赖 Skills。
+
+### 流畅强度与存储强度
+
+区分两种学习强度：
+
+- **Fluency strength**：当下能够顺畅提取或复述；
+- **Storage strength**：经过时间后仍能提取、应用和迁移。
+
+流畅会制造已经掌握的错觉，长期保持才是目标。用 desirable difficulty 建立 Storage strength：
+
+- retrieval practice：不看答案，从记忆中提取；
+- spacing：把练习分散到不同时间；
+- interleaving：在技能练习中交错相关主题，而不是连续重复同一题型。
+
+## 每次教学会话
+
+1. 读取 `MISSION.md`、`RESOURCES.md`、`GLOSSARY.md`、相关学习记录、近期课程和必要笔记，恢复当前状态。
+2. 若 mission 缺失或含糊，一次只问一个问题，直到真实动机、可观察结果和约束足以指导教学；系统访谈可使用 `$grilling`，完成后回到本流程。
+3. 用短诊断、回忆题或小任务估计用户当前基础和 Zone of Proximal Development。自述可以作为线索，但不能替代掌握证据。
+4. 从高可信资料获得本课所需 Knowledge；资料不足、事实可能变化或用户要求核验时，使用 `$research` 完成有停止条件的调查，再把筛选后的来源写入 `RESOURCES.md`。
+5. 只设计下一节最小课程：一个目标、必要知识、一次主动练习、紧反馈和一个高可信主要来源。课程必须直接服务 mission，并位于用户的 Zone of Proximal Development。
+6. 用户完成练习后检查证据。只有用户能正确回忆、应用或迁移时，才更新学习记录或术语表；material covered 不等于 material learned。
+7. 总结本次小胜利、仍不稳固之处、适合的复习时机和下一节候选目标。
+
+`$teach` 可以调用 `$grilling` 或 `$research`；被调用 skill 返回访谈结果或证据后，控制权回到当前教学会话，不启动第二个 `$teach`。
+
+## 课程
+
+Lesson 是 Knowledge 和 Skills 到达用户的主要单元。每节是一个自包含 HTML 文件，保存为 `lessons/0001-<dash-case-name>.html`、`0002-...`，编号递增。
+
+每节 lesson：
+
+- 只教授一个紧凑目标，短到可以很快完成，并让用户获得一个可继续累积的有形成果；
+- 直接追溯到 `MISSION.md`，难度处于当前 Zone of Proximal Development；
+- 使用清晰、可读、高信息密度、响应式且可打印的排版，使用户愿意日后复习；
+- 通过 HTML anchors 链接相关 lessons 和 reference documents；
+- 推荐一个实际核验过、最适合本课的高质量主要来源；
+- 提醒用户可以向 agent 追问不清楚之处；
+- 包含主动练习与尽可能即时、最好自动化的反馈，而不是只让用户继续阅读。
+
+生成后返回文件的绝对路径。只有用户要求时才打开浏览器或外部应用。
+
+## 可复用资产
+
+Lessons 由 `assets/` 中可复用的 components 构建：样式表、quiz widgets、simulators、diagram helpers，以及任何后续 lesson 会复用的内容。
+
+创建 lesson 前先检查已有 `assets/`。能够复用时直接复用；需要新的通用 component 时将它写入 `assets/` 并从 lesson 链接，不在多个 lesson 中复制。共享样式表是第一个合理的 component，因为每节课都会使用它；随着工作区增长，component library 也应随真实复用点增长。
+
+## 学习使命
+
+每节 lesson 都必须服务用户学习该主题的真实原因。若用户无法说明为什么学习，或 `MISSION.md` 尚未建立，先访谈 mission；没有 mission，就无法判断下一步应该教什么，课程也会变得抽象。
+
+Mission 会随着 Skills 和 Knowledge 增长而变化。变化时先与用户确认，再更新 `MISSION.md`，并用 learning record 记录这次变化及其对后续教学的影响。
+
+## 最近发展区
+
+每节课都应让用户感到“刚好需要努力”。用户可以指定下一项学习内容；否则根据 mission 与 learning records，选择最相关、又刚好超出其独立完成能力的下一项。
+
+## 知识
+
+Lesson 应围绕用户要获得的一项 skill 设计，只教授获得该 skill 必需的 Knowledge。先给必要知识，再让用户进入互动反馈循环。
+
+Knowledge 必须优先来自 `RESOURCES.md` 中的可信资料。课程中的事实性主张应就近链接外部来源；推断和经验判断明确标注。获取 Knowledge 时，无关难度会占用理解所需的 working memory，应尽量降低。
+
+## 技能
+
+Knowledge 关乎获得，Skills 关乎耐久与迁移。技能练习可以有意增加难度，因为 effortful retrieval 会提高 Storage strength。
+
+可用形式包括：
 
-按需创建文件，不要预先生成空目录：
+- 带 quiz 或轻量浏览器任务的 interactive lessons；
+- 引导用户在真实环境中完成一组步骤的 lessons；
+- 能立即对表现给出反馈的模拟器或小任务。
 
-- `MISSION.md`：学习动机、可观察成功标准、约束和非目标。创建或修订时读取 [mission-format.md](references/mission-format.md)。
-- `RESOURCES.md`：经筛选并带用途说明的可信资料。创建或修订时读取 [resources-format.md](references/resources-format.md)。
-- `GLOSSARY.md`：用户已经理解并能正确使用的统一术语。需要维护时读取 [glossary-format.md](references/glossary-format.md)。
-- `lessons/NNNN-*.html`：每次一个目标、可快速完成的自包含课程。
-- `reference/*`：可重复查阅的速查表、示例、流程图或术语资料；默认使用适合内容的 HTML 或 Markdown。
-- `learning-records/NNNN-*.md`：已经有证据表明用户掌握的关键知识。写入时读取 [learning-record-format.md](references/learning-record-format.md)。
-- `assets/*`：至少会被两个课程复用的样式、测验或模拟组件。
-- `NOTES.md`：稳定的教学偏好、约束和必要工作笔记；不要写成逐次聊天日志。
+每项练习都必须有 feedback loop，并尽量缩短“尝试—反馈”的距离。选择题各选项词数必须一致，字符数尽可能一致；格式、措辞和长度不得泄露答案。
 
-一个工作区只服务一个主学习目标。无关主题使用另一个目录。
+## 获得判断力
 
-## 工作流
+Wisdom 来自在学习环境之外检验 Skills。遇到需要实践判断的问题时，先尽力回答，同时指出哪些部分需要由真实共同体反馈。
 
-1. 读取已有的 `MISSION.md`、`RESOURCES.md`、`GLOSSARY.md`、学习记录、近期课程和必要笔记，恢复当前状态。
-2. 如果目标不具体，一次只问一个问题；需要系统访谈时调用 `grilling`，由它返回目标、成功标准、约束和已知基础后继续本流程。
-3. 通过短诊断、回忆题或小任务判断用户当前基础和最近发展区。不要只依据“我看懂了”判断掌握。
-4. 资源不足、事实可能变化或用户要求核验时，调用 `research` 完成一个有停止条件的研究项；接收其带来源结论并筛选进 `RESOURCES.md`。不要把搜索摘要或模型记忆当作事实依据。
-5. 只设计下一节最小课程：给出单一学习目标、必要知识、一个主动练习、即时反馈方式和可信来源。优先让用户检索、应用和解释，而不是继续阅读。
-6. 用户完成练习后检查证据。只有能够正确回忆、应用或迁移时，才更新学习记录或术语表；“已经讲过”不等于“已经学会”。
-7. 给出本次收获、仍不稳固之处、建议复习时间和下一节候选目标。不要一次生成完整课程体系。
+共同体可以是高质量论坛、专业社区、线下课程或本地兴趣小组。优先寻找声誉良好、治理清晰且适合 mission 的共同体；只提供建议，不自动加入、发帖、联系他人或购买服务。用户不愿参与共同体时尊重并记录这一偏好。
 
-调用关系必须保持单向：`teach` 可以调用 `grilling` 或 `research`，它们返回访谈结果或证据后由原流程继续；被调用 skill 不得重新启动新的 `teach`。
+## 参考文档
 
-## 课程设计
+创建 lessons 时同步识别值得长期查阅的 reference documents。Lesson 可能很少重看，reference documents 会被反复使用，因此它们应把课程压缩为快速可用的形式。
 
-- 每节课程只追求一个可观察的小胜利，并直接服务 `MISSION.md`。
-- 知识讲解降低无关难度；技能练习增加适度的检索难度，并提供尽可能短的反馈回路。
-- 通过间隔复习和相关主题交错提升长期保持，不用当下答题流畅度冒充长期掌握。
-- 选择题不得通过选项长度、格式或措辞泄露答案。
-- 课程引用尽量链接到官方文档、规范、论文、原始数据或公认的一手材料；推断和经验判断要明确标注。
-- HTML 课程应可访问、响应式、可打印并复用已有资产。只有产生第二个真实复用点时才抽取新组件。
-- 只返回课程文件路径；仅在用户要求时打开浏览器或其他应用。
+适合成为 reference 的内容包括：
 
-## 完成标准
+- 编程语法与代码片段；
+- 流程的算法与流程图；
+- 动作、姿势和练习序列；
+- 训练动作与计划；
+- 任何有专门 nomenclature 的主题 glossary。
 
-- 已确认工作区、学习目标和当前基础。
-- 本次课程只有一个清楚目标，并包含主动练习、反馈方式和可信来源。
-- 学习状态只依据真实证据最小更新，没有把覆盖内容当成掌握。
-- 用户知道本次结果、建议复习时间和下一步。
+Glossary 尤其重要。一旦建立，后续 lessons、references 和 learning records 都应使用其中的 canonical language。
 
-## 反模式
+## `NOTES.md`
 
-- 不要在普通代码仓库根目录未经确认地创建一组教学文件。
-- 不要依靠模型记忆编造课程事实或引用。
-- 不要把课程做成长篇百科、完整训练营或华而不实的页面。
-- 不要因为用户读过或听过就写入学习记录或术语表。
-- 不要自动加入社区、发帖、联系他人、购买课程或打开外部应用。
-- 不要让教学工作流修改业务代码、提交、推送或代替工程交付流程。
+当用户表达稳定的教学偏好、需要长期记住的限制或其他会影响课程设计的信息时，记录到 `NOTES.md`。保持紧凑，不记录逐次活动，也不重复其他教学资产已经保存的内容。

package/skills/teach/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Teach"
-  short_description: "建立可信资料驱动的跨会话学习工作区，用短课程与练习持续推进"
-  default_prompt: "请使用 $teach 在专用目录中建立跨会话学习工作区，并从我的目标设计第一课。"
+  short_description: "在状态化学习工作区中用可信资料、短课和练习持续教学"
+  default_prompt: "请使用 $teach 在我确认的工作区中建立跨会话学习项目，并设计下一节最小课程。"
 policy:
-  allow_implicit_invocation: true
+  allow_implicit_invocation: false

package/skills/teach/references/glossary-format.md

@@ -1,21 +1,46 @@
 # `GLOSSARY.md` 格式
 
-`GLOSSARY.md` 保存用户已经理解的统一术语，而不是待背诵的外部词典。
+`GLOSSARY.md` 是教学工作区的 canonical language。所有 lessons、reference documents 和 learning records 都应遵循它。把概念压缩成准确定义本身就是学习证据，因此只有用户已经理解的术语才进入这里。
 
-```markdown
+## 模板
+
+```md
 # {主题} Glossary
 
-## Terms
+{用一至两句说明本 glossary 覆盖的主题和适用边界。}
+
+## 术语（Terms）
 
 **{主术语}**：
-{一至两句准确、紧凑的定义。}
+{用一至两句说明它是什么。}
 _避免使用_：{容易混淆的别名，如有}
+
+**{另一主术语}**：
+{紧凑定义。定义中优先使用已经收录的主术语。}
+_在本工作区中_：{若外部世界对此词使用含糊，明确本工作区采用的含义。}
+```
+
+## 完整条目示例
+
+```md
+## 术语（Terms）
+
+**Idempotency（幂等性）**：
+同一操作执行一次或重复执行多次，对系统可观察状态产生相同最终结果。
+_避免使用_：把“可以安全重试”当作幂等性的完整同义词；重试还涉及时序、错误分类和外部副作用。
+
+**Retry（重试）**：
+一次操作未获得可接受结果后，依据明确策略再次尝试。重试策略必须说明哪些失败可重试、最大次数与退避方式。
+_在本工作区中_：只有不会重复制造外部副作用的尝试才称为安全重试。
 ```
 
-规则：
+## 规则
 
-- 只有用户能正确解释或使用术语后才收录。
-- 同一概念选择一个主名称，把其他叫法标为应避免别名。
-- 定义说明“它是什么”，保持一至两句；需要教程时链接课程或参考资料。
-- 已收录术语应在后续课程和记录中保持一致。
-- 理解加深时原位修订，并在存在实质认知变化时补充学习记录。
+- **理解之后再加入。** Glossary 是 compressed knowledge 的记录，不是用户尚未学会的外部词典。刚介绍过一个概念并不够；等用户能正确解释或使用后再收录。
+- **作出主名称选择。** 同一概念存在多个名称时，选择最准确的一个，把其余列为应避免的 aliases。统一语言本身会压缩后续学习成本。
+- **定义保持紧凑。** 一至两句，说明术语是什么，而不是完整教程或操作步骤；教程链接到 lesson 或 reference。
+- **用 glossary 自己的词定义新词。** 已收录术语应在后续定义和全部教学资产中优先使用，复杂概念会因此更容易掌握。
+- **自然成组时使用子标题。** 例如 `## Anatomy`、`## Programming`；术语本就属于同一组时保持扁平。
+- **显式解决含糊。** 外部领域松散使用某词时，写明“在本工作区中……”的唯一含义，避免每节课重新解释。
+- **理解加深时原位修订。** 早期定义可能被后续学习纠正；更新旧定义，不保留失效条目。若这代表重要认知变化，同时写 learning record。
+- **不重复学习记录。** Glossary 保存定义；learning records 保存非显然洞见、证据及其对后续教学的影响。

package/skills/teach/references/learning-record-format.md

@@ -1,18 +1,48 @@
-# 学习记录格式
+# Learning Record 格式
 
-学习记录位于 `learning-records/`，使用 `0001-slug.md`、`0002-slug.md` 的连续编号。仅在出现第一条合格记录时创建目录。
+Learning records 位于 `learning-records/`，文件名使用递增编号：`0001-<slug>.md`、`0002-<slug>.md`。只有出现第一条合格记录时才创建目录。
 
-```markdown
-# {已经掌握或修正的关键认识}
+它们相当于教学领域的 ADR：保存会改变未来课程选择的非显然学习、关键洞见、已纠正误解和用户已经具备的基础，用于判断 Zone of Proximal Development。
 
-{1 至 3 句说明用户展示了什么理解、证据是什么，以及它如何改变后续教学。}
+## 基本模板
+
+```md
+# {已经学会或确认的简短标题}
+
+{用 1 至 3 句说明学会了什么或确认了什么既有基础、证据是什么，以及它为什么会改变后续教学。}
 ```
 
-满足以下任一条件才记录：
+完整格式可以只有这一个段落。价值在于记录“这件事现在已经有证据成立”以及“它改变了什么”，不在于填满栏目。
+
+## 可选内容
+
+只有确实增加价值时才加入；大多数记录不需要：
+
+- `status: active | superseded-by: LR-NNNN` frontmatter：旧理解后来被纠正或替代时使用；
+- `## Evidence`：记录用户如何展示理解，例如正确回答、完成练习、解释迁移案例或提供可核验的既有经验；
+- `## Implications`：说明这项学习为后续 lessons 解锁或排除了什么，适合影响不显然的情况；
+- 指向 `MISSION.md`、lesson 或 reference document 的链接：只在它们直接支撑本记录时加入。
+
+## 编号
+
+扫描 `learning-records/` 中现有文件的最大编号并加一。不要复用已删除或 superseded 的编号，也不要根据文件数量猜下一个编号。
+
+## 何时记录
+
+满足以下任一条件时写一条：
+
+1. **用户展示了对非平凡内容的真实理解。** 不只是接触过，而是能正确回忆、应用或迁移；这为后续教学设定了新的起点。
+2. **用户披露了既有基础。** 记录“已经知道什么”以及所声称或展示的深度，避免未来重复教授。
+3. **重要误解已经纠正。** 记录旧理解为什么不成立以及新理解带来的影响；这类记录能预测相关主题中的未来困难。
+4. **学习使 mission 发生变化。** 用户发现自己真正关心的目标不同于最初设想；先更新并链接 `MISSION.md`，再记录变化。
+
+## 不应记录
+
+- 仅仅讲过或读过的 material。Coverage 不是 learning，等待掌握证据。
+- 已经由 `GLOSSARY.md` 紧凑保存的纯术语定义。不要重复。
+- 每次会话做了什么的流水账。Learning records 不是日记。
+- 尚未验证的推测、礼貌性“我懂了”或 agent 对用户水平的单方面判断。
 
-1. 用户能正确回忆、应用或迁移一个非平凡概念。
-2. 用户说明已有基础，并提供了足以判断深度的证据。
-3. 一个重要误解已经通过练习被纠正。
-4. 学习结果使目标发生变化，且用户已确认修订 `MISSION.md`。
+## 替代关系
 
-不要记录仅仅讲过的内容、重复的术语定义或逐次会话流水账。后来的证据推翻旧记录时，标记旧记录被新编号取代，不要删除学习轨迹。
+后续证据推翻或深化旧记录时，不删除历史。创建新编号，并把旧记录标记为 `superseded-by: LR-NNNN`。理解如何演化本身就是未来教学的有用信号。

package/skills/teach/references/mission-format.md

@@ -1,28 +1,31 @@
 # `MISSION.md` 格式
 
-`MISSION.md` 位于教学工作区根目录，说明为什么学习以及什么结果才算成功。所有课程、资料和练习都应能追溯到它。
+`MISSION.md` 位于教学工作区根目录，记录用户为什么学习这个主题。之后教什么、推荐什么资料、设计什么练习，都应能追溯到它。
 
-```markdown
+## 模板
+
+```md
 # Mission: {主题}
 
-## Why
-{1 至 3 句具体说明：掌握后，工作或生活会发生什么可观察变化。}
+## 为什么学习
+{用 1 至 3 句描述用户追求的真实结果。掌握后，工作或生活会发生什么可观察变化？不要停在“理解 X”，继续追问它服务什么结果。}
 
-## Success looks like
-- {用户能够完成的具体行为}
-- {另一项可观察结果}
+## 成功是什么样
+- {用户将能完成的一项具体、可观察行为}
+- {另一项具体结果}
+- {……}
 
-## Constraints
-- {时间、预算、基础、可用工具或学习偏好}
+## 约束
+- {时间、预算、既有承诺、可用工具、学习偏好或其他边界}
 
-## Out of scope
-- {当前明确不学习的相邻主题}
+## 超出范围
+- {用户当前明确不追逐的相邻主题，用来保护 Zone of Proximal Development}
 ```
 
-规则：
+## 规则
 
-- 一个工作区只保留一个主目标。
-- 用“完成某事”替代“了解某物”。
-- 目标不具体时先访谈，不要用假设填空。
-- 现实目标变化时先向用户确认，再修订文件并记录原因。
-- 保持在一屏左右；它是方向标，不是完整学习计划。
+- **一个工作区一个 mission。** 两个互不相关的学习目标使用两个工作区。
+- **具体胜过抽象。** “十月前跑完半程马拉松”胜过“变得更健康”；“向团队交付一个 Rust CLI”胜过“学习 Rust”。
+- **挑战含糊表达。** 用户说不清 Why 时，先逐题访谈，不要替其填出一个听起来合理的 mission。坏 mission 比暂时没有更容易误导后续教学。
+- **现实变化时修订。** 用户的目标移动后，先确认，再更新本文档并写 learning record；不要让过期 mission 继续掌舵。
+- **保持一屏以内。** `MISSION.md` 是指南针，不是完整计划。超过一屏时删去执行细节，只保留方向与边界。