# dsh-better-summary 详细设计

> 状态：**v1 已实现并全部验证通过**（typecheck / 143 项单元与组件测试 / 5 条 E2E lane 全绿）
> 目标版本：v1（无撤销 / 内联 diff / 保留「在文件夹中显示」）
> 约束：不修改 `deepseek-harness/` 任何源码；关键路径不依赖 git
> 实现与设计的差异见 [§18 实施记录](#18-实施记录与设计的差异)。

---

## 目录

1. [背景与目标](#1-背景与目标)
2. [决策记录](#2-决策记录)
3. [技术调研结论（证据链）](#3-技术调研结论证据链)
4. [总体架构](#4-总体架构)
5. [数据推导抽象层](#5-数据推导抽象层)
6. [卡片 UI 规格](#6-卡片-ui-规格)
7. [设置与动态调整](#7-设置与动态调整)
8. [Host 半边设计](#8-host-半边设计)
9. [包与工程形态](#9-包与工程形态)
10. [配置项总表](#10-配置项总表)
11. [边界与降级矩阵](#11-边界与降级矩阵)
12. [测试与 E2E 验证](#12-测试与-e2e-验证)
13. [安全与隐私](#13-安全与隐私)
14. [性能](#14-性能)
15. [风险与缓解](#15-风险与缓解)
16. [实施步骤](#16-实施步骤)
17. [未来增量](#17-未来增量)
18. [实施记录（与设计的差异）](#18-实施记录与设计的差异)
18. [附录 A：DSH 接口证据索引](#附录-adsh-接口证据索引)
19. [附录 B：落地前待验证项](#附录-b落地前待验证项)
20. [附录 C：术语](#附录-c术语)

---

## 1. 背景与目标

### 1.1 背景

DSH 的对话流在每轮结束时渲染一行「任务产出」：文件 chip + 省略计数 + 「在文件夹中显示」。该位置是 **list** 槽 `conversation.chat.turnTail`：条目按 `id` 划分单元格，同一单元格内按 priority **升序遮蔽**，只有最低的存活条目渲染；新 `id` 追加一行，复用已有 `id` 即顶替该行。在本部署中，这一行实际由已安装的第三方插件 **`dsh-better-sidebar`** 接管渲染（它沿用 DSH 自带产出行的单元格 `id`，priority `-1`，遮蔽自带 `ui-deliverables` 的 `0`）；DSH 自带的 `ui-deliverables` 被遮蔽，一旦其上的条目注销即作为该单元格的下一顺位重新渲染（即回落行）。

用户希望把它换成 **Codex 风格** 的汇总卡片：`已编辑 N 个文件` + 总计 `+X −Y` + 每文件 `+a −d` + 折叠展开 + Review 内联 diff + 保留「在文件夹中显示」。

### 1.2 目标

| | 内容 |
|---|---|
| 交付形态 | 常驻 bundle 插件（独立仓库、独立 npm 包），以 profile bundle 方式挂载 |
| 视觉 | Codex 风格卡片，替换现有 chip 行 |
| 数据 | 精确的每文件新增/删除行数与总计，**不依赖 git**，非 git 目录同样可用 |
| 交互 | 折叠/展开、按文件内联 diff、审查模式、行点击打开文件、「在文件夹中显示」 |
| 配置 | 在 DSH 设置中以独立页面动态调整，保存即生效 |
| 可扩展 | 数据推导按「变更来源」抽象，新增工具/新增来源只需注册策略 |
| 验证 | 单元 + 组件 + Playwright E2E（含真实工具链的确定性 lane 与复用本机已配置 API 的真实模型 lane） |

### 1.3 非目标（v1）

撤销（Undo）、全屏 review 面板、git 补漏层、非工具途径（`bash`/代码生成器）改动的可见性、设置变更的跨客户端推送、双语 README。

---

## 2. 决策记录

设计过程中被明确否决或推迟的方案，记录于此以免后人重复讨论。

| # | 议题 | 结论 | 理由 |
|---|---|---|---|
| D1 | 实现机制：动态 Cordis 插件 vs 常驻 bundle 包 | **常驻 bundle 包** | 用户要求长期生效；本部署已跑通 bundle 渠道（`dsh-better-sidebar` 等 3 个包） |
| D2 | 行数统计来源：`git diff --numstat` | **否决** | 强依赖 git；非 git 目录、临时目录直接失效 |
| D3 | 行数统计来源：DSH 工具结果里持久化的 applied diff | **采纳** | `write`/`edit` 把 `{diffs: FileDiff[]}` 写进 tool result `meta` 并随会话日志持久化；含前后文本与上下文，精确且与 git 无关 |
| D4 | 撤销实现：`git restore` | **否决** | 会连坐"任务开始前就存在的未提交改动"，且依赖 git |
| D5 | 撤销实现：反向应用 hunk | **推迟到 v2** | 机制可行（把 hunk 的 `newText` 换回 `oldText`，含 staleness 校验），但 v1 按用户决策不做 |
| D6 | Review 形态：全屏 overlay 面板 | **推迟到 v2** | v1 采用卡片内联 diff，单槽单组件，复杂度最低 |
| D7 | 「在文件夹中显示」：复用 `dsh-better-sidebar` 的侧栏定位 | **否决** | 其服务 `BetterSidebarService` 只暴露 `openTab`/`registerTab`/…，**没有** explorer reveal 接口；跨插件耦合也不可取 |
| D8 | 「在文件夹中显示」：自研原生打开 | **采纳** | 与 DSH 早期"原生文件夹交接"语义一致；Host 侧 argv 数组 + 路径围栏，零耦合 |
| D9 | 数据推导：硬编码在组件里 | **否决** | 用户要求抽象化，便于后续接入其它工具 |
| D10 | 配置载体：仅 cordis Config | **否决** | 用户要求能在 DSH 设置中动态调整；cordis Config 只保留部署级项 |
| D11 | E2E 数据来源：录制会话 fixture | **备选** | 会话以 `session.jsonl.zstd` 存储，fixture 绑定会话格式版本；首选 mock 模型 lane |
| D12 | E2E 真实模型 lane：是否需要 API key 环境变量 | **不必要** | 可直接复用本机 `$DSH_HOME` 中已配置的 provider 与凭据（只读复制进 scratch 环境），故该 lane 为必选 |

---

## 3. 技术调研结论（证据链）

以下为设计所依赖的 DSH 行为，均已在本仓库源码中确认（路径相对 `deepseek-harness/`）。

### 3.1 槽与接管

| 事实 | 证据 |
|---|---|
| `conversation.chat.turnTail` 是 **list** 槽，scope `session`；条目按 `id` 划分单元格，同格内按 priority **升序遮蔽**，**只有最低的存活条目渲染**（无 `select` 座位、无 `matched` 注入）；新 `id` 追加一行，复用已有 `id` 即顶替该行 | 槽 catalog；`packages/client/ui-slots/src/index.ts` 的 `SlotCore.register` / `SlotCore.entriesOfSlot` |
| owner props 恰好是 `{ turn, seq, openFile }`（条目在渲染期自行据此组装数据） | `packages/client/ui-chat/src/client/chat/TurnTailNodeView.tsx:25-26` |
| 当前占用者：`dsh-better-sidebar`（同一 `id`，-1）、`ui-deliverables`（同一 `id`，0） | 运行时槽树查询 |
| list 槽要求注册项带 `options.id`（缺失即在加载期抛 `list slot "conversation.chat.turnTail" requires options.id`）；同一单元格的同 priority 再注册也会抛错，必须换 priority 才能遮蔽。常驻 bundle 包不经过动态守卫，priority 由注册者自带（本包默认 `-2`，设置项可调） | `packages/client/ui-slots/src/index.ts` 的 `SlotCore.register`；`packages/extensions/cordis-client-runner/src/client/guard.ts` 的 `guardedSlots`（动态包对非 chain 槽自动分配 shadowing rank） |
| 该槽标准 props 含 `useChat` / `useSession` / `useWorkspaces` / `t`（经 `locale` 选项） | 槽 catalog `standardProps` |

### 3.2 数据来源

| 事实 | 证据 |
|---|---|
| `write`/`edit` 执行时把 applied diff 分块写进 tool result `meta`，**随会话日志持久化**（供 replay 复现 diff 卡片） | `packages/fs/tool-fs/src/diff.ts:14-20` |
| 每个 `FileDiff = { path, oldText: string\|null, newText: string }` 是一个**含 3 行上下文**的 hunk（上下文行同时出现在两侧） | `packages/fs/tool-fs/src/diff.ts:33-57` |
| 工具执行结果本身返回 `{ path, before, after }` | `packages/fs/tool-fs/src/write.ts:121-126`、`edit.ts:140-144` |
| 会话事件 `'tool/result'` 携带 `meta?: JsonValue` | `packages/core/session/src/types.ts:353-360` |
| Client 侧 Chat 节点保留该 meta | `packages/client/ui-chat/src/client/conversation-nodes/tool.ts:65` |
| `ChatSnapshot` 暴露 `order` / `nodes: ChatNodeStore` / `locations.getTurn(turn)` | `packages/client/ui-chat/src/client/contract/snapshot.ts:92-99` |
| 产出文件清单来自 Turn data：`owner.turn.data.get('deliverables')` → `{ produced: [{ seq, path }] }`（**只有路径，无行数**） | `packages/client/ui-deliverables/src/client/turn-deliverables.ts:122-145` |
| `str_replace_editor` **无** result meta，只有调用期 `presentCall` 派生的 diffs（`create` 纯新增 / `str_replace` 片段 / `insert` 无文本） | `packages/fs/tool-str-replace-editor/src/index.ts:385-415` |

### 3.3 设置

| 事实 | 证据 |
|---|---|
| Host `settings.register(ns, schema, { base, applies, validate })` → `SettingsScope<T>`（`get` / `watch`）；`update/replace/mutate` + `describe` 返回 `{ ns, value, revision, base, user, applies }`；命名空间必须是小写连字符标识符 | Host `settings` 服务契约 |
| `applies: 'live' | 'restart'` 是语义声明，供设置界面提示 | `SettingsApplies` |
| `settingsController` 提供 `@Remote describe / update / replace / mutate`，即客户端可用的 `ctx.remote.settings` 命名空间 | Host 服务目录 |
| 设置页槽：`settings.section`（list，注册项 `{ id, order, label }`）；`settings.general.item` 用于单行偏好 | 运行时槽树查询 |
| 设置与凭据的存储位置：`$DSH_HOME/settings.yaml`、`$DSH_HOME/.credentials.yaml`（`$DSH_HOME/.env` 为只读回落） | `packages/settings/settings-file/src/index.ts:57`、`packages/credentials/credentials-local/src/index.ts:61` |

### 3.4 客户端半边与主题

| 事实 | 证据 |
|---|---|
| 静态 client bundle 形态：`window.__ModuleLoader__.load({ id: <包名>, factory: (require) => {...} })`（CJS closure），平台外部化 `react` / `react/jsx-runtime` / `react-dom` / `cordis` / `ui-slots` / `ui-primitives`，其余内联；CSS Modules 编译为哈希类名并在 factory 执行时注入 `<style data-plugin>` | `DSH-better-sidebar/tsdown.config.ts`（已验证可跑通本部署） |
| 第三方 client 插件不得值导入其他插件（purity gate），跨插件协作走 cordis 服务或槽 | 同上 |
| 内置语言只有 `zh` / `en` | `packages/client/locale/src/locale-settings.ts:15` |
| 可用主题 token（13 个）：`--dsw-alias-bg-base/-bg-layer-1/-bg-layer-2/-bg-overlay`、`-border-l1/-border-l2`、`-brand-primary`、`-label-primary/-label-secondary`、`-state-error-primary/-state-success-primary/-state-warn-primary`、`--dsw-specific-sidebar-fill` | Theme 运行时查询 |

### 3.5 Host 侧能力

| 事实 | 证据 |
|---|---|
| 自建 HTTP 路由：`ctx.webServer.register({ kind: 'prefix', path, handler })` | better-sidebar `src/index.ts:863` |
| 原生打开的三个平台分支：linux `xdg-open <dir>`、darwin `open -R <path>`、win32 `explorer.exe /select,<path>`（argv 数组，无 shell 插值） | better-sidebar `src/open-external.ts` |
| 会话 cwd：`ctx.get('sessions').get(sessionId).header.cwd`（`SessionHeader` 保证 `cwd` 为绝对路径） | `packages/core/session/src/index.ts:464`、`:111-114` |
| 自定义模型端点：`DEEPSEEK_BASE_URL` 被适配器采纳，请求 `POST {base}/chat/completions`（SSE） | `packages/llm/llm-deepseek/src/adapter.ts:651`、`lib/types/index.d.ts:45` |

---

## 4. 总体架构

```
┌─ Browser：lib/client.js（静态 client bundle） ───────────────────────────┐
│                                                                          │
│  apply(ctx)                                                              │
│   ├─ ctx.provide('betterSummary', service)      ← 变更来源注册表          │
│   ├─ store = createSummaryStore()               ← 跨条目共享状态          │
│   ├─ slots.inject('conversation.chat.turnTail') → register(priority=-2)    │
│   │     id = 自带产出行的单元格  ← 同格遮蔽 better-sidebar / 自带行        │
│   │     SummaryCard → selectSummaryMatch(props)；无产出渲染 null（不让格） │
│   │       ├─ useChat → 该 turn 节点 → 来源管线 → TurnSummary（useMemo）   │
│   │       ├─ useStore → collapsedRows / inlineDiffMaxLines / folderReveal │
│   │       └─ fetch('/better-summary/api/reveal')  ← 唯一 Host 调用        │
│   └─ slots.inject('settings.section') → register(SettingsSection)         │
│         └─ ctx.remote.settings.describe/update → commit 到同一个 store    │
└──────────────────────────────────────────────────────────────────────────┘
                                   │ POST JSON（仅回环）
┌─ Node：lib/index.js（Host 半边） ────────────────────────────────────────┐
│  apply(ctx)                                                              │
│   ├─ ctx.settings.register('better-summary', schema, { applies:'live' })  │
│   ├─ ctx.webServer.register({ kind:'prefix', path:'/better-summary/api' })│
│   │     └─ reveal：回环围栏 → 路径围栏 → 选目录 → spawn(argv)             │
│   └─ registerWorkspaceSource()  ← L3 来源注册位（v1 只登记不调用）        │
└──────────────────────────────────────────────────────────────────────────┘
```

**职责边界**：Client 负责一切展示与推导（可离线、可回放、零 git）；Host 只负责两件客户端做不到的事——写设置命名空间、把目录交给操作系统打开。

---

## 5. 数据推导抽象层

### 5.1 设计目标

- 汇总一个 turn 的产出**不绑定任何具体工具**；工具差异全部收敛进「变更来源」。
- 新增来源（新工具、git 补漏、文件监听）= **写一个策略 + 注册**，不改卡片、不改聚合、不改 UI。
- 来源只在**边界**接触活数据（Chat 节点），向内只产出纯 JSON。

### 5.2 数据契约

```ts
/** 一个文件在汇总窗口内的变更（纯数据，跨层唯一通货）。 */
interface FileChange {
  readonly path: string
  /** 上下文式 diff 分块；来源若已自带精确计数可省略。 */
  readonly hunks?: readonly ChangeHunk[]
  /** 来源自报的精确计数，优先于由 hunk 推导。 */
  readonly counts?: { readonly added: number; readonly removed: number }
  /** 溯源：产生该变更的来源 id 与工具名，用于 UI 提示与排障。 */
  readonly origin?: { readonly source: string; readonly tool?: string }
}

/** 一个 diff 分块。DSH fs 工具的约定是"两侧文本均含 3 行上下文"。 */
interface ChangeHunk {
  readonly oldText: string | null   // null = 纯新增
  readonly newText: string
}

/** 聚合结果：卡片唯一消费的数据。 */
interface TurnSummary {
  readonly files: readonly FileSummary[]
  readonly totalAdded: number
  readonly totalRemoved: number
  readonly hasStats: boolean
}

interface FileSummary {
  readonly path: string
  readonly added: number
  readonly removed: number
  readonly hunks: readonly ChangeHunk[]
  readonly hasStats: boolean                 // 无任何来源给出数字时为 false
  readonly origins: readonly string[]
}
```

### 5.3 三层来源接口

```ts
/** L1 节点级来源（Client）：把一个 Chat 节点翻译成文件变更。v1 主路径。 */
interface NodeChangeSource {
  readonly id: string
  readonly priority: number                                 // 降序尝试，先到先得
  match(node: NodeLike): boolean                            // 只读 kind / isError 等标量
  extract(node: NodeLike): readonly FileChange[] | null      // null = 不认这个节点
}

/** L2 轮次级来源（Client）：看整轮而非单节点（例如按调用参数推导）。 */
interface TurnChangeSource {
  readonly id: string
  readonly priority: number
  collect(input: {
    nodes: readonly NodeLike[]
    produced: readonly string[]
  }): readonly FileChange[] | null
}

/** L3 工作区级来源（Host）：非工具途径的改动（git 补漏、目录监听等）。 */
interface WorkspaceChangeSource {
  readonly id: string
  readonly priority: number
  collect(request: {
    sessionId: string
    paths: readonly string[]
  }): Promise<readonly FileChange[]>
}
```

`NodeLike` 是边界类型：只暴露本包实际读取的叶子字段（`kind`、`isError`、`meta`），来源实现不得把节点对象存进任何长生命周期状态。

### 5.4 聚合管线（来源无关，纯函数，可单测）

```
该轮的变更累积条目（本包定义从原始事件折叠而来）
  → L1 来源按 priority 降序 match/extract            ← 命中即短路
  → 按 path 归并：hunks 顺序拼接、counts 累加
  → 与 deliverables 清单取并集（清单顺序优先，保序）
  → 无任何来源给出数字的路径：hasStats = false
  → L2 来源补充仍无数字的路径
  → L3 来源（异步、可选）仅补"清单里完全没有"的路径，绝不覆盖已有数字
  → 计数：counts 优先，否则 splitHunk(hunk) 推导
  → TurnSummary
```

**冲突与优先级规则**（同时写入接口 JSDoc 与 README）：

1. 同一 path 被多个 L1 来源命中 → **全部累加**（同一文件多次编辑本就应累加）。
2. `counts` 与 `hunks` 并存 → 计数用 `counts`，展示用 `hunks`。
3. L3 只做**补缺**：路径已存在则丢弃。这保证「有 git / 无 git」结果一致。
4. priority 相同的来源按注册顺序；注册顺序稳定可复现。
5. 来源抛错被隔离：单个来源异常不影响其它来源与卡片渲染（记入 `console`，卡片降级）。

### 5.5 内置来源（v1 唯一实现）

| id | 优先级 | 层 | 命中条件 | 提取 |
|---|---|---|---|---|
| `dsh.tool-result-diff-meta` | 100 | L1 | `node.kind === 'tool-result'` 且 `!node.isError`，且 `node.meta.diffs` 通过收窄 | 逐项 `{ path, oldText, newText }` → `FileChange{ hunks, origin }` |
| `dsh.tool-call-args` | 50 | L1 | 同上，且 `node.call.name ∈ {write, edit, str_replace_editor}` | 由调用参数推导：`write`/`create` 计纯新增，`edit`/`str_replace` 计增减，`insert` 计新增 |

第二个来源是实施期新增的：`write` **新建**文件时工具没有前像，`meta.diffs` 是空数组，
优先级更高的 meta 来源返回 null，选举落到参数来源。两个来源合起来覆盖
「新建 + 编辑」两种路径，且「覆盖已有文件」仍使用工具自报的真实 applied diff。

**收窄 `readDiffs(meta)`**：`meta` 为普通对象、`diffs` 为非空数组、每项满足 `path: string` / `oldText: string|null` / `newText: string`。不合法项丢弃；整块不合法返回 `null`（交给下一个来源）。

**计数 `splitHunk(hunk)`**：按 `\n` 切行（`oldText: null` → 空数组），剥离 old/new 的**公共前缀行与公共后缀行**，中段即 `removed[]` / `added[]`，计数取长度。该规则与"含上下文的 hunk"约定绑定并写进接口文档；自带计数的来源用 `counts` 绕开。

> 已知边界：极端情况下 hunk 边界行文本重复可能造成 ±1 偏差；届时可换用 LCS 实现（仍为纯 Client 计算），不影响接口。

### 5.6 对外扩展点

Client 半边发布 cordis 服务（与 `ctx.betterSidebar` 同款范式）：

```ts
interface BetterSummaryService {
  registerNodeSource(source: NodeChangeSource): () => void
  registerTurnSource(source: TurnChangeSource): () => void
  listSources(): readonly SourceInfo[]        // { id, layer, priority, owner }
  readonly features: readonly string[]        // v1: ['nodeSource','turnSource','settings']
  readonly version: string
}
```

Host 半边发布同构的注册位 `registerWorkspaceSource()`（v1 只登记、不调用；`summary.workspace` RPC 方法存在但默认返回空数组）。

**"换工具"的落地路径**（README 中给出两个示例）：

1. 新工具的 tool result 携带可识别 meta → 由插件作者注册一个 10 行的 `NodeChangeSource`，卡片立即支持；
2. 工具什么元数据都没有 → 由 L3 来源在 Host 侧兜底（git / 目录监听），或由 `TurnChangeSource` 从调用参数推导。

---

## 6. 卡片 UI 规格

### 6.1 布局

```
┌────────────────────────────────────────────────────────────────────────┐
│ ⬒ 已编辑 48 个文件                     [📁 在文件夹中显示] [审查]   +3,278 −282        │
│ ────────────────────────────────────────────────────────────────────── │
│  ⌄  …/internal/migrat…/runtime_v1_test.go              +17   −1        │
│     │ -  old line …                                                    │
│     │ +  new line …                                                    │
│  ⌄  …/internal/reset/reset_test.go                     +89  −37        │
│  ⌄  …/cmd/event-migrate/main.go                         +7   −5        │
│  ⌄  显示其余 45 个文件                                                        │
└────────────────────────────────────────────────────────────────────────┘
```

- 位置：卡片渲染在轮次尾部（closing assistant 之后、动作行之前），与今天同一位置。
- **数据面（实施期修正）**：卡片不读 Chat 渲染节点。紧凑显示模式下，一轮的工具调用会被
  折叠成一个 `turn-process` 节点，工具结果节点不再单独 materialize，读节点会拿不到
  applied diff（只有文件清单、没有数字）。因此本包注册自己的
  `ConversationNodeDefinition`（kind/key 均为 `better-summary`）折叠原始事件，
  只发布 Turn 数据、不发布视图节点 —— 与显示模式完全解耦。
- 头部：文件图标 + `已编辑 N 个文件`；中间偏右两个按钮；**最右**是总计 `+X`（success 色）/`−Y`（error 色）——
  合计必须排在头部**末项**，才能与文件行的计数**逐列对齐**（见 §6.4）。
- 行：等宽字体；目录前缀淡化、basename 高亮；超长时中段省略；`title` 保留原始完整路径；右侧右对齐 `+a −d`（与头部合计同列）。
- 无任何数字时（`hasStats === false`）：隐藏 `+/−` 与「审查」，仅显示清单。

### 6.2 交互状态机

| 交互 | 行为 |
|---|---|
| 行点击 | `owner.openFile(path)`（既有漏斗：better-sidebar 存在时进其编辑器，否则进 DSH 文本预览） |
| 行左侧 chevron | 展开/收起**该文件**的内联 diff |
| 「审查」 | 切换审查模式：全部文件展开 + 所有 diff 打开；按钮态变「收起审查」 |
| 「在文件夹中显示」 | `POST /better-summary/api/reveal`；失败时卡片底部显示一次性提示（约 4s 后消失） |
| 「显示其余 N 个文件」/「收起」 | 折叠行数取 `collapsedRows`；展开区 `max-height: 360px` + 滚动 |
| 统计缺失 | 头部仅显示文件数；「审查」置灰 |

组件内部只有三个局部状态：`expandedAll`、`openDiffs: Set<path>`、`revealStatus`。跨条目共享的状态（设置）走声明的 store。

### 6.3 内联 diff 规格

- 每个 hunk 渲染为等宽 `<pre>` 块，三行上下文：
  - 公共前缀/后缀行 → 上下文行（淡色，前缀两个空格）
  - `removed[]` → `-` 前缀，红底
  - `added[]` → `+` 前缀，绿底
- 多 hunk 之间插入 `⋯` 分隔行，表示被跳过的未变更区域（meta 只存 3 行上下文）。
- 每文件渲染上限 `inlineDiffMaxLines`（默认 200）；超限截断并显示「差异已截断」。
- 长行横向滚动（`white-space: pre; overflow-x: auto`），不换行。
- `str_replace_editor` 的场景照常渲染（片段级语义在 README 限制章节说明）。

### 6.4 样式与主题

仅使用已确认可用的 `--dsw-*` token，不硬编码颜色：

| 用途 | token |
|---|---|
| 卡片底 / 头部底 | `--dsw-alias-bg-layer-1` / `--dsw-alias-bg-layer-2` |
| 外框 / 内部分隔 | `--dsw-alias-border-l2` / `--dsw-alias-border-l1` |
| 主文本 / 次文本 | `--dsw-alias-label-primary` / `--dsw-alias-label-secondary` |
| 新增 / 删除 / 强调 | `--dsw-alias-state-success-primary` / `--dsw-alias-state-error-primary` / `--dsw-alias-brand-primary` |

行底色使用 `color-mix(in srgb, var(--dsw-alias-state-success-primary) 12%, transparent)`，并提供不支持 `color-mix` 时的边框降级。几何：8px 圆角、1px 边框、头部 32px、行高 22px、等宽字体栈 `ui-monospace, SFMono-Regular, Menlo, monospace`。

**字号**：卡片不硬编码 px，而是读组件注入的 `--summary-font-size`；该变量默认值为
`var(--dsh-content-font-size, 14px)` —— `--dsh-content-font-size` 是 DSH 自身的正文字号变量
（由 `ui-layout` 的主题呈现器写在 `document.body`，受 DSH 字体设置驱动），因此默认即「与正文一致」。
设置项 `fontSize` 选具体档位时，注入值变为该 px。只有行内 diff 用相对单位 `0.95em` 跟随卡片字号
缩放，其余文字一律继承卡片字号（`.path` 此前另有硬编码 `font-size: 12px`，已移除）。

**计数列对齐**：`+N` / `−N` 出现两处——头部合计（`.stats`）与每个文件行（`.counts`），**两者共用
同一条规则**：定宽列 `var(--summary-count-col)`（`3ch`，在 `.card` 上统一定义）、6px 间距（
`.removed` 的 `margin-left`）、等宽字体栈、每格 `text-align: right`。任何一处不同都会错位，因为列
位置 = 距卡片右缘的距离 + 列宽 + 列间距，而列宽是 `ch`（随字体而变）。三条约束各对应一次修正：

- **行内跨行对齐（水平）**：此前是可变宽 `inline-flex` 块整体右靠，同一行里 `−N` 的宽度会把 `+N`
  顶走、`+N` 自身也随位数左右浮动（像素实测：`+18/−8`、`+23/−19`、`+8/−2` 的 `+N` 左缘落在
  966/961/972）。定宽列让每行两列位置完全一致；超出列宽的值（如 4 位的 `+528`）向左溢出，各列
  对齐不受影响。
- **头部与行对齐（水平）**：合计必须排在**头部最末**（按钮之后），才能与贴右缘的行计数共享同一条
  右缘；排在标题之后时两者相差 554px（实测 `totalAdded.right` 632 vs `rowAdded.right` 1186）。
  此外 `.stats` 原用正文字体 + 8px 间距，与行计数的等宽字体 + 6px 间距不同，列宽因此也不相等。
- **两格基线重合（垂直）**：两个计数必须分享**同一条基线**。容器因此是 `display: inline-block`
  + 两个 `inline-block` 子项（`vertical-align: baseline`），而**不是**两列 `inline-grid`：网格项各自
  成行盒，各自的行盒度量决定各自的基线，只要某一格的字形落到度量不同的回退字体（`−` 是 U+2212，
  回退很常见），该格数字就整体上下浮动（实测：仅扰动 `−N` 的行盒度量，两格基线即相差 4px，与用户
  截图里 `+4` 比 `−1` 高 3px 同因）。同一行盒里的两个 inline-block 由构造共享基线——内部行盒
  再怎么变，数字都落在同一条基线上。

无统计的文件用 `width: calc(var(--summary-count-col) * 2 + 6px)` 让 `—` 占满两列宽度并右对齐，
观感与有统计时一致。

### 6.5 文案（locale 命名空间 `better-summary`，`zh` + `en`）

| key | zh | en |
|---|---|---|
| `editedFile` / `editedFiles` | 已编辑 {count} 个文件 | Edited {count} file / files |
| `showMore` | 显示其余 {count} 个文件 | Show {count} more files |
| `showLess` | 收起 | Show less |
| `review` / `reviewing` | 审查 / 收起审查 | Review / Hide review |
| `showInFolder` | 在文件夹中显示 | Show in folder |
| `diffTruncated` | 差异已截断 | Diff truncated |
| `revealFailed` | 无法打开文件管理器 | Could not open the file manager |
| `settingsTitle` / `settingsIntro` | 任务产出 / 配置产出卡片的显示方式 | Task summary / Configure how the produced-files card renders |
| 设置项标签（6 项） | 折叠行数 / 内联 diff 行数上限 / 文件夹按钮 / 卡片字号 / 槽位优先级 / 启用 | Collapsed rows / Inline diff line cap / Folder button / Card font size / Slot priority / Enabled |
| `sourcesTitle` | 生效的变更来源 | Active change sources |

数字使用 `Intl.NumberFormat()` 加千分位。字典通过 `ctx.locale.register(NS, { zh, en })` 注册，并用 `LocaleNamespaceMap` 声明合并取得 `t` 的类型安全；槽注册带 `locale: NS` 以获得标准 `t` 座位。

---

## 7. 设置与动态调整

### 7.1 分层

| 层 | 载体 | 内容 | 生效 |
|---|---|---|---|
| 部署级 | cordis Config（`cordis.patch.yml` / profile） | `routePrefix`、`opener` | 重启 |
| **用户级** | **DSH settings 命名空间 `better-summary`** | `collapsedRows`、`inlineDiffMaxLines`、`folderReveal`、`fontSize`、`priority`、`enabled` | **保存即生效** |

### 7.2 Host：命名空间注册

```ts
ctx.settings.register('better-summary', SummarySettingsSchema, {
  base: SUMMARY_DEFAULTS,   // 组合层默认值
  applies: 'live',          // 语义声明：保存后立即生效，不提示重启
})
```

- 命名空间名必须是**小写连字符标识符**，否则 `register` 抛 `TypeError`。
- 返回 `SettingsScope<T>`：`get()` 读当前值、`watch(cb)` 订阅提交。Host 侧行为（槽位优先级重建）由 `watch` 驱动。
- 非法值在注册期 fail-loud；已存在的非法 section 会让注册本身失败（最早的判定点）。

### 7.3 Client：读写与实时传播

```
设置页（settings.section 条目）
  ctx.inject(['remote.settings'], …)
  → describe({ redactSecrets: true }) 找 ns === 'better-summary' 的描述符
  → update(ns, patch, expectedRevision)     // 乐观并发；冲突则重读并提示
  ↓ 写入成功后 commit
共享 store（apply 内创建，两个 register 传同一 handle）
  ↓ props.useStore 订阅
卡片条目 → 立即重渲染（无需刷新）
```

- **共享状态通道**：在 `apply` 内 `createSummaryStore()`，把同一 handle 传给卡片条目与设置条目——这是"跨条目共享状态"的官方通道；不使用模块级单例，也不自造 React context。
- **外部编辑 `settings.yaml` 的场景**：设置页挂载时、以及每次写操作前重新 `describe()` 回填。这是 v1 的明确边界（v2 可加推送）。
- **Plan B 通道**：若目标 DSH 版本没有 `ctx.remote.settings`，退回自建路由 `settings.get` / `settings.update` 包装 `ctx.settings`（`dsh-better-sidebar` 现用做法，已在本环境验证）。两条通道收敛在同一个 `settingsClient` 接口之后，UI 无感知。

### 7.4 设置页形态（已确认：独立 `settings.section`）

| 控件 | 绑定 | 范围 |
|---|---|---|
| 数字步进 | `collapsedRows` | 1–20 |
| 数字步进 | `inlineDiffMaxLines` | 20–2000 |
| 单选 | `folderReveal` = `label` / `icon` / `off` | — |
| 下拉 | `fontSize` = `跟随正文` / 11–18px | 默认跟随 `--dsh-content-font-size` |
| 数字输入（高级） | `priority`，默认 -2 | 整数 |
| 开关 | `enabled` | — |
| 只读列表 | `listSources()` | 展示当前生效的变更来源，便于将来第三方策略排障 |

### 7.5 动态生效机制

- `collapsedRows` / `inlineDiffMaxLines` / `folderReveal`：纯展示，store 更新即生效。
- `priority` / `enabled`：需要**重建单元格条目**。`apply` 内维护一个 effect-owned 控制器：`dispose()` 旧注册 → 按新配置重新 `slots.register`。注销会把单元格交还给下一顺位条目（`dsh-better-sidebar` → DSH 自带产出行），因此 `enabled` 闸门刻意留在**注册期**；list 槽在渲染期返回 `null` 只让本条目渲染为空，并不会让出单元格。重建幂等；重建瞬间旧行短暂回归（毫秒级，无闪烁）。
- 所有注册都挂在 `ctx.effect` / `ctx.slots.inject` 上，卸载即摘除。

---

## 8. Host 半边设计

### 8.1 路由契约

| 项 | 值 |
|---|---|
| 注册 | `ctx.effect(() => ctx.webServer.register({ kind: 'prefix', path: '/better-summary/api', handler }))`（前缀固定，见 §18） |
| 回环围栏 | 仅接受回环来源（`127.0.0.1` / `::1` / `::ffff:127.0.0.1`），否则 403 |
| 方法 | `POST` + `application/json`；其他方法 405 |
| 方法名 | URL 尾段（`/reveal`），未知方法 404 |
| 请求 | `{ sessionId: string, paths: string[] }`（paths 为该轮产出清单） |
| 成功 | `{ ok: true, value: { opened: string, mode: 'folder' \| 'select' } }` |
| 失败 | `{ ok: false, error: { code, message } }`，`code ∈ forbidden / method-error / not-found / bad-request / no-session / no-opener` |
| 状态码 | `forbidden`→403、`method-error`→405、`not-found`→404、`bad-request`→400、`no-opener`/`internal`→**500**（服务端能力失败，非客户端请求错误） |

### 8.2 `reveal` 处理流程

1. 校验 `sessionId` 为字符串；`paths` 为字符串数组，长度 ≤ 200，单项长度 ≤ 4096。
2. `ctx.get('sessions')?.get(sessionId)?.header.cwd` 取会话工作目录；取不到 → `no-session`。
3. **路径解析**：绝对路径直接采纳（产出常在 `/tmp`、兄弟仓库等会话工作目录之外，把它们重定向到工作目录会让按钮打开错误的目录）；相对路径相对 `cwd` 解析并禁止 `..` 逃逸，越界的相对路径丢弃。
4. **目标选择**：全部有效路径的父目录唯一 → 该目录；否则 → `cwd`；无有效路径 → `cwd`。
5. **WSL 判定**（`WSL_DISTRO_NAME`/`WSL_INTEROP` 环境标记，或内核版本含 `microsoft`）为真时，先用 `wslpath -w` 把目标翻译成 Windows 路径。
6. **平台分支**（纯函数 `opener.ts`，argv 数组，**不经过 shell**）：

| 平台 | 命令 | 语义 |
|---|---|---|
| linux | `xdg-open <dir>` | 打开所在目录（Linux 无通用 select 协议） |
| linux + WSL | `explorer.exe /select,<winPath>` / `powershell.exe -NoProfile -Command "Invoke-Item -LiteralPath '<winPath>'"` | 交给 Windows 桌面：单文件选中文件，目录用 `Invoke-Item`（直接 `explorer.exe <dir>` 不能可靠唤起窗口，与 DSH 自带 path opener 同款结论） |
| darwin | `open -R <firstPath>` | 在 Finder 中选中文件 |
| win32 | `explorer.exe /select,<firstPath>` | 在资源管理器中选中文件 |

7. 若配置了 `opener` 覆盖，则用覆盖命令替换平台默认（参数里的 `{path}` 占位符替换为选定目标）。
8. `spawn(command, args, { detached: true })`，并在 **2 秒窗口**内观察结论：`error` 事件（命令不存在）→ `no-opener`；非零退出码 → `no-opener`（`explorer.exe` 除外，它成功打开窗口时也返回 1）；超窗仍在运行 → 视为成功交接。
9. 返回打开目标与模式。

> 不使用 `ctx.shell`：其接口是命令字符串，需要自行拼接引号，存在注入面；argv 数组更安全。
>
> 为什么必须看退出码：WSL 的 Linux 侧通常没有桌面，`xdg-open` 会**启动成功、随后以退出码 3 失败**（`no method available`）。只看 `spawn` 事件会把它报成成功，用户看到的就是「点了没反应」。

### 8.3 与 `dsh-better-sidebar` 的关系

- 它的单元格条目（同一 `id`，priority `-1`）被本包（`-2`）**遮蔽** → 它的 chip 行与其「在文件夹中显示」不再出现。
- 它对 `remote.session.openWorkspacePath` 的**全局漏斗拦截仍然生效** → 本卡片行点击依旧打开它的编辑器（期望行为）。
- 它的服务没有 explorer reveal 接口，因此「在文件夹中显示」由本插件自研原生打开，零跨插件耦合。
- 若它被禁用或卸载，本插件功能不受影响（行点击回落到 DSH 原生文本预览）。

---

## 9. 包与工程形态

### 9.1 仓库布局

```
dsh-better-summary/
├─ .git/                       git 仓库（main 分支）
├─ .gitignore                  node_modules/ lib/ *.tgz coverage/ playwright-report/ test-results/
├─ .editorconfig
├─ LICENSE                     MIT
├─ README.md                   项目说明（安装、配置、原理、限制、开发）
├─ docs/design.md              本文件
├─ package.json
├─ cordis.patch.yml            dsh.bundle.patch：insert 一行 better-summary
├─ tsconfig.json               typecheck（noEmit）
├─ tsconfig.build.json         只 emit lib/types 声明
├─ tsdown.config.ts            Host ESM + Client CJS bundle 双构建
├─ vitest.config.ts
├─ playwright.config.ts        E2E lane（testDir tests/e2e）
├─ scripts/
│  ├─ e2e-common.sh            共享骨架：scratch DSH_HOME / 挂载 / 启动 / 就绪轮询 / 清理
│  ├─ e2e-mount.sh             主入口（keyless）：L1–L4
│  └─ e2e-real.sh              真实模型 lane（复用本机已配置 API）：L5
├─ src/
│  ├─ index.ts                 Host：settings 注册、reveal 路由、L3 注册位
│  ├─ settings.ts              Host：schema + 默认值 + SettingsScope 封装
│  ├─ config.ts                部署级 Config（routePrefix、opener）
│  ├─ opener.ts                平台 argv 纯函数 + 覆盖命令
│  ├─ wire.ts                  路由契约与错误码
│  └─ client/
│     ├─ index.tsx             字典、store、两个槽注册、服务发布
│     ├─ service.ts            ctx.betterSummary：来源注册表
│     ├─ sources/types.ts      第 5 章接口定义
│     ├─ sources/diff-meta.ts  内置 L1 来源
│     ├─ sources/registry.ts   注册表 + 优先级选举
│     ├─ summary.ts            聚合管线 + splitHunk
│     ├─ settings-client.ts    remote.settings 封装（含 Plan B 通道）
│     ├─ settings-store.ts     共享 store
│     ├─ SettingsSection.tsx   设置页
│     ├─ SummaryCard.tsx       卡片
│     ├─ locales.ts            zh / en
│     ├─ icons.tsx             内联 SVG（不引图标集）
│     └─ SummaryCard.module.css
└─ tests/
   ├─ summary.spec.ts / sources.spec.ts / opener.spec.ts / wire.spec.ts / settings.spec.ts
   ├─ summary-card.client.spec.tsx / settings-section.client.spec.tsx
   └─ e2e/
      ├─ host.ts               公共助手（PAGE_URL、launch cookie、hostRpc）
      ├─ model-stub.ts         本地 mock 模型（SSE）
      ├─ opener-shim.sh        记录 argv 的"文件管理器"替身
      ├─ mount.e2e.ts / card.e2e.ts / settings.e2e.ts / reveal.e2e.ts
      └─ real-turn.e2e.ts      L5（复用本机已配置 API）
```

### 9.2 `package.json` 关键字段

| 字段 | 值 | 说明 |
|---|---|---|
| `name` / `version` | `dsh-better-summary` / `0.2.0` | **包名即 client bundle id**，必须一致 |
| `type` | `module` | ESM |
| `main` / `types` | `lib/index.js` / `lib/types/index.d.ts` | Host 半边 |
| `exports` | `.` / `./client` / `./src/*` / `./package.json` | `./client` 是浏览器半边入口 |
| `dsh.bundle.patch` | `./cordis.patch.yml` | 让 `dsh plugin add` 自动协调 `dsh.profile.bundles` |
| `dsh.client.platform` | `web` | 浏览器半边 |
| `dsh.client.inject` | `@deepseek-ai/dsh-client-ui-slots`、`-ui-conversation`、`-locale` | 信息性依赖边（不决定激活顺序） |
| `files` | `lib/**`、`src`、`cordis.patch.yml`、`README.md`、`docs`、`LICENSE` | 发布面收敛 |
| `peerDependencies` | `@deepseek-ai/cordis`、`react` | 运行期共享 |
| `engines` | `node >=20`、`dsh >=0.1.6-alpha.2` | 宿主版本下限，见 §9.6 |
| `devDependencies` | `typescript`、`tsdown`、`vitest`、`jsdom`、`@playwright/test`、`lightningcss`、`@types/*`，以及 type-only 的 `@deepseek-ai/dsh-client-ui-slots / -ui-conversation / -ui-chat / -locale / dsh-host-webserver / dsh-settings` | 与 `dsh-better-sidebar` 同款工具链 |

> 类型依赖兜底：若 `@deepseek-ai/dsh-client-ui-chat` 未发布，则在本包内局部声明 `conversation.chat.turnTail` 的 owner props（只用到 `turn` / `seq` / `openFile` 与 `useChat` / `t`）。

### 9.3 `cordis.patch.yml`

```yaml
- insert:
    - id: better-summary
      name: 'dsh-better-summary'
```

### 9.4 构建

| 段 | 输入 | 输出 | 关键设置 |
|---|---|---|---|
| Host | `src/index.ts` | `lib/index.js`（ESM / node / es2024） | 无外部化 |
| Client | `src/client/index.tsx` | `lib/client.js`（CJS closure） | 复刻官方 client bundle 预设 |

Client bundle 的硬性约定：

- banner `window.__ModuleLoader__.load({ id: "dsh-better-summary", factory: (require) => {`，footer `return module.exports; } });`，前言 `var module = { exports: {} }; var exports = module.exports;`
- `external`：`react`、`react/jsx-runtime`（平台模块表 seed）与 `@deepseek-ai/dsh-client-store`（平台基线模块）；其余全部内联；`codeSplitting: false`。bundled 产物里只有这三个 `require`。
- CSS Modules → 哈希类名映射 + 执行时注入 `<style data-plugin="dsh-better-summary">`
- **纯净度闸门**：禁止未声明的 `@deepseek-ai/*` 值导入（type-only 会被擦除，允许）

### 9.5 安装与回滚

| 渠道 | 步骤 |
|---|---|
| 官方 CLI | `dsh plugin --profile web add dsh-better-summary@0.2.0`（依据 `dsh.bundle.patch` 自动追加 bundle） |
| 本地 tgz | ① `pnpm build && pnpm pack`；② `~/.dsh/profiles/web/package.json` 的 `dependencies` 加 `file:<tgz>`，`dsh.profile.bundles` 追加 `dsh-better-summary`；③ `pnpm install`；④ 重启 `dsh web` |
| 回滚 | 从 bundles 移除（或把 patch 行置 `disabled: true`）→ 旧 chip 行立即回归；DSH 源码零改动 |

> 重启 `dsh web` 会中断当前 GUI 会话，实施时安排在最后一步。

### 9.6 宿主版本要求与打包钩子

| 项 | 内容 | 原因与效力 |
|---|---|---|
| `engines.dsh` | `>=0.1.6-alpha.2` | 0.2.0 按 list 槽形态注册（`id`）；更早的宿主该槽是 chain 槽，注册期直接抛 `chain slot "conversation.chat.turnTail" requires options.select` |
| 该字段的实际效力 | DSH **不读取也不校验**（`deepseek-harness` 全仓无 `engines` 处理代码）；Node 包管理器也只认识 `node`/`npm`/`pnpm` 三个键，未知键在安装期被忽略 | 它是随清单发布的**声明**，不是闸门；真正的拦截是用户按 README「兼容性」表选对版本 |
| `prepack` | `pnpm build` | `lib/` 被 gitignore、`files` 却要求 `lib/index.js`：缺这个钩子时，从干净克隆执行 `pnpm pack` / `npm publish` 会打出**没有 `lib/` 的空包**（`main` 指向不存在的文件，装上即「找不到入口」） |
| `prepare` | `pnpm build` | 只影响从 **git 依赖**安装（`dsh plugin add github:…` / `git+file://…`）：仓库里没有 `lib/`，安装期只有 `prepare` 会构建。**pnpm 10 默认不执行依赖的构建脚本**，所以这条路还要目标 profile 把本包写进 `pnpm-workspace.yaml` 的白名单（`allowBuilds` 或 `onlyBuiltDependencies`），否则 pnpm 以 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` 拒绝安装——比装出缺 `lib/` 的坏包好排查。tarball 渠道不受影响（安装 tarball 不跑 `prepare`，构建已在打包时由 `prepack` 完成） |

> pnpm 打包时会从发布清单里删掉 `prepack` / `prepare`（它们只对源码树有意义），但保留 `engines`：
> 所以 tarball 里的 `scripts` 没有这两个钩子、而 `engines.dsh` 仍在。这是预期行为，不是漏配；
> git 依赖读的是**仓库里的** `package.json`，`prepare` 照常生效。

---

## 10. 配置项总表

| key | 层 | 类型 | 默认 | 范围 | 动态 |
|---|---|---|---|---|---|
| `collapsedRows` | settings | number | 3 | 1–20 | ✅ 即时 |
| `inlineDiffMaxLines` | settings | number | 200 | 20–2000 | ✅ 即时 |
| `folderReveal` | settings | enum | `label` | `label`/`icon`/`off` | ✅ 即时 |
| `fontSize` | settings | `'inherit'` \| number | `inherit` | `inherit` 或 10–24（设置页给 11–18 档） | ✅ 即时 |
| `priority` | settings（高级） | number | -2 | 整数 | ✅ 重建单元格条目 |
| `enabled` | settings | boolean | `true` | — | ✅ 注册/注销 |
| `opener` | cordis Config | `{ command, args? }` | 平台默认 | — | 重启 |

> `routePrefix` 在实施时被取消（见 §18）：客户端 bundle 里的调用路径是编译期常量，
> 可配置前缀会让两侧可能漂移，收益不抵风险。

`priority` 默认 `-2` 的理由：同一单元格（自带产出行的 `id`）现有 `dsh-better-sidebar` `-1` 与 `ui-deliverables` `0`，格内按 priority 升序遮蔽、**最低者渲染**，故 `-2` 必胜且与二者都不冲突（同格同 priority 再注册会被加载期校验拒绝，因此必须取不同值）。

---

## 11. 边界与降级矩阵

| 场景 | 表现 |
|---|---|
| 非 git 仓库 / 临时目录 / 无版本控制 | **全功能**（统计、内联 diff、打开文件夹），与 git 仓库无差别 |
| 该轮无产出 | 卡片组件返回 `null` → 该单元格渲染为空；注意 list 槽的渲染期 `null` **不会**把单元格让给被遮蔽条目（被遮蔽的自带产出行不会顶上来） |
| 老会话 / 工具未写 meta | 该轮只显示清单，数字隐藏，「审查」置灰，不报错 |
| `str_replace_editor` | `create` 精确（纯新增）；`str_replace` 片段级近似；`insert` 仅清单 |
| 二进制 / 超大文件 | 无 hunk → 该文件仅清单 |
| 同一文件多轮编辑 | 聚合为一行、多 hunk，数字累加 |
| 单轮数百文件 | 折叠 N 行 + 展开区滚动；推导为 O(该轮节点数)，`useMemo` 缓存 |
| 无 `xdg-open` / headless / 无桌面 | `reveal` 返回 `no-opener`，卡片底部一次性提示，不抛出 |
| `dsh-better-sidebar` 被禁用 | 本卡片照常；行点击落到 DSH 原生文本预览 |
| 本插件 `enabled=false` 或卸载 | 单元格条目注销，该单元格立即交还下一顺位（旧 chip 行回归） |
| 某个第三方来源抛错 | 隔离该来源，其余照常，卡片降级并记录日志 |

---

## 12. 测试与 E2E 验证

### 12.1 分层测试

| 层 | 文件 | 覆盖 |
|---|---|---|
| 纯函数 | `summary.spec.ts` | hunk 计数（纯插入 / 纯删除 / 替换 / 多 hunk / 空）、聚合管线、清单并集与保序、`counts` 优先规则 |
| 纯函数 | `sources.spec.ts` | 收窄拒绝畸形 meta；优先级选举与短路；来源异常隔离；**"注册一个假来源即可支持新工具"的端到端推导测试**（抽象可用性的证明） |
| 纯函数 | `opener.spec.ts` | 三平台 argv 分支；目标目录选择（单父目录 / 多目录 / 空）；`opener` 覆盖与占位符替换 |
| Host | `wire.spec.ts` | 非回环 403、非 POST 405、未知方法 404、参数越界、路径逃逸被丢弃、spawn 失败 → `no-opener` |
| Host | `settings.spec.ts` | 命名空间注册、schema 校验、默认值、冲突（revision）路径 |
| 组件 | `summary-card.client.spec.tsx` | 头部计数与总计、折叠与展开、审查模式、单文件 chevron、diff 截断提示、行点击调用 `openFile`、文件夹按钮发出请求与失败提示 |
| 组件 | `settings-section.client.spec.tsx` | 控件渲染与写入调用、冲突提示、只读来源列表 |
| 生命周期 | 同上 | dispose 插件 fiber 后单元格条目、字典、路由、设置命名空间全部摘除 |

### 12.2 E2E 形态

沿用本环境已跑通的骨架：脚本编排**真实挂载**（官方 CLI 安装 npm 打包产物到 scratch profile）+ Playwright 无头验证。

- `playwright.config.ts`：`testDir: ./tests/e2e`、`testMatch: '**/*.e2e.ts'`（vitest 永不收集）、`retries: 0`、`workers: 1`、chromium headless、`screenshot: 'only-on-failure'`、`trace: 'retain-on-failure'`、viewport 1440×900。
- `scripts/e2e-common.sh`：解析 `dsh` 命令、解析 tarball、创建**专属 scratch `DSH_HOME`**（调用方提供的目录本身绝不写入）、`dsh plugin --profile web add file:<tgz>`、`dsh web --port 0`、从日志解析 URL、就绪轮询、trap 清理。
- 断言基线：每个 spec 首部挂 `pageerror` / console error / 请求失败 / ≥400 响应收集器，收尾统一断言为空（挂载冒烟的硬门槛）。

### 12.3 五条 lane（实际落地）

| lane | 触发 | 实际断言 |
|---|---|---|
| **L1 挂载冒烟** | `pnpm test:e2e` | 官方渠道真实挂载 → 启动 → 页面无 pageerror / console error / 坏响应；设置导航出现「任务产出」，点开后控件可见且可读（**同时证明 Host 与 Client 双侧生效**），只读来源列表含 `dsh.tool-result-diff-meta` |
| **L2 卡片与内联 diff** | 同上 | mock 模型跑真实工具链（write a.txt → write b.txt（12 行）→ edit a.txt）；断言 `Edited 2 files`、总计 `+15 −1`、a.txt `+3 −1`、b.txt `+12 −0`、a.txt 的 6 行内联 diff（`+alpha +beta ⋯ alpha -beta +BETA`）、审查模式展开全部、行点击可达；并断言**字号跟随 `--dsh-content-font-size`**、**计数单元格跨行等宽且两列右缘重合**（两行 `+N` 为 2 位与 3 位，故该断言对「可变宽内联块」的回归有判别力） |
| **L3 设置动态生效** | 同上 | 设置页把折叠行数改为 1、文件夹按钮改为 off → **不刷新页面**断言卡片只剩一行、出现「显示其余 1 个文件」、按钮消失；再改回并断言双向持久化 |
| **L4 在文件夹中显示** | 同上 | profile 覆盖 opener 指向 `opener-shim.sh`（记录 argv）→ 断言宿主把该轮产出的父目录交给了操作系统；再把 shim 换成目录制造 spawn 失败 → 断言路由返回 5xx、卡片显示「无法打开文件管理器」且无页面异常 |
| **L5 真实模型端到端** | `pnpm test:e2e:real` | 只读复制本机 `~/.dsh` 的 `settings.yaml`/`.credentials.yaml`/`.env` 到 scratch → 真实 provider 与凭据在**非 git** 工作区跑一轮 → 断言卡片出现、统计为非零真实数字、内联 diff 可展开 |

**共存验证**（harness 的 `E2E_EXTRA_PLUGINS`）：把 `dsh-better-sidebar`（同一单元格 `id`，priority `-1`）
与本插件挂进同一个 scratch profile 后重跑整条 lane —— 4 通过，卡片仍以 `-2` 遮蔽对方、独占该单元格，
统计与内联 diff 全部正确。这验证了真实部署组合下的单元格遮蔽顺序。

实施期确定的三个关键事实（都写进了 harness 注释）：

1. **每个 spec 必须重置工作区**：DSH 的 fs 观察守卫要求「修改已存在文件前先读过它」，
   复用上一次 spec 留下的文件会让脚本化的工具调用全部失败（这本身是正确行为，
   但会让该轮无产出、卡片不渲染）。因此每次 spec 前清空共享工作区。
2. **工作区选择器只在 hero（未绑定工作区）出现一次**；后续会话记住工作区，
   只在还没有可用输入框时才走选择器。
3. **外壳噪声白名单**：scratch profile 未挂载 `/open-in-app/icon/*` 路由，打开文件时
   外壳会 404；该噪声已显式列入白名单并注明理由。

### 12.6 视觉基线

对卡片根元素使用 `expect(locator).toHaveScreenshot()`，阈值放宽，只抓结构性回归（行高、间距、语义色）。基线随仓库提交，更新走 `--update-snapshots` 并在 README 记录。

### 12.7 命令与门禁

| 命令 | 内容 |
|---|---|
| `pnpm test` | vitest：纯函数 + 组件 |
| `pnpm test:e2e` | 构建 → pack → `scripts/e2e-mount.sh`（L1–L4，keyless） |
| `pnpm test:e2e:real` | 追加 L5（复用本机已配置 API；无凭据时 skip） |
| `pnpm test:all` | `test` + `test:e2e` |

门禁建议：`test` + `test:e2e` 为必过；`test:e2e:real` 在具备凭据的机器上必过（本机具备）。

---

## 13. 安全与隐私

| 面 | 措施 |
|---|---|
| HTTP 路由 | 仅回环来源；单一动作（打开文件管理器）；无读写能力 |
| 路径 | 相对 `cwd` 解析 + 前缀校验，拒绝 `..` 逃逸；超长/超量参数拒绝 |
| 进程启动 | argv 数组，`detached` + `stdio: 'ignore'`，无 shell 插值 |
| 凭据 | 仅在 scratch 环境临时复制，权限收敛、退出即删；不进仓库与产物 |
| 数据 | 只读节点叶子字段；不把活对象存入长生命周期状态；不上传任何内容 |
| 设置写入 | 走 DSH 设置服务（乐观并发 + schema 校验），不直接写文件 |

---

## 14. 性能

| 点 | 设计 |
|---|---|
| 推导成本 | O(该 turn 的节点数)，只读 `kind` / `isError` / `meta`；`useMemo` 以 `nodes` store 标识 + 该 turn 节点键 + 清单为依赖缓存 |
| 历史轮次 | 每个卡片只算自己那一轮，互不影响 |
| 渲染 | 折叠默认 3 行；展开区限高滚动；内联 diff 按文件懒渲染并限行 |
| 设置读取 | 一次 `describe()`，结果进 store；不做轮询 |
| Host | `reveal` 为一次性 spawn，无线程/无长驻资源 |

---

## 15. 风险与缓解

| 风险 | 影响 | 缓解 |
|---|---|---|
| 与 `dsh-better-sidebar` 的单元格 priority 竞争 | 卡片不出现 | 默认 `-2` 稳赢；priority 可在设置中调整；若调到与对方相同的 `-1`，同格同 priority 会被加载期校验拒绝（fail-loud，不会静默并排两行）；症状（chip 行复现）易定位 |
| 安装需重启，会中断当前会话 | 施工中断 | 构建与单测全绿后再安装；或先用动态 Cordis Package 验证视觉再打包 |
| 外部包 client bundle 的热重载行为未验证 | 迭代变慢 | 首次安装后实测；否则以 `pnpm build` + 刷新 / 重启为节奏 |
| `useChat` 标准 prop 未来变动 | 数字消失 | 只依赖 `locations.getTurn` 与 `nodes` 两个读取点；不可用时降级为"仅清单" |
| `ctx.remote.settings` 在某版本不可用 | 设置页不可用 | 收敛在 `settings-client.ts` 后；Plan B 自建路由（已验证做法） |
| mock 模型与真实协议不符 | L2/L3 失败 | 先跑探针钉死帧格式；漂移时报错直接指向 `adapter.ts` |
| `meta` 体积（整文件写入时 hunk 很大） | 渲染卡顿 | 限行 + 折叠；不复制进任何持久状态 |
| 抽象层过度设计 | 维护成本 | 只定义 3 个接口 + 1 个注册表；v1 仅 1 个内置来源、L2/L3 只留接口与空实现，且有"新工具接入"单测兜底 |
| 会话格式/元数据未来变化 | 数字消失 | 收窄失败即降级（不报错）；来源机制本身就是应对变化的入口 |

---

## 16. 实施步骤

> 已按此顺序完成，结果与差异见 §18。

1. **仓库骨架**：目录、`package.json`、`tsconfig*`、`tsdown.config.ts`、`vitest.config.ts`、`.gitignore`、`LICENSE`；`git init` 已完成，此步提交骨架。
2. **抽象层先行**：`sources/types.ts` → `sources/registry.ts` → `summary.ts` + 单测（含"假来源接入新工具"的测试）。
3. **内置来源**：`sources/diff-meta.ts` + 单测。
4. **Host**：`settings.ts`、`wire.ts`、`opener.ts`、`config.ts`、`index.ts` + 单测。
5. **Client**：`settings-store.ts`、`settings-client.ts`、`service.ts`、`SettingsSection.tsx`、`SummaryCard.tsx`、`locales.ts`、CSS + 组件测试。
6. **发布面**：`cordis.patch.yml`、`README.md`、`pnpm build && pnpm pack` 冒烟。
7. **E2E**：`e2e-common.sh` → mock 探针 → L1/L2 → L3/L4 → 截图基线 → L5（复用本机 API）。
8. **安装验收**：安装进 `web` profile → 重启 → 人工验收（含非 git 工作区一轮修改）→ 打 tag。

每步完成即提交，保持仓库始终可构建、可测试。

---

## 17. 未来增量

| 版本 | 内容 |
|---|---|
| v2 | 撤销：反向应用 hunk（staleness 校验 + 备份目录）；全屏 review 面板（`shell.overlay`） |
| v2 | L3 工作区来源首个实现：git 补漏（有 git 才生效，纯附加） |
| v2 | 设置变更推送（外部编辑 `settings.yaml` 即时反映） |
| v3 | 双语 README（`README.md` + `README_EN.md`）与 npm 公开发布流程 |
| v3 | 与 `dsh-better-sidebar` 的可选协作：若其暴露 explorer reveal API，则优先在侧栏内定位 |

---

## 18. 实施记录（与设计的差异）

v1 已按本设计实现，落地过程中有四处修正，均已回写到对应章节：

| # | 设计原案 | 实施结果 | 原因 |
|---|---|---|---|
| 1 | 卡片经 `useChat` 读该轮的 Chat 渲染节点，再由变更来源提取 | 自注册 `ConversationNodeDefinition`（kind/key `better-summary`）折叠原始事件，把成功工具结果发布到 Turn 数据，卡片只消费该数据 | 紧凑显示模式下工具节点被折叠进 `turn-process`，节点读不到 applied diff（实测只有文件清单、数字全空） |
| 2 | 单一内置来源 `dsh.tool-result-diff-meta` | 增加第二个内置来源 `dsh.tool-call-args`（优先级 50） | `write` 新建文件时工具无前像，`meta.diffs` 为空数组，需要由调用参数补齐新增行数 |
| 3 | 部署级配置含 `routePrefix` | 取消该项，路由前缀固定为 `/better-summary` | 客户端 bundle 里的调用路径是编译期常量，可配置前缀有两侧漂移风险 |
| 4 | E2E 逐条 lane 按设计描述实现 | lane 内容一致；另有三个实施细节：每个 spec 前重置工作区、工作区选择器只在 hero 出现、外壳 `/open-in-app/icon/*` 404 白名单 | 见 §12.3 |

另外两处工程决定：

- **E2E 的「命令缺失」降级路径**用「把替身脚本换成目录」制造确定性的 spawn 失败（EACCES），
  无需第二套配置或第二次启动；同时该 spec 会断言路由确实返回 5xx（把失败路径变成正向断言）。
- **`no-opener` 的 HTTP 状态码**从 400 改为 500：请求本身合法，失败发生在服务端能力
  （系统里没有可用的打开命令），语义上不是客户端错误。

### 0.1.2 修正（「在文件夹中显示」点了没反应）

现场（WSL2 + WSLg，Linux 侧无桌面）暴露了 v1 的三个问题，均已回写到 §8.2：

| # | v1 行为 | 修正 | 原因 |
|---|---|---|---|
| 1 | linux 一律 `xdg-open` | 增加 WSL 分支：`wslpath -w` 翻译后交给 Windows 桌面（单文件 `explorer.exe /select,`，目录 `Invoke-Item`） | WSL 的 Linux 侧通常没有文件管理器，`xdg-open` **启动成功、随后退出 3**（`no method available`）——点按钮完全没反应 |
| 2 | 只等 `spawn` 事件即报成功 | 2 秒窗口内观察退出码；非零即 `no-opener`（`explorer.exe` 除外，它成功时也返回 1），卡片显示原因 | 「启动了但什么都没发生」被报成成功，用户与日志里都没有线索 |
| 3 | 绝对路径也受工作目录围栏约束，越界即回落到 `cwd` | 绝对路径直接采纳；只有相对路径禁止 `..` 逃逸 | 产出常在 `/tmp`、兄弟仓库；静默换成 `cwd` 会让按钮打开错误的目录 |

配套：`wslpath` 翻译与退出码判据都可注入，因此三条分支在单测里断言（`tests/opener.spec.ts` 23 项、`tests/host.spec.ts` 26 项）；覆盖命令**不经翻译**——覆盖方自带命令语义（可能是 Linux 侧命令），拿到原样路径。

### 验证结果

| 验证 | 结果 |
|---|---|
| `pnpm typecheck` | 通过（strict，含 DSH 0.1.6-alpha.2 的官方类型包） |
| `pnpm test` | 143 项 / 8 个 spec 文件全部通过 |
| `pnpm test:e2e`（L1–L4，keyless） | 4 通过 / 1 跳过（L5 由下面一行单独触发），真实挂载 + mock 模型 |
| `pnpm test:e2e:real`（L5） | 1 通过（复用本机已配置的 provider 与凭据；本轮只改文档、清单与打包钩子，运行时代码未动，沿用适配提交上的结果） |
| `pnpm build && pnpm pack` | Host 21.8 KB / Client 67.2 KB / 25 个 `.d.ts`；tarball 可被官方渠道安装（`engines.dsh` 不影响安装） |
| `pnpm pack`（树里没有 `lib/`） | 仍产出 27 个 `lib/` 文件 —— `prepack` 钩子生效；无钩子时同一棵树打出的是空包（对比实测） |
| `pnpm install`（仓库自身，先删掉 `lib/`） | `prepare` 触发构建、`lib/` 重建，工作区保持干净 |
| git 依赖安装走 DSH CLI（`dsh plugin --profile web add git+file://…clone`） | 无白名单 → **exit 1** 且报 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`、插件未安装；在 profile 的 `pnpm-workspace.yaml` 加 `allowBuilds: {dsh-better-summary: true}` 后重跑 → exit 0，`lib/index.js` / `lib/client.js` 齐备，`dsh.profile.bundles` 出现 `dsh-better-summary`（探针关掉 side-effects cache，确保是真构建而非命中缓存） |
| **负向 lane**：把 0.2.0 挂到 DSH 0.1.5-alpha.1 宿主 | 4 失败（卡片始终不出现），页面 `pageErrors` 正是 `chain slot "conversation.chat.turnTail" requires options.select`，且 `consoleErrors` / `requestFailures` 为空——失败纯粹来自插件装载，与网络或渲染无关 |

### 0.2.0 适配（DSH 0.1.6-alpha.2：`turnTail` 由 chain 槽改为 list 槽）

DSH 0.1.6-alpha.2 把 `conversation.chat.turnTail` 的 kind 从 `chain` 改为 `list`：条目不再有
`select` 路由座位，组件也不再收到选中结果 `matched`；条目改为按 `id` 划分单元格，同格按
priority 升序**遮蔽**，只有最低的存活条目渲染，且渲染期返回 `null` **不会**把单元格让给被遮蔽的
条目（唯一让位方式是条目注销）。本包据此调整，并已回写到 §1.1、§3.1、§4、§6.5、§7.5、§8.3、§10、§11、§12.3、§15 与附录 A/C：

| # | 0.1.1 行为（chain 槽） | 0.2.0 修正（list 槽） | 原因 |
|---|---|---|---|
| 1 | 注册 `select: selectSummaryMatch`，由槽在路由期调用（选中即向组件注入匹配值） | 去掉 `select`，改为注册 `id: DELIVERABLES_CELL_ID`（DSH 自带产出行的单元格 id，硬编码——跨插件值导入被构建期纯净度闸门拒绝）；`selectSummaryMatch` 改由卡片组件在渲染期自行调用 | list 槽没有 `select` 座位；缺 `id` 会在加载期抛 `list slot "conversation.chat.turnTail" requires options.id`；沿用自带行的 `id` 才是「顶替」而非「并排再加一行」 |
| 2 | `SummaryCardProps.matched` 由槽注入 | 组件内 `const matched = selectSummaryMatch(props)` 自算，无产出时返回 `null` | list 槽没有 `matched` prop（那是 chain 选中结果的注入值） |
| 3 | 渲染期 `null` 即让链回落到下一条目 | `null` 只让本条目渲染为空（单元格留空）；`enabled` 闸门保持在**注册期**（禁用即 dispose 条目） | 只有注销才把单元格交还下一顺位（`dsh-better-sidebar` → DSH 自带产出行）；渲染期 `null` 不释放单元格，被遮蔽条目永远不会挂载 |
| 4 | 设置项标签「链优先级 / Chain priority」 | 「槽位优先级 / Slot priority」 | 该槽已不是 chain，priority 的含义是同格遮蔽顺位 |
| 5 | 版本 `0.1.1`；DSH devDep 声明 `0.1.5-alpha.1` | 版本 `0.2.0`；DSH devDep 声明 `0.1.6-alpha.2` | 跟随上游槽契约变更（`kind: 'list'`） |

`priority` 默认值仍为 `-2`（同格中低于 `dsh-better-sidebar` 的 `-1` 与自带产出行的 `0`）；
`DELIVERABLES_CELL_ID` 取 `@deepseek-ai/dsh-client-ui-deliverables`，与 `dsh-better-sidebar` 0.20.0
注册时使用的单元格 id 一致，因此共存时仍是本包遮蔽对方，最终表现与 chain 时代一致。

### 0.2.0 界面修正（卡片字号与计数列对齐）

| # | 修正前 | 修正后 | 原因 |
|---|---|---|---|
| 1 | 卡片硬编码 `font-size: 12px`（比 DSH 正文默认 14px 明显偏小），且用户无处可调 | 改读 `--summary-font-size`，默认 `var(--dsh-content-font-size, 14px)` 跟随正文；新增设置项 `fontSize`（`跟随正文` 或 11–18px 档位） | 「与正文一致」是默认预期；同时保留「我就想要更小/更大」的出口。行内 diff 用 `0.95em` 跟随缩放 |
| 2 | `+N` / `−N` 是可变宽 `inline-flex` 块整体右靠：同一行 `−N` 的宽度会把 `+N` 顶走，`+N` 自身也随位数浮动（像素实测：`+18/−8`、`+23/−19`、`+8/−2` 三行的 `+N` 左缘落在 966/961/972，右缘 981/976/981） | 两列各 `3ch` 定宽并各自右对齐，跨行形成对齐的列 | 计数属表格型数据，右对齐定宽列才是可读形式；定宽而非 `min-width` 才能保证「不随同行内容浮动」 |
| 3 | mock 场景两行计数为 `+3`/`+2`（**同宽**），任何对齐断言都是空洞的 | b.txt 改为 12 行 → `+3` 与 `+12` 位宽不同 | 让 L2 的对齐断言具备判别力，成为真实的回归防护 |
| 4 | 头部合计排在**标题之后**，与贴右缘的文件行计数相差 554px（实测 `totalAdded.right` 632 vs `rowAdded.right` 1186）；且 `.stats` 用正文字体 + 8px 间距，与行计数的等宽字体 + 6px 间距不同，列宽也不等 | 合计移到**头部最末**（按钮之后），并与 `.counts` **合并为同一条 CSS 规则**（定宽列 / 6px 间距 / 等宽字体 / 右对齐） | 「头部合计」与「行计数」读作同一张表的合计行与数据行，必须同列才可读；只有同为末项才共享右缘，只有同字体同间距才有同列宽 |
| 5 | 头部末项变多后，窄卡片下标题可能把头部顶溢出 | `.title` 加 `min-width: 0` + `overflow: hidden` + `text-overflow: ellipsis` | 标题可收缩出省略号，而不是挤压/溢出兄弟项 |
| 6 | 两格计数用两列 `inline-grid`：各自成行盒，各自的行盒度量决定各自基线。`−`（U+2212）落到度量不同的回退字体时，`−N` 整格数字下移（用户实测 `+4` 墨迹 y56-65，`−1` 墨迹 y59-68，相差 3px） | 容器改 `display: inline-block` + 两个 `inline-block` 子项（`vertical-align: baseline`），两格由构造共享同一基线；间距由 grid gap 改为 `.removed` 的 `margin-left: 6px` | 网格项的行盒度量各自独立，字体回退就会把两列数字错开；同一行盒里的两个 inline-block 没有这个问题，且与「两列定宽右对齐」的水平约束互不干扰 |
| 7 | 上面这条无法被自动化验证（headless Chromium 的等宽字体自带 U+2212，不会触发回退） | L2 增加**基线探针断言**：用零尺寸 `inline-block` 读出两格真实基线，并注入 `line-height` 扰动模拟回退，断言扰动前后基线都重合 | 修复前该断言以 4px 之差失败（369 vs 373），是可判别、可回归的验证 |

### 0.2.0 公开前的收尾（文档准确性、宿主下限、打包钩子、git 安装）

| # | 修正前 | 修正后 | 原因 |
|---|---|---|---|
| 1 | README 与本文档的测试数停留在 v1 时代的 122 项（`tests/host.spec.ts` 记作 24 项） | 143 项 / 8 个 spec 文件；`host.spec.ts` 26 项 | 0.2.0 的字号与对齐修正新增了断言；仓库公开后这些数字会被当作可信信息 |
| 2 | 安装示例写 `dsh-better-summary-0.1.0.tgz`（该版本从未产出），而当时版本已是 0.2.0 | 全部改为 `0.2.0` | 照抄示例会找不到文件 |
| 3 | `lib/` 被 gitignore 且无打包钩子：从干净克隆 `pnpm pack` / `npm publish` 打出**缺 `lib/` 的空包** | 加 `prepack: pnpm build`（见 §9.6） | `files` 要求 `lib/index.js`，`main` 也指向它 |
| 4 | 宿主版本下限只存在于提交记录与对话里 | `engines.dsh` 声明（§9.6）+ README 独立「兼容性」小节，含**两个方向**的报错原文 | 0.2.0 与 0.1.1 互不兼容是装载期硬失败，必须在用户动手前可见 |
| 5 | 只覆盖 tarball 渠道：`dsh plugin add github:…`（git 依赖）会**静默装出缺 `lib/` 的包** | 加 `prepare: pnpm build`，README 增「从 GitHub 安装」小节并写明 pnpm 10 的白名单步骤 | 仓库公开后 git 依赖是很自然的尝试；有了 `prepare`，这条路从「静默坏包」变成「明确报错 + 一行放行即可用」 |

两个方向的报错都来自槽注册表按 kind 校验必填座位这一条规则：DSH 0.1.5 的该槽是 chain（要 `select`，
本包只给 `id`），DSH 0.1.6 的该槽是 list（要 `id`，0.1.1 只给 `select`）。0.1.5 方向不只是读源码推的：
用同一条 lane 把 0.2.0 挂到 0.1.5-alpha.1 宿主上跑了一次负向验证，4 条用例全失败且报错原文一致（见上表末行）。

## 附录 A：DSH 接口证据索引

路径相对 `deepseek-harness/`。

| 主题 | 位置 |
|---|---|
| turnTail 槽渲染与 owner props | `packages/client/ui-chat/src/client/chat/TurnTailNodeView.tsx:25-26` |
| turnTail 槽声明（`kind: 'list'`，scope `session`） | `packages/client/ui-chat/src/client/contract/slots.ts` 的 `'conversation.chat.turnTail'` |
| 槽注册表按 kind 校验必填座位：list 缺 `id`、chain 缺 `select` 的报错原文 | `packages/client/ui-slots/src/index.ts` 的 `SlotCore.register`（`switch (spec.kind)`）；DSH 0.1.5-alpha.1（master）第 853 / 861 行 |
| list 槽语义：`id` 分格、缺 `id` 报错、同格最低 priority 遮蔽渲染 | `packages/client/ui-slots/src/index.ts` 的 `SlotCore.register` / `SlotCore.entriesOfSlot` |
| 动态守卫对槽位 priority 的处理（非 chain 槽自动分配 shadowing rank） | `packages/extensions/cordis-client-runner/src/client/guard.ts` 的 `guardedSlots` |
| tool/result 事件的 meta | `packages/core/session/src/types.ts:353-360` |
| applied diff 的产生与持久化 | `packages/fs/tool-fs/src/diff.ts:14-20,33-57` |
| write / edit 的 result 与 meta | `packages/fs/tool-fs/src/write.ts:121-146`、`edit.ts:140-164` |
| str_replace_editor 的调用期 diffs | `packages/fs/tool-str-replace-editor/src/index.ts:385-415` |
| Client 节点保留 meta | `packages/client/ui-chat/src/client/conversation-nodes/tool.ts:65` |
| ChatSnapshot 结构 | `packages/client/ui-chat/src/client/contract/snapshot.ts:92-99` |
| deliverables turn data | `packages/client/ui-deliverables/src/client/turn-deliverables.ts:122-145` |
| 会话 header.cwd | `packages/core/session/src/index.ts:111-114,464` |
| 设置与凭据文件位置 | `packages/settings/settings-file/src/index.ts:57`、`packages/credentials/credentials-local/src/index.ts:61` |
| 内置语言 | `packages/client/locale/src/locale-settings.ts:15` |
| LLM 自定义端点 | `packages/llm/llm-deepseek/src/adapter.ts:651` |
| 客户端 bundle / 路由 / 原生打开的可行范式 | `DSH-better-sidebar/{tsdown.config.ts, src/index.ts:863, src/open-external.ts}` |

## 附录 B：落地前待验证项（均已验证）

| # | 项 | 结论 |
|---|---|---|
| 1 | `ctx.remote.settings` 可用 | ✅ 可用，Plan B 路由通道未启用（实现仍保留了网关接口边界） |
| 2 | priority `-2` 压过 `dsh-better-sidebar(-1)` | ✅ 卡片在真实挂载中取代了 chip 行 |
| 3 | `useChat` 读 Chat 节点可行 | ❌ **不可行**：紧凑显示下工具节点被折叠 → 改为自注册定义折叠原始事件（见 §6.1、§18） |
| 4 | mock 模型 SSE 帧格式 | ✅ 与 `translate.ts` 一致：`choices[].delta` + `finish_reason` + `usage` + `[DONE]` |
| 5 | 外部包 client bundle 的重建行为 | 迭代以 `pnpm build` + 重新挂载（scratch）或重启为准 |
| 6 | scratch 复用本机配置跑真实一轮 | ✅ L5 通过（复用本机 provider 与凭据，无需额外环境变量） |

## 附录 C：术语

| 术语 | 含义 |
|---|---|
| turn tail | 一轮对话收尾处的扩展位置（`conversation.chat.turnTail` list 槽） |
| 单元格 / 遮蔽 | list 槽按条目 `id` 划分的渲染格；同格内 priority 最低的存活条目渲染，其余条目被它遮蔽（注销即交还下一顺位） |
| 产出清单 | 该轮成功调用 `write`/`edit`/`str_replace_editor` 产生的文件路径集合（来自 Turn data `deliverables`） |
| 变更来源 / 策略 | 把节点或工作区翻译成 `FileChange[]` 的可注册实现（L1/L2/L3） |
| hunk | 一段带上下文的 diff 分块（`{ path, oldText, newText }`） |
| scratch home | E2E 专用的临时 `DSH_HOME`，与用户真实 home 完全隔离 |