前言¶
在 DeepSeek Harness（DSH）里做任务时，笔记往往落在 Joplin 里：检索旧结论、把对话摘要写回笔记本、按路径整理项目笔记。若只能人工复制粘贴，智能体无法稳定引用本地知识库。下面介绍社区插件 dsh-joplin（维护者 ddssh）：它只连本机 Joplin 桌面版的 Web Clipper 服务，提供搜索、全文读取、创建与可选的修改/删除，默认偏只读，无运行时第三方依赖。
这是什么¶
dsh-joplin 是面向 DeepSeek Harness 的 Host 插件，通过 Joplin 桌面端启用的 Web Clipper API（默认 http://127.0.0.1:41184）访问笔记。它不依赖 Python、uv 或常驻 sidecar，实现上仅使用 Node 内置模块（node:http / node:fs）。插件在 npm 上发布为 dsh-joplin（当前资料中版本 0.1.4），许可证 MIT，要求 DSH 所在环境 Node.js >= 20。
不支持 Joplin Cloud 与移动端 API；仅 Joplin 桌面版在运行且 Web Clipper 已开启时可用。
核心功能¶
资料中列出的能力如下。
十个工具与默认权限¶
| 工具 | 作用 | 默认权限 |
|---|---|---|
joplin_status |
诊断：token 来源、连通性、笔记本数量、近期更新 | 只读 |
joplin_list_notebooks |
笔记本树（完整路径与 id） | 只读 |
joplin_search_notes |
关键词搜索与摘要；空 query 且指定 notebook 时列出该本笔记 |
只读 |
joplin_get_note |
全文、所属本、标签、内部链接 | 只读 |
joplin_find_linked_notes |
通过 :/<id> 查 outgoing / back links |
只读 |
joplin_create_note |
创建笔记（可选本、可选 todo） | allowCreate 开 |
joplin_create_notebook |
创建本或子本 | allowCreate 开 |
joplin_import_markdown |
将本地 .md 导入为笔记 |
allowCreate 开 |
joplin_update_note |
按需改标题/正文/本/todo | allowUpdate 关，且需 user_confirmed |
joplin_delete_note |
删除（默认进回收站，permanent: true 永久删） |
allowDelete 关，且需 user_confirmed |
笔记本参数可为 32 位 id、唯一标题或完整路径（如 Work/ProjectA）；歧义时会报错并列出候选，不猜测。
设计与隐私¶
- 最小权限：创建默认开启；更新与删除默认关闭。能力关闭时，工具在发出任何写请求之前即抛错，Joplin 不会被改动。
- 写后校验：每次写入会读回比对；正文不一致时抛出
WRITE_VERIFY_FAILED，避免 Joplin 侧大正文 UTF-8 写入损坏被静默忽略（插件对出站 JSON 做 ASCII 转义\uXXXX以规避已知问题）。 - 搜索降级：Joplin 全文搜索接口卡住时，约 8 秒后回退本地扫描并在结果中标注
engine；可用mode: "local"强制本地扫描。 - 隐私：只连接你配置的
baseUrl，无上传、无遥测；插件会安装常驻提示规则JOPLIN_NOTES，要求笔记正文与摘要不得通过网页搜索、浏览器、子智能体等渠道外泄。
使用前准备¶
- 安装并运行 Joplin 桌面版。
- 在「Tools → Options → Web Clipper」中启用 Web Clipper 服务（默认端口 41184），并复制 API token。
- DSH 主机侧 Node.js >= 20。
安装与启用¶
DSH 生态里插件可通过 npm、GitHub 或本地目录安装；以下命令均来自项目 README。
方式一：npm registry
plugin_manager(action: "install_bundle", target: "dsh-joplin")
或：
dsh plugin --profile <profile> add dsh-joplin
方式二：从 GitHub 由 DSH 直接安装仓库
plugin_manager(action: "install_bundle", target: "github:ddssh/dsh-joplin")
方式三：本地目录（需先将插件目录放到本机，再指定绝对路径）
dsh plugin --profile <profile> add /absolute/path/to/dsh-joplin
安装后会注册 joplin_* 工具。这是纯 Host 插件、无 client 半部，一般无需重启 DSH；若你修改了插件 JS，需重启（Node 会缓存已导入模块）。
配置¶
配置按优先级解析，先出现的非空值生效：
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | ~/.dsh/joplin.json |
推荐：改完即生效，token 不必写进 profile YAML |
| 2 | 环境变量 JOPLIN_TOKEN、JOPLIN_BASE_URL、JOPLIN_TIMEOUT_MS、JOPLIN_DEFAULT_NOTEBOOK、JOPLIN_ALLOW_CREATE / JOPLIN_ALLOW_UPDATE / JOPLIN_ALLOW_DELETE |
需重启 Harness |
| 3 | 插件配置（Settings 或 profile 内 cordis.patch.yml） |
baseUrl、token、timeoutMs、defaultNotebook、allowCreate、allowUpdate、allowDelete |
最小示例：
cat > ~/.dsh/joplin.json <<'JSON'
{
"token": "your-web-clipper-token",
"baseUrl": "http://127.0.0.1:41184"
}
JSON
chmod 600 ~/.dsh/joplin.json
可选字段包括 defaultNotebook、timeoutMs，以及 allowCreate / allowUpdate / allowDelete。配置完成后，应先调用 joplin_status：它会报告 token 来自哪一层、服务是否可达、笔记本数量。
若需允许改笔记，可在配置中显式打开（仍须在调用更新/删除工具时传 user_confirmed: true）：
{ "token": "…", "allowUpdate": true }
典型用法¶
- 连通性检查：智能体调用
joplin_status，确认 Web Clipper 可达且 token 有效。 - 按关键词找笔记：
joplin_search_notes传入query；若全文接口 hang，结果中会体现本地扫描引擎。 - 读全文与链接：
joplin_get_note取正文；joplin_find_linked_notes查看双向链接。 - 写入：默认可用
joplin_create_note、joplin_create_notebook、joplin_import_markdown；修改或删除需先在配置中开启对应权限，并在工具参数里带user_confirmed: true。
笔记本路径示例：Work/ProjectA、id 或唯一标题。
适用场景与注意¶
适合：已在本地用 Joplin 桌面版沉淀笔记、希望 DSH 智能体在本机检索与（按需）写回的开发者；社区目录将其归类为联网工具（实质为连本地 HTTP API）。
务必注意：
- 插件以当前 DSH 进程的用户与权限运行，能访问你配置的 Joplin token 与本地 Markdown 导入路径；安装前请阅读 源码与 LICENSE，确认行为符合预期。
- Joplin 桌面 3.7.18 上曾复现全文搜索 hang、大正文写入损坏等问题；插件有回退与写后校验，但仍建议在重要笔记上先小范围试写。
- 社区插件目录 SkillHub 上的 dsh-joplin 页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 理念是「一切皆插件」，按需选用即可。
结尾¶
dsh-joplin 把 Joplin 桌面 Web Clipper 收成十个 DSH 工具：默认只读与关闭更新/删除，配合本地配置与 JOPLIN_NOTES 规则，适合在本机知识库与 Harness 智能体之间做可控桥接。
