知识格式

Bonsai 是你和你的 AI 助手共用的知识空间。空间里的一切都是纯文本的 Markdown 文件，任何 Markdown 编辑器都能打开，二十年后也一样。

这一页讲这些文件长什么样，以及 Bonsai 怎么从一个装满笔记的文件夹里，读出今天的任务、项目进度和习惯。

一篇笔记长什么样

下面是一篇项目笔记，比如 1_Projects/Kitchen-Renovation/Kitchen-Renovation.md:

---
tags:
  - home
---

# 🔨 Project · Kitchen Renovation

- **Key Result:** 十二月前厨房可以正常做饭。

## 🧩 Context

- 施工队：[[王师傅]]，电话在他的笔记里
- 预算上限 6 万

## Next Steps

- [x] 量好尺寸
- [/] 选定橱柜方案 📅 2026-11-05
- [ ] 下单橱柜
- [!] 等物业批准施工时间

就这些。普通的 Markdown,加上几条简单的写法。大多数时候 AI 助手会替你写，你只要告诉它想记什么。但看懂这些写法会很有帮助，下面一块一块说。

Front matter

文件最上面、夹在两行 --- 之间的那一块，叫 YAML front matter。它是写给机器看的笔记卡片：每行一个 键：值,列表用 - 开头。

---
tags:
  - home
---

正文写给人读，front matter 写给程序读。把两样分开，正文就可以自由地写，不必为了让机器看懂而塞进奇怪的标记。

Bonsai 认得的键不多：

键	作用	谁来写
`tags`	分类和筛选	你，或创建笔记时的 AI
`repo`	有代码的项目，仓库在哪里	你，或 AI 通过专门的工具
`archived`	这件事已经结束	只有你，在网页上点归档
`generated`	这篇是谁写的，什么时候实质改过	服务端
`verified`	谁核对过，一条一条往下记	服务端，代你或 AI 记下
`status`	草稿、稳定还是已废弃	AI 创建时填写
`stale_after`	过了这天就算过期	AI 创建时填写

笔记的标题就是文件名，不需要另写 title。

为什么有些键 AI 写不了

AI 可以帮你写正文，但不能随手改 front matter。它只能在创建笔记的那一刻写一次，之后要改，只能走专门的工具，由服务端代写。

原因很简单：front matter 里有些东西是承诺。archived 决定一件事还会不会出现在你的待办里；verified 记录了这篇笔记有没有被人看过。如果 AI 可以随手改这几行，它就可以替你结束一个项目，或者替你签字说「我看过了」。所以这几个键要么只有你能写，要么只有服务端能写。

这篇笔记能信几分

AI 写的内容越来越多，你需要一眼看出一篇笔记的来历。generated、verified、status、stale_after 这四个键回答的就是这个问题。它们的定义原样采用开放的 OKF 规范，没有改写。

generated:
  by: claude/claude-opus-5
  at: 2026-08-20T10:53:00+09:00
verified:
  - by: codex/gpt-5.4
    at: 2026-08-20T11:20:00+09:00
  - by: human:alex
    at: 2026-08-20T13:37:00+09:00

verified 是一张只增不改的列表。同一个空间里会有好几个 AI 进出，如果它只是一个值，后来的 AI 跑一遍交叉检查，就会把你的签核覆盖掉。做成列表，你的那一条就永远留在里面。

读的时候看整张列表：没人核过，是未验证；只有 AI 核过，是机器确认；只要有一条来自你本人，就是人工审阅过。

只有 AI 写的笔记才带这几个键。你自己写的日记和随手记，什么都不用加。

任务

复选框里的那个字符，就是任务的状态：

写法	意思
`- [ ]`	在等前置条件，暂时做不了
`- [/]`	现在就能做
`- [x]`	做完了
`- [!]`	卡点：在等外部的事，或者挡住了别的事

比常见的「做了 / 没做」多两种，是因为一张待办清单最需要回答的问题是「现在能做什么」。Bonsai 的「今天」页面就按这几个字符把任务分成到期、可做、卡点三组。

同一个标题下的几个 [/] 会被当成一条有先后顺序的链，「今天」只显示第一个，其余折叠起来。所以两条并行的工作线，各给一个标题就好。

有截止日的任务，在后面写 📅 YYYY-MM-DD。不用把它链接到哪天的日记，Bonsai 会自己把到期的任务找出来。

链接

[[笔记名]] 链接到另一篇笔记，人可以点过去，AI 也可以顺着它去读。

在 Bonsai 里，一个事实只住在一个地方。王师傅的电话写在他自己的笔记里，项目笔记里放一个链接就够了。复制一份，两边迟早会对不上。

表格和图

有些结构本身就是信息，Bonsai 会直接把它画出来：

项目笔记里一张带 step、date、status 列的表，会原地变成时间线，告诉你今天在哪、离下一步还有几天。
领域笔记里 ## Habit 下面的表，定义你的习惯，在日志页变成热力图。
一段 mermaid 代码块会被画成图，比如任务之间的依赖关系。

这些都还是普通的 Markdown 表格和代码块。在别的编辑器里打开，它们照样是一张能读的表。

为什么是 Markdown

你的笔记只有一份。 Bonsai 的界面是这些文件算出来的结果，背后没有另一个数据库藏着「真正的数据」。索引和缓存随时可以丢掉重建，文件才是唯一的真相。

人和 AI 读的是同一份。 结构来自固定的写法，比如复选框里的字符、约定的小节标题、front matter 里的键，而不是一套只有程序才看得懂的格式。你读得顺，AI 也读得准。

它不会把你锁住。 纯文本不依赖任何一家公司。换 App、换 AI、换设备，笔记都还在，也都还能读。

AGENTS.md:写给 AI 的说明书

每个空间的根目录都有一份 AGENTS.md。它把这一页讲的格式，连同空间怎么组织、AI 可以怎么读写，完整地写给所有来访的 AI。它在每个用户那里都一样。

你自己的规矩，比如希望助手用什么语言回复、怎么称呼你，写在 7_Self/Instructions.md。它可以加规则，但不能改格式，因为格式是 Bonsai 和你的笔记之间的约定。