dsh-youdaonote

DeepSeek Harness (dsh) 的有道云笔记工具插件：给 agent 提供 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. Agent 第一次调用任意 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	插件装进了别的 profile，dsh plugin 是按 profile 安装的

兼容性与实现说明

• 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 等）仅供测试与诊断，不属于插件契约。