dsh-sideby-note 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.en.md ADDED
@@ -0,0 +1,302 @@
1
+ # Sideby Note · 边记部
2
+
3
+ Asynchronously draft your ideas while the agent is working
4
+
5
+ [中文](README.md) | English
6
+
7
+ > **Personal fork notice:** This is a personal adaptation of [dsh-aside-note](https://github.com/Rayle8/dsh-aside-note) (旁边记 / AsideNote), based and inspired by the original project; most of the text below is preserved from the original README. Main differences from the original:
8
+ >
9
+ > - Display name and copy are **Sideby Note** (边记部); the package name, plugin id and update channel are the fork's `dsh-sideby-note`, installed with `npx dsh-sideby-note install`.
10
+ > - **Anonymous feature statistics removed:** the Tencent Cloud RUM SDK, reporting code, Settings › Privacy switch and related local storage keys are gone, so no usage events are sent.
11
+ > - Local storage keys keep the upstream `dsh.aside-note.*` names, so existing notes and settings carry over after the rename.
12
+ > - The README screenshots come from this fork, not upstream.
13
+
14
+ Jot it down · Open as needed · Tuck it away
15
+
16
+ Sideby Note is a lightweight session notes plugin for DeepSeek Harness (DSH). Keep passing thoughts and follow-ups beside the conversation, bring them back to the chat input when needed, then tuck the panel away and carry on.
17
+
18
+ ## Preview and entry
19
+
20
+ ![Sideby Note right-side panel](./docs/assets/preview-right.png)
21
+
22
+ The same panel in the dark theme; every colour comes from DSH theme tokens:
23
+
24
+ ![Sideby Note right-side panel, dark](./docs/assets/preview-right-dark.png)
25
+
26
+ A **Sideby Note** button at the top right of the conversation, with the open count:
27
+
28
+ <img src="./docs/assets/preview-badge.png" width="460" alt="Sideby Note button at the top right">
29
+
30
+ The same button in the dark theme:
31
+
32
+ <img src="./docs/assets/preview-badge-dark.png" width="460" alt="Sideby Note button at the top right, dark">
33
+
34
+ Clicking the entry opens a fixed panel on the right. A blank new session has no conversation header yet, so the button sits in the top-right corner beside the right-sidebar control and shows the workspace list only until the first message.
35
+
36
+ ## Quick install
37
+
38
+ Sideby Note installs into a DSH profile as the npm package `dsh-sideby-note`. Pick one: hand the prompt to an agent, or run a single command.
39
+
40
+ ### Install with an agent
41
+
42
+ Give your agent this block:
43
+
44
+ ```text
45
+ Install the DSH plugin Sideby Note by running: npx -y dsh-sideby-note install
46
+ No DSH restart is needed afterwards: the 边记部 entry is at the top right of the conversation.
47
+ If it is missing, tell me to refresh the Plugins page and switch the plugin off and on once.
48
+ If it says DSH or a profile cannot be found, tell me to install and start the DeepSeek Harness
49
+ client first and retry; do not clone the repo, hand-assemble dependencies, or restart DSH.
50
+ ```
51
+
52
+ ### Install from the command line
53
+
54
+ ```bash
55
+ npx dsh-sideby-note install
56
+ ```
57
+
58
+ The installer pulls this package from npm, finds the DSH profile (it honours `DSH_PROFILE_DIR`, otherwise `~/.dsh/profiles/desktop`), backs up `package.json` and `pnpm-lock.yaml` into `.local-backup/`, adds the dependency, appends `dsh-sideby-note` to `dsh.profile.bundles`, runs `pnpm install` **through the node and pnpm DeepSeek Harness ships** (falling back to the pnpm on PATH, and `DSH_RUNTIME_DIR` pins a runtime) and finally verifies the installed `client/client.js`. The host's own toolchain keeps the profile's pnpm store in step with the host — a profile written by another pnpm major answers `ERR_PNPM_UNEXPECTED_STORE` on the host's next install.
59
+
60
+ ```bash
61
+ npx dsh-sideby-note install --profile work # pick a profile
62
+ npx dsh-sideby-note install --dry-run # print the plan, write nothing
63
+ npx dsh-sideby-note install --version 0.1.0 # pin the version instead of ^0.1.0
64
+ ```
65
+
66
+ It is safe to re-run. No restart is needed: DSH re-composes the profile within about a second, and the 边记部 entry appears at the top right of the conversation. If it does not, refresh the sidebar **Plugins** page and toggle the plugin off and on once — the running host recomposes and the entry appears.
67
+
68
+ To uninstall, drop `dsh-sideby-note` from `dsh.profile.bundles`, run `pnpm remove dsh-sideby-note` in the profile directory, and no restart is needed: the entry disappears right away, and if the **Plugins** page still lists it, refresh that page.
69
+
70
+ ## Why Sideby Note
71
+
72
+ Working with AI often brings up things you want to revisit: a detail to change later, a result to double-check, or an idea to explore next.
73
+
74
+ Sending them straight into the conversation can interrupt the task at hand. Writing them somewhere else means finding them again later. Sideby Note keeps them beside the conversation so you can jot them down and carry on.
75
+
76
+ A few small tasks should not need a whole management system. Capture a thought, look back when you need it, and let it go when you are done. Open the panel on your terms and tuck it away afterward, with little interruption to the work at hand.
77
+
78
+ ## From a quick note to the next step
79
+
80
+ ### Capture it and keep going
81
+
82
+ Click the **Sideby Note** button at the top right of the conversation to open the right-side panel. Record tasks, ideas, and details to revisit. The button shows the unfinished count; check off each item as you finish it.
83
+
84
+ ### Keep it in the workspace and pick it up later
85
+
86
+ Sessions in one workspace share a single list by default: whichever session you open, you see the same tasks. The panel header also switches between **Workspace** and **Session** — workspace covers the whole workspace, session covers only the current conversation. Sessions outside a workspace have no workspace scope and always stay per-session. On first open, notes already recorded in member sessions are folded into the workspace list once, so nothing is lost.
87
+
88
+ ### Bring it back when you are ready
89
+
90
+ Click a note's forward button to append it to the current chat input as a list item. Add to or edit it, then send when you are ready. You can customize the prefix prompt, which is added only when the input is empty. Forwarding never sends the message automatically or marks the note as completed.
91
+
92
+ ### Small details for everyday use
93
+
94
+ - **Saved drafts**: close the panel and pick up where you left off when you reopen it; conversations in one workspace share the same draft, so switching conversations does not mean retyping.
95
+ - **Completed history**: separate open and completed sections, with creation and completion times.
96
+ - **Adjustable panel**: resize the width and height, with your preferences remembered.
97
+ - **Fits into DSH**: follows the light/dark theme and all eight DSH-official languages (Chinese, English, Japanese, Spanish, French, German, Russian and Brazilian Portuguese).
98
+ - **Browser-local persistence**: records survive page refreshes and DSH restarts, with updates synced across tabs in the same browser.
99
+
100
+ > Notes are stored in the current browser and do not sync across devices or browsers. Clearing site data removes them. See [Where data lives](#where-data-lives).
101
+
102
+ [Quick install](#quick-install) · [Feedback and issues](https://github.com/LighghtEeloo/dsh-sideby-note/issues)
103
+
104
+ ## Features
105
+
106
+ - **Workspace-level notes**: one list is shared by every session in a workspace by default, so switching conversations keeps it in view; the panel header switches between **Workspace** and **Session**, and sessions outside a workspace only have the session scope. Tabs in the same browser stay in sync.
107
+ - **Entry and panel**: an icon button at the top right badges the open count; a blank new session shows it in the corner with the workspace list only until the first message, without the session option; clicking it opens a fixed panel aligned to the entry, which shifts left of the DSH right sidebar and closes when you switch sessions.
108
+ - **Note actions**: add, complete, copy, forward, and rewind a note into the composer to edit; clearing completed notes asks for confirmation, and completed notes expand for review. Clearing the composer after rewinding a note removes it.
109
+ - **One-click forward**: each note is appended to the **currently open conversation's** composer as a `-` item, with the customizable prefix written only when the composer is empty — nothing is sent automatically. The forward button gains a check per list, and clicking it again removes the mark.
110
+ - **Remembered state**: add drafts are saved per workspace (per session outside a workspace), so switching conversations or the Workspace/Session switch never loses them; submitting still writes the list selected at that moment. Drafts are restored when the panel reopens, and the open/completed expand state plus the scope choice are remembered too.
111
+ - **Panel size**: drag the left edge for width and the bottom handle for height, double-click either to reset; both persist in the browser.
112
+ - **List regions**: **Open** and **Completed** each keep a sticky header and its own scroll, and expanding completed never compresses open; completed notes show creation and completion times, newest completion first.
113
+ - **Settings**: send shortcut (Enter or ⌘/Ctrl+Enter), forward prefix, and About (version, check, author, source), saved automatically.
114
+ - **Update notice**: a newer release puts a dot on the settings button, and Settings › About shows the notes and the update action; see [Update notice](#update-notice).
115
+ - **Native look**: colours, radii, elevation and scrollbars all reuse DSH design tokens, following light/dark and the DSH locale; see [Design tokens](#design-tokens).
116
+
117
+ ## Feature screenshots
118
+
119
+ Five states shot from the same demo session and the same set of notes, in both themes:
120
+
121
+ <table>
122
+ <tr>
123
+ <th width="130">Feature</th>
124
+ <th>Light</th>
125
+ <th>Dark</th>
126
+ </tr>
127
+ <tr>
128
+ <td>Panel overview<br>open / completed sections</td>
129
+ <td><img src="./docs/assets/features/panel.png" width="300" alt="Panel overview"></td>
130
+ <td><img src="./docs/assets/features/panel-dark.png" width="300" alt="Panel overview, dark"></td>
131
+ </tr>
132
+ <tr>
133
+ <td>Settings<br>send shortcut, forward prefix, about</td>
134
+ <td><img src="./docs/assets/features/settings.png" width="300" alt="Settings"></td>
135
+ <td><img src="./docs/assets/features/settings-dark.png" width="300" alt="Settings, dark"></td>
136
+ </tr>
137
+ <tr>
138
+ <td>Row actions<br>copy / forward / rewind on hover</td>
139
+ <td><img src="./docs/assets/features/actions.png" width="300" alt="Row actions"></td>
140
+ <td><img src="./docs/assets/features/actions-dark.png" width="300" alt="Row actions, dark"></td>
141
+ </tr>
142
+ <tr>
143
+ <td>Clear completed<br>a second confirmation guards clearing</td>
144
+ <td><img src="./docs/assets/features/clear.png" width="300" alt="Clear completed confirmation"></td>
145
+ <td><img src="./docs/assets/features/clear-dark.png" width="300" alt="Clear completed confirmation, dark"></td>
146
+ </tr>
147
+ <tr>
148
+ <td>Empty state<br>guidance when a session has no notes</td>
149
+ <td><img src="./docs/assets/features/empty.png" width="300" alt="Empty state"></td>
150
+ <td><img src="./docs/assets/features/empty-dark.png" width="300" alt="Empty state, dark"></td>
151
+ </tr>
152
+ </table>
153
+
154
+ ## Design tokens
155
+
156
+ The panel and the entry button read from one token block in `src/client/styles/panel.css`:
157
+
158
+ | Axis | Token | Values |
159
+ | --- | --- | --- |
160
+ | Colour | `--dsw-alias-*` | DSH semantic aliases only (ink, hover, border, state, settings card); no local ramp |
161
+ | Type | `--an-fs-caption/row/title` | 12 / 13 / 14, all on a 20px line height |
162
+ | Weight | 400 / 500 | 500 is the cap; hierarchy comes from size and ink |
163
+ | Spacing | `--an-space-1 … -6` | 4 / 8 / 12 / 16 / 24 / 32 |
164
+ | Radius | `--dsw-radius-sm/md/lg/panel` + 999 | 8 (compact controls) / 16 (groups and fields) / 28 (floating panel) / pills paired with `corner-shape:round` |
165
+ | Shadow | `--dsw-elevation-panel` | the panel is `border:0`; the 0.5px hairline is the shadow's first layer |
166
+ | Material | `--dsh-an-panelSurface` (`--dsw-alias-bg-layer-2`) | opaque panel surface shared with the pinned header |
167
+ | Motion | `--ds-transition-duration*`, `--ds-ease-in-out` | 100 / 200ms, opacity and transform only |
168
+ | Scrollbar | shared theme skin | the panel rebinds `--dsh-scrollbar-*` to l2 and gives the list a 9px rail with a 2px inset |
169
+
170
+ Feedback reuses product surfaces too: copy, forward, rewind, clear-completed, and failed writes all report through a `shell.overlay` toast that outlives the panel, and icon buttons use the `ui-primitives` `Tooltip`.
171
+
172
+ ## Usage
173
+
174
+ 1. Click the **Sideby Note** button at the top right of the conversation to open the right-side panel. Its badge shows the unfinished count when there are open notes; the **Workspace / Session** switch in the panel header moves between the whole workspace and the current conversation.
175
+ 2. Write one concrete follow-up in the panel and use your configured add shortcut or click **Add**.
176
+ 3. To change a note, click its **Rewind** button (↺): the text goes back into the top composer, ready to edit and submit again. Clearing that composer removes the note.
177
+ 4. When you are ready to continue, click the note's forward button to append it to the chat input, then review and send it yourself.
178
+ 5. Click the circle to mark it complete; expand **Completed** to look back.
179
+ 6. Click outside the panel or press Esc to close.
180
+
181
+ ## Where data lives
182
+
183
+ Session notes live in the browser's `localStorage` under `dsh.aside-note` — the upstream key name, kept so data already in the browser loads after the package rename — in the original v1 shape:
184
+
185
+ ```json
186
+ {
187
+ "version": 1,
188
+ "sessions": {
189
+ "session-…": {
190
+ "sessionId": "session-…",
191
+ "updatedAt": 0,
192
+ "items": []
193
+ }
194
+ }
195
+ }
196
+ ```
197
+
198
+ The list shared by one workspace lives separately under `dsh.aside-note.workspaces`:
199
+
200
+ ```json
201
+ {
202
+ "version": 1,
203
+ "workspaces": {
204
+ "workspace-…": {
205
+ "workspaceId": "workspace-…",
206
+ "updatedAt": 0,
207
+ "items": [],
208
+ "seededSessionIds": ["session-…"]
209
+ }
210
+ }
211
+ }
212
+ ```
213
+
214
+ `workspaces` holds the list shared by one workspace; `seededSessionIds` remembers which member sessions were already folded in, so notes are merged once and never resurrect after a delete. Session data stays under the original `dsh.aside-note` key and workspace data is never written back into it; sessions without a workspace only use their `sessions` record. The panel header's scope choice lives separately under `dsh.aside-note.scope-mode` (`workspace` or `session`, default `workspace`).
215
+
216
+ Unsaved add drafts live under `dsh.aside-note.drafts`: sessions in one workspace share a single workspace draft, so switching conversations or the scope never loses text; the submitted note goes to the workspace list or the session list according to the scope selected at that moment. Sessions outside a workspace keep their own draft. The first time a workspace is opened after upgrading, the current session's old draft is folded into the shared one; `edits` records left by the old inline editor are ignored and cleaned up on the next draft write.
217
+
218
+ Therefore:
219
+
220
+ - Refreshing, restarting DSH, or switching sessions keeps the records.
221
+ - Notes already stored by the upstream package load without a migration.
222
+ - Nothing is written into the project or synced to another machine/browser.
223
+ - Clearing site data clears the notes.
224
+ - Reading old data never rewrites the shape of `dsh.aside-note`; workspace lists are read from `dsh.aside-note.workspaces`, and the first visit to a workspace folds its member-session notes in once. Keys like `dsh.aside-notes.*` from earlier builds are not read. If your data still sits under the old `dsh.aside-notes.*.v2` keys, rename them to the matching `dsh.aside-note.*` keys and reload.
225
+
226
+ ## Update notice
227
+
228
+ When the panel opens, the plugin quietly checks the latest published version (npm, falling back to npmmirror and then the latest GitHub Release) and caches the answer for an hour. When a newer version exists, the settings button gains a dot and Settings › About shows the update card:
229
+
230
+ - **Check for updates** re-reads the registry immediately, bypassing that hourly cache, and reports “checking”, “up to date” or a failure underneath.
231
+ - **Notes show by default:** an available update immediately lists the release notes from the GitHub Release body — no disclosure to open. The notes are the block between its `app-update-notes:en` / `app-update-notes:zh` markers, flattened to plain text — no HTML is executed or injected.
232
+ - **Across several versions:** when the published release is several versions ahead, the notes list every release in the gap, newest first. The newest stays open and each older version expands on its own. Drafts and prereleases are skipped, at most six releases are listed, and a link points at the releases page when more were left out.
233
+ - **Full release notes** sits to the right of the update button and opens the matching GitHub Release page in a new tab.
234
+ - **Update now** installs over the running copy through the host's own update route, without going through the plugin market, and offers a page refresh when it finishes.
235
+ - **Manual fallback:** when the host has no update route, or refuses to replace the in-use plugin files, the card states the command with the offered version and profile directory, plus **Copy update prompt** — one click to copy a ready-to-paste instruction for an agent. Prereleases also pin the npmjs registry so the command cannot fall back to the stable line.
236
+
237
+ Updating is always an explicit click: the panel only checks, explains and starts the host update — it never runs a command itself, and your notes are never touched. The check only reads public version numbers and release bodies.
238
+
239
+ Release notes are composed by `tools/release/notes.mjs` from `CHANGELOG.md` — English and Chinese blocks with `app-update-notes` markers, install links and a Full Changelog link — and the tag-triggered workflow creates the Release (with the tarball attached) from it. See [release and versioning](./docs/release.md).
240
+
241
+ ## Development
242
+
243
+ The browser half lives in `src/client/` and tsdown bundles it into a single `client/client.js`:
244
+
245
+ ```bash
246
+ npm install
247
+ npm run check # lint + typecheck + tests + build
248
+ npm run build # regenerate client/client.js only
249
+ ```
250
+
251
+ To run the checkout inside DSH, link it into a profile (replace `<path-to-repo>`) and run `pnpm install` in the profile directory:
252
+
253
+ ```json
254
+ {
255
+ "dependencies": {
256
+ "dsh-sideby-note": "link:<path-to-repo>"
257
+ },
258
+ "dsh": {
259
+ "profile": {
260
+ "bundles": ["dsh-sideby-note"]
261
+ }
262
+ }
263
+ }
264
+ ```
265
+
266
+ After adding the bundle row, toggle it off/on in the sidebar **Plugins** page to recompose a running Host without a restart.
267
+
268
+ The entry is `src/client/index.ts`, which exports `apply(ctx)`; tsdown wraps it in DSH's loader shell:
269
+
270
+ ```js
271
+ window.__ModuleLoader__.load({ id: 'dsh-sideby-note', factory: (require) => { … } })
272
+ ```
273
+
274
+ The artifact is committed: CI rebuilds it and fails when `client/` does not match, so do not edit `client/client.js` by hand.
275
+
276
+ `index.js` is the empty Host half; `cordis.patch.yml` inserts the package into the profile composition. The UI depends on two services, `slots` and `locale`:
277
+
278
+ - `conversation.composer.dock`: used only to capture the active session ID; it renders no visible entry.
279
+ - The top-right entry is injected into the host header with a MutationObserver, because the host's re-render reclaims a React portal there.
280
+
281
+ The panel mounts as its own `react-dom/client` root on `document.body` and follows the trigger with fixed positioning. All styles use DSH's `--dsw-alias-*` theme variables, so light and dark themes work.
282
+
283
+ Run `npm run build` after source changes; the dev client HMR swaps the new bundle, otherwise refresh or restart DSH.
284
+
285
+ The screenshot and preview pipeline lives in the [screenshot SOP](./docs/screenshot-sop.md): one command re-shoots both themes from an isolated profile, and credentials are not copied unless `COPY_CREDENTIALS=1`.
286
+
287
+ Code structure, data model and build conventions: [architecture](./docs/architecture.md).
288
+
289
+ Branching, versioning and the release checklist: [release and versioning](./docs/release.md) (Chinese).
290
+
291
+ ## Verification
292
+
293
+ Loaded in an isolated DSH profile and driven through headless Chrome:
294
+
295
+ - the **Sideby Note** button appears at the top right, with the open count on its badge;
296
+ - clicking it opens the panel on the right, aligned with the entry;
297
+ - adding updates both the badge and the panel count;
298
+ - complete, copy, forward, rewind into the composer, and clear-completed work in the panel;
299
+ - records survive a refresh, and the panel header switches between the workspace list and the current session's list;
300
+ - the npmjs → npmmirror → GitHub Release fallback, the one-hour cache, and the version comparison are covered by the contract tests, and the jsdom test drives the visible update notice; the live notice needs a published npm package or a GitHub Release.
301
+
302
+ `npm run check` passes: lint, typecheck, build, and 126 tests, including jsdom integration tests that drive the whole panel, expand the release notes, run an update through the host route, and check the busy and no-route fallbacks.
package/README.md CHANGED
@@ -1,3 +1,302 @@
1
- # Temporary Holding Version
1
+ # 边记部 · Sideby Note
2
2
 
3
- 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.
3
+ 当主代理大功告成之际,过去的你异步发出的思绪将如闪电般归来
4
+
5
+ [English](README.en.md) | 中文
6
+
7
+ > **个人改版说明**:本项目基于并受 [dsh-aside-note](https://github.com/Rayle8/dsh-aside-note)(旁边记 / AsideNote)启发,仅作个人使用,正文大部分保留自原 README。与上游的主要区别:
8
+ >
9
+ > - 界面名称与文案改为「边记部 / Sideby Note」;包名、插件 id 与更新通道改为本仓库的 `dsh-sideby-note`,安装命令为 `npx dsh-sideby-note install`。
10
+ > - **移除匿名功能统计**:不再内置腾讯云 RUM SDK,不发送任何使用事件;设置 › 隐私中的统计开关与相关本地存储键一并移除。
11
+ > - 本地存储键沿用上游的 `dsh.aside-note.*`,升级后已有便笺与设置无需迁移。
12
+ > - README 截图来自本改版,而非上游版本。
13
+
14
+ 轻量记录 · 按需打开 · 用完收起
15
+
16
+ 边记部是面向 DeepSeek Harness(DSH)的轻量会话便笺。临时的想法、稍后的待办,随手留在对话旁;需要时一键带回,用完收起,继续眼前的事。
17
+
18
+ ## 界面与入口
19
+
20
+ ![边记部右侧面板](./docs/assets/preview-right.png)
21
+
22
+ 暗色主题下外观保持一致,颜色全部取自 DSH 主题令牌:
23
+
24
+ ![边记部右侧面板(暗色)](./docs/assets/preview-right-dark.png)
25
+
26
+ 会话顶部右侧的「边记部」按钮,带未完成数量:
27
+
28
+ <img src="./docs/assets/preview-badge.png" width="460" alt="顶部右侧边记部按钮">
29
+
30
+ 暗色主题下的同一按钮:
31
+
32
+ <img src="./docs/assets/preview-badge-dark.png" width="460" alt="顶部右侧边记部按钮(暗色)">
33
+
34
+ 点击入口后在右侧打开固定面板。空白新会话还没有对话头,按钮落在右上角、右侧栏按钮左侧;发出第一条消息前只显示工作区清单。
35
+
36
+ ## 快速安装
37
+
38
+ 边记部以 npm 包 `dsh-sideby-note` 装进 DSH profile。两种方式选一个:把提示词交给 agent,或自己执行一条命令。
39
+
40
+ ### 通过 agent 安装
41
+
42
+ 把下面这段发给你的 agent:
43
+
44
+ ```text
45
+ 帮我安装 DSH 插件 Sideby Note(边记部),在终端执行:npx -y dsh-sideby-note install
46
+ 装好后不用重启 DSH,会话右上角即可看到「边记部」入口;如果没出现,
47
+ 让我到「插件」页刷新,再把它手动关闭并开启一次。
48
+ 如果提示找不到 DSH 或找不到 profile,转告我先安装并启动 DeepSeek Harness 再重试;
49
+ 不要改仓库、不要手动拼装依赖、不要重启 DSH。
50
+ ```
51
+
52
+ ### 通过命令行安装
53
+
54
+ ```bash
55
+ npx dsh-sideby-note install
56
+ ```
57
+
58
+ 脚本会从 npm 临时拉取本包,找到 DSH profile(存在 `DSH_PROFILE_DIR` 时用它,否则默认 `~/.dsh/profiles/desktop`),先把 `package.json` 和 `pnpm-lock.yaml` 备份到 `.local-backup/`,再写入依赖、把 `dsh-sideby-note` 追加进 `dsh.profile.bundles`,然后用 **DeepSeek Harness 自带的 node 与 pnpm** 执行 `pnpm install`(找不到运行时才回退到 PATH 上的 pnpm,可用 `DSH_RUNTIME_DIR` 指定),最后校验装出来的 `client/client.js`。用宿主自己的工具链是为了让 profile 的 pnpm store 与宿主保持一致——换成另一个主版本的 pnpm 写入,宿主下次安装会报 `ERR_PNPM_UNEXPECTED_STORE`。
59
+
60
+ ```bash
61
+ npx dsh-sideby-note install --profile work # 指定 profile
62
+ npx dsh-sideby-note install --dry-run # 只打印计划,不改任何文件
63
+ npx dsh-sideby-note install --version 0.1.0 # 固定版本,而不是 ^0.1.0
64
+ ```
65
+
66
+ 重复执行是幂等的。装完不需要重启 DSH:profile 会在约 1 秒内重新组合,安装后会话右上角即可看到「边记部」入口。如果入口没有出现,到侧边栏「插件」页刷新,把它关闭再开启一次,运行中的 Host 会重新组合,入口随即可见。
67
+
68
+ 卸载:从 `dsh.profile.bundles` 移除 `dsh-sideby-note`,在 profile 目录执行 `pnpm remove dsh-sideby-note`,无需重启;右上角入口随之消失,若「插件」页里仍列着它,刷新该页即可。
69
+
70
+ ## 为什么做边记部
71
+
72
+ 和 AI 一起做事时,总会冒出一些暂时顾不上的小事:这个细节等会儿改,那段结果还要核对,还有一个思路想留着继续讨论。
73
+
74
+ 先发进对话,容易打断当前任务;记到别处,回来又得重新找。边记部就在会话旁边,让你先把事情记下,继续手头的工作。
75
+
76
+ 不必为几件小事建立一套管理方法。想到就记,需要就看,做完就放下。它只在你需要时打开,用完收起,尽量少打扰当前的工作。
77
+
78
+ ## 从随手记,到继续做
79
+
80
+ ### 想到就记,继续手头的事
81
+
82
+ 点击会话顶部右侧的「边记部」按钮,打开右侧面板,记录待办、补充想法或需要回看的细节。入口显示未完成数量,做完一条,勾掉一条。
83
+
84
+ ### 留在工作区,下次接着做
85
+
86
+ 同一个工作区默认共享一份清单。无论从哪个会话打开,看到的都是同一批事项;面板顶部还能在「工作区」与「会话」之间切换,工作区级汇总整个工作区,会话级只看当前会话。工作区之外的会话没有工作区级,始终按会话保存。第一次打开时,成员会话里已经记下的便笺会自动并入工作区清单,不会丢。
87
+
88
+ ### 准备好了,一键带回对话
89
+
90
+ 点击便笺上的转发按钮,内容就会以列表项追加到当前对话输入框。你可以继续补充、调整,再决定发送。前缀提示词支持自定义,且仅在输入框为空时添加;转发不会自动发送,也不会把便笺标记为完成。
91
+
92
+ ### 日常使用的小细节,也准备好了
93
+
94
+ - **草稿自动保存**:临时关闭面板,再打开接着写;同一工作区的会话共用同一份草稿,切换会话也不用重打。
95
+ - **完成后可回看**:未完成与已完成分区展示,保留创建与完成时间。
96
+ - **面板大小可调整**:宽高按需拖动,记住你的习惯。
97
+ - **融入 DSH 界面**:跟随明暗主题与 DSH 全部八种官方语言(中文、英语、日语、西班牙语、法语、德语、俄语和巴西葡萄牙语)。
98
+ - **当前浏览器持久保存**:刷新页面、重启 DSH 后仍可继续查看;同一浏览器的多个标签页同步更新。
99
+
100
+ > 便笺保存在当前浏览器,不跨设备或浏览器同步;清理站点数据会清除记录。详见[数据保存在哪里](#数据保存在哪里)。
101
+
102
+ [查看安装方法](#快速安装) · [反馈问题或建议](https://github.com/LighghtEeloo/dsh-sideby-note/issues)
103
+
104
+ ## 功能
105
+
106
+ - **工作区级便笺**:同一个工作区默认共享一份清单,切换会话也能接着看;面板顶部可在「工作区 / 会话」之间切换,工作区之外的会话只有会话级。同一浏览器的多个标签页同步更新。
107
+ - **入口与面板**:会话顶部右侧的图标按钮用角标显示未完成数;空白新会话在右上角出现,首轮对话前只提供工作区清单、不显示「会话」选项;点击打开固定面板并与之对齐,DSH 右侧栏打开时自动左移,切换会话时收起。
108
+ - **条目操作**:添加、打勾完成、复制、转发、退回输入框重新编辑;「清除已完成」需要二次确认,已完成的条目可展开回看。退回后清空输入框即等于删除该条。
109
+ - **一键转发**:把便笺按 `- 内容` 追加到**当前打开的会话**输入框,仅当输入框为空时写入可自定义的前缀,不自动发送;转发后按钮显示勾选,按清单记住,再点一次取消。
110
+ - **状态记忆**:新增草稿按工作区自动保存(工作区之外的会话按会话),切换会话或在「工作区 / 会话」之间切换都不会丢;提交时仍写入当前选中的清单。关掉面板再打开会恢复草稿,「未完成 / 已完成」的展开折叠状态与范围选择也会记住。
111
+ - **面板尺寸**:拖左边缘调宽度、拖底部把手调高度,双击复位;宽高都保存在浏览器里。
112
+ - **列表分区**:「未完成」「已完成」各有吸顶标题与独立滚动,展开已完成不会压缩未完成;已完成显示创建与完成时间,并按完成时间倒序。
113
+ - **设置**:发送快捷键(Enter 或 ⌘/Ctrl+Enter)、转发前缀、关于(版本、检查更新、作者、源码),改动自动保存。
114
+ - **更新提示**:有新版本时设置按钮出现提示点,设置 › 关于 可查看更新说明并更新;详见[更新提示](#更新提示)。
115
+ - **界面融入**:颜色、圆角、阴影与滚动条全部复用 DSH 设计令牌,自动适配明暗主题与 DSH 全部官方语言;详见[设计规范](#设计规范)。
116
+
117
+ ## 功能截图
118
+
119
+ 五个主要状态的实拍,明暗同源(同一演示会话、同一批便笺,只切换主题):
120
+
121
+ <table>
122
+ <tr>
123
+ <th width="130">功能</th>
124
+ <th>明色</th>
125
+ <th>暗色</th>
126
+ </tr>
127
+ <tr>
128
+ <td>面板总览<br>未完成 / 已完成分区</td>
129
+ <td><img src="./docs/assets/features/panel.png" width="300" alt="面板总览"></td>
130
+ <td><img src="./docs/assets/features/panel-dark.png" width="300" alt="面板总览(暗色)"></td>
131
+ </tr>
132
+ <tr>
133
+ <td>设置<br>发送快捷键、一键转发前缀、关于</td>
134
+ <td><img src="./docs/assets/features/settings.png" width="300" alt="设置"></td>
135
+ <td><img src="./docs/assets/features/settings-dark.png" width="300" alt="设置(暗色)"></td>
136
+ </tr>
137
+ <tr>
138
+ <td>行操作<br>悬浮显示复制 / 转发 / 退回</td>
139
+ <td><img src="./docs/assets/features/actions.png" width="300" alt="行操作"></td>
140
+ <td><img src="./docs/assets/features/actions-dark.png" width="300" alt="行操作(暗色)"></td>
141
+ </tr>
142
+ <tr>
143
+ <td>清除已完成<br>二次确认,避免误删</td>
144
+ <td><img src="./docs/assets/features/clear.png" width="300" alt="清除已完成确认"></td>
145
+ <td><img src="./docs/assets/features/clear-dark.png" width="300" alt="清除已完成确认(暗色)"></td>
146
+ </tr>
147
+ <tr>
148
+ <td>空状态<br>还没有记录时的引导</td>
149
+ <td><img src="./docs/assets/features/empty.png" width="300" alt="空状态"></td>
150
+ <td><img src="./docs/assets/features/empty-dark.png" width="300" alt="空状态(暗色)"></td>
151
+ </tr>
152
+ </table>
153
+
154
+ ## 设计规范
155
+
156
+ 面板与入口按钮的样式由 `src/client/styles/panel.css` 的令牌块统一驱动,改一处即可全站生效:
157
+
158
+ | 维度 | 令牌 | 取值 |
159
+ | --- | --- | --- |
160
+ | 颜色 | `--dsw-alias-*` | 直接复用 DSH 语义别名(墨色 / 悬停 / 描边 / 状态 / 设置卡),插件不再自建灰阶 |
161
+ | 字号 | `--an-fs-caption/row/title` | 12 / 13 / 14,行高统一 20 |
162
+ | 字重 | 400 / 500 | 上限 500,强调靠字号与墨色 |
163
+ | 间距 | `--an-space-1 … -6` | 4 / 8 / 12 / 16 / 24 / 32 |
164
+ | 圆角 | `--dsw-radius-sm/md/lg/panel` + 999 | 8(紧凑控件)/ 16(分组与字段)/ 28(浮动面板)/ 胶囊配 `corner-shape:round` |
165
+ | 阴影 | `--dsw-elevation-panel` | 浮层 `border:0`,0.5px 发丝描边画在阴影第一层 |
166
+ | 材质 | `--dsh-an-panelSurface`(`--dsw-alias-bg-layer-2`) | 实心面板表面,与吸顶块共用同一颜色 |
167
+ | 动效 | `--ds-transition-duration*`、`--ds-ease-in-out` | 100 / 200ms,只动 opacity 与 transform |
168
+ | 滚动条 | 主题共享 skin | 面板内只重绑 `--dsh-scrollbar-*` 到 l2,并为列表设置 9px 轨道 / 2px 内缩 |
169
+
170
+ 反馈层同样复用产品能力:复制、转发、退回、清除完成与写失败都经 `shell.overlay` 的全局 Toast 报告,面板关闭后仍然可见;图标按钮用 `ui-primitives` 的 `Tooltip`。
171
+
172
+ ## 使用
173
+
174
+ 1. 点击会话顶部右侧的「边记部」按钮,打开右侧面板;有未完成条目时,按钮角标显示数量。面板顶部的「工作区 / 会话」用来切换整个工作区与当前会话的清单。
175
+ 2. 在面板里写一条具体的小事,按设置中的添加快捷键或点击「添加」。
176
+ 3. 需要改一条便笺时,点该条右侧的「退回」,内容回到顶部输入框,改完再提交;退回后清空输入框就删除了这一条。
177
+ 4. 需要继续处理时,点击该条便笺的转发按钮,将内容追加到对话输入框,确认后自行发送。
178
+ 5. 做完后点左侧圆圈打勾;点「已完成」展开回看。
179
+ 6. 点面板外部或按 Esc 关闭。
180
+
181
+ ## 数据保存在哪里
182
+
183
+ 会话便笺保存在**当前浏览器**的 `localStorage` 中,键为 `dsh.aside-note`(沿用上游键名,包名改为 `dsh-sideby-note` 后已有数据仍直接读取),保持原来的 v1 结构:
184
+
185
+ ```json
186
+ {
187
+ "version": 1,
188
+ "sessions": {
189
+ "session-…": {
190
+ "sessionId": "session-…",
191
+ "updatedAt": 0,
192
+ "items": []
193
+ }
194
+ }
195
+ }
196
+ ```
197
+
198
+ 同一个工作区共享的清单单独保存在 `dsh.aside-note.workspaces`:
199
+
200
+ ```json
201
+ {
202
+ "version": 1,
203
+ "workspaces": {
204
+ "workspace-…": {
205
+ "workspaceId": "workspace-…",
206
+ "updatedAt": 0,
207
+ "items": [],
208
+ "seededSessionIds": ["session-…"]
209
+ }
210
+ }
211
+ }
212
+ ```
213
+
214
+ `workspaces` 是同一个工作区共享的清单;`seededSessionIds` 记住哪些会话的旧便笺已经并进来,避免重复合并或删除后复活。会话数据仍留在原来的 `dsh.aside-note` 键里,工作区数据不会写回这个键;没有工作区的会话只使用自己的 `sessions` 记录。面板顶部的范围选择单独保存在 `dsh.aside-note.scope-mode`(`workspace` 或 `session`,默认 `workspace`)。
215
+
216
+ 未提交的新增草稿保存在 `dsh.aside-note.drafts`:工作区内的会话共用一份工作区草稿,所以切会话、切范围都不会丢字;提交时才按当前范围写进工作区清单或会话清单。工作区之外的会话仍按会话保存草稿。升级后首次打开工作区时,当前会话的旧草稿会自动并入共享草稿;旧版就地编辑留下的 `edits` 记录会被忽略,并在下次写入草稿时清理。
217
+
218
+ 因此:
219
+
220
+ - 刷新页面、重启 DSH、切换会话都不会丢。
221
+ - 从上游版本升级或改为本包名后,已有便笺无需迁移。
222
+ - 不会写入项目文件,也不会同步到其他机器或其他浏览器。
223
+ - 清理浏览器站点数据会清除便笺。
224
+ - 读取旧数据时不会改写 `dsh.aside-note` 的结构;工作区清单从 `dsh.aside-note.workspaces` 读取,首次进入工作区时把成员会话的旧便笺合入一次。不会读取 `dsh.aside-notes.*` 这类更早的键。如果本地数据仍在旧的 `dsh.aside-notes.*.v2` 键下,把键名改为对应的 `dsh.aside-note.*` 后刷新页面即可继续使用。
225
+
226
+ ## 更新提示
227
+
228
+ 打开面板时,插件会静默检查一次 npm 上的最新版本(npmjs 不可用时回退到 npmmirror,再回退到 GitHub 的最新 Release);结果缓存一小时。若最新版本更高,设置按钮右上角出现提示点,设置 › 关于 中出现更新卡片:
229
+
230
+ - **检查更新**:立即重新读取 registry,绕过这一小时的缓存;按钮下方会显示「正在检查」「已是最新」或失败状态。
231
+ - **更新内容默认展示**:有新版时直接在卡片里列出 GitHub Release 的更新说明,不需要再点开。说明由 Release 正文中 `app-update-notes:zh` / `app-update-notes:en` 标记之间的内容提供,统一压成纯文本渲染,不会执行或注入任何 HTML。
232
+ - **跨多个版本**:如果线上版本领先本地好几个版本,说明区会按版本从新到旧逐条列出这段区间内的 Release;最新版本默认展开,更早的版本各自折叠、点标题单独展开。草稿与预发布不参与,最多列出 6 个版本,更多时给出「更早的版本请见完整更新说明」链接。
233
+ - **完整更新说明**:链接位于「立即更新」右侧,点击在新标签页打开对应的 GitHub Release 页面。
234
+ - **立即更新**:通过宿主自己的更新端点就地覆盖安装,不经过插件市场;完成后提供「刷新页面」,需要重启时会说明。
235
+ - **更新方式兜底**:宿主没有更新路由,或拒绝替换正在使用的插件文件时,卡片直接给出带目标版本和 profile 目录的命令,并提供「拷贝更新提示词」——一键复制可直接粘给 agent 的更新指令。预发布还会固定 npmjs registry,避免装回稳定版。
236
+
237
+ 更新始终需要手动点击:面板只负责检查、说明和发起宿主更新,自己不执行任何命令,也从不改动本地便笺。版本检查与说明读取只访问公开的版本号与 Release 正文,不上报任何数据。
238
+
239
+ 发布说明由 `tools/release/notes.mjs` 从 `CHANGELOG.md` 生成:中英文两段,各自带 `app-update-notes` 标记,外加安装链接与 Full Changelog 链接;打 tag 时发布流程会用它创建 Release 并附上 tgz。详见 [发布与版本迭代](./docs/release.md)。
240
+
241
+ ## 开发
242
+
243
+ 浏览器半侧在 `src/client/`,由 tsdown 打包成单个 `client/client.js`:
244
+
245
+ ```bash
246
+ npm install
247
+ npm run check # lint + typecheck + 测试 + 构建
248
+ npm run build # 只重新生成 client/client.js
249
+ ```
250
+
251
+ 本地调试时把仓库 link 进 DSH profile(`<path-to-repo>` 换成克隆目录),再在 profile 目录执行 `pnpm install`:
252
+
253
+ ```json
254
+ {
255
+ "dependencies": {
256
+ "dsh-sideby-note": "link:<path-to-repo>"
257
+ },
258
+ "dsh": {
259
+ "profile": {
260
+ "bundles": ["dsh-sideby-note"]
261
+ }
262
+ }
263
+ }
264
+ ```
265
+
266
+ 新增插件行后,在侧边栏「插件」页把该组合包关闭再开启,运行中的 Host 会在线重新组合,无需重启。
267
+
268
+ 入口是 `src/client/index.ts`,导出 `apply(ctx)`;tsdown 负责套上 DSH 的加载壳:
269
+
270
+ ```js
271
+ window.__ModuleLoader__.load({ id: 'dsh-sideby-note', factory: (require) => { … } })
272
+ ```
273
+
274
+ 产物单独提交:CI 会重建并对比 `client/`,不一致就失败,因此不要手改 `client/client.js`。
275
+
276
+ `index.js` 是空的 Host 半侧;`cordis.patch.yml` 负责把包插入 profile 的组合。界面依赖 `slots` 与 `locale` 两个服务:
277
+
278
+ - `conversation.composer.dock`:只用来捕获当前会话 ID,不渲染可见入口。
279
+ - 顶部右侧入口由 MutationObserver 注入宿主 header,因为宿主重渲染会回收 React portal。
280
+
281
+ 面板用 `react-dom/client` 的独立 root 挂到 `document.body`,用 fixed 定位跟随入口;所有样式使用 DSH 的 `--dsw-alias-*` 主题变量,自动适配明暗主题。
282
+
283
+ 修改源码后先 `npm run build`;开发模式下 DSH 会热替换新 bundle,否则刷新页面或重启 DSH。
284
+
285
+ 截图与预览图的产出流程见 [截图与预览图 SOP](./docs/screenshot-sop.md):在隔离 profile 里造演示会话,一条命令重拍明暗两套;凭据默认不复制。
286
+
287
+ 代码结构、数据模型与构建约定见 [架构文档](./docs/architecture.md)。
288
+
289
+ 分支模型、版本策略与发版步骤见 [发布与版本迭代](./docs/release.md)。
290
+
291
+ ## 验证
292
+
293
+ 已在独立的 DSH profile 中实际加载,并用无头 Chrome 走通:
294
+
295
+ - 会话顶部右侧出现「边记部」按钮,角标显示未完成数;
296
+ - 点击按钮在右侧打开面板,面板右上角对齐入口;
297
+ - 添加后按钮角标与面板计数同步;
298
+ - 面板内可完成、复制、转发、退回输入框重新编辑、清除已完成;
299
+ - 刷新页面后记录仍在;面板头部可在工作区级与当前会话级清单之间切换;
300
+ - 版本检查的 npmjs → npmmirror → GitHub Release 回退、1 小时缓存与版本比较由契约测试覆盖;发布说明的标记提取、中英文回退、上限与 Markdown 压平有独立测试;jsdom 集成测试会驱动面板显示更新卡片、展开说明并通过宿主更新端点完成一次更新。真实更新提示需先发布到 npm 或创建 GitHub Release。
301
+
302
+ `npm run check` 通过:lint、类型检查、构建与 126 个测试(含 jsdom 里驱动完整面板流程的集成测试)。