dsh-youdaonote

Readme

# dsh-youdaonote

[DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 的有道云笔记工具插件：给 agent 提供 8 个工具，覆盖笔记 CRUD、待办管理和网页剪藏。

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

底层封装[官方 `youdaonote` CLI](https://note.youdao.com/help-center/cli-install-guide.html)（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

```bash
# 本地目录或 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` 加：

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