memory-comark

Memory Comark

Basic Memory 笔记可以包含以 Comark 块指令（::bm-bars{...} … ::）编写的轻量、安全组件。Basic Memory Cloud 会在笔记、Wiki 和共享页面中渲染这些组件。在其他所有地方（本地编辑器、GitHub、Agent 的原始读取内容中），相同的 Markdown 仍会显示为普通列表、表格或段落，因此组件不会隐藏内容。

当组件的形式比一句话或一个列表更能表达内容时，再使用组件。以正文为主：每个想法配一个图表，每个章节最多两个，并在图表之间用一句话说明图表展示的内容。

完整的组件词汇表、所有属性和所有数据语法均见references/components.md。使用之前未用过的组件前，请先阅读该文档。

选择组件

大多数笔记只需使用以下组件。参考文档列出了其余组件（总计 39 个）。

想要展示的内容	使用
一个或几个醒目的数字	bm-stat
少量数值的比较	bm-bars
简短的排名列表	bm-rank
小型数据表	bm-table
整体进度	bm-meter
无坐标轴的趋势	bm-spark
逐步收窄的步骤	bm-funnel
任务列表	bm-check
分泳道展示工作（现在、接下来、以后）	bm-kanban
按顺序排列的事件	bm-timeline
加框展示的主张或摘要	bm-frame
简短路径（a → b → c）	bm-flow
真正的图、序列或状态机	围栏代码块 ```mermaid（不是组件）

如果没有合适的组件，就写正文或使用普通 Markdown 表格。切勿自行发明组件：未知名称（例如 ::bm-pie）不会被渲染，只会显示为原始文本。

编写组件

每个组件都以独占一行的 ::bm-name{attributes} 开始，并以独占一行的 :: 结束。

The queue rewrite more than doubled steady-state throughput.

::bm-bars{title="Throughput" caption="Before and after the queue rewrite"}
- Before: 42/s
- **After: 96/s**
::

重要规则：

• 数据应以 Markdown 的形式写在正文中，而不是属性中：使用 - label: value 行，网格则使用表格。粗体表示当前行或选定行，斜体表示弱化， — note 用于添加旁注。
• **属性值必须用双引号括起，且不能包含 "。**没有转义方式。在 query 中使用单引号括起短语： query="search 'queue rewrite'"。
• **任务状态应保留在 Markdown 中。**在 bm-check 和 bm-kanban 中使用 - [ ] 和 - [x]；用户可以在渲染后的笔记中勾选方框。
• 笔记中绝不能放入 HTML、脚本、样式或类名，也绝不能将组件包在代码围栏中（围栏代码块会按字面内容显示）。
• **只能使用已注册的属性。**未知属性会在警告框中生成 prop-unknown，并显示原始源码和已注册属性；绝不会被静默丢弃。

清单和看板：

::bm-check{title="Launch"}
- [x] Freeze the schema
- [ ] Write the migration note — due Friday
::

::bm-kanban{title="Roadmap"}
### Now
- **Billing page**
- [ ] Usage emails

### Next
- *Partner portal*
::

知识库上的实时视图

带有 query 属性的组件会显示其所在项目中的当前数据。如果笔记描述的是自身的知识库，优先使用实时视图，而不是手动复制数字，因为复制的计数会过时。

::bm-stat{label="Open decisions" query="notes | where type == decision and status == open | count"}
::

::bm-bars{title="Open decisions by owner" query="notes | where type == decision and status != done | group owner | sort count desc"}
::

::bm-table{title="Due soon" query="notes | where tags contains infra and due < 2026-10-15 | fields title, owner, due | sort due"}
::

::bm-timeline{title="Recent edits" query="activity 7d"}
::

::bm-rank{title="Related notes" query="search 'checksum conflict' | limit 5"}
::

管道从左向右读取：先读取来源（notes、search 'phrase'、 activity 7d|30d），然后按顺序执行可选阶段：where、group、count 或 sum field、fields、sort、limit（1–50）。参考文档列出了所有运算符，以及各组件接受的数据形状。

适用的数据形状：

• 图表、排名和条形图每行都需要一个数值：添加 group field、count、 或 sum field，也可以使用 search 来源。
• Spark 图、KPI 和绘图需要多行数据（group、daily 或 search）， 不能只用单个 count。
• bm-table 接受 fields；bm-timeline 接受不带 daily 的 activity； bm-activity 接受 activity 30d | daily。

在周围的正文中准确说明以下语义：

• notes 视图是对已索引 frontmatter 的精确计数。搜索视图会排序且有数量上限；应称其为匹配项，绝不能称为“全部”。
• != 会保留缺少该字段的笔记。group 会将缺少该字段的笔记归入 none 组。
• Frontmatter 中的数字以文本形式存储；比较和求和时会将十进制文本视为数字，并忽略其他所有内容。

引用渲染结果前先检查

在 Basic Memory Cloud 中，read_note(view="text") 会返回读者看到的笔记内容：每个组件都以纯 Markdown 呈现，并即时运行实时查询。写入实时视图后，请读取笔记并确认视图中有行，再在正文中陈述数字。对笔记中不存在的字段进行查询，会渲染出空视图。

在其他环境中，只有浏览器会运行查询，因此请自行运行等效读取（例如，使用元数据筛选条件调用 search_notes；参见 memory-metadata-search 技能）。

实时图表的正文是它的快照：无法加载实时数据时，读者看到的行。新建实时视图时，正文可能为空；用户可以在编辑器中点击 Freeze snapshot 填入内容。如果你自行添加快照行，请在正文中将其标注为快照，并遵循图表的行格式。

编辑已有组件的笔记

• 使用 edit_note 修改单个组件（在其指令行或行内容上使用 find_replace）。不要为了更改一个值而重写整篇笔记。
• 用户编辑笔记时，富文本编辑器会规范化格式：属性顺序会变化，YAML 块会转换为 JSON。值会保留；不要试图阻止这种格式变化。
• 保留结尾的 :: 行。包含正文但没有结束符的块会产生 directive-unclosed；警告中会显示起始符和 YAML 属性，而后续 Markdown 仍会正常显示。请在源内容中预期的边界处添加结束符；编辑器不会自行推断。没有正文的独立叶节点仍然有效，不过新组件应使用显式结束符。

组件显示错误时

损坏的组件会在自己的框架中显示带代码的问题和修复方法；笔记的其余部分仍会正常显示。在 Basic Memory Cloud 中，write_note 和 edit_note 会在结果的 Component problems 下列出这些问题（它们不会阻止写入），因此请立即使用 edit_note 修复。手册中的 comark(7)（memory://man/comark(7)）可快速查阅语法和代码。最常见的代码包括：

Code	含义	修复方法
prop-unknown	组件不接受的属性	移除该属性，或使用警告或参考资料中列出的已注册属性
directive-unclosed	包含正文的块缺少结束符	在 Markdown 源内容的预期边界处添加 ::
query-measure	图表的每行没有数值	添加 group、count 或 sum，或使用 search
query-series	仅有一个值的趋势	使用 group、daily，或使用带有 limit ≥ 2 的 search
query-escaped-quote	查询中包含 \"	在查询中使用单引号
query-field / query-operator	字段名称或运算符无效	字段须符合 [A-Za-z0-9_-] 格式，并支持点分路径；运算符为 == != < <= > >= contains
query-stage-order	阶段顺序错误	where、group、count/sum、fields、sort、limit
chart-body-empty	正文中没有行	添加 - label: value 行
chart-body-number	某行没有数值	每行都需要一个数值

未知属性会在附近的富文本编辑操作中保留原始指令和数据。已闭合但格式错误的组件可以使用经过审核的 Agent 替换并撤销；修复缺少结束符的问题则需要编辑源内容。在修复之前，规范验证和严格导出会拒绝格式错误的源内容。切勿编写 bm-problem 等内部恢复节点。请根据参考资料检查组件名称和属性。

检查清单

1. 这里用图表是否比用句子更好？如果不是，就写句子。
2. 组件名称和每个属性是否都在参考资料中？
3. 数据是否以 Markdown 行或表格的形式放在正文中，且值中不包含 "？
4. 对于实时视图：查询流水线是否生成了组件所需的数据形状？你是否自行读取并检查了数字？
5. 图表周围是否有正文说明它展示的内容，以及计数是精确值还是排名？