|最后更新: Invalid Date

创建 Skill：WeRead Notion Sync

你现在要帮我在当前 AI 工具中创建一个可复用的 skill 文件夹，而不是直接帮我执行这次同步任务。
这个 skill 的目标是：让用户把微信读书 / WeRead 的书架、划线、想法和书评同步到用户自己的 Notion 书籍系统中。每个用户的 Notion 页面结构都不一样，所以安装时必须先确认和映射数据库结构，不能硬编码我的页面 ID、数据库 ID、字段名、API key 或本机路径。
请按下面流程创建真实的 skill 文件夹和文件。

一、创建前向我收集配置

先用问答形式向我提问，不要用选择题、按钮式选项或 A/B/C/D 选择卡。可以给参考回答示例，但必须让我自然语言回答。
请一次性问完下面这些问题：
  1. 请粘贴你的 Notion 书架数据库、书架模板页面，或包含书架数据库的 Notion 页面链接。
      2. 如果不确定哪个是数据库，直接贴你平时记录书的那个页面链接即可。
  1. 你的摘录准备放在哪里？
      2. 请说明：已有摘录数据库链接 / 希望自动创建摘录数据库 / 希望写进每本书页面正文。
  1. 你的 Notion 里是否已经有“阅读状态”字段？
      2. 如果有，请告诉我表示“正在读”和“读完了”的选项名称；如果没有，可以说“没有”。
  1. 你是否希望同步书籍封面？
      2. 可以回答：同步封面 / 不同步封面 / 不确定先默认同步。
  1. 你希望默认同步范围是什么？
      2. 可以回答：全书架 / 只同步有笔记的书 / 每次指定书 / 只同步书籍不导入摘录。
  1. 是否允许安装流程在 Notion 数据库里新增必要字段？
      2. 如果允许，安装 AI 必须先列出缺失字段和用途，等我确认后再新增。
  1. WeRead API Key 请不要直接贴给我。
      2. 请确认是否同意安装 AI 引导你把它存进当前电脑系统支持的安全凭证库，并在 skill 中只记录凭证库类型、service/account 名称或安全读取方式。
如果用户没有回答全部问题，优先用安全默认值继续：
  • skill 名称默认：weread-notion-sync
  • 默认同步范围：全书架 + 可导出的摘录
  • 默认同步封面：同步
  • 默认使用独立摘录数据库；如果用户没有摘录数据库，则先只同步书籍，并提示后续可配置摘录库
  • 默认不自动新增字段；必须先展示缺失字段并确认
  • 默认凭证 service：weread-api
  • 默认凭证 account：default
安装 AI 还必须先做依赖预检：
  • 检查 Notion CLI：运行 command -v ntn 和 ntn doctor。
  • 如果没有安装 Notion CLI，先告诉用户将安装 Notion CLI，然后运行官方安装命令：
  • 安装后再次运行 ntn doctor；如果没有登录，引导用户运行 ntn login。
  • 检查当前 AI 环境是否已经有微信读书 skill。
  • 不要假设用户使用 Codex，也不要只搜索 ~/.codex/skills 这类 Codex 专属目录。
  • 如果没有微信读书 skill，或无法确认是否已安装，直接运行：
  • 安装后重新检查微信读书 skill 是否可用；如果当前工具需要重启才能加载新 skill，明确告诉用户重启。
  • 安装完成后，必须自动检测用户系统，选择安全凭证存储方式，引导用户配置 WeRead API key，并用只读 /shelf/sync 做连通性检查。
凭证存储规则：
  • macOS：使用系统 Keychain。
  • Windows：优先使用 Windows Credential Manager；可通过 PowerShell SecretManagement / CredentialManager 模块写入和读取。
  • Linux：优先使用 Secret Service / pass / 当前桌面环境支持的安全凭证库。
  • 如果当前系统没有可用安全凭证库，必须先向用户说明风险，并征得同意后才允许使用环境变量作为 fallback。
  • 不要把 API key 写进 SKILL.md、脚本、配置文件、日志或安装 prompt。

二、收到回答后，先整理配置映射

收到用户回答后，先输出一份配置映射，不要立刻写文件。
必须按下面四类整理：

A 类：固定不问，直接写死

  • 使用 WeRead API 的书架、划线、想法接口
  • 用 WeRead bookId 作为书籍去重主键
  • 用 WeRead bookmarkId / reviewId 作为摘录去重主键
  • 默认支持 dry-run
  • 默认不把“微信读书”写入主题标签
  • 默认不导入不可导出的书签内容

B 类：简单偏好

  • skill 文件夹名称
  • 默认同步范围
  • 是否同步封面
  • 阅读状态选项映射
  • 摘录保存方式

C 类：需要查找或操作

  • Notion 书架页面 / 数据库链接
  • Notion 书籍数据库 data source ID
  • Notion 摘录数据库 data source ID
  • 书籍库字段映射
  • 摘录库字段映射
  • 是否允许新增缺失字段
  • 微信读书 skill 安装是自动依赖预检，不作为安装问题；未安装时固定使用 npx skills add Tencent/WeChatReading -g

D 类：敏感凭证

  • WeRead API Key
绝对不要让用户把 API key 明文写进 skill 文件、prompt、配置文件或聊天记录保存区。只记录安全读取方式，例如 credential backend、service/account、环境变量名（仅 fallback）。
整理配置映射后，继续执行下面步骤。

三、创建文件结构

在当前 AI 工具支持的 skill 目录中创建 skill。若用户使用 Codex，默认路径：
创建这些文件：
安装时可在同一目录创建用户本地配置：
config.local.json 可以包含用户自己的 Notion database/data source ID、字段映射、状态映射、凭证读取方式、service/account，但绝不能包含 API key 明文。
如果用户当前 AI 工具支持 skill-creator 的初始化脚本，优先用初始化脚本创建目录；否则手动创建上述结构。

四、SKILL.md Frontmatter

写入 SKILL.md 的 frontmatter：

五、写入 SKILL.md 正文

写入前，把第三节、第四节、以及下方正文 ## Configuration 章节中所有 {{变量名}} 占位符，统一替换为第二节整理出的实际值。替换完成后，正文中不应存在任何剩余的 {{}} 占位符。

六、创建脚本与配置文件

创建 config.example.json：
创建 scripts/sync-weread-notion.js，实现以下行为：
  • 读取 config.local.json
  • 支持 -setup
  • 支持 -dry-run
  • 支持 -books-only
  • 支持 -notes-only
  • 支持 -book-id=<id>
  • 从配置的安全凭证库读取 WeRead API key；只有用户明确接受 fallback 时才读取环境变量
  • 调用 WeRead API：
    • /shelf/sync
    • /book/bookmarklist
    • /review/list/mine
  • 调用 Notion CLI：
    • 始终通过 env -u NOTION_API_TOKEN ntn ...
    • 查询 data source
    • 创建/更新页面
    • 必要时读取 schema
  • 输出 JSON summary，至少包含：
    • dryRun
    • scope
    • books.create
    • books.update
    • notes.create
    • notes.update
    • blocked
    • errors
脚本必须有防御逻辑：
  • 如果 ntn 不存在，输出明确错误并提示安装命令。
  • 如果 ntn doctor 失败，输出 Notion CLI 登录/权限排查建议。
  • 如果微信读书 skill 缺失，setup 必须运行 npx skills add Tencent/WeChatReading -g。
  • 如果安装后当前 AI 工具需要重启才能加载 skill，输出明确提示并停止后续同步。
  • 如果 /shelf/sync 无法连通，输出明确错误并提示检查 API key / 网络 / API 权限。
  • schema 缺字段时，普通同步失败并说明字段名
  • setup 模式下才允许提出补字段方案
  • 没有摘录数据库时，不要强行创建；先按用户配置决定
  • Notion URL property 如果不接受 weread://，降级为普通书籍链接或跳过链接字段，并在 summary 中说明
  • 不输出 API key
  • 不把用户的 Notion token 写进日志

七、创建后检查并测试

创建完成后必须检查：
  1. 文件存在：
      • SKILL.md
      • agents/openai.yaml
      • scripts/sync-weread-notion.js
      • config.example.json
  1. 依赖预检：
      • ntn 存在
      • ntn doctor 可运行
      • 能找到微信读书 skill，或已运行 npx skills add Tencent/WeChatReading -g
      • 能读取微信读书 skill 的说明文档
      • 能通过 /shelf/sync 做只读连通性检查
      • WeRead API key 只保存在系统安全凭证管理器中；若使用环境变量 fallback，必须确认用户已明确同意
  1. 占位符残留：
      • 检查 {{ 和 }} 是否还出现在最终文件中
  1. 私人信息残留：
      • 不应有真实 API key
      • 不应有真实 token
      • 不应有安装者以外的 Notion database ID
      • 不应有本机绝对路径，除非是用户自己的配置文件路径
  1. 基础验证请求：
用户可以这样测试：
期望行为：
  • skill 先检查配置
  • 如果缺配置，进入 setup
  • 如果配置完整，运行 dry-run
  • 输出书籍和摘录的新增/更新数量
  • 不写入 Notion
  1. 写入验证请求：
期望行为：
  • 读取配置
  • 同步书籍
  • 同步可导出的摘录
  • 关联摘录到书籍
  • 输出 created/updated/blocked summary
最后告诉用户：
  • skill 文件夹位置
  • 创建了哪些文件
  • 如何按当前系统配置 WeRead API Key 的安全读取方式
  • 如何触发 dry-run
  • 如何执行真实同步
Loading...