# 未实现能力与原因（NOT-DONE）

本文件记录**评估过但决定不做**的能力，以及评估依据。目的是避免同一问题被反复提出，
也避免后来者以为「只是没来得及做」。

判定口径：不是「做不了」，而是「收益 / 成本 / 与现有能力重叠」三者权衡后不做。
每条都写明：想要什么、为什么不做、未来若做该怎么做。

---

## 1. 预览页截图（PNG）

**想要什么**：把 `preview` 生成的页面截成 PNG，供 README 配图与截图声明文件使用。

**评估过三条路**：

| 方案 | 结论 | 依据 |
| --- | --- | --- |
| 纯内联 JS 调浏览器原生截图 | **不可行** | 浏览器没有「页面自截」API；`navigator.mediaDevices.getDisplayMedia()` 需要用户手势 + 授权，拿到的是屏幕/窗口而非页面精确渲染，无头自动化不可用 |
| html2canvas 内联（DOM → canvas → `toDataURL()`） | 可行但失真 | 库体积约 200KB 需内联；跨域图片会空白，`backdrop-filter`、阴影、滤镜、部分 CSS 失真，字体需内联 |
| 服务端截（chrome `--headless --screenshot`） | 可行 | 依赖本机 chrome 内核与用户态库；`--screenshot` 只能截视口，整页需要 CDP WebSocket 或超大 `--window-size` 近似 |

**决定不做**，原因：

1. **与现有能力重叠**：宿主已有 browser 插件（`browser_screenshot` 支持视口/整页/保存路径），
   截图这件事已经有更保真、更完整的实现，插件内再包一层属于重复建设。
2. **两条可行路各有硬伤**：html2canvas 失真（README 配图不够用）；服务端截依赖本机浏览器内核，
   换机器没装就用不了，而本机 playwright 目前是坏软链（指向已不存在的 `.pnpm` 目录），
   无法作为「探测到就用」的稳定依赖。
3. **维护成本与收益不匹配**：截图需求集中在「写 README 时截几张图」这种低频场景，
   用 browser 插件按需截即可，不需要常驻能力。

**未来若做**（形态已评估）：`preview action=shot`，参数 `url|file`、`viewport`、`fullPage`、`outDir`，
内核路径全部环境变量可覆盖（`SHOT_CHROME` / `SHOT_CHROMELIBS` / `SHOT_FONTS`），
产物默认 `assets/screenshots/*.png`；`fullPage` 需要 CDP，不能用 CLI 凑。

---

## 2. 自包含快照模式（离线单文件）

**想要什么**：抓一次真实后端响应内嵌进单文件 HTML，双击 `file://` 即可查看（离线、无 CORS、无服务）。

**评估**：

- 与 `preview serve --backend` 是**两种不同形态**：serve 是实时反代（最贴近真实），
  快照是冻结一份可归档/可分享的静态页。
- 实现需要「知道页面会调用哪些 `/api/*` 并拿到响应」：要么用浏览器拦截网络（当前无可用
  playwright），要么在 serve 层加录制模式（`/api/*` 代理时把请求与响应存成 JSON），
  再由快照动作生成内嵌 `fetch` 替换的 HTML。
- 已知坑：预览页的 i18n locale mock 是 `(key) => key`，直接内嵌会让界面显示 key 而不是文案，
  必须按真实 locale 注入。

**决定不做**，原因：

1. **场景重叠**：`serve --backend` 已覆盖「接真后端看效果」的主场景；快照是额外的归档形态，
   当前没有明确的归档/分享需求驱动。
2. **实现成本高且易腐**：录制 + 内嵌 + fetch 替换 + locale 注入，任何一环与页面实现漂移都会
   产生「看起来正常但数据是假的」的假象，维护成本高于收益。
3. **离线可看有更简单的替代**：单文件 HTML 本身就内联了 React UMD 与插件 client.js，
   不带后端数据时已经能离线打开看界面骨架。

**未来若做**：`preview action=snapshot`，先 `serve --record` 录一轮 `/api/*` 响应到
`.preview/<file>.snapshot.json`，再生成内嵌该 JSON 与 fetch 替换的 HTML；locale 必须按真实注入。

---

## 3. shell 可调用的启动器

**想要什么**：不经过 AI 工具面，命令行/CI 也能起 mini 宿主或预览服务。

**决定不做**，原因：

1. **工具面已覆盖**：`minihost` 与 `preview` 的启动/停止/状态都已经是工具参数，
   命令行场景可以直接调插件入口，不需要额外脚本。
2. **多一份脚本就多一份漂移**：脚本要自己解析参数、定位插件根、维护 PID 台账，
   与工具层重复；一旦工具层参数变化，脚本就会落后。
3. **没有明确使用方**：当前没有「非 AI 场景定期起服务」的实际需求。

---

## 4. spec 多挂载点 mounts[]

**想要什么**：一个预览页同时渲染多个插槽（如 `settings.section` + `settings.plugin.item`），
每项可带自己的 props，便于多槽插件一次看完。

**现状**：`preview gen` 只挂一个组件（按优先级挑 `settings.section` > `settings.plugin.item` > `sidebar`）。
单槽插件够用；多槽插件目前只能分多次生成。

**为什么暂缓**：要改 gen 的挂载模型（每个 mount 一个容器 + 各自 props 注入 + 布局），
而当前实践里（dsh-session-migrate、dsh-skill-scoreboard 等）都只有一个主槽；
等真有多槽需求再做，避免为未出现的场景增加挂载复杂度。

**若做**：spec 增加 `mounts: [{ slot, props, title }]`，gen 为每项生成一个 `<section data-slot>`，
`post` 阶段逐个 `createRoot().render()`；返回里给每个 mount 的渲染状态（是否捕获到组件）。

---

## 修改记录

| 版本 | 变更 |
| --- | --- |
| 0.1.26 | 新增第 4 项：spec 多挂载点 `mounts[]`（当前单槽够用，暂缓）。 |
| 0.1.5 | 首版：记录截图、自包含快照、shell 启动器三项的评估结论与不做原因。 |