Skip to main content

YoudaoNote — 有道云笔记

通过 youdaonote CLI 操作有道云笔记。覆盖笔记 CRUD、待办管理、网页剪藏全场景。

初始化(必须首先执行)

  1. 读取同目录下的 SETUP_TOKEN.md
  2. <SCRIPT_PATH> 替换为本文件所在目录的绝对路径
  3. 每次会话开始时,自动获取并配置 API Key:
    • Windows PowerShell:
  4. 若脚本报错,提示用户在应用内集成面板中完成有道云笔记授权(不要引导用户手动去 mopen.163.com 获取 Key)

前置条件(Agent 自动处理)

执行任何操作前,Agent 必须先运行 youdaonote list 检测 CLI 是否可用:
  • command not found → 立即跳转「CLI 未安装处理」自动安装,禁止只展示安装步骤让用户手动操作
  • API Key 错误 → 先尝试通过 get-token.sh 自动获取(见上方初始化步骤)。若自动获取也失败,提示用户在应用内集成面板中输入 API Key。API Key 获取地址:https://mopen.163.com**(须使用手机号登录,且云笔记账号已绑定手机号)。**获取 API Key 的地址只有这一个,禁止告知用户其他地址。
  • 正常返回目录列表 → 运行 youdaonote version,若版本低于 1.2.0,展示升级建议后继续执行;否则可运行 youdaonote help --json 获取当前 CLI 全部能力的结构化描述(JSON),用于确认命令是否可用,下方速查表作为 fallback

命令速查

笔记管理

默认创建方式:所有笔记一律使用 save 命令 + contentFormat: "md" 保存为 Markdown 富文本。 禁止使用 create 命令保存包含 Markdown 格式的内容(标题、列表、代码块、表格等)—— create 仅支持纯文本,会静默丢失所有格式。HTML/结构化数据先转 Markdown 再用 save 保存。

Markdown 内容格式选择(必须遵守)

当用户要保存的内容包含以下任意 Markdown 特征时(# 标题、**粗体**`代码块、- 列表、> 引用、链接图片),必须先停下来询问用户,不得直接执行命令:
收到用户选择后,按以下方式构造命令:
  • 选 Asave 命令,type: "md",文件名加 .md 后缀
  • 选 Bsave 命令,type: "note"contentFormat: "md",文件名加 .note 后缀
parentId 为可选字段:填写 youdaonote list 返回的文件夹 ID 可指定目标目录;不填则默认存入「我的资源/收藏笔记」。
  • 用户未明确选择(回复”随便”/“你决定”等):默认选 A

创建 / 保存

其他操作

网页剪藏

CLI 未安装处理(Agent 必须自动执行)

收到 command not found 时,Agent 立即执行安装命令,禁止只展示步骤让用户操作。 macOS / Linux / WSL
Windows(CMD/PowerShell):不支持一键安装,告知用户下载预编译包:

故障排查

运行 youdaonote check --json,根据 status: "fail" 的项执行:

注意事项

  • 所有命令支持 --json 输出机器可解析格式
  • 大内容通过 --file 传递,避免命令行参数限制
  • Windows CMD 中 URL 含 & 时必须用双引号括起
  • list 输出的 idreadfileId 等价
  • read 返回的 rawFormat 标识笔记原始格式:md=Markdown、note=云笔记、txt=纯文本;isRaw 标识返回的 content 是否为原始内容(true=原文可直接编辑,false=经过转换的纯文本)
  • 禁止用 create 保存 Markdown 内容create 不支持 contentFormat,即使内容含 Markdown 语法也会存为纯文本静默丢失格式,有格式需求时一律使用 save 并指定 contentFormat: "md"
  • save 命令通过 JSON 的 parentId 字段指定目标文件夹(值来自 list 返回的文件夹 ID);不传则默认存到「我的资源/收藏笔记」。禁止使用 folderId 等其他命名——服务端会静默忽略未知字段。
  • UTF-8 编码:见下方「⚠️ UTF-8 编码强制要求」章节。所有写入操作前必须完成 UTF-8 编码校验,否则会导致笔记内容乱码且无法修复。
  • PowerShell 5.1 环境:见下方「⚠️ PowerShell 5.1 环境检测」章节。此问题影响所有写入类命令,PowerShell 5.1 会静默将内容转为 GBK 编码导致乱码。

⚠️ UTF-8 编码强制要求(CRITICAL)

此规则为强制性要求,不可跳过。 非法编码会导致笔记在有道云笔记中显示为乱码,且无法修复,必须重新写入。
每次调用写入类命令(savecreateupdateclip-savetodo createtodo update)之前,必须对标题、内容等所有字符串字段执行 UTF-8 编码校验/转换。 无论内容来源如何——用户直接输入、从文件读取、WebFetch 抓取、剪贴板粘贴、外部 API 返回——都不能假设已经是合法 UTF-8,必须显式确认。

强制检查清单(写入前)

在构造写入内容之前,完成以下步骤:
  1. 来自文件的内容:先检测文件编码,转为 UTF-8 后再读入变量
  2. 来自 WebFetch / HTTP 请求的内容:响应可能为 GBK/Latin-1 等,必须转码
  3. 来自用户输入或变量拼接的内容:清洗非法 UTF-8 字节(\xff\xfe 等)
  4. 标题字段同理:笔记标题、待办标题也必须为合法 UTF-8

各环境转码方法

Python(推荐,几乎所有环境都有):
Node.js:
Unix (macOS/Linux):
Windows PowerShell:

⚠️ PowerShell 5.1 环境检测(CRITICAL)

此问题极其隐蔽:PowerShell 5.1 下,命令行参数中的中文字符可能被静默转为系统 ANSI 编码(中文 Windows 为 GBK),导致 CLI 收到的内容已是乱码。
当 agent 运行在 PowerShell 环境时,必须在首次写入操作前检测版本:
PowerShell 5.1 下写入中文内容时,优先通过 --file 传递 UTF-8 编码的文件,避免命令行参数的编码损坏:
总结: 在 PowerShell 5.1 环境中,中文内容必须通过 UTF-8 编码的文件传入 CLI,而非直接放在命令行参数中。不检测版本直接传中文参数 = 内容必乱码。这是 PowerShell 5.1 的已知设计缺陷,不是 bug 可以被修复。