1. 项目概述：一个为AI工作流减负的“哨兵”

如果你正在使用像OpenClaw、Claude这类AI智能体来管理你的Notion任务看板，大概率会遇到两个让人头疼的核心矛盾。第一个是成本问题：每次AI回答“今天还有什么任务”时，它都需要调用Notion API去查询，这个“工具调用-获取结果-生成回答”的过程会持续消耗LLM的上下文令牌。日常高频的问答下来，令牌成本就像细水长流，积少成多。第二个更棘手的是数据一致性问题：AI为了快速响应，可能会把某次查询到的任务状态存入自己的记忆（向量数据库或会话上下文）。但如果之后你在Notion里手动把任务状态从“进行中”改成了“已完成”，AI并不知道这个变化。下次你问它时，它很可能依据过时的记忆给出错误答案，比如告诉你“那个报告还在做”，实际上你已经交差了。

노션우렁각시 （Woongaksi）就是为了解决这两个痛点而生的。它本质上是一个轻量级的后台守护进程（Daemon），扮演着“哨兵”的角色。它的工作逻辑非常直接：你照常在Notion里编辑你的任务看板，Woongaksi会以你设定的时间间隔（默认5分钟）主动去检查你指定的Notion数据库。一旦它发现有任何任务的内容、状态、截止日期等属性发生了变更，就会立刻通过Telegram Bot，将这条变更信息以一条自然语言消息的形式，发送到你与AI智能体共享的Telegram群组或聊天中。

这样一来，AI智能体就不再需要为了获取最新状态而频繁、主动地去查询Notion API。它只需要“倾听”Telegram聊天中的消息流。当Woongaksi发出“📋 项目X：状态 [进行中 → 已完成]”这样的通知时，AI就能在对话上下文中实时获知这一更新。后续当你询问任务进展时，AI可以直接基于聊天记录中最新的事实来回答，无需再次调用API，既实现了“零令牌”成本的状态同步，又彻底避免了因记忆陈旧导致的“幻觉”回答。整个方案只需要一个Notion集成令牌、一个Telegram Bot令牌和一个聊天ID，五分钟就能跑起来，将AI从重复的、昂贵的查询劳动中解放出来，让它专注于理解和决策。

2. 核心设计思路与架构解析

2.1 为什么是“轮询”而非“Webhook”？

看到这个设计，可能第一个疑问是：为什么选择周期性的轮询（Polling），而不是更“实时”的Webhook？这背后是Notion API当前限制下的务实选择。截至现在，Notion官方并未为数据库的变更提供原生的Webhook或推送通知服务。这意味着，没有任何一种方法能让Notion在数据变化时“主动通知”你的服务器。因此，想要获取变更，主动查询是唯一途径。

轮询间隔的设置（默认5分钟）是一个在实时性、API调用成本和系统负载之间的平衡点。对于大多数任务管理场景，5分钟内的延迟是完全可接受的。将间隔设置得更短（如1分钟）固然能提升实时性，但会导致对Notion API的调用次数呈线性增长，可能触及API的速率限制，同时也增加了不必要的网络开销和服务器负载。5分钟是一个经过权衡的、对用户友好且对系统友好的值。当然，这个间隔在配置文件中是完全可调的，你可以根据自己业务的敏感度来设定。

2.2 变更检测的核心：基于内容哈希的缓存比对

轮询的核心不是简单地拉取数据，而是 智能地识别出哪些数据发生了变化 。Woongaksi实现这一点的方法既经典又高效：基于内容哈希的缓存比对。

每次轮询时，程序会执行以下步骤：

1. 获取当前快照 ：通过Notion API，读取目标数据库中的所有条目（或根据过滤条件筛选后的条目），并提取你所关心的属性（如 标题 、 状态 、 负责人 、 截止日期 ）。
2. 生成唯一指纹 ：为数据库中的每个条目（Page）生成一个“指纹”。这个指纹不是简单的ID，而是将你指定追踪的所有属性值（ tracked_properties ）序列化为一个字符串（例如JSON格式），然后对这个字符串计算一个哈希值（如MD5或SHA-1）。这个哈希值就是该条目当前状态的唯一代表。只要任何一个被追踪的属性值发生改变，这个哈希值就会完全不同。
3. 与历史缓存比对 ：程序在本地维护一个简单的缓存文件（例如JSON格式），存储了上一次轮询时每个条目的ID及其对应的状态哈希值。将本次生成的新哈希值与缓存中的旧哈希值逐条对比。
4. 识别并通知变更 ：对于任何一个条目，如果发现其新旧哈希值不一致，则判定该条目发生了变更。程序会解析出具体是哪个属性发生了变化（从旧值到新值），并格式化一条易于阅读的消息，通过Telegram Bot发送出去。

这种方法的优势在于精准和轻量。它只会在真正发生变化时发出通知，避免了无谓的消息轰炸。同时，本地缓存机制使得程序重启后，能通过对比识别出自上次运行以来的所有变更，确保了状态的连续性。

2.3 与AI智能体的无缝集成哲学

Woongaksi的设计哲学是“通知而非查询”，这深刻影响了它与AI智能体的集成方式。它不试图成为AI的一个插件或直接修改AI的内部逻辑，而是通过一个双方都能理解的 公共通信通道（Telegram） 来传递事实。

这种松耦合的集成方式带来了巨大优势：

• 无侵入性 ：你不需要修改OpenClaw或其他AI智能体的核心代码。只需要确保AI智能体有能力读取并理解Telegram群组中的消息。
• 通用性 ：任何能接入Telegram的AI系统（无论是基于OpenAI API、Claude API还是本地模型）都能立即受益。
• 上下文即状态 ：AI智能体将Telegram聊天记录作为其对话上下文的一部分。Woongaksi发送的通知自然成为上下文中的最新事实。当用户提问时，AI的检索增强生成（RAG）机制或简单的上下文查找，就能优先使用这些新鲜、可靠的事实，无需触发成本高昂且缓慢的“工具调用”流程。

你需要为AI智能体做的唯一“设置”，就是在它的系统提示词（或称为角色设定、SOUL文件）中，明确加入一条规则： “来自Woongaksi Bot的、带有特定表情符号（如📋）的变更通知，是Notion数据库的真实、实时更新，应被视为最高优先级的事实来源，并据此更新内部认知。” 这相当于给AI建立了一条处理这类信号的标准操作程序。

3. 详细配置与实操部署指南

3.1 环境准备与依赖安装

Woongaksi基于Python 3.10+开发，确保你的系统环境符合要求是第一步。我推荐使用Linux服务器（如Ubuntu）或macOS进行长期后台运行，Windows则可用于测试。

# 检查Python版本，必须3.10及以上
python3 --version

# 升级pip至最新版本，避免安装依赖时出现问题
pip install --upgrade pip

接下来，获取Woongaksi的源代码。假设项目已托管在GitHub上：

# 克隆仓库到本地
git clone https://github.com/EESIZ/woongaksi.git
cd woongaksi

# 安装项目依赖
# 使用`pip install .`会以“可编辑”模式安装，方便开发。
# 对于生产部署，更推荐使用`pip install -r requirements.txt`（如果存在）。
# 这里假设项目使用`pyproject.toml`，直接安装即可。
pip install .

安装过程会自动处理所有Python包依赖，主要会包括 requests （用于调用Notion和Telegram API）、 pyyaml （用于解析配置文件）、 python-dotenv （用于管理环境变量）等。

3.2 核心凭证获取：Notion与Telegram

这是最关键的一步，任何凭证错误都会导致服务无法启动。

1. 创建Notion集成并获取API密钥：

• 访问 Notion开发者门户的集成创建页面 。
• 点击 “New integration” 。
• 为你的集成起一个名字，例如 Woongaksi Monitor 。
• 通常关联一个工作区（Workspace）。
• 在“Capabilities”权限部分， 至少需要勾选“Read content” 。因为我们只需要读取数据库内容来检测变更，不需要写入权限，这符合最小权限原则，更安全。
• 点击“Submit”创建。创建成功后，页面会显示一个以 secret_ 开头的 Internal Integration Token 。请立即复制并妥善保存，它只会显示这一次。

2. 将集成连接到你的数据库：

• 打开你想要监控的Notion数据库页面。
• 点击页面右上角的 ··· 菜单，选择 “Connections” 或 “Add connections” 。
• 在弹出窗口中，搜索并选择你刚刚创建的集成（如 Woongaksi Monitor ）。
• 点击确认。 这一步至关重要！ 每个需要被监控的数据库都必须单独执行此操作，否则API调用会返回 403 Forbidden 错误。

3. 获取数据库ID：

• 在Notion网页版中打开你的数据库。
• 浏览器地址栏的URL通常格式为： https://www.notion.so/yourworkspace/xxxxxxxxxxxxxxxxxxxxxxxxxxxx?v=... 。
• xxxxxxxxxxxxxxxxxxxxxxxxxxxx 这32位字符（可能包含连字符）就是你的数据库ID。复制它。

4. 创建Telegram Bot并获取令牌与Chat ID：

• 在Telegram中搜索 @BotFather 。
• 发送命令 /newbot 并按提示操作：为你的Bot起一个显示名称（如 Notion Update Bot ）和一个唯一的用户名（必须以 bot 结尾，如 my_notion_update_bot ）。
• 创建成功后，BotFather会提供一串如 1234567890:ABCdefGhIjKlMnOpQrStUvWxYz 的令牌，这就是 TELEGRAM_BOT_TOKEN 。
• 获取Chat ID ：这是一个容易出错的步骤。首先，将你刚创建的Bot添加到一个Telegram群组，或者直接给它发一条消息。
• 打开浏览器，访问以下URL（将 <你的Bot令牌> 替换为实际令牌）： https://api.telegram.org/bot<你的Bot令牌>/getUpdates
• 如果一切正常，你会看到一个JSON响应。在响应中寻找 "chat":{"id": -100xxxxxxxxxx} 或 "chat":{"id": xxxxxxxxx} 这样的字段。这个数字就是 TELEGRAM_CHAT_ID 。私聊的Chat ID是正数，群组的Chat ID通常是负数（并且以 -100 开头）。

关键提示 ：为了能让AI智能体接收到通知，你必须确保AI智能体（例如OpenClaw的Telegram插件）也在这个 相同的Chat ID所对应的聊天或群组中 。这样，Woongaksi Bot发送的消息，AI才能看到。

3.3 配置文件详解与定制

Woongaksi的配置主要通过一个YAML文件（ config.yaml ）来管理，结构清晰，易于理解。

首先，复制示例配置文件并进行编辑：

cd woongaksi
cp config.example.yaml config.yaml
cp .env.example .env

编辑 .env 文件 ，填入你的核心机密凭证：

# .env 文件内容
NOTION_API_KEY=secret_你的Notion令牌
TELEGRAM_BOT_TOKEN=你的TelegramBot令牌
TELEGRAM_CHAT_ID=你的Telegram聊天ID
# 以下为可选，有默认值
# POLL_INTERVAL_MINUTES=3
# WOONGAKSI_CONFIG=./config.yaml

编辑 config.yaml 文件 ，这是配置的核心：

# 全局轮询间隔（分钟）
poll_interval_minutes: 5

# 需要监控的数据库列表
databases:
  - name: "daily_tasks"          # 内部标识符，用于日志和缓存文件名
    id: "你的第一个数据库ID"      # 替换为实际的Notion数据库ID
    emoji: "📋"                   # 发送通知时使用的前缀表情，便于识别
    label: "每日任务"             # 通知中显示的数据库友好名称
    title_property: "任务名称"    # 你的数据库中，作为条目标题的属性名
    tracked_properties:           # 指定要监控变化的属性
      - "状态"
      - "优先级"
      - "截止日期"
      - "负责人"
    filter:                       # 可选的过滤条件，只监控符合条件的条目
      property: "状态"
      select:
        does_not_equal: "已完成"  # 例如：只监控状态不是“已完成”的任务

  - name: "project_ideas"
    id: "你的第二个数据库ID"
    emoji: "💡"
    label: "项目灵感库"
    title_property: "Idea Name"   # 属性名需与Notion中完全一致，英文区分大小写
    tracked_properties:
      - "Category"
      - "Priority"
      - "Stage"
    # 不设置filter则监控该数据库所有条目

配置项深度解析：

• tracked_properties ：这是精度控制的关键。只列出你真正关心的属性。如果你列了10个属性，但其中8个几乎不变，那么任何其他不相关属性的改动也会触发通知（因为哈希值变了）。建议只追踪那些状态会频繁变化的核心属性。
• filter ：强烈建议使用。例如，在任务数据库中，只监控“未完成”的任务可以显著减少API返回的数据量，提升轮询效率，并避免收到大量关于已完成历史任务的无关通知。
• title_property ：务必确认该属性在你的Notion数据库中存在且名称完全匹配（包括空格和大小写）。通常默认是 "Name" ，但中文环境可能是 "任务名" 、 "标题" 等。

3.4 服务启动、测试与后台常驻

配置完成后，可以进行测试运行。

# 方法一：手动加载.env变量并运行（适用于测试）
export $(grep -v '^#' .env | xargs)  # 在Linux/macOS Bash中加载.env文件
woongaksi --config config.yaml

# 方法二：程序自动加载.env（如果代码支持）
woongaksi --config config.yaml

如果一切正常，你将在终端看到类似以下的日志，表明它成功连接Notion并获取了初始数据：

[2024-05-27 10:00:00] INFO woongaksi: === 노션우렁각시 v0.1.0 시작 ===
[2024-05-27 10:00:00] INFO woongaksi: 모니터링 DB 2개, 폴링 간격 5분
[2024-05-27 10:00:00] INFO woongaksi:   📋 每日任务 [数据库ID...]
[2024-05-27 10:00:00] INFO woongaksi:   💡 项目灵感库 [数据库ID...]
[2024-05-27 10:00:01] INFO woongaksi.client: [daily_tasks] 15건 조회 (필터 적용)
[2024-05-27 10:00:01] INFO woongaksi: [daily_tasks] 최초 실행, 캐시 시딩 (15건)

进行手动测试 ：保持程序运行。立刻去Notion中，修改一个被监控数据库中的条目，改变其 状态 或 负责人 等被追踪的属性。等待最多5分钟（或你设置的轮询间隔），检查Telegram指定的聊天中是否收到了格式为 📋 每日任务：”撰写周报“的状态从 [进行中] 变更为 [已完成] 的通知。

部署为系统服务（以Linux systemd为例） ： 对于需要7x24小时运行的服务器，建议配置为systemd用户服务。

# 1. 创建配置和缓存目录
mkdir -p ~/.config/woongaksi
mkdir -p ~/.cache/woongaksi

# 2. 将配置文件和环境变量文件复制过去
cp config.yaml ~/.config/woongaksi/
# 注意：生产环境不建议将密钥放在.env文件，而是直接写在service文件里
# 复制.env中的键值对，准备写入service文件

# 3. 创建systemd用户服务文件
nano ~/.config/systemd/user/woongaksi.service

将以下内容写入 woongaksi.service 文件，并替换 YOUR_ACTUAL_TOKEN 为真实值：

[Unit]
Description=Woongaksi Notion Monitor Daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/python3 -m woongaksi --config /home/你的用户名/.config/woongaksi/config.yaml
Restart=on-failure
RestartSec=10
# 关键：在这里直接设置环境变量，比.env文件更安全
Environment="NOTION_API_KEY=secret_YOUR_ACTUAL_TOKEN"
Environment="TELEGRAM_BOT_TOKEN=YOUR_ACTUAL_BOT_TOKEN"
Environment="TELEGRAM_CHAT_ID=YOUR_ACTUAL_CHAT_ID"
WorkingDirectory=/home/你的用户名/.cache/woongaksi
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

然后启用并启动服务：

# 重新加载systemd配置
systemctl --user daemon-reload

# 设置开机自启
systemctl --user enable woongaksi

# 立即启动服务
systemctl --user start woongaksi

# 查看服务状态和日志
systemctl --user status woongaksi
journalctl --user -u woongaksi -f  # 实时跟踪日志

4. 与AI智能体的深度集成策略

仅仅让Woongaksi发送通知和让AI接收通知是不够的。要让AI“聪明地”利用这些信息，需要在其“大脑”（系统提示词）中植入明确的规则。以下是一个针对OpenClaw或类似AI智能体的系统提示词补充模块示例，你可以将其整合到你的 SOUL.md 或角色设定文件中。

## 🛠️ 外部系统集成与数据可信度协议

### Notion状态更新协议 (Woongaksi Relay)
1.  **信号识别**：本聊天中，由特定Telegram Bot（用户名可能为 `@xxx_notion_bot`）发出的、以特定图标（如 📋, 💡, 🚀）开头的格式化消息，是来自“Woongaksi”守护进程的官方通知。
2.  **数据权威性**：该通知代表Notion数据库中的**真实、实时（延迟<5分钟）变更**。其内容（如任务状态变更、属性更新）应被视为比任何内部缓存或记忆更高级别的可信数据源。
3.  **自动认知更新**：
    *   收到此类通知后，应立即在内部更新对相关任务或项目的认知。
    *   例如，收到“📋 任务‘产品评审’的状态从 [待开始] 变更为 [进行中]”，则后续所有关于“产品评审”任务的讨论，都应基于其“正在进行”的状态进行。
4.  **API调用抑制**：对于近期（例如过去1小时内）已通过Woongaksi通知更新过的项目，当用户询问其状态时，**禁止**为此目的再次调用Notion API查询。应直接引用通知中的最新信息。仅在用户明确要求“重新从Notion同步”或信息存在矛盾时，才执行API查询。

### 信息源优先级
1.  **最高优先级 - 实时中继**：Woongaksi的Telegram通知。
2.  **高优先级 - 用户直接陈述**：用户在对话中明确说明的信息。
3.  **中优先级 - 主动API查询**：通过工具调用从Notion等系统获取的信息（注意时效性）。
4.  **低优先级 - 长期记忆**：向量数据库或会话历史中存储的旧信息。当与更高优先级来源冲突时，必须被覆盖。

### 响应话术指引
*   **当基于Woongaksi通知回答时**，可以自然引用：“根据刚才收到的更新，那个任务已经显示为完成了...”
*   **当用户询问的状态刚被更新过**，应自信回答，无需提及“让我查一下”的延迟过程。

这段提示词的核心是建立AI的“行为准则”，让它学会信任并优先使用Woongaksi提供的流式更新，从而将昂贵的API调用从默认路径变为备用路径。

5. 高级配置、问题排查与优化经验

5.1 支持与扩展：处理复杂的Notion属性

Woongaksi默认支持Notion中常见的属性类型。了解其处理逻辑有助于你配置 tracked_properties 。

• 基础类型 ： title , rich_text , number , checkbox , url , date 等。它们的值变化会被直接比较。
• 选择类型 ： select （单选）、 multi_select （多选）、 status （状态）。比较其选项名称。
• 人员与关联 ： people , relation 。通常比较的是关联对象的ID或名称列表。需注意，如果关联的数据库条目名称改变，也可能触发变更检测。
• 公式与汇总 ： formula , rollup 。这些是只读属性，其值由Notion自动计算。监控它们可以捕获基于其他属性变化而产生的衍生变化，非常有用。

实操技巧 ：对于 date 类型，如果你只关心日期部分，而Notion API返回的是包含时间的ISO字符串，可能会导致时间部分的微小差异（如秒级不同）被误判为变更。一个稳健的做法是在计算哈希前，对日期值进行标准化处理（例如，只取“YYYY-MM-DD”部分），这可能需要你稍微修改Woongaksi的代码逻辑。

5.2 常见问题与排查清单

在部署和运行过程中，你可能会遇到以下典型问题：

现象	可能原因	排查与解决步骤
启动失败，报错 403 Forbidden	1. Notion集成未连接到目标数据库。 2. 数据库ID错误。	1. 进入Notion数据库页面，通过 ··· -> Connections 确认并添加集成。 2. 仔细核对 config.yaml 中的数据库ID，确保是从URL中正确复制的32位字符。
启动失败，报错 401 Unauthorized	Notion API令牌无效或格式错误。	1. 检查 .env 文件中的 NOTION_API_KEY ，确保是完整的以 secret_ 开头的令牌。 2. 令牌可能已失效，去Notion集成页面重新复制或生成一个新令牌。
程序运行但收不到Telegram通知	1. 数据确实无变更。 2. Telegram Bot令牌或Chat ID错误。 3. Bot未被添加到目标聊天。 4. 缓存文件导致首次运行无通知。	1. 确认Notion中已修改被追踪的属性。 2. 使用 curl 测试Bot： curl -X POST https://api.telegram.org/bot<TOKEN>/sendMessage -d "chat_id=<CHAT_ID>&text=Test" 。 3. 将Bot拉入群组或发起私聊。 4. 首次运行是“缓存播种”期，不会发通知 ，这是正常行为。修改后等待 第二个 轮询周期。
收到重复的变更通知	本地缓存文件损坏或不同步。	1. 停止Woongaksi服务。 2. 删除缓存目录（默认可能是 ./cache 或 ~/.cache/woongaksi ）下对应的 .json 缓存文件。 3. 重启服务，它会重新建立缓存基线。
通知格式混乱或属性名显示为内部ID	config.yaml 中的 title_property 或 tracked_properties 名称与Notion中不匹配。	1. 在Notion中，进入数据库视图，点击任一属性列标题，选择“属性”，查看其 精确的名称 。 2. 确保 config.yaml 中的名称与之完全一致（英文注意大小写，中文注意空格）。
轮询导致Notion API速率限制	监控的数据库条目过多或轮询间隔太短。	1. 充分利用 filter 配置，减少每次API调用返回的数据量。 2. 适当增加 poll_interval_minutes ，例如从5分钟调整为10分钟。 3. Notion API有速率限制，如果监控多个大型数据库，需错开它们的轮询时间（这可能需要修改代码）。

5.3 性能优化与安全建议

• 精细化监控 ：只追踪真正必要的属性（ tracked_properties ）和必要的行（ filter ）。这是减少数据处理量和网络传输的最有效方法。
• 缓存目录持久化 ：如果你使用Docker或经常重启服务器，请确保 WOONGAKSI_CACHE 指向的目录是一个持久化存储卷。否则缓存丢失会导致重启后误报大量“变更”。
• 密钥管理 ：生产环境中，绝对不要将 NOTION_API_KEY 等密钥提交到版本控制系统（如Git）。 .env 文件应被加入 .gitignore 。使用systemd服务的 Environment 指令、服务器环境变量或专业的密钥管理工具（如HashiCorp Vault、AWS Secrets Manager）来存储密钥。
• 日志与监控 ：配置日志轮转（logrotate），避免日志文件无限增大。对于systemd服务，可以使用 journalctl 进行日志查看和监控。考虑添加简单的健康检查，例如监控日志中是否出现连续的错误信息。
• 错误处理与重试 ：一个健壮的守护进程应该能处理网络临时中断、API暂时不可用等情况。检查Woongaksi的代码是否实现了网络请求的重试机制和指数退避策略。如果没有，你可能需要自己添加或用 supervisor 等进程管理工具来保证其持续运行。

6. 扩展思路与应用场景

Woongaksi的基础模式“监控变更 -> 通知消息 -> 更新认知”可以扩展到许多其他场景。

1. 多AI智能体协同 ：你可以让多个专注于不同领域的AI智能体（如一个负责设计任务，一个负责代码任务）都加入同一个Telegram群组。Woongaksi关于任务分配的更新可以同时被所有AI感知，便于它们进行跨职能协作。

2. 触发下游自动化 ：除了通知AI，你还可以扩展Woongaksi，使其在检测到特定变更时触发其他自动化工作流。例如，当某个任务状态变为“待测试”时，自动在GitHub创建Issue、在Slack测试频道发送提醒，或者触发一个CI/CD管道。

3. 状态仪表板 ：将Woongaksi发送到Telegram的消息同时转发到一个专用的看板频道，或者通过Telegram Bot API将这些变更写入一个简单的数据库（如SQLite），再配上一个轻量级Web界面，就能形成一个实时的项目状态仪表板。

4. 与更多工具集成 ：其核心逻辑并不绑定于Telegram。你可以修改通知模块，将变更发送到Slack、Discord、Microsoft Teams，甚至是WebSocket服务器，以适应你团队现有的通信生态。

这个项目的精髓在于它用一种极其简单、低耦合的方式，解决了AI智能体与外部动态数据源同步的核心难题。它不试图重塑整个工作流，而是巧妙地嵌入其中，做一个安静的、高效的“桥梁”。