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
+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
```