立即执行
目标：$ARGUMENTS
KB 中的所有文档都存在于一个集合中：kb/ 下的一个目录，包含本地的 COLLECTION.md，例如 kb/notes/、kb/reference/、kb/instructions/，或已安装的库集合，例如 kb/commonplace/notes/。每个接受写入的集合都有一个 COLLECTION.md，其中包含其注册表、质量目标、类型供应和链接约定。
带有前置元数据的文档携带一个路径值 type:，指向一个类型规格文档，例如 type: kb/types/note.md 或 type: kb/reference/types/adr.md。没有前置元数据的文件被视为隐式的 text。
第 1 步 - 解析参数
编辑模式：第一个参数是现有 .md 文件的路径。读取它，从路径推断集合，并从其前置元数据读取 type: 路径。如果它有前置元数据但没有 type:，请停止并在进行结构编辑之前修复该结构性问题。如果没有前置元数据，则将其视为隐式的 text。在进行结构编辑之前，打开由 type: 命名的类型规格文档。
新建模式：其他情况。从参数中提取集合、类型和主题。默认值：集合 notes，类型 kb/types/note.md。如果请求的类型是指令且未明确指定集合，则使用集合 instructions。
对于新建操作，将目标集合解析为 kb/ 下具有本地 COLLECTION.md 的目录；简写名称（例如 notes）表示 kb/notes/。读取该集合的 ## Types 部分，并选择一个列出的类型路径。如果请求的类型未列出且用户未给出显式路径，请停止并列出可用类型。如果用户给出显式的 kb/.../*.md 类型路径，请在使用前打开该文件并验证它是类型规格文档。
第 2 步 - 加载集合约定
读取目标集合的 COLLECTION.md，了解该集合的写作约定，包括出站链接规则。找到出站链接部分（标题各不相同 — 查找那个命名目标和标签的部分），并将其视为权威。它会告诉你此源集合可以链接到哪些目标集合、哪些目标被排除、哪些标签被授权用于哪些源-目标对，以及每个标签所服务的读者需求。内部格式各不相同（按目标分块的块、带有目标列的单标签表、散文） — 根据内容而非形状来阅读。没有单独的链接文档可供查阅。
如果目标集合没有 COLLECTION.md，则硬性失败。每个接受写入的集合都必须有一个 COLLECTION.md；其注册表、质量目标和链接规则是区分集合的关键。不要使用默认约定继续进行。
第 3 步 - 加载类型规格
读取选定的类型规格文档。其前置元数据必须包含 type: kb/types/type-spec.md、name、description 和 schema。其正文提供工件形状，并可能包含一个模板块。遵循该正文作为结构化编写契约。
不要从缺失的类型路径回退到 note。
对于 text，仅当用户明确想要非结构化记录时，才编写没有前置元数据的原始 markdown。否则使用 kb/types/note.md。
第 4 步 - 写前搜索
写入不执行主动发现 — 那是 cp-skill-connect 的工作。写入负责编写一条笔记，并只提交作者手中已有的链接，外加一个廉价的重复项防护：
- 近重复项检查。 使用
rg搜索目标集合中新笔记的独特标题词条（例如rg -i "关键术语" kb/notes/ --glob "*.md"）。这是针对特定词条的搜索 — 请不要枚举整个集合；完整列出会消耗线性上下文，并且对于单条笔记的重复项检查来说是不合适的工具。如果近重复项已存在，请优先编辑它而非创建第二条笔记。 - 已加载的上下文。 为本次写入而拉入会话中的笔记、源和引入内容是一等链接候选。如果值得阅读，就值得考虑作为链接。
- 用户命名的目标。 用户在提示中提到的链接目标。
在编辑模式下，还要对目标笔记执行反向链接查询 — 一次查询，无正文搜索 — 以便编辑不会孤立依赖项。
除此之外的所有发现 — 全集合描述扫描、跨目标勘探、正文搜索、标签遍历、链接追踪、反向边推理 — 属于 cp-skill-connect，而非此处。写入保持专注于编写一条笔记。
第 5 步 - 起草并保存
遵循类型规格文档和集合约定。除非编辑现有文件，否则从 # Title 派生小写连字符分隔的文件名。对于类型化工件，将 type: 设置为确切的仓库相对类型规格路径，而非类型名称。
仅当有明显需要时才设置特征。可用特征及其含义在目标类型的规格中定义（例如 kb/types/note.md 中的特征表） — 从那里获取词汇表，而不是从记忆的列表中获取。
在编辑期间保留现有的前置元数据和链接，除非请求的更改要求修改它们。
第 6 步 - 验证
验证你编写或编辑的笔记：
commonplace-validate path/to/file.md
在停止之前修复结构性故障。
然后建议 cp-skill-connect 作为下一步。第 4 步仅提交作者手中已有的链接（已加载上下文、用户命名的）加上重复项防护；笔记在图中剩余的部分 — 全集合描述扫描、跨目标候选项、正文搜索命中、标签遍历、链接追踪、反向边候选项 — 仅在连接技能下才显现。该建议不是可选的润色。
通用机制
这些适用于所有类型化工件，无论集合如何。
前置元数据使笔记可查询。没有前置元数据意味着隐式的 text；任何带有前置元数据的文件必须包含路径值的 type:。大多数库笔记还需要 description（双引号，50-200 个字符），以及可选的 traits、tags 和 status。
描述是检索过滤器，而非摘要。测试：如果智能体搜索此笔记的概念并返回 5 个结果，此描述是否有助于选择这一个？复述标题不会增加任何检索价值。
词汇表。 使用根目录 AGENTS.md 中声明的活跃词汇表。在编写或实质性编辑散文时，在读者可能不熟悉该术语的首次有意义的提及中，注释并链接活跃词汇表。不要仅为了添加词汇表链接而改动未触及的段落。
链接。 使用从源文件开始的相对 markdown 路径。每个链接必须指向一个真实文件。
位置体现了承诺。行内散文连接器（since [X](./x.md)、because [X](./x.md)、but [X](./x.md)）是最强的 — 目标是当前论点的前提。页脚链接携带显式标签和上下文短语：- [标题](./path.md) — 标签：上下文短语。
集合的 COLLECTION.md 授权每个目标的标签，并命名每个标签所服务的读者需求。选择一个标签，其读者需求与链接的目的匹配；编写上下文短语以回答"[源]连接到[目标]因为[具体原因]。"如果没有授权的标签合适，则该候选超出此集合的范围 — 放弃该链接或将其提交给集合作者以扩展授权。
文件名为小写、连字符分隔、.md，源自 # Title，最长 70 个字符。
精炼追踪：当从笔记精炼到聚焦的工件时，在每个源笔记的页脚添加 Distilled into:。精炼后的工件不链接回来。
重命名：切勿手动重命名。使用 commonplace-relocate-note 来更新反向链接。