minimal-agent 0.18.5 → 0.18.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.18.5",
+  "version": "0.18.7",
   "description": "Bun-first 的本地 Agent 内核，支持工具、插件、工作流、上下文压缩、长期记忆与 OpenAI 兼容接口；Tauri 桌面宿主和 Node.js npm 发布可复用同一内核",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

package/plugins/workflow-runner/src/runtime/context.js

@@ -29,7 +29,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { dirname, isAbsolute, resolve } from 'node:path';
-import { ALL_TOOLS, createAgentRuntimeContext, isReadOnlyShellCommand, parseCheckString, recordRead, resolveProviderForModel, resolveProviderForWorkflowRole, runQuery, chat as sdkChat, runVerification, executeTool as sdkExecuteTool, stripThinkBlocks, } from '../../../../src/plugin-sdk.js';
+import { ALL_TOOLS, createAgentRuntimeContext, parseCheckString, recordRead, resolveProviderForModel, resolveProviderForWorkflowRole, runQuery, chat as sdkChat, runVerification, executeTool as sdkExecuteTool, stripThinkBlocks, } from '../../../../src/plugin-sdk.js';
 import { withGoalAnchor } from '../goalAnchor.js';
 import { MAIN_LANE } from '../journal.js';
 import { extractJsonPayload } from '../jsonPayload.js';
@@ -401,8 +401,7 @@ export function createWorkflowContext(deps) {
             : opts.allowedTools.filter((n) => hostTools.has(n));
         const toolByName = new Map((ctx.tools ?? []).map((tool) => [tool.name, tool]));
         const allowed = opts.toolMode === 'read-only'
-            ? requested.filter((name) => name === 'Bash' ||
-                name === 'PowerShell' ||
+            ? requested.filter((name) => name !== 'Bash' && name !== 'PowerShell' &&
                 toolByName.get(name)?.isReadOnly === true)
             : requested;
         // ⚠️ 过滤掉的名字必须报出来，而且要**区分两种原因** ——
@@ -443,7 +442,7 @@ export function createWorkflowContext(deps) {
                 `本节点实际可用工具只有：${allowed.length ? allowed.join('、') : '无'}。`,
                 '宿主系统提示或既往历史中提及的其他工具不属于本节点，不得调用。',
                 opts.toolMode === 'read-only'
-                    ? '本节点严格只读：不得创建、覆盖、修改、移动或删除文件；Bash/PowerShell 也只能执行只读查询。完成调查后直接返回事实报告。'
+                    ? '本节点严格只读：不得创建、覆盖、修改、移动或删除文件；使用 Read/Glob/Grep 等只读工具，不提供 Bash/PowerShell 通用执行。完成调查后直接返回事实报告。'
                     : '',
             ].filter(Boolean).join('\n')
             : '';
@@ -700,20 +699,9 @@ export function createWorkflowContext(deps) {
         recovery: 'change-input',
         sensitivity: 'public',
     });
-    const readOnlyDenial = (name, rawArgs) => {
+    const readOnlyDenial = (name, _rawArgs) => {
         if (name === 'Bash' || name === 'PowerShell') {
-            let command = '';
-            try {
-                const parsed = JSON.parse(rawArgs);
-                if (typeof parsed.command === 'string')
-                    command = parsed.command;
-            }
-            catch {
-                return readOnlyFailure(name, '命令参数不是合法 JSON');
-            }
-            return !command || !isReadOnlyShellCommand(command)
-                ? readOnlyFailure(name, '命令可能产生副作用；请改用 Read/Glob/Grep 或只读查询命令')
-                : undefined;
+            return readOnlyFailure(name, '通用 Shell 无法保证严格只读；请改用 Read/Glob/Grep，或在获准执行的节点运行命令');
         }
         return ctx.tools.find((tool) => tool.name === name)?.isReadOnly !== true
             ? readOnlyFailure(name, '该工具不是只读工具')

package/plugins/workflow-runner/src/runtime/context.ts

@@ -42,7 +42,6 @@ import type {
 import {
   ALL_TOOLS,
   createAgentRuntimeContext,
-  isReadOnlyShellCommand,
   parseCheckString,
   recordRead,
   resolveProviderForModel,
@@ -640,8 +639,7 @@ export function createWorkflowContext(deps: ApiDeps): WorkflowContext {
     const toolByName = new Map((ctx.tools ?? []).map((tool) => [tool.name, tool]));
     const allowed = opts.toolMode === 'read-only'
       ? requested.filter((name) =>
-          name === 'Bash' ||
-          name === 'PowerShell' ||
+          name !== 'Bash' && name !== 'PowerShell' &&
           toolByName.get(name)?.isReadOnly === true)
       : requested;
 
@@ -682,7 +680,7 @@ export function createWorkflowContext(deps: ApiDeps): WorkflowContext {
           `本节点实际可用工具只有：${allowed.length ? allowed.join('、') : '无'}。`,
           '宿主系统提示或既往历史中提及的其他工具不属于本节点，不得调用。',
           opts.toolMode === 'read-only'
-            ? '本节点严格只读：不得创建、覆盖、修改、移动或删除文件；Bash/PowerShell 也只能执行只读查询。完成调查后直接返回事实报告。'
+            ? '本节点严格只读：不得创建、覆盖、修改、移动或删除文件；使用 Read/Glob/Grep 等只读工具，不提供 Bash/PowerShell 通用执行。完成调查后直接返回事实报告。'
             : '',
         ].filter(Boolean).join('\n')
       : '';
@@ -952,18 +950,9 @@ export function createWorkflowContext(deps: ApiDeps): WorkflowContext {
     sensitivity: 'public' as const,
   });
 
-  const readOnlyDenial = (name: string, rawArgs: string) => {
+  const readOnlyDenial = (name: string, _rawArgs: string) => {
     if (name === 'Bash' || name === 'PowerShell') {
-      let command = '';
-      try {
-        const parsed = JSON.parse(rawArgs) as { command?: unknown };
-        if (typeof parsed.command === 'string') command = parsed.command;
-      } catch {
-        return readOnlyFailure(name, '命令参数不是合法 JSON');
-      }
-      return !command || !isReadOnlyShellCommand(command)
-        ? readOnlyFailure(name, '命令可能产生副作用；请改用 Read/Glob/Grep 或只读查询命令')
-        : undefined;
+      return readOnlyFailure(name, '通用 Shell 无法保证严格只读；请改用 Read/Glob/Grep，或在获准执行的节点运行命令');
     }
     return ctx.tools.find((tool) => tool.name === name)?.isReadOnly !== true
       ? readOnlyFailure(name, '该工具不是只读工具')

package/plugins/workflow-runner/src/runtime/model.js

@@ -32,6 +32,8 @@ export class ModelExecutionOutcome {
                 code: event.code ?? 'execution_error',
                 message: event.error,
             };
+        if ((event.type === 'error' || event.type === 'interrupted') && event.usage)
+            this.usage = event.usage;
         if (event.type === 'interrupted')
             this.interrupted = true;
         if (event.type === 'turn_done') {
@@ -40,8 +42,8 @@ export class ModelExecutionOutcome {
                 !event.completionStatus || event.completionStatus === 'completed';
             if (!this.completed)
                 this.failure ??= {
-                    code: 'delivery_incomplete',
-                    message: '阶段未正常完成交付',
+                    code: event.completionStatus === 'no_answer' ? 'no_answer' : 'delivery_incomplete',
+                    message: event.completionStatus === 'no_answer' ? '模型没有产出最终答复；已有进展保留供恢复，不作为成功结果。' : '阶段未正常完成交付',
                 };
         }
     }

package/plugins/workflow-runner/src/runtime/model.ts

@@ -46,6 +46,7 @@ export class ModelExecutionOutcome {
         code: event.code ?? 'execution_error',
         message: event.error,
       };
+    if ((event.type === 'error' || event.type === 'interrupted') && event.usage) this.usage = event.usage;
     if (event.type === 'interrupted') this.interrupted = true;
     if (event.type === 'turn_done') {
       this.usage = event.usage;
@@ -53,8 +54,8 @@ export class ModelExecutionOutcome {
         !event.completionStatus || event.completionStatus === 'completed';
       if (!this.completed)
         this.failure ??= {
-          code: 'delivery_incomplete',
-          message: '阶段未正常完成交付',
+          code: event.completionStatus === 'no_answer' ? 'no_answer' : 'delivery_incomplete',
+          message: event.completionStatus === 'no_answer' ? '模型没有产出最终答复；已有进展保留供恢复，不作为成功结果。' : '阶段未正常完成交付',
         };
     }
   }

package/plugins/workflow-runner/test/api.test.ts

@@ -112,9 +112,11 @@ describe('零工具调用信号（announce-not-do）', () => {
     expect(out).toBe('minor'); // 正常返回，没有因为零工具调用而失败
   });
 
-  test('产出为空时不报 —— 那是另一类问题（空答），不是 announce-not-do', async () => {
+  test('空答明确失败，但不误报为 announce-not-do', async () => {
     const h = await harness(textOnlyChat('   '));
-    await h.globals.model.agent('干点什么');
+    await expect(h.globals.model.agent('干点什么')).rejects.toMatchObject({
+      name: 'WorkflowModelError', code: 'no_answer', recovery: { partialText: '' },
+    });
     expect(h.progress()).not.toContain('零工具调用');
   });
 

package/plugins/workflow-runner/test/embeddedExecution.test.ts

@@ -226,7 +226,7 @@ test('read-only node hides write tools and rejects fabricated Write plus mutatin
       if (round++ === 0) {
         const names = requestTools?.map((tool) => tool.name) ?? [];
         expect(names).toContain('Read');
-        expect(names).toContain('Bash');
+        expect(names).not.toContain('Bash');
         expect(names).not.toContain('Write');
         expect(JSON.stringify(messages)).toContain('工作流节点工具边界');
         expect(JSON.stringify(messages)).toContain('本节点严格只读');
@@ -252,7 +252,6 @@ test('read-only node hides write tools and rejects fabricated Write plus mutatin
         return;
       }
       const transcript = JSON.stringify(messages);
-      expect(transcript).toContain('当前工作流节点为只读');
       expect(transcript).toContain('不在当前工作流节点的有效工具集中');
       yield { type: 'text_delta', delta: '只读调查完成' };
       yield { type: 'done', stopReason: 'stop' };
@@ -281,13 +280,13 @@ test('read-only node hides write tools and rejects fabricated Write plus mutatin
     h.events.some(
       (event) =>
         event.type === 'warning' &&
-        String(event.message).includes('已移除写工具：Write'),
+        String(event.message).includes('已移除写工具：Bash、Write'),
     ),
   ).toBe(true);
   await h.state.flush();
 });
 
-test('read-only node still executes Bash commands classified as read-only', async () => {
+test('strict read-only node rejects even apparently read-only shell commands', async () => {
   let round = 0;
   const executed: string[] = [];
   const gateRequests: { name: string; isReadOnly: boolean }[] = [];
@@ -325,8 +324,8 @@ test('read-only node still executes Bash commands classified as read-only', asyn
       isolated: true,
     }),
   ).resolves.toBe('done');
-  expect(executed).toEqual(['Bash']);
-  expect(gateRequests).toEqual([{ name: 'Bash', isReadOnly: true }]);
+  expect(executed).toEqual([]);
+  expect(gateRequests).toEqual([]);
   await h.state.flush();
 });
 

package/plugins/workflow-runner/test/modelOutcome.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from 'bun:test';
+import { ModelExecutionOutcome, WorkflowModelError } from '../src/runtime/model.js';
+
+test('no_answer fails with recovery evidence and never becomes a successful node value', () => {
+  const outcome = new ModelExecutionOutcome();
+  outcome.observe({ type: 'turn_done', completionStatus: 'no_answer' });
+  expect(outcome.completed).toBe(false);
+  try {
+    outcome.assertSuccess('已有进展', ['Read'], ['report.md']);
+    throw new Error('Expected failure');
+  } catch (error) {
+    expect(error).toBeInstanceOf(WorkflowModelError);
+    expect((error as WorkflowModelError).code).toBe('no_answer');
+    expect((error as WorkflowModelError).recovery).toMatchObject({ partialText: '已有进展', toolNames: ['Read'], artifacts: ['report.md'] });
+  }
+});
+
+test('an empty answer does not overwrite provider errors or cancellation', () => {
+  const failed = new ModelExecutionOutcome();
+  failed.observe({ type: 'error', code: 'llm_error', error: 'provider failed' });
+  failed.observe({ type: 'turn_done', completionStatus: 'no_answer' });
+  expect(failed.failure?.code).toBe('llm_error');
+  const cancelled = new ModelExecutionOutcome();
+  cancelled.observe({ type: 'interrupted', reason: 'manual' });
+  cancelled.observe({ type: 'turn_done', completionStatus: 'no_answer' });
+  expect(() => cancelled.assertSuccess('', [], [])).toThrow('阶段执行已中断');
+});
+
+test('completed stays successful; other incomplete states keep their failure', () => {
+  const completed = new ModelExecutionOutcome();
+  completed.observe({ type: 'turn_done', completionStatus: 'completed' });
+  expect(() => completed.assertSuccess('报告', [], [])).not.toThrow();
+  const incomplete = new ModelExecutionOutcome();
+  incomplete.observe({ type: 'turn_done', completionStatus: 'delivery_incomplete' });
+  expect(incomplete.failure?.code).toBe('delivery_incomplete');
+});

package/skills/dynamic-ui/SKILL.md

@@ -1,287 +1,47 @@
 ---
 name: dynamic-ui
-description: Desktop 回复需解释架构、工作流、状态转换、组件关系或数值趋势时主动使用紧凑 SVG，优先于大段 ASCII 框图；也用于文档配图。简单事实、一步命令和清晰表格不必画图；不做网站/App，终端纯问答不输出 SVG。
+description: 解释流程、架构、时序、状态关系时优先 Mermaid，定制布局或数据图用 SVG，替代大段 ASCII；适用于 Desktop/Web 回复和文档配图。CLI/TUI 直接显示用文字或表格，生成图形文件不受此限；简单回答不强制配图。
 ---
 
-# dynamic-ui —— 内联可视化 / 文档配图设计判断
+# 动态图示：先选载体，再选图形
 
-## 这份技能管什么，不管什么
+## 判断是否需要图
 
-管两件事：**该不该画一张图**，以及**画哪种图、怎么保证节点/连线/标签不重叠不脏**。
-不管：整份文档的配色/字阶/版式 VI 决策（那是 [ui-design](../ui-design/SKILL.md) 的活，见下一节）；
-不拥有任何专属渲染工具——本技能只产出一段 `<svg>...</svg>` 标记，由调用它的宿主或工具负责把这段
-标记放到最终产出物里（聊天回复的围栏代码块，或者正在写的文档文件）。
+图应让关系比文字更清楚，而不是装饰。简单事实、一步命令、短列表、清晰表格不画图。
+保留用户指定 ASCII、原样代码/目录树和紧凑的 A → B 表达。正文用一句话保留图的关键结论。
 
-## 先分流：你在哪个宿主
+## 输出载体
 
-Desktop 中一旦判断关系或流程值得画图，优先采用本技能的 SVG，而不是用字符拼接方框、树枝和连线。用户明确要求 ASCII、需要原样引用日志/代码/目录树时保留原格式；简单列表和 `A → B` 这样的紧凑表达无需转换。不要为减少 ASCII 而强制给每次回答配图。
-
-用一句正文保留图的关键结论，使无法看到图的用户仍能理解。图是解释，不是假按钮、执行状态或正式成果附件；真实状态来自工具事件，真实文件/网站仍按宿主交付机制提交。技能或图形渲染不可用时用文字/表格降级，不反复输出大段源码。
-
-每轮系统上下文里都有一行「宿主: `<surface>`」（`desktop`/`tui`/`cli`/`headless`/`workflow`/`subagent`
-之一），据此决定怎么交付：
-
-- **`desktop`**（minimal-desktop 聊天界面）：聊天气泡只认两种围栏代码块会被真正渲染——
-  ` ```mermaid `（另一套机制，不归本技能管）和 ` ```svg `（本技能）。除此之外，直接写在正文里的
-  裸 `<svg>`/`<div>` 会被 Markdown 渲染器（`react-markdown` 开了 `skipHtml`）**静默丢弃**——不是
-  显示不出来，是从回复里彻底消失，绝不要这样做。判断值得画图时，直接输出**一个** ` ```svg ` 围栏
-  代码块；不要在围栏前后旁白"我先画一个坐标系"之类的过程说明，围栏本身就是最终产物。
-- **`tui` / `cli` / `headless`**（终端）：没有任何图形渲染能力，SVG 字节原样打印到终端只会是一堆
-  乱码，绝不能往回复文本里塞 `svg` 围栏。这些宿主下本技能只在**你正在用 Write / docx / pptx 等
-  工具落盘一份文档、报告、幻灯片、作业讲义**时起作用——继续读下面的设计规则，把 SVG 片段嵌进正在
-  生成的那份文件；如果只是普通问答且没有落盘目标，判断 Markdown 表格/文字是否已经够用，够用就
-  不要额外画图，这不是本技能能交付的场景。
-- **`subagent` / `workflow`**：跟随发起它的宿主环境；拿不准时按"落盘文档"场景处理，不要把 SVG
-  写回文本回复。
-
-## 与 ui-design 的分工——别重复造轮子
-
-[ui-design](../ui-design/SKILL.md) 是这个项目里"样式与视觉设计"决策的统一入口：任何涉及整份
-文档/整套 deck 的配色、VI、字体字阶、版式布局，都应该先去那里定下来。本技能的职责窄得多：
-**这段内容值不值得画一张图、该画哪种图、怎么保证画出来的东西不重叠不脏**——是排版执行细节，
-不是设计系统决策。
-
-具体到颜色：下面「视觉 Token」表里的十六进制都是**兜底色**，不是权威色板。写文档、报告、幻灯片
-时，如果 ui-design 已经为这份产出物定出了品牌色，直接把兜底色整体换成那份色值；只有在 Desktop
-聊天场景（没有独立文档、没有 ui-design 介入的必要）才直接用表里给的兜底色。
-
-## 输出契约
-
-**两个宿主的根节点要求不一样，别弄混**：
-
-- **Desktop 内联围栏**（```svg 围栏块）：内容可以是一段纯 `<svg>...</svg>`，也可以是一段
-  静态的 HTML 卡片片段（比如 `comparison-cards` 那种带分隔线的卡片、徽标）——渲染层
-  （`SvgWidget.tsx`）只要求内容"看起来是标记"（以 `<` 开头），不强制根标签必须是
-  `<svg>`。两种情况都会被塞进一个独立的 Shadow DOM 宿主，类名不会跟同一会话里的其它围栏块
-  冲突。
-- **写进文档**（docx/pptx/独立 html 报告，当图片资源嵌入）：**必须是单一根节点的
-  `<svg>...</svg>`**——Word/PowerPoint 的图片嵌入管线需要一段真正的矢量图形，塞一段
-  `<div>` 卡片布局进去没有任何渲染器认得。如果一份文档里想要"卡片对比"这种排版，直接用
-  文档格式自己的表格/形状/文本框（参考 [ui-design](../ui-design/SKILL.md)/
-  [pptx](../pptx/SKILL.md)/[docx](../docx/SKILL.md)），不要试图把 HTML 卡片硬塞成"SVG"。
-  素材库里 `tree-flow`/`sequence-diagram` 这类图表类模板内部本来就是一个独立的
-  `<svg>...</svg>` 子树（外层 `<div class="widget">` 只是 Desktop 卡片外壳），写文档时把
-  这段内部 `<svg>` 单独抽出来即可；`comparison-cards`/`architecture-elements` 这类以 HTML
-  卡片为主的模板目前只适合 Desktop 内联场景，不要抽取硬塞进文档。
-
-不管落到哪种根节点，都不要 `<!DOCTYPE>`、`<html>`、`<head>`、`<body>`、注释、说明性文字混进
-这段标记内部。
-
-**没有任何一个宿主能执行 `<script>`**：Desktop 的 CSP 是 `script-src 'self'`，内联脚本和
-`onXxx` 事件属性本来就跑不起来；静态文档更不必说。因此：
-- 不产出 `<script>` 标签、不产出 `onclick`/`onload` 这类事件属性。
-- 不依赖 hover/click 才能看到的信息——数值、标签、图例这些关键信息必须直接画在图上常驻可见，
-  不能只在假想的交互态里出现。原技能里"局部交互/tooltip/toggle"的设想在这两个宿主下都不成立，
-  见 `scenes/micro-interaction.md` 里的替代做法。
-
-## 视觉 Token
-
-角色化 CSS 自定义属性，统一写法是 `var(--dui-<角色>, <字面量兜底值>)`。Desktop 环境下
-`--dui-*` 已经在 App 全局样式（`global.css`）里定义并跟随亮暗主题；脱离 Desktop 时（独立 SVG
-片段、嵌进文档、被人复制到别处）这些变量本来就不存在，`var()` 会直接落到兜底值——两种场景
-零特判，不要为文档场景另写一套字面量色板，只需要在有 ui-design 品牌色时替换兜底值本身。
-
-| 角色 | 写法 | 兜底值（= App 深色主题） | 用途 |
-|---|---|---|---|
-| 正文文字 | `var(--dui-text, #f4f1e7)` | #f4f1e7 | 图上主要文字 |
-| 次要文字 | `var(--dui-text-muted, #9fb0ae)` | #9fb0ae | 元数据、图例、说明、坐标轴 |
-| 弱化文字 | `var(--dui-text-faint, #6f8280)` | #6f8280 | 占位、禁用态、次要连线 |
-| 边框 | `var(--dui-border, rgba(238,241,235,.14))` | — | 卡片/面板描边 |
-| 表面 | `var(--dui-surface, #172321)` | — | 卡片/面板填充 |
-| 次表面 | `var(--dui-surface-muted, #1e2c29)` | — | 嵌套区域 |
-| 品牌色 | `var(--dui-brand, #c85f3d)` | — | 主焦点、主路径、推荐项 |
-| 强调色 | `var(--dui-accent, #2bb8c4)` | — | 次焦点、第二类目 |
-| 成功 | `var(--dui-success, #2bb8c4)` | — | 仅状态/风险语义时用 |
-| 警示 | `var(--dui-warning, #d9b354)` | — | 同上 |
-| 危险 | `var(--dui-danger, #d9645a)` | — | 同上 |
-| 系列 1 | `var(--dui-chart-series-1, #c85f3d)` | = 品牌色 | 同类并列数据源第 1 项 |
-| 系列 2 | `var(--dui-chart-series-2, #2bb8c4)` | | 第 2 项 |
-| 系列 3 | `var(--dui-chart-series-3, #d9b354)` | | 第 3 项 |
-| 系列 4 | `var(--dui-chart-series-4, #6fa87c)` | | 第 4 项 |
-| 系列其它 | `var(--dui-chart-other, #6f8280)` | | Top N + Other 的 Other |
-
-**品牌基线**：不默认紫色——那是原技能抄来的，不是这个项目的品牌。Desktop 环境下品牌色自动是
-App 自己的铁锈橙（`--accent`）；写文档时如果 ui-design 给了别的品牌色，把上表兜底值整体替换，
-不要还留着铁锈橙或紫色。
-
-字体：`font-family: var(--font, -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif)`
-（正文），`var(--mono, "Cascadia Code", "JetBrains Mono", Consolas, monospace)`（数值、代码风格
-标识）。
-
-间距/圆角/字号是纯字面量，不必变量化跨主题（结构性数值本来就不该跟着主题换）：
-- 间距：4 / 8 / 12 / 16 / 20 / 24px，用于 gap、padding、图例行距。
-- 圆角：8px 默认；12px 卡片；999px 胶囊/圆点。
-- 字号：12/18（说明文字，最小不低于 11px）、14/20（正文基线）、16/24（标题，不能再大）。
-
-## Scope
-
-用于：数值趋势、量级对比、构成/占比、分布、流程强度；模块关系、依赖图、流程图、状态转移、
-调用链、时间线/排期；方案对比、技术选型、风险摘要、决策矩阵；原理讲解、因果链；需要展示"切换前
-后/开关两态"这类状态对比但做不到真交互的场景（见 `scenes/micro-interaction.md`）。
-
-不用于：独立可运行的网站/App/交互原型（用 [ui-design](../ui-design/SKILL.md) 或
-[web-artifacts-builder](../web-artifacts-builder/SKILL.md)）；一次性事实、一步命令、Markdown
-表格已经足够清楚的内容；没有明确焦点的装饰性配图；`tui`/`cli`/`headless` 下没有落盘目标的纯
-聊天场景。
-
-## File Map
-
-`{{SKILL_DIR}}` 是本 `SKILL.md` 所在目录。
-
-```
-{{SKILL_DIR}}/
-├── SKILL.md              ← 唯一入口（本文件）
-├── scenes/                ← 场景指南（每个场景一个文件）
-│   ├── data-visualization.md
-│   ├── architecture-and-flow.md
-│   ├── comparison-and-decision.md
-│   ├── mechanism-explanation.md
-│   └── micro-interaction.md
-├── tokens/
-│   └── visual-tokens.md   ← 完整 token 定义（按需读取）
-└── templates/              ← 素材库（可复用原型示例）
-    ├── manifest.json
-    └── <template-id>/
-        ├── template.md         ← 素材说明（20-30 行）
-        ├── widget-code.html    ← 完整可用示例（纯 <svg>，无 <script>）
-        └── fixture.json        ← 示例数据
-```
-
-`templates/manifest.json` 里 `status` 字段如实标注：`ready` 表示已按本文档的静态 SVG 契约验证
-可用；`needs-static-rewrite` 表示 `widget-code.html` 还是旧版 Chart.js/`<script>` 悬浮提示交互
-实现，两个宿主都执行不了脚本，**暂不可用**——按 `template.md` 记录的设计意图手工画静态 SVG，
-或改用下面的回退基元，不要因为目录存在就当它能直接抄。
-
-## Visual Design 核心原则
-
-- **无缝** —— 用户不该看出宿主界面在哪结束、你画的图从哪开始。
-- **扁平** —— 不用渐变、噪点纹理、装饰性阴影，干净的平面。
-- **紧凑** —— 内联展示最关键的信息，其余留给正文文字。
-- **分离** —— 解释性文字放正文，图上只放视觉证据。
-- **图表就是图表** —— 图表类 widget 只画图表本身、可选的简短标题、以及坐标轴/图例/标签这些必要
-  的读图辅助；不要在图表 widget 里塞洞见、结论、建议或页脚文案。
-
-素材源：先读 `templates/manifest.json`，再读选中的 `templates/<id>/template.md`，再决定是否
-借用 `widget-code.html`/`fixture.json`。素材是参考范例，不是死板的固定布局。
-
-兜底规则：没有现成素材匹配时，自定义输出也必须选定一种紧凑原型（`chart-card`、
-`metric-strip-chart`、`node-flow`、`decision-cards`、`compact-table-visual`、
-`explanation-panel` 之一），并遵守与素材相同的 token、表面、密度、颜色优先级、字体、间距、
-圆角、焦点规则。自定义输出不能为了凑内容而发明新色板、新字号阶梯、新间距刻度、新圆角值。
-对于 SVG 流程图、架构图、框架图、关系图，只有在先做过一次简单的坐标规划、确认节点/标签/
-连线轨道/图例/徽标都能不重叠地放下之后，才允许走这条兜底路线。
-
-**焦点色**：颜色契约的优先级高于语义色猜测。先用中性表面/连线加 `--dui-brand`/
-`--dui-chart-series-*`；只有用户明确要求状态/风险/健康度编码，或数据字段本身就是状态/风险
-变量时，才用 `--dui-accent` 或语义色。"success/failure/warning/blocked/accepted/rejected"
-这类词本身不能自动带出绿/黄/红。
-
-**图表系列色**：同类数据源统一用 `--dui-chart-series-1` 到 `-4`；溢出/其它用
-`--dui-chart-other`。不要给普通数据源用彩虹色、语义色。5 个以上同级数据源应归组为 Top N +
-Other、拆成小倍图、或改用表格/列表。
-
-**图示分类**：结构用中性色，焦点/推荐用品牌色，次要类目用强调色。普通流程图/架构图/框架图/
-依赖图优先用中性+品牌色或图表系列色，而不是语义色。一张紧凑图最多 1-2 个有含义的颜色。连线
-本身不应用图示分类色。
-
-**连线**：默认中性 `--dui-text-faint` 或 `--dui-border`；主路径用 `--dui-brand`；只有明确标注
-的并列路径才用 `--dui-chart-series-*`；只有状态/风险是主要编码变量时才用语义连线色。流程图连线
-用平滑曲线/圆角折线，`stroke-linecap="round"`，`stroke-linejoin="round"`。一张图最多 2 种连线
-样式。方向箭头用统一的 marker：`viewBox="0 0 8 8"`、`refX="7"`、`refY="4"`、
-`markerWidth="8"`、`markerHeight="8"`、`markerUnits="userSpaceOnUse"`、`orient="auto"`，箭头
-路径 `M1 1 L7 4 L1 7 Z`，配合 `marker-end` 挂在代表连线本身的那条 path 上——不要用花括号、
-双曲线、独立三角形拼箭头。
-
-## Content Rules
-
-每张图只要一个清晰可见的焦点（推荐项、关键路径、瓶颈、最高值、阶段边界、风险标记），用位置、
-标签或一个强调色让它显眼，不要只靠颜色区分。
-
-文案密度：节点标签 2-5 个字/词；卡片标题 6-10 个字/词；副标题 ≤5 个字/词；连线标签 1-3 个字/
-词，能省则省。
-
-复杂度预算：1 个焦点，2-5 个主节点，2-4 个选项/KPI/系列，最多 1 个交互概念（在两个宿主下等价于
-"最多一种状态对比"，见 micro-interaction）。横向一排最多 4 个方框，5 个以上要归组/换行/拆分。
-自定义 SVG 图示保持 ≤6 个未分组节点、≤8 条连线，更大的结构要归组、拆面板、改表格，或直接用
-Markdown 回答。
-
-数据诚实：估算值要标注"约/估计"；数值保留一致的小数位；数字旁标单位；来源本身是粗略估计时不要
-显得像精确值。绝不画地图——按区域用条形图/表格/矩阵代替。
-
-## SVG Fundamentals
-
-出现 SVG、连线、流程图、架构图、结构图、机制示意图时都适用下面的几何规则。
-
-**ViewBox**：优先 `viewBox="0 0 720 H"`，`width="100%"`，`height="auto"`。安全边距 ≥40 设计
-单位或 viewBox 宽度的 6%（取更大值）。`H` 由最低可见图形/文字基线/连线加底部留白决定。不要用
-负坐标、不要为了塞下过长标签而收缩 viewBox、不要在底部留大片无法解释的空白、不要靠裁剪/背景块
-掩盖不合法的几何。
-
-**文字尺寸**：标签 14px（拉丁字符约 8px/字宽），元数据 12px（约 7px/字宽）。节点宽度 ≥
-max(标题字数×8, 副标题字数×7) + 24px 内边距。中文标签要比可用宽度短。代码风格字符串、数学
-符号、长标识符、混合文字要按 30-50% 放大宽度估算。
-
-**硬性拟合门槛**：在给每个可见文字标签、节点、连线标签、图例项、徽标、容器都估算出包围盒之前，
-不要画自定义 SVG。任何一个盒子放不下就先削减内容：缩短标签、归组节点、拆分图示、改成表格/列表，
-或直接用 Markdown 回答。不要用更小的字号、透明重叠、`overflow: hidden`、裁剪蒙版或背景矩形来
-替代一次真正合法的布局。
-
-**连线**：每条 path/polyline 都要 `fill="none"`，绕开无关节点。同一行相邻节点检查
-`left.x + left.width + gap <= right.x`，无关节点间距 ≥32，流程步骤间距 ≥60；同一列相邻节点
-检查 `top.y + top.height + gap <= bottom.y`，堆叠节点间距 ≥28，带连线标签时 ≥56。结构容器要
-先于内部节点放置，且必须留出可见内边距、不与标题/图例/外部输入输出碰撞。
-
-**画之前的静默自检**：viewBox 高度按最低元素+留白算出；所有内容落在 x=0..720 内；每个文字
-标签都留了内边距；任何带文字的 `<rect>`/面板/卡片/图例都按内容尺寸撑开容器并留出内边距；没有
-两个节点/标签/徽标/图例/连线标签的包围盒重叠；没有连线穿过无关节点或文字；流程图节点用圆角
-矩形，判断/特殊形状用软化路径。以上任意一条不满足，就不要输出这段 SVG——简化视觉，或改用文字/
-表格兜底。
-
-## Scene Router
-
-先判断用户意图，路由到**一个**场景文件：
-
-| 用户意图 | 场景文件 |
+| 最终阅读载体 | 输出方式 |
 |---|---|
-| 数值趋势、量级对比、构成/占比、分布、流程强度、密度热力 | `scenes/data-visualization.md` |
-| 模块关系、依赖图、流程图、状态转移、调用链、排期 | `scenes/architecture-and-flow.md` |
-| 方案对比、技术选型、风险摘要、决策矩阵 | `scenes/comparison-and-decision.md` |
-| 原理讲解、物理/抽象机制、因果链 | `scenes/mechanism-explanation.md` |
-| "切换前后"这类状态对比（不是真交互，见该场景文件） | `scenes/micro-interaction.md` |
-
-流程（内部执行步骤，不要讲给用户听）：
-
-1. 判断紧凑可视化是否比 Markdown 更清楚；不是就跳过。
-2. 路由到匹配的场景文件。
-3. 结合素材：读 `templates/manifest.json`，只在 `status: "ready"` 的候选里挑，读对应
-   `templates/<id>/template.md` 再决定是否借用 `widget-code.html`/`fixture.json`。
-4. 优先选用能以最小改动表达焦点的素材；场景组合优于生搬硬套一个不太合适的素材；没有清晰焦点
-   时优先选择纯文字。
-5. 按选中场景文件的强制工作流执行，再落笔画 SVG。
-6. 素材是可复用范例不是死板模板——按需借用布局、CSS、token 用法，混用多个素材时每一块必须回答
-   一个不同的问题。
-7. 改造图表类素材时保留 `tokens/visual-tokens.md` 的颜色契约，不要把某个模板局部的调色例外
-   搬到别的图表类型上，也不要让语义标签名反过来决定图表系列色的顺序。
-8. 只有在没有 `ready` 素材匹配、每个候选都有明确的 avoid 规则冲突、场景本质是需要独特图示的
-   机制讲解、组合多个原型比硬套一个完整素材更清楚，或者 Markdown 本来就比图更清楚时，才生成
-   自定义输出。"手写更快""这很简单""自己画更轻量""我已经会画这个了"都不是有效理由。
-9. 没有 `ready` 素材匹配时不要从零自由发挥，选一个兜底原型（见上面 Visual Design 一节）并保持
-   同一套 token/颜色/字体/间距/圆角/布局契约。
-10. 兜底优先用中性结构，再用品牌色/图表系列色表达焦点或并列类目；语义色只用于明确的状态/风险
-    编码；卡片/面板背景保持中性，颜色放在标记/边框/标签/焦点路径/图标上；不要在同一张图里堆叠
-    多个兜底原型，除非每一块回答的是不同问题。
-11. 如果兜底方案放不下（字太小、出现嵌套滚动、标签被裁、连线重叠、连线穿过文字、隐藏溢出、
-    超过 4 个同级图表色加 Other、超过 2 个互不相关的视觉块），改用 Markdown 回答或要求用户
-    收窄范围，而不是硬塞。
-
-素材意图速查：`line-trend` 趋势；`bar-chart-multiple` 分组对比；`scatter-chart` 相关性/离群点；
-`gantt-chart` 排期/关键路径；`funnel-bar-chart` 转化流失；`sankey-chart` 带权重的分阶段流动；
-`heatmap-chart` 密度；`pie-donut-text` 带总计的构成；`bar-stacked-legend` 堆叠贡献；
-`pie-chart-label-list` 带标签的部分-整体；`radar-chart-legend`/`radar-chart-lines-only` 画像
-对比；`comparison-cards` 方案权衡；`sequence-diagram` 有序调用；`tree-flow` 层级；
-`architecture-elements` 架构原语。
-
-新增、改名、删除或调整某个素材的路由意图时，`templates/<template-id>/template.md`、
-`widget-code.html`、`fixture.json`、`templates/manifest.json`、相关 `scenes/*.md`、
-`templates/README.md` 要一起改。目录或必需文件缺失就不能标 `ready`。兜底原型不是素材 id，
-不应出现在 `templates/manifest.json` 里。
+| Desktop/Web 聊天 | `mermaid` 或 `svg` 围栏；不输出正文裸 SVG/HTML，Markdown 会忽略它们 |
+| CLI/TUI 直接阅读 | 文字、表格、紧凑 ASCII；不把 Mermaid/SVG 源码当可见图 |
+| 文档、网页、图形文件（包括 CLI 发起） | Mermaid/SVG；目标不渲染 Mermaid 时先转为 SVG/PNG 再嵌入 |
+| headless/workflow/subagent | 跟随最终阅读载体，不把运行入口当成输出格式；保持结构化协议契约 |
+| 载体未知 | 保留文字结论，按请求交付图形源码/文件，不声称已渲染 |
+
+不创建无关文件。用户要文件时交付真实路径/附件；内联图不是假按钮、执行状态或虚构成果。
+不宣称渲染器会自动把错误反馈给 Agent；只有实际观察或工具检查才算验证。
+
+## 图形选择：只读所选分支
+
+1. **流程、架构、依赖、时序、状态、层级**：默认 Mermaid，读取 [mermaid.md](mermaid.md)。
+   不需要读取 SVG 模板、颜色表或手算节点坐标。
+2. **精确布局、机制示意、定制数据图**：选 SVG，读取 [svg-design.md](svg-design.md)，
+   再按该文件选择一个场景/所需素材。简单 Mermaid 能清楚表达时不升级到手写 SVG。
+3. **精确数值比较**：先考虑表格；需要趋势、分布或空间关系时才画图。
+4. **网站/App 的真实交互**：使用 [ui-design](../ui-design/SKILL.md)，不把静态图伪装成应用。
+
+复杂图先分组或拆分，保留关键节点和方向，不靠小字号塞满屏幕。
+缺少可用渲染器或图连续失败时保留文字/表格，不反复倾倒源码。
+
+## 交付与检查
+
+- Desktop/Web 用对应语言围栏，图下简述结论，不重复展示一份源码。
+- SVG 不含脚本、事件处理器、外部资源或需要点击才能看见的关键信息。
+  新图优先真正的 SVG；旧静态 HTML 卡片兼容性不意味着 HTML 是通用图片格式。
+- 文档中的图片必须是真正的 SVG 或 PNG，不把 HTML 卡片当 SVG。
+  独立 SVG 导出须将 CSS 主题变量解析为实际色值与字体；目标转换器不兼容时提供 PNG。
+- 有渲染工具时检查真实渲染：标签完整、无重叠、明暗主题可读、窄屏不裁切。
+  没有验证条件则如实说明，不能把语法看似正确当作渲染成功。
+- 下载或预览依赖宿主真实成果机制，不能用画出来的下载按钮替代。

package/skills/dynamic-ui/mermaid.md

@@ -0,0 +1,32 @@
+# Mermaid 轻量路径
+
+适合结构和关系，不套用 SVG 的模板选择或坐标规划。宿主已有 Mermaid 渲染器，
+不为聊天图另行安装库。使用标准语法，避免依赖特定版本的新图种。
+
+- 流程/架构：`flowchart TD` 或 `flowchart LR`；窄屏优先纵向。
+- 交互时序：`sequenceDiagram`。
+- 状态转换：`stateDiagram-v2`。
+- 实体关系：`erDiagram`；需要精确布局或渲染器不支持时改 SVG/表格。
+- 节点使用短稳定 ASCII ID，显示标签使用带引号的中文文本。
+- 标签短句，不嵌入 HTML、脚本、click 回调、外部图片或 init 配置覆盖宿主安全与主题设置。
+- 单图只表达一个问题；大图按阶段或职责拆分，避免横向长链。
+- 不强制配色，优先宿主主题，不画假的实时状态或操作按钮。
+
+Desktop/Web 回复示例（正文保留结论）：
+
+人类确认目标后，Agent 执行并交由人类验收。
+
+```mermaid
+flowchart TD
+  goal["确认目标"] --> work["Agent 执行"]
+  work --> review["人类验收"]
+  review -->|需要修改| work
+  review -->|通过| done["交付成果"]
+```
+
+检查节点、箭头方向、分支标签与事实一致。可用渲染工具时实际渲染，
+失败先简化语法/标签，不无限重试；仍失败就用 SVG 或文字/表格。
+没有渲染证据不能声称已验证。
+
+生成文档时保存源码仅在需要时进行；不支持 Mermaid 的阅读器需先将图渲染成 SVG/PNG，
+然后用目标文档的图片机制嵌入并检查成品。不要直接粘贴围栏就称完成配图。

package/skills/dynamic-ui/scenes/architecture-and-flow.md

@@ -1,5 +1,8 @@
 # 架构与流程场景
 
+默认先走 `../mermaid.md`，用 Mermaid 表达流程、架构、时序和状态关系。
+只有需要定制 SVG 布局时才执行下方 SVG 素材与坐标规则，并读取 `../svg-design.md`。
+
 共用契约：`SKILL.md`、本文件、`templates/manifest.json`、选中的 `templates/<id>/template.md`、
 `tokens/visual-tokens.md`。
 
@@ -48,7 +51,7 @@
    素材。
 5. 边界符合时用 `sequence-diagram`、`tree-flow`、`architecture-elements`。
 6. 只有边界不匹配、关系规模超出素材能力，或 Markdown 明显更清楚时才否掉一个现成素材
-   （`gantt-chart` 目前是 `needs-static-rewrite`，暂不可用，见 `SKILL.md`）。
+   （`gantt-chart` 目前是 `needs-static-rewrite`，暂不可用，见 `../svg-design.md`）。
 7. 没有素材匹配时选 `node-flow` 或 `explanation-panel`，再套用下面的 SVG 布局规则。
 8. 画之前先选定一种骨架：横向流程、纵向流程、泳道/时序、分组架构，或排期——不要混用骨架，
    除非每种各占一个独立面板。