Feishu Diagram Chooser#

Parse natural language descriptions and output structured diagram scheme recommendations.

---

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

0.1 正向触发（应当调用）#

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

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

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

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

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

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

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

0.2 负向触发（不应调用）#

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

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

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

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

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

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

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

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

---

1. 输入参数#

ParameterTypeRequiredDescriptiondescriptionstringYesNatural language description of what the user wants to visualizecontextobjectNoAdditional context including data structure, style preference, output format constraintscontext.dataFormatstringNoData format hint: structured, unstructured, relational, time-series, hierarchical``context.styleHintstringNoVisual style preference: formal, casual, colorful, minimal, technical``context.constraintsobjectNoConstraints like maxNodes, maxDepth, hasTimeDimension, mermaidVersion, allowedDiagramTypes, echartsSupported``context.constraints.mermaidVersionstringNoMermaid version in use, e.g. "10.0.0", "10.5.0"``context.constraints.allowedDiagramTypesstring[]NoWhitelist of allowed diagram subtypes, e.g. ["flowchart", "sequenceDiagram", "classDiagram"]``context.constraints.echartsSupportedbooleanNoWhether ECharts-based data charts can be rendered in the current environmentcontext.constraints.maxNodesnumberNoEstimated maximum comfortable node count for diagram (for complexity control)

---

2. 输出 Schema#

typescript

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，分类可视化意图：

Intent CategoryKeywordsData CharacteristicsProcess流程, 步骤, 怎么做, process, workflow, step, how-toSequential actions with decisionsRelationship关系, 连接, 依赖, relation, dependency, connectEntities and their connectionsHierarchy结构, 组织, 层级, hierarchy, structure, orgParent-child relationshipsTime-based时间, 进度, 计划, 时间线, timeline, schedule, Gantt, 里程碑Temporal sequences or durationsComparison对比, 比较, 排名, compare, rank, vsMultiple items for comparisonDistribution分布, 占比, 比例, distribution, percentage, ratioPart-to-whole relationshipsState状态, 变化, 转换, 生命周期, state, status, transitionState machines or lifecycleArchitecture架构, 系统, 模块, 组件, architecture, system, moduleComponent relationshipsJourney/UX用户旅程, 体验路径, journey, funnelUser journey, experience flows

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

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

示例澄清问题：

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

3.2 Mermaid Type Mapping（结构图映射）#

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

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

映射表：

Diagram TypeSubtypeBest ForSyntax VersionNotesFlowchartflowchart TD / flowchart LRProcess, workflow, decision trees10.0+默认方向 TD，节点 > maxNodes 时考虑拆分或改用其他图SequencesequenceDiagramInteraction between actors, API calls10.0+多角色交互优先选择StatestateDiagram-v2State machines, status transitions10.0+生命周期、状态流转ERerDiagramDatabase schema, entity relationships10.0+仅用于“实体-字段-关系”的场景ClassclassDiagramOOP class structures, inheritance10.0+用于类/接口结构GanttganttProject schedules, timelines with tasks10.0+含任务、阶段、起止日期MindmapmindmapHierarchical thinking, brainstorming10.5+ (experimental)仅在 mermaidVersion >= 10.5 且未被禁用时推荐TimelinetimelineChronological events, history10.5+ (experimental)同上，适用于历史事件/里程碑GitgraphgitGraphGit branch history, version control10.0+代码分支场景专用User JourneyjourneyUser experience flows10.0+用户旅程/漏斗型体验C4ContextC4Context, C4ContainerSystem architecture (C4 model)10.0+复杂架构时可选，若环境不支持则降级为 flowchart/classDiagram

版本约束：

• 当 context.constraints.mermaidVersion 存在时：

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

---

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

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

IntentChart TypeLibrary注意点Trend over timeLine, AreaECharts类别较多时优先 line；时间维度清晰Category comparisonBar (vertical/horizontal)ECharts类别数 > 10 时谨慎使用饼图Part-to-wholePie, Donut, TreemapECharts类别数 ≤ 8 更适合 Pie/DonutMulti-variable comparisonRadar, ParallelECharts维度数 ≤ 6 更可读CorrelationScatter, HeatmapECharts连续变量之间关系GeographicMapECharts需要地理维度Flow/ConversionSankey, FunnelECharts流转关系/转化漏斗Text frequencyWordCloudECharts + echarts-wordcloud文本频次、标签云

✳ 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 结构图近似展示关键关系”。

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

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

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

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

   • 例如： jsonc

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

---

3.4 Fallback Strategy（通用兜底）#

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

1. 尝试生成 Mermaid 的高层结构草图
   • 使用 flowchart 或 mindmap（若支持）粗略表达要素和关系
   • 若仍然感觉强行结构化会误导用户 → 放弃结构图
2. 生成图片描述（Image Prompt）作为最终兜底

typescript

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[用户登录]
2. 中文标签统一包在节点文本中：
   • A[用户输入账号密码]
   • 避免在 ID 中直接使用中文或特殊字符
3. 特殊字符转义和注释：
   • 避免在标签中包含 :, {, } 等影响语法的字符，必要时用文本描述替代
   • 顶部可添加注释： %% auto-generated by feishu-diagram-chooser
4. 复杂图建议分组 / 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
2. 数据对比可视化，环境支持 ECharts

   • 用户输入：

     想做一个柱状图，对比今年各产品线的销售额

   • 上下文： echartsSupported = true

   • 结果：

     • Intent = Comparison → 推荐 echarts + bar
3. 时间线展示历史事件

   • 用户输入：

     帮我把公司这五年的大事件画成一条时间线

   • 上下文： mermaidVersion >= 10.5

   • 结果：

     • Intent = Time-based → 推荐 timeline
4. 在已有图基础上继续修改

   • 上一轮已用本 Skill 输出登录流程图

   • 本轮输入：

     在登录失败后加一个验证码步骤

   • 结果：

     • 识别为对现有图的增量修改 → 继续用本 Skill 更新 Mermaid

6.2 反例：不应该调用本 Skill#

1. 只是解释已有图

   • 用户输入：

     帮我解释一下这张 ER 图每个字段的含义

   • 结果：

     • 虽然有「ER 图」，但没有「画/生成/可视化」等行为词
     • 不触发本 Skill，用普通文本解释
2. 明确不要画图

   • 用户输入：

     不用画流程图，你直接用文字帮我描述登录过程就行

   • 结果：

     • 包含「流程图」，但与否定意图绑定
     • 不触发本 Skill
3. 禁止使用某种图形工具

   • 用户输入：

     不要用 Mermaid 帮我画图，你直接给一个文字版的接口调用顺序

   • 结果：

     • 明确禁止 Mermaid
     • 不调用本 Skill；除非后续用户再次主动提出要画图
4. 仅想要概念说明

   • 用户输入：

     ER 图和类图有什么区别，给我讲一下

   • 结果：

     • 只是知识问答，不是生成新图
     • 不调用本 Skill