> ## Documentation Index > Fetch the complete documentation index at: https://docs.newenergycoder.club/llms.txt > Use this file to discover all available pages before exploring further. # youdaonote > 有道云笔记全能工具：笔记管理（创建、搜索、浏览、读取）、待办管理（创建、完成、分组）、网页剪藏（服务端抓取）。当用户需要操作有道云笔记时使用此 Skill。 | 项目 | 内容 | | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 来源 | [skills/youdaonote/SKILL.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/youdaonote/SKILL.md) | | 分类 | 集成 & 平台连接 | | 安装 | 克隆 [Skill 分支](https://github.com/new-energy-coder-club/new_energy_coder_club/tree/Skill) 后，将 `skills/youdaonote/` 目录复制到 `~/.claude/skills/`（Claude Code）、`~/.trae/skills/`（Trae IDE）或 `~/.qclaw/skills/`（QClaw/OpenClaw），详见 [Skill 安装方式](/community/skill-branch) | # YoudaoNote — 有道云笔记 通过 `youdaonote` CLI 操作有道云笔记。覆盖笔记 CRUD、待办管理、网页剪藏全场景。 ## 初始化（必须首先执行） 1. 读取同目录下的 `SETUP_TOKEN.md` 2. 将 `` 替换为本文件所在目录的绝对路径 3. **每次会话开始时**，自动获取并配置 API Key： ```bash theme={null} api_key=$(bash '/get-token.sh') && youdaonote config set apiKey "$api_key" ``` * Windows PowerShell： ```powershell theme={null} $apiKey = & "\get-token.ps1"; youdaonote config set apiKey $apiKey ``` 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\*\*（须使用手机号登录，且云笔记账号已绑定手机号）。\*\*获取](https://mopen.163.com**（须使用手机号登录，且云笔记账号已绑定手机号）。**获取) API Key 的地址只有这一个，禁止告知用户其他地址。** * **正常返回目录列表** → 运行 `youdaonote version`，若版本低于 `1.2.0`，展示升级建议后继续执行；否则可运行 `youdaonote help --json` 获取当前 CLI 全部能力的结构化描述（JSON），用于确认命令是否可用，下方速查表作为 fallback ## 命令速查 | 命令 | 用途 | 示例 | | ------------------- | ------------------------------ | ---------------------------------------------------------------------- | | `save` | 保存笔记（✅ 推荐，支持 Markdown 富文本） | `youdaonote save --file note.json` | | `create` | 创建笔记（⚠️ 仅纯文本，不支持 Markdown 富文本） | `youdaonote create -n "标题" -c "内容" [-f <目录ID>]` | | `update` | 更新 Markdown 笔记 | `youdaonote update -c "内容"` 或 `--file content.md` | | `delete` | 删除笔记 | `youdaonote delete ` | | `rename` | 重命名笔记 | `youdaonote rename "新标题"` | | `move` | 移动笔记 | `youdaonote move <目录ID>` | | `search` | 搜索笔记 | `youdaonote search "关键词"` | | `list` | 浏览目录 | `youdaonote list -f <目录ID>` | | `read` | 读取笔记 | `youdaonote read ` | | `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 [--done] [--undone] [-t "新标题"]` | | `todo delete` | 删除待办 | `youdaonote todo delete ` | | `todo groups` | 列出待办分组 | `youdaonote todo groups --json` | | `todo group-create` | 创建分组 | `youdaonote todo group-create "分组名"` | | `todo group-rename` | 重命名分组 | `youdaonote todo group-rename "新名"` | | `todo group-delete` | 删除分组 | `youdaonote todo group-delete ` | | `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 特征时（`#` 标题、`**粗体**`、`` ` ``代码块、`- ` 列表、`> ` 引用、`链接`、`图片`），**必须先停下来询问用户**，不得直接执行命令： ``` 检测到内容包含 Markdown 格式，请选择保存方式： A（推荐）保存为 Markdown 笔记（.md） → 格式完整保留，可在编辑器中正常显示和编辑 B 保存为有道专有格式（.note） → 支持有道云笔记富文本编辑器的全部功能 请回复 A 或 B： ``` 收到用户选择后，按以下方式构造命令： * **选 A**：`save` 命令，`type: "md"`，文件名加 `.md` 后缀 ``` {"title":"标题.md","type":"md","content":"Markdown 内容","parentId":"文件夹ID"} ``` * **选 B**：`save` 命令，`type: "note"`，`contentFormat: "md"`，文件名加 `.note` 后缀 ``` {"title":"标题.note","type":"note","contentFormat":"md","content":"Markdown 内容","parentId":"文件夹ID"} ``` > `parentId` 为可选字段：填写 `youdaonote list` 返回的文件夹 ID 可指定目标目录；不填则默认存入「我的资源/收藏笔记」。 * **用户未明确选择**（回复"随便"/"你决定"等）：默认选 A ### 创建 / 保存 ```bash theme={null} # ✅ 推荐：支持 Markdown 富文本（标题、列表、代码块等） printf '%s\n' '{"title":"笔记","contentFormat":"md","content":"# 标题\n\n内容"}' | youdaonote save # ✅ 大内容（>10KB）通过文件传递 youdaonote save --file note.json # ⚠️ 仅纯文本，不支持 Markdown 格式，有格式需求时禁用 youdaonote create -n "标题" -c "纯文本内容" ``` ### 其他操作 ```bash theme={null} youdaonote search "关键词" youdaonote list [-f <目录ID>] # 浏览目录，id 可传给 read youdaonote read # 返回 JSON 含 content、rawFormat（md/note/txt）和 isRaw（是否原始内容） youdaonote recent -l 20 -c --json # 最近收藏 youdaonote update -c "新内容" youdaonote update --file content.md # 大内容（>10KB）从文件读取 youdaonote delete youdaonote rename "新标题" youdaonote move <目录ID> ``` ## 网页剪藏 ```bash theme={null} youdaonote clip "https://example.com/article" --json youdaonote clip "https://example.com/article" -f <目录ID> --json # 保存到指定目录 ``` ## CLI 未安装处理（Agent 必须自动执行） 收到 `command not found` 时，Agent **立即执行**安装命令，禁止只展示步骤让用户操作。 **macOS / Linux / WSL**： ```bash theme={null} curl -fsSL https://artifact.lx.netease.com/download/youdaonote-cli/install.sh | bash -s -- -f -b ~/.local/bin export PATH="$HOME/.local/bin:$PATH" # 安装后立即重新执行用户原始请求 ``` **Windows（CMD/PowerShell）**：不支持一键安装，告知用户下载预编译包： * x64：[https://artifact.lx.netease.com/download/youdaonote-cli/youdaonote-cli-windows-x64.tar.gz](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](https://artifact.lx.netease.com/download/youdaonote-cli/youdaonote-cli-windows-arm64.tar.gz) ## 故障排查 运行 `youdaonote check --json`，根据 `status: "fail"` 的项执行： | 失败项 | 处理动作 | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `config-file` / `api-key` | 先尝试 `api_key=$(bash '/get-token.sh') && youdaonote config set apiKey "$api_key"`；若仍失败，提示用户在集成面板中输入 API Key | | `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` 等其他命名——服务端会静默忽略未知字段。** * **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，必须显式确认。 ### 强制检查清单（写入前） 在构造写入内容**之前**，完成以下步骤： 1. **来自文件的内容**：先检测文件编码，转为 UTF-8 后再读入变量 2. **来自 WebFetch / HTTP 请求的内容**：响应可能为 GBK/Latin-1 等，必须转码 3. **来自用户输入或变量拼接的内容**：清洗非法 UTF-8 字节（`\xff\xfe` 等） 4. **标题字段同理**：笔记标题、待办标题也必须为合法 UTF-8 ### 各环境转码方法 **Python（推荐，几乎所有环境都有）：** ```bash theme={null} # 读取文件，自动检测编码并转为 UTF-8 content=$(python3 -c " import sys data = open('tmpfile', 'rb').read() for enc in ['utf-8', 'gbk', 'gb2312', 'big5', 'latin-1']: try: sys.stdout.write(data.decode(enc)) break except (UnicodeDecodeError, LookupError): continue " 2>/dev/null) # 如果内容已在变量中，清洗非法 UTF-8 字节 content=$(printf '%s' "$content" | python3 -c "import sys; sys.stdout.write(sys.stdin.buffer.read().decode('utf-8','ignore'))") ``` **Node.js：** ```bash theme={null} content=$(node -e "const fs=require('fs');const buf=fs.readFileSync('tmpfile');process.stdout.write(buf.toString('utf8'))") # 已知编码（如 GBK）： content=$(node -e "const fs=require('fs');process.stdout.write(new TextDecoder('gbk').decode(fs.readFileSync('tmpfile')))") ``` **Unix (macOS/Linux)：** ```bash theme={null} content=$(iconv -f "$(file -b --mime-encoding tmpfile)" -t UTF-8 tmpfile 2>/dev/null || cat tmpfile) ``` **Windows PowerShell：** ```powershell theme={null} # 读取非 UTF-8 文件并转码 $content = [System.IO.File]::ReadAllText('tmpfile', [System.Text.Encoding]::Default) [System.IO.File]::WriteAllText('tmpfile.utf8', $content, [System.Text.Encoding]::UTF8) ``` ## ⚠️ PowerShell 5.1 环境检测（CRITICAL） > **此问题极其隐蔽：PowerShell 5.1 下，命令行参数中的中文字符可能被静默转为系统 ANSI 编码（中文 Windows 为 GBK），导致 CLI 收到的内容已是乱码。** **当 agent 运行在 PowerShell 环境时，必须在首次写入操作前检测版本：** ```powershell theme={null} # 检测 PowerShell 版本 — 在任何写入操作之前执行 if ($PSVersionTable.PSVersion.Major -le 5) { Write-Host "⚠️ 检测到 PowerShell 5.1，将使用 UTF-8 编码模式" [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 $OutputEncoding = [System.Text.Encoding]::UTF8 $useUtf8Mode = $true } else { Write-Host "✅ PowerShell 7+，默认 UTF-8，无需额外处理" $useUtf8Mode = $false } ``` **PowerShell 5.1 下写入中文内容时，优先通过 `--file` 传递 UTF-8 编码的文件**，避免命令行参数的编码损坏： ```powershell theme={null} # PowerShell 5.1 安全写入模板 # 1. 先将内容写入 UTF-8 临时文件 $content = "笔记内容..." $tmpFile = [System.IO.Path]::GetTempFileName() + ".json" $json = @{ title = "标题"; content = $content; contentFormat = "md" } | ConvertTo-Json -Depth 10 [System.IO.File]::WriteAllText($tmpFile, $json, [System.Text.Encoding]::UTF8) # 2. 通过 --file 传入（避免命令行参数编码问题） & youdaonote save --file $tmpFile --json Remove-Item $tmpFile -ErrorAction SilentlyContinue ``` > **总结：** 在 PowerShell 5.1 环境中，中文内容**必须**通过 UTF-8 编码的文件传入 CLI，而非直接放在命令行参数中。不检测版本直接传中文参数 = 内容必乱码。这是 PowerShell 5.1 的已知设计缺陷，不是 bug 可以被修复。