harveyz-skill 0.1.2 → 0.2.0

package/skills/writing/mermaid-diagram/references/color-templates.md

@@ -0,0 +1,75 @@
+# Roland Berger 配色标准
+
+## 色板总览
+
+| 角色 | 用途 | fill | stroke |
+|------|------|------|--------|
+| **subgraph 上游** | 最底层 / 最重要 / 上游容器 | `#00205B` | `#1E4A9A` |
+| **subgraph 中游** | 中间层 / 平台层容器 | `#003E96` | `#1A6AC4` |
+| **subgraph 下游** | 应用层 / 端侧容器 | `#1E5C9E` | `#3A8ACC` |
+| **节点 上游** | 上游 subgraph 内的节点 | `#0A2E7A` | `#1E4A9A` |
+| **节点 中游** | 中游 subgraph 内的节点 | `#0050B8` | `#1A6AC4` |
+| **节点 下游** | 下游 subgraph 内的节点 | `#2A6EAE` | `#3A8ACC` |
+
+**规律**：同层的 subgraph 比其内节点颜色**深 10–15%**，形成层次感。文字颜色一律 `color:#fff`。
+
+---
+
+## 语义辅助色
+
+用于传达风险信号，叠加在主色体系之上：
+
+| 语义 | 场景 | fill | stroke |
+|------|------|------|--------|
+| 预警 / 高风险 / 规避 | 危险区域、卖出信号 | `#7B1010` | `#B52020` |
+| 机会 / 买入 / 低风险 | 买入区域、推荐配置 | `#1A5E3A` | `#2A7E50` |
+| 等待 / 持有 / 中性 | 观察区域、中性态度 | `#003E96` | `#1A6AC4` |
+| 投机 / 主题 / 高波动 | 高风险高回报区域 | `#2E0078` | `#5A20A0` |
+| 价值 / 配置 / 稳健 | 价值投资区域 | `#004060` | `#1A5E80` |
+
+---
+
+## 使用规则
+
+1. **深色背景必须加白字**：任何 `fill` 颜色深于 `#4A4A4A`，必须加 `color:#fff`
+2. **单图最多 3 种主色**：不要同时使用上游/中游/下游/语义色全部五组
+3. **容器比节点深**：subgraph 的 fill 必须比其内节点的 fill 深，否则层次感消失
+4. **sequenceDiagram / gantt / timeline 不着色**：这些类型使用库默认颜色，不应用 RB 色板
+5. **语义色优先级低于主色**：只在需要传达明确风险信号时才使用语义辅助色
+
+---
+
+## style 片段速查
+
+三层结构（直接复制，按实际节点 ID 替换）：
+
+```
+style UP   fill:#00205B,color:#fff,stroke:#1E4A9A
+style MID  fill:#003E96,color:#fff,stroke:#1A6AC4
+style DOWN fill:#1E5C9E,color:#fff,stroke:#3A8ACC
+
+style U1 fill:#0A2E7A,color:#fff,stroke:#1E4A9A
+style M1 fill:#0050B8,color:#fff,stroke:#1A6AC4
+style D1 fill:#2A6EAE,color:#fff,stroke:#3A8ACC
+```
+
+两层结构：
+
+```
+style TOP fill:#00205B,color:#fff,stroke:#1E4A9A
+style BOT fill:#003E96,color:#fff,stroke:#1A6AC4
+
+style T1 fill:#0A2E7A,color:#fff,stroke:#1E4A9A
+style B1 fill:#0050B8,color:#fff,stroke:#1A6AC4
+```
+
+语义色（按需挑选）：
+
+```
+style X fill:#7B1010,color:#fff,stroke:#B52020   /* 预警红 */
+style X fill:#1A5E3A,color:#fff,stroke:#2A7E50   /* 机会绿 */
+style X fill:#2E0078,color:#fff,stroke:#5A20A0   /* 投机紫 */
+style X fill:#004060,color:#fff,stroke:#1A5E80   /* 价值蓝绿 */
+```
+
+> 含真实内容的完整产业链示例 → `references/flowchart.md`

package/skills/writing/mermaid-diagram/references/flowchart.md

@@ -0,0 +1,88 @@
+# flowchart 详细规则与布局技法
+
+## 基本语法
+
+```yaml
+方向:    TD 优先；LR 仅用于天然横向内容
+节点:    ["标签"] 格式，标签内用 <br/> 换行
+子图:    subgraph ID["显示名"] ... end
+颜色:    style NodeID fill:#xxx,color:#fff,stroke:#xxx
+边:      --> 有向；--- 无向（用于矩阵配对）；-.-> 虚线
+禁止:    emoji, ·, →, direction TB in subgraph
+```
+
+## 矩阵布局（subgraph 内 2 列网格）
+
+当 subgraph 内节点 ≥ 4 个时，用 `---`（无向边）配对强制 2 列布局：
+
+```mermaid
+flowchart TD
+    subgraph LAYER["层级名称"]
+        A["节点A"] --- B["节点B"]
+        C["节点C"] --- D["节点D"]
+        E["单数节点（居中）"]
+    end
+```
+
+- `---` 产生细线连接，视觉上表示"同组"
+- 奇数节点放最后一行，独立居中
+- 严禁 4 个或以上节点堆在同一无连接行（会横向撑满）
+
+## subgraph 间箭头
+
+```mermaid
+flowchart TD
+    subgraph UP["上游"] end
+    subgraph MID["中游"] end
+    subgraph DOWN["下游"] end
+
+    UP -->|"标签"| MID
+    MID -->|"标签"| DOWN
+```
+
+- subgraph ID 可直接作为箭头端点（Mermaid v9+）
+- 层间箭头标签保持**单行短语**，不用 `\n`
+
+## 多行节点标签
+
+```
+✅ A["第一行<br/>第二行<br/>第三行"]
+❌ A["第一行\n第二行\n第三行"]   ← \n 在部分渲染器失效
+```
+
+---
+
+## 完整示例：三层产业链板块地图
+
+```mermaid
+flowchart TD
+    subgraph UP["上游 算力基础设施"]
+        U1["AI芯片 / 晶圆代工<br/>NVIDIA AMD Broadcom<br/>寒武纪 海光"] --- U2["设备 / 存储 HBM<br/>ASML 北方华创<br/>SK海力士 Micron"]
+        U3["光模块 / 服务器<br/>中际旭创 新易盛<br/>工业富联 Dell"]  --- U4["IDC / 液冷 / 电力<br/>英维克 Vertiv<br/>阳光电源 VST"]
+    end
+
+    subgraph MID["中游 模型与平台"]
+        M1["大模型<br/>GPT Gemini 通义 DeepSeek"] --- M2["云平台<br/>Azure AWS 阿里云 腾讯云"]
+    end
+
+    subgraph DOWN["下游 应用与端侧"]
+        D1["企业SaaS<br/>Palantir ServiceNow<br/>金山办公"] --- D2["AI编程 / 搜索<br/>Copilot Cursor Google"]
+        D3["端侧硬件<br/>机器人 智驾 AI眼镜"]
+    end
+
+    UP -->|"卖铲子"| MID
+    MID -->|"挖金子"| DOWN
+
+    style UP   fill:#00205B,color:#fff,stroke:#1E4A9A
+    style MID  fill:#003E96,color:#fff,stroke:#1A6AC4
+    style DOWN fill:#1E5C9E,color:#fff,stroke:#3A8ACC
+    style U1 fill:#0A2E7A,color:#fff,stroke:#1E4A9A
+    style U2 fill:#0A2E7A,color:#fff,stroke:#1E4A9A
+    style U3 fill:#0A2E7A,color:#fff,stroke:#1E4A9A
+    style U4 fill:#0A2E7A,color:#fff,stroke:#1E4A9A
+    style M1 fill:#0050B8,color:#fff,stroke:#1A6AC4
+    style M2 fill:#0050B8,color:#fff,stroke:#1A6AC4
+    style D1 fill:#2A6EAE,color:#fff,stroke:#3A8ACC
+    style D2 fill:#2A6EAE,color:#fff,stroke:#3A8ACC
+    style D3 fill:#2A6EAE,color:#fff,stroke:#3A8ACC
+```

package/skills/writing/mermaid-diagram/references/gantt-timeline.md

@@ -0,0 +1,62 @@
+# gantt / timeline 详细规则与示例
+
+## gantt
+
+```yaml
+日期格式:  dateFormat YYYY-MM-DD（必须，不可用 YYYY-Q 或其他格式）
+轴标签:   axisFormat %Y（年份粒度）或 %b %Y（月份+年份）
+          默认不写则渲染器自选，通常不美观，建议显式声明
+状态:     done（已完成）/ active（进行中）/ 空（未来计划）
+任务ID:   ASCII，不含特殊字符
+中文任务名: 直接写在 : 前，可以含中文
+```
+
+示例：
+
+```mermaid
+gantt
+    title GPU芯片技术迭代
+    dateFormat YYYY-MM-DD
+    axisFormat %Y
+
+    section 英伟达 NVIDIA
+    A100     :done,   nv1, 2020-04-01, 2022-09-01
+    H100     :done,   nv2, 2022-09-01, 2024-06-01
+    B100     :active, nv3, 2024-06-01, 2026-01-01
+
+    section AMD
+    MI250    :done,   amd1, 2021-11-01, 2023-12-01
+    MI300    :active, amd2, 2023-12-01, 2025-06-01
+```
+
+**axisFormat 选择原则：**
+- 跨度 ≥ 3 年 → `%Y`（只显示年份，不拥挤）
+- 跨度 3–18 个月 → `%b %Y`（月份缩写 + 年份）
+- 跨度 < 3 个月 → `%m-%d`
+
+---
+
+## timeline
+
+```yaml
+结构:    timeline → title → section（可选）→ key : event1 \n : event2
+key:     纯文本，不含 + % & 等特殊字符
+section: 分组用，可选
+注意:    不支持自定义颜色；渲染为垂直时间轴，天然窄页友好
+```
+
+示例：
+
+```
+timeline
+    title AI 大模型发展里程碑
+    section 2022
+        ChatGPT 发布 : OpenAI 推出对话式 AI
+                      : 用户量 1 亿破纪录
+    section 2023
+        GPT-4 发布    : 多模态能力
+        Claude 2      : Anthropic 发布
+    section 2024
+        o1 系列       : 推理模型时代开启
+        DeepSeek R1   : 开源推理模型
+```

package/skills/writing/mermaid-diagram/references/other-charts.md

@@ -0,0 +1,55 @@
+# quadrantChart / mindmap 详细规则
+
+## quadrantChart
+
+```yaml
+quadrant标签: 不含 / & → 等字符
+              ❌ quadrant-3 减仓/规避
+              ✅ quadrant-3 减仓规避
+点标签:       "标签名: [x, y]"，x/y 在 0.0–1.0 之间
+              中文标签可用，但不能有冒号之外的特殊字符
+```
+
+示例：
+
+```mermaid
+quadrantChart
+    title 板块配置矩阵
+    x-axis 确定性低 --> 确定性高
+    y-axis 弹性低 --> 弹性高
+    quadrant-1 重仓配置
+    quadrant-2 高风险高回报
+    quadrant-3 规避区域
+    quadrant-4 低配持有
+    AI算力: [0.8, 0.9]
+    新能源: [0.5, 0.6]
+    消费: [0.3, 0.3]
+```
+
+---
+
+## mindmap
+
+```yaml
+缩进:    严格 2 空格/级，不混用 tab
+节点文本: 纯文本，不含 : ( ) [ ] { } 等 Mermaid 控制字符
+root:    root((显示文本)) 圆形；root[文本] 方形
+分隔符:  同级用空格，不用 · / → 等
+```
+
+示例：
+
+```mermaid
+mindmap
+  root((AI产业))
+    算力层
+      芯片
+      存储
+      服务器
+    模型层
+      基础模型
+      微调模型
+    应用层
+      企业软件
+      消费应用
+```

package/skills/writing/mermaid-diagram/references/sequence.md

@@ -0,0 +1,143 @@
+# sequenceDiagram 详细规则与示例
+
+## 基本语法
+
+```yaml
+参与者:   participant A as 显示名（推荐）或 participant "含空格/中文名"
+角色图标: actor 替代 participant，渲染为火柴人（人类角色用 actor，系统用 participant）
+箭头:     ->>  同步调用（实线箭头）
+          -->> 返回/异步响应（虚线箭头）
+          -x   消息丢失（实线+X，表示失败/超时）
+          --x  异步失败
+激活框:   activate A ... deactivate A （或缩写 ->>+ / ->>-）
+编号:     autonumber（在 sequenceDiagram 下一行加此关键字）
+```
+
+## 最重要规则：参与者名称
+
+含中文、空格或特殊字符的参与者名必须处理，否则语法报错：
+
+```
+✅ participant U as 用户
+✅ participant "用户服务"
+✅ actor Client as 客户端
+❌ participant 用户服务          ← 中文无引号，部分渲染器报错
+❌ participant User Service     ← 空格无引号，报错
+```
+
+**推荐用 alias 语法（`X as 显示名`）而非引号**：ID 保持 ASCII，显示名随意。
+
+## activate / deactivate 配对规则
+
+每个 `activate X` 必须有对应的 `deactivate X`，否则激活框会无限叠加：
+
+```mermaid
+sequenceDiagram
+    participant C as 客户端
+    participant S as 服务端
+
+    C ->> S: 请求
+    activate S
+    S -->> C: 响应
+    deactivate S
+```
+
+**简写形式**（`->>+` 等价于发送后 activate，`-->>-` 等价于返回后 deactivate）：
+
+```mermaid
+sequenceDiagram
+    participant C as 客户端
+    participant S as 服务端
+
+    C ->>+ S: 请求
+    S -->>- C: 响应
+```
+
+## 条件 / 循环 / 并行块
+
+所有块必须以 `end` 关闭：
+
+```mermaid
+sequenceDiagram
+    participant C as 客户端
+    participant S as 服务端
+    participant DB as 数据库
+
+    C ->> S: 查询用户
+
+    alt 缓存命中
+        S -->> C: 返回缓存
+    else 缓存未命中
+        S ->> DB: 查询数据库
+        activate DB
+        DB -->> S: 返回数据
+        deactivate DB
+        S -->> C: 返回结果
+    end
+
+    loop 每5分钟心跳
+        C ->> S: ping
+        S -->> C: pong
+    end
+
+    par 并行操作
+        S ->> DB: 写日志
+    and
+        S ->> S: 更新缓存
+    end
+```
+
+## Note 注释
+
+```
+Note right of A: 文字          ← A 右侧
+Note left of A: 文字           ← A 左侧
+Note over A,B: 跨越 A 和 B     ← 跨多个参与者
+```
+
+## 窄页宽度控制
+
+sequenceDiagram 天然横向排列，参与者越多越宽：
+
+- **≤ 5 个参与者**可适配 700–900px 的 Markdown 窄页
+- 超过 5 个时，考虑拆成两张图或用 `destroy` 提前移除不再需要的参与者
+
+## 禁止事项
+
+```
+❌ 消息文本内换行（\n / <br/>）    → sequenceDiagram 消息只支持单行
+❌ activate 未配对 deactivate      → 会产生叠加激活框 bug
+❌ 中文/空格参与者名不加处理        → 用 alias 或引号
+❌ 禁用字符（· → — "" emoji）     → 同其他图类型规则
+❌ 自定义颜色（style/classDef）    → sequenceDiagram 不支持节点着色
+```
+
+## 完整示例：API 调用时序
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as 用户
+    participant G as API网关
+    participant A as 认证服务
+    participant B as 业务服务
+    participant DB as 数据库
+
+    U ->>+ G: POST /api/order
+    G ->>+ A: 验证 Token
+    A -->>- G: Token 有效
+
+    G ->>+ B: 创建订单
+    B ->>+ DB: INSERT order
+    DB -->>- B: 成功
+
+    alt 库存充足
+        B -->>- G: 订单ID: 12345
+        G -->>- U: 200 创建成功
+    else 库存不足
+        B -->>- G: 错误: 库存不足
+        G -->>- U: 400 库存不足
+    end
+
+    Note over B,DB: 异步写入审计日志
+```

package/skills/writing/mermaid-diagram/references/statediagram.md

@@ -0,0 +1,54 @@
+# stateDiagram-v2 详细规则与示例
+
+## 基本语法
+
+```yaml
+方向:     direction TB（不用 LR，否则横向过宽）
+state ID: 只用 ASCII（S1 S2 Idle 等）
+显示文本: state "中文描述" as ASCII_ID
+转换标签: S1 --> S2 : 简短描述（单行，无 → / 等特殊字符）
+```
+
+## 为什么 state ID 必须是 ASCII
+
+Mermaid 解析器对中文 state ID 的支持不稳定——某些渲染器（如 GitHub、Notion）
+会报语法错误或产生乱码。始终用 ASCII ID + `state "..." as ID` 语法：
+
+```mermaid
+stateDiagram-v2
+    direction TB
+    [*] --> S1
+    state "概念炒作阶段 PE 30x to 100x+" as S1
+    state "业绩验证阶段" as S2
+    S1 --> S2 : 财报兑现
+    S2 --> S1 : 预期落空
+```
+
+## 语义配色（classDef）
+
+```mermaid
+stateDiagram-v2
+    direction TB
+    classDef opportunity fill:#1A5E3A,stroke:#2A7E50,color:#fff
+    classDef hold        fill:#003E96,stroke:#1A6AC4,color:#fff
+    classDef danger      fill:#7B1010,stroke:#B52020,color:#fff
+
+    state "买入区" as S1
+    state "持有区" as S2
+    state "规避区" as S3
+
+    [*] --> S1
+    S1 --> S2 : 价格回升
+    S2 --> S3 : 估值透支
+    S3 --> S1 : 回调充分
+
+    class S1 opportunity
+    class S2 hold
+    class S3 danger
+```
+
+## 注意事项
+
+- `note right of / left of` 语法部分渲染器不支持，谨慎使用
+- 转换标签（`:` 后）避免 `/`、`→`、`<`、`>` 等特殊字符
+- 不使用 nested state（嵌套状态）——渲染不稳定

package/skills/writing/mermaid-diagram/scripts/check_mermaid.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""
+Mermaid block validator — checks for known fatal characters and syntax errors.
+
+Usage:
+    python check_mermaid.py report.md
+    python check_mermaid.py *.md
+"""
+
+import re
+import sys
+
+RISKY_CHARS = {
+    '·': 'middle-dot ·',
+    '→': 'arrow →',
+    '—': 'em-dash —',
+    '“': 'left-quote "',
+    '”': 'right-quote "',
+}
+
+
+def check_mermaid_blocks(md_content: str) -> list[str]:
+    blocks = re.findall(r'```mermaid\n(.*?)```', md_content, re.DOTALL)
+    issues = []
+
+    for i, block in enumerate(blocks, 1):
+        dtype = block.strip().split('\n')[0]
+        label = f"图{i} [{dtype}]"
+
+        for ch, name in RISKY_CHARS.items():
+            if ch in block:
+                issues.append(f"{label}: 含禁用字符 {name}")
+
+        if 'flowchart' in dtype or 'graph' in dtype:
+            if re.search(r'"[^"]*\\n[^"]*"', block):
+                issues.append(f"{label}: 节点标签含 \\n，应改 <br/>")
+
+        if 'flowchart LR' in block:
+            issues.append(f"{label}: 使用横向 LR，评估是否需改 TD")
+
+        if 'direction LR' in block and 'stateDiagram' in dtype:
+            issues.append(f"{label}: stateDiagram 使用 direction LR，建议改 TB")
+
+        if 'quadrantChart' in dtype and re.search(r'quadrant-\d[^#\n]*/[^#\n]*', block):
+            issues.append(f"{label}: quadrant 标签含 /")
+
+        if 'gantt' in dtype and re.search(r'\d{4}-Q\d', block):
+            issues.append(f"{label}: gantt 使用 YYYY-Q 格式，应改 YYYY-MM-DD")
+
+        if 'stateDiagram' in dtype:
+            lines = block.split('\n')
+            for line in lines:
+                line = line.strip()
+                if line.startswith('state ') and ' as ' not in line:
+                    state_id = line.split()[1].strip('"\'')
+                    if any(ord(c) > 127 for c in state_id):
+                        issues.append(f"{label}: state ID 含中文，应用 ASCII ID + as 别名")
+
+    return issues
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python check_mermaid.py <file.md> [file2.md ...]")
+        sys.exit(1)
+
+    all_clean = True
+    for path in sys.argv[1:]:
+        with open(path, encoding='utf-8') as f:
+            content = f.read()
+        issues = check_mermaid_blocks(content)
+        if issues:
+            all_clean = False
+            print(f"\n{path}:")
+            for issue in issues:
+                print(f"  ❌ {issue}")
+        else:
+            print(f"{path}: ✅ 通过")
+
+    sys.exit(0 if all_clean else 1)
+
+
+if __name__ == '__main__':
+    main()