YoudaoNote — 有道云笔记

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

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

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

• - command not found → 跳转「CLI 未安装处理」，仅向用户提供官方安装命令并提示用户手动执行；等待用户回复“已安装”后再继续原请求
• API Key 错误 → 提示用户访问 https://mopen.163.com 获取 API Key（须使用手机号登录，且云笔记账号已绑定手机号），然后执行 youdaonote config set apiKey <用户提供的Key>。获取 API Key 的地址只有这一个，禁止告知用户其他地址。
• 正常返回目录列表 → 运行 youdaonote version，若版本低于 1.2.0，展示升级建议后继续执行；否则可运行 youdaonote help --json 获取当前 CLI 全部能力的结构化描述（JSON），用于确认命令是否可用，下方速查表作为 fallback

命令速查

命令	用途	示例
INLINECODE7	保存笔记（✅ 推荐，支持 Markdown 富文本）	INLINECODE8
INLINECODE9

创建笔记（⚠️ 仅纯文本，不支持 Markdown 富文本） | youdaonote create -n "标题" -c "内容" [-f <目录ID>] | | update | 更新 Markdown 笔记 | youdaonote update <fileId> -c "内容" 或 --file content.md | | delete | 删除笔记 | youdaonote delete <fileId> | | rename | 重命名笔记 | youdaonote rename <fileId> "新标题" | | move | 移动笔记 | youdaonote move <fileId> <目录ID> | | search | 搜索笔记 | youdaonote search "关键词" | | list | 浏览目录 | youdaonote list -f <目录ID> | | read | 读取笔记 | youdaonote read <fileId> | | recent | 最近收藏 | youdaonote recent -l 20 -c --json | | clip | 网页剪藏（服务端） | youdaonote clip "https://..." [-f <目录ID>] --json | | clip-save | 保存外部剪藏 JSON | youdaonote clip-save --file data.json | | todo list | 列出待办 | youdaonote todo list [--group <分组ID>] --json | | todo create | 创建待办 | youdaonote todo create -t "标题" [-c "内容"] [-d 2025-12-31] [-g <分组ID>] | | todo update | 更新待办 | youdaonote todo update <todoId> [--done] [--undone] [-t "新标题"] | | todo delete | 删除待办 | youdaonote todo delete <todoId> | | todo groups | 列出待办分组 | youdaonote todo groups --json | | todo group-create | 创建分组 | youdaonote todo group-create "分组名" | | todo group-rename | 重命名分组 | youdaonote todo group-rename <groupId> "新名" | | todo group-delete | 删除分组 | youdaonote todo group-delete <groupId> | | check | 健康检查 | youdaonote check | | config show | 查看配置 | youdaonote config show --json | | config set | 设置配置 | youdaonote config set apiKey YOUR_KEY |

笔记管理

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

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

当用户要保存的内容包含以下任意 Markdown 特征时（# 标题、**粗体**、` `代码块、- 列表、> 引用、链接、），**必须先停下来询问用户**，不得直接执行命令： CODEBLOCK0 收到用户选择后，按以下方式构造命令： - **选 A**：save 命令，type: "md"，文件名加 .md 后缀 CODEBLOCK1 - **选 B**：save 命令，type: "note"，contentFormat: "md"，文件名加 .note 后缀 CODEBLOCK2 > parentId 为可选字段：填写 youdaonote list 返回的文件夹 ID 可指定目标目录；不填则默认存入「我的资源/收藏笔记」。 - **用户未明确选择**（回复"随便"/"你决定"等）：默认选 A ### 创建 / 保存 CODEBLOCK3 ### 其他操作 CODEBLOCK4 ## 网页剪藏 CODEBLOCK5 ## CLI 未安装处理（用户手动执行安装） 收到 command not found 时，Agent 仅提供官方安装命令，由用户在终端手动执行。Agent 不自动执行安装命令，不进行系统级变更。 确认文案建议： CODEBLOCK6 安全边界（必须遵守）： - 仅允许使用官方安装源：https://artifact.lx.netease.com/download/youdaonote-cli/install.sh - 禁止执行任何非官方来源的远程脚本或替代安装命令 - 安装仅用于补齐 youdaonote CLI 依赖；Agent 不执行与当前任务无关的系统操作 - 安装与环境变量导出步骤均由用户手动执行，Agent 不写入 shell 启动文件（如 ~/.zshrc/~/.bashrc） - 建议用户在执行前确认命令来源可信；如对管道执行有顾虑，可先下载脚本后本地查看再执行 **macOS / Linux / WSL**： CODEBLOCK7 **Windows（CMD/PowerShell）**：Agent 应自动完成下载、解压、加入 PATH 的全过程，尽量不让用户手动操作。下载地址： - x64（常见新 CPU）：https://artifact.lx.netease.com/download/youdaonote-cli/youdaonote-cli-windows-x64.tar.gz - x64（旧 CPU、无 AVX2 等，运行默认包秒退 / 退出码约 0xC000001D）：https://artifact.lx.netease.com/download/youdaonote-cli/youdaonote-cli-win-x64-bl.tar.gz - ARM64：https://artifact.lx.netease.com/download/youdaonote-cli/youdaonote-cli-windows-arm64.tar.gz 安装策略：先尝试默认 x64 包，若运行闪退或退出码为 0xC000001D，自动换用 x64 baseline 包重试。 ## 故障排查 运行 youdaonote check --json，根据 status: "fail" 的项执行： | 失败项 | 处理动作 | |--------|---------| | config-file / api-key | youdaonote config set apiKey YOURKEY | | mcp-connection | API Key 有效但网络不通，提示用户检查网络或稍后重试 | ## 注意事项 - 所有命令支持 --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` 等其他命名——服务端会静默忽略未知字段。