learning

学习

你正在管理机构知识——记录洞见、搜索以往经验，并将重要模式提炼到 CLAUDE.md 中，作为永久参考。

适用场景

此技能会在以下情况下触发：

• 用户调用 /learning 命令
• 其他技能引用 desplega:learning
• 用户说“我们来记录一下”“关于 X，我们学到了什么”或类似的知识管理表达

子命令路由

解析第一个参数以确定流程：

参数	流程
*（无参数）或 status	设置 / 状态
capture [insight]	记录
recall <topic>	回忆
promote [id-or-topic]	提升
review	审查

---

设置 / 状态（不带参数的 /learning）

1. 检查配置：读取 ~/.agentic-learnings.json
2. 如果未找到（首次运行）：
   • 简要说明学习系统：“学习技能会跨会话和项目捕获、搜索并提升机构知识。它会将学习内容保存为带有结构化 frontmatter 的 Markdown 文件。”
   • 使用默认架构创建 ~/.agentic-learnings.json（参见下方的配置文件架构），并使用本地后端
   • 使用 AskUserQuestion：“是否要配置其他后端？（用于语义搜索的 qmd、用于远程团队存储的 agent-fs）”，选项：["仅本地（默认）", "配置 qmd", "配置 agent-fs", "两者都配置"]
   • 如果选择 qmd：
     • 检查是否可用 qmd MCP 工具（尝试 mcp__qmd__status）。在配置中注明 "accessMode": "mcp" 或 "cli"。
     • 使用 AskUserQuestion：“要搜索哪些 qmd 集合中的学习内容？（输入逗号分隔的名称，例如 'ai-toolbox, my-notes'）”
   • 如果选择 agent-fs，逐步完成配置：
     • 使用 AskUserQuestion：“是否已配置 agent-fs API 密钥？”选项：["是，已设置在我的环境中 (AGENT_FS_API_KEY)", "是，我现在提供", "否，我需要先设置"]
     • 如果现在提供：使用 AskUserQuestion：“输入你的 agent-fs API 密钥”
     • 如果需要设置：说明如何获取密钥，然后暂停
     • 使用 AskUserQuestion：“应将学习内容存储在哪个 agent-fs 组织中？”选项：["使用现有组织（我会提供名称）", "为学习内容创建新组织"]
     • 如果使用现有组织：使用 AskUserQuestion：“输入组织名称”
     • 如果创建新组织：使用 AskUserQuestion：“新组织应叫什么名称？”——然后通过 Bash 运行 agent-fs org create <name>
     • 使用 AskUserQuestion：“应将学习内容存储在哪个云盘中？”选项：["使用现有云盘（我会提供名称）", "创建名为 'learnings' 的新云盘"]
     • 如果使用现有云盘：使用 AskUserQuestion：“输入云盘名称”
     • 如果创建新云盘：通过 Bash 运行 agent-fs drive create learnings --org <org>
   • CLAUDE.md 初始化：创建配置后，使用 AskUserQuestion：“是否要在项目的 CLAUDE.md 中添加‘学习系统’部分，以便后续会话了解该学习系统？”选项：["是，添加到项目 CLAUDE.md", "是，添加到全局 ~/.claude/CLAUDE.md", "否，跳过"]
   • 如果选择是，将以下部分追加到所选的 CLAUDE.md：

     ## Learning System
     Use `/learning recall <topic>` before research/planning to check for prior learnings.
     Use `/learning capture` to record significant insights, decisions, and gotchas.
     Config: `~/.agentic-learnings.json`
     

3. 如果已找到（回访用户）：
   • 显示已配置后端及其状态（已启用/已禁用）
   • 统计每个后端的学习条目数（本地：Glob 计数，agent-fs：agent-fs ls 计数）
   • 显示最近的 5 条学习内容（文件名 + frontmatter 中的主题）

---

记录（/learning capture）

第 1 步：获取心得

• 如果调用时附带了内联文本（例如，/learning capture "qmd requires manual update"）：将其作为心得
• 如果未提供文本：使用 AskUserQuestion：「你想记录什么心得或经验？」

第 2 步：重要性检查

继续之前，使用以下默认启发式规则进行评估：

1. 这能帮助他人在未来的会话中吗？（首要判断标准）
2. 这是否已记录在 CLAUDE.md 或代码注释中？（如果是，则跳过）
3. 用户是否纠正了 Agent 的处理方式？（始终记录）
4. 是否遇到了出乎意料的困难或故障？（通常记录）

例外：如果项目级或全局 CLAUDE.md 中存在 ## Learning Capture Rules 部分，则优先遵循其中的规则，而非上述默认规则。

如果心得未达到重要性门槛，请告知用户，但仍提供记录选项——最终决定权在用户。

第 3 步：分类

使用 AskUserQuestion：「这条心得最适合归入哪个类别？」并提供以下选项：

• product-decisions — 架构选择、权衡，以及选择 X 而非 Y 的原因
• technical-gotchas — Bug、易错点、出乎意料的行为和变通方案
• human-nudges — 用户纠正、工作流偏好、沟通风格
• patterns — 发现的可复用方法、惯例和最佳实践
• mistakes — 出错之处及今后应如何改进

第 4 步：确定范围

使用 AskUserQuestion：「这条心得应为个人专属还是共享？」并提供以下选项：

• Personal — 保存到 thoughts/{user}/learnings/，仅在当前用户的上下文中可见
• Shared — 保存到 thoughts/shared/learnings/，纳入 Git 版本控制，对所有协作者（人类和 Agent）可见

第 5 步：写入心得

1. 生成文件名：YYYY-MM-DD-<slug>.md
   • Slug：根据主题生成，使用小写字母和连字符，最长 50 个字符
   • 保存到共享范围时，在 slug 中包含作者姓名，以避免多人使用时发生冲突（例如，2026-03-19-taras-qmd-indexing.md）
2. 使用收集到的信息填写 cc-plugin/base/skills/learning/template.md 中的模板
3. 使用 Write 工具写入相应路径
4. 同步后端：
   • 如果启用了 qmd 后端：通过 Bash 运行 qmd update
   • 如果启用了 agent-fs 后端：通过 Bash 运行 agent-fs write /learnings/<filename> --content "<content>"
5. 确认记录完成并提供文件路径

---

回顾（/learning recall）

第 1 步：获取主题

• 如果调用时附带了主题（例如，/learning recall qmd indexing）：使用该主题
• 如果未提供主题：使用 AskUserQuestion：「你想搜索什么主题？」

第 2 步：并行搜索所有已配置的后端

同时查询所有已启用的后端：

• 本地：在 thoughts/{user}/learnings/ 和 thoughts/shared/learnings/ 中搜索该主题
• qmd：使用 mcp__qmd__query 查询 [{type:'lex', query:'<topic>'}, {type:'vec', query:'<topic>'}]，搜索范围限定为已配置的集合
• agent-fs：通过 Bash 运行 agent-fs search --query "<topic>" 或 agent-fs fts --query "<topic>"

第 3 步：呈现结果

• 按相关性对结果排序（完全匹配优先，其次是语义匹配）
• 每条结果显示：日期、类别、主题和一行摘要
• 本地结果附上 file:line 引用
• 提供阅读完整心得或采取后续操作（提升、归档）的选项

---

提升（/learning promote）

第 1 步：选择一条心得

• 如果提供了文件路径：直接读取该心得
• 如果提供了主题：先执行回顾，再让用户选择要提升的心得
• 如果未提供参数：不指定主题执行回顾（列出最近的心得），再让用户选择

第 2 步：选择目标

使用 AskUserQuestion：「应将这条心得提升到哪里？」并提供以下选项：

• Project CLAUDE.md — 添加到当前项目的 CLAUDE.md
• Global ~/.claude/CLAUDE.md — 添加到全局 CLAUDE.md

步骤 3：整理格式并追加

1. 读取完整的学习文件
2. 将其整理为适合放入 CLAUDE.md 的简洁规则（1-3 行）
3. 使用 AskUserQuestion 确认整理后的规则，然后再写入
4. 将规则追加到所选 CLAUDE.md 中的合适章节下（如有需要，创建新章节）
5. 更新学习文件的 frontmatter：将 promoted_to: 设置为目标路径（例如，promoted_to: "CLAUDE.md" 或 promoted_to: "~/.claude/CLAUDE.md"）

---

审查（/learning review）

步骤 1：列出所有学习内容

• 按时间从近到远列出默认后端中的所有学习内容
• 显示 1 行摘要：日期、类别、主题、是否已推广
• 使用本地后端：Glob thoughts/{user}/learnings/*.md + thoughts/shared/learnings/*.md

步骤 2：选择要审查的内容

使用 AskUserQuestion（multiSelect）询问：“您想审查哪些学习内容？”并列出这些学习内容

步骤 3：处理每项选中的学习内容

对每项选中的学习内容：

1. 显示完整内容
2. 使用 AskUserQuestion 询问：“您想如何处理这项学习内容？”并提供以下选项：
   • Keep — 不做更改
   • Promote — 为此学习内容运行推广流程
   • Archive — 移动到 thoughts/{user}/learnings/archive/（或对应的共享目录）
   • Delete — 完全删除该文件

步骤 4：备选方案 — 文件审查

如果 file-review 可用（检查该命令是否存在），则提供批量审查的备选方案：

• “您想使用 file-review 进行可视化批量审查吗？”
• 如果是：创建临时摘要文件并启动 file-review

步骤 5：报告

处理完所有选中的学习内容后，报告：“保留 N 项，推广 N 项，归档 N 项，删除 N 项。”

---

后端适配器参考

所有后端都支持 4 种操作：写入、搜索、列出、删除。

本地后端

操作	实现方式
write	将工具写入 thoughts/{user}/learnings/ 或 thoughts/shared/learnings/
search	使用 Grep/Glob 在个人和共享学习目录中搜索主题
list	Glob thoughts/{user}/learnings/*.md + Glob thoughts/shared/learnings/*.md
delete	Bash rm <path>（学习文件只是一个本地文件）

qmd 后端

qmd 是一个针对 Markdown 文档的本地搜索引擎。可通过 MCP 工具（若已配置为 MCP 服务）或 CLI 访问。

• 安装：npm install -g @tobilu/qmd（或 bun install -g @tobilu/qmd）— github.com/tobi/qmd
• MCP 访问：使用 mcp__qmd__query、mcp__qmd__get、mcp__qmd__multi_get 工具（配置 qmd MCP 服务后即可使用）
• CLI 访问：通过 Bash 运行 qmd query、qmd get、qmd update（安装后始终可用）

操作	实现方式
write	与本地后端相同（qmd 会索引本地文件），然后通过 Bash 运行 qmd update 以重新建立索引
search	MCP：使用 mcp__qmd__query 执行 lex+vec 子查询，并限定在已配置的集合中。CLI：通过 Bash 运行 qmd query --collection <name> "<topic>"
list	MCP：使用 mcp__qmd__multi_get 和 glob 模式（例如，learnings/*.md）。CLI：通过 Bash 运行 qmd get "learnings/*.md"
delete	删除本地文件，然后通过 Bash 运行 qmd update（qmd 会重新建立索引并移除该条目）

如果 MCP 工具可用，优先使用它们（输出更丰富，无需转义 Shell 字符）。如果未配置 MCP，则回退到 CLI。

agent-fs 后端

agent-fs 提供远程、团队共享的文件存储，并支持语义搜索。仅通过 CLI 访问。

• 安装：bun add -g @desplega.ai/agent-fs — github.com/desplega-ai/agent-fs
• CLI 访问：所有操作都通过 Bash 使用 agent-fs <command>

操作	实现方式
写入	通过 Bash 使用 agent-fs write /learnings/<filename> --content "<content>"
搜索	通过 Bash 使用 agent-fs search --query "<topic>"（语义搜索）或 agent-fs fts --query "<topic>"（关键词搜索）
列出	通过 Bash 使用 agent-fs ls /learnings/
删除	通过 Bash 使用 agent-fs rm /learnings/<filename>

---

配置文件架构

配置文件位于 ~/.agentic-learnings.json：

{
  "defaultBackend": "local",
  "backends": {
    "local": { "enabled": true, "basePath": "thoughts/{user}/learnings/" },
    "qmd": { "enabled": false, "accessMode": "mcp", "collections": [] },
    "agentFs": { "enabled": false, "apiKey": "", "org": "", "drive": "" }
  }
}

• defaultBackend：用于写入的默认后端（初始时始终为 "local"）
• backends.local.basePath：路径模板 — {user} 在运行时会替换为当前用户名
• backends.qmd.accessMode："mcp"（首选，使用 MCP 工具）或 "cli"（备用，通过 Bash 使用 qmd CLI）
• backends.qmd.collections：要搜索的 qmd 集合名称列表
• backends.agentFs：agent-fs 连接详情（仅在使用远程团队存储时需要）
• backends.agentFs.apiKey：API 密钥 — 可在此处设置，也可通过 AGENT_FS_API_KEY 环境变量设置

此技能不是什么

• 不是聊天机器人记忆 — 学习内容是有意整理和筛选的知识，而非对话历史
• 不是自动化的 — Agent 不会自动捕获内容；它会通过子技能引用进行提醒，由用户或 Agent 做出决定
• 不是 CLAUDE.md 的替代品 — 学习内容是暂存区；重要内容会被提升到 CLAUDE.md 中
• 不是 brain — brain 是独立的个人知识工具；此技能用于项目和团队的机构知识