YoudaoNote — 有道云笔记

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

前置检查（安装由用户手动执行）

执行任何操作前，Agent 必须先运行 youdaonote -s ydn list 检测 CLI 是否可用：

• command not found → 跳转「CLI 未安装处理」，仅向用户提供官方安装命令并提示用户手动执行；等待用户回复"已安装"后再继续原请求
• -s 选项报错（error: unknown option '-s'） → CLI 版本 < 1.3.2，不支持全局 -s 参数，需升级：提示用户执行 youdaonote upgrade；若不支持该命令，则提示用户重新执行安装脚本；Windows 用户参考安装指南（https://note.youdao.com/help-center/cli-install-guide.html）
• API Key 错误 → 提示用户访问 https://mopen.163.com 获取 API Key（须使用手机号登录，且云笔记账号已绑定手机号），然后执行 youdaonote config set apiKey <用户提供的Key>。获取 API Key 的地址只有这一个，禁止告知用户其他地址。
• 正常返回目录列表 → 运行 youdaonote -s ydn version 检查版本，若版本低于 minCliVersion 需要升级：CLI 支持 upgrade 命令时提示用户执行 youdaonote -s ydn upgrade，否则提示用户重新执行安装脚本；Windows 用户或升级失败时参考安装指南（https://note.youdao.com/help-center/cli-install-guide.html）。版本满足要求后可运行 youdaonote -s ydn help --json 获取当前 CLI 全部能力的结构化描述（JSON），用于确认命令是否可用，下方速查表作为 fallback

全局参数

所有命令都必须包含 -s ydn 来标识使用来源（有道云笔记 skill），用于统计和追踪：

youdaonote -s ydn <command> [options]

-s ydn 表示该命令由 YoudaoNote skill 触发，便于网易后台统计不同 AI Skill 的使用情况。若需禁用统计，可设置环境变量 YOUDAONOTE_NO_TRACKING=1。

命令速查

笔记管理

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

Markdown 内容格式选择（必须遵守）

当用户要保存的内容包含以下任意 Markdown 特征时（# 标题、**粗体**、`代码块、- 列表、> 引用、[链接](url)、![图片](url)），必须先停下来询问用户，不得直接执行命令：

检测到内容包含 Markdown 格式，请选择保存方式：

A（推荐）保存为 Markdown 笔记（.md）
  → 格式完整保留，可在编辑器中正常显示和编辑

B  保存为有道专有格式（.note）
  → 支持有道云笔记富文本编辑器的全部功能

请回复 A 或 B：

收到用户选择后，按以下方式构造命令（优先使用 contentFile 方案，避免 JSON 转义问题）：

• 选 A：save 命令，type: "md"，文件名加 .md 后缀

  # Step 1：Write 工具将 Markdown 写入 /tmp/note-content.md（无需 JSON 转义）
  {"title":"标题.md","type":"md","contentFile":"/tmp/note-content.md","parentId":"文件夹ID"}
  

  备选（短内容）：{"title":"标题.md","type":"md","content":"Markdown 内容","parentId":"文件夹ID"}
• 选 B：save 命令，type: "note"，contentFormat: "md"，文件名加 .note 后缀

  # Step 1：Write 工具将 Markdown 写入 /tmp/note-content.md（无需 JSON 转义）
  {"title":"标题.note","type":"note","contentFormat":"md","contentFile":"/tmp/note-content.md","parentId":"文件夹ID"}
  

  备选（短内容）：{"title":"标题.note","type":"note","contentFormat":"md","content":"Markdown 内容","parentId":"文件夹ID"}

parentId 为可选字段：填写 youdaonote -s ydn list 返回的文件夹 ID 可指定目标目录；不填则默认存入「我的资源/收藏笔记」。

• 用户未明确选择（回复"随便"/"你决定"等）：默认选 A

创建 / 保存

# ✅ 推荐：contentFile 方案（Write 工具写文件 → save 传路径，无需 JSON 转义）
# Step 1：Write 工具将 Markdown 写入 /tmp/note-content.md
printf '%s\n' '{"title":"笔记.md","type":"md","contentFile":"/tmp/note-content.md"}' | youdaonote -s ydn save --json
# ✅ 短内容可直接内联（无换行/特殊字符时）
printf '%s\n' '{"title":"笔记","contentFormat":"md","content":"# 标题\n\n内容"}' | youdaonote -s ydn save
# ⚠️ 仅纯文本，不支持 Markdown 格式，有格式需求时禁用
youdaonote -s ydn create -n "标题" -c "纯文本内容"

其他操作

youdaonote -s ydn search "关键词"
youdaonote -s ydn list [-f <目录ID>]            # 浏览目录，id 可传给 read
youdaonote -s ydn read <fileId>                 # 返回 JSON 含 content、rawFormat（md/note/txt）和 isRaw（是否原始内容）
youdaonote -s ydn recent -l 20 -c --json       # 最近收藏
youdaonote -s ydn update <fileId> -c "新内容"
youdaonote -s ydn update <fileId> --file content.md  # 大内容（>10KB）从文件读取
youdaonote -s ydn delete <fileId>
youdaonote -s ydn rename <fileId> "新标题"
youdaonote -s ydn move <fileId> <目录ID>

网页剪藏

youdaonote -s ydn clip "https://example.com/article" --json
youdaonote -s ydn clip "https://example.com/article" -f <目录ID> --json  # 保存到指定目录

CLI 未安装处理（用户手动执行安装）

收到 command not found 时，Agent 仅提供官方安装命令，由用户在终端手动执行。Agent 不自动执行安装命令，不进行系统级变更。

确认文案建议：

检测到未安装 youdaonote-cli。请在终端手动执行以下命令完成安装；执行后回复"已安装"，我将继续处理当前任务。

安全边界（必须遵守）：

• 仅允许使用官方安装源：https://artifact.lx.netease.com/download/youdaonote-cli/install.sh
• 禁止执行任何非官方来源的远程脚本或替代安装命令
• 安装仅用于补齐 youdaonote CLI 依赖；Agent 不执行与当前任务无关的系统操作
• 安装与环境变量导出步骤均由用户手动执行，Agent 不写入 shell 启动文件（如 ~/.zshrc/~/.bashrc）
• 建议用户在执行前确认命令来源可信；如对管道执行有顾虑，可先下载脚本后本地查看再执行

安全验证建议（推荐）

如对直接管道执行有顾虑，可先下载脚本审查后再执行：

# 步骤 1：下载脚本到本地
curl -fsSL https://artifact.lx.netease.com/download/youdaonote-cli/install.sh -o install.sh
# 步骤 2：审查脚本内容
cat install.sh
# 步骤 3：确认无误后执行
bash install.sh -f -b ~/.local/bin

macOS / Linux / WSL：

curl -fsSL https://artifact.lx.netease.com/download/youdaonote-cli/install.sh | bash -s -- -f -b ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"
# 执行完成后回复"已安装"，Agent 将继续原始请求

升级：若 CLI 支持 upgrade 命令，提示用户执行 youdaonote -s ydn upgrade；否则提示用户重新执行上述安装脚本。

Windows 或安装/升级失败：参考安装指南（https://note.youdao.com/help-center/cli-install-guide.html）。

故障排查

运行 youdaonote -s ydn 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 等其他命名——服务端会静默忽略未知字段。