@bovinphang/craft-common 0.0.0-stage → 1.0.1

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/cc-technical-diagrams/references/diagram-workflows.md

@@ -0,0 +1,81 @@
+# 图表工作流
+
+## 事实源选择
+
+| 图表类型 | 首选源 | QA 重点 |
+| ------------ | ---------------- | -------- |
+| ER 图 | Mermaid ER、DBML、Graphviz、SVG | 基数标签、表名、关键字段、交叉关系。 |
+| UML 类图 | Mermaid class、PlantUML、Graphviz | 继承方向、方法/属性换行、包分组。 |
+| 序列图 | Mermaid sequence、PlantUML | lifeline 顺序、activation 范围、异步/返回箭头、消息文本。 |
+| 技术架构 | 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、层顺序、分支汇合、重复块、注释。 |
+| 流程图 / 流程工作流 | Mermaid flowchart、HTML `workflow` IR、SVG、draw.io | 决策标签、终止状态、回环可读性、连接线间距、异常路径清晰度。 |
+| 会话实时草图 | 本地交互式浏览器服务 | 增量呈现、session 隔离、拖拽后的标签可读性、导出交接。 |
+
+## 交互式实时图表
+
+当图表本身是对话的一部分，并且用户能从“边生成边看见结构出现”中受益时，使用实时路线。它适合流程草图、架构初稿、简短思维导图式拆解，以及需要先拖拽或改标签再导出的快速讲解图。
+
+启动本地服务：
+
+```bash
+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`，再添加节点，最后添加连线；每条命令尽量小，让浏览器能持续增量更新。
+
+支持的命令包括 `init`、`node`、`edge`、`container`、`remove`、`clear`、`layout`、`title` 和 `export`。支持的节点类型包括 `terminal`、`terminal-end`、`process`、`decision`、`service`、`database`、`success`、`error` 和 `container`。
+
+服务端导出可用 `/export?s=session-id&format=json`、`svg` 或 `drawio`。PNG 导出使用浏览器工具栏。如果本地服务无法启动，不要阻塞用户，改用 Mermaid、SVG 或 HTML technical diagrams。
+
+## 最小源清单
+
+渲染路径允许时，在 PNG 旁保存布局 manifest：
+
+```json
+{
+  "canvas": { "width": 1280, "height": 720 },
+  "boxes": [
+    { "id": "api", "x": 80, "y": 120, "width": 220, "height": 96, "label": "API Gateway" }
+  ],
+  "connectors": [
+    { "id": "api-db", "from": "api", "to": "db", "points": [[300, 168], [560, 168]] }
+  ]
+}
+```
+
+坐标是导出后的 PNG 像素坐标。boxes 应覆盖可见标签/节点边界，而不仅是中心点。
+
+## 图表修复手册
+
+- **节点重叠：** 增加 rank/列间距、拆分簇，或将低优先级注释移入图例。
+- **标签截断：** 加宽节点、添加手动换行、保留完整文字并调整源布局。
+- **连接线穿过标签：** 添加 waypoints、沿框体周围正交布线，或将标签移到线段上方。
+- **连接线堆叠：** 用不同 waypoints 分离平行边，或用带共享标签的 bus 汇总。
+- **边缘裁剪：** 增加外边距，或扩大导出 viewBox/canvas 尺寸。
+- **密集图不可读：** 拆成总览图加细节图，不要整体缩小。
+- **箭头含义不清：** 添加 `flow` 和简短标签，不要只依赖颜色。
+
+## 架构图
+
+用户需要浏览器可打开的单文件、显式系统拓扑、分组、信任边界、数据流和 PNG QA 时，优先使用 HTML `architecture` IR。需要官方厂商图形、diagrams.net 编辑或长期人工维护时，使用 draw.io。希望图主要留在 Markdown 或纯文本技术文档中时，使用 Mermaid/C4。
+
+Agent、memory、RAG、tool-call 或 multi-agent 图中，如果形状能帮助解释系统，优先使用语义 architecture 节点类型：`agent`、`model`、`memory`、`vectorstore`、`graphdb`、`tool`、`document`、`queue`、`browser`、`user`、`gateway`。使用 `flow` 值 `control`、`data`、`read`、`write`、`async`、`feedback` 区分读取路径、写入路径、事件和推理回路。先把结构画清楚，再添加 `visual.style`。
+
+UML 覆盖优先走确定性源：class、ER、state-machine、activity 和 sequence 需求可使用 Mermaid、PlantUML、HTML technical diagrams、SVG 或 draw.io。需要后续人工编辑或官方记法库时优先 draw.io；需要浏览器可打开交付和 PNG QA 时优先 HTML/SVG。
+
+## 流程工作流
+
+用户需要浏览器可打开的流程地图、审批流、自动化 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/cc-technical-diagrams/references/html-technical-diagrams.md

@@ -0,0 +1,243 @@
+# HTML 技术图
+
+当技术图需要单文件浏览器打开、便于分享、支持暗/亮主题，并且导出 PNG 后要做视觉 QA 时，使用这一路线。
+
+这一路线补充但不替代其他图表源：
+
+| 需求 | 优先选择 |
+| ---- | -------- |
+| 小型 Markdown 维护图 | Mermaid、Graphviz 或 SVG |
+| 后续人工编辑的图源 | `cc-drawio-studio` 和 `.drawio` |
+| 浏览器可打开的主题化技术图 | HTML 技术图路线 |
+| 位图优先的视觉概念、海报、产品图或图片编辑 | 图片生成或编辑路线 |
+
+## 支持的图表意图
+
+- `architecture`：系统拓扑、系统蓝图、部署拓扑、云区域、信任边界、客户端、网关、服务、数据存储、事件总线、认证流、Agent runtime 图、memory/recall 总览、before/after 架构对比和基础设施总览。
+- `workflow`：职责泳道、流程地图、审批门禁、自动化运行、异常路径、循环流程、runbook、CI/CD、事故响应、工具调用和请求生命周期。
+- `sequence`：参与者随时间交互、API 调用链、缓存回退、鉴权检查、异步链路和返回消息。
+- `dataflow`：来源、采集、处理、存储、消费者、PII 边界、治理、分析和血缘。
+- `lifecycle`：对象状态、终止状态、重试、等待、取消、超时、部署或订单状态流转。
+
+浏览器可交付的架构总览优先用 `architecture` 模式。需要 `.drawio` 源、官方厂商图标、diagrams.net 手工编辑或复杂自动布局时，改用 `cc-drawio-studio`。
+
+## 主题化语义图
+
+同一份 JSON 源需要更明确的交付语气时，可以使用 `visual.style`：`default`、`terminal`、`blueprint`、`minimal`、`glass`、`warm`、`openai` 或 `editorial-dark`。
+
+Agent、memory 和 AI 工作流图优先在 architecture 节点上使用语义 `type`：
+
+- 参与者和入口：`user`、`browser`、`gateway`。
+- 智能与编排：`agent`、`model`、`tool`。
+- 记忆与知识：`memory`、`vectorstore`、`graphdb`、`document`。
+- 运行时流动：`queue`、`messagebus`、`backend`、`external`。
+
+连线不仅表达方向，还需要表达含义时使用 `flow`：
+
+- `control`：编排、策略、触发或命令。
+- `data`：请求载荷、文档、embedding、事实或响应。
+- `read`：从 memory 或存储中读取。
+- `write`：持久化、索引、笔记或 memory 更新。
+- `async`：事件或队列工作。
+- `feedback`：循环、重试、细化或推理回路。
+
+出现两种以上 flow 时，渲染器会自动输出 flow legend。连线标签保持简短，密集分组、标题标签和节点内部区域用 `waypoints` 绕开。
+
+## 系统蓝图工作流
+
+生成展示级系统蓝图、部署拓扑、集成关系图、Agent runtime 视图、memory/recall 图或 before/after 架构对比时，使用 architecture 路线。先抽取紧凑的系统模型，再绘图：
+
+- 入口层：浏览器、移动端、CLI、webhook、调度器或 agent/session 入口。
+- 应用层：网关、前端应用、后端服务、worker、编排层、运行时宿主和工具适配器。
+- 数据层：数据库、对象存储、缓存、向量库、队列、事件总线、日志和分析存储。
+- 外部依赖：身份提供方、AI 模型、支付/邮件服务、SaaS API、云服务、设计工具或运行时连接器。
+- 身份与信任边界：认证、权限、PII 区域、租户边界、私有网络、密钥存储和策略检查。
+- 关键流：请求/控制流、数据流、事件流、部署流、recall/memory flow 或 before/after 迁移流。
+
+第一版蓝图保持可读：
+
+- 展示 4-10 个主节点，把低价值文件、类或端点折叠成分组节点。
+- 使用 1-3 个分组边界表达层级、信任区、运行环境或所有权域。
+- 标题和副标题要足够清楚，文件脱离原会话也能分享。
+- 用图例或最多 3 张摘要卡片说明 runtime、data、trust、risks、inputs 或 outcomes。
+- 优先使用语义配色，不做装饰性堆砌；当连线或标签变密时拆成多张图。
+
+面向 README 或干系人交付时，保留 JSON IR 和 HTML 作为可编辑事实源，再导出 SVG/PNG/JPG 产物：
+
+```bash
+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 导出需要本地浏览器。
+
+## JSON IR
+
+所有模式都需要：
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "SaaS Architecture",
+    "subtitle": "Browser-ready infrastructure overview"
+  }
+}
+```
+
+各模式最小字段：
+
+- `architecture`：`nodes`、`connections`；可选 `groups`、`legend`、`summary`。
+- `workflow`：`lanes`、`nodes`、`edges`；可选 `summary`。
+- `sequence`：`participants`、`messages`。
+- `dataflow`：`stages`、`nodes`、`flows`。
+- `lifecycle`：`lanes`、`states`、`transitions`。
+
+ID 必须以字母开头，只使用字母、数字、`_` 和 `-`。节点标签保持短小；较长说明放到图外文字或摘要卡片。
+
+## 流程工作流 IR
+
+`workflow` 模式适合有明确顺序的流程：它更关注职责、决策、分支和回环，而不是精确的基础设施拓扑。用 `lanes` 表示参与者或系统，用 `nodes` 表示步骤，用 `edges` 表示流转结果。节点仍使用显式 `col` 控制阅读顺序，不依赖隐藏的自动布局引擎。
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Procurement Approval",
+    "subtitle": "Request to payment"
+  },
+  "lanes": [
+    { "id": "requester", "label": "Requester" },
+    { "id": "system", "label": "System" },
+    { "id": "manager", "label": "Manager" }
+  ],
+  "nodes": [
+    { "id": "start", "lane": "requester", "col": 0, "type": "start", "label": "Submit Request", "actor": "Employee" },
+    { "id": "classify", "lane": "system", "col": 1, "type": "active", "label": "Classify Spend", "actor": "Policy Engine", "sublabel": "auto rules" },
+    { "id": "review", "lane": "manager", "col": 2, "type": "decision", "label": "Approved?", "step": "A" },
+    { "id": "pay", "lane": "system", "col": 3, "type": "success", "label": "Issue Payment" },
+    { "id": "reject", "lane": "requester", "col": 3, "type": "failure", "label": "Return Request" }
+  ],
+  "edges": [
+    { "from": "start", "to": "classify", "label": "intake", "variant": "emphasis" },
+    { "from": "classify", "to": "review", "label": "policy result" },
+    { "from": "review", "to": "pay", "label": "yes", "variant": "emphasis" },
+    { "from": "review", "to": "reject", "label": "no", "variant": "return", "waypoints": [[650, 396], [520, 396]] }
+  ],
+  "summary": [
+    { "title": "Inputs", "type": "active", "items": ["Purchase request", "Policy threshold"] },
+    { "title": "Outcomes", "type": "success", "items": ["Payment issued", "Requester notified"] }
+  ]
+}
+```
+
+Workflow 节点字段：
+
+- `type`：流程语义使用 `start`、`active`、`waiting`、`decision`、`success`、`failure` 或 `external`。
+- `actor`：可选，显示在节点上方的简短负责人或系统标签。
+- `step`：可选，显示的步骤标记。未提供时，workflow 节点会自动获得顺序编号。
+- `sublabel`、`width`、`height` 和 `yOffset`：可选，用于提升密集泳道中的可读性。
+
+Workflow 连线字段：
+
+- `variant`：主路径使用 `emphasis`，回环和返工使用 `return` 或 `dashed`，只有信任或策略检查才使用 `security`。
+- `waypoints`：可选 `[x, y]` 点，用于异常路径、跨行连接或需要避开标签和节点的回环。
+
+`summary` 用于简短记录前置条件、输入/输出或工具等流程元信息。长说明放在 SVG 外，避免节点标签不可读。
+
+## Architecture IR
+
+架构图使用显式坐标，因为系统图通常需要刻意安排位置、边界和信任区域：
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "SaaS Architecture",
+    "subtitle": "Browser-ready infrastructure overview"
+  },
+  "visual": {
+    "style": "blueprint"
+  },
+  "groups": [
+    { "id": "cloud", "label": "Cloud region", "type": "cloud", "x": 170, "y": 50, "width": 620, "height": 280 }
+  ],
+  "nodes": [
+    { "id": "web", "label": "Web App", "type": "frontend", "x": 48, "y": 160, "sublabel": "React" },
+    { "id": "api", "label": "API Gateway", "type": "cloud", "x": 230, "y": 160, "group": "cloud" },
+    { "id": "svc", "label": "App Service", "type": "backend", "x": 420, "y": 160, "group": "cloud" },
+    { "id": "db", "label": "PostgreSQL", "type": "database", "x": 620, "y": 160, "group": "cloud" }
+  ],
+  "connections": [
+    { "from": "web", "to": "api", "label": "HTTPS", "variant": "emphasis" },
+    { "from": "api", "to": "svc", "label": "REST" },
+    { "from": "svc", "to": "db", "label": "SQL" }
+  ],
+  "summary": [
+    { "title": "Runtime", "type": "backend", "items": ["API and worker services", "Managed relational data"] }
+  ]
+}
+```
+
+节点和分组类型支持 `frontend`、`backend`、`database`、`cloud`、`security`、`messagebus`、`external`、`agent`、`model`、`memory`、`vectorstore`、`graphdb`、`tool`、`document`、`queue`、`browser`、`user` 和 `gateway`。连接支持 `default`、`emphasis`、`security`、`dashed` 和 `return`；architecture 连接还可以添加 `flow`。当连线需要绕开边界或标签时，添加 `waypoints`，格式为 `[[x, y], ...]`。
+
+架构图默认根据节点类型生成图例；设置 `legend: false` 可关闭。自定义图例使用 `{ "label": "...", "type": "..." }`。`summary` 最多渲染 3 张图下摘要卡片，不进入 layout manifest，PNG QA 聚焦主图。
+
+## 架构图布局规则
+
+- 分组用于表达云区域、集群、信任边界或安全域，不作为装饰面板。
+- 图例放在所有边界之外或下方；空间不足时增大坐标和画布，不压缩文字。
+- 事件总线用 `messagebus` 节点，放在服务之间的空隙。
+- 鉴权、令牌、策略或信任边界流使用 `security` 连接。
+- 网关扇出到多个服务时，优先用 `waypoints` 控制路径，避免密集交叉线。
+- 如果总览图需要多个密集簇，或必须缩小文字才放得下，应拆成总览图加细节图。
+
+## 渲染命令
+
+```bash
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs \
+  --input diagram.json \
+  --output diagram.html \
+  --type architecture \
+  --manifest diagram.layout.json
+```
+
+生成的 HTML 是自包含文件，包含：
+
+- Inline SVG。
+- CSS 变量暗/亮主题。
+- 浏览器内主题切换、SVG 下载、打印/PDF 控制。
+- 可选 layout manifest，用于 PNG QA。
+
+## QA 和修复
+
+导出 PNG 后运行：
+
+```bash
+node skills/cc-technical-diagrams/scripts/png-qa.mjs \
+  --png diagram.png \
+  --manifest diagram.layout.json \
+  --format markdown
+```
+
+修复应回到 JSON 源或渲染尺寸：
+
+- 重叠：拆分密集分组，或增加节点/分组间距。
+- 标签截断：对完整标签换行、保留文字或加宽节点。
+- 连线穿过标签：减少边标签，添加 `waypoints`，或移动节点。
+- 流向过密：拆成总览图和细节图。
+- 边缘裁剪：增加输出空间或简化路径。
+
+## 交付说明
+
+交付 `.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 必须视觉审阅；记录工具可用性、版本、主题、比例、修复轮次和残留问题，未解决时标记部分验收。

package/localized/zh-CN/skills/cc-technical-diagrams/scripts/diagram-browser.mjs

@@ -0,0 +1,153 @@
+// @ts-check
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+export function findBrowser() {
+  const candidates = [process.env.FEC_BROWSER_PATH,
+    "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe",
+    "C:/Program Files/Microsoft/Edge/Application/msedge.exe",
+    "C:/Program Files/Google/Chrome/Application/chrome.exe",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+    "google-chrome", "chromium", "chromium-browser", "msedge", "brave-browser", "vivaldi"];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    if (path.isAbsolute(candidate) ? fs.existsSync(candidate) : spawnSync(candidate, ["--version"], { timeout: 5000, windowsHide: true, stdio: "ignore" }).status === 0) return candidate;
+  }
+  return null;
+}
+
+/** @typedef {{evaluate:(expression:string)=>Promise<unknown>,screenshot:(width:number,height:number,scale?:number)=>Promise<Buffer>}} DiagramSession */
+
+/**
+ * Export failures must stay within the wording callers match on, so CDP details are wrapped here.
+ * @param {string} detail @returns {Error}
+ */
+const exportFailure = (detail) => new Error(`Browser raster export failed: ${detail}`);
+
+/** @param {()=>string} read @param {number} deadline @returns {Promise<number>} */
+export async function waitForDebuggingPort(read, deadline) {
+  while (Date.now() < deadline) {
+    try {
+      const value = read().split("\n")[0].trim();
+      const port = Number(value);
+      if (/^\d+$/.test(value) && Number.isInteger(port) && port > 0 && port <= 65535) return port;
+    } catch (error) {
+      const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+      if (!["EBUSY", "ENOENT", "EPERM"].includes(code)) throw exportFailure(error instanceof Error ? error.message : String(error));
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(50, Math.max(0, deadline - Date.now()))));
+  }
+  throw exportFailure("browser debugging port did not become readable before the initialization deadline.");
+}
+
+/**
+ * The target URL can be advertised before its execution context has finished navigating.
+ * Retry only that initialization window; action failures must propagate without replaying exports.
+ * @param {DiagramSession['evaluate']} evaluate @param {string} url @param {number} deadline
+ */
+export async function waitForDiagramReady(evaluate, url, deadline) {
+  while (Date.now() < deadline) {
+    try {
+      const ready = await evaluate(`(async()=>{if(location.href!==${JSON.stringify(url)})return false;if(document.readyState!=="complete")await new Promise(r=>window.addEventListener("load",r,{once:true}));await document.fonts.ready;await new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r)));return true;})()`);
+      if (ready === true) return;
+    } catch (error) {
+      if (!(error instanceof Error) || !/^Browser raster export failed: (?:Execution context was destroyed|Cannot find default execution context)\.?$/.test(error.message)) throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(50, Math.max(0, deadline - Date.now()))));
+  }
+  throw exportFailure("diagram page did not become ready before the initialization deadline.");
+}
+
+/**
+ * Chromium keeps profile files locked until its whole process tree is gone, so cleanup waits for
+ * the process instead of sleeping a fixed amount. @param {ReturnType<typeof spawn>} child @param {number} ms @returns {Promise<void>}
+ */
+const waitForExit = async (child, ms) => {
+  if (child.exitCode !== null) return;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  await new Promise((resolve) => {
+    const finish = () => { if (timer) clearTimeout(timer); child.off("exit", finish); resolve(undefined); };
+    timer = setTimeout(finish, ms);
+    child.once("exit", finish);
+  });
+};
+
+/** @template T @param {string} html @param {{theme:'light'|'dark',timeoutMs:number}} options @param {(session:DiagramSession)=>Promise<T>} action @returns {Promise<T>} */
+export async function withDiagramPage(html, options, action) {
+  const browser = findBrowser();
+  if (!browser) throw new Error("PNG/JPG export requires a local Chromium browser. Export SVG instead, or install a Chromium browser and rerun this command.");
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fec-diagram-browser-"));
+  const page = path.join(dir, "diagram.html"), profile = path.join(dir, "profile");
+  fs.writeFileSync(page, html);
+  const child = spawn(browser, ["--headless=new", "--disable-gpu", "--no-first-run", "--no-default-browser-check", "--hide-scrollbars", "--remote-debugging-port=0", "--remote-allow-origins=http://localhost", `--user-data-dir=${profile}`, pathToFileURL(page).href], { windowsHide: true, stdio: "ignore" });
+  let childError = "";
+  child.on("error", (error) => { childError = error.message; });
+  /** @type {WebSocket | undefined} */
+  let socket;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  try {
+    const work = async () => {
+    const deadline = Date.now() + Math.min(15000, options.timeoutMs);
+    const portFile = path.join(profile, "DevToolsActivePort");
+    while (!fs.existsSync(portFile) && Date.now() < deadline && (child.exitCode === null || child.exitCode === 0) && !childError) await new Promise((resolve) => setTimeout(resolve, 50));
+    if (!fs.existsSync(portFile)) throw exportFailure(`browser did not start a debugging session${childError ? ` (${childError})` : ""}.`);
+    const port = await waitForDebuggingPort(() => fs.readFileSync(portFile, "utf8"), deadline);
+    // Select the intended target first; the readiness handshake below also waits for its context.
+    /** @type {{webSocketDebuggerUrl?:string}|undefined} */
+    let target;
+    while (Date.now() < deadline) {
+      const pages = await (await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(Math.min(5000, options.timeoutMs)) })).json();
+      target = pages.find(/** @param {{type:string,url:string}} p */ (p) => p.type === "page" && p.url === pathToFileURL(page).href);
+      if (target) break;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    if (!target?.webSocketDebuggerUrl) throw exportFailure("browser did not create a diagram page.");
+    socket = new WebSocket(target.webSocketDebuggerUrl);
+    await new Promise((resolve, reject) => { socket?.addEventListener("open", resolve, { once: true }); socket?.addEventListener("error", reject, { once: true }); });
+    /** @type {Map<number,{resolve:(value:Record<string,unknown>)=>void,reject:(reason:Error)=>void}>} */
+    const pending = new Map();
+    socket.addEventListener("close", () => { for (const entry of pending.values()) entry.reject(exportFailure("session closed before export completed.")); pending.clear(); });
+    let serial = 0;
+    socket.addEventListener("message", (event) => {
+      const message = JSON.parse(String(event.data));
+      const entry = pending.get(message.id);
+      if (!entry) return;
+      pending.delete(message.id);
+      if (message.error) entry.reject(exportFailure(message.error.message)); else entry.resolve(message.result ?? {});
+    });
+    /** @param {string} method @param {Record<string,unknown>} [params] @returns {Promise<Record<string,unknown>>} */
+    const call = (method, params = {}) => new Promise((resolve, reject) => { const id = ++serial; pending.set(id, { resolve, reject }); socket?.send(JSON.stringify({ id, method, params })); });
+    /** @param {string} expression */
+    const evaluate = async (expression) => {
+      const result = await call("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true });
+      if (result.exceptionDetails) throw new Error(`Diagram evaluation failed: ${JSON.stringify(result.exceptionDetails)}`);
+      return /** @type {{value?:unknown}} */ (result.result).value;
+    };
+    /** @type {DiagramSession} */
+    const session = { evaluate, screenshot: async (width, height, scale = 1) => {
+      await call("Emulation.setDeviceMetricsOverride", { width: Math.ceil(width), height: Math.ceil(height), deviceScaleFactor: scale, mobile: false });
+      const result = await call("Page.captureScreenshot", { format: "png", captureBeyondViewport: true, clip: { x: 0, y: 0, width, height, scale: 1 } });
+      return Buffer.from(String(result.data), "base64");
+    } };
+    await waitForDiagramReady(evaluate, pathToFileURL(page).href, deadline);
+    return await action(session);
+    };
+    return await Promise.race([work(), new Promise(/** @param {(reason:Error)=>void} reject */ (_, reject) => { timer = setTimeout(() => reject(exportFailure("export timed out.")), options.timeoutMs); })]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ id: 999999, method: "Browser.close" }));
+    // Browser.close is graceful, so wait for the process rather than guessing with a fixed sleep:
+    // Chromium's child processes keep profile files locked until the tree is gone.
+    await waitForExit(child, 2000);
+    socket?.close();
+    if (child.exitCode === null) child.kill();
+    // The Chromium profile is owned by this invocation only. Windows may release locks after exit.
+    try { fs.rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 }); } catch { /* A locked temporary profile can be removed by OS cleanup. */ }
+  }
+}