Obsidian base author

你要把一个组织需求落成一份合法、可被 Obsidian 正确渲染的 .base 文件。你不需要判断问题能不能用 base 回答、该不该为它新建 base，你要做的只是想尽一切办法创建符合查询需求的 base 文件。

前置条件

Obsidian 1.12.7 及以上，并已启用 CLI：Settings → General → Command line interface（一次性注册后会生成 obsidian 命令）。若命令报「command not found」，说明 CLI 尚未注册，请如实报告，不要改用其他工具绕开。

命令依赖 Obsidian 应用运行，但不必手动先开；首条命令会自动把它启动起来，可能略有延迟。

关键约定

1. 一个 .base 文件只放一个视图。 需要第二个视图就新建第二个文件。
2. 文件名主体等于视图的 name 字段，由「功能词加视图类型词」连写组成。 视图类型词取常用三种的中文说法（表格、卡片、列表），紧跟在功能词之后，不加点号也不加任何分隔符。例如把阅读清单做成卡片视图，存成 阅读清单卡片.base，name 也写「阅读清单卡片」。这样跑 obsidian bases 看一眼文件名就能同时认出视图的功能与类型。

由这两条推出的简化：因为只有一个视图，全局 filters 与视图级 filters 的区分失去意义，两者求值时按 AND 拼接。筛选统一写在全局 filters，单个 views 条目只管呈现，即 order、groupBy、limit、视图级 summaries，结构最干净。

工作流

1. 先列出已有 base。 跑 obsidian bases 列出 vault 里全部 .base 文件，确认目标文件名不与现有文件冲突。新建的 .base 一律写到 vault 根的 bases 目录下。这一步强制，不可跳过。
2. 确认数据集与布局。 明确这一个视图要呈现哪些笔记，可按标签、文件夹、属性、日期、文件类型圈定，以及用哪种布局，可选 table、cards、list、map。
3. 写 filters（统一放全局）。 用比较运算符与函数表达筛选。注意 file.hasTag 连带命中嵌套标签，file.inFolder 连带命中子文件夹。详见 references/filters-and-operators.md 与 references/properties-and-this.md。
4. 按需写 formulas。 计算列写在这里。可能缺失的属性一律用 if(prop, ...) 做空值保护；两个日期相减得到的是毫秒数，类型为 number，求天数要除以 86400000，小时除 3600000、周除 604800000，结果是数字可直接 .round()，没有 .days 这类字段；公式间引用不得成环。详见 references/type-system.md 与 references/functions-index.md。
5. 写 properties 与 summaries。 properties 配显示名，summaries 定义自定义汇总。默认汇总有 Average、Sum、Median、Earliest、Checked、Unique 等，见 references/views-and-summaries.md。
6. 组装那唯一的 views 条目。 name 与文件名主体一致，填 order 定要显示的属性顺序、sort 定行的排序，以及 groupBy、limit、视图级 summaries。凡是要「最近 N 篇」「某序在前」的，必须写 sort，只写 limit 是按默认顺序截断，拿不到想要的那批。视图细节见 references/views-and-summaries.md。
7. 校验后写入 vault。 必须是合法 YAML；含双引号的公式整体用单引号包裹；含特殊字符的字符串加引号；order 与 properties 里每个 formula.X 都要在 formulas 有定义。引号规则见 references/quoting-rules.md，逐项校验见 references/validation-checklist.md，具体错误模式见 references/ 下 pitfall- 开头的各页。
8. 自检渲染结果。 跑 obsidian base:query path=bases/<文件名>.base format=md，路径即第 7 步写入的那个，看视图是否真的产出预期行。单视图无须传 view=。纯写文件无法预览，这一步是唯一的事实校验。
   • backlinks 与 properties 引发的豁免。 若自检结果与预期不符，而这个 base 的筛选、公式或 order 用到了 file.backlinks 或 file.properties，先怀疑是这两者不随 vault 自动刷新、CLI 读到陈旧索引所致，而不是 base 文件本身有错。判据是：把对这两个属性的依赖排除后，base 在 YAML 语法与查询逻辑上都成立。满足时不要反复改 base 去追这个假错误，把这次不符判为豁免，如实告诉用户自检受索引刷新限制无法确认，并引导用户自己在 Obsidian 里打开这个 .base 文件查看，应用内是实时数据，以应用内结果为准。

参考文档导航

正文细节全部下沉到 references/，按需求查下表打开对应页面：

需求	看哪一页
整体 YAML 形状与五大区块	references/base-file-schema.md
写筛选条件、运算符	references/filters-and-operators.md
属性引用、file 属性表、this	references/properties-and-this.md
类型、日期算术、日期相减得毫秒数	references/type-system.md
找某个函数（速查签名）	references/functions-index.md
某函数的参数语义与示例	references/functions-detail.md
视图配置、汇总、默认 summary	references/views-and-summaries.md
引号该用单双引号	references/quoting-rules.md
写入前逐项校验	references/validation-checklist.md
字符串含特殊字符报 YAML 错	references/pitfall-unquoted-special-chars.md
双引号公式报 YAML 错	references/pitfall-nested-quotes.md
日期相减算不出天数	references/pitfall-date-subtraction-no-days.md
属性为空时公式崩	references/pitfall-missing-null-guard.md
formula.X 静默失效	references/pitfall-undefined-formula-reference.md
进行中任务表格范例	references/example-tasks-in-progress.md
阅读清单卡片范例	references/example-reading-list.md
日记索引表格范例	references/example-daily-note-index.md