ship-this

Ship this

UI 变更发布前的最终审查。假定代码可以编译且通过 lint，因此会跳过 lint 工具强制执行的机械式风格检查，但仍会审查逻辑、正确性和安全性。此技能会检查差异中 lint 工具无法发现的设计品质退化，然后将差异整理成简洁的提交信息和 PR 描述。

核心要求

审查已变更的代码，以及验证变更所需的最少周边上下文。不要审计代码库中无关的部分。找出 lint 工具无法检测的退化，例如无障碍性、动效、响应式布局，以及视觉或 UX 偏差。然后撰写提交信息和 PR 描述，确保读起来自然，像是开发者写的，不提及工具归属。

报告的每项结果都必须来自实际运行过的命令或已读取的源文件。绝不要在未运行扫描器的情况下声称秘密扫描已通过；绝不要报告 git 未确认的提交或推送；也不要为了增加审查内容而捏造发现。如果只能部分验证某项内容，应如实说明，不要暗示结果完全正常。

严重性等级

等级	含义
阻断	真实缺陷、泄露的秘密，或已发布的无障碍性问题。不得合并。
提示	值得检查的问题、可能的回归或质量缺口，但不一定有问题。

干净的差异应以空列表通过。不要为了增加列表内容而捏造轻微问题，也不要提出格式和命名偏好。

检查清单

1. 收集差异

收集所有待处理的变更，确保干净的结果可信。开始时读取一次 git 状态、当前分支、其上游分支、默认分支和 git status --short，以便后续步骤复用这些信息，而不是再次调用 shell 命令。选择符合请求的审查范围。

• 即将提交的未提交工作。运行 git diff HEAD，获取已跟踪文件中暂存和未暂存的编辑。
• 准备提交 PR 的整个分支。运行 git diff <base>...HEAD 获取已提交的工作，然后运行 git diff HEAD 获取其上的任何未提交工作。

git diff 不包含未跟踪文件，因此要用 git status --short 检测它们，并直接检查每个新增的 UI 文件。将 <base> 设为 PR 合并到的分支，通常是通过 git symbolic-ref --short refs/remotes/origin/HEAD 得到的默认分支；若无法获取，则依次回退到 origin/main 或 origin/master，仅当不存在远程分支时才回退到本地 main 或 master。不要使用当前分支自己的上游分支，因为它跟踪的是该分支的远程副本，会隐藏大部分变更。如果无法有把握地确定基准分支，请先询问再继续。

2. 审查 UI 差异

根据以下各项检查差异。由于这是静态代码审查，凡是需要查看渲染页面、进行键盘操作或运行减少动态效果模式的检查，都视为尚未验证，并在 Testing 下标记为待处理。

• 无障碍 — 新增的交互元素具备键盘处理程序或原生语义；存在焦点样式且未被移除；焦点顺序合理；没有键盘陷阱；角色和名称正确。
• 动态效果 — 每个新增动画都提供适当的 prefers-reduced-motion 替代方案，使用高性能的动画属性，并且动画有明确理由、频率合理。
• 响应式 — 没有固定宽度导致小视口溢出；包含断点和容器查询逻辑；触控目标尺寸和安全区域处理正确。
• 视觉和 UX 偏差 — 使用设计令牌替代硬编码的颜色、间距和字体样式。改动符合周边设计系统。存在令牌时，不应使用魔法数字。
• 面向用户的文案 — 新增的标签、错误提示、空状态和工具提示都清晰易读。深入审查时，请参考 docs-style-guide 和 writing-checklist 技能。
• 正确性和安全性 — 检查差一错误、null 和 undefined 处理、竞态条件以及注入风险。
• 机密和凭据 — 差异中不得引入令牌、密钥、密码或凭据。请参阅下方的扫描说明。
• 整洁性 — 不留下注释掉的代码块。console.log 和 debugger 交由负责管理它们的代码检查工具处理。

在无障碍、动态效果和响应式设计方面进行深入检查时，请遵循此软件包中的 keyboard-accessibility、motion-design 和 responsive-design 技能。

机密和凭据扫描

差异中若包含凭据，即为阻塞问题。不要合并，并告知用户轮换该凭据，因为提交的机密即使被移除，也已遭到泄露。

• 优先使用真正的扫描工具，而不是目测。如果有 gitleaks、trufflehog、git secrets 或 detect-secrets 可用，请对差异运行扫描，并以其输出为准。使用工具自身规则集中的精确匹配模式，不要自行编写模式。
• 如果没有可用的扫描工具，请改用有记录依据的模式检查，并且只扫描新增行，以免差异删除的机密造成误报。已验证的 GitHub 令牌前缀是具体的识别依据：ghp_ 表示经典令牌，github_pat_ 表示细粒度令牌，gho_ 表示 OAuth 令牌，ghu_ 表示用户到服务器令牌，ghs_ 表示安装令牌，ghr_ 表示刷新令牌。还应检查私钥 PEM 标头，例如 -----BEGIN PRIVATE KEY-----，以及赋给 password、secret、token 或 api_key 等名称的高熵值。
• 如实说明扫描覆盖范围。如果只运行了回退检查，应报告扫描是启发式检查，不要暗示扫描结果完全可靠。

3. 编写提交消息

遵循仓库现有的约定。不要擅自采用 Conventional Commits。先读取 git log <base> -20 --pretty=format:"%s%n%b---"，然后进行分类。

• Conventional Commits（type(scope): summary）——遵循该格式，并且只使用仓库中已有的类型。不要凭空创造从未出现过的类型。
• 工单前缀（PROJ-123: summary 或 [PROJ-123] summary）——使用该前缀；如果其他地方看不出工单 ID，就从分支名称中查找。
• 普通祈使句（Add x、Fix y）——遵循这种风格，不要强加仓库未使用的类型或作用域体系。
• 如果日志为空或风格过于混杂，无法分类，则默认使用 Conventional Commits。

无论采用哪种风格，都要遵循以下要求。

• 主题行不超过 72 个字符，并使用祈使语气（“add”，而不是“added”）。
• 只有在变更内容需要额外说明时，才添加正文。
• 只有在变更路径能明确体现作用域，或仓库惯例要求时，才添加作用域或前缀；如果差异涉及互不相关的区域，则省略。
• 不得注明工具归属。 绝不添加“由 AI 编写”、Generated-by: 标记，或工具的共同作者行。提交消息是持久记录，工具早已被遗忘后，人们仍会阅读它。

4. 起草 PR 描述

总结整个分支，而不只是最新提交。

如果仓库的受支持位置中包含 PR 模板，请填写该模板，而不是使用以下结构。若存在多个模板且未指定使用哪个，则采用仓库默认模板或最适用的模板。否则使用以下默认结构。

• ## Summary ——用两到四句话说明变更内容及原因。
• ## Changes ——以项目符号列出具体变更，并描述其最终效果。
• ## UI notes ——说明审查者应关注的视觉或交互变化，例如新增状态、动效或响应式行为。指出哪些地方适合提供截图或录屏。
• ## Testing ——说明如何或应如何针对不同视口、输入方式和减少动态效果设置进行验证。只报告有证据支持的检查；未执行的检查应标为待完成，不要暗示其已通过。
• ## Notes ——仅在存在破坏性变更、后续工作或有意省略的内容时添加。

无论采用哪种结构，都要遵循以下要求。

• 绝不逐条列出单个提交。 审查者可以在提交标签页查看提交记录。请描述分支的最终效果，而不是按提交历史逐项叙述。
• 不得声称未经证实的测试已通过，例如“运行了测试套件”。这类信息属于 CI。只有在 Testing 部分报告审查者无法从其他地方查到的手动验证。
• 不得注明工具归属，原因同提交消息的要求。

更新已有的 PR 描述时，应将其改写为对整个分支的连贯说明。不要每次提交都追加一行。内容必须以实际差异为依据，不要猜测代码中看不出的意图。

5. 提议提交并推送

写好消息后，提议在当前分支上执行操作。重用第 1 步收集的分支、上游和默认分支状态，绝不自行假设。

只展示符合该状态的选项。

• 使用此消息提交已暂存的更改。
• 暂存所有已跟踪的更改，然后提交。
• 提交，然后推送到现有上游。
• 提交，然后使用 git push -u origin <branch> 推送并设置上游（当不存在上游时）。
• 修改上一次提交，仅当上一次提交尚未推送时才提供此选项。
• 不执行任何操作，让用户手动提交。

遵循以下安全规则。

• 提交可撤销，因此按用户的选择继续。
• 推送会影响共享内容且难以撤销，因此执行前必须获得明确确认，且绝不强制推送。
• 当目标是仓库默认分支时，推送前发出警告并再次确认，因为直接推送到该分支通常并非本意。
• 运行实际的 git 命令并报告其真实退出结果。绝不打印命令未实际输出的成功信息。

写作风格

所有提交正文和 PR 描述都使用平实的文字，仅使用逗号和句号为生成的句子添加标点。不要使用破折号、冒号或分号。将需要使用冒号或分号的句子拆开，并用逗号或新句改写插入的破折号内容。此规则适用于你撰写的提交正文和 PR 文案，不适用于提交主题行或工具或约定要求的结构语法，因此主题行、type(scope): 提交前缀、PROJ-123: 任务前缀、Markdown 标题以及代码跨度中的内容都保持原样。

确保文本从头到尾流畅连贯。提交正文或 PR 描述中的每个段落都写成一行，不要在段落内强制换行。段落之间仅空一行。主题行长度限制是单行长度上限，不是换行要求，因此仍须遵守；Markdown 标题下的项目符号等需要单独换行的结构语法也应保留。

输出

按以下固定顺序返回三个部分，标题必须完全一致：## Review、## Commit message，然后是 ## PR description。在 ## Review 下，每项发现单独列为一个项目，格式为 Severity, path:line, finding；如果差异中没有问题，则写 No issues found.。将提交消息放在单独的 text 代码块中，并将 PR 描述放在单独的代码块中。然后提供第 5 步中的提交和推送选项。

---

作者：@planetabhi