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

5.3 KiB
Raw Blame History

图示优先的表达

  • 功能:规定「界面长什么样、流程怎么走、结构怎么连」这类信息一律用图交付,禁止在回复里用等宽字符 / ASCII 拼框图。
  • 何时用:汇报布局或界面改动、解释流程 / 时序 / 数据流向、给架构与依赖关系、对比改造前后、做设计评审。纯数据、字段清单、命令输出仍用表格或代码块,不要硬画成图。

规则

禁止:等宽字符画

回复正文里不允许出现这类表达:

[‹] 自由回忆            [用量] [退出]
(导图铺满)
[范围名                    ]
[正在提示与查漏]  ← 这就是被禁止的写法
┌─────────┬─────────┐
│ 导图    │ 辅助区  │
└─────────┴─────────┘

问题不在美观:字符宽度随字体/终端漂移,错位就失真;不能缩放、不能点击、无法用浏览器打开评审;改一处要重排整块;与实际界面没有可验证的对应关系,读者分不清哪是真实渲染、哪是记忆里的想象。

按信息类型选工具,优先级从上到下

要表达的东西 用什么 落在哪
真实运行中的界面 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:

    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=,避免浏览器缓存给出旧图。

附:可直接复用的取图方式

# 真实界面:按视口矩阵截图(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 让它在对话里内联显示
# 设计图评审页
cd docs/diagrams && python3 -m http.server 8000
# http://localhost:8000/<主题>/index.html