chore: 迁移 mermaid 绘图技能到 meta 层

This commit is contained in:
cat-shark
2026-10-09 12:28:53 +08:00
parent 4bb42385e8
commit 4cf0ddb681
8 changed files with 959 additions and 2 deletions
+140
View File
@@ -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/&lt;主题&gt;/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
View File
@@ -4,6 +4,10 @@
!.gitignore
!/OPTIMIZATION_BACKLOG.md
# Workspace-level agent skills and diagram review output
!/.agents/
!/docs/
# Local/editor noise
.DS_Store
Thumbs.db
+12 -2
View File
@@ -31,6 +31,8 @@
| 目录 | 用途 |
|------|------|
| `lpt-docs` | 概念与设计文档项目,只维护系统概念和设计思路 |
> 工作区级代理技能在 `.agents/skills/`,图表评审产物在 `docs/diagrams/`。
| `lpt-be` | Java Spring Boot 后端,提供 REST API、认证、数据库访问 |
| `lpt-fe` | Vue 3 + TypeScript 前端 |
| `lpt-ai` | TypeScript + Fastify 独立 AI 服务 |
@@ -68,12 +70,20 @@ clone 完成后,进入或修改某个子项目前,先读取该子项目根
## 工作区规则
- 本 meta 仓库只维护 `AGENTS.md` 和 `.gitignore`,不要在本仓库根目录创建业务代码或文档。
- `.gitignore` 忽略所有子项目目录,避免把独立 Git 仓库提交进本 meta 仓库。
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
- `.gitignore` 忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。
- 不要删除子项目内的 `.git`,也不要对子项目执行跨仓库的 `git add .`。
- 对子项目执行 Git 操作时使用 `git -C lpt-be <command>` 这类形式。
- 如果某个子项目目录已存在但不是 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/` 等文档文件。
+26
View File
@@ -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/&lt;主题&gt;/index.html</code>。</p>
<ul>
</ul>
</body>
</html>
+263
View File
@@ -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);