YoudaoNote — 有道云笔记
通过youdaonote CLI 操作有道云笔记。覆盖笔记 CRUD、待办管理、网页剪藏全场景。
初始化(必须首先执行)
- 读取同目录下的
SETUP_TOKEN.md - 将
<SCRIPT_PATH>替换为本文件所在目录的绝对路径 - 每次会话开始时,自动获取并配置 API Key:
- Windows PowerShell:
- 若脚本报错,提示用户在应用内集成面板中完成有道云笔记授权(不要引导用户手动去 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 特征时(# 标题、**粗体**、`代码块、- 列表、> 引用、链接、图片),必须先停下来询问用户,不得直接执行命令:
- 选 A:
save命令,type: "md",文件名加.md后缀 - 选 B:
save命令,type: "note",contentFormat: "md",文件名加.note后缀
parentId为可选字段:填写youdaonote list返回的文件夹 ID 可指定目标目录;不填则默认存入「我的资源/收藏笔记」。
- 用户未明确选择(回复”随便”/“你决定”等):默认选 A
创建 / 保存
其他操作
网页剪藏
CLI 未安装处理(Agent 必须自动执行)
收到command not found 时,Agent 立即执行安装命令,禁止只展示步骤让用户操作。
macOS / Linux / WSL:
- x64:https://artifact.lx.netease.com/download/youdaonote-cli/youdaonote-cli-windows-x64.tar.gz
- ARM64:https://artifact.lx.netease.com/download/youdaonote-cli/youdaonote-cli-windows-arm64.tar.gz
故障排查
运行youdaonote check --json,根据 status: "fail" 的项执行:
注意事项
- 所有命令支持
--json输出机器可解析格式 - 大内容通过
--file传递,避免命令行参数限制 - Windows CMD 中 URL 含
&时必须用双引号括起 list输出的id与read的fileId等价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)
此规则为强制性要求,不可跳过。 非法编码会导致笔记在有道云笔记中显示为乱码,且无法修复,必须重新写入。每次调用写入类命令(
save、create、update、clip-save、todo create、todo update)之前,必须对标题、内容等所有字符串字段执行 UTF-8 编码校验/转换。 无论内容来源如何——用户直接输入、从文件读取、WebFetch 抓取、剪贴板粘贴、外部 API 返回——都不能假设已经是合法 UTF-8,必须显式确认。
强制检查清单(写入前)
在构造写入内容之前,完成以下步骤:- 来自文件的内容:先检测文件编码,转为 UTF-8 后再读入变量
- 来自 WebFetch / HTTP 请求的内容:响应可能为 GBK/Latin-1 等,必须转码
- 来自用户输入或变量拼接的内容:清洗非法 UTF-8 字节(
\xff\xfe等) - 标题字段同理:笔记标题、待办标题也必须为合法 UTF-8
各环境转码方法
Python(推荐,几乎所有环境都有):⚠️ PowerShell 5.1 环境检测(CRITICAL)
此问题极其隐蔽:PowerShell 5.1 下,命令行参数中的中文字符可能被静默转为系统 ANSI 编码(中文 Windows 为 GBK),导致 CLI 收到的内容已是乱码。当 agent 运行在 PowerShell 环境时,必须在首次写入操作前检测版本:
--file 传递 UTF-8 编码的文件,避免命令行参数的编码损坏:
总结: 在 PowerShell 5.1 环境中,中文内容必须通过 UTF-8 编码的文件传入 CLI,而非直接放在命令行参数中。不检测版本直接传中文参数 = 内容必乱码。这是 PowerShell 5.1 的已知设计缺陷,不是 bug 可以被修复。