btp-diagram-generator

BTP 解决方案图生成器

在工作区中生成一个符合 SAP BTP 解决方案图指南的 .drawio 文件，并通过已配置的 draw.io MCP 服务打开它。

其验证和交付规范借鉴了 Archify：确定性产物、机器可读的修复回执、明确的质量门槛、保留上一个可用版本，以及区分自动化审查与感知审查的结论。

⚡ 快速入门（先用此方式）

对于绝大多数图表，不要手写 XML。请使用 btp_builder Python 包——它负责图标查找、SAP 调色板、端口固定、标签 HTML、A4 尺寸、SVG 放大和验证。典型的 L1 图表约需 20 行代码。

# scripts/examples/task_center_arch.py — runnable end-to-end
import sys
from pathlib import Path
# Add the skill's scripts/ dir to sys.path so `btp_builder` imports work
# regardless of where the skill is installed
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

from btp_builder import BtpDiagram

d = BtpDiagram(level="L1", title="Task Center Reference Architecture")

btp = d.btp_container(x=260, y=80, w=560, h=440)
sub = d.subaccount(parent=btp, label="Subaccount",
                   x=btp.x + 24, y=btp.y + 110, w=520, h=170)

wz = d.service("work zone",   in_=sub, x=sub.x + 60, y=sub.y + 60)
tc = d.service("task center", right_of=wz)
ci = d.service("cloud identity", below=tc)

eu = d.user("End User", x=60, y=btp.y + 100)
ac = d.app_client("Application Clients\n(Mobile or Desktop)", below=eu)

s4    = d.external("SAP S/4HANA\nOn-Premise Solutions",
                   x=btp.right_edge() + 40, y=btp.y + 70, kind="sap")
third = d.external("3rd Party\nApplications", below=s4, kind="non-sap")
cloud = d.external("SAP Cloud\nApplications", below=third, kind="sap")
idp   = d.idp("3rd-party Identity Provider",
              x=ci.center_x() - 140, y=btp.bottom_edge() + 60)

d.connect(eu, ac, direction="down")
d.connect(ac, wz, direction="right")
d.connect(wz, tc, kind="dblhd")
d.connect(tc, ci, kind="dblhd", direction="down")
d.connect(tc, s4); d.connect(tc, third); d.connect(tc, cloud)
d.connect(idp, ci, kind="dashed", direction="up")

d.save("btp-task-center-architecture.drawio")  # validates, then atomically commits

请在仓库根目录通过 uv run python <script>.py 运行。save() 会先进行验证；如果发现问题，则会通过 ValueError 抛出完整的错误列表；警告则会打印出来。 构建器的输出具有确定性：相同的图表内容会生成完全相同的 XML 字节和稳定的图表 ID。save() 会在同一目录中写入候选文件，并仅在验证通过后以原子方式替换目标文件，因此提交失败时会保留之前的产物。

Quick-Path API 表面

调用	返回值	说明
BtpDiagram(level, title)	builder	level ∈ L0/L1/L2。控制图标大小和标签字重。
.btp_container(x,y,w,h, sub_label, env_label, with_logo)	NodeRef	浅蓝色外框 + SAP 角标 + Subaccount/Multi-Cloud 标签。
.subaccount(parent, label, ...)	NodeRef	BTP 容器内的白色卡片。
.inner_card(parent, label, ...)	NodeRef	通用白色子卡片（例如 CIS 服务组）。
.service(name, in_=, right_of=, left_of=, below=, above=)	NodeRef	name 会通过 references/icon-aliases.json 进行模糊匹配（例如 "task center"、"cpi"、"hana cloud"）。
.user(label, kind="sap")	NodeRef	kind ∈ sap / non-sap / highlight。
.app_client(label, ...)	NodeRef	通用移动端/桌面端图块。
.external(label, kind="sap"/"non-sap", ...)	NodeRef	右侧外部系统图块。
.idp(label, ...)	NodeRef	第三方身份提供商图块。
.connect(src, tgt, kind, direction)	edge id	kind ∈ std/dblhd/dashed/optional/auth/scim/trust/neutral。direction 会自动固定端口，也可用 "right"/"left"/"up"/"down" 覆盖。
.save(path, validate=True)	Path	验证后，以原子方式提交确定性 XML（出错时抛出异常）。

位置关键字参数（right_of、left_of、below、above、in_）会自动放置节点——每行/每列只需为第一个锚点设置显式 x,y。

查找图标名称

from btp_builder import list_aliases, list_icons, lookup_icon
print(list(list_aliases())[:30])     # short names → canonical keys
print(lookup_icon("integration suite", "L1")["key"])

如果 lookup_icon 抛出 IconNotFound，请改用样式化图块（external(label, kind="sap")），并在最终回复中说明。

打开图表

uv run python skills/btp-diagram-generator/scripts/open_diagram.py btp-task-center-architecture.drawio

如果找不到系统打开程序，则会退回到打印 https://app.diagrams.net/?…#create=... URL。如果运行环境中有 draw.io MCP 工具，请优先使用——只调用工具列表中实际出现的 MCP 工具。

---

手动 XML 路径（仅适用于高级/特殊情况）

仅当 Quick Path 无法满足需求时使用（例如特殊图例变体、自定义流程协议标签或构建器尚不支持的新布局）。下文介绍构建器为你生成的底层 XML 基元。

适用场景

遇到以下请求时触发：

• “为……绘制 BTP 架构图”
• “生成一张 BTP 解决方案图，展示 CAP + HANA Cloud + Build Workzone”
• “为我们的 SAP BTP 集成版图创建一张 draw.io 图” -“针对 绘制 L0 / L1 / L2 BTP 图”

如果请求的是通用流程图、时序图或非 SAP 架构，请勿使用此技能——改用 Mermaid 或普通 draw.io 工作流生成。

需要收集的输入（一次性简洁询问）

生成前，确认缺少哪些信息。若未指定，默认采用 L1。

输入	默认值	备注
受众级别	L1	L0 = 业务概览（无图例，连接线样式中性）；L1 = 技术级（服务 + 主要流向）；L2 = 详细级（数据流、协议、组件）
BTP 服务 / SaaS 应用	（必须询问）	例如：CAP、Build Code、Integration Suite（CPI/Event Mesh/API Mgmt）、HANA Cloud、SAC、AI Core、Joule、Build Workzone、Identity Authentication、Destination、Connectivity
非 BTP 系统	（可选）	例如：S/4HANA Cloud、SuccessFactors、Ariba、第三方 SaaS、本地系统、最终用户
环境 / 运行时	Cloud Foundry	Cloud Foundry、Kyma、ABAP Environment
区域 / 是否多区域？	单区域	影响分组容器
主要流向	（必须询问）	连接什么、方向、用途
输出格式	.drawio + PNG	始终生成 .drawio；可选通过 draw.io CLI 导出 PNG（-s 2）、SVG 或 PDF
输出文件名	btp-diagram.drawio	保存到工作区根目录，除非用户另有指定

如果用户提供的一行提示包含足够的服务且流向明确，则直接继续，无需询问——在最终回复中说明假设。

组件允许列表规范

布局前，根据请求创建明确的组件允许列表：

1. 列出请求中指定的参与者、客户端、服务、目标，以及架构上必需的支持服务（例如，用于身份验证流程的 CIS）。
2. **不要为了装饰而添加熟悉的产品。**SAP Build Work Zone、SuccessFactors 或额外的发布目标，只有在用户明确要求或所述流程需要时才出现。
3. 保留请求指定的顺序，并将其作为有序边列表。例如，Outlook → Document AI → Integration Suite → S/4HANA Cloud 表示仅包含这些相邻边——不要插入中间步骤或添加其他目标。

工作流

1. 将需求映射到 BTP 图标

不存在 mxgraph.sap.* 模板系列。 draw.io 中的 SAP BTP 图标是以 base64 编码嵌入在 shape=image;image=data:image/svg+xml,<base64>;… 样式字符串中的 SVG，分发于 SAP draw.io shape library XML 文件。生成 shape=mxgraph.sap.foo 会在画布上显示一个空方框——你已经见过这种失败情况。

对于每个请求的服务，请在 references/icon-index.json 中查找其实际 style 字符串：

1. 首选： 加载 references/icon-index.json（约 660 KB，100 个图标）。该文件将每个图标标题（例如 31068-sap-build-work-zone_sd）映射到其 style 字符串以及库单元格的 width/height。通过与请求的服务名称进行子字符串匹配来查找。
2. 源 XML 库（如果需要非默认尺寸，或索引中未包含的元数据字段）位于 references/libraries/——每个图标集都有一个 M 尺寸的 mxlibrary（包括 foundational、integration suite、app-dev、AI、data-analytics、BTP-SaaS、all-in-one）。
3. 样式参考： 对于复合模式（子账户卡片、NETWORK 边界、胶囊标签、图例卡片），请参阅精选的 references/examples/——其中有 11 个官方可编辑图表（Task Center L0/L1/L2、Build Work Zone L2、Process Automation L2、Cloud Identity Services L1/L2、Private Link L2、SAP Start L2）。打开其中任意一个并复制准确的样式字符串。
4. 如果库中确实没有某项服务，请使用带样式的备用图块（见下文 §3），并在最终回复中列出该服务，以便用户替换。

按受众级别选择的默认图标几何尺寸（与官方示例一致——参见 references/example-patterns.md §5）：

SVG 固有尺寸警告： SAP 形状库中的每个图标，其根 <svg> 元素都设有 width="16" height="16"，即使在 M 尺寸集合中也是如此。draw.io 会先以该固有尺寸栅格化，再放大图像，导致图标模糊。提取 base64 SVG 后，请将根 <svg width> 和 <svg height> 修改为与目标单元格尺寸一致（例如 L1 为 48），然后重新编码。保持 viewBox 不变。Python 辅助程序见 references/example-patterns.md §11。

Level	Icon size	Label
L0	50×50	Arial 14 bold
L1	48×48	Arial 14 bold
L2	32×32	Arial 12 regular

标签放在单元格的 value= 属性中，并显示在图标下方（库样式已设置 verticalLabelPosition=bottom）。始终保留库样式中的 points=[[0,0,0,0,0],…] 12 锚点数组，以确保连接器能够准确吸附。

2. 应用 SAP Fiori Horizon 配色

仅使用以下颜色（切勿随意选择填充色）。来源：SAP BTP Solution Diagram 指南 — Foundation (Atoms) 和 Areas：

Token	Hex	用途
SAP/BTP border（主色）	#0070F2	BTP 容器描边、强调填充、子卡片描边
SAP/BTP fill	#EBF8FF	BTP 容器背景
Non-SAP border	#475E75	非 SAP／外部区域描边、通用数据流连接线
Non-SAP fill / Subtle bg	#F5F6F7	非 SAP 区域、页面背景、通用胶囊填充
Title text	#1D2D3E	标题、主要标签
Secondary text	#556B82	次级标签、说明、脚注
Positive（认证，绿色）	#188918 / bg #F5FAE5	认证流程（SAML、OIDC）— 按照指南
Critical（警告，橙色）	#C35500 / bg #FFF8D6	警告
Negative（错误，红色）	#D20A0A / bg #FFEAF4	错误
Teal accent	#07838F / bg #DAFDF5	高亮区域
Indigo（授权）	#5D36FF / bg #F1ECFF	授权／配置（SCIM）流程 — 按照指南
Pink（信任）	#CC00DC / bg #FFF0FA	信任流程（相互信任、联合）— 按照指南

字体：Arial（标题也可使用 Arial Black），正文标签字号为 12，服务标签字号为 14，组标题字号为 16。

3. 应用原子结构

遵循 SAP 原子设计系统（Atoms → Molecules → Organisms）。可直接复制的精确样式字符串、尺寸和 HTML 标签模式位于 references/example-patterns.md — 请遵照这些模式，不要自行创造变体。

• 文档标题（每张图）：位于 BTP 容器上方的浮动文本单元格，蓝色 #0070F2、粗体 Arial 16，格式为 "{Scenario} - SAP BTP Solution Diagram"。
• 外层容器（Subaccount / Multi-Cloud）：rounded=1;strokeColor=#0070F2;fillColor=#EBF8FF;arcSize=32;absoluteArcSize=1;strokeWidth=1.5;。左上角带有 SAP 徽标图像块，并有两个上下排列的标签：粗体 Subaccount（Arial 16）+ 较小的 Multi-Cloud（Arial 12）。
• 子容器（BTP 边界内的白色卡片，例如 Cloud Identity Services 组）：使用相同的 #0070F2 描边、#FFFFFF 填充和 arcSize=16。位于 BTP 容器内的卡片始终使用蓝色描边，绝不使用石板色。根据指南 区域 / 嵌套：父级和子级之间交替使用填充与无填充，以保持视觉对比（BTP 容器使用填充 #EBF8FF，因此内部卡片使用白色）。
• 服务节点：当需要单独的文本标签或与其他形状共同定位时，将 BTP 图标（§1）放在 style="group" connectable="0" 单元格中。子级坐标相对于组原点。
• 外部系统块（例如 SAP S/4HANA On-Premise）：由一组元素组成（白色卡片 arcSize=14 + 左上角约 28×28 的图标 + 右侧粗体 font-size:16px 标签）。放置在 BTP 容器外。
• 用户 / 参与者：一个包含用户 SVG 图像和下方居中 End User 文本标签的 group。
• 连接线——从示例模式参考中复制相应变体。根据指南的 连接线 部分，线条_样式_表示流的性质，线条_颜色_表示流的语义：
  • **线条样式：**实线 = 直接同步请求/响应 · dashed=1 = 间接 / 异步 · dashed=1;dashPattern=1 4;（点线）= 可选 · strokeWidth=3 = 仅用于防火墙 / 网络屏障。
  • **语义颜色：**身份验证 = 绿色 #188918 · 授权 / 配置（SCIM）= 靛蓝色 #5D36FF · 相互信任 / 联合 = 粉色 #CC00DC · 通用数据 = 石板色 #475E75。
  • 标准数据流：endArrow=blockThin;strokeColor=#475E75;endFill=1;endSize=4;startSize=4;strokeWidth=1.5;
  • 直角连接线：添加前缀 edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;
  • 身份验证（SAML/OIDC）：形状相同，使用 strokeColor=#188918
  • 授权 / 配置（SCIM）：形状相同，使用 strokeColor=#5D36FF
  • 相互信任：添加 startArrow=blockThin;startFill=1 和 strokeColor=#CC00DC
  • 异步 / 间接：使用 edgeStyle=entityRelationEdgeStyle;rounded=0;html=1;strokeColor=#475E75;strokeWidth=1.5;endArrow=blockThin;endFill=1;endSize=4;startArrow=none;startFill=0;startSize=4;jumpStyle=none;jumpSize=0;targetPerimeterSpacing=15;dashed=1;（SAP 官方间接连接线样式——entityRelationEdgeStyle + targetPerimeterSpacing=15）
  • 可选：在上述异步样式中添加 dashed=1;dashPattern=1 4;（点线）
  • 网络 / 防火墙边界线：粗灰色垂直分隔线 strokeColor=#475E75;strokeWidth=3;jumpStyle=gap;，旁边带有小号大写 NETWORK 标签（#475E75）。仅将 strokeWidth=3 用于防火墙 / 网络屏障——不要将其用于普通数据流。
  • 始终固定出口 / 入口端口，以避免自动路由为对角线：添加 exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;（根据方向调整 X/Y）。对于垂直连接线，使用 exitY=1 / entryY=0。除非需要有意绕行，否则移除手动 <mxPoint> 路点——将 <Array as="points"/> 留空。完整端口固定参考请参见 references/example-patterns.md §8。
• 边标签使用_独立的顶点药丸标签_，而非内嵌在线条上的文本——小型圆角矩形 arcSize=50，高度约 16 px，颜色与连接线匹配（通用数据 #475E75/#F5F6F7，身份验证 #188918/#F5FAE5，授权/SCIM #5D36FF/#F1ECFF，信任 #CC00DC/#FFF0FA）。
• L0：不添加图例或协议药丸标签；连接线使用中性的 endArrow=block 或 endArrow=none。
• L1：使用带方向的 endArrow=blockThin 连接线，可选添加少量带颜色的身份验证 / 配置流和药丸标签。
• L2：在标题下方添加描述块 + Diagram Level: L2，为每条有意义的边添加药丸标签，并在右上角放置图例卡片（白色卡片，strokeColor=#eaecee，为每种流类型使用带颜色的 16×16 椭圆色块，并为每种箭头样式提供示例箭头）。

4. 生成 draw.io XML

遵循 draw.io AI 生成规则：

• 使用未压缩 XML，并包含完整的 <mxfile> 包装元素（以便使用文件级变量）。
• 始终包含 <mxCell id="0"/> 和 <mxCell id="1" parent="0"/>。
• 顶点：vertex="1"。边：edge="1"，带有 source/target。两者不能同时使用。
• 图表中的 ID 必须唯一。
• 坐标：左上角为 (0,0)，x→右，y→下。组内子元素使用相对于组的坐标。
• 周长应与形状匹配（例如，椭圆使用 perimeter=ellipsePerimeter）。
• 对标签进行 XML 转义（&、<、>、"）。允许在 value= 中使用 HTML 标记，这是加粗和调整文字大小的标准方式——请参见官方示例。
• HTML 标签转义：先构造完整的 HTML 字符串（标签 + 文本，其中的 </>/" 保持原样），然后进行一次完整的转义（&→&、<→<、>→>、"→"），再插入 value="…" 属性。使用 xml.etree.ElementTree 时，传入未转义的值，由序列化器负责转义。使用真正的 XML 解析器解析写入的文件，并拒绝任何包含 <font、<font 或 <div 的可见标签。
• 在区域形状（BTP 边界、子账户卡片）上使用 container=0;——不要使用 draw.io 的容器行为——以便连接线能够正确穿过这些区域。
• 网格间距保持为 10 px 的倍数（gridSize="10"）；同级元素之间留出 ≥20 px 的间隔；子容器内边距约为 18–24 px。
• 图表使用负坐标是正常且预期的（例如 x="-2200"）；draw.io 会根据内容居中。
• 每个边的 mxCell 必须包含 <mxGeometry relative="1" as="geometry" />——自闭合的边单元格无效，且不会渲染。

页面尺寸：始终使用 A4 横向——pageWidth="1169" pageHeight="827"，即使是内容密集的 L2 也是如此。通过在负坐标区域分散组来扩大虚拟画布，而不是更改页面尺寸。L2 还需在 <mxGraphModel> 上设置 background="none"。

5. 写入文件

保存到用户指定的路径（默认：工作区根目录 btp-diagram.drawio）。未经确认，不要覆盖现有文件。

6. 通过 MCP 服务打开

按以下顺序检测可用的 draw.io MCP 集成，并使用第一个已配置的集成：

1. MCP Tool Server（@drawio/mcp / npx @drawio/mcp）：调用其“打开图表”工具，将生成的 XML 传入以在浏览器中启动编辑器。
2. MCP App Server（mcp.draw.io/mcp 远程）：调用其渲染工具，在聊天中嵌入交互式查看器。
3. 均未配置：静默跳过，改为打印按照 FAQ 构造的 https://app.diagrams.net/?pv=0&grid=0#create=... URL（URI 编码 JSON {"type":"xml","compressed":true,"data":"<base64-deflate-raw>"}）。如果无法在当前上下文中压缩，则打印文件路径，并指示用户使用已安装的 draw.io 打开该文件。

切勿臆造 MCP 工具名称——只能调用可用工具列表中实际出现的工具。

7. 交付前验证

每次候选编辑后都要进行验证。迭代时使用 standard；它会接受警告，但会报告警告。最终交付时使用 showcase；此时每条警告都会变成阻塞错误。

python3 skills/btp-diagram-generator/scripts/validate_diagram.py \
  <file.drawio> --quality standard --json

python3 skills/btp-diagram-generator/scripts/validate_diagram.py \
  <file.drawio> --quality showcase --json

JSON 收据包含稳定的诊断代码、确切的本地对象、支持的修复方法、每项检查的状态，以及制品的字节数和 SHA-256。如果验证失败，只修改诊断指出的对象，然后重新运行验证。如果连续两次修复都未能减少错误数量，请停止并报告未解决的诊断，不要重写整个图表。

最终 showcase 收据通过后，制品即被冻结：之后不要再编辑。只能打开或导出通过验证的确切文件。如果验证或保存失败，且已有较旧的输出文件，那么该文件就是最后一个可用制品，而不是被拒绝的候选文件。

如果提示图标模糊（SVG 固有尺寸小于单元格），请就地修复：

python3 skills/btp-diagram-generator/scripts/upscale_svg_icons.py <file.drawio> --size 48 --in-place

自动验证可证明 XML 结构、连接器／样式约定和字节一致性，但无法证明视觉效果是否精致。请另外通过目视检查以下项目：

• 所有标签均已进行 XML 转义（不显示原始 <font>）。
• 没有形状重叠（间距 ≥20px）。
• BTP 容器在视觉上包含所有 BTP 服务；外部系统位于容器之外。
• L0 图表没有图例，且连接器使用中性色；L2 图表在右上方包含图例卡片，并在标题下方包含说明块。
• 边标签是药丸状的 vertex 单元格，而不是 edge="1" 单元格上的内联 value= 文本。
• 连接器不会穿过无关容器。
• 不包含未经请求的组件（请对照允许列表检查）。
• 服务顺序与用户要求的顺序一致。
• CIS 位于 Subaccount 之外、BTP 之内。
• 图例（如有）不会与任何连接器重叠。

验证器会检查其余所有内容：根单元格、唯一 ID、顶点／边的互斥性、不含 mxgraph.sap.*、边的源／目标有效性、端口固定、手动航点、SVG 固有尺寸与单元格几何尺寸、调色板颜色，以及 A4 横向页面尺寸。

如需更深入的验证，请参考 mxfile.xsd 和样式参考检查清单。

最终回复模板

完成后，请按以下内容回复：

1. 保存文件的路径，格式为相对于工作区的 Markdown 链接。
2. 图表是否已在 MCP 编辑器中打开（以及打开方式），或提供备用 URL／说明。
3. JSON 收据中的最终质量配置、检查数量、错误／警告总数、制品 SHA-256 和字节数。
4. 单独说明目视检查状态，与自动验证结果分开。
5. 简短列出所做的假设，以及任何回退为通用图块的图标，供用户修正。
6. 如果图表是在使用深色主题的 draw.io 工作区中打开，请说明 SAP 标签（#1D2D3E）根据 Fiori Horizon 规范有意设为深色，因此在深色画布上会显得较淡——请将 draw.io 切换为浅色主题，或导出为 PNG／SVG 进行检查。
7. 用一句话说明如何继续迭代（例如：“请让我添加 X 服务，或将受众级别改为 L2。”）。

捆绑资源

• references/icon-index.json — 包含所有 100 个 BTP 服务图标和 3 个通用用户图标（generic:user-sap / -non-sap / -highlight）的扁平 {title → {style, width, height}} 映射。**图标样式的首选查询来源。**Quick-Path 构建器会为你读取此文件。
• references/icon-aliases.json — 短名称 → 规范键的映射（132 个别名，如 "task center"、"cpi"、"hana cloud"、"end user"）。为 BtpDiagram.service() 中的模糊查询提供支持。
• references/styles.json — 命名的 SAP 样式字符串（container_btp、card_subaccount、tile_external_sap、arrow_dblhd、pill_auth 等）、端口固定片段和各级图标尺寸。由构建器加载；手动编写 XML 时可将其作为复制粘贴参考。
• references/templates/ — 空白的 L0/L1/L2 mxfile 骨架，可直接填充。
• references/sap-logo.b64.txt — SAP 角标 Logo SVG 的 base64 数据，由 btp_container(with_logo=True) 嵌入。
• references/libraries/ — 7 个官方 SAP draw.io mxlibrary XML 文件（foundational、integration-suite、app-dev-automation、data-analytics、AI、BTP-SaaS，以及全合一 size-M 集合）。需要索引中未公开的原始库数据时使用。
• references/svg/ — 每个 BTP 服务图标对应的 129 个原始 .svg 源文件。需要编辑／重新着色图标、导出为非 draw.io 格式，或在 draw.io 样式字符串之外嵌入图标时使用。
• references/examples/ — 11 个官方可编辑示例图表（Task Center L0/L1/L2、Build Work Zone L2、Process Automation L2、Cloud Identity Services L1/L2、Private Link L2、SAP Start L2）。复合样式模式的首选来源（子账户卡片、网络边界、胶囊标签、图例卡片）。
• references/sap-btp-palette.json — 上文所述的精确颜色令牌，可直接粘贴到 draw.io Extras → Configuration 的 customColorSchemes 中。
• references/example-patterns.md — 从示例图表中提取的可直接复制的样式字符串、尺寸、标签 HTML 和连接器／胶囊配方。需要容器、图标、边或胶囊的确切样式时，请查阅此文件——不要自行设计。

捆绑脚本

在 scripts/ 中，可通过 uv run python 运行（无第三方依赖）：

• scripts/btp_builder/ — Quick-Path 包。BtpDiagram DSL、支持别名解析的图标查询、调色板常量、端口固定辅助函数、SVG 放大、命名样式。导入方式：from btp_builder import BtpDiagram。
• scripts/examples/task_center_arch.py — 可运行的规范示例，端到端复现 Task Center 参考架构。
• scripts/open_diagram.py — 使用操作系统的打开程序（macOS open、Linux xdg-open、Windows start）打开 .drawio 文件；如果失败，则打印 app.diagrams.net URL。
• scripts/validate_diagram.py — 强制执行 §7 检查清单。可检测 mxgraph.sap.* 拼写错误、重复 ID、源／目标已断开的边、缺失的端口固定点、手动路点、非调色板颜色和 SVG 固有尺寸导致的模糊。最终检查时使用 --quality showcase --json，可确保零警告并生成机器可读的结果。仍支持旧版 --strict-palette 和 --strict-waypoints 标志。还提供 validate_xml(xml) / validate_path(path)，可在 Python 中复用。
• scripts/upscale_svg_icons.py — 通过修补根 <svg> 的 width／height 以匹配单元格几何尺寸，修复模糊图标（保持 viewBox 不变）。默认目标尺寸为 48 px；L2 使用 --size 32，L0 使用 --size 50。使用 --in-place 覆盖文件。（Quick-Path 构建器会自动执行此操作；仅对手动编写的 XML 手动运行。）

布局提示

避免连接线重叠

生成连接较多的图表时：

1. 固定出发点和进入点 — 始终为连接线设置明确的 exitX、exitY、entryX、entryY，以精确控制连接线离开或到达形状的位置。
2. 沿周边分散连接点 — 从一个形状引出 N 条连接线时，分散设置出发点。例如，底部有 3 条连接线时，设置为 exitX=0.25、0.5、0.75（不要全部设为 exitX=0.5）。
3. 使用路径点 — 路径较复杂时，在 <Array as="points"> 中添加 <mxPoint> 路径点，强制连接线通过指定通道。
4. 错开垂直间距 — 将连接较多的元素放在不同的 Y 轴位置，为连接线留出空间。
5. 通过视觉区分流类型 — 不同流类型使用形状的不同边（数据流从右侧引出，身份验证流从底部引出）。
6. 优先使用一条连接线指向共享目标区域 — 如果 S/4HANA 和 SuccessFactors 位于同一个“Sap Cloud Solutions”区域内，则使用一条连接线指向该区域边界，而不是扇形分散连接线。
7. 将外部目标放在侧边列中 — 按 SAP 参考图的方式，使外部区域与集成中心水平对齐。

连接线不得穿过容器

连接线不得在视觉上穿过与其无关的容器。

1. 检查完整路径（所有线段），确认它不会与任何无关容器的边界框相交。
2. 调整容器位置，避开连接线通道。
3. 分别检查每条正交线段：位于 X=V 的垂直线不得穿过横跨该 X 坐标的容器；位于 Y=H 的水平线不得穿过横跨该 Y 坐标的容器。

线条保持笔直且统一（尽量减少转折）

优先使用零转折；通常最多转折一次（90°）。只有在障碍物使其无法避免时，才允许出现两次或更多转折。

1. 按中心坐标对齐元素 — 两个元素需要以直线相连时，确保它们的 X 中心相同（垂直线），或 Y 中心相同（水平线）。
2. 围绕连接线几何形状设计布局 — 先确定直线约束，再摆放元素。
3. 遵守转折数量限制： 0 次转折 = 共用中心轴；1 次转折 = 固定一个 mxPoint；2 次或更多转折 = 拒绝并重新调整位置，除非确实是障碍物所致。
4. 不要依赖自动正交路由处理位置偏移的元素——它会产生不必要的折线。请固定明确的路径点。

连接线标签留白

连接线不得穿过图标标签、产品名称或区域标题：

1. 优先使用 value="" 的图标单元格，并在其下方单独设置文本单元格。
2. 如果垂直连接线必须从图标下方继续延伸，应从标签单元格的下边缘引出，而不是从图标引出。
3. 水平连接线保持在图标中心线上，标签放在下方（exitY=0.5、entryY=0.5）。
4. 箭头前至少留出 20px 的直线。转折点不得紧挨图标。

SAP Cloud Identity Services 的位置

CIS 必须位于 Subaccount 外部、BTP 内部（身份服务在 BTP 层级配置，而不是在子账户内配置）：

1. 将 CIS 放在 Subaccount 下方，但仍位于 BTP 边界内。
2. 将 CIS 放在 BTP 的左侧，避免从 Integration Suite（右侧）引出的垂直连接线穿过 CIS。
3. CIS 容器：白色填充（#ffffff），灰色边框（#475E75）——采用交替填充模式（BTP 蓝色 → CIS 白色）。
4. CIS → Subaccount：使用绿色虚线的 双向 OIDC 信任连接线。现代 BTP 信任不使用 SAML 2.0——SAML 仅适用于上游企业 IdP 联合身份验证。
5. 仅在需要身份配置时，单独显示 SCIM 2.0（靛蓝色 #5D36FF）。

Application Clients 的呈现方式

Application Clients 应为独立的图标 + 标签，不要将其包在容器中：

1. 使用 "Application and User" 组件组中的 App Clients 图标。
2. 将图标的 value=""，并在下方添加一个单独的文本单元格，设置 value="Application Clients
Mobile / Desktop"。
3. 从图标侧面（exitY=0.5）连接水平数据流，不要穿过标签。
4. 不要为其添加容器区域。

区域嵌套填充模式

嵌套时始终交替填充：blue → white → blue → white。

L0: BTP Platform   (border #0070F2, fill #EBF8FF)
  L1: Subaccount   (border #475E75, fill #ffffff)
    L2: Service group (border #0070F2, fill #EBF8FF)
  L1: CIS          (border #475E75, fill #ffffff)

蓝色填充容器的直接子项必须使用白色填充（不能蓝色叠蓝色）。

图例位置

图例不得与任何连接线或元素重叠：

1. 放在空白角落，优先选择右下角（数据流从左到右、从上到下）。
2. 检查所有连接线的路径；图例不得与任何路径相交。
3. 不要放在连接线经过的源和目标之间。

图表标题位置

任何容器边框都不得遮挡标题：

1. 将标题放在 BTP 容器顶部边缘上方（例如标题 y=10，BTP y=50）。
2. 或将标题放在 BTP 内部，并与边框至少保持 10px 的间距。
3. 在每个区域顶部预留 45-60px 的标题带。

导出工作流（draw.io CLI）

前提条件

# macOS (Homebrew installs as `drawio`, no dot)
drawio --version

# macOS (full path fallback)
/Applications/draw.io.app/Contents/MacOS/draw.io --version

# Linux
draw.io --version

# Windows
"C:\Program Files\draw.io\draw.io.exe" --version

如果未安装，请从 jgraph/drawio-desktop/releases 安装。

步骤 1 — 导出预览 PNG（不使用 -e）

drawio -x -f png -s 2 -o diagram.png diagram.drawio

步骤 2 — 自检

使用视觉检查（如果可用）验证导出的 PNG：

检查项	检查内容
SAP 颜色正确	SAP 使用蓝色 #0070F2，非 SAP 使用灰色 #475E75
区域嵌套	蓝色 / 白色交替填充
形状重叠	所有同级元素之间间隔 ≥20px
标签被裁切	文本被截断 → 增大形状尺寸
连接缺失	箭头未连接 → 检查源 / 目标 id
线条样式	实线 = 同步，虚线 = 异步
未请求的组件	允许列表中未包含的产品 → 移除
服务顺序错误	边缘顺序与所请求的顺序不同 → 修正
标题冲突	图标 / 标签触碰区域标题 → 移至预留标题带下方
原始 HTML 文本	可见 <font> 标记 → 修正转义

另请运行：python3 scripts/validate_diagram.py diagram.drawio --strict-palette

最多进行 2 轮自检。

步骤 3 — 审核循环

向用户展示预览。根据反馈进行有针对性的 XML 修改。重复此过程，直到获得批准。**安全措施：**经过 5 轮后，建议用户在 draw.io 桌面应用中打开 .drawio 文件进行手动微调。

步骤 4 — 最终导出（使用 -e 嵌入图表）

# PNG with embedded diagram XML (editable in draw.io)
drawio -x -f png -e -s 2 -o diagram.drawio.png diagram.drawio

# SVG with embedded diagram
drawio -x -f svg -e -o diagram.drawio.svg diagram.drawio

# PDF
drawio -x -f pdf -o diagram.pdf diagram.drawio

关键标志：-x 导出模式 · -f 格式 · -e 嵌入图表 XML · -s 缩放比例（PNG 推荐设为 2）· -o 输出路径 · -b 10 边框。

已知问题：使用 -e 导出的 PNG 中 IEND 被截断

draw.io CLI 导出的 -e PNG 在 IEND 处会被截断 8 个字节，导致某些查看器 / API 无法读取该文件。导出 SVG / PDF 不受影响。如果最终 PNG 无法打开，请重新导出一个不带 -e 的版本，作为面向用户的图像。

回退链

场景	行为
缺少 draw.io CLI，有 Python 可用	生成 .drawio + 输出 https://app.diagrams.net/?… 浏览器 URL
缺少 draw.io CLI，也没有 Python	仅生成 .drawio XML；提示用户手动打开
沙盒中无法使用 CLI（macOS）	使用浏览器回退方案；请用户在非沙盒终端中导出
自检时无法使用视觉功能	跳过视觉验证；继续向用户展示文件
Linux 无头导出失败	尝试 xvfb-run -a drawio …；如果出现 EGL 错误，添加 --disable-gpu

WSL2 特殊说明

# CLI path on WSL2
"/mnt/c/Program Files/draw.io/draw.io.exe" --version

# Open exported file (convert path first)
cmd.exe /c start "" "$(wslpath -w diagram.drawio.png)"

常见错误

错误	修复
缺少 id="0" / id="1" 根单元格	始终在 <root> 开头同时包含这两个单元格
自闭合边缘 mxCell（<mxCell ... edge="1" />）	使用展开形式，并包含 <mxGeometry relative="1" as="geometry" /> 子元素
XML 注释中出现 --	根据 XML 规范，这是非法的——请改写
shape=mxgraph.sap.* 样式	不存在；请使用 shape=image;image=data:image/svg+xml,...，图标来源为 icon-index.json
标签中含字面值 \n	在 value 属性中使用 &#xa; 表示换行符
HTML 标签双重转义	先构建 HTML 字符串，再完整转义一次（&amp;、&lt;、&gt;、&quot;），然后插入 value="…"
图表中可见原始 <font> 标记	生成后使用 XML 解析器验证；使用 xml.etree.ElementTree.fromstring()
图标模糊	编码前将 SVG 的 width/height 调整为单元格大小；运行 upscale_svg_icons.py
边缘穿过无关容器	重新定位容器或添加路径点
所有连接器都从同一点离开	沿周边分散出口/入口（exitX=0.25、0.5、0.75）
自动路由生成曲折线段	固定显式路径点；对齐中心以绘制直线
数据流使用 strokeWidth=3	仅将粗灰线用于防火墙/网络屏障
macOS 出现 command not found: draw.io	Homebrew 安装的命令是 drawio（没有句点）
视觉功能提示“dimensions exceed 2576×2576px”	使用 --width 2000 重新导出，而不是 -s 2