# 前端共创计划 · dsh-auto-memory

> **一句话**：这个插件的前端（记忆面板 12 页签 + 设置页 8 分组）目前是「能用」的水平，
> 我们知道它离「好用」还有距离。**视觉与交互的改进，交给社区。**
> 你有想法，提 PR；我们提供完整的落点地图、约束清单和一个不碰后端的沙盒。

---

## 一、为什么把前端交给社区

三条实话：

1. **功能已经稳定，前端是短板。** 后端 17 个模型工具、49 条路由、98 个设置键都在跑，
   但记忆面板的信息密度高、布局拥挤，用户第一眼常常不知道该看哪里。
2. **前端的取舍没有唯一答案。** 「唤起回顾该怎么展示」「12 个页签该不该合并」
   这类问题取决于你自己的工作方式——而你们的工作方式比我们更丰富。
3. **改前端的边际成本低于改后端。** 前端零构建、单文件、纯 ESM，
   你不需要装任何东西就能跑起来改。

我们同时公开了**落点地图**（每个能力现在住在哪一行）和**视觉远期规划**（哪些不做、为什么），
避免你花了力气做出来的东西因为「不在规划里」被拒。

---

## 二、你可以改什么（三档）

### 🟢 A 档 · 随时欢迎，几乎不会被拒

| 方向 | 具体例子 |
|---|---|
| **信息层级** | 12 页签分组/折叠/重排；概览页只留最关键的三行 |
| **可读性** | 长列表虚拟滚动；日志页签的行距与等宽字体；中文断行 |
| **交互细节** | 键盘导航；Esc/焦点管理；加载态与空态；错误提示人话化 |
| **一致性** | 组件间距/圆角/字号收敛到设计令牌（见 §5） |
| **无障碍** | 对比度、focus-visible、aria-label、屏幕阅读器路径 |
| **文案** | 设置项说明从「参数名」改成人话 |

### 🟡 B 档 · 欢迎，但请先开 issue 对齐

| 方向 | 为什么需要先对齐 |
|---|---|
| **页签合并/拆分** | 会改变所有人的肌肉记忆，属于破坏性变更 |
| **新增面板内视图** | 需要确认数据源已有路由支持（见 §4 路由表） |
| **动效体系** | 需要与「背景顺滑 / 角色克制」的分层帧率原则一致 |
| **亮色主题补全** | 令牌已备（`#f9f8f8`），但需要整套校验 |

### 🔴 C 档 · 请不要做

| 方向 | 原因 |
|---|---|
| **改动注入语义** | 注入时机/预算/分层措辞是引擎契约，前端改不了也不该改 |
| **绕过 `saveConfigPatch` 直写配置** | 它是唯一写入出口（含校验与原子落盘），绕过会破坏配置完整性 |
| **新增运行时依赖** | 插件受单文件/无构建约束，不允许引入构建链或 npm 运行时依赖 |
| **改 `lib/*-pre.js` 的写入路径** | 这些文件的改动属于后端，需走另一套评审 |
| **提交后端 bug 修到前端 PR 里** | 请分开提，便于独立 review 与回滚 |

---

## 三、落点地图（你改的东西住在哪）

### 3.1 六处插槽（插件 UI 的物理入口，全在 `lib/client.js`）

| # | 插槽 | 承载 | 定义行 |
|---|---|---|---|
| 1 | `sidebar.footer.action` | 侧栏入口按钮 | `client.js:5664` |
| 2 | `shell.overlay` | 浮层面板（12 页签） | `client.js:5667` |
| 3 | `shell.overlay` | 7 种弹窗 | `client.js:5670` |
| 4 | `shell.overlay` | 自动接续确认卡 | `client.js:5673` |
| 5 | `settings.section` | 设置页分区「自动记忆」 | `client.js:5676` |
| 6 | `conversation.view` | 会话页顶栏白板看板 | `client.js:5683` |

### 3.2 12 页签 → 组件 → 数据源

| 页签 | 组件（定义行） | 读 | 写 |
|---|---|---|---|
| 概览 | OverviewTab（2315）+ GreetingCard（2115） | `/state` `/workspaces` `/greet` | `/reflect-auto` |
| 日志 | LogsTab（2537）**+ 硬约束编辑器**（2590） | `/list` `/file` | `/rules/apply` |
| 唤起回顾 | RefineTab（2413） | `/shadow-recent` | `/review-feedback` |
| 记忆中枢 | MemoryHubTab（2724） | `/memory-hub` | `/memory-hub` |
| 存储管理 | StorageTab（2850） | `/storage-manage` | `/storage-manage` `/scan-dirty` |
| 笔记 | NotesTab（2936） | `/state` | `/note` |
| 白板 | PlanTab（3111） | `/handoff-state` | `/handoff-continue` |
| 反思 | ReflectionsTab（3364） | `/file` | `/reflect` |
| 接续 | ConnectTab（3764） | `/external` `/external-view` | `/external-import` `/external-remove` |
| 日历 | CalendarTab（3594） | `/calendar` | `/calendar` |
| 检索 | SearchTab（3420） | — | `/recall` `/smart-recall` |
| 工作区 | WorkspaceTab（3543） | `/workspaces` | — |

面板外壳另有：`/config` `/notices` `/update-check` `/debug`；看板另有 `/kanban-board`。

### 3.3 设置页 8 分组（60 个可写键，共 98 个配置键）

| 分组 | 键数 | 内容 |
|---|---|---|
| 自动记忆引擎 | 9 | 联想开关/锚点/冷却/候选策略/思维链观察 |
| 记忆中枢 | 8 | 情节与技能的晋升门限、高风险审批 |
| 外观 | 2 | 欢迎向导、语言 |
| 存储 | 3+ | 用户级/项目级/记忆根目录 |
| 记忆窗口 | 10 | 注入预算、容量、排除源、快照节奏 |
| 自动化 | 17 | 自动固化、无人值守、时段总结、定时班 |
| 上下文管理 | 11 | 交接、自动接续、水位、看板模式、子代理回收 |
| 维护 | — | 版本/更新/调试中心（只读） |

**写入唯一出口**：`saveConfigPatch`（`client.js:999-1200`）→ `POST /config`。**不要绕过它。**

---

## 四、约束清单（提交前请自查）

### 4.1 硬约束

- [ ] **零新增依赖**：不引 React/Vue/构建链/任何 npm 运行时包。现有 UI 是组件库内置原语 + 手写 CSS。
- [ ] **配置写入走 `saveConfigPatch`**：不得直写 `/config` 或本地存储绕开校验。
- [ ] **不改注入语义**：不碰任何决定「什么时候注入、注入多少」的逻辑。
- [ ] **失败要留痕**：新增的 fail-soft 分支必须产生**可观察信号**（面板可见或日志留痕），禁止静默吞异常。
- [ ] **开关解耦**：单个开关不得顺带改变其它功能的行为。
- [ ] **双语**：所有面向用户的文案必须同时给中文与英文（现有 `data-en` / 中文源文模式）。
- [ ] **不引入授权待清的资产**：字体/图标/图片必须自带许可或使用系统字体。

### 4.2 自查清单

- [ ] 本地能跑起来（见 §5）
- [ ] 键盘可达：Tab 能走到，Esc 能退出，焦点可见
- [ ] 空态 / 加载态 / 错误态 都有处理
- [ ] 长内容不溢出（工作区名可能很长、日志可能几千行）
- [ ] 改设置后**界面立刻回显**（写盘成功但界面没变 = 功能坏了，这是明确的项目红线）
- [ ] 在窄窗口（≤640px）下不横向滚动

---

## 五、怎么跑起来改（零安装）

插件是**纯 ESM 单文件 + 手写 CSS，没有构建步骤**：

```bash
git clone https://github.com/Aik358/dsh-auto-memory.git
cd dsh-auto-memory
# 把 profile 指向你的开发树（link: 挂载）
# 然后重启 DSH，侧栏就会出现「记忆」入口
```

改 `lib/client.js` / `lib/client-*.js` 后刷新页面即可看到效果。

**回归自检**（改完请跑，PR 里贴上结果）：

```bash
node tools/run-smoke.mjs --timeout=90000 \
  --exclude=-live- --exclude=m79-feature-v2-pre \
  --exclude=m710-fv2-emit-pre --exclude=c4-fresh-install-pre
```

期望：**PASS 141 / FAIL 0 / TIMEOUT 0**（并行 ×4，约 44 秒）。

---

## 六、已公开的设计文献（动笔前先读）

| 文档 | 内容 |
|---|---|
| `docs/internal/FEATURE-INVENTORY.md` | 三层功能全量清单：L1 39 条用户能力 / L2 承载面 / L3 工程细节（含全部 17 工具、49 路由、98 键） |
| `docs/internal/ARCHITECTURE-FOR-ZCODE-20260920.md` | 面向新开发者的结构文档，61 个模块职责表 |
| `docs/internal/ART-DIRECTION-DEEPSEEK-20260920.md` | 现行美术方向（DeepSeek 官网体系） |
| `.dsh/skills/transitions-motion/` | 43 个生产级动效的完整源码与技法文档（含 motion token 刻度） |
| `site/` | 项目主页（纯静态，可直接本地打开） |

---

## 七、视觉远期规划（哪些暂时不做，为什么）

以下方向**已经论证过可行性，但明确排在远期**。原因是它们属于「重投入、收益不确定」，
在当前阶段不适合占用主线资源。**如果你愿意做，我们欢迎——前提是先开 issue 对齐范围。**

| 方向 | 结论 | 阻塞点 |
|---|---|---|
| **项目主页三维档案终端** | 技术已验证可行（Three.js 阵列 + 逐帧开场，本机跑通） | ① 参考项目的 3D 模型受 MIT 覆盖范围限制，**不可直接沿用**，需自建或程序化几何；② 配色需从暖灰底整体重标定为深底+品牌蓝（含光照/雾/AO）；③ 40 份档案正文需重写 |
| **角色层（鲸鱼娘）** | 抽象线描已产出（Ark9 生图 + 本地亮度键控） | 三维场景内使用需要模型，非 2D 位图；2D 图层叠加是可行的降级方案 |
| **亮色主题** | 令牌已备（`#f9f8f8`） | 需整套对比度与光照校验 |
| **面板整体重排** | 需要先有特征化测试 | 前端目前回归网极薄（146 个套件里仅 3 个断言组件行为） |

---

## 八、怎么提 PR

1. **先开 issue** 说明你想改什么、为什么、大概怎么做（B 档方向必须先走这步）
2. Fork → 建分支 → 改 → 跑 §5 回归 → 提 PR
3. PR 描述里请写：**改了什么 / 为什么 / 怎么验证 / 截图或录屏**
4. 我们会用同一份 §4 约束清单 review
5. 后端改动请单独提 PR，不要混在前端 PR 里

**许可**：本插件代码以 **BSD-3-Clause** 发布。你的贡献将以同一许可合入。
页脚的角色设定署名（CC BY-NC-SA 4.0）与上游项目署名（MIT）**请勿删除或改写**。