企业官网建设流程全解析

1. 为什么你的架构图总是“活不过三个月”

如果你维护过微服务项目的架构文档，大概率经历过这个循环：项目启动时花两天画了一张漂亮的架构图，放进 README 或飞书文档；三个月后业务迭代，新增了两个服务、拆掉了一个网关、消息队列从 Kafka 换成了 Pulsar，但架构图还停留在上个版本。新同事入职对着图问了一圈，发现图上的组件有一半在代码里找不到，代码里的模块有一半图上没有。

这个问题的根源不在于“画图工具不够好”，而在于架构图是视觉产物，它和代码之间没有强绑定关系。代码变了，图不会自己变，只能靠人记得去改。而人总是会忘的。

LikeC4 的思路是把架构从“画出来的图片”变成“写出来的模型”。你用一套 DSL 描述系统里有哪些元素、元素之间是什么关系，LikeC4 根据这份模型自动渲染出可交互的架构图。模型文件跟代码一起进 Git，改代码的时候顺手改模型，CI 里跑一条命令就能重新生成图。架构图从“静态文档”变成了“可版本控制的结构化资产”。

再叠加 AI 之后，这件事的杠杆就更大了：你可以让大模型读你的代码结构，直接生成合法的 LikeC4 DSL；也可以把现有模型丢给 AI，让它帮你补全缺失的依赖关系、生成新的视图。本文就围绕“LikeC4 DSL 建模 + AI 生成架构图”这条落地链路，交付一套可复制的项目骨架、TaoToken 统一 Key 的接入配置，以及从 DSL 到可交互架构图的完整验证步骤。

2. TaoToken 前置：把 AI 能力接进你的建模工作流

在讲 LikeC4 的具体配置之前，先把 AI 这一侧的通路打通。因为后面无论是让模型生成 DSL、还是让 Agent 读取架构模型做问答，都需要一个稳定的模型调用入口。

TaoToken 在这里扮演的角色是统一 Key 接入层。你不需要在项目里维护多套不同厂商的 API Key，也不用担心某个模型的接入格式和另一个不一样。通过一个统一的 API 地址和一把 Key，就可以在 LikeC4 的 AI 辅助流程里调用对话模型、代码模型等不同能力。

具体来说，你需要先拿到自己的 API Key。访问 API Keys 管理页面：

https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=likec4_ai_arch

在这个页面里创建一个新的 Key，复制出来保存好。这个 Key 就是你后续在编辑器插件、CLI 工具、Agent 脚本里统一使用的凭证。

如果你更习惯用命令行工具来管理，也可以直接走 API 端点：

https://taotoken.net/api

注意这个地址是 API 的基础端点，不带 UTM 参数，适合直接写进配置文件或环境变量。而上面那个带 UTM 的链接是给人工点击用的，方便你从文档跳转到控制台。

拿到 Key 之后，建议先把它写进环境变量，而不是硬编码在项目文件里：

export TAOTOKEN_API_KEY="sk-你的实际Key"

这样后续无论是 settings.json 还是脚本里引用，都可以用${TAOTOKEN_API_KEY}的方式读取，避免 Key 泄露到 Git 仓库。

3. 可复制配置：LikeC4 项目骨架 + AI 工具 settings.json

这一节直接给可复制的内容。先建 LikeC4 项目骨架，再配 AI 工具的接入参数。

3.1 LikeC4 项目初始化

前置要求是 Node 20 以上。在你的项目根目录下执行：

npm install --save-dev likec4

安装完成后，创建 LikeC4 的配置文件likec4.config.json：

{ "name": "my-architecture", "title": "订单中台架构模型", "projects": [ { "id": "order-platform", "title": "订单中台" } ] }

然后创建模型文件model.likec4。这里给一个微服务场景的骨架，你可以直接复制后按自己的业务改：

specification { element actor element system element component element database element queue relationship async relationship sync } model { user = actor '用户' gateway = system 'API 网关' orderService = component '订单服务' payService = component '支付服务' orderDB = database '订单库' payQueue = queue '支付消息队列' user -> gateway 'HTTPS' gateway -> orderService 'REST' gateway -> payService 'REST' orderService -> orderDB '读写' orderService -> payQueue '发送支付事件' async payService -> payQueue '消费支付事件' async } views { view context { title '系统上下文' include * } view container { title '容器视图' include gateway, orderService, payService, orderDB, payQueue } }

保存后运行本地预览：

npx likec4 start

浏览器会自动打开一个本地地址，你就能看到根据 DSL 渲染出来的可交互架构图。点击元素可以高亮关联关系，切换视图可以看到不同层级的结构。

3.2 AI 工具接入 TaoToken 的 settings.json

如果你用的是支持自定义模型端点的编辑器插件或 CLI 工具，通常会在项目根目录或用户目录下有一个settings.json。下面是一个接入 TaoToken 统一 Key 的配置片段：

{ "ai.provider": "openai-compatible", "ai.baseUrl": "https://taotoken.net/api", "ai.apiKey": "${TAOTOKEN_API_KEY}", "ai.model": "claude-sonnet-4-20250514", "ai.maxTokens": 8192, "ai.temperature": 0.2, "likec4.aiAssist": { "enabled": true, "contextFile": "https://likec4.dev/llms-full.txt", "autoValidateDsl": true } }

几个关键点说明一下。ai.baseUrl填的是 TaoToken 的 API 基础端点，不带 UTM 参数。ai.apiKey用环境变量引用，不要直接写明文。ai.model这里填的是你实际要调用的模型标识，具体可用模型列表可以在模型对话页面查看：

https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=likec4_ai_arch

likec4.aiAssist.contextFile指向 LikeC4 官方为大模型准备的语义描述文件llms-full.txt。这个文件里包含了 DSL 语法、元素类型、关系语义、示例模型等全部核心信息。把它作为上下文喂给模型，模型生成的 DSL 合法率会高很多，不会出现“看起来像 LikeC4 但跑不起来”的情况。

如果你用的是 Coding Plan 这类长期编码场景，建议把模型调用走 Coding Plan 的通道，稳定性和额度都更适合持续性的代码生成任务：

https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=likec4_ai_arch

3.3 让 AI 生成 DSL 的提示词模板

配置好之后，你可以直接在编辑器里选中一段代码或一段需求描述，让 AI 生成 LikeC4 DSL。下面是一个实测下来比较稳定的提示词模板：

你是一个 LikeC4 DSL 生成助手。请根据以下信息生成合法的 LikeC4 DSL 代码： 1. 参考 LikeC4 官方语义描述：https://likec4.dev/llms-full.txt 2. 业务场景：{这里写你的业务描述} 3. 已知组件：{列出服务名、数据库、队列等} 4. 关系约束：{谁调用谁、同步还是异步} 要求： - 使用 specification 定义元素类型和关系类型 - 在 model 块中定义所有元素和关系 - 在 views 块中至少生成 context 和 container 两个视图 - 输出完整的 .likec4 文件内容，不要省略

把这段提示词和你的业务信息一起发给模型，它输出的 DSL 可以直接保存成.likec4文件，然后跑npx likec4 validate校验语法。

4. 验证请求：从 DSL 到可交互架构图的完整链路

配置写完不算完，得跑通验证。这一节按顺序走一遍从 DSL 校验到架构图生成的完整流程。

4.1 校验 DSL 语法

在项目根目录执行：

npx likec4 validate

如果 DSL 有语法错误，这个命令会直接报出文件和行号。常见的错误包括元素类型未在 specification 中定义、关系引用了不存在的元素、视图 include 了未声明的元素等。修到命令返回成功为止。

4.2 启动本地预览

npx likec4 start

终端会输出一个本地地址，通常是http://localhost:5173。打开后你应该能看到：

• 左侧是视图列表，包含你在 views 块里定义的 context 和 container
• 中间是渲染出来的架构图，元素按类型有不同的颜色和图标
• 点击任意元素，与之相关的关系线会高亮，无关元素会变暗
• 顶部有导出按钮，可以导出 PNG、Mermaid、D2 等格式

如果你在 DSL 里改了内容，保存文件后浏览器会自动刷新，不需要重启服务。

4.3 导出为文档可用的格式

架构图确认无误后，导出成可以嵌入文档的格式：

npx likec4 export png -o assets

这会在assets目录下生成 PNG 图片。如果你要嵌入 Markdown 文档或技术博客，导出 Mermaid 更合适：

npx likec4 export mermaid -o docs

导出的 Mermaid 文件可以直接贴进支持 Mermaid 渲染的文档平台，保持和 DSL 模型同步。

4.4 接入 CI 实现自动更新

把下面这段加到你的 CI 配置里（以 GitHub Actions 为例）：

name: Update Architecture Diagram on: push: paths: - 'model.likec4' - 'likec4.config.json' jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm ci - run: npx likec4 validate - run: npx likec4 export png -o assets - uses: actions/upload-artifact@v4 with: name: architecture-diagram path: assets/

这样每次模型文件变更，CI 会自动校验语法并重新生成架构图。如果校验失败，CI 会直接报错，防止不合法的模型被合并进主分支。

4.5 用 AI 做架构问答验证

如果你想把架构模型变成可问答的知识库，可以结合 Agent 能力做一个简单的 QA 脚本。核心思路是把model.likec4的内容作为上下文，通过 TaoToken 的统一 API 发给模型：

import os import requests api_key = os.environ["TAOTOKEN_API_KEY"] model_content = open("model.likec4", "r", encoding="utf-8").read() response = requests.post( "https://taotoken.net/api/v1/chat/completions", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" }, json={ "model": "claude-sonnet-4-20250514", "messages": [ { "role": "system", "content": "你是一个架构问答助手。根据提供的 LikeC4 模型回答用户问题，不要编造模型中不存在的信息。" }, { "role": "user", "content": f"以下是架构模型：\n{model_content}\n\n问题：订单服务和支付服务之间是怎么通信的？" } ], "temperature": 0.1 } ) print(response.json()["choices"][0]["message"]["content"])

跑通之后，新同事问架构问题，直接让脚本回答，答案来自模型文件本身，不会出现“AI 瞎猜”的情况。

5. 本篇常见错排查

这一节列几个实际落地时容易踩的坑，按报错现象、原因、解决方式来说。

5.1npx likec4 validate报 “Element type not defined”

现象是校验命令输出类似Element type "queue" is not defined in specification的错误。原因是你在 model 块里用了queue类型，但 specification 块里没有声明它。解决方式是在 specification 里补上：

specification { element queue }

LikeC4 要求所有元素类型和关系类型都必须先在 specification 中声明，不能在 model 里直接使用未声明的类型。这是为了保证模型的结构化程度，避免随意定义导致模型不可维护。

5.2 AI 生成的 DSL 跑不起来

模型生成的 DSL 看起来语法没问题，但npx likec4 validate报错。最常见的原因是模型没有严格遵循 LikeC4 的语法规则，比如用了不存在的属性、关系方向写反、视图 include 了未定义的元素。

解决方式有两个。第一，在提示词里明确要求模型参考https://likec4.dev/llms-full.txt，并且要求它输出完整的文件内容而不是片段。第二，在 settings.json 里开启autoValidateDsl，让工具在生成后自动跑一次校验，报错就重新生成。

如果反复生成都不合法，可以把报错信息连同 DSL 一起发回给模型，让它根据报错修正。实测下来，带上报错信息的二次生成成功率会高很多。

5.3 本地预览端口被占用

npx likec4 start默认用 5173 端口，如果这个端口已经被其他项目占用，会启动失败。可以指定端口：

npx likec4 start --port 5174

或者先查一下哪个进程占用了 5173，关掉之后再启动。

5.4 导出的 PNG 里元素重叠

当模型里的元素比较多、关系比较复杂时，自动布局可能会出现元素重叠或连线交叉。LikeC4 的布局引擎会尽量优化，但复杂模型还是需要手动调整。可以在视图里用include和exclude控制显示范围，把大图拆成多个小视图，每个视图只展示一个关注点。比如：

views { view orderFlow { title '订单流程' include orderService, orderDB, payQueue } view payFlow { title '支付流程' include payService, payQueue } }

拆成多个视图后，每个视图的元素数量减少，布局会清晰很多。

5.5 API 调用返回 401

如果你在脚本里调用 TaoToken API 返回 401，先检查三件事。第一，环境变量TAOTOKEN_API_KEY是否真的设置成功了，可以用echo $TAOTOKEN_API_KEY确认。第二，请求头里的Authorization格式是否是Bearer sk-xxx，注意 Bearer 和 Key 之间有一个空格。第三，Key 是否已经过期或被删除，去 API Keys 页面确认一下状态。

如果 401 排除了，但返回 429，说明触发了速率限制。这种情况下可以降低请求频率，或者检查一下是不是在循环里高频调用了 API。

6. 让架构模型成为可查询、可演进的知识资产

走到这一步，你的 LikeC4 项目已经具备了几个关键能力：DSL 模型可版本控制、架构图可自动生成、AI 可以辅助生成和校验 DSL、CI 可以自动更新图。但还有一个值得做的收尾动作：把架构模型变成团队可以随时查询的知识源。

具体做法是把model.likec4和likec4.config.json作为上下文，通过 TaoToken 的统一 API 接入一个轻量的问答入口。新同事入职时不用追着人问“订单服务依赖哪些下游”，直接问问答入口就行，答案来自模型文件本身，不会出现信息偏差。

如果你已经在用 Coding Plan 做日常开发，可以把架构问答也挂到同一个通道下，Key 和额度统一管理，不用在多个平台之间切换。模型对话页面可以快速验证不同模型对 LikeC4 DSL 的理解能力，选一个生成合法率最高的模型固定下来用：

https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=likec4_ai_arch

接入文档里有完整的 API 参数说明和示例代码，如果你要把架构问答集成到内部工具里，可以直接参考：

https://taotoken.net/docs?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=likec4_ai_arch

架构图不再手画的核心，不是换一个更漂亮的画图工具，而是把架构从“视觉产物”变成“结构化模型”。模型在 Git 里，图就能跟着代码走；模型能被 AI 理解，架构就能被查询、被校验、被演进。LikeC4 负责前半段，TaoToken 统一 Key 负责后半段的 AI 接入，两者接起来，架构图才算真正“活”了。