CocoSketch 是 CocoPlus 中的可视化产物生成流水线，目标是把 CocoPlus 的各类产物转换为 draw.io 图表。其核心原则是：图表质量需要一条流水线，而不是单次提示。AI 负责生成 XML，确定性脚本负责校验与修复，且不允许跳过校验或修复步骤。
七步流水线（所有模式通用）
第一步：解析样式预设。优先检查 ~/.cocoplus/sketch-styles/，其次检查 .cortex/sketch/styles/built-in/。内置样式包括 default、corporate、handdrawn，默认使用 default.json，并应用到所有生成的单元格。
第二步：检查 draw.io CLI 可用性。依次尝试 drawio --version、draw.io --version 以及操作系统特定路径。二进制名称只解析一次，存为 DRAWIO_BIN，并在第五步和第七步中原样使用。若 draw.io 不可用，则进入回退链：先生成 Mermaid 标记并写入 <name>.mmd 并告知开发者；若 Mermaid 不适用，则交付原始 .drawio XML 并附上浏览器打开说明。
第三步：规划布局。序列或流水线使用 LR 方向，层级或模式使用 TB 方向。节点超过 15 个时，运行 invoke cocosketch/sketch-autolayout <input.json> <layout.json>；不超过 15 个时手工放置坐标，建议尺寸 120px 宽 × 60px 高，水平间距 50px，垂直间距 40px。分组使用 swimlane 单元格对相关节点进行视觉聚类。
第四步：生成 XML 并校验。XML 需包含 mxGraphModel、root、id 为 0 和 1 的 mxCell，以及 parent="1" 且 id 唯一的形状单元格。运行 invoke cocosketch/sketch-validate <file.drawio>，若失败则立即停止，报告结构错误，不得进入第五步。
第五步：导出预览 PNG（不带 -e）。命令为 $DRAWIO_BIN -x -f png --width 2000 -o <name>-preview.png <file.drawio>。预览供智能体视觉 API 使用，嵌入 XML 会产生被截断的 IEND，导致视觉 API 拒绝该 PNG。
第六步：自检。使用视觉能力读取预览 PNG，识别节点重叠、标签被裁剪、缺失的边连接，并在 .drawio XML 源中自动修复，最多两轮。第二轮后继续，并在输出中注明遗留问题。
第七步：最终导出与修复。命令为 $DRAWIO_BIN -x -f png -e --width 2000 -o <name>.png <file.drawio>，随后运行 invoke cocosketch/sketch-repair <name>.png。-e 会把图表 XML 嵌入 PNG，开发者可直接在 draw.io 中打开；sketch-repair 用于恢复 -e 可能产生的截断 IEND 块。输出 <name>.png 和 <name>.drawio 到 .cocoplus/diagrams/。命令输出中需记录最终 PNG 的确切路径；若使用 Mermaid 回退，则输出 .mmd 路径并明确说明 PNG 导出不可用。
模式说明
$sketch schema [--tables <list>]：查询 Snowflake，执行 SHOW TABLES（完整模式）或限定到 --tables 列表，对每张表执行 SHOW COLUMNS IN TABLE <name>，构建表关系图：外键引用为有向边，共享键列名为无向虚线边，视图依赖为有向点线边，并对关系图应用传递归约，最后执行七步流水线，输出 .cocoplus/diagrams/schema-[timestamp].png。
$sketch flow [file]：读取 flow.json（默认 .cocoplus/flow.json，若提供 [file] 则使用之），把每个阶段映射为节点（标签为阶段名，副标题为 persona 与 model），阶段依赖映射为有向边，HITL 门在连接边标签上用 ⊛ 标记，MANDATORY 检查点在节点上用双边框标记，执行七步流水线，输出 .cocoplus/diagrams/flow-[timestamp].png。
$sketch deps [--reduce]：读取 .cocoplus/map/coco-map.json 的结构依赖视图，从函数依赖构建节点与边图。默认（--reduce 开启）在布局前运行 invoke cocomap/map-reduce <input.json> <reduced.json>；--reduce off 时使用完整传递闭包。执行七步流水线，并计算和报告依赖指标：节点数、归约前边数、归约后边数、归约百分比。输出 .cocoplus/diagrams/deps-[timestamp].png。
$sketch diff <from> <to>：比较两个模式或依赖快照、git 引用或图表元数据文件，输出新增对象、移除对象、修改的关系，以及元数据存在时的策略或角色变更。写入 .cocoplus/diagrams/diff-[from]-[to]-[timestamp].md，并在 draw.io 可用时用标准七步流水线生成 PNG。若任一侧无法解析，则以清晰的缺失引用消息停止。
$sketch view [diagram-path]：为 CocoSketch 图表生成自包含 HTML 查看器，支持平移、缩放、过滤和对象元数据。已提交的 .drawio/PNG 仍是源产物，查看器只是便利导出，写入 .cocoplus/diagrams/viewer-[timestamp].html。
若需把生成的图表说明打包为 Markdown/HTML/PDF，可使用：invoke reporting/report-export --source <diagram-report.md> --format <markdown|html|pdf> --out-dir .cocoplus/diagrams/exports。
退出标准
每次调用都必须在第五步前运行 cocosketch/sketch-validate，失败即停止流水线；每次调用都必须在第七步后运行 cocosketch/sketch-repair；预览 PNG（第五步）不带 -e；最终 PNG（第七步）带 -e；$sketch deps 默认应用传递归约，--reduce off 跳过；$sketch deps 报告节点数、原始边数、归约后边数和归约百分比；命令输出包含最终 PNG 路径或回退 .mmd 路径；~/.cocoplus/sketch-styles/ 中的用户样式优先于内置样式；节点超过 15 个时在第三步调用 cocosketch/sketch-autolayout；draw.io CLI 不可用时执行回退链（Mermaid → 原始 XML）；$sketch diff 在可用时报告新增、移除、修改的关系以及策略/角色变更；$sketch view 写入自包含 HTML 查看器且不替换已提交的图表产物。
反合理化
文档列出了若干常见错误做法及其原因：跳过 cocosketch/sketch-validate 会因无效 XML 产生空白或损坏图表且无报错；预览 PNG 使用 -e 会截断 IEND 导致视觉 API 拒绝；跳过 cocosketch/sketch-repair 会因截断 IEND 在多种常见查看器中损坏 PNG；不经过流水线而用单次 LLM 生成会产生糟糕布局和结构错误；不检查就复用 draw.io 二进制名称不可靠，因为名称随操作系统和安装方式变化，应只解析一次；只说“图表已生成”而不给路径会让用户无法检查或附加图表。