scchearn/loam

使用 loam

这是 loam 技能命名空间的路由器。它本身不执行工作，而是告诉您针对某个意图应调用哪个 loam 技能，以及适用于所有技能的共同规则。

这是一个路由/元技能。 当您识别到匹配的技能时，通过宿主工具的技能加载器调用它。不要在此处执行实际工作。

不可妥协的规则

三条规则确保 loam 工作与内存模型保持一致。

1. 在任何 loam 操作之前调用相关技能。 不仅是工具调用。在规划、调研、开始、恢复、检查点、辩论或达成共识、修改计划、添加到内存、查询内存、修改内存、检查内存、规范化内存、审查内存、捕获学习、审计指导、搭建 wiki 或初始化 vaule 之前：调用匹配的技能。本文档是一个路由器。技能本体拥有实际规则。其余一切由你负责。宁可调用，不要跳过。
2. 内存优先，基底其次。 首先谈论“内存”。仅在需要将 Markdown 基底与指导或检查点基底区分时才使用“wiki”。绝不要用“wiki”代替“内存”——wiki 只是内存的一个基底，而非全部。
3. 代理拥有的内存写操作。 代理可在无需预先批准的情况下编写、修正、路由和归档内存。人类可以标记过时或错误的内容，这将触发与代理发现矛盾时相同的修正流程。

内存模型

内存是 loam 捕获所有内容的总概念。存在三个基底：

基底	是什么	谁维护
wiki	位于 wiki/ 下、兼容 Obsidian 的永久性 Markdown 笔记。主题、实体、概念、分析页面。	loam-memory 组（大部分技能）
guidance	AGENTS.md 是规范指导文件。CLAUDE.md 是一个简化的导入 shim（仅包含 @AGENTS.md）。.claude.local.md 用于个人覆盖。	loam-memory 组（auditing-guidance、learning-from-session guidance 路径）
checkpoints	位于 wiki/checkpoints/ 下的瞬态工作状态。恢复笔记，非持久化知识。	loam-work 组（checkpointing 写入，resuming 读取）

wiki 基底是 qmd 索引的对象。guidance 基底是宿主工具作为提示上下文加载的内容。检查点是工作状态，而非知识——它们拒绝接触 index.md 或 log.md，且不应成为持久性声明。

首先谈论“内存”。仅在基底区分重要时才使用“wiki”。 一个操作 Markdown 笔记的技能处理的是内存的 wiki 基底。一个编辑 AGENTS.md 的技能处理的是内存的 guidance 基底。两者都是内存。

持久化内存准入规则

在创建 wiki 页面之前使用此规则。创建页面的技能应引用此部分，而非复制它。

一个声明只有通过以下全部三项才能获得 wiki 页面：

• R1 可复用——未来关于不同任务的会话很可能会需要它。
• R2 关于项目/领域——代码库、架构、决策、约定、外部依赖或持久外部事实；而非对话、代理或用户瞬态状态。
• R3 难以重建且可再次验证——从实时源（代码、配置、日历、任务列表）重新推导该声明的成本高于维护该页面的成本。如果一条命令或一次文件读取就能恢复，则不值得创建页面。当存在外部源时，页面应引用该源，以便新鲜度可以重新验证。纯粹的决策和理由是其自身来源，通过陈述推理满足。

否决条件覆盖准入规则：

• D1 瞬态——构建状态、当前分支、“今天我运行了 X”等操作报告。
• D2 重复——已有页面涵盖该内容，则应修改现有页面而不是创建另一个。

打破平局：如果无法从实时源重建，则接纳；如果可以重建，则丢弃。wiki/.archive/ 仅用于曾是持久化但现已废弃的内容。从未持久化的材料不写入 wiki 且从不归档。

路由矩阵

材料	目的地	技能路径
可复用的项目/领域事实，通过准入规则	持久化 wiki 页面	loam::adding-to-memory，自修正
代理行为约定/命令/陷阱	AGENTS.md / CLAUDE.md	loam::learning-from-session guidance 路径
用于恢复/交接的会话状态	wiki/checkpoints/<slug>.md	loam::checkpointing
附加到工作单元的任务上下文	任务注释/计划文件	loam::planning，loam::starting
构建输出、分支状态、一次性、不可验证或未通过准入规则	丢弃，可选地在 log.md 中记录审计行	无

自修正和用户标记触发

• 自修正： 当代理读取内存并发现与当前证据矛盾时，将废弃的持久化页面移动到 wiki/.archive/ 并添加归档头，在实时位置写入修正，向 log.md 追加一条 self-correct 条目，然后继续原任务。
• 用户标记： 当用户指出某内存页面错误或过时时，将其视为修正触发，而非审批请求。读取被标记的页面和当前证据，将废弃的持久化页面归档，写入修正，记录日志，并报告变更内容。
• 归档范围： .archive/ 仅用于曾持久化但后来变得错误、过时或废弃的页面。从未持久化的材料应路由到其他地方或丢弃。

新鲜度验证触发

使用现有的 updated_at 加上检查时的证据；不要添加新鲜度前置元数据。

• F1 引用的文件路径自页面 updated_at 后发生了变化。
• F2 重构、重命名、删除或迁移涉及了引用的路径（loam::syncing-code-graph --touched）。
• F3 页面中提到的固定版本、API 或外部文档有更新的提及。
• F4 updated_at 超过 90 天且页面引用易变表面（如 API、配置、版本或代码路径）。检查标记此页面以重新验证，但不会自动归档。
• F5 读取时发现矛盾，由自修正处理。

验证结果是以下之一：已确认（更新 updated_at）、已修正（归档 + 重写 + 日志）或已降级（归档并注明原因“不再适用”）。

红旗：意味着停止并调用的想法

这些合理化想法会导致跳过技能。如果您发现自己产生了任何这些想法，请调用相关技能，即使您在此会话中“已经读过它”。

想法	操作
“我直接写到 wiki 就行”	调用 loam-adding-to-memory。应用准入规则，然后写入或路由。
“我直接规划，这个很简单”	调用 loam-writing-spec。在 loam-planning 之前必须先有规约。
“我直接让代理们快速辩论一下”	调用 loam-configuring-agents。辩论需审批授权；未授权前不能发送。
“我直接编辑这个计划”	调用 loam-amending-plan。计划变更会级联；该技能会评估影响。
“我写这个内存页面是因为以后可能有用”	首先应用准入规则。如果失败，则路由或丢弃。
“wiki 过期了，我直接修改”	将废弃的持久化页面归档，写入修正，记录日志，然后继续。
“我就把这个学习内容记为一个笔记”	调用 loam-learning-from-session。它将其路由到 wiki 或 guidance，而不是你。
“我就快速查一下 wiki”	调用 loam-querying-memory。始终基于内存，而非过时的上下文。
“我就把这个命令加到 AGENTS.md”	调用 loam-learning-from-session（guidance 路径）或 loam-auditing-guidance 进行全面审计。
“我就暂停一下，稍后继续”	调用 loam-checkpointing。检查点是可恢复的工件，而非心理笔记。
“我恢复上次离开的地方”	调用 loam-resuming。在操作之前验证实时状态。
“我搭建 wiki”	先调用 loam-scaffolding-wiki，然后调用 loam-initializing-vault 进行 Obsidian 配置。

loam 生命周期

对于任何 loam 任务：

1. 定位。 根据下面的决策图识别匹配的技能。如果两个技能看似相关，应用优先级规则。
2. 选择技能。 通过宿主工具的技能加载器调用它。
3. 保持基底边界。 不要将检查点写入持久化页面。不要将 guidance 写入 wiki 页面。不要将 wiki 内容写入 AGENTS.md。每个基底都有其技能。
4. 在内存写入之前应用准入和路由。 持久化 wiki 页面必须通过准入规则；其他内容路由到 guidance、检查点、任务注释或丢弃。
5. 仅通过匹配的技能更新计划/检查点/guidance。 不要直接编辑计划——使用 loam-amending-plan。不要直接写入检查点——使用 loam-checkpointing。不要直接编辑 AGENTS.md——使用 loam-learning-from-session 或 loam-auditing-guidance。

冲突规则（当两个技能看似相关时）

• 进程/当前工作技能优先于内存维护技能。 如果执行过程中发现内存问题，先完成当前工作步骤（或为它创建检查点），然后再调用内存技能。
• 内存写入由代理拥有。 如果当前工作产生了学习，通过路由矩阵进行路由；如果暴露了过时的内存，通过归档加日志的方式直接修正。
• 检查点是瞬态的。 它们位于 wiki/checkpoints/ 下，但不是持久性声明。它们拒绝更新 index.md 或 log.md。不要在没有经过 loam-adding-to-memory 的情况下将检查点提升为持久化笔记。
• 修正 vs 检查。 loam-amending-memory 修复特定的错误声明。loam-linting-memory 对整体图进行健康检查。如果发现了特定错误，进行修正。如果需要进行全面检查，进行 lint。
• 查询 vs 审查。 loam-querying-memory 回答问题。loam-reviewing-memory 揭示缺口。如果想要答案，进行查询。如果想要了解未解决的问题，进行审查。
• 添加 vs 学习。 loam-adding-to-memory 摄取来源（文件、文章、对话作为笔记）。loam-learning-from-session 捕获会话衍生的见解并将其路由到 wiki 或 guidance。如果有来源，进行添加。如果会话产生了见解，进行学习。

决策图

”我想要...“
├─ 开始新事情
│  ├─ 调研问题 ──────────── /loam::writing-spec
│  ├─ 规划已批准的工作 ────── /loam::planning
│  └─ 辩论/达成共识 ──────── /loam::configuring-agents
├─ 执行工作
│  ├─ 开始一个计划 ───────── /loam::starting
│  ├─ 暂停/交接 ─────────── /loam::checkpointing
│  ├─ 暂停后恢复 ────────── /loam::resuming
│  └─ 变更进行中的计划 ───── /loam::amending-plan
├─ 处理内存
│  ├─ 添加来源 ──────────── /loam::adding-to-memory
│  ├─ 摄取代码库 ────────── /loam::ingesting-codebase
│  ├─ 同步代码图漂移 ────── /loam::syncing-code-graph
│  ├─ 提问 ──────────────── /loam::querying-memory
│  ├─ 修复错误 ──────────── /loam::amending-memory
│  ├─ 健康检查 ──────────── /loam::linting-memory
│  ├─ 规范化杂乱语料库 ───── /loam::normalizing-memory
│  ├─ 查看未解决的问题 ───── /loam::reviewing-memory
│  ├─ 捕获会话学习 ───────── /loam::learning-from-session
│  └─ 审计代理指导 ───────── /loam::auditing-guidance
└─ 设置基底
   ├─ 搭建 wiki ──────────── /loam::scaffolding-wiki
   └─ 初始化 Obsidian vault ─ /loam::initializing-vault

不确定情况下的优先级说明

如果一个意图映射到两个技能，上方的树是主要路由器。当树无法区分时，应用生命周期部分中的冲突规则。如果仍然不确定：询问用户哪个意图更接近。

简洁技能参考

每个技能一行。决策图是主要路由器；此为快速查找之用。

• loam-writing-spec — 调研问题，生成 specs/<slug>.md
• loam-planning — 将已批准的规约编译为可执行的计划
• loam-starting — 开始或恢复计划的执行
• loam-resuming — 从检查点笔记恢复
• loam-checkpointing — 在暂停前写入可恢复的检查点
• loam-configuring-agents — 运行需要审批的结构化辩论或会议，涉及多个具有不同立场的代理并产生一致性成果
• loam-amending-plan — 在范围变更后更新进行中的计划
• loam-adding-to-memory — 将来源摄取到内存中（wiki 基底）
• loam-ingesting-codebase — 将代码库作为实体页面摄取，并附带 wikilink 边
• loam-syncing-code-graph — 在计划关卡或按需将代码图与存储库对齐
• loam-querying-memory — 从内存中回答问题
• loam-amending-memory — 修复具体错误或过时的内存声明
• loam-linting-memory — 对内存图进行健康检查
• loam-normalizing-memory — 为杂乱的记忆语料库回溯性地构建结构
• loam-reviewing-memory — 揭示内存中未解决的缺口
• loam-learning-from-session — 捕获会话学习，路由到 wiki 或 guidance
• loam-auditing-guidance — 审计并改进 AGENTS.md / CLAUDE.md / .claude.local.md
• loam-scaffolding-wiki — 实例化一个新的 wiki 基底脚手架
• loam-initializing-vault — 设置带有配置的 Obsidian 资料库

安装斜杠命令

如果用户希望将 /checkpoint 和 /resume 作为快捷命令（而不是输入 /loam::checkpointing 和 /loam::resuming），您可以安装它们。命令文件位于 loam 仓库的 commands/ 目录下。

阅读 references/commands-install.md 获取完整协议。其中包括：

• 您正在运行的宿主工具（检测信号）
• 宿主工具期望的命令格式（Markdown 与 TOML）
• 安装位置（全局与项目本地）
• 复制前请求授权的协议

命令文件作为资产打包在 assets/commands/ 下

…

[已截断以进行翻译]