OpenClaw Notcrawl Skill:以本地 Notion 归档为优先的 Agent 检索实战指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文以 OpenClaw 仓库中的 notcrawl Skill 定义 为主体拆解归档优先archive-first这一工作模式如何落地Skill 的 frontmatter 如何声明二进制依赖与 Go 安装来源doctor/status/sync/search/sql各命令在什么时机使用以及为什么必须限制只读 SQL、不得默认 Notion API token 可用。读完本文你能理解 notcrawl 在 OpenClaw Agent 技能体系中的定位并复现一套先查本地归档、再考虑在线 API的 Notion 数据检索流程。一、Notcrawl 是什么为 Agent 提供的本地 Notion 归档入口notcrawl SKILL.md 位于.agents/skills/目录下是 OpenClaw 的项目级 Agent 技能。它教给 Agent 的核心纪律只有一句话在处理最近/当前类问题之前先使用本地 Notion 归档数据而不是直接去浏览网页或调用在线 Notion API原文Use local Notion archive data before browsing or live Notion API calls。在 OpenClaw 的技能加载体系中这一定位有明确的机制支撑。docs/tools/skills.md 给出的加载优先级表显示优先级来源路径1 — 最高Workspace skillsworkspace/skills2Project agent skillsworkspace/.agents/skills3Personal agent skills~/.agents/skills仅默认 state4Managed / local skillsstate-dir/skills5Bundled skills随安装包分发6 — 最低Extra directoriesskills.load.extraDirs 插件技能notcrawl 放在workspace/.agents/skills/notcrawl/即优先级表中的第 2 档Project agent skills它只对当前工作区的 Agent 生效且同名技能会被更高优先级的来源覆盖。技能目录支持分组布局只要SKILL.md出现在某个技能根目录下最多 6 层深即可被发现技能名与斜杠命令取自 frontmatter 的name字段——notcrawl 的name: notcrawl因此同时是技能名和 Agent 可引用的$notcrawl命令名。二、Frontmatter 元数据依赖声明与安装来源SKILL.md 顶部的 YAML frontmatter 定义了技能何时可被激活、如何补齐依赖--- name: notcrawl description: Notion archive: search, sync freshness, pages/databases, Markdown exports, SQL counts, and Notcrawl repo work. metadata: openclaw: homepage: https://github.com/openclaw/notcrawl requires: bins: - notcrawl install: - kind: go module: github.com/vincentkoc/notcrawl/cmd/notcrawllatest bins: - notcrawl ---结合 docs/tools/skills.md 对metadata.openclaw的说明可以逐项解读requires.bins: [notcrawl]技能在加载期按二进制是否存在过滤。系统上找不到notcrawl可执行文件时该技能不会被注入当前 Agent 的提示词从而避免 Agent 引用一个无法运行的工具。这是 OpenClaw 技能门控gating机制的标准写法与requires.env、requires.config等条件属于同一族install段声明了可选的安装器规格kind: go表示通过go install安装 Go 模块github.com/vincentkoc/notcrawl/cmd/notcrawllatest安装后应产出notcrawl二进制。该规格主要供 macOS Skills UI 使用brew / node / go / uv / download 几种 kind让界面能按声明的来源自动补齐依赖description浓缩了技能的六大能力面——搜索、同步新鲜度、页面/数据库查询、Markdown 导出、SQL 计数以及对 Notcrawl 仓库本身的操作。Agent 依据这段描述判断何时选用该技能。技能目录下还有一份配套的 Agent 接口配置 agents/openai.yaml给出了技能的展示名与默认提示词interface: display_name: Notcrawl short_description: Search local Notion archives and freshness default_prompt: Use $notcrawl to search local Notion pages and databases, check freshness, inspect exports, and report exact date spans and source gaps.其中$notcrawl即引用该技能的斜杠命令形式default_prompt强调了两个报告要求精确的日期跨度exact date spans与来源缺口source gaps——这与 SKILL.md 正文的汇报纪律完全一致。三、Archive-First 工作流三个阶段的命令序列SKILL.md 正文给出了完整的操作时序按先验新鲜度、按需刷新、有界查询三阶段组织。阶段 1检查新鲜度再回答最近/当前类问题notcrawl doctor notcrawl status --json原文档明确要求在处理 recent/current 类问题之前先检查新鲜度Check freshness for recent/current questions。doctor用于诊断归档环境是否健康status --json输出机器可读的同步状态。从命令语义看这一步的价值在于Agent 在引用归档中的当前状态之前必须先拿到一个可审计的时间基准——否则本地快照与线上 Notion 的偏差范围无从交代。阶段 2仅在过期或被要求时刷新notcrawl sync --source desktop notcrawl sync --source api原文档的措辞是Refresh only when stale or asked——同步是受控动作而非每轮对话的默认步骤。两个--source对应两条数据来源--source desktop从 Notion 桌面端本地数据同步零 token 成本依赖桌面端缓存的导出/数据--source api走 Notion API 同步。原文档特别警告API 模式要求NOTION_TOKEN且不得假设 token 一定存在API mode requiresNOTION_TOKEN; do not assume token availability。也就是说Agent 在选用 api 源之前应先探测该环境变量缺失时应回退到 desktop 源或向操作者说明而不是编造一个 token。阶段 3以有界读取bounded reads做查询notcrawl search query notcrawl databases notcrawl report notcrawl sql select count(*) from pages;bounded reads的含义是查询应限定范围与返回量避免把整库内容倾倒进上下文。search做全文检索databases列出数据库report生成汇总报告sql则对归档做 SQLite 风格的只读查询——示例中的select count(*) from pages;说明归档底层至少存在pages这类可查询的表结构。四、汇报纪律与安全红线SKILL.md 最后两行是整份技能的合规条款值得单独强调报告必须交代边界汇报 workspace/teamspace 名称、页面/数据库标题、绝对日期跨度absolute date spans、记录计数以及已知缺口known gaps。日期用绝对值而非最近一周这类相对表述缺口必须明说——这让下游读者人或其他 Agent能判断结论的覆盖范围是归档查询区别于直接在线查询的关键可审计性来源。SQL 只读绝不改归档Use read-only SQL only; never mutate the archive.归档是只读数据源任何写操作都会破坏本地快照 某时刻事实这一前提。不假设凭证NOTION_TOKEN仅在 API 模式需要且不可假定存在——这条纪律防止 Agent 在未确认凭证的前提下发起必然失败的 API 调用或在报告中假装数据来自 API 同步。五、crawl 家族的设计范式从源码结构看notcrawl 并非孤例。.agents/skills/下还存在一组同范式的crawl技能各自对应一种数据源的本地归档技能归档对象对应 SKILL.mdgitcrawlGitHub issue/PR 归档.agents/skills/gitcrawl/SKILL.mdslacrawlSlack 消息归档.agents/skills/slacrawl/SKILL.mddiscrawlDiscord 归档.agents/skills/discrawl/SKILL.mdgraincrawl其他本地归档.agents/skills/graincrawl/SKILL.mdnotcrawlNotion 页面/数据库归档.agents/skills/notcrawl/SKILL.md这一家族的共性约定高度一致notcrawl 只是其中面向 Notion 的变体统一的命令面家族成员都以doctor/status起步检查新鲜度以search/sql等只读查询收尾。例如 gitcrawl SKILL.md 要求Use local GitHub issue/PR archives before live GitHub search并规定在做出评论、打标签、合并等变更性决策前必须切换到在线验证——notcrawl 的归档优先、变更不依赖归档与其一脉相承统一的安装声明均以requires.bins声明 CLI 依赖以kind: go声明 Go 模块安装来源统一的汇报口径均要求报告绝对日期、来源缺口禁止基于本地相似度的臆断直接驱动变更操作。对使用者而言这意味着掌握 notcrawl 的这套doctor → status → 按需sync → bounded query → 带边界的报告流程后迁移到同家族其他归档工具几乎没有额外成本。六、实践要点小结触发条件技能只有在本机存在notcrawl二进制时才会进入 Agent 的可用技能集requires.bins门控缺失时可按 frontmatter 中的 Go 模块声明安装时序不可颠倒先doctor/status --json确认新鲜度再决定sync --source desktop|api最后做search/databases/report/sql查询API 源有硬前提NOTION_TOKEN必须真实存在否则应改用 desktop 源或向操作者报告绝不默认 token 可用输出带边界任何报告都应包含 workspace/teamspace、标题、绝对日期跨度、计数与已知缺口红线SQL 只读、不改归档不基于本地归档数据单独做出线上变更决策。技能全文短小但信息密度高——frontmatter 定义能不能用正文定义怎么用、何时用、报什么两者共同构成 OpenClaw 中一个完整的 archive-first 技能样板。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考