Compare commits

...
7 Commits
9 changed files with 1130 additions and 20 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/` 等文档文件。
+171 -18
View File
@@ -10,6 +10,9 @@
| 生成时间 | 2026-09-14 |
| 代码基线 | `lpt-be` c961157 / `lpt-fe` e66bdb7 / `lpt-ai` 200f088 / `lpt-infra` 0a23075 / `lpt-docs` 9cb9c75 |
| 核对方式 | 通读上述仓库源码 + 对线上 prod/dev 做只读探测(见附录 A) |
| 复核时间 | 2026-10-08 |
| 复核基线 | `lpt-be` 04d1f40 / `lpt-fe` 99a1b16 / `lpt-ai` bf56c2b / `lpt-infra` 34f2380 / `lpt-docs` a16cb4c |
| 复核结论 | 会话-01/02/03 已修(`lpt-be` `d8c8b76`);会话-04 仍无 `@Scheduled`;AI-03 已修(见条目)。基础设施变更:时区固定、LLM 切换为 DeepSeek(不影响本清单条目) |
若某仓库 HEAD 已明显晚于上表,先确认问题是否已被修复,再动手。
@@ -28,9 +31,9 @@
| 模块 | 条目 | 优先级 | 状态 | 需要先定什么 |
|------|------|--------|------|--------------|
| 学习会话生命周期 | 会话-01 遗忘检测路径不统一 | P0 | 可直接实施 | — |
| | 会话-02 `isOverTime()` 误报超时 | P0 | 可直接实施 | — |
| | 会话-03 结束会话不幂等 | P0 | 可直接实施 | — |
| 学习会话生命周期 | 会话-01 遗忘检测路径不统一 | P0 | 已完成 | — |
| | 会话-02 `isOverTime()` 误报超时 | P0 | 已完成 | — |
| | 会话-03 结束会话不幂等 | P0 | 已完成 | — |
| | 会话-04 悬挂会话无收敛 | P0 | 待决策 | 收敛方式(惰性 / 定时扫描 / 并用)+ 2 小时硬兜底阈值 |
| | 会话-05 活跃会话拦截无出路 | P1 | 待决策 | 出口形式(结束并开始新任务 / 放弃会话),建议与会话-04 同批 |
| 内容归属与报告 | 归属-01 内容归属与待归类 | 待实施 | 设计已确认 | 实现级取舍:碎片表如何承载归属、报告字段拆分、归类交互落点 |
@@ -42,23 +45,31 @@
| | 复习-04 覆盖率查询拉全量 | P3 | 依赖复习-01 | 覆盖率口径(复习-01 第 3 项) |
| | 复习-05 Feed 返回全文 | P3 | 依赖复习-01 | 条目单位与摘要口径(复习-01 第 1 项) |
| | 复习-06 学习引导 | P1 | 已确认待实施 | 依赖 AI-02 / AI-03,以及标记-01 的存储设计 |
| | 复习-07 复习耗时统计 | P2 | 可直接实施(口径已定) | — |
| | 复习-07 复习耗时统计 | P2 | 已完成 | — |
| AI 链路 | AI-01 事务内同步等 AI | P2 | 待决策 | 事务外纯读对比(小改)/ 任务表 + 异步回写 |
| | AI-02 全链路同步阻塞 | P2 | 可实施(方案已定) | 若 AI-01 选任务表方案,则与 AI-01 同批 |
| | AI-03 单 worker 串行无重试 | P2 | 可直接实施 | — |
| | AI-03 单 worker 串行无重试 | P2 | 已完成 | — |
| | AI-04 防并发锁是 JVM 内存锁 | P2 | 可直接实施 | 需确认「生成中」的对外语义(返回任务状态而非实体) |
| 数据与检索 | 数据-01 业务主表缺索引 | P3 | 可直接实施 | — |
| 数据与检索 | 数据-01 业务主表缺索引 | P3 | 已完成 | — |
| | 数据-02 统计聚合在内存 | P3 | 待决策 | SQL 聚合下推 / 物化统计表 |
| | 数据-03 编号撞号风险 | P3 | 待决策 | UUID/ULID / 加随机位 |
| 导出 | 导出-01 无数据导出 | P1 | 待决策(小) | 格式(Markdown / JSON)与范围(按任务 / 时间),默认方案可直接采用 |
| 安全 | 安全-01 数据库凭证明文 | P4 | 待决策 + 需你执行 | 是否轮换凭证;历史值清理还是视为已泄露 |
| | 安全-02 Actuator 鉴权边界 | P4 | 待决策 | 白名单 / 独立端口 + 网络策略(涉 `lpt-infra`) |
| | 安全-03 AI 入站无防护 | P4 | 可直接实施 | 内部鉴权方式(共享 token / 仅网络策略) |
| | 安全-04 生产打印全部 SQL | P4 | 可直接实施 | — |
| | 安全-04 生产打印全部 SQL | P4 | 已完成 | — |
| 运维与清理 | 运维-01 备份只在同一 PVC | P4 | 待决策 | 异地 / 对象存储目标选型,需你提供目标 |
| | 清理-01 死代码与死表 | P4 | 待决策 | 删除 / 保留并在 `lpt-docs` 说明定位 |
| 学习录音 | 录音-01 采集后端接口与 OBS 后端 | P1 | 已实现·已暂停 | 先定采集方案:OBS / 自研原生 |
| | 录音-02 控制通道与会话绑定 | P1 | 已暂停 | 轮询 lpt-be / 直连本机端口(建议轮询) |
| | 录音-03 音频落盘与对象存储 | P1 | 已暂停 | 对象存储选型(MinIO / 云对象存储) |
| | 录音-04 转写链路(provider 可配置) | P2 | 已暂停 | AI-02 / AI-03 |
| | 录音-05 录制可见性与隐私边界 | P1 | 已暂停 | 指示形态、他人语音口径 |
| | 录音-06 浏览器侧接入 | P1 | 已暂停 | 油猴脚本 / 直接进 lpt-fe |
已确认的设计决策(不是待办):会话-决策01 少于 10 分钟不计入总时长;会话-决策02 遗忘判定阈值 50 分钟。
> **学习录音模块已整体暂停**(2026‑10‑08):录音-01 的实现已完成并实测通过,但采到系统音频的两条路线(依赖 OBS / 自研原生)还没定,其余条目全部挂起。详见 §12。
已确认的设计决策(不是待办):会话-决策01 少于 10 分钟不计入总时长;会话-决策02 遗忘判定阈值 50 分钟;录音-决策01 录音由本机伴随程序负责;录音-决策02 只采系统输出不采麦克风。
---
@@ -77,13 +88,34 @@
- **决策**:25~50 分钟区间默认用户仍在屏幕前(番茄钟已提醒但可能正在收尾),不做截断;超过 50 分钟才判定为「忘了点暂停/结束」。
- **注意**:不要把这个阈值改成等于番茄钟长度(25 分钟);阈值存在的意义是区分「在学」与「忘了关」。真正要修的是执行路径不统一,见 会话-01。
### 录音-决策01 录音由运行在本机的伴随程序负责,浏览器不采集也不传输音频
- **依据**:浏览器无法在 Linux/macOS 采集系统音频(Chrome/Edge 仅在 Windows/ChromeOS 共享整个屏幕时可采系统声,Linux/macOS 只能采标签页音频,Firefox/Safari 不支持音频捕获);Chromium `media/audio/pulse/audio_manager_pulse.cc` 明确排除 monitor(loopback)设备。此外公网页面直连本机端口在 Chrome 142+ 受 Local Network Access 权限约束(Chrome 152 实测:公网页面向 `127.0.0.1` 的 fetch 被拒,`navigator.permissions.query({name:'local-network-access'})` 返回 `prompt`)。
- **决策**:采集、编码、上传全部由运行在用户本机的伴随程序完成;网页只负责发起、结束与展示。网页关闭或崩溃不影响录音。
- **注意**:不要把「浏览器直接采系统声」当作可用的退化路径,也不要默认用「本地端口直连」做控制通道(取舍见 录音-02)。
### 录音-决策02 只采系统输出,不采麦克风
- **依据**:录音要回答的是「用户听到了什么」,而不是「房间里发生了什么」。
- **决策**:只采系统混音,不采麦克风,也不用麦克风作为兜底来源。
- **注意**:这条同时收敛隐私范围与转写噪音,不要为提高「完整性」而混入麦克风。
### 录音-决策03 采集层只用 OBS,不自研原生采集(**已暂停,待重评**)
> 2026‑10‑08:本决策已回退为「待重评」。录音-01 实现完成后暴露了两个与决策依据相冲的事实:① OBS 无法直接录出纯音频(详见 §12),必须再引入 ffmpeg 抽音轨;② OBS 安装体积与跨平台配置差异成本高于先前估计。重启本模块前重新拍板,参见 §12「路线分叉」。
- **依据(当时)**:OBS 三平台都原生支持系统音频采集(Windows WASAPI loopback、Linux PulseAudio/PipeWire monitor、macOS 13+ ScreenCaptureKit),官方发布覆盖 Windows x64/arm64、macOS Apple/Intel、Ubuntu `.deb`;自研需分别实现三套原生采集(尤其 macOS SCK),成本远高于引入 OBS。
- **决策(暂停)**:采集层只做 OBS 后端,不保留原生后端的分支;OBS 的发布与升级由用户自行负责。
- **注意**:不要因为「不想让用户装 OBS」而临时增加虚拟声卡方案(Linux `module-remap-source` + 常驻 watcher),该路线已实测可行但被本决策取代。
---
## 4. P0 数据正确性
### 会话-01(原 LPT-01)遗忘检测只在「重新进入学习页面」这一条路径上执行
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `d8c8b76`
- **涉及仓库**:`lpt-be`(可选 `lpt-fe` 心跳)
- **前提**:系统已具备遗忘检测(见 会话-决策02),问题不在于缺少机制,而在于它只挂在一条路径上。
- **依据**:`pausedStudySession(lastStartTime.plusMinutes(WORK_DURATION))` 只在 `StudySessionsServiceImpl.startOrContinueStudySession()` 中出现(全仓唯一)。而 `pauseStudySession()` 与 `StudySessionsEntity.endedStudySession()`(内部 `pausedStudySession(now)`)都是直接 `effective += now - lastStartTime`,没有遗忘检测。
@@ -94,7 +126,8 @@
### 会话-02(原 LPT-03)`isOverTime()` 误报「超时 25 分钟」
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `d8c8b76`
- **涉及仓库**:`lpt-be`
- **依据**:`StudySessionsEntity.isOverTime()` 只比较 `last_start_time` 与当前时间,不看 `end_time` 与 `session_state`。`startOrContinueStudySession()` 用同一判定既驱动截断又驱动 `systemMessage`。
- **影响**:已暂停很久的会话(时间早已在暂停时正确入账),每次回到页面都会弹「上段学习任务已经超时 25 分钟,将仅计算为 25 分钟的有效学习时间」。
@@ -103,7 +136,8 @@
### 会话-03(原 LPT-04)结束会话不幂等,会产生重复学习报告
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `d8c8b76`
- **涉及仓库**:`lpt-be`
- **依据**:`StudySessionsEntity.endedStudySession()` 在 `state = ENDED` 时只 `log.warn` 并原样返回;`StudySessionsServiceImpl.endedStudySession()` 随后无条件 `studyReportsMapper.insert(...)`。
- **影响**:重复点击、网络重试即可写入多条报告 → 复习 Feed 重复项、标准导图重复节点、统计重复计数。
@@ -177,8 +211,11 @@
### 复习-07 复习耗时统计
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `3b33cd8`、`67c8711`,`lpt-fe` `21af81f`
- **涉及仓库**:`lpt-be` + `lpt-fe`
- **已实施**:回忆记录落 `review_duration_seconds`,`recall` 接口接收前端计时并由服务端统一结算,复习总览按任务聚合后与学习时长并列。
- **遗留**:学习引导尚未实现(复习-06),其耗时复用同一个 `review_duration_seconds` 字段,不需要再改表结构。
- **依据**:复习总览目前只展示来自会话的“累计有效学习时长”(`ReviewTaskStats.effectiveTime`),复习行为本身没有任何计时,投入不可见。
- **已定口径**:只对回忆对比与学习引导计时,滚动浏览不计时;超过 5 分钟无交互则截断到上一次交互时间(复习没有暂停动作);命名“复习耗时”,不叫有效复习时间、不套用 10 分钟最小阈值;复习总览按任务与学习时长并列展示;不做跨任务汇总大数字、不设目标、不参与复习排序。
- **建议**:把复习行为作为时间记录的主体(回忆对比已有记录实体,学习引导新增),耗时写在该行为上;前端补空闲检测并上报交互时间。
@@ -208,12 +245,19 @@
### AI-03(原 LPT-13)`lpt-ai` 单 worker 串行且无重试
- [ ] 未完成
- [x] 已完成
- **涉及仓库**:`lpt-ai`(+ `lpt-be` 超时策略)
- **完成于** `lpt-ai` `bf56c2b`
- **依据**:`task-queue.ts` 只有一个 `processing` 标志顺序处理;失败直接置 `failed`,无退避重试;任务记录 `TTL_MS = 1 小时`。
- **影响**:N 个并发请求时第 N 个需等待 N × LLM 耗时,超过 `lpt-be` 的 600s 超时后表现为「AI 实际成功、客户端已超时」,结果既不落库也不告知,用户重复点击导致重复计费。LLM 的 429/5xx 抖动被当成永久失败。
- **建议**:worker pool(并发度对齐服务商限流)+ 429/5xx 退避重试 + 幂等键/结果缓存(同一导图、同一报告草稿的相同输入直接复用)。
- **验收**:并发 N 个任务时耗时不再线性增长;可重试错误不产生失败结论。
- **已实施**:
- **Worker 池**:并发度 `LPT_AI_CONCURRENCY`(默认 2),队列改为基于 id 的 FIFO。
- **退避重试**:新增 `llm/retry.ts`,仅重试 408/429/5xx 与超时;4xx 客户端错误与「API Key 未配置」不重试;服务端 `Retry-After` 优先于自算退避。为此让 `LlmError` 保留上游真实状态码(原先一律记为 502,无法区分 429 与 400)。
- **幂等与结果复用**:以 `type + params` 的稳定哈希为幂等键(支持显式 `idempotencyKey`);进行中的相同请求合并为同一任务,已完成结果在 `LPT_AI_RESULT_CACHE_MS` 窗口内复用;**失败任务不复用**,保留用户重试机会;请求体 `force: true` 可强制重新生成。
- 队列改为可注入依赖的 `TaskQueue` 类,测试覆盖并发、重试、复用与清理。
- **不得改动的契约**:`/ai/tasks` 必须固定返回 201(Java 端 `AiServiceClient` 把非 201 视为提交失败),复用信息放在响应体的 `reused` / `status` 字段。
- **验收**:并发 N 个任务时耗时不再线性增长;可重试错误不产生失败结论。✅ 已用假 LLM 服务端到端验证:4 个任务× 300 ms 共用 431 ms(串行需 1200 ms+);前两次 429 后仍为 `done`;相同请求只调用 LLM 1 次。
- **遗留**:`lpt-ai` 的部署(`lpt-infra` configmap)未设队列相关环境变量,目前走默认值;需要调优时再补。
### AI-04(原 LPT-14)防并发锁是 JVM 内存锁
@@ -230,7 +274,8 @@
### 数据-01(原 LPT-15)业务主表缺索引,而每条查询都被追加租户条件
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `e506c4d`(补了 created_by 打头的复合索引;EXPLAIN 需在 MySQL 上核对)
- **涉及仓库**:`lpt-be`
- **依据**:`V20250629_1__LPT_dataBase_init.sql` 中 `study_sessions` / `study_reports` / `study_report_fragments` / `tasks` 均只有主键;`MybatisPlusConfig` 的租户拦截器给每条 SELECT/UPDATE/DELETE 追加 `created_by = ?`;全仓仅少数 review 表有索引。
- **影响**:所有高频查询(Feed、统计、按会话取碎片/报告)都是全表扫描 + 过滤,随使用量线性劣化。
@@ -313,7 +358,8 @@
### 安全-04(原 LPT-24)生产环境打印全部 SQL
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `af13bd5`
- **涉及仓库**:`lpt-be`
- **依据**:`application.yml` 中 `mybatis-plus.configuration.log-impl: org.apache.ibatis.logging.stdout.StdOutImpl`(注释里保留了 `Slf4jImpl` 备选)。
- **影响**:生产日志包含全部 SQL 与参数(含学习内容),噪音大且不利于排查。
@@ -345,10 +391,11 @@
1. **学习会话生命周期**:会话-03(结束幂等)+ 会话-01(结算口径统一)一批,修正时间数据口径并补用例;再做会话-02;最后做会话-04 + 会话-05(需先给收敛方式与出口形式的决策)。
2. **内容归属与报告**:归属-01 与报告-01 合并一次改完碎片表与报告结构(碎片归属、报告四段结构、导图待更新标记、检索口径);标记-01(统一标记存储)随同定下,学习引导的来源标记依赖它。
3. **复习**:先落复习-01 的六项结论(口径与内容边界),再做复习-07(复习耗时,可独立先做)与复习-02 / 复习-03 / 复习-04 / 复习-05;复习-06(学习引导)依赖 AI-02 / AI-03 与标记-01,排在 AI 链路之后。
3. **复习**:先落复习-01 的六项结论(口径与内容边界),复习-07(复习耗时)已独立完成;再做复习-02 / 复习-03 / 复习-04 / 复习-05;复习-06(学习引导)依赖 AI-02 / AI-03 与标记-01,排在 AI 链路之后。
4. **AI 链路**:AI-01(先把 AI 移出事务)→ AI-02 + AI-03(异步任务与队列可靠性)→ AI-04(并发锁与生成中语义)。
5. **数据与检索 + 导出**:数据-01(补索引)→ 数据-02 / 数据-03,导出-01 可并行。
6. **安全与运维清理**:安全-01 ~ 安全-04、运维-01、清理-01,彼此独立,可并行推进。
7. **学习录音(已暂停)**:模块整体挂起,重启前先定 §12「路线分叉」(依赖 OBS / 自研原生)。
---
@@ -396,6 +443,112 @@
---
## 12. 新增能力:学习录音(已暂停)
> **模块状态:已暂停(2026‑10‑08)**。录音-01 的实现已完成并实测通过,但「依赖 OBS」与「自研原生采集」两条路线的取舍未定,其余条目已挂起。重启前先读完本节末尾的「路线分叉」。
> 目标:学习会话期间采集设备上全部播放声音(含蓝牙耳机等全部输出设备),转写为文本,作为学习报告与知识碎片的上下文原料。概念与边界见 `lpt-docs` 的 `docs/concepts/study-recording.md`。
**采集架构(已确认)**:采集由运行在用户本机的伴随程序负责,音频直传后端;浏览器不采集音频、不传输音频,只发起与展示。
**采集后端(待重评)**:当前实现走 OBS,但 录音-决策03 已回退为待重评,见下方「路线分叉」。
**代码位置**:`lpt-companion`(本地独立仓库,已加入 meta 的 `.gitignore`,远端待建)。
| 分支 | 内容 |
|------|------|
| `main` | 仓库脚手架 + `AGENTS.md`(含待定方案、约束与实测坑位总结) |
| `feature/study-recording` | 第一版实现(OBS 后端 + 抽音轨),HEAD `8d0969d` |
已实现并实测的部分:obs-websocket 协议客户端与认证、独立 profile / 场景集合 / 场景 / 系统音频源的幂等准备、平台音频源映射、录制控制、用 ffmpeg 抽音轨并删中间视频,共 85 个单测。
**平台能力核对**(2026-10-07 本机实测 + 源码核对):
| 平台 | 系统音频来源 | 证据 |
|------|-------------|------|
| Windows | WASAPI loopback | OBS 桌面音频标准能力(本机无法验证) |
| Linux | 默认 sink 的 monitor | 本机实测:`pw-record --target=<sink>.monitor` 采集成功(峰值 32768 / RMS 27959);浏览器经 `module-remap-source` 走 `getUserMedia` 亦成功,且能录到非浏览器客户端的播放声 |
| macOS 13+ | ScreenCaptureKit | OBS 源码 `plugins/mac-capture/mac-sck-audio-capture.m`;`plugin-main.c` 中 `coreaudio_output_capture_info` 已标 `OBS_SOURCE_DEPRECATED`,改用 `sck_audio_capture_info`(本机无法验证) |
**已排除的路线**:
- 浏览器直接采集系统声:仅 Windows/ChromeOS 在共享整个屏幕时支持;Chromium 明确排除 monitor 设备。
- 把 monitor 包装成普通输入源再由浏览器采集:本机验证可行(`module-remap-source`),但需要常驻 watcher 跟随默认输出设备,且网页关闭即中断,已被伴随程序方案取代。
- 公网页面直连本机端口做控制:Chrome 142+ 起受 Local Network Access 权限约束(实测见 录音-决策01)。
- 用配置让 OBS 只录音频:`RecFormat2=ogg` 会让容器变成 ogg,但 OBS 仍用 `libfdk_aac` 写入,容器与编码器不匹配 → 产出 0 字节文件;`RecAudioEncoder` 设成 `aac` / `opus` / `ffmpeg_opus` 均未改变实际编码器。
### 路线分叉(重启本模块前必须先定)
| | 依赖 OBS(当前实现) | 自研原生采集 |
|---|---|---|
| 原理 | 经 obs-websocket 驱动 OBS 录出「视频+音频」,再用 ffmpeg 抽出音轨并丢弃视频 | 直接读操作系统混音端点,写出纯音频 |
| 实测状态 | Linux ✅ 已验证;Win / macOS 未验证 | Linux ✅ 已验证(`pw-record`,20 行);Win / macOS 未实现 |
| 额外依赖 | OBS + ffmpeg | 无 |
| 体积 | 35 MB(发行版包)~2.5 GB(flatpak) | 几 MB |
| 中间产物 | 会写出较大的视频文件再删(已压到 112 MB/小时) | 无 |
| 主要成本 | 三平台配置差异与 OBS 版本漂移 | 需自写三套原生采集(macOS SCK 最难) |
伴随程序必须运行在**声音实际播放的那台机器**上,所以「多端」的含义是:每台用于学习的设备都要装一份并各自配对;换了播放设备(例如改用手机听)该设备就必须有自己的采集能力。
### 录音-01 采集后端接口与 OBS 后端
- [x] 已实现并实测通过(模块已暂停,代码在分支)
- **涉及仓库**:`lpt-companion`,分支 `feature/study-recording`,HEAD `8d0969d`
- **完成于** `feature/study-recording` `8d0969d`;`main` 仅保留脚手架与说明
- **依据**:OBS 32.2.2 提供 Windows x64/arm64、macOS Apple/Intel、Ubuntu 24.04/26.04 发布;obs-websocket 5.x 自 OBS 28 内置。
- **已实测验证**(Linux / PipeWire / OBS 32.2.2 / obs-websocket 5.7.4):
1. 端到端可采到系统混音:OBS 日志 `pulse-input: Started recording from 'alsa_output...analog-stereo.monitor' (default)`,与非默认输出设备无关。
2. 采到的是**其他应用**的声音:用 `pw-cat`(非浏览器)播放 440 Hz,录出的音轨 FFT 主频精确为 440 Hz,峰值 9873。
3. 配置隔离成功:独立 `CreateProfile` / `CreateSceneCollection` / `CreateScene` / `CreateInput`,不影响用户已有配置。
4. 采集路径:OBS 录 Simple+mkv(320×240@5fps、200 kbps),抽出 Opus/Ogg 后删视频。中间文件约 112 MB/小时,最终音频约 18 MB/小时。
- **实现要点(踩坑记录均已写入 `lpt-companion/AGENTS.md`)**:`--profile`/`--collection` 首次运行会被忽略,改用 obs-websocket 的 `CreateProfile`;空场景集合必须先 `CreateScene`;输出模式/容器/画布变更必须重启 OBS(`prepare()` 用 `restartRequired` 告知);以 kill 结束 OBS 会留下 sentinel 导致卡在安全模式对话框;flatpak 版配置路径与启动方式不同。
- **OBS 侧的已知限制**:无法通过配置让 OBS 只录音频(`RecFormat2=ogg` 会因编码器不匹配产出 0 字节文件),故改走「录标准容器 + 用 ffmpeg 抽音轨」。
- **新增外部依赖**:抽音轨需要 `ffmpeg`(配置项 `media.ffmpegPath`);分发时需考虑自带或引导安装。
- **验收**:在未手动操作 OBS 界面的前提下,能从零建立独立配置并录出可播放的音频文件;用户已有的 OBS 配置不被改动。✅ 已验证
### 录音-02 控制通道与会话绑定
- [ ] 未完成
- **涉及仓库**:`lpt-be` + 伴随程序
- **依据**:Chrome 142+ 的 Local Network Access 权限使「网页直连本机端口」需要用户授权一次,且网页关闭会中断控制(实测见 录音-决策01)。
- **建议**(待确认):轮询式控制通道——网页只写 `lpt-be` 标记开始/结束,伴随程序带设备 token 轮询 `lpt-be` 取任务,音频由伴随程序直传 `lpt-be`。备选:直连 `127.0.0.1` 换取即时起停,代价是 LNA 授权与网页生命周期耦合。
- **验收**:网页发起后伴随程序在轮询周期内开始录音;关闭网页不影响录音继续与上传;未配对的设备无法拉取任务。
### 录音-03 音频落盘与对象存储
- [ ] 未完成
- **涉及仓库**:`lpt-be` + `lpt-infra`
- **依据**:`lpt-be` 现有 45 个端点全为 JSON,无任何文件上传能力(`MultipartFile` 零命中);`lpt-infra` 仅有 mysql 10Gi 与 lpt-logs 5Gi PVC,无对象存储。实测码率:Opus 32 kbps ≈ 14.8 MB/小时(未限码率时 58 MB/小时)。
- **建议**:录音元数据入业务库(会话、起止、时长、对象键、状态),音频本体入 S3/MinIO 兼容对象存储;分片上传并支持断点续传;长期保留。与 运维-01(备份异地)同源,建议一并规划。
- **验收**:一段会话录音可通过元数据定位并取回;上传中断后可续传;容量按 15 MB/小时可控增长。
### 录音-04 转写链路(provider 可配置)
- [ ] 未完成
- **涉及仓库**:`lpt-ai` + `lpt-be`
- **依据**:`lpt-ai` 目前只有 SiliconFlow OpenAI 兼容 chat(`Qwen/Qwen2.5-32B-Instruct`),无任何 ASR 能力;`AiServiceClient` 为同步轮询(见 AI-01 / AI-02)。
- **建议**:provider 在配置中切换 `online`(SiliconFlow 转写接口)/ `local`(whisper.cpp)/ `off`(只存音频),默认 `off`。
- **依赖**:AI-02 / AI-03。长音频转写若走同步链路,等于复制 AI-01 / AI-02 的问题。
- **验收**:切换配置即可改变转写来源;`off` 时全链路不因缺少转写而失败。
### 录音-05 录制可见性与隐私边界
- [ ] 未完成
- **涉及仓库**:`lpt-companion` + `lpt-fe`(或油猴脚本) + `lpt-docs`
- **依据**:录音采集的是系统混音,可能包含他人语音(线上会议、通话);采集范围由系统决定,用户无法逐条挑选;OBS 自身窗口可能被最小化到托盘,不足以充当「正在录音」的指示。
- **建议**:除了网页侧展示状态,伴随程序还要有常驻的本地可见指示,并提供一键停止;开始前明确说明采集范围与长期保留策略;未配对或未授权时不得开始录音。
- **待确认**:本地指示形态(托盘图标变化 / 常驻悬浮提示);他人语音的产品口径;会话暂停期间是否继续录音。
- **验收**:录制中存在不易忽略的可见指示;任意时刻可一键停止;停止后不再产生新分片。
### 录音-06 浏览器侧接入
- [ ] 未完成
- **涉及仓库**:`lpt-fe`(或独立油猴脚本)
- **依据**:浏览器侧只需发起、结束与展示状态,不接触音频。
- **建议**:优先直接接入 `lpt-fe`(类型安全、随应用版本发布);若仍使用油猴脚本,脚本只调用 `lpt-be` 接口,不持有音频。
- **待确认**:油猴脚本还是直接进 `lpt-fe`。
- **验收**:学习会话中可一键开始/结束录音,并看到状态与转写结果。
## 附录 A 核对方式(可复现)
- 代码核对:阅读 `lpt-be` 的 `service/impl/*`、`entity/*`、`controller/*`、`config/*`、`resources/application*.yml`、`resources/db/migration/*`;`lpt-fe/src` 的 `utils/request.ts`、`components/*`、`api/*`;`lpt-ai/src` 全部;`lpt-infra` 的 `dev/`、`prod/`、`traefik/`。
+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);