feishu-diagram-chooser（飞书图表选择器）

Feishu Diagram Chooser

Parse natural language descriptions and output structured diagram scheme recommendations.

0. 触发规则（何时使用本 Skill）

0.1 正向触发（应当调用）

当用户的需求满足以下任意条件时，应调用本 Skill：

1. 明确提出要“画图/做图表/可视化”

- 示例： - 「帮我画一个登录流程图」 - 「把这个系统架构画出来」 - 「做个 ER 图/时序图/甘特图」 - 「把这段业务流程可视化一下」

1. 命中图相关关键词 + 行为词

- 图相关关键词（任意一个）： - 中文：图表、流程图、时序图、状态图、ER 图、类图、甘特图、思维导图、时间线、架构图、组织结构图 - 英文：diagram, chart, flowchart, sequence, mermaid - 泛词：可视化、画图、图形 - 行为关键词（至少一个）： - 画、生成、做一个、做成、转换成、可视化、展示成、画成

规则：(图相关词) AND (行为词) → 强触发。

1. 上下文已经在“改一张图”，继续编辑

- 上几轮已经使用本 Skill 生成了图，本轮用户说： - 「再加一个审批节点」 - 「在中间插一个网关」 - 「把数据库拆成两个表」 - 默认继续调用本 Skill，对已有图进行扩展或重构。

0.2 负向触发（不应调用）

即使命中图相关词，但属于以下情况时，不调用本 Skill，而是走普通文本回答：

• 用户只是想理解/评价现有图：

- 「帮我解释一下这个 ER 图」 - 「帮我点评这张架构图」 - 「这个流程图有没有问题？」

• 用户明确表示不需要画图：

- 「不用画流程图，用文字说明就行」

• 用户要求禁止使用某类图/某种工具：

- 「不要用 Mermaid，只要文字」 - 「不要用任何图表」

在这些情况下，Skill 只应在用户之后再次明确提出“要画图”时才重新触发。

1. 输入参数

2. 输出 Schema

interface DiagramScheme {
  // Primary recommendation
  primary: {
    type: 'mermaid' | 'echarts' | 'image';
    subtype: string;           // Specific diagram subtype
    reasoning: string;         // Why this type is recommended
    mermaidCode?: string;      // Generated Mermaid code (if type='mermaid')
    chartConfig?: object;      // ECharts option config (if type='echarts')
    imagePrompt?: string;      // Image generation prompt (if type='image')
  };

  // Alternative options, ordered by preference (descending)
  alternatives: Array<{
    type: 'mermaid' | 'echarts' | 'image';
    subtype: string;
    reasoning: string;
    score?: number;            // Optional relative score (0-1), primary is highest
  }>;

  // Confidence score 0-1 for primary choice
  confidence: number;

  // When classification is ambiguous or confidence < 0.6, provide clarification questions
  clarificationNeeded?: string[];
}

约定：alternatives 按推荐优先级排序，前面的方案优于后面的方案。

3. 决策逻辑

3.1 Intent Classification（意图分类）

分析 description，分类可视化意图：

若描述同时出现多种意图（如既有流程又有架构、又有数据），应：

• 降低 confidence
• 优先生成 clarificationNeeded，询问用户关注的主视角

示例澄清问题：

• 「你更想重点展示：1）流程步骤 2）系统组件关系 3）数据趋势，哪一个？」
• 「时间线和流程图你更想要哪种表现形式？」

3.2 Mermaid Type Mapping（结构图映射）

在满足以下条件时，优先使用 Mermaid：

• 环境支持 Mermaid（默认 true）
• context.constraints.allowedDiagramTypes 未显式禁用对应子类型
• 或 ECharts 不可用（见 3.3 中兜底逻辑）

映射表：

版本约束：

• 当 context.constraints.mermaidVersion 存在时：

- 若 < 10.5，不推荐 mindmap / timeline - 若某 subtype 不在 allowedDiagramTypes 中，也不推荐

3.3 Data Chart Mapping（数据图映射 & 兜底策略）

当描述明显指向“数据可视化”时，先尝试 ECharts：

✳ ECharts 不可视化时的兜底链路

当满足以下任一条件时，不要输出 type='echarts' 作为 primary，而是执行分级兜底：

• context.constraints.echartsSupported === false
• 当前运行环境无法渲染 ECharts（由上层 Agent 判定后传入）
• 上下文明确指出「无法使用 ECharts」或「当前环境不支持图表渲染」

兜底顺序：

1. 尝试用 Mermaid 图近似表达数据关系（结构化代替可视化图表）

- 例如： - 数据流/转化 → flowchart / journey / sankey-like 流程图 - 类别对比 → 用 flowchart 列出节点 + 简要文字标注 - 时间趋势 → timeline / gantt（若版本支持），或用 flowchart 线性列出关键时间点 - 此时： - primary.type = 'mermaid' - primary.reasoning 中要明确说明：“因为当前环境无法渲染 ECharts，改用 Mermaid 结构图近似展示关键关系”。

1. 若 Mermaid 也不适合表达（纯统计图需求，结构化表达会严重失真）

则退而求其次使用图片生成：

- primary.type = 'image' - primary.subtype = 'ai-generated' - 通过数据描述 + styleHint 构造 imagePrompt

1. ECharts 在任何情况下可以作为 alternatives 出现在返回结果中，以便在其他环境下渲染：

- 例如：

     {
       "primary": { "type": "mermaid", ... },
       "alternatives": [
         {
           "type": "echarts",
           "subtype": "bar",
           "reasoning": "在支持 ECharts 的环境中，这种图表能更好呈现数据对比",
           "score": 0.8
         }
       ]
     }

3.4 Fallback Strategy（通用兜底）

当无法确定合适的结构图或者数据图（confidence < 0.6 且意图仍不清晰）：

1. 尝试生成 Mermaid 的高层结构草图

- 使用 flowchart 或 mindmap（若支持）粗略表达要素和关系 - 若仍然感觉强行结构化会误导用户 → 放弃结构图

1. 生成图片描述（Image Prompt）作为最终兜底

function generateImagePrompt(description: string, style: string): string {
  const base = "Professional technical illustration";
  const styleModifiers = {
    formal: "clean corporate style, blue and gray color scheme",
    casual: "friendly hand-drawn style, warm colors",
    colorful: "vibrant modern design, multiple accent colors",
    minimal: "minimalist line art, monochromatic",
    technical: "detailed engineering diagram, precise annotations"
  };

  return `${base}. ${description}. ${styleModifiers[style] || styleModifiers.formal}. 
    No text, no labels, purely visual representation. 
    White background, high contrast.`;
}

1. 提供 clarificationNeeded，引导用户收窄需求视角：

- 「你更关注时间演进、结构关系还是数据对比？」 - 「这张图是用来沟通给非技术同学，还是技术设计评审？」

4. Mermaid 代码生成规范（质量与兼容性）

为减少渲染失败，生成 Mermaid 代码时遵守：

1. 节点 ID 使用英文与数字，不含空格和中文：

- 用 node_login, node_approve1 这类 ID - 中文展示放在方括号/圆括号内容中，例如：node_login[用户登录]

1. 中文标签统一包在节点文本中：

- A[用户输入账号密码] - 避免在 ID 中直接使用中文或特殊字符

1. 特殊字符转义和注释：

- 避免在标签中包含 :, {, } 等影响语法的字符，必要时用文本描述替代 - 顶部可添加注释：%% auto-generated by feishu-diagram-chooser

1. 复杂图建议分组 / section（尤其是 Gantt、journey 等）

5. Quality Checklist

• [ ] 触发场景正确（未误触解释型需求）
• [ ] 意图正确分类，并处理多意图混合（必要时给出澄清问题）
• [ ] 推荐类型符合环境约束（版本、allowedDiagramTypes、echartsSupported）
• [ ] Mermaid 类型与版本兼容（mindmap/timeline 仅在支持时使用）
• [ ] ECharts 环境不支持时，已优先切换到 Mermaid，再退回图片
• [ ] Mermaid 语法合法，节点命名规范，可渲染
• [ ] ECharts 配置是模板化的，可由上层填充真实数据
• [ ] alternatives 有清晰的优先级/评分，理由明确
• [ ] 输出符合 Schema（primary/alternatives/confidence/clarificationNeeded）

6. 触发示例（正例 / 反例）

6.1 正例：应该调用本 Skill

1. 明确要画流程图

- 用户输入： > 帮我画一个用户登录的流程图，包含密码错误三次锁定账号 - 结果： - 命中「画」「流程图」→ 触发 - Intent = Process → 推荐 flowchart TD

1. 数据对比可视化，环境支持 ECharts

- 用户输入： > 想做一个柱状图，对比今年各产品线的销售额 - 上下文：echartsSupported = true - 结果： - Intent = Comparison → 推荐 echarts + bar

1. 时间线展示历史事件

- 用户输入： > 帮我把公司这五年的大事件画成一条时间线 - 上下文：mermaidVersion >= 10.5 - 结果： - Intent = Time-based → 推荐 timeline

1. 在已有图基础上继续修改

- 上一轮已用本 Skill 输出登录流程图 - 本轮输入： > 在登录失败后加一个验证码步骤 - 结果： - 识别为对现有图的增量修改 → 继续用本 Skill 更新 Mermaid

6.2 反例：不应该调用本 Skill

1. 只是解释已有图

- 用户输入： > 帮我解释一下这张 ER 图每个字段的含义 - 结果： - 虽然有「ER 图」，但没有「画/生成/可视化」等行为词 - 不触发本 Skill，用普通文本解释

1. 明确不要画图

- 用户输入： > 不用画流程图，你直接用文字帮我描述登录过程就行 - 结果： - 包含「流程图」，但与否定意图绑定 - 不触发本 Skill

1. 禁止使用某种图形工具

- 用户输入： > 不要用 Mermaid 帮我画图，你直接给一个文字版的接口调用顺序 - 结果： - 明确禁止 Mermaid - 不调用本 Skill；除非后续用户再次主动提出要画图

1. 仅想要概念说明

- 用户输入： > ER 图和类图有什么区别，给我讲一下 - 结果： - 只是知识问答，不是生成新图 - 不调用本 Skill