get-shit-done 的 /gsd:ui-review：用「六支柱对抗式视觉审计」给已实现前端代码打分

get-shit-done 的 /gsd:ui-review：用「六支柱对抗式视觉审计」给已实现前端代码打分

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

这篇技术指南介绍 get-shit-done（GSD）内置的/gsd:ui-review命令——一种面向已实现前端代码的「追溯式（Retroactive）六支柱视觉审计」流程。无论你的项目是否由 GSD 的 phase 体系管理，只要代码已落地，就能用它生成一份带 1–4 分分级评分、可执行的UI-REVIEW.md审计报告。读完本文，你将掌握该命令的参数形态、底层编排流程、gsd-ui-auditor子代理的对抗式审计立场、六支柱打分模型，以及 Playwright-MCP / CLI 截图与 Registry 安全审计等自动化验证手段。

命令定位：为什么需要「追溯式」审计

GSD（get-shit-done）是以 spec-driven 开发与 phase 编排为核心的轻量级上下文工程系统。它的前端流程中，/gsd:ui-phase负责在动手写代码前产出UI-SPEC.md设计契约；而/gsd:ui-review正好与之互补，它解决的是另一个问题：

代码写完之后，怎么知道它是否真的符合当初的设计契约？

从 get-shit-done/workflows/ui-review.md 的定义看，这个工作流是：

Retroactive 6-pillar visual audit of implemented frontend code. Standalone command that works on any project — GSD-managed or not.

三个关键词：

• Retroactive（追溯式）——审计发生在执行完成之后，而不是设计阶段；
• 6-pillar（六支柱）——围绕文案、视觉、色彩、排版、间距、体验设计六个维度分别打分；
• Standalone（独立可用）——不要求目标工程必须是 GSD 托管项目，普通仓库也能跑。

命令的产出物固定为一个文件：{phase_num}-UI-REVIEW.md，由 commands/gsd/ui-review.md 中的 objective 明确写出。它把「前端做完了没」这种模糊问题，转成一张 6 行、满分 24 的评分表。

与周边命令的分工

其中 UI-SPEC 是审计的「基线（baseline）」，这一点在 agents/gsd-ui-auditor.md 的<upstream_input>节有明确表格：UI-SPEC 中的 Design System、Spacing Scale、Typography、Color、Copywriting Contract 五个 Section 分别对应审计时「该拿什么去核对」。若目标 phase 没有 UI-SPEC，审计则退化为对照抽象的六支柱标准。

命令形态与参数

在 docs/COMMANDS.md 的命令索引中（见/gsd-ui-review一节，约 L304–L318），命令定义如下：

实际调用方式：

/gsd-ui-review # 审计最近完成的 phase /gsd-ui-review 3 # 指定审计 phase 3

前置条件：项目里存在已实现的前端代码；不要求该项目是 GSD 项目。产出物包括：{phase}-UI-REVIEW.md，以及在启动截图流程后存放于.planning/ui-reviews/的截图文件。

在命令文件 commands/gsd/ui-review.md 的 frontmatter 中，还能看到它声明的工具面：

• allowed-tools：Read / Write / Bash / Glob / Grep / Agent / AskUserQuestion；
• requires: [phase]——必须有 phase 作为输入，但该值可选（默认取最后完成的 phase）；
• description 中明确其工作方式是6-pillar 打分（每项 1–4）+ 产出可执行发现。

提示：GSD 命令支持gsd:与历史无前缀形式两种斜杠命名（同一命令常同时登记为/gsd:ui-review与/gsd-ui-review），实际以你安装版本呈现为准。

编排流程拆解

命令本体只是入口，真正的执行由 get-shit-done/workflows/ui-review.md 这份工作流驱动。它要求先阅读 get-shit-done/references/ui-brand.md（GSD 面向用户的视觉规范），并指明可用的子代理类型必须精确为gsd-ui-auditor，不得降级为通用代理。

完整流程共 6 个阶段：

Step 0：初始化与 banner

通过 SDK 查询获取 phase 操作上下文与模型解析：

INIT=$(gsd-sdk query init.phase-op "${PHASE_ARG}") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi AGENT_SKILLS_UI_REVIEWER=$(gsd-sdk query agent-skills gsd-ui-auditor)

需要解析出的字段包括：phase_dir、phase_number、phase_name、phase_slug、padded_phase、commit_docs；随后解析审计代理应使用的模型：

UI_AUDITOR_MODEL=$(gsd-sdk query resolve-model gsd-ui-auditor --raw)

最后按 ui-brand.md 的 Stage Banner 规范输出阶段横幅（横幅统一使用━分隔线 +GSD ►前缀，宽度与样式不可混搭）：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► UI AUDIT — PHASE {N}: {name} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1：探测输入状态

SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null) UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1) UI_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-UI-REVIEW.md 2>/dev/null | head -1)

两个关键分支：

• 若 SUMMARY 文件为空：直接退出并提示「Phase {N} 尚未执行，请先运行/gsd:execute-phase {N}」。这条 gate 保证了审计对象确实执行过、有真实的实现产物可查。
• 若已存在 UI-REVIEW.md：通过AskUserQuestion询问用户是「Re-audit（重新跑一遍全新审计）」还是「View（展示现有报告后退出）」。

此外工作流保留了text mode兼容逻辑：当配置中workflow.text_mode: true或参数含--text时，所有AskUserQuestion会被替换为纯文本编号列表。这是为 OpenAI Codex、Gemini CLI 等没有AskUserQuestion的非 Claude 运行时准备的通道。

Step 2–3：收集上下文并拉起审计子代理

工作流为该 phase 目录构建文件清单并全部交给子代理阅读：

• 所有SUMMARY.md——各计划实际构建了什么；
• 所有PLAN.md——本来打算构建什么；
• UI-SPEC.md（若存在）——审计基线；
• CONTEXT.md（若存在）——被锁定的用户决策。

随后拼装审计 prompt 并以subagent_type="gsd-ui-auditor"精确拉起：

Agent( prompt=ui_audit_prompt, subagent_type="gsd-ui-auditor", model="{UI_AUDITOR_MODEL}", description="UI Audit Phase {N}" )

工作流对 Codex 运行时还有一条ORCHESTRATOR RULE：一旦调用Agent()，编排者必须立即停止读取文件、编辑代码或运行测试，等待子代理返回结果，以避免重复劳动与上下文浪费。

Step 4：处理返回并展示成绩单

若子代理返回## UI REVIEW COMPLETE，编排者向用户呈现压缩版成绩单（总分 /24 + 六支柱分表 + Top 3 修复项 + 完整报告路径），末尾附带明确的 Next 指引——/clear之后通常二选一：

• /gsd:verify-work {N}——进入 UAT 测试；
• /gsd:plan-phase {N+1}——规划下一 phase。

Step 5：按配置提交

gsd-sdk query commit "docs(${padded_phase}): UI audit review" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-REVIEW.md"

仅当commit_docs配置开启时才执行提交。

gsd-ui-auditor：一个被设计成「不手软」的子代理

审计的真正执行者是 agents/gsd-ui-auditor.md 定义的gsd-ui-auditor子代理。它的角色声明非常直白：以对抗性姿态审查已实现前端，对已构建内容按设计契约或六支柱标准打分，且不得为缓和结论而把分数平均上抬。

FORCE 立场与常见「发软」模式

子代理内置的默认假设是：在截图或代码分析证明之前，每个支柱都视为存在缺陷；起始假设是 UI 偏离了设计契约，凡是偏差都必须暴露。它甚至显式列出审计员最常见的五种自我放水路径，要求审计时绕开：

1. 把各支柱分数向上取平均，避免某一项分数看起来太难看；
2. 把「组件存在」当作「UI 正确」的证据，而不去核对间距、色彩、交互；
3. 不按 UI-SPEC.md 的断点与间距刻度检验，仅凭肉眼判断布局；
4. 只验证品牌主色合规，就为 Color 支柱打满分，却不检查 60/30/10 分布；
5. 找出 3 个优先修复项就停手，明明存在 6 个以上问题。

发现项两级分类

审计产出的每条发现必须有明确分类：

• BLOCKER：支柱得 1 分，或某个具体缺陷直接阻断用户完成任务——发布前必修；
• WARNING：支柱得 2–3 分，或某缺陷降低质量但不阻断流程——建议修复。

同时有一条硬性约束：每个被评分的支柱，都必须至少有一条具体发现来支撑该分数，杜绝无依据打分。

六支柱打分模型（1–4 × 6）

评分定义如下：

总分Σ = 0–24。六个支柱及其审计方法与目标在 agents/gsd-ui-auditor.md 的<audit_pillars>节有详细定义，每项都给出可复制的 grep 检查命令，本质是把「视觉质量」翻译成可静态扫描的证据：

Pillar 1：Copywriting（文案）

用 grep 扫描字符串字面量，查找泛化标签、空态与报错文案：

# 查找泛化标签 grep -rn "Submit\|Click Here\|OK\|Cancel\|Save" src --include="*.tsx" --include="*.jsx" 2>/dev/null # 查找空态模式 grep -rn "No data\|No results\|Nothing\|Empty" src --include="*.tsx" --include="*.jsx" 2>/dev/null # 查找报错模式 grep -rn "went wrong\|try again\|error occurred" src --include="*.tsx" --include="*.jsx" 2>/dev/null

有 UI-SPEC 时逐条比对契约声明的 CTA / 空态 / 报错文案与实际字符串；无契约时对照 UX 最佳实践标记泛化文案。

Pillar 2：Visuals（视觉）

不依赖 grep，检查组件结构与视觉层级信号：主屏是否有清晰视觉焦点？纯图标按钮是否配 aria-label 或 tooltip？是否通过尺寸、字重或颜色制造视觉层级？

Pillar 3：Color（色彩）

# 统计强调色用量 grep -rn "text-primary\|bg-primary\|border-primary" src --include="*.tsx" --include="*.jsx" 2>/dev/null | wc -l # 查找硬编码颜色 grep -rn "#[0-9a-fA-F]\{3,8\}\|rgb(" src --include="*.tsx" --include="*.jsx" 2>/dev/null

有 UI-SPEC 时验证强调色只出现在契约声明过的元素上；无契约时标记强调色滥用（>10 个元素）与硬编码颜色。

Pillar 4：Typography（排版）

# 统计正在使用的字号种数 grep -rohn "text-\(xs\|sm\|base\|lg\|xl\|2xl\|3xl\|4xl\|5xl\)" src --include="*.tsx" --include="*.jsx" 2>/dev/null | sort -u # 统计字重种数 grep -rohn "font-\(thin\|light\|normal\|medium\|semibold\|bold\|extrabold\)" src --include="*.tsx" --include="*.jsx" 2>/dev/null | sort -u

有契约时只允许契约声明的字号与字重；无契约时若出现 >4 种字号或 >2 种字重即标记。

Pillar 5：Spacing（间距）

# 间距类使用分布 grep -rohn "p-\|px-\|py-\|m-\|mx-\|my-\|gap-\|space-" src --include="*.tsx" --include="*.jsx" 2>/dev/null | sort | uniq -c | sort -rn | head -20 # 查找任意值（arbitrary value） grep -rn "\[.*px\]\|\[.*rem\]" src --include="*.tsx" --include="*.jsx" 2>/dev/null

有契约时核对间距是否符合声明的刻度；无契约时标记任意间距值与不一致模式（[13px]这类 Tailwind arbitrary value 通常是间距体系失控的信号）。

Pillar 6：Experience Design（体验设计）

# 加载态 grep -rn "loading\|isLoading\|pending\|skeleton\|Spinner" src --include="*.tsx" --include="*.jsx" 2>/dev/null # 错误态 grep -rn "error\|isError\|ErrorBoundary\|catch" src --include="*.tsx" --include="*.jsx" 2>/dev/null # 空态 grep -rn "empty\|isEmpty\|no.*found\|length === 0" src --include="*.tsx" --include="*.jsx" 2>/dev/null

打分依据：加载态是否齐全、是否使用错误边界、空态是否被处理、动作是否有禁用态、破坏性操作是否有二次确认。

截图取证：从「纯代码审计」升级到「真实渲染审计」

单纯的类名 grep 无法证明视觉正确性。因此审计器内置了两级截图取证机制，并且在此之前先跑一道gitignore gate。

gitignore gate（截图入库安全闸）

为了防止二进制截图被误提交进 git 历史，每次审计在截图之前无条件执行：

mkdir -p .planning/ui-reviews # 若不存在则写入 .gitignore，忽略 *.png/*.webp/*.jpg 等

即使审计完成后用户执行git add .，截图也不会进入提交。

路线一：Playwright-MCP（优先）

会话中存在mcp__playwright__*工具时直接走自动化验证，跳过 CLI 方案：

mcp__playwright__navigate(url="http://localhost:3000") mcp__playwright__screenshot(name="desktop", width=1440, height=900) mcp__playwright__screenshot(name="mobile", width=375, height=812)

随后针对 UI-SPEC 中列出的每个组件逐一路由访问并截屏比对，例如「组件 X 宽度是否真的为 70vw」「强调色是否只出现在声明过的元素」「间距是否符合声明的刻度」。量化的偏差（尺寸、颜色、布局）自动作为对应支柱下的补充发现写入报告；而品牌感、内容语气这类需要主观判断的项目则标记needs_human_review: true，在自动轮次结束后单独呈现给用户。

路线二：CLI 截屏（降级路径）

无 MCP 时按 agents/gsd-ui-auditor.md 的<screenshot_approach>检测本地 dev server（依次尝试端口 3000 → 5173 Vite 默认 → 8080），命中后以npx playwright screenshot截取桌面/移动/平板三档：

DEV_STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null || echo "000") if [ "$DEV_STATUS" = "200" ]; then SCREENSHOT_DIR=".planning/ui-reviews/${PADDED_PHASE}-$(date +%Y%m%d-%H%M%S)" mkdir -p "$SCREENSHOT_DIR" npx playwright screenshot http://localhost:3000 \ "$SCREENSHOT_DIR/desktop.png" --viewport-size=1440,900 2>/dev/null npx playwright screenshot http://localhost:3000 \ "$SCREENSHOT_DIR/mobile.png" --viewport-size=375,812 2>/dev/null npx playwright screenshot http://localhost:3000 \ "$SCREENSHOT_DIR/tablet.png" --viewport-size=768,1024 2>/dev/null else echo "No dev server at localhost:3000 — code-only audit" fi

若 dev server 未运行，审计自动降级为纯代码审计（Tailwind 类审计、泛化文案字符串审计、状态处理检查），并在报告中注明未捕获视觉截图。这一可用性设计（运行时可探测、无需任何配置改动）在 get-shit-done/workflows/ui-review.md 的「Automated UI Verification」一节也有镜像说明。

Registry 安全审计：供应链维度的加分项

六支柱打分完成后、写报告之前，若项目满足两个条件——存在components.json（即初始化过 shadcn）且UI-SPEC.md 列出了第三方 registry——则执行一道组件安全审计：

test -f components.json || echo "NO_SHADCN" # 拉取实际安装的 block 源码 npx shadcn view {block} --registry {registry_url} 2>/dev/null > /tmp/shadcn-view-{block}.txt # 检查可疑模式 grep -nE "fetch\(|XMLHttpRequest|navigator\.sendBeacon|process\.env|eval\(|Function\(|new Function|import\(.*https?:" /tmp/shadcn-view-{block}.txt 2>/dev/null # 与本地版本 diff，暴露安装后被改动的部分 npx shadcn diff {block} 2>/dev/null

可疑模式的判定规则相当明确：

命中任一标志时：在UI-REVIEW.md中「Files Audited」之前插入Registry Safety章节，逐个列出 registry URL、带行号的可疑代码与风险类别；每个被标记的 block 使 Experience Design 支柱扣 1 分（下限 1）；若shadcn diff显示本地存在改动则仅作信息记录，不视为标志。全绿时写入Registry audit: {N} third-party blocks checked, no flags。

产物标准：UI-REVIEW.md 的固定结构

无论走哪条取证路线，审计器都必须用Write 工具（而非cat << EOFheredoc）向$PHASE_DIR/$PADDED_PHASE-UI-REVIEW.md写入报告，模板包含：

1. 头部：Phase 编号、审计日期、基线类型（UI-SPEC.md / 抽象标准）、截图状态（captured / not captured）；
2. Pillar Scores 表：六支柱各自的 1–4 分 + 一行关键发现，末尾Overall: {total}/24；
3. Top 3 Priority Fixes：每条 = 具体问题 + 用户影响 + 具体修法；
4. Detailed Findings：按支柱分节，低分支柱给更多细节，全部发现须带file:line引用；
5. Files Audited：实际检查过的文件清单（find src -name "*.tsx" -o ...得到）。

报告完成后，审计器向编排者返回结构化结果（## UI REVIEW COMPLETE），其中包含总分、支柱摘要、Top 3、创建的文件路径，以及「Priority fixes / Minor recommendations」的计数。

质量门槛：什么才算一次合格的审计

工作流与子代理各自定义了 success criteria，合并起来即一次合格审计的验收清单：

• Phase 已校验，SUMMARY.md 存在（确认执行已完成）；
• 已处理的既有审查（Re-audit / View 分支）；
• 以正确的上下文拉起gsd-ui-auditor；
• 截图前执行过 .gitignore gate；
• 尝试过 dev server 探测，截图已捕获（或注明不可用）；
• 六支柱全部带证据打分，Top 3 优先修复项给出具体解决方案；
• Registry 安全审计已执行（若满足前置条件）；
• UI-REVIEW.md写入正确路径，并向编排者返回结构化结果。

四条质量指示器尤其值得在复用这套方法时借鉴：证据化（每个分数都引用具体文件、行或类模式）；可执行修复（应写「把装饰边框上的text-primary改为text-muted」，而不是「修一下颜色」）；公平打分（4/4 是可达到的，1/4 意味着真问题，而非完美主义）；比例感（低分支柱详写，通过的支柱从简）。

小结

/gsd:ui-review把「前端视觉验收」从人工点检升级为可复现、可打分、可执行的自动化审计管线：它用 UI-SPEC 设计契约或抽象标准作为基线，由gsd-ui-auditor以对抗姿态逐支柱取证打分，用 Playwright-MCP / CLI 截图提供真实渲染证据，用 Registry 安全审计补上第三方组件的供应链视角，最终沉淀为结构化的UI-REVIEW.md。对任何采用 phase + 计划执行模式、又希望前端质量可度量的团队来说，这套六支柱模型本身也是一份可以直接借鉴的验收清单。

想继续深入，可以按需阅读以下仓库文件：

• 命令入口与工具面声明：commands/gsd/ui-review.md
• 完整编排工作流：get-shit-done/workflows/ui-review.md
• 审计执行主体与六支柱 grep 方法：agents/gsd-ui-auditor.md
• 上游设计契约生成命令：commands/gsd/ui-phase.md
• GSD 自身的品牌输出规范：get-shit-done/references/ui-brand.md
• 命令行用法与参数索引：docs/COMMANDS.md

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done