LikeC4 与 LeanIX 桥接与 Draw.io 往返导出leanix-bridge、leanix 导出 Profile 与 Agent 边界实践指南【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4本指南聚焦 LikeC4 生态中的 LeanIX 集成场景如何以 LikeC4 DSL 为唯一权威源canonical source of truth通过likec4 gen leanix/likec4 sync leanix生成并同步 LeanIX 形态的库存制品如何用--profile leanix导出携带桥接元数据的 Draw.io 图并在导出/解析/同步之间完成身份往返round-trip以及 MCP 与 CLI 桥接工具之间应有的边界。读完本文你将掌握从 LikeC4 模型到 LeanIX 事实表fact sheet与关系relation的完整工作流并能正确区分「查询类」MCP 工具与「写入类」CLI 桥接命令的职责。本指南以仓库中的 bridge-leanix-drawio.md 参考文档为主体骨架并以其实现包 likec4/leanix-bridge 与 Draw.io 生成器 的源码作为底层佐证。建议先阅读 CLI 参考 熟悉命令体系。1. 权威源与职责边界Canonical source of truth与 LeanIX、Draw.io 相关的任务首先要确立一条铁律LikeC4 DSL.c4/.likec4是唯一权威源。桥接bridge所做的一切——生成 LeanIX 形态的库存、为 Draw.io 图添加注解——都是从已解析的 LikeC4 语义模型resolved model派生的而非反向让 LeanIX 或 Draw.io 成为事实来源。对应到实现层likec4/leanix-bridge包在 contracts.ts 中明确声明了这一点外部 ID 是「按 Provider 隔离」的external?: PartialRecordProvider, ProviderExternalIds即 LeanIX 的factSheetId只是 LikeC4 实体的一个外部注解语义锚点始终是 LikeC4 的 FQN。在此基础上Agent Skill 的边界同样清晰本仓库的 likec4-dsl skill 及其参考文档负责传授 DSL 语法与 CLI 契约但它不代替运行命令本身。涉及实际产出的操作必须执行likec4 gen leanix …likec4 sync leanix …likec4 export drawio --profile leanix换言之Skill 是「教你怎么用」CLI 是「真正干活」。2. 一级 CLI 命令从 dry-run 到 Live Sync以下命令需在项目根目录执行完整细节可查阅 likec4/leanix-bridge 的 README。命令的四个典型目标是目标命令Manifest dry-run 报告likec4 gen leanix dry-run -o out/bridge同步工作流dry-run / 计划likec4 sync leanix --dry-run -o out/bridge将同步应用到 LeanIX APIlikec4 sync leanix --apply -o out/bridge需要LEANIX_API_TOKEN导出带桥接管理单元的 Draw.io 图likec4 export drawio --profile leanix -o ./diagramsdry-run 阶段纯本地、无网络likec4 gen leanix dry-run一次性产出三类制品到out/bridgemanifest.json—— 身份清单canonical ID 占位外部 IDleanix-dry-run.json—— LeanIX 形态的库存事实表 关系无真实 IDreport.json—— 汇总报告各类数量与制品名。同步阶段涉及 LeanIX APIlikec4 sync leanix --dry-run除了写出制品还会在设置了LEANIX_API_TOKEN时只读查询LeanIX产出一个sync-plan.json描述「将创建 vs 将更新」的每一项供你在真正推送前审查likec4 sync leanix --apply才会真实调用 LeanIX API 创建/更新事实表与关系要求环境变量LEANIX_API_TOKEN存在。Phase 2 入站inbound只读如需从 LeanIX 拉取快照并与模型对账可用# 只读抓取 LeanIX 库存快照到 out/bridge likec4 gen leanix inventory -o out/bridge # 在 manifest 与 LeanIX 库存之间执行对账输出到 out/bridge likec4 gen leanix reconcile -o out/bridgeDraw.io 导出使用 LeanIX profile 导出时顶点与边会携带likec4Id、likec4ViewId、likec4RelationId与bridgeManaged等属性为后续同步与往返解析提供稳定身份详见第 4 节。补充说明Phase 2库存快照、对账与 Phase 3影响分析、漂移检测、ADR 生成、治理检查均在likec4/leanix-bridge的范围内但「AI 特性」与「新的顶层 CLI 命名空间」不在其范围内——这是该包 README 的 Scope 声明 明确划定的边界。3. 映射配置YAML / JSON 与默认映射LeanIX 的事实表类型、关系类型是按工作区元模型meta-model而异的不存在普适分类法因此桥接提供可配置的映射并给出保守的安全默认值。3.1 配置项自定义 LeanIX 映射YAML 或 JSON在默认映射之上合并merge over defaults支持三个顶层键对应 mapping.ts 中的LeanixMappingConfig配置键作用默认值DEFAULT_LEANIX_MAPPINGfactSheetTypesLikeC4 元素 kind → LeanIX 事实表类型system → Application、container → ITComponent、component → ITComponent、actor → ProviderrelationTypesLikeC4 关系 kind → LeanIX 关系类型名default → depends onmetadataToFieldsLikeC4 标签 / 元数据键 → LeanIX 字段名title → name、description → description、technology → technology当某个 kind 未命中时会沿「精确 kind →default→ 兜底常量」的优先级回退事实表兜底为ApplicationFALLBACK_FACT_SHEET_TYPE关系兜底为depends onFALLBACK_RELATION_TYPE。actor类型默认映射到Provider除非被显式覆盖。3.2 严格校验坏形状会被拒绝映射配置在通过mergeWithDefault/ 校验归一化时非法形状会抛出带明确信息的错误见 mapping.ts 的parseLeanixMappingInput顶层键只能是factSheetTypes、relationTypes、metadataToFields之一出现未知键会报错LeanIX mapping has unknown key …. Allowed: factSheetTypes, relationTypes, metadataToFields每个键的值必须是「字符串键 → 字符串值」的普通对象数组会被拒绝isPlainObjectRecordOfStrings会检查Array.isArray(value)非字符串值同样报错传入null/undefined视为「未提供」直接返回走默认映射。合并语义是浅合并shallow mergemergeWithDefault先拷贝默认值再用用户配置逐键覆盖因此你只需声明需要偏离默认的部分。4. Draw.io 导出 Profile 与往返Round-trip心智模型4.1 default profile vs leanix profileDraw.io 生成器generate-drawio.ts支持两种导出 profile由GenerateDrawioOptions.profile控制默认 profiledefaultstyle 中不包含bridgeManaged/likec4Id等桥接字段LeanIX profileleanix为往返与 LeanIX 对齐追加桥接元数据。按源码中buildBridgeManagedStyleForNode与buildBridgeManagedStyleForEdge的实现generate-drawio.tsleanix profile 的 style 字段如下元素写入的 style 字段顶点vertexbridgeManagedtrue、likec4Id、likec4Kind、likec4ViewId可选likec4ProjectId当提供了 kind → 事实表类型映射时还会写入leanixFactSheetType边edgebridgeManagedtrue、likec4RelationId根单元root cellbridgeManagedtrue、likec4ViewId、可选likec4ProjectId同时无论哪种 profile节点与边都会写入一组likec4*往返字段如likec4Description、likec4Technology、likec4Notes、likec4Tags、likec4NavigateTo、likec4Icon、likec4Summary、likec4Border、likec4Opacity、likec4StrokeColor、likec4RelationshipKind、likec4Metadata等用于把 DSL 属性完整编码进 Draw.io style保证「图即是数据」。导出的相关实用旗标--roundtrip将布局信息以注释形式嵌入 DSL 中--all-in-one多视图合并导出--uncompressed输出未压缩的原始 XML默认是base64(deflateRaw(encodeURIComponent(xml)))压缩格式Draw.io 两种都接受。4.2 往返闭环官方参考文档给出的心智模型是三步闭环其每一环都有源码支撑导出用likec4 export drawio --profile leanix导出使单元格携带稳定的 LikeC4 身份解析回 DSL用 Draw.io 解析器packages/generators的 Draw.io 模块见 generate-drawio.spec.ts 与 parse-drawio.spec.ts 的测试将图解析回 DSL解析器支持的地方顶点上的likec4Id与边上的likec4RelationId保留了 FQN 与关系身份同步后映射LeanIX 同步完成后manifestToDrawioLeanixMapping(manifest)把likec4Id与 LeanIX 事实表 / 关系 ID 对应起来供重新导出或工具链消费。manifestToDrawioLeanixMapping的实现在 drawio-leanix-roundtrip.ts它返回{ likec4IdToLeanixId, relationKeyToLeanixRelationId }两个映射——前者从 manifest 实体中取external.leanix.factSheetId ?? external.leanix.externalId后者以关系的复合键sourceFqn|targetFqn|relationId为键取external.leanix.relationId。配套的 drawio-leanix-roundtrip.spec.ts 覆盖了该映射的构建逻辑。重要约束不要臆造 bridge JSON 的形状。所有制品要么通过 CLI 生成要么通过likec4/leanix-bridge的公开 API 生成具体契约以包 README 为准。5. 程序化使用likec4/leanix-bridge API除了 CLI桥接能力也可以直接以 TypeScript 方式接入 LikeC4 配置或自定义脚本。包 index.ts 导出了完整 API。5.1 自定义 Generator替代方案在 likec4.config.ts 中注册自定义 generator用桥接函数产出三类制品// likec4.config.ts import { defineConfig } from likec4/config import { buildBridgeReport, toBridgeManifest, toLeanixInventoryDryRun, } from likec4/leanix-bridge export default defineConfig({ name: my-project, generators: { my-leanix: async ({ likec4model, ctx }) { const manifest toBridgeManifest(likec4model, { mappingProfile: default }) const dryRun toLeanixInventoryDryRun(likec4model, { mappingProfile: default }) const report buildBridgeReport(manifest, dryRun) await ctx.write({ path: [out, bridge, manifest.json], content: JSON.stringify(manifest, null, 2) }) await ctx.write({ path: [out, bridge, leanix-dry-run.json], content: JSON.stringify(dryRun, null, 2) }) await ctx.write({ path: [out, bridge, report.json], content: JSON.stringify(report, null, 2) }) }, }, })随后运行likec4 gen my-leanix即可。5.2 同步计划推送前审查planSyncToLeanix只读查询 LeanIX返回一个描述「将创建 vs 将更新」的同步计划供人工审查后再执行真正的同步import { LeanixApiClient, planSyncToLeanix } from likec4/leanix-bridge const client new LeanixApiClient({ apiToken: process.env.LEANIX_API_TOKEN!, baseUrl: https://app.leanix.net, requestDelayMs: 200, }) const plan await planSyncToLeanix(dryRun, client, { idempotent: true }) // plan.summary: { factSheetsToCreate, factSheetsToUpdate, relationsToCreate } // plan.factSheetPlans: [{ likec4Id, name, type, action: create|update, existingFactSheetId? }] // 将 plan 写入 out/bridge/sync-plan.json 审查后再执行同步5.3 同步到 LeanIX API生成 dry-run 制品以及可选的同步计划之后推送需要 API tokenimport { LeanixApiClient, syncToLeanix, manifestToDrawioLeanixMapping } from likec4/leanix-bridge const client new LeanixApiClient({ apiToken: process.env.LEANIX_API_TOKEN!, baseUrl: https://app.leanix.net, requestDelayMs: 200, }) const result await syncToLeanix(manifest, dryRun, client, { idempotent: true }) // result.manifest 中每个实体带 external.leanix.factSheetId const mapping manifestToDrawioLeanixMapping(result.manifest) // 使用 mapping.likec4IdToLeanixId 做 Draw.io 往返5.4 底层 API 一览完整导出index.ts包括制品构建toBridgeManifest(model, options?)身份清单、toLeanixInventoryDryRun(model, options?)LeanIX 形态库存、buildBridgeReport(manifest, leanixDryRun)汇总报告API 客户端LeanixApiClient(config)——GraphQL 客户端带 Bearer 认证与限流apiToken必填baseUrl?默认https://app.leanix.netrequestDelayMs?默认 200见 leanix-api-client.ts同步planSyncToLeanix(leanixDryRun, client, options?)、syncToLeanix(manifest, leanixDryRun, client, options?)返回带external.leanix.factSheetId与关系 ID 的更新后 manifest往返manifestToDrawioLeanixMapping(manifest)Phase 2fetchLeanixInventorySnapshot(client, options?)只读分页快照、reconcileInventoryWithManifest(snapshot, manifest, options?)返回 matched / unmatchedInLikec4 / unmatchedInLeanix / ambiguousPhase 3buildDriftReport(reconciliation)、impactReportFromSyncPlan(plan)、generateAdrFromReconciliation(...)/generateAdrFromDriftReport(...)、runGovernanceChecks(reconciliation, options?)类型守卫isBridgeManifest(obj)/isLeanixInventorySnapshot(obj)用于校验解析自 CLI 制品文件的 JSON。5.5 核心契约manifest 与往返身份遵循以下稳定契约contracts.tscanonicalIdLikeC4 FQN如cloud.backend.apiviewIdLikeC4 视图 id如index、landscape.overviewrelationId compositeKeysourceFqn|targetFqn|relationId作为关系稳定身份manifest 元数据manifestVersion当前为1.0见BRIDGE_MANIFEST_VERSION、generatedAtISO 时间戳、bridgeVersion与包版本同步、mappingProfiledefault或custom。6. MCP 与桥接的边界很多使用者会混淆 MCP 与 CLI 桥接的职责参考文档给出了明确划分MCPlikec4 mcp、likec4/mcp暴露的是read / query 类工具——对 LikeC4 工作区模型的元素、视图、关系进行查询。它不替代likec4 gen leanix或likec4 sync leanix凡是涉及LeanIX 制品、Draw.io leanix profile、manifest dry-run的操作一律走CLI或程序化的likec4/leanix-bridge如本文第 2、4 节所述。这一边界的意义在于查询模型是廉价且只读的而 LeanIX 同步是对外部系统的写入操作二者不应混用避免 Agent 在「只想读模型」时意外触发外部 API 调用。7. 给 Agent 的实操清单综合本文Agent 处理 LeanIX / Draw.io 桥接任务时应遵守以 LikeC4 DSL 为唯一权威源所有 LeanIX 形态制品均由已解析模型派生Skill 只教语法与契约不代替执行命令产出制品必须运行likec4 gen leanix …、likec4 sync leanix …、likec4 export drawio --profile leanix先 dry-run 后 apply用likec4 gen leanix dry-run与likec4 sync leanix --dry-run审查变更含只读的 sync plan确认无误后再--apply导出用 leanix profile并保留--roundtrip能力确保likec4Id/likec4RelationId等身份字段写入 style使图可被解析回 DSL 并与 LeanIX 对齐不要臆造 bridge JSON 形状一律通过 CLI 或likec4/leanix-bridge公开 API 生成映射配置遵循严格校验仅允许factSheetTypes/relationTypes/metadataToFields三个顶层键值为字符串映射对象非法形状会被mergeWithDefault校验拒绝查询用 MCP写入用 CLI不要跨界。通过以上流程你可以在不改变 LikeC4 单一事实源的前提下完成「模型 → LeanIX 库存 → 带桥接元数据的 Draw.io 图 → 解析回 DSL → 同步对齐」的完整闭环并让 LeanIX 工作区的差异创建/更新、漂移、影响始终处于可审查、可回滚的受控状态。【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考