每天一个开源项目#47 4.4K Stars 的 LikeC4：让架构图随代码进化

每天一个开源项目#47 4.4K Stars 的 LikeC4：让架构图随代码进化

GitHub Trending 第 5 名 ｜快照日期：2026-07-23｜Stars：4,461 ｜Forks：307 ｜主语言：TypeScript ｜License：MIT

项目地址：github.com/likec4/like...

数据口径：Trending 排名来自当日脚本快照；Stars、Forks、版本和社区指标来自 2026-07-23 同日 GitHub/NPM API 补充核验。脚本未保留"今日新增 Stars"，本文不会用排名反推日增量。

📋 项目概览

项目	内容
项目名	LikeC4（likec4/likec4）
一句话定位	用可版本化 DSL 描述软件架构，并持续生成与模型同步的交互式架构图
Trending 排名	第 5 名（19 个仓库）
Stars / Forks	4,461 / 307
主语言	TypeScript 97.49%（GitHub Languages API）
License	MIT
最新版本	v1.59.2（2026-07-22 发布）
当前审计提交	f9700621c2bd8cc6c002d54b813a4d251e3f7bd8
主要入口	CLI、VS Code、Vite/React、静态站点、MCP Server
官网	likec4.dev

LikeC4 不是"再画一张图"的在线白板，而是把架构事实从图片搬回代码仓库：系统、组件、关系、部署节点和视图都写进 .c4 文件，接受 Git 的版本控制、代码评审和 CI 校验，再由工具链生成可浏览、可嵌入、可导出的图。

本次没有机械选择脚本预抓取的第 3 名 i-have-adhd。后者是一个约束 Agent 输出风格的轻量技能，实用但产品层主要是规则文本；LikeC4 则同时包含 DSL、语言服务器、语义模型、图布局、交互式渲染、代码生成与 MCP 查询，技术纵深和团队级价值更高。榜首 WorldMonitor 与第 2 名 RuView 也已在历史报告中分析过，因此第 5 名是兼顾技术含量与去重后的更优选择。

🔥 为什么值得关注

软件架构文档最大的敌人不是"画得不好"，而是画完即过期。传统流程中，架构师在 Draw.io、Visio 或 PPT 里维护一份图，开发者在代码里维护另一份真实系统；两者没有同一套变更机制。LikeC4 的价值，是把架构从一次性展示物变成工程资产：架构变化可以提交 PR、查看 diff、做语义和布局校验，并随版本一起发布。

它也没有把 C4 模型做成僵硬模板。README 明确说明项目受 C4 Model 与 Structurizr DSL 启发，但允许团队定义自己的元素类型、关系类型、图例和任意嵌套层级。这意味着它既能表达经典的 System / Container / Component，也能适配"业务域---服务---模块---数据表""App---SDK---能力---接口"等组织内部语言。

更值得注意的是，LikeC4 已经越过"DSL + 图片生成器"的早期阶段。它提供语言服务器、VS Code 实时预览、静态站点、React/Vite 集成、多格式导入导出，以及可让 AI Agent 查询架构图谱的 MCP Server。架构模型因此不仅供人阅读，也能成为机器可查询的上下文边界。

🏗️ 核心特性

1. 模型与视图分离：同一份事实生成多张图

模型层描述"系统里有什么、彼此如何关联"，视图层决定"这次给谁看、展示到哪一层"。最小示例：

specification {
  element person
  element system
}

model {
  user = person 'Mobile User'
  app = system 'Android App'
  api = system 'Backend API'

  user -> app 'uses'
  app -> api 'HTTPS / JSON'
}

views {
  view index {
    include *
  }
}

这种分离避免复制关系：面向管理层可以只保留系统级依赖，面向研发可以展开到组件和接口，部署视图则映射到环境与节点，但底层元素仍来自同一个模型。

2. 自定义架构语言，而不是被固定层级绑住

LikeC4 的 Langium 语法文件达到 1,254 行，入口规则覆盖：

1. specification：元素、关系、标签、颜色和部署节点类型；
2. model：层级元素与关系；
3. views：静态元素视图、动态视图、部署视图；
4. deployment：部署节点与实例；
5. import：跨项目引入模型元素。

语法允许团队把领域术语变成一等公民，例如定义 boundedContext、androidModule、api，而不是被迫把所有内容压进预设的四层结构。

3. 交互式预览、热更新与多格式交付

CLI 会递归发现 .c4 / .likec4 文件，解析后启动本地预览；源码变化会触发浏览器热更新。需要交付时，可输出静态网站或生成多种格式：

npx likec4 start
npx likec4 build -o ./dist
npx likec4 export png -o ./assets
npx likec4 codegen mermaid
npx likec4 codegen dot
npx likec4 codegen d2
npx likec4 codegen plantuml
npx likec4 export drawio -o ./diagrams

PNG 导出内部会启动本地服务并通过 Playwright 截图；这不是简单拼 SVG。Draw.io 支持双向路径：既可把 LikeC4 视图导出给现有协作流程，也能将存量 .drawio 转换为 .c4，降低迁移门槛。

4. 从编辑器到应用：同一模型覆盖多个消费端

LikeC4 的主包并非单体 CLI，而是语言服务、React 组件、Vite 插件与命令行的组合。典型嵌入方式如下：

// vite.config.ts
import react from '@vitejs/plugin-react'
import { LikeC4VitePlugin } from 'likec4/vite-plugin'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [react(), LikeC4VitePlugin()],
})

import { LikeC4View } from 'likec4:react'

export function Architecture() {
  return <LikeC4View viewId="index" />
}

这使架构图能进入研发门户、组件文档站或内部治理平台，而不是停留在某位架构师电脑上的文件里。

5. MCP 把架构模型变成 Agent 可查询图谱

@likec4/mcp 暴露的不只是"打开图片"，而是解析后的结构化模型。当前 README 列出 18 个工具，包括：

• 按 ID、标题、类型、标签和元数据搜索元素；
• 读取元素的入边、出边、部署实例和所在视图；
• 查询祖先、后代、兄弟节点及上下游完整图；
• 通过有界 BFS 查找两个元素之间的关系路径；
• 批量读取元素、生成子图摘要、比较元素差异。

因此 Coding Agent 可以先问"修改支付 API 会影响哪些消费者"，再读取相关代码，而不是把整个仓库和一堆截图都塞进上下文。不过要注意：MCP 提供的是模型查询能力，模型是否与真实代码同步仍依赖团队维护和 CI 治理，它不是自动从任意代码恢复完美架构的魔法。

🔬 技术架构深度解析

1. 端到端流水线

.c4 / .likec4 源文件
        │
        ▼
Langium Grammar + Language Server
语法解析 / 作用域 / 引用解析 / 诊断 / 补全
        │
        ▼
Parsed Model
元素、关系、部署节点、标签、元数据、视图规则
        │
        ▼
Computed Model / View Computation
层级展开、include/exclude、隐式关系、动态流程
        │
        ├──────────────► MCP 图查询 / SDK 遍历
        │
        ▼
Layout Layer
Graphviz WASM（默认）或本机 Graphviz binary
静态图布局 + 独立的 sequence layout
        │
        ▼
Diagram Model
节点坐标、边路径、样式、导航与源码位置
        │
        ├──► React / VS Code / Playground / SPA
        ├──► Vite Plugin / 代码生成
        └──► PNG / JSON / Mermaid / DOT / D2 / PlantUML / Draw.io

2. 解析层：真正的"产品内核"是语义模型

packages/language-server/src/like-c4.langium 定义 DSL 语法，语言服务器负责引用解析、作用域和诊断；packages/core 则提供模型类型、Builder、视图计算、图遍历和几何工具。源码中的 API 可以直接从工作区或字符串初始化：

import { LikeC4 } from 'likec4'

const likec4 = await LikeC4.fromWorkspace('./architecture')
const model = likec4.model()

const consumers = model
  .element('cloud.backend.api')
  .incoming()
  .filter(r => r.tags.includes('http'))
  .map(r => r.source)

这说明 LikeC4 的核心不是"把文本转成图片"，而是先建立可遍历、可验证的架构图，再把不同视图投影出来。MCP、代码生成和编辑器能力都复用这层结构化模型。

3. 布局层：Graphviz 是默认引擎，但不是外部强依赖

@likec4/layouts 同时依赖 @hpcc-js/wasm-graphviz 和 Graphviz binary 适配器。语言服务默认选择 WASM：

createLanguageServices
  └─ graphviz = "wasm"（默认）
       ├─ GraphvizWasmAdapter：跨平台、开箱即用
       └─ GraphvizBinaryAdapter：显式选择本机 dot

布局包还维护 Element、Dynamic、Deployment 三类 DOT Printer，并为时序视图提供独立 layouter。这样既利用成熟图布局算法，又把模型计算、布局和渲染解耦。代价是大型模型的自动布局仍可能产生"语义正确但视觉不理想"的结果，所以项目的 validate 命令还加入 layout drift 校验，而不是只查语法。

4. 渲染与分发层：Monorepo 而非单一 npm 包

在审计提交 f970062 上，确定性源码统计如下：

指标	结果	说明
工作区 packages	20	core、language-server、layouts、diagram、mcp、vscode、react 等
应用	2	docs、playground
TypeScript / TSX 文件	6,626	不含 node_modules 与 .git
TypeScript / TSX 文本行	348,438	物理行，不等于有效代码行
.c4 示例/fixture 文件	80	共 11,078 行
测试命名文件	344	按文件名含 test/spec 的启发式统计
GitHub 语言占比	TypeScript 97.49%	其次 MDX 1.36%、Astro 0.44%

根目录使用 pnpm + Turborepo，提供 build、typecheck、lint、Vitest 单测和 Playwright E2E 脚本。这些是可执行质量门，而不是 README 中的口头承诺。

5. 工程边界与风险

风险	具体表现	建议
模型漂移	DSL 与真实实现由人分别修改	将 likec4 validate、生成物检查纳入 CI，并在架构变更 PR 中强制更新模型
自动布局不稳定	元素/关系变化可能引起大范围位置变化	拆小视图、固定语义边界，启用布局漂移检查，不把一张图塞进全公司系统
版本兼容信息漂移	包 README 写 Node 20+，当前根源码要求 Node >=22.22.3	对 v1.59.2 和当前仓库开发环境优先使用 Node 22.22.3
AI 误读架构	MCP 返回的是模型事实，不是运行时事实	让 Agent 同时核对代码、配置与部署数据，不把 DSL 当唯一真相
输出体积	交互式静态站包含完整前端运行时	文档站用静态构建；只需图片时使用 PNG/SVG/其他代码生成路径

📖 README 核心内容摘要

README 的设计哲学可以归纳为四句话：

1. Architecture as Code：架构源文件与业务代码一起版本化；
2. Inspired by C4, not constrained by C4：借鉴 C4 与 Structurizr，但允许自定义表示法与无限嵌套；
3. Live diagrams：编辑时实时反馈，而不是手工重新导图；
4. One model, many outputs：同一模型服务于预览、静态站点、React、VS Code、代码生成和 MCP。

README 给出的主路径非常短：安装或直接使用 npx likec4 start，工具递归查找模型文件并启动本地服务。更完整的 CLI 则覆盖：

能力	命令/集成	适合场景
本地预览	likec4 serve/start/dev	编写模型时实时检查
静态发布	likec4 build	GitHub Pages、Netlify、内部文档站
图片导出	likec4 export png	方案评审、PPT、离线文档
代码格式	Mermaid、DOT、D2、PlantUML	接入既有文档工具链
Draw.io	import / export	迁移存量图、与非研发角色协作
应用嵌入	Vite Plugin + React	研发门户、服务目录、治理平台
Agent 查询	MCP stdio / HTTP	影响分析、上下游检索、架构问答

v1.59.0 还加入了动态视图流程控制：opt、loop、break、alt/when/else、try/catch/finally 等块可以渲染为嵌套时序框架；v1.59.2 则修复跨项目动态视图引用、元数据关键字兼容及 MCP 运行时依赖发布问题。这说明项目正在把"静态 C4 图"扩展成更完整的交互与行为建模工具。

🚀 快速上手指南

1. 准备环境

当前审计环境使用 Node.js v22.22.3、npm 10.9.8，并成功执行 LikeC4 v1.59.2。推荐直接使用 Node 22.22.3 或更高版本：

mkdir architecture-demo
cd architecture-demo
npm install --save-dev likec4@1.59.2

2. 创建 model.c4

specification {
  element person
  element system
}

model {
  customer = person 'Customer'
  mobile = system 'Mobile App'
  backend = system 'Backend'

  customer -> mobile 'uses'
  mobile -> backend 'HTTPS'
}

views {
  view index {
    include *
  }
}

3. 验证并预览

npx likec4 validate . --json
npx likec4 start

本次实测的验证结果：

{
  "valid": true,
  "errors": [],
  "stats": {
    "totalFiles": 1,
    "totalErrors": 0,
    "filteredFiles": 1,
    "filteredErrors": 0
  }
}

4. 构建静态站点

npx likec4 build . -o ./dist

在同一台机器的冷启动烟雾测试中，Graphviz WASM 完成布局，Vite 主构建耗时约 636 ms ，生成 dist/index.html 及配套资源。这个数字只证明最小样例链路可用，不是项目官方性能基准，也不能外推到大型企业模型。

5. 接入 AI Agent（可选）

{
  "mcpServers": {
    "likec4": {
      "command": "npx",
      "args": ["-y", "@likec4/mcp"],
      "env": {
        "LIKEC4_WORKSPACE": "${workspaceFolder}"
      }
    }
  }
}

如果模型是稳定快照，可给 MCP CLI 加 --no-watch 降低文件监听资源占用；需要编辑器联动时保留默认监听。

📊 增长速度与社区热度

1. 核心社区指标

指标	数据	解读
Stars	4,461	中等规模但目标用户高度专业
Forks	307	Star/Fork 比约 14.5，存在真实二次开发需求
GitHub open items	166	API 口径包含 Issues 与 Pull Requests，不能直接视为 166 个缺陷
Watchers	25	主动订阅规模较小，符合开发工具型项目特征
Contributors	52	GitHub Contributors API 三页合计；其中 48 个非 Bot 类型
Releases	182	从 2023-05 的 v0.8.0 到 2026-07 的 v1.59.2
近 30 天提交	118	其中 108 个非 merge commit，9 位作者
NPM 最近 7 天下载	39,233	统计区间 2026-07-15 至 2026-07-21
NPM 最近 30 天下载	134,480	统计区间 2026-06-22 至 2026-07-21

项目创建于 2023-03-24，截至快照约 1,216.6 天。用 4,461 Stars 除以仓库年龄，生命周期基线约为 3.67 Stars/天 。这只能表示长期平均，不能描述当前 Trending 爆发速度；由于脚本没有保留"今日新增 Stars"，本文明确把日增量标记为不可得。

维护活跃度比单纯 Star 更有说服力：v1.59.0、v1.59.1、v1.59.2 分别在 7 月 19、20、22 日发布，四天内连续三个正式版本；近 30 天 118 次提交也表明它不是靠旧积累偶然返榜。另一方面，贡献高度集中：核心作者 davydkov 的 GitHub API 贡献计数为 4,115，显著高于第二位人类贡献者。团队采用时应关注维护者集中度和升级节奏。

2. 今日 Trending 完整榜单

排名	仓库	技术方向
1	koala73/worldmonitor	实时全球情报与多源态势监控
2	ruvnet/RuView	基于 WiFi 信号的空间感知与生命体征监测
3	ayghri/i-have-adhd	面向 Coding Agent 的简洁输出规则
4	schollz/croc	基于中继与口令的安全跨设备文件传输
5	likec4/likec4	Architecture-as-Code 与实时架构图
6	chrislgarry/Apollo-11	阿波罗 11 号制导计算机汇编源码
7	jamiepine/voicebox	开源 AI 语音克隆与创作工作室
8	diegosouzapw/OmniRoute	多模型 AI Gateway 与额度感知路由
9	shiyu-coder/Kronos	金融市场时序基础模型
10	ComposioHQ/awesome-claude-skills	Claude Skills 资源合集
11	oblien/openship	自托管应用部署平台
12	agegr/pi-web	Pi Coding Agent Web UI
13	rohitg00/ai-engineering-from-scratch	AI Engineering 教程与示例
14	tirth8205/code-review-graph	本地优先的代码知识图谱与 MCP
15	dreamhunter2333/cloudflare_temp_email	Cloudflare 临时域名邮箱系统
16	DioxusLabs/dioxus	Rust 全栈 Web、桌面与移动框架
17	hyprwm/Hyprland	动态平铺 Wayland 合成器
18	Pumpkin-MC/Pumpkin	Rust 高性能 Minecraft 服务器
19	dottxt-ai/outlines	LLM 结构化输出约束框架

榜单中不乏 Star 更高的项目，但 LikeC4 的优势是它击中了"架构知识无法跟随代码演进"这一长期工程问题，并形成了从 DSL 到语言服务、布局、渲染、发布和 Agent 查询的闭环，不是薄封装或资料合集。

🎯 适用场景

场景	为什么适合	落地建议
微服务依赖治理	关系可检索，可按视图过滤上下游	先从核心域和跨服务 API 开始，避免一次建模全部系统
Android 模块化架构	可表达 App、Feature、Core、SDK、Backend 依赖	自定义 androidModule、sdk、api 元素类型，并在 PR 校验
架构评审与 ADR	图与源码同仓、变更可 diff	将模型修改与 ADR、实现 PR 绑定
内部研发门户	Vite/React 可直接嵌入交互图	静态构建发布，按团队或业务域拆分视图
AI Coding Agent 上下文	MCP 能按关系查询局部子图	只把命中的元素和上下游交给 Agent，减少无关上下文
Draw.io 存量迁移	支持导入和再导出	先做小范围转换并人工核对语义，别把视觉布局等同于结构模型
CI 架构治理	validate 可检查语法、语义和布局漂移	固定版本，失败阻断合并，并审核自动生成的大范围布局变化

不适合的情况也很明确：一次性汇报图、完全不愿维护架构模型的小团队，或希望工具自动扫描所有代码并百分之百还原真实架构的场景。LikeC4 提供的是高质量建模与消费基础设施，不替代架构判断本身。

💡 总结

LikeC4 最有价值的地方，不是多支持一种架构图语法，而是把"模型---视图---布局---交付---查询"连成工程流水线。4.4K Stars 不算今日榜单里最耀眼的数字，但 20 个工作区包、18 个 MCP 查询工具、182 个 Release、近月 118 次提交和 13.4 万次 NPM 下载，说明它已经是一套成熟度较高的开发工具链。

如果团队正被过期架构图、微服务依赖不透明或 AI Agent 缺乏系统边界困扰，LikeC4 值得从一个真实业务域试点。最合理的切入点不是先画全景大图，而是选一条关键链路，将 .c4、validate 和 PR 评审跑通，再逐步扩展成可查询的架构知识库。