@zhaoolee/dsh-notes

dsh plugin --profile web add @zhaoolee/dsh-notes

@zhaoolee/dsh-notes

DeepSeek Harness 插件：把用户对话导出为锤子便签。

Host 面工具插件。安装后，智能体获得一个 notes_export_conversation 工具，分级模式

工作：

1. 已配置便签服务（NOTES_API_BASE_URL + Token 或用户名密码）：把对话内容整理成

Markdown 后调用，工具通过便签服务 API 在当前账号的云端工作区新建一张便签，或按

note_id 更新已有便签，返回便签 ID、标题和可打开的前端链接。

2. 未配置任何用户信息：回退到默认演示服务器 https://notes.fangyuanxiaozhan.com 的

匿名导出接口，把对话渲染成锤子便签长图 PNG 保存到本地并返回文件路径——开箱即用尝鲜，

但不能写入便签列表（匿名模式没有账号工作区）。

配套的开源便签服务：<https://github.com/zhaoolee/notes>

安装

可以在 DSH 的“插件市场”中搜索 notes 并直接安装。仓库随源码提交预编译的 lib/

产物，因此即使市场保持默认的构建脚本拦截策略，也不需要额外开启 allowBuilds。

也可以直接从 npm 安装到目标 profile（例如 web）：

dsh plugin --profile web add @zhaoolee/dsh-notes

安装后重启目标 profile 生效。

已经安装旧版本时，更新到最新版：

dsh plugin --profile web update @zhaoolee/dsh-notes --latest

0.1.0 会在 DSH 0.1.0-rc.6 首次执行工具时因宿主运行时重复安装而中止会话；

请使用 0.1.1 或更高版本。

本地开发时，先在本目录构建产物（产出 lib/）：

npm install
npm run build

再从源码目录安装进目标 profile：

npx -p @deepseek-ai/dsh dsh plugin --profile web add /绝对路径/dsh-plugin

也可以用 --patch 直接叠加而不安装：

dsh web --patch /绝对路径/dsh-plugin/cordis.patch.yml

配置

配置按以下优先级解析（插件配置 → 进程环境变量）：

配置键（插件 config） · 环境变量 · 必填 · 说明

baseUrl · NOTES_API_BASE_URL · 否* · 便签服务基础地址，例如 http://127.0.0.1:18080；未配置时自动回退默认演示服务器

token · NOTES_API_TOKEN · 写入模式二选一 · 稳定 Bearer Token（notes_sk_v1. 开头）

username · NOTES_API_USERNAME · 写入模式二选一 · 无 token 时用于一次性申请 token

password · NOTES_API_PASSWORD · 写入模式二选一 · 同上

demoServer · NOTES_DEMO_SERVER · 否 · 回退用的演示服务器，默认 https://notes.fangyuanxiaozhan.com

\* 配置了 baseUrl 后必须同时提供 token 或用户名密码（写入模式）；只配地址不配凭据会

明确报错，不会静默降级。

示例（进程环境变量，最常用）：

NOTES_API_BASE_URL=http://127.0.0.1:18080
NOTES_API_TOKEN=notes_sk_v1.xxx

没有 token 时，插件会用用户名/密码向 /api/auth/skill-token 申请 token（仅保存在内存，

不落盘）。

使用

用户说“把我们的对话导出成便签”之类的话时，智能体会整理对话为 Markdown 并调用

notes_export_conversation。便签标题取自 Markdown 第一行，因此建议第一行写

# 标题。

工具参数：

• markdown（必填）：对话内容整理后的 Markdown 全文。
• note_id（写入模式）：更新已有便签时传它的 ID（来自上一次导出的 note_id）。
• folder（写入模式）：文件夹 ID 或精确名称；none / null / 未分类 表示清除分类。
• starred（写入模式）：是否加星。
• pinned（写入模式）：是否置顶。
• theme（图片模式）：便签主题，default / smartisan-dark / apple-notes /

apple-notes-light / bear / telegraph，默认 default。

返回 { action, note_id, title, url, file_path, updated_at, server }：

• 写入模式：action 为 created / updated，url 为便签前端链接，file_path 为

null。

• 图片模式：action 为 exported-image，url 为演示服务器上的图片链接，

file_path 为本地 PNG 绝对路径，note_id / updated_at 为 null。

• server 始终标明实际使用的服务地址。

隐私提示

未配置便签服务时，工具会把对话内容发送到默认演示服务器

https://notes.fangyuanxiaozhan.com 的匿名导出接口用于渲染图片（该接口不留存内容

到任何账号工作区，且无法写入便签列表）。涉及敏感对话时，请配置自己的便签服务

（NOTES_API_BASE_URL + 凭据）后使用，避免内容经过公共服务器。

匿名导出的本地 PNG 会写入系统临时目录下随机创建的私有子目录；在支持 POSIX 权限的

系统中，目录仅允许当前用户访问（0700），图片仅允许当前用户读写（0600）。

说明

• 读写逻辑与仓库 skills/notes-export-api/scripts/notes_api.mjs 保持一致：整工作区

读改写、expectedUpdatedAt 乐观并发、409 冲突自动重读并最多重试 4 次。

• 更新便签只替换 Markdown 并刷新 updatedAt；未显式传入的 folder/starred/pinned

保留原值。

• 数据边界：写入模式只操作调用方配置的服务上当前账号自己的工作区，服务端不接受

用户 ID 参数，普通用户与超级管理员数据严格隔离。

测试

npm test        # 本目录：单元测试（mock fetch）+ 端到端（启动真实后端、临时存储）
npm run typecheck

端到端测试会以临时 DATA_STORAGE_DIR / IMAGE_STORAGE_DIR 和随机端口启动仓库后端，

验证写入便签与匿名导出图片两条链路，不触碰真实 storage/data。