Youdaonote

YoudaoNote — 有道云笔记

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

初始化（必须首先执行）

1. 读取同目录下的 SETUP_TOKEN.md
2. 将 <SCRIPT_PATH> 替换为本文件所在目录的绝对路径
3. 每次会话开始时，自动获取并配置 API Key：

   api_key=$(bash '<SCRIPT_PATH>/get-token.sh') && youdaonote config set apiKey "$api_key"
   

   • Windows PowerShell：

   $apiKey = & "<SCRIPT_PATH>\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（须使用手机号登录，且云笔记账号已绑定手机号）。获取 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 特征时（# 标题、**粗体**、`代码块、- 列表、> 引用、[链接](url)、![图片](url)），必须先停下来询问用户，不得直接执行命令：

检测到内容包含 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

创建 / 保存

# ✅ 推荐：支持 Markdown 富文本（标题、列表、代码块等）
printf '%s\n' '{"title":"笔记","contentFormat":"md","content":"# 标题\n\n内容"}' | youdaonote save
# ✅ 大内容（>10KB）通过文件传递
youdaonote save --file note.json
# ⚠️ 仅纯文本，不支持 Markdown 格式，有格式需求时禁用
youdaonote create -n "标题" -c "纯文本内容"

其他操作

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

网页剪藏

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：

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
• 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，必须显式确认。

强制检查清单（写入前）

在构造写入内容之前，完成以下步骤：

1. 来自文件的内容：先检测文件编码，转为 UTF-8 后再读入变量
2. 来自 WebFetch / HTTP 请求的内容：响应可能为 GBK/Latin-1 等，必须转码
3. 来自用户输入或变量拼接的内容：清洗非法 UTF-8 字节（\xff\xfe 等）
4. 标题字段同理：笔记标题、待办标题也必须为合法 UTF-8

各环境转码方法

Python（推荐，几乎所有环境都有）：

# 读取文件，自动检测编码并转为 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：

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)：

content=$(iconv -f "$(file -b --mime-encoding tmpfile)" -t UTF-8 tmpfile 2>/dev/null || cat tmpfile)

Windows PowerShell：

# 读取非 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 版本 — 在任何写入操作之前执行
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 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 可以被修复。