From c6140565788a9161a1ffe95fc2aa811291a785ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=9C=E7=81=AF?= Date: Tue, 20 Oct 2026 06:47:31 +0800 Subject: [PATCH 1/2] docs: attach PR screenshots with GitHub CLI Model: gpt-6.1-sol --- .agents/docs/visual-explanations.md | 23 +++++++++++++++---- ...2026-10-20-ui-pr-comparison-screenshots.md | 22 ++++++++++++------ ...6-10-20-ui-pr-comparison-screenshots.zh.md | 19 ++++++++++----- .github/PULL_REQUEST_TEMPLATE.md | 4 +++- 4 files changed, 49 insertions(+), 19 deletions(-) diff --git a/.agents/docs/visual-explanations.md b/.agents/docs/visual-explanations.md index bd1386e7b..6143ac450 100644 --- a/.agents/docs/visual-explanations.md +++ b/.agents/docs/visual-explanations.md @@ -142,17 +142,30 @@ comparable viewport, theme, and interaction state so the difference is clear. Prepare a safe scene before capture: prefer demo or synthetic fixtures and an isolated development data directory over a personal workspace. Crop to the relevant UI while retaining enough context to judge the change. Inspect both -images before uploading or committing for conversation text, source contents, +images before uploading for conversation text, source contents, names, avatars, local paths, repository details, notifications, credentials, and other private content. If cropping or redaction is needed, inspect the final export and share only that sanitized file; do not upload or commit the private original alongside it. Follow the repository's prohibition on captured user or agent transcripts. -Attach safe images inline or link to an artifact reviewers can access; a local -filesystem path alone is not reviewable in a PR. A small side-by-side table works -well for a pair. Captions should identify the relevant state and any deliberate -comparison differences. +Keep PR-only screenshots in temporary or ignored paths and out of Git commits. +Upload safe images as GitHub attachments with `gh pr create --attach` or +`gh pr edit --attach`. +For an existing PR, keep its complete body in `/tmp/pr-body.md` and put +`![Before](/tmp/before.png)` and `![After](/tmp/after.png)` in its Before / After +table, then upload the referenced files: + +```sh +gh pr edit 123 --body-file /tmp/pr-body.md \ + --attach /tmp/before.png --attach /tmp/after.png +``` + +The CLI replaces matching local image references with uploaded attachment URLs. +Without a body file, `--attach` appends the images to the existing PR body. Check +`gh pr edit --help` for the installed CLI's attachment support. Any linked artifact +must be accessible to reviewers; a local filesystem path alone is not reviewable. +Captions should identify the relevant state and any deliberate comparison differences. Screenshots are recommended, not mandatory, and add no submission requirement or automated gate. Authors may omit screenshots without explanation. The existing diff --git a/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.md b/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.md index 17f1676f3..d7eff0ead 100644 --- a/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.md +++ b/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.md @@ -12,7 +12,8 @@ UI pull requests can describe a visible change without showing the result, leaving reviewers to reproduce both versions. The PR template now recommends labeled before/after screenshots, and the visual guide explains how Agents can capture them during implementation using synthetic data. Privacy takes priority: -authors inspect the exported images before sharing. Screenshots are optional +authors inspect the exported images before sharing, then upload review captures +as GitHub attachments instead of committing them. Screenshots are optional and may be omitted without explanation; this guidance adds no automated gate. ## Decision @@ -29,18 +30,25 @@ nearly full root or GitHub `AGENTS.md` files. The comparison uses real UI or owning Storybook fixtures with comparable state, viewport, and theme. Synthetic data and an isolated development scene reduce exposure before capture; inspection of the final crop or redacted export catches -private content before either a public upload or a commit. Captured user/agent +private content before a public upload. Captured user/agent transcripts remain prohibited. Reviewers receive accessible safe artifacts, not local-only paths. +The attachment clarification keeps PR-only captures in temporary or ignored paths, +out of Git history. GitHub CLI supports `gh pr create --attach` and +`gh pr edit --attach`; matching local Markdown image references in the complete body file are rewritten +to uploaded attachment URLs. The guide includes a command for a before/after pair. + Authors decide whether to include screenshots and may omit them without explanation. Existing required template headings and the structural-view validator remain unchanged. ## Verification -The change is documentation only. All 23 existing PR-template and policy tests -passed, including complete and rejected bodies. `pnpm format` and the full -`pnpm check` passed. Documentation checking retains only the six existing missing -Kimi/Pi submodule links in the bilingual subagent-events note, with no new errors -or SHA-protected topic changes. No UI rendering change is claimed. +The attachment clarification is documentation only. All 23 existing PR-template +and policy tests pass. Installed `gh pr create --help` and `gh pr edit --help` +confirm attachment uploads and local image-reference rewriting. `pnpm format` +passes. Documentation checking retains the six existing missing Kimi/Pi submodule +links, with no new errors or protected-topic changes. Full type/build/runtime +checks were not rerun for this documentation-only clarification. Template headings, +validators and runtime code remain unchanged. diff --git a/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.zh.md b/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.zh.md index 090f840bb..97372f8eb 100644 --- a/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.zh.md +++ b/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.zh.md @@ -10,7 +10,8 @@ PR: [#1744](https://github.com/LodyAI/Lody/pull/1744) UI PR 有时只描述可见变化而不展示结果，评审者需要自行复现前后两个版本。 现在 PR 模板推荐附上标注清楚的修改前后截图，可视化指南说明 Agent 如何在实现过程中 -使用合成数据采集对比。隐私优先：作者在分享前检查导出图片。截图并非强制要求， +使用合成数据采集对比。隐私优先：作者在分享前检查导出图片，再作为 GitHub 附件上传， +不把评审截图放进提交。截图并非强制要求， 不提供也无需解释；这条建议没有增加自动检查门槛。 ## 决定 @@ -22,16 +23,22 @@ UI PR 有时只描述可见变化而不展示结果，评审者需要自行复 没有向接近大小上限的根目录或 GitHub `AGENTS.md` 增加新的指令。 截图使用真实 UI 或所属的 Storybook 示例，并保持可比较的界面状态、视口和主题。 -使用合成数据和隔离的开发场景，可以在截图前减少隐私暴露；提交或公开上传前， +使用合成数据和隔离的开发场景，可以在截图前减少隐私暴露；公开上传前， 检查最终裁剪或遮盖后的导出图片，确认其中没有私人内容。禁止提交捕获的用户或 Agent 对话记录的规则继续有效。评审者应能访问安全的图片，不能只有本地路径。 +附件说明明确：仅供 PR 评审的截图放在临时或已忽略的目录，不纳入 Git 提交。 +GitHub CLI 的 `gh pr create --attach` 和 `gh pr edit --attach` 支持直接上传， +并把完整正文文件中匹配的本地 Markdown 图片引用替换为附件链接。 +指南提供修改前后两张图的具体命令。 + 作者自行决定是否附上截图，不提供也无需解释。现有必填模板标题和结构图校验器 均保持不变。 ## 验证 -本次仅修改文档。已有 PR 模板与策略测试共 23 项全部通过，包含完整正文和拒绝案例。 -`pnpm format` 和完整 `pnpm check` 均已通过。文档检查仅保留 subagent-events 双语笔记中 -原有的六个 Kimi/Pi 子模块缺失链接，没有新增错误或需要审阅的 SHA 保护主题变化。 -本次没有改变 UI 渲染行为。 +附件说明仅修改文档。已有 PR 模板与策略测试共 23 项全部通过；本机 +`gh pr create --help` 和 `gh pr edit --help` 确认支持附件上传及本地图片引用替换。 +`pnpm format` 通过。文档检查保留原有六个 Kimi/Pi 子模块缺失链接，没有新增错误或 +保护主题变化。本次文档说明未重跑完整类型、构建和运行时检查。 +模板标题、校验器和运行时代码均未改变。 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index b5a2da49c..00d8e5cf1 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -51,7 +51,9 @@ Any supporting artifact must be reachable by reviewers; a local HTML file is not For UI changes, consider adding labeled Before/After screenshots of the actual UI. Agents: capture the baseline and final result during the implementation loop when practical, using synthetic data and comparable viewport, theme, and UI state. -Inspect both images for private content before uploading or committing. +Inspect both images for private content before uploading. +Upload with GitHub CLI (`gh pr create --attach` or `gh pr edit --attach`). +Keep PR-only screenshots in temporary or ignored paths, out of commits. Screenshots are encouraged, not mandatory; authors may omit them without explanation. This recommendation adds no automated check. Capture and privacy guidance: .agents/docs/visual-explanations.md#ui-screenshots From 81b379377bb650a2dd422e1689fb2c7267c7156b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=9C=E7=81=AF?= Date: Tue, 20 Oct 2026 06:50:14 +0800 Subject: [PATCH 2/2] docs: link screenshot attachment guidance PR Model: gpt-6.1-sol --- .../process/2026-10-20-ui-pr-comparison-screenshots.md | 2 +- .../process/2026-10-20-ui-pr-comparison-screenshots.zh.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.md b/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.md index d7eff0ead..835fe8ee9 100644 --- a/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.md +++ b/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.md @@ -2,7 +2,7 @@ Status: implemented Translation: current -PR: [#1744](https://github.com/LodyAI/Lody/pull/1744) +PR: [#1744](https://github.com/LodyAI/Lody/pull/1744), [#1747](https://github.com/LodyAI/Lody/pull/1747) [中文](2026-10-20-ui-pr-comparison-screenshots.zh.md) diff --git a/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.zh.md b/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.zh.md index 97372f8eb..8b1549203 100644 --- a/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.zh.md +++ b/.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.zh.md @@ -2,7 +2,7 @@ Status: implemented Translation: current -PR: [#1744](https://github.com/LodyAI/Lody/pull/1744) +PR: [#1744](https://github.com/LodyAI/Lody/pull/1744), [#1747](https://github.com/LodyAI/Lody/pull/1747) [English](2026-10-20-ui-pr-comparison-screenshots.md)