Files
lpt-meta/.agents/roles/visual-communication.md
T

82 lines
5.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 图示优先的表达
- **功能**:规定「界面长什么样、流程怎么走、结构怎么连」这类信息一律用图交付,禁止在回复里用等宽字符 / 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
```