notion-life-system

Notion 生活系统（Life System）

核心规则

把 Notion 当作一个活的个人操作系统。默认只读检查，除非用户明确要求创建、更新、移动、归档、删除或以其他方式修改 Notion 数据。

绝不从本 skill 修改数据库 schema。结构探查类任务期间绝不修改 Notion 页面。

当用户说要写入某个具体 Notion 页面，或提供了目标 Notion 页面 URL 加内容时，把这视为只对该页面的明确修改授权。除非用户明确要求替换，否则保留页面已有内容。

必备参考文件

按需加载，不一次全读：

• references/notion-intake-rules.md: 处理随手输入的主路由规则，含每个数据库的场景、写入策略、可填字段、关联字段、禁填字段，以及 queryDefaults（排序字段 + 展示字段）。
• references/notion-intake-rules.json: 入库规则的机器可读版本。创建页面、查询记录或运行数据库查询前先用它。
• references/notion-system-schema.md: 人类可读总览、路由表、数据库 ID、关联图、rollup 图、属性表。
• references/notion-system-schema.json: 精确的机器可读 schema，含所有 data source ID、数据库 page ID、属性 ID、关联目标、select/status 选项、rollup 配置和完整公式表达式。

当前快照由 数据管理 页面用 ntn CLI 生成。若用户说 Notion 结构变了，刷新它。

CLI 模式

Notion 操作用 ntn，不用浏览器自动化。

默认直连。打包脚本不再强制走代理。仅当 Notion API 调用因 TLS 或连接错误失败时， 才通过导出 NOTION_CLI_PROXY 选择走代理 （如 export NOTION_CLI_PROXY=http://127.0.0.1:1082）—— 脚本会自动识别。

ntn api v1/data_sources/<data_source_id>

数据库行查询用 data source ID：

ntn api v1/data_sources/<data_source_id>/query -d '{"page_size":10}'

页面读取或更新用 page ID：

ntn pages get <page_id>

指定页面的读写工作流，优先用打包的 helper：

~/.claude/skills/notion-life-system/scripts/notion_page_io.zsh id <page-url-or-id>
~/.claude/skills/notion-life-system/scripts/notion_page_io.zsh get <page-url-or-id> [output.md]
~/.claude/skills/notion-life-system/scripts/notion_page_io.zsh append <page-url-or-id> [content.md]
~/.claude/skills/notion-life-system/scripts/notion_page_io.zsh replace <page-url-or-id> [content.md]

append 和 replace 在调用 ntn pages update 之前，会先在 ~/.fios/notion-page-backups 下创建本地 Markdown 备份。

ntn 操作实战要点（踩过的坑，务必遵守）

• 创建页面（写记录）：ntn api v1/pages -X POST -d '{"parent":{"type":"data_source_id","data_source_id":"<id>"},"properties":{...}}'。parent 用 data_source_id（当前 API 版本 2026-03-11）；relation 填 {"relation":[{"id":"<page_id>"}]}、日期带时段用 {"date":{"start":"2026-06-03T14:00:00.000+08:00"}}。
• 删除/归档页面：用 ntn api v1/pages/<id> -X PATCH -d '{"in_trash":true}'。不要用 ntn pages trash——非交互环境会因确认提示失败（要 --yes）。
• 写入/PATCH 偶发失败要重试：ntn 偶有间歇失败（返回空/非 page，伴随 "stale cached OpenAPI spec" warning），原样重试 1–4 次通常即成功。批量写入/迁移/删除要逐项 GET 验证、失败重试——实测一批十个 PATCH 可能大半首发失败、静默漏掉。
• 解析响应前先清控制字符：ntn 返回的 JSON 常含未转义控制字符（formula 字段里的裸换行等），直接 jq/python 解析会报 "control characters must be escaped"。先 tr -d '\000-\037\177'（或 python re.sub(r'[\x00-\x1f\x7f]','',raw)）再解析；查询本身也偶发返回空，要重试。
• jq 后处理两个易错点：① 对象构造里中文 key 必须加引号（{"事项":...} 而非 {事项:...}）；② jq 顶层不能用分号连两个表达式（会编译错）。
• select/status/multi_select 绝不臆造值：select/multi_select 塞 options 里没有的值，Notion 不报错、自动新建脏选项（污染选项库，比报错更隐蔽）；status 塞越界值则 400。一律匹配 options，匹配不到留空。
• 字段名以 intake-rules.json 为准，可能含尾随空格：例如「日常打卡」指向习惯分类的 relation 字段名是 习惯分类 （末尾带一个空格），写错会 400「property does not exist」。