dsh-mosaic 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,39 @@
 > 兼容性分两处表达：`package.json` 的 `engines.dsh` 给机器可读的范围，README「安装」一节给「插件版本 ↔ 实测 Harness 版本」对照表；每次在真实 Harness 上验证后更新这两处。
 > `0.2.1` 及各 `0.2.1-<标签>` 是改规则前的历史版本，保留用于追溯。
 
+## 1.1.1
+
+发布流程修正，运行时代码与 `1.1.0` 相同。
+
+- `release.yml` 去掉了 `actions/setup-node@v4` 不认识的 `package-manager-cache` 输入。该行此前被忽略，每次发布都会打一条 unexpected-input 警告；缓存本就默认关闭，而这个 job 不安装任何依赖，因此直接删除并注明原因。
+
+## 1.1.0
+
+### 示意图
+
+- `diagram` 从 4 种扩到 13 种。新增 `quadrant`、`tree`、`funnel`、`venn`、`swimlane` 由插件自己排布（与 `timeline`、`layers` 同一条原生 SVG 路线，不依赖图引擎）；新增 `state`、`er`、`gantt`、`mindmap` 走 Mermaid 语法。
+- `legend: [{label, tone}]`：给颜色加说明，所有图类型通用，渲染在卡片下方。
+- 节点按标签文字估宽，不再固定宽度后截断成省略号；`tree` 的父节点按子树居中，`swimlane` 的列宽随步数自适应，`quadrant` 的标签相撞时自动下移。
+- 修复同页多张图共用 `#mosaic-arrow` / `#mosaic-seq-arrow` 的问题：marker id 现在按组件实例生成。
+
+### 导出
+
+- 每个 diagram 卡片新增 `svg` 与 `png` 导出。导出前用 `getComputedStyle` 把主题令牌解析成实际颜色并内联，去掉仍带 `var(--m-*)` 的表现属性，因此文件脱离页面也能正常显示；PNG 以 2 倍尺寸光栅化，并先铺卡片背景。
+
+### 视觉修正
+
+- 列表圆点和链接箭头改用 `1lh` 定高，跟随实际行高居中；此前用写死的像素偏移，宿主行高不同就会一个偏高、一个偏低。
+- 柱状图柱宽封顶 28px 并在分类槽里居中，多序列组内留 4px 间距；此前柱宽按分类宽度等比放大，7 个分类时每根接近 60px。
+- Mermaid 输出的 SVG 带 `width="100%"`，插件此前用 `max-width:none` 去掉上限，导致整图被拉到卡片宽度、文字跟着放大。现在按 `viewBox` 钉回自然尺寸，并套用与原生示意图相同的高度上限。
+- ER 与 sequence 在 Mermaid 内部写死 14px / 16px，不认 `themeVariables.fontSize`；统一归一到 12px，作用域限定在该 SVG 自己的 id 上。
+- `row` 的子节点原本套着一层 `.mosaic-grid-item`，`col` 的百分比宽度会按这层收缩到内容宽度的包装计算（40% 只剩 30px）。改用 `display:contents` 让 `col` 直接作为 flex 子项，两栏按比例分配并吸收间距。
+- README 的效果图按修复后的渲染重新截图。
+
+### 校验与建议
+
+- `validate_view` 与 `render_view` 新增 `warnings=`：视图合法但超出可读规模时给出具体改法（表格超过 8 行、列表超过 7 项、图表点数为 1、`accent` 用在超过 2 个元素、卡片嵌套超过 2 层、某类图超过自己的规模、`widget` 引用外部资源）。这些只是建议，不影响渲染。
+- 模型侧提示词与 `SKILL.md` 增加反模式清单、焦点规则和每类图的可读规模；`SKILL.md` 补全 13 种图的字段说明与选型表。
+
 ## 1.0.0
 
 首个稳定版，也是 npm 上第一次发布的完整版本（`0.2.1` 之后的所有改动都在这里）。

package/README.md

@@ -6,8 +6,9 @@ Mosaic 是一个轻量的 DeepSeek Harness 可视化回答插件。它把模型
 
 它刻意不追求“什么都能画”：
 
-- 主包没有 ECharts / Three.js；flowchart / sequence 用官方 Mermaid 发行包，作为懒加载资产，只在出现 diagram 时下载（原始 5.5 MB，gzip 后约 1.3 MB，带版本号可长期缓存）。
-- 每个 diagram 卡片右上角有 `drawio` 按钮，可导出标准 mxGraph XML，在 draw.io 里继续编辑。
+- 主包没有 ECharts / Three.js；`flowchart`、`sequence`、`state`、`er`、`gantt`、`mindmap` 用官方 Mermaid 发行包，作为懒加载资产，只在出现这几种图时下载（原始 5.5 MB，gzip 后约 1.3 MB，带版本号可长期缓存）。
+- `timeline`、`layers`、`quadrant`、`tree`、`funnel`、`venn`、`swimlane` 由插件自己排布，不依赖图引擎；节点宽度按标签文字估算，不截断成省略号。
+- 每个 diagram 卡片右上角有 `svg` / `png` / `drawio` 三个导出按钮：前两个直接下载图片（颜色、字号按当前主题解析后内联，脱离页面也能看），`drawio` 导出标准 mxGraph XML，在 draw.io 里继续编辑。
 - 组件目录保持精简，字段、校验、提示词来自同一份定义。
 - 普通文件/Office 只给链接，不在聊天里硬解。
 - 交互默认在本地完成；只有声明了 `action` 的组件才回模型。
@@ -57,6 +58,26 @@ Mosaic 是一个轻量的 DeepSeek Harness 可视化回答插件。它把模型
 
 `diff` 带行号和 `-`/`+` gutter，长行自动换行。
 
+`diagram` 支持 13 种图，按“读者要回答的问题”选：
+
+| 读者要看懂 | kind | 建议规模 |
+| --- | --- | --- |
+| 分支、重试、判断 | `flowchart` | 9 节点 / 12 边 |
+| 谁在什么时候说了什么 | `sequence` | 5 条生命线 / 12 条消息 |
+| 时间线上的事件 | `timeline` | 7 项 |
+| 分层结构 | `layers` | 6 层 |
+| 两轴定位（优先级、取舍） | `quadrant` | 12 项 |
+| 父子层级、组织关系 | `tree` | 12 节点 / 4 层 |
+| 逐级流失的转化 | `funnel` | 6 级 |
+| 集合重叠 | `venn` | 3 个集合 |
+| 跨角色的交接 | `swimlane` | 6 步 / 5 条泳道 |
+| 状态与迁移 | `state` | 9 个状态 |
+| 表结构与关系 | `er` | 8 个实体 |
+| 排期 | `gantt` | 12 个任务 |
+| 主题发散 | `mindmap` | 12 个分支 |
+
+`legend: [{label, tone}]` 给颜色加说明：`tone` 表达含义时写，纯装饰时省略。
+
 完整字段见 [`SKILL.md`](./SKILL.md)。
 
 ## 日志
@@ -137,14 +158,28 @@ dsh plugin --profile desktop add link:/absolute/path/to/dsh-mosaic
 
 | 插件版本 | 实测通过的 DeepSeek Harness | 说明 |
 | --- | --- | --- |
+| `1.1.1` | `0.2.1-rc.5` | 运行时代码与 `1.1.0` 相同；仅修正发布工作流的无效输入 |
+| `1.1.0` | `0.2.1-rc.5` | 13 种示意图、PNG/SVG 导出、`warnings=` 可读规模提示、布局修正 |
 | `1.0.0` | `0.2.1-rc.5`（同时复核 rc.3 行为） | 首个稳定版；含 Widget 沙箱、路由权威、Prompt 并发等修正 |
 | `0.2.1` | `0.2.1-rc.3`、`0.2.1-rc.5` | 上一版，npm 上的历史发布 |
 
 Harness 升级到 `0.3.x` 后，请先在新版本上验证再放宽 `engines.dsh`，并在此表补一行。
 
+## 校验与建议
+
+`validate_view` 和 `render_view` 除了报错，还会返回 `warnings=` 行，指出“能渲染但读起来费劲”的地方，例如：
+
+- 表格超过 8 行、列表超过 7 项、图表超过 12 个点或只有 1 个点；
+- 同一个视图里 `accent` 用在超过 2 个元素上；
+- 卡片嵌套超过 2 层；
+- 某类图超过它自己的可读规模（flowchart 9 节点、sequence 5 条生命线……）；
+- `widget` 里引用了外部 CDN 资源（沙箱没有网络，必定加载失败）。
+
+这些不阻塞渲染，只是给出改法。
+
 ## 限制
 
-- 80 节点、6 层嵌套、表格 40×8、图表 40 点、diagram 12 节点/20 边、widget 代码 20k。
+- 硬上限：80 节点、6 层嵌套、表格 40×8、图表 40 点、diagram 12 节点/20 边、widget 代码 20k。可读规模见上文的表格与 `SKILL.md`。
 - 不读本地文件、不渲染 docx/pptx/xlsx；这些用 `link` 卡片交给宿主打开。
 - 不内置数学公式排版；公式可以放在 `code` 或普通文本里。
 - 围栏渲染依赖 DSH 当前的代码块 DOM；宿主结构变化时可能需要适配。

package/SKILL.md

@@ -27,7 +27,7 @@ Rules:
 - Prefer one focal component; do not repeat the same data as both a table and a chart.
 - For files or Office documents, use a `link` card. Mosaic does not read local files or render Office; those open in the host app.
 - Media (`image`, `video`, `audio`, `pdf`) accepts an `http(s)` URL or a root-relative path.
-- `validate_view` is available for a preflight check on complex specs. For a flowchart longer than 6 nodes, prefer `direction: "TB"`; a long `LR` diagram scrolls horizontally.
+- `validate_view` is a preflight check: besides errors it returns `warnings=` lines for a valid but heavy view. For a flowchart longer than 6 nodes, prefer `direction: "TB"`; a long `LR` diagram scrolls horizontally.
 
 ## Components
 
@@ -62,16 +62,45 @@ Rules:
   - `donut` is single-series; use `data` only.
   - For grouped bars or multi-line, use `series`.
   - Keep it to 40 points and 8 series.
-- `diagram`: `{kind: "flowchart|sequence|timeline|layers", title?, direction?: "TB|LR", ...}` — see the section below.
+- `diagram`: `{kind, title?, legend?, ...}` — see the section below.
 
 ### Diagram
 
-When you show a flow, sequence, timeline, or layered architecture, use `diagram`. It is plain JSON; do not hand-write Mermaid markup for these unless the content needs a real Mermaid engine inside a widget. Flowchart and sequence nodes are rendered through a lazy-loaded Mermaid engine; timeline and layers use the built-in renderer. Every diagram card also has a `drawio` download button.
-
-- `flowchart`: `nodes: [{id, label, sub?, tone?: "accent|success|warning|danger|muted", shape?: "box|round|diamond"}], edges: [{from, to, label?, kind?: "solid|dashed|accent"}], direction?: "TB|LR"`
+Use `diagram` for a flow, a sequence, a timeline, a hierarchy, or a two-axis map. It is plain JSON; do not hand-write Mermaid markup for these unless the content needs a real Mermaid engine inside a widget.
+
+Pick the kind by the question the reader has, and stay near its readable size:
+
+| The reader must see… | `kind` | Readable size |
+|---|---|---|
+| branches, retries, gates | `flowchart` | 9 nodes, 12 edges |
+| who says what, in order | `sequence` | 5 lifelines, 12 messages |
+| events on a line | `timeline` | 7 items |
+| stacked levels | `layers` | 6 layers |
+| two-axis positioning | `quadrant` | 12 items |
+| parent → children | `tree` | 12 nodes, depth 4 |
+| a drop-off across stages | `funnel` | 6 steps |
+| overlap between sets | `venn` | 3 sets |
+| hand-offs across owners | `swimlane` | 6 steps, 5 lanes |
+| states and transitions | `state` | 9 states |
+| tables and relations | `er` | 8 entities, 8 relations |
+| scheduled work | `gantt` | 12 tasks |
+| a topic map | `mindmap` | 12 branches |
+
+Fields by kind:
+
+- `flowchart` / `state`: `nodes: [{id, label, sub?, tone?: "accent|success|warning|danger|muted", shape?: "box|round|diamond"}], edges: [{from, to, label?, kind?: "solid|dashed|accent"}]`; `flowchart` also takes `direction?: "TB|LR"`, and `state` takes `initial?: id` and `final?: [id]`.
 - `sequence`: `participants: [{id, label}], messages: [{from, to, label, kind?: "sync|return|async"}]`
 - `timeline`: `items: [{title, desc?, time?}]`
 - `layers`: `layers: [{title, items: string[]}]`
+- `quadrant`: `xAxis: [low, high], yAxis: [low, high], quadrants?: {tl, tr, bl, br}, items: [{label, x, y, tone?}]` — `x` and `y` are 0–1, with `(0,0)` at the bottom-left.
+- `tree` / `mindmap`: `root: {label, sub?, tone?, children?: [same shape]}` — one root, at most four levels.
+- `funnel`: `items: [{label, value}]` — two to eight stages, widest first.
+- `venn`: `sets: [{label, tone?}], center?` — two or three sets.
+- `swimlane`: `lanes: [string], steps: [{lane, label}]` — `lane` indexes `lanes`; steps run left to right in array order.
+- `er`: `entities: [{name, fields: [{name, type?, key?: "PK|FK"}]}], relations?: [{from, to, label?, cardinality?: "one-to-one|one-to-many|many-to-one|many-to-many"}]`
+- `gantt`: `tasks: [{name, start, end, section?}]` — dates are `YYYY-MM-DD`.
+
+`legend: [{label, tone?}]` names what a colour means, for every kind. Add it when `tone` carries meaning (a focal step, a failure state); leave it out when the colours are decoration.
 
 A single `diagram` node fragment (this is not a complete fence; wrap it in `{"items":[…]}` under a `dsh-view` tag):
 
@@ -85,10 +114,10 @@ A single `diagram` node fragment (this is not a complete fence; wrap it in `{"it
   {"from":"start","to":"check"},
   {"from":"check","to":"hit","label":"是","kind":"accent"},
   {"from":"check","to":"miss","label":"否"}
-]}
+],"legend":[{"label":"命中路径","tone":"accent"}]}
 ```
 
-Keep a flowchart to 12 nodes / 20 edges; sequence to 8 participants / 20 messages; timeline to 12 items; layers to 8 layers.
+`flowchart`, `sequence`, `state`, `er`, `gantt`, and `mindmap` render through a lazy-loaded Mermaid engine; `timeline`, `layers`, `quadrant`, `tree`, `funnel`, `venn`, and `swimlane` are drawn by Mosaic itself. Every diagram card has `svg`, `png`, and `drawio` export buttons in its header.
 
 ### Media and links
 
@@ -151,3 +180,34 @@ After an action, update the existing view instead of restating the whole answer.
 - Choose the smallest component that carries the structure; avoid decorative cards, repeated summaries, and nested scrolling.
 - Keep the tree under 80 nodes and 6 levels.
 - A malformed fence falls back to the original code block; a widget that fails to boot shows its source and an error strip.
+
+### What reads as decoration
+
+Run this before emitting a view. Each row is a real habit, not a hypothetical:
+
+| Anti-pattern | Do instead |
+|---|---|
+| Three equal-width `stat` cards as a header | One stat, or a table |
+| `tone: "accent"` on more than two elements | Decide what is focal and accent only that |
+| Cards nested more than two deep | Flatten one level |
+| A table longer than 8 rows in chat | Add `filter`/`sort`, or split the table |
+| A chart with one point | Write the sentence |
+| A diagram of two boxes | Write the sentence |
+| The same numbers in a table *and* a chart | Pick one |
+| A component that only restates the paragraph above it | Delete it |
+| A `widget` loading a CDN script | Inline the library; the sandbox has no network |
+
+`validate_view` returns these as `warnings=` lines, so a valid but heavy view is named before you emit it.
+
+### Budgets
+
+The hard caps only keep a view renderable. These are the sizes at which a chat card still reads at a glance:
+
+| Component | Readable | Hard cap |
+|---|---|---|
+| `table` | 8 rows | 40 rows × 8 columns |
+| `chart` | 12 points | 40 points, 8 series |
+| `list` | 7 items | 30 items |
+| `diagram` | per-kind table above | 12 nodes / 20 edges |
+| focal accents per view | 2 | — |
+| card nesting | 2 levels | 6 levels |