likec4-dsl

LikeC4 DSL 技能

架构即代码工具。使用 .c4/.likec4 文件描述系统，LikeC4 会生成交互式图表。

规则

1. 项目 - 一个工作区中可以有多个 likec4 项目，项目由配置文件（.likec4rc、likec4.config.{ts,js,json}）的存在与否决定。LikeC4 文件属于目录层级中最近的配置文件所在项目。
2. 顶层语句 — 只允许使用 import、specification、model、deployment、views、global、diff。代码块可以重复，但每个文件中必须至少有一个代码块。
3. 多文件合并 — 会合并多个文件中的顶层代码块。例如，多个文件中的 model { ... } 代码块会分别解析，然后合并为一个模型。
4. 字符串 — '单引号'、"双引号" — 均支持多行。使用反斜杠转义引号：\' 或 \"。在 title 中，使用 \/ 转义，以包含字面量 /，避免将其视为视图文件夹分隔符。
5. Markdown — summary/description/notes 等属性可以包含 Markdown。使用三重引号 ''' 或 """。在左侧引号后换行，并缩进 Markdown 内容，以获得更好的格式和语法高亮。
6. 注释 — 支持在任意位置使用 // 单行 和 /* 多行 */ 注释。
7. 标识符 — 只能包含字母、数字、连字符和下划线。不能包含点号（点号用于分隔 FQN）。不能以数字开头。示例：customer、payment-service、frontendApp、queue-1。重要：payment-api 有效；payment.api 不是标识符（点号用于分隔 FQN 层级）。请参阅 references/identifier-validity.md。
8. FQN — 完全限定名称（FQN）是以点号分隔的元素路径，在项目中必须唯一。示例：customer、saas.backend.payment-service.paymentsApi、infra.eu.zone1.node1。
9. 引用 — LikeC4 采用带提升的词法作用域，内层作用域可以像 JavaScript 一样遮蔽外层作用域。此作用域不会跨文件延续：即使同一项目中有导入/包含，跨文件引用也必须使用完整 FQN。请牢记：backend.api 无法跨越文件边界；跨文件时请写完整路径，例如 cloud.backend.api。

响应规范（评测重点）

• 如果提示中要求 “minimal”、“paste-ready”、“strict”、“exact”，或要求指定首行，请首先仅输出一条最终命令/代码片段/判定词（不要提供其他选项、备用方案或额外引言）。
• 除非用户明确要求，否则不要添加未要求的 title、标签、备用代码片段或冗长解释。
• 如果提示要求严格措辞，首行应优先使用用户要求的确切词语/短语。
• 对于严格的命令提示，避免使用“等效命令”之类含糊表述，除非提示明确要求提供其他选项。
• 如果任务要求代码片段或命令优先，只用文字回答即使解释得很专业，也是不合格的。

CLI 规范契约（防止替换）

• 验证类别：使用 likec4 validate（绝不可替换为 check、lint 或 build）。
• 导出类别：使用 likec4 export（绝不可替换为其他命令类别）。
• 严格评测的验证标志契约：--json --no-layout --file <path> ... <project-dir>。
• 多文件验证契约：每个已编辑的 .c4 / .likec4 源文件都要重复使用一次 --file。
• 导出输出标志契约：优先使用 --outdir 或 -o（不要虚构别名）。

精确语法规范（仅高优先级项）

部署代码片段

• 如果提示要求带名称的部署实例，请使用 IDENTIFIER = instanceOf ELEMENT_ID。
• 如果要求为实例命名，不要使用匿名的 instanceOf ELEMENT_ID 行替代。
• 如果提示要求完整的 fixture，请保留最精简的可执行结构：specification、model、deployment 和 views。

关系扩展匹配器

• 关系身份通过 源 + 目标 + 类型（必要时加标题） 匹配。
• 如果存在带类型的关系，在严格消歧提示中省略 KIND 是错误的。
• 如果多个关系具有相同的源／目标／类型，则在匹配器中加入标题。
• 当提示要求精确识别关系身份时，不要将带类型的匹配器“简化”为 extend SOURCE -> TARGET ...。

带类型的备选项共存时的判断依据：

// Existing relationships
api -[async]-> queue "publishes"
api -[sync]-> queue "publishes"

// ✅ Correct: exact relationship selected
extend api -[async]-> queue "publishes" { metadata { retries "3" } }

// ⚠️ Ambiguous: kind omitted, async vs sync both match source/target/title family
extend api -> queue "publishes" { metadata { retries "3" } }

// ❌ Wrong: selects the other relationship
extend api -[sync]-> queue "publishes" { metadata { retries "3" } }

简明的歧义判定规则：

• 有歧义 —— 省略了类型，且多个带类型的关系具有相同的源／目标／标题系列，而你只是在解释匹配器为何指定不足。
• 错误 —— 任务要求为特定的异步／同步关系提供最终匹配器／代码片段，却省略了类型。

工作流

1. （必需）查找现有项目配置或创建新配置（见下文对应章节）。包含项目配置的目录定义了该目录及其子目录中所有 LikeC4 文件的作用域。如果不确定作用域，请询问用户。
2. （必需）查找现有的 specification { ... } 或创建一个，它决定了你可以使用哪些类型的元素／部署／关系／标签。参见下文的规范章节。
3. 架构元素和关系定义在 model { ... } 块中。参见下文的模型章节。
4. 部署拓扑定义在 deployment { ... } 块中。参见下文的部署章节。
5. 视图（图表）定义在 views { ... } 块中。参见下文的视图章节。
6. 编辑 LikeC4 文件后，使用 CLI 进行验证。

生成 → 自检 → 完成

对于严格的命令／代码片段提示，请使用简洁的循环：

1. 生成仅包含所请求的最终命令／代码片段。
2. 快速自检：

• 命令系列是否准确／必需标志／重复的 --file 数量
• 是否满足代码片段优先或首行约定
• 谓词语义（*、_、**）是否准确说明
• 作用域／FQN 是否正确
• 是否满足部署命名要求
• 关系匹配器是否足够具体（必要时包含 kind、title）
• 动态视图是否精确：返回箭头、链式形式、按要求使用单个并行块、流程控制块的位置（alt 分支、不得嵌套 parallel、try/catch/finally 顺序）

3. 完成时就地修正（除非明确要求，否则不要提供其他备选方案）。

最终回答前，如果提示依赖特定词元，请确认它们按原样出现（例如：--no-layout、instanceOf、variant sequence、global predicate、-[async]->、parallel {、alt {、when、try {、<-）。

除非确实运行过 CLI，否则绝不要声称运行过 CLI。

验证

<runtime> likec4 validate --json --no-layout --file <edited-file> <project-dir>

此命令系列中的运行时启动器等效：

npx likec4 validate --json --no-layout --file <edited-file> <project-dir>
bunx likec4 validate --json --no-layout --file <edited-file> <project-dir>
pnpm dlx likec4 validate --json --no-layout --file <edited-file> <project-dir>

• --json — 输出结构化结果（stdout），日志写入 stderr
• --no-layout — 跳过布局漂移检查（更快，仅进行语法和语义检查）
• --file <path> — 与 --json 搭配使用，将结果限定为已编辑的文件。不使用 --json 时，文本输出仍会显示所有诊断信息。每个已编辑的源文件重复指定一次。
• <project-dir> — 项目目录的路径
• 没有 likec4 check 命令；请使用 likec4 validate。

对于评测／评分／执行，请确保兼容不同的运行器（npx/bunx/pnpm dlx），并根据子命令、标志和项目范围判断正确性。

如果工作区已将 likec4 作为依赖项，请从 package.json 检查其版本，并确保版本不低于 1.53.0。如果需要固定版本，请使用当前运行器（npx/bunx/pnpm dlx）指定 [email protected]。

输出示例：

{
  "valid": false,
  "errors": [
    {
      "message": "...",
      "file": "/abs/path.c4",
      "line": 5,
      "range": { "start": { "line": 5, "character": 2 }, "end": { "line": 5, "character": 20 } }
    }
  ],
  "stats": {
    "totalFiles": 100, // Total number of files in the project
    "totalErrors": 500, // Total number of errors in the project
    "filteredFiles": 1, // Number of files that match the --file filter
    "filteredErrors": 1 // Number of errors in the filtered files
  }
}

大型项目中的规范／模型若存在问题，可能会导致大量错误波及所有文件。请始终使用 --file 将检查范围限定为你编辑的文件。如果 filteredErrors 为 0，但 totalErrors 很高，则说明你的文件没有问题，但项目中的其他部分存在错误（这不是你的问题）。请自行检查 filteredFiles 是否与通过 --file 传入的文件数一致。

字段语义（回答中必须明确说明）：

• filteredFiles：通过重复使用 --file 筛选器实际纳入的文件数
• filteredErrors：仅筛选子集中的错误数
• totalErrors：整个项目模型中的错误数

边缘情况示例：如果传入 3 个文件，但其中一个是 likec4.config.json，则 filteredFiles 可能为 2，因为配置 JSON 不是用于 DSL 验证的 .c4/.likec4 源文件。

导出 PNG 标志（精确性）

规范输出目录标志：

• --outdir（长格式）
• -o（短格式）

不要臆造 --out-dir 之类的标志。根据 LikeC4 版本不同，--output 可能会作为兼容别名出现；为确保答案一致，请优先使用 --outdir/-o。

完整 CLI 参考 → references/cli.md

高差异语法系列的规范代码片段

如果提示要求测试语法，而非宽泛解释，请将这些代码片段作为精确性基准。

可复用的 predicateGroup 谓词

global {
  predicateGroup core-services {
    include cloud.* where kind is service
    exclude * where tag is #deprecated
  }
}

views {
  view service-overview {
    global predicate core-services
  }
}

带命名实例的部署样例

deployment {
  vm appVm {
    primary = instanceOf cloud.api
    secondary = instanceOf cloud.api
  }
}

范围限定的 include 语义

views {
  view backend of cloud.backend {
    include *
    include -> cloud.backend
  }
}

解释基准：在范围限定的视图中，include * 表示将范围限定的元素及其直接子元素作为基础包含集合；邻接元素仍可通过范围限定的关系可见性显示。

元数据谓词

include * where metadata.region is "eu"
include * where metadata.regions is "eu"
exclude * where not metadata.owner
exclude * -> * where metadata.protocol is "http"
exclude * -> * where target.metadata.zone is "restricted"

判断要点：

• 数组包含：如果数组包含 "eu"，则 metadata.regions is "eu" 匹配。
• 范围：未限定的 metadata.* 筛选匹配的元素或关系本身；source.metadata.* / target.metadata.* 筛选端点。
• 部署视图：实例标签会累积；如果存在实例元数据，则其会整体替代逻辑元数据，否则回退到逻辑元数据。

部署视图样式防护规则

对于有关部署视图的严格修复提示，安全的答案是在部署视图内部使用本地 style ... {}。

需求	优先使用	避免作为答案
为一个部署视图设置样式	deployment view prod { include prod.** style prod._ { color primary } }	deployment view prod { include prod.** with { color primary } }
在部署视图修复中复用样式	在该部署视图中使用本地 style ... {} 规则	global style theme

小提示：在部署视图中，将 include ... with {} 和 global style ... 视为不受支持的修复模式。改为在部署视图内部使用本地 style ... {} 规则。

LikeC4 项目配置

配置文件（likec4.config.json、.likec4rc 或 likec4.config.{ts,js}）定义一个项目。其所在位置决定项目范围（LikeC4 文件属于目录层级中最近的配置文件所定义的项目）。

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "my-project",
  "title": "Project Title"
}

关键选项：name（必填，在工作区中唯一的 ID）、title（显示名称） 完整参考 → references/configuration.md

规范

定义所有命名词汇：元素种类、部署节点种类、关系种类、标签和自定义颜色令牌。必须在这些种类用于 model 或 deployment 块之前出现。

关键提示：所有定义在各文件之间全局生效；重复的种类或标签标识符会导致验证错误；规范变更会触发整个项目重新解析——请将其放在专用的 spec.c4 文件中。

完整语法、各类的选项和示例 → references/specification.md

模型

元素和关系的分层结构。元素具有一种种类（来自规范）、在其父级范围内唯一的标识符，以及可选属性和嵌套元素。

关键提示：this/it 是嵌套关系中当前元素的别名；跨文件引用必须使用完整 FQN；禁止父子元素之间的直接关系；extend FQN { } 会将标签、元数据和链接合并到现有元素中，而不重新定义该元素。

完整语法、扩展模式、属性表和示例 → references/model.md

样式

样式属性用于控制视觉外观：color、shape、border、opacity、size、padding、textSize、sizing、icon、iconColor、iconSize、iconPosition、multiple。sizing fixed 会以相同的宽度和高度绘制所有具有相同 size 的元素（内容会缩小以适应）；默认的 auto 会将 size 视为最小值。关系样式还支持 line、head 和 tail 箭头形状。

完整颜色令牌表、所有形状值、边框/不透明度/尺寸令牌、图标包前缀（aws:、azure:、gcp:、tech:、bootstrap:）以及正确用法模式 → references/style-tokens-colors.md

要发现可用图标，请使用 CLI：likec4 list-icons（文本，每行一个）。使用 --group <name> 按分组筛选。图标分组及大致数量：aws（约 307 个）、azure（约 614 个）、gcp（约 216 个）、tech（约 2000 个）、bootstrap（约 2051 个）（详情参见 references/cli.md）。

部署

使用 instanceOf 将逻辑模型元素映射到物理基础设施节点。使用规范中的 deploymentNode 种类。自动继承所有逻辑模型关系；也可以内联定义额外的部署级关系。

命名与匿名实例、多环境固定示例、部署关系和部署筛选器元数据规则 → references/deployment.md

视图

三种视图类型：元素视图（view id 或 view id of element）、动态视图（dynamic view id）、部署视图（deployment view id）。视图属性：title、description、metadata、link。

包含/排除谓词、视图级样式规则、分组、autoLayout、extends、navigateTo 和全局谓词组 → references/views.md

快速决策树

“我需要入向关系谓词”

Need inbound relation selection?
├─ From any source to target element → `include -> target`
├─ From explicit wildcard source     → `include * -> target`
└─ Include both directions around X  → `include -> X ->`

include -> X 和 include * -> X 相关，但在所有上下文中不可互换；优先使用用户/评估要求的确切形式。

作用域谓词真值卡（*、_、**）

选择器	一句话说明	典型用途
parent.*	仅包含 parent 的直接子级	展示直接结构
parent._	包含与累积结果存在关系的 parent 直接子级	仅保留有关联的直接子级
parent.**	包含与累积结果存在关系的 parent 递归后代	探索有关联的深层后代

硬性规则：不要将 * 描述为递归；不要将 _ 描述为通配符匹配全部；不要省略 _ / ** 的关系条件语义。

“我需要创建图表/视图，或展示流程或序列”

What kind of diagram?
├─ Interaction flow / sequence → Dynamic View
├─ Infrastructure / deployment → Deployment View
├─ From architecture model → Element View
│   ├─ Primary element known → Scoped view: `view name of element { ... }`
│   └─ Extend existing view → `view name extends other { ... }`
└─ Other → `view name { ... }`

“我需要设置……的样式”

Styling?
├─ Style element(s) in a view → view `style` rule, see `references/views.md`
├─ Style element(s) in some views, but not all
│   ├─ views in same file → local view rule, see `references/views.md`
│   └─ views in different files → global view rule, see `references/views.md`
├─ Style element globally → property inside element definition, see Model section
├─ Style all elements of a kind → property inside kind specification, see Specification section
├─ Style by tag → view rule, see `references/views.md`
├─ Style relationship(s) in a view → view rule, see `references/views.md`
├─ Style relationship globally → property inside relationship definition, see Model section
├─ Style all relationships of a kind → property inside kind specification, see Specification section
├─ Reuse same styles across views → see `references/views.md`

“我需要跨文件组织内容”

Multi-file project?
├─ Import from another project → import { backend } from 'shared-project' (project name, not a file path)
├─ Cross-file lookup → short names do not inherit lexical/container scope across files; use full FQN
├─ Extend element → extend cloud.backend { service newSvc "New" }
├─ Extend relationship → extend cloud -> amazon { metadata { ... } }
├─ Metadata merge → Duplicate keys become arrays
├─ Organize views → views "Use Cases" { ... } (folder label)
└─ All blocks are mergeable across files

“我需要展示流程或序列”

Flow / sequence diagram?
├─ Basic steps → source -> target "title"
├─ Response / backward → source <- target "returns"
├─ Parallel actions → one `parallel { ... }` block (also: `par { ... }`)
├─ Optional / repeated steps → `opt { ... }` / `loop { ... }` (optional title each)
├─ Mutually exclusive branches → `alt { when '...' { } else '...' { } }`
├─ Success + error handling → `try { } catch { } finally { }`
├─ Chained steps → customer -> frontend "x" -> backend "y"
├─ Step with notes → step { notes 'Markdown content' }
├─ Link to another view → step { navigateTo other-view }
├─ Sequence variant → dynamic view name { variant sequence }
└─ Full reference → references/dynamic-views.md

流程控制块（实验性）——均可使用可选标题，并可任意深度嵌套，但 parallel/par 不能嵌套。when/if/else 只能直接放在 alt 内；loop/opt/parallel/try 不能作为 alt 的直接子级（将它们嵌套在某个分支中）。请参阅 references/dynamic-views.md。

返回箭头精确性：

• 如果提示要求响应箭头返回，优先使用 <- 步骤，而不是替换为新的正向箭头。
• 如果提示要求在链中的特定跳转上添加主体块，只将该块附加到该跳转。
• 如果提示要求单次扇出，将同级操作放在一个 parallel { ... } 块中，而不是使用多个只有一步的并行块。

严格提示中应避免的反模式

反模式	失败原因	正确做法
用命令族（check/build）替代 validate	破坏精确的命令约定	保留 likec4 validate
臆造/猜测标志	会产生不可移植的无效命令	仅使用规范文档中记载的标志
对一个严格要求提供多个备选代码片段	降低精确度；无法通过严格输出评分	除非要求提供备选方案，否则只输出一个最终答案
在含糊图中扩展类型化关系，但未指定类型/标题	可能会指向错误的关系	使用来源 + 目标 + 类型（必要时加上标题）进行匹配

常见错误与调试

当模型报错或评估答案似乎有误时，加载包含以下内容的 references/troubleshooting.md：

• 语法错误 — 标识符格式（标识符中禁止使用点）、未知类型、FQN 重复、where 谓词格式错误
• 模型与层级结构 — FQN 引用错误、父子关系约束、跨文件可见性
• 视图谓词 — 混淆 * 与 **、缺少相邻元素、WHERE 区分大小写
• 部署 — instanceOf FQN 解析、未定义的 deploymentNode 类型
• 动态视图 — 流程控制块（parallel/opt/loop/alt/try）、alt 分支放置规则、禁止嵌套 parallel、响应箭头对称性、精确的 variant sequence 关键字
• 验证与导入 — 未找到配置、导入路径解析、上游错误级联
• 性能 — 将规范放在单独的文件中、拆分大型视图
• 5 步调试工作流 — 优先验证并使用 --file、FQN 完整性、隔离谓词、优先验证规范
• 7 项 Skill 最佳实践 — 响应规范、关系消歧、FQN 使用、安全编辑规则

参考索引

当任务涉及相应主题时，加载参考文件。Claude 会先读取 SKILL.md；仅在需要时按需加载这些文件。

文件	用途 — 在以下情况下加载...
references/specification.md	编写/编辑 specification { } 块，定义 element/deploymentNode/relationship/tag/color 类型
references/model.md	编写/编辑 model { } 块、元素层级、关系、extend 模式、属性名称
references/deployment.md	编写/编辑 deployment { } 块、instanceOf、命名实例、多环境拓扑、部署元数据筛选
references/style-tokens-colors.md	应用颜色、形状、图标或关系线样式；需要准确的标记名称
references/views.md	编写视图、包含/排除规则、视图中的样式规则、组、autoLayout、全局谓词
references/predicates.md	复杂的 where 条件、元数据筛选、with 覆盖、全局谓词组、可复用谓词
references/include-predicates-wildcards.md	怀疑对通配符存在混淆（* 与 _ 与 **）；需要准确了解作用域视图语义
references/dynamic-views.md	编写动态视图：步骤、返回箭头、链式步骤、流程控制块（parallel/opt/loop/alt/try）、variant sequence
references/identifier-validity.md	混淆标识符与 FQN；出现“名称中包含点”的错误；了解 FQN 的构造方式
references/relationships-bidirectional.md	双向关系语法和 <-> 视图谓词模式
references/diffs.md	计划中的模型变更（diff 块）、应用或丢弃变更、安全删除元素
references/bridge-leanix-drawio.md	LeanIX 桥接 · drawio --profile leanix · 往返 · 映射 · MCP 与桥接 · 同步/制品/受管理单元
references/cli.md	完整 CLI 参考：serve、build、export、codegen、mcp、format；标志消歧
references/configuration.md	项目配置选项、多项目设置、包含/排除路径、生成器
references/examples.md	精简的真实示例：extend、组、全局项、动态视图、部署、rank
references/troubleshooting.md	错误、意外输出、评估失败 — 6 个错误表、5 步调试工作流、7 项最佳实践