元习 yotta-learn

元习 —— 跨智能体的知识库技能：把跨项目可复用的经验、方法、避坑与教程沉淀进分类知识库（草稿 → 审核 → 可检索），供所有智能体与项目复用；首次使用由 AI 引导初始化知识库位置并自动接入 MCP。触发：值得沉淀的时刻（命令失败 / 被用户纠正 / 发现更好做法 / 知识过时 / 请求缺失能力 / 外部接口故障）与需要查询知识的时刻（开工前 / 动手解决不显然问题前 / 用户问"以前怎么解决的"）；或用户说 知识库 / kb / 查知识 / 记一笔 / 沉淀 / 经验 / 踩坑 / self-improvement / learnings 等。边界：私密 / 敏感信息不写入知识库（走元忆私密区）；项目专属经验写项目自身文件；不自动改动系统文件。

把「这次学到的」变成「下次可复用的」：跨项目通用的经验、方法、避坑与教程沉淀进分类知识库（KB），供后续会话与其他智能体检索复用。

使用模型（先读这一节）

归位决策树：这条东西写哪里？

#	判据	去向
1	私密 / 敏感（令牌、个人信息、关系、本机内部数据）	元忆私密区（PREF / BOUND / COMMIT）；绝不进 KB 与项目公开文件
2	只对当前项目成立（仓库怪癖、部署细节、项目决策依据）	项目自身载体（AGENTS.md / docs / 项目状态与任务文件等），直接写目的地
3	跨项目可复用知识（方法 / 流程 / 避坑 / 教程）	本技能 KB：kb add（草稿）→ 三问审核 → verified
4	事实 / 结论 / 红线（跨项目共享的记忆型信息）	元忆 FACT +（长期红线）机器级记忆锚点
5	已成熟、可流程化的经验	技能化（护栏 / 门禁 / 清单 / 规则）

一句话：「事」进元忆，「法」进知识库，「项目专属」进项目，「未定形」进 KB 草稿。

写库门槛：什么适合 / 什么不适合（进 KB 前必读）

适合写 KB（跨项目可复用的「法」）：

• 方法 / 流程 / 清单：可复用的操作步骤、核查点、检查表；
• 避坑 / 教训：根因 + 触发条件 + 解法；
• 教程 / 判据：怎么判断 / 怎么选型 / 怎么验证。

不适合写 KB（按归位决策树去别处）：

• 单次项目的具体发现 / 结论 / 决策依据 → 项目自身文件（把可复用的部分归纳出来才进 KB）；
• 事实 / 红线 / 承诺 → 元忆（FACT / BOUND / COMMIT）；
• 私密 / 敏感（密钥、凭据、个人信息、本机路径）→ 元忆私密区，绝不进 KB；
• 未验证的猜测 / 一次性现场数据 → 不写，或留 KB 草稿等验证。

三问判定标准（写入与 kb review 同一标准）：

1. 验证过？ 有可验证证据：亲手实测 / 实审命中并回读确认（不是「看起来对」）；evidence 写清「在哪、怎么验的」。
2. 自包含？ 离开原会话 / 原项目仍可复用：正文自带判据、步骤、关键词，不依赖上下文。
3. 无敏感？ 无密钥 / 凭据 / 个人信息 / 本机路径；涉及具体项目未修复漏洞细节的，标注共享边界（本机库可留，共享前脱敏）。

身份与审核：

• 写库带身份：CLI 用 --agent <名字> 或设 YOTTA_LEARN_AGENT（MCP 用 agent 参数，缺省 mcp@<host>）；不声明则审计记 unknown@<host>，来源断链。

• 审核口径：kb review --pass 必须过三问 + 有证据；敏感 / 重复命中用 --force --note 留审计。自审允许（逐条过三问并写明证据）；跨智能体共享面 / 高价值条目建议由另一智能体或用户复核后再 verified（当前不强制阻断）。

• 写前查重：先 kb query / kb list，已有同题就更新，不新建。

• 旧 .learnings/ 已退役为遗留兼容（见下文专节）：新知识不再默认写入。

写 / 查时机

什么时候写（按归位决策树定位后立即写，不积攒）：

• 事件驱动：命令失败、被用户纠正、发现更好做法、知识过时、请求缺失能力、外部接口故障；
• 周期驱动：批次复盘三问（能否护栏化？能否复用？归哪层？）、周级 review（草稿 → verified / 合并 / 废弃）、月级自评。

什么时候查（默认动作，不靠自觉）：

• 开工时：按当前任务关键词 kb query <关键词>（结果为空再动手）；
• 动手解决"不显然"的问题之前：先查有没有现成经验；
• 沉淀前：查重；
• 复盘时：kb list --status draft 过一遍草稿。

分类治理

• 复用优先：写前先 kb category list 看现有分类，能装下就复用；
• 新建门槛：现有分类都无法容纳才新建；slug 用小写连字符，名称与描述必填；
• 一条一主分类：检索补充用 --tags；
• 周期治理：周级 review 时用 kb category merge / kb category deprecate 合并或停用碎片分类。

首次使用：激活知识库（AI 必做）

首次加载本技能时，AI 先运行 kb config get 判定状态，然后：

1. 未初始化：向用户说明用途 → 请用户确认库位置（默认 ~/.yottalearn/knowledge，可指定其它位置）→ 用户确认后执行初始化（默认位置直接 kb init；指定其它位置先 kb config set --dir <路径> 再 kb init）；
2. 写「发现锚点」：把库位置与查询方式写入机器级记忆（各宿主全局 AGENTS.md 等效文件），让后续会话与其他智能体都能发现；
3. 自动接入 MCP：把本技能的 MCP server 写入当前客户端 mcpServers（见「AI 接口（MCP）」），并写永久记忆护栏；未加载时自动降级 CLI；
4. 自检回报：kb stats 确认可用（0 条也算成功激活）。

位置由用户确认（数据主权）；其余步骤全部由 AI 执行。同机后续智能体读取同一 ~/.yottalearn/config.json（单一真源），只需完成第 3 步的 MCP 接入即可共享同一库。

命令入口

两种等价用法，按可用性择一：

• 已装 CLI：yotta-learn <命令> —— 如 yotta-learn kb query 关键词、yotta-learn view（图形管理台）。
• 技能目录直跑：python3 scripts/yotta_learn.py <命令> —— 与 CLI 完全等价。

安装 / 更新技能本体（把技能装进智能体目录，不是装 CLI）：

bash

npx -y @yottameta/yotta-learn install --agent <名称>   # 推荐：装到指定智能体用户级技能目录
npx -y @yottameta/yotta-learn --agent <名称>           # 旧用法兼容（等价）
# 全局安装后专属安装器入口同样可用：yotta-learn-install --agent <名称>

知识库（KB）

• 位置：默认 ~/.yottalearn/knowledge（配置 ~/.yottalearn/config.json）；优先级 --dir > YOTTA_LEARN_KB > 配置 > 默认。旧版位置只读兼容：回退生效时写操作 fail-closed 并提示一次性迁移；迁移用 kb config set --dir <新位置> --move。
• 结构：categories/<slug>/（category.json + entries/ + index.json）+ 全局索引 + 审计 + 回收站 + 快照。
• 条目：Markdown + 受控 frontmatter；ID KB-YYYYMMDD-XXX；状态机 draft（默认）→ verified → deprecated。
• 查询：中文 bigram + 单字兜底；默认只出 verified（--include-draft 可含草稿）。
• 审核门：kb review <ID> --pass --evidence "..."（核验需证据）；敏感 / 疑似重复会阻断，可用 --force --note "说明" 留审计放行。
• 常用命令：

bash

yotta-learn kb init                                   # 初始化（幂等；已存在拒绝覆盖）
yotta-learn kb config get                             # 位置与状态（未初始化会给引导提示）
yotta-learn kb category create <slug> --name "..." --description "..."
yotta-learn kb add --category <slug> --title "..." --message "..." --source "..."
yotta-learn kb review <KB-ID> --pass --evidence "..."
yotta-learn kb query <关键词>
yotta-learn kb list --status draft
yotta-learn kb doctor                                 # 体检
yotta-learn kb backup create --out <目录>              # 备份
yotta-learn view                                      # 图形管理台（仅 127.0.0.1:8791）

• 完整命令面、数据协议与可靠性说明：references/kb.md。

AI 接口（MCP）

scripts/yotta_learn_mcp.py（stdio；读 kb_query / kb_get / kb_list / kb_stats / kb_categories，写 kb_add / kb_review / kb_update / kb_deprecate / kb_category_*，运维 kb_doctor / kb_index_rebuild；写工具 fail-closed，与 CLI 同源）。

AI 自动接入：首次使用时把该 server 写入客户端 mcpServers 并写永久记忆护栏；未加载自动降级 CLI。配置示例：

json

{"mcpServers":{"yotta-learn":{"command":"python","args":["<技能目录>/scripts/yotta_learn_mcp.py"]}}}

.learnings 遗留兼容

.learnings/（LEARNINGS / ERRORS / FEATURE_REQUESTS）是本技能旧版的项目内原始捕获区，现已退役为遗留形态：

• 不再默认写入：新知识按「归位决策树」直达归宿（项目自身文件 / KB / 元忆）。
• 已有数据可用：旧命令（log / list / review / update / resolve / promote / extract）全部保留，用于读取、处置与迁移已有条目；init 幂等，不覆盖任何已有文件。
• 迁移：跨项目可复用的条目用 kb add --from-learning <LRN-ID> --category <slug> 转成 KB 草稿（仍走审核门）；项目专属条目按决策树第 2 条写进项目自身文件。
• 字段与示例见 references/examples.md。

元忆联动（可选）

• 遗留条目路径支持 log --remember 同步到元忆（yotta-memory）；未安装 / 未初始化 / 失败自动降级（A / B / C），只提示、不阻断。
• 不写入 package.json 依赖。

Hook 模板

见 hooks/ 目录：Claude Code（claude-settings.json）、Codex（codex-settings.json）、OpenClaw（openclaw-setup.md）；activator.sh / error-detector.sh 为 Linux-only 可选 bash hook。当前 hook 仍指向遗留 .learnings 捕获路径，后续批次再改造。

参考

• references/kb.md — 知识库完整命令面、数据协议与可靠性说明
• references/faq.md — 常见问题速查（条目写哪 / 首装激活 / 审核 / 备份 / 报错）
• references/walkthroughs.md — 命令失败 / 用户纠正 / 接口降级三类走查（按新归位模型）
• references/examples.md — 遗留 .learnings 字段与示例
• references/hooks-setup.md — 各智能体 hook 接入步骤

何时使用（速查）

• 沉淀：上文"什么时候写"任一命中 → 先归位 → 立即写；
• 查询：开工 / 动手前 / 写前 / 复盘 → kb query、kb list；
• 首次使用：走「激活知识库」四步；
• 关键词：知识库 / kb / 查知识 / 记一笔 / 沉淀 / 经验 / 踩坑 / learnings 等。

Do NOT：不把私密 / 敏感信息写进 KB 与项目公开文件；不把项目专属经验塞进共享 KB；未初始化时先走激活引导，不假装可用。

日常排障先看 references/faq.md。