chore: 迁移 mermaid 绘图技能到 meta 层
This commit is contained in:
@@ -0,0 +1,140 @@
|
|||||||
|
---
|
||||||
|
name: mermaid-diagram
|
||||||
|
description: 绘制并交付可在线评审的 mermaid 流程图:按业务主题建独立文件夹、写 .mmd 图源与渲染页、本地起服务让人在 web 端 review。当用户要求画流程图/现状图/链路图/架构图、把图放到 docs/diagrams 下、或让你出图给他看时使用。触发词:画图、绘图、流程图、mermaid、现状图、链路图、架构图、出图、图形评审、docs/diagrams。
|
||||||
|
metadata:
|
||||||
|
short-description: 绘制可在线评审的 mermaid 流程图
|
||||||
|
---
|
||||||
|
|
||||||
|
# Mermaid 绘图与在线评审
|
||||||
|
|
||||||
|
输出物 = 「`docs/diagrams/<主题>/` 下的 `.mmd` 图源 + 渲染页」+ 「一个能在浏览器里打开评审的 URL」。
|
||||||
|
|
||||||
|
本技能属于 LPT 工作区的 meta 层,图面向跨仓库实现评审(链路、现状、架构、表关系),不写入 `lpt-docs`(该仓库只保留系统概念与设计,禁止文件路径与代码片段)。
|
||||||
|
|
||||||
|
## 工作区约定(路径固定,不要另起目录)
|
||||||
|
|
||||||
|
| 用途 | 路径 |
|
||||||
|
|------|------|
|
||||||
|
| 技能目录 | `.agents/skills/mermaid-diagram/` |
|
||||||
|
| 脚手架脚本 | `.agents/skills/mermaid-diagram/scripts/new_figure.py` |
|
||||||
|
| 图表根目录 | `docs/diagrams/`(meta 仓库根,即本文件向上找到 `.agents` 的那一层) |
|
||||||
|
| 共享渲染器 | `docs/diagrams/viewer.js`(由脚本自动从技能 `assets/viewer.js` 铺设) |
|
||||||
|
| 主题索引页 | `docs/diagrams/index.html` |
|
||||||
|
| 主题渲染页 | `docs/diagrams/<topic>/index.html` |
|
||||||
|
| 图源 | `docs/diagrams/<topic>/<name>.mmd` |
|
||||||
|
|
||||||
|
- 命令默认在 meta 仓库根执行(含 `.agents/` 的那一层)。
|
||||||
|
- 图源、渲染页、共享渲染器都由脚本或本技能维护,不要手写在别处。
|
||||||
|
|
||||||
|
## Step 1 确认需求
|
||||||
|
|
||||||
|
先问清(缺一项就问,不要猜):
|
||||||
|
|
||||||
|
| 项 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| 主题 | 一个业务主题名(决定文件夹名与是否有现成目录) |
|
||||||
|
| 内容边界 | 要表达哪几层/哪几段,每段一张图还是一个整图 |
|
||||||
|
| 视图 | 现状 / 目标态 / 现状 vs 目标(决定配色中的「变化」标注) |
|
||||||
|
| 涉及仓库 | 图覆盖 lpt-be / lpt-fe / lpt-ai / lpt-infra 中的哪些 |
|
||||||
|
| 评审人关注点 | 待拍板的决策、待核实的口径,交付时要单独列出 |
|
||||||
|
|
||||||
|
## Step 2 建目录(同一主题复用,不新建重复目录)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 已存在同主题目录就直接用;新主题用脚手架生成目录 + 渲染页骨架
|
||||||
|
python3 .agents/skills/mermaid-diagram/scripts/new_figure.py \
|
||||||
|
--topic crm-data-sync --title "CRM 数据同步流程" \
|
||||||
|
--figures "ingest:入库加工,master-read:主表直读"
|
||||||
|
```
|
||||||
|
|
||||||
|
脚手架会:
|
||||||
|
|
||||||
|
- 建 `docs/diagrams/<topic>/`;
|
||||||
|
- 生成 `index.html`(分节、图例位、引用 `../viewer.js`、`?v=`);
|
||||||
|
- 生成各 `.mmd` 骨架(已带统一配色 classDef);
|
||||||
|
- 首次运行时自动铺设 `docs/diagrams/viewer.js` 与 `docs/diagrams/index.html`;
|
||||||
|
- 在索引页登记主题,并打印预览 URL。
|
||||||
|
|
||||||
|
## Step 3 写图源(.mmd)
|
||||||
|
|
||||||
|
每张图一个 `.mmd`,内容多就多拆几张,不要一张图塞完。
|
||||||
|
|
||||||
|
### 取证规范(evidence)
|
||||||
|
|
||||||
|
- 节点里出现的**类名、方法名、列名必须有代码依据**:先去看代码/表结构确认,再写图。
|
||||||
|
- 无法从代码验证的(外部调度号、DBA 约定)必须标出来源,用 `:::origin` 节点或注释写明。
|
||||||
|
- 「入口」节点必须落到真实入口:Controller 方法、定时任务、消息消费、前端路由或事件,写清 `文件名#方法`。
|
||||||
|
- 页面名/入口名以实际路由或组件为准,不要用口语化臆测的名字。
|
||||||
|
- 引用表/列时写出真实表名列名;涉及迁移脚本的时间点标出脚本名。
|
||||||
|
- 已废弃但仍存在于代码中的分支,必须显式标注为死代码,不要省略也不要当作有效链路。
|
||||||
|
|
||||||
|
### 节点文案规范(style)
|
||||||
|
|
||||||
|
- 首词用 `「角色」` 标记,角色取值:`入口`、`取`、`用`、`源`、`变更`、`说明`。
|
||||||
|
- 列名统一写 `表名.列名`;表名简写在全图内保持一致,复杂图在子图里放「表名简写」框。
|
||||||
|
- 消费类节点回答「取 / 用 / 源」三问:取什么条件、用于什么、原始值来自哪个字段或导入列。
|
||||||
|
- 长文本拆成子图内的多个小节点,不要把一段话塞进一个节点。
|
||||||
|
- 节点内换行用 `<br/>`。
|
||||||
|
|
||||||
|
### 方向与布局
|
||||||
|
|
||||||
|
- 数据流向 / 流程 / 调用链用 `flowchart LR`。
|
||||||
|
- **ER 图 / 表关系图用「主表居中、相关表向两侧辐射」**:`flowchart TB` + 主表先声明 + 无向连线 `A ---|"1:N"| B` 标基数,不要一律从左到右。
|
||||||
|
- 每张图默认一眼看全,避免超过约 25 个节点;超了就按阶段/子域拆图。
|
||||||
|
|
||||||
|
### 统一配色(全局一致,不要随手改色)
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
classDef src fill:#ffe1e1,stroke:#c0392b,stroke-width:3.5px,color:#7b1414
|
||||||
|
classDef api fill:#e8f0fe,stroke:#1a56b0,stroke-width:1.2px,color:#111
|
||||||
|
classDef take fill:#e7f6ea,stroke:#2e8b57,stroke-width:1.2px,color:#14532d
|
||||||
|
classDef use fill:#f3f0fb,stroke:#6b4fa0,stroke-width:1.2px,color:#3b2a63
|
||||||
|
classDef origin fill:#fff3cd,stroke:#b8860b,stroke-dasharray:4 3,color:#664d03
|
||||||
|
classDef note fill:#f7f7f7,stroke:#999,stroke-dasharray:4 3,color:#333
|
||||||
|
classDef warn fill:#ffe1e1,stroke:#c0392b,stroke-width:2.2px,color:#7b1414
|
||||||
|
```
|
||||||
|
|
||||||
|
语义对照:`src` 关键源/差异点、`api` 入口、`take` 取值、`use` 用途/处理、`origin` 值来源、`note` 说明、`warn` 风险/待拍板。
|
||||||
|
|
||||||
|
## Step 4 起本地服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd docs/diagrams && python3 -m http.server 8000 # 8000 被占用就换端口
|
||||||
|
```
|
||||||
|
|
||||||
|
必须在该目录(各主题文件夹的上级)起服务:渲染页靠 `../viewer.js` 引用共享渲染器,服务根设为主题文件夹会导致 `../` 越界 404。
|
||||||
|
|
||||||
|
## Step 5 自检(交付前必做)
|
||||||
|
|
||||||
|
用浏览器打开每个页面确认:图全部渲染成功、无 console 报错、节点不重叠、文字可读(必要时截图核对)。有失败先修再交付。
|
||||||
|
|
||||||
|
字段类图/表额外做两项:
|
||||||
|
|
||||||
|
- **覆盖率**:页面展示列(`prop`)数 = 字段来源表的列行数,少一列即未完成;
|
||||||
|
- **可读通**:每行的取值链能一路读到具体字段/表达式 + `文件名 第 N 行`,且同一列的「本阶段改写 / 沿用上阶段值」两种状态分开写明。
|
||||||
|
|
||||||
|
## Step 6 交付评审
|
||||||
|
|
||||||
|
给用户的回复必须包含:
|
||||||
|
|
||||||
|
1. **URL 清单**(索引页 + 每个页面),一行一个;
|
||||||
|
2. 每张图一句话说明它回答什么问题;
|
||||||
|
3. 涉及页面字段的,说明字段来源表的覆盖情况(页面列数 = 表行数);
|
||||||
|
4. 待其拍板的点(口径、字段、边界)单独列出,别混在图里。
|
||||||
|
|
||||||
|
## Step 7 按反馈迭代
|
||||||
|
|
||||||
|
只改 `.mmd`,改后递增渲染页里的 `?v=`,再跑一遍 Step 5 自检,然后把新 URL 给他。
|
||||||
|
|
||||||
|
## 禁止事项
|
||||||
|
|
||||||
|
- 把图内容写死在 html 里;改图不走 `.mmd`。
|
||||||
|
- 不同业务主题的图混放同一文件夹;同主题另建平行目录。
|
||||||
|
- 在 `lpt-docs` 内落图(违反该仓库「禁止文件路径与代码片段」规则)。
|
||||||
|
- 跳过自检就交付;改完图源忘记递增 `?v=`。
|
||||||
|
|
||||||
|
## 参考实现
|
||||||
|
|
||||||
|
- 共享渲染器:`.agents/skills/mermaid-diagram/assets/viewer.js`(铺设到 `docs/diagrams/viewer.js`)
|
||||||
|
- 主题索引:`docs/diagrams/index.html`
|
||||||
|
- 目录 + 多页渲染 + 图例 + 速查表:`docs/diagrams/<最早上线的主题>/`
|
||||||
@@ -0,0 +1,7 @@
|
|||||||
|
schema_version: v1
|
||||||
|
interface:
|
||||||
|
display_name: Mermaid 绘图评审
|
||||||
|
short_description: 绘制 mermaid 流程图并本地起服务在线评审
|
||||||
|
default_prompt: |
|
||||||
|
使用 $mermaid-diagram 按业务主题在 docs/diagrams/<主题>/ 下生成 .mmd 图源与渲染页,
|
||||||
|
按取证规范核对类名/方法名/列名的代码依据,起本地服务后给出可评审的 URL 清单。
|
||||||
@@ -0,0 +1,263 @@
|
|||||||
|
/*
|
||||||
|
* LPT 共享 mermaid 渲染器
|
||||||
|
* 由 .agents/skills/mermaid-diagram/scripts/new_figure.py 铺设到 docs/diagrams/viewer.js
|
||||||
|
*
|
||||||
|
* 用法(渲染页底部):
|
||||||
|
* <script src="../viewer.js?v=2"></script>
|
||||||
|
* <script>MermaidViewer.init();</script>
|
||||||
|
*
|
||||||
|
* 页面里每个图位写成:
|
||||||
|
* <div class="diagram" data-src="xxx.mmd?v=1" data-height="72vh">加载中…</div>
|
||||||
|
*
|
||||||
|
* 默认只读视图一眼看全;点「查看」进入全屏交互:Ctrl+滚轮缩放、拖拽平移、Esc 退出。
|
||||||
|
*/
|
||||||
|
(function (global) {
|
||||||
|
'use strict';
|
||||||
|
|
||||||
|
var MERMAID_CDN = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';
|
||||||
|
var seq = 0;
|
||||||
|
|
||||||
|
function ensureMermaid() {
|
||||||
|
if (global.mermaid) return Promise.resolve(global.mermaid);
|
||||||
|
return new Promise(function (resolve, reject) {
|
||||||
|
var s = document.createElement('script');
|
||||||
|
s.src = MERMAID_CDN;
|
||||||
|
s.async = true;
|
||||||
|
s.onload = function () {
|
||||||
|
if (global.mermaid) resolve(global.mermaid);
|
||||||
|
else reject(new Error('mermaid 已下载但未挂载到 window'));
|
||||||
|
};
|
||||||
|
s.onerror = function () {
|
||||||
|
reject(new Error('无法加载 mermaid(离线环境?):' + MERMAID_CDN));
|
||||||
|
};
|
||||||
|
document.head.appendChild(s);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function configureMermaid(mermaid) {
|
||||||
|
mermaid.initialize({
|
||||||
|
startOnLoad: false,
|
||||||
|
securityLevel: 'loose',
|
||||||
|
theme: 'base',
|
||||||
|
themeVariables: {
|
||||||
|
fontFamily: '"PingFang SC","Microsoft YaHei","Hiragino Sans GB",sans-serif',
|
||||||
|
fontSize: '14px'
|
||||||
|
},
|
||||||
|
flowchart: { htmlLabels: true, useMaxWidth: false, curve: 'basis' },
|
||||||
|
er: { useMaxWidth: false }
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function injectStyle() {
|
||||||
|
if (document.getElementById('mv-style')) return;
|
||||||
|
var css = [
|
||||||
|
'.mv-diagram{background:#fff;border:1px solid #e0e0e0;border-radius:8px;margin:10px 0;padding:0;overflow:hidden}',
|
||||||
|
'.mv-bar{display:flex;align-items:center;gap:8px;padding:6px 12px;border-bottom:1px solid #eee;background:#fbfbfb;font-size:12.5px;color:#666}',
|
||||||
|
'.mv-bar code{font-family:Menlo,Consolas,monospace}',
|
||||||
|
'.mv-bar .mv-spacer{flex:1}',
|
||||||
|
'.mv-btn{border:1px solid #1a56b0;background:#fff;color:#1a56b0;border-radius:4px;padding:2px 10px;font-size:12.5px;cursor:pointer}',
|
||||||
|
'.mv-btn:hover:not([disabled]){background:#e8f0fe}',
|
||||||
|
'.mv-btn[disabled]{opacity:.45;cursor:default}',
|
||||||
|
'.mv-stage{display:flex;justify-content:center;align-items:flex-start;overflow:auto;padding:16px}',
|
||||||
|
'.mv-stage svg{max-width:100%;height:auto;display:block}',
|
||||||
|
'.mv-err{color:#c0392b;font-size:13px;white-space:pre-wrap;font-family:Menlo,Consolas,monospace}',
|
||||||
|
'.mv-overlay{position:fixed;top:0;right:0;bottom:0;left:0;z-index:9999;background:rgba(20,20,20,.92);display:flex;flex-direction:column}',
|
||||||
|
'.mv-obar{display:flex;align-items:center;gap:8px;padding:8px 14px;color:#eee;font-size:13px;flex-wrap:wrap}',
|
||||||
|
'.mv-obar code{font-family:Menlo,Consolas,monospace;color:#9fd0ff}',
|
||||||
|
'.mv-obar .mv-spacer{flex:1}',
|
||||||
|
'.mv-obtn{border:1px solid #888;background:#2a2a2a;color:#eee;border-radius:4px;padding:3px 10px;font-size:13px;cursor:pointer}',
|
||||||
|
'.mv-obtn:hover{background:#3a3a3a}',
|
||||||
|
'.mv-viewport{flex:1;overflow:hidden;cursor:grab;background:#fff}',
|
||||||
|
'.mv-viewport.mv-grabbing{cursor:grabbing}',
|
||||||
|
'.mv-canvas{transform-origin:0 0;will-change:transform}',
|
||||||
|
'.mv-canvas svg{display:block;background:#fff}'
|
||||||
|
].join('');
|
||||||
|
var style = document.createElement('style');
|
||||||
|
style.id = 'mv-style';
|
||||||
|
style.textContent = css;
|
||||||
|
document.head.appendChild(style);
|
||||||
|
}
|
||||||
|
|
||||||
|
function openOverlay(title, svgMarkup) {
|
||||||
|
var overlay = document.createElement('div');
|
||||||
|
overlay.className = 'mv-overlay';
|
||||||
|
overlay.innerHTML =
|
||||||
|
'<div class="mv-obar"><code>' + title + '</code><span class="mv-spacer"></span>' +
|
||||||
|
'<button type="button" class="mv-obtn" data-act="out">缩小</button>' +
|
||||||
|
'<button type="button" class="mv-obtn" data-act="in">放大</button>' +
|
||||||
|
'<button type="button" class="mv-obtn" data-act="reset">重置</button>' +
|
||||||
|
'<span>Ctrl+滚轮缩放 · 拖拽平移 · Esc 退出</span>' +
|
||||||
|
'<button type="button" class="mv-obtn" data-act="close">关闭</button></div>' +
|
||||||
|
'<div class="mv-viewport"><div class="mv-canvas"></div></div>';
|
||||||
|
|
||||||
|
var viewport = overlay.querySelector('.mv-viewport');
|
||||||
|
var canvas = overlay.querySelector('.mv-canvas');
|
||||||
|
canvas.innerHTML = svgMarkup;
|
||||||
|
document.body.appendChild(overlay);
|
||||||
|
|
||||||
|
var scale = 1;
|
||||||
|
var tx = 0;
|
||||||
|
var ty = 0;
|
||||||
|
|
||||||
|
function apply() {
|
||||||
|
canvas.style.transform = 'translate(' + tx + 'px,' + ty + 'px) scale(' + scale + ')';
|
||||||
|
}
|
||||||
|
|
||||||
|
function fit() {
|
||||||
|
scale = 1;
|
||||||
|
tx = Math.max(0, (viewport.clientWidth - canvas.offsetWidth) / 2);
|
||||||
|
ty = Math.max(0, (viewport.clientHeight - canvas.offsetHeight) / 2);
|
||||||
|
apply();
|
||||||
|
}
|
||||||
|
|
||||||
|
function zoomAt(factor, cx, cy) {
|
||||||
|
var next = Math.min(8, Math.max(0.2, scale * factor));
|
||||||
|
tx = cx - (cx - tx) * (next / scale);
|
||||||
|
ty = cy - (cy - ty) * (next / scale);
|
||||||
|
scale = next;
|
||||||
|
apply();
|
||||||
|
}
|
||||||
|
|
||||||
|
viewport.addEventListener('wheel', function (e) {
|
||||||
|
if (!e.ctrlKey) return;
|
||||||
|
e.preventDefault();
|
||||||
|
var rect = viewport.getBoundingClientRect();
|
||||||
|
zoomAt(e.deltaY < 0 ? 1.12 : 1 / 1.12, e.clientX - rect.left, e.clientY - rect.top);
|
||||||
|
}, { passive: false });
|
||||||
|
|
||||||
|
var dragging = false;
|
||||||
|
var lastX = 0;
|
||||||
|
var lastY = 0;
|
||||||
|
|
||||||
|
function onMove(e) {
|
||||||
|
if (!dragging) return;
|
||||||
|
tx += e.clientX - lastX;
|
||||||
|
ty += e.clientY - lastY;
|
||||||
|
lastX = e.clientX;
|
||||||
|
lastY = e.clientY;
|
||||||
|
apply();
|
||||||
|
e.preventDefault();
|
||||||
|
}
|
||||||
|
|
||||||
|
function onUp() {
|
||||||
|
dragging = false;
|
||||||
|
viewport.classList.remove('mv-grabbing');
|
||||||
|
}
|
||||||
|
|
||||||
|
viewport.addEventListener('mousedown', function (e) {
|
||||||
|
dragging = true;
|
||||||
|
lastX = e.clientX;
|
||||||
|
lastY = e.clientY;
|
||||||
|
viewport.classList.add('mv-grabbing');
|
||||||
|
e.preventDefault();
|
||||||
|
});
|
||||||
|
viewport.addEventListener('contextmenu', function (e) { e.preventDefault(); });
|
||||||
|
|
||||||
|
window.addEventListener('mousemove', onMove);
|
||||||
|
window.addEventListener('mouseup', onUp);
|
||||||
|
|
||||||
|
function close() {
|
||||||
|
window.removeEventListener('mousemove', onMove);
|
||||||
|
window.removeEventListener('mouseup', onUp);
|
||||||
|
document.removeEventListener('keydown', onKey);
|
||||||
|
if (overlay.parentNode) overlay.parentNode.removeChild(overlay);
|
||||||
|
}
|
||||||
|
|
||||||
|
function onKey(e) {
|
||||||
|
if (e.key === 'Escape') close();
|
||||||
|
}
|
||||||
|
document.addEventListener('keydown', onKey);
|
||||||
|
|
||||||
|
overlay.querySelector('.mv-obar').addEventListener('click', function (e) {
|
||||||
|
var act = e.target && e.target.getAttribute && e.target.getAttribute('data-act');
|
||||||
|
if (!act) return;
|
||||||
|
if (act === 'close') return close();
|
||||||
|
if (act === 'reset') return fit();
|
||||||
|
zoomAt(act === 'in' ? 1.2 : 1 / 1.2, viewport.clientWidth / 2, viewport.clientHeight / 2);
|
||||||
|
});
|
||||||
|
|
||||||
|
requestAnimationFrame(fit);
|
||||||
|
}
|
||||||
|
|
||||||
|
function renderOne(container, mermaid) {
|
||||||
|
var src = container.getAttribute('data-src');
|
||||||
|
var height = container.getAttribute('data-height') || '72vh';
|
||||||
|
|
||||||
|
container.classList.add('mv-diagram');
|
||||||
|
container.innerHTML = '';
|
||||||
|
|
||||||
|
var bar = document.createElement('div');
|
||||||
|
bar.className = 'mv-bar';
|
||||||
|
var nameEl = document.createElement('code');
|
||||||
|
nameEl.textContent = src;
|
||||||
|
bar.appendChild(nameEl);
|
||||||
|
var spacer = document.createElement('span');
|
||||||
|
spacer.className = 'mv-spacer';
|
||||||
|
bar.appendChild(spacer);
|
||||||
|
var btn = document.createElement('button');
|
||||||
|
btn.type = 'button';
|
||||||
|
btn.className = 'mv-btn';
|
||||||
|
btn.textContent = '查看';
|
||||||
|
btn.disabled = true;
|
||||||
|
bar.appendChild(btn);
|
||||||
|
|
||||||
|
var stage = document.createElement('div');
|
||||||
|
stage.className = 'mv-stage';
|
||||||
|
stage.style.height = height;
|
||||||
|
|
||||||
|
container.appendChild(bar);
|
||||||
|
container.appendChild(stage);
|
||||||
|
|
||||||
|
return fetch(src, { cache: 'no-cache' })
|
||||||
|
.then(function (resp) {
|
||||||
|
if (!resp.ok) throw new Error('图源加载失败:HTTP ' + resp.status + ' ' + src);
|
||||||
|
return resp.text();
|
||||||
|
})
|
||||||
|
.then(function (code) {
|
||||||
|
return mermaid.render('mv-' + (seq++) + '-' + Date.now(), code);
|
||||||
|
})
|
||||||
|
.then(function (res) {
|
||||||
|
stage.innerHTML = res.svg;
|
||||||
|
var svg = stage.querySelector('svg');
|
||||||
|
if (svg) {
|
||||||
|
svg.removeAttribute('height');
|
||||||
|
svg.style.maxWidth = '100%';
|
||||||
|
svg.style.height = 'auto';
|
||||||
|
}
|
||||||
|
btn.disabled = false;
|
||||||
|
btn.addEventListener('click', function () { openOverlay(src, res.svg); });
|
||||||
|
})
|
||||||
|
.catch(function (err) {
|
||||||
|
stage.innerHTML = '';
|
||||||
|
var box = document.createElement('div');
|
||||||
|
box.className = 'mv-err';
|
||||||
|
box.textContent = '渲染失败:' + (err && err.message ? err.message : err);
|
||||||
|
stage.appendChild(box);
|
||||||
|
console.error('[mermaid-viewer]', src, err);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function init(options) {
|
||||||
|
options = options || {};
|
||||||
|
var selector = options.selector || '.diagram';
|
||||||
|
if (document.querySelector('.mv-diagram')) injectStyle();
|
||||||
|
var containers = Array.prototype.slice.call(document.querySelectorAll(selector));
|
||||||
|
if (!containers.length) return Promise.resolve([]);
|
||||||
|
injectStyle();
|
||||||
|
return ensureMermaid()
|
||||||
|
.then(function (mermaid) {
|
||||||
|
configureMermaid(mermaid);
|
||||||
|
return Promise.all(containers.map(function (c) { return renderOne(c, mermaid); }));
|
||||||
|
})
|
||||||
|
.catch(function (err) {
|
||||||
|
console.error('[mermaid-viewer] 初始化失败', err);
|
||||||
|
containers.forEach(function (c) {
|
||||||
|
c.classList.add('mv-diagram');
|
||||||
|
c.innerHTML = '<div class="mv-stage"><div class="mv-err">初始化失败:' +
|
||||||
|
(err && err.message ? err.message : err) + '</div></div>';
|
||||||
|
});
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
global.MermaidViewer = { init: init, version: '2' };
|
||||||
|
})(window);
|
||||||
@@ -0,0 +1,244 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""新建一个「主题文件夹 + 渲染页骨架 + .mmd 骨架」,并在图形索引页登记主题。
|
||||||
|
|
||||||
|
用法:
|
||||||
|
python3 .agents/skills/mermaid-diagram/scripts/new_figure.py \
|
||||||
|
--topic crm-data-sync --title "CRM 数据同步流程" \
|
||||||
|
--figures "ingest:入库加工,master-read:主表直读"
|
||||||
|
|
||||||
|
约定(见 .agents/skills/mermaid-diagram/SKILL.md):
|
||||||
|
docs/diagrams/<topic>/index.html ← 渲染页(分节 + 图例 + ../viewer.js + ?v=)
|
||||||
|
docs/diagrams/<topic>/<name>.mmd ← 图源(骨架已带统一配色 classDef)
|
||||||
|
docs/diagrams/viewer.js ← 共享渲染器(首次运行时从技能 assets 铺设)
|
||||||
|
docs/diagrams/index.html ← 图形索引(脚本插入主题条目)
|
||||||
|
|
||||||
|
图表根目录 = 向上找到 `.agents/` 的那一层下的 docs/diagrams(本工作区即 meta 仓库根)。
|
||||||
|
"""
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import re
|
||||||
|
import shutil
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
SKILL_DIR = Path(__file__).resolve().parent.parent
|
||||||
|
VIEWER_SRC = SKILL_DIR / "assets" / "viewer.js"
|
||||||
|
|
||||||
|
PALETTE = """ classDef src fill:#ffe1e1,stroke:#c0392b,stroke-width:3.5px,color:#7b1414
|
||||||
|
classDef api fill:#e8f0fe,stroke:#1a56b0,stroke-width:1.2px,color:#111
|
||||||
|
classDef take fill:#e7f6ea,stroke:#2e8b57,stroke-width:1.2px,color:#14532d
|
||||||
|
classDef use fill:#f3f0fb,stroke:#6b4fa0,stroke-width:1.2px,color:#3b2a63
|
||||||
|
classDef origin fill:#fff3cd,stroke:#b8860b,stroke-dasharray:4 3,color:#664d03
|
||||||
|
classDef note fill:#f7f7f7,stroke:#999,stroke-dasharray:4 3,color:#333
|
||||||
|
classDef warn fill:#ffe1e1,stroke:#c0392b,stroke-width:2.2px,color:#7b1414
|
||||||
|
"""
|
||||||
|
|
||||||
|
MMD_STUB = """flowchart LR
|
||||||
|
%% {title}
|
||||||
|
%% 依据:<写清类名/方法名/表名从哪来,未经验证的内容标注来源>
|
||||||
|
|
||||||
|
{palette}
|
||||||
|
subgraph T1["{title}"]
|
||||||
|
direction LR
|
||||||
|
A["「入口」<br/>类名#方法"]:::api
|
||||||
|
B["「取」<br/>条件 → 聚合(表.列)"]:::take
|
||||||
|
C["「用」<br/>结果用途"]:::use
|
||||||
|
D["「源」<br/>该值来自哪个字段 / 哪个导入列"]:::origin
|
||||||
|
A --> B --> C
|
||||||
|
B -.-> D
|
||||||
|
end
|
||||||
|
"""
|
||||||
|
|
||||||
|
PAGE = """<!DOCTYPE html>
|
||||||
|
<html lang="zh-CN">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<title>{title}</title>
|
||||||
|
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
|
||||||
|
<style>
|
||||||
|
body {{ margin: 0 auto; max-width: 1600px; padding: 24px; background: #fafafa; font-family: "PingFang SC", "Microsoft YaHei", sans-serif; color: #333; }}
|
||||||
|
h1 {{ font-size: 20px; }}
|
||||||
|
h2 {{ font-size: 16px; border-left: 4px solid #1a56b0; padding-left: 10px; margin-top: 40px; }}
|
||||||
|
.tip {{ color: #777; font-size: 13px; line-height: 1.8; }}
|
||||||
|
.legend {{ font-size: 13px; color: #555; margin: 4px 0 0; }}
|
||||||
|
.legend span {{ display: inline-block; padding: 1px 8px; border-radius: 4px; margin-right: 6px; border: 1px solid; }}
|
||||||
|
.diagram {{ background: #fff; border: 1px solid #e0e0e0; border-radius: 8px; padding: 16px; margin: 10px 0; }}
|
||||||
|
code {{ font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 12.5px; }}
|
||||||
|
details {{ background: #fff; border: 1px solid #e0e0e0; border-radius: 6px; padding: 8px 12px; margin: 10px 0; }}
|
||||||
|
summary {{ cursor: pointer; font-size: 13.5px; color: #1a56b0; }}
|
||||||
|
table {{ border-collapse: collapse; width: 100%; font-size: 13px; margin-top: 6px; }}
|
||||||
|
th, td {{ border: 1px solid #e0e0e0; padding: 5px 8px; text-align: left; vertical-align: top; }}
|
||||||
|
th {{ background: #f4f6f8; }}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<h1>{title}</h1>
|
||||||
|
<p class="tip">图源为同目录 <code>.mmd</code> 纯文本(可直接编辑);改动后需递增下方 <code>?v=</code> 版本号以避开浏览器缓存。<br/>
|
||||||
|
节点首行的「」为角色(入口 / 取 / 用 / 源 …);列名写 <code>表名.列名</code>,简写对照见各图内的「表名简写」框。<br/>
|
||||||
|
本地预览:在 <code>docs/diagrams</code> 目录执行 <code>python3 -m http.server 8000</code>,再访问
|
||||||
|
<code>http://localhost:8000/{topic}/index.html</code>。<br/>
|
||||||
|
每张图默认<b>只读视图</b>、一眼看全;点「查看」进入交互后 <b>Ctrl+滚轮</b>缩放、<b>右键拖拽</b>平移,<kbd>Esc</kbd> 退出。</p>
|
||||||
|
|
||||||
|
{sections}
|
||||||
|
<script src="../viewer.js?v=2"></script>
|
||||||
|
<script>MermaidViewer.init();</script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
"""
|
||||||
|
|
||||||
|
INDEX = """<!DOCTYPE html>
|
||||||
|
<html lang="zh-CN">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<title>LPT 图表索引</title>
|
||||||
|
<style>
|
||||||
|
body {{ margin: 0 auto; max-width: 1600px; padding: 24px; background: #fafafa; font-family: "PingFang SC", "Microsoft YaHei", sans-serif; color: #333; }}
|
||||||
|
h1 {{ font-size: 20px; }}
|
||||||
|
.tip {{ color: #777; font-size: 13px; line-height: 1.8; }}
|
||||||
|
ul {{ list-style: none; padding: 0; }}
|
||||||
|
li {{ background: #fff; border: 1px solid #e0e0e0; border-radius: 8px; padding: 12px 16px; margin: 12px 0; }}
|
||||||
|
li a {{ font-size: 15px; color: #1a56b0; text-decoration: none; }}
|
||||||
|
li a:hover {{ text-decoration: underline; }}
|
||||||
|
li p {{ margin: 6px 0 0; color: #777; font-size: 13px; }}
|
||||||
|
code {{ font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 12.5px; }}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<h1>LPT 图表索引</h1>
|
||||||
|
<p class="tip">每个业务主题一个文件夹,图源为同目录 <code>.mmd</code> 纯文本,渲染页靠 <code>../viewer.js</code> 共享渲染器。<br/>
|
||||||
|
本地预览:在 <code>docs/diagrams</code> 目录执行 <code>python3 -m http.server 8000</code>,再访问
|
||||||
|
<code>http://localhost:8000/<主题>/index.html</code>。</p>
|
||||||
|
<ul>
|
||||||
|
</ul>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
"""
|
||||||
|
|
||||||
|
SECTION = """ <h2>{heading}</h2>
|
||||||
|
<div class="diagram" data-src="{name}.mmd?v=1" data-height="72vh">加载中…</div>
|
||||||
|
<p class="legend">
|
||||||
|
<span style="background:#e8f0fe;border-color:#1a56b0">蓝 入口</span>
|
||||||
|
<span style="background:#e7f6ea;border-color:#2e8b57">绿 取值</span>
|
||||||
|
<span style="background:#f3f0fb;border-color:#6b4fa0">紫 用途 / 处理</span>
|
||||||
|
<span style="background:#fff3cd;border-color:#b8860b">橙(虚线)值来源</span>
|
||||||
|
<span style="background:#f7f7f7;border-color:#999">灰(虚线)说明</span>
|
||||||
|
</p>
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
def parse_figures(raw: str):
|
||||||
|
out = []
|
||||||
|
for item in raw.split(","):
|
||||||
|
item = item.strip()
|
||||||
|
if not item:
|
||||||
|
continue
|
||||||
|
name, _, heading = item.partition(":")
|
||||||
|
name = name.strip()
|
||||||
|
if not re.fullmatch(r"[A-Za-z0-9._-]+", name):
|
||||||
|
sys.exit(f"图名只能用字母/数字/._- :{name}")
|
||||||
|
out.append((name, heading.strip() or name))
|
||||||
|
if not out:
|
||||||
|
sys.exit("--figures 至少要给一个图")
|
||||||
|
return out
|
||||||
|
|
||||||
|
|
||||||
|
def find_diagrams_root(start: Path) -> Path:
|
||||||
|
for p in [start, *start.parents]:
|
||||||
|
if (p / ".agents").is_dir():
|
||||||
|
return p / "docs" / "diagrams"
|
||||||
|
sys.exit("未找到工作区根目录(向上找不到 .agents/),请在 meta 仓库内执行或用 --root 指定")
|
||||||
|
|
||||||
|
|
||||||
|
def ensure_viewer(root: Path, refresh: bool):
|
||||||
|
target = root / "viewer.js"
|
||||||
|
if not VIEWER_SRC.exists():
|
||||||
|
sys.exit(f"技能缺少共享渲染器:{VIEWER_SRC}")
|
||||||
|
if target.exists() and not refresh:
|
||||||
|
print(f"已存在共享渲染器,未覆盖:{target}(如需同步请加 --refresh-viewer)")
|
||||||
|
return
|
||||||
|
shutil.copyfile(VIEWER_SRC, target)
|
||||||
|
print(f"铺设共享渲染器:{target}")
|
||||||
|
|
||||||
|
|
||||||
|
def ensure_index(root: Path):
|
||||||
|
index = root / "index.html"
|
||||||
|
if index.exists():
|
||||||
|
return index
|
||||||
|
index.write_text(INDEX, encoding="utf-8")
|
||||||
|
print(f"新建图形索引:{index}")
|
||||||
|
return index
|
||||||
|
|
||||||
|
|
||||||
|
def register_in_index(root: Path, topic: str, title: str, page: str):
|
||||||
|
index = ensure_index(root)
|
||||||
|
html = index.read_text(encoding="utf-8")
|
||||||
|
if f'href="{topic}/' in html:
|
||||||
|
print(f"提示:索引页已登记 {topic},跳过")
|
||||||
|
return
|
||||||
|
entry = (
|
||||||
|
" <li>\n"
|
||||||
|
f' <a href="{topic}/{page}">{title}</a>\n'
|
||||||
|
f' <p>目录:<code>{topic}/</code></p>\n'
|
||||||
|
" </li>\n"
|
||||||
|
)
|
||||||
|
if " </ul>" not in html:
|
||||||
|
print(f"提示:索引页缺少插入锚点,请手动登记 {topic}")
|
||||||
|
return
|
||||||
|
html = html.replace(" </ul>", entry + " </ul>", 1)
|
||||||
|
index.write_text(html, encoding="utf-8")
|
||||||
|
print(f"已在索引页登记主题:{index}")
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
ap = argparse.ArgumentParser()
|
||||||
|
ap.add_argument("--topic", required=True, help="主题文件夹名(英文/数字/-)")
|
||||||
|
ap.add_argument("--title", required=True, help="页面标题")
|
||||||
|
ap.add_argument("--figures", required=True, help="图名:小节标题,逗号分隔,如 a:入库,b:直读")
|
||||||
|
ap.add_argument("--page", default="index.html", help="渲染页文件名,默认 index.html")
|
||||||
|
ap.add_argument("--root", help="图表根目录(默认向上查找 .agents/);传 docs/diagrams 本身也可")
|
||||||
|
ap.add_argument("--force", action="store_true", help="覆盖已存在的页面/图源")
|
||||||
|
ap.add_argument("--refresh-viewer", action="store_true", help="用技能 assets 覆盖 docs/diagrams/viewer.js")
|
||||||
|
args = ap.parse_args()
|
||||||
|
|
||||||
|
if not re.fullmatch(r"[A-Za-z0-9._-]+", args.topic):
|
||||||
|
sys.exit("--topic 只能用字母/数字/._-")
|
||||||
|
|
||||||
|
if args.root:
|
||||||
|
base = Path(args.root).resolve()
|
||||||
|
root = base if base.name == "diagrams" else base / "docs" / "diagrams"
|
||||||
|
else:
|
||||||
|
root = find_diagrams_root(Path.cwd().resolve())
|
||||||
|
root.mkdir(parents=True, exist_ok=True)
|
||||||
|
topic_dir = root / args.topic
|
||||||
|
topic_dir.mkdir(parents=True, exist_ok=True)
|
||||||
|
|
||||||
|
ensure_viewer(root, args.refresh_viewer)
|
||||||
|
|
||||||
|
figures = parse_figures(args.figures)
|
||||||
|
sections = "\n".join(SECTION.format(heading=h, name=n) for n, h in figures)
|
||||||
|
|
||||||
|
page_path = topic_dir / args.page
|
||||||
|
if page_path.exists() and not args.force:
|
||||||
|
print(f"已存在,未覆盖:{page_path}")
|
||||||
|
else:
|
||||||
|
page_path.write_text(PAGE.format(title=args.title, topic=args.topic, sections=sections), encoding="utf-8")
|
||||||
|
print(f"写入渲染页:{page_path}")
|
||||||
|
|
||||||
|
for name, heading in figures:
|
||||||
|
mmd = topic_dir / f"{name}.mmd"
|
||||||
|
if mmd.exists() and not args.force:
|
||||||
|
print(f"已存在,未覆盖:{mmd}")
|
||||||
|
continue
|
||||||
|
mmd.write_text(MMD_STUB.format(title=heading, palette=PALETTE), encoding="utf-8")
|
||||||
|
print(f"写入图源:{mmd}")
|
||||||
|
|
||||||
|
register_in_index(root, args.topic, args.title, args.page)
|
||||||
|
|
||||||
|
print("\n预览:")
|
||||||
|
print(f" cd {root} && python3 -m http.server 8000")
|
||||||
|
print(f" http://localhost:8000/{args.topic}/{args.page}")
|
||||||
|
print("\n下一步:按 .agents/skills/mermaid-diagram/SKILL.md 的「图源规范」填充 .mmd,改完递增页面里的 ?v=。")
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
@@ -4,6 +4,10 @@
|
|||||||
!.gitignore
|
!.gitignore
|
||||||
!/OPTIMIZATION_BACKLOG.md
|
!/OPTIMIZATION_BACKLOG.md
|
||||||
|
|
||||||
|
# Workspace-level agent skills and diagram review output
|
||||||
|
!/.agents/
|
||||||
|
!/docs/
|
||||||
|
|
||||||
# Local/editor noise
|
# Local/editor noise
|
||||||
.DS_Store
|
.DS_Store
|
||||||
Thumbs.db
|
Thumbs.db
|
||||||
|
|||||||
@@ -31,6 +31,8 @@
|
|||||||
| 目录 | 用途 |
|
| 目录 | 用途 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| `lpt-docs` | 概念与设计文档项目,只维护系统概念和设计思路 |
|
| `lpt-docs` | 概念与设计文档项目,只维护系统概念和设计思路 |
|
||||||
|
|
||||||
|
> 工作区级代理技能在 `.agents/skills/`,图表评审产物在 `docs/diagrams/`。
|
||||||
| `lpt-be` | Java Spring Boot 后端,提供 REST API、认证、数据库访问 |
|
| `lpt-be` | Java Spring Boot 后端,提供 REST API、认证、数据库访问 |
|
||||||
| `lpt-fe` | Vue 3 + TypeScript 前端 |
|
| `lpt-fe` | Vue 3 + TypeScript 前端 |
|
||||||
| `lpt-ai` | TypeScript + Fastify 独立 AI 服务 |
|
| `lpt-ai` | TypeScript + Fastify 独立 AI 服务 |
|
||||||
@@ -68,12 +70,20 @@ clone 完成后,进入或修改某个子项目前,先读取该子项目根
|
|||||||
|
|
||||||
## 工作区规则
|
## 工作区规则
|
||||||
|
|
||||||
- 本 meta 仓库只维护 `AGENTS.md` 和 `.gitignore`,不要在本仓库根目录创建业务代码或文档。
|
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
|
||||||
- `.gitignore` 忽略所有子项目目录,避免把独立 Git 仓库提交进本 meta 仓库。
|
- `.gitignore` 忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。
|
||||||
- 不要删除子项目内的 `.git`,也不要对子项目执行跨仓库的 `git add .`。
|
- 不要删除子项目内的 `.git`,也不要对子项目执行跨仓库的 `git add .`。
|
||||||
- 对子项目执行 Git 操作时使用 `git -C lpt-be <command>` 这类形式。
|
- 对子项目执行 Git 操作时使用 `git -C lpt-be <command>` 这类形式。
|
||||||
- 如果某个子项目目录已存在但不是 Git 仓库,或 clone 因 SSH 权限/网络失败,应停止并说明原因,不要用空目录或本地副本替代。
|
- 如果某个子项目目录已存在但不是 Git 仓库,或 clone 因 SSH 权限/网络失败,应停止并说明原因,不要用空目录或本地副本替代。
|
||||||
|
|
||||||
|
## 代理技能与图表
|
||||||
|
|
||||||
|
- 工作区级技能放在 `.agents/skills/<技能名>/`,不放进子项目;子项目专用技能才留在各仓库 `skills/`。
|
||||||
|
- `mermaid-diagram`:按业务主题在 `docs/diagrams/<主题>/` 生成 `.mmd` 图源与渲染页,起本地服务在线评审。
|
||||||
|
- 共享渲染器为 `docs/diagrams/viewer.js`,主题索引为 `docs/diagrams/index.html`;新增主题用脚手架:
|
||||||
|
`python3 .agents/skills/mermaid-diagram/scripts/new_figure.py --topic <主题> --title "<标题>" --figures "<图名>:<小节>"`。
|
||||||
|
- 图表面向跨仓库实现评审(链路、现状、架构、表关系),不写入 `lpt-docs`(该仓库只保留系统概念与设计)。
|
||||||
|
|
||||||
## 文档维护
|
## 文档维护
|
||||||
|
|
||||||
- 所有系统文档统一在 `lpt-docs` 仓库维护,代码仓库不保留 README、`docs/` 等文档文件。
|
- 所有系统文档统一在 `lpt-docs` 仓库维护,代码仓库不保留 README、`docs/` 等文档文件。
|
||||||
|
|||||||
@@ -0,0 +1,26 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="zh-CN">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<title>LPT 图表索引</title>
|
||||||
|
<style>
|
||||||
|
body { margin: 0 auto; max-width: 1600px; padding: 24px; background: #fafafa; font-family: "PingFang SC", "Microsoft YaHei", sans-serif; color: #333; }
|
||||||
|
h1 { font-size: 20px; }
|
||||||
|
.tip { color: #777; font-size: 13px; line-height: 1.8; }
|
||||||
|
ul { list-style: none; padding: 0; }
|
||||||
|
li { background: #fff; border: 1px solid #e0e0e0; border-radius: 8px; padding: 12px 16px; margin: 12px 0; }
|
||||||
|
li a { font-size: 15px; color: #1a56b0; text-decoration: none; }
|
||||||
|
li a:hover { text-decoration: underline; }
|
||||||
|
li p { margin: 6px 0 0; color: #777; font-size: 13px; }
|
||||||
|
code { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 12.5px; }
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<h1>LPT 图表索引</h1>
|
||||||
|
<p class="tip">每个业务主题一个文件夹,图源为同目录 <code>.mmd</code> 纯文本,渲染页靠 <code>../viewer.js</code> 共享渲染器。<br/>
|
||||||
|
本地预览:在 <code>docs/diagrams</code> 目录执行 <code>python3 -m http.server 8000</code>,再访问
|
||||||
|
<code>http://localhost:8000/<主题>/index.html</code>。</p>
|
||||||
|
<ul>
|
||||||
|
</ul>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
@@ -0,0 +1,263 @@
|
|||||||
|
/*
|
||||||
|
* LPT 共享 mermaid 渲染器
|
||||||
|
* 由 .agents/skills/mermaid-diagram/scripts/new_figure.py 铺设到 docs/diagrams/viewer.js
|
||||||
|
*
|
||||||
|
* 用法(渲染页底部):
|
||||||
|
* <script src="../viewer.js?v=2"></script>
|
||||||
|
* <script>MermaidViewer.init();</script>
|
||||||
|
*
|
||||||
|
* 页面里每个图位写成:
|
||||||
|
* <div class="diagram" data-src="xxx.mmd?v=1" data-height="72vh">加载中…</div>
|
||||||
|
*
|
||||||
|
* 默认只读视图一眼看全;点「查看」进入全屏交互:Ctrl+滚轮缩放、拖拽平移、Esc 退出。
|
||||||
|
*/
|
||||||
|
(function (global) {
|
||||||
|
'use strict';
|
||||||
|
|
||||||
|
var MERMAID_CDN = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';
|
||||||
|
var seq = 0;
|
||||||
|
|
||||||
|
function ensureMermaid() {
|
||||||
|
if (global.mermaid) return Promise.resolve(global.mermaid);
|
||||||
|
return new Promise(function (resolve, reject) {
|
||||||
|
var s = document.createElement('script');
|
||||||
|
s.src = MERMAID_CDN;
|
||||||
|
s.async = true;
|
||||||
|
s.onload = function () {
|
||||||
|
if (global.mermaid) resolve(global.mermaid);
|
||||||
|
else reject(new Error('mermaid 已下载但未挂载到 window'));
|
||||||
|
};
|
||||||
|
s.onerror = function () {
|
||||||
|
reject(new Error('无法加载 mermaid(离线环境?):' + MERMAID_CDN));
|
||||||
|
};
|
||||||
|
document.head.appendChild(s);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function configureMermaid(mermaid) {
|
||||||
|
mermaid.initialize({
|
||||||
|
startOnLoad: false,
|
||||||
|
securityLevel: 'loose',
|
||||||
|
theme: 'base',
|
||||||
|
themeVariables: {
|
||||||
|
fontFamily: '"PingFang SC","Microsoft YaHei","Hiragino Sans GB",sans-serif',
|
||||||
|
fontSize: '14px'
|
||||||
|
},
|
||||||
|
flowchart: { htmlLabels: true, useMaxWidth: false, curve: 'basis' },
|
||||||
|
er: { useMaxWidth: false }
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function injectStyle() {
|
||||||
|
if (document.getElementById('mv-style')) return;
|
||||||
|
var css = [
|
||||||
|
'.mv-diagram{background:#fff;border:1px solid #e0e0e0;border-radius:8px;margin:10px 0;padding:0;overflow:hidden}',
|
||||||
|
'.mv-bar{display:flex;align-items:center;gap:8px;padding:6px 12px;border-bottom:1px solid #eee;background:#fbfbfb;font-size:12.5px;color:#666}',
|
||||||
|
'.mv-bar code{font-family:Menlo,Consolas,monospace}',
|
||||||
|
'.mv-bar .mv-spacer{flex:1}',
|
||||||
|
'.mv-btn{border:1px solid #1a56b0;background:#fff;color:#1a56b0;border-radius:4px;padding:2px 10px;font-size:12.5px;cursor:pointer}',
|
||||||
|
'.mv-btn:hover:not([disabled]){background:#e8f0fe}',
|
||||||
|
'.mv-btn[disabled]{opacity:.45;cursor:default}',
|
||||||
|
'.mv-stage{display:flex;justify-content:center;align-items:flex-start;overflow:auto;padding:16px}',
|
||||||
|
'.mv-stage svg{max-width:100%;height:auto;display:block}',
|
||||||
|
'.mv-err{color:#c0392b;font-size:13px;white-space:pre-wrap;font-family:Menlo,Consolas,monospace}',
|
||||||
|
'.mv-overlay{position:fixed;top:0;right:0;bottom:0;left:0;z-index:9999;background:rgba(20,20,20,.92);display:flex;flex-direction:column}',
|
||||||
|
'.mv-obar{display:flex;align-items:center;gap:8px;padding:8px 14px;color:#eee;font-size:13px;flex-wrap:wrap}',
|
||||||
|
'.mv-obar code{font-family:Menlo,Consolas,monospace;color:#9fd0ff}',
|
||||||
|
'.mv-obar .mv-spacer{flex:1}',
|
||||||
|
'.mv-obtn{border:1px solid #888;background:#2a2a2a;color:#eee;border-radius:4px;padding:3px 10px;font-size:13px;cursor:pointer}',
|
||||||
|
'.mv-obtn:hover{background:#3a3a3a}',
|
||||||
|
'.mv-viewport{flex:1;overflow:hidden;cursor:grab;background:#fff}',
|
||||||
|
'.mv-viewport.mv-grabbing{cursor:grabbing}',
|
||||||
|
'.mv-canvas{transform-origin:0 0;will-change:transform}',
|
||||||
|
'.mv-canvas svg{display:block;background:#fff}'
|
||||||
|
].join('');
|
||||||
|
var style = document.createElement('style');
|
||||||
|
style.id = 'mv-style';
|
||||||
|
style.textContent = css;
|
||||||
|
document.head.appendChild(style);
|
||||||
|
}
|
||||||
|
|
||||||
|
function openOverlay(title, svgMarkup) {
|
||||||
|
var overlay = document.createElement('div');
|
||||||
|
overlay.className = 'mv-overlay';
|
||||||
|
overlay.innerHTML =
|
||||||
|
'<div class="mv-obar"><code>' + title + '</code><span class="mv-spacer"></span>' +
|
||||||
|
'<button type="button" class="mv-obtn" data-act="out">缩小</button>' +
|
||||||
|
'<button type="button" class="mv-obtn" data-act="in">放大</button>' +
|
||||||
|
'<button type="button" class="mv-obtn" data-act="reset">重置</button>' +
|
||||||
|
'<span>Ctrl+滚轮缩放 · 拖拽平移 · Esc 退出</span>' +
|
||||||
|
'<button type="button" class="mv-obtn" data-act="close">关闭</button></div>' +
|
||||||
|
'<div class="mv-viewport"><div class="mv-canvas"></div></div>';
|
||||||
|
|
||||||
|
var viewport = overlay.querySelector('.mv-viewport');
|
||||||
|
var canvas = overlay.querySelector('.mv-canvas');
|
||||||
|
canvas.innerHTML = svgMarkup;
|
||||||
|
document.body.appendChild(overlay);
|
||||||
|
|
||||||
|
var scale = 1;
|
||||||
|
var tx = 0;
|
||||||
|
var ty = 0;
|
||||||
|
|
||||||
|
function apply() {
|
||||||
|
canvas.style.transform = 'translate(' + tx + 'px,' + ty + 'px) scale(' + scale + ')';
|
||||||
|
}
|
||||||
|
|
||||||
|
function fit() {
|
||||||
|
scale = 1;
|
||||||
|
tx = Math.max(0, (viewport.clientWidth - canvas.offsetWidth) / 2);
|
||||||
|
ty = Math.max(0, (viewport.clientHeight - canvas.offsetHeight) / 2);
|
||||||
|
apply();
|
||||||
|
}
|
||||||
|
|
||||||
|
function zoomAt(factor, cx, cy) {
|
||||||
|
var next = Math.min(8, Math.max(0.2, scale * factor));
|
||||||
|
tx = cx - (cx - tx) * (next / scale);
|
||||||
|
ty = cy - (cy - ty) * (next / scale);
|
||||||
|
scale = next;
|
||||||
|
apply();
|
||||||
|
}
|
||||||
|
|
||||||
|
viewport.addEventListener('wheel', function (e) {
|
||||||
|
if (!e.ctrlKey) return;
|
||||||
|
e.preventDefault();
|
||||||
|
var rect = viewport.getBoundingClientRect();
|
||||||
|
zoomAt(e.deltaY < 0 ? 1.12 : 1 / 1.12, e.clientX - rect.left, e.clientY - rect.top);
|
||||||
|
}, { passive: false });
|
||||||
|
|
||||||
|
var dragging = false;
|
||||||
|
var lastX = 0;
|
||||||
|
var lastY = 0;
|
||||||
|
|
||||||
|
function onMove(e) {
|
||||||
|
if (!dragging) return;
|
||||||
|
tx += e.clientX - lastX;
|
||||||
|
ty += e.clientY - lastY;
|
||||||
|
lastX = e.clientX;
|
||||||
|
lastY = e.clientY;
|
||||||
|
apply();
|
||||||
|
e.preventDefault();
|
||||||
|
}
|
||||||
|
|
||||||
|
function onUp() {
|
||||||
|
dragging = false;
|
||||||
|
viewport.classList.remove('mv-grabbing');
|
||||||
|
}
|
||||||
|
|
||||||
|
viewport.addEventListener('mousedown', function (e) {
|
||||||
|
dragging = true;
|
||||||
|
lastX = e.clientX;
|
||||||
|
lastY = e.clientY;
|
||||||
|
viewport.classList.add('mv-grabbing');
|
||||||
|
e.preventDefault();
|
||||||
|
});
|
||||||
|
viewport.addEventListener('contextmenu', function (e) { e.preventDefault(); });
|
||||||
|
|
||||||
|
window.addEventListener('mousemove', onMove);
|
||||||
|
window.addEventListener('mouseup', onUp);
|
||||||
|
|
||||||
|
function close() {
|
||||||
|
window.removeEventListener('mousemove', onMove);
|
||||||
|
window.removeEventListener('mouseup', onUp);
|
||||||
|
document.removeEventListener('keydown', onKey);
|
||||||
|
if (overlay.parentNode) overlay.parentNode.removeChild(overlay);
|
||||||
|
}
|
||||||
|
|
||||||
|
function onKey(e) {
|
||||||
|
if (e.key === 'Escape') close();
|
||||||
|
}
|
||||||
|
document.addEventListener('keydown', onKey);
|
||||||
|
|
||||||
|
overlay.querySelector('.mv-obar').addEventListener('click', function (e) {
|
||||||
|
var act = e.target && e.target.getAttribute && e.target.getAttribute('data-act');
|
||||||
|
if (!act) return;
|
||||||
|
if (act === 'close') return close();
|
||||||
|
if (act === 'reset') return fit();
|
||||||
|
zoomAt(act === 'in' ? 1.2 : 1 / 1.2, viewport.clientWidth / 2, viewport.clientHeight / 2);
|
||||||
|
});
|
||||||
|
|
||||||
|
requestAnimationFrame(fit);
|
||||||
|
}
|
||||||
|
|
||||||
|
function renderOne(container, mermaid) {
|
||||||
|
var src = container.getAttribute('data-src');
|
||||||
|
var height = container.getAttribute('data-height') || '72vh';
|
||||||
|
|
||||||
|
container.classList.add('mv-diagram');
|
||||||
|
container.innerHTML = '';
|
||||||
|
|
||||||
|
var bar = document.createElement('div');
|
||||||
|
bar.className = 'mv-bar';
|
||||||
|
var nameEl = document.createElement('code');
|
||||||
|
nameEl.textContent = src;
|
||||||
|
bar.appendChild(nameEl);
|
||||||
|
var spacer = document.createElement('span');
|
||||||
|
spacer.className = 'mv-spacer';
|
||||||
|
bar.appendChild(spacer);
|
||||||
|
var btn = document.createElement('button');
|
||||||
|
btn.type = 'button';
|
||||||
|
btn.className = 'mv-btn';
|
||||||
|
btn.textContent = '查看';
|
||||||
|
btn.disabled = true;
|
||||||
|
bar.appendChild(btn);
|
||||||
|
|
||||||
|
var stage = document.createElement('div');
|
||||||
|
stage.className = 'mv-stage';
|
||||||
|
stage.style.height = height;
|
||||||
|
|
||||||
|
container.appendChild(bar);
|
||||||
|
container.appendChild(stage);
|
||||||
|
|
||||||
|
return fetch(src, { cache: 'no-cache' })
|
||||||
|
.then(function (resp) {
|
||||||
|
if (!resp.ok) throw new Error('图源加载失败:HTTP ' + resp.status + ' ' + src);
|
||||||
|
return resp.text();
|
||||||
|
})
|
||||||
|
.then(function (code) {
|
||||||
|
return mermaid.render('mv-' + (seq++) + '-' + Date.now(), code);
|
||||||
|
})
|
||||||
|
.then(function (res) {
|
||||||
|
stage.innerHTML = res.svg;
|
||||||
|
var svg = stage.querySelector('svg');
|
||||||
|
if (svg) {
|
||||||
|
svg.removeAttribute('height');
|
||||||
|
svg.style.maxWidth = '100%';
|
||||||
|
svg.style.height = 'auto';
|
||||||
|
}
|
||||||
|
btn.disabled = false;
|
||||||
|
btn.addEventListener('click', function () { openOverlay(src, res.svg); });
|
||||||
|
})
|
||||||
|
.catch(function (err) {
|
||||||
|
stage.innerHTML = '';
|
||||||
|
var box = document.createElement('div');
|
||||||
|
box.className = 'mv-err';
|
||||||
|
box.textContent = '渲染失败:' + (err && err.message ? err.message : err);
|
||||||
|
stage.appendChild(box);
|
||||||
|
console.error('[mermaid-viewer]', src, err);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function init(options) {
|
||||||
|
options = options || {};
|
||||||
|
var selector = options.selector || '.diagram';
|
||||||
|
if (document.querySelector('.mv-diagram')) injectStyle();
|
||||||
|
var containers = Array.prototype.slice.call(document.querySelectorAll(selector));
|
||||||
|
if (!containers.length) return Promise.resolve([]);
|
||||||
|
injectStyle();
|
||||||
|
return ensureMermaid()
|
||||||
|
.then(function (mermaid) {
|
||||||
|
configureMermaid(mermaid);
|
||||||
|
return Promise.all(containers.map(function (c) { return renderOne(c, mermaid); }));
|
||||||
|
})
|
||||||
|
.catch(function (err) {
|
||||||
|
console.error('[mermaid-viewer] 初始化失败', err);
|
||||||
|
containers.forEach(function (c) {
|
||||||
|
c.classList.add('mv-diagram');
|
||||||
|
c.innerHTML = '<div class="mv-stage"><div class="mv-err">初始化失败:' +
|
||||||
|
(err && err.message ? err.message : err) + '</div></div>';
|
||||||
|
});
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
global.MermaidViewer = { init: init, version: '2' };
|
||||||
|
})(window);
|
||||||
Reference in New Issue
Block a user