dsh-side-memo 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reemo Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# Side Memo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![Side Memo — your notes, right where you work](assets/side-memo-banner.png)
+
+**Language:** **English** · [简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md)
+
+![Side Memo panel open in the right sidebar, with searchable notes and labels](assets/plugin0_0_1_screenshot.jpg)
+
+A lightweight, toggleable **right-side notes panel** for [DeepSeek Harness](https://deepseek.com/harness). Jot memos while you chat — text, inline images, and labels — copy them with one click, star favorites to keep them pinned at the top, and move everything in or out as an Excel workbook.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Version](https://img.shields.io/badge/version-1.2.0-4D6BFE)
+[![npm](https://img.shields.io/npm/v/dsh-side-memo?label=npm&color=4D6BFE)](https://www.npmjs.com/package/dsh-side-memo)
+[![CI](https://github.com/r48n34/dsh-side-memo/actions/workflows/ci.yml/badge.svg)](https://github.com/r48n34/dsh-side-memo/actions/workflows/ci.yml)
+![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-0.2.x-4D6BFE)
+![Platform](https://img.shields.io/badge/platform-Web%20%7C%20Desktop-lightgrey)
+
+**Category:** UI & Experience
+
+## Install
+
+`dsh-side-memo` is [published on npm](https://www.npmjs.com/package/dsh-side-memo). Install it through your DSH profile:
+
+```bash
+dsh plugin --profile web add dsh-side-memo
+```
+
+The same plugin can also be installed straight from this repository — use the GitHub form when you need a commit that is not on npm yet, or when npm is unreachable:
+
+```bash
+dsh plugin --profile web add github:r48n34/dsh-side-memo
+```
+
+If your DSH runs the Desktop profile, use the profile name shown in **Settings → Plugins** (for the Desktop app this is usually `desktop`):
+
+```bash
+dsh plugin --profile desktop add dsh-side-memo
+```
+
+After installing, the **Side Memo** icon is already available in the Session header — at the header's right edge, including before any Session exists (the first screen) and on the new-Session welcome screen. Open it from there, from the Session header's right-side utilities, or from the right sidebar's add/guide control. If the icon does not appear, restart DSH once so the new plugin bundle is loaded.
+
+To remove it, use **Settings → Plugins** in DSH (or the equivalent `dsh plugin` command for your profile).
+
+## What it does
+
+- **Quick notes:** Open notes beside your chat, or in a floating drawer before a Session starts.
+- **Drag into chat:** Drag a memo from the list onto the chat box to paste its text into the message you are writing.
+- **Stay organized:** Search notes, add labels, filter or group by label, and pin favorites.
+- **Add images:** Paste or drag images into notes, or use the image button.
+- **Resize images:** Select an inline image for a Photoshop-style transform box, then drag a handle, nudge with the arrow keys, or reset it to its original size.
+- **Copy and transfer:** Copy notes in one click; import or export notes as Excel workbooks.
+- **Save locally:** Notes and images stay in your browser and are available across Sessions.
+
+## Usage
+
+1. Click the **Side Memo** icon at the right of the conversation header to open or close the panel.
+2. Click **New** and start writing. Changes save automatically; you can also create a note from the editor.
+3. Add labels below the title, or paste, drag in, or insert an image. Click an image to select it: a brand-colored outline, eight resize handles and a `W × H` size badge appear. Drag a handle to resize — corners and edges keep the aspect ratio, `Shift`-drag distorts freely and `Alt`-drag resizes from the center — press the arrow keys to step by 8 px (`Shift`+arrow changes one axis only), and double-click the image or click the overlay's reset button to restore its original size. Press `Escape` or click elsewhere in the editor to deselect it. Use the star to pin a favorite and the copy icon to copy a note.
+4. Search or use the label filters and **Group by label** to find notes. Use the toolbar's import/export icons to transfer notes as `.xlsx` files.
+5. While writing a message, drag a memo from the list onto the chat box; its text is inserted at the caret in your draft, and the memo's images stay in the panel.
+
+Imports add new notes without overwriting existing ones. Images remain local and are not included in Excel exports. An image's chosen display size is saved with the memo, so it survives reloads; resizing only changes how the stored image is shown, not the stored image itself.
+
+## Compatibility
+
+- DeepSeek Harness **0.2.x** (developed and tested against **0.2.1-rc.3**, Desktop profile).
+- Web GUI and Desktop (Electron/Chromium). The client half relies on standard browser APIs: `localStorage`, IndexedDB, Clipboard, File API, `Blob`/`URL`, Canvas, and `DecompressionStream('deflate-raw')` for reading compressed `.xlsx` files.
+- Uses the shipped right-sidebar plugin API (`@deepseek-ai/dsh-client-ui-sidebar-right`); the panel is a normal right-sidebar tab, so a Session is required to host it. Before any Session exists the same notes UI is rendered by the plugin itself in the frame-level overlay layer (`shell.overlay`). In the pre-Session and new-Session phases the toggle mounts through the resident header's `conversation.header.leading` seat and positions itself at the header's right edge from the live header/panel-toggle geometry.
+- Uses the conversation client's composer insertion API (`inputActions`) to paste a dragged memo into the chat draft as a single undoable edit.
+- TypeScript sources live under `src/`; `client.js` and `index.js` are the compiled browser and Host modules committed to the repository, so installing or running the plugin never needs a build step.
+
+## Permissions & privacy
+
+- **No network access** and no external services.
+- **No Host data access** and no agent-facing tools. The Host half is an empty `apply()`.
+- Memos and images stay in this browser (`localStorage` for notes, under the `dsh.side-memo.notes.v1` key; IndexedDB for image data, under the `dsh-side-memo-images` database); they are not encrypted or synced across devices.
+- Clipboard writes happen only when you click copy.
+- Excel files are read from and written to your machine through the browser's file picker/download — they are never uploaded.
+
+## Known limitations
+
+- Browser-local storage only: no cross-device or cross-browser sync.
+- Without a Session the notes open in the plugin's own floating drawer (the right sidebar itself is Session-scoped); the drawer and the right-sidebar tab are alternative hosts for the same notes.
+- Drag-to-compose needs an open Session with an editable chat box and pastes plain text only: memo images and labels are not transferred.
+- Text is plain text (no Markdown or rich-text formatting); images are the only rich content. Images are downscaled before storage and are not exported to Excel — the `Images` column only holds a count.
+- Image support needs IndexedDB and Canvas. If the browser blocks IndexedDB, the text memos keep working and image insertion is disabled.
+- Excel import reads the first worksheet only; formulas import as their cached values, and rich-text cell formatting is ignored.
+- Limits: 300 memos, 120-character titles, 8,000-character bodies, 12 labels per memo (24 characters each), 20 images per memo (source images up to 24 MB, downscaled to at most 1,400 px at quality 0.82 before storage; display sizes 24–1,400 px), 8 MB `.xlsx` imports (up to 32 MB expanded across at most 64 entries), and a 60 MB total image budget for the browser.
+- Labels are flat tags — no nesting, per-label colors, or separate tag manager — and each label is stored per memo, so renaming one means editing every memo that carries it.
+- Favorites are pinned within the memo list; there is no separate favorites-only view yet.
+
+## Development
+
+TypeScript sources live under `src/` and compile to the committed `client.js` / `index.js` with the TypeScript compiler only (no bundler):
+
+| File | Role |
+|---|---|
+| `package.json` | Bundle/client manifest (`dsh.bundle` patch and `dsh.client` browser module) |
+| `cordis.patch.yml` | Inserts the `dsh-side-memo` Loader row |
+| `index.js` | Host half (no-op `apply`; generated from `src/host/index.ts`) |
+| `client.js` | Notes panel, tab type, always-available header toggle, pre-Session drawer, localStorage + IndexedDB store, inline-image editor with the resize/transform overlay, label tags/filter/grouping, editor top-bar new-memo button, drag-memo-to-composer paste, `.xlsx` import/export (generated from `src/client/`) |
+| `src/` | TypeScript sources for both halves |
+| `tsconfig.json`, `scripts/build.mjs` | Type-check configuration and the `yarn build` script |
+| `locale/en.json`, `locale/zh.json` | Plugin Manager title and description |
+| `icon.svg` | Plugin artwork |
+
+Load it into a profile with the DSH Plugin Manager (`install_bundle` on this directory) or install it with the commands in [Install](#install). Package contents are limited to the published files — `index.js`, `client.js`, the locale files, `icon.svg`, `package.json` and `cordis.patch.yml`. The TypeScript sources, build script and config never ship, and the published tarball only adds the three READMEs and the LICENSE.
+
+### Tests
+
+- Unit tests: `yarn test` runs `node --test` on Node.js **>=22** after rebuilding the artifacts (`pretest`). Run `yarn install` once for the build toolchain — `typescript` and `@types/react` are the only dev dependencies and the published package has none — then the suite exercises the real helpers in the compiled `client.js`.
+- Browser e2e (optional, dev-only; not part of `yarn test`): see [`test/e2e/README.md`](test/e2e/README.md) for the isolated-profile harness and its suites.
+- CI runs the unit suite on every push and pull request: [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+## License
+
+[MIT](LICENSE) © 2026 Reemo Studio

package/README.zh-CN.md

@@ -0,0 +1,118 @@
+# 侧边便签（Side Memo）
+
+![侧边便签——随时记录，伴你工作](assets/side-memo-banner.png)
+
+**语言：** [English](README.md) · **简体中文** · [繁體中文](README.zh-TW.md)
+
+![侧边便签面板打开时的截图：右侧边栏中可搜索的便签与标签](assets/plugin0_0_1_screenshot.jpg)
+
+一个轻量、可开关的 **右侧便签面板**，为 [DeepSeek Harness](https://deepseek.com/harness) 打造。聊天时随手记下内容——文字、内嵌图片和标签——一键复制，收藏常用便签让它始终置顶，还能把所有便签整体导入或导出为 Excel 工作簿。
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Version](https://img.shields.io/badge/version-1.2.0-4D6BFE)
+[![npm](https://img.shields.io/npm/v/dsh-side-memo?label=npm&color=4D6BFE)](https://www.npmjs.com/package/dsh-side-memo)
+[![CI](https://github.com/r48n34/dsh-side-memo/actions/workflows/ci.yml/badge.svg)](https://github.com/r48n34/dsh-side-memo/actions/workflows/ci.yml)
+![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-0.2.x-4D6BFE)
+![Platform](https://img.shields.io/badge/platform-Web%20%7C%20Desktop-lightgrey)
+
+**分类：** 界面与体验
+
+## 安装
+
+`dsh-side-memo` 已[发布到 npm](https://www.npmjs.com/package/dsh-side-memo)。通过你的 DSH 配置（profile）安装：
+
+```bash
+dsh plugin --profile web add dsh-side-memo
+```
+
+也可以直接从本仓库安装——当需要的提交尚未发布到 npm，或无法访问 npm 时，使用 GitHub 形式：
+
+```bash
+dsh plugin --profile web add github:r48n34/dsh-side-memo
+```
+
+如果你的 DSH 运行的是 Desktop 配置（profile），请使用 **设置 → 插件** 中显示的配置名（Desktop 应用通常是 `desktop`）：
+
+```bash
+dsh plugin --profile desktop add dsh-side-memo
+```
+
+安装后，**侧边便签** 图标就已经在会话标题栏上——位于标题栏右端，包括还没有任何会话时（首屏）以及新会话欢迎页。可以从这里打开它，也可以从会话标题栏右侧的功能区，或右侧边栏的添加/引导控件打开。如果没有看到图标，请重启一次 DSH，让新的插件包完成加载。
+
+要移除它，请在 DSH 的 **设置 → 插件** 中操作（或使用与你的配置对应的 `dsh plugin` 命令）。
+
+## 功能
+
+- **便签面板** —— 通过标题栏开关打开；有会话时显示在右侧边栏，没有会话时显示浮动抽屉。
+- **编辑与收藏** —— 自动保存便签；收藏置顶，其余按更新时间排序。编辑器可直接新建便签，并复用空白草稿；删除需二次确认。
+- **内嵌图片** —— 粘贴、插入或拖放图片；图片缩小后保存在本地，可在编辑器中移除。
+- **调整图片大小** —— 点选内嵌图片会出现 Photoshop 式变换框，可拖动手柄、用方向键微调，或一键还原原始大小。
+- **标签与搜索** —— 搜索标题、正文和标签；可按多个标签同时筛选或按标签分组。每条便签最多 12 个标签，每个最多 24 个字符，重复标签不区分大小写。
+- **快速复制** —— 复制正文，正文为空时复制标题；只有图片的便签复制第一张图片。
+- **拖入聊天框** —— 把列表中的便签直接拖到聊天输入框上，正文会粘贴到正在编辑的消息里。
+- **Excel 导入 / 导出** —— 导出全部便签到 `.xlsx`，或追加导入便签，不覆盖现有内容。图片本身不会导出，`Images` 列仅记录数量。
+- **本地保存** —— 便签和图片引用存于浏览器的 `localStorage`，图片数据存于 IndexedDB；刷新后保留，并在会话间共享。
+
+## 使用方法
+
+1. 点击标题栏右端的 **侧边便签** 图标。没有会话时打开浮动抽屉，可按 `Esc` 或点击关闭按钮收起；建立会话后便签会移至右侧边栏。
+2. 点击 **新建**，输入标题和正文，编辑会自动保存。编辑器顶栏也可直接新建便签。粘贴、拖放图片或使用图片按钮添加图片；悬停图片并点击 **×** 可移除。点击图片即可选中：会出现品牌色边框、8 个缩放手柄和 `W × H` 尺寸标记；拖动手柄缩放（角和边默认保持宽高比，按住 `Shift` 自由变形，按住 `Alt` 从中心缩放），按方向键每次调整 8 px（`Shift`+方向键只调整单轴），双击图片或点击浮层上的还原按钮可恢复原始大小。按 `Esc` 或点击编辑器其他位置即可取消选择。
+3. 在 **添加标签…** 中输入标签，按 `Enter`、输入 `,` 或点击别处提交；点击标签的 **×** 可移除。列表支持搜索、标签筛选和分组；多选标签时仅显示包含全部所选标签的便签，**全部标签** 可清除筛选。
+4. 点击便签编辑，用星标收藏或复制图标复制。工具栏可导出全部便签到 `side-memo-YYYY-MM-DD.xlsx`，或追加导入首个工作表；标题和正文均为空的行会跳过，文件上限为 8 MB。
+5. 写消息时可以直接把便签从列表拖到聊天输入框：正文会插入到当前光标位置，便签中的图片不会随文字一起粘贴。
+6. 再次点击标题栏图标或使用侧边栏收起控件，隐藏面板。
+
+## 兼容性
+
+- DeepSeek Harness **0.2.x**（在 **0.2.1-rc.3**、Desktop 配置下开发和测试）。
+- Web GUI 与 Desktop（Electron/Chromium）。客户端部分只依赖标准浏览器 API：`localStorage`、IndexedDB、Clipboard、File API、`Blob`/`URL`、Canvas，以及用于读取压缩 `.xlsx` 文件的 `DecompressionStream('deflate-raw')`。
+- 使用内置的右侧边栏插件 API（`@deepseek-ai/dsh-client-ui-sidebar-right`）；面板是标准的右侧边栏标签页，因此需要一个会话来承载它。在任何会话出现之前，同一套便签界面由插件自己在框架级覆盖层（`shell.overlay`）中渲染。在会话建立前和新会话阶段，开关通过常驻标题栏的 `conversation.header.leading` 位置挂载，并根据实时的标题栏/面板开关几何信息把自己定位到标题栏右端。
+- 使用会话客户端的输入框插入 API（`inputActions`）把拖入的便签作为一次可撤销的编辑写入聊天草稿。
+- TypeScript 源码位于 `src/`；`client.js` 与 `index.js` 是由源码编译并提交到仓库的浏览器/宿主模块，因此安装或运行插件都不需要构建步骤。
+
+## 权限与隐私
+
+- **不访问网络**，也不使用任何外部服务。
+- **不访问宿主数据**，不提供面向智能体的工具。宿主部分只有一个空的 `apply()`。
+- 便签和图片只保存在当前浏览器中（便签存于 `localStorage` 的 `dsh.side-memo.notes.v1` 键，图片数据存于 `dsh-side-memo-images` 这个 IndexedDB 数据库）；不加密，也不会跨设备同步。
+- 只有在你点击复制时才会写入剪贴板。
+- Excel 文件通过浏览器的文件选择器/下载在你的电脑上读写——绝不会被上传。
+
+## 已知限制
+
+- 仅支持浏览器本地存储：不支持跨设备或跨浏览器同步。
+- 没有会话时，便签会在插件自带的浮动抽屉中打开（右侧边栏本身是会话级的）；抽屉和右侧边栏标签页是同一套便签的不同宿主。
+- 拖入聊天框需要已建立会话且输入框可编辑；只会粘贴便签的纯文本，图片和标签不会随文字一起粘贴。
+- 文本是纯文本（不支持 Markdown 或富文本格式）；图片是唯一的富内容。图片在保存前会被缩小，也不会导出到 Excel——`Images` 列只记录数量。所选显示尺寸随便签保存，刷新后仍会保留；它只改变图片的显示方式，不会重新编码或替换已保存的图片。
+- 图片功能依赖 IndexedDB 和 Canvas。如果浏览器禁用了 IndexedDB，文字便签仍可正常使用，但插入图片会被禁用。
+- Excel 导入只读取第一个工作表；公式按其缓存值导入，富文本单元格格式会被忽略。
+- 上限：300 条便签、标题 120 字符、正文 8,000 字符、每条便签 12 个标签（每个 24 字符）、每条便签 20 张图片（单张源图片不超过 24 MB，保存前会缩小到最长边 1,400 像素、质量 0.82，显示尺寸限制在 24–1,400 像素）、`.xlsx` 文件 8 MB（解压后总量不超过 32 MB，压缩包内最多 64 个条目），以及浏览器图片总量 60 MB。
+- 标签是扁平标签——不支持层级、按标签着色或独立的标签管理器——而且每个标签都按便签单独存储，所以重命名一个标签意味着要编辑所有带有它的便签。
+- 收藏只是固定在便签列表内；目前还没有单独的“仅收藏”视图。
+
+## 开发
+
+TypeScript 源码位于 `src/`，仅用 TypeScript 编译器（不含打包器）编译为提交在仓库中的 `client.js` 与 `index.js`：
+
+| 文件 | 作用 |
+|---|---|
+| `package.json` | Bundle/客户端清单（`dsh.bundle` 补丁与 `dsh.client` 浏览器模块） |
+| `cordis.patch.yml` | 插入 `dsh-side-memo` 的 Loader 行 |
+| `index.js` | 宿主部分（空的 `apply`；由 `src/host/index.ts` 生成） |
+| `client.js` | 便签面板、标签页类型、始终可用的标题栏开关、会话前抽屉、localStorage + IndexedDB 存储、内嵌图片编辑器（含缩放/变换浮层）、标签筛选/分组、编辑器顶栏新建按钮、拖入聊天框粘贴、`.xlsx` 导入/导出（由 `src/client/` 生成） |
+| `src/` | 两部分的 TypeScript 源码 |
+| `tsconfig.json`、`scripts/build.mjs` | 类型检查配置与 `yarn build` 脚本 |
+| `locale/en.json`、`locale/zh.json` | 插件管理器的标题和描述 |
+| `icon.svg` | 插件图标 |
+
+可以用 DSH 插件管理器（对本目录调用 `install_bundle`）把它加载到某个配置中，或用 [安装](#安装) 中的命令安装。包内容仅限上表列出的运行时文件——源码与构建脚本不会进入发布包，npm tarball 只是在这些运行时资源之外附带三个 README 和 LICENSE。
+
+### 测试
+
+- 单元测试：`yarn test` 会先重新构建（`pretest`），再用 Node.js 内置的 `node --test` 运行（需要 Node.js **>=22**）。首次运行请执行一次 `yarn install` 安装构建工具链——开发依赖仅有 `typescript` 与 `@types/react`，发布的包本身没有依赖——测试会直接调用编译后的 `client.js` 中的真实辅助函数。
+- 浏览器端到端测试（可选，仅开发使用，不包含在 `yarn test` 中）：参见 [`test/e2e/README.md`](test/e2e/README.md)，了解隔离配置下的测试环境与运行方式。
+- CI 在每次 push 和 pull request 时运行单元测试：[`.github/workflows/ci.yml`](.github/workflows/ci.yml)。
+
+## 许可证
+
+[MIT](LICENSE) © 2026 Reemo Studio

package/README.zh-TW.md

@@ -0,0 +1,119 @@
+# 側邊便箋（Side Memo）
+
+![側邊便箋——隨時記錄，伴你工作](assets/side-memo-banner.png)
+
+**語言：** [English](README.md) · [简体中文](README.zh-CN.md) · **繁體中文**
+
+![側邊便箋面板開啟時的截圖：右側邊欄中可搜尋的便箋與標籤](assets/plugin0_0_1_screenshot.jpg)
+
+一個輕量、可開關的 **右側便箋面板**，為 [DeepSeek Harness](https://deepseek.com/harness) 打造。聊天時隨手記下內容——文字、內嵌圖片與標籤——一鍵複製，收藏常用便箋讓它始終置頂，還能把所有便箋整批匯入或匯出為 Excel 活頁簿。
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Version](https://img.shields.io/badge/version-1.2.0-4D6BFE)
+[![npm](https://img.shields.io/npm/v/dsh-side-memo?label=npm&color=4D6BFE)](https://www.npmjs.com/package/dsh-side-memo)
+[![CI](https://github.com/r48n34/dsh-side-memo/actions/workflows/ci.yml/badge.svg)](https://github.com/r48n34/dsh-side-memo/actions/workflows/ci.yml)
+![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-0.2.x-4D6BFE)
+![Platform](https://img.shields.io/badge/platform-Web%20%7C%20Desktop-lightgrey)
+
+**分類：** 介面與體驗
+
+## 安裝
+
+`dsh-side-memo` 已[發佈到 npm](https://www.npmjs.com/package/dsh-side-memo)。透過你的 DSH 設定檔（profile）安裝：
+
+```bash
+dsh plugin --profile web add dsh-side-memo
+```
+
+也可以直接從這個儲存庫安裝——當需要的提交尚未發佈到 npm，或無法連線到 npm 時，使用 GitHub 形式：
+
+```bash
+dsh plugin --profile web add github:r48n34/dsh-side-memo
+```
+
+如果你的 DSH 執行的是 Desktop 設定檔（profile），請使用 **設定 → 外掛**（Settings → Plugins）中顯示的設定檔名稱（Desktop 應用程式通常是 `desktop`）：
+
+```bash
+dsh plugin --profile desktop add dsh-side-memo
+```
+
+安裝後，**側邊便箋** 圖示已經出現在工作階段標題列上——位於標題列最右側，包括尚未建立任何工作階段時（首屏）以及新工作階段歡迎畫面。你可以從那裡開啟它，也可以從工作階段標題列右側的功能區，或右側邊欄的加入/引導控制項開啟。如果沒看到圖示，請重新啟動 DSH 一次，讓新的外掛套件完成載入。
+
+要移除它，請在 DSH 的 **設定 → 外掛** 中操作（或使用與你的設定檔對應的 `dsh plugin` 指令）。
+
+## 功能
+
+- **便箋面板** —— 透過標題列開關開啟；尚無工作階段時使用浮動抽屜，建立後改用右側邊欄分頁。
+- **編輯與收藏** —— 便箋自動儲存；收藏置頂，其餘依更新時間排序。可在編輯器直接新增便箋，空白草稿會被沿用；刪除需按兩次確認。
+- **圖片與複製** —— 可貼上、插入或拖放圖片，圖片會縮小並儲存在本機。複製時使用內文，內文為空時使用標題；只有圖片的便箋會複製第一張圖片。
+- **調整圖片大小** —— 點選內嵌圖片會出現 Photoshop 式變形框，可拖曳控點、用方向鍵微調，或一鍵還原原始大小。
+- **拖入聊天框** —— 把清單中的便箋直接拖到聊天輸入框上，內文會貼到正在編輯的訊息裡。
+- **標籤與搜尋** —— 搜尋標題、內文和標籤；每則最多 12 個標籤、每個最多 24 字元，重複標籤不分大小寫。可篩選同時符合多個標籤的便箋，或依標籤分組。
+- **Excel 匯入 / 匯出** —— 匯出所有便箋為 `.xlsx`，或附加匯入新便箋，不覆寫現有內容。圖片不會匯出，`Images` 欄僅記錄數量。
+- **本機保存** —— 便箋及圖片參照存於瀏覽器的 `localStorage`，圖片資料存於 IndexedDB；重新載入後保留，並在工作階段間共用。
+
+## 使用方式
+
+1. 點標題列最右側的 **側邊便箋** 圖示。尚無工作階段時會開啟浮動抽屜，可按 `Esc` 或關閉按鈕關閉；建立工作階段後會切換至右側邊欄。
+2. 點 **新增**，輸入標題與內文；編輯會自動儲存。編輯器頂端的 **新增** 可直接建立下一則便箋。
+   - 貼上、用圖片按鈕插入或拖放圖片；移到圖片上點 **×** 可移除。點選圖片即可選取：會出現品牌色外框、8 個縮放控點和 `W × H` 尺寸標記；拖曳控點縮放（邊角預設保持長寬比，按住 `Shift` 自由變形，按住 `Alt` 以中心縮放），按方向鍵每次調整 8 px（`Shift`+方向鍵只調整單軸），雙擊圖片或點擊覆蓋層上的還原按鈕可恢復原始大小。按 `Esc` 或點擊編輯器其他位置即可取消選取。
+   - 在 **新增標籤…** 輸入標籤，按 `Enter`、輸入逗號或點到別處即可新增；點標籤上的 **×** 可移除。
+3. 點便箋編輯，用星號收藏或複製圖示複製。使用搜尋、標籤篩選或 **依標籤分組** 整理清單；**全部標籤** 可清除篩選。
+4. 用工具列匯入 / 匯出圖示處理 Excel。匯入只讀取第一個工作表、略過標題與內文皆空白的資料列，檔案上限為 8 MB。
+5. 撰寫訊息時，可直接把便箋從清單拖到聊天輸入框：內文會插入到目前游標位置，便箋中的圖片不會隨文字一起貼上。
+6. 再點一次標題列圖示或使用側邊欄收合控制項，即可隱藏面板。
+
+## 相容性
+
+- DeepSeek Harness **0.2.x**（在 **0.2.1-rc.3**、Desktop 設定檔下開發與測試）。
+- Web GUI 與 Desktop（Electron/Chromium）。用戶端部分只依賴標準瀏覽器 API：`localStorage`、IndexedDB、Clipboard、File API、`Blob`/`URL`、Canvas，以及用來讀取壓縮 `.xlsx` 檔的 `DecompressionStream('deflate-raw')`。
+- 使用內建的右側邊欄外掛 API（`@deepseek-ai/dsh-client-ui-sidebar-right`）；面板是標準的右側邊欄分頁，因此需要一個工作階段來承載它。在任何工作階段出現之前，同一套便箋介面由外掛本身在框架層覆蓋層（`shell.overlay`）中繪製。在工作階段建立前與新工作階段階段，開關會透過常駐標題列的 `conversation.header.leading` 位置掛載，並依即時的標題列/面板開關幾何資訊，把自己定位在標題列最右側。
+- 使用工作階段用戶端的輸入框插入 API（`inputActions`）把拖入的便箋以單次可復原的編輯寫入聊天草稿。
+- TypeScript 原始碼位於 `src/`；`client.js` 與 `index.js` 是由原始碼編譯並提交到儲存庫的瀏覽器/Host 模組，因此安裝或執行外掛都不需要建置步驟。
+
+## 權限與隱私
+
+- **不存取網路**，也不使用任何外部服務。
+- **不存取 Host 資料**，不提供任何給代理程式（agent）使用的工具。Host 端只有空的 `apply()`。
+- 便箋與圖片只留在目前瀏覽器（便箋存於 `localStorage` 的 `dsh.side-memo.notes.v1` 鍵，圖片資料存於 `dsh-side-memo-images` 這個 IndexedDB 資料庫）；不會加密，也不會跨裝置同步。
+- 只有在你點擊複製時才會寫入剪貼簿。
+- Excel 檔透過瀏覽器的檔案選擇器/下載在你的電腦上讀寫——絕不會被上傳。
+
+## 已知限制
+
+- 僅限瀏覽器本機儲存：無法跨裝置或跨瀏覽器同步。
+- 沒有工作階段時，便箋會在外掛自帶的浮動抽屜中開啟（右側邊欄本身是工作階段範圍的）；抽屜與右側邊欄分頁是同一套便箋的兩種不同宿主。
+- 拖入聊天框需要已建立工作階段且輸入框可編輯；只會貼上便箋的純文字，圖片與標籤不會隨文字一起貼上。
+- 文字為純文字（不支援 Markdown 或富文字格式）；圖片是唯一的豐富內容。圖片在儲存前會先縮小，也不會匯出到 Excel——`Images` 欄只記錄數量。所選顯示尺寸會隨便箋儲存，重新載入後仍會保留；它只改變圖片的顯示方式，不會重新編碼或取代已儲存的圖片。
+- 圖片功能需要 IndexedDB 與 Canvas。若瀏覽器封鎖 IndexedDB，文字便箋仍可正常運作，但插入圖片會被停用。
+- Excel 匯入只讀取第一個工作表；公式會以其快取值匯入，儲存格中的富文字格式會被忽略。
+- 上限：300 則便箋、標題 120 個字元、內文 8,000 個字元、每則便箋 12 個標籤（每個 24 個字元）、每則便箋 20 張圖片（單張來源圖片不超過 24 MB，儲存前會縮小到最長邊 1,400 像素、品質 0.82，顯示尺寸限制在 24–1,400 像素）、`.xlsx` 檔 8 MB（解壓後總量不超過 32 MB，壓縮檔內最多 64 個項目），以及瀏覽器圖片總量 60 MB。
+- 標籤是扁平標籤——不支援階層、個別標籤顏色或獨立的標籤管理員——而且每個標籤都以個別便箋為單位儲存，所以重新命名一個標籤必須編輯所有帶有它的便箋。
+- 收藏只固定在便箋清單內；目前尚未提供只顯示收藏的檢視。
+
+## 開發
+
+TypeScript 原始碼位於 `src/`，僅用 TypeScript 編譯器（不含打包器）編譯成提交在儲存庫中的 `client.js` 與 `index.js`：
+
+| 檔案 | 用途 |
+|---|---|
+| `package.json` | Bundle/用戶端資訊清單（`dsh.bundle` 修補與 `dsh.client` 瀏覽器模組） |
+| `cordis.patch.yml` | 插入 `dsh-side-memo` 的 Loader 列 |
+| `index.js` | Host 端（空的 `apply`；由 `src/host/index.ts` 產生） |
+| `client.js` | 便箋面板、分頁類型、隨時可用的標題列開關、工作階段前抽屜、localStorage + IndexedDB 儲存、內嵌圖片編輯器（含縮放/變形覆蓋層）、標籤篩選/分組、編輯器頂端列新增便箋按鈕、拖入聊天框貼上、`.xlsx` 匯入/匯出（由 `src/client/` 產生） |
+| `src/` | 兩部分的 TypeScript 原始碼 |
+| `tsconfig.json`、`scripts/build.mjs` | 型別檢查設定與 `yarn build` 腳本 |
+| `locale/en.json`、`locale/zh.json` | 外掛管理員的標題與說明 |
+| `icon.svg` | 外掛圖示 |
+
+可以用 DSH 外掛管理員（對此目錄呼叫 `install_bundle`）把它載入某個設定檔，或使用 [安裝](#安裝) 中的指令安裝。套件內容僅限上表所列的執行時檔案——原始碼與建置腳本不會進入發布套件，npm tarball 只是在這些執行時資源之外附帶三個 README 與 LICENSE。
+
+### 測試
+
+- 單元測試：`yarn test` 會先重新建置（`pretest`），再使用 Node.js 內建的 `node --test` 執行（需要 Node.js **>=22**）。第一次執行請先 `yarn install` 安裝建置工具鏈——開發相依套件只有 `typescript` 與 `@types/react`，發布的套件本身沒有相依套件——測試會直接呼叫編譯後的 `client.js` 中的真實輔助函式。
+- 瀏覽器端對端測試（選用，僅供開發使用，不包含在 `yarn test` 中）：參見 [`test/e2e/README.md`](test/e2e/README.md)，了解隔離設定檔下的測試環境與執行方式。
+- CI 會在每次 push 和 pull request 時執行單元測試：[`.github/workflows/ci.yml`](.github/workflows/ci.yml)。
+
+## 授權條款
+
+[MIT](LICENSE) © 2026 Reemo Studio