@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/localized/zh-CN/skills/cc-technical-diagrams/assets/quality-examples/README.md

@@ -0,0 +1,14 @@
+# 技术图质量样例
+
+JSON 样例覆盖时序自调用、流程决策回环、架构分组和双向连接。Mermaid 源用于标准时序与流程图；修改布局时保留全部文字和连接关系。
+
+```sh
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs --input skills/cc-technical-diagrams/assets/quality-examples/workflow.json --type workflow --output workflow.html --manifest workflow.layout.json
+node skills/cc-technical-diagrams/scripts/export-diagram.mjs --input workflow.html --format png --output workflow.png --theme light --scale 2 --manifest workflow.layout.json --output-manifest workflow.actual.json
+node skills/cc-technical-diagrams/scripts/png-qa.mjs --png workflow.png --manifest workflow.actual.json --format json
+node skills/cc-technical-diagrams/scripts/mermaid-render.mjs --input skills/cc-technical-diagrams/assets/quality-examples/sequence.mmd --output sequence.svg --report sequence.render.json
+```
+
+PNG 需要本地 Chromium，可用 FEC_BROWSER_PATH 指定路径。Mermaid 需要已安装的 mmdc，不自动安装或使用 CDN；缺失时明确记录并使用 JSON/HTML。需要手工编辑的架构图复用 cc-drawio-studio，大型拓扑可选 Graphviz。
+
+按交付阅读尺寸检查 1x 和 2x 图片，检查形状内部文字、标签和箭头、分支返回、回环、分组及明暗主题对比。几何 QA 不能替代看图。显式尺寸不足或 waypoints 受阻时报告问题，在源级修复且保留意图。默认最多修复两轮，用户要求时最多五轮，未解决则报告部分验收。

package/localized/zh-CN/skills/cc-technical-diagrams/assets/quality-examples/architecture.json

@@ -0,0 +1,121 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "业务平台分层与信任边界"
+  },
+  "visual": {
+    "style": "minimal"
+  },
+  "groups": [
+    {
+      "id": "private",
+      "label": "内部可信网络 / 业务与数据服务",
+      "x": 360,
+      "y": 70,
+      "width": 920,
+      "height": 470,
+      "type": "security"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "web",
+      "label": "用户浏览器应用",
+      "sublabel": "外部入口",
+      "type": "browser",
+      "x": 70,
+      "y": 160,
+      "width": 200,
+      "height": 112
+    },
+    {
+      "id": "gateway",
+      "label": "统一身份验证与请求路由网关",
+      "type": "gateway",
+      "x": 420,
+      "y": 150,
+      "width": 220,
+      "height": 112,
+      "group": "private"
+    },
+    {
+      "id": "service",
+      "label": "订单查询与审批业务服务",
+      "type": "backend",
+      "x": 760,
+      "y": 150,
+      "width": 220,
+      "height": 112,
+      "group": "private"
+    },
+    {
+      "id": "cache",
+      "label": "短期查询结果缓存",
+      "type": "memory",
+      "x": 420,
+      "y": 370,
+      "width": 220,
+      "height": 112,
+      "group": "private"
+    },
+    {
+      "id": "db",
+      "label": "订单与审批记录数据库",
+      "type": "database",
+      "x": 760,
+      "y": 370,
+      "width": 220,
+      "height": 112,
+      "group": "private"
+    },
+    {
+      "id": "queue",
+      "label": "异步任务与消息通知队列",
+      "type": "queue",
+      "x": 1060,
+      "y": 370,
+      "width": 180,
+      "height": 112,
+      "group": "private"
+    }
+  ],
+  "connections": [
+    {
+      "from": "web",
+      "to": "gateway",
+      "label": "鉴权请求",
+      "flow": "control"
+    },
+    {
+      "from": "gateway",
+      "to": "service",
+      "label": "已验证请求",
+      "flow": "control"
+    },
+    {
+      "from": "service",
+      "to": "gateway",
+      "label": "查询响应",
+      "flow": "data"
+    },
+    {
+      "from": "service",
+      "to": "cache",
+      "label": "读取缓存",
+      "flow": "read"
+    },
+    {
+      "from": "service",
+      "to": "db",
+      "label": "查询记录",
+      "flow": "read"
+    },
+    {
+      "from": "service",
+      "to": "queue",
+      "label": "提交通知任务",
+      "flow": "async"
+    }
+  ]
+}

package/localized/zh-CN/skills/cc-technical-diagrams/assets/quality-examples/invalid-explicit.json

@@ -0,0 +1,41 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "预期失败诊断样例"
+  },
+  "nodes": [
+    {
+      "id": "tiny",
+      "label": "A complete long label that cannot fit explicit size",
+      "x": -12,
+      "y": 40,
+      "width": 48,
+      "height": 24
+    },
+    {
+      "id": "overlap",
+      "label": "Overlap",
+      "x": 20,
+      "y": 44,
+      "width": 100,
+      "height": 60
+    }
+  ],
+  "connections": [
+    {
+      "from": "tiny",
+      "to": "overlap",
+      "waypoints": [
+        [
+          30,
+          50
+        ],
+        [
+          800,
+          -20
+        ]
+      ]
+    }
+  ]
+}

package/localized/zh-CN/skills/cc-technical-diagrams/assets/quality-examples/sequence.json

@@ -0,0 +1,53 @@
+{
+  "schema_version": 1,
+  "diagram_type": "sequence",
+  "meta": {
+    "title": "订单查询与缓存回填"
+  },
+  "participants": [
+    {
+      "id": "client",
+      "label": "用户浏览器客户端",
+      "type": "frontend"
+    },
+    {
+      "id": "api",
+      "label": "订单服务接口",
+      "type": "backend"
+    },
+    {
+      "id": "db",
+      "label": "持久化数据库",
+      "type": "database"
+    }
+  ],
+  "messages": [
+    {
+      "from": "client",
+      "to": "api",
+      "label": "查询订单详细信息与当前支付状态"
+    },
+    {
+      "from": "api",
+      "to": "api",
+      "label": "验证身份与订单访问权限"
+    },
+    {
+      "from": "api",
+      "to": "db",
+      "label": "缓存未命中，读取订单记录"
+    },
+    {
+      "from": "db",
+      "to": "api",
+      "label": "返回订单记录与支付状态",
+      "variant": "return"
+    },
+    {
+      "from": "api",
+      "to": "client",
+      "label": "返回查询结果并更新页面",
+      "variant": "return"
+    }
+  ]
+}

package/localized/zh-CN/skills/cc-technical-diagrams/assets/quality-examples/sequence.mmd

@@ -0,0 +1,21 @@
+sequenceDiagram
+ participant Web as 用户浏览器客户端
+ participant API as 订单服务接口
+ participant DB as 持久化数据库
+ Web->>API: 查询订单详细信息与当前支付状态
+ API->>API: 验证身份与订单访问权限
+ API->>DB: 缓存未命中，读取订单记录
+ DB-->>API: 返回订单记录与支付状态
+ API-->>Web: 返回查询结果并更新页面
+
+ activate API
+ alt 缓存命中
+ API-->>Web: 返回缓存结果
+ else 缓存未命中
+ loop 重试失败查询
+ API->>DB: 读取记录
+ DB-->>API: 返回结果
+ end
+ end
+ API-)Web: 异步更新通知
+ deactivate API

package/localized/zh-CN/skills/cc-technical-diagrams/assets/quality-examples/workflow.json

@@ -0,0 +1,98 @@
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "订单审批与异常回退"
+  },
+  "lanes": [
+    {
+      "id": "user",
+      "label": "用户提交"
+    },
+    {
+      "id": "ops",
+      "label": "审批与处理"
+    },
+    {
+      "id": "sys",
+      "label": "系统执行"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "start",
+      "lane": "user",
+      "col": 0,
+      "label": "提交订单申请",
+      "type": "start"
+    },
+    {
+      "id": "check",
+      "lane": "ops",
+      "col": 1,
+      "label": "检查订单信息是否完整且符合审核条件",
+      "type": "decision"
+    },
+    {
+      "id": "approve",
+      "lane": "ops",
+      "col": 2,
+      "label": "人工审批并记录处理意见",
+      "type": "backend"
+    },
+    {
+      "id": "retry",
+      "lane": "user",
+      "col": 1,
+      "label": "补充缺失材料后重新提交",
+      "type": "waiting"
+    },
+    {
+      "id": "save",
+      "lane": "sys",
+      "col": 3,
+      "label": "保存审批结果并异步通知申请人",
+      "type": "database"
+    },
+    {
+      "id": "done",
+      "lane": "sys",
+      "col": 4,
+      "label": "处理完成",
+      "type": "success"
+    }
+  ],
+  "edges": [
+    {
+      "from": "start",
+      "to": "check",
+      "label": "提交审核"
+    },
+    {
+      "from": "check",
+      "to": "approve",
+      "label": "信息完整"
+    },
+    {
+      "from": "check",
+      "to": "retry",
+      "label": "需要补充",
+      "variant": "dashed"
+    },
+    {
+      "from": "retry",
+      "to": "check",
+      "label": "重新审核"
+    },
+    {
+      "from": "approve",
+      "to": "save",
+      "label": "审批通过"
+    },
+    {
+      "from": "save",
+      "to": "done",
+      "label": "通知成功"
+    }
+  ]
+}

package/localized/zh-CN/skills/cc-technical-diagrams/assets/quality-examples/workflow.mmd

@@ -0,0 +1,7 @@
+flowchart TD
+ A([提交订单申请]) --> B{检查订单信息是否完整且符合审核条件}
+ B -->|信息完整| C[人工审批并记录处理意见]
+ B -->|需要补充| D[补充缺失材料后重新提交]
+ D -->|重新审核| B
+ C -->|审批通过| E[(保存审批结果并异步通知申请人)]
+ E -->|通知成功| F([处理完成])

package/localized/zh-CN/skills/{fec-image-generation → cc-technical-diagrams}/references/diagram-workflows.md

@@ -7,10 +7,10 @@
 | ER 图 | Mermaid ER、DBML、Graphviz、SVG | 基数标签、表名、关键字段、交叉关系。 |
 | UML 类图 | Mermaid class、PlantUML、Graphviz | 继承方向、方法/属性换行、包分组。 |
 | 序列图 | Mermaid sequence、PlantUML | lifeline 顺序、activation 范围、异步/返回箭头、消息文本。 |
-| 技术架构 | HTML `architecture` IR、Mermaid flowchart、C4/Structurizr、SVG/HTML、draw.io | 分层分组、信任边界、数据流方向、图例。 |
+| 技术架构 | draw.io、Mermaid/C4、HTML `architecture` IR、SVG/HTML | 分层分组、信任边界、数据流方向、图例。 |
 | Agent / memory 架构 | 带语义节点类型和 flow 连线的 HTML `architecture` IR、SVG/HTML、draw.io | read/write 路径分离、tool-call 回路、memory 分层、retrieval 标签、flow legend。 |
 | ML / 深度学习 | SVG/HTML/canvas | tensor shape、层顺序、分支汇合、重复块、注释。 |
-| 流程图 / 流程工作流 | HTML `workflow` IR、Mermaid flowchart、SVG、draw.io | 决策标签、终止状态、回环可读性、连接线间距、异常路径清晰度。 |
+| 流程图 / 流程工作流 | Mermaid flowchart、HTML `workflow` IR、SVG、draw.io | 决策标签、终止状态、回环可读性、连接线间距、异常路径清晰度。 |
 | 会话实时草图 | 本地交互式浏览器服务 | 增量呈现、session 隔离、拖拽后的标签可读性、导出交接。 |
 
 ## 交互式实时图表
@@ -20,7 +20,7 @@
 启动本地服务：
 
 ```bash
-node skills/fec-image-generation/scripts/interactive-diagram-server.mjs --port 6100
+node skills/cc-technical-diagrams/scripts/interactive-diagram-server.mjs --port 6100
 ```
 
 打开 `http://127.0.0.1:6100/?s=meaningful-session-id`，再向 `/cmd?s=meaningful-session-id` 发送命令。每张图都必须使用唯一 session id。先发送 `init`，再添加节点，最后添加连线；每条命令尽量小，让浏览器能持续增量更新。
@@ -50,7 +50,7 @@ node skills/fec-image-generation/scripts/interactive-diagram-server.mjs --port 6
 ## 图表修复手册
 
 - **节点重叠：** 增加 rank/列间距、拆分簇，或将低优先级注释移入图例。
-- **标签截断：** 加宽节点、添加手动换行、缩短标签，或提高导出倍率。
+- **标签截断：** 加宽节点、添加手动换行、保留完整文字并调整源布局。
 - **连接线穿过标签：** 添加 waypoints、沿框体周围正交布线，或将标签移到线段上方。
 - **连接线堆叠：** 用不同 waypoints 分离平行边，或用带共享标签的 bus 汇总。
 - **边缘裁剪：** 增加外边距，或扩大导出 viewBox/canvas 尺寸。
@@ -67,8 +67,15 @@ UML 覆盖优先走确定性源：class、ER、state-machine、activity 和 sequ
 
 ## 流程工作流
 
-用户需要浏览器可打开的流程地图、审批流、自动化 runbook、事故流程或循环运营流程，并且需要泳道、步骤编号、参与者、决策、异常路径和摘要卡片时，优先使用 HTML `workflow` IR。流程必须作为 `.drawio` 文件长期维护、需要 diagrams.net 编辑、官方形状库、手工泳道维护或交付后由利益相关方继续修改时，改用 `fec-drawio-studio`。
+用户需要浏览器可打开的流程地图、审批流、自动化 runbook、事故流程或循环运营流程，并且需要泳道、步骤编号、参与者、决策、异常路径和摘要卡片时，优先使用 HTML `workflow` IR。流程必须作为 `.drawio` 文件长期维护、需要 diagrams.net 编辑、官方形状库、手工泳道维护或交付后由利益相关方继续修改时，改用 `cc-drawio-studio`。
 
 ## 导出指引
 
 位图 PNG 优先以 2x 倍率导出；只有在文字仍清晰时才下采样。凡是未来可能修改图表的地方，都应提交或附上可编辑源文件。
+
+
+## 质量交付约定
+
+标准序列/流程图优先本地 Mermaid；架构图需要手工编辑时复用 cc-drawio-studio，大型拓扑可选 Graphviz。无本地工具时使用兼容 JSON/HTML，不自动安装或下载。HTML 预览、独立 SVG 和 PNG 使用同源主题样式；导出指定 `--theme light|dark`。PNG 导出等待字体并测量文字，使用 `--manifest source.layout.json --output-manifest image.actual.json` 写出缩放后的像素坐标。QA 必须读取 actual manifest，不能把估算坐标直接用于 2x PNG。
+
+扩展 manifest 保留 canvas/boxes/connectors，增加 coordinateSpace、scale、measurement、groups、labels 与 issues。分组包含节点不算节点重叠。新增 node-text-overflow、label-content-loss、label-out-of-bounds、edge-label-collision、text-overlap 与 degenerate-connector 检查。旧 manifest 保留估算检测。显式尺寸或 waypoints 不满足约束时定位问题，不删字、不改关系、不静默移动。提高导出分辨率不能修复源级溢出。最终 PNG 必须视觉审阅；记录工具可用性、版本、主题、比例、修复轮次和残留问题，未解决时标记部分验收。

package/localized/zh-CN/skills/{fec-image-generation → cc-technical-diagrams}/references/html-technical-diagrams.md

@@ -7,7 +7,7 @@
 | 需求 | 优先选择 |
 | ---- | -------- |
 | 小型 Markdown 维护图 | Mermaid、Graphviz 或 SVG |
-| 后续人工编辑的图源 | `fec-drawio-studio` 和 `.drawio` |
+| 后续人工编辑的图源 | `cc-drawio-studio` 和 `.drawio` |
 | 浏览器可打开的主题化技术图 | HTML 技术图路线 |
 | 位图优先的视觉概念、海报、产品图或图片编辑 | 图片生成或编辑路线 |
 
@@ -19,7 +19,7 @@
 - `dataflow`：来源、采集、处理、存储、消费者、PII 边界、治理、分析和血缘。
 - `lifecycle`：对象状态、终止状态、重试、等待、取消、超时、部署或订单状态流转。
 
-浏览器可交付的架构总览优先用 `architecture` 模式。需要 `.drawio` 源、官方厂商图标、diagrams.net 手工编辑或复杂自动布局时，改用 `fec-drawio-studio`。
+浏览器可交付的架构总览优先用 `architecture` 模式。需要 `.drawio` 源、官方厂商图标、diagrams.net 手工编辑或复杂自动布局时，改用 `cc-drawio-studio`。
 
 ## 主题化语义图
 
@@ -65,8 +65,8 @@ Agent、memory 和 AI 工作流图优先在 architecture 节点上使用语义 `
 面向 README 或干系人交付时，保留 JSON IR 和 HTML 作为可编辑事实源，再导出 SVG/PNG/JPG 产物：
 
 ```bash
-node skills/fec-image-generation/scripts/export-diagram.mjs --input docs/architecture/system-blueprint.html --format svg
-node skills/fec-image-generation/scripts/export-diagram.mjs --input docs/architecture/system-blueprint.html --format png --scale 2
+node skills/cc-technical-diagrams/scripts/export-diagram.mjs --input docs/architecture/system-blueprint.html --format svg
+node skills/cc-technical-diagrams/scripts/export-diagram.mjs --input docs/architecture/system-blueprint.html --format png --scale 2
 ```
 
 位图导出会优先使用本机已有的 Chromium 系浏览器。环境无法栅格化 SVG 时，交付生成的 HTML/SVG，并说明 PNG/JPG 导出需要本地浏览器。
@@ -198,7 +198,7 @@ Workflow 连线字段：
 ## 渲染命令
 
 ```bash
-node skills/fec-image-generation/scripts/tech-diagram-render.mjs \
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs \
   --input diagram.json \
   --output diagram.html \
   --type architecture \
@@ -217,7 +217,7 @@ node skills/fec-image-generation/scripts/tech-diagram-render.mjs \
 导出 PNG 后运行：
 
 ```bash
-node skills/fec-image-generation/scripts/png-qa.mjs \
+node skills/cc-technical-diagrams/scripts/png-qa.mjs \
   --png diagram.png \
   --manifest diagram.layout.json \
   --format markdown
@@ -226,7 +226,7 @@ node skills/fec-image-generation/scripts/png-qa.mjs \
 修复应回到 JSON 源或渲染尺寸：
 
 - 重叠：拆分密集分组，或增加节点/分组间距。
-- 标签截断：缩短标签、添加 `sublabel` 或加宽节点。
+- 标签截断：对完整标签换行、保留文字或加宽节点。
 - 连线穿过标签：减少边标签，添加 `waypoints`，或移动节点。
 - 流向过密：拆成总览图和细节图。
 - 边缘裁剪：增加输出空间或简化路径。
@@ -234,3 +234,10 @@ node skills/fec-image-generation/scripts/png-qa.mjs \
 ## 交付说明
 
 交付 `.html` 源和用户要求的 SVG/PNG/JPG。说明使用的路线、源文件、导出文件、QA 结果，以及仍需人工确认的命名或领域假设。
+
+
+## 质量交付约定
+
+标准序列/流程图优先本地 Mermaid；架构图需要手工编辑时复用 cc-drawio-studio，大型拓扑可选 Graphviz。无本地工具时使用兼容 JSON/HTML，不自动安装或下载。HTML 预览、独立 SVG 和 PNG 使用同源主题样式；导出指定 `--theme light|dark`。PNG 导出等待字体并测量文字，使用 `--manifest source.layout.json --output-manifest image.actual.json` 写出缩放后的像素坐标。QA 必须读取 actual manifest，不能把估算坐标直接用于 2x PNG。
+
+扩展 manifest 保留 canvas/boxes/connectors，增加 coordinateSpace、scale、measurement、groups、labels 与 issues。分组包含节点不算节点重叠。新增 node-text-overflow、label-content-loss、label-out-of-bounds、edge-label-collision、text-overlap 与 degenerate-connector 检查。旧 manifest 保留估算检测。显式尺寸或 waypoints 不满足约束时定位问题，不删字、不改关系、不静默移动。提高导出分辨率不能修复源级溢出。最终 PNG 必须视觉审阅；记录工具可用性、版本、主题、比例、修复轮次和残留问题，未解决时标记部分验收。

package/localized/zh-CN/skills/cc-technical-diagrams/references/png-qa-autofix.md

@@ -0,0 +1,37 @@
+# PNG 质检与自动修复
+
+## 循环
+
+1. 从可编辑源文件或图像工作流导出 PNG。
+2. 目视检查 PNG。
+3. 有 manifest 时，带 manifest 运行 `png-qa.mjs`。
+4. 将每个问题转化为源文件、提示词或布局变更。
+5. 默认重复 2 轮；用户要求更多修复尝试时最多 5 轮。
+
+## 问题映射
+
+| 问题 | 修复方式 |
+| ----- | ------ |
+| `blank-image` | 检查导出目标、渲染器错误、隐藏图层、透明填充或图像生成失败。 |
+| `edge-clipping` | 增加画布留白、扩大 SVG viewBox、降低主体缩放，或导出更大的画幅。 |
+| `box-overlap` | 增加间距、重排为网格/图层、拆分簇，或对完整标签换行。 |
+| `box-out-of-bounds` | 将节点移入画布，或增大画布尺寸。 |
+| `label-overflow` | 文本换行、加宽框体、保留完整文案，并同时增大字体/容器尺寸。 |
+| `connector-through-label` | 在框体周围添加 waypoints、移动标签，或使用正交布线。 |
+| `connector-stacking` | 偏移平行连接线，或用带标签的分组路径替代重复线条。 |
+| `manifest-canvas-mismatch` | 根据最终导出尺寸重新生成 manifest。 |
+
+## Manifest 质量
+
+只有当 manifest 坐标与导出的 PNG 匹配时，辅助脚本才能判断重叠和连接线问题。若 manifest 过期，先修复 manifest，再重新运行 QA。
+
+## 报告要求
+
+报告 QA 轮数和最终问题列表。若由于源渲染器无法暴露布局坐标而仍有遗留问题，说明哪些检查只能基于图像，哪些需要人工视觉复核。
+
+
+## 质量交付约定
+
+标准序列/流程图优先本地 Mermaid；架构图需要手工编辑时复用 cc-drawio-studio，大型拓扑可选 Graphviz。无本地工具时使用兼容 JSON/HTML，不自动安装或下载。HTML 预览、独立 SVG 和 PNG 使用同源主题样式；导出指定 `--theme light|dark`。PNG 导出等待字体并测量文字，使用 `--manifest source.layout.json --output-manifest image.actual.json` 写出缩放后的像素坐标。QA 必须读取 actual manifest，不能把估算坐标直接用于 2x PNG。
+
+扩展 manifest 保留 canvas/boxes/connectors，增加 coordinateSpace、scale、measurement、groups、labels 与 issues。分组包含节点不算节点重叠。新增 node-text-overflow、label-content-loss、label-out-of-bounds、edge-label-collision、text-overlap 与 degenerate-connector 检查。旧 manifest 保留估算检测。显式尺寸或 waypoints 不满足约束时定位问题，不删字、不改关系、不静默移动。提高导出分辨率不能修复源级溢出。最终 PNG 必须视觉审阅；记录工具可用性、版本、主题、比例、修复轮次和残留问题，未解决时标记部分验收。