diff --git a/.agents/skills/mermaid-diagram/SKILL.md b/.agents/skills/mermaid-diagram/SKILL.md new file mode 100644 index 0000000..28c9bc3 --- /dev/null +++ b/.agents/skills/mermaid-diagram/SKILL.md @@ -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//index.html` | +| 图源 | `docs/diagrams//.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//`; +- 生成 `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) + +- 首词用 `「角色」` 标记,角色取值:`入口`、`取`、`用`、`源`、`变更`、`说明`。 +- 列名统一写 `表名.列名`;表名简写在全图内保持一致,复杂图在子图里放「表名简写」框。 +- 消费类节点回答「取 / 用 / 源」三问:取什么条件、用于什么、原始值来自哪个字段或导入列。 +- 长文本拆成子图内的多个小节点,不要把一段话塞进一个节点。 +- 节点内换行用 `
`。 + +### 方向与布局 + +- 数据流向 / 流程 / 调用链用 `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/<最早上线的主题>/` diff --git a/.agents/skills/mermaid-diagram/agents/openai.yaml b/.agents/skills/mermaid-diagram/agents/openai.yaml new file mode 100644 index 0000000..8e815cd --- /dev/null +++ b/.agents/skills/mermaid-diagram/agents/openai.yaml @@ -0,0 +1,7 @@ +schema_version: v1 +interface: + display_name: Mermaid 绘图评审 + short_description: 绘制 mermaid 流程图并本地起服务在线评审 + default_prompt: | + 使用 $mermaid-diagram 按业务主题在 docs/diagrams/<主题>/ 下生成 .mmd 图源与渲染页, + 按取证规范核对类名/方法名/列名的代码依据,起本地服务后给出可评审的 URL 清单。 diff --git a/.agents/skills/mermaid-diagram/assets/viewer.js b/.agents/skills/mermaid-diagram/assets/viewer.js new file mode 100644 index 0000000..3f69b6b --- /dev/null +++ b/.agents/skills/mermaid-diagram/assets/viewer.js @@ -0,0 +1,263 @@ +/* + * LPT 共享 mermaid 渲染器 + * 由 .agents/skills/mermaid-diagram/scripts/new_figure.py 铺设到 docs/diagrams/viewer.js + * + * 用法(渲染页底部): + * + * + * + * 页面里每个图位写成: + *
加载中…
+ * + * 默认只读视图一眼看全;点「查看」进入全屏交互: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 = + '
' + title + '' + + '' + + '' + + '' + + 'Ctrl+滚轮缩放 · 拖拽平移 · Esc 退出' + + '
' + + '
'; + + 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 = '
初始化失败:' + + (err && err.message ? err.message : err) + '
'; + }); + }); + } + + global.MermaidViewer = { init: init, version: '2' }; +})(window); diff --git a/.agents/skills/mermaid-diagram/scripts/new_figure.py b/.agents/skills/mermaid-diagram/scripts/new_figure.py new file mode 100644 index 0000000..4b50894 --- /dev/null +++ b/.agents/skills/mermaid-diagram/scripts/new_figure.py @@ -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//index.html ← 渲染页(分节 + 图例 + ../viewer.js + ?v=) + docs/diagrams//.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["「入口」
类名#方法"]:::api + B["「取」
条件 → 聚合(表.列)"]:::take + C["「用」
结果用途"]:::use + D["「源」
该值来自哪个字段 / 哪个导入列"]:::origin + A --> B --> C + B -.-> D + end +""" + +PAGE = """ + + + + {title} + + + + +

{title}

+

图源为同目录 .mmd 纯文本(可直接编辑);改动后需递增下方 ?v= 版本号以避开浏览器缓存。
+ 节点首行的「」为角色(入口 / 取 / 用 / 源 …);列名写 表名.列名,简写对照见各图内的「表名简写」框。
+ 本地预览:在 docs/diagrams 目录执行 python3 -m http.server 8000,再访问 + http://localhost:8000/{topic}/index.html。
+ 每张图默认只读视图、一眼看全;点「查看」进入交互后 Ctrl+滚轮缩放、右键拖拽平移,Esc 退出。

+ +{sections} + + + + +""" + +INDEX = """ + + + + LPT 图表索引 + + + +

LPT 图表索引

+

每个业务主题一个文件夹,图源为同目录 .mmd 纯文本,渲染页靠 ../viewer.js 共享渲染器。
+ 本地预览:在 docs/diagrams 目录执行 python3 -m http.server 8000,再访问 + http://localhost:8000/<主题>/index.html。

+
    +
+ + +""" + +SECTION = """

{heading}

+
加载中…
+

+ 蓝 入口 + 绿 取值 + 紫 用途 / 处理 + 橙(虚线)值来源 + 灰(虚线)说明 +

+""" + + +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 = ( + "
  • \n" + f' {title}\n' + f'

    目录:{topic}/

    \n' + "
  • \n" + ) + if " " not in html: + print(f"提示:索引页缺少插入锚点,请手动登记 {topic}") + return + html = html.replace(" ", entry + " ", 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() diff --git a/.gitignore b/.gitignore index 0f37af2..225c336 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 15d06de..c0fd23e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 ` 这类形式。 - 如果某个子项目目录已存在但不是 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/` 等文档文件。 diff --git a/docs/diagrams/index.html b/docs/diagrams/index.html new file mode 100644 index 0000000..e660cc2 --- /dev/null +++ b/docs/diagrams/index.html @@ -0,0 +1,26 @@ + + + + + LPT 图表索引 + + + +

    LPT 图表索引

    +

    每个业务主题一个文件夹,图源为同目录 .mmd 纯文本,渲染页靠 ../viewer.js 共享渲染器。
    + 本地预览:在 docs/diagrams 目录执行 python3 -m http.server 8000,再访问 + http://localhost:8000/<主题>/index.html。

    +
      +
    + + diff --git a/docs/diagrams/viewer.js b/docs/diagrams/viewer.js new file mode 100644 index 0000000..3f69b6b --- /dev/null +++ b/docs/diagrams/viewer.js @@ -0,0 +1,263 @@ +/* + * LPT 共享 mermaid 渲染器 + * 由 .agents/skills/mermaid-diagram/scripts/new_figure.py 铺设到 docs/diagrams/viewer.js + * + * 用法(渲染页底部): + * + * + * + * 页面里每个图位写成: + *
    加载中…
    + * + * 默认只读视图一眼看全;点「查看」进入全屏交互: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 = + '
    ' + title + '' + + '' + + '' + + '' + + 'Ctrl+滚轮缩放 · 拖拽平移 · Esc 退出' + + '
    ' + + '
    '; + + 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 = '
    初始化失败:' + + (err && err.message ? err.message : err) + '
    '; + }); + }); + } + + global.MermaidViewer = { init: init, version: '2' }; +})(window);