dsh-sidebar-organizer 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+版本格式遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
+本文件的中文条目为默认语言；英文条目见英文段落（同一版本内）。
+
+## 0.4.0 — 2026-11-02
+
+- 源码拆分为 `src/` 下的模块（constants / styles / storage / icons / slot /
+  runtime / menu / plugin），新增 `scripts/build.mjs` 在构建期拼接为
+  `lib/client.js`（DSH 客户端以经典脚本加载，运行时无法 `import`）。
+- 版本号改为构建期从 `package.json` 注入，避免多处手写漂移。
+- 新增 `README.en.md`、`NOTICE.md`、`NOTICE.en.md`、`CITATION.cff`：
+  README/NOTICE 中英文分文件、顶部链接切换；补齐 AI 使用、代码来源、
+  商标与引用声明。
+- `package.json` 增加 `repository`/`homepage`/`bugs`/`keywords`，`private`
+  设为 `false`，补充构建与检查脚本，准备发布 npm。
+- 行为无变化，仍为 0.3.6 的功能集。
+
+### English
+
+- Split sources into modules under `src/` and added `scripts/build.mjs`, which
+  concatenates them into `lib/client.js` at build time (the DSH client loads
+  plugins as classic scripts, so there is no runtime `import`).
+- The version is injected from `package.json` during the build.
+- Added `README.en.md`, `NOTICE.md`, `NOTICE.en.md`, and `CITATION.cff` with
+  language switching, AI-usage/code-origin disclosure, trademark notes, and
+  citation metadata.
+- `package.json`: added repository/homepage/bugs/keywords, set `private: false`,
+  added build/check scripts, preparing for npm publication.
+- No behavioural changes; feature set is the same as 0.3.6.
+
+## 0.3.6 — 2026-11-02
+
+- 点击「更多」菜单中「已收纳」的条目只打开对应面板，不再顺带把它放回侧栏；
+  恢复显示只通过「拖回左侧」触发。
+
+## 0.3.5 — 2026-11-02
+
+- 指针捕获从 `pointerdown` 推迟到长按成立之后，修复「已收纳」条目无法单击打开。
+
+## 0.3.4 — 2026-11-02
+
+- 图标 SVG 内嵌 id 统一加前缀，修复「上下文洞察」等带 `mask` 的面板收纳后图标空白。
+- 「已收纳」分组内支持长按拖动排序。
+
+## 0.3.3 — 2026-11-02
+
+- 修复 0.3.2 回归：React 18 不接受 DOM 节点作为 children，改为 SVG 标记 +
+  `dangerouslySetInnerHTML`，并加 `MenuBoundary` 降级兜底。
+
+## 0.3.2 — 2026-11-02
+
+- 「已收纳」行改用 `MenuItemButton` 的 `icon` 槽位，与原生菜单行排版一致。
+
+## 0.3.1 — 2026-11-02
+
+- 拖动期性能：按下时冻结几何快照、`requestAnimationFrame` 合并写入、
+  拖动中暂停布局 pass。
+- 「已收纳」行沿用面板本地化名称与图标；移除菜单提示行。
+
+## 0.3.0 — 2026-11-02
+
+- 「更多」收纳：拖到「更多」= 收纳，菜单内长按拖出 = 恢复。
+- `Alt+↑/↓` 键盘排序；拖动期间抑制 `:hover` 与 tooltip。
+
+## 0.2.1 — 2026-11-02
+
+- 改用属性/结构选择器定位面板行，修复 CSS Modules 哈希类名导致的静默失效。
+
+## 0.2.0 — 2026-11-02
+
+- 重写为只读 DOM 版本：`style.order` 排序、`localStorage` 持久化、看门狗、
+  逃生开关；移除会卡死页面的插槽重注册（0.1.0 事故）。
+
+## 0.1.0 — 2026-11-02
+
+- 初版：通过影子注册重排 `sidebar.panellist`，因反馈环导致页面卡死，已废弃。

package/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "dsh-sidebar-organizer: Drag-to-reorder and tuck-away for the DSH sidebar panel strip"
+version: 0.4.0
+date-released: "2026-11-02"
+license: MIT
+type: software
+authors:
+  - alias: TLEWA
+    name: TLEWA
+repository-code: "https://github.com/TLEWA/dsh-sidebar-organizer"
+url: "https://github.com/TLEWA/dsh-sidebar-organizer"
+abstract: >-
+  A DSH (DeepSeek Harness) sidebar plugin that adds long-press drag reordering and
+  tuck-away-to-More for the global panel strip, implemented with read-only slot
+  access and inline DOM ordering to avoid re-registration feedback loops.
+keywords:
+  - DSH plugin
+  - DeepSeek Harness
+  - sidebar
+  - drag and drop
+  - UI customization

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-modmenu contributors
+
+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/NOTICE.en.md

@@ -0,0 +1,88 @@
+# NOTICE — dsh-sidebar-organizer
+
+[简体中文](NOTICE.md) · **English**
+
+This file records code origin, third-party components, AI involvement, and how to
+cite the project. Last updated: 2026-11-02 (v0.4.0).
+
+## 1. What this project is
+
+`dsh-sidebar-organizer` is a community third-party plugin. It is **not** an
+official DeepSeek product and is not endorsed or certified by DeepSeek. It uses
+the plugin interfaces the DSH client exposes at runtime (`window.__ModuleLoader__.load`,
+`ctx.slots`, `ctx.locale`, `ctx.effect`) and does not modify any file in the host
+installation.
+
+## 2. Third-party code and assets
+
+- **No host source code is included.** This project does not copy, adapt, or
+  redistribute any DSH (DeepSeek Harness) source code or assets. DSH is
+  proprietary; this project is written against its public plugin mechanism
+  (bundle package format, client module loader, slot API).
+- **Runtime dependencies come from the host.** `react` is provided by the DSH
+  client module loader; `MenuItemButton` from
+  `@deepseek-ai/dsh-client-ui-primitives` is an optional enhancement used only
+  when present. Neither package is redistributed here.
+- **Icons are read from the host at runtime.** The icon at the left of each menu
+  row is cloned from the SVG the sidebar panel itself renders (element ids such
+  as `mask` / `gradient` references are rewritten with a prefix). No icon assets
+  are bundled.
+- **No third-party runtime code.** Nothing in `src/`, `lib/`, or
+  `test/harness.html` inlines a third-party library; the harness uses native DOM
+  APIs and a hand-written fake module loader.
+- **Development tools** (not shipped): Node.js (MIT), npm (Artistic License 2.0).
+- If you believe a part of this implementation closely resembles your project
+  without attribution, please open an issue; we will verify and either add
+  credit or change the implementation.
+
+## 3. AI usage and code origin
+
+- **How it was built.** The project was built in DeepSeek Harness by an AI coding
+  agent (DeepSeek model) working with the maintainer: the maintainer set
+  requirements, reviewed the interaction, reported defects, and made acceptance
+  and release decisions; the AI implemented, debugged, and drafted docs.
+- **Scope of AI involvement.** All client code under `src/` and `lib/`, the host
+  placeholder, the offline harness, and the first drafts of README / NOTICE /
+  CHANGELOG are AI-generated or substantially AI-edited, then verified by the
+  maintainer release by release on a real DSH desktop install (dragging, tucking,
+  menu behaviour, performance, freeze regression).
+- **Human responsibility.** The maintainer is ultimately responsible for the
+  repository content, build artifacts, and published versions.
+- **Privacy.** The plugin makes no network requests and collects no telemetry.
+  All state (order, tucked list, kill switch) lives in browser `localStorage`
+  under the keys documented in the README.
+- **Stability caveat.** The plugin depends on the host's rendered DOM structure
+  and slot projection (undocumented details). A DSH upgrade may break it; when it
+  breaks, the sidebar keeps the host's default order, and the escape hatches in
+  the README disable it.
+
+## 4. Citing this project
+
+Use [CITATION.cff](CITATION.cff):
+
+```bibtex
+@software{dsh_sidebar_organizer,
+  author  = {TLEWA},
+  title   = {dsh-sidebar-organizer: Drag-to-reorder and tuck-away for the DSH sidebar panel strip},
+  version = {0.4.0},
+  year    = {2026},
+  license = {MIT},
+  url     = {https://github.com/TLEWA/dsh-sidebar-organizer}
+}
+```
+
+When citing code, include the version or commit SHA, e.g.
+`dsh-sidebar-organizer v0.4.0 (https://github.com/TLEWA/dsh-sidebar-organizer)`.
+
+## 5. Trademarks
+
+"DeepSeek", "DeepSeek Harness", and "DSH" are marks of their respective owners.
+The name `dsh-sidebar-organizer` is descriptive (naming the host and purpose) and
+implies no affiliation or endorsement. Third-party product names in the README
+are used only to describe compatibility.
+
+## 6. License
+
+Released under the [MIT](LICENSE) license. When redistributing sources or build
+artifacts, keep `LICENSE` and this `NOTICE` file. The MIT license provides no
+warranty.

package/NOTICE.md

@@ -0,0 +1,73 @@
+# NOTICE — dsh-sidebar-organizer
+
+**简体中文** · [English](NOTICE.en.md)
+
+本文件说明本项目的代码来源、第三方组件、AI 参与方式与引用方式。
+最后更新：2026-11-02（v0.4.0）。
+
+## 1. 项目性质
+
+`dsh-sidebar-organizer` 是社区第三方插件，**不是** DeepSeek 官方产品，也未获得
+DeepSeek 的背书或认证。它通过 DSH 客户端在运行时暴露的插件接口
+（`window.__ModuleLoader__.load`、`ctx.slots`、`ctx.locale`、`ctx.effect`）
+与宿主交互，不修改宿主安装目录中的任何文件。
+
+## 2. 第三方代码与资源
+
+- **不包含宿主源代码。** 本项目未复制、未改编、未再分发 DSH（DeepSeek Harness）
+  的任何源代码或资源。DSH 为专有软件，其版权归 DeepSeek 所有；本项目仅依据其
+  公开的插件机制（bundle 包格式、客户端模块加载器、插槽 API）编写。
+- **运行时依赖由宿主提供。** `react` 由 DSH 客户端模块加载器提供；
+  `@deepseek-ai/dsh-client-ui-primitives` 的 `MenuItemButton` 为可选增强，
+  仅在宿主存在时调用，本项目不分发这两个包。
+- **图标由宿主实时提供。** 菜单行左侧图标是运行时从侧栏面板自身渲染的 SVG
+  克隆而来（含 `mask` / `gradient` 的 id 前缀改写），本项目不附带任何图标资源。
+- **无第三方运行时代码。** `src/`、`lib/`、`test/harness.html` 中未内联任何
+  第三方库；测试夹具使用原生 DOM API 与手写的假模块加载器。
+- **开发工具**（不随包分发）：Node.js（MIT）、npm（Artistic License 2.0）。
+- 若你认为本项目某段实现与你的项目高度相似且未被署名，请通过 issue 联系，
+  我们会核实并补充署名或调整实现。
+
+## 3. AI 使用与代码来源声明
+
+- **开发方式。** 本项目在 DeepSeek Harness 中、由 AI 编程代理（DeepSeek 模型）
+  与维护者结对完成：维护者负责提出需求、评审交互、指出缺陷、验收与发布决策；
+  AI 负责实现、调试与文档初稿。
+- **AI 参与范围。** `src/` 与 `lib/` 的全部客户端代码、宿主侧占位代码、离线
+  测试夹具、README / NOTICE / CHANGELOG 的初稿，均由 AI 生成或大幅修改，
+  并经维护者在真实 DSH 桌面端逐版验证（拖动、收纳、菜单、性能与卡死回归）。
+- **人类责任。** 维护者对仓库内容、构建产物与发布版本负最终责任。
+- **隐私。** 插件不发起网络请求、不采集遥测；全部状态（顺序、收纳列表、
+  停用开关）只写入浏览器 `localStorage`，键名见 README。
+- **稳定性提示。** 本插件依赖宿主渲染出的 DOM 结构与插槽投影（未文档化细节）。
+  DSH 升级后可能失效；失效时侧栏会保持宿主默认顺序，并可用 README 中的
+  逃生开关停用。
+
+## 4. 引用方式
+
+若在教学、文章或研究中引用本项目，请使用 [CITATION.cff](CITATION.cff)：
+
+```bibtex
+@software{dsh_sidebar_organizer,
+  author  = {TLEWA},
+  title   = {dsh-sidebar-organizer: Drag-to-reorder and tuck-away for the DSH sidebar panel strip},
+  version = {0.4.0},
+  year    = {2026},
+  license = {MIT},
+  url     = {https://github.com/TLEWA/dsh-sidebar-organizer}
+}
+```
+
+代码引用请同时标注版本号或 commit SHA，例如
+`dsh-sidebar-organizer v0.4.0 (https://github.com/TLEWA/dsh-sidebar-organizer)`。
+
+## 5. 商标
+
+「DeepSeek」「DeepSeek Harness」「DSH」等名称与标识归其权利人所有。本项目名称
+`dsh-sidebar-organizer` 仅作描述性使用（说明其适用的宿主与用途），不代表任何
+关联或背书。README 中出现的第三方产品名仅用于说明兼容性。
+
+## 6. 许可
+
+本项目以 [MIT](LICENSE) 许可发布。再分发源码或构建产物时，请保留 `LICENSE`
+与本 `NOTICE` 文件。MIT 许可不提供任何担保。

package/README.en.md

@@ -0,0 +1,149 @@
+# dsh-sidebar-organizer
+
+[简体中文](README.md) · **English**
+
+Adds **custom ordering** and **tucking away** to the "global panels" strip at the
+top-left of the DSH (DeepSeek Harness) sidebar — the column of icons for plugins,
+marketplace, skills manager, scheduled tasks, and so on.
+
+> Version **0.4.0**: sources split into `src/` modules with a build script;
+> AI-usage and code-origin disclosure added; multilingual docs.
+
+## What it does
+
+- **Long-press to reorder**: hold a panel icon for ~0.26 s; it lifts (a ghost
+  follows the pointer, plus a drop indicator) and you drag it up or down.
+  The order applies immediately and is persisted.
+- **Tuck into "More"**: drop a row on the More button and that panel disappears
+  from the strip, moving into the "Tucked away" group of the More menu.
+- **Pull back out of "More"**: open the More menu, long-press a tucked panel and
+  drag it onto the strip to restore it.
+- **Reorder inside the menu**: long-press drag within the tucked group to change
+  the order of tucked panels.
+- **Keyboard**: focus a row and press `Alt+↑` / `Alt+↓`.
+- **Reset**: once the layout is customized, "Reset layout" appears at the bottom
+  of the More menu.
+- The layout survives page reloads and DSH restarts.
+- While dragging, rows under the pointer do not react with `:hover` or tooltips
+  (rows get `pointer-events: none`; hit-testing is pure geometry).
+- The "Plugins" entry can be reordered and tucked too; the More button always
+  stays last.
+
+## Install
+
+### From npm (recommended)
+
+```bash
+dsh plugin install dsh-sidebar-organizer
+```
+
+Or search for `dsh-sidebar-organizer` in the DSH plugin manager.
+
+### From source
+
+This repository is itself a DSH plugin bundle. Clone it, then point the plugin
+manager at the checkout:
+
+```
+plugin_manager  action: install_bundle  target: <absolute path to the checkout>
+```
+
+Refresh the Web UI (`Ctrl+R`) afterwards. When the profile links the checkout,
+edit `src/` and run `npm run build`, then refresh — no reinstall needed.
+
+> Versions up to 0.3.6 were called `dsh-modmenu`. The old layout key
+> `dsh.modmenu.layout.v1` migrates automatically to
+> `dsh.sidebar-organizer.layout.v1`, and `window.__dshModmenu` remains an alias
+> of `window.__dshSidebarOrganizer`.
+
+## Safety design
+
+0.1.0 re-registered the whole panel column from inside the slot's own change
+notification, creating a `register → notify → register` feedback loop that froze
+the page. Since 0.2.0 the mechanism is different:
+
+1. **The panel slot is read-only.** The plugin never registers or shadows a
+   `sidebar.panellist` entry; it only reads `entriesOfSlot` for ids and labels.
+2. **Order/visibility is written as inline DOM styles.** The strip is
+   `display:flex; flex-direction:column`, so `style.order` on each row changes
+   the visual order; tucking uses `style.display:none` plus `data-dso-hidden`.
+3. **Exactly one static slot write**: a row registered into
+   `sidebar.panellist.actions` (the More menu) named `panel-organizer`. It is
+   registered once and never re-registers or subscribes.
+4. **Idempotent and rate-limited**: a pass only writes when a value actually
+   changes, and passes are coalesced via `requestAnimationFrame`.
+5. **Watchdog**: more than 90 passes in 3 s disables observers and listeners.
+6. **`childList` only**: the plugin's own style/attribute writes cannot retrigger
+   the observer.
+7. **Escape hatches** (browser console):
+
+   ```js
+   window.__dshSidebarOrganizer.reset();      // forget the saved layout
+   window.__dshSidebarOrganizer.disable();    // persist a kill switch and stop
+   window.__dshSidebarOrganizer.hide("id");   // tuck away manually
+   window.__dshSidebarOrganizer.reveal("id"); // restore manually
+   window.__dshSidebarOrganizer.status();     // inspect current state
+   ```
+
+   To undo `disable()`, run
+   `localStorage.removeItem("dsh.sidebar-organizer.disabled")` and refresh.
+8. If this plugin stops working entirely, the sidebar simply keeps DSH's default
+   order.
+
+## How it works
+
+- The panel list is the list slot `sidebar.panellist`; registrations look like
+  `{ options: { id, order, label }, component }`, and the sidebar projects
+  `entriesOfSlot` into `{id, order, label}` sorted by `order`.
+- Rendered rows are mapped back to registration ids by exact match between the
+  resolved label and the row's `aria-label`, falling back to the projection
+  index, then to `label:<text>`.
+- Persisted layout:
+  `localStorage["dsh.sidebar-organizer.layout.v1"] = { version: 2, order: [id…], hidden: [id…] }`.
+- Drag layer: document-capture `pointerdown` → 260 ms long-press timer (cancelled
+  by >8 px movement) → ghost clone plus indicator; drop target by vertical
+  midpoints; dropping inside the More button rect (6 px tolerance) tucks the
+  row; clicks within 500 ms of a drop are swallowed.
+
+## Repository layout
+
+```
+src/                 sources (concatenated in dependency order at build time)
+scripts/build.mjs    assembles src/ into lib/client.js
+lib/client.js        generated client half (what DSH loads)
+lib/index.js         host half (placeholder)
+cordis.patch.yml     bundle patch applied on install
+test/harness.html    offline harness: fake sidebar DOM + slot projection
+```
+
+DSH loads client plugins as classic scripts via
+`window.__ModuleLoader__.load({ id, factory })`, not as ES modules, so there is
+no runtime `import` — hence module sources plus build-time concatenation.
+
+## Development
+
+```bash
+npm run build   # src/ → lib/client.js
+npm run check   # syntax check
+```
+
+Open `test/harness.html` in a browser for the self-checking regression run
+(ordering, persistence, reset, tuck/restore, in-menu drag, DOM churn during drag).
+
+## Compatibility
+
+- DSH `>= 0.2.1-rc.3` (developed against `0.2.1-rc.5`).
+- The client only requires `react`; `MenuItemButton` from
+  `@deepseek-ai/dsh-client-ui-primitives` is used when present, with a built-in
+  fallback otherwise.
+
+## Notices
+
+- Third-party code and trademarks: [NOTICE.en.md](NOTICE.en.md)
+- AI assistance and code origin: the "AI usage and code origin" section of
+  [NOTICE.en.md](NOTICE.en.md)
+- Citation metadata: [CITATION.cff](CITATION.cff)
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+# dsh-sidebar-organizer
 
-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.
+**简体中文** · [English](README.en.md)
+
+给 DSH（DeepSeek Harness）左侧栏左上角那块「全局面板」栏——插件、市场、技能管理、定时任务……那一列图标——加上**自定义排序**与**收纳**能力。
+
+> 当前版本 **0.4.0**：源码拆分为 `src/` 模块并加入构建脚本；补齐 AI 使用与代码来源声明；多语言文档。
+
+## 现在能做什么
+
+- **长按拖动排序**：按住某个面板图标约 0.26 秒，图标浮起（跟随指针的 ghost + 一条落点指示线），上下拖到目标位置松手即可。顺序即时生效并保存。
+- **收进「更多」**：把行拖到「更多」按钮上松手，该面板就从面板栏消失，收进「更多」菜单的「已收纳」分组。
+- **从「更多」拖回来**：打开「更多」菜单，长按被收纳的面板并拖到左侧面板栏的目标位置松手，即恢复显示。
+- **菜单内排序**：在「已收纳」分组里长按拖动，也能调整被收纳面板之间的顺序。
+- **键盘排序**：聚焦某行后 `Alt+↑` / `Alt+↓` 上下移动。
+- **恢复默认排序**：自定义过布局后，「更多」菜单底部会出现「恢复默认排序」。
+- 刷新页面、重启 DSH 后布局保持。
+- 拖动过程中，指针下方的行不会触发 `:hover` 或 tooltip（拖动期间行临时 `pointer-events: none`，命中判定全部走几何矩形）。
+- 「插件」入口可以参与排序，也可以被收纳；「更多」按钮永远是最后一个。
+
+## 安装
+
+### 从 npm 安装（推荐）
+
+```bash
+dsh plugin install dsh-sidebar-organizer
+```
+
+或在 DSH 的插件管理器里搜索 `dsh-sidebar-organizer`。
+
+### 从源码安装
+
+本仓库本身就是一个 DSH 插件包（bundle）。克隆后，用插件管理器指向仓库目录安装：
+
+```
+plugin_manager  action: install_bundle  target: <仓库的绝对路径>
+```
+
+安装后刷新 Web 界面（`Ctrl+R`）。以 `link:` 方式装进 profile 时，改 `src/` 并执行 `npm run build` 后刷新页面即可生效，不必重装。
+
+> 0.3.6 及更早版本名为 `dsh-modmenu`。改名后旧的布局存储键
+> `dsh.modmenu.layout.v1` 会自动迁移到 `dsh.sidebar-organizer.layout.v1`，
+> 控制台句柄 `window.__dshModmenu` 也保留为 `window.__dshSidebarOrganizer` 的别名。
+
+## 安全设计
+
+0.1.0 曾在每次插槽变更通知里重新注册整列面板，形成
+`注册 → 通知 → 再注册` 的反馈环，把页面拖死。0.2.0 起彻底换掉机制：
+
+1. **面板列表只读**：不注册、不 shadow 任何 `sidebar.panellist` 条目，只读
+   `ctx.slots.entriesOfSlot("sidebar.panellist")` 获取面板 `id` 与标签。
+2. **排序 / 隐藏只写 DOM 内联样式**：面板列是 `display:flex; flex-direction:column`，
+   给每行写 `style.order` 即可改视觉顺序；收纳用 `style.display:none` + `data-dso-hidden`。
+3. **唯一一次插槽写入**：往 `sidebar.panellist.actions`（「更多」菜单）注册一个静态行
+   `panel-organizer`，用于列出被收纳面板并支持拖回。只注册一次，不订阅、不重注册。
+4. **幂等 + 限流**：每次布局 pass 都是「值不同才写」，并用 `requestAnimationFrame` 合并到每帧最多一次。
+5. **看门狗**：3 秒内超过 90 次 pass 即判定异常并停止观察与监听。
+6. **只观察 `childList`**：自身写入的 `style` / `data-*` 不会反过来触发观察器。
+7. **逃生开关**（浏览器控制台）：
+
+   ```js
+   window.__dshSidebarOrganizer.reset();      // 忘掉保存的布局
+   window.__dshSidebarOrganizer.disable();    // 置 localStorage 开关并停用，刷新后也不启动
+   window.__dshSidebarOrganizer.hide("id");   // 手动收纳
+   window.__dshSidebarOrganizer.reveal("id"); // 手动恢复
+   window.__dshSidebarOrganizer.status();     // 查看当前状态
+   ```
+
+   `disable()` 之后要恢复，执行
+   `localStorage.removeItem("dsh.sidebar-organizer.disabled")` 再刷新。
+8. 就算本插件完全不工作，侧栏也只是保持 DSH 默认顺序，不会有其他副作用。
+
+## 实现说明
+
+- 面板所在的 list 插槽为 `sidebar.panellist`，注册项形如 `{ options: { id, order, label }, component }`；
+  侧栏把 `entriesOfSlot` 投影成 `{id, order, label}` 并按 `order` 升序渲染为 `nav > button`。
+- 本插件把渲染出来的行映射回注册 `id`：先按解析后的 `label` 与行 `aria-label` 精确匹配，
+  匹配不到再按投影下标兜底，两者都不行就用 `label:<文字>` 做键。
+- 保存的布局：`localStorage["dsh.sidebar-organizer.layout.v1"] = { version: 2, order: [id…], hidden: [id…] }`
+  （`order` 同时包含可见与已收纳的 id）。
+- 拖拽层：document 捕获阶段 `pointerdown` → 260ms 长按计时（指针移动超过 8px 取消）→
+  激活后克隆行做 ghost、插入落点指示线；落点按其余行的竖直中点判定；拖到「更多」按钮矩形
+  （外扩 6px）内即收纳；松手后 500ms 内吞掉紧随的 click，避免误触打开面板。
+- 「更多」菜单里的行包在 `div[data-dso-more-key]` 中，同一套拖拽层据此识别来源并恢复。
+
+## 目录结构
+
+```
+src/                 源码（模块化，按依赖顺序拼接）
+  constants.js       常量、文案、共享句柄
+  styles.js          注入的样式表
+  storage.js         localStorage 布局持久化
+  icons.js           图标 SVG 序列化与 id 前缀处理
+  slot.js            只读访问 sidebar.panellist 投影
+  runtime.js         DOM 运行时：定位面板列、应用顺序、拖拽手势
+  menu.js            「更多」菜单里注册的那一行
+  plugin.js          插件入口 apply()
+scripts/build.mjs    把 src/ 拼成 lib/client.js
+lib/client.js        构建产物（DSH 实际加载的客户端半）
+lib/index.js         宿主半（占位）
+cordis.patch.yml     bundle 补丁（安装时插入 profile）
+test/harness.html    离线夹具：伪造侧栏 DOM 与插槽数据，浏览器打开即回归
+```
+
+DSH 的客户端插件是以经典脚本方式通过 `window.__ModuleLoader__.load({ id, factory })`
+加载的，不是 ES 模块，因此运行时无法 `import`；源码模块化 + 构建期拼接是这个约束下的折中。
+
+## 开发
+
+```bash
+npm run build   # src/ → lib/client.js
+npm run check   # 语法检查
+```
+
+回归测试不碰真实 UI：用浏览器打开 `test/harness.html`，页面会自检并打印顺序、
+持久化、`reset()`、收纳 / 恢复、菜单内拖动、拖动途中 DOM 替换与滚动的结果。
+
+## 兼容性
+
+- DSH `>= 0.2.1-rc.3`（在 `0.2.1-rc.5` 上开发）。
+- 客户端只 `require("react")`；`@deepseek-ai/dsh-client-ui-primitives` 的 `MenuItemButton`
+  存在时优先使用，缺失时降级为内置按钮样式。
+
+## 路线图
+
+- [x] 0.2.0 — 只读 + DOM `order` 的最小可行版本
+- [x] 0.2.1 — 属性选择器修复（CSS Modules 哈希类名导致选择器失配）
+- [x] 0.3.0 — 「更多」收纳、键盘排序、拖动期抑制 `:hover`
+- [x] 0.3.1 — 拖动期性能：几何快照、rAF 合并、暂停布局 pass
+- [x] 0.3.2 — 「已收纳」行使用 `MenuItemButton` 的图标槽位
+- [x] 0.3.3 — 修复 DOM 节点作为 React children 的回归
+- [x] 0.3.4 — 图标内嵌 id 加前缀；「已收纳」内排序
+- [x] 0.3.5 — 指针捕获延后到拖动成立，修复收纳条目无法点击
+- [x] 0.3.6 — 点击收纳条目只打开面板，不再自动放回侧栏
+- [x] 0.4.0 — 源码模块化与构建脚本、多语言文档、AI 使用与代码来源声明
+- [ ] 0.5.0 — 无障碍补强（菜单内上移 / 下移按钮、屏幕阅读器朗读顺序变化）
+
+## 声明与引用
+
+- 第三方代码与商标说明：[NOTICE.md](NOTICE.md)
+- AI 参与方式、代码来源与引用方式：见 [NOTICE.md](NOTICE.md) 的「AI 使用与代码来源声明」一节
+- 引用本项目的 BibTeX：[CITATION.cff](CITATION.cff)
+
+## 许可
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-sidebar-organizer bundle patch
+#
+# Installed by the DSH plugin manager (or `dsh plugin add <path>`); this
+# patch inserts the plugin row into the active profile.
+- insert:
+    - id: sidebar-organizer
+      name: 'dsh-sidebar-organizer'
+      config: {}