Acme Platform【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4ContextHow the system fits its surroundings.可见 Mermaid 内容带有 title frontmatter实体与关系均以 graph TB 节点/连线声明式写法呈现GitHub 会将其直接渲染为内联图。 ## 从需求到代码特征文件与 CLI 处理函数 需求侧由两个 Gherkin 特征文件描述与实现一一对应 - [render-project-as-markdown.feature](https://link.gitcode.com/i/35fdeb30210b3c7b9d4ee928cac6875a)单项目渲染规则——单文档以项目标题开头、配置的描述作为概览出现在第一个视图小节之前、无描述则直接从标题进入第一个小节、每个已编写视图按模型编写顺序成为小节、无源文件的自动生成视图被省略、有描述的视图描述置于图上方、无描述的视图小节只含标题和图、两次渲染逐字节一致 - [export-workspace-to-markdown.feature](https://link.gitcode.com/i/3b9e8eb82cf936507a03479bd371993f)工作区级导出规则——每个项目在自己的目录得到 README、无视图项目跳过、可限定单个项目、未知项目名报错「not found」、生成的页面带生成标记、已有生成页会被覆盖、手写 README 受保护除非显式 --force、无法读取的 README 视为不安全而整体失败且不覆盖。 CLI 侧的实现是 [handler.ts](https://link.gitcode.com/i/ec6ffcb6df352117d37d23472bd09ef7) 中的 runExportMarkdown关键调用链 1. fromWorkspace(args.path, { graphviz: args.useDot ? binary : wasm, watch: false }) 打开工作区一次性布局、非 watch 模式 2. 遍历 likec4.languageServices.projects()若指定了 args.project 则过滤过滤后为空即报错并抛 project not found: id 3. 对每个项目取 layoutedModel(prj.id)经 hasAuthoredViews 判定是否有源文件视图没有则跳过 4. projectDescription(prj.config.metadata) 从项目配置的 metadata 包中提取字符串类型的 description 字段传给 generateMarkdown——这正是需求中「配置的 project description 会带到页面上」的实现 5. 写入前经 canWrite 做保护判定见下成功后 writeFile(outfile, GENERATED_MARKER content) 并计数 6. written 0 时抛错否则计时日志收尾。 ### 手写 README 的保护逻辑 canWrite 是覆盖安全的核心行为精确对应特征文件的三个场景 ts // packages/likec4/src/cli/export/markdown/handler.ts async function canWrite(outfile: string, force: boolean): Promiseboolean { if (force) return true let existing: string try { existing await readFile(outfile, utf-8) } catch (error) { if (error instanceof Error code in error error.code ENOENT) return true throw error } return existing.startsWith(GENERATED_MARKER) }文件不存在ENOENT→ 允许写入文件存在且以GENERATED_MARKER开头 → 是上一次本命令生成的页面允许覆盖对应「Regenerating a previously generated page」文件存在但读不出内容非 ENOENT 的读取错误→ 按不安全处理错误直接上抛绝不静默覆盖其他内容手写 README→ 拒绝除非传入--force。测试证据生成器测试 generate-markdown.spec.ts 以 11 个用例逐条覆盖渲染规则单文档单 H1、描述位置断言descIdx介于标题与首个###之间、无描述时文档等于「标题 首小节起的内容」、小节标题按编写顺序等于[Context, Containers, Deployment]且不含##二级标题、无源文件的 Landscape 视图被省略、【免费下载链接】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），仅供参考 Acme Platform
Acme Platform【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4ContextHow the system fits its surroundings.可见 Mermaid 内容带有 title frontmatter实体与关系均以 graph TB 节点/连线声明式写法呈现GitHub 会将其直接渲染为内联图。 ## 从需求到代码特征文件与 CLI 处理函数 需求侧由两个 Gherkin 特征文件描述与实现一一对应 - [render-project-as-markdown.feature](https://link.gitcode.com/i/35fdeb30210b3c7b9d4ee928cac6875a)单项目渲染规则——单文档以项目标题开头、配置的描述作为概览出现在第一个视图小节之前、无描述则直接从标题进入第一个小节、每个已编写视图按模型编写顺序成为小节、无源文件的自动生成视图被省略、有描述的视图描述置于图上方、无描述的视图小节只含标题和图、两次渲染逐字节一致 - [export-workspace-to-markdown.feature](https://link.gitcode.com/i/3b9e8eb82cf936507a03479bd371993f)工作区级导出规则——每个项目在自己的目录得到 README、无视图项目跳过、可限定单个项目、未知项目名报错「not found」、生成的页面带生成标记、已有生成页会被覆盖、手写 README 受保护除非显式 --force、无法读取的 README 视为不安全而整体失败且不覆盖。 CLI 侧的实现是 [handler.ts](https://link.gitcode.com/i/ec6ffcb6df352117d37d23472bd09ef7) 中的 runExportMarkdown关键调用链 1. fromWorkspace(args.path, { graphviz: args.useDot ? binary : wasm, watch: false }) 打开工作区一次性布局、非 watch 模式 2. 遍历 likec4.languageServices.projects()若指定了 args.project 则过滤过滤后为空即报错并抛 project not found: id 3. 对每个项目取 layoutedModel(prj.id)经 hasAuthoredViews 判定是否有源文件视图没有则跳过 4. projectDescription(prj.config.metadata) 从项目配置的 metadata 包中提取字符串类型的 description 字段传给 generateMarkdown——这正是需求中「配置的 project description 会带到页面上」的实现 5. 写入前经 canWrite 做保护判定见下成功后 writeFile(outfile, GENERATED_MARKER content) 并计数 6. written 0 时抛错否则计时日志收尾。 ### 手写 README 的保护逻辑 canWrite 是覆盖安全的核心行为精确对应特征文件的三个场景 ts // packages/likec4/src/cli/export/markdown/handler.ts async function canWrite(outfile: string, force: boolean): Promiseboolean { if (force) return true let existing: string try { existing await readFile(outfile, utf-8) } catch (error) { if (error instanceof Error code in error error.code ENOENT) return true throw error } return existing.startsWith(GENERATED_MARKER) }文件不存在ENOENT→ 允许写入文件存在且以GENERATED_MARKER开头 → 是上一次本命令生成的页面允许覆盖对应「Regenerating a previously generated page」文件存在但读不出内容非 ENOENT 的读取错误→ 按不安全处理错误直接上抛绝不静默覆盖其他内容手写 README→ 拒绝除非传入--force。测试证据生成器测试 generate-markdown.spec.ts 以 11 个用例逐条覆盖渲染规则单文档单 H1、描述位置断言descIdx介于标题与首个###之间、无描述时文档等于「标题 首小节起的内容」、小节标题按编写顺序等于[Context, Containers, Deployment]且不含##二级标题、无源文件的 Landscape 视图被省略、【免费下载链接】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），仅供参考