用途
Black-Tortoise UI Reviewer 聚焦 Black-Tortoise 的 Angular 20 + Material Design 3 UI 技术栈，在源代码层面识别并修复表现层（presentation layer）问题。当被要求审查该仓库的 UI、布局或设计时使用。
适用范围
- Black-Tortoise Angular 20 表现层
- Material Design 3 组件样式与 token
- 独立组件（standalone components）模板与 SCSS 文件
前置条件
必需：
- 目标 UI 可访问：本地开发服务器（如 http://localhost:4200，可配置）、预发布环境，或生产环境（只读审查）
- 浏览器自动化可用：截图捕获、页面导航、DOM 信息获取
- 进行修复时需访问源代码：项目须存在于工作区中，且编辑仅限表现层文件
工作流程
流程为：信息收集 → 视觉检查 → 问题修复 → 重新验证，若仍有问题则回到视觉检查，否则输出完成报告。
步骤 1：信息收集
1.1 URL 确认：若未提供 URL，向用户询问要审查的网站 URL（如 http://localhost:3000）。
1.2 理解项目结构：进行修复时收集框架（确认是否为 Angular 20 独立组件）、样式方法（是否为带 Material Design 3 token 的 SCSS）、源码位置（哪些表现层组件或样式）、审查范围（仅特定页面还是整个 UI）。
1.3 自动项目检测：尝试从工作区文件自动检测，检测目标包括 package.json（Angular 20 + Material + @ngrx/signals）、angular.json（Angular CLI 配置）、src//*.scss（组件样式，优先表现层）、src/styles/（样式配置，如存在 M3 token）、src/app/presentation/**（UI 源码，如存在）。
1.4 识别样式方法：SCSS（主要）对应组件 SCSS 文件；全局样式对应 src/styles.scss（如存在）；M3 token 对应 src/styles/**（如存在）的 token 定义。
步骤 2：视觉检查
2.1 页面遍历：导航到指定 URL、捕获截图、获取 DOM 结构/快照（如可能）；若存在其他页面，通过导航遍历。
2.2 检查项：
- 布局问题：元素溢出（高）、元素重叠（高）、对齐问题（中）、间距不一致（中）、文本截断（中）
- 响应式问题：不友好于移动端（高）、断点问题（中）、触摸目标过小（中）
- 无障碍问题：对比度不足（高）、无焦点状态（高）、缺少 alt 文本（中）
- 视觉一致性：字体不一致（中）、颜色不一致（中）、间距不一致（低）
2.3 视口测试（响应式）：移动端 375px（iPhone SE/12 mini）、平板 768px（iPad）、桌面 1280px（标准 PC）、宽屏 1920px（大显示器）。
步骤 3：问题修复
3.1 问题优先级：P1 立即修复（影响功能的布局问题）、P2 其次修复（降低 UX 的视觉问题）、P3 尽可能修复（轻微视觉不一致）。
3.2 识别源文件：基于选择器搜索（按类名或 ID 搜索代码库，用 grep_search 探索样式定义）；基于组件搜索（从元素文本或结构识别组件，用 semantic_search 探索相关文件）；文件模式过滤（样式文件 src//*.scss、src/styles/；组件 src/app/presentation/；页面 src/app/presentation/pages/）。
3.3 应用修复：框架特定修复指南见 references/framework-fixes.md。修复原则：最小改动、尊重现有模式（遵循 Angular + M3 token 用法与现有结构）、避免破坏性变更、层级安全（仅编辑表现层样式/模板，不触碰 domain/application）。
步骤 4：重新验证
4.1 修复后确认：重新加载浏览器（或等待开发服务器 HMR）、捕获修复区域截图、对比前后。
4.2 回归测试：验证修复未影响其他区域，确认响应式显示未被破坏。
4.3 迭代决策：若仍有问题则回到步骤 2，否则进入完成报告。迭代限制：若某问题需要超过 3 次修复尝试，咨询用户。
输出格式
审查结果报告包含：摘要（目标 URL、框架、样式、测试视口、检测到的问题数、已修复问题数）；检测到的问题（按 P1/P2 等列出页面、元素、问题描述、修复文件、修复详情、前后截图）；未修复问题（原因与建议操作）；建议（未来改进建议）。
所需能力
- 网页导航（必需）
- 截图捕获（必需）
- 图像分析（必需）
- DOM 获取（推荐）
- 文件读写（修复时必需）
- 代码搜索（修复时必需）
参考实现
推荐使用 Playwright MCP 作为参考实现。能力与工具对应：导航 browser_navigate、快照 browser_snapshot、截图 browser_take_screenshot、点击 browser_click、调整尺寸 browser_resize、控制台 browser_console_messages。
MCP 服务器配置示例：
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@latest", "--caps=vision"]
}
}
}
其他兼容的浏览器自动化工具：Selenium（广泛浏览器支持、多语言支持）、Puppeteer（专注 Chrome/Chromium、Node.js）、Cypress（易于与 E2E 测试集成）、WebDriver BiDi（标准化的下一代协议）。只要提供必要能力（导航、截图、DOM 获取），工具选择灵活。
最佳实践
推荐：始终在修复前保存截图；一次修复一个问题并逐一验证；样式更新使用 Material Design 3 token；模板中尊重 Angular 20 控制流语法；详尽记录修复细节。
不推荐：未经确认的大规模重构；忽略设计系统或品牌指南；忽略性能的修复；一次修复多个问题（难以验证）。
故障排查
问题：找不到样式文件。检查 package.json 中的依赖；考虑 CSS-in-JS 的可能性；考虑构建时生成的 CSS；询问用户样式方法。
问题：修复未生效。检查开发服务器 HMR 是否工作；清除浏览器缓存；若项目需要构建则重新构建；检查 CSS 特异性问题。
问题：修复影响其他区域。回滚更改；使用更具体的选择器；考虑使用 CSS Modules 或 scoped 样式；咨询用户确认影响范围。