# Oblearn

> 从项目内 agent 记忆库、设计/计划文档、ADR、最近变更，或非项目临时会话摘要、会话记录中提取可跨场景复用的经验，并沉淀到 Obsidian 公共知识笔记。适用于用户说 $oblearn、沉淀经验、提取公共知识、复盘项目、同步 lessons 到 Obsidian、从当前对话、粘贴 transcript 或会话记录提炼经验，或希望把已记录经验转成公共知识。

- Skill: `geekxtop/oblearn` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add geekxtop/oblearn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/geekxtop/oblearn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: GeekXtop (https://skillmd.com/u/geekxtop)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/geekxtop/oblearn

---


# Oblearn

从当前项目或用户明确提供的临时会话材料提取“可复用知识”，写入 Obsidian 的 `Agent/Knowledge/`。它不是初始化工具，不创建项目入口文件；项目初始化使用 `$obinit`。

## 职责边界

`oblearn` 只负责从当前项目材料或非项目临时会话材料中提取、脱敏和写入可复用知识。

- 可以追加到明确匹配的已有公共知识笔记。
- 可以在新知识无明确稳定主题时，建议写入 `Agent/Knowledge/Inbox/`。
- 可以在追加或新建笔记时只做最小维护，例如补必要 frontmatter、`aliases` 或修正当前写入会用到的 wikilink。
- 可以在没有项目 memory 时，从当前对话、用户摘要、粘贴 transcript 或用户提供的会话记录 中提取公共经验。
- 不负责初始化临时目录或为非项目任务创建 `.agents/`。
- 不负责全库重分类，不做批量移动、重命名、合并、拆分或重建索引。
- 结构性整理交给 `$obcurate`，例如清理 Inbox、合并重复主题、拆分过长笔记、整理 `Agent/Knowledge/_catalog.md`。

## 运行时假设

- 写入公共知识需要桌面端已打开目标 vault 且 `obsidian` CLI 可用；CLI 不可用或无法解析 vault 本地路径时请用户提供或确认路径，不退回 CLI mutation。
- 非项目临时会话模式需要用户提供摘要、transcript 或可精确定位的会话记录；只读取精确匹配的 transcript，不扩大扫描无关历史。
- 项目模式需要项目内 memory 可读；没有项目 memory 时按非项目临时会话处理，不要求先 `$obinit`。
- 追加前先读取目标笔记当前内容；已有条目与本次结论重复时合并或跳过，不追加近似重复条目。

## 默认行为

用户只说 `$oblearn` 或“提取公共知识”时，按安全默认值执行：

- 如果用户明确提供临时会话摘要、transcript、会话记录 或指定非项目材料，按非项目临时会话模式处理，即使当前目录存在项目 memory。
- 如果用户没有指定非项目材料，且当前目录有项目 memory，读取当前项目的记忆库、设计/计划/ADR 和最近变更摘要。
- 如果用户没有指定非项目材料，且当前目录没有项目 memory，按非项目临时会话处理；只使用当前对话、用户提供的摘要、transcript 或可精确定位的会话记录，不要求先 `$obinit`。
- 只提取跨项目可复用的经验，不复制项目私有业务内容。
- 先读取 `Agent/Knowledge/_catalog.md`（如果存在）作为已沉淀领域的事实来源。
- 再用候选主题、技术栈、错误信息或平台名做关键词定向搜索。
- 明确匹配已有笔记时，可以追加短条目。
- 需要新建公共知识笔记时，优先建议写入 `Agent/Knowledge/Inbox/` 并等待用户确认。
- 只有本次已确认写入目标、关键词明确且不含敏感信息时，才对 `Agent/Knowledge/_catalog.md` 做最小明确更新。
- 不扫描整个 vault。
- 不凭空假设某个领域已经沉淀；没有 `_catalog.md` 命中或搜索命中时，就按新知识处理。
- 不写 secret、账号、token、客户信息、内部路径细节。
- 不把设计/计划文档原文复制进 Obsidian。
- 新建或追加的 Obsidian 公共知识和项目回写内容默认遵循用户或项目既有语言偏好；当前模板使用简体中文。技术标识符、路径、命令、包名和英文专有名词保持原样。

## 输入来源

项目模式下，按需读取这些项目内文件：

```text
.agents/instructions.md
.agents/active.md
.agents/handoffs/
.agents/progress.md
.agents/lessons.md
.agents/archive/progress-YYYY.md
docs/adr/
# 项目内既有的设计/计划文档（路径以 .agents/active.md 指向为准）
```

`.agents/archive/` 读取范围由明确证据触发：`.agents/active.md`、`.agents/progress.md` 或 `.agents/lessons.md` 指向归档；用户要求复盘长期项目；或当前候选知识需要旧阶段证据。

如果是 git 项目，可以读取最近变更摘要：

```bash
git status --short
git diff --stat
git log -5 --oneline
```

只读取与当前任务、当前 spec/plan 或用户指定范围相关的文档；不要遍历大型目录。

## 非项目临时会话

当前目录没有 `.agents/instructions.md`，或任务明显不属于软件项目时，不要要求用户先运行 `$obinit`。

可用输入：

- 当前对话中明确出现的事实、命令、错误和结论。
- 用户粘贴的 transcript、命令输出或会话摘要。
- 用户提供的会话记录，且本机能在 本机会话存储中精确定位对应 transcript。
- 用户明确指定的本地文件或笔记。

如果用户提到“昨天的 Codex app 对话”“之前那个临时任务”等历史会话，但当前上下文没有 transcript、摘要或会话记录，不能假装能自动读取历史；先请用户提供摘要、关键命令、错误信息、结论或 session id。

### 会话记录定位

用户提供会话 id 或导出的 transcript 时，把它作为授权和定位线索，做精确本地查找。通用原则：

- 只用完整 id 做精确匹配；不要按日期、关键词或标题扩大扫描历史会话。
- 优先使用文件名或元数据中 id 精确相等的记录。
- 只命中派生关系（如 fork、parent、child）时不算目标记录；继续查找目标 id，找不到就向用户说明。
- 不运行交互式恢复命令读取历史；那类命令用于恢复会话，不是导出。
- 找到唯一记录后，可以读取该记录并从 user / assistant / tool 事件中提取候选经验；不要把完整对话原文写入公共知识。
- 找不到或命中不唯一时，请用户提供摘要、导出的 transcript 或明确文件路径。

示例（Codex）：`$CODEX_HOME/session_index.jsonl`、`$CODEX_HOME/sessions/`、`$CODEX_HOME/archived_sessions/`；未设置 `$CODEX_HOME` 时使用 `%USERPROFILE%\.codex` 或 `~/.codex`。其他工具按各自的本机会话存储格式定位。

非项目模式下：

- 只提取跨场景可复用的操作经验、检查清单、风险提示或调试结论。
- 默认建议写入 `Agent/Knowledge/Inbox/<简短主题>.md`，并设置 `status: draft`。
- 主题应从候选知识的核心适用范围中提炼，优先使用平台、技术栈、命令、错误类型、风险类型或工作流类型等真实信号；不要把说明性示例、会话背景或临时任务外壳当成固定分类，也不要把所有临时会话归到同一主题。
- 仍然先读 `Agent/Knowledge/_catalog.md` 并用关键词定向搜索；不要全 vault 扫描。
- 不创建 `.agents/`、`docs/adr/`、项目 Obsidian 笔记或项目 memory。
- 不记录本机磁盘清单、绝对路径细节、账号、隐私信息、客户数据、token 或 secret。
- 不把聊天摘要原文作为公共知识；只把经过泛化、脱敏、可执行的经验写入公共知识。

## 可提取内容

只提取满足至少一条的内容：

- 其他项目也可能遇到的坑。
- 可复用的框架约定、目录约定、组件约定。
- 可执行检查清单。
- 已验证的调试结论。
- 长期有效的技术取舍。
- 多次出现或明显高成本的错误模式。
- 临时会话中可迁移到其他机器、项目或操作任务的安全步骤。

不要提取：

- 本项目专属业务逻辑。
- 临时任务状态。
- 聊天摘要原文。
- 未验证猜测。
- 大段 spec/plan 原文。
- secret、账号、密钥、客户数据、隐私信息。
- 与已退役（`deprecated`）笔记同结论的经验。

## 输出目标

`oblearn` 只写入 `Agent/Knowledge/`，不写入 `Agent/Documents/`。`Agent/Knowledge/` 保存短经验、规则、检查清单和启发式判断；`Agent/Documents/` 保存 `$obdoc` 生成的人类可读文档。

用户指定路径优先；已有明确命中的公共知识笔记优先追加；不稳定时建议写入 `Agent/Knowledge/Inbox/` 并设置 `status: draft`；稳定归类、移动、合并或拆分交给 `$obcurate`。

优先追加到定向搜索命中的已有 Obsidian 公共知识笔记：

```text
Agent/Knowledge/<主题>.md
```

主题应来自用户指定路径、`Agent/Knowledge/_catalog.md` 命中、定向搜索命中或用户确认。如果没有合适笔记，先向用户提出新建建议，不要擅自创建一堆分类。

新知识尚未稳定归类时，建议目标是：

```text
Agent/Knowledge/Inbox/<简短主题>.md
```

`Agent/Knowledge/_catalog.md` 是已沉淀领域的事实来源。它只记录已经存在或本次确认创建的公共知识入口，不记录猜测分类。

建议结构：

```yaml
## terms

- term: <关键词>
  aliases: []
  kind: knowledge
  use_as: rule
  notes:
    - [[<真实笔记标题>]]
```

`kind` 表示命中对象的类型，`use_as` 表示查到后怎么用。`oblearn` 写入的是 `kind: knowledge`；常见 `use_as` 是 `rule`、`checklist` 或 `heuristic`。机器层使用英文 token，中文展示用于正文、计划和完成说明，例如“类型：知识（`kind: knowledge`）”“用途：检查清单（`use_as: checklist`）”。最小明确更新 catalog 时只使用真实笔记标题、已有 frontmatter、用户确认的别名或本次知识的明确关键词。无法判断时，不登记，只列出维护建议并交给 `$obcurate`。

## 知识生命周期

公共知识笔记用 frontmatter `status` 表示生命周期：`draft` 表示未稳定归类，`active` 表示默认可用，`needs-review` 表示待复核（有怀疑但无直接证据），`deprecated` 表示已退役（有直接证伪证据或人工裁决）。`last_verified: YYYY-MM-DD` 记录最近一次真实使用验证；缺失时按 `created` / `updated` 推断新旧，不批量回填。

- 已退役笔记保留原文，在正文顶部追加 `## 退役` 小节：退役原因、证据、日期和（如有）替代笔记的 wikilink。
- 检索命中 `deprecated` 或 `needs-review` 笔记时不作为有效经验使用；退役记录只作为“此路不通”的反例背景。
- 候选知识与已退役笔记同结论时不重新提取为有效经验；如有新证据推翻退役结论，先列出复核建议等用户裁决。
- `status` 变更按证据强度分级：有直接证伪证据可标 `deprecated` 并附证据；仅怀疑标 `needs-review`；批量复查、恢复裁决和删除属于 `$obcurate`。

## Tags

`tags` 是辅助 metadata，用于 Obsidian UI、Bases、Dataview、人工筛选和低频整理辅助，不作为 agent 发现入口。agent 发现公共知识以 `Agent/Knowledge/_catalog.md` 的 `terms` / `aliases` / `kind` / `use_as` 为准。

新建公共知识笔记可以使用粗粒度 tag，例如 `agent/knowledge` 或 `skill/design`。不要用 tags 替代 `kind: knowledge`、`source_skill: oblearn`、catalog 入口或脱敏判断。

## Obsidian 写入

所有 Obsidian Markdown mutation，包括创建、覆盖、追加、局部修改、frontmatter、catalog 或项目笔记更新，以及移动和重命名，都直接操作 vault 本地文件系统。

`obsidian` CLI 只用于 vault 定位、有限搜索、读取和写入后读回校验。

不得以 `obsidian create`、`obsidian append`、`obsidian prepend`、`obsidian property:set`、`obsidian move`、`obsidian rename` 或 `content=` 作为写入或回退路径。

无法解析 vault 本地路径时，请用户提供或确认目标 vault 的本地文件系统路径，再执行文件操作。

写入前先读取目标文件的当前内容；发现本次范围外的外部改动时停止写入并列出待确认项，不覆盖对方内容。

## 工作流

项目模式：

1. 确定项目根目录。
2. 读取 `.agents/active.md`，确认当前任务、当前 spec/plan、项目笔记路径。
3. 读取 `.agents/lessons.md` 和相关 `.agents/progress.md` 条目。
4. 如当前材料指向归档或用户要求长期复盘，读取 `.agents/archive/` 中相关年份文件。
5. 按 `.agents/active.md` 指向读取相关 spec/plan/ADR。
6. 从材料中列出候选知识，每条包含来源、证据、适用范围、建议目标笔记。
7. 过滤掉项目私有、未验证、过细或不可复用内容。
8. 读取 `Agent/Knowledge/_catalog.md`（如果存在），用候选关键词匹配 `terms` 和 `aliases`。
9. 用 Obsidian CLI 定向搜索目标笔记。
10. 对明确匹配的已有笔记追加短条目。
11. 对需要新建的笔记，先列清单等用户确认；默认建议放入 `Agent/Knowledge/Inbox/`。
12. 写入完成后，如关键词和目标明确，对 `Agent/Knowledge/_catalog.md` 做最小明确更新；不明确时只列出 `terms` / `aliases` / `notes` 建议，并建议 `$obcurate` 处理。
13. 更新项目 Obsidian 笔记的 `相关知识`。
14. 读回本次写入的笔记和 `Agent/Knowledge/_catalog.md`，核对条目、frontmatter、`terms` / `aliases` 和 wikilink。
15. 在 `.agents/active.md` 或 `.agents/lessons.md` 记录本次提取结果。

非项目临时会话模式：

1. 确认没有可用项目 memory，或用户明确要求从临时会话提取经验。
2. 从当前对话、用户摘要、transcript 或精确匹配的会话记录 中列出候选知识，每条包含来源、证据、适用范围、脱敏点和建议目标笔记。
3. 如果证据不足，先请用户补充关键命令、错误信息、结论或上下文。
4. 过滤掉本机私有路径、隐私、secret、未验证猜测和不可复用聊天内容。
5. 读取 `Agent/Knowledge/_catalog.md`（如果存在），用候选关键词匹配 `terms` 和 `aliases`。
6. 用 Obsidian CLI 定向搜索目标笔记。
7. 对明确匹配的已有笔记追加短条目。
8. 对需要新建的笔记，先列清单等用户确认；默认建议放入 `Agent/Knowledge/Inbox/`。
9. 写入完成后，如关键词和目标明确，对 `Agent/Knowledge/_catalog.md` 做最小明确更新；不明确时只列出 catalog 建议，并建议 `$obcurate` 处理。
10. 读回本次写入的笔记和 `Agent/Knowledge/_catalog.md`，核对条目、frontmatter 和 wikilink。
11. 不回写项目 memory。

## Obsidian 查找

使用关键词定向搜索：

```bash
obsidian read path="Agent/Knowledge/_catalog.md"
obsidian search query="<主题关键词>" limit=5
obsidian read path="Agent/Knowledge/<实际命中笔记>.md"
```

`Agent/Knowledge/_catalog.md` 只在本次实际写入公共知识且有明确关键词时建议创建或更新。

Obsidian 查找使用关键词定向搜索。搜索词应来自候选知识本身的技术栈、错误信息、平台名、命令名或用户确认的主题；搜索没有命中时，按新知识处理。

## 公共知识条目格式

追加到公共知识笔记时，使用短条目：

使用 `templates/public-knowledge-entry.md`。

条目要能被下一个 agent 直接执行，不写散文。

## 新建公共知识笔记模板

仅在用户确认后创建：

使用 `templates/public-knowledge-note.md`。

如果用户没有指定稳定主题，默认创建在 `Agent/Knowledge/Inbox/`，并设置 `status: draft`。稳定归类、移动、合并或拆分由 `$obcurate` 后续处理。

引用真实存在或本次确认创建的 Obsidian 笔记时使用 wikilink。外部链接用标准 Markdown 链接。

## Catalog 最小更新

`Agent/Knowledge/_catalog.md` 用于让后续 agent 知道哪些领域已经沉淀过。它不是分类体系，不要求完整，不是全 vault 索引。

可以最小更新 catalog 的情况：

- 本次追加到已有笔记，且候选关键词明确匹配该笔记。
- 本次新建笔记，且用户确认标题、别名或关键词。
- 正在补充的笔记已有 `aliases`、`platform`、`topic` 或 tags 可直接转换为 `terms` / `aliases`。

最小更新只允许：

- 为本次实际写入或更新的真实笔记新增一个入口。
- 为已存在的匹配入口追加少量明确 `terms`、`aliases`、`kind`、`use_as` 或 `notes`。
- 保留 catalog 既有结构，不重排、不移动、不删除、不批量改名。

不要更新 catalog 的情况：

- 只是猜测某平台或领域可能以后会用到。
- 搜索结果不明确。
- 目标笔记仍需要用户确认。
- 关键词包含本地事实、内网地址、账号、客户名或其他需要脱敏的信息。

结构性 catalog 维护由 `$obcurate` 执行，包括清理 Inbox、移动或重命名主题、合并重复入口、拆分大主题、批量修正 aliases/tags/wikilink、删除过期入口和全局重分类。

## 模板升级与历史公共知识

模板升级只影响新建笔记和后续追加条目；历史公共知识默认保持原样，仍应按当时内容读取和复用。

读取旧公共知识笔记时兼容缺失字段，从正文推断适用场景、检查项、经验或相关链接，不要因为缺少新模板字段就判定无效。不要批量迁移历史公共知识。

只有在以下情况才做最小回填：

- 正在向该笔记追加新条目。
- 缺失字段会导致下一个 agent 误用经验或无法判断适用范围。
- 需要脱敏、泛化或修正过期内容。

回填时只补必要字段、短句或条目，不整体重写历史笔记。

## 已有公共知识维护

`oblearn` 对已有公共知识维护只做最小修改：添加当前写入必需的 `aliases`、更新 `title` / H1 / tags、修正 wikilink、追加新条目，或修正当前条目中不够脱敏的内容。

维护动作应服务于可复用性和可发现性，只做最小修改。

如果用户要求移动、重命名主题、合并或拆分笔记、批量修正 catalog、清理 Inbox，转交 `$obcurate`；不要把这些结构性整理塞进一次经验提取。

## 项目回写

仅项目模式执行项目回写。

如果提取了公共知识，在 `.agents/active.md` 追加或更新：

使用 `templates/active-knowledge-extracted.md` 的结构。

如果只是发现项目内经验但不适合公共化，保留在 `.agents/lessons.md`。

## 完成说明

结束时只汇报：

- 读取了哪些项目文件。
- 非项目模式下，说明使用了哪些当前对话、用户摘要、transcript 或会话记录 材料。
- 追加了哪些 Obsidian 公共知识笔记。
- 新建或建议写入了哪些 `Agent/Knowledge/Inbox/` 笔记。
- 是否最小更新了 `Agent/Knowledge/_catalog.md`，或只提出了维护建议。
- 建议新建但等待确认的笔记。
- 回写了哪些项目内 memory 文件。