dsh-plugin-core 0.2.14 → 0.3.0

package/docs/design/architecture.md

@@ -1,6 +1,6 @@
 # 运行逻辑
 
-系统级分层、边界、触发关系与不变量。不写接口细节（那些在 `docs/design/features/`）。
+系统级分层、边界、触发关系与不变量。不写接口细节（那些在帮助文档区 `docs/help/`）。
 
 ## 一句话
 
@@ -9,7 +9,7 @@
 ```
 dsh-plugin-core/
 ├── design/         token + createStyleKit 注入器工厂 + 主题判据    （零 React）
-├── ui/             基础控件（Button / Input / Picker / Modal / toast …） （依赖 design）
+├── ui/             基础控件与布局容器（Button / Input / Picker / Modal / toast / PanelDock …） （依赖 design）
 ├── utils/          纯方法：日期 / 字符串 / 字节 / 时间区间 / HTTP / 路径    （零 React / DOM）
 ├── adv.explorer/   文件浏览成品（目录树 + 面包屑 + 预览）           （依赖 ui + utils）
 └── adv.session/    会话记录预览成品                                 （依赖 ui + utils）
@@ -51,21 +51,51 @@ utils（谁都不依赖，谁都可以用）
 为什么必须运行时注入：DSH 客户端产物是 `window.__ModuleLoader__.load({ id, factory })` 的
 CJS 闭包，`import './x.css'` 只会产出独立 css 资源、**内核不加载它** ⇒ CSS 只能以字符串在运行时注入。
 
+**但那只约束产物，不约束源码**。样式是分三层走的：
+
+```
+src/**/*.css            真源 —— 编辑器高亮 / 括号匹配 / 格式化 / CSS lint 都生效
+        │  scripts/gen-css.mjs（构建期：lightningcss 解析 + JSON.stringify）
+        ▼
+*.generated.ts         字符串常量（入库，勿手改）
+        │  tsc 1:1 编译
+        ▼
+dist/**                产物形态不变，仍由 createStyleKit 拼成一份文本注入 <style>
+```
+
+为什么要这一层：2026-10-19 曾因手写模板字符串结尾多一个反斜杠，在注入文本里留下字面反引号，
+吞掉紧随其后那条规则的选择器，排查耗掉一天（见 `docs/design/external/dsh-host.md` §9）。
+`JSON.stringify` 生成 + 构建期解析闸，把这类事故从根上删掉，产物形态却一点没变。
+
+改样式的正确姿势：改 `src/**/*.css` → `pnpm run gen:css`（或 `pnpm run build`）→ 提交含生成物与
+`dist/`。`pnpm test` 的 `pretest` 会跑 `gen:css --check`，生成物不同步直接红。
+
 为什么是工厂而不是模块级单例：单例只有一个固定 style id，多个插件同处一页时会抢同一个 `<style>` 标签、
 后挂载的覆盖先挂载的。每个插件领一套自己的（`id` 按插件唯一）；变量前缀全生态统一 `dshpc`。
 
 为什么 core 可以用模块级变量存「当前 kit」：core 会被**内联进每个插件各自的 bundle**（不是共享运行时），
 模块级变量天然按插件隔离，不像共享模块那样会互相踩。
 
-## 数据从哪来（组件不自己取数）
+## 数据从哪来
+
+工作区列表、模型列表、会话消息都要跨 host↔client 边界。分两条口径（2026-10-20 拍板）：
 
-工作区列表、模型列表、会话消息都要跨 host↔client 边界，而那条通道是**插件私有**的 ⇒ 组件取不到。
-所以统一约定：**数据由调用方经 props 给，宿主能力经接口注入**。
+- **通用控件是纯零件**：数据由调用方经 props 给，宿主能力经接口注入（`FileBrowser` /
+  `openFilePreview` / `pickWorkspaceFile`、`SessionPreview`、通用 `Picker` 都算这类）。
+- **领域选择器自带数据面**：`ModelPicker` / `WorkspacePicker` 经接线后**自己取数自己显示**，
+  消费方不再传数组。两条通路（2026-10-20 真机核实）：
+  - 工作区：client 侧 `ctx.inject(['workspaces'])` 的快照（getSnapshot + subscribe，follow 流实时更新），
+    封装在 `src/ui/host-data.ts` 的 `workspaceList`。
+  - 模型目录：client 侧 remote **拿不到**每个 provider 的模型 ⇒ 插件宿主侧
+    `llm.listModels()` 现查、`serveModelCatalog()`（`src/host/index.ts`，`./host` 子路径）挂成只读路由，
+    client 侧 `connectHost(ctx, { modelsPath })` fetch。两侧共用同一个 path 常量。
+  任一通路缺席只影响那一块，选择器渲染空态 / 降级提示。
 
-| 组件 | 要调用方给什么 |
+| 组件 | 数据从哪来 |
 |---|---|
-| `Picker` / `ModelPicker` / `WorkspacePicker` / `FilePicker` | 选项数据（props） |
-| `ExplorerPanel` | `WorkspaceFilesFace`（从 ctx 取出后注入） |
+| `Picker` | 选项数据（props） |
+| `ModelPicker` / `WorkspacePicker` | 自取（connectHost 接线；`groups` 参数仅作覆盖） |
+| `FileBrowser` / `openFilePreview` / `pickWorkspaceFile` | `WorkspaceFilesFace`（从 ctx 取出后注入） |
 | `SessionPreview` | `SessionSource`（同上） |
 
 不传整个 `ctx`：ctx 是宿主给的整个大对象，传进来就把本包和宿主版本焊死；只传需要的那一小块，

package/docs/design/copywriting.md

@@ -0,0 +1,95 @@
+# 文案撰写规范（.doc.ts 真源里的用户可见文案）
+
+适用：`docs/**/*.doc.ts` 里的 `heading` / `prose` / `api[].desc` / `code[].src`。
+由 `scripts/gen-docs.mjs` 投影成两份：`docs/**/*.md`（Agent / 人读，随包发布）与
+`doc-data.generated.ts`（demo 站读），所以**一份文案同时喂两个读者**，标准必须两头都成立。
+EN: Copy rules for every user-visible string in `docs/**/*.doc.ts`. One source feeds two projections
+(`docs/**/*.md` for agents/humans, `doc-data.generated.ts` for the demo site), so each rule must hold for both readers.
+
+## 读者定性
+
+**第一读者是 Agent。** demo 站是同一份文案的人类视图。
+Agent 打开文档只问三件事：**这是什么 / 怎么用 / 每个参数是什么**。答完即止。
+EN: The primary reader is an agent; the demo site is the human view of the same text. An agent asks only
+three things: what is it / how do I use it / what is each argument. Answer those and stop.
+
+## R1 · 禁止过程叙事 · No process narrative
+
+文档记录**现在是什么**，不记录**怎么变成这样**。
+
+| 禁写 | 改写成 |
+|---|---|
+| 日期、`2026-10-22 解包核实`、`unpack xxx@0.2.0-rc.2` | 直接给结论（结论要溯源就指 `external/` 里的核实文档） |
+| `拍板` / `定` / `二次拍板` / `ivc用户接受，不要自行优化` | 写成约束句：`必须 X` / `不要 Y` |
+| `推翻此前结论` / `此前以为…后来发现…` | 只写当前成立的事实 |
+| `已证伪、勿再尝试` / `某某方案已删` / `备选方案 ` | 删掉。若某写法确实危险，写成约束：`不要用 X（会 Y）` |
+| `已接上` / `已对齐官方结构` / `已上线` | 删掉，直接描述当前能力 |
+
+判据：一句话里如果出现了「曾经的另一个状态」，它就是过程，删。
+EN: Never record dates, who decided what,推翻/已删/已对齐, or any earlier state. Write the current fact only.
+Test: if a sentence contains a previous state of anything, it is process — delete it.
+
+## R2 · 一段一事、一段两句 · One fact per paragraph
+
+- 每段 ≤ 2 句，每段 ≤ 110 字（zh）；每句 ≤ 40 字。
+  **反引号内的 API 标识符不计入**（代码块、参数名不是散文，按字数惩罚它们会把有用信息砍掉）。
+- 一个 section 的 `prose` ≤ 5 段。写不下 = 拆 section，不是堆段。
+- 段首不用「另外 / 同时 / 值得一提」起句。
+- 例外：**步骤清单型**（一段一个整数编号步骤、几乎无标点扩充）不受段数限制，它是
+  「有一个以上代码块等待处、每步对应一句」的导航条，不是散文。`quickstart` 是例子。
+EN: ≤ 2 sentences and ≤ 110 characters (zh) per paragraph. A section carries ≤ 5 prose paragraphs; overflow
+means split the section. Exception: **stepped lists** (one numbered step per paragraph, each indexed against
+the code blocks below) are navigation, not prose, so the count limit does not apply — `quickstart` is the example.
+
+## R3 · 表格只装参数 · API cells are not essays
+
+`desc` 一格 = 一句话动词短语，写**是什么 / 不给会怎样**：
+
+| 差的写法 | 好的写法 |
+|---|---|
+| `本包 ui 已零官方依赖；要用官方件就在插件侧自己处理平台模块` | `本包 ui 不依赖官方件；要用请自行处理平台模块` |
+| `造型太花时间：因为右侧分栏在场时遮罩已让位，100vw 会溢出到分栏上` | `宽度用遮罩盒的 100%，不要用 100vw（会溢出到右侧分栏）` |
+| `归档 = 开分支确认框，未归档 = 直跳官方会话页，当然归档会话不进主视图` | `true = 开分支确认框；false = 直跳官方会话页` |
+
+- 默认值写进 `def`，不写进 `desc`。
+- 背景与动机写进 `prose`，不写进表格。
+EN: `desc` is one verb phrase stating what it is or what happens without it. Defaults go in `def`, rationale goes in `prose`.
+
+## R4 · 三处不许重复 · Say it once
+
+同一事实只能在 `prose` / `api.desc` / `code` 注释里出现**一次**。
+能在表里说清的，不进散文；能在代码里看懂的，不进表。
+EN: A fact appears exactly once, in the cheapest slot: table beats prose, code beats table.
+
+## R5 · 保留不变式，丢掉考古 · Keep invariants, drop archaeology
+
+保留：必填项、默认值、失败/降级行为、禁写顾忌、必须成对出现的参数。
+删除：调查路径、版本解包、被否方案、工作量描述（「无额外开发」这类）。
+EN: Keep required/default/failure behaviour and constraints. Drop investigation paths and rejected alternatives.
+
+## R6 · 双语对译 · Bilingual parity
+
+- `zh` / `en` 是**同一信息的两种语言**，不是翻译腔。术语表固定：`token`、`selector`、`invoke`、`dock`、`snapshot`、`fallback`、`mask`（EN 侧统一拼写，不用 Modal/弹出）。
+- 两个字段的段数、句数、信息量相同 —— `en` 不得比 `zh` 少半句或多一整段背景。
+- 代码块里的注释跟着 `lang` 走：代码块本身不双语，注释用英文。
+EN: `zh`/`en` carry identical information in identical shape — same count of paragraphs and facts.
+Code comments are English-only.
+
+## R7 · 格式与字段不变 · Format is frozen
+
+`id` / `heading` / `prose` / `api` / `code` 字段与 `section.id` 一律不动（demo 站按 id 取值）。
+本次只改文案内容，不改结构。新增/删除 section 是另一次变更。
+EN: Field names and `section.id` values are frozen — the demo reads entries by id. Only copy changes here.
+
+## 自检
+
+改完跑：
+
+```bash
+pnpm gen:docs && pnpm typecheck:docs
+```
+
+复审清单：① 全文搜 `\d{4}-\d{2}-\d{2}` 应零命中；② 搜 `拍板|推翻|证伪|已删|改造|当前不同的是` 应零命中；
+③ 任一 section 的 prose 段数 ≤ 4；④ 抽 3 条 desc，确认「一句话说得清」。
+EN: After editing run `pnpm gen:docs && pnpm typecheck:docs`. Review checklist: zero date hits, zero process-word hits,
+≤ 4 prose paragraphs per section, three sampled `desc` values readable in one breath.

package/docs/design/doc-format.md

@@ -0,0 +1,80 @@
+# 文档格式规范（.doc.ts 真源 + 双投影）
+
+## 一句话
+
+所有「既给 demo 展示、也给 Agent 读」的内容，**唯一真源**是 `docs/**/*.doc.ts`（typed 数据模块）。`scripts/gen-docs.mjs` 在构建期把它投影成两份：
+
+- `docs/**/*.md` —— 给 Agent / 人读，随包发布（`files: ["dist","docs"]`）。
+- `packages/demo/src/doc-data.generated.ts` —— 给 demo 零解析消费（入库、勿手改）。
+
+本仓既有铁律「真源在别处就不抄第二份」（`docs/README.md` 三条硬约定）在此落为机制：demo 与 md 都从 `.doc.ts` 派生，绝不手写第二份内容。
+
+## 为什么不是 MD 真源
+
+- `md → 数据` 是解析，永远缺斤少甲：转义管道、列头校验、禁多行单元格……防不住子集外的写法。
+- `数据 → md` 是渲染，容易且完备。
+- TS 两头占：机器侧同 JSON 之强且**类型即 schema**（`tsc` 编译期校验），人侧 prose 走模板字符串（`src/utils/i18n.ts` 59KB 同款先例），零新依赖。
+- JSON prose 满篇转义、YAML 要引解析器依赖或手搓子集（重回 fragile），均否。
+
+## 文件组织
+
+| 角色 | 落位 | 说明 |
+|---|---|---|
+| 真源（手写） | `docs/help/<主题>.doc.ts` | 一主题一文件（`index` / `integration` / `ui` / `design` / `utils` / `explorer` / `session`）；帮助侧唯一的输入 |
+| 生成（引用方 / Agent 读） | `docs/help/<主题>.md` | 由 gen-docs 从 `.doc.ts` 生成，覆盖同名手写文件；**勿手改** |
+| 生成（demo 消费） | `packages/demo/src/doc-data.generated.ts` | 按 `section.id` 扁平聚合；**勿手改** |
+
+真源只放**帮助侧**（`docs/help/`）：开发侧文档（`requirements.md` / `architecture.md` / `structure.md` /
+`external/**` / 本文件 / `copywriting.md`）保持手写 md，不进投影——demo 不展示、无漂移风险。
+手写的 `.doc.ts` 若写在别处，必须在 `gen-docs.mjs` 的 `MAP` 里登记才会被处理。
+
+## schema（权威定义在 `docs/design/doc-format.ts`）
+
+```ts
+export type Bilingual = { zh: string; en: string }
+export type ApiRow = { name: string; type: string; def: string; required?: string; desc: Bilingual }
+export type ApiTable = { id: string; rows: ApiRow[] }
+export type CodeBlock = { id: string; lang: string; src: string }
+export type Section = {
+  id: string                         // 全局唯一，且 1:1 对应 demo 的 SectionId
+  heading: Bilingual
+  prose?: Bilingual[]
+  api?: ApiTable[]                  // 一个 section 可有多张表，按数组顺序渲染
+  code?: CodeBlock[]
+}
+export type DocTopic = {
+  title: Bilingual
+  topics?: string[]
+  exports?: string[]
+  display?: Record<string, Bilingual>
+  sections: Section[]
+}
+```
+
+## section.id 契约（解耦关键）
+
+- 每个 `section.id` **全局唯一**，且 **1:1 对应** demo 的 `SectionId`（`packages/demo/src/sections/index.tsx`）。
+- gen-docs 把所有 `.doc.ts` 的 `sections` **按 id 扁平聚合**成 `docData[id]`；demo 只写 `docData[sectionId]`，与「这段在哪个文件、属于哪个子包」无关。
+- **重分类零成本**：拆文件 / 挪 group 只动 `MAP` 和文件内 section 摆放，demo 页（按 id 取）一行不动。
+- 重 id → gen-docs 直接报错退出（闸）。`--check` 还会校验「每个 demo `SectionId` 都有对应 doc `section.id`」（见阶段4 测试）。
+
+## 双语
+
+所有用户可见文案都是 `{ zh, en }`。demo 的 `locale` 选对应字段；样式、组件、布局**不进真源**（已在仓库 CSS 生成链 `gen-css.mjs` 单独处理）。
+
+## 类型闸与生成
+
+| 命令 | 作用 |
+|---|---|
+| `pnpm typecheck:docs` | `tsc -p tsconfig.docs.json` 校验 `.doc.ts` 结构（schema 即闸） |
+| `pnpm gen:docs` | 重新生成两份投影 |
+| `pnpm gen:docs --check` | 比对已落盘的 `doc-data.generated.ts` 是否最新，不一致退出 1（挂 `pretest`） |
+
+`build` 含 `gen:docs`；`pretest` 含 `gen:docs --check`；`prepublishOnly` 双保险（发布前 regen）。
+
+## 随包与 Agent 读取
+
+- core 包 `files: ["dist","docs"]` 同时发 `.md` 与 `.doc.ts`；Agent 的入口是
+  `node_modules/dsh-plugin-core/docs/help/index.md`（按任务挑一份，不必全读）。
+- 插件产物不含文档：bundler 不吃 `.md`/`.ts` 文档（无 md/text loader），文档不进 bundle。
+- 消费方指引句（抄进各插件项目 `AGENTS.md`）见本仓 `docs/README.md` 阶段5 行。

package/docs/design/doc-format.ts

@@ -0,0 +1,39 @@
+// 文档真源（.doc.ts）的类型 schema。改这里 = 改结构；tsconfig.docs.json 编译期校验。
+export type Bilingual = { zh: string; en: string }
+
+export type ApiRow = {
+  name: string
+  type: string
+  def: string
+  required?: string // 可选：「必填」列（是/否）
+  desc: Bilingual
+}
+
+export type ApiTable = {
+  id: string
+  rows: ApiRow[]
+}
+
+export type CodeBlock = {
+  id: string
+  lang: string
+  src: string
+}
+
+// section.id 必须全局唯一，且 1:1 对应 demo 的 SectionId（packages/demo/src/sections/index.tsx）。
+// gen-docs 按 id 扁平聚合 docData[id]；重 id 直接报错退出。
+export type Section = {
+  id: string
+  heading: Bilingual
+  prose?: Bilingual[]
+  api?: ApiTable[] // 一个 section 可有多张表，按数组顺序渲染
+  code?: CodeBlock[]
+}
+
+export type DocTopic = {
+  title: Bilingual
+  topics?: string[]
+  exports?: string[]
+  display?: Record<string, Bilingual>
+  sections: Section[]
+}

package/docs/design/external/dsh-host.md

@@ -14,7 +14,10 @@
   但它同样要回答「css 资源谁来加载」——而内核不加载（见上），哈希类名对应的规则页面上根本不存在。
 - 官方自己的做法也是运行时注入：官方 CSS module 由宿主注入 `<style data-plugin-css="…">`。
 - ⇒ 本包把 CSS 以 **TS 字符串**分发、运行时注入。这不是偏好，是宿主产物形态决定的。
-- 若将来宿主支持加载 css 资源，可回归 `.css` + CSS Module——那是破坏性变更，要发 major。
+- ⚠️ 这条只约束**产物**：源码自 2026-10-19 起就是真的 `.css` 文件（`src/**/*.css`），
+  由 `scripts/gen-css.mjs` 在构建期转成 `*.generated.ts`（见 `docs/design/architecture.md` §样式注入）。
+  两者不冲突——真源享受编辑器的高亮/括号匹配/格式化，产物仍是一段字符串。
+- 若将来宿主支持加载 css 资源，可让产物也回归 `.css` + CSS Module——那是破坏性变更，要发 major。
 - 来源：同上（三处 css.ts 注释结论 + 官方 `official-classes.ts` 观察到的注入形态）。
 
 ## 2. 官方包只在宿主编解，Node / 非内核环境不可解析
@@ -35,6 +38,22 @@
 - 后果：本包调用处一律显式传 `{}`。
 - 来源：`dsh-task-dispatch-table/src/client/file-preview.tsx` 的 `WorkspaceFilesFace` 注释（真机 2026-10-03 踩坑记录）。
 
+## 3.1 `read` / `readBytes` 参数的**取值**约束（2026-10-21 读官方源码核实）
+
+- 版本：`@deepseek-ai/dsh-api-workspace-files@0.2.1-rc.2`（`lib/index.js` / `lib/typert.remote-client.js`）。
+- `read` 的 `range = { offset?, limit? }`：`offset` **从 1 起算**（`resolvePage` 里
+  `integerAtLeast(range.offset, 1)`，缺省 1）；`limit` 缺省 `maxLines`，**超过即抛
+  `gateway/bad-request`**（部署默认 `maxLines = 5000`）。⇒ 首页传 `{}`、翻页传 `{ offset }`，
+  **不要自己塞 limit**（曾经塞 `limit: 5000` 且 `offset: 0`，所有文件一律「加载失败」）。
+- `readBytes` 的 `options` 是 **strictObject**，只认 `range` / `baseFile` 两个键，
+  `{}` 合法；不带 `range` = 读全量，上限是部署 `maxFileBytes`（默认 32MiB），超出抛
+  `workspace-file/too-large`。
+- 两者成功体都在信封 payload：`read → { offset, text, lines, eof, absolutePath, version, bytes? }`，
+  `readBytes → { offset, data: Uint8Array, eof, absolutePath, version, bytes? }`。
+- 定位共用 `locateFile`：`path` 为空抛 `gateway/bad-request`，不存在抛 `workspace-file/not-found`，
+  非普通文件抛 `workspace-file/not-regular-file`。
+- 来源：官方包 `lib/index.js:427/447/536/546/589`、`lib/typert.remote-client.js:44-76`。
+
 ## 4. 明暗判据
 
 - 事实：宿主启动脚本 `toggleAttribute` 往 body 写 `data-ds-dark-theme`，是**唯一**明暗判据，
@@ -73,3 +92,133 @@
 - 后果：`dsh-task-dispatch-table/src/client/mirror/` 有 15 个逐行镜像官方 `ui-tool` 的文件；
   「会话预览要长得像官方」必须自己维护这套镜像，且**宿主升级就要跟着改**。
 - 状态：本包 `session` **尚未搬入**这套镜像，只有最简渲染 + `renderMessage` 扩展点。
+
+## 9. 插件注入的 CSS 曾被自己的模板字符串污染（2026-10-19，已修复）
+
+- ❌ **已作废的结论**：本项目曾长期认为「宿主会吃掉 token 块之后的**第一条** CSS 规则」，
+  并据此在控件样式最前面加了一条 `.dshpc-css-guard{display:none}` 牺牲规则。**这是误判，
+  官方没有这种行为。** 该牺牲规则机制已整体删除。
+- **真因**：`src/design/tokens-css.ts` 模板字符串结尾多写了一个反斜杠（写成 `\`` 而非 `` ` ``），
+  字符串内容里因此多出一个**字面反引号**。所有 CSS 拼成一份文本写进 `<style>` 时，反引号正好落在
+  tokens 与控件样式的交界处；CSS 解析器把它当成不合格选择器的开头，一路吞到下一个 `{`，
+  ⇒ **紧随其后的那条规则的整个选择器**被污染（`.dshpc-seg` → `` `.dshpc-seg ``），永远匹配不到元素。
+- **后果**：规则仍在 CSSOM 里（所以按选择器名去查会误判为“规则不存在”），但永不生效。
+  当时排首位的是 `.dshpc-seg{display:inline-flex;}` ⇒ 轨道退化成 `block` ⇒ `gap`/`padding`
+  对 block 容器无效 ⇒ 星期方块挤成一坨。拆成多条单声明时「只有第一条失效」也是同一原因。
+- **为什么长期没被发现**：CSS 天生容错（非法 token 走错误恢复，不抛错、不打日志）；TS 里
+  `\`` 是**合法转义**（语法完全正确）；而当年的牺牲规则恰好排反引号之后替它挨刀，
+  现象被“修好了”，反而加固了错误结论。
+- **官方侧核实**（`github.com/deepseek-ai/deepseek-harness`）：插件 `<style>` 相关代码只有两处——
+  `packages/client/modules/src/client/system.ts` 的 `claimStyles`（给 factory 执行期新增的、
+  未标记的 `<style>` 打 `data-plugin` 并登记 `data-plugin-css`）与
+  `packages/client/modules/src/client/entry-lifecycle.ts` 的 `removeOwnedStyles`（卸载时 `el.remove()`）。
+  **没有任何代码改写 `textContent` 或操作 `cssRules`。**
+  官方自己的注入顺序是 `textContent` 先、`appendChild` 后（`packages/client/tsdown.client.ts`），
+  与本仓相反——但**该差异与本次事故无关**（用 `replaceSync` 即可复现，完全不经 DOM 插入）。
+- **防再犯**：`test/css-contract.test.mjs` 现在断言——注入文本（tokens + 控件）不得含反引号/反斜杠、
+  tokens 模板必须以 `}` 收尾、括号与注释平衡。
+- ⚠️ **教训**：只凭现象推断的“谁吃了规则”，在读到对方源码前不要写成结论；先看拼接处的原始字节。
+- 来源：`packages/demo/src/probes.ts` P27–P34 实测（2026-10-19，用户回传读数）+ 官方仓库源码 +
+  本仓 `ledger/worklog/202610/19-1604-按钮与输入分区控件样式全面梳理与修复-823a.md`。
+
+## 10. 官方 HoverCard 的 compact 变体不设文字色（2026-10-19 实测）
+
+- **事实**：`HoverCard` 的默认 `variant` 就是 `'compact'`，走 `.card`。该变体**只写背景、不写 `color`**：
+
+  | 变体 | 背景 | 文字色 |
+  |---|---|---|
+  | `.card`（compact，默认） | `--dsw-hovercard-bg: #2C2C2E`（**硬编码，不随明暗变**） | **无声明** |
+  | `.preview` | `--dsw-alias-bg-layer-1`（跟随主题） | `--dsw-alias-label-primary` |
+
+  卡片最终 `createPortal(card, document.body)` ⇒ 挂在 `body` 直下 ⇒ 文字色退化为**继承**。
+- **后果**：亮色主题下继承到 body 的前景色（实测 `rgb(15,17,21)` ≈ `#0f1115`），压在 `#2C2C2E` 深底上
+  ⇒ **黑字看不清**；暗色下继承到近白，看起来正常。**只有亮色暴露。**
+- **为什么官方自己不暴露**：`.card` 的 `content` 收任意 ReactNode，宿主自己传的都是官方组件（自带 color）。
+  传裸 `div` / 纯文本就会踩到。本仓 demo 正是这么踩到的（已修）。
+- **修法**：由**调用方自己给内容色**。因为背景恒为 `#2C2C2E`（官方写死的深色），内容就该恒亮——
+  用官方在同场景（Tooltip 深底）使用的常量 `--dsw-static-neutral-bluish-00`（`#fff`）。
+  ⚠️ 别用 `--dsw-alias-label-primary`：它在亮色下是近黑，压深底正好复现这个 bug。
+- **对照：官方 Tooltip 没有这个问题**——`.bubble` 两条声明齐全
+  （`background: var(--dsw-alias-tooltip-bg)` + `color: var(--dsw-static-neutral-bluish-00)`），
+  实测亮/暗都正常。气泡带 `role="tooltip"`，需要选中它时可用该属性（不要用 CSS-module 哈希类名）。
+- 来源：`@deepseek-ai/dsh-client-ui-primitives@0.2.1-rc.2`
+  · `lib/HoverCard.module.css` 的 `.card` / `.preview`
+  · `lib/index.js` 的 `function HoverCard({ …, variant = "compact", … })`
+  · 真机实测 2026-10-19（宿主**亮色**）：浮层类名 `_card_38jqx_9`、`role: null`、
+    父节点 `BODY`、`color: rgb(15,17,21)`、`background: rgb(44,44,46)`。
+
+## 11. client 侧现成数据面：`workspaces` 服务与 `remote.llm`（2026-10-20 核实）
+
+- 事实 1（工作区）：官方 client 挂了 cordis 服务 **`workspaces`**（`IWorkspaces`），
+  其 `list` 是 observable 快照源（`getSnapshot()` + `subscribe()`）；
+  快照 `items: readonly WorkspaceView[]`，每行含 `workspaceId` / `path` / `title` /
+  `sessionIds` / `createdAt` / `updatedAt`；数据由宿主 `workspace/follow` 流实时推送。
+- 事实 2（模型）：client remote 命名空间 **`llm`** 有 `listProviders()`（已注册路由，
+  `{id, name}`）与 `listConfigurableProviders()`（可配置目录，带 `settingsNs` /
+  `settingsPath`）。**各 provider 的已配模型不在 remote 里**——要读设置镜像
+  （`configForms.describe()`）里该 provider profile 的 `models` 数组，且只认用户层
+  真正写过的（空壳 profile 不算）。写法照 `dsh-session-title-pattern` 的 DirectoryStore。
+- 事实 3（归档集合，2026-10-22 解包 `0.2.0-rc.2` 核实）：`workspaces.list` 快照**还带**
+  `archivedSessionIds: readonly SessionId[]` —— **registry-global** 归档集合（宿主
+  `workspaceRegistry.archivedSessionIds` 那一份，**不是每工作区一份**），由 follow 流的
+  baseline / `archived` 增量整体替换（`client/model.js` `installArchived`、
+  `client/index.js` `accept.replaceArchived`）。某会话是否已归档 = `archivedSessionIds` 里有它。
+  - ⚠️ **推翻的旧结论（2026-10-22）**：曾以为「归档集合 client 读不到，只能宿主侧读
+    `workspaceRegistry` 挂只读路由」，且误按**每个工作区实体**的 `archivedSessionIds` 取数
+    （实体的这个字段根本不存在；`types.d.ts` 里它只出现在 `WorkspaceArchiveValue` /
+    `WorkspaceBaseline` / follow 增量上）⇒ 集合恒为空，已归档会话一个都标不出来。
+    那条宿主路由（`serveArchivedSessions`）已删除，改走 `workspaces` 快照。
+- 后果：工作区在 client 侧 `ctx.inject(['workspaces'])` 即可自取（本包 `workspaceList` 就是它的镜像）。
+- ⚠️ **模型不能只靠 client**：`remote.llm` 只有 `listProviders` / `listConfigurableProviders` /
+  `discoverModels`，**没有「某 provider 的模型列表」**；模型只能宿主侧
+  `llm.listModels(providerId)` 取（`dsh-task-dispatch-table/src/dispatch.ts:81-88` 实测用法）。
+  ⇒ 要模型就得插件 host 半侧挂一条只读路由（本包 `src/host/index.ts` 的 `serveModelCatalog`）。
+- ❌ **已废弃的结论（2026-10-20）**：曾以为「读设置镜像 `configForms.describe()` 里各 provider
+  profile 的 `models`」能拿全（照抄 dsh-session-title-pattern 的 DirectoryStore）。真机上 demo
+  按此路子读出来是 0 个供应商（describe 快照里的命名空间不保证含 provider 模型）。别再走它。
+- 来源：`@deepseek-ai/dsh-api-workspace-controller@0.2.0-rc.1`
+  · `lib/types/client/index.d.ts:19`（`workspaces: IWorkspaces`）、`lib/types/client/index.js:8`
+  （client 模块 inject = `['remote','remote.workspace']`）、`lib/types/client/service.d.ts:38`
+  · `@deepseek-ai/dsh-llm` `lib/typert.remote-client.d.ts:10-12`
+  · `dsh-session-title-pattern/src/client/model-pair.tsx:32-217`（模型目录组装口径）
+
+### 11.1 插件宿主侧数据面：`llm.listModels` + `webServer.register`（2026-10-20 核实）
+
+- 事实（`@deepseek-ai/dsh-llm` 宿主服务）：`listProviders()` 同步返回已注册 provider
+  `{id,name}`；`listModels(providerId)` **异步**返回该 provider 可发现的模型
+  （advisory，未列出 ≠ 不可用）。单个 provider 抛错要局部跳过，不整表失败。
+- 事实（`webServer` 服务）：`register({ kind:'exact' | 'prefix', path, handler(req,res) })`；
+  客户端同源相对路径 `fetch('/api/xxx')` 即可取（`dsh-task-ledger` / `dsh-task-dispatch-table` 同款）。
+- 口径：**模型目录必须走宿主 → 路由 → client**；client 侧 remote 只够列供应商名字。
+  本包 `src/host/index.ts` 的 `serveModelCatalog()` 封装了这条链路，`connectHost(ctx, { modelsPath })`
+  在 client 侧 fetch 同一个 path。
+- 来源：`dsh-task-dispatch-table/src/host.ts:214-232`（`HostLlm` 面）、`src/dispatch.ts:81-88`（listModels 用法）、
+  `dsh-task-ledger/packages/plugin/src/host/routes.ts:20-44`（webServer.register + sendJson）。
+
+## 12. workspaceFiles.list / read 的路径语义与越界判定（2026-10-22 解包核实）
+
+- 版本：`@deepseek-ai/dsh-api-workspace-files@0.2.1-rc.2`（npm 拉包读 `lib/index.js`；0.2.0-rc.2 / 0.2.1-rc.1 的 confine 逻辑一致）。
+- **list 的 path 绝对/相对都收**（jsDoc `index.js:491` "absolute or relative to the workspace root"）：`inspect`
+  用 `lstat(path, { cwd: workspaceRoot })`（`index.js:563-571`），空 path 抛 `gateway/bad-request`
+  （本仓 `listPathOf('') → '.'` 的由来），不存在抛 `workspace-file/not-found`，非目录抛 `not-directory`。
+- **目录列举限会话工作区内**：`confine`（`index.js:576-583`）`resolve` 后
+  `contains(root, target)` 为假 ⇒ 抛 `workspace-file/outside-workspace`。**这是 list 专属**。
+- **read / readBytes 允许工作区外文件**（jsDoc `index.js:421` / `480` "files outside it are allowed"），
+  无 contains 检查 ⇒ 绝对路径直读任何 OS 可达文件。**后果**：同一绝对路径，read 成功而 list(父目录)
+  被拒是官方设计的不对称，不是 bug——表现为「文件预览正常、路径栏/目录树退化成只读」。
+- **list 是会话作用域服务**：`workspaceFileScope.workspaceRoot` 按 sessionId 派生（`index.js:563`；
+  兄弟项目 `dsh-task-dispatch-table/src/host.ts:177` 注释同结论：「list 以 sessionId 解析工作区根，
+  必须有属于该工作区的会话才能列其文件」）。⇒ 调用方只给绝对路径时，默认 sessionId 的根未必含它。
+- **错误码全集（0.2.1-rc.2）**：`gateway/bad-request`、`workspace-file/not-found`、`not-directory`、
+  `not-regular-file`、`outside-workspace`、`too-large`、`not-text`、`invocation-unavailable`、
+  `service-unavailable`。⚠️ **没有 `lookup-not-found`**（本仓 `errView` / `noteOutside` 曾误引，
+  2026-10-22 移除，来源为初版 commit eca3f25，无官方依据）。
+- **对照**（`github.com/omdsh-dev/DSH-better-sidebar`，2026-10-22 读）：它的文件树**不走**官方
+  `workspaceFiles.list`，走自建 host 路由 `fs.tree`（host 直接 fs）；且 v0.23.0 起删掉了自己的
+  workspace fence（README 原话：「fs 路由不做 workspace 包含检查……调用方不得把这些路由当作有栅栏的」）
+  ⇒ 它那里「跨工作区随便逛」是绕开官方 confinement 的结果，**不代表官方 API 贯通**。
+- 处置（本仓）：`workspaceAnchorForPath`（`src/explorer/types.ts`）按最长前缀把绝对路径解析到
+  宿主工作区清单里的所属工作区，list 换该工作区名下的会话 id；`openFilePreview({ workspaceAnchors })`
+  透传；匹配不到 ⇒ 回落 `props.sessionId` + `crumbBarPlain` 的 hint 说破原因。
+- 来源：官方包 `lib/index.js:489-512 / 563-583 / 421 / 480`；`dsh-task-dispatch-table/src/host.ts:174-187`；
+  `dsh-better-sidebar` README + `docs/plans/2026-08-29-workspace-fence-toggle-design.md` + `src/client/use-session-root.ts`。

package/docs/design/features.md

@@ -1,19 +1,6 @@
-# 功能总索引
+# 功能总索引（不适用）
 
-本包提供什么、对应哪个文件。详细用法在 `docs/design/features/<包名>.md`。
+本槽位由帮助索引 `docs/help/index.md` 承担：它按「你要做的事」路由到各功能文档，
+并在随包发布时直接作为引用方与 Agent 的入口。本文件不再维护第二份内容。
 
-| 子路径 | 提供什么 | 详细文档 |
-|---|---|---|
-| `dsh-plugin-core/design` | token 变量表（含深色段）、`createStyleKit` 注入器工厂、`DARK_THEME_SELECTOR` | [`features/design.md`](features/design.md) |
-| `dsh-plugin-core/ui` | 控件：Button / IconButton / Segmented / Textarea / Checkbox / Input 家族 / Picker / ModelPicker / WorkspacePicker / FilePicker / **Card** / **StripCard** / **Chip** / Modal / toast / Loading / SectionHead / MarqueeText / LiveText / BackToTop / resizer / EmptyState / ErrorBoundary | [`features/ui.md`](features/ui.md) |
-| `dsh-plugin-core/utils` | 日期（含相对时间过去/未来）、字符串、字节/计数、时间区间、HTTP 取数、内置中英多语言 | [`features/utils.md`](features/utils.md) |
-| `dsh-plugin-core/explorer` | `ExplorerPanel`（面包屑 + 目录树 + 预览）、`WorkspaceFilesFace` 契约与路径工具（**不含选择器**——选工作区/选文件在 ui） | [`features/explorer.md`](features/explorer.md) |
-| `dsh-plugin-core/explorer/preview` | 单文件预览体（文本 / 图片 / 不支持兜底） | 同上 |
-| `dsh-plugin-core/session` | `SessionPreview`（弹窗 / 侧栏 / 整页三种承载）、`SessionSource` 契约、`renderMessage` 定制扩展点 | [`features/session.md`](features/session.md) |
-
-## 不提供什么
-
-- 官方会话 UI 的完整镜像（工具卡 / 代码块 / 推理行）—— `session` 目前只有最简渲染，
-  富内容走 `renderMessage` 扩展点。
-- 代码语法高亮 / PDF / Office 预览 —— `explorer` 的预览只有文本与图片。
-- 设置页骨架、i18n 框架（插件自己的文案插件自己管）、`host` 宿主类型面。
+本槽位在上级规则里是**路径固定**的，故保留文件与槽位行，不删、不改名、不挪位。

package/docs/design/methods.md

@@ -1,43 +1,22 @@
-# 方法规范
+# 方法规范（本仓内部）
 
-`utils` 的口径：**解析失败不抛错、给兜底、不编造**。这是全包统一的方法论，
-新增方法时按这一页的口径来，别自创一套。
+> EN: Helper conventions (internal)
 
-## 总口径
-
-| 情形 | 统一行为 |
-|---|---|
-| 输入解析失败（日期 / 数字） | **不抛错**，返回调用方兜底；兜底可传则传，不可传用固定占位 |
-| 固定占位 | 日期类 `—`，时刻类 `-`，体积类 `—`；调用方可用 `opts.fallback` 覆盖 |
-| 空值（`null` / `undefined` / 空串） | 与解析失败同口径，不特殊崩 |
-| 边界值（0 / 负数 / NaN） | 明确处理并写进注释，不静默通过 |
-| 时区 | 一律**本机时区**（沿用三家现有口径）；要显式时区请在调用方转换后再传 |
-
-## 为什么解析失败不抛错
-
-这些函数大量用在渲染路径上（列表每一行都调）。一个坏数据让整页崩 vs 显示一个占位符——
-后者明显是我们要的。**但兜底不能编造**：不知道就不显示，不要猜一个时间。
-
-## 分模块口径
-
-- **日期**：见 [`features/utils.md`](features/utils.md) 的表格，每个函数的失败返回都列了。
-  `relativePast` / `relativeFuture` 对偶，别用错。
-- **字符串**：`truncateBytes` 按 **UTF-8 字节**截断，不切半个字（中文场景必须）。
-  `baseNameOf` 处理目录尾斜杠，不会取成空串。
-- **数字**：`formatBytes` 对 0 与负数返回 `—`，不显示「0 B」这种假精确。
-- **HTTP**：默认 10s 超时；超时抛 `AbortError`，非 2xx 抛带 `status` 的 `HttpError`。
-
-## 多语言口径
-
-- 核心提供的固定提示语 ⇒ 本包内置中英（`setLocale` 切）。
-- 需要文案的 API 一律可传 `translate: Translate` 覆盖，默认走内置。
-- 插件自己界面的文案 ⇒ 插件自己管，本包不提供插件级 i18n 框架。
-- 新增 key 必须被真正使用（`test/no-dead-keys.test.mjs` 盯着，死 key 会让测试红）。
+使用侧内容（统一口径与返回值约定）在帮助文档区 `docs/help/`。
+本文件只留**往 `utils` 里加方法时**要守的东西。
+EN: The caller-facing material (shared contract and return values) lives in `docs/help/`. What stays here is
+only what you must honour when **adding a helper to `utils`**.
 
 ## 新增一个方法的 checklist
 
+> EN: Checklist for a new helper
+
 - [ ] 失败路径有明确兜底，且兜底可覆盖
 - [ ] 边界值（空 / 0 / 负 / NaN）有测试
 - [ ] 进了 `src/utils/index.ts` 出口（曾漏过 `relativeFuture`）
 - [ ] 需要文案的走 `t()` + `translate` 参数
-- [ ] 在 [`features/utils.md`](features/utils.md) 的表格里登记一行
+- [ ] 在帮助文档区 `docs/help/` 的对应参数表里登记一行
+
+EN: Failure path has a clear, overridable fallback; edge cases (empty / 0 / negative / NaN) covered by tests;
+exported from `src/utils/index.ts`; text goes through `t()` + `translate`; registered as a row in the
+matching parameter table under `docs/help/`.