# Obsidian Base Author

> 编写与修改 Obsidian Bases（`.base` 文件），为笔记建立数据库式视图，含筛选、公式、属性显示名、汇总与单个视图的布局。当前工作目录本身就是一个 Obsidian vault。当用户要新建或改动 `.base`，要给笔记做表格、卡片、列表视图，要做阅读清单、索引、仪表盘这类需求时走本 skill。它内置了 Bases 语法、函数的完整参考，以及本仓库约定的命名与单视图规则。触发示例：「给我的任务建一个表格视图」「做一个阅读清单的卡片视图」「按文件夹和标签筛出笔记列成表格」「改一下这个 base 的筛选条件」。

- **Type:** Skill
- **Install:** `agentstack add skill-21noises-agent-skills-obsidian-base-author`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [21noises](https://agentstack.voostack.com/s/21noises)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [21noises](https://github.com/21noises)
- **Source:** https://github.com/21noises/agent-skills/tree/main/plugins/obsidian/skills/obsidian-base-author

## Install

```sh
agentstack add skill-21noises-agent-skills-obsidian-base-author
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

你要把一个组织需求落成一份合法、可被 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` |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [21noises](https://github.com/21noises)
- **Source:** [21noises/agent-skills](https://github.com/21noises/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-21noises-agent-skills-obsidian-base-author
- Seller: https://agentstack.voostack.com/s/21noises
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.