@taylorwong/ichartjs 2.0.6 → 2.0.8

package/docs/agent/zh-CN/charting-scenario.md

@@ -26,6 +26,32 @@
 - Heatmap 通过 `colorScale.missing` 区分缺失值和数值零。
 - Radar 应为每个指标声明 `min` 和 `max`；缺失域或混合单位会产生告警。
 
+## 配置项位置
+
+`encoding` 只描述字段角色和 Series 语义。以下配置应放在 Spec 顶层：
+
+| 配置 | 正确位置 | 适用范围 |
+| --- | --- | --- |
+| 坐标轴标题和格式 | `xAxis.title/format`、`yAxis.title/format` | Line、Area、Bar、Column、Scatter |
+| 易读数值域 | `yAxis.nice`、`yAxis.ticks`、`yAxis.domain` | Line、Area、Bar、Column、Scatter |
+| 数据标签 | `labels.enabled/format` | 能力清单声明支持 labels 的图表 |
+| 图例 | `legend.visible/position` | 多系列笛卡尔图、Pie、Radar |
+| Gauge 坐标域 | `domain: [min, max]` | Gauge |
+| Heatmap 颜色域 | `colorScale.domain` | Heatmap |
+| Radar 指标域 | `indicators[].min/max` | Radar |
+
+不要把 `title`、`format`、`labels` 或 `legend` 放在 `encoding` 中；`validateSpec()` 会报告结构化警告。数值纵轴默认使用易读域（`nice: true`、`ticks: "auto"`）；需要固定范围时使用 `yAxis.domain: [min, max]`，需要保留原始边界时使用 `yAxis.nice: false`。分类/时间横轴的 `min/max` 和 `domain` 不支持。
+
+## Encoding 契约
+
+不同图表只接受对应的数据通道：笛卡尔图表使用 `encoding.x`/`encoding.y`；Pie、Funnel、Gauge 使用 `encoding.category`/`encoding.value`；Heatmap 使用 `encoding.x`/`encoding.y`/`encoding.color`；Radar 使用 `indicators[].field`。字段不存在或通道不支持会成为校验错误，不应静默改名。Gauge 必须提供 `domain: [min, max]`；超出范围时弧形会限制在范围内，并产生 `VALUE_CLAMPED`。全部图表的最小可执行 Spec 见 `@taylorwong/ichartjs/recipes/minimal-specs`。
+
+## 意图注册词
+
+传给 `planChart()` 的 `intent` 必须是 `getCapabilities().intents` 中的精确值，而不是用户原句。比如把“展示销售随时间变化”映射为 `trend`；未知词会返回 `UNKNOWN_INTENT` 和降级方案，不能忽略该警告。
+
+未知词的规划结果还会给出 `intentKnown: false`、`fallbackUsed: true` 和 `intentSuggestions`，应据此重新映射或请求确认。
+
 ## Agent 流程
 
 1. 使用 `inspectData(data)` 检查字段和缺失值。
@@ -33,6 +59,10 @@
 3. 生成 JSON-serializable Chart Spec。
 4. 先调用 `validateSpec(spec)`，再调用 `createChart(spec)`。
 5. 使用 `chart.describe()` 和 `chart.getState()` 检查结果。
+6. 如果需要 lineage、联动筛选或后续更新，为每条记录提供稳定字符串 `id`；没有 `id` 时 Runtime 会使用 `record-0` 这类确定性后备值。
+7. 展示前检查 `chart.getState().health.renderable`、`health.status` 和 `warnings`。`ready` 表示没有阻止渲染的问题，`degraded` 表示带诊断继续渲染，`empty` 表示结果没有可用内容。
+
+`locale` 默认是 `en-US`，需要中文数字/日期输出时设置 `locale: "zh-CN"`。输入日期保持 ISO-8601 字符串；运行时不负责自然语言日期解析。
 
 ## 最小 Spec
 
@@ -40,7 +70,7 @@
 {
   type: 'line',
   renderer: 'svg',
-  data: { values: [{ month: 'Jan', sales: 120 }] },
+  data: { values: [{ id: 'jan', month: 'Jan', sales: 120 }] },
   encoding: {
     x: { field: 'month', type: 'category' },
     y: { field: 'sales', type: 'quantitative' }

package/docs/agent/zh-CN/coding-agent-integration.md

@@ -22,7 +22,7 @@ npm Registry 中无作用域的 `ichartjs` 是安全占位包，并非本项目
 npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
-Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
+Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.8/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
 
 使用 `npx skills add wanghetommy/ichartjs --list` 验证发现结果，其中应包含 `ichartjs`。
 

package/docs/agent/zh-CN/diagram-scenario.md

@@ -6,10 +6,39 @@
 
 - `flow`：节点和边组成的流程图。
 - `swimlane`：带责任泳道的流程图。
+- `architecture`：带可选层和边界的业务、数据或技术架构图。
+- `mindmap`：以树形或放射布局呈现想法层级的思维导图。
+
+架构图和思维导图都属于结构化图，但不能混用：架构图表达明确的领域或系统关系，思维导图表达想法层级。
+
+思维导图建议使用简洁的父子数据：
+
+```js
+{
+  type: 'mindmap',
+  nodes: [
+    { id: 'root', label: '发布计划' },
+    { id: 'scope', label: '范围', parentId: 'root' },
+    { id: 'risk', label: '风险', parentId: 'root' }
+  ],
+  diagram: { mode: 'mindmap', layout: 'tree', routing: 'curved', curveTension: 0.4 }
+}
+```
 
 ## 当前能力
 
-已支持节点、边、泳道、Group、Port、四种布局、三种路由、节点拖动、多选、对齐、网格吸附、键盘移动、Copy/Paste、Group 折叠展开、Port 键盘连线和 Undo/Redo。
+已支持节点、边、泳道、Group、Port、四种布局、三种路由、Mindmap 三次贝塞尔曲线、节点拖动、多选、对齐、网格吸附、键盘移动、Copy/Paste、Group 折叠展开、Port 键盘连线、边选择、折点/正交线段手柄、持久化 `waypoints`、边删除和 Undo/Redo。
+
+导航和编辑能力默认关闭。普通图表保持静态，缩放、平移、框选、节点拖动、线段拖动、Port 连线和结构编辑必须由宿主显式开启：
+
+```js
+interaction: { zoom: true, pan: true, drag: true, edgeDrag: true, portConnect: true },
+editing: { enabled: true, allowDelete: true, allowStructuralChanges: true }
+```
+
+Canvas 与 SVG 共用 Scene Graph 命中、`waypoints`、命令、历史和交互行为，不提供渲染器专属编辑能力。
+
+Mindmap 默认使用曲线父子连线。`diagram.curveTension` 支持 `0.2` 到 `0.8`；显式边可以覆盖 `routing` 或 `curveTension`。存在 `waypoints` 时优先使用人工折线，当前不支持直接拖动贝塞尔控制点。
 
 当前限制：
 
@@ -22,7 +51,7 @@
 1. 为节点和边分配稳定 ID。
 2. 使用 `validateDiagram(spec)` 检查端点、Port、Group、Lane 和布局。
 3. 使用 `createChart(spec)` 创建图表。
-4. 使用 `moveNodes`、`alignNodes`、`snapNodes` 等命令编辑。
+4. 使用 `moveNodes`、`alignNodes`、`snapNodes`、`updateEdge`、`removeEdge` 等命令编辑。
 5. 编辑遵循 `editing-contract.md` 的 Preview/Confirm/Commit 流程。
 
 ## 开发位置与验收
@@ -34,4 +63,4 @@
 - 专用 Demo：`playground/diagram-editor.html`
 - 全量 Gallery：`playground/project-gallery.html`
 
-节点移动后必须验证边、箭头和标签跟随；同时检查 Canvas 与 SVG 的一致性。
+节点移动后必须验证边、箭头和标签跟随；同时检查 Canvas 与 SVG 的边命中、手柄拖动、waypoint 持久化、键盘和导出一致性。

package/docs/agent/zh-CN/editing-contract.md

@@ -23,5 +23,7 @@ const result = chart.applyEdit(command, { preview, confirmed: true, source: 'age
 - 默认需要 Host 确认；确认不等同于授权。
 - 成功提交产生 ChangeSet、审计信息、revision 和 Undo 历史。
 - 外部持久化、权限和认证由 Host 应用负责。
+- 指针导航和编辑默认关闭。`editing.enabled` 授权编辑事务；`interaction.drag`、`interaction.edgeDrag`、`interaction.portConnect` 分别控制直接操作 UI。
+- Diagram 边通过 JSON-safe 的 `waypoints` 持久化；路径更新使用 `updateEdge`，删除使用 `removeEdge`，并要求结构编辑权限。
 
 Schema、命令、Preview/Commit、事务和历史的实现分别位于 `src/schema.mjs`、`src/command.mjs`、`src/edit.mjs`、`src/edit-controller.mjs` 和 `src/history.mjs`。

package/docs/agent/zh-CN/frontend-integration.md

@@ -6,7 +6,7 @@ iChart.js 应作为普通 JavaScript UI 组件运行在浏览器应用中。数
 npm install @taylorwong/ichartjs@^2
 ```
 
-无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.6`。
+无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.8`。
 
 ```js
 import { createChart } from '@taylorwong/ichartjs';

package/docs/agent/zh-CN/iteration-12.md

@@ -0,0 +1,98 @@
+# Iteration 12：结构化图——架构图与思维导图
+
+Iteration 12 在 Flow/Swimlane 现有 Diagram Runtime 上增加两种结构化图模式。架构图和思维导图共用节点、边、布局、交互、导出和 Agent 契约，不新增第二套渲染器。
+
+## 12A：共享结构化图模型
+
+- 复用稳定节点 ID、边、Group、Port、位置、尺寸、路由、选择、键盘导航、历史、Canvas/SVG 渲染以及 JSON/SVG/PNG 导出。
+- 将 `diagram.mode` 归一化为 `process`、`architecture` 或 `mindmap`。
+- 思维导图可以从 `node.parentId` 推导父子边，同时保留显式边。
+- 校验缺失父节点、自引用、重复 ID、无效层引用和思维导图循环。
+- Agent 统一使用 `validateDiagram()` 作为校验入口。
+
+## 12B：架构图模式
+
+- 使用 `type: 'architecture'` 表达业务架构、数据架构和技术架构。
+- 使用 `layers` 表达稳定的架构分层。
+- 使用 `boundaries` 表达领域、系统、平台或上下文边界，并支持 `nodeIds`、标签、边距和颜色。
+- 普通边表达依赖、实现、持久化、发布等关系；Runtime 不擅自推断业务语义。
+- 有明确位置时保留手工布局，否则使用确定性的分层布局。
+
+## 12C：思维导图模式
+
+- 使用 `type: 'mindmap'` 和 `parentId` 表达简洁的 Agent 友好层级。
+- 支持确定性的 `tree` 和 `radial` 布局。
+- 使用现有 Diagram 模型表达根节点和分支强调，不新增独立编辑模型。
+- 保留稳定 ID 和父引用，Agent 可以只更新一个分支。
+
+## 12D：Agent 契约与 Schema
+
+- 在 `getCapabilities()`、`planChart()`、图表能力、TypeScript 声明和 manifest 中暴露 `architecture`、`mindmap`。
+- 增加 `architecture-node`、`architecture-edge`、`mindmap-node` Schema。
+- 对层、边界和父节点语义返回 assumptions 与结构化诊断，不静默猜测。
+- 两者都归入 `diagram` 家族，仅在 architecture、hierarchy、brainstorm 等意图下推荐。
+
+## 12E：Playground 与文档
+
+- 在 `playground/project-gallery.html` 增加 Architecture 和 Mindmap 示例。
+- 要区分：架构图表达领域/系统结构，思维导图表达想法层级；思维导图不默认等同于架构图。
+- 执行 `npm run playground`，打开 `http://localhost:3000/playground/project-gallery.html`，搜索 `Architecture` 或 `Mindmap`。
+
+## 12F：Canvas/SVG 一致的线段编辑
+
+线段直接编辑必须是与渲染器无关的 Diagram 能力。可以先用 SVG 验证交互体验，但 Canvas 与 SVG 必须提供相同的公共操作、编辑语义、持久化数据、键盘行为和最终验收状态。只要任一渲染器仍为只读或能力缩水，12F 就不算完成。
+
+Runtime 默认状态必须静态、安全，不产生意外的视图或结构变化。缩放、平移、框选、节点拖动、线段拖动、端口连线和结构命令默认全部关闭，必须由宿主显式开启。Agent 编辑继续使用经过校验的预览/提交契约，不得隐式开启页面中的指针编辑能力。
+
+### 第一阶段：边命中与选择
+
+- 增加基于几何距离的边命中算法和宽容的交互容差，不再依赖 Scene Node 的矩形 `bounds`。
+- Flow、Swimlane、Architecture、Mindmap 中的边都可选择，但不影响普通 Line 等数据图表的折线交互。
+- Canvas 与 SVG 一致支持选中、Hover、焦点、删除、Escape 和键盘遍历状态。
+- 命中检测放在共享 Scene Graph 中；SVG 可以使用透明粗描边优化 DOM 交互，但不能以 SVG DOM 作为唯一事实来源。
+- 通过 `getCapabilities()` 明确暴露边选择和边编辑能力。
+- 默认图表 Spec 必须关闭导航与编辑；Gallery 和只读嵌入页面不能隐式开启这些能力。
+
+### 第二阶段：折点与线段手柄
+
+- 仅在编辑模式选中边后显示折点手柄和线段中点手柄。
+- 拖动折点只更新一个 waypoint；拖动正交线段中点只移动对应的水平或垂直线段。
+- 使用不可见的扩大命中区域和最小触控尺寸，让细线易于操作，同时不改变可见线宽。
+- 复用共享编辑控制器的预览、确认、提交、撤销、重做和审计能力。
+- 可以先在 SVG 中验证交互，但不能发布渲染器特有的公共行为。
+
+### 第三阶段：人工路由持久化
+
+- 在边契约中增加 JSON-safe 的 `waypoints`，继续使用稳定 edge ID。
+- Canvas、SVG、JSON 导出、SVG/PNG 导出、复制粘贴、复制和 Agent 编辑均使用同一 waypoint 模型。
+- 路由优先级定义为：存在显式 waypoints 时优先使用，否则执行自动避障路由。
+- 节点移动后尽量保留有效人工线段，修复无效的端点线段；人工路径不可用时回退到确定性的自动路由。
+- Agent 通过经过校验的 `updateEdge` 操作更新路径，不增加渲染器专属命令。
+
+### 12F 验收
+
+- Canvas 与 SVG 通过同一套边命中、选择、手柄拖动、持久化、撤销/重做、键盘和导出测试。
+- Flow、Swimlane、Architecture、Mindmap 共用同一套边编辑契约和交互实现。
+- 细线在不改变可见宽度的情况下仍容易选择。
+- 人工 waypoints 在重绘、切换渲染器、序列化、导出和重新创建图表后保持不变。
+- 节点移动后边不能穿过节点；无效人工路径必须被修复或确定性地重新路由。
+- 在双渲染器一致性全部通过前，Capabilities 应报告线段拖动不可用，而不是只声明 SVG 支持。
+- 默认图表保持静态：缩放、平移、框选、节点拖动、线段拖动、端口连线和结构编辑只有在宿主显式配置后才启用。
+
+## 12G：Mindmap 贝塞尔曲线
+
+- Mindmap 父子连线默认使用 `routing: 'curved'`；Flow、Swimlane、Architecture 继续默认使用正交路由。
+- `curved` 在 Canvas 与 SVG 中都渲染为一段真实三次贝塞尔曲线，不再是四点折线。
+- `diagram.curveTension` 和单边 `curveTension` 支持 `0.2` 到 `0.8`，默认值为 `0.4`。
+- 标签位于贝塞尔中点，箭头根据终点切线定向；共享 Scene Graph 通过曲线采样保持 Canvas/SVG 命中一致。
+- 曲线穿过其他节点时，确定性回退到具备避障能力的正交路由。
+- 显式 `waypoints` 优先并继续使用人工折线。暂不提供贝塞尔控制点拖动；节点移动后自动重新计算曲线。
+
+## 验收
+
+- `npm run agent:check` 通过，公开图表类型为 18 个，业务 Schema 为 10 个。
+- Architecture 在 SVG 和 Canvas 下均能显示层、边界、节点和依赖边。
+- Mindmap 能校验父引用与循环，生成稳定父子边，并确定性渲染 tree/radial 布局。
+- 既有 Flow、Swimlane 测试和预览不回归。
+- Iteration 12F 只有在 Canvas 与 SVG 具备一致的线段编辑能力后才通过验收。
+- Iteration 12G 只有在 Canvas、浏览器 SVG 与 Headless SVG 都输出真实三次贝塞尔路径，并保持默认静态交互时才通过验收。

package/docs/agent/zh-CN/quickstart.md

@@ -36,6 +36,34 @@ Agent 与开发者使用同一个 ESM 入口。编码 Agent 的完整方式见 [
 6. 仅在 `validation.valid` 为 `true` 时调用 `createChart()`。
 7. 用 `chart.explain()`、`chart.getState()`、JSON/SVG/PNG export 完成自检。需要持久化或附件生成时使用 `chart.export({type:'json'|'svg'|'png'})`，在浏览器环境可调用 `chart.downloadPNG()` / `chart.downloadSVG()` / `chart.downloadJSON()` 触发保存，最后调用 `chart.destroy()`。
 
+### 意图必须使用注册词
+
+`intent` 是精确的机器词，不是自然语言句子。先从 `getCapabilities().intents` 获取允许值，再传入 `trend`、`time-series`、`comparison`、`ranking`、`distribution`、`relationship`、`matrix`、`multidimensional`、`schedule`、`architecture` 或 `mindmap` 等值。不要直接传入 `trend over time` 或 `展示销售趋势`。未知词会返回 `UNKNOWN_INTENT` 警告并安全降级；如果忽略警告，可能选错图表。
+
+如果用户输入的是自然语言，先映射为注册词，再调用 `planChart()`，同时保留原始用户意图用于展示。
+
+### 配置项放在 Spec 正确层级
+
+`encoding` 只描述字段角色和 Series 语义，标题、格式和显示组件放在 Spec 顶层：
+
+| 需求 | 正确位置 | 常见错误 |
+| --- | --- | --- |
+| 坐标轴标题 | `xAxis.title`、`yAxis.title` | `encoding.x.title`、`encoding.y.title` |
+| 坐标轴格式 | `xAxis.format`、`yAxis.format` | `encoding.x.format`、`encoding.y.format` |
+| 数据标签 | `labels.enabled`、`labels.format` | `encoding.labels` |
+| 图例 | `legend.visible` | `encoding.legend` |
+| 主题和配色 | `theme.mode`、`theme.preset`、`theme.palette` | 随意猜测 Series 颜色 |
+
+`validateSpec()` 会把这些错误位置报告为结构化警告，应先修复再展示。单系列笛卡尔图默认会把字段名作为图例；不需要时使用 `legend: { visible: false }`。
+
+### 当前坐标域限制
+
+数值型笛卡尔图表默认使用易读的纵轴域：`yAxis.nice` 默认为 `true`，`yAxis.ticks` 默认为 `"auto"`。需要固定范围时使用 `yAxis.domain: [min, max]`，例如 `{ domain: [0, 2000], ticks: 5 }` 可稳定生成五个标签；使用 `yAxis.nice: false` 可保留原始数据边界。`yAxis.format` 只负责格式化刻度显示，`yAxis.right` 支持同样的配置。Agent 可通过 `chart.getState().axes` 或 `chart.explain().axes` 获取原始域、计算域、刻度、步长和策略进行自检。分类/时间横轴的范围仍由数据记录推导，因此 `xAxis.min/max` 和 `xAxis.domain` 不支持。图表专用域配置仍包括：`gauge.domain`、`heatmap.colorScale.domain`、`radar.indicators[].min/max`；项目图表的日期范围当前由数据记录自动计算。
+
+图表通道是严格按类型定义的：笛卡尔图表使用 `x`/`y`，Pie/Funnel/Gauge 使用 `category`/`value`，Heatmap 使用 `x`/`y`/`color`，Radar 使用 `indicators[].field`。缺失字段或不支持的通道会校验失败；Gauge 必须声明 `domain`。新建图表可直接使用 `@taylorwong/ichartjs/recipes/minimal-specs` 中的最小目录。
+
+Agent 自检使用 `chart.getState().health` 和 `chart.explain().health`，其中包含 `ready`、`degraded`、`empty`、警告数、隐藏标签数、限制值数和已渲染标记数。`locale` 默认 `en-US`，需要中文输出时设置 `locale: "zh-CN"`，输入日期仍使用 ISO-8601。
+
 ## 品牌署名（Branding）默认行为
 
 - 默认 `branding: true`：在画面与所有导出产物（PNG/SVG/JSON）右下角同步出现 `Powered by iChart.js` 低对比度署名。
@@ -73,6 +101,8 @@ const headlessPng = await chart.exportAsync({ type: 'png' });
 
 不要虚构字段、单位、日期、依赖关系、日历规则或预测置信度。Radar 使用混合单位时必须提供显式 domain；Heatmap 必须区分缺失值和零；高基数占比数据优先使用 Bar 而不是 Pie。
 
+为了让 lineage 自检和联动更新稳定，建议每条输入记录提供稳定字符串 `id`。没有 `id` 时 Runtime 会使用 `record-0` 这类位置后备值，只适合本地展示，不应当视为持久业务身份。
+
 ## 完整示例
 
 ```bash

package/docs/agent/zh-CN/runtime-contract.md

@@ -10,10 +10,14 @@ getCapabilities → inspectData → planChart → 创建 Spec → validateSpec
 
 Agent 应优先使用 `getCapabilities()`，不要硬编码未声明的图表类型或操作。
 
+图表创建后的视觉设置使用 `getPreferenceCapabilities(chartType, { locale }) → chart.getPreferences() → validatePreferences(patch) → chart.setPreferences(patch, { source: 'agent' }) → chart.getState().preferences`。这样 Agent 与内置设置菜单始终使用同一份白名单契约。
+
 Iteration 8 通过 `getChartCapability(type)` 提供逐图表能力档案，包括必需数据角色、支持的交互、Renderer、功能状态、导出和建议限制。Agent 不应猜测未声明能力。
 
 `planChart(data, { intent, renderer })` 返回版本化规划结果：主选图表、备选项、置信度、原因、缺失字段、建议编码、假设、警告、不支持请求和安全下一步。规划不会虚构业务含义、单位、日期或缺失字段。
 
+未知 intent 还会返回 `intentKnown`、`intentSuggestions` 和 `fallbackUsed`。Spec 的通道按图表类型约束：笛卡尔图表是 `x`/`y`，Pie/Funnel/Gauge 是 `category`/`value`，Heatmap 是 `x`/`y`/`color`，Radar 字段位于 `indicators`。`validateSpec()` 会拒绝不支持的通道和缺失字段。Gauge 必须显式声明 `domain`，超出范围时会报告 `VALUE_CLAMPED`。
+
 `validateSpec()` 分开返回 `errors`、`warnings` 和 `normalizations`；诊断包含稳定代码、JSON 路径、期望值和修复建议。`chart.explain()` 返回编码、转换、交互、假设、警告、稳定记录血缘和无障碍摘要。
 
 ## 关键规则
@@ -23,6 +27,8 @@ Iteration 8 通过 `getChartCapability(type)` 提供逐图表能力档案，包
 - 布局和数据语义不依赖 Renderer。
 - 通用图表使用 `data.values`；Flow/Swimlane 使用 `nodes/edges/lanes`。
 - `svg` 适合 DOM 交互和可访问性；`canvas` 适合大量图元和绘制性能。
+- 数值纵轴默认使用易读域（`yAxis.nice: true`、`yAxis.ticks: "auto"`）；使用 `yAxis.domain: [min, max]` 固定范围，或使用 `yAxis.nice: false` 保留原始边界。Agent 可通过 `chart.getState().axes` 或 `chart.explain().axes` 自检原始域、计算域、刻度、步长和策略。分类/时间横轴的 `min/max` 和 `domain` 不支持，范围由数据确定。
+- `chart.getState().health` 和 `chart.explain().health` 提供 `ready`、`degraded` 或 `empty`，以及可渲染性、问题代码、警告数、隐藏标签数、限制值数和已渲染标记数。`locale` 默认 `en-US`，可设置 `zh-CN` 影响输出格式；输入日期应使用 ISO-8601 字符串。
 
 ## 品牌署名（Branding）
 
@@ -80,6 +86,6 @@ iChart.js 导出采用**双底层单源架构**，所有产物共享 `buildScene
 - `DOWNLOAD_HEADLESS`：`chart.download*()` 仅在浏览器有 DOM 时可用，无头用 `export`。
 - `EXPORT_TYPE_UNSUPPORTED`：不支持的导出类型。
 
-公共 API：`inspectData`、`normalizeData`、`planChart`、`recommend`、`validateSpec`、`createChart`、`getCapabilities`、`getChartCapability`、`chart.describe`、`chart.explain`、`chart.getState`、`chart.export`、`chart.exportAsync`、`chart.toDataURL`、`chart.toBlob`、`chart.download`、`chart.downloadPNG`、`chart.downloadSVG`、`chart.downloadJSON`。
+公共 API：`inspectData`、`normalizeData`、`planChart`、`recommend`、`validateSpec`、`createChart`、`getCapabilities`、`getChartCapability`、`getPreferenceCapabilities`、`validatePreferences`、`chart.describe`、`chart.explain`、`chart.getState`、`chart.getPreferences`、`chart.setPreferences`、`chart.resetPreferences`、`chart.selectEdges`、`chart.getSelectedEdgeIds`、`chart.deleteSelectedEdges`、`chart.export`、`chart.exportAsync`、`chart.toDataURL`、`chart.toBlob`、`chart.download`、`chart.downloadPNG`、`chart.downloadSVG`、`chart.downloadJSON`。
 
 实现位置：`src/index.mjs`、`src/spec.mjs`、`src/scene.mjs`、`src/renderer.mjs`、`src/plugin.mjs`、`src/scale.mjs`、`src/charts.mjs`、`src/capabilities.mjs`。

package/docs/agent/zh-CN/theme-guide.md

@@ -66,7 +66,11 @@ const chart = createChart({
   data: { values: rows },
   preferences: pagePreferences
 });
-mountChartSettings(chart, { locale: 'zh-CN' });
+const settings = mountChartSettings(chart, {
+  locale: 'zh-CN',
+  placement: 'auto',
+  preferredPlacements: ['right', 'top', 'bottom']
+});
 
 // Agent 对话也使用同一套 API。
 chart.setPreferences({
@@ -74,8 +78,36 @@ chart.setPreferences({
   typography: { scale: 1.15 },
   components: { grid: false }
 }, { source: 'agent' });
+
+// 宿主永久移除图表时同步销毁快捷设置浮层。
+settings.destroy();
+```
+
+快捷设置面板会通过 Portal 放到图表裁剪区域之外。自动定位优先使用按钮右侧，其次上侧、下侧；都无法完整容纳时限制在浏览器视口内。滚动时保持已经选定的方位并跟随按钮，不再被视口约束拉回；图表或菜单按钮离开视口时直接关闭。窗口缩放和内容变化时可以重新计算方位。
+
+### Agent 配置发现与验证
+
+Agent 不应硬编码菜单选项，应先调用 `getPreferenceCapabilities(chartType, { locale })`。该接口会返回每个偏好字段的类型、默认值、候选值、作用域、当前图表适用性和 `menu.visible` 状态；对话调整和宿主自定义设置页应使用同一份契约。
+
+```js
+import { getPreferenceCapabilities, validatePreferences } from '@taylorwong/ichartjs';
+
+const capabilities = getPreferenceCapabilities(chart.getSpec().type, { locale: 'zh-CN' });
+const menuFields = capabilities.fields.filter(field => field.menu.visible);
+const current = chart.getPreferences();
+const patch = {
+  theme: { preset: 'dashboard', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+};
+const checked = validatePreferences(patch, { partial: true });
+if (!checked.valid) throw new Error(JSON.stringify(checked.errors));
+chart.setPreferences(checked.value, { scope: 'chart', source: 'agent' });
+const applied = chart.getState().preferences;
 ```
 
+快捷菜单字段为 `theme.mode`、`theme.palette`、`typography.scale`，以及当前图表支持的 `components.legend`、`components.labels`、`components.grid`。完整白名单另外包含 `theme.preset`、`density`、`branding.enabled` 和 `motion`。无法识别语言时默认返回英文。
+
 单图表快捷菜单使用紧凑的汉堡图标，只保留高频操作：主题模式、配色、字号，以及当前图表真正支持的图例、数据标签和网格线。能力检测会自动隐藏无效设置；修改即时生效，并支持 `zh-CN`、`en` 和按文档语言自动识别。
 
 低频选项和页面级配置应放在图表弹出菜单之外的独立设置页。页面内图表共享同一个 store，并使用 `store.setGlobal()` 或 `chart.setPreferences(patch, { scope: 'global' })` 更新全局。完整设置页可提供 preset、密度、署名等白名单能力，而不挤占每张图表。Node/SSR 默认使用内存，浏览器需要显式选择 `localStorage` 或宿主存储适配器。快捷菜单验收地址：`http://localhost:3000/playground/project-gallery.html`；完整页面设置验收地址：`http://localhost:3000/playground/preferences-lab.html`。

package/docs/agent/zh-CN/usage-scenarios.md

@@ -116,7 +116,7 @@ npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --ye
 需要固定发布版本时，直接安装已发布的 Skill 目录：
 
 ```bash
-npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs \
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.8/skills/ichartjs \
   --agent codex --global --yes
 ```
 
@@ -150,6 +150,8 @@ Agent 可以创建一个 ESM 脚本或独立 HTML 页面，输出：
 - `gantt`、`timeline`、`milestone`、`burndown`：项目进度和交付计划；
 - 项目分析：capacity、velocity、release forecast、risk、issue aging；
 - `flow`、`swimlane`：流程、责任、分组、Port 和受控编辑。
+- `architecture`：业务、数据或技术架构，使用明确的层、边界和关系。
+- `mindmap`：想法层级，以 `parentId` 为事实来源，支持树形或放射布局。
 
 保留稳定的 record、node、edge、lane、group、port ID。业务编辑先返回 preview，确认后再 commit，并返回审计结果。
 

package/docs/manifests/capabilities.json

@@ -8,15 +8,45 @@
   "agentQuickstart": "docs/agent/quickstart.md",
   "usageScenarios": "docs/agent/usage-scenarios.md",
   "agentWorkflowExample": "examples/agent-workflow.mjs",
+  "minimalSpecs": "@taylorwong/ichartjs/recipes/minimal-specs",
   "officialSkill": "skills/ichartjs/SKILL.md",
   "scenarios": {
     "charting": ["line", "area", "bar", "column", "pie", "scatter", "funnel", "gauge", "heatmap", "radar"],
     "project": ["gantt", "timeline", "milestone", "burndown"],
-    "diagram": ["flow", "swimlane"]
+    "diagram": ["flow", "swimlane", "architecture", "mindmap"]
   },
   "projectIntelligence": ["variance", "capacity", "release", "risk", "aging"],
-  "chartModes": ["stacked", "percent-stacked", "donut", "mixed-line-column", "bin"],
+  "chartModes": ["stacked", "percent-stacked", "donut", "mixed-line-column", "bin", "architecture-layers", "architecture-boundaries", "mindmap-tree", "mindmap-radial", "mindmap-curved-edges"],
   "renderers": ["canvas", "svg"],
+  "locale": {
+    "default": "en-US",
+    "recommended": ["en-US", "zh-CN"],
+    "appliesTo": ["axis", "labels", "tooltip", "export"],
+    "inputDates": "ISO-8601 strings; natural-language date parsing is not supported."
+  },
+  "health": {
+    "state": ["ready", "degraded", "empty"],
+    "apis": ["chart.getState().health", "chart.explain().health"],
+    "metrics": ["warnings", "suppressedLabels", "clampedValues", "renderedMarks"]
+  },
+  "interactionDefaults": { "zoom": false, "pan": false, "brush": false, "drag": false, "edgeDrag": false, "portConnect": false, "editing": false },
+  "diagramEditing": {
+    "renderers": ["canvas", "svg"],
+    "edgeSelection": true,
+    "waypointDrag": true,
+    "segmentDrag": true,
+    "persistentWaypoints": true,
+    "enabledByDefault": false,
+    "activation": ["editing.enabled", "interaction.edgeDrag"]
+  },
+  "diagramCurves": {
+    "renderers": ["canvas", "svg"],
+    "type": "cubic-bezier",
+    "mindmapDefault": true,
+    "curveTension": { "minimum": 0.2, "maximum": 0.8, "default": 0.4 },
+    "obstacleFallback": "orthogonal",
+    "controlPointEditing": false
+  },
   "excluded": ["map", "3d"],
   "exports": ["png", "svg", "json"],
   "headless": {
@@ -65,8 +95,17 @@
     "version": "1.0",
     "scopes": ["global", "chart"],
     "persistence": ["memory", "localStorage", "adapter"],
+    "fields": ["theme.mode", "theme.preset", "theme.palette", "typography.scale", "density", "components.legend", "components.labels", "components.grid", "branding.enabled", "motion"],
     "agentAdjustable": true,
-    "interactiveSettingsUI": true
+    "interactiveSettingsUI": true,
+    "precedence": ["defaults", "global", "chart", "temporary-agent-patch"],
+    "discovery": {
+      "capabilities": "getPreferenceCapabilities(chartType?, { locale? })",
+      "current": "chart.getPreferences()",
+      "validate": "validatePreferences(patch, { partial: true })",
+      "apply": "chart.setPreferences(patch, { scope, source: 'agent' })",
+      "verify": "chart.getState().preferences"
+    }
   },
   "styleSystem": {
     "modes": ["auto", "light", "dark", "contrast"],

package/docs/manifests/commands.json

@@ -2,27 +2,28 @@
   "version": "1.0",
   "source": "src/command.mjs#operationTypes",
   "commands": {
-    "updateField": { "models": ["project-task", "timeline-event", "milestone", "burndown-sample", "flow-node", "flow-edge", "swimlane"], "previewRequired": true, "undoable": true },
-    "updateRecord": { "models": ["project-task", "timeline-event", "milestone", "burndown-sample", "flow-node", "flow-edge", "swimlane"], "previewRequired": true, "undoable": true },
+    "updateField": { "models": ["project-task", "timeline-event", "milestone", "burndown-sample", "flow-node", "flow-edge", "swimlane", "architecture-node", "architecture-edge", "mindmap-node"], "previewRequired": true, "undoable": true },
+    "updateRecord": { "models": ["project-task", "timeline-event", "milestone", "burndown-sample", "flow-node", "flow-edge", "swimlane", "architecture-node", "architecture-edge", "mindmap-node"], "previewRequired": true, "undoable": true },
     "updateTask": { "models": ["project-task"], "previewRequired": true, "undoable": true },
     "shiftTask": { "models": ["project-task"], "required": ["taskId", "days"], "previewRequired": true, "undoable": true },
     "updateProgress": { "models": ["project-task"], "required": ["taskId", "progress"], "previewRequired": true, "undoable": true },
     "addDependency": { "models": ["project-task"], "required": ["taskId", "dependencyId"], "previewRequired": true, "undoable": true },
     "removeDependency": { "models": ["project-task"], "required": ["taskId", "dependencyId"], "previewRequired": true, "undoable": true },
     "updateMilestone": { "models": ["milestone"], "required": ["recordId"], "previewRequired": true, "undoable": true },
-    "moveNode": { "models": ["flow-node"], "required": ["nodeId", "position"], "previewRequired": true, "undoable": true },
-    "moveNodes": { "models": ["flow-node"], "required": ["nodeIds", "delta"], "previewRequired": true, "undoable": true },
+    "moveNode": { "models": ["flow-node", "architecture-node", "mindmap-node"], "required": ["nodeId", "position"], "previewRequired": true, "undoable": true },
+    "moveNodes": { "models": ["flow-node", "architecture-node", "mindmap-node"], "required": ["nodeIds", "delta"], "previewRequired": true, "undoable": true },
     "moveNodeToLane": { "models": ["flow-node"], "required": ["nodeId", "laneId"], "previewRequired": true, "undoable": true },
-    "resizeNode": { "models": ["flow-node"], "required": ["nodeId", "size"], "previewRequired": true, "undoable": true },
-    "alignNodes": { "models": ["flow-node"], "required": ["nodeIds", "alignment"], "previewRequired": true, "undoable": true },
-    "snapNodes": { "models": ["flow-node"], "required": ["nodeIds"], "previewRequired": true, "undoable": true },
+    "resizeNode": { "models": ["flow-node", "architecture-node", "mindmap-node"], "required": ["nodeId", "size"], "previewRequired": true, "undoable": true },
+    "alignNodes": { "models": ["flow-node", "architecture-node", "mindmap-node"], "required": ["nodeIds", "alignment"], "previewRequired": true, "undoable": true },
+    "snapNodes": { "models": ["flow-node", "architecture-node", "mindmap-node"], "required": ["nodeIds"], "previewRequired": true, "undoable": true },
     "moveGroup": { "models": ["flow-node"], "required": ["groupId", "delta"], "previewRequired": true, "undoable": true },
     "resizeGroup": { "models": ["flow-node"], "required": ["groupId", "size"], "previewRequired": true, "undoable": true },
     "assignNodesToGroup": { "models": ["flow-node"], "required": ["nodeIds", "groupId"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
     "duplicateGroup": { "models": ["flow-node", "flow-edge"], "required": ["groupId"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
     "deleteGroup": { "models": ["flow-node", "flow-edge"], "required": ["groupId", "policy"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
-    "updateEdge": { "models": ["flow-edge"], "required": ["edgeId", "changes"], "previewRequired": true, "undoable": true },
-    "addEdge": { "models": ["flow-edge"], "required": ["from", "to"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
+    "updateEdge": { "models": ["flow-edge", "architecture-edge"], "required": ["edgeId", "changes"], "previewRequired": true, "undoable": true },
+    "removeEdge": { "models": ["flow-edge", "architecture-edge"], "required": ["edgeId"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
+    "addEdge": { "models": ["flow-edge", "architecture-edge"], "required": ["from", "to"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
     "toggleGroupCollapse": { "models": ["flow-node"], "required": ["groupId"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
     "duplicateSelection": { "models": ["flow-node", "flow-edge"], "required": ["nodeIds"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
     "pasteSelection": { "models": ["flow-node", "flow-edge"], "required": ["nodes"], "previewRequired": true, "confirmationRequired": true, "undoable": true }

package/docs/manifests/schemas.json

@@ -7,7 +7,10 @@
     "milestone": { "key": "id", "required": ["id", "title", "date"], "editable": ["title", "date", "status"] },
     "burndown-sample": { "key": "id", "required": ["id", "date", "remaining"], "editable": ["date", "remaining", "scopeChange"] },
     "flow-node": { "key": "id", "required": ["id", "label"], "editable": ["label", "position", "size", "laneId", "description", "status"] },
-    "flow-edge": { "key": "id", "required": ["id", "from", "to"], "editable": ["from", "to", "label"] },
-    "swimlane": { "key": "id", "required": ["id", "label"], "editable": ["label"] }
+    "flow-edge": { "key": "id", "required": ["id", "from", "to"], "editable": ["from", "to", "fromPort", "toPort", "label", "status", "routing", "curveTension", "waypoints"] },
+    "swimlane": { "key": "id", "required": ["id", "label"], "editable": ["label"] },
+    "architecture-node": { "key": "id", "required": ["id", "label"], "editable": ["label", "layerId", "boundaryId", "position", "size", "description", "status"] },
+    "architecture-edge": { "key": "id", "required": ["id", "from", "to"], "editable": ["from", "to", "label", "relation", "routing", "curveTension", "waypoints", "status"] },
+    "mindmap-node": { "key": "id", "required": ["id", "label"], "editable": ["label", "parentId", "position", "size", "branch", "description", "status"] }
   }
 }

package/examples/agent-workflow.mjs

@@ -57,6 +57,7 @@ export function runAgentWorkflow(rows, options = {}) {
   try {
     const explanation = chart.explain();
     const state = chart.getState();
+    const expectedRecordIds = rows.map((row, index) => String(row.id ?? row.key ?? `record-${index}`));
     return {
       ok: true,
       stage: 'complete',
@@ -69,7 +70,7 @@ export function runAgentWorkflow(rows, options = {}) {
       state,
       selfCheck: {
         chartDeclared: capabilities.chartTypes.includes(plan.primary),
-        recordIdsPreserved: rows.every(row => explanation.lineage.recordIds.includes(row.id)),
+        recordIdsPreserved: expectedRecordIds.every(recordId => explanation.lineage.recordIds.includes(recordId)),
         warningsVisible: plan.warnings.every(warning => state.warnings.some(item => item.code === warning.code)),
         styleExplained: explanation.style?.preset === plan.styleRecommendation.preset
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taylorwong/ichartjs",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "Agent-first, renderer-independent charting and project visualization runtime",
   "type": "module",
   "main": "./src/index.mjs",

package/skills/ichartjs/SKILL.md

@@ -21,7 +21,7 @@ Recommended installation:
 npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
-Use `--agent codex --global --yes` for global non-interactive Codex installation. Use the tagged directory `https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs` when reproducibility matters. WorkBuddy can import the same directory through its Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it.
+Use `--agent codex --global --yes` for global non-interactive Codex installation. Use the tagged directory `https://github.com/wanghetommy/ichartjs/tree/v2.0.8/skills/ichartjs` when reproducibility matters. WorkBuddy can import the same directory through its Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it.
 
 The Skill is a workflow adapter, not the chart runtime. If the current JavaScript or TypeScript project does not already depend on iChart.js, install the matching runtime from GitHub:
 
@@ -36,14 +36,18 @@ Do not install the unscoped npm registry package named `ichartjs`; it is current
 1. Locate the package or repository root. Read `docs/agent/quickstart.md` when available.
 2. Call `getCapabilities()` before selecting a chart or interaction.
 3. Call `inspectData()` and preserve stable record IDs.
-4. Call `planChart(data, { intent, renderer, context })` and inspect the complete result, including `styleRecommendation`.
-5. Stop when `requiredFields` is non-empty; request data or explain a supported alternative.
-6. Build a JSON-serializable Spec using `suggestedEncodings`, the selected capability, and an applicable recipe.
-7. Call `validateSpec()` before rendering. Repair only from structured diagnostics.
-8. Call `createChart()` only after validation succeeds.
-9. Self-check with `chart.explain()`, `chart.getState()`, and JSON export.
-10. Provide an exact preview URL or artifact path and report assumptions, warnings, and deferred checks.
-11. Prefer `theme: { mode: 'auto', preset, palette }`; preserve explicit user style choices and use `chart.setTheme()` for live switching.
+4. Discover `getCapabilities().intents`; map natural-language requests to an exact registered token before calling `planChart(data, { intent, renderer, context })`.
+5. Inspect the complete planning result, including `styleRecommendation`, warnings, and fallback status.
+6. Stop when `requiredFields` is non-empty; request data or explain a supported alternative.
+7. Build a JSON-serializable Spec using `suggestedEncodings`, the selected capability, and an applicable recipe.
+8. Use chart-specific channels: Cartesian `x`/`y`, Pie/Funnel/Gauge `category`/`value`, Heatmap `x`/`y`/`color`, and Radar `indicators[].field`. Start from `@taylorwong/ichartjs/recipes/minimal-specs` when a type is unfamiliar.
+9. Keep titles/formats under `xAxis`/`yAxis`, labels under `labels`, and legend under `legend`; do not place them inside `encoding`.
+10. Call `validateSpec()` before rendering. Repair `UNSUPPORTED_ENCODING_CHANNEL`, `MISSING_ENCODING_FIELD`, `MISSING_GAUGE_DOMAIN`, `UNKNOWN_INTENT`, misplaced-option, and unsupported-axis warnings before presenting the chart.
+11. Call `createChart()` only after validation succeeds. Gauge Specs must declare a meaningful `domain`.
+12. Self-check with `chart.explain()`, `chart.getState()`, `health.renderable`, and JSON export. Treat `VALUE_CLAMPED`, `LABELS_SUPPRESSED`, and `ZERO_TOTAL` as material diagnostics to report.
+12. Provide an exact preview URL or artifact path and report assumptions, warnings, and deferred checks.
+13. Prefer `theme: { mode: 'auto', preset, palette }`; preserve explicit user style choices and use `chart.setTheme()` for live switching.
+14. For post-creation visual changes, call `getPreferenceCapabilities(chartType, { locale })`, validate the patch with `validatePreferences()`, apply it with `chart.setPreferences(..., { source: 'agent' })`, and verify `chart.getState().preferences`.
 
 Use `@taylorwong/ichartjs` for package imports. Use `examples/agent-workflow.mjs` as the executable baseline when working in the repository.
 
@@ -68,9 +72,15 @@ Route by requested output:
 
 - Never invent fields, units, dates, dependencies, calendar rules, domains, or forecast confidence.
 - Never silently drop validation errors, warnings, assumptions, normalizations, or unsupported requests.
+- Treat `getCapabilities().intents` as an allowlist; never pass a natural-language sentence as `planChart().intent`.
+- If planning returns `fallbackUsed: true`, use `intentSuggestions` to remap or ask for confirmation; never silently accept the fallback chart.
+- Keep axis titles/formats under `xAxis`/`yAxis`, labels under `labels`, and legend settings under `legend`.
+- Repair `UNKNOWN_INTENT`, misplaced-option, and unsupported-axis warnings before presenting a chart. For numeric y-axes, prefer the default readable domain; use `yAxis.domain: [min, max]` for an explicit range, `yAxis.nice: false` for raw boundaries, and `yAxis.ticks` for a stable label count.
+- Add stable string `id` values to tabular rows when lineage or linked updates are part of the deliverable.
 - Avoid Pie for high-cardinality categories; prefer Bar for comparison.
 - Require explicit Radar domains when units differ.
 - Distinguish missing Heatmap values from zero.
+- Set `locale` explicitly when output needs localization; the default is `en-US`, and input dates must be ISO-8601 strings.
 - Use categorical, sequential, diverging, or status palettes by data semantics; do not invent arbitrary color sets or rely on color alone.
 - Surface theme contrast diagnostics and high-cardinality color warnings.
 - Do not generate Map or 3D Specs unless capabilities explicitly add them.