dsh-sticky-notes

dsh-sticky-notes

English | 中文

version	1.0.7
npm	dsh-sticky-note-panel@1.0.7
release	v1.0.7 · 预构建 tarball
dshmarket	目录 PR awesome-dsh-plugin#12977（审核中 / pending review）
DSH	>= 0.2.0-rc.1（在 0.2.1-rc.5 桌面版开发与实测）
license	MIT
Node	>= 22（仅运行冒烟测试需要）

仓库名 dsh-sticky-notes · npm 包名 dsh-sticky-note-panel（安装 / 加依赖请用后者）。 The repo is named dsh-sticky-notes, but the published npm package is dsh-sticky-note-panel — use that name when installing or adding a dependency.

English

dsh-sticky-notes is a sticky-notes plugin for DeepSeek Harness (DSH): a draggable floating panel beside the conversation, a full page in the sidebar, Markdown preview, image paste, and settings. All data lives in the browser's localStorage; there is no host-side logic.

It ships as a prebuilt npm package (dsh-sticky-note-panel@1.0.7) and a version-pinned GitHub Release tarball, and has been submitted to the curated awesome-dsh-plugin catalog so it can be found and installed from dshmarket.

Features

Feature	Description
Floating panel	A tab on the right edge of the screen with a note-count badge; the panel opens on click, its title bar drags, and the position persists (re-clamped to the viewport on smaller screens)
Full page	A sidebar icon opens the full page; it shares the same data as the floating panel, and edits sync instantly in both directions
Settings	Both the panel (⚙) and the page carry a settings area with 7 options (below)
Markdown preview	Notes render through the host's MarkdownText; click a rendered note to edit it as plain text, blur to return to preview
Paste images	Ctrl+V an image into a note to attach it; each thumbnail has its own × remove button
Bilingual	Follows the host locale service; falls back to the browser language, so Chinese users see Chinese even when the host locale service is unavailable
Cross-window sync	Notes and settings both listen to the storage event, so every window stays in step
Data robustness	Corrupted storage is never overwritten (a warning shows; the write-back is authorized only by a real edit); failed writes show a "kept only until you close this page" warning

Settings

Setting	Type	Default	Description
Floating panel	switch	on	Whether the floating tab shows on the right edge
Sidebar entry	switch	on	Whether the notes icon shows in the left sidebar (the settings page stays reachable either way)
Markdown preview	switch	on	Off = every note is a plain text field
Count badge	switch	on	The number on the floating tab
Panel width	number	320	240–560 pixels, clamped
Note order	select	newest first	Newest first / Oldest first, shared by panel and page
Delete all notes	button	—	Requires an explicit confirmation

Storage and limits

Key	Content
dsh-sticky-notes:v1	Note list ([{id, text, images, updatedAt}])
dsh-sticky-notes:settings	Settings
dsh-sticky-notes:pos	Floating-panel position

Image limits: at most 8 images per note, each ≤700KB (data URLs; worst case ≈5.6MB per note). On read, values that are not data:image/ are dropped and the list is capped at 8. Data does not sync across devices.

Install

The package is prebuilt — client.js ships as-is, so installs skip the allowBuilds build-approval step. Pick whichever channel suits you:

1 · One command (recommended) — install the published npm package:

dsh plugin --profile web add dsh-sticky-note-panel

2 · dshmarket — the plugin has been submitted to the curated awesome-dsh-plugin catalog (category ui, PR #12977). While that review is pending, use method 1 or 3; once the PR is merged, it appears in dshmarket's Discover tab with one-click install. (The catalog is remote and curated — a local install cannot add an entry.)

3 · Version-pinned Release tarball — the same prebuilt bytes, no npm required:

dsh plugin --profile web add "https://github.com/stallenlu/dsh-sticky-notes/releases/download/v1.0.7/dsh-sticky-note-panel-1.0.7.tgz"

When both an npm package and a tarball are known, dshmarket prefers npm; the pinned Release tarball is a fallback and is also consumed by other storefronts (e.g. dshfind.com). The v1.0.7 tag is byte-identical to the published npm tarball (all 9 files match).

4 · Manual (profile.json) — if you manage the profile by hand instead of the CLI, declare the official npm version directly in $DSH_PROFILE_DIR/package.json:

{
  "dependencies": {
    "dsh-sticky-note-panel": "1.0.7"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-sticky-note-panel"]
    }
  }
}

The bundle's own cordis.patch.yml inserts the plugin row (ui-sticky-notes); no profile patch edit is needed. This points at the published npm release (a copy under node_modules), so local source edits no longer apply — bump the version to pick up a newer release. Editing package.json / cordis.patch.yml needs a DSH restart. Never use a link: (or file:) dependency pointing at a local clone here: once that folder is moved or deleted it leaves a dangling directory junction, and the next launch fails with dsh: cannot resolve profile bundle "dsh-sticky-note-panel". To work on the source, edit a separate clone and publish a new npm version instead.

Development

node smoke.mjs        # 147 assertions; the guard lines on stderr are expected
node --check client.js

Negative controls (to prove the assertions bite): temporarily remove a piece of logic in client.js (e.g. the || n.images.length > 0 persistence condition, the .slice(0, MAX_IMAGES) read cap, or the .dsn-hint render line) — the matching assertion must fail; then restore.

Implementation notes

• Client halves of static boot bundles receive only require in their factory — styles/host/harness do not exist there. Styles are installed by hand as a <style> element appended to document.head.
• All colors go through --dsw-alias-* theme tokens; no literal colors in CSS.
• apply() and the inner slots.register are both wrapped in try/catch: during boot the host audits every manifest plugin, and one non-active entry blocks the whole Web UI. A decorative panel must degrade to "not shown", never to "no app".
• MarkdownText comes from the platform seed table via require('@deepseek-ai/dsh-client-ui-primitives'); when unavailable the note degrades to plain text.

Architecture

├─ package.json        dsh.client = { platform: "web", inject: [] }
├─ cordis.patch.yml    - insert:  id: ui-sticky-notes
├─ index.js            Host half (empty; all data is browser-side)
├─ client.js           Client half (window.__ModuleLoader__ static bundle)
├─ locale/{en,zh}.json Display metadata (meta.title / meta.description)
├─ icon.svg            Plugin icon
└─ smoke.mjs           Smoke test (147 assertions, zero deps, run with node)

Client-half slots: shell.overlay (floating tab + panel, order 900), sidebar.panellist (sidebar icon, order 60, registered/unregistered per setting), main (full page), settings.section (settings area).

中文

dsh-sticky-notes 是 DeepSeek Harness（DSH）的便签插件：对话旁一个可拖动的浮动便签窗，外加侧边栏完整页面、Markdown 预览、粘贴图片和设置项。数据全部存在浏览器 localStorage，无 Host 侧逻辑。

已发布为预构建 npm 包（dsh-sticky-note-panel@1.0.7）与固定版本的 GitHub Release tarball，并已提交到 awesome-dsh-plugin 精选目录，以便通过 dshmarket 搜索与安装。

功能

功能	说明
浮动便签窗	屏幕右侧中部悬浮标签，显示便签计数徽章；点击展开面板，标题栏可拖动，位置持久化（换分辨率后自动收回视口内）
完整页面	左侧边栏便签图标进入完整页面，与浮窗共享同一份数据，改一处另一处即时同步
设置页	浮窗 ⚙ 与完整页面均有设置区，共 7 项（见下）
Markdown 预览	使用宿主 MarkdownText 渲染；点击预览区切回纯文本编辑，失焦后回到预览
粘贴图片	在便签文本框内 Ctrl+V 粘贴图片即附加；缩略图右上角 × 单独移除
双语	跟随宿主语言服务；宿主未提供时回退浏览器语言，中文环境显示中文
跨窗口同步	便签与设置都监听 storage 事件，多窗口各视图实时一致
数据健壮性	存储损坏不覆盖原数据（给出警示，用户编辑后才授权写回）；写失败显示「仅保留到关闭页面」警告

设置项

设置	类型	默认	说明
浮动面板	开关	开	是否显示屏幕右侧的浮动标签
侧边栏入口	开关	开	是否在左侧边栏显示便签图标（设置页始终可达）
Markdown 预览	开关	开	关闭后所有便签退回纯文本编辑框
计数徽章	开关	开	浮动标签上的便签数量
面板宽度	数字	320	240–560 像素，越界自动收拢
便签排序	下拉	最新的在前	最新的在前 / 最旧的在前，浮窗与页面共享
删除全部便签	按钮	—	需二次确认

存储与限制

键	内容
dsh-sticky-notes:v1	便签列表（[{id, text, images, updatedAt}]）
dsh-sticky-notes:settings	设置项
dsh-sticky-notes:pos	浮窗位置

图片限制：每条便签最多 8 张，单张 ≤700KB（data URL，最坏总量约 5.6MB）；读取时清洗非 data:image/ 的值并截断到 8 张。数据不跨设备同步。

安装

本包是预构建的——client.js 随包发布，安装时跳过 allowBuilds 构建授权步骤。任选一种方式：

1 · 一条命令（推荐）——安装已发布的 npm 包：

dsh plugin --profile web add dsh-sticky-note-panel

2 · dshmarket——插件已提交到 awesome-dsh-plugin 精选目录（ui 分类，PR #12977）。审核期间请先用方式 1 或 3；PR 合并后，它会出现在 dshmarket 的 Discover 标签页，可一键安装。（目录是远端精选，本地安装无法新增条目。）

3 · 固定版本 Release tarball——同一份预构建内容，无需 npm：

dsh plugin --profile web add "https://github.com/stallenlu/dsh-sticky-notes/releases/download/v1.0.7/dsh-sticky-note-panel-1.0.7.tgz"

当 npm 包与 tarball 同时存在时，dshmarket 优先用 npm；固定版本的 Release tarball 作为兜底，同时供其它商店（如 dshfind.com）使用。v1.0.7 标签与已发布的 npm tarball 逐字节一致（9 个文件全部匹配）。

4 · 手动声明（profile.json）——如果不走命令行、而是直接管理 profile，就在 $DSH_PROFILE_DIR/package.json 里声明官方 npm 版本：

{
  "dependencies": {
    "dsh-sticky-note-panel": "1.0.7"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-sticky-note-panel"]
    }
  }
}

bundle 自带的 cordis.patch.yml 会插入插件行（ui-sticky-notes），无需改 profile 的 patch 文件。这里指向已发布的 npm 版本（node_modules 里是一份拷贝），本地源码改动不再生效——要升级就改版本号。改 package.json / cordis.patch.yml 需要重启 DSH。不要在这里用 link:（或 file:）依赖指向本地克隆目录：该目录一旦被移动或删除，就会留下悬空的目录 Junction，下次启动直接报 dsh: cannot resolve profile bundle "dsh-sticky-note-panel"。要改源码，请在独立克隆里修改并发布新的 npm 版本。

开发

node smoke.mjs        # 147 条断言；stderr 里的 guard 日志是预期输出
node --check client.js

反向对照（验证断言有约束力）：临时删掉 client.js 中某段逻辑（如 || n.images.length > 0、.slice(0, MAX_IMAGES)、.dsn-hint 渲染行），对应断言应失败；测完恢复。

实现要点

• 静态 boot bundle 的 client 半面工厂只收到 require——styles/host/harness 在这里不存在。样式自建 <style> 元素插入 document.head。
• 颜色全部走 --dsw-alias-* 主题 token，CSS 不写死颜色。
• apply() 整体与生成器内 slots.register 都包 try/catch：boot 期宿主会审计每个 manifest 插件，一条未 active 就让整个 Web UI 拒绝启动。装饰性组件必须降级为「不显示」，而不是「崩宿主」。
• MarkdownText 来自平台 seed 表 require('@deepseek-ai/dsh-client-ui-primitives')，取不到时优雅退回纯文本。

架构

├─ package.json        dsh.client = { platform: "web", inject: [] }
├─ cordis.patch.yml    - insert:  id: ui-sticky-notes
├─ index.js            Host 半面（空实现，数据全在浏览器端）
├─ client.js           Client 半面（window.__ModuleLoader__ 静态 bundle）
├─ locale/{en,zh}.json 展示元数据（meta.title / meta.description）
├─ icon.svg            插件图标
└─ smoke.mjs           冒烟测试（147 条断言，零依赖，node 直跑）

Client 半面注册的 slot：shell.overlay（浮动标签 + 面板，order 900）、sidebar.panellist（侧边栏图标，order 60，按设置注册/注销）、main（完整页面）、settings.section（设置区）。

License

MIT