有道云笔记 xmzd-S/dsh-youdaonote

dsh-youdaonote

DeepSeek Harness (dsh) 的有道云笔记工具插件：给智能体提供 8 个工具，覆盖笔记 CRUD、待办管理和网页剪藏。

零手动安装：首次调用任何工具时，插件自动把官方 youdaonote CLI 装到自己的数据目录（~/.dsh/integrations/dsh-youdaonote/bin，不碰系统路径）；API Key 免手动输入：检测到未配置时，通过 dsh 的用户提问服务弹卡片向你索要，拿到后自动写入 CLI 配置。

底层封装官方 youdaonote CLI（API Key 鉴权），本插件不直接调用云笔记 HTTP API，鉴权与协议升级都由 CLI 承担。

工具一览

| 工具 | 用途 | 只读（可并发） |
| youdaonote_search | 关键词搜索笔记 | ✅ |
| youdaonote_read | 读取笔记全文（含 rawFormat 元数据） | ✅ |
| youdaonote_list | 浏览目录（根目录或指定文件夹） | ✅ |
| youdaonote_save | 新建 Markdown 笔记（内部走 save，不走纯文本的 create，格式不丢失） | ❌ |
| youdaonote_update | 覆盖更新正文（经临时文件传递，大内容安全） | ❌ |
| youdaonote_manage | delete / rename / move | ❌ |
| youdaonote_todo | 待办 list / groups / create / update / delete | 仅 list、groups |
| youdaonote_clip | 网页剪藏（服务端抓取） | ❌ |

设计要点：保存一律走 save（contentFormat: "md"）保格式；正文经 stdin/临时文件传递避免转义与长度问题；输出超过 maxOutputChars 自动截断；CLI 部分子命令实际不支持 --json（如 todo update、list），插件自动回退到纯文本输出再交给模型。

首次使用流程（全自动）

1. 智能体第一次调用任意 youdaonote 工具时，插件检查 CLI：
- 已存在（PATH 或数据目录）→ 直接用；
- 不存在且平台是 Linux/macOS → 自动执行官方安装脚本装入 ~/.dsh/integrations/dsh-youdaonote/bin（需要 curl 和 bash，阿里云 Linux 默认都有）；
- Windows 不支持自动安装，会报错并附手动安装指引。
2. 接着运行 youdaonote check：若 api-key 未配置且运行环境支持提问（Web UI / TUI 均支持），弹卡片请你粘贴 API Key（从 https://mopen.163.com 获取，手机号登录），拿到后自动执行 config set apiKey 完成配置；环境不支持提问（headless 等）时，报错信息里带手动配置命令。
3. 配置结果按进程记忆，之后不再重复检查；如果中途 Key 失效，下一次调用会自动重新检查并再次询问。

API Key 由 CLI 自己存储（~/.youdaonote.json），插件不落盘、不进日志。

安装到 dsh

本地目录或 tgz 均可（--profile 填实际运行的 profile）
dsh plugin --profile web add --save-exact /path/to/dsh-youdaonote

验证 + 重启
dsh --profile web --dump-config | grep youdaonote # 应看到 "- id: youdaonote"
sudo systemctl restart dsh

升级 / 卸载：dsh plugin --profile web update|remove dsh-youdaonote。

配置

默认值全部内建，patch 行可以不写 config。需要覆盖时在 profile 的 cordis.patch.yml 加：

- insert:
- id: youdaonote
name: dsh-youdaonote
config:
bin: youdaonote # CLI 路径覆盖；设为非默认值后插件只认这一处，不再自动找 statSource: ydn # CLI -s 统计来源参数 timeoutMs: 120000 # 单次 CLI 调用超时（clip 剪藏较慢，别低于 60s） maxOutputChars: 100000 # 工具输出字符上限 autoInstall: true # CLI 缺失时自动安装（Linux/macOS） autoAskKey: true # 缺 Key 时通过提问服务索要 dataDir: ~/.dsh/integrations/dsh-youdaonote # 插件数据目录 binDir: ~/.dsh/integrations/dsh-youdaonote/bin # 自动安装的目标目录 installUrl: https://artifact.lx.netease.com/download/youdaonote-cli/install.sh

排错

| 现象 | 处理 |
| 自动安装失败 | 检查服务器能否访问 artifact.lx.netease.com（curl -I 试一下）；失败信息里有手动安装命令 |
| 想重新触发 Key 提问 | 重启 dsh 进程即可（检查结果按进程记忆）；或手动 youdaonote config set apiKey <KEY> |
| 提示"不支持交互提问" | 当前 profile 未挂载提问服务（如 headless）。按报错里的手动命令配置 Key |
| 工具输出是纯文本不是 JSON | 正常：CLI 部分子命令不支持 --json，插件已自动回退，id 等信息仍在文本中 |
| dump-config 里没有 youdaonote | 插件装进了别的配置档，dsh plugin 是按配置档安装的 |

兼容性与实现说明

- dsh：0.1.2-alpha.4 至 0.1.5-rc.2（developer preview 阶段上游接口可能变动，升 dsh 后跑一次 --dump-config 验证）。
- 只依赖宿主的 tools 服务与 @deepseek-ai/dsh-tools 的 defineTool；userQuestions 运行时防御性访问，缺失不影响插件加载。
- 实测基于 youdaonote CLI 1.3.4（Windows）验证，Linux 走同一官方安装脚本。
- _internal 导出（needsKey/ensureCli/ensureApiKey 等）仅供测试与诊断，不属于插件契约。