一个 Skill，把架构设计变成可分享的技术图

一个 Skill把架构设计变成可分享的技术图技术方案讨论完成以后我们经常会对 AI 说“帮我画一张架构图。”图很快就能生成但只要认真检查就可能发现服务名称被改写同步调用和异步消息没有区分等待、重试、回滚路径消失系统边界只剩几个并排的卡片桌面端能看手机端却缩成一团图已经生成却无法验证是否保留了关键事实。技术可视化真正困难的不是把图画出来而是让图准确承载已经确认的技术设计。technical-visual-companion就是为这个问题设计的 Agent Skill。它可以把确认过的架构、流程、状态和部署信息整理成一份美观、离线、响应式并经过验证的单文件 HTML 技术视觉说明。截图位置 1最终生成的离线 HTML 全貌时序图它能做什么1. 只使用已经确认的技术事实Skill 只使用当前对话中已经确认的信息或者用户明确指定的本地文件。如果方案仍有分歧、文档互相冲突或者缺少关键边界、顺序和恢复路径它会停止生成先请用户确认而不是擅自补全。这样可以避免技术图最危险的情况图画得很像真的却混入了未经确认的推断。2. 先建立视觉事实模型生成前Skill 会整理参与者和系统边界职责与所有权连接方向和交互类型执行顺序和关键门禁等待、重试、失败和恢复路径明确排除的内容必须原样保留的名称、版本、端口和数量。事实模型负责保证内容准确图形只负责把关系表达清楚。3. 自动选择合适的图它不会默认套用一张万能架构图而是根据问题选择一至三种互补图形需要表达的内容优先选择的图形系统边界和职责归属系统边界图或职责图调用顺序和同步、异步交互时序图或泳道图状态、等待、重试和恢复状态机节点、网络、容器和端口部署拓扑图数据来源、处理和去向数据流图版本、能力和方案差异对比矩阵分阶段发布、迁移和回滚阶段流程图或时间线如果一种图已经能够回答全部问题就只生成一种避免用重复图形堆满页面。4. 生成一个离线 HTML最终交付物只有一个 HTML 文件无需联网即可打开不依赖 CDN 和外部字体不包含 JavaScript 和iframe使用语义化 HTML 和内联 SVG文字可以搜索关键术语可以校验可以直接发送、评审和归档可以从浏览器中截取图片用于文档或汇报。用户没有指定输出位置时默认写入docs/visuals/topic-slug.html5. 自动进行结构校验Skill 自带验证脚本可以检查 HTML 结构、离线约束、响应式规则、文件大小和关键术语。python scripts/validate_html.py--htmlC:/path/to/visual.html --required-termOrder Service--required-termPayment Service--required-termrollback验证结果会返回overall、errors和metrics。只有overall为passed结构校验才算通过。6. 同时检查桌面端和移动端结构校验通过以后还要在浏览器中检查真实页面桌面端检查层级、箭头、边界、标签、间距和整页阅读顺序390px 移动端检查文字、方向、状态和纵向语义布局页面不能重叠、裁切或依赖横向滚动。移动端不是把桌面画布整体缩小而是重新组织关系同时保留相同的技术事实。如果当前环境没有浏览器可以保留候选 HTML但必须报告visual verification pending截图位置 3同一个 HTML 390px 移动端完整工作流一次完整执行包括检查输入是否已经确认整理视觉事实模型选择一至三种互补图形生成一个离线 HTML运行确定性结构校验完成桌面端视觉检查完成 390px 移动端检查所有条件通过后再宣布完成。文件生成成功不等于视觉交付已经完成。只有事实、结构、桌面布局和移动端布局都通过检查任务才真正结束。如何使用一个有效的请求需要说清楚四件事视觉要回答什么问题可以使用哪些已确认来源哪些术语必须原样保留输出文件放在哪里。例如请使用 technical-visual-companion 根据已经确认的 docs/order-retry-design.md 生成订单失败恢复流程的离线 HTML 技术视觉说明。 只使用这一个文件不要扫描仓库补充信息。 必须原样保留 - Order Service - Payment Service - retry_count 3 - manual approval - rollback 输出到 docs/visuals/order-retry.html。用户不需要指定卡片坐标和颜色。事实来源、关键术语和输出边界由用户控制图形选择与页面组织交给 Skill。项目地址与安装technical-visual-companion已收录在Visual Agent Copilot中。Visual Agent Copilot 是 Role Copilot Skills 中面向视觉沟通的角色集合专门把复杂内容转化为易理解、可交付的视觉表达。GitHub 项目地址https://github.com/huajiexiewenfeng/role-copilot-skills/tree/main/visual-agent-copilot使用 Skills CLI 一键安装npx skillsaddhuajiexiewenfeng/role-copilot-skills/visual-agent-copilot/technical-visual-companion安装完成后就可以在支持 Agent Skills 的工具中调用technical-visual-companion。如果这个 Skill 对你有帮助也欢迎访问仓库查看源码、使用说明和后续更新。适合哪些场景它适合已经完成设计讨论、准备进入评审或交付阶段的任务系统架构和服务边界服务调用顺序与消息流程状态流转、重试、失败和恢复节点、容器、网络与端口数据采集、处理、存储和消费链路版本、能力或方案对比分阶段迁移、发布与回滚需要离线发送或归档的技术材料。它不适合设计尚未确认却希望 Skill 自动补齐架构产品 UI、运营页面或交互原型只需要 Mermaid、PPT、PDF 或 PNG需要实时数据和在线交互的页面未经允许扫描整个仓库或覆盖现有文件。如果问题还是“系统应该怎么设计”应该先完成设计讨论。如果问题已经变成“如何准确展示确认过的设计”才轮到这个 Skill 出场。分享和运行要求分享时需要保留完整目录不能只复制SKILL.mdtechnical-visual-companion/ ├── SKILL.md ├── references/ │ ├── diagram-selection.md │ ├── visual-language.md │ └── html-contract.md └── scripts/ └── validate_html.py运行环境需要目标目录写入权限Python 3.11 或更高版本可以检查桌面端和 390px 视口的浏览器。把完整目录安装到支持 Agent Skills 的工具中就可以使用。总结technical-visual-companion做的事情很明确把已经确认的技术设计转换成一份准确、美观、离线、响应式并经过验证的 HTML 技术视觉说明。它让技术图不再只是一次临时生成而是成为可以评审、分享和归档的正式交付物。先守住事实再组织关系先通过验证再谈完成。