Compare commits

...
50 Commits
Author SHA1 Message Date
cat-shark 8222a50208 docs: lpt-android 补充分支与环境口径(master 生产包 / dev 开发包) 2026-11-08 17:59:53 +08:00
cat-shark af232b8156 docs: 登记 lpt-android 子项目 2026-11-08 17:39:28 +08:00
cat-shark da267fd55c docs: lpt-ai 分支改为 master/dev 双环境并记录分支环境对应 2026-11-08 14:36:59 +08:00
cat-shark ba16a65063 docs: 补充开发环境自解锁与求助阈值规则 2026-10-22 21:55:14 +08:00
cat-shark b1d1317491 docs: 记录 AI 降级与有效学习时间两条优化项 2026-10-22 21:55:14 +08:00
cat-shark 9bed0ac12f docs: 分支列改为默认拉取分支 2026-10-10 17:10:03 +08:00
cat-shark 701d22d51d docs: 同步推进顺序的收口状态 2026-10-10 17:03:43 +08:00
cat-shark 1307c30d2c docs: 标记闭环-04 完成并记录数据-05 2026-10-10 17:02:41 +08:00
cat-shark 285d11c0fe docs: 标记闭环-03 完成 2026-10-10 15:08:01 +08:00
cat-shark eb73ab69f1 docs: AGENTS 瘦身,通用规则移入 roles 目录 2026-10-10 15:07:44 +08:00
cat-shark a6243c0887 docs: 标记闭环-02/03 后端完成并记录数据-04 2026-10-10 15:02:20 +08:00
cat-shark 58c4a5161e docs: 规则文件统一为名称/功能/何时用三段开头 2026-10-10 14:53:10 +08:00
cat-shark 7767fbd689 docs: 修正规则文件中的复制范围描述 2026-10-10 14:41:33 +08:00
cat-shark 5b5a8ae7e9 docs: 标记闭环-01 完成 2026-10-10 14:38:55 +08:00
cat-shark 5da4192bed docs: 通用规则收口径到 .agents/roles 2026-10-10 14:38:43 +08:00
cat-shark d3e7f713d8 docs: 建立通用规则目录并落 todo 收口纪律 2026-10-10 14:34:23 +08:00
cat-shark d5896498c1 docs: 补充并行与委派规则 2026-10-10 14:27:43 +08:00
cat-shark d35cb40222 docs: 标记闭环-05 完成 2026-10-10 14:25:07 +08:00
cat-shark 7efb9ca900 docs: 记录学习闭环重构决策 2026-10-10 14:21:06 +08:00
cat-shark acc49a4d5c docs: 整理学习闭环改动清单 2026-10-10 13:42:56 +08:00
cat-shark af65fe1ca6 docs: 补齐清单状态列 2026-10-09 19:49:58 +08:00
cat-shark b4914c41a9 docs: 登记归属-01/报告-01/标记-01/复习-02/复习-06 完成 2026-10-09 19:49:41 +08:00
cat-shark fb9a26f456 docs: 登记复习-04/05 完成 2026-10-09 19:36:11 +08:00
cat-shark fa46e1f5bd docs: 明确报告分段顺序 2026-10-09 19:33:04 +08:00
cat-shark 884a5ba576 docs: 登记复习相关条目后端实施进度 2026-10-09 19:31:25 +08:00
cat-shark a4b0ac63d9 docs: 清理-01 决策完成 2026-10-09 17:50:48 +08:00
cat-shark dc1e1a4a0f docs: 运维-01 记录暂缓决定 2026-10-09 17:50:15 +08:00
cat-shark 2558cbdd26 docs: 复习-01 决策完成并汇总实现要点 2026-10-09 17:48:18 +08:00
cat-shark df5cd79aab docs: 复习-01 记录反馈动作决策并收敛 4 项口径 2026-10-09 17:28:38 +08:00
cat-shark 136265272a docs: 标记-01 决策完成并汇总实现要点 2026-10-09 17:23:31 +08:00
cat-shark 7b3525d584 docs: 记录标记检索入口的决策 2026-10-09 17:21:17 +08:00
cat-shark e1391d1096 docs: 记录标记值存法的决策 2026-10-09 17:17:59 +08:00
cat-shark 7d9b66a84e docs: 记录标记可挂对象与标记名受控方式的决策 2026-10-09 17:11:44 +08:00
cat-shark 8a72580258 docs: 归属-01 决策完成并汇总实现要点 2026-10-09 16:38:50 +08:00
cat-shark d6e61d534b docs: 记录老报告过渡与历史碎片上下文的决策 2026-10-09 16:37:40 +08:00
cat-shark 04cc862a25 docs: 记录报告分组实时聚合的决策 2026-10-09 16:34:15 +08:00
cat-shark 794ae7a53f docs: 记录报告删除与任务删除的决策 2026-10-09 16:32:33 +08:00
cat-shark c557fe4939 docs: 记录报告与碎片修订范围的决策 2026-10-09 16:22:16 +08:00
cat-shark 243e532462 docs: 登记安全-02/03 与复习-03 完成,记录安全-01 暂缓决策 2026-10-09 15:53:39 +08:00
cat-shark 7eb346b260 docs: 问题汇报改为根因/修复方案/影响范围三段式 2026-10-09 15:43:24 +08:00
cat-shark e13a19c0c5 docs: 补充 AI-02 前端提交记录 2026-10-09 15:22:10 +08:00
cat-shark 84f2e06f09 docs: 登记 AI-01/02/04 与数据-02 完成 2026-10-09 15:09:06 +08:00
cat-shark 94c807ef30 docs: 登记会话-04/05、导出-01、数据-03 完成 2026-10-09 12:44:10 +08:00
cat-shark 4cf0ddb681 chore: 迁移 mermaid 绘图技能到 meta 层 2026-10-09 12:28:53 +08:00
cat-shark 4bb42385e8 docs: 补充复习-07 重构提交 2026-10-09 11:53:59 +08:00
cat-shark 6b085fb2e3 docs: 登记复习-07 完成 2026-10-09 11:17:09 +08:00
cat-shark 0b9bb674af docs: 更新索引与 SQL 日志条目完成状态 2026-10-09 10:52:47 +08:00
cat-shark 59df390ce8 docs: 更新会话结算条目完成状态 2026-10-09 10:48:30 +08:00
cat 76cdf6ad3c docs: 登记 AI-03 完成并复核基线 2026-10-08 17:33:09 +08:00
cat e980984b62 docs: 录音模块暂停并记录分支 2026-10-08 17:25:13 +08:00
18 changed files with 1822 additions and 154 deletions
+63
View File
@@ -0,0 +1,63 @@
# 通用规则(`.agents/roles/`)
存放**跨仓库通用的代理行为规则**。
目录名叫 `roles`,但里面不放「角色扮演」式定义(没有「你是某某角色、你的职责是……」),
**只记录规则本身**:什么情况下必须做什么、怎么核对。
## 放什么,不放什么
判断标准只有一句:**这条规则换到另一个仓库还成立吗?**
| 内容 | 位置 | 例子 |
|------|------|------|
| 通用规则(不限仓库) | meta 仓库 `.agents/roles/` | 提交规范、调研汇报、并行委派 |
| 项目专属规则 | 各仓库自己的 `roles/` | 后端的迁移规范、前端的代码标准 |
| 项目知识与架构约定 | 各仓库 `AGENTS.md` | 端口、调用关系、命名约定 |
| 跨仓库待办与验收标准 | `OPTIMIZATION_BACKLOG.md` | 优化条目 |
| 工作区级技能 | `.agents/skills/` | `mermaid-diagram` |
| 项目专属技能 | 各仓库自己的 `skills/` | `lpt-be/skills/comment-cleanup` |
## 生效方式(重要)
**`.agents/roles/` 不是自动加载入口。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用——
`AGENTS.md` 是每次会话自动加载的项目指令入口,只有它(和按描述触发的 skills)会被读到。
所以:新增规则时,务必同时在 `AGENTS.md` 对应章节挂上入口。
配套事实:pi 加载 `AGENTS.md` 时会同时读**工作目录及其父目录**。
因此在 `lpt-be` 这类子目录里干活时,meta 的 `AGENTS.md` 仍会被读到——
这正是各子项目不再重复通用规则的前提。
## 规则文件的写法(强制)
每个规则文件的**开头必须是如下三段**,顺序不变,方便 agent 在决定是否继续读之前就能判断该不该用:
1. **名称**——作为 `#` 一级标题;
2. **功能简述**——一句话说明这条规则解决什么问题;
3. **关键字 / 情况**——告诉 agent **何时需要用到这条规则**。这部分要简洁(一行枚举触发场景即可),**不要在这里展开内容**,正文放到后面。
模板:
```markdown
# <名称>
- **功能**:<一句话说明这条规则做什么>
- **何时用**:<触发场景 / 关键字的简短枚举>
## <正文…>
```
新增或修改规则后自查:标题是名称?有「功能」行?有「何时用」行?「何时用」是否够短?
## 规则清单
| 规则 | 文件 | 何时用(触发点) |
|------|------|--------|
| todo 收口纪律 | `todo-discipline.md` | 提交后 / 轮末 / 会话压缩后 |
| 并行与委派 | `parallel-and-delegation.md` | 开工排期、派发子任务时 |
| 提交规范 | `commit-convention.md` | 写提交信息时 |
| 调研与问题定位 | `research-and-reporting.md` | 调研/排查/定位问题类任务 |
| Windows / PowerShell 环境 | `shell-environment.md` | 执行 shell 命令、报错排查时 |
| 工作区资产归属 | `workspace-layout.md` | 决定文档/规则/技能放哪时 |
| 跨仓库 Git 操作 | `repo-operations.md` | 对子项目执行 git 命令时 |
| 开发环境自解锁与求助阈值 | `dev-unblock-and-escalation.md` | 被登录/权限/凭据卡住、同一问题反复尝试未解决时 |
+11
View File
@@ -0,0 +1,11 @@
# 提交规范
- **功能**:统一本工作区所有仓库的提交信息格式,让提交历史一眼可读。
- **何时用**:准备 `git commit` 时;写提交信息时;判断该用哪个类型前缀时。
## 规则
- 提交信息必须简短且使用中文,不要使用英文长句。
- 格式:`类型: 简述`,例如 `docs: 更新说明`、`feat: 新增用户登录接口`、`fix: 修复多租户拦截器空指针`、`perf: Feed 只返回摘要`。
适用于 meta 与全部子项目仓库。各仓库不必再重复这段规则,示例可按仓库语境自选。
@@ -0,0 +1,23 @@
# 开发环境自解锁与求助阈值
- **功能**:规定在开发环境被登录、凭据、权限等环境性障碍卡住时,如何用可控的临时手段自行解锁,以及何时必须停下来向用户求助。
- **何时用**:开发环境中复现/验证被登录或权限拦住时;缺凭据、缺测试数据、缺开关导致无法推进时;同一问题连续尝试多轮仍未解决时。
## 规则
### 自行解锁优先
- 在开发环境(本地 / dev 环境)里,若因登录、鉴权、凭据或测试数据缺失而无法完成验证,允许**临时修改被测系统**来打通路径,例如临时调整后端登录接口、放开某条校验、注入测试账号或数据。
- 临时改动必须满足:只在开发环境生效;范围最小、位置集中、一眼可识别;不提交、不混入业务改动。
- 解锁完成后必须**还原临时改动**,并在最终汇报里说明「改了什么、是否已还原」;若无法还原,必须明确标出并提示用户。
- 禁止用复杂且会污染运行环境的绕过手段(伪造会话状态、拦截网络请求、长时间改配置等)替代直接、可控的临时解锁。
### 尝试预算与求助阈值
- 对同一个目标,若连续尝试达到 **5 次**仍未解决,立即停止继续加码。
- 出现以下任一情况时,不再自行尝试,直接询问用户:
- 无法用可控的临时手段解锁,或解锁本身有风险、会破坏环境;
- 同一目标尝试达到 5 次仍未解决;
- 障碍超出自身可处理范围(需要外部凭据、他人授权、环境权限)。
- 求助时必须**把问题描述清楚**,至少包含:想做什么、卡在哪一步、已经尝试了什么及结果、需要用户提供什么(凭据 / 决策 / 环境操作)。
- 不要在信息不足时硬猜或反复试探;一次清晰的提问优于多次无效尝试。
+39
View File
@@ -0,0 +1,39 @@
# 并行与委派
- **功能**:把「什么时候并行、什么时候串行、怎么派活」固定下来,避免串行浪费时间、也避免盲目并行互相覆盖。
- **何时用**:开工排期时;判断多个任务该并行还是串行时;派发子任务给 subagent 时;同一目录出现第二个写入者时;跨仓库同时改动时。
## 为什么有这条规则
本工作区是多仓库结构(meta + 5 个子项目),可并行的活儿很多,但同一目录只允许一个写入者。
串行推进浪费最大,盲目并行会互相覆盖。这条规则把「什么时候并行、什么时候串行、怎么派活」固定下来。
2026-10-10 之前,这条规则被复制到了**全部 5 个仓库**的 `AGENTS.md`,而且各仓库的条目数与措辞都不一致:
meta 与 lpt-be / lpt-fe 各 4 条,lpt-ai 3 条,lpt-docs 2 条(且混着一条 lpt-docs 专属条款),
meta 还把它混在「工作区规则」里。同一套约束在 5 个仓库里各不相同。
现在统一到本文件,各仓库不再重复。
## 规则
### 默认并行
不同子项目之间、或同一项目内互不依赖的任务,**必须同时推进**,不要逐个串行。
不要凭「感觉」判定可以串行。
### 只有真实依赖才串行
存在真实依赖(后一步要用前一步的产出)时才串行,并在派发说明里写明依赖点。
### 同一目录单写入者
同一仓库 / 工作目录同时只允许一个写入者。第二个写入者要么等,要么用 worktree 隔离。
### 派发说明要写全
派发子任务时把**已确认口径、涉及文件、验收命令、提交信息**写清楚。
信息不全的子任务会退回,不要用「你看着办」代替。
### meta 仓库只由主代理写
`OPTIMIZATION_BACKLOG.md` 只由主代理更新,子代理不要改(避免 meta 仓库并发写);
完成情况由主代理统一记录。
+11
View File
@@ -0,0 +1,11 @@
# 跨仓库 Git 操作
- **功能**:规定在 meta 工作区里对子项目仓库执行 Git 与文件操作的方式,避免误提交、误删除、用错路径。
- **何时用**:对子项目执行 git 命令时;clone 子项目时;子项目目录存在但不是 Git 仓库时;需要跨仓库批量操作时;派发子任务到某个子项目时。
## 规则
- 可并行的工作优先用 `subagent` 派到对应子项目执行。
- 不要删除子项目内的 `.git`,也不要对子项目执行跨仓库的 `git add .`。
- 对子项目执行 Git 操作时使用 `git -C lpt-be <command>` 这类形式。
- 如果某个子项目目录已存在但不是 Git 仓库,或 clone 因 SSH 权限/网络失败,应停止并说明原因,不要用空目录或本地副本替代。
+20
View File
@@ -0,0 +1,20 @@
# 调研与问题定位
- **功能**:约束「调研、排查、定位问题」类任务的推进方式与汇报格式,避免发散式尝试、避免把推测当结论。
- **何时用**:任务是调研 / 排查 / 定位问题时(例如「现象是不是这个改动引起的」「为什么这里变慢了」);根因不明、需要先取证时;同一方向连续失败两次时。**不适用于已有明确改法的一次性修改。**
## 规则
- 本规则适用于「调研、排查、定位问题」类任务(例如“现象是不是这个改动引起的”“为什么这里变慢了”),不适用于已有明确改法的一次性修改。
- 「1 轮调研」指一条连续的最小验证路径:确认现象范围 → 对比可疑改动 → 拿到可复现/可量化的证据。
- 如果 1 轮调研后仍未定位到根因,必须停止自行扩大调查范围,先向用户汇报,由用户决定是否继续调查或调整方向。
- 汇报必须按以下**固定三段式**表述,顺序不变;只写结论与关键证据,不要罗列调查过程:
1. **根因**:问题的直接原因,以及支撑它的证据(命令、文件、提交、返回值)。没有证据的推测禁止写进这一段。
- 附上已排除的可能原因及排除依据。
2. **修复方案**:怎么改。分为「必做 / 建议做 / 不建议做」三类,每项标注代价、以及由谁执行(我 / 用户)。
- 附上当前卡点:还缺哪个信息、需要谁提供。
3. **影响范围**:受影响的功能、用户、环境与数据;不修会怎样;修了会不会连带影响其它东西。
- 三段式之外不另起新段式;额外信息(已排除项、卡点)归到对应段落下面。
- 先用一句话给出结论,再展开三段;不要让用户从推导过程里自己提炼结论。
- 汇报后等待用户决定,不要一边汇报一边继续发散式尝试;同一方向连续失败两次就转为汇报。
- 禁止把「可能是 X」直接当成结论去改代码;只有拿到证据的结论才允许进入修改阶段。
+27
View File
@@ -0,0 +1,27 @@
# Windows / PowerShell 环境
- **功能**:约束本机 shell 的用法,避免把 Bash 语法交给 PowerShell、避免 Windows 兼容与编码坑。
- **何时用**:执行 shell 命令时;命令报 `ParserError` / `CommandNotFoundException` / `ParameterBindingException` / `Cannot find path` / Python `SyntaxError` 时;要写脚本、处理引号或中文编码时;操作 Windows 原生组件时;同一命令连续失败两次后。
## 规则
- 默认 shell 视为 Windows PowerShell 5.1;不要假设 Bash、zsh 或 PowerShell 7。必要时先查 `$PSVersionTable.PSVersion`、`Get-Command pwsh -ErrorAction SilentlyContinue`。
- Windows 桌面、Visual Studio/MSBuild、WPF/WinForms/WinUI、COM、注册表、服务、系统托盘、PyInstaller、UI 自动化等任务优先用 Windows 原生环境;不要默认切 WSL。
- 仅在 Linux 部署、Bash 脚本、Linux 工具链或项目本身位于 WSL 时考虑 WSL;跨环境前确认仓库路径、依赖和运行目标。
- 禁止把 Bash 语法交给 PowerShell:`python - <<'PY'`、`cat <<EOF`、`export`、`source`、`rm -rf`、`cp -r`、`xargs`、Bash 后台 `&`。
- PowerShell 中 `&` 是调用运算符;URL 或参数含 `&` 时整体单引号引用。
- 避免 PowerShell 5.1 下使用 Bash 风格 `&&` / `||`;顺序步骤用多行 PowerShell、短命令或多次工具调用。
- 参数含空格、括号、中文、`&|;><$` 或引号时默认用单引号;只有需要变量插值时才用双引号。
- 外部程序路径可能有空格时,用 `& 'C:\path with spaces\tool.exe' arg1`;多参数外部命令优先数组 splatting。
- PowerShell 数组传给外部程序时直接 splat;不要把多个路径或参数拼成一个带空格的字符串。
- 文件操作优先 PowerShell 原生命令和 `-LiteralPath`;遇到参数不存在先按 PowerShell 5.1 兼容写法处理。
- 复杂 Python 不用 `python -c`;涉及 SQL、JSON、中文、反斜杠路径、换行或多层引号时,用仓库脚本、临时 `.py` 或 `apply_patch`。
- 禁止在 PowerShell 用 Bash here-doc。临时传 Python 源码只允许 PowerShell here-string,且尽量保持 ASCII。
- Python 源码含中文常量时,不通过 PowerShell 管道传给 `python -`;用 UTF-8 脚本文件、仓库脚本或 `\uXXXX`。
- 不只依赖 `chcp 65001` 解决编码;必要时同时设置 `$OutputEncoding`、`[Console]::InputEncoding`、`[Console]::OutputEncoding`、`PYTHONUTF8`、`PYTHONIOENCODING`。
- 搜索文本/文件优先 `rg` / `rg --files`;多个根目录作为多个独立参数传入。
- `sqlite3.exe` 不存在时用 Python `sqlite3` 查询,不反复尝试不存在的 CLI。
- 编辑文件优先 `apply_patch`;不要用复杂 PowerShell 字符串重写文件。
- 数据库或生产内容写操作前先查询当前数据;写入必须有明确筛选条件,禁止无条件 `DELETE` / `UPDATE`。
- 出现 `ParserError`、`CommandNotFoundException`、`ParameterBindingException`、`Cannot find path`、Python `SyntaxError` 时,先排查 shell 语法、引用、PATH、PowerShell 5.1 兼容和 `workdir`。
- 同一 PowerShell 命令连续失败两次后,停止微调长命令;改短命令、脚本文件、数组 splatting 或分步验证。
+57
View File
@@ -0,0 +1,57 @@
# todo 收口纪律
- **功能**:让待办列表始终反映真实进度——做完的事当场收口,不留「已经做完、却还显示未完成」的陈旧条目。
- **何时用**:创建或更新 todo 时;一项工作做完时;`git commit` 成功后;准备发出最终回复前;会话被压缩后;发现待办状态与事实不符时。
## 为什么有这条规则
2026-10-09 的一次会话里:`todo` 工具 `create` 23 次,`update` 只有 14 次——
**13 条(57%)从未被标记完成**,而它们对应的活儿全都做完并提交了。
表现是待办面板长期显示一堆「未完成」,看起来像插件不显示完成态,实际是**没人去收口**。
放大因素(都真实发生过):
- 批量创建后跨多轮续跑,缺少「收口上一条」这个动作的触发点;
- 多项经 subagent 执行,子代理返回、验证后直接进入下一步;
- **会话被压缩后,压缩摘要与 todo 列表漂移**,没人对账;
- 插件会把已完成项在下一轮隐藏(其既定设计),使遗漏反而更不容易被看见。
## 规则
三条都有明确触发点——不需要「记得」,只需要在触发点做一次。
### R1 提交后立即收口
**触发点**:`git commit` 成功。
每次提交成功后,**立刻**把这次提交覆盖的 todo 标为 `completed`。
提交是本项目工作的收尾动作,触发点天然存在,不依赖记性。
### R2 轮末对账
**触发点**:准备发出最终回复前。
发最终回复前跑一次 `todo list`,凡是「实际已完成、但状态仍是 `pending` / `in_progress`」的,
一律收口。对账是幂等的:没有遗漏时它就是一次空转。
### R3 压缩后对账
**触发点**:会话被压缩、出现压缩摘要之后。
压缩摘要与 todo 列表是两套状态,压缩后先对账一次再继续干活。
本规则正是从压缩后漂移的场景里总结出来的。
## 边界
- **不得为收口而收口**:测试失败、实现不完整、仍有未解决报错时保持 `in_progress`,
并为阻塞另建条目(既有约定不变)。
- 建议单批条目不超过 5 条。本规则的诞生场景里 23 条远超面板默认 12 行预算,
本来看不全,也更难发现自己漏维护。这是建议,不是硬规则。
- 这些 todo 只是会话内草稿(插件不写盘,状态由会话分支重放),
收口不涉及代码、数据库或任何仓库内容。
## 怎么核对
- `todo list` 看最终状态分布;
- 需要复盘时,重放会话文件里的 `todo` 调用,统计 `create` 与 `update` 次数是否匹配。
+24
View File
@@ -0,0 +1,24 @@
# 工作区资产归属
- **功能**:规定各类文档与产物放在哪个仓库/目录,避免重复、错位与正文复制。
- **何时用**:新增或修改文档时;决定某段说明该写进哪个仓库时;处理优化清单时;判断某个文件是否该出现在 meta 仓库时;放规则或技能时。
## 规则
### 文档归属
- 所有系统文档统一在 `lpt-docs` 仓库维护,代码仓库不保留 README、`docs/` 等文档文件。
- `lpt-docs` 只维护系统概念描述和设计思路,不保存开发记录、系统中间态和开发过程产物。
- 跨仓库的实现优化清单记录在 meta 仓库 `OPTIMIZATION_BACKLOG.md`(只放待办、依据与验收标准);概念与设计仍归 `lpt-docs`。
- 修改 `lpt-docs` 后,如需在 meta 仓库补充说明,保持 meta 仓库不复制文档正文。
### meta 仓库的维护边界
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能与通用规则)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
- `.gitignore` 忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。
### 规则与技能的落位
- 通用规则(跨仓库)→ meta 仓库 `.agents/roles/`。
- 项目专属规则 → 该仓库自己的 `roles/`。
- 工作区级技能 → `.agents/skills/<技能名>/`;子项目专属技能 → 该仓库 `skills/`。
+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
+35 -61
View File
@@ -1,51 +1,56 @@
# LPT Workspace Meta-Repo
本仓库不是产品项目,不包含前后端业务代码。它只作为本地工作区协调仓库,用于让 Codex 一次性了解多个独立项目,并在缺失子项目时自动拉取。
本仓库不是产品项目,不包含前后端业务代码。它只作为本地工作区协调仓库,用于让 agent 一次性了解多个独立项目,并在缺失子项目时自动拉取。
## 调研与问题定位规则
## 规则与技能位置
- 本规则适用于「调研、排查、定位问题」类任务(例如“现象是不是这个改动引起的”“为什么这里变慢了”),不适用于已有明确改法的一次性修改。
- 「1 轮调研」指一条连续的最小验证路径:确认现象范围 → 对比可疑改动 → 拿到可复现/可量化的证据。
- 如果 1 轮调研后仍未定位到根因,必须停止自行扩大调查范围,先向用户汇报,由用户决定是否继续调查或调整方向。
- 汇报必须包含以下内容,缺一不可:
- 已确认的事实与证据(具体命令、文件、提交、返回值,而不是推测)。
- 已排除的可能原因(以及排除依据)。
- 当前卡点:还缺哪个信息、需要谁提供(例如用户登录凭据、某个环境的数据量、一次控制台取样)。
- 建议的后续方案(1-3 个,标注推荐项与各自代价)。
- 汇报后等待用户决定,不要一边汇报一边继续发散式尝试;同一方向连续失败两次就转为汇报。
- 禁止把「可能是 X」直接当成结论去改代码;只有拿到证据的结论才允许进入修改阶段。
- **通用规则(跨仓库)**:`.agents/roles/`
- `todo-discipline.md` 待办收口 · `parallel-and-delegation.md` 并行与委派 · `commit-convention.md` 提交规范
- `research-and-reporting.md` 调研与问题定位 · `shell-environment.md` Windows/PowerShell · `workspace-layout.md` 资产归属 · `repo-operations.md` 跨仓库 Git 操作
- `dev-unblock-and-escalation.md` 开发环境自解锁与求助阈值
- **各子项目专属规则**:该仓库自己的 `roles/`(如 `lpt-be/roles/`、`lpt-fe/roles/`)
- **工作区级技能**:`.agents/skills/<技能名>/`
- **子项目专属技能**:该仓库自己的 `skills/`(如 `lpt-be/skills/`)
## 提交规范
- 提交信息必须简短且使用中文,不要使用英文长句。
- 格式:`类型: 简述`,例如 `docs: 更新说明`。
> 规则文件开头必须是三段:名称(一级标题)→ 功能简述 → 关键字/情况(何时用,要简短,正文放后面)。
> 规则与技能的存放边界见 `.agents/roles/workspace-layout.md`。
## 本仓库
| 项目 | SSH 地址 | 建议分支 |
|------|----------|----------|
| 项目 | SSH 地址 | 默认拉取分支 |
|------|----------|--------------|
| LPT meta | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git` | `main` |
> 「默认拉取分支」只用于首次初始化:新人或 LLM 按这一列拉取仓库。它不表示当前的工作分支,实际在哪个分支上开发由维护者决定,不要据此推断。
## 仓库结构
| 目录 | 用途 |
|------|------|
| `lpt-docs` | 概念与设计文档项目,只维护系统概念和设计思路 |
| `lpt-be` | Java Spring Boot 后端,提供 REST API、认证、数据库访问 |
| `lpt-fe` | Vue 3 + TypeScript 前端 |
| `lpt-ai` | TypeScript + Fastify 独立 AI 服务 |
| `lpt-android` | Android 客户端(Kotlin + Compose),学习会话 + 系统级悬浮窗 |
| `lpt-infra` | Kubernetes / Traefik 部署与基础设施清单 |
| `lpt-docs` | 概念与设计文档项目,只维护系统概念和设计思路 |
> 图表评审产物在 `docs/diagrams/`。
## 子项目 Git 仓库
| 目录 | SSH 地址 | 建议分支 |
|------|----------|----------|
| 目录 | SSH 地址 | 默认拉取分支 |
|------|----------|--------------|
| `lpt-be` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-be.git` | `master` |
| `lpt-fe` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-fe.git` | `master` |
| `lpt-ai` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-ai.git` | `main` |
| `lpt-ai` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-ai.git` | `master` |
| `lpt-android` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-android.git` | `master` |
| `lpt-infra` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-infra.git` | `master` |
| `lpt-docs` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-docs.git` | `main` |
> 「默认拉取分支」只用于首次克隆初始化,下面 `git clone -b` 用的就是这一列。clone 完成后不要假定工作分支:动手前先 `git branch --show-current` 看仓库实际所在分支。
>
> **分支 ↔ 环境对应**:`lpt-be` / `lpt-fe` / `lpt-ai` 均为「`master` → prod、`dev` → dev」,部署流水线第一步会校验两者匹配,跨环境出包(例如用 `dev` 发 prod)会被直接拒绝;`lpt-ai` 的 `main` 是历史分支(停在 prod 冻结点),不再用于发版。`lpt-infra` 单分支(`master`),靠 `dev/` 与 `prod/` 目录区分清单。`lpt-android` 为「`master` → 生产包、`dev` → 开发包」,两个分支**只差默认 API 地址**,不参与 k8s 部署(构建在 Gitea 手动触发,第一步会校验分支与默认地址是否匹配)。`lpt-docs` 不参与部署。
## 首次初始化
首次 clone 本仓库:
@@ -54,63 +59,32 @@
git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git lpt-meta
```
只拉取本 meta 仓库时,下列子项目目录不会包含在 Git 内容中。Codex 在开始任务前应检查目录是否存在;如果缺失,直接自动 clone,无需用户手动操作:
只拉取本 meta 仓库时,下列子项目目录不会包含在 Git 内容中。agent 在开始任务前应检查目录是否存在;如果缺失,直接自动 clone,无需用户手动操作:
```bash
git clone -b master ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-be.git lpt-be
git clone -b master ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-fe.git lpt-fe
git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-ai.git lpt-ai
git clone -b master ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-ai.git lpt-ai
git clone -b master ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-android.git lpt-android
git clone -b master ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-infra.git lpt-infra
git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-docs.git lpt-docs
```
clone 完成后,进入或修改某个子项目前,先读取该子项目根目录的 `AGENTS.md`;如果缺失,则读取 `README.md`。
## 工作区规则
- 本 meta 仓库只维护 `AGENTS.md` 和 `.gitignore`,不要在本仓库根目录创建业务代码或文档。
- `.gitignore` 忽略所有子项目目录,避免把独立 Git 仓库提交进本 meta 仓库。
- 不要删除子项目内的 `.git`,也不要对子项目执行跨仓库的 `git add .`。
- 对子项目执行 Git 操作时使用 `git -C lpt-be <command>` 这类形式。
- 如果某个子项目目录已存在但不是 Git 仓库,或 clone 因 SSH 权限/网络失败,应停止并说明原因,不要用空目录或本地副本替代。
## 文档维护
- 所有系统文档统一在 `lpt-docs` 仓库维护,代码仓库不保留 README、`docs/` 等文档文件。
- 代理协作规范保留在各仓库 `AGENTS.md`。
- `lpt-docs` 只维护系统概念描述和设计思路,不保存开发记录、系统中间态和开发过程产物。
- 跨仓库的实现优化清单记录在本仓库 `OPTIMIZATION_BACKLOG.md`(只放待办、依据与验收标准);概念与设计仍归 `lpt-docs`。
- 修改 `lpt-docs` 后,如需在 meta 仓库补充说明,保持 meta 仓库不复制文档正文。
## 跨项目调用关系
```text
浏览器 → lpt-fe (5158) ──/api──→ lpt-be (5157) ──HTTP──→ lpt-ai (5199)
│
Android → lpt-android ──/api──────────┤
└── MySQL
```
lpt-android 通过 REST 直连后端,认证走 Sa-Token 请求头 `satoken`,只使用学习会话相关端点。
lpt-infra 提供 dev/prod 的 Kubernetes 清单和 Traefik 路由。
## Windows / PowerShell 全局规则
## 图表
- 默认 shell 视为 Windows PowerShell 5.1;不要假设 Bash、zsh 或 PowerShell 7。必要时先查 `$PSVersionTable.PSVersion`、`Get-Command pwsh -ErrorAction SilentlyContinue`。
- Windows 桌面、Visual Studio/MSBuild、WPF/WinForms/WinUI、COM、注册表、服务、系统托盘、PyInstaller、UI 自动化等任务优先用 Windows 原生环境;不要默认切 WSL。
- 仅在 Linux 部署、Bash 脚本、Linux 工具链或项目本身位于 WSL 时考虑 WSL;跨环境前确认仓库路径、依赖和运行目标。
- 禁止把 Bash 语法交给 PowerShell:`python - <<'PY'`、`cat <<EOF`、`export`、`source`、`rm -rf`、`cp -r`、`xargs`、Bash 后台 `&`。
- PowerShell 中 `&` 是调用运算符;URL 或参数含 `&` 时整体单引号引用。
- 避免 PowerShell 5.1 下使用 Bash 风格 `&&` / `||`;顺序步骤用多行 PowerShell、短命令或多次工具调用。
- 参数含空格、括号、中文、`&|;><$` 或引号时默认用单引号;只有需要变量插值时才用双引号。
- 外部程序路径可能有空格时,用 `& 'C:\path with spaces\tool.exe' arg1`;多参数外部命令优先数组 splatting。
- PowerShell 数组传给外部程序时直接 splat;不要把多个路径或参数拼成一个带空格的字符串。
- 文件操作优先 PowerShell 原生命令和 `-LiteralPath`;遇到参数不存在先按 PowerShell 5.1 兼容写法处理。
- 复杂 Python 不用 `python -c`;涉及 SQL、JSON、中文、反斜杠路径、换行或多层引号时,用仓库脚本、临时 `.py` 或 `apply_patch`。
- 禁止在 PowerShell 用 Bash here-doc。临时传 Python 源码只允许 PowerShell here-string,且尽量保持 ASCII。
- Python 源码含中文常量时,不通过 PowerShell 管道传给 `python -`;用 UTF-8 脚本文件、仓库脚本或 `\uXXXX`。
- 不只依赖 `chcp 65001` 解决编码;必要时同时设置 `$OutputEncoding`、`[Console]::InputEncoding`、`[Console]::OutputEncoding`、`PYTHONUTF8`、`PYTHONIOENCODING`。
- 搜索文本/文件优先 `rg` / `rg --files`;多个根目录作为多个独立参数传入。
- `sqlite3.exe` 不存在时用 Python `sqlite3` 查询,不反复尝试不存在的 CLI。
- 编辑文件优先 `apply_patch`;不要用复杂 PowerShell 字符串重写文件。
- 数据库或生产内容写操作前先查询当前数据;写入必须有明确筛选条件,禁止无条件 `DELETE` / `UPDATE`。
- 出现 `ParserError`、`CommandNotFoundException`、`ParameterBindingException`、`Cannot find path`、Python `SyntaxError` 时,先排查 shell 语法、引用、PATH、PowerShell 5.1 兼容和 `workdir`。
- 同一 PowerShell 命令连续失败两次后,停止微调长命令;改短命令、脚本文件、数组 splatting 或分步验证。
- 工作区级技能 `mermaid-diagram`:按业务主题在 `docs/diagrams/<主题>/` 出图并本地起服务评审。用法见 `.agents/skills/mermaid-diagram/SKILL.md`。
- 图表根目录为 `docs/diagrams/`,共享渲染器 `docs/diagrams/viewer.js`,主题索引 `docs/diagrams/index.html`。
+565 -93
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,37 +31,53 @@
| 模块 | 条目 | 优先级 | 状态 | 需要先定什么 |
|------|------|--------|------|--------------|
| 学习会话生命周期 | 会话-01 遗忘检测路径不统一 | P0 | 可直接实施 | — |
| | 会话-02 `isOverTime()` 误报超时 | P0 | 可直接实施 | — |
| | 会话-03 结束会话不幂等 | P0 | 可直接实施 | — |
| | 会话-04 悬挂会话无收敛 | P0 | 待决策 | 收敛方式(惰性 / 定时扫描 / 并用)+ 2 小时硬兜底阈值 |
| | 会话-05 活跃会话拦截无出路 | P1 | 待决策 | 出口形式(结束并开始新任务 / 放弃会话),建议与会话-04 同批 |
| 内容归属与报告 | 归属-01 内容归属与待归类 | 待实施 | 设计已确认 | 实现级取舍:碎片表如何承载归属、报告字段拆分、归类交互落点 |
| | 报告-01 报告与碎片不可修订 | P1 | 待设计 | 与归属-01 同批改报告结构;修订与删除的边界(软删除、历史报告标记) |
| 标记与元信息 | 标记-01 统一标记存储 | P1 | 待决策 | 可挂对象;标记名受控方式;标记值类型;按标记检索;标记名治理与可见性 |
| 复习 | 复习-01 复习回路补全 | 待确认 | 待决策(6 项) | Feed 是否含报告;反馈动作形态;覆盖率口径;待归类呈现;遗漏项语义;排序可配置性 |
| | 复习-02 Feed 只读无反馈动作 | P1 | 依赖复习-01 | 反馈动作形态(复习-01 第 2 项) |
| | 复习-03 Feed 随机取样 | P3 | 待决策 | id 区间随机 / 候选池 / 时间窗口随机 |
| | 复习-04 覆盖率查询拉全量 | P3 | 依赖复习-01 | 覆盖率口径(复习-01 第 3 项) |
| | 复习-05 Feed 返回全文 | P3 | 依赖复习-01 | 条目单位与摘要口径(复习-01 第 1 项) |
| | 复习-06 学习引导 | P1 | 已确认待实施 | 依赖 AI-02 / AI-03,以及标记-01 的存储设计 |
| | 复习-07 复习耗时统计 | P2 | 可直接实施(口径已定) | — |
| AI 链路 | AI-01 事务内同步等 AI | P2 | 待决策 | 事务外纯读对比(小改)/ 任务表 + 异步回写 |
| | AI-02 全链路同步阻塞 | P2 | 可实施(方案已定) | 若 AI-01 选任务表方案,则与 AI-01 同批 |
| | AI-03 单 worker 串行无重试 | P2 | 可直接实施 | — |
| | AI-04 防并发锁是 JVM 内存锁 | P2 | 可直接实施 | 需确认「生成中」的对外语义(返回任务状态而非实体) |
| 数据与检索 | 数据-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 | 可直接实施 | — |
| 运维与清理 | 运维-01 备份只在同一 PVC | P4 | 待决策 | 异地 / 对象存储目标选型,需你提供目标 |
| | 清理-01 死代码与死表 | P4 | 待决策 | 删除 / 保留并在 `lpt-docs` 说明定位 |
| 学习会话生命周期 | 会话-01 遗忘检测路径不统一 | P0 | 已完成 | — |
| | 会话-02 `isOverTime()` 误报超时 | P0 | 已完成 | — |
| | 会话-03 结束会话不幂等 | P0 | 已完成 | — |
| | 会话-04 悬挂会话无收敛 | P0 | 已完成 | — |
| | 会话-05 活跃会话拦截无出路 | P1 | 已完成 | — |
| 内容归属与报告 | 归属-01 内容归属与待归类 | P1 | 已完成 | — |
| | 报告-01 报告与碎片不可修订 | P1 | 已完成 | — |
| 标记与元信息 | 标记-01 统一标记存储 | P1 | 已完成 | — |
| 复习 | 复习-01 复习回路补全 | P1 | 已完成 | — |
| | 复习-02 Feed 只读无反馈动作 | P1 | 已完成 | — |
| | 复习-03 Feed 随机取样 | P3 | 已完成 | — |
| | 复习-04 覆盖率查询拉全量 | P3 | 已完成 | — |
| | 复习-05 Feed 返回全文 | P3 | 已完成 | — |
| | 复习-06 学习引导 | P1 | 已完成 | — |
| | 复习-07 复习耗时统计 | P2 | 已完成 | — |
| AI 链路 | AI-01 事务内同步等 AI | P2 | 已完成 | — |
| | AI-02 全链路同步阻塞 | P2 | 已完成 | — |
| | AI-03 单 worker 串行无重试 | P2 | 已完成 | — |
| | AI-04 防并发锁是 JVM 内存锁 | P2 | 已完成 | — |
| 数据与检索 | 数据-01 业务主表缺索引 | P3 | 已完成 | — |
| | 数据-02 统计聚合在内存 | P3 | 已完成 | — |
| | 数据-03 编号撞号风险 | P3 | 已完成 | — |
| | 数据-04 主键生成方式不一致 | P3 | 已完成 | — |
| | 数据-05 逻辑删除标签占唯一键 | P3 | 已完成 | — |
| 导出 | 导出-01 无数据导出 | P1 | 已完成 | — |
| 安全 | 安全-01 数据库凭证明文 | P4 | 已暂缓(维护者决定) | 重新评估前提见条目内「当前决策」 |
| | 安全-02 Actuator 鉴权边界 | P4 | 已完成 | — |
| | 安全-03 AI 入站无防护 | P4 | 已完成 | — |
| | 安全-04 生产打印全部 SQL | P4 | 已完成 | — |
| 运维与清理 | 运维-01 备份只在同一 PVC | P4 | 已暂缓(维护者决定) | 恢复前提见条目内「维护者决定」 |
| | 清理-01 死代码与死表 | P4 | 已完成 | — |
| 学习录音 | 录音-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 操作入口归位 | P1 | 已完成 | — |
| | 闭环-02 任务名自动成为标签 | P1 | 已完成 | — |
| | 闭环-03 标签管理与搜索选择 | P1 | 已完成 | — |
| | 闭环-04 按标签复习生成导图 | P1 | 已完成 | — |
| | 闭环-05 任务执行页展示并编辑导图 | P1 | 已完成 | — |
| | 闭环-06 记录应用过程中犯的错误 | P2 | 只出设计 | 实现前仍需定:归属关系、入口关系、删除口径 |
已确认的设计决策(不是待办):会话-决策01 少于 10 分钟不计入总时长;会话-决策02 遗忘判定阈值 50 分钟。
> **学习录音模块已整体暂停**(2026‑10‑08):录音-01 的实现已完成并实测通过,但采到系统音频的两条路线(依赖 OBS / 自研原生)还没定,其余条目全部挂起。详见 §12。
已确认的设计决策(不是待办):会话-决策01 少于 10 分钟不计入总时长;会话-决策02 遗忘判定阈值 50 分钟;录音-决策01 录音由本机伴随程序负责;录音-决策02 只采系统输出不采麦克风。
---
@@ -77,13 +96,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 +134,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 +144,8 @@
### 会话-03(原 LPT-04)结束会话不幂等,会产生重复学习报告
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `d8c8b76`
- **涉及仓库**:`lpt-be`
- **依据**:`StudySessionsEntity.endedStudySession()` 在 `state = ENDED` 时只 `log.warn` 并原样返回;`StudySessionsServiceImpl.endedStudySession()` 随后无条件 `studyReportsMapper.insert(...)`。
- **影响**:重复点击、网络重试即可写入多条报告 → 复习 Feed 重复项、标准导图重复节点、统计重复计数。
@@ -112,17 +154,16 @@
### 会话-04(原 LPT-05)缺少服务端兜底:悬挂会话与超长会话无人收敛
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `db55218`
- **涉及仓库**:`lpt-be`
- **依据**:全仓无 `@Scheduled` / `EnableScheduling`;`getActiveSession()` 直接返回最新的 ONGOING/PAUSED 会话;遗忘检测只在用户主动访问该任务页面时执行(见 会话-01)。
- **影响**:
- 会话可长期停留「进行中/暂停」,只能等用户回到该任务页才被被动修正;用户不访问时「今日有效学习时间」等统计是滞后或错误的。
- 用户始终不回到该任务时,ONGOING 会话永久悬挂,并被 会话-05 的活跃会话守卫用来阻塞新任务。
- **建议**:
1. 增加超长会话硬兜底:ONGOING 且 `now - last_start_time` 超过第二阈值(暂定 2 小时)时强制暂停、按遗忘规则(会话-决策02)截断,并打异常标记,供前端提示「本次会话疑似忘记结束」。
2. 收敛方式:惰性收敛(读取时收敛)+ 低频定时扫描兜底,二选一或并用。
3. 三类阈值(25 分钟番茄钟、50 分钟遗忘判定、2 小时强制暂停)统一配置化,不要散落在实体常量里。
- **验收**:制造一个 3 小时前的 ONGOING 会话,在不访问该任务页面的前提下,惰性/定时收敛后状态为 PAUSED 且有效时间已按 会话-决策02 截断;正常进行中的会话不受影响。
- **已实施**:
1. 硬兜底阈值 2 小时:进行中且最后一段超过该时长时强制收敛为暂停,按遗忘规则(会话-决策02)截断到 `last_start_time + 25 分钟`,并落 `auto_converged` 标记供前端提示「疑似忘记结束」。
2. 收敛方式采用**并用**:惰性收敛挂在「活跃会话」与「任务未结束会话」两个读取入口;定时扫描(默认 10 分钟)兜底,保证用户不回来时统计也会收敛、悬挂会话不再阻塞新任务。
3. 四类阈值(25 分钟番茄钟、50 分钟遗忘判定、2 小时硬兜底、10 分钟有效时间下限)统一收到 `lpt.study-time.*` 配置,实体入口由统一的时间口径对象承载;非法组合(兜底阈值小于遗忘阈值等)在启动时直接失败。
- **实现约束**:收敛写入一律使用「状态仍为 ONGOING」的条件更新,惰性收敛与定时扫描并发时只结算一次;定时扫描跨租户扫描(系统级后台任务,无登录态),但不影响读取路径的租户隔离。
- **测试环境**:定时任务用 `lpt.study-time.scan-enabled: false` 在测试配置里关闭,避免调度任务与用例自造的悬挂会话互相干扰(落库集成测试直接调用扫描方法)。
- **验收**:制造一个 3 小时前的 ONGOING 会话,在不访问该任务页面的前提下,惰性/定时收敛后状态为 PAUSED 且有效时间已按 会话-决策02 截断;正常进行中的会话不受影响。✅ 已用落库集成测试覆盖(惰性、定时、不会误伤正常会话、不跨租户、重复扫描不重复结算)
---
@@ -130,15 +171,44 @@
### 会话-05(原 LPT-07)活跃会话拦截没有出路,会永久堵住新任务
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-fe` `25fbc67`(+ `lpt-docs` `804d53a`)
- **涉及仓库**:`lpt-fe`(+ `lpt-be` 需提供结束/放弃能力)
- **依据**:`Study.vue` 的 `startTask()` 在发现其他活跃会话后只提供「前往继续 / 取消」,取消分支为空函数,不跳转。
- **已实施**:拦截入口补两个新出口:「结束它并开始新任务」(复用 `ended` 接口,旧会话会生成一份未填写总结的报告)与「放弃该会话」(复用 `abort`,仅限未产生学习残片的会话,后端拒绝时原样转达原因);两者成功后继续开始当前任务,一次交互内解除阻塞。另对 会话-04 自动收敛过的会话在弹窗与任务页给出「疑似乎忘记结束」提示。
- **依据(修正)**:守卫实际位于 `StartTask.vue` 的 `loadTaskSession()`(清单原文写的是 `Study.vue` 的 `startTask()`,与实际代码不符,已按实际位置改);原行为只有「前往继续 / 取消」,取消后只弹一条提示,用户无处可去。
- **影响**:一个搁置数月的暂停会话会阻止开始任何新任务(所有任务入口都撞同一个守卫),用户必须先找回那个任务手动结束。
- **建议**:弹窗补充「结束它并开始新任务」或「放弃该会话」出口;复用已实现的会话关闭能力(`POST /{sessionNum}/study-sessions/ended` 与 `.../abort`,后者仅限未产生学习残片的会话)。
- **验收**:存在陈旧活跃会话时,用户可在一次交互内开始新任务。
- **验收**:存在陈旧活跃会话时,用户可在一次交互内开始新任务。✅ 已用交互式集成测试覆盖五个出口分支(前往继续 / 结束并开始 / 放弃 / 放弃失败 / 取消)
### 会话-06(2026‑10‑22 新需求)结束会话时无法修正有效学习时间
- [ ] 未完成
- **涉及仓库**:`lpt-fe` + `lpt-be`
- **依据**:结束会话弹窗(`lpt-fe/src/components/StartTask.vue` 的「结束会话总结」)只让用户填写报告三段,有效学习时间由后端按 `lpt.study-time.*` 口径自动结算(`StudySessionsServiceImpl`),用户没有任何修正入口。现实里「学完忘了点结束」会让时间虚高,而现有出口只有 会话-04 的 2 小时硬兜底与 25 分钟遗忘截断(`last_start_time + 25 分钟`),只能兜住极端情况。
- **影响**:任务累计有效学习时长与复习总览的数字和真实投入不一致,用户无法自行纠正;虚高还会连带影响学习报告的「预期达成判断」。
- **建议**:在结束会话界面上增加「有效学习时间」可编辑项,**只允许调小**(`0 < 新值 ≤ 服务端结算值`),随结束会话请求提交;服务端校验上限并用新值覆盖结算结果,超出上限**直接拒绝**而不是静默截断(否则用户以为改了却没生效)。界面需同时显示服务端结算值与上限。
- **待确认**:① 是否允许调到 0(等价于本次不计入);② 会话-决策01 的「少于 10 分钟不计入总学习时间」是否按修正后的值重新判定;③ 是否需要留痕(审计/报告中标注「已手动下调」)。
- **验收**:结束会话时可下调有效学习时间且立即反映到任务累计时长;提交大于服务端结算值的值被拒绝并给出明确提示;不做修正时行为与现在完全一致。
### 报告-01(原 LPT-08)学习报告与知识碎片不可修订
- [x] 已完成
- **完成于** `lpt-be` `c74f73a`(+ `lpt-fe` `18a2580`)
- **已实施**:碎片与报告都支持编辑与删除(软删除);新增 `PUT /report-fragments/{id}/ownership`、`DELETE /report-fragments/{id}`、`PUT|DELETE /review/report/{id}`、`GET /review/report/{id}/structured`;报告改为结构化三段(`session_summary` / `expectation_verdict` / `free_summary`,原 `content` 直接改名,不做老数据兼容),「按归属分组的碎片」查看时实时聚合;删除报告不连带删碎片,弹窗明示碎片保留。
> **已确认的决策(2026-10-09,维护者)**
>
> 1. **修订范围**:知识碎片与学习报告**都可编辑、都可删除**。删除一律走软删除(`deleted`),Feed / 统计 / 导图取材按未删除过滤。
> - 取舍:接受了「报告可被改写,因此不再是不可变的原样事实」,换取记录成本下降。这与 §3 支点「学习报告是会话产出的真实记录」存在张力,属于维护者的有意取舍。
> - 连带口径:**碎片删除不连带删报告**(碎片是原料,报告是收敛)。
> - 导图处理:删改后给受影响任务置「待更新」标记,AI 重建**由用户手动触发**,不自动重建(避免一次删除触发大范围 AI 调用)。
> 2. **删除报告不连带删碎片**:报告与碎片在库里是并列关系(都挂在会话上),碎片是独立原料。删除报告时弹窗明示「本次学习的 N 条碎片会保留」。
> - 关键理由:归属-01 之后碎片有独立的内容归属,可能已被归类到**其他任务**;连带删除会删掉已经归属到别处的内容。
> - 删除后:报告 `deleted=1`;碎片不变;受影响任务置「待更新」;统计里报告数 -1、碎片数不变。
> 3. **删除学习任务时**:碎片**保留**并把内容归属置空(进入待归类),其余(会话、报告、标准导图、回忆记录、应用场景)**随任务一并软删除**。
> - 与决策 1、2 一致:碎片是原料,不因归属消失而消失;删任务撤销的是「这次学习的时间记录与收敛结果」,不是知识本身。
> - 弹窗必须分别列出「即将删除」与「即将保留(N 条碎片进入待归类)」,避免用户以为删干净了。
> - 顺带修复:当前 `deleteTask` 只软删任务行、不级联任何东西,而前端弹窗却写着「关联的会话/报告/应用场景将被一并删除」——文案与实现不一致。
- [ ] 未完成
- **涉及仓库**:`lpt-be`(+ `lpt-fe`)
- **依据**:端点清单——`StudyReportFragments` 只有 `POST` / `PUT /{id}` / `GET`;`StudyReports` 只有创建与查询,**没有 PUT、没有 DELETE**;碎片也没有 DELETE。
@@ -149,6 +219,11 @@
### 复习-02(原 LPT-09)复习 Feed 只读,没有反馈动作
- [x] 已完成
- **完成于** `lpt-be` `63824b2`(+ `lpt-fe` `232fdb8`)
- **已实施**:碎片新增 `mastered` / `revisit` / `last_reviewed_time`;`PUT /review/feed/{fragmentId}/feedback` 标记或取消两个动作,`POST /review/feed/{fragmentId}/touched` 记录「接触」;智能排序的第三个信号取「最近接触时间」,「稍后再看」×1.6,「已掌握」×0.3(**不归零**,保留文档要求的随机性)。
- **刻意的取舍**:Feed 响应里 `mastered` / `revisit` 用 `@JsonIgnore` **隐藏**,前端只跟踪本次浏览内的点击状态。这样前端无法把反馈做成徽标或计数——一旦展示成状态,复习就会滑回清单模式。
- [ ] 未完成
- **涉及仓库**:`lpt-be`(+ `lpt-fe`)
- **依据**:Feed 仅提供列表/详情/回忆对比;`ReviewServiceImpl.reviewNeedWeight()` 的智能权重只有两个信号——时间衰减(`createdTime`)与任务最近一次回忆覆盖率。
@@ -159,16 +234,20 @@
### 导出-01(原 LPT-10)无数据导出
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `faaaa13`、`lpt-fe` `87e4cea`
- **涉及仓库**:`lpt-be`(+ `lpt-fe`)
- **依据**:端点清单中没有任何导出能力。
- **已实施**:两个只读接口 `GET /export/task/{taskNum}` 与 `GET /export/range?startDate&endDate`,均支持 `format=markdown|json`(默认 markdown);内容随统一响应体返回(`ExportResult{fileName, contentType, content}`),前端落成文件下载,不引入新的响应约定。两种格式共用同一个导出模型,保证内容一致。
- **范围口径**:按时间范围导出时,报告与碎片先按时间倒序合并再按内容归属分组,保证同一任务下两种内容交错时顺序仍然正确;起止日期均为闭区间,省略即不限制(默认方案)。
- **附带效果**:导出内容包含任务维度的统计,顺带覆盖了 复习-07 新增的复习耗时。
- **理由**:`lpt-docs` 明确系统定位是「辅助学习的工具」,工具型系统应保证数据可携带;同时可缓解备份粒度过粗的问题(见 运维-01)。
- **建议**:导出学习报告、知识碎片、任务统计为 Markdown / JSON,按任务或时间范围筛选。
- **验收**:导出内容可独立阅读,包含报告/碎片原文与时间信息。
- **验收**:导出内容可独立阅读,包含报告/碎片原文与时间信息。✅ 单测覆盖两种格式、范围分组顺序、空范围、非法格式/起止日期倒置;前端集成测试覆盖导出弹窗主流程与未选时间段的拦截
### 复习-06 学习引导
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-ai` `fb3c6f9`、`lpt-be` `b51a621`(+ `lpt-fe` `232fdb8`)
- **已实施**:新增复习行为实体 `review_guidance_conversations`(记录上下文与复习耗时都挂在它身上);`GUIDANCE` AI 任务类型按轮提交,AI 回复写回会话轮次作为下一轮上下文;入口为 Feed 卡片与导图节点;用户确认后产出的碎片记录上下文为这次复习行为、默认内容归属为被引导概念所属任务、并带 `FROM_GUIDANCE` 系统标记;放弃不产生任何数据。
- **涉及仓库**:`lpt-be` + `lpt-fe` + `lpt-ai`(概念文档已写入 `lpt-docs`)
- **依据**:复习只有接触(Feed)与结构提取(回忆对比),概念边界上的误解(例如把“参数量”当成能决定磁盘占用)不会被覆盖率捕捉。
- **已定**:开放式问题引导(例:“1B 参数量的 LLM 模型,会占用多少磁盘空间?”),无标准答案、不判分;AI 在对话中纠正回答里隐含的边界问题;对话不设轮数上限;产出是知识碎片,由用户确认后记录;复用碎片全链路(归属、待归类、导图取材、Feed 回收);碎片默认归属“被引导概念所属的学习任务”,并带「来自学习引导」标记(仅标记,不做特殊处理);记录上下文为复习行为;耗时计入复习-07;不进入学习报告;入口为 Feed 卡片与导图节点;不提供降级形态,AI 不可用时该功能整体不可用。
@@ -177,8 +256,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 分钟最小阈值;复习总览按任务与学习时长并列展示;不做跨任务汇总大数字、不设目标、不参与复习排序。
- **建议**:把复习行为作为时间记录的主体(回忆对比已有记录实体,学习引导新增),耗时写在该行为上;前端补空闲检测并上报交互时间。
@@ -199,30 +281,64 @@
### AI-02(原 LPT-12)AI 全链路同步阻塞,用户需干等最长 10 分钟
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `cf380c5`、`lpt-fe` `e52682c`(+ `lpt-docs` `39efbb6`)
- **涉及仓库**:`lpt-be` + `lpt-fe` + `lpt-ai`
- **依据**:`lpt-fe/src/utils/request.ts` 的 `timeout: 600000`;`lpt-be` 的 `AiServiceClient.submitAndWait()` 内部轮询最长 600s;`GET /study-sessions/{sessionNum}/report-draft` 这类 GET 也会触发 10 分钟阻塞并计费;`ReviewRecall.vue` 存在「AI 对比分析中,已等待 N 秒…」的分档文案。
- **影响**:页面只能干等;刷新或断开后请求丢失,AI 已消耗的 token 无法回收,结果也不落库。
- **建议**:`lpt-be` 建 AI 任务表(提交后立即返回 taskId),前端轮询 `lpt-be`;结果回写后前端再取。生成期间允许离开页面再回来。
- **验收**:提交 AI 任务后接口在秒级返回任务标识;任务结果可重复获取,无需重试即可拿到。
- **已实施**:新增 `ai_tasks` 表与统一 AI 任务接口(`POST /ai/tasks`、`GET /ai/tasks/{taskNum}`、`GET /ai/tasks/latest`):
- 提交秒级返回任务标识,结果写在 `result_payload`,按标识可重复获取;
- 三类能力(回忆对比、标准导图生成、报告草稿)全部改为任务;
- 读取接口不再产生副作用:`GET /review/standard-mind-map/{taskNum}` 不再自动生成(缺失时返回 null),`GET /study-sessions/{sessionNum}/report-draft` 已删除;
- 执行器在 `ai-task-*` 线程池里执行,提交后立即投递,`@Scheduled` 兜底扫描接手投递失败与进程重启;卡在 RUNNING 超过阈值的任务会被回收重试。
- **顺带修掉的一个真实缺陷**:后台执行线程没有 Web 上下文,而租户拦截器与公共字段自动填充都取 `StpUtil`,会直接抛 `NotWebContextException`。已引入 `TenantContext` 让后台线程显式声明执行身份(以任务所属用户执行),请求线程行为不变。
- **遗留**:`lpt-ai` 侧无需改动(AI-03 已提供任务队列);`lpt-be` 的 `AiServiceClient` 仍是「提交到 lpt-ai 后轮询」的同步封装,但已被调用在执行线程内,不再阻塞请求。
- **依据**:`lpt-fe/src/utils/request.ts` 的 `timeout: 600000`;`lpt-be` 的 `AiServiceClient.submitAndWait()` 内部轮询最长 600s;`GET /study-sessions/{sessionNum}/report-draft` 这类 GET 也会触发 10 分钟阻塞并计费。
- **验收**:提交 AI 任务后接口在秒级返回任务标识;任务结果可重复获取,无需重试即可拿到。✅ 落库集成测试覆盖:提交不在请求线程里调 AI、按标识重复查询结果一致、失败任务可查到原因、任务受租户隔离
### 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 内存锁
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `cf380c5`
- **涉及仓库**:`lpt-be`
- **依据**:`StandardMindMapServiceImpl` 的 `ConcurrentHashMap<String, AtomicBoolean> generatingTasks`。
- **影响**:多副本部署时锁失效;「生成中」的重复请求会返回 `queryByTaskNum()` 的结果(可能为 `null`)而被前端当成成功。
- **建议**:改为数据库/分布式锁,并明确「生成中」的对外语义(返回任务状态而不是实体)。
- **验收**:多副本场景下同一任务不会并发生成;生成中重复请求返回明确的进行中状态。
- **已实施**:删除 `StandardMindMapServiceImpl` 里的 `ConcurrentHashMap<String, AtomicBoolean> generatingTasks`,改为基于 `ai_tasks` 的进行中判定:同一用户 + 同一类型 + 同一目标已有 `PENDING`/`RUNNING` 任务时复用该任务,因此不存在「多副本锁失效」。执行侧再用「状态仍为 PENDING」的条件更新抢占,多副本并发也不会重复执行。
- **对外语义已明确**:提交接口返回的是**任务状态**(`AiTaskResponse`),不再是可能为 null 的实体;前端据此展示「正在生成」。
- **验收**:多副本场景下同一任务不会并发生成;生成中重复请求返回明确的进行中状态。✅ 单测覆盖「同一目标重复提交返回同一任务标识」,集成测试覆盖重复提交复用
### AI-05(2026‑10‑22 新发现)AI 不可用时静默降级为内置规则,用户以为内容由 AI 整理
- [ ] 未完成
- **涉及仓库**:`lpt-be` + `lpt-ai`(概念口径需同步 `lpt-docs`)
- **依据**:`MindMapOutlineGenerator.generate()` 在 AI 客户端返回空时降级到 `BuiltinMindMapGenerator`(`isAvailable()` 恒为 `true`),任务照常 `SUCCEEDED`;`RemoteAiMindMapClient.isAvailable()` 只看 `lpt.ai-service.url` 是否配置,**不探测服务是否真的可达**。因此 lpt-ai 没启动时,点「补充新碎片」走完全程弹的是 `ElMessage.success("新碎片已整理进标签导图")`(`lpt-fe/src/components/TagReview.vue`),导图内容实际由内置规则拼接。
- **现状清单(全工作区的降级路径)**:
| 链路 | AI 不可用时的行为 | 用户看到 |
|---|---|---|
| 任务导图 / 标签导图生成 | 降级 `BuiltinMindMapGenerator` | 成功提示 |
| 学习报告草稿 | 降级为按序拼接(`StudySessionsServiceImpl`) | 成功提示 |
| 回忆对比(任务 / 标签) | 降级为内置文本相似度匹配(`StandardMindMapServiceImpl`) | 成功提示 |
| 学习引导 | 无降级,直接失败 | 错误提示(唯一一条) |
- **影响**:
1. 用户无法区分「AI 整理的结构」与「按会话分组的规则拼接」,对内容质量产生错误信任;
2. 降级结果会写库(`review_standard_mind_maps` / `review_tag_mind_maps` / 报告表),AI 恢复后不会自动纠正,要用户再手动重建一次;
3. `AiServiceTaskFailedException`(例如 LLM 402 余额不足这类确定性原因)在 `AiServiceClient.generateMindMap()` 的 `catch (Exception)` 里被一并吞掉降级,同样不可见;
4. 来源标签与事实不符:`lpt-fe/src/components/TagMindMapList.vue` 把 `BUILTIN` 显示成「AI 生成」,而「补充新碎片」之后 generator 又被强制写成 `USER_MERGE`,显示成「含手动编辑」。
- **建议**:**删除全部内置规则降级路径**(导图生成、报告草稿、回忆对比),AI 不可用或调用失败时任务直接失败并给出可定位的原因,**不做任何数据改动**(不写新导图、不覆盖旧导图、不落报告)。前端来源标签需要能如实区分生成来源。
- **已排除的替代方案(待维护者确认)**:保留降级但在结果里带 `degraded: true` + 原因,前端改用警告提示。
- **验收**:lpt-ai 未启动时点「补充新碎片」,任务失败且界面提示 AI 服务不可用;库中导图内容与生成时间均未变化;AI 恢复后同一操作能正常成功。
---
@@ -230,7 +346,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、统计、按会话取碎片/报告)都是全表扫描 + 过滤,随使用量线性劣化。
@@ -239,16 +356,19 @@
### 复习-03(原 LPT-16)Feed 使用 `ORDER BY RAND()`
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `251a468`
- **涉及仓库**:`lpt-be`
- **依据**:`ReviewServiceImpl.getReviewFeed()` 与 `getSmartFeed()` 对报告表和碎片表分别使用 `ORDER BY RAND() LIMIT ...`,smart 模式抽样量为 `limit × 5`(上限 500)。
- **影响**:MySQL 上属全表随机排序,单次请求两次全表随机。
- **建议**:改为 id 区间随机、预生成候选池或「按时间窗口随机 + 按需补充」。
- **验收**:Feed 接口不产生全表随机排序(`EXPLAIN` 可验证)。
- **已实施**:采样方式改为「**随机起点 + 顺序取窗口**」:先用 `MIN(id)/MAX(id)`(`StudyReportFragmentsMapper.selectIdRange`)取主键区间,在区间内随机选起点,再按 `id ASC` 取够数量;不足时从头回绕补齐,并按主键去重。`random` 与 `smart` 两种模式共用该方法,全仓已无 `ORDER BY RAND()`。
- 起点后的 `id >= ? ORDER BY id LIMIT n` 走主键索引,不再有全表随机排序。
- 取舍:删除造成的 id 空洞会让靠后的内容被略微偏重。对「偶遇式」的 Feed 可以接受,换来的是稳定的访问路径;若将来需要严格均匀,可改为预生成候选池。
- **验收**:Feed 接口不产生全表随机排序(`EXPLAIN` 可验证)。✅ 落库集成测试覆盖取满数量、页内不重复、确实随机(40 轮取样去重后远多于单页容量)、起点落在末尾时的回绕补齐
### 复习-04(原 LPT-17)取「每任务最近一次回忆覆盖率」时拉取全部回忆记录
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `3dda263`
- **已实施**:新增 `ReviewRecallRecordMapper.selectLatestRatioByTask`,用「按任务取最大 id」的 JOIN 在 SQL 侧定位每个任务的最新记录,只返回 `task_num` + `recall_ratio` 两列,不再读取 `compare_result` 大字段。
- **涉及仓库**:`lpt-be`
- **依据**:`ReviewServiceImpl.latestRecallRatioByTask()` 按 `taskNum in (...)` 查询全部记录(含体积较大的 `compare_result` JSON)后只在内存里取每条任务的第一条。
- **影响**:数据传输量与内存占用随复习次数线性增长。
@@ -266,7 +386,9 @@
### 复习-05(原 LPT-19)Feed 返回全文
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `dbeafba`
- **已实施**:Feed 条目只返回 ≤200 字的摘要(换行压成空格),另加 `contentLength`(原文总长度)与 `contentTruncated`;全文继续由详情接口按需拉取。前端本来就只在 120 字处截断,因此展示行为不变。
- **涉及仓库**:`lpt-be` + `lpt-fe`
- **依据**:`ReviewFeedItem.content` 直接返回报告/碎片全文,`getReviewFeed(100, "smart")` 一次最多 100 条;前端只展示前几十个字(详情页才需要全文)。
- **建议**:Feed 返回摘要字段(含长度标记),详情接口按需拉全文。
@@ -274,12 +396,33 @@
### 数据-03(原 LPT-20)编号生成有撞号风险且无唯一约束
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `3cc3be1`
- **涉及仓库**:`lpt-be`
- **依据**:`GenerateNumTool.getNextSequence()` 使用 `System.currentTimeMillis() % 1_000_000`,格式为 `PREFIX-yyyyMMdd-<6位>`;`session_num` / `task_num` 上没有唯一索引(仅两张导图表有 `unique key`)。
- **影响**:同毫秒创建可能撞号;撞号后 `getOneOpt` 会因多行结果抛异常。
- **建议**:改用 UUID/ULID 或加随机位,并对业务编号加唯一约束。
- **验收**:并发创建 N 个任务/会话无重复编号,数据库层有唯一约束保护。
- **已实施**:编码后缀由「6 位毫秒片段」改为「6 位毫秒片段 + 6 位随机数」(`SecureRandom`),保留 `PREFIX-yyyyMMdd-<12位>` 的可读形态,不破坏已有编号与前端引用;同时补上唯一约束 `(created_by, task_num)` 与 `(created_by, session_num)`(迁移 `V20261009_3`),作为最终防线。
- **证据**:此风险不是推测——为 复习-07 写落库集成测试时,同毫秒两次 `generateNum` 真的产出了完全相同的 `task_num`,导致两个任务的数据被并到同一条聚合。
- **注意**:唯一约束迁移在历史数据已有重复编号时会直接失败——这是有意为之,需要人工确认后再处理,而不是静默跳过约束。
- **验收**:并发创建 N 个任务/会话无重复编号,数据库层有唯一约束保护。✅ 单测覆盖 300 次连续生成无重复
### 数据-04(2026‑10‑10 新发现)`TaskEntity` 主键生成方式与表结构、其余实体都不一致
- [x] 已完成
- **完成于** `lpt-be` `7acfc7e`
- **涉及仓库**:`lpt-be`
- **依据(有实证)**:`TaskEntity` 写的是裸 `@TableId`(无 `IdType`),MyBatis-Plus 默认走 `ASSIGN_ID` 生成 snowflake 的 long,回写 Integer 主键时被截断(实测得到 1673719810 / 1912795138 这类值,并不是自增 id)。而 tasks 表 id 是 `auto_increment`,仓库里其余所有实体(markers / fragments / sessions / ai_tasks / …)都用 `IdType.AUTO`,`TaskEntity` 是唯一例外。
- **影响**:snowflake 低 32 位在毫秒回绕(约 1.024s)且 sequence 相同时会撞值,表现为**偶发**的 tasks 主键重复插入失败。不是猜测:为 闭环-02/03 写落库集成测试时,新增用例多插了约 11 个任务,就把既有的 `MarkerServiceIntegrationTest.systemMarker_isVisibleButNotEditable` 推到 `DuplicateKey` 失败;stash 掉新代码后全量套件又通过,可以定位到时序被放大而不是新逻辑本身写错。
- **修复**:`@TableId(value = "id", type = IdType.AUTO)`,与表结构和其余实体一致;`UserEntity` 已核查,其 `user.id` 是 `varchar(255)` 非自增,不动。
- **验收**:全量 `./mvnw -q test`(418 用例)绿;任务 id 由数据库自增分配。
### 数据-05(2026‑10‑10 新发现)逻辑删除的标签占着唯一键,移除后重打同名标签会插入失败
- [x] 已完成
- **完成于** `lpt-be` `02d5c24`
- **涉及仓库**:`lpt-be`
- **依据**:`markers` 的唯一键是 `uk_markers_object_marker (object_type, object_num, kind, marker_name, marker_value)`,**不含 `deleted`**;而 `MarkerServiceImpl.addUserTag` 只按 `deleted = 0` 查重(`@TableLogic` 自动追加)后直接 `insert`。因此「移除某标签后再给同一对象打同名标签」会与被逻辑删除的那一行撞唯一键。
- **影响**:必现的写入失败。闭环-02 的自动任务名标签会踩到:用户删掉自动标签后重新归类同一碎片,`addOwnerTaskNameTag` 抛唯一键冲突并让归类操作失败。这是闭环-02/04 实现过程中发现的既有缺陷(与 `user_tags` 的「删除后同名复用旧行」是同一类问题,那里已按复用处理)。
- **修复**:新增 `MarkerMapper.selectAnyByObjectAndName`(自定义 SQL,含逻辑删除行)与 `revive(id)`,`addUserTag` 查到已删除的旧行时复用(把 `deleted` 归零)而不是插入新行。
- **验收**:`MarkerServiceIntegrationTest` 新增两例(移除后重打同名标签复用同一行;删掉自动任务名标签后重新归类仍只有一条标签);全量 `./mvnw -o test` 452 用例 0 失败。
---
@@ -287,16 +430,28 @@
### 安全-01(原 LPT-21)数据库凭证明文入库
- [ ] 未完成
- [ ] 未完成(**维护者决定暂缓,见下方「当前决策」**)
- **涉及仓库**:`lpt-be` + `lpt-infra`
- **依据**:`application-prod.yml`、`application-dev.yml`、`application-local.yml` 均包含明文数据库账号密码(三个环境同一份)。`lpt-infra` 已通过 `lpt-secrets` 注入 `SPRING_DATASOURCE_PASSWORD` 覆盖,但配置文件仍在 Git 历史中。
- **建议**:轮换凭证 → 配置文件只保留占位符/环境变量引用 → 清理历史(或至少视为已泄露处理)。
- **验收**:仓库中不再出现明文凭证;本地开发通过环境变量或本地未跟踪配置提供。
- **注意**:**不要把任何密码值复制进本文档。**
- **2026-10-09 核查补充**(供重新评估时使用,均不含凭证值本身):
- 三个环境的 username 与 password 完全相同,且 username 是 `root`(即三环境共用一个 root 账号,爆炸半径为「全库 + 全环境」)。
- `application-local.yml` 指向一个公网 MySQL,实测该端口 TCP 可达;这一份**没有 k8s env 覆盖**(本地开发无集群),是「活的」可能性最高的一份。
- `application-prod.yml` / `application-dev.yml` 的值在集群内被 `lpt-secrets` 覆盖,可能只是死值;需用一条 `kubectl get secret` 核实是否与文件值相同。
- `lpt-infra` 把 MySQL 暴露为 `NodePort`(dev 30306 / prod 30307),这条与「凭证是否泄露」无关,是独立的暴露面。
- `lpt-infra` 全仓无 `NetworkPolicy`。
- **当前决策(2026-10-09,维护者)**:**暂缓**。项目处于开发阶段,认为该风险可接受;不同环境使用不同密码会给开发带来不必要的精力消耗。
- 重新评估的前提:进入对外发布/多人协作阶段,或 `lpt-secrets` 的值与仓库中的值相同(后者意味着公开在 Git 里的就是生产口令)。
- 若重新开工,建议顺序:**先轮换凭证**(使历史值作废)→ 再改配置占位符 → 「清 Git 历史」收益很低,可只做整洁性处理(改写历史会让所有已有克隆失效,且已外流的副本不受影响)。
### 安全-02(原 LPT-22)Actuator 端点鉴权边界未固定
- [ ] 未完成
- [x] 已完成
- **完成于** `lpt-be` `251a468`
- **已实施**:把暴露清单显式固定为 `health,info`,并写明「`/actuator/**` 不受 `SaInterceptor` 约束,这里是唯一的口子,临时排查请用 local profile 覆盖而不是改这里」。
- **方案取舍**:清单给的两个选项里选了「显式固定白名单」,因为集群内没有任何 `NetworkPolicy`(已核实),「独立端口 + 网络策略」当前没有可依赖的基础设施。
- **涉及仓库**:`lpt-be`
- **依据**:线上只读探测确认 `/api/actuator/health`、`/api/actuator/info` 未登录返回 200,而 `/api/actuator/env` 与业务接口返回 401(已注册的 actuator 端点不受 `SaInterceptor` 约束)。
- **影响**:当前探针正常,但一旦放开 metrics/prometheus 等端点,会连带公开。
@@ -305,15 +460,24 @@
### 安全-03(原 LPT-23)`lpt-ai` 缺少入站防护(SSRF 与滥用)
- [ ] 未完成
- **涉及仓库**:`lpt-ai`
- **依据**:`POST /fetch-title` 由服务端抓取用户可控 URL(可探测内网/云元数据地址);`/ai/tasks` 与 `/admin` 无鉴权、无速率限制、无请求体上限;`admin/store.ts` 把完整 prompt 与学习内容明文写入 `data/logs.json`。
- **建议**:抓取改为白名单/内网地址黑名单 + 协议与重定向校验;入站加鉴权与限流;`/admin` 加访问控制;日志中学习内容按需脱敏或缩短保留期。
- **验收**:`/fetch-title` 无法访问内网与元数据地址;未授权请求无法提交 AI 任务。
- [x] 已完成
- **完成于** `lpt-ai` `f091fe6`、`1c31682`,`lpt-be` `251a468`、`bad7d6b`,`lpt-infra` `9160dd1`
- **已实施**:
1. **抓取四层校验**(`utils/ssrf-guard.ts`):协议白名单 → 端口白名单(默认只允许 80/443,避免被用来探测内网 Redis/MySQL)→ **DNS 解析后逐个校验每一个解析结果**(防解析到内网与 DNS rebinding)→ **重定向逐跳重新校验**(防「首跳合法、次跳内网」);响应体截断到 512 KiB 且只接受网页类型。
覆盖 IPv4 私网/回环/链路本地(含云元数据 169.254.169.254)/CGNAT/组播/保留段,以及 IPv6 回环、ULA、链路本地、组播,并识别 IPv4-mapped 与 NAT64 里内嵌的 IPv4。
2. **入站令牌(可选)**:`LPT_AI_TOKEN` 设置后 `/ai/*` 与 `/admin` 都要求携带(header `x-api-token` 或 query `token`);`lpt-be` 侧由 `lpt.ai-service.token` 提供。部署清单用 `secretKeyRef.optional: true` 引用 `lpt-secrets/lpt-ai-token`,**没设这个 key 也能启动**(此时不校验)。
3. **限流**:`/ai/tasks` 按来源限流(默认 30 次/分钟,`LPT_AI_RATE_LIMIT`)。
4. **请求体上限**:`LPT_AI_BODY_LIMIT_BYTES`,默认 256 KiB。
- **两条实现取舍(与维护者确认过)**:
- 令牌**默认不启用**:维护者明确表示开发阶段不想为额外凭据付出精力。因此实现为「一条环境变量即可收紧」,并保证未启用时启动告警 + Pod 正常启动。
- **不做日志脱敏**:`admin/store.ts` 已按条数限制保留(`MAX_ENTRIES=200`),而按内容脱敏会削弱 `/admin` 面板的排查能力;本项不在验收标准内,留待后续隐私专项。
- **顺带发现**:`POST /fetch-title` **全工作区零调用**(`lpt-fe` 走的是 `lpt-be` 的 `/utils/fetch-title`,用 Java 侧 `TitleFetcher`)。保留是为满足本条目验收;如需精简可连同抓取工具一并删除,列入 清理-01 候选。
- **验收**:`/fetch-title` 无法访问内网与元数据地址;未授权请求无法提交 AI 任务。✅ 已用单测覆盖内网/回环/元数据/IPv4-mapped/NAT64/端口/协议/域名解析到回环等绕过路径,以及令牌校验的放行与拒绝分支
### 安全-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 与参数(含学习内容),噪音大且不利于排查。
@@ -322,6 +486,13 @@
### 运维-01(原 LPT-25)备份只在集群内同一 PVC
> **维护者决定:暂不做(2026-10-09)。**
> - 现状:每日 `mysqldump --all-databases` 写入同集群的 `mysql-backup` PVC,保留 14 天,dev 与 prod 混在同一个 dump 里。
> - 恢复前提:需要维护者提供异地/对象存储目标(S3/MinIO 兼容存储的端点与凭据,或一台可 SSH 的常开主机及其保留策略)。
> - 若重新开工,建议顺序:先把现有备份做可靠(**按库分文件**、备份后校验非空且可读、失败可见)→ 再做一次**真实的恢复演练**(当前从未验证过备份可恢复)→ 最后接异地副本。
> - 未做的风险已明确:集群级故障即全丢,这一点维护者已知悉并接受。
- [ ] 未完成
- **涉及仓库**:`lpt-infra`
- **依据**:`mysql-backup-cronjob.yaml` 每日 `mysqldump --all-databases` 写入同一集群的 `mysql-backup` PVC,保留 14 天,且 dev 与 prod 混在同一 dump。
@@ -331,6 +502,15 @@
### 清理-01(原 LPT-26)死代码与死表清理
> **已确认的决策(2026-10-09,维护者)**:**删代码,两张表先保留并在 `lpt-docs` 记录定位**。
>
> - 删除(7 个文件):`TestController` 及其单测、`TestTableService` / `TestTableServiceImpl` / `TestTableServiceImplTest` / `TestTableMapper` / `TestTableEntity`。
> - 保留并记录:`test_table`、`review_mind_maps`(后者已被 `review_standard_mind_maps` 取代,零代码引用)。
> - 保留表的理由:删表不可逆,且无法连接线上库核实是否还有数据(`review_mind_maps` 曾支持 xmind 上传解析,可能存有导入过的导图);两张表几乎不占空间,代价只是不够整洁。
> - 接受的代价:失去「手动触发四种业务异常」的入口。`GlobalExceptionHandlerTest` 覆盖的是 handler 层逻辑(直接调用,不经 Spring),本条目不再提供端到端手工验证手段。
> - **现状修正**:清单原依据提到「`lpt-fe/src/api/review.ts` 仍导出 `/review/mind-map/*`」——已核实前端这部分**已经清理干净**,无需处理。
- [ ] 未完成
- **涉及仓库**:`lpt-be` + `lpt-fe`
- **依据**:`TestController`(`/test/{id}`)与 `test_table` 仍在生产代码中;`review_mind_maps` 表自 `V20260620_1` 创建后无任何代码引用也未 drop;`lpt-fe/src/api/review.ts` 仍导出 `/review/mind-map/*`(含 xmind 上传解析)相关调用,而后端已无对应端点。
@@ -343,12 +523,14 @@
同一模块内的条目触碰同一批表结构、口径或配置,建议一个模块一次性改完,避免出现双口径并存的中间态。
1. **学习会话生命周期**:会话-03(结束幂等)+ 会话-01(结算口径统一)一批,修正时间数据口径并补用例;再做会话-02;最后做会话-04 + 会话-05(需先给收敛方式与出口形式的决策)。
2. **内容归属与报告**:归属-01 与报告-01 合并一次改完碎片表与报告结构(碎片归属、报告四段结构、导图待更新标记、检索口径);标记-01(统一标记存储)随同定下,学习引导的来源标记依赖它。
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,彼此独立,可并行推进。
1. **学习会话生命周期**:会话-01/02/03 已完成;会话-04 + 会话-05 已完成(收敛方式取「惰性 + 定时并用」,出口取「结束并开始新任务 + 放弃」)。**会话-06 是本次(2026‑10‑22)新增的待办,本模块重新开启。**
2. **内容归属与报告**:归属-01 + 报告-01 + 标记-01 均已一次改完(碎片表拆分归属、报告结构化、导图待更新标记、检索口径),学习引导的来源标记随之落地。本模块已收口。
3. **复习**:复习-01 六项结论已落;复习-02 / 复习-03 / 复习-04 / 复习-05 / 复习-06 / 复习-07 均已完成。本模块已收口。
4. **AI 链路**:AI-01 / AI-02 / AI-03 / AI-04 均已完成。**AI-05 是本次(2026‑10‑22)新增的待办(移除内置规则降级),本模块重新开启。**
5. **数据与检索 + 导出**:数据-01 / 数据-02 / 数据-03 / 导出-01 均已完成;数据-04 / 数据-05 是本次实现过程中新发现并已修的既有缺陷(主键生成方式不一致、逻辑删除标签占唯一键)。本模块已收口。
6. **安全与运维清理**:安全-02 / 安全-03 / 安全-04 已完成;安全-01 与运维-01 由维护者决定暂缓(见条目内记录);清理-01 已完成。
7. **学习录音(已暂停)**:模块整体挂起,重启前先定 §12「路线分叉」(依赖 OBS / 自研原生)。
8. **学习闭环重构**:闭环-01 / 闭环-02 / 闭环-03 / 闭环-04 / 闭环-05 均已完成(首页只读化 → 任务名自动标签 → 标签字典与搜索选择 → 按标签复习与标签导图 → 执行页就地编辑导图);闭环-06 本次只出设计(概念落 `lpt-docs/docs/concepts/error-record.md`),实现前仍需定归属关系、入口关系与删除口径。
---
@@ -356,6 +538,27 @@
### 归属-01(原 DC-01)内容归属与待归类
> **已确认的决策(2026-10-09,维护者)**
>
> 1. **报告里的「按归属分组的碎片」采用实时聚合,不做快照。**
> - 报告表只存三段文本(会话摘要、预期达成判断、自由总结);「按归属分组的碎片」在查看时按碎片的**当前内容归属**聚合,不落库。展示顺序按 `learning-report.md`:会话摘要 → 预期达成判断 → 按归属分组的碎片 → 自由总结(分组排在自由总结之前)。
> - 理由:与标准导图的取材口径一致(都按当前归属),避免出现「报告说属于甲、导图放在乙」的双口径——而这正是本条目要消灭的东西;同时表结构最简单,不需要碎片改归属时的同步逻辑。
> - 代价:删除碎片会让历史报告的分组段变短。这与决策 1「碎片可删」是同一个取舍,已接受。
> - 推论:「旁支碎片」不需要额外字段——它就是「归属不等于本会话所属任务」的那部分碎片,同样是派生结果。
> 2. **不做老数据兼容**(维护者):现有报告的 `content` 列直接改名为 `free_summary`,老数据顺势落进「自由总结」,新代码不读旧语义、不维护双渲染路径。摘要与达成判断两段对老报告留空(本来就不存在)。
> - 维护者的后续计划:之后自行把老数据的**碎片与导图**迁移进新系统,报告不在迁移范围内。
> 3. **迁移进来的历史碎片必须带上原会话**:记录上下文保持 `NOT NULL` 的硬约束,不做放宽。
> - 维护者准备的迁移数据需按「任务 → 会话 → 碎片」顺序提供:老任务(归属目标)、老会话(`session_num` / `task_num` / `start_time`)、老碎片(正文 + 所属会话)。
> - 代价:迁移脚本比「只迁碎片」麻烦一层,换来的是老碎片仍能回答「当时在学什么的时候记的」,且时间统计能接回时间轴。
> - 已排除的替代方案:造一个「历史导入」虚拟会话兜底(会让一条虚拟会话被当成真实学习、需在统计里特判);放宽 `session_num` 为可空(会放弃 lpt-docs 的「记录上下文不可为空」约束)。
> 4. **待归类内容两处都要出现**:复习总览里一个独立区块(回答「还欠多少」),复习 Feed 卡片上加「待归类」标记并**就地归类**(归类到已有任务,或升格为新任务)。这是个可选项,不做成待办清单。
> - 理由:`lpt-docs` 要求「待归类内容必须被看见,否则归类无从发生」;而复习的日常入口常常是 Feed 而不是总览,两处缺一都会漏。
> - 已排除:只放总览(归类时机与注意到的时机错开);只在 Feed 打标(永远不知道积压多少);独立「待归类」页面(会变成待办清单,且与总览职责重叠)。
>
> **归属-01 已完成(2026-10-09)。** 完成于 `lpt-be` `c74f73a`(+ `lpt-fe` `18a2580`、`lpt-docs` `8c55b86`)。
>
> **归属-01 决策完毕(2026-10-09),可以开工。** 实现要点汇总:碎片表拆 `context_type` + `context_num`(不可空、不可变)与内容归属字段(可空、可变、单一);报告表 `content` → `free_summary` 并新增 `session_summary` / `expectation_verdict`,分组段实时聚合不落库;删任务时碎片归属置空进待归类、其余软删;待归类在总览独立区块与 Feed 卡片两个入口呈现并支持就地归类/升格为任务。
- **文档**:`lpt-docs/docs/concepts/knowledge-ownership.md`(设计已确认,见文末结论)、`lpt-docs/docs/concepts/learning-report.md`(结构化报告形态)、`lpt-docs/docs/design/system-structure.md`(设计总纲)
- **背景**:学习 A 内容时顺手记下的旁支知识(例:学 AI 时记下“1B = one billion”)目前会被算作 A 的知识,进 A 的导图与回忆对比基准。根因是把「记录地点」当成了「内容归属」。
- **变更内容**:拆分记录上下文(不可变、不可为空;取值是学习会话或复习行为)与内容归属(可变、单一、可为空);时间按行为统计(学习会话→学习时间,复习行为→复习耗时)、内容按归属聚合;新增待归类视图;归类动作挂在复习 Feed 里;AI 只给归属建议;待归类内容可升格为学习任务;学习报告改为结构化(会话摘要、预期达成判断、按归属分组的碎片、自由总结,旁支碎片留在本次报告单独标注)。
@@ -369,6 +572,35 @@
### 复习-01(原 DC-02)复习回路补全
> **已确认的决策(2026-10-09,维护者)**
>
> **以下 4 项无需决策——文档与实现已经收敛到同一口径,直接按此执行:**
>
> | 项 | 结论 | 文档依据 | 实现依据 |
> |---|---|---|---|
> | 1 | Feed **不含**学习报告 | `review-feed.md`:「Feed 的条目单位是知识碎片。学习报告不以条目形式出现在 Feed 中」 | `getReviewFeed` / `getSmartFeed` 均调用 `mergeAndConvert(List.of(), fragments)`,报告列表恒为空 |
> | 3 | 覆盖率口径 = **最近一次**(不做加权) | `recall-review.md`:「为复习排序提供任务级掌握度:最近一条记录的覆盖率」;`review-loop.md` 同 | `ReviewServiceImpl.latestRecallRatioByTask()` 取 `created_time` 降序的第一条 |
> | 4 | 待归类内容**两处都出现**(总览独立区块 + Feed 混排打标、就地归类) | `review-loop.md`:「待归类内容在复习总览中可见,在 Feed 中可归类」 | 待实现;口径见归属-01 决策 4 |
> | 5 | 遗漏项 = **本次对比的快照,不做跨次累计** | `recall-review.md`:「遗漏项是本次对比的快照,不是跨次累计的待办集合」 | 对比结果写在单条回忆记录的 `compare_result` 里,不跨记录聚合 |
>
> **需要决策的第 2 项(已定)**:
>
> 2. **Feed 反馈动作:提供「已掌握」与「稍后再看」两个轻量动作**,另外把「上次复习时间」作为**第三个**权重信号(原只有时间衰减与任务级覆盖率两个)。
> - 两个动作**只调整出现概率,不产生状态展示、不计总数、不做待复习列表**:`已掌握` 降低概率但**不归零**(保留文档要求的随机性——「每条内容都有机会出现」),`稍后再看` 提高概率。
> - 展开查看 / 进入回忆对比会刷新「上次复习时间」,本身不产生额外数据。
> - 不落进标记表:文档明确「标记不是状态」,因此反馈状态落在碎片自身的字段上。
> - 已排除:只做「稍后再看」(无法低成本表达「这条我熟」,重复出现只能等时间衰减);只做「已掌握」(缺少正向「再巩固」入口,且回忆对比是任务级的);不做反馈(重复出现的痛点原样保留)。
>
> **需要决策的第 6 项(已定)**:
>
> 6. **排序信号强度用三档预设,不做精确权重。** 档次为「时间为主(默认)/均衡/掌握度为主」,前端可切换。
> - 现状落差:文档写「信号强度可配置」,但实现里系数写死(`0.3 + ageDays/90*0.7` 与 `1.0 - ratio*0.7`),本项即为填补这个落差。
> - 理由:现有公式是「时间因子 × 掌握度因子」两个乘数而非加权和,给百分比是假精度;两个信号本身抽象,调完也未必知道是哪一项起作用;三档已覆盖真实意图(「怎么老给我看旧内容」与「怎么总给我看熟的」)。
> - 已排除:与任务优先级一致的前端百分比权重弹窗(假精度 + 需重构公式 + 为低频设置多写一套持久化与校验);只做后端配置项(等于不可用,不会为看 Feed 效果去改 yaml 重启);写死并改文档(放弃一个已经留好的口子)。
>
> **复习-01 决策完毕(2026-10-09)。** 连带解锁:复习-02(反馈动作)、复习-04(覆盖率查询依赖口径)、复习-05(Feed 摘要口径)、复习-06(学习引导,前置 AI-02/03 与标记-01 均已满足)。
- **文档**:
- **文档**:`lpt-docs/docs/design/review-loop.md`(立场、内容来源、两个层级、排序、归类、反馈、AI 边界)、`lpt-docs/docs/concepts/review-overview.md`(新增)、`recall-review.md`(回忆记录、覆盖率、复习起点、遗漏项)、`review-feed.md`、`lpt-docs/docs/design/principles.md`、`module-boundaries.md`。
- **背景**:复习此前只有零散描述(Feed、导图、回忆对比各自成文),缺少系统级口径:复习内容的完整来源、任务级与条目级两层入口、覆盖率与掌握度的定义、遗漏项的语义、反馈动作、归类动作落点、AI 边界都未定;文档写的是“Feed 展示碎片和学习报告”,实现只返回碎片。
- **本次补全(已按以下取向写入文档)**:复习只做“低阻力反复出现 + 主动提取”,不做到期调度、打卡、评分;Feed 条目单位是碎片,报告从任务记录进入;覆盖率按任务聚合成掌握度,作为排序信号之一;遗漏项是每次对比的快照,不做跨次累计待办;归类动作落在复习里;AI 只做语义匹配与归属建议。
@@ -383,6 +615,32 @@
### 标记-01 统一标记存储
> **已确认的决策(2026-10-09,维护者)**
>
> 1. **可挂对象:知识碎片 + 学习任务**。对象用「类型 + 标识」引用(`object_type` ∈ {`FRAGMENT`, `TASK`})。
> - 报告不挂:它是会话的派生结果,且「按归属分组的碎片」本身就是一个分组维度,再加标记会出现两套「分组」语义。
> - 会话不挂:时间轴对象,状态/是否收敛这类流程性信息按文档要求留在主体上。
> - 表格是通用的,以后要加对象类型只需加枚举值与校验。
> 2. **标记名受控方式:两类彻底分开**。
> - 系统标记:标记名与值来自**代码里的固定词表**(枚举),由系统写入,**用户只读**、不可删改。理由:「找出所有来自 X 的碎片」这类检索的可靠性依赖于它没被改过。
> - 用户标签:标记名**自由输入**,可增删改。
> - 同一对象上两类共存、互不覆盖,用「种类」字段区分展示(系统标记灰底只读,标签可删)。
> - 已排除:允许用户修改系统标记(系统检索不可靠);标签也走预置词表(与「用户自由建立的分类」冲突);不区分两类(复习-06 的「来源标记」失去落点)。
> 3. **标记值的存法:名副其实**。系统标记用「标记名 + 标记值」成对存储(`来源 = 学习引导`);用户标签**只有标记名**,`marker_value` 留空(标签名本身就是全部信息,不做「英语 = 英语」这种冗余)。
> - 已排除:让标签也带值(输入成本上升、语义与「内容归属」及碎片正文混淆、检索要区分「有名」与「名+值都匹配」);扁平命名不带值(丢失「按来源聚合」的维度,且与文档定义的「标记名与标记值」不一致);类型化值 BOOLEAN/ENUM/TEXT(目前只有两个真实需求,属于过度设计,且三列互斥存储会让读写校验变重)。
> 4. **检索入口:支持单一标签筛选,点标签即筛选**(碎片列表 / 复习 Feed / 任务列表)。不做多标签 AND/OR 组合、不做跨对象统一搜索页。
> - 关键理由:`knowledge-ownership.md` 规定标签「只影响检索,不影响聚合与统计」,且标记不能表达第二归属、不能参与流程判断——**检索是标记唯一的作用**,不做检索入口等于让标签失去意义。
> - 已排除:只展示不检索(标签变成纯装饰);多标签组合 + 跨对象搜索(要查询构建器与动态 SQL,而标签体系规模未知、组合筛选未必用得上);独立标记页(与列表内筛选职责重叠)。
> 5. **治理与可见性:全可见 + 标签可改名 + 可删除**。
> - 系统标记对用户**可见**(灰底只读标签)。理由:学习引导产出的碎片默认归属被引导概念所属任务,用户看到「来源=学习引导」才能理解它为何归在那里;且复习-06 的验收就是「带来源标记」,隐藏它等于它不存在。
> - 用户标签**可重命名**(一次更新影响所有带该标签的对象)**、可删除**(从所有对象移除)。不做「废弃而非删除」那套状态机。
> - 改名安全性依据:文档明确「标记不参与聚合口径,也不改变内容归属」,因此批量改名不存在数据口径风险——这正是它与「改内容归属」的关键区别。
> - 已排除:系统标记对用户隐藏(用户无法解释学习引导碎片为何归在那里、调试时看不到系统写了什么);只能删不能改名(改名退化为「删旧建新 + 逐条重打」,而批量改名本身无数据风险);可废弃(多一套状态转换与检索判断,而标签不参与聚合、保留历史标记的收益很小)。
>
> **标记-01 已完成(2026-10-09)。** 完成于 `lpt-be` `c6258fa`(+ `lpt-fe` `232fdb8`)。
>
> **标记-01 决策完毕(2026-10-09),可以开工。** 实现要点:一张通用标记表(`object_type` ∈ {FRAGMENT,TASK} + `object_num` + `kind` ∈ {SYSTEM,USER} + `marker_name` + 可空 `marker_value` + 建立者/时间);系统标记走代码枚举词表且用户只读;索引两条(按标记找对象、按对象列标记);前端提供点标签即筛选的单一筛选入口。
- **文档**:`lpt-docs/docs/concepts/marker.md`(新增,含 5 个待决问题)
- **背景**:来源标记、用户标签等弱信息分散在各功能里考虑,缺少统一存放位置;每新增一种标记就要改一次功能表结构。
- **已定**:标记统一存放,至少包含对象类型与标识、标记名与值、种类(系统标记 / 用户标签)、建立者与时间;标记不是状态——会话状态、报告可否修订、导图是否待更新这类流程判断留在主体上;学习引导产出的碎片带「来自学习引导」系统标记。
@@ -396,6 +654,220 @@
---
## 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`。
- **验收**:学习会话中可一键开始/结束录音,并看到状态与转写结果。
## 13. 学习闭环重构(新需求,2026‑10‑10)
> **状态:口径已定(2026‑10‑10 维护者确认),可以实施。** 本节把维护者 2026‑10‑10 提出的产品方向整理成可执行条目。概念级设计(为什么这样学、概念如何组织)仍归 `lpt-docs`,本节只放**待办、依据与验收标准**;本轮决策已同步写入 `lpt-docs`(标记、标准思维导图、回忆对比、复习 Feed、复习回路、模块边界)。
>
> **共同背景(为什么做)**:学习过程中「定义」这类内容其实不多,残片产生量有限、且往往集中出现;真正消耗时间的是「如何正确识别这些概念」与「概念的实际应用」(大部分发生在做题过程中)。现有实现把残片级操作铺在首页,聚合维度又只有「任务」一个,撑不起「按概念 / 按应用场景」的学习闭环。
>
> **现状坐标(接手时先看这里)**
> - **首页** = `/welcome` → `lpt-fe/src/components/Welcome.vue`:落地页(`Login.vue:44` 登录后跳这里),实际承担的是**复习 Feed 滚动条**(`getReviewFeed(100, "smart")`),并在残片卡片上直接挂了写操作。
> - **复习模块** = `/review` → `lpt-fe/src/components/Review.vue`:任务维度总览(任务卡片 + 统计、待归类内容、标签管理弹窗、导出/排序偏好),任务卡片主操作是「回忆复习」。
> - **任务执行页** = `/start-task/:taskNum` → `lpt-fe/src/components/StartTask.vue`。
> - **基础导图** = 表 `review_standard_mind_maps`,端点 `GET/PUT /review/standard-mind-map/{taskNum}`、`POST /review/standard-mind-map/{taskNum}/find-node`(均在 `ReviewController`);前端 `lpt-fe/src/api/standardMindMap.ts` + `components/MindMapViewer.vue`(已支持 `:editable`)。
> - **残片标签** = 表 `markers`,端点 `GET|POST /markers`、`POST /markers/batch`、`DELETE /markers/{id}`、`PUT /markers/rename`、`GET /markers/filter`、`GET /markers/tags`;系统词表 `SystemMarkerEnum` 目前只有 `FROM_GUIDANCE("来源", "学习引导")`。
---
### 闭环-01 操作入口归位:首页只暴露残片内容
- [x] 已完成
- **完成于** `lpt-fe` `33b1c8a`
- **涉及仓库**:`lpt-fe`(`components/Welcome.vue`、`components/ReviewDetail.vue`、`components/Review.vue`)
- **依据**:`Welcome.vue` 的残片卡片当前直接挂了 `MarkerChips`(`Welcome.vue:497`,打标签/筛选)与三个动作按钮「已掌握 / 稍后再看 / 学习引导」(`Welcome.vue:504-525`);另有 `color-legend` 图例(`Welcome.vue:465`,文案「学习残片」+ 一段 tooltip 解释)。首页因此同时承担了「暴露内容」与「执行操作」两件事。
- **建议**:
1. 首页滚动条只保留**只读展示**:残片正文、来源任务、时间等;移除打标签、反馈(已掌握/稍后再看)、学习引导等写操作控件。
2. 移除 `color-legend` 图例及其 `el-tooltip` 说明(「学习碎片」图例即此处)。
3. 上述操作改在复习模块完成。落点需先定:复习 Feed 就地操作,还是进 `ReviewDetail.vue` 详情后操作。
- **已定口径(2026‑10‑10)**:
- 首页保留「点击残片跳到复习详情」的纯导航;打标签、反馈(已掌握/稍后再看)、学习引导集中到 **`ReviewDetail.vue` 详情页**,不为残片新增独立的操作面板。
- **归类仍留在 Feed 卡片**(与 §10 归属-01 一致:归类只是一次选择,复习是成本最低的时机),本次不迁移。
- **已实施**:`Welcome.vue` 只保留只读展示与导航(删掉 `MarkerChips`、三个动作按钮、`color-legend` 图例与标记筛选条,回想卡片新增「查看详情」入口),归类仍留在 Feed 卡片;`ReviewDetail.vue` 新增碎片操作区(`MarkerChips` 打标签/删标签、已掌握/稍后再看、学习引导);点碎片标签跳 `/review?markerName=xxx` 并在 `Review.vue` 挂载时应用该筛选。
- **验收**:首页不出现任何打标签/反馈/引导控件与图例;同样的操作在复习模块内可完成。✅ `Welcome.spec.ts` 改为只读断言(控件/图例不存在、`getMarkersBatch` 不被调用、可进详情),新增 `ReviewDetail.spec.ts`(4 例:标记增删、标签跳转筛选、反馈回显、学习引导)与 `Review.spec.ts`(2 例:带/不带 `markerName`);`npm run type-check` 与全量 `npm test`(39 文件 / 245 用例)全绿
### 闭环-02 任务名自动成为标签(把「任务」降级成一种标签)
- [x] 已完成
- **完成于** `lpt-be` `99290d9`
- **涉及仓库**:`lpt-be`(残片产生路径)
- **依据**:任务名目前只是 `tasks.task_name`,没进标签体系;而 `markers` 已支持自由标签(`MarkerKindEnum` 的 TAG)与系统标记两套语义(见 §5 标记-01)。回忆复习里导图取材已改为「归属该任务的残片」(§5 归属-01),聚合维度实际被任务锁死。
- **建议**:残片落库时自动打一条「任务名标签」,用户可改可删;实现上优先复用 `markers` 的自由标签,不再造第二套标签存储。
- **已定口径(2026‑10‑10)**:
- 任务名标签走**自由标签**(`MarkerKindEnum` 的 TAG),可改名、可删除;不给 `SystemMarkerEnum` 增类型。
- 打标时机:残片获得内容归属时打——产生时即有归属,或之后被归类时**补打**;学习引导产出的碎片同样适用。
- 任务改名**不追溯**:历史碎片保留当时的名字,不批量改写旧标签。
- 删任务时自动标签**保留**(残片按既有语义进入待归类)。
- **已实施**:打标收敛到 `MarkerService.addOwnerTaskNameTag(...)` 一个内部方法,四处调用:碎片创建 `createFragments`、`PUT /report-fragments/{id}`(升格/归类)、`PUT /report-fragments/{id}/ownership`、学习引导 `GuidanceServiceImpl.confirmFragment`;同名用户标签幂等不重复。前端无需改动(标签本来就走 `MarkerChips` 展示)。
- **验收**:新建残片后自动带上任务名标签;用户可修改或删除;同一任务名的残片能用该标签一次筛出。✅ 落库集成测试覆盖:创建即有归属自动打标、归类补打、同名不重复、任务改名后历史标签不变、删任务标签保留
### 闭环-03 标签管理与打标签时搜索选择
- [x] 已完成
- **完成于** `lpt-be` `6ea408e`、`lpt-fe` `4c43364`
- **涉及仓库**:`lpt-fe`(`components/MarkerChips.vue`、`Review.vue` 的标签管理弹窗)+ `lpt-be`
- **依据**:`MarkerChips.vue` 的打标签入口是普通 `el-input`(`placeholder="标签名"`,`MarkerChips.vue:87`),**没有候选也没有搜索**,只能靠记忆手输;标签管理目前只有 `Review.vue:509` 的弹窗 + `PUT /markers/rename`、`GET /markers/tags`(用量统计),没有「提前新建/批量整理」的入口。
- **建议**:
1. 标签管理支持提前增删改:新建空标签、改名、删除、看用量。
2. 打标签改为可搜索选择:输入即过滤已有标签(含自动的任务名标签),同时允许输入新标签。
3. 「提前存在的标签」目前无处可放(`markers` 的每一行都挂在一个对象上)。这是本条的**实现前提**,见下。
- **已定口径(2026‑10‑10)**:
- 标签字典**新增 `user_tags` 表**,不为「无对象标签」在 `markers` 里造行。
- 字典只做候选:改名与删除**不影响**任何对象上已打好的标记。
- 去重口径:名字按 trim + 大小写不敏感判重,展示保留用户输入的原样。
- **已实施(后端)**:`user_tags`(`tag_name` 原样 + `normalized_name` trim+小写,`UNIQUE(created_by, normalized_name)`);接口 `GET|POST /markers/tags/dictionary`、`PUT|DELETE /markers/tags/dictionary/{id}`、`GET /markers/tags/candidates?keyword=`(字典 ∪ 已用过的用户标签);打标签时输入不在字典里的名字会自动补进字典,删除后同名再被用到时复用(复活)旧行避免撞唯一键。
- **待做(前端)**:`MarkerChips` 打标签改为可搜索选择(用 candidates),`Review.vue` 的标签管理弹窗支持提前新建空标签 / 字典改名 / 删除字典项。
- **已实施(前端)**:`api/markers.ts` 补 5 个接口封装;`MarkerChips.vue` 的打标签入口改成 `el-select`(filterable + allow-create),打开输入框时拉一次 candidates,既可搜已有标签也可直接输入新名字;`Review.vue` 标签管理弹窗拆成两块——「标签字典」(新建空标签 / 改名 / 删除,只影响候选)与「已用过的标签」(沿用标记-01 的批量改名与连带删除),文案明示两者区别。
- **验收**:可在标签管理里提前建好标签;打标签时能搜到并选中;删除字典标签不破坏已有标记。✅ 单测:`markers.spec.ts` 覆盖 5 个新接口;`MarkerChips.spec.ts` 覆盖候选拉取、直接输入新标签、系统标记只读与用户标签筛选/删除;`Review.spec.ts` 覆盖字典新建与删除(并断言不触发 `renameDictionaryTag`);`npm run type-check` 与全量 `npm test`(40 文件 / 252 用例)全绿
### 闭环-04 按标签做回忆复习并生成导图
- [x] 已完成
- **完成于** `lpt-be` `6a30022`(新增标签导图存储与生成)、`4b30c88`(标签范围回忆对比与记录口径),均在 `dev` 分支;`lpt-fe` `72a1792`(新增按标签复习与标签导图页面,路由 `/review/by-tag`,复习总览工具栏有「按标签复习」入口)
- **涉及仓库**:`lpt-be`(导图存储与取材口径、回忆对比入口)+ `lpt-fe`(`Review.vue` / `ReviewRecall.vue`)+ `lpt-ai`(提示词入参)
- **依据**:回忆复习目前是任务维度——`Review.vue` 任务卡片主操作进 `/review/recall/:taskNum`(`ReviewRecall.vue`),基础导图也按 `taskNum` 存取。想要「按概念复习」,现在没有任何入口。
- **建议**:复习模块增加「按标签复习」:选一个或多个标签 → 聚合带这些标签的残片 → 生成/更新一张导图 → 走既有回忆对比链路。
- **已定口径(2026‑10‑10)**:
- 与按任务复习**并存**,不替换既有 `/review/recall/:taskNum`。
- 标签导图**新增独立表**(以规范化标签集合为键),不改 `review_standard_mind_maps` 的 task_num 唯一键。
- 多标签由用户在界面上选**并集/交集**(默认并集);缓存键把标签集合(排序后)与模式一起纳入。
- 重算**手动触发**:素材变化只置「待更新」,与报告-01 的导图重建口径一致。
- 按标签复习**写回忆记录**:`review_recall_records.task_num` 改为可空,并加范围列(任务/标签 + 标签集合),复习耗时与覆盖率统计一并可用。
- **已实施**:`review_tag_mind_maps` 独立表(范围键 = 归一化标签集合排序拼接 + 取数模式的 SHA-256,合一即同一张导图);`review_recall_records.task_num` 改为可空并新增 `scope_type`/`scope_key`/`scope_tags`/`scope_mode` 范围列,任务范围行显式写 `scope_type=TASK`,既有任务维度统计与查询口径不变;多标签由界面选并集(UNION)/交集(INTERSECT),默认并集;生成走 `POST /ai/tasks` 的 `TAG_MIND_MAP`(targetNum=范围键,params 带 tags/combineMode/mode),回忆对比走 `TAG_RECALL_COMPARE`;素材变化(标签增删改、碎片删除、碎片获得自动任务名标签)只置「待更新」,重建手动触发;lpt-ai 未改动(沿用既有提示词入参)。
- **接口**:`POST /review/tag-mind-map/query`(读范围状态,不触发生成)、`PUT /review/tag-mind-map`(整体大纲保存,不存在即新建)、`POST /review/tag-mind-map/recall-records`(范围历史)。
- **验收**:选定标签后可生成导图并完成一次回忆对比,记录落库可追溯;不影响既有按任务复习。✅ `lpt-be` 全量 `./mvnw -o test` = 452 用例 0 失败(含标签导图取材并集/交集、范围键稳定、素材变化只置待更新、软删除碎片不取材、租户隔离、任务维度统计不受标签行影响);`lpt-fe` `vue-tsc` 干净 + 全量 `npx vitest run` = 42 文件 / 259 用例全绿(新增 `tagMindMap.spec.ts` 3 例与 `TagReview.spec.ts` 4 例)。
### 闭环-05 任务执行页展示并编辑该任务的基础导图
- [x] 已完成
- **完成于** `lpt-fe` `dfa9b1d`
- **涉及仓库**:`lpt-fe`(`components/StartTask.vue`)
- **依据**:后端**已有** `GET/PUT /review/standard-mind-map/{taskNum}` 与 `POST .../find-node`;前端 `api/standardMindMap.ts` 已封装 `getStandardMindMap` / `updateStandardMindMap` / `findNode`,`MindMapViewer.vue` 已支持 `:editable="true"`。但这套只在 `ReviewRecall.vue`(`/review/recall/:taskNum`)用过,`StartTask.vue`(任务执行页)完全没有导图。**所以这条基本是前端接线,不需要后端改造。**
- **建议**:任务执行页增加该任务基础导图的展示 + 就地编辑(复用 `MindMapViewer` 与既有 PUT),让「应用知识时发现定义有缺陷」能立刻改导图。
- **已定口径(2026‑10‑10)**:
- 编辑粒度与回忆页一致:复用 `MindMapViewer` 的**全量编辑**(Tab 加子节点 / Enter 加同级 / 双击改文字 / 拖拽 / 右键菜单),保存走 `toOutline()` + 整体 `PUT`。
- 并发覆盖:**保持整体 PUT 覆盖,暂不加乐观锁**(两个入口同时编辑会「后写覆盖先写」,风险已知悉;需要时另开条目补版本校验)。
- **已实施**:`StartTask.vue` 新增「基础导图」卡片,复用 `getStandardMindMap` / `updateStandardMindMap` 与 `MindMapViewer`;任务加载时并行拉取导图(失败不阻塞学习主流程),无导图时以「新建导图」入口给一个以任务名命名的根节点,保存即新建;`needsUpdate` 提示与复习页同义(重建仍只在复习页手动触发)。
- **验收**:任务执行页能看到当前任务的基础导图;改动后能在复习页看到同一份(同一份数据,两处共用 PUT);编辑冲突按已定口径为「后写覆盖」。✅ 单测覆盖「拉取后渲成树 + 编辑后整体 PUT 保存」「无导图时以任务名作根节点新建」;`npm run type-check` 与全量 `npm test`(37 文件 / 241 用例)全绿
### 闭环-06 记录应用过程中犯的错误(本次只出设计)
- [ ] 未完成(**已定:本次只出设计,不动代码**)
- **涉及仓库**:设计落 `lpt-docs`(概念文档 `error-record.md`);实现阶段才碰 `lpt-be` + `lpt-fe`
- **依据**:维护者观察——学习时间主要花在「识别概念」与「实际应用(做题)」上,而现在的残片体系只适合记录「刚学到的内容」,**没有地方记录「用错了 / 做错了」**。这类信息才是查缺补漏的直接线索,且天然发生在做题时(不在学习页面)。
- **已定设计(2026‑10‑10,维护者确认)**:详见 `lpt-docs/docs/concepts/error-record.md`。要点:新增独立实体(不复用残片 + 系统标记);概念/导图节点关联**可选**;入口允许从题目直接记录;复习方式是**单独的错误回看列表**(按概念/标签聚合),不进现有 Feed;AI 归并作为二期能力且**必须由用户手动触发**。
- **实现前仍需定**:错误记录与内容归属的关系;回看列表与复习总览的入口关系;删除口径。
- **验收**:待上述待定项定稿后补。**在数据模型与入口定下来之前不要动手实现。**
---
## 附录 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);