youdaonote

YoudaoNote — 有道クラウドノート

youdaonote CLI を使って有道クラウドノートを操作します。ノートの CRUD、ToDo 管理、ウェブページのクリッピングを一通りカバーします。

前提条件（エージェントが自動処理）

操作を実行する前に、エージェントは必ず youdaonote -s ydn list を実行して、CLI が利用可能か確認する必要があります：

• command not found → ただちに「CLI 未インストール時の対応」に進んで自動インストールします。インストール手順を表示するだけで、ユーザーに手動操作させることは禁止です
• -s オプションでエラー（error: unknown option '-s'） → CLI のバージョンが 1.3.2 未満で、グローバルな -s パラメーターに対応していません。アップグレードが必要です。まず youdaonote upgrade を試します。このコマンドに対応していない場合は、「CLI 未インストール時の対応」に記載された方法で再インストールします。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 を実行し、対応していない場合は「CLI 未インストール時の対応」に記載されたアップグレード方法で操作します。Windows ユーザー、またはアップグレードに失敗した場合は、インストールガイド（https://note.youdao.com/help-center/cli-install-guide.html）を参照してください。必要なバージョンを満たした後、`youdaonote -s ydn help --json` を実行して、現在の CLI の全機能を構造化した説明（JSON）を取得し、コマンドが利用可能か確認できます。以下の早見表はフォールバックとして使用します

グローバルパラメーター

すべてのコマンドを実行する際は、使用状況の統計のため、必ず -s ydn を付けてください：

youdaonote -s ydn <command> [options]

コマンド早見表

コマンド	用途	例
mkdir	フォルダーの作成	youdaonote -s ydn mkdir "文件夹名" [-f <父目录ID>]
save	ノートの保存（✅ 推奨。Markdown リッチテキストに対応）	youdaonote -s ydn save --file note.json
create	ノートの作成（⚠️ プレーンテキストのみ。Markdown リッチテキストには非対応）	youdaonote -s ydn create -n "标题" -c "内容" [-f <目录ID>]
update	Markdown ノートの更新	youdaonote -s ydn update <fileId> -c "内容" または --file content.md
delete	ノートの削除	youdaonote -s ydn delete <fileId>
rename	ノート名の変更	youdaonote -s ydn rename <fileId> "新标题"
move	ノートの移動	youdaonote -s ydn move <fileId> <目录ID>
search	ノートの検索	youdaonote -s ydn search "关键词"
list	ディレクトリの閲覧	youdaonote -s ydn list -f <目录ID>
read	ノートの読み込み	youdaonote -s ydn read <fileId>
recent	最近のコレクション	youdaonote -s ydn recent -l 20 -c --json
clip	ウェブページのクリッピング（サーバー側）	youdaonote -s ydn clip "https://..." [-f <目录ID>] --json
clip-save	外部クリッピング JSON の保存	youdaonote -s ydn clip-save --file data.json
todo list	ToDo の一覧表示	youdaonote -s ydn todo list [--group <分组ID>] --json
todo create	ToDo の作成	youdaonote -s ydn todo create -t "标题" [-c "内容"] [-d 2025-12-31] [-g <分组ID>]
todo update	ToDo の更新	youdaonote -s ydn todo update <todoId> [--done] [--undone] [-t "新标题"]
todo delete	ToDo の削除	youdaonote -s ydn todo delete <todoId>
todo groups	ToDo グループの一覧表示	youdaonote -s ydn todo groups --json
todo group-create	グループの作成	youdaonote -s ydn todo group-create "分组名"
todo group-rename	グループ名の変更	youdaonote -s ydn todo group-rename <groupId> "新名"
todo group-delete	グループの削除	youdaonote -s ydn todo group-delete <groupId>
upgrade	CLI のアップグレード	youdaonote -s ydn upgrade [--check] [--force] [--json]
check	ヘルスチェック	youdaonote -s ydn check
config show	設定の確認	youdaonote -s ydn config show --json
config set	設定	youdaonote config set apiKey YOUR_KEY

ノート管理

デフォルトの作成方法：すべてのノートは save コマンドと contentFormat: "md" を使用して、Markdown リッチテキストとして保存します。 Markdown 形式の内容を保存する際に create コマンドを使うことは禁止です（見出し、リスト、コードブロック、表など）。create はプレーンテキストのみ対応しており、すべての書式が通知なく失われます。HTML／構造化データは先に Markdown に変換してから、save で保存してください。

Markdown 内容形式の選択（必ず遵守）

ユーザーが保存する内容に、次のいずれかの Markdown の特徴が含まれる場合（# 見出し、**太字**、`コードブロック、- リスト、> 引用、[リンク](url)、![画像](url)）、必ずいったん停止してユーザーに確認してください。コマンドを直接実行してはいけません：

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

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

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

请回复 A 或 B：

ユーザーから選択を受け取った後、次の方法でコマンドを組み立てます（JSON のエスケープ問題を避けるため、contentFile 方式を優先してください）：

• 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 未安装处理（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"
# 安装后立即重新执行用户原始请求

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

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

故障排查

运行 youdaonote -s ydn check --json，根据 status: "fail" 的项执行：

失败项	处理动作
config-file / api-key	youdaonote config set apiKey YOUR_KEY
mcp-connection	API Key 有效但网络不通，提示用户检查网络或稍后重试

注意事项

• 所有命令支持 --json 输出机器可解析格式
• 大内容通过 --file 传递，避免命令行参数限制
• Windows CMD 中 URL 含 & 时必须用双引号括起
• Windows 管道/重定向场景中文可能乱码（CLI 输出 UTF-8，但 PowerShell/CMD 默认按 GBK 解读）：PowerShell 中执行 [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)，CMD 中执行 chcp 65001；可运行 youdaonote -s ydn check 查看诊断建议
• 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 等其他命名——服务端会静默忽略未知字段。