鱼骨图

关于鱼骨图

鱼骨图（又称石川图或因果图）将问题的潜在原因映射到一条横向主骨上，主骨末端指向"结果"——即问题陈述。每条主要分支代表一类原因，子分支承载各项细节。石川馨于 1968 年将这一技法作为制造业质量管控工具推出，此后扩展到医疗、软件工程和业务运营领域，成为根本原因分析的结构化头脑风暴方法。团队在回顾会议、DMAIC 改进阶段和故障事后复盘中使用它，以避免过早聚焦于最显眼的假设。

Schematex 遵循 **Ishikawa（1968）**因果图规范，支持标准 6M 制造类别（Man 人员、Machine 机器、Material 材料、Method 方法、Measurement 测量、Mother Nature/Environment 环境）及其服务业变体（People 人员、Process 流程、Place 场所、Policy 政策、Procedures 程序、Patron 顾客）。结构化和紧凑两种编写风格可在同一文档中混用。外部参考：Ishikawa, K. — Guide to Quality Control (1968) · ASQ 因果图 · ISO 9001:2015 §10.2 — 纠正措施。

1. 第一张鱼骨图

最小的可用鱼骨图：三个类别，每类一条原因，其中一条带有子原因。

四条规则涵盖 80% 的使用场景：

1. 以 fishbone 开头，后面可选跟一个引号括起的标题。
2. 用 category id "标签" 声明每条分支——id 是短的内部键，"标签" 是图上显示的文字。
3. 在独立行上用 id : "原因文本" 添加原因。
4. 在某行缩进至少 2 个空格并以 - 开头，可在前一条原因下创建子原因（二阶分支）。

注释可以 #、// 或 Mermaid 风格的 %% 开头，须独占一行。

2. 构成要素

主骨与结果

effect "问题陈述" 将文本放置在鱼头处。若省略 effect，解析器将回退到使用图表标题。

fishbone "标题"
effect "具体问题陈述"

鱼头默认位于右侧（config direction = right）。使用 config direction = left 可翻转方向。

类别（主骨）

category id "标签" 声明一条分支。id 在内部用于分配原因；引号括起的 "标签" 显示在图上。

类别还可在 […] 中接受可选属性：

category rework "Rework" [color: "#E53935", side: top, order: 1]

原因（小骨）

支持两种风格，可在同一图中混用：

风格 A——结构化。 先声明类别，再用 id : "文本" 分配原因：

category code "Code"
category infra "Infra"
code : "N+1 query in endpoint"
code : "Missing cache layer"
infra : "Auto-scaling lag"

风格 B——紧凑式。 类别标签与原因写在同一行，用 ; 或 , 分隔：

category Code: N+1 query; Missing cache; Synchronous call
category Infra: Auto-scaling lag; CDN misconfigured

紧凑风格中，id 由标签文字自动派生（转小写，空格替换为连字符）。原因文本的引号可选。

风格 C——Mermaid 思维导图简写。 顶层裸行成为类别，缩进的 - 项成为该类别下的同级一阶原因：

fishbone "Why is the site slow?"
effect "Page LCP > 4s"
Content
  - heavy hero image
  - too much above-the-fold text
Tech
  - JS bundle too large
  - render-blocking CSS

3. 子原因（二阶分支）

在一阶原因之后，将 - 行缩进至少 2 个空格，即可将子原因附加到该原因上。- 连字符是语法的一部分，文字紧随其后。

method : "Stencil aperture undersized"
  - "Tolerance spec from 2018 board revision"
  - "No re-validation after material change"
method : "Pick-and-place speed too high"
  - "Speed limit lifted during overtime run"

子原因显示为从父级小骨分叉出的更短、更细的枝条。

4. 配置选项

config key = value 行可出现在标题之后的任意位置。未知的键和值将被静默忽略。

config direction = left
config density = compact
config slope = gentle
config sides = top

5. 标签与注释

• 图表标题： fishbone "网站流量下降" — 第一行，可选。
• 结果标签： effect "自然流量下降 30%" — 鱼头处的问题描述。
• 类别标签： category id "易读名称" — 打印在分支上。
• 原因文本： 用引号括起 "这样" 或不加引号（紧凑风格允许含空格）。
• 子原因文本： 在前导 - 之后，加引号或不加引号均可。
• 注释： #、// 或 %% 位于行首（前面可有空白）。同样的标记在双引号字符串之外也可用于行尾注释。

6. 保留字与转义

行首保留字： fishbone（标头）、effect、category、config。

- 前缀在缩进行上是子原因标记。若要在原因文本开头包含字面连字符，请加引号：code : "- old deprecated path"。

含空格的字符串在结构化风格的原因文本中应加双引号：code : "N+1 query"。在紧凑风格（category Label: ...）中，文本延伸到 ; 或 , 分隔符前，引号可选。

注释标记（#、//、%%）在双引号字符串外均表示注释。

7. 常见错误

8. 语法（EBNF）

document       = header (blank | comment | effect | category | config | cause | sub-cause | implicit-category)*

header         = "fishbone" ":"? ( WS quoted-string )? NEWLINE
effect         = "effect" ":"? WS quoted-string NEWLINE
config         = "config" WS config-key WS "=" WS config-value NEWLINE
config-key     = "direction" | "width" | "height" | "sides"
               | "slope" | "ribslope" | "density" | "causeside" | "cause-side"
config-value   = bare-word | number | quoted-string

category       = "category" WS id WS label-or-compact ( "[" category-attrs "]" )? NEWLINE
implicit-category
               = bare-text NEWLINE                         # top-level, no ":"

label-or-compact
               = quoted-string                            # structured form: category id "Label"
               | id WS ":" WS compact-causes             # compact form: category Label: cause; cause

category-attrs = category-attr ("," category-attr)*
category-attr  = "color:" quoted-string
               | "side:" ( "top" | "bottom" )
               | "order:" integer

cause          = id WS ":" WS cause-text NEWLINE         # structured form
cause-text     = quoted-string | bare-text

sub-cause      = INDENT≥2 "-" WS cause-text NEWLINE

compact-causes = compact-cause ( (";" | ",") compact-cause )*
compact-cause  = quoted-string | bare-text

comment        = ( "#" | "//" | "%%" ) any NEWLINE
id             = [a-zA-Z] [a-zA-Z0-9_-]*
quoted-string  = '"' any-char-but-unescaped-quote* '"'

权威来源：src/diagrams/fishbone/parser.ts。若本文档与解析器有出入，以解析器为准——欢迎提 issue。

9. 标准合规性

Schematex 鱼骨图遵循 **Ishikawa（1968）**因果图规范：横向主骨，右端为标记结果的鱼头，斜向小骨代表主要原因类别，每条小骨上附有细节原因。两级层次结构（类别→原因→子原因）与六西格玛 DMAIC 和 ISO 9001 纠正措施工作流中传统"5 个为什么"的分析深度相符。

当前已实现：

• ✅ 结构化风格：category id "标签" + id : "原因"
• ✅ 紧凑风格：category Label: 原因; 原因; 原因
• ✅ 子原因（二阶）通过缩进 - 前缀实现
• ✅ 每个类别的颜色和方向覆盖
• ✅ direction、density、slope、sides、causeside 配置
• ✅ 可选的显式 width / height
• ⏳ 三阶及以上子子原因（解析器存储子节点，但渲染器当前限制在第 2 层）
• ⏳ 自动建议标准类别集（6M、8P、5P）
• ⏳ order 渲染（已解析但布局引擎尚未应用）

参考文献：

• Ishikawa, K. (1968). Guide to Quality Control. JUSE Press.
• ASQ — Cause-and-Effect (Fishbone) Diagram
• ISO 9001:2015 §10.2 — 不合格与纠正措施

10. 相关示例

11. 路线图

计划中——当前尚不可解析。 请勿在生成的 DSL 中使用以下功能；解析器将拒绝或忽略它们。

• 三阶子子原因 — 第三缩进层；AST 结构已支持，但渲染器目前止步于第 2 层。
• causeside 每类别覆盖 — 在单个类别上设置 cause-side，而非全局设置。
• 自动建议标准类别 — template: 6M / template: 8P 简写，自动填入标准制造或服务类别名称。
• 图例块 — legend 关键字，声明在图表旁渲染的颜色编码说明。
• metadata: 块 — 结构化键值元数据（主持人、日期、修订号），显示在角落注释中。

如需提前实现以上功能，请在 GitHub issues 中跟踪。