# 交接：dsh-auto-memory 功能梳理 + 首页构建（2026-09-20 · 来自 DSH 线）

---

# 🚨 2026-09-20 更新 · 美术方向已换（**先读这段**）

**用户裁定：「把原有的那个色调和风格丢掉，主要采用 DeepSeek 主页的形式。」**

## 权威文档已更换

| | 文档 | 状态 |
|---|---|---|
| ❌ **作废** | `docs/internal/ART-DIRECTION-WIREFRAME.md` | **不要再照它做配色** |
| ✅ **现行** | **`docs/internal/ART-DIRECTION-DEEPSEEK-20260920.md`** | **照这份做** |

**链接**（用户在文件面板可直接打开）：

```
D:\dsh-auto-memory\docs\internal\ART-DIRECTION-DEEPSEEK-20260920.md
```

## 如果你已经在做了 —— 自查三条，一样就继续，不一样就改

| # | 自查项 | 若不符 → 改成 |
|---|---|---|
| **1** | **主色是品牌蓝 `#4d6bfe` 吗？** | 若是**信号橙 `#E9470C`** ⇒ **改** |
| **2** | **用了玻璃 + 圆角吗？** | 若你**避开了** `backdrop-filter` 和圆角 ⇒ **改**（官网自己就在用：`blur(12px)`、卡片 24px） |
| **3** | **背景与角色是分层帧率吗？** | 若是**整页统一帧率** ⇒ **改**（背景 60fps + **角色 24fps 线描抽象**） |

## 三条核心规格（速记）

1. **底色**：亮 `#f9f8f8` / 暗 **`#0a0a0a`**（**建议主推暗色**，贴「黑鲸」调性）
2. **层级**：**半透明白叠加**（`surface-1..5`），不画实色分区线
3. **★ 分层帧率**：**背景 60fps 丝滑** + **角色 24fps 抽象线描** —— 两层**不需要同步**，这是刻意的视觉对比

## 角色层规格（**抽象优先**，用户明确要求）

- 单色线描，1–1.5px；**极简甚至零着色**（只留发丝高光 + 瞳孔一点蓝）
- **剪影可辨识 > 五官精细**；远景可只留四个特征：轮廓 + 呆毛 + 头鳍 + 鲸尾
- 好处：**耐看 · 省体积 · 且绕开了「等精绘排期」这个最大卡点**

## 角色版权约束（**必读**）

鲸鱼娘源自「明月」（作者 **商山无行**），协议 **CC BY-NC-SA 4.0** ⇒ **须署名 · 禁商用 · 衍生同协议**。
本项目为非商业开源插件，属可接受范畴；**将来若商业化必须重评**。

**官网 CSS 本地副本**（可直接读）：`artifacts/_ds-css/`（三份，共 85 KB）

**完整理由与逐项对照** → 见 `ART-DIRECTION-DEEPSEEK-20260920.md`（351 行，§0 专讲为什么要推翻旧版）

---

> **这是什么**：一份**自包含**的交接文档。读完它 + 它指向的三份权威文档，你就能接手工作，**不需要**访问 DSH 的记忆系统或聊天记录。
> **谁写的**：在 DSH（DeepSeek Harness）线上做这个插件的 agent。
> **给谁**：ZCode 线的 agent。
> **为什么交接**：DSH 线转入维护期；本轮工作（功能梳理 + 架构梳理 + 首页）需要**构建链 + 浏览器迭代能力**，ZCode 的 computer use 更强。


---

## §0 一句话启动指令（用户可直接把下面这段粘给 ZCode）

```
项目在 D:\dsh-auto-memory。先读 docs/internal/HANDOFF-TO-ZCODE-20260920.md（全文），
再读它 §2 列的三份权威文档。读完在会话里复述：①我在做什么 ②哪三个目录我可以写
③哪两个目录绝对不能碰 ④三路任务分别的交付物是什么。复述完再开工，不要提前动手。
```

---

## §1 你的工作边界（**先看这段，越界会造成真实损失**）

### ✅ 你可以写的地方

| 目录 | 用途 |
|---|---|
| `docs/` | 文档、功能清单、架构图、首页源码（含新建子目录） |
| `新目录（自选）` | 首页工程（如 `landing/`、`site/`）—— **见 §4-C 的方案** |

### ❌ 你**不能**碰的地方

| 目录 | 为什么 |
|---|---|
| **`lib/`** | **这是活的宿主代码**。本地 profile 用 `link:` 挂载，`lib/` 一改，正在运行的 DSH 宿主**立刻受影响**。而且它与 DSH 线的开发同步进行 —— 两边同时改会撞车。 |
| `tests/` | 与 `lib/` 绑定（146 个回归套件）。**不要动。** |
| `tools/` | 发布工具链。**不要动。** |
| `.dsh-memory/` | DSH 线的记忆数据。**只读，不要写。** |

### ⚠️ 一条硬约束（重要）

**插件（`lib/client.js`）不能加构建链。** 它是手写的 `__ModuleLoader__` bundle，只有一个文件、没有构建步骤、依赖只能是宿主 seed 表里的包。

**但首页不受这条约束** —— 首页是**独立静态站点**，可以有构建链（Astro/Vite/Three.js 随便用）。详见 §4-C。

---

## §2 权威文档索引（**按顺序读，不要跳**）

| # | 文档 | 讲什么 | 你必须从中得到什么 |
|---|---|---|---|
| **1** | **✅ `docs/internal/ART-DIRECTION-DEEPSEEK-20260920.md`**（351 行，2026-09-20） | **美术方向 v2 · DeepSeek 官网体系**：官网实测色板 / 圆角玻璃投影六档 / 按钮态 / **分层帧率** / **角色抽象化规格** / 鲸鱼娘版权链 | **首页就按这份做** —— 旧 `ART-DIRECTION-WIREFRAME.md` **已作废**（见文首横幅） |
| **2** | `docs/internal/PRE-FRONTEND-CHECKLIST-20260919.md`（705 行） | **排期权威视图**：§4 含 R1–R7 前端要求、§8 真实进度执行序、**§10 = 前端之后一起做的三项遗留** | 理解「前端项目的边界与已定事项」 |
| **3** | `docs/internal/DESIGN-OVERHAUL-PRE-RESEARCH.md`（285 行） | **大排期预研**：§2 现状硬数据（量化）、§4 三条线目标形态、§5 排期、**§8 六个拍板点** | **功能清单与架构梳理的起点** —— §2 已经有一批量化数据可直接引用 |

**索引文档（按需查，不必通读）**：

- `docs/internal/UI-INVENTORY-RAW.md` —— 设置项 8 组 / 85 键的原始清单
- `docs/UI-REFACTOR-PRE-RESEARCH.md` —— 界面重构预研
- `docs/internal/ISSUE10-FIX-EXECUTION-20260919.md` —— ⑩ 系列修复执行记录（下文的「变更」多出自此）
- `README.md` / `docs/USER-GUIDE.zh-CN.md` —— 面向用户的现有说明（**已知覆盖不全**，见 §4-A）

---

## §3 你在 09-14 之后缺失的变更（**你的记忆缺口在这里**）

你在 `~/.zcode/cli/memories/projects/dsh-auto-memory-4412cd98b2e33c51/memory/` 已有 31 份本项目记忆，**最新到 09-14**（含一份 `handoff-2026-09-11-from-dsh.md`）。
**09-14 之后 DSH 线做的事，你的记忆里没有 —— 以下是全量清单：**

### 3.1 上游 issue 全批闭环（GitHub 队列清零）

- **13 条 issue** 全部带针对性证据回复并关闭；**6 个 PR** squash-merge 进 `main`（`821a35d7` → `8da0d606`）。
- **仓库当前 open issue/PR 数 = 0。**
- 关键结论：**上游 issue 的根因清单可能整体过时** —— 它们多基于 `main@d816497(v3.0.0)` 撰写，而开发线经多轮重构后，其中「17 个 smoke 红」「python import 失效」等描述**均不成立**。⇒ 处理上游 issue 前**必须先实跑核验**，不可照单全修。

### 3.2 已交付的后端能力（**这些是首页可以宣传的素材**）

| 代号 | 能力 | 用户能看到什么 |
|---|---|---|
| **T4** | procedure memory **模型直写通路** | 模型可以自己写技能/流程（新增工具 `memory_procedure_pre`，模型工具数 16→17） |
| **R7** | 用户级硬性约束**可视编辑** | 用户能在面板里**自己增删改**「每轮必注入的硬约束」，有预览、删除二次确认 |
| **R1–R6** | 审批界面**可读性** | 技能审批不再只有英文枚举：中文化阶段 + **「为什么还不能晋升」用人话说**（含具体数字）+ 可展开预览真实步骤 |
| **#82** | 配置**原子写入 + 损坏隔离** | 保存中途崩溃不再无感重置全部配置；损坏文件被改名保留（`.corrupt-<ts>`） |
| **#86-3** | `DSH_HOME` 统一 | 7 处实现收敛到 1 处，跨平台路径不再打架 |
| **#84** | 诊断留痕 | 事件环丢弃有计数；unhandledRejection 有 `{count, firstAt, lastAt}` |
| **T10** | 机械流程切片**默认关闭** | 解耦开关 `hubMechanicalProcedureFeedEnabled`（默认 false） |

### 3.3 三条**可复用的工程纪律**（你写文档时也该遵守）

1. **fail-soft 必须留痕** —— 不能静默降级。本项目所有 catch 分支都要有可观察信号。
2. **变异测试必须真红** —— 把条件改成常量后，JS 三元**仍会渲染假分支**，字符串还在文件里 ⇒ 断言要**先定位分支再断言**，不能只查「字符串存在」。
3. **「PR merge 成功 ≠ 修复落地」** —— PR 常改**陈旧副本**（`lib/*.js` 而非宿主真正 import 的 `lib/*-pre.js`），必须另行移植。

---

## §4 三路任务书（**并行执行**）

> **用户明确要求：兵分三路并行。** 三路互不阻塞，可同时开工。

### 4-A · 第一路：**功能全量调查 → 三层功能清单**

**目标**：产出一份 `docs/internal/FEATURE-INVENTORY.md`，**同时满足用户视角与工程视角**。

**交付物规格（三层结构，缺一不可）**：

| 层 | 内容 | 粒度要求 |
|---|---|---|
| **L1 用户能力** | 「用户能用它做什么」 | 一句话一条，**面向宣传** |
| **L2 承载面** | 每个能力**现在住在哪**（页签/插槽/设置分组） | 表格，**面向前端搬家** |
| **L3 工程细节** | 全部实现细节 | **全量不删减** |

**⚠️ L3 的硬要求（用户原话：「所有的工程细节信息都要保存着」）**：

- 必须有：**17 个模型工具**（逐个列出签名与用途）、**49 条 HTTP 路由**、**85 个设置键**（8 组）、**6 处插槽注册**、数据文件清单、关键调用链
- **不许摘要化、不许「等等」省略、不许只写代表性的**
- **L3 的地位不是「附录」，是「存档」** —— 用户要自己决定哪些展示、哪些宣传、哪些留在后台

**建议做法**：
1. 先读 `docs/internal/DESIGN-OVERHAUL-PRE-RESEARCH.md` §2（已有量化数据可直接引用，别重做）
2. 再读 `docs/internal/UI-INVENTORY-RAW.md`（85 键清单）
3. `lib/` **只读**扫一遍，把工具/路由/插槽/设置项**机械枚举**出来（不要靠猜）
4. 补 L1/L2 的映射关系

**注意**：`lib/` 你**不能改，但可以读**。枚举时用 `grep`/`node` 脚本，不要手工抄。

### 4-B · 第二路：**架构与技术栈调查**

**目标**：产出 `docs/internal/ARCHITECTURE-FOR-ZCODE-20260920.md`，让后续任何 agent 能理解「这东西是怎么搭起来的」。

**必须覆盖**：

| 主题 | 要点 |
|---|---|
| **三层结构** | 宿主 `lib/index.js`（Node 侧，11460 行）／浏览器 `lib/client.js`（5701 行）／可选 Python 语义引擎 |
| **插槽系统** | 宿主的 `ctx.slots` API：`inject` / `register` 语义、**61 个插槽清单**、`one handle one scope` 约束 |
| **数据流** | 记忆文件 → 注入面 → 检出 → 检索；HTTP 路由的认证边界（**loopback-only，401 是预期**） |
| **双线结构** | pre 开发线（`D:\dsh-auto-memory`）vs REL 发布线（`D:\dsh_debug\_publish_dsh-auto-memory`） |
| **文件名约定** | 宿主真正 import 的是 `lib/*-pre.js`；同名的 `lib/*.js` 是**陈旧副本，不生效** |
| **测试体系** | 146 个 smoke 套件、`node tools/run-smoke.mjs` 用法、**前端仅 3 个断言组件行为**（已知缺口） |

**关键已知事实（别重新发现）**：插槽调查已在 DSH 线做过一轮，结论在 §6.3 与 `dsh-plugin-ecosystem-integration.md`（你自己的记忆里就有）。

### 4-C · 第三路：**开始构建首页**（标准最高的一路）

**目标**：**新首页从 0 做出来**，按 **`ART-DIRECTION-DEEPSEEK-20260920.md`** 的规格（**不是**旧线框稿版）。

**用户的两条明确指令**：

1. **旧 HTML 直接扔掉** —— `docs/landing/index.html`（1745 行 / 122 KB）**废弃**，从 0 重做。
2. **~~「就按一周之前的那个规划来做」~~ → 已更新为「主要采用 DeepSeek 主页的形式」** —— 即按 **`ART-DIRECTION-DEEPSEEK-20260920.md`**，并结合三个开源素材库。

**两个已拍板的前提**：

| 项 | 决定 |
|---|---|
| **托管方式** | **GitHub Pages**（放弃 htmlpreview） |
| **面板形态** | **保持液态玻璃不变** —— 线框稿风格**只用于首页**，不要试图改面板 |

**用户对抄素材的态度（原话）**：

> 「这个风险无所谓……你就大大方方让他抄就行了。**就是要这种优秀的美学风格和艺术风格，能多抄多少就抄多少。**」

**迭代方式**：用户明确说 **「先让模型改到自己满意」**，且 **ZCode 的 computer use 很好** —— 可以**一步一步截图、一步一步滚、一步一步迭代**。请用起来。

---

## §5 三路共用的硬纪律

### 5.1 用户级硬规则（**违反会造成真实损失**）

| # | 规则 | 为什么 |
|---|---|---|
| **1** | **绝不停止/重启 DSH web 宿主（3080 端口）** | 一旦关闭，**用户的会话思维链会直接断开卡死**。宿主只能由用户手动重启。 |
| **2** | **绝不无差别杀 node 进程** | DSH harness 与插件宿主**都跑在 node 上**。`Get-Process node \| Stop-Process` 会连带杀死正在运行的会话（2026-09-14 实际发生过一次）。 |
| **3** | **不碰 `lib/`** | 见 §1。 |
| **4** | **改 DSH 配置前必须先备份** | 避免块级结构丢失。 |

### 5.2 本仓工程纪律

| 纪律 | 说明 |
|---|---|
| **文件用 CRLF，无 BOM** | 本仓全部源文件是 CRLF。改动后校验：`LFonly` 必须为 0。 |
| **大文件分块写入** | 一次性生成整个大文件会被拒绝。 |
| **`edit` 用 `replace_all` 后必须核对命中数** | 替换范围**包含同一次编辑新加入的代码块** —— 若新块内文本与待替换文本相同，会一起替换（曾造成辅助函数自递归）。 |
| **fail-soft 必须留痕** | 不得静默降级。 |
| **别用固定字符窗口做断言** | 曾因 `SRC.slice(idx, idx+900)` 越界到相邻函数而误判。要**用花括号配对精确取函数体**。 |

### 5.3 与 DSH 线的协作约定

- **`lib/` 归 DSH 线，`docs/` 与首页归 ZCode 线。** 各改各的，不要交叉。
- 若你发现**必须改 `lib/`** 才能完成的任务：**不要改**，写进文档的「待 DSH 线处理」清单。
- 你把交付物写到仓库里，DSH 线**能读到** —— 两边通过**文件**同步，不通过聊天。

---

## §6 三个素材库（已取证）

| 仓库 | 语言/栈 | ⭐ | License | 体积 | 备注 |
|---|---|---|---|---|---|
| **[JesseLee-CN/rhinelab-blog-theme](https://github.com/JesseLee-CN/rhinelab-blog-theme)** | Astro + Three.js + TS + Pagefind | 5 | **MIT** | 55.8 MB | **同作者配套**：自述「含 RhineLabUI 三维档案终端 `/lab/`（脱敏开源版）」 |
| **[LBEILC/RhineLabUI](https://github.com/LBEILC/RhineLabUI)** | TypeScript + Three.js | **565** | **MIT** | 133.5 MB | 有线上 demo：<https://rhine-lab-ui.vercel.app> |
| **[Ulchemist/arknights-motion-library](https://github.com/Ulchemist/arknights-motion-library)** | JavaScript | 2 | **NOASSERTION** | 25.9 MB | 见下方提醒 |

### 6.1 用户对复用的态度（已授权）

> 「这个风险无所谓，我现在这个东西，几个人就能用啊，而且我现在用的也是开源库，**你就大大方方让他抄就行了**。**就是要这种优秀的美学风格和艺术风格，能多抄多少就抄多少。**」

⇒ **以美学风格复用为主**（配色/排版/动效/三维交互的**做法与观感**），这是最有价值的部分。

### 6.2 事实性提醒（知情即可，不构成阻碍）

- `arknights-motion-library` 的 License 显示为 **NOASSERTION** —— GitHub **未能识别出标准许可证**，意味着复用权利**不明确**，建议点进仓库确认作者实际声明。
- 名字含 **Arknights（明日方舟）**：**代码许可 ≠ 美术资源许可**。游戏角色素材的版权归属游戏方，这类「动作库」通常复用其**动作数据格式/播放器实现**而非原画。

### 6.3 一个关键技术结论（**决定复用可行性**）

> **首页与插件是两套约束，互不影响。**

| | 插件（`lib/client.js`） | **首页（独立站点）** |
|---|---|---|
| 运行环境 | 宿主 GUI 内，被 `__ModuleLoader__` 加载 | **独立网页，浏览器直接打开** |
| 依赖 | ❌ 只能用宿主 seed 表提供的包 | **✅ 随便用** |
| 构建步骤 | ❌ **没有**，手写单文件 | **✅ 可以有**（Astro / Vite / TS 随便） |
| 产物 | 随 npm 包分发 | **GitHub Pages 托管构建产物（标准做法）** |

⇒ **三个素材库都需要构建链（Astro / TypeScript），这完全不触碰插件约束。** 你可以放手用。

### 6.4 「怎么 combine」的建议方向（**供参考，最终由你做决定**）

| 从哪来 | 拿什么 |
|---|---|
| **ART-DIRECTION-DEEPSEEK-20260920.md** | **骨架与规格**：官网实测色板（品牌蓝 `#4d6bfe` / 暗底 `#0a0a0a`）、圆角玻璃投影六档、按钮态、**分层帧率（背景 60fps + 角色 24fps）**、**角色抽象化规格** |
| **rhinelab-blog-theme** | **Astro 站点结构 + 三维终端页的做法**（它本身就是一个含 `/lab/` 的博客主题，与首页定位最接近） |
| **RhineLabUI** | **三维档案界面的交互范式与视觉语言**（565 stars，最成熟） |
| **arknights-motion-library** | **动效/序列帧播放的实现思路**（对应你要的 24fps 动效） |

**✅ 原「美学冲突」已消失**：旧版 §2.4 禁玻璃/圆角/投影，与 RhineLab 系深色发光玻璃**冲突**；**改走 DeepSeek 官网体系后，两边调性一致**（都用玻璃 + 圆角 + 暗色高科技），可放心 combine。
⇒ **这两套美学的调性不同**，combine 时需要一个明确取舍。**建议：以线框稿的「克制 + 工程图」为骨架，把 RhineLab 的动效与三维交互作为「局部亮点」引入**，而不是整体转向深色霓虹。

---

## §7 完成判据（自我验收）

| 路 | 判据 |
|---|---|
| **4-A** | `FEATURE-INVENTORY.md` 三层齐全；**L3 覆盖 17 工具 / 49 路由 / 85 设置键 / 6 插槽，无「等等」省略** |
| **4-B** | `ARCHITECTURE-FOR-ZCODE-*.md` 能让**没见过这个项目的 agent** 理解整体结构 |
| **4-C** | 首页可本地打开并正常渲染；**有截图证据**；遵循 ART-DIRECTION 的色板与禁止项；**已考虑 GitHub Pages 部署方式** |

---

## §8 你现在就该做的三件事（按顺序）

1. **通读本文档 + §2 的三份权威文档**（不要跳）
2. **在会话里复述**：①我在做什么 ②能写哪三个目录 ③不能碰哪两个目录 ④三路交付物分别是什么 —— **复述完再动手**
3. **三路并行开工**：先派调查（4-A / 4-B），同时自己起手首页（4-C）

> **最后一句**：这份文档是**自包含**的。你不需要 DSH 的记忆系统。但如果你想知道「为什么当初这么决定」，`docs/internal/` 下有完整的决策记录（`PRE-FRONTEND-CHECKLIST-20260919.md` §8 有真实进度执行序）。