@idoall/dsh-session-colors 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-22
+
+First release.
+
+### Added
+
+- A colour mark for any Session, chosen from a system-style picker in the
+  conversation header: saturation/value field, hue and alpha sliders, hex and
+  RGBA fields, seven theme swatches, a saved-colours row, and screen eyedropper
+  where the browser supports `EyeDropper`.
+- A colour chip on the marked Session's sidebar row, painted into a
+  frame-wide click-through overlay and clipped to the sidebar's scroll
+  container.
+- Host-side storage: marks live in `session-colors.json` under the profile's
+  data directory, served by the plugin's own `GET`/`POST /plugins/dsh-session-colors/marks`
+  routes, so a colour chosen on one device is visible on every other one,
+  including over LAN and tunnels.
+- Live cross-device pickup: the open page re-reads marks when it becomes visible
+  again and on a slow interval.
+- Optional `dataDir` config; without it marks live for the process only and the
+  feature degrades instead of failing.
+- Diagnostics on the overlay element (`data-dsh-sc-build`, `-status`,
+  `-writable`, `-marks`, `-error`) so a device that shows nothing can say why
+  from a plain DOM dump.
+
+
+
+### Fixed
+
+- The picker's hex field clipped its own value: seven characters (`#FFCC00`) did
+  not fit in the 51px it had, so the panel showed `#FFCC0`. The hex column is
+  wider than the numeric ones now and the inputs carry tighter padding, so the
+  full value is visible.
+- A colour chip is now visible inside a phone's sidebar drawer. Two causes
+  stacked: DSH confines `shell.overlay` to a stacking context of its own
+  (`z-index: 20`), so a mobile adapter that promotes the sidebar to a
+  `position: fixed; z-index: 10000` drawer painted its opaque background over
+  every chip; and that drawer slides in with a CSS transition, which fires no
+  scroll, resize or DOM mutation, so the layer kept the off-screen coordinates it
+  had while the drawer was closed. The layer now renders through a portal on
+  `document.body`, measures the row's own ancestor chain to paint one level above
+  whatever holds the sidebar (1 on a stock desktop, 10001 behind such a drawer),
+  and follows an ancestor's transition. On the desktop the layer still sits below
+  dialogs, and the build marker is now `host-routes+drawer-aware`, so a device can
+  report which client it runs.
+
+### Changed
+
+- Both READMEs rewritten around what a reader needs first: the verified DSH
+  version, requirements, usage, a compatibility table, cross-device storage,
+  configuration, troubleshooting, security boundaries and uninstall. All three
+  screenshots were retaken from the current build (sidebar marks, the picker, and
+  a phone's drawer).
+- The DSH version this build was verified against is now declared in
+  `package.json` as `dsh.compatibility.dshReleases` (DSH ignores the field) and
+  both READMEs must repeat exactly that list: a test fails if a README drops a
+  version, if the claim falls outside the `peerDependencies` range, or if a
+  README image stops resolving.
+- Repository housekeeping, no change to what the package ships: the abandoned
+  "pinned Sessions" line is **deleted** — its documents, its two demos, its test
+  material and its evidence — so the repository holds only the shipping plugin and
+  its own records. A test now keeps `docs/` to the design record plus
+  `docs/images/` instead of letting a second spec grow back.
+- `demos/session-color-mark-demo.html` was rebuilt as a single self-contained page
+  that mirrors the real picker's styling and the chip's geometry (4×16 bar in the
+  row's left padding, clear of the status dot).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DSH Session Colors 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/README.md

@@ -0,0 +1,262 @@
+<h1 align="center">DSH Session Colors</h1>
+
+<p align="center">Give any Session a colour and spot it at a glance in the sidebar.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@idoall/dsh-session-colors"><img alt="npm" src="https://img.shields.io/badge/npm-not%20published-lightgrey"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-0F172A"></a>
+</p>
+
+<p align="center">English | <a href="README.zh.md">中文</a></p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#usage">Usage</a> ·
+  <a href="#compatibility">Compatibility</a> ·
+  <a href="#cross-device-and-lan">Cross-device</a> ·
+  <a href="#configuration">Configuration</a> ·
+  <a href="#troubleshooting">Troubleshooting</a> ·
+  <a href="#security-boundaries">Security</a> ·
+  <a href="#limitations">Limitations</a> ·
+  <a href="#uninstall">Uninstall</a> ·
+  <a href="#development">Development</a>
+</p>
+
+> DSH Session Colors is a DeepSeek Harness community plugin. It does not modify
+> DSH core and does not rewrite any Session or Workspace data: a mark is only
+> "Session id → one colour".
+
+Work is spread across several workspaces, and the workspace list is a wall of
+look-alike titles. Once a task finishes, the Session you were just in is hard to
+find again — the status dot is idle and the title is one of twenty. **A colour you
+chose yourself is the cheapest way to make one row recognisable.**
+
+<p align="center">
+  <img src="docs/images/sidebar-chips.png" width="280" alt="Four colour marks in the sidebar: four Sessions in one workspace list, each carrying a differently coloured bar (amber, red, green, blue)">
+</p>
+
+## Features
+
+- **A colour mark on the Session row** — a short bar in the row's left padding
+  that **deliberately avoids the status dot**, so "which one finished" is never
+  covered up.
+- **A system-style colour picker** — a large saturation/value field, hue and alpha
+  sliders, hex and RGBA fields, seven theme swatches, your saved colours, and
+  screen eyedropper where the browser supports `EyeDropper`. It sits in the
+  Session header's utilities, not next to the title.
+- **Marked once, visible everywhere.** Marks live on the **Host**, not in the
+  browser, so a colour chosen on your computer is also there on your phone —
+  over a LAN address or a tunnel alike.
+- **Visible on a phone too.** A phone turns the sidebar into a drawer, and the
+  chips follow it: they travel with the drawer as it slides in, and they are
+  painted above it.
+- **Changes arrive on their own.** The page re-reads marks when it becomes
+  visible again and every 20 seconds, so a colour set on another device shows up
+  without a refresh.
+- **Never blocks the UI.** The chip layer is click-through and clipped to the
+  sidebar's scroll container; the worst case is that a chip does not appear.
+- **A failure says so.** When the store cannot be reached, the header control
+  shows ⚠ with a reason instead of looking like a Session with no colour.
+
+<p align="center">
+  <img src="docs/images/color-picker.png" width="276" alt="The colour picker: saturation/value field, eyedropper button, hue and alpha sliders, hex and RGBA fields, theme swatches, saved colours and a clear button; the colour control in the Session header is above it">
+</p>
+
+## Install
+
+Requirements:
+
+- DeepSeek Harness with a Web profile
+- Node.js 20 or newer
+- **Verified DSH version: `0.1.6-alpha.2`** (see [Compatibility](#compatibility))
+
+`@idoall/dsh-session-colors` is **not published on npm yet**, so install the
+repository directory for now (once published, the same plugin command installs
+the npm version):
+
+```sh
+dsh plugin --profile <profile> add link:/path/to/dsh-session-colors
+```
+
+Then give it a data directory in the profile's `cordis.patch.yml` — the same
+shape other plugins that need durability use, because **the plugin never guesses
+the profile path**:
+
+```yaml
+- id: dsh-session-colors
+  config:
+    dataDir: /absolute/path/to/profiles/<profile>/data/dsh-session-colors
+```
+
+Finally **restart `dsh web`** (the Host half loads only at boot), then refresh the
+Web GUI. It also works without `dataDir`, but then marks live only for the life of
+the Host process.
+
+## Usage
+
+1. Open the Session you want to mark.
+2. Click the colour control in the Session header (🎨 when the Session has no
+   colour, the colour itself once it has one).
+3. Pick a colour, or paste a hex value. The bar appears on that Session's sidebar
+   row immediately.
+4. To clear it, open the picker again and click **Clear mark**, or choose the
+   transparent swatch among the theme colours.
+
+Opening the picker on a marked Session starts from its current colour. Colours are
+stored as HSVA, so alpha round-trips exactly.
+
+<p align="center">
+  <img src="docs/images/mobile-drawer.png" width="300" alt="The sidebar drawer on a phone: the same Session list shows colour marks, with amber, red, green and blue visible at once">
+</p>
+
+## Compatibility
+
+Current release: plugin **`0.1.0`**, verified against DeepSeek Harness
+**`0.1.6-alpha.2`**.
+
+| Plugin version | Verified DeepSeek Harness | npm status | What it is |
+| --- | --- | --- | --- |
+| **`0.1.0`** | `0.1.6-alpha.2` | **Not published** (repository only) | First release: Session colour marks, Host-side storage, visible inside a phone's sidebar drawer |
+
+- **Verified DeepSeek Harness** is the exact DSH version this plugin was actually
+  run against. That list has one home — `dsh.compatibility.dshReleases` in
+  [`package.json`](package.json) — and a test keeps both READMEs' compatibility
+  sections word-for-word with it and inside the range `peerDependencies`
+  declares. A DSH version that is not listed is **never claimed as compatible**.
+- `peerDependencies` declares `>=0.1.6-0 <0.2.0` for `dsh-client-ui-layout` and
+  `dsh-client-ui-conversation`: that is the range allowed to **load**, which is
+  not the same as verified.
+- DSH moving faster than this plugin does not break it: chips depend on DSH's row
+  DOM (see [Limitations](#limitations)), so a large change to the row structure
+  can at worst stop chips from appearing — it cannot block clicking.
+
+## Cross-device and LAN
+
+Storage goes through the plugin's **own** HTTP route
+(`GET`/`POST /plugins/dsh-session-colors/marks`), persisted to one JSON file in
+the profile's data directory. That is deliberate:
+
+DSH's own user-settings service host-backs settings **only for loopback pages** —
+
+```js
+persistence = $host.isLoopback ? "host" : "memory"
+```
+
+— so a page opened over a LAN address or a tunnel gets a permanently unavailable
+scope: it can neither read nor write. An own route is not subject to that rule,
+which is exactly what makes a mark visible on every device. LAN forwarders
+(`dsh-bridge`, `dsh-lan-proxy`, and friends) rewrite `Host`/`Origin` to loopback
+and inject the auth cookie, so a request that arrives over the LAN still looks
+like loopback to DSH and the route answers normally.
+
+## Configuration
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `dataDir` | absolute path | Where `session-colors.json` is written. Without it, marks live in process memory only. |
+
+A mark is one JSON document:
+
+```json
+{
+  "version": 1,
+  "marks": {
+    "session-0698599a-…": { "h": 211.3, "s": 1, "v": 1, "a": 1 }
+  }
+}
+```
+
+Writes are **atomic** (temporary file, then rename). To drop a mark, use **Clear
+mark** in the picker, or remove that line from the file.
+
+## Troubleshooting
+
+**The colour still is not visible on my phone.**
+First check which build the device runs:
+
+```js
+document.querySelector('.dsh-sc-layer').dataset
+// { dshScBuild, dshScStatus, dshScWritable, dshScMarks, dshScError }
+```
+
+If `dshScBuild` is not `host-routes+drawer-aware`, the device is running a
+**cached client**: refresh the page (the browser half reloads on a refresh, no DSH
+restart needed). If `dshScStatus` is not `ready`, the store cannot be read — see
+the next item.
+
+**The header control shows ⚠.**
+That means the store cannot be reached: `dshScError` carries the reason and
+`dshScWritable` says whether writes are possible. This happens when the Host route
+was never registered (the profile did not load the plugin) or the data directory
+is not writable. It is **not** the same as "this Session has no colour".
+
+**A LAN page behaves differently.**
+Since `0.1.0` this plugin behaves identically on LAN/tunnel pages and loopback
+pages, because storage uses its own route. If you see the old "settings
+unavailable" behaviour, check which version is installed.
+
+**Chips are in the wrong place, or gone.**
+The layer finds rows by ARIA role and reads the Session id from the React fiber.
+A large change to DSH's sidebar structure can make it find nothing; chips then
+disappear, but **clicking is unaffected** because the layer is click-through.
+
+## Security boundaries
+
+- A mark stores **only a Session id and a colour**. It never writes Session logs,
+  titles, history, status, archive records, or Workspace membership.
+- It **never creates, copies, moves, or reorders a Session**; a mark is not part
+  of Session data.
+- The chip layer **never accepts pointer events** and is clipped to the sidebar's
+  scroll container: the worst case is a chip that does not appear.
+- The Host route reuses DSH's own auth fence (`connection.requestRejection`), and
+  writes add a same-origin check on top.
+- The plugin registers no model Tool, spawns no subprocess, and makes no network
+  requests.
+
+## Limitations
+
+- **The chip depends on DSH's row DOM.** It reads rows by ARIA role and the
+  Session id from React internals. A future DSH release can stop chips from
+  appearing; it cannot break clicking.
+- **Marks are per DSH instance.** They live in one profile's data directory, so
+  two independent DSH servers do not share them.
+- **No permission model.** Anyone who can reach the Host's authenticated routes
+  for this profile can read and write marks.
+- **Colour only.** No labels, icons, or emoji.
+
+## Uninstall
+
+```sh
+dsh plugin --profile <profile> remove @idoall/dsh-session-colors
+```
+
+Restart DSH and refresh the Web GUI. `session-colors.json` in the data directory
+is not deleted for you; remove it yourself if you do not want it.
+
+## Development
+
+```sh
+npm test        # 34 tests: bundle shape, store, route, cross-device, geometry, docs
+```
+
+The browser half is a hand-authored `__ModuleLoader__` bundle, which is the only
+format the DSH client loader accepts for a package client half. It is written by
+hand on purpose: there is no build step, so nothing can drift from the DSH
+version it targets.
+
+```
+src/index.js       Host half: routes, the JSON store, auth fence
+src/client.js      Browser half: picker, chip layer, the fetch-backed store
+tests/             Unit tests for both halves, plus the doc-consistency checks
+docs/              The design record (Chinese) and the README screenshots
+demos/             A standalone HTML demo of the picker
+```
+
+Design decisions and measurements live in
+[docs/plugin-design.zh.md](docs/plugin-design.zh.md) (the current part starts at
+the 「会话颜色标记版」 section).
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,192 @@
+<h1 align="center">DSH 会话颜色标记</h1>
+
+<p align="center">给任意会话上一个颜色，在侧栏一眼认出它。</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@idoall/dsh-session-colors"><img alt="npm" src="https://img.shields.io/badge/npm-%E6%9C%AA%E5%8F%91%E5%B8%83-lightgrey"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-0F172A"></a>
+</p>
+
+<p align="center"><a href="README.md">English</a> | 中文</p>
+
+<p align="center">
+  <a href="#功能">功能</a> ·
+  <a href="#安装">安装</a> ·
+  <a href="#使用">使用</a> ·
+  <a href="#兼容性">兼容性</a> ·
+  <a href="#跨设备与局域网">跨设备与局域网</a> ·
+  <a href="#配置">配置</a> ·
+  <a href="#故障排查">故障排查</a> ·
+  <a href="#安全边界">安全边界</a> ·
+  <a href="#限制">限制</a> ·
+  <a href="#卸载">卸载</a> ·
+  <a href="#开发">开发</a>
+</p>
+
+> DSH Session Colors 是 DeepSeek Harness 社区插件。它不修改 DSH 核心，也不改写任何会话或工作区数据：一个标记只是"会话 ID → 一个颜色"。
+
+工作分散在多个工作区里，而工作区列表就是一堵长得差不多的标题墙。任务跑完之后，刚才那条会话就很难再找回来——状态点已经回到空闲，标题也只是二十个里的一个。**自己选的颜色，是让一行变得好认的最省事办法。**
+
+<p align="center">
+  <img src="docs/images/sidebar-chips.png" width="280" alt="侧栏里的四个颜色标记：同一个工作区列表里四条会话各自带一条不同颜色的竖条（琥珀、红、绿、蓝）">
+</p>
+
+## 功能
+
+- **会话行上的颜色标记**——行左侧内边距里的一小段色条，**刻意避开状态点**，所以"哪个跑完了"这个信号不会被盖掉。
+- **系统风格的颜色选择器**——大色板、色相与透明度滑条、十六进制与 RGBA 输入、七个主题色、我的颜色，以及浏览器支持 `EyeDropper` 时的屏幕吸色。注册在会话头部的工具区，不占标题位置。
+- **一处标记，处处可见。** 标记存在**宿主**而不是浏览器里，所以在电脑上选的颜色，手机上也能看到——局域网地址、隧道访问都算。
+- **手机端同样显示。** 手机把侧栏变成抽屉，色块跟着抽屉走：抽屉滑进来时它一起移动，并且画在抽屉之上。
+- **自动获取改动。** 页面重新可见时、以及每 20 秒会重读一次，别的设备改了颜色不用刷新就能看到。
+- **绝不挡住界面。** 色块浮层**点击穿透**，并且按侧栏滚动容器裁剪；最坏情况只是色块不显示。
+- **失败会说。** 读不到存储时，头部控制会显示 ⚠ 并给出原因，而不是装作"这个会话没有颜色"。
+
+<p align="center">
+  <img src="docs/images/color-picker.png" width="276" alt="颜色选择器：色相/明度大色板、吸色按钮、色相与透明度滑条、十六进制与 RGBA 输入、主题颜色色板、我的颜色与清除标记按钮；上方是会话头部里的颜色控件">
+</p>
+
+## 安装
+
+要求：
+
+- 带 Web profile 的 DeepSeek Harness
+- Node.js 20 或更新版本
+- **已验证的 DSH 版本：`0.1.6-alpha.2`**（见[兼容性](#兼容性)）
+
+npm 上的 `@idoall/dsh-session-colors` **尚未发布**，所以现在装的是本仓库目录（发布后可用同样的插件命令装 npm 版本）：
+
+```sh
+dsh plugin --profile <profile> add link:/path/to/dsh-session-colors
+```
+
+然后在 profile 的 `cordis.patch.yml` 里给它一个数据目录（与其它需要持久化的插件做法一致，**插件不会去猜 profile 路径**）：
+
+```yaml
+- id: dsh-session-colors
+  config:
+    dataDir: /absolute/path/to/profiles/<profile>/data/dsh-session-colors
+```
+
+最后**重启 `dsh web`**（宿主半边只在启动时加载），再刷新 Web GUI。不配 `dataDir` 也能用，但标记只活在宿主进程的生命周期里。
+
+## 使用
+
+1. 打开要标记的会话。
+2. 点会话头部的颜色控件（未设色时显示 🎨，设色后显示该颜色）。
+3. 选一个颜色，或直接粘贴十六进制值。该会话在侧栏的行上会立刻出现色条。
+4. 取消标记：再次打开选择器，点**清除标记**，或选主题色里那个透明色块。
+
+在已标记的会话上打开选择器，会从它当前的颜色开始。颜色以 HSVA 保存，所以透明度能原样往返。
+
+<p align="center">
+  <img src="docs/images/mobile-drawer.png" width="300" alt="手机上的侧栏抽屉：会话列表里同样显示颜色标记，同一个列表里能同时看到琥珀、红、绿、蓝四条">
+</p>
+
+## 兼容性
+
+当前版本：插件 **`0.1.0`** 已针对 DeepSeek Harness **`0.1.6-alpha.2`** 验证。
+
+| 插件版本 | 已验证的 DeepSeek Harness | npm 发布状态 | 该版本是什么 |
+| --- | --- | --- | --- |
+| **`0.1.0`** | `0.1.6-alpha.2` | **未发布**（仅本仓库） | 首个版本：会话颜色标记、宿主侧存储、手机抽屉内可见 |
+
+- **已验证的 DeepSeek Harness** 是这个插件**实际跑过**的确切 DSH 版本。这份清单只有一个存放处——[`package.json`](package.json) 的 `dsh.compatibility.dshReleases`——并且有测试保证两个 README 的兼容性段落与它逐字一致、且落在 `peerDependencies` 声明的范围内。未列出的 DSH 版本**不会被宣称为兼容**。
+- `peerDependencies` 声明的范围是 `>=0.1.6-0 <0.2.0`（`dsh-client-ui-layout` 与 `dsh-client-ui-conversation`）：这是**允许加载**的范围，不等于已验证。
+- DSH 升级快于插件时，插件本身不会因此报错：色块依赖 DSH 的行 DOM（见[限制](#限制)），所以 DSH 大改行结构时最坏的结果是**色块不再显示**，不会挡住点击。
+
+## 跨设备与局域网
+
+存储走插件**自己的** HTTP 路由（`GET`/`POST /plugins/dsh-session-colors/marks`），落盘到 profile 数据目录里的一个 JSON 文件。这是**有意为之**：
+
+DSH 自带的用户设置服务**只对回环页面**做宿主持久化——
+
+```js
+persistence = $host.isLoopback ? "host" : "memory"
+```
+
+——所以用局域网地址或隧道打开的页面，设置 scope 会**永久不可用**，读不了也写不进。自有路由不受这条规则限制，这正是标记能跨设备的原因。局域网转发（`dsh-bridge`、`dsh-lan-proxy` 等）会把 `Host`/`Origin` 改写成回环并注入认证 cookie，所以经局域网进来的请求在 DSH 侧仍是回环，路由正常响应。
+
+## 配置
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `dataDir` | 绝对路径 | `session-colors.json` 的写入位置。不填则标记只存在于进程内存。 |
+
+标记是一个 JSON 文档：
+
+```json
+{
+  "version": 1,
+  "marks": {
+    "session-0698599a-…": { "h": 211.3, "s": 1, "v": 1, "a": 1 }
+  }
+}
+```
+
+写入是**原子**的（先写临时文件，再 rename）。要清掉某个标记，用选择器里的**清除标记**，或直接从文件里删掉那一行。
+
+## 故障排查
+
+**手机上还是看不到颜色。**
+先看设备跑的是哪个构建：
+
+```js
+document.querySelector('.dsh-sc-layer').dataset
+// { dshScBuild, dshScStatus, dshScWritable, dshScMarks, dshScError }
+```
+
+`dshScBuild` 不是 `host-routes+drawer-aware` 就是**客户端缓存**，刷新页面即可（客户端半边刷新即热重载，不需要重启 DSH）。`dshScStatus` 不是 `ready` 则是存储读不到，见下一条。
+
+**头部控制显示 ⚠。**
+表示读不到存储：`dshScError` 里有原因，`dshScWritable` 说明能不能写。宿主路由未注册（插件没被 profile 加载）或数据目录不可写时会这样。注意**这不是**"这个会话没有颜色"。
+
+**局域网页面上功能不全。**
+从 `0.1.0` 起本插件在局域网/隧道页面与回环页面行为一致（存储走自有路由）。如果你看到的是旧版那种"设置读不到"的表现，先确认装的是哪个版本。
+
+**色块位置不对或消失。**
+色块浮层靠 ARIA role 找会话行、靠 React fiber 取会话 ID。DSH 大改侧栏结构后可能找不到行；此时色块会消失，但**不会影响点击**，因为浮层是点击穿透的。
+
+## 安全边界
+
+- 标记只保存**会话 ID 与颜色**，不写会话日志、标题、历史、状态、归档记录或工作区归属。
+- **不创建、不复制、不移动、不重排任何会话**；标记不是会话数据的一部分。
+- 色块浮层**从不接收指针事件**，并且按侧栏滚动容器裁剪：最坏情况只是色块不显示。
+- 宿主路由复用 DSH 自带的鉴权栅栏（`connection.requestRejection`），写入另加同源检查。
+- 插件不注册模型 Tool、不启动子进程、不访问网络。
+
+## 限制
+
+- **色块依赖 DSH 的行 DOM。** 它靠 ARIA role 找行、靠 React 内部结构取会话 ID。DSH 未来改版可能让色块不再显示；但**不会影响点击**。
+- **标记属于单个 DSH 实例。** 它存在某个 profile 的数据目录里，两个独立的 DSH 服务之间不共享。
+- **没有权限模型。** 凡是能访问该 profile 已鉴权路由的人，都能读写标记。
+- **只有颜色。** 没有文字标签、图标或 emoji。
+
+## 卸载
+
+```sh
+dsh plugin --profile <profile> remove @idoall/dsh-session-colors
+```
+
+重启 DSH 并刷新 Web GUI。数据目录里的 `session-colors.json` 不会被自动删除；不需要就自行删除。
+
+## 开发
+
+```sh
+npm test        # 34 项：bundle 结构、存储、路由、跨设备、几何、文档一致性
+```
+
+浏览器半边是**手写的** `__ModuleLoader__` bundle——这是 DSH 客户端加载器接受的唯一格式。手写是刻意的：**没有构建步骤**，就不会有产物与目标 DSH 版本漂移的问题。
+
+```
+src/index.js       宿主半边：路由、JSON 存储、鉴权栅栏
+src/client.js      浏览器半边：选择器、色块浮层、fetch 存储
+tests/             两个半边的单元测试，外加文档一致性检查
+docs/              设计记录（中文）与 README 截图
+demos/             独立的选择器 HTML Demo
+```
+
+设计取舍与实测记录见 [docs/plugin-design.zh.md](docs/plugin-design.zh.md)；独立的选择器 Demo 见 [demos/session-color-mark-demo.html](demos/session-color-mark-demo.html)。
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# Bundle mount for the Session-colours plugin: one Host-side entry.
+#
+# `name` is the Node-resolvable package name and must stay in sync with
+# package.json; `id` is the local mount id, so profile config keys keep the
+# short `dsh-session-colors` spelling.
+#
+# Durability needs a `dataDir` from the profile owner — see README.md. Without
+# it the routes still answer and marks live for the process only.
+- insert:
+    - id: dsh-session-colors
+      name: '@idoall/dsh-session-colors'

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@idoall/dsh-session-colors",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "DSH web plugin: give any Session a colour mark, shown as a chip in the sidebar and picked from the conversation header. Marks are stored on the Host, so a colour chosen on one device is visible on every other one — including over LAN and tunnels.",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/images"
+  ],
+  "dsh": {
+    "manifestVersion": 1,
+    "compatibility": {
+      "dshReleases": {
+        "0.1.6-alpha.2": "compatible"
+      }
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.6-0 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-layout": ">=0.1.6-0 <0.2.0",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-client-ui-conversation": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-layout": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/idoall/dsh-session-colors.git"
+  },
+  "homepage": "https://github.com/idoall/dsh-session-colors#readme",
+  "bugs": {
+    "url": "https://github.com/idoall/dsh-session-colors/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek",
+    "deepseek-harness",
+    "harness",
+    "cordis",
+    "plugin",
+    "session",
+    "colors",
+    "sidebar",
+    "web"
+  ],
+  "packageManager": "pnpm@10.33.1"
+}