1. 引言

氛围编程（Vibe code）、Harness 工程（Harness Engineering）是AI Agent 时代的软件工程新范式，核心是为 AI 智能体构建一套约束、工具、文档与反馈闭环的系统，让 AI 可靠、高效、自主完成工程任务，而非仅靠提示词驱动。

工程师角色转变也从传统模式：工程师是代码实现者，直接编写、调试代码，开始向Harness 模式转变。工程师是环境设计师 + 意图规范者，定义目标、搭建 Harness 系统、制定规则，AI 负责执行、验证、迭代。

AI时代的工程师更需要能够让AI 读懂你的设计思想，这样AI才能快速、精准地完成设计任务。

AI 时代架构师的利器：AI + markdown + mermaid + 浏览器插件Markdown_viewer

2. Markdown 轻量化标准化的内容承载核心

Markdown 是一种轻量级标记语言，用简单符号就能快速排版，易读易写，广泛用于笔记、文档、博客、GitHub 等场景。

• 核心特点
  • 纯文本，兼容所有编辑器
  • 语法简单，几分钟就能学会
  • 可直接导出为 HTML、PDF 等格式

2.1. AI 时代 Markdown 的新价值

AI 技术的普及让 Markdown 从“面向人阅读”的格式，升级为“人机协作”的黄金格式，应用场景大幅扩展：

1. AI 最易理解的稳定交互格式
   大模型对 Markdown 具备天然友好性：结构清晰（标题、列表、表格、代码块等层级分明）、无复杂格式干扰、几乎不会出现乱码或排版错乱，成为 AI 输出报告、方案、笔记的首选格式。
2. 从“手动排版”到“AI 自动生成”
   过去需人工完成的打字、排版工作，如今只需一句自然语言指令，AI 即可生成 PPT 结构、数据表、技术文档、思维导图大纲等内容，Markdown 成为人与 AI 之间的“通用接口”。
3. 一站式内容流水线：AI → MD → 全格式输出
   主流工作流：AI 生成 Markdown 内容 → 直接转换为网页、PDF、PPT、电子书、博客/公众号文章，全程无需复杂编辑器，提效显著。
4. AI 编程与文档创作的标配
   README、API 文档、技术笔记等均以 Markdown 为核心格式；AI 编写代码时，``` 代码块格式输出最稳定，可直接复制运行；AI 梳理架构、绘制流程图/Mermaid 图，也均基于 Markdown 载体。
5. 个人知识库的最佳格式
   搭配 AI 助手可实现：上传 MD 文件自动总结、扩写、改写；跨设备、跨软件通用；可直接投喂至个人知识库或本地大模型，适配未来 AI 应用场景。

简言之，Markdown 已成为“写给 AI 看、也写给人看”的通用语言，AI 技术越发展，这种简单、干净、结构化的格式价值越突出。

3. Mermaid 可视化落地，让架构逻辑 “看得见”

Mermaid 是一个基于 JavaScript 的图表绘制工具，它允许你使用类似 Markdown 的文本语法来定义图表，并在支持的渲染器中自动将其转换为 SVG 格式的流程图、时序图、甘特图、类图等。它的核心理念是“图表即代码”（Diagrams as Code），使得图表可以像代码一样被版本控制、审查和维护。

官方网址：
官方中文网:

3.1. 核心特点

• 文本驱动：无需拖拽式图形界面，仅通过文本描述即可生成图表，降低绘图门槛；
• 易集成：可无缝嵌入 Markdown 文件、Wiki 系统（GitLab、GitHub、Notion）、文档工具（MkDocs、Docusaurus）及各类开发 IDE；
• 丰富的图表类型：支持流程图、时序图、类图、状态图、实体关系图、用户旅程图、甘特图、饼图、需求图、思维导图、时间线、C4 架构图等；
• 开源免费：GitHub 托管的开源项目，社区活跃，持续迭代更新；
• 安全渲染：GitHub 等现代平台原生支持 Mermaid 渲染，默认启用沙箱机制防止恶意脚本执行。

举例：

3.2. Mermaid + AI：效率翻倍的可视化组合

Mermaid 与 AI 结合是当前效率最高的可视化方案之一，核心优势：

1. 无需学习复杂语法：只需描述业务/逻辑，AI 即可输出可直接运行的 Mermaid 代码；
2. 极速生成图表：传统手绘架构图需半小时，AI 生成仅需 10 秒，复制即可使用；
3. 与 Markdown 完美兼容：AI 输出 Markdown + Mermaid 内容后，可通过浏览器插件直接渲染，复制到文档/博客/PPT 均可用，且支持版本管理、修改、搜索；
4. 图表可维护：修改文本即可更新图表，无需重绘，适配多人协作场景，适合技术文档、架构说明、需求文档等场景。

比如告诉大模型：帮我画一个用户登录流程。
AI 会快速生成如下的mermaid流程图：

4. 浏览器 Markdown Viewer 插件，即时预览，提升阅读与协作效率

浏览器 Markdown Viewer 是Chrome/Edge/Firefox 等主流浏览器的扩展，核心作用是：直接在浏览器里把 .md 纯文本渲染成带排版、代码高亮、公式、图表的可读页面，不用打开编辑器、不用转 PDF/HTML，本地/远程文件都能看。

• 插件图标
  

4.1. 核心功能

4.1.1. 基础渲染能力

• 兼容 GitHub Flavored Markdown（GFM）：支持标题、列表、表格、代码块、引用、链接、图片、脚注等全量格式；
• 代码高亮：支持数十种编程语言，高亮效果可直接复制使用；
• 自动目录（TOC）：侧边栏生成大纲，点击可跳转至对应章节；
• 多主题适配：内置 30+ 主题（含深色模式），支持自定义 CSS 样式。

4.1.2. 高级能力（技术文档必备）

• 公式渲染：支持 MathJax / KaTeX 渲染 LaTeX 数学公式；
• Mermaid 图表渲染：原生支持流程图、时序图等所有 Mermaid 图表类型；
• 本地文件支持：拖入浏览器或通过 file:// 路径打开，需开启“允许访问文件网址”权限；
• 自动重载：本地 MD 文件保存后，浏览器页面自动刷新；
• 多格式导出：支持打印为 PDF、复制 HTML 代码、导出 Word 文档。

4.1.3. 安全与体验优化

• 本地渲染：所有解析操作在浏览器端完成，文件不上传至服务器，保障数据安全；
• 细粒度权限：可自定义允许渲染的网站/本地路径；
• 滚动记忆：自动记住上次阅读位置，再次打开文件无需重新定位。

4.2. 主流插件对比

4.3. 安装与使用（Chrome/Edge）

以Edge 为例：

1. 打开 Edge，点击“扩展” --> “获取 Microsoft Edge 扩展”
2. 搜索 Markdown Viewer（作者 simov）
3. 点击「获取」→ 添加扩展
   

4.4. 访问控制

更据需要设置URL和本地文件的访问权限。

4.5. 推荐配置

• 主题：GitHub（最通用）
• 解析器：markdown-it（支持 GFM 最全）
• 开启：MathJax、Mermaid、TOC、自动重载
• 布局：wide（1400px） 或 auto

4.6. AI 时代的价值

• AI 输出直接预览：让 AI 生成 Markdown，拖进浏览器立刻看排版
• 技术文档一站式：README、API 文档、笔记、Mermaid 图、公式，浏览器全搞定
• 快速导出：一键转 PDF/Word，用于汇报、分享

4.7. Mermaid 10.8.0 和 11.13.0

但遗憾的是，目前的Markdown Viewer 在24年4月30号以后就没有再更新了，插件只支持Mermaid 10.8.0版本，而目前最新的Mermaid版本是11.13.0。

Mermaid 10.8.0（2023年中版本）和 11.13.0（2024年后期版本）是两个跨度较大的版本，核心差异集中在语法兼容性、功能增强、渲染性能、新图表类型支持等方面。以下是详细的差异明细和实操示例：

4.7.1. 核心差异明细

4.7.2. 关键差异举例

4.7.2.1. 新增图表类型：Timeline（时间线）

10.8.0 无此类型，强行使用会渲染失败；11.13.0 原生支持：

%% 11.13.0 支持，10.8.0 报错
timeline
    title 产品迭代时间线
    2023-Q3 : 需求调研, 原型设计
    2023-Q4 : 开发1.0版本, 内部测试
    2024-Q1 : 正式上线, 用户反馈收集
    2024-Q2 : 迭代2.0版本, 性能优化

4.7.2.2. 新增图类型：class 图

class diagram

classDiagram
direction TD

class Animal

class Duck
Animal <|-- Duck

class Goose
Animal <|-- Goose

namespace animals {
    class Animal
}

namespace animals.birds {
    class Duck:::animals_birds
    class Goose:::animals_birds
}

classDef animals_birds color:lightgreen, fill:darkgreen, stroke: lightgreen

4.7.2.3. 新增 GitGraph

gitGraph
    commit
    branch develop
    checkout develop
    commit
    commit tag:"v1.0-beta" tag:"release-1.0"
    checkout main
    merge develop tag:"v1.0-stable"

4.7.2.4. 动画连接线

flowchart TD
  Start e1@--> Process
  Process e2@--> Decision
  Decision e3@--> End1
  Decision e4@--> End2
  
  e1@{ animate: true }
  e2@{ animation: fast }
  e3@{ animation: slow }
  e4@{ animate: true }

e1@–> 给连接线分配 ID（e1 是 ID，@ 是标记符）
e1@{ animate: true } 开启该连接线的动画
animation: fast/slow 设置动画速度

5. 升级Markdown viewer插件的mermaid版本

5.1. 下载Markdown viewer 代码

git clone https://github.com/simov/markdown-viewer.git

5.2. 分析代码结构

代码结构如下：

从构建代码：build/package.sh 可以看到，各个模块的构建最后会存入vendor目录下。

重点看下mermaid模块，该模块依赖文件：build/mermaid/package.json

{
  "name": "markdown-viewer",
  "version": "0.0.0",
  "description": "Markdown Viewer / Browser Extension",
  "private": true,
  "dependencies": {
    "mermaid": "10.8.0"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

从这里可以看到当前支持的mermaid的版本是10.8.0。

5.3. 升级mermaid版本

5.3.1. 查看构建脚本：build/package.sh

#!/bin/bash

# set current working directory to directory of the shell script
cd "$(dirname "$0")"

# before
npm ci 2> /dev/null || npm i
mkdir -p tmp

# mermaid.min.js
node fix-csp-issue.js \
  node_modules/mermaid/dist/mermaid.min.js \
  tmp/mermaid.min.js

# copy
cp tmp/mermaid.min.js ../../vendor/mermaid.min.js

# after
rm -rf node_modules/ tmp/

这里看到构建完成后，mermaid.min.js 被复制到 …/…/vendor/mermaid.min.js

5.3.2. 使用 ncu 命令升级依赖包版本

ncu -u
Upgrading /mnt/d/git/markdown_viewer/markdown-viewer/build/mermaid/package.json
[====================] 1/1 100%

 mermaid  10.8.0  →  11.13.0

Run npm install to install new versions.

5.3.3. 使用 npm install 安装依赖包

 npm install

up to date, audited 129 packages in 3s

3 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

5.3.4. 确定版本升级

npm list mermaid
markdown-viewer@0.0.0 /mnt/d/git/markdown_viewer/markdown-viewer/build/mermaid
└── mermaid@11.13.0

5.3.5. 构建代码

./build.sh

added 128 packages, and audited 129 packages in 54s

3 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

5.3.6. 确定生成新的依赖

ll ../../vendor/mermaid.min.js
-rw-r--r-- 1 root root 2963880 Mar 17 15:48 ../../vendor/mermaid.min.js

5.3.7. 下载发布版本：markdown-viewer-v5.3.zip

下载：

下载后展开到 markdown-viewer 目录下。

5.3.8. 替换markdown-viewer/vendor/mermaid.min.js

拷贝构建的：vendor/mermaid.min.js 替换下载的：markdown-viewer/vendor/mermaid.min.js

5.3.9. 修改版本编号

修改：manifest.json 中的版本编号, 从 5.3 改为 5.3.1，便于区分。

 "version"         : "5.3.1",

5.4. 安装插件

使用浏览器插件安装：“加载解压缩扩展”

• 安装后的结果：

升级成功后，再去看前面的mermaid源码，就没有问题了。

6. 总结

在 AI 深度渗透研发与架构设计的时代，AI + Markdown + Mermaid + Markdown Viewer 构成了架构师高效工作流的核心工具链，实现了“AI 智能生成→Markdown 标准化存储→Mermaid 可视化落地→Markdown Viewer 高效阅读协作”的全流程闭环，核心价值体现在三方面：

6.1. 效率翻倍

AI 替代排版、绘图、文档编写等重复性工作，Markdown 简化内容管理，Mermaid 快速实现逻辑可视化，Markdown Viewer 提升阅读与协作效率，让架构师从琐事中解放，聚焦核心的架构设计与决策。

6.2. 沟通降本

标准化 Markdown 文档 + 可视化 Mermaid 图表，让复杂技术逻辑（如 AI Agent 框架、分布式系统）更易传递，跨团队协作无需反复解释，大幅降低沟通成本。

6.3. 质量可控

AI 辅助优化逻辑，Markdown 支持版本管理，Mermaid 图表可追溯修改，Markdown Viewer 保障阅读体验，让架构设计的每一环都可追溯、可优化，提升方案质量与稳定性。

对于聚焦 AI Agent 技术、多技术栈研发、教育场景技术落地的架构师而言，这套工具链兼顾专业深度与轻量化高效的诉求，是 AI 时代提升生产力的核心选择。

注：更新的插件下载地址：https://gitee.com/shendong70/markdown-viewer/releases/tag/5.3.1