# 大排期预研：界面 × 文档 × 首页

> 生成时间：2026-09-10 · 对应版本 v2.4.0（pre 线）
> 上游：`docs/UI-REFACTOR-PRE-RESEARCH.md`（设置页重构预调研，其「第 0 步·止血」已落地：路径表一致性锁 + 写配置单一出口）
> 本文性质：**预研 + 排期草案，未开工**。文末 §8 有 6 个待你拍板的点。

---

## 0. 你定的验收标准（原文口径）

> 「找得到但太杂，现在美学设计比较一般，而且很乱。这属于强技术、弱外观、弱使用。」
> 「目标用户是 npm 公开用户，目前 1 万多下载，很多用户反映需要有说明书，没法直接上手。」
> 「改动规模比较大，但应该单独放出一个排期来做，**其他的后端不能动**。要把三件事一起做完：①前端和设计页面的大改 ②README 里的用户说明书/项目文档的大改 ③项目首页 HTML 的大改。」

拆成五条可验收的判据（§6 展开）：**能上手 / 看得懂 / 不重复 / 后端零改动 / 每步可发版**。

---

## 1. 边界：什么叫「后端不能动」

### 1.1 冻结清单（本次排期一律不碰）

| 冻结项 | 具体范围 | 为什么 |
| --- | --- | --- |
| 记忆引擎 | `lib/index.js` 的记忆/检索/注入/水位/接续全部逻辑；`lib/*-pre.js` 除 `client.js` 外的全部模块 | 后端行为不变，才能保证"改外观不会改行为" |
| HTTP 契约 | 46 条路由的路径、方法、请求/响应结构 | 界面已收敛到路径表（第 0 步），改契约会连锁 |
| 配置语义 | `DEFAULT_CONFIG` 85 键的名称、类型、默认值、联动规则 | 用户已落盘的配置必须继续有效 |
| prompt 层 | `DEFAULT_PROMPT_LAYERS`、注入文案、缓存友好性 | 影响 token 与官方缓存命中 |
| Python 引擎 | `python/`、worker 协议、安装向导的后端步骤 | 与外观无关 |
| 工具面 | 14 个 `memory_*` 工具的名字与参数 | 已发布契约 |
| 测试 | `tests/smoke/69` 个套件的既有断言 | 只能新增，不能放宽 |

### 1.2 可动清单

`lib/client.js`（界面半边）、`README.md` / `README.zh-CN.md`、`docs/USER-GUIDE.{en,zh-CN}.md`、`docs/landing/index.html`、`package.json` 的**打包元数据**（`files` / `homepage` / `description` / `keywords` / `engines` / `scripts`）、新增 `docs/internal/**`、`docs/screenshots/**`（重拍）、新增测试。

**`package.json` 的例外说明**：只动对外元数据字段，**不动** `main` / `exports` / `dsh` 的 bundle 与 client 注入契约（除非要新增一个注入包，见 §4.2——那是打包层，不是引擎层）。

### 1.3 可行性已证：看起来要动后端的事，其实都不用

| 想做的事 | 直觉上要改后端？ | 实际做法（全在客户端/打包层） |
| --- | --- | --- |
| 设置项分组 + 每项「改了会怎样」说明 | ✗ 不需要 `DEFAULT_CONFIG` 加元数据 | 客户端 i18n 字典已有 119 个标签键 + zh/en 两块；分组与说明写在客户端常量里 |
| 场景预设（省心/平衡/激进） | ✗ | 把一组 patch 发给既有的 `POST /config`（宿主本来就是 patch 合并，`index.js:1425`） |
| 「仅文件键」折叠 | ✗ | 客户端本来就不渲染那 18 个键，只需显式标注 |
| 幽灵键 `pythonGpu` | ✗ 宿主侧**零引用**（`index.js` 0 次 / `client.js:4154` 1 次） | 删客户端那一处即可 |
| 术语改写（水位→上下文余量…） | ✗ | 客户端 i18n |
| 首启「一键开启主动联想」 | ✗ | 客户端在向导里明确询问后写入 `POST /config`（**不改出厂默认值**，见 §4.4） |
| 把页面挂到原生插槽（侧栏面板等） | ✗ | `slots.inject(name, () => slots.register({name,id,order,label}, 组件))` 是通用 API（`client.js:4509-4523`）；必要时在 `package.json` 的 `dsh.client.inject` 加一个包名 |

---

## 2. 现状硬数据

### 2.1 界面（`lib/client.js` 4,541 行）

| 指标 | 数值 | 出处 |
| --- | --- | --- |
| 注册面 | 5 个：侧栏入口按钮 / 浮层面板 / 弹窗宿主 / 自动接续宿主 / 设置页 | `client.js:4507-4523` |
| 浮层尺寸 | **440×560 固定**，可拖拽缩放，位置存 localStorage | `client.js:34-36` 等 |
| 页签 | **12 个**（概览/日志/唤起回顾/记忆中枢/存储管理/笔记/白板/反思/接续/日历/检索/工作区） | `client.js:307` |
| 设置分组 | 8 组 / 85 键（界面可改 67、仅文件 18） | `UI-INVENTORY-RAW.md` §2 |
| 巨型函数 | `SettingsPage` **582 行**（8 分组+目录浏览器+模型抽屉+环境检测+向导挂载+更新检查+调试中心）、`DialogHost` **478 行**（7 种弹窗+首启向导状态机） | 同上 §4 |
| 逐字重复 | `RefineTab` 的 `badge`/`reasonChip`/`apeRow` 两份完全相同 | `client.js:1644-1662` / `1682-1699` |
| 文案机制 | **两套混用**：`I18N` 字典（`client.js:150-453`）+ 内联 `locale==='zh'?…:…` 约 **354 处**；4,450 非空行中 **737 行含中文（16.6%）** | 冷启动审计 |
| 界面专有名词 | ≈49 个（12 页签 + 8 分组 + 19 配置键 + 杂项） | 文档审计 |

### 2.2 设计语言：**三套并存**（这是「乱」最硬的结构性证据）

| 语言 | 用在哪 | 令牌/特征 | 证据 |
| --- | --- | --- | --- |
| DSH 原生 | 插件所在的宿主界面 | `--dsw-*` 令牌体系（`dsh-client-ui-theme` 内 **768 处**引用），亮/暗自动切换；CSS Modules 私有不可复用 | 官方 checkout `dsh-client-ui-theme/lib/client.js` |
| 面板「液态玻璃」 | 插件面板 | `backdrop-filter: blur(28px) saturate(1.55)`、`border-radius: 16px`、渐变高光、圆角卡片层叠 | `client.js:951-971` |
| 首页「现代主义」 | `docs/landing/index.html` | 暖纸 `#F4F1EB` / 墨 `#17171A` / 信号橙 `#E9470C` / 1px 细线 / 12 列网格 / **无渐变·无圆角·无阴影** | `:root` 令牌块；自述"现代主义·国际主义" |

补充事实：首页的**原始大纲**写的是「深色底 #0B0F1A + 渐变 #4D6BFE→#9B7EFF + 磨砂玻璃卡片」（`docs/LANDING-OUTLINE.md:13`），落地时被实现成了**相反的**现代主义风格（大纲允许"美术完全自由发挥"）。也就是说：宿主一套、面板一套、首页一套，且首页连自己的大纲都没继承——**三套语言、三个来源、互不知情**。

### 2.3 文档

| 指标 | 数值 |
| --- | --- |
| README | `README.md` 490 行 / `README.zh-CN.md` 492 行（**说明书式内容 147 行 = 30%**） |
| 操作词频（中文侧） | 向导 16 / 开关 12 / 设置页 10 / 面板 8 / 点击 6 / 页签 6 / 勾选 2 / 按钮 2 |
| README 与 USER-GUIDE | 重复讲同一件事 **13 处**；两份 USER-GUIDE 各 382 行，是**页面导向**的说明书（30 标题 / 61 配置键 / 13 条排错） |
| docs 全量 | 盘上 **106 个 .md**，其中 **48 个连 git 都没进**（含 `USER-GUIDE.en.md`、`HANDBOOK.md`、`ROADMAP.md`、`STATUS-BOARD.md`、`docs/prompts/*` 36 份）——**npm tarball 是其中相当一部分的唯一副本** |
| npm 包体量 | 2.4.0 tarball **209 文件 / 12.59 MB，其中 docs 占 10.86 MB = 86%**（截图 7.92 MB）；**101/106 个 md 是内部工程文档**，README 只引用 8 个 |
| 事实性错误 | 至少 **6 处**（见 §4.5 表） |

### 2.4 首页与分发面

| 项 | 现状 |
| --- | --- |
| 首页 | `docs/landing/index.html`，**1,745 行 / 122 KB 自包含单文件**（1 个 `<style>` + 1 个 `<script>`，零外链，中英双语切换） |
| 发布链 | 只在 `preview` 分支；README 用 **第三方代理** `htmlpreview.github.io/?…/blob/preview/docs/landing/index.html` 渲染（`README.md:9`）；**无 `.github/`、无 gh-pages、无 CNAME、无 Pages workflow** |
| 线上一致性 | 已核对：GitHub `preview` 分支该文件 blob sha = 本地 `ec6604…`，**内容一致**（不存在"线上是旧的"问题） |
| 配图 | `docs/screenshots` 29 张 / 7.92 MB：22 张界面图（panel-* / tour-* / settings-* / calendar-* / overview-* …）+ 7 张六幕宣传图；**全部需要按新 UI 重拍** |
| 门面件 | `.github/` 完全不存在（无 issue 模板 / CONTRIBUTING / SECURITY / workflow）；`package.json` 缺 `homepage`；description 331 字符被 npm 截到 255（中文段全丢） |

### 2.5 冷启动（npm 公开用户的真实断点）

| # | 断点 | 证据 |
| --- | --- | --- |
| 1 | **头号卖点出厂关闭**：`associativeMemoryEnabled: false`，而首启向导把它渲染成「推荐 + 默认开」（`tg.def!==false`） | `index.js:349` / `client.js:3229,3303`；用户不点 = 看到 ON 但实际 OFF（幻觉），点一下才真写入 |
| 2 | **向导无兜底触发**：只有 `update-check` 返回 `current` 才分发首启弹窗；断网/代理拦截 → **完全没有首启引导**；`firstRunDone` 是死键（只读无写） | `client.js:4439,4398` |
| 3 | 向导进引擎步**自动开下 130MB 模型**，失败态**没有重试按钮** | `client.js:3168-3175,3287` |
| 4 | 「面板怎么打开」没有独立说明（README 只有一句"侧边栏出现「记忆」入口"） | `README.md:277` |
| 5 | README 首屏 8 张图（3.11 MB）之后才有第一句价值叙事 | `README.md:13-53,61` |
| 6 | USER-GUIDE 让用户跑 `node tools/subagent-gc.mjs`——`tools/` **根本没打包**；且泄漏 `-pre` 期命名 | `USER-GUIDE.en.md:307,355,329,369` |

### 2.6 设计审计：样式层的量化证据（只读，`lib/client.js` L954-1259 为 CSS 区）

**体量与写法**：CSS 数组 306 行 / 290 条字符串；`data-dam-*` 出现 **673 次 / 86 种**；内联 style 对象 **228 个**，而 `className` **仅 4 处**——**样式只有 1.7% 走 class**，其余全在 JS 里。

**令牌层「只有名字，没有层」**：

| 项 | 实测 |
| --- | --- |
| 自有 `--dam-*` | 引用 63 次，**8 个名字**，其中 4 个只是首启向导的玻璃美术参数；真正服务全 UI 的只有 `--dam-accent` 与 `--dam-scale` |
| 宿主 `--dsw-*` | 引用 86 次 / **11 个名字**；上游公开 `--dsw-alias-*` 有 **79 个** → 只用了 **14%** |
| **幽灵令牌** | `--dsw-alias-text-primary`×4、`--dsw-alias-warn`×4、`--dsw-alias-danger`×1 —— **上游不存在**，这 9 处永远走 fallback |
| 硬编码颜色 | **320 处 / 132 种**（hex 131 处 37 种 + rgba 189 处 95 种） |
| **主题色的 5 个 fallback** | 同一个 `--dam-accent` 分别兜底 `#2456c4`(14) `#3a6df0`(9) `#4f7cff`(9) `#1d4ed8`(7) `#6b98ff`(1)——**等于承认这个语义从没定过一个值** |

**「乱」的取值集合（去重后）**：

| 维度 | 种数 | 最刺眼的一条 |
| --- | --- | --- |
| `border-radius` | **25 种** | 9/10/11/12/14/16 六个相邻值同时存在，各只出现 1-4 次，没有台阶 |
| `padding` | **47 种** | 内联 58 处里 22 种只出现一次（如 `4px 2px 2px 8px`） |
| `gap` | **14 种** | **2px→13px 连续满档一个不缺** = 没有间距刻度的直接证据 |
| `font-size` | **19 种** | 裸值与 `calc(Npx * var(--dam-scale))` 并存 → **缩放开关对约 20% 的文字无效** |
| `box-shadow` | **20 种** | CSS 侧 16 种**全是 singleton（100%）**，没有任何两个相同 |
| `line-height` | **13 种** | CSS 侧 7 种全 singleton |
| 毛玻璃 | **8 套配方** | 5/6/10/12/14/16/20/28/30px 九档并存 |
| `z-index` | 6 种 | `1/2/3/5/3000/2147482900`——中间全空 |
| `opacity`（内联） | **29 种** | 缺「说明文字」级别的直接后果 |

**布局**：面板尺寸在 **CSS 与 JS 各写一遍**（`width:440px;height:560px` 与 `DEFAULT_W/H`）；`@media` **只有 1 条且是 `prefers-reduced-motion`，没有任何宽度断点**。窄面板推演：拖到 300px 下限 → body padding 16 后剩 268 → 设置页 `92px 导航 + 18px gap` 剩 158 → 行 label `flex:0 0 110px` → **输入控件只剩 ≈48px**，而 12 个页签在 196px 里必然长距离横滚。

**状态与可访问性（几乎全是"补"的）**：`:hover` 12 条、`:active` 2 条、**`:focus` 0 条、`:focus-visible` 0 条**；`aria-*` 9、`role` 1、`tabIndex` 0；`window.confirm` **0 次**——`StorageTab` 删除是**单击即删**（仅"输入没填全则 disabled"的软保护），危险色有 **5 个值**各自为政。

**排版**：**6 套卡片**并存（`data-dam-card` / `data-dam-banner` / 内联 `var card`×2 份逐字复制 / `panelStyle`×2 / 向导卡）；"表格"有 **4 种实现**（grid auto / 固定 110px / 120px / 140px）；"标题"有 **4 种写法**（`h3`×1 / `b`×19 / `strong`×1 / 内联 `fontWeight:700`×14）；`RefineTab` 同一页里圆角玻璃卡 + 尖角左边框条 + 细分隔线三种表达并存。

**一个 CSS 装两个产品**：CSS 的 **67%**、`@keyframes` 的 **32/38**、`data-dam-*` 的 **43/86** 都服务首启向导与更新卡（核心面板只用 14,619 字符）——`z-index: 2147482900`、`border-radius: 23px/27px` 这些值其实只用一次，却容易被误当成"设计语言的一部分"。

**与首页的纪律差距（这是"不像同一个产品"的量化来源）**：

| | 首页 `docs/landing/index.html` | 面板 `lib/client.js` |
| --- | --- | --- |
| 令牌 : 字面量 | 227 : 75 = **3.03 : 1** | 86 : 320 = **0.27 : 1** |
| 圆角出现 | **2 次**（都是 `50%`） | **96 次 / 25 种** |
| 阴影出现 | **2 次**（状态点光环） | **20 种配方** |
| `backdrop-filter` | **0 次** | 17 处 / 8 配方 |

**上游令牌层是「纯颜色层」**：79 个 `--dsw-alias-*` 里检索 `radius|space|font|shadow|z-` **命中 0**。→ 结论：**颜色/边框必须 100% 继承 `--dsw-*`（可做到零字面量）；间距/圆角/字号/行高/阴影/层级/玻璃强度必须自建 `--dam-*`，且只留这一套真值；向导美术隔离到 `--dam-tour-*`。**

**收敛映射（可直接当施工单）**：圆角 **25 → 5**（6/10/16/999/50%）· padding **47 → 5**（4/8/12/16/24）· 字号 **19 → 6**（10/11/12/13/14/20，且全量 `calc(… * var(--dam-scale))`）· 行高 **13 → 3** · 阴影 **20 → 3(+1 高光)** · 层级 **6 → 5** · 玻璃 **8 → 3** · 边框 **24 → 3** · 字重 **7 → 3**。触碰点：颜色 320 处、间距 ≈253 处、字号 104 处、圆角 96 处、阴影/玻璃 44 处；**零风险的 9 处幽灵令牌建议第一批做**。
**风险最高 5 处**：面板玻璃配方（全产品观感）· `SettingsPage`/设置栅格（窄面板塌陷）· `DialogHost`（67% CSS 所在地，须先物理拆出 `--dam-tour-*`）· 日历象限色（要重新定义语义而非机械替换）· `fontScale` 全量生效（会让从未缩放的 20% 文本在 `xl` 档溢出，四档逐一实测）。

---

## 3. 诊断：为什么"乱"（每条都可反驳）

1. **没有设计令牌层** → 同一语义有多种取值：面板自己定义玻璃/圆角/间距，既不统一于 DSH 的 `--dsw-*`，也不统一于首页的 `--paper/--ink/--accent`。后果：任何一处调整都是局部补丁，且亮/暗主题下表现不一致。
2. **没有组件层** → 卡片/行/标签/按钮各页各写一套（`RefineTab` 两份逐字重复、`data-dam-settings-row` 全仓仅 3 处），新增功能只能"往缝隙里塞"（4 个补丁式入口已被盘点）。
3. **三套设计语言并存**（§2.2）——用户看到的"美学一般且很乱"，本质是**没有统一的美学主张**。
4. **内容与容器错配**：12 个页签 + 8 个设置分组 + 85 个键，全塞进一个 **440×560** 的浮层。这不是"东西多"，是**把内容管理型界面塞进了状态展示型容器**。
5. **文档在替界面说话**：README 30% 是操作说明、49 个界面专名 → 等价于承认"界面自己没说清"。
6. **冷启动断链**：卖点功能出厂关闭 + 向导无兜底 + 无重试 → 公开用户"装上了但没看见效果"，于是回头找说明书。

---

## 4. 方案：三条线的目标形态

### 4.1 W1-a 设计基座（令牌 + 组件原语 + 去玻璃）

- **颜色/边框/层级唯一来源 = `--dsw-*`**（宿主原生令牌，亮/暗自动跟随）；面板不再自造色值。
- **新增一层极小的度量令牌**（写死在 client.js 的 `:root` 注入）：间距（4/8/12/16/24）、圆角（4/8/12）、字号阶（11/12/13/15/18）、行高、层级（面板/弹窗/提示）、密度（舒适/紧凑）。
- **去掉液态玻璃层叠**：`backdrop-filter` 从"每张卡一层"降为"面板底板一层"（或按宿主环境决定），圆角收敛到 3 档，去渐变高光。
- **三层职责划分**（依 §2.6 审计结论）：**颜色/边框 = `--dsw-alias-*` 唯一来源（零字面量，亮暗自动跟随）**；**间距/圆角/字号/行高/阴影/层级/玻璃强度 = 自建 `--dam-*`（上游不提供，必须自建且只留这一套真值）**；**首启向导/更新卡美术 = `--dam-tour-*` 独立命名空间**（物理隔离，否则会把只用一次的美术值当设计语言抄进令牌表）。
- **抽 7 个组件原语**（替换现存的 6 套卡片 / 4 套「表格」/ 4 种标题 / 4 套浮层 / 2 套页签）：`Card` / `Row`(label+control+hint) / `Field` / `Badge` / `Tabs` / `Modal`(含 Popover) / `Toolbar`（可选第 8 个 `SegmentedControl`）。
- **术语表替换**（Top5）：水位 → **上下文余量**；接续 → **换窗口续做**；锚定 → **记忆索引**；白板 PLAN / 账本 → **项目看板 / 交接记录**；唤起·固化·晋升 → **想起来 / 记下来 / 变成技能**。全部走 i18n，中英同步。

### 4.2 W1-b IA 重排：12 页签 → 三处原生落点

DSH 插槽目录共约 58 个（从 `dsh-cordis-client-runner` 提取），插件今天只用了 3 个。可用落点与建议：

| 今天的位置 | 建议落点 | 为什么 |
| --- | --- | --- |
| 概览 / 水位 / 接续状态 | `conversation.session.header.utilities` 或 `conversation.composer.bar`（常驻一行小状态） | 状态展示型内容不该占浮层；"瞄一眼"原则 |
| 日志 / 笔记 / 白板 / 反思 | `sidebar.panellist`（侧栏面板，可停靠） | 内容管理型，需要空间与常驻 |
| 记忆中枢 / 存储管理 / 工作区关系图 / 日历 | `sidebar.right.tab.document`（右侧文档页，宽幅） | 表格与图需要宽度 |
| 检索 / 唤起回顾 | 对话内交互（`conversation.*`）或侧栏面板 | 结果就地展示，不做"独立页" |
| 设置（85 键） | `settings.section`（已用）+ `settings.onboarding` | 原生设置位 |
| 浮层面板 | **降级为"状态 + 快捷入口"**（小、只读、不承载内容管理） | 保留老用户肌肉记忆，但不再当仓库 |

**实现可行性**：`slots.inject(name, () => slots.register({name,id,order,label}, render))` 是通用 API，注册别的插槽不需要改后端；跨包插槽可能需要在 `package.json` 的 `dsh.client.inject` 里加包名（打包层）。
**第一个动作（P2 开工当天）**：写一个 20 行的 spike——向 `sidebar.panellist` 注册一个空面板，重启后确认渲染位置与样式。**失败则回退**为"保留浮层但按 §4.2 三组重排"。

### 4.3 W1-c 设置台重构

- 85 键分 5 组：**记忆（她记什么）/ 引擎（怎么检索）/ 接续（怎么交接）/ 界面 / 高级**。
- 组内再分「**政策**」（用户该懂的开关、阈值、容量，默认可见）与「**实现**」（文件路径、模型文件名、目录名 → 折进「高级」，展开时明确警示）。
- **场景预设**三档（省心 / 平衡 / 激进）一键写一组值，并显示"已偏离预设"。
- 每项配一句「改了会怎样」（客户端 i18n，~67 条）。
- 删幽灵键 `pythonGpu`；把 `SettingsPage` 582 行按分组拆成多个组件。

### 4.4 W2 冷启动闭环（公开用户的关键）

| 动作 | 做法 | 是否动后端 |
| --- | --- | --- |
| 向导兜底触发 | `update-check` 失败/超时也用本地条件（localStorage + 版本）决定是否播放；清掉死键 `firstRunDone` | ✗ |
| 消除"幻觉 ON" | 向导第 3 步**如实显示出厂关**，并给「帮我打开（推荐）」一键按钮 → 明确写入配置 | ✗（不改默认值） |
| 引擎步 | 改为"点『安装』才下载"；失败态加**重试**按钮（复用设置页同源 API） | ✗ |
| 面板怎么开 | 首启在侧栏入口旁给一次性提示（tooltip/渐变高亮），README 不再承担 | ✗ |
| 术语与文案 | §4.1 术语表；把 354 处内联 `locale==='zh'?…:…` 收进 i18n 字典（英文 UI 漏翻的结构性原因） | ✗ |

**唯一需要你破例的后端改动（可选）**：把 `associativeMemoryEnabled` 出厂默认改为 `true`。我**不建议**——它会让老用户升级后行为突变；用"向导明说 + 一键开启"更稳。

### 4.5 W3 文档体系

| 文档 | 现在 | 目标 | 关键动作 |
| --- | --- | --- | --- |
| README（双语） | 490 / 492 行，30% 说明书 | **各 ≤120 行**，五段式：一句话价值 → 30 秒上手 → 为什么值得装 → 装与不装 → 指针 | 落地已写好的 `docs/NEXT-MAJOR-README-DRAFT.zh.md`（205 行）为骨架，但**必须改掉**：安装位置提前、"十个页签"错、"配置 JSON 保留区"删除、`memory_search` 错名、草稿 58 行违反自家文风守则的句式 |
| USER-GUIDE（双语） | 各 382 行，页面导向 | **各 ≤260 行**，任务导向（"我想找回上周的决定"/"我想让她别总弹窗"…） | 设置键说明降为附录表；删 `-pre` 泄漏与不可用命令 |
| docs 打包 | 101/106 个 md 不该进包 | `docs/internal/**` 移出 `files`；保留 `screenshots/` + 3 篇论文 + system-map.html | **不能整目录删 docs**：README/GUIDE 的图片是相对路径 `docs/screenshots/…`，删了 npm 页图全断 |
| 双语漂移 | 靠人工纪律，已漏（`README.md:294` 的 `/n/n`，ZH +2 行） | 加**对账脚本**：标题序列 + 命令块 + 关键数字（0GB/130MB/563MB、0.75/0.80、8000/200000）必须逐字符一致 | 新增 `tools/check-readme-parity.mjs` |
| 事实性错误 6 处 | — | 全部修正 | ①handoff「默认开启」写 4 处（实为 false）②「Ten tabs」实为 12 ③`memory_search` 实为 `memory_recall` ④EN:294 `/n/n` ⑤EN 的 H1 是中文 ⑥GUIDE 让跑未打包的 `tools/subagent-gc.mjs`、配置路径写成非 `-pre` 名 |

### 4.6 W3 首页 + 发布链

- **改版**：沿用现代主义的**排版纪律**（网格/细线/等宽标签），把品牌色与产品面板的关系说清；内容按现状大纲重写（数据流 → 十二能力 → 界面速览 → 三步安装 → 社区）。
- **配图**：重拍 22 张界面图 + 更新六幕宣传图（依赖 P1/P2 定稿）。
- **发布链**（建议改）：把 landing 从 `preview` 分支 + htmlpreview 代理，改为 **GitHub Pages**（需要你开仓库 Settings → Pages，或加一条 `gh-pages` workflow）；README 入口改直链。理由：第三方代理是单点依赖（限流/失效即断），且多一跳渲染。
- **门面件**：补 `.github/`（issue 模板、CONTRIBUTING）、`package.json` 的 `homepage`、缩短 description 到 255 字符内（中文段前置）。

---

## 5. 排期（每阶段独立可发版）

| 阶段 | 内容 | 产出 | 验收 | 预估 |
| --- | --- | --- | --- | --- |
| **P0 前置** | ①`git add` 48 份未跟踪 md（防丢）②双语对账脚本 ③边界快照（现界面/现首页全屏留档） | 脚本 + 基线截图 | 脚本跑绿；48 份文件进 git | 0.5 天 |
| **P1 设计基座** | 令牌层 + 6-8 组件原语 + 去玻璃 + 术语表 | `client.js` 重构（**功能零变化**） | smoke 69/69；亮/暗双主题截图；你目视签收 | 2-3 天 |
| **P2 IA 重排 + 设置台** | 插槽 spike → 三处落点；浮层降级；85 键分组/预设/高级折叠；拆 `SettingsPage` | 新面板 + 新设置页 | 12 页签全部可达（≤2 次点击）；无功能丢失（逐项对账表） | 4-6 天 |
| **P3 冷启动闭环** | 向导兜底/真默认/重试/术语/空状态/一次性提示 | 向导 v2 | 断网也能进向导；引擎步失败可重试；英文 UI 无中文残留 | 2-3 天 |
| **P4 文档体系** | README 双语重写 + GUIDE 任务化 + docs 分层出包 + 6 处纠错 | 4 份公开文档 + 收窄的 `files` | README ≤120 行、操作词频归零；`docs/internal` 不在 tarball；图片仍可渲染 | 3-4 天 |
| **P5 首页 + 发布链** | landing 改版 + 22 张图重拍 + Pages/gh-pages + 门面件 | 新首页 | 直链可访问；双语切换正常；图与产品一致 | 3-5 天 |
| **P6 收口发版** | 一致性走查（术语/数字/截图/链接）+ CHANGELOG + 发版 | 大版本 | §6 判据全绿；三处复核（npm/GitHub/tag） | 1-2 天 |

**合计约 16-24 个工作日**。每阶段结束都可单独发一个版本，中断不会留下半成品界面。

---

## 6. 验收判据（替代旧 J1-J4）

| 判据 | 目标 | 怎么测 |
| --- | --- | --- |
| **J1 能上手** | 陌生用户**不看文档**，5 分钟内完成"装上 → 打开面板 → 看见她在工作" | 找 1-2 个真人（或录屏自测）：从 npm 页开始计时；且**卖点功能真的在跑**（不是幻觉 ON） |
| **J2 看得懂** | 界面术语零专业黑话；英文 UI 无中文残留、中文 UI 无英文残留 | 术语表逐项对照；`grep` 统计残留 |
| **J3 找得到** | 任一设置项 ≤2 次点击；"政策级"键默认可见数 ≤20 | 点击路径走查 |
| **J4 不重复** | README 操作指引 = 0；README ≤120 行；docs 内部文档不进包 | 操作词频统计 + tarball 清单 |
| **J5 后端零改动** | 46 路由 / 85 键语义 / 14 工具 / prompt 层**逐字节未变** | `git diff` 只命中可动清单；smoke 69/69 |

---

## 7. 风险与坑

1. **48 份未入 git 的文档**（`USER-GUIDE.en.md`、`HANDBOOK.md`、`ROADMAP.md`、`STATUS-BOARD.md`、`docs/prompts/*`）——改造前必须先收编，否则"整理 docs"会直接销毁只存在于磁盘/npm 包里的文件。**这是 P0 的第一件事。**
2. **治理冻结**：`docs/PROJECT-FREEZE-AND-ROADMAP.md:8` 写着「大版本完成前禁止改 README；npm 同步也等大版本一起」——本次排期**就是**那个大版本，所以不冲突，但**必须由你确认**这条冻结以本次排期为准解除。
3. **插槽可行性尚未实测**：`sidebar.panellist` 等原生位能否被第三方插件注册、样式是否可接受，需要 P2 的 spike 验证；有回退方案（保留浮层重排）。
4. **npm 页面按版本缓存 README**：文档改动必须随下一次 publish 才在 npm 可见。
5. **配图重拍成本**：22 张界面图 + 7 张宣传图，且 landing/README 都引用相对路径——改图必须同步改文，顺序是"UI 定稿 → 重拍 → 改文"。
6. **双语维护**：中文母本 + 英文按骨架重写（**不做逐句翻译**：EN 现行 H1 是中文、文风守则的中文语料不可迁移），并用对账脚本锁住命令与数字。
7. **pre 线不能发布**：仓库 `package.json:5` 是 `private: true`（REL 由 `release.mjs` 剥离），任何"从 pre 发一版"都会失败；`-pre` 专名会持续往文档里漏，需在 P4 统一清理。

---

## 8. 待你拍板（6 件）

1. **首页托管**：继续 htmlpreview + `preview` 分支，还是改 GitHub Pages / `gh-pages`？（改 Pages 需要你在仓库 Settings 里开一次）
2. **设计主张**：产品内界面**向 DSH 原生靠**（`--dsw-*` 令牌 + 原生插槽），首页**保留现代主义品牌风**——接受"同一产品两种语境"，还是要求两者视觉完全统一？
3. **浮层面板**：同意降级为"状态 + 快捷入口"，内容迁到侧栏/右侧原生位？（P2 会先做 spike，失败即回退）
4. **出厂默认**：`associativeMemoryEnabled` 保持 `false` + 向导明说并一键开启（我推荐），还是改为出厂 `true`（破例动后端默认值）？
5. **docs 出包**：同意把内部文档移到 `docs/internal/` 并收窄 `files`（npm 包体量预计从 12.6 MB 降到 ~1.5 MB）？保留 `docs/screenshots` + 3 篇论文 + system-map.html。
6. **排期节奏**：按 P0-P6 顺序推进（每阶段可发版），还是先集中做 P1+P2（界面）再谈文档？

---

## 9. 本次不做什么

后端引擎与协议（§1.1 全部）、功能语义（不新增/不删除能力）、prompt 与注入策略、Python 引擎、既有 69 个 smoke 的断言、`npm publish` / push（按你的规矩，未获明确指示不发）。