agentleFS
70asunflower70asunflower/70asunflower-skills/notion-im-helper/SKILL.md

notion-im-helper

Skill1 starsChanged 15 days agoMITView on GitHub

Sync IM messages to Notion via Notion API. Supports 7 content types, 4 formats, 2 metadata types, multi-page sync. Append-only. Triggers: 发到 Notion, 记到 Notion, 闪念速记, 待办清单, 同步消息到 Notion.

  • Reads credentials
  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 5 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    For AI callers: If user says "notion lifeos 日记:" or mentions "lifeos" page, add --page lifeos.

    line 72
  2. Distinctive:

    When the user sends a message matching a trigger pattern, execute the corresponding script:

    line 88
  3. Very specific:

    If the message also has preceding text (before caption:), that text is synced as a normal callout (diary/idea), and only the caption text …

    line 163
  4. Distinctive:

    Remove metadata from content before passing to script

    line 186
  5. Very specific:

    Always run check_config.py first on first use.

    line 204
  6. Distinctive:

    When user sends both image and text in one message:

    line 217
  7. Distinctive:

    Do NOT put image and text in the same command

    line 232
  8. Very specific:

    When user sends image only (no text or just "同步到notion"), upload the image as-is using record.py image.

    line 233
  9. Very specific:

    Implementation for link + caption: Write URL + caption text together to .pending_content.txt, then run record.py record --type link.

    line 242
  10. Very specific:

    Content passing: Always use .pending_content.txt (write file → run script).

    line 253
  11. Very specific:

    ⚠️ CRITICAL — File path: Write to .pending_content.txt,放在本技能的 scripts 目录(即 record.py 所在目录;无论从哪个 runtime 调用,都以脚本自身目录为准)。写工作区根目录会读到空内容。

    line 254
  12. Distinctive:

    Type inference: If user says "notion" or "同步" without specifying type, infer from content:

    line 256
  13. Very specific:

    Undo: Use record.py undo — respects 5-min batch window, deletes all blocks from last batch.

    line 262

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Notion IM Helper

通过消息自动同步内容到 Notion。支持日记、笔记、待办、想法、问题、链接、摘抄 7 种类型。

Environment Variables

  • NOTION_API_KEY - Notion Integration Token
  • NOTION_PARENT_PAGE_ID - Target Notion Page ID (32 chars)
  • NOTION_QUOTES_PAGE_ID (optional) - Separate page for quotes

Setup

  1. No third-party dependencies — everything (API calls and image uploads) is implemented with the Python standard library (urllib). No pip install needed.
  2. Set config in P:/my_project/.notion_env (see Configuration & Resilience below) — do NOT rely on C: environment variables alone, they are wiped on system reset.
  3. Authorize integration on Notion page (··· > Connections).

Directory Structure

scripts/
├── core/                  # Generic, portable — no user data
│   ├── blocks.py          # Block builders (callout, paragraph, image, etc.)
│   ├── dispatch.py        # Content dispatch & format parsing
│   └── __init__.py
├── user/                  # Personalized — your config only (not committed)
│   ├── pages.json         # Named page ID mappings (e.g., "lifeos")
│   ├── lifeos/            # 8+1 Life OS modules (os_entry.py 依赖)
│   │   ├── client.py      # Notion DB 读写
│   │   ├── commands.py    # 命令路由
│   │   └── config.json    # 数据库 ID 映射(不入库)
│   └── README.md
├── record.py              # Entry point (imports from core/)
├── os_entry.py            # OS 管道入口
├── os_parser.py           # OS 属性解析(@桶 / energy: / mood: 等)
├── notion_client.py       # Notion API client
├── check_config.py        # Config verification
├── search_notes.py        # Keyword search
└── summary.py             # Monthly summaries

Multi-Page Support

You can sync to multiple Notion pages by configuring named pages in scripts/user/pages.json(个人页面 ID,不入库;新环境从 NOTION_PARENT_PAGE_ID 起步,或自建该文件):

{
  "2026": {
    "page_id": "<32-char page id>",
    "description": "2026 年度页(默认同步目标)"
  },
  "lifeos": {
    "page_id": "<32-char page id>",
    "description": "8+1 Life OS(用 --page lifeos 指定)"
  }
}

Then use --page <name> in any command:

python scripts/record.py record --type diary --page lifeos
python scripts/record.py image --page lifeos "image.jpg"
python scripts/record.py undo --page lifeos

Without --page, defaults to NOTION_PARENT_PAGE_ID.

For AI callers: If user says "notion lifeos 日记:" or mentions "lifeos" page, add --page lifeos. Otherwise omit --page for the default page.

Configuration & Resilience

  • Config file (survives system resets): P:/my_project/.notion_env — keep secrets here, NOT only in C: environment variables (a Windows reset wipes C:).
    NOTION_API_KEY=ntn_xxxxx
    NOTION_PARENT_PAGE_ID=<32-char page id>   # 2026 annual page (default sync target)
    NOTION_QUOTES_PAGE_ID=...   # optional
  • The client resolves config in this order: environment variable → Windows registry → P:/my_project/.notion_env (first match wins).
  • Default sync page is 2026(页面 ID 见 scripts/user/pages.json,不入库). Use --page lifeos to target the 8+1 Life OS page.
  • Image uploads need no extra library. notion_client.upload_file() implements Notion's File Upload API directly with urllib (create upload session → send bytes as multipart). It runs on whatever interpreter invokes record.py; there is no dedicated venv and nothing on C: to lose on a system reset.

Usage

When the user sends a message matching a trigger pattern, execute the corresponding script:

python scripts/record.py record --type {type} "{content}"
python scripts/record.py record --type {type} --page {name} "{content}"
python scripts/record.py record --type {type} --file {file_path}
python scripts/record.py heading --level {1|2|3} "{text}"
python scripts/record.py divider
python scripts/record.py list --kind {bullet|number} "{items}"
python scripts/record.py toggle "{json}"
python scripts/record.py image [--caption "text"] "{file_path_or_url}"
python scripts/record.py image --page {name} [--caption "text"] "{file_path_or_url}"
python scripts/record.py undo
python scripts/check_config.py
python scripts/search_notes.py "{keyword}"
python scripts/summary.py {monthly|quote}

Trigger Rules

⚠️ FIRST CHECK — OS vs Page routing (MUST check before anything else)

The two pipelines are mutually exclusive. Never let a message fall through from one to the other.

Message arrives
    ↓
STEP 0: Starts with "os " (case-insensitive)?
    → YES: Route to OS Sync (§ below). STOP. Do NOT check page triggers.
    → NO:  Route to Page Sync (§ below).

OS Sync (OS Sync — 8+1 Life OS section) → structured database rows. Page Sync (rest of this section) → append callout blocks to page.

Page Sync Triggers (only if NOT "os ")

  • 日记: / 今天: / riji: / d → diary
  • 笔记: / 学习: / note: / n → note
  • 待办: / todo: / t → todo
  • done: / 完成: / √ → done
  • 想法: / 灵感: / idea: / flash: / 闪念: / i → idea
  • 问题: / 疑问: / q: → question
  • 摘抄: / quote: / qu: / z → quote
  • 链接: / link: / url: / l → link
  • 图片: / photo: / img: / p → image
  • caption: / 说明: / 补: → image caption (text becomes caption of the co-sent image; always used with an image)

Formats:

  • * text → H1 heading
  • ** text → H2 heading
  • *** text → H3 heading
  • > text → quote block
  • --- → divider
  • - text → bulleted list
  • 1. text / 2. text etc → numbered list
  • toggle: title + subsequent - / -- / --- lines → toggle block

Commands:

  • 月报 / monthly → extract current month records for summary
  • 摘抄 / 随机摘抄 → random historical entry
  • 搜: xxx / search: xxx → search records by keyword
  • 撤回 / undo → delete last batch of blocks (within 5 min window)
  • 配置检查 / check config → verify config

Smart detection (no prefix, AI infers):

  • Pure URL → link
  • Starts with YYYY-MM-DD → diary
  • Contains [ ] or 【 】 → todo
  • Default → idea

Caption — routing rule (IMPORTANT):

caption: / 说明: / 补: is ALWAYS used together with an image in the same message for this user. There is no standalone "caption without image" case — do NOT use record.py caption (which appends to the last callout); that path is NOT used here.

  • The text after caption: becomes the image's caption, uploaded via record.py image --caption "text" "path".
  • If the message also has preceding text (before caption:), that text is synced as a normal callout (diary/idea), and only the caption text goes on the image (see Image + Text Sync Rules below).
  • Strip any @image#N:... / wechatmp-img-... markers from the caption text before passing it.

Implementation:

python scripts/record.py image --caption "caption文字" "图片路径"

Caption attachment reference (verified via API):

Block typeSupports caption?How to attach
Image✅ Yes (API accepts despite official docs showing no)--caption on record.py image
Bookmark✅ Yes--caption on record.py record --type link (auto-extracts)
File✅ Yesvia API directly
Code✅ Yesvia API directly
Callout (💡/📒)❌ NoNotion API has no caption field on callout blocks

Metadata

Scan the LAST line for metadata:

  • #关键词 → tag
  • /p:项目名 → project
  • Remove metadata from content before passing to script

Batch & Undo

  • Multi-line messages: each format line (heading/quote/divider/list) becomes a separate block, sent in a single API call
  • Undo within 5 minutes: deletes all blocks from the last batch
  • Undo after 5 minutes: deletes only the last single block
  • Day separator: a divider is auto-inserted when the last record is from a different day

Output Protocol

Scripts emit standardized output prefixes:

  • OK|message → success, relay success message to user
  • ERROR|CONFIG → guide user to set up Notion integration
  • ERROR|AUTH → invalid API key or page not authorized
  • ERROR|RATE_LIMIT → tell user to wait
  • ERROR|NETWORK → tell user to retry later

Always run check_config.py first on first use. Never modify or delete existing Notion blocks.

Image Upload

  • Supports local file paths (e.g., C:\Users\photos\img.jpg) and HTTP URLs (e.g., https://example.com/photo.png)
  • Local files are uploaded to Notion servers via the File Upload API, then attached as image blocks
  • URL images are referenced directly as external image blocks
  • Optional --caption flag to add caption text to the image
  • Max file size: 5MB (Notion API limit)
  • Supported formats: jpg, jpeg, png, gif, webp, bmp, svg

Image + Text Sync Rules

When user sends both image and text in one message:

  1. Parse text: split by caption: / 说明: keyword (if present) — this is the Caption Separator mode
    • Before caption: → diary/idea/note content (synced as callout)
    • After caption: → image caption (added to last image via --caption)
  2. Upload images: first N-1 images without caption, last image with --caption
  3. Sync text: write diary/idea content to .pending_content.txt, then record.py record --type {type}

Examples:

  • OPPO园区很好 caption: 园区环境 + 3 images → last image gets caption "园区环境", diary "OPPO园区很好" synced separately
  • 这张图有意思 + 1 image → no caption keyword, so no caption on image, "这张图有意思" synced as idea
  • 2 images only → just upload both, no caption, no callout

IMPORTANT:

  • Image and text are always separate operations — image via record.py image, text via record.py record
  • Do NOT put image and text in the same command
  • When user sends image only (no text or just "同步到notion"), upload the image as-is using record.py image. Do NOT transcribe/OCR the image content into a callout
  • CRITICAL — No double sync: When message starts with caption: and has an image, the text after caption: goes ONLY as image caption (via --caption). Do NOT also create a diary/note callout with the same text. If caption: is the FIRST keyword (no text before it), the entire content is caption-only — zero callout blocks.

Link + Caption

Same caption: pattern works for links:

  • 链接: https://example.com caption: 好文章 → bookmark with caption "好文章"
  • Without caption:, just a plain bookmark card (Notion auto-fetches title)

Implementation for link + caption: Write URL + caption text together to .pending_content.txt, then run record.py record --type link. The code auto-extracts URLs and uses remaining text as bookmark caption. Do NOT sync link and caption separately — cmd_caption only appends to callout blocks, not bookmark blocks.

Long Content Auto-Split

  • ≤2000 chars: Single callout (most entries)
  • >2000 chars: Auto-split into multiple callouts at paragraph boundaries (e.g., 3-4k chars → 2-3 callouts)
  • Metadata (tags/projects) only added to the last callout
  • AI should write the entire content to .pending_content.txt at once — do NOT manually split into multiple calls

Best Practices for AI Callers

  • Content passing: Always use .pending_content.txt (write file → run script). Never pass content via command-line args (PowerShell $ expansion issues).
    • ⚠️ CRITICAL — File path: Write to .pending_content.txt,放在本技能的 scripts 目录(即 record.py 所在目录;无论从哪个 runtime 调用,都以脚本自身目录为准)。写工作区根目录会读到空内容。
  • Image passing: Pass image file path or URL directly as command-line argument to record.py image. Do NOT copy to .pending_image.jpg — that file is only used internally for cleanup.
  • Type inference: If user says "notion" or "同步" without specifying type, infer from content:
    • Starts with caption: / 说明: / 补: → image caption (must be paired with image; use record.py image --caption)
    • Contains "日记"/"今天" → diary
    • Contains URL → link
    • Image only → image (use record.py image)
    • Default → idea
  • Undo: Use record.py undo — respects 5-min batch window, deletes all blocks from last batch.

OS Sync — 8+1 Life OS

以 os 命名空间前缀触发,同步到结构化数据库。与页面同步互斥,绝不串线。

Trigger Detection

消息以 os (不区分大小写)开头时,立即进入 OS 同步流程。不检查页面触发词。

❌ 错误: i 想法 → OS sync(没 os 前缀,走页面) ✅ 正确: os i 想法 @学习 → OS sync ✅ 正确: i 想法 → page sync(idea callout) ❌ 错误: os 月报 → 错误路由到页面 monthly summary

OS Commands

python scripts/os_entry.py "os l 晨跑5公里 @身体 energy:h duration:30"
python scripts/os_entry.py "os i 试试Obsidian做知识图谱 @学习 source:ai"
python scripts/os_entry.py "os h 冥想"
python scripts/os_entry.py "os 今天"

Command Routing

触发命令目标数据库说明
os l / os log / os 记录活动记录Daily Log记录做了什么,可带属性
os i / os idea / os 灵感灵感捕捉Idea Inbox快速捕捉想法
os h / os habit / os 打卡习惯打卡Habit Log标记习惯完成
os hs / os streaks查看 streakHabits更新并显示连续天数
os 今天今日摘要Daily Log查看今日活动
os 本周本周汇总Daily Log近 7 天活动
os 桶 @身体桶查询Daily Log某桶近 14 天记录
os 灵感列表灵感列表Idea Inbox查看未处理灵感
os 周报 / os wr周回顾Weekly ReviewAgent 生成周报
os 月报 / os mr月复盘Periodic ReviewAgent 生成月报

Attribute Syntax

用空格分隔的属性语法,AI 通过 os_parser.py 自动解析:

属性语法示例
桶@桶名@身体 @Learning @Body
能量energy:h/m/lenergy:h (高/中/低)
心情mood:great/good/neutral/low/terriblemood:good
时长duration:Nduration:30 (分钟)
来源source:xxxsource:ai source:book
紧急度urgency:now/thisweek/laterurgency:now
备注note:xxx 备注:xxxnote:天气不错

桶名匹配:支持中英文(@身体 = @Body),不区分大小写。未知桶名会返回可用列表。

Content vs Notes — 分开存

  • Content(标题):一句话「做了什么」,如「写作 320 字」「晨跑 5 公里」。这是列表里显示的那行。
  • Notes(备注):补充细节、感受、对不上选项的原话放这里。如「状态不错,挺有成就感」。

AI 调用时,若消息含描述性文字(超过动作本身),把动作放 Content,其余放 Notes:

os l 写作320字,状态不错挺有成就感 @学习 energy:h
→ Content: "写作320字"
→ Notes: "状态不错,挺有成就感"

Smart Inference(无显式属性时自动推断)

Energy 口语映射:

  • 累 / 没劲 / 困 → energy:l
  • 一般 / 还行 / 正常 → energy:m
  • 精神好 / 精力充沛 / 有干劲 → energy:h

Mood 口语映射:

  • 开心 / 有成就感 / 爽 → mood:good 或 mood:great
  • 一般 / 还行 → mood:neutral
  • 烦 / 难受 / 焦虑 / 低能量 → mood:low 或 mood:terrible

Bucket 关键词推断:

  • 跑步 / 健身 / 运动 / 饮食 / 睡眠 → @身体
  • 读书 / 上课 / 论文 / 学习 / 课程 → @学习
  • 工作 / 项目 / 写代码 / 开会 / 赚钱 → @赚钱
  • 家人 / 父母 / 视频通话 → @家庭
  • 朋友 / 聚会 / 社交 → @社交
  • 冥想 / 日记 / 独处 / 正念 → @精神
  • 开源 / 帮助 / 指导 / 公益 → @服务
  • 游戏 / 旅行 / 玩 / 放松 → @玩乐

匹配不到就留空,不回传 bucket 属性。绝不替用户建新桶。

多事件拆分

一条消息含多件事时,拆成多条 os l 命令分别调用:

os l 晨跑5公里 @身体 energy:h duration:30
os l 写代码3小时 @赚钱 energy:m duration:180
os l 晚上和爸妈视频 @家庭

大小写规则(Notion API 敏感)

所有属性名和 select 值必须精确大小写:

  • Energy: High / Medium / Low(不是 high)
  • Mood: Great / Good / Neutral / Low / Terrible(不是 good)
  • Daily Log 属性名: Content, Date, Energy, Duration_min, Bucket, Adventure, Mood, Notes
  • 公式/rollup 字段(OverallScore, TotalCompletions, Avg_*)绝不要写
  • Place 字段跳过,不要写

短记录 vs 长日记(路由)

  • os l 或无前缀且短 → 建 Daily Log 行(结构化属性)
  • 日记: 或明显长篇/情绪流 → 走原有页面同步(append callout blocks)

AI 调用流程

  1. 检测用户消息以 os 开头
  2. 智能推断(消息无显式属性时):
    • 扫描关键词推断 bucket(跑步 → @身体)
    • 扫描情绪词推断 energy/mood(累 → energy:l;开心 → mood:good)
    • 提取时长(一小时 → duration:60)
  3. 拆解 Content vs Notes:
    • 把「动作」放 Content(「晨跑5公里」)
    • 把「感受/细节」放 Notes(「状态不错,呼吸顺畅」)
  4. 构建完整 os 命令(带推断出的属性),调用 python scripts/os_entry.py "完整消息"
  5. 解析输出:OK|... / INFO|... / ERROR|...
  6. 不需要 .pending_content.txt 文件(OS 直接传参)

OS vs Page Sync — 严格互斥(MUST)

两个管道绝不串线。os 开头 → OS 同步,否则 → 页面同步。没有歧义、没有回退、没有"两者都试试"。

消息正确管道错误管道
os l 晨跑 @身体OS → Daily Log 行—
os i 灵感 @学习OS → Idea Inbox 行—
i 随便一个想法Page → idea callout❌ 别走 OS
想法: 好主意Page → idea callout❌ 别走 OS(没 os 前缀)
日记: 今天好累Page → diary callout❌ 别走 OS
月报Page → monthly summary❌ 别走 OS(os 月报 才对)
os 月报OS → 数据库聚合✅

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.