# Notion Sync

> 将对话内容结构化地同步到 Notion 数据库。触发词：同步到 notion、更新到 notion、存到 notion、记录到 notion、保存到 notion、写入 notion。首次使用需交互式配置 API Token 和数据库 ID，自动读取属性结构并设置映射。

- Skill: `duangduang55/notion-sync` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add duangduang55/notion-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/duangduang55/notion-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: duangduang55 (https://skillmd.com/u/duangduang55)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/duangduang55/notion-sync

---


# Notion Sync Skill

将 Claude 对话中的关键内容以结构化方式写入 Notion 数据库。自动区分用户输入和 AI 回答，原文直出不做加工。

## 配置存储

- 配置文件：`config.json`
- 辅助脚本：`scripts/notion_client.py`

## 初始化流程（首次触发时执行）

当检测到配置文件不存在时，执行以下流程：

### 步骤 1：引导用户获取必要信息

告知用户需要提前准备两样东西：

**1. Notion API Token（Internal Integration Secret）**
引导用户前往 https://www.notion.so/my-integrations：
- 点击 "New Integration" → 填写名称（如 "Claude Sync"）
- 选择关联的工作空间 → 点击 Submit
- 复制 "Internal Integration Secret"（以 `secret_` 开头）

**2. Database ID**
用户在 Notion 中打开目标数据库页面，URL 格式为：
`https://www.notion.so/{ workspace }/{ page_id }?v=...`
其中 `page_id` 的 32 位 UUID 即为 database_id。

### 步骤 2：交互式初始化

运行辅助脚本的 init 命令：

```bash
python3 ./scripts/notion_client.py init
```

此脚本会：
1. 提示用户输入 API Token 和 Database ID
2. 自动验证连接有效性
3. 读取并展示数据库所有属性（名称、类型、说明）
4. 标记 title 属性
5. 询问用户是否要自定义属性映射
6. 保存配置到 config.json

### 步骤 3：授权提醒

如果初始化时报 404 错误，提醒用户：
- 确保 Integration 已被邀请到目标数据库
- 在数据库页面右上角 → Share → Invite → 选择刚才创建的 Integration

## 主流程（每次触发时执行）

每次用户触发"同步到 Notion"时，执行以下步骤：

### 步骤 1：读取配置

```bash
python3 ./scripts/notion_client.py show-config
```

如果配置文件存在 → 继续主流程
如果配置文件不存在 → 转入初始化流程

### 步骤 2：提取对话内容

从当前对话上下文中提取以下内容：

**a) 用户原始输入** — 用户最近一次输入的全部内容，**原文保留**
**b) AI 回答** — 我对该次输入的全部回答内容，**原文保留，不做任何加工**
**c) 用户输入提炼总结** — 对用户输入进行结构化提炼，格式示例：
    ```
    核心问题：xxx（一句话）
    关键要点：
    - 要点 1
    - 要点 2
    ```
**d) 核心思想摘要** — 用**150字以内**总结本次对话的核心思想，作为 Summary 属性值
**e) 标签** — 提炼 **1~3 个标签**（逗号分隔），作为 Tags 属性值
**f) 生成标题** — 根据用户输入，生成 30 字以内的简洁标题

### 步骤 3：生成结构化 JSON

将内容直接组装为 JSON（不加工、不提炼），通过管道传给辅助脚本的 create-page 命令。AI 回答会被脚本解析为 Notion 原生 blocks（标题、段落、列表、表格、代码块等）：

```bash
cat << 'JSONEOF' | python3 ./scripts/notion_client.py create-page
{
  "title": "30字以内的标题",
  "user_raw": "用户的原始输入内容（原文）",
  "user_summary": "提炼后的用户核心需求\n- 要点1\n- 要点2",
  "summary": "150字以内的核心思想摘要",
  "tags": "标签1, 标签2, 标签3",
  "ai_response": "AI 的回答内容（原文，完整保留原始 Markdown 格式）"
}
JSONEOF
```

### 步骤 4：反馈结果

- 成功：告知用户 "✅ 已同步到 Notion"，附上页面 URL
- 失败：输出错误信息，根据错误类型给出修复建议：
  - 401 → Token 失效，需要重新初始化
  - 404 → 数据库访问权限问题
  - 400 → 请求体格式问题（通常是属性类型不匹配）

## 管理命令

用户可以通过以下方式管理配置：

- **查看配置** → 运行 `python3 .../notion_client.py show-config`（或在对话中询问 "查看 notion 配置"）
- **重置配置** → 运行 `python3 .../notion_client.py reset`（或在对话中询问 "重置 notion 配置"）

## 关键注意事项

1. **API Token 安全**：token 只存储在本地 config.json，不在对话中暴露完整 token
2. **Notion API 版本**：固定使用 `2022-06-28`
3. **属性兼容**：不同的属性类型对应不同的 JSON 格式（helper 脚本已内置处理）
4. **保持原文**：user_raw 和 ai_response 必须保持原始内容，不做缩写、重写
5. **AI 回答格式**：ai_response 中的 Markdown 会被解析为 Notion 原生 block（标题、段落、列表、表格、代码块等），请保证 ai_response 使用标准 Markdown 格式
6. **Summary 属性**：summary 字段控制在 150 字以内，提炼此次对话的核心思想
7. **Tags 属性**：tags 字段用逗号分隔 1~3 个标签