dsh-plugin-deck-studio 0.2.10 → 0.2.13

package/lib/data-dir.js

@@ -0,0 +1,288 @@
+/**
+ * 数据目录（dataRoot / projectsRoot）解析与指针文件（P0）。
+ *
+ * 口径（规格 `.deck-assistant-scratch/deckline-data-dir-spec.md` §1 / §4）：
+ * - 解析优先级：env `DSH_DECK_DATA_ROOT` > 指针文件 `$DSH_HOME/deckline/location.json`
+ *   > profile patch `deck-studio.config.dataRoot` > 默认 `$DSH_HOME/deckline`；
+ * - 每次解析都把**命中来源**（env / pointer / profile / default）带出去，设置页与黄条直接显示；
+ * - 指针文件位置固定，不随 dataRoot 配置移动（否则自指）；写入 0600、不含任何 key；
+ * - env 覆盖时指针只读：写了也不生效，界面必须说明「由环境变量 … 指定（只读）」。
+ *
+ * 本模块只做「解析 + 读写指针」，不碰 deck 内容；不匹配检测在 lib/data-dir-detect.js。
+ * @module dsh-plugin-deck-studio/data-dir
+ */
+
+import { accessSync, chmodSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { defaultDataRoot, expandHome } from "./config.js";
+
+/** 覆盖 dataRoot 的环境变量名（优先级最高）。 */
+export const DATA_DIR_ENV = "DSH_DECK_DATA_ROOT";
+/** 覆盖 projectsRoot 的环境变量名。 */
+export const PROJECTS_ROOT_ENV = "DSH_DECK_PROJECTS_ROOT";
+/** 指针文件名（固定住在 `$DSH_HOME/deckline/`，不随 dataRoot 移动）。 */
+export const LOCATION_FILE_NAME = "location.json";
+/** 指针文件格式版本。 */
+export const LOCATION_VERSION = 1;
+
+/** 解析命中来源（顺序 = 优先级）。 */
+export const DATA_DIR_SOURCES = ["env", "pointer", "profile", "default"];
+
+/** 命中来源的人话标签（设置页第一行 / 诊断信息共用）。 */
+export const DATA_DIR_SOURCE_LABELS = {
+  env: `环境变量 ${DATA_DIR_ENV}`,
+  pointer: "指针文件 location.json",
+  profile: "profile patch（deck-studio.config.dataRoot）",
+  default: "默认 $DSH_HOME/deckline",
+};
+
+/** 每本 deck 的数据状态标签（检测模块与 UI 共用一张词表）。 */
+export const DECK_DATA_STATUS_LABELS = {
+  ok: "正常",
+  mismatch: "不在这",
+  partial: "正文丢失",
+  absent: "尚未初始化",
+};
+
+/**
+ * 规范化用户输入的目录：展开 `~`、去首尾空白与尾部斜杠。
+ * **不**把相对路径悄悄 resolve 成绝对路径——写指针时要求绝对路径，相对路径直接报错。
+ * @param {unknown} value
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function normalizeDirPath(value, env = process.env) {
+  const expanded = expandHome(String(value ?? "").trim(), env).trim();
+  if (!expanded) return "";
+  return expanded.length > 1 ? expanded.replace(/[/\\]+$/, "") : expanded;
+}
+
+/** `$DSH_HOME`（未配置时 `~/.dsh`）。 */
+export function dshHomeOf(env = process.env) {
+  return normalizeDirPath(env.DSH_HOME || "~/.dsh", env);
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 目录可写？目录还不存在时看最近的已存在祖先（不替你建目录）。
+ * @param {string} path
+ */
+export function dirWritable(path) {
+  const target = String(path ?? "").trim();
+  if (!target) return false;
+  let dir = target;
+  while (!existsSync(dir)) {
+    const parent = dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+  try {
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 一个目录的三个事实（自检面板 / 首次引导校验共用）。
+ * @param {unknown} path
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function dirFacts(path, env = process.env) {
+  const value = normalizeDirPath(path, env);
+  return { value, exists: value ? isDirectory(value) : false, writable: dirWritable(value) };
+}
+
+/** 指针文件的固定位置：`<DSH_HOME>/deckline/location.json`。 */
+export function locationFileOf(env = process.env) {
+  return join(defaultDataRoot(env), LOCATION_FILE_NAME);
+}
+
+/**
+ * 读指针文件。坏文件不抛：返回 `found:true, error:…`，让界面能说清「文件坏了」而不是「没有」。
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function readLocationPointer(env = process.env) {
+  const path = locationFileOf(env);
+  const base = { found: false, path, version: null, dataRoot: "", projectsRoot: "", setBy: "", updatedAt: "", error: null };
+  if (!existsSync(path)) return base;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    return {
+      found: true,
+      path,
+      version: Number.isFinite(Number(raw?.version)) ? Number(raw.version) : null,
+      dataRoot: normalizeDirPath(raw?.dataRoot ?? "", env),
+      projectsRoot: normalizeDirPath(raw?.projectsRoot ?? "", env),
+      setBy: typeof raw?.setBy === "string" ? raw.setBy.trim() : "",
+      updatedAt: typeof raw?.updatedAt === "string" ? raw.updatedAt.trim() : "",
+      error: null,
+    };
+  } catch (error) {
+    return { ...base, found: true, error: `location.json 解析失败：${error?.message ?? error}` };
+  }
+}
+
+/**
+ * 指针文件所在目录能不能写（首次引导 / 设置页在写之前先问，避免「点了才发现不行」）。
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function pointerWritable(env = process.env) {
+  const file = locationFileOf(env);
+  let dir = dirname(file);
+  const missing = [];
+  while (!existsSync(dir)) {
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    missing.unshift(dir);
+    dir = parent;
+  }
+  const writable = dirWritable(dir);
+  return {
+    path: file,
+    dir,
+    dirExists: existsSync(dirname(file)),
+    writable,
+    missing,
+    error: writable ? null : `目录不可写：${dir}`,
+  };
+}
+
+/**
+ * 写指针文件（0600、不含任何 key）。
+ *
+ * 只改指针、不改 profile patch：这条路径不需要重启 DSH 就生效。
+ * env 覆盖时**不允许**写（写了也不生效，只会让人困惑）；调用方先看 `resolveDataDir().envOverride.active`。
+ *
+ * @param {{dataRoot: unknown, projectsRoot?: unknown, setBy?: string}} input
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {Date} [now]
+ */
+export function writeLocationPointer(input = {}, env = process.env, now = new Date()) {
+  const dataRoot = normalizeDirPath(input.dataRoot, env);
+  if (!dataRoot) throw new Error("dataRoot 不能为空");
+  if (!isAbsolute(dataRoot)) throw new Error(`数据目录必须是绝对路径：${dataRoot}`);
+  const projectsRoot = normalizeDirPath(input.projectsRoot, env);
+  if (projectsRoot && !isAbsolute(projectsRoot)) throw new Error(`projectsRoot 必须是绝对路径：${projectsRoot}`);
+  const setBy = String(input.setBy ?? "settings").trim() || "settings";
+  const pointer = { version: LOCATION_VERSION, dataRoot, projectsRoot, setBy, updatedAt: now.toISOString() };
+  const path = locationFileOf(env);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(pointer, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  // mode 只对新建文件生效；已存在的文件显式收紧一次（失败不静默放宽，也不因此让写入失败）。
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    /* Windows / 特殊文件系统不支持 chmod */
+  }
+  return { path, pointer };
+}
+
+/** 删掉指针文件（切换回滚用；文件不存在不报错）。 */
+export function deleteLocationPointer(env = process.env) {
+  const path = locationFileOf(env);
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    /* 权限不足等：把结果交给上层提示，不在这里编造「已删除」 */
+  }
+  return { path, removed: !existsSync(path) };
+}
+
+/**
+ * 把指针文件回滚成 `snapshot`（= `readLocationPointer(env)` 的原样快照）。
+ * 切换失败时不能让指针停在新目录上，否则重启后直接进错目录。
+ */
+export function restoreLocationPointer(snapshot, env = process.env) {
+  if (snapshot?.found) {
+    return writeLocationPointer({ dataRoot: snapshot.dataRoot, projectsRoot: snapshot.projectsRoot ?? "", setBy: snapshot.setBy ?? "rollback" }, env);
+  }
+  return deleteLocationPointer(env);
+}
+
+/** 统一的「根对象」形状：`{value, source, envOverridden, writable, exists}`。 */
+function rootFact(value, source, env) {
+  const facts = dirFacts(value, env);
+  return { value: facts.value, source, envOverridden: source === "env", writable: facts.writable, exists: facts.exists };
+}
+
+/** `<dataRoot>/decks` 是否为空（不存在也算空）。 */
+function decksDirEmpty(dataRoot) {
+  const dir = join(dataRoot, "decks");
+  if (!existsSync(dir)) return true;
+  try {
+    return readdirSync(dir).length === 0;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * 解析 dataRoot / projectsRoot 与命中来源（唯一入口，纯读取）。
+ *
+ * @param {{env?: NodeJS.ProcessEnv, profileDataRoot?: string, profileProjectsRoot?: string, logger?: {warn?: Function}}} [input]
+ */
+/** 冲突 warn 只打一次：5s 轮询与多次重建服务都不重复刷屏。 */
+let warnedDataRootConflict = false;
+let warnedProjectsRootConflict = false;
+
+export function resolveDataDir({ env = process.env, profileDataRoot = "", profileProjectsRoot = "", logger = null } = {}) {
+  const envDataRoot = normalizeDirPath(env[DATA_DIR_ENV] ?? "", env);
+  const envProjectsRoot = normalizeDirPath(env[PROJECTS_ROOT_ENV] ?? "", env);
+  const profileRoot = normalizeDirPath(profileDataRoot, env);
+  const profileProjects = normalizeDirPath(profileProjectsRoot, env);
+  const warn = typeof logger?.warn === "function" ? logger.warn.bind(logger) : null;
+  // env 赢 profile 是规格要求，但会让「两处都配过」的老用户静默换目录：留一条 warn 痕迹，只打一次。
+  if (warn && envDataRoot && profileRoot && envDataRoot !== profileRoot && !warnedDataRootConflict) {
+    warnedDataRootConflict = true;
+    warn(`dataRoot 同时由环境变量与 profile 配置指定，已按 env 生效（env=${envDataRoot}，profile=${profileRoot}）`);
+  }
+  if (warn && envProjectsRoot && profileProjects && envProjectsRoot !== profileProjects && !warnedProjectsRootConflict) {
+    warnedProjectsRootConflict = true;
+    warn(`projectsRoot 同时由环境变量与 profile 配置指定，已按 env 生效（env=${envProjectsRoot}，profile=${profileProjects}）`);
+  }
+  const pointer = readLocationPointer(env);
+  // 坏指针 / 指向相对路径的指针不当依据：否则数据根会被悄悄换成空值。
+  const pointerDataRoot = pointer.error || !isAbsolute(pointer.dataRoot) ? "" : pointer.dataRoot;
+  const pointerProjectsRoot = pointer.error || !isAbsolute(pointer.projectsRoot) ? "" : pointer.projectsRoot;
+
+  const dataRoot = envDataRoot || pointerDataRoot || profileRoot || normalizeDirPath(defaultDataRoot(env), env);
+  const source = envDataRoot ? "env" : pointerDataRoot ? "pointer" : profileRoot ? "profile" : "default";
+  const projectsSource = envProjectsRoot ? "env" : pointerProjectsRoot ? "pointer" : profileProjects ? "profile" : "default";
+  const projectsRootValue = envProjectsRoot || pointerProjectsRoot || profileProjects;
+
+  const dataRootFact = rootFact(dataRoot, source, env);
+  const projectsRootFact = projectsRootValue
+    ? rootFact(projectsRootValue, projectsSource, env)
+    // 空串 = 沿用旧口径 `<dataRoot>/projects/<deckId>/source`：可写性跟 dataRoot 走，不伪造一个不存在的目录。
+    : { value: "", source: "default", envOverridden: false, writable: dataRootFact.writable, exists: dataRootFact.exists };
+
+  return {
+    dataRoot: dataRootFact,
+    projectsRoot: { ...projectsRootFact, effective: projectsRootValue || join(dataRootFact.value, "projects") },
+    dshHome: rootFact(dshHomeOf(env), env.DSH_HOME ? "env" : "default", env),
+    pointerFile: {
+      path: pointer.path,
+      exists: pointer.found,
+      error: pointer.error,
+      setBy: pointer.setBy,
+      updatedAt: pointer.updatedAt,
+      version: pointer.version,
+    },
+    envOverride: { active: source === "env", name: DATA_DIR_ENV },
+    // 真·首次：这个数据目录里还没有任何 deck、没存过出图设置、也没有指针文件（规格 §3 触发条件）。
+    firstRun: decksDirEmpty(dataRootFact.value) && !existsSync(join(dataRootFact.value, "render-settings.json")) && !pointer.found,
+    processCwd: process.cwd(),
+    sourceLabel: DATA_DIR_SOURCE_LABELS[source] ?? source,
+    profileDataRoot: profileRoot,
+    profileProjectsRoot: profileProjects,
+    defaults: { dataRoot: normalizeDirPath(defaultDataRoot(env), env) },
+  };
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "dsh-plugin-deck-studio",
-  "version": "0.2.10",
+  "version": "0.2.13",
   "description": "Deckline：DSH 的 image deck / PPT 工作台插件——原生 Chat + 整页图片 deck 工作区 + 设计风格库；用对话做 PPT、按页出图、版本可追踪、导出 PDF/PPTX。",
+  "icon": "assets/icon.svg",
   "homepage": "https://github.com/yuna78/dsh-deck-studio#readme",
   "repository": {
     "type": "git",
@@ -70,6 +71,7 @@
     "client.js",
     "lib/",
     "ui/",
+    "assets/",
     "seeds/",
     "cordis.patch.yml",
     "cordis.example.yml"

package/seeds/docs/install.en.md

@@ -43,9 +43,13 @@ node -v && pnpm -v && dsh --version
 dsh --profile deckline --from-default-profile web
 
 # 2) install the plugin; dsh plugin add adds the bundle to the profile and enables it
-dsh plugin --profile deckline add dsh-plugin-deck-studio
+dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.13
 ```
 
+> Do not skip step 1: the `deckline` profile is **never created automatically**. Running
+> `dsh --profile deckline --port 13090` without it fails with `profile "deckline" does not exist`
+> — that is a missing profile, not a plugin problem.
+
 ### B. From the Git repository (public repo, no npm account needed)
 
 ```sh
@@ -146,17 +150,56 @@ creating a deck, check this table first.
   ```sh
   tar czf deckline-backup-$(date +%Y%m%d).tgz "$DSH_HOME/deckline" "<your projectsRoot>"
   ```
-- The workbench **Settings** panel shows the current data directory; keep `dataRoot` outside the source tree
-  in normal installs so runtime data is portable and plugin upgrades cannot overwrite it.
+- **Where to look:** if a top banner says the body/images are not in the current data directory, use its
+  "switch to this directory" (one click, no restart). With no banner (this deck was never initialized here) go
+  **⚙ → right-hand Settings → "Other" → "current data directory" → "open self-check" → "change data directory"**.
+  Both show `dataRoot` and what decided it (`env var` / `pointer file` / `profile config` / `default`); with
+  `DSH_DECK_DATA_ROOT` they add "set by environment variable (read-only)" — edit that env var and restart DSH.
+- **Two instances on one machine read their own `dataRoot`.** 3080 (the default `web` profile) and 13090 (the
+  `deckline` profile) do not share a process and do **not** share data by default — each resolves its own
+  directory, both defaulting to `~/.dsh/deckline`; once either side sets `dataRoot` / `DSH_DECK_DATA_ROOT`
+  they diverge. So "the other port shows an empty deck / titles but blank pages" is not a port problem: check
+  the ⚙ panel on that instance. **Changing the port never changes data; only `dataRoot` does.**
+- Do not assemble paths by hand when reporting a problem: **Copy diagnostics** at the bottom of the self-check
+  panel copies a sanitized report generated by the plugin (never keys) — cwd / `dataRoot` with its source /
+  `projectsRoot` / whether each deck has `script/current.md`.
+- In normal installs keep `dataRoot` outside the source tree, and never write runtime data into the repo
+  (see the "development data directory" note in section 7).
+
+## 3. Start: the profile comes first, the port is cosmetic
+
+`--profile deckline` only **selects** a profile, it never creates one. Starting without one stops at:
+
+```text
+profile "deckline" does not exist
+```
 
-## 3. Start
+From zero to 13090, run these three commands in order (options for steps 1–2 are in section 1):
 
 ```sh
+# 1) create the deckline profile (from the web template shipped with DSH)
+dsh --profile deckline --from-default-profile web
+
+# 2) install the plugin (adds it to that profile and enables it)
+dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.13
+
+# 3) start
 dsh --profile deckline --port 13090
 ```
 
 Open the `http://127.0.0.1:13090/?token=…` URL printed in the terminal.
-`--port` is optional; the default is 13090 to avoid colliding with DSH's web profile on 3080.
+The explicit form `dsh --profile deckline web --port 13090` is the same thing with the `web` subcommand;
+`profile "deckline" does not exist` has nothing to do with that spelling — it means the profile was never created.
+
+### How 3080 and 13090 relate
+
+- **Ports pick the browser address, not the data.** Each instance resolves its own `dataRoot`; both default to
+  `~/.dsh/deckline`, so with defaults you see the same data. Set `dataRoot` / `DSH_DECK_DATA_ROOT` on one side and
+  they diverge.
+- 3080 is the default `web` profile (`dsh web`); 13090 is the `deckline` profile. If the `web` profile also has
+  Deckline installed, it is simply a second, independent instance with its own data directory.
+- **Changing the port never empties your data.** Titles showing with blank pages means the two instances point at
+  different `dataRoot`s — compare "current data directory" under ⚙ on both (section 2.5).
 
 ## 4. Configure the image key (required for real renders)
 
@@ -249,11 +292,20 @@ Swiss minimal / aurora gradient / deep-sea amber), each with samples. See [style
 |---|---|
 | Port already in use | `dsh --profile deckline --port 13100`; or kill the old process with `lsof -tiTCP:13090 -sTCP:LISTEN` |
 | Page 404 / blank | Make sure the plugin bundle is enabled: `dsh --profile deckline --dump-config \| grep deck-studio` |
+| `profile "deckline" does not exist` on start | The profile was never created: run `dsh --profile deckline --from-default-profile web`, then `dsh plugin --profile deckline add …`, then start (section 3) |
+| 3080 and 13090 show different content (titles but blank pages) | Not a port issue: the two instances have different `dataRoot`s. Compare "current data directory" under ⚙ on both (section 2.5); point them at the same path, or use only one |
+| Top banner says body/images are not in the current data directory | Click "switch to this directory" in the banner — no restart needed. With no candidate listed, type the absolute path into the banner and confirm |
+| No banner, but this deck has no body here | Normal only for a **locally created deck** on first open (its source is under `projectsRoot` and nothing has been rendered yet). Anything else — especially an external source deck — that has no body in the current data directory **always** gets the banner; with no candidate, the banner offers an absolute-path input |
+| Settings says "set by environment variable DSH_DECK_DATA_ROOT (read-only)" | The UI cannot change it: edit that env var and restart DSH (unrelated to `--port`) |
+| Inspector says "当前数据目录没有这本 deck 的 script" | The current data directory has no working copy of this deck. Check the `dataRoot` printed in that message (section 2.5) |
 | No "render" button / render fails | Check the key state in Settings; confirm `render.mode: real`; `curl` the node endpoint |
 | New decks land in the wrong place | Set `projectsRoot`; otherwise they go to `<dataRoot>/projects/` (by default `<DSH_HOME>/deckline/projects/`) |
 | Where are data / samples | See section 2.5: source decks in `projectsRoot`, working copies / renders in `dataRoot` (default `~/.dsh/deckline`) |
 | Upgrading the plugin | `dsh plugin --profile deckline install <spec>`, or `add` the new version again |
 
+> Early profiles were named `deck-studio`: swap `deckline` in the commands above for that name — the two differ only
+> in the profile name, which must match the directory under `~/.dsh/profiles/`.
+
 ## 7. Developers: local verification
 
 ```sh
@@ -264,3 +316,9 @@ dsh --profile deck-studio --no-open             # development profile (port conf
 
 The plugin has no third-party runtime dependencies (Node built-ins only). Changes to
 `plugin/deck-studio/index.js` require a profile restart; changes to `ui/` html/css hot-reload.
+
+> **Development data directory (debug only, not a recommendation):** the repo dev profile (`deck-studio`), or
+> pointing `dataRoot` at the repo, writes runtime data to `.deck/` at the repo root (gitignored, never committed);
+> the UI labels it as the **development data directory**. It exists so both profiles share one repo-local data
+> root and traces stay continuous (ADR-0006 D6) — never present it as a default. Normal installs use
+> `~/.dsh/deckline` or another directory outside the repo.

package/seeds/docs/install.md

@@ -45,12 +45,16 @@ node -v && pnpm -v && dsh --version
 dsh --profile deckline --from-default-profile web
 
 # 2) 装插件；dsh plugin add 会自动把组合包加入 profile 并默认启用
-dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.4
+dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.13
 ```
 
+> 第 1 步不能省：`deckline` profile **不会**被自动创建。跳过第 1 步直接 `dsh --profile deckline --port 13090`，
+> 报的是 `profile "deckline" does not exist` —— 这不是插件问题，是 profile 不存在。
+> 装过之后再升级只走第 2 步，不用再建一次 profile。
+
 > 国内网络直连 `registry.npmjs.org` 可能很慢（20 MB 包实测约 19 KB/s，要十几分钟）。换镜像会快很多：
 > ```sh
-> npm_config_registry=https://registry.npmmirror.com dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.4
+> npm_config_registry=https://registry.npmmirror.com dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.13
 > ```
 > 或一次性 `npm config set registry https://registry.npmmirror.com`。
 
@@ -71,7 +75,7 @@ DSH 目前没有官方插件市场，市场是「索引源」模式：添加下
    https://raw.githubusercontent.com/yuna78/dsh-deck-studio/main/market-index.json
    ```
 
-3. 搜索 `Deckline` 或 `PPT` → **安装**，会安装 `dsh-plugin-deck-studio@0.2.4`（索引里声明了国内镜像 registry）。
+3. 搜索 `Deckline` 或 `PPT` → **安装**，会安装 `dsh-plugin-deck-studio@0.2.13`（索引里声明了国内镜像 registry）。
 4. 之后同 A 的第 3 步启动。
 
 索引文件就是仓库根目录的 [`market-index.json`](../market-index.json)（格式 1），新版本发布后更新版本号即可。
@@ -175,19 +179,61 @@ Deckline 的数据分两处：**你的 deck 源**（`projectsRoot`，纯 md +
   ```sh
   tar czf deckline-backup-$(date +%Y%m%d).tgz "$DSH_HOME/deckline" "<你的 projectsRoot>"
   ```
-- 工作台「设置」面板会显示当前数据目录；开发环境也建议使用独立的 `dataRoot`，不要把运行数据写进仓库。
+- **「当前数据目录」在哪看**：指错目录时先看顶栏有没有黄条——有就点黄条里的「切到这个目录」，一步到位；没有黄条
+  （这本 deck 从没初始化过）才走 **⚙ → 右栏设置 →「其它」→「当前数据目录」→「打开自检面板」→「改数据目录」** 手填。
+  两处都写着 `dataRoot` 和它是被谁定的（`环境变量` / `指针文件` / `profile 配置` / `默认值`）；env 覆盖时追加
+  「由环境变量 DSH_DECK_DATA_ROOT 指定（只读）」，界面改不了，只能改环境变量后重启 DSH。
+- **同一台机器上的两个实例，看的是各自的 `dataRoot`**：3080（默认 `web` profile）和 13090（`deckline` profile）
+  不共享进程，也**不天然共享数据**——各自解析自己的数据目录，默认都是 `~/.dsh/deckline`；任意一边配了
+  `dataRoot` / `DSH_DECK_DATA_ROOT`，两边就各看各的。所以「换到另一个端口，内容变空 / 标题在但页面空白」先别怀疑端口：
+  去那个实例的 ⚙ 看「当前数据目录」，再和这边显示的路径比一比。
+  **换端口不改数据，换 dataRoot 才改数据。**
+- 报问题不用自己拼路径：⚙ →「当前数据目录与自检」底部 **「复制诊断信息」** 一键复制（内容由插件生成、已脱敏，
+  不含 key），贴出来就包含 cwd / dataRoot（含来源）/ projectsRoot / 每本 deck 有没有 `script/current.md`。
+- 开发环境用独立 `dataRoot`，不要把运行数据写进仓库（见 §7「开发数据目录」）。
 - **preset 工具实例要和根挂载用同一个数据根**（F-98）：DSH 面板路由与 Agent 工具是两个实例，根挂载里覆盖了
   `dataRoot` / `projectsRoot` 时，preset 的 `deck-studio-tools` 也要写同一组值（推荐 YAML 锚点），
   否则新建 deck 只进一边的注册表，Agent 会报「未知 deck：…」。
 
-## 3. 启动
+## 3. 启动：先有 profile，再谈端口
+
+`--profile deckline` 只**选** profile，不会创建它。profile 没建就启动，会停在这一行：
+
+```text
+profile "deckline" does not exist
+```
+
+从零跑到 13090，三条命令按顺序执行（第 1、2 步的具体选项见 §1；少任何一条都会停在上面的报错或白屏）：
 
 ```sh
+# 1) 建 deckline profile（基于 DSH 自带的 web 模板）
+dsh --profile deckline --from-default-profile web
+
+# 2) 装插件（自动加进该 profile 并启用）
+dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.13
+
+# 3) 启动
 dsh --profile deckline --port 13090
 ```
 
 浏览器打开终端打印的 `http://127.0.0.1:13090/?token=…`。
-`--port` 可换；不换默认 13090，避免和 DSH web profile 的 3080 冲突。
+
+带 `web` 子命令的写法也常见：`dsh --profile deckline web --port 13090`。它和上面第 3 条只差一个子命令；
+`profile "deckline" does not exist` 与写法无关，只说明 profile 没建。
+
+### 3080 和 13090 是什么关系
+
+| | 3080（默认 `web` profile） | 13090（`deckline` profile） |
+|---|---|---|
+| 怎么起 | `dsh web`（不带 `--profile`） | `dsh --profile deckline --port 13090` |
+| 装了什么 | 你日常的插件；**它若也装了 Deckline，就是另一个独立实例** | 单独一份 Deckline 挂载（同一个 npm 包） |
+| 看哪份数据 | 这个 profile 自己的 `dataRoot` | 这个 profile 自己的 `dataRoot` |
+
+- **端口只决定浏览器地址，不决定数据。** 两边各自解析 `dataRoot`：默认都是 `~/.dsh/deckline`，
+  所以都保持默认时看到的是同一份数据；哪一边配了 `dataRoot` / `DSH_DECK_DATA_ROOT`，那边就换成另一个目录。
+- 想只给 Deckline 一个入口，就用 13090；想让两边看到同一份数据，就**别只给一边配 `dataRoot`**（都不配，或配成同一路径）。
+- 反过来：**换端口不会让内容变空**。两个实例看到不同内容，几乎都是 `dataRoot` 指向了不同目录
+  （界面表现：标题在、页面空白、Inspector 报「读取正文失败」）——按 §2.5 在两边 ⚙ 里比对「当前数据目录」。
 
 ## 4. 配置生图 key（正式出图必看）
 
@@ -303,11 +349,20 @@ Designs 页 **＋ 导入预设风格** 会一次导入 9 个自带风格（商
 |---|---|
 | 端口被占 | `dsh --profile deckline --port 13100`；或 `lsof -tiTCP:13090 -sTCP:LISTEN` 杀掉旧进程 |
 | 页面 404 / 白屏 | 确认插件组合包已启用：`dsh --profile deckline --dump-config \| grep deck-studio` |
+| 启动报 `profile "deckline" does not exist` | profile 没建，不是插件问题：先 `dsh --profile deckline --from-default-profile web`，再 `dsh plugin --profile deckline add …`，然后启动（§3） |
+| 3080 和 13090 内容不一样（标题在、页面空白） | 不是端口问题：两个实例的 `dataRoot` 不同。按 §2.5 在两边 ⚙ 里比对「当前数据目录」；让两边指向同一路径，或只用其中一个 |
+| 顶栏黄条：正文 / 图片不在当前数据目录（有 deck 但没 script，或图片在正文丢了） | 点黄条里的「切到这个目录」，不重启即恢复；候选为空时在黄条里填绝对路径 →「用这个目录」 |
+| 没有黄条，但这本 deck 里没有正文 | 正常：只有**本机新建 deck**（源就在 `projectsRoot`，还没出过图）首次打开时静默。其它情况——尤其外部源 deck——当前数据目录里找不到正文**一定**出黄条，零候选时黄条里给手填绝对路径输入框 |
+| 设置里显示「由环境变量 DSH_DECK_DATA_ROOT 指定（只读）」 | 界面不能改：改这个环境变量后重启 DSH（与 `--port` 无关） |
+| Inspector 报「读取正文失败：当前数据目录没有这本 deck 的 script」 | 当前数据目录里没有这本 deck 的工作副本。按文案里的 `dataRoot` 核对（§2.5） |
 | 没有「生图」按钮 / 出图失败 | 设置面板看 key 是否配置；确认 `render.mode: real`；节点 endpoint 可 `curl` 通 |
 | 新 deck 目录落错位置 | 配 `projectsRoot`；否则落在 `<dataRoot>/projects/`（默认 `<DSH_HOME>/deckline/projects/`） |
 | 数据 / 样张在哪 | 见 §2.5：源 deck 在 `projectsRoot`，工作副本 / 出图在 `dataRoot`（默认 `~/.dsh/deckline`） |
 | 升级插件 | `dsh plugin --profile deckline install <spec>`，或重新 `add` 新版本 |
 
+> 早期按 `deck-studio` 建过 profile 的机器：把上面命令里的 `deckline` 换成那个名字即可——两者只是 profile 名不同，
+> 命令里的名字要和 `~/.dsh/profiles/` 下的目录名一致。
+
 ## 7. 开发者：本地验证
 
 ```sh
@@ -319,6 +374,11 @@ dsh --profile deck-studio --no-open             # 本仓开发 profile（端口
 插件无第三方运行时依赖（只用 Node 内置模块）；改 `plugin/deck-studio/index.js` 需要重启 profile，
 只改 `ui/` 里的 html/css 会热更新。
 
+> **开发数据目录（仅调试用，不是推荐值）**：本仓开发 profile（`deck-studio`），或手动把 `dataRoot` 指到仓库时，
+> 运行数据会落在仓库根的 `.deck/`（已在 `.gitignore`，不会进 git），界面上标成**「开发数据目录」**。
+> 这么做只为「两个 profile 同仓同数据、trace 连续」（ADR-0006 D6），**不要当成默认值写给用户**：
+> 正常安装用默认的 `~/.dsh/deckline`，或自己指定一个仓库外的目录。
+
 ## 2.5 首次启动会自动准备好什么（bootstrap）
 
 装完第一次启动（DSH 0.2.x 会先弹一次 Preview Notice，点 **Continue** 即可），Deckline 默认做四件事：

package/ui/workbench.css

@@ -238,6 +238,44 @@ body.resizing{user-select:none;cursor:col-resize}
 .hn-label{flex:1}
 .home-nav-item em{font-style:normal;font-size:10px;color:#93a0a3;background:#fffdf8;border:1px solid var(--line);border-radius:9px;padding:0 5px}
 .home-nav-item.active em{color:var(--teal);border-color:#bfe0dc}
+/* F-193/F-194：左栏「关于」单入口（版本 chip + 有新版小圆点） */
+.home-nav-sep{height:1px;background:var(--line);margin:10px 4px 0}
+.hn-dot{width:6px;height:6px;border-radius:50%;background:var(--gold);box-shadow:0 0 0 3px color-mix(in srgb,var(--gold) 18%,transparent)}
+.hn-dot[hidden]{display:none}
+/* F-194：「关于」单页——从上到下：作者 → 公众号 → 版本 → 开源 → 其他项目 */
+.about-stack{display:flex;flex-direction:column;gap:12px;max-width:880px}
+.about-card{border:1px solid var(--line);background:#fffdf8;border-radius:10px;padding:16px 18px;min-width:0}
+.about-card h3{display:flex;align-items:baseline;gap:8px;flex-wrap:wrap;margin:0 0 8px;font-family:"Noto Serif SC",Georgia,serif;font-size:16px;color:var(--ink)}
+.about-role{font-family:Inter,-apple-system,sans-serif;font-size:10.5px;font-weight:400;color:#93a0a3;letter-spacing:.02em}
+.about-hero{display:flex;flex-direction:column;gap:14px;background:linear-gradient(180deg,#fffdf8 0%,#faf5e9 100%)}
+.about-profile{display:flex;gap:14px;align-items:center;min-width:0}
+.about-wechat{display:flex;align-items:center;gap:14px;border-top:1px solid var(--line);padding-top:13px}
+.about-wechat-text{flex:1;min-width:0;display:flex;flex-direction:column;gap:2px}
+.about-wechat b{font-size:13px;color:var(--teal);line-height:1.5}
+.about-wechat .eyebrow{color:#93a0a3}
+.about-wechat .about-hint{margin:2px 0 0}
+.about-wechat .about-qr{flex:0 0 auto;width:104px;max-width:104px;border-radius:7px}
+.about-avatar{flex:0 0 auto;width:58px;height:58px;border-radius:14px;display:flex;align-items:center;justify-content:center;font-family:"Noto Serif SC",Georgia,serif;font-size:24px;color:#fffdf8;background:linear-gradient(145deg,#0e5563,#08343d);box-shadow:inset 0 0 0 1px #ffffff22}
+.about-profile-body{min-width:0;max-width:560px}
+.about-desc{margin:0 0 8px;color:#5d7276;font-size:12px;line-height:1.65}
+.about-line{margin:0 0 4px;color:#728086;font-size:11.5px}
+.about-line b{color:var(--teal)}
+.about-line code{font-size:11px;color:#5d7276;background:#f3efe4;border:1px solid var(--line);border-radius:5px;padding:1px 5px}
+.about-hint{margin:8px 0 0;color:#93a0a3;font-size:10.5px;line-height:1.6;word-break:break-word}
+.about-actions{display:flex;gap:8px;flex-wrap:wrap;margin-top:10px}
+.about-actions .btn{font-size:11px}
+.about-state{margin:8px 0 0;color:var(--gold)}
+.about-qr{display:block;width:140px;max-width:140px;aspect-ratio:1;object-fit:contain;border:1px solid var(--line);border-radius:8px;background:#fff}
+.about-qr-empty{display:flex;align-items:center;justify-content:center;width:140px;aspect-ratio:1;color:#93a0a3;font-size:11px;border:1px dashed var(--line);border-radius:8px;background:#f8f5ed;text-align:center;padding:8px}
+.about-project-list{list-style:none;margin:2px 0 0;padding:0}
+.about-project-row{display:flex;gap:14px;align-items:flex-start;justify-content:space-between;padding:12px 0;border-top:1px solid var(--line)}
+.about-project-row:first-child{border-top:0;padding-top:2px}
+.about-project-main{flex:1;min-width:0}
+.about-project-head{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+.about-project-head b{font-size:13px;color:var(--ink)}
+.about-badge{flex:0 0 auto;font-size:10px;color:var(--teal);background:#e2f1ef;border:1px solid #bfe0dc;border-radius:9px;padding:1px 7px}
+.about-project-row .about-desc{margin:4px 0 0}
+.about-project-row .btn{flex:0 0 auto}
 .home-main{padding:26px 32px;overflow-y:auto;min-width:0}
 .home-greet{padding-bottom:16px;border-bottom:1px solid var(--line);margin-bottom:18px}
 .home-greet h1{margin:5px 0 4px;font-family:"Noto Serif SC",Georgia,serif;font-size:30px;color:var(--ink);letter-spacing:.01em}