@jspg-ai/coding-bb 0.0.1

package/cbb/tools/cbb-plantuml-authoring/SKILL.md

@@ -0,0 +1,448 @@
+---
+name: cbb-plantuml-authoring
+description: "PlantUML 图创作全流程：从零画图到语法排错。触发场景：画/写/起草 PlantUML 图/活动图(=流程图)/时序图/类图/状态图/组件图/部署图/应用架构图/技术架构图、写 .puml 文件、贴 @startuml 代码片段、技术方案需要画图、修改现有流程需画修订版流程图（颜色高亮改动点+legend+变更说明）、检查 PlantUML 语法、PlantUML 渲染报错排查、用脚本生成 PlantUML 源码。即便简单图也要校验后交付。不适用：Mermaid、draw.io。依赖 java + plantuml.jar。"
+---
+
+# cbb-plantuml-authoring
+
+PlantUML 图的完整创作，三条主线：
+
+1. **主线一：画图** — 从零起草，画出语法正确又好看的图
+2. **主线二：校验** — 用 jar 抓 `Error line N`，不校验不交付
+3. **主线三：脚本生成注意事项** — 字符串字面量里的 `\n` 陷阱
+
+校验是手段，目的是"画对 + 画好"。先讲前置依赖，再分三条主线；质量规范、语法坑、模板作为各主线的补充。
+
+## 前置依赖
+
+- **java**（JDK 即可，运行 plantuml.jar）。`java -version` 验证
+- **plantuml.jar**：见下节"获取 plantuml.jar"，jar **不随 skill 打包**，首次使用需自行放置
+
+### 获取 plantuml.jar（jar 不打包进 skill）
+
+按优先级自动找 jar：
+
+1. 环境变量 `PLANTUML_JAR`
+2. 候选路径中首个存在的：`~/.plantuml/plantuml.jar`、`~/plantuml.jar`
+
+**推荐（一次配置永久生效）**：下载 jar 到 `~/.plantuml/plantuml.jar`：
+
+```
+# 下载地址（maven central）
+https://repo1.maven.org/maven2/net/sourceforge/plantuml/plantuml/1.2024.7/plantuml-1.2024.7.jar
+
+# Windows(PowerShell)
+mkdir $HOME\.plantuml -Force
+Invoke-WebRequest "https://repo1.maven.org/maven2/net/sourceforge/plantuml/plantuml/1.2024.7/plantuml-1.2024.7.jar" -OutFile "$HOME\.plantuml\plantuml.jar"
+
+# macOS / Linux
+mkdir -p ~/.plantuml
+curl -L "https://repo1.maven.org/maven2/net/sourceforge/plantuml/plantuml/1.2024.7/plantuml-1.2024.7.jar" -o ~/.plantuml/plantuml.jar
+```
+
+放好后无需额外配置。也可设 `PLANTUML_JAR` 指向任意位置。**不要**用 IntelliJ 插件自带的 `plantuml-mit-*.jar`（路径深、版本不可控）。
+
+---
+
+## 主线一：画图
+
+### 画图流程
+
+1. **画前定位（3 问 + 粒度）** — 核心场景讲什么事 / 边界从哪到哪 / 要不要分组，**画时序图和组件图还要先定粒度**（见补充·图类型选型·粒度选择）。答不出别动手
+2. **选图类型** — 按要表达的内容选（见补充·图类型选型）；流程→活动图、交互→时序图、拓扑分层→组件图，状态机→状态图，表关系→类图
+3. **套模板 + skinparam 基底** — 从 `references/drawing-templates.md` 拿对应模板，顶部贴 `backgroundColor #FEFEFE` 等基底（见补充·skinparam）
+4. **定结构** — `partition`/`box`/`package` 做层次分组，消除"一坨"（见补充·层次与分组）
+5. **配色 + 改动点高亮** — Material 色阶（同色系深浅=层级）；修订图用约定色高亮改动点 + `legend`（见补充·配色）
+6. **本地 jar 校验** — 见主线二，exit 0 且无渲染警告才完
+
+写 PlantUML 遵守下面的补充规范，可避免绝大多数渲染失败，且图更好看。
+
+### 补充·通用骨架
+
+```
+@startuml
+title 图标题
+' 内容
+@enduml
+```
+
+- `@startuml` / `@enduml` 必须成对，缺一不可
+- 中文文本必须加 `-charset UTF-8` 跑 jar，否则乱码/误报
+- 颜色名用 PlantUML 内置颜色（Wikipedia/Web colors）：`LightPink`/`LightBlue`/`LightGreen`...，不要自造缩写
+
+### 补充·图类型选型
+
+按要表达的内容选，不要一律画时序图。PlantUML 没有独立 flowchart 类型，**流程图统一用活动图画**。
+
+| 要表达 | 选 | 别选 |
+|---|---|---|
+| 业务流程/审批流/状态流转/流程图 | 活动图 | 时序图（信息过载） |
+| 多系统/多角色时序交互 | 时序图 | 活动图（丢失时序） |
+| 领域模型/表关系/类继承组合 | 类图 | — |
+| 对象状态机 | 状态图 | 活动图（粒度错） |
+| 系统部署/依赖拓扑 | 组件图/部署图 | — |
+| 应用分层/应用间调用（应用架构图） | 组件图（package 分层） | — |
+| 层级拆解/脑暴 | 思维导图 | — |
+
+#### 粒度选择（时序图/组件图动手前必先定）
+
+participant 的粒度决定信息密度和图层次。一张图只画一个粒度，不要混级，否则读者抓不住这图讲什么。
+
+**时序图**：
+
+| 粒度 | participant 是 | 适用场景 |
+|---|---|---|
+| 应用间 | 应用/服务 | 跨服务调用链、系统交互 |
+| 类/方法间 | 类或方法 | 单服务内部调用链、代码设计 |
+
+**组件图**：
+
+| 粒度 | component 是 | 适用场景 |
+|---|---|---|
+| 应用级 | 应用/服务 | 应用拓扑架构图（应用间调用、职责边界） |
+| 模块级 | 应用内模块/包 | 单应用内部分层 |
+| 类/接口级 | 具体类/接口 | 详细设计、接口依赖 |
+
+**规则**：一张图只画一个粒度。要同时表达"应用间 + 应用内"或"应用级 + 类级"，拆成多张图，不要混在一张图里。应用级图里混入具体类、时序图里应用和方法当同级 participant，都是常见错误。
+
+各图类型最小骨架见 `references/drawing-templates.md`。
+
+### 补充·绘图质量规范
+
+校验只保证语法对，不保证图好。以下规范让图类型恰当、层次清晰、颜色有意义。完整可复制模板见 `references/drawing-templates.md`。
+
+#### 画前先定位（3 问）
+
+动手前用一句话回答，答不出说明还没想清，别急着画：
+1. **核心场景**：这张图要讲清什么事？（如"下单到支付的状态流转"）
+2. **边界**：从哪开始、到哪结束？哪些参与方画进来、哪些不画？
+3. **层次**：要不要分组？（按角色/按阶段/按子系统）
+
+#### 层次与分组（消除"一坨"）
+
+- 时序图：`box "子系统名" #LightBlue` 把相关 participant 圈起来；`autonumber` 给消息编号便于引用
+- 活动图：`partition "阶段名" #Color { ... }` 分区，**每个 partition 给不同背景色**（用背景色分组破"瘦长"感）；配 `skinparam PartitionBorderThickness 1` 细框线（partition 不支持虚线边框，用细线近似）。注意：活动图**不支持** `left to right direction`，加了会解析失败
+- 类图：`package "模块" { class ... }` 分包
+- 分组别过度：超过 3 层嵌套就该拆成多张图
+
+#### 配色（层级用色阶，跨图色系一致）——表达性关键
+
+配色不是装饰，是传递层级和归属的语义。两条原则（从真实好图提炼，完整调色板见 references）：
+- **同色系深浅表达层级**：package/box 用浅色，内部 component/participant 用同色系深一档；层级越深色越浓（如浅蓝包 → 中蓝组件 → 深蓝原子能力）。用 Material Design 色阶
+- **跨图色系一致**：同一子系统/参与方在组件图、时序图、活动图里用相同色系（如 saas-admin 在所有图里都是绿色系），读者跨图能秒认
+
+**修订现有图时，改动点必须用约定颜色突出，并在图底加 `legend` 说明**：
+
+| 含义 | 颜色 | 示例（活动图） |
+|---|---|---|
+| 新增 | `#LightGreen` | `#LightGreen:新动作;` |
+| 修改 | `#Gold` | `#Gold:改后动作;` |
+| 删除 | `#LightGray` | `#LightGray:废弃动作;`（文本前标 `[DEL]`） |
+| 关键路径/重点 | `#LightBlue` | `#LightBlue:核心动作;` |
+| 异常/警告 | `#Salmon` | `#Salmon:异常处理;` |
+
+时序图给 participant 上色：`participant "订单服务" as order #LightGreen`；消息变更用 `note over order: 本次新增` 标注（消息箭头本身不支持色块）。类图：`class Foo <<new>> #LightGreen`。完整改动点高亮模板见 references。
+
+**时序图 participant 着色一致性（易错，务必遵守）**：participant 的背景色要么**全员都加**，要么**全员都不加**，禁止只给个别 participant 上色。一张时序图里只有一个对象带色块、其余全白，视觉极其突兀，是最高频的配色失误。
+
+- **全员都加（推荐）**：每个 participant 都用 `box` 包裹 + 头部同色系深一档背景色，无一例外。**关键：不在任何 box 里的"裸 participant"即使加了 `#Color`，也只染头部一小块、无框无边线背景，跟 box 里的对象视觉完全不同，等于没加。** 所以外部的 MQ/CRM/第三方系统也要各自包 `box`（可单对象一个 box），不要留裸 participant。box 底色浅、participant 头部深一档表达层级；legend 列出各色含义。例：
+  ```
+  box "capacity-server" #E8F0FE
+    participant "Consumer" as W #BBD6F5
+    participant "Service" as CS #BBD6F5
+  end box
+  box "延时MQ" #FFF3E0          ' 外部系统也包 box，不要裸 participant
+    participant "tp_ka_task_event" as MQ #FFE0B2
+  end box
+  box "CRM" #F3E5F5
+    participant "XunJiFacade" as CRM #E1BEE7
+  end box
+  ```
+- **全员都不加**：完全不写 `#Color`，只靠 `box` 分组底色 + `note over X: 本次新增` 表达归属与改动点，participant 头部统一默认色。participant 数量少、归属简单时可用这种，最干净。但注意：此模式下 box 仍要包住所有 participant，不要留裸 participant 在 box 外（裸 participant 无框，与 box 内对象不一致）。
+- **选择标准**：想用颜色编码系统归属/新增高亮 → 全员都加（每个 participant 包 box + 头部色）；只想分组不想逐个着色 → 全员都不加（box 包全员，头部默认色）。两者之间不要折中，绝不能出现"box 里有色、box 外裸着无框"的混合。
+- 类图/组件图同理：节点背景色要么全加要么全不加，不要只给个别节点上色。
+
+#### 箭头标签极简 + 显式方向
+
+- 标签写"调用类型+目的"（`: RPC登录`/`: REST`/`: MQ通知`），不写整句话
+- 组件图用显式方向（`-down->`/`-right->`）控制布局，避免线条交叉
+- 时序图箭头可着色编码动作类型（`-[#F57C00]->`=取消/异常、`-[#00695C]->`=回调），同语义同色
+
+#### 时序图分段与细节收纳
+
+- 用 `== 段名 ==` 把长时序图分成几个逻辑段（如"凭据校验""登录处理"），段名即阶段
+- 步骤细节（内部执行的 1.2.3.）放 `note right of X`，主流程箭头保持干净——不要把多步操作挤进一个箭头标签
+- 多错误码场景用嵌套 `alt/else`（每个 else 对应一种错误返回），比活动图 if 更清晰；模板见 references
+
+#### skinparam 美化（统一观感）
+
+默认样式偏素，加这几行立刻好看（可整体放进模板顶部）：
+```
+skinparam backgroundColor #FEFEFE
+skinparam defaultFontSize 13
+skinparam roundCorner 10
+skinparam shadowing false
+skinparam activity { BackgroundColor #FAFAFA BorderColor #888888 }
+skinparam sequence { ArrowColor #555555 ParticipantBorderColor #555555 }
+```
+`backgroundColor #FEFEFE`（浅灰白）比纯白柔和，是通用基底。
+
+#### 可读性
+
+- 文字简短：节点文本一行不超 15 字，长的用 `\n` 换行
+- 方向：活动图默认竖排；步骤多时拆 `partition` 分区或拆多张图（活动图不支持 `left to right direction`）
+- 避免线条交叉：调整 participant 声明顺序
+- 大图拆小：一张图超 30 个元素，按子系统拆多张
+
+#### 活动图瘦长治理（常见问题：竖排又长又窄）
+
+活动图节点天然竖排，partition 多了易瘦长。治法：
+- **partition 给不同背景色**（`partition "名" #Color {}`），用色块分组破"一列窄条"的视觉
+- **线性无分支步骤合并**：像"标准化+批量保存+更新状态"这种顺跑的合并成单节点，别每步一个节点
+- **partition 控量**：3-4 个为宜，超过就拆多张图
+- **legend 放顶部**：`legend top right`（不要放底部，竖排长图底部 legend 难看到）
+
+### 补充·架构图指导（应用架构 / 技术架构）
+
+技术方案里的"架构图"主要是应用架构图和技术架构图，PlantUML 用组件图/部署图表达最合适。
+
+#### 架构图分类与 PlantUML 选型
+
+| 架构图类型 | 讲什么 | PlantUML 选型 |
+|---|---|---|
+| 应用架构图 | 应用分层、应用间调用、应用职责边界 | 组件图（package 分层 + component + 调用箭头） |
+| 技术架构图 | 技术栈、中间件、部署拓扑 | 组件图/部署图（component + database + queue + 节点） |
+| 业务架构图 | 业务域、能力地图、业务流程 | 思维导图（mindmap）/活动图——不用组件图 |
+| 数据架构图 | ER 关系/数据流转 | 类图（ER）/活动图（数据流转）——不用组件图 |
+
+> 本 skill 只深入应用架构图、技术架构图（PlantUML 擅长的）；业务/数据架构给选型指向，不展开。
+
+#### 应用架构图画法（对照真实好图提炼）
+
+- **package 表达分层**：前端层 / 业务前台层 / 领域层 / 现有系统，每层一个 package，层间用 `-down->` 表达自上而下调用
+- **package 可嵌套**：大系统（如"企业用户中心"）内套"前台应用层""底层领域层"两个子 package，表达系统边界 + 内部分层
+- **同层组件同色，层间色系递进**：前端橙系、业务绿系、用户中心蓝系、现有系统紫系；同 package 内组件同色，跨 package 色系区分（色阶见 references）
+- **database/queue 单独画**：MySQL/Redis/Kafka 放最底层，用 `database`/`queue` 关键字区分类型
+- **完整模板见 references/drawing-templates.md「应用架构图」**
+
+### 补充·修改现有功能的流程图（强制 4 件套）
+
+画"修改现有功能"的流程图是技术方案里最高频也最易翻车的场景。仅画节点+箭头=不及格，缺任何一项都算返工。**强制 4 件套**：
+
+| # | 要素 | 不做会怎样 |
+|---|---|---|
+| 1 | 明确上下文边界（入口/出口） | 读者不知道这段流程从哪开始、被谁调、返回到哪 |
+| 2 | 用颜色高亮修订点 + legend | 读者看不出"哪些节点被改过" |
+| 3 | 删除的分支也画出来（用 #LightGray + 虚线 + [DEL]） | 读者不知道"原版有什么"，无法对比 |
+| 4 | 图下方附带"流程变更说明模板"4 段文字 | 读者不知道为什么改、有没有风险、怎么回滚 |
+
+#### 1. 上下文边界（消除"上下文过少"问题）
+
+**入口**：用 note 文字标注"被谁调、触发条件"。**禁止**只画内部逻辑，前面是黑盒。
+
+**出口**：用 note 文字标注"返回到哪里、上游如何处理"。
+
+**关键简化规则**：从触发入口到第一个变更点之间，如果**未改动且非重要节点**的逻辑，可以用 ... 省略，不必逐节点画。
+
+```
+✗ 错误：start → 调度器扫描 → 拉取任务 → 状态校验 → 参数组装 → 触发 doScheduleTask → [改的逻辑]
+✓ 正确：start → 调度器触发 doScheduleTask（注：触发条件=任务状态=WAITING） → [改的逻辑]
+```
+
+判断"未改动且非重要"的两个标准**同时**满足：
+- 这次需求确实没改这段逻辑
+- 读图人不看这段也能理解变更点
+
+只要有一个不满足，就老老实实画全。
+
+#### 2. 修订色高亮 + legend（强制）
+
+**约定的颜色表**：
+
+| 含义 | 颜色 | 文本前缀 | 适用 |
+|---|---|---|---|
+| 新增 | `#LightGreen` | （无） | 本次新加的节点/分支 |
+| 修改后保留 | `#Gold` | （无） | 原版有，本次改了，新版还保留 |
+| 删除（原版有，新版无） | `#LightGray` | `[DEL]` | **必须画出来**，不能只在新版图里删掉 |
+| 默认（无变更） | `#LightBlue` | （无） | 原版就有，本次完全没动 |
+| 关键路径/异常 | `#Salmon` | （无） | 重点关注或异常分支 |
+
+**图底 legend 强制项**（任何修订版流程图都必须带）：
+
+```
+legend right
+  | 颜色 | 含义 |
+  |<#Gold>| 本次修改后保留 |
+  |<#LightGray>| 本次删除 |
+  |<#LightBlue>| 未变更（原版即有） |
+endlegend
+```
+
+#### 3. 删除的分支必须画出来（关键）
+
+很多人画"修改后流程"时，只画新版的内容，把旧版删掉的分支藏起来——这导致读者无法对比"原版 vs 新版"。
+
+**正确做法**：用 #LightGray 虚线框 + `[DEL]` 文本前缀，把删除的分支画出来。
+
+```
+if (新版条件?) then (新版是)
+  :[保留] 新版核心动作;
+elseif ([DEL] 旧版条件?) then ([DEL])
+  :[DEL] 旧版动作;
+  note right: 旧版逻辑，本次删除\n原因：xxx
+else (新版否)
+  :[保留] 新版兜底;
+endif
+```
+
+删除的分支用 note right 简单说明**为什么删**，而不是"凭空消失"。
+
+#### 4. 流程变更说明模板（强制 4 段，缺一段返工）
+
+图下方必须带这 4 段结构化文字，顺序固定：
+
+```
+6.X xxx 流程（修改后）
+[PlantUML 图 + legend]
+
+**变更摘要**（必填，删/改/增 各列 1-2 条）：
+- 删除：xxx 流程中的 xxx 判断分支
+- 修改：xxx 流程的 xxx 条件（从 A 改为 B）
+- 新增：xxx 流程新增 xxx 步骤
+
+**变更动机**（必填，引用 PRD/Issue 链接）：
+- 简述为什么要改，引用 PRD 链接或 Issue
+- 用 1-2 句话点出"旧版痛点"
+
+**影响范围**（必填）：
+- 任务/接口：列出受影响的 Java 类/方法/接口
+- 数据：列出受影响的表/字段
+- 灰度：先发哪台机器，观察多久
+- 监控：列出需要新增/调整的告警项
+
+**回滚方案**（必填）：
+- 如何回退到旧逻辑
+- 是否需要数据回滚
+- 兜底开关在哪里（配置项/特性开关）
+```
+
+**反面教材**：图下方只写"改动：删除时间判断分支"一行——这不够，读者不知道为什么改、有没有风险、怎么回滚都不知道。
+
+#### 4 件套落地 Checklist（画图前自检）
+
+画完后，逐条核对：
+
+- [ ] 入口是否有 note 标注"被谁调、触发条件"
+- [ ] 出口是否有 note 标注"返回到哪里"
+- [ ] 触发入口到变更点之间的非重要节点是否用 ... 省略
+- [ ] 每个修改/新增/删除的节点是否用了约定的颜色
+- [ ] 图底是否带 legend 颜色图例
+- [ ] 删除的分支是否用 #LightGray + [DEL] 画出来
+- [ ] 图下方是否带了 4 段结构化变更说明
+- [ ] 4 段说明是否引用了 PRD/Issue 链接
+- [ ] 变更说明里的"影响范围"是否列出了任务/接口/数据/灰度/监控
+- [ ] 变更说明里的"回滚方案"是否可操作（不是"回滚代码"这种空话）
+
+---
+
+## 主线二：校验
+
+写完必须校验，不校验不交付。Claude 无法凭记忆保证 PlantUML 语法正确，必须跑 jar 抓 `Error line N`。
+
+### 校验命令
+
+```bash
+java -jar "<plantuml.jar路径>" -charset UTF-8 -v file.puml
+```
+
+- exit 0 且输出无 `Error line` = 通过
+- 输出含 `Error line N` = 第 N 行语法错
+- **不要用 `-checkonly`**：它只返回退出码，不打印具体错误行，无法定位
+- `-v` 是 verbose，只有带它（或生成 PNG）才会输出 `Error line N`
+- 中文必须加 `-charset UTF-8`，否则乱码/误报
+
+### 校验的两道闸：Error line + 渲染警告
+
+仅看 `Error line N` 不够，**还要看 jar 是否生成了 PNG + 是否报 `abort` / `too many colors`**。
+
+- exit 0 但 jar 输出包含 `abort` 或 `too many colors` → 渲染异常（常见原因：participant 名字被换行符截断、节点数过多、颜色冲突），即使没报 Error 也要查
+- exit 0 且 PNG 成功生成 → 本地校验通过
+- 仅"exit 0 且无 Error" → **不够**，还要确认 PNG 生成
+
+**怎么确认 PNG 成功生成**：看 jar 输出末尾的 `File size : <N>`，无 `abort` 即视为生成成功。
+
+---
+
+## 主线三：脚本生成 PlantUML 的换行符陷阱
+
+### 问题背景
+
+`@startuml ... @enduml` 之间的源码是普通文本，PlantUML 用反斜杠+小写n（`\n` = backslash + n）表示"换行"，不是真实换行符（Line Feed, 0x0A）。**这是 PlantUML 的硬性规则**。
+
+但当 PlantUML 源码是通过 JS / Python / Shell 脚本动态拼接时，容易踩字符串字面量陷阱：
+
+```
+脚本源码里的 `\n`     →  脚本运行时  →  写入 CDATA 里  →  PlantUML 看到
+─────────────────────────────────────────────────────────────────────────
+JS 模板字符串 "A\nB"   →  A<LF>B     →  A<LF>B              →  ✗ 真实换行，破坏语法
+JS 模板字符串 "A\\nB"  →  A\nB       →  A\nB                →  ✓ 字面 \n，正确
+```
+
+**结果**：本地 `java -jar plantuml.jar -v` 看到的是 `A<LF>B`，能"容错"地解析（很多场景下不会报 Error），但渲染时可能更严格，直接失败。
+
+### 怎么避免：两道闸
+
+**闸 1（写时）**：脚本里需要保留字面 `\n`（backslash + n），**用双反斜杠**：`'A\\nB'`（JS 模板字符串中）→ 运行时是 `A\nB` → PlantUML 看到 `A\nB` 正确换行。
+
+**闸 2（本地校验）**：用 jar 跑校验，确认无 `Error line` + 无 `abort` + PNG 生成成功。
+
+### 不同脚本语言的 `\n` 写法对照
+
+| 场景 | 想保留字面 `\n` | 想写真实换行 |
+|---|---|---|
+| JS 模板字符串 | `'A\\nB'` | `'A\nB'` |
+| JS 普通字符串 | `'A\\nB'` | `'A\nB'` |
+| Python 普通字符串 | `'A\\nB'` | `'A\nB'` |
+| Python raw 字符串 | `r'A\nB'`（✓ 简单） | 不支持，需换行字符串 |
+| Shell 单引号 | `'A\nB'`（✓ 单引号不转义） | `'A<Enter>B'`（物理回车） |
+| Shell 双引号 | `'A\\nB'` | `"A\nB"` |
+| Java 普通字符串 | `"A\\nB"` | `"A\nB"` |
+| Java 文本块（`"""`） | `"A\nB"`（✓ 文本块不转义） | `"""A<Enter>B"""` |
+
+> 容易踩的：JS 模板字符串 + Python f-string + Shell 双引号——都会把 `\n` 当转义。
+> 安全的：Python raw 字符串 + Shell 单引号 + Java 文本块。
+
+---
+
+## 补充·常见语法坑（实测导致渲染失败）
+
+### 活动图（activity，新语法）
+
+- 颜色写在标签前、用合法颜色名，冒号分隔文本：
+  - ✗ `#p:LogWarn[文字];` — `#p` 非合法颜色名；`[文字]` 是 if 分支标签语法，不能用在普通动作行
+  - ✓ `#LightPink:LogWarn: 文字;`
+  - ✓ `#LightBlue:LogInfo: 文字;`
+- 动作标签文本支持真实换行（`:动作;</b>;` 合法）
+- `if` 分支标签才用 `[文字]`，且分支内**禁用多行 note 语法**（必须用单行 `note right: 内容`）：
+  - ✗ `if (x) then (y)\n  note right\n  ...\n  end note` — 活动图 if 分支内多行 note 会报 Error
+  - ✓ `if (x) then (y)\n  note right: 单行内容\nendif`
+
+### 时序图（sequence）
+
+- `->` 消息文本**必须用字面 `\n`**（反斜杠+小写n）表示换行，**绝不能写真实换行**：
+  - ✗ `Alice -> Bob: 第一行\n第二行`（真实换行） — 真实换行会让消息标签跨行，部分场景会破坏语法
+  - ✓ `Alice -> Bob: 第一行\n第二行`（字面 `\n`，一行） — 渲染时 `\n` 变换行
+  - ✓ `note over X: 文本\n文本` 同理
+  - **判断方法**：在文本编辑器里打开 .puml，该行必须是物理单行，行内只能有字面 `\n` 不能有真实换行
+- participant 名字**必须用字面 `\n`**（backslash + n）：
+  - ✗ `participant "WechatMessage<LF>Consumer" as WMC`（真实换行） — 名字被截断
+  - ✓ `participant "WechatMessage\nConsumer" as WMC`（字面 `\n`，物理单行） — 渲染时换行
+
+### 通用
+
+- `@startuml`/`@enduml` 必须成对
+- 中文加 `-charset UTF-8`
+- 颜色用内置名（`LightPink` 等），不自造缩写
+- 嵌套结构（如 `if`/`endif`、`box`/`end box`）必须闭合
+- `left to right direction` **只用于类图/组件图**；活动图（activity）加了会解析失败报 Error line（已实测）。活动图横排无可靠替代，用 `partition` 分区或拆多张图代替
+- jar 输出末尾出现 `abort` 或 `too many colors` → 渲染异常，即使没 `Error line` 也要查