docs: 新增说人话与图示优先两条规则,登记跨仓库笔记

This commit is contained in:
cat-shark
2026-11-20 09:36:54 +08:00
parent 84ce312e4b
commit 281585698b
7 changed files with 241 additions and 4 deletions
@@ -0,0 +1,70 @@
# Agent Note: 下线内容暴露记录,复习参考资料只取知识碎片
Status: implemented
## Problem
回忆侧曾有三套记录同时存在:回忆请求(`requests`)、回忆记录(`RecallRecord`)、以及「内容暴露记录」——用户看到过哪条提示、哪段原文,都通过 `POST /review/recalls/{recallNum}/exposures` 写回文档(`detail.exposures`),再作为 `exposures` 传给 AI。
这条链路实际没有消费方:不做评分、不做统计、页面也不读它。它带来的成本却很实在——前端要维护离线重放队列与冲突判定,后端要在隐私清理时多判一次「是否已显示」,AI 请求体多一个字段并多一套校验。同时它把「看过」这件事固化成事实,与「不按提示次数扣分、不推断记忆来源」的设计意图天然拉扯。
同一次排查还发现资料的组成过宽:复习参考资料同时装入知识碎片、同源学习报告与任务范围内的应用场景。界面把每条资料的 80 字预览常驻,预览已含结论;学习报告摘要更接近标准答案。三者都在用户主动索取之前把内容铺开。
## Decision
### 一、删除内容暴露记录(三仓库同批)
- 删除端点 `POST /review/recalls/{recallNum}/exposures`、DTO `ExposureRequest` / `Exposure` / `AiExposure`、`RecallDetail.exposures`、AI 请求体的 `exposures`。
- 删除写入点:`revealHint` / `applyHints` / `exposeCheck` / `openSource`;前端不再有 `useRecallDraft` 的 `pendingExposures` 队列(离线重放、冲突判定、`beforeunload` 条件随之简化)。
- 删除读取点:隐私清理 `sourceDeleted` 的 `exposed` 分支、`ReviewRecallStore` 的脱敏映射、`RecallAiService` 的 `AiExposure` 组装、`lpt-ai` 的字段校验与 prompt 规则。
- 迁移 `V20261118_2__strip_recall_exposures`:按 id 流式清理 `document_json.detail.exposures`,其它字段原样保留;解析失败或结构不可识别的文档原样跳过并计数(日志只带 id),不阻断升级、不新增删除路径。幂等。
- 读兼容依赖 `RecallJson.readStored` 的 `FAIL_ON_UNKNOWN_PROPERTIES=false`:历史文档里的 `exposures`、`REPORT`、`APPLICATION` 来源都不再导致反序列化失败,首次写入时自然落掉旧字段。
- 保留:提示默认模糊、点「显示内容」在本地展开(`revealed` 内存集合);回忆查漏结果直接展开。行为不变,只是不再回写。
### 二、复习参考资料 = 本次复习范围选中的知识碎片
- `RecallReferenceLoader.snapshot` 只产 `FRAGMENT` 来源;学习报告(`REPORT`)与应用场景(`APPLICATION`)不再进入参考资料,limitations 只留「资料可能有遗漏或相互冲突,不作为标准答案。」
- 概念文档同口径:`review-reference.md` 的来源表只剩知识碎片,并明确排除学习报告、保存的思维导图与应用场景;`recall-hint.md` 删掉「内容暴露记录」整节,「尽量避开已经表达或提示的内容」收窄为「已经表达的内容」。
- 从来源直接开回忆(`entry`)仍支持 `FRAGMENT` / `REPORT` 入口,这与参考资料组成是两件事,不改。
### 三、界面:本次资料 → 相关碎片
- 标题「相关碎片(N 条)」,旁挂一个信息图标,说明这些碎片按本次所选复习范围取出(碎片实际用户标签的并集或交集),不含学习报告;后端给的限制说明并进同一个图标,不再并排两个问号。
- 只渲染 `role === 'PRIMARY'`(知识碎片);学习报告条目不显示。
- 条目默认收起,只给标题与角色;点「展开」才显示原文开头 80 字,「查看全文」读全文。原文弹窗标题改为「原文」。预览不再常驻。
### 四、布局:导图铺满整屏 + 全部内容浮层
评审第一版是「导图 | 辅助栏」两栏,导图仍只占半屏;第二版改成导图铺满工作区、辅助区浮在右上,但页头、范围行、计时条仍按文档流占据顶部一整块(截图红框)。最终版把整页变成画布:
- `.recall-workspace.workspace-canvas` 用 `position: fixed; inset: 0` 铺满视口,导图卡片 `position: absolute; inset: 0`,页面本身不产生滚动条。
- 页头(`MyHead`)在 App.vue 里按 `route.meta.recallWorkspace && route.params.recallNum` 切到 `canvas-shell`:`position: fixed` + 半透明底 + 毛玻璃 + 阴影,`pointer-events: none` 让空白处透传点击,只有卡片本身可交互。标签入口页(`/review/by-tag`)没有 `recallNum`,仍是普通文档流。
- 左下 `.hud`:范围名 + 状态 chip + 同步状态 + 计时三组 + 操作(更多 / 切换范围 / 完成回忆);可收成一行摘要(状态 + 倒计时 + 有效时间 + 展开)。提醒、离线提示、草稿恢复面板同在这个左下栈里。
- 右上 `.help-drawer`:提示与查漏(请求 → 结果 → 相关碎片),可收成一条标题条;抽屉内部一条滚动轴,不引出页面滚动。2026-11-19 起抽屉只留最近一次结果,另加「放大」三栏视图,见 [自由回忆辅助区放大成三栏阅读](../../../../lpt-fe/.agents/notes/implemented/feature/2026-11-19-recall-help-expanded-reading.md)。
- 导图自带的左上工具条、空图提示、节点配色面板统一让开页头:`top: calc(var(--shell-header-height) + …)`。
- 窄屏:辅助区改成 `position: fixed` 的贴底抽屉(默认收起),状态条同样可收起;导图仍然铺满。
- 窄屏页头压成一行(约 48px):返回、`AI 用量统计`、`退出登录` 在画布页窄屏换成图标(`MyHead` 按 `route.meta.recallWorkspace` 挂 `compact-head`,桌面仍保留文字)。原来 ≤768px 的「竖排 + 按钮满宽」在画布页会把整块导航堆三行。
- 计时问号并进「有效时间」的值行(`timing-value-row`),不再作为 `recall-metrics` 的独立子项吃 `border-left`,避免看起来像空白第三列。
- 浮层卡片在窄屏会被内容撑宽:`.hud-stack` / `.hud` 都改用 `grid-template-columns: minmax(0, 1fr)` 并给子项 `min-width: 0`;`.hud .workspace-header` 在 ≤768px 允许换行(范围名独占一行,状态与收起同行)。
- 节点配色入口补上触屏路径:mind-elixir 只监听 `contextmenu`(右键/安卓长按),iOS 长按不触发,只读草稿也根本没有菜单。现在选中节点后会在节点上方浮出「配色」小按钮(`MindMapViewer` 内 `.palette-chip`),点它打开同一个面板;面板改成贴着选中节点出现(原来是固定右上,正好被浮动的提示抽屉压住),窄屏(≤768px)进一步改成贴底横条,避免和 HUD、提示文案互相挤压。
## Alternatives considered
- **保留「内容暴露记录」,只在界面弱化展示**:能力还在,未来想做「提示依赖度」分析时不用重做契约。但用户判断这个设计本身无用,弱化后的数据没人读,却要继续维护三仓库字段、隐私分支、离线队列与 AI prompt 规则,维护成本不降反升,因此整条删除。
- **参考资料同时保留学习报告与应用场景**:上下文更全,查漏时能引用报告结论。但它们不是「应回忆的知识」,混进引用会让 AI 把总结当标准答案,也让「本次资料」的来源说不清;用户明确要求只取知识碎片。
- **后端照旧返回、前端只过滤不显示报告**:改动最小,不用动 AI 与迁移。但报告仍会进 `units` 与 AI prompt,支付 token 且扩大隐私面,属于「界面上看不见、系统里还在」,否决。
- **保留 `POST /exposures` 端点一段时间做兼容**:可以避免三仓库同批发布。但暴露记录已无消费方,留着就会有人接,最终还是要删;三仓库同一分支一起发(`dev` 配 `dev`、`master` 配 `master`)已经能覆盖升级窗口,因此不留兼容层。
- **迁移脚本遇到坏 `documentJson` 直接删整条回忆**:数据一致但会误删用户内容。改为跳过并计数、只记 id,保留「唯一删除路径仍是 `ReviewRecallStore.deleteUnreadable`」的边界。
## Consequences
- 三个仓库必须同批发布:BE 停发字段、AI 停收、FE 停调;单独上线会出现 400/404。旧客户端访问旧端点会 404。
- AI 不再知道「已经给过哪些提示」,用户可能收到重复线索。这是删除暴露记录的已知代价,评审时接受。
- 旧草稿的 `documentJson` 仍可能带 `detail.exposures`:读取靠 `RecallJson.readStored` 的 `FAIL_ON_UNKNOWN_PROPERTIES=false` 兼容,写入前由迁移 `V20261118_2` 清掉;迁移坏 JSON 跳过并计数、幂等、不阻断升级。
- 「相关碎片」只列知识碎片,条数等于实际行数(`RecallReferenceLoader.knowledgeSources()`)。
- 布局改成整页画布后,页面自身不再滚动,滚动只发生在辅助区抽屉内部;窄屏页头压成一行图标,桌面仍保留文字按钮。
- 少了一条链路(提交暴露、离线补发、隐私分支、AI prompt 规则)与一个字段,AI 输入变小、成本下降;代价是将来要做「提示依赖度」类分析需要重新设计。
## 未决
- 保存的思维导图是否仍保留「参考关系」:代码侧参考资料从未包含保存图,但 `mind-map.md`、`principles.md` 等 8 处文档仍写「保存图默认在对应范围启用参考、参与以后核对」。本轮未改,需单独定口径。
@@ -0,0 +1,40 @@
# Agent Note: 新增「说人话」规则,禁止用行话统称代替具体内容
Status: implemented
## Problem
在评估 `lpt-fe` 前端设计规则时,我把「焦点环的颜色宽度偏移、动效的时长与缓动、层叠顺序的档位」三组具体取值说成「设计系统缺三类 token」,还用「token 是设计取值变量」这种再抽象一步的方式解释。用户连续两次追问才听懂,最后指出这只是「颜色和大小相关的常量」,要求以后直接说人话。
问题不在术语本身对不对,在**用抽象统称代替具体内容**:读者必须先猜「三类 token」包含什么,才能判断这个结论与自己有没有关系。既有规则管不到这件事——`business-terminology.md` 管的是业务概念叫哪个名字(且要求用术语表原词),`visual-communication.md` 管的是用什么媒介表达(图还是表),两者都不约束「拿工程行话包装日常概念」和「先抛统称再让读者拆」。
## Decision
新增通用规则 `.agents/roles/plain-language.md`(说人话),四组硬约束:
1. **先给具体,再给统称**:回答「是什么 / 缺什么 / 怎么改」时,第一句写具体对象与取值,统称只在具体项之后出现用来收口。
2. **日常概念不用行话包装**:颜色、字号、间距、圆角、层叠顺序就叫「取值 / 常量」,不叫 token、design token、设计令牌;外部框架造词进中文回复要先翻成动作描述。
3. **一句话最多一层抽象**:禁止「X 体系的 Y 机制」「三类 Z」这类只描述结构、不落到对象的句子。
4. **自查**:把每个统称问一句「它具体指哪几个东西」,答不出或要绕一圈就重写;用户已经追问过的句子,下次直接写进回复。
生效方式按 `.agents/roles/README.md` 的「规则文件不是自动加载入口」:在 meta `AGENTS.md` 的通用规则清单里登记(标强制),并在 `.agents/roles/README.md` 的规则清单表加一行触发场景。`business-terminology.md` 末尾加一条指认边界的链接——术语表管「叫哪个名字」,说人话管「用什么说法讲」,避免两条规则被读成互相冲突。
## Alternatives considered
### 为什么不写进 `business-terminology.md`?
`business-terminology.md` 的单一职责是「同一概念在同一套名字上对齐」,核心是术语表这个权威源;把语域规则塞进去会让它同时承担两件事,而它已经被 9 个文件引用为术语权威,改动面大、语义还会变糊。新增一份 38 行的规则文件成本更低,触发场景也独立(写回复时读,而不是描述系统概念时读)。
### 为什么不写进 `visual-communication.md`?
那份规则的对象是**表达媒介**(图 / 表 / 代码块),判定标准是「信息类型该不该画成图」。说人话的对象是**用词层级**,与媒介无关:一段纯文字表格同样可以说得抽象。合并会让「什么时候该画图」的判断被稀释。
### 为什么不改名 `business-terminology.md` 来容纳两者?
改名要同步 `AGENTS.md`(meta、lpt-be、lpt-fe、lpt-ai、lpt-android、lpt-docs)、`lpt-docs/.agents/roles/documentation-scope.md`、`OPTIMIZATION_BACKLOG.md` 共 9 处引用。规则新增比规则改名便宜,且改名不带来任何行为差异。
## Consequences
- 后续回复与交付说明多了一道自查:每个统称要能立刻展开成具体项。代价是句子会变长一点,收益是用户不必追问「这是什么意思」。
- 规则只约束表达,不约束代码标识符与命令(`plain-language.md` 的「不在约束内」已写清),不会与 `business-terminology.md` 的英文名派生要求打架。
- 这条规则靠自觉执行,没有脚本门禁;能机械检查的部分(行话黑名单)暂不做,因为黑名单必然漏词,而误判成本高于收益。
+2
View File
@@ -67,3 +67,5 @@
| 跨仓库 Git 操作 | `repo-operations.md` | 对子项目执行 git 命令时 |
| 开发环境自解锁与求助阈值 | `dev-unblock-and-escalation.md` | 被登录/权限/凭据卡住、同一问题反复尝试未解决时 |
| 业务名词收敛 | `business-terminology.md` | 描述系统概念、拆需求、派子代理、写笔记或提交信息时 |
| 图示优先的表达 | `visual-communication.md` | 汇报布局/流程/结构、做设计评审、回答「长什么样」时 |
| 说人话 | `plain-language.md` | 写回复、解释方案与取舍、写交付说明时;用户说「什么意思」「太复杂」时 |
+1
View File
@@ -44,3 +44,4 @@
- 新概念尚未定稿:标「术语待定」并在同一次改动里补表,不要用「暂时叫 X」了事。
- 术语表与代码、注释、文档用词冲突:以术语表为准修正其他位置,按 `research-and-reporting.md` 报事实,不自行造词补齐。
- 交付前自查:把本次回复与改动里的业务名词、以及新增或改动的类名/表名/字段名/前端类型名,逐项对一遍术语表;解释不出来的就是自造词,出现表外词就是未完成。
- 用词层级不在本文约束内:术语表管「叫哪个名字」,说人话管「用什么说法讲」,见 `plain-language.md`。
+38
View File
@@ -0,0 +1,38 @@
# 说人话
- **功能**:约束回复、解释与交付说明的用词层级,禁止拿行话统称代替具体内容,让没读过实现的人也能对上号。
- **何时用**:写面向用户的回复、解释方案与取舍、写交付说明、做设计或规则评审时(**强制**);用户说「什么意思」「太复杂」「说人话」时。
## 规则
### 先给具体,再给统称
- 回答「是什么 / 缺什么 / 怎么改」,第一句就写具体对象和具体取值:什么颜色、多宽、偏移多少、几毫秒、落在哪个文件哪一处。
- 统称只在具体项列完之后出现,用来收口,不用来开场。禁止先抛一个统称(「三类 X 机制」「Y 体系」)再让读者猜它包含什么。
### 日常概念不用行话包装
- 颜色、字号、间距、圆角、层叠顺序这类东西就叫「取值」或「常量」,不叫 token、design token、设计令牌。
- 外部框架的造词(token、primitive、style lock、lint 规则名等)要进中文回复,先翻成动作描述:「先查有没有现成的、没有再画」「按钮的悬停、按下、聚焦三种样子都要有」。
- 必须保留的外部专名(Flyway、Sa-Token 这类产品或命令)按原样写,但首次出现要附一句中文说明它干什么。
### 一句话最多一层抽象
- 不写「X 体系的 Y 机制」「三类 Z」这种只描述结构、不落到对象的句子;一律改成「哪三个东西、各是什么、分别用在哪」。
- 被问「这是什么意思」时,先用人话答完,再决定要不要补术语名;不要反过来先讲名字再解释。
### 不借术语省字
- 术语为了指向准确,不为缩短句子;省下来的字由读者承担。
- 同一个抽象统称在一段里出现两次以上,说明自己在绕,停下来把第一句改写成具体项。
### 自查
- 把回复里每个统称问一句「它具体指哪几个东西」;答不出、或要绕一圈才答得出,就重写成具体项。
- 提前写出「用户最可能追问的那一句」;用户已经追问过,就说明前一条没做到,下次直接写进去。
- 用户明确说过「说人话」之后,后续同类内容直接按本条执行,不逐次解释为什么之前换了个说法。
## 不在约束内
- 代码标识符、字段名、命令、路径按代码原样书写,不为「说人话」改造它们。
- 业务概念名仍以 `lpt-docs/docs/concepts/README.md` 术语表为准(见 `business-terminology.md`):说人话是不拿行话包装,不是把术语表里的词换成别名。
+81
View File
@@ -0,0 +1,81 @@
# 图示优先的表达
- **功能**:规定「界面长什么样、流程怎么走、结构怎么连」这类信息一律用图交付,禁止在回复里用等宽字符 / ASCII 拼框图。
- **何时用**:汇报布局或界面改动、解释流程 / 时序 / 数据流向、给架构与依赖关系、对比改造前后、做设计评审。**纯数据、字段清单、命令输出仍用表格或代码块,不要硬画成图。**
## 规则
### 禁止:等宽字符画
回复正文里不允许出现这类表达:
```text
[‹] 自由回忆 [用量] [退出]
(导图铺满)
[范围名 ]
[正在提示与查漏] ← 这就是被禁止的写法
```
```text
┌─────────┬─────────┐
│ 导图 │ 辅助区 │
└─────────┴─────────┘
```
问题不在美观:字符宽度随字体/终端漂移,错位就失真;不能缩放、不能点击、无法用浏览器打开评审;改一处要重排整块;与实际界面没有可验证的对应关系,读者分不清哪是真实渲染、哪是记忆里的想象。
### 按信息类型选工具,优先级从上到下
| 要表达的东西 | 用什么 | 落在哪 |
|---|---|---|
| 真实运行中的界面 | `agent_browser` 截图(**JPEG q80**),再 `read <jpg>` 让终端内联显示 | `/tmp/*.jpg` 或用户指定目录 |
| 目标态 / 未实现的界面 | SVG 线框(真实文案 + 设计 token 配色) | `docs/diagrams/<主题>/*.svg` |
| 流程、时序、状态流转、依赖关系 | Mermaid(`.mmd` + `rendered/index.html` 评审页) | `docs/diagrams/<主题>/`,按 `.agents/skills/mermaid-diagram` 执行 |
| 纯数据、字段、命令输出 | 表格 / 代码块 | 回复正文 |
- **界面截图必须来自真实运行**:先起服务、进到目标状态,再截。不要凭记忆或代码手绘「应该长这样」冒充截图;做不到就说明没截到,而不是画一张。
- **多视口一次给全**:布局类改动至少 `375 / 768 / 1280`(必要时 1440)各一张,逐张附一句变化点,不要让读者拿一张宽屏图推断窄屏。
- **截图带状态**:折叠/展开、编辑/只读、空态/有数据这些差异要用截图证明,而不是文字保证「也能收起」。
- **图里写真实文案**:SVG/Mermaid 用界面上的真实中文与配色 token,不写 `Lorem`、`节点 A`、`Box 1`。
- **评审页可打开**:设计图放 `docs/diagrams/<主题>/index.html`,本地 `python3 -m http.server 8000` 起服务给链接;改动后递增 `?v=` 版本号。
### 截图体积(强制)
截图会整份进入上下文,并且**每次请求都重新上传**(prompt cache 只省 prefill 算力,不省上行字节)。实测:单张 1280×1000 的 PNG 平均 **126 KB**,33 张 = 4.1 MB 二进制 / 5.7 MB base64,把请求体顶到 8.6 MB,每轮多花 **6–7 秒**上传。
**本机复测(LPT 登录页,1280×800):PNG 385.8 KiB → JPEG q80 54.9 KiB(−86%),图中中文、表单、按钮全部清晰可读。**
- **一律 JPEG q80**。注意 `--screenshot-format` / `--screenshot-quality` 是**全局 flag,必须放在子命令前面**,否则报 `Pass global flags on the outer batch invocation`:
```text
agent_browser({ args: ["--screenshot-format","jpeg","--screenshot-quality","80","screenshot","/tmp/recall-375.jpg"] })
```
需要更稳的文字小字号时用 q90(相对 PNG 仍约 −48%)。
- **路径用 `.jpg`**,不要用 `.png` 命名 JPEG 文件。
- **同一页面没变就不重复截**:在子命令上加 `screenshot <path> --if-changed --threshold 0.05`。未变化时返回 `Screenshot unchanged; no image saved.`(`success`,不产图)——这是「没变化」而不是「截图失败」。⚠️ 已实测:**首次调用不会跳过**(需先有一次基线截图),所以只作为省体积的附加手段,不要指望它替代 JPEG 压缩。
- 只有逐像素比对、或交付给设计评审的终稿才用 PNG,并写明理由。
- 视口 `1280×800`~`1440×900` 足够评审;pi 只在 >2000 px 或 >4.5 MB 时才二次压缩,所以**捕获时就得压**。
- 若启动环境已设 `AGENT_BROWSER_SCREENSHOT_FORMAT=jpeg` 与 `AGENT_BROWSER_SCREENSHOT_QUALITY=80`(需重启 pi/pi-web 才生效),全局 flag 可省;未设时按上面显式写。
### 交付格式
1. 先给结论一句话,再贴图(每张图配一行「看什么」)。
2. 终端支持内联图片时直接 `read <图片路径>`(Pi 的 `terminal.showImages` 默认开启,kitty/iTerm2 协议);不支持时给路径 + 一句说明,**仍不退回 ASCII 框图**。
3. 图有版本时同步更新 `index.html` 的说明与 `?v=`,避免浏览器缓存给出旧图。
### 附:可直接复用的取图方式
```text
# 真实界面:按视口矩阵截图(agent_browser 逐条命令,全局 flag 放在最前)
# open http://localhost:5158/... → set viewport 375 812
# → args: ["--screenshot-format","jpeg","--screenshot-quality","80","screenshot","/tmp/recall-375.jpg"]
# 同一页面重复截:子命令尾部加 --if-changed --threshold 0.05
# 然后 read /tmp/recall-375.jpg 让它在对话里内联显示
```
```bash
# 设计图评审页
cd docs/diagrams && python3 -m http.server 8000
# http://localhost:8000/<主题>/index.html
```