【开源评测】stack-diagram:架构图从一句话开始,但交付、分享和保密不能省略

取证快照:2026-11-05|新建仓库Stars排序冻结快照第13位|非GitHub Weekly Trending
仓库地址:https://github.com/caru-ini/stack-diagram
固定Commit:1ed53e3e9525364ae5d82e0430f2bb3f7ef4c838
许可证:MIT|累计Stars:1818(API快照采集值)
评测等级:L3 有界静态取证通过(含对象库例外)
评测体系:Valhalla SafeNet Accelerator × Matrix Alchemy Lab
作者:Valhalla Matrix治理实验室
⚠️ 评测声明:本文为固定提交、最多30文件只读静态证据评测,未调用Agent生成架构图、部署站点、访问公共画廊、执行权限测试。L3仅代表取证过程可复核,不等于站点安全、绘图结果准确性、权限体系完备性认证;文件词法核验≠代码覆盖率、安全审计结论。存在1个未选中blob对象库例外,本评测不覆盖全仓库所有文件。

🔍 摘要

架构师、后端工程师画系统架构图,大量时间往往消耗在挑选图标、调整布局、导出文件、整理样式上,而不是梳理系统数据流、信任边界。
stack-diagram 是面向Agent的架构图生成工具:输入一句自然语言描述,自动生成带厂商品牌图标、样式规整的架构示意图,配套公共画廊站点用于分享。
它的亮点不在于“AI画图”本身,而是在设计上区分了本地生成产物和公开画廊上传两个动作,内置错误脱敏、资源自包含、归属权限校验逻辑。
核心提醒:排版整洁 ≠ 架构真实。AI生成的图很容易省略认证链路、缓存、异常分支、跨域信任边界,生成图仅作为沟通草图,不能直接等同于生产部署文档。


一、它解决了什么核心痛点

日常架构绘图有两类典型痛点:

  1. 绘图成本高:手动拖拽组件、对齐连线、统一明暗主题、导出多格式,挤占架构设计思考时间;
  2. 分享边界模糊:草图、内部架构图随手上传到公共分享平台,不经意泄露业务链路、供应商信息、内部服务拓扑;
  3. 产物携带麻烦:图片版本零散、字体缺失、图标丢失,发给同事经常出现样式错乱。

stack-diagram 给出一套轻量化方案:自然语言驱动生成架构草图,输出自包含HTML,同时配套画廊分享机制,并在代码层面对“生成”和“公开发布”做权限隔离。

边界重点:它是沟通草图工具,不是架构评审、合规归档的正式建模工具。绘图的正确性、数据流、信任边界,仍然需要架构负责人人工逐条核验。


二、技术架构深度拆解

2.1 自包含单文件HTML:解决产物携带,不解决内容正确性

项目支持将字体、品牌Logo资源内联进HTML文件,同时内置深色/浅色两套主题,导出格式支持PNG、React组件等。
✅ 优势:单文件HTML可以放进知识库、离线文档、会议演示,脱离原图生成环境也能正常打开渲染;
⚠️ 局限:生成过程中依然存在联网拉取素材的行为;资源打包不代表图里的数据流、访问关系是准确的。
本次取证仅核验文档契约,未完整覆盖Agent生成链路,无法验证全部导出分支的实际行为。

源码参考:README.md 产物导出规范

2.2 生成与公开画廊上传,拆成两个独立权限动作

这是本项目最有工程参考价值的设计点:
生成架构图只是本地动作;上传到公共画廊是独立的发布动作,上传前会弹窗预览全部公开内容,要求用户二次确认。
哪怕原始提示词不上传,图中包含的服务名称、技术栈、第三方组件、业务拓扑,依然属于敏感信息。
底层逻辑:允许生成 ≠ 允许对外公开,两个动作必须分开审批,不能默认放行。
很多团队的安全漏洞,就是把“生成草图”和“公开分享”混为一谈。

源码参考:README.md 画廊上传确认流程

2.3 分层错误脱敏:前端泛化提示,后端隔离诊断信息

站点中间件 start.ts 做了异常隔离设计:

  • 路由、有状态预期错误:单独识别处理;
  • 数据库等底层异常:原始报错(可能包含SQL语句、参数)仅保留在后端控制台日志;
  • 向前端浏览器返回通用友好提示,不向下游暴露原始异常cause。

✅ 价值:避免数据库报错、底层堆栈信息直接外泄给访问者;
⚠️ 局限:这只是局部代码实现观察,不等于全链路日志脱敏、日志访问权限管控已经完成审计,其他异常路径仍然存在泄露风险。

源码参考:site/src/start.ts 异常处理逻辑

2.4 归属权校验:明确帖子所有者判定规则,但非完整授权闭环

仓库自带归属权单元测试 ownership.test.ts,覆盖三类场景:同一GitHub账号、不同账号、匿名访客,用来判断谁有权修改、删除画廊内的图。
✅ 价值:可以清晰看到设计者对资源归属的定义,防止匿名用户随意篡改他人分享内容;
⚠️ 局限:本次没有执行测试,仅看测试用例规格;局部用例通过,不代表所有修改/删除接口都严格执行归属校验,不能认定权限体系完整可靠。

源码参考:site/src/features/account/server/ownership.test.ts


三、L3取证边界与可复现说明

取证项快照信息
来源排序近7天新建仓库Stars冻结快照第13位(非周Trending)
固定版本1ed53e3e9525364ae5d82e0430f2bb3f7ef4c838
文件树总量242个文件条目
核验范围有界选取30个文件100%核验,存在1个未选中blob对象库例外,非全仓扫描
克隆方式浅克隆 shallow=true,仅HEAD单提交
数据通道GH Proxy Primary,SafeNet可信源校验
校验摘要Manifest SHA-256:65695a79ef846747c5d0673420f29e888255ef8e68d5c93bf845840386c32638
例外Blobd67a1a7f4e7b32db92c9bd465908f2388d15b182
未执行项未调用Agent绘图、启动站点、验证导出流程、执行权限测试

取证核心原则:L3仅证明选中文件文本与固定Commit可追溯复核;对象库例外不破坏已核验部分的证据链,但不能宣称全仓库检查完毕。不推导站点安全、绘图准确度结论。


四、风险清单 & 合规红线(企业落地必看)

  1. 拓扑信息本身就是敏感资产
    即使架构图不包含账号密码、密钥,内部服务名、供应商依赖、跨区域数据流、信任边界,都属于业务敏感信息,上传画廊前必须做脱敏审查,图片和元数据同步检查。
  2. AI生成天然存在信息省略
    大模型生成架构图习惯简化链路,容易丢失认证鉴权、消息队列、熔断降级、缓存失效、灾备等关键分支,草图不能直接作为上线、等保、审计用架构图。
  3. 前端脱敏 ≠ 后端日志安全
    页面看不到原始报错,不代表后端日志自动脱敏。私有化部署时,必须单独管控日志内容、日志存储周期、日志访问权限。
  4. MIT协议不覆盖第三方素材
    代码本体为MIT许可,但内置的云厂商Logo、图标、字体有独立版权;对内演示尚可,对外宣传、商业材料中使用,需要单独核对品牌素材使用规范。

五、落地实施建议(PoC验证路线)

适合想引入这个工具的团队,推荐低风险落地流程:

  1. 先用公开业务示例验证
    优先拿已经对外公开的参考系统生成草图,由架构负责人逐条核对节点、连线方向、协议、跨信任域关系,建立校验标准;
  2. 多格式离线产物验收
    分别测试自包含HTML、PNG导出;验证弱网、无网络环境、明暗主题切换下的可读性,排查图标、字体丢失问题;
  3. 严格隔离画廊上传权限
    默认禁止内部架构图上传公共画廊,把上传作为独立审批节点,图片、标题、备注元数据同步脱敏;
  4. 规范交付物定位
    统一团队约定:stack-diagram产出 = 讨论草图,正式架构文档、评审归档图,必须经过人工修订、版本管理、审批留痕。

六、评测结论

stack-diagram 的核心价值,不在于一句话生成好看的架构图,而在于它把“生成草图”和“公开分享”拆成两套独立动作,给AI绘图工具补上了分享边界意识。
适用场景:技术沟通草图、方案快速脑暴、对外公开技术方案示意图、团队快速对齐技术栈;
不适合:生产环境正式架构归档、等保合规材料、高敏感内部拓扑文档、作为唯一架构依据交付。

如果你团队正在使用LLM生成架构示意图,它的权限隔离、错误脱敏设计思路非常值得借鉴;但受本次L3静态取证边界限制,无法确认站点完整权限、全链路安全和导出稳定性,上线前务必补充专项验证。


📌 发布溯源说明

所有证据锁定上述固定commit;Stars数值、排名为快照采集时点数据,会动态变化。
本文独立分析,没有搬运上游图片、大图与长段原文;沿用已有SafeNet账本,不新增媒体、依赖下载。
SafeNet账本链头:3fa55800a09530686f00c8ae3780dc816fa57e4daeb0ae9575b894af43628619

系列专栏:开源项目L3静态取证评测|Valhalla-Matrix实验室


Logo

更多推荐