Files

王冕 a27e3b8e43 feat: sync full workspace including web modules, docs, and configurations to Gitea

Optimized the root .gitignore to exclude virtual environments, node modules,
and temp folders to ensure clean and lightweight version tracking.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-09 18:12:25 +08:00

3.5 KiB

Raw Blame History

调试指南

核心思想：先定位规范与目标页面，再用自动化完成复现、修复与回归；尽量不要求用户提供技术细节。

1. 调试前准备

开始调试前，按顺序确认以下信息：

目标目录下的 spec.md、index.tsx、style.css（如有）
相关主题文件：DESIGN.md、designToken.json、globals.css（如有）
验收规则：rules/development-guide.md
涉及视觉或布局问题时，额外参考 rules/design-guide.md

1.1 视觉问题的设计规范优先级

当问题属于样式、布局、层级、字体、配色、组件状态不一致时，按以下顺序判断：

用户提供的设计规范
主题内设计系统：DESIGN.md
默认设计规范（兜底）
- 基础型界面：/skills/third-party/interface-design/SKILL.md
  - 适用：后台、ToB、工具类、设置页、数据工作台
- 风格化界面：/skills/third-party/frontend-design/SKILL.md
  - 适用：落地页、品牌展示、营销页、ToC 产品页、强视觉 App 页面

2. 标准调试流程

2.1 先跑验收脚本

优先运行项目验收脚本，拿到真实状态和目标地址：

node scripts/check-app-ready.mjs /components/[组件目录]
# 或
node scripts/check-app-ready.mjs /prototypes/[原型目录]

处理原则：

ERROR：优先修复构建、依赖、运行时报错，再进入浏览器复现
READY：直接进入浏览器自动化验收
TIMEOUT：优先排查启动卡死、接口阻塞、长任务或脚本异常

2.2 自动化复现与定位

优先使用 Chrome DevTools MCP；没有时使用 Playwright MCP
如果当前环境没有可用 MCP：直接提示用户安装并完成配置，再继续自动化验收
自动化过程中必须完成：
- 打开验收脚本返回的 targetUrl
- 检查 Console、Network、页面报错与资源加载状态
- 复现核心交互链路，而不是只看首屏
- 必要时截图、快照、记录关键 DOM / 样式状态

3. 问题处理顺序

按影响范围由大到小处理：

构建与启动问题：依赖缺失、编译失败、路径错误、语法错误
运行时问题：白屏、崩溃、接口异常、状态错误、空数据未兜底
交互问题：按钮不可点、表单无反馈、弹层错位、路由异常
视觉问题：尺寸、间距、颜色、字体、层级、响应式、主题不一致

重要：一次只修一个明确问题。每次修复后必须重新验收，确认未引入新问题，再继续下一个。

4. 视觉与交互调试要求

当页面可访问后，不仅要看“能打开”，还要验证：

关键任务路径是否能走通
空状态、加载态、错误态是否合理
文案、字段、组件层级是否与 spec.md 一致
响应式布局是否在主要断点下可用
颜色、字体、圆角、阴影、边框是否与主题或设计规范一致

如果属于视觉偏差，但用户未提供设计稿：

基础型界面按 /skills/third-party/interface-design/SKILL.md 约束修复
风格化界面按 /skills/third-party/frontend-design/SKILL.md 约束修复

5. 回归验收

每次修复后都必须重复以下动作：

重新运行 check-app-ready.mjs
再次打开 targetUrl
重跑刚才失败的交互链路
确认 Console 无新增报错
确认页面状态恢复正常

只有当前问题完成回归后，才能进入下一个问题。

3.5 KiB Raw Blame History Unescape Escape