{ "schemaVersion": "1.0", "item": { "slug": "ui-debug-methodology", "name": "ui-debug-methodology", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/chrsh44e/ui-debug-methodology", "canonicalUrl": "https://clawhub.ai/chrsh44e/ui-debug-methodology", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/ui-debug-methodology", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ui-debug-methodology", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "slug": "ui-debug-methodology", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-12T20:24:41.870Z", "expiresAt": "2026-05-19T20:24:41.870Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ui-debug-methodology", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ui-debug-methodology", "contentDisposition": "attachment; filename=\"ui-debug-methodology-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "ui-debug-methodology" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/ui-debug-methodology" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/ui-debug-methodology", "agentPageUrl": "https://openagent3.xyz/skills/ui-debug-methodology/agent", "manifestUrl": "https://openagent3.xyz/skills/ui-debug-methodology/agent.json", "briefUrl": "https://openagent3.xyz/skills/ui-debug-methodology/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "UI 问题调试方法论", "body": "核心原则：先理解机制，后动手修改。\n\n当 UI 行为不符合预期时，禁止立即修改代码。必须先完成以下调试流程。" }, { "title": "触发条件", "body": "当遇到以下情况时，必须激活本 skill 的调试流程：\n\nUI 行为不符合预期\nCSS/样式不生效\n组件交互有问题（拖拽、点击、hover 等）\n布局错乱\n第一次尝试修复失败后" }, { "title": "强制流程", "body": "┌─────────────────────────────────────────────────────────────┐\n│ UI 问题调试流程 │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ 1. 观察现象 用 DevTools 检查实际 DOM 和样式 │\n│ │ │\n│ ▼ │\n│ 2. 理解机制 搞清楚组件/CSS 的工作原理 │\n│ │ │\n│ ▼ │\n│ 3. 定位根因 找到真正控制行为的代码/配置 │\n│ │ │\n│ ▼ │\n│ 4. 最小修复 只改必要的部分 │\n│ │ │\n│ ▼ │\n│ 5. 验证 测试所有场景 │\n│ │ │\n│ └──── 失败 ────▶ 回到步骤 1，不要继续打补丁 │\n│ │\n└─────────────────────────────────────────────────────────────┘" }, { "title": "Step 1: 观察现象", "body": "必须使用 DevTools 或 Playwright，而不是猜测。" }, { "title": "检查清单", "body": "检查项方法实际的 DOM 结构Elements 面板Computed styles查看 width/height/min-width/max-width 等样式来源看是哪个 CSS 规则在生效是否有覆盖查看被划掉的样式布局模式table-layout / display / flex / grid事件是否触发Console 加 log 或 breakpoint" }, { "title": "使用 Playwright 检查（AI Agent 执行）", "body": "当作为 AI Agent 调试时，使用 Playwright 获取运行时信息：\n\n// 获取元素的 computed style\nconst style = await page.$eval('selector', el => {\n const computed = window.getComputedStyle(el);\n return {\n width: computed.width,\n minWidth: computed.minWidth,\n maxWidth: computed.maxWidth,\n display: computed.display,\n position: computed.position,\n tableLayout: computed.tableLayout\n };\n});\n\n// 获取实际 DOM 结构\nconst html = await page.$eval('selector', el => el.outerHTML);\n\n// 检查元素是否可见\nconst isVisible = await page.isVisible('selector');\n\n// 截图对比\nawait page.screenshot({ path: 'debug-before.png' });\n\n关键：先拿到实际数据，再做判断。不要基于代码猜测运行时状态。" }, { "title": "Step 2: 理解机制", "body": "在动手前，必须能回答以下问题：\n\n这个组件/CSS 属性的工作原理是什么？\n哪些因素会影响它的行为？\n我要修改的代码，在整个流程中扮演什么角色？" }, { "title": "常见机制陷阱", "body": "场景陷阱真相Ant Design Table 列宽以为 的 width 控制列宽实际由 + scroll.x 控制scroll.x: 'max-content'以为只是让表格可横向滚动实际让浏览器忽略 width，根据内容计算Flexbox 子元素宽度设置了 width 但不生效需要同时设置 flex-shrink: 0CSS position: absolute以为相对于父元素实际相对于最近的 position: relative 祖先transform只是视觉变换会影响 position: fixed 子元素的定位z-index 不生效以为值越大越靠前需要在同一个 stacking context 中比较overflow: hidden只影响自身会创建新的 BFC，影响子元素布局" }, { "title": "如果不熟悉机制", "body": "先查官方文档（MDN、组件库文档）\n搜索 \"X not working\" / \"X width ignored\" 等关键词\n检查组件库源码\n创建最小复现 demo" }, { "title": "Step 3: 定位根因", "body": "问自己：是我的代码问题，还是框架/机制问题？" }, { "title": "二分法排除", "body": "移除可疑代码，看问题是否消失\n创建最小复现，逐步添加代码直到问题出现\n检查是否有其他 CSS/JS 在干扰" }, { "title": "常见根因类型", "body": "类型示例修复方向配置问题scroll.x: 'max-content' 导致列宽失效修改配置CSS 优先级全局样式覆盖了组件样式提高优先级或改选择器组件 API 误用用错了 prop 或 callback 签名查文档，改用法机制不匹配想用 CSS 控制，但实际由 JS 控制改用正确的控制方式第三方库限制库不支持这种用法换方案或 fork" }, { "title": "Step 4: 最小修复", "body": "只改必要的部分，不引入新复杂度。" }, { "title": "原则", "body": "能用原生实现就不引入库\n能改配置就不改代码\n能改一处就不改多处\n改完能解释清楚为什么这样改" }, { "title": "反模式（禁止）", "body": "反模式问题引入新库解决小问题增加依赖，可能带来新问题到处加 !important掩盖问题，后续更难维护在多个地方加补丁说明没找到根因改了生效但不知道为什么下次还会踩坑用 as any / @ts-ignore 绕过类型错误隐藏真实问题" }, { "title": "Step 5: 验证", "body": "测试所有场景，不只是出问题的那个。" }, { "title": "验证清单", "body": "原问题场景修复\n 相关场景没有回归\n 边界情况（空数据、超长内容、极小/极大值）\n 不同浏览器（如果需要）\n 响应式布局（如果需要）" }, { "title": "失败后的处理", "body": "如果验证失败，回到 Step 1 重新观察。\n\n禁止：\n\n继续在当前方向打补丁\n猜测 \"可能是这个原因\"\n没观察就尝试下一个修复" }, { "title": "❌ 错误路径（实际发生的）", "body": "问题：拖拽列宽时，某些列往左拖不动\n\n尝试 1：用 react-resizable 库 → 失败\n尝试 2：设置 minWidth/maxWidth → 失败 \n尝试 3：改 CSS table-layout → 失败\n尝试 4：改 transform → 失败\n...（反复折腾 N 次）\n最终：改 scroll.x → 成功" }, { "title": "✅ 正确路径（应该这样做）", "body": "1. 观察：DevTools 检查 的 computed width\n → 发现 width 确实在变，但视觉没变\n\n2. 理解：搜索 \"ant design table column width not working\"\n → 发现 scroll.x: 'max-content' 会让浏览器忽略 width\n\n3. 定位：scroll.x 是根因\n\n4. 修复：scroll.x 改成列宽总和\n\n5. 验证：所有列都能正常拖拽\n\n总耗时：10 分钟（而不是 N 小时）" }, { "title": "禁止事项", "body": "禁止不观察就动手改代码\n禁止不理解机制就引入新库\n禁止修复失败后继续猜测打补丁\n禁止改了生效但说不清为什么\n禁止跳过验证步骤直接提交" }, { "title": "速查表", "body": "UI 问题 → DevTools 观察 → 理解机制 → 定位根因 → 最小修复 → 验证\n ↑ |\n └────────── 失败则回到这里 ──────────────┘" } ], "body": "UI 问题调试方法论\n\n核心原则：先理解机制，后动手修改。\n\n当 UI 行为不符合预期时，禁止立即修改代码。必须先完成以下调试流程。\n\n触发条件\n\n当遇到以下情况时，必须激活本 skill 的调试流程：\n\nUI 行为不符合预期\nCSS/样式不生效\n组件交互有问题（拖拽、点击、hover 等）\n布局错乱\n第一次尝试修复失败后\n强制流程\n┌─────────────────────────────────────────────────────────────┐\n│ UI 问题调试流程 │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ 1. 观察现象 用 DevTools 检查实际 DOM 和样式 │\n│ │ │\n│ ▼ │\n│ 2. 理解机制 搞清楚组件/CSS 的工作原理 │\n│ │ │\n│ ▼ │\n│ 3. 定位根因 找到真正控制行为的代码/配置 │\n│ │ │\n│ ▼ │\n│ 4. 最小修复 只改必要的部分 │\n│ │ │\n│ ▼ │\n│ 5. 验证 测试所有场景 │\n│ │ │\n│ └──── 失败 ────▶ 回到步骤 1，不要继续打补丁 │\n│ │\n└─────────────────────────────────────────────────────────────┘\n\nStep 1: 观察现象\n\n必须使用 DevTools 或 Playwright，而不是猜测。\n\n检查清单\n检查项\t方法\n实际的 DOM 结构\tElements 面板\nComputed styles\t查看 width/height/min-width/max-width 等\n样式来源\t看是哪个 CSS 规则在生效\n是否有覆盖\t查看被划掉的样式\n布局模式\ttable-layout / display / flex / grid\n事件是否触发\tConsole 加 log 或 breakpoint\n使用 Playwright 检查（AI Agent 执行）\n\n当作为 AI Agent 调试时，使用 Playwright 获取运行时信息：\n\n// 获取元素的 computed style\nconst style = await page.$eval('selector', el => {\n const computed = window.getComputedStyle(el);\n return {\n width: computed.width,\n minWidth: computed.minWidth,\n maxWidth: computed.maxWidth,\n display: computed.display,\n position: computed.position,\n tableLayout: computed.tableLayout\n };\n});\n\n// 获取实际 DOM 结构\nconst html = await page.$eval('selector', el => el.outerHTML);\n\n// 检查元素是否可见\nconst isVisible = await page.isVisible('selector');\n\n// 截图对比\nawait page.screenshot({ path: 'debug-before.png' });\n\n\n关键：先拿到实际数据，再做判断。不要基于代码猜测运行时状态。\n\nStep 2: 理解机制\n\n在动手前，必须能回答以下问题：\n\n这个组件/CSS 属性的工作原理是什么？\n哪些因素会影响它的行为？\n我要修改的代码，在整个流程中扮演什么角色？\n常见机制陷阱\n场景\t陷阱\t真相\nAnt Design Table 列宽\t以为 的 width 控制列宽\t实际由 + scroll.x 控制\nscroll.x: 'max-content'\t以为只是让表格可横向滚动\t实际让浏览器忽略 width，根据内容计算\nFlexbox 子元素宽度\t设置了 width 但不生效\t需要同时设置 flex-shrink: 0\nCSS position: absolute\t以为相对于父元素\t实际相对于最近的 position: relative 祖先\ntransform\t只是视觉变换\t会影响 position: fixed 子元素的定位\nz-index 不生效\t以为值越大越靠前\t需要在同一个 stacking context 中比较\noverflow: hidden\t只影响自身\t会创建新的 BFC，影响子元素布局\n如果不熟悉机制\n先查官方文档（MDN、组件库文档）\n搜索 \"X not working\" / \"X width ignored\" 等关键词\n检查组件库源码\n创建最小复现 demo\nStep 3: 定位根因\n\n问自己：是我的代码问题，还是框架/机制问题？\n\n二分法排除\n移除可疑代码，看问题是否消失\n创建最小复现，逐步添加代码直到问题出现\n检查是否有其他 CSS/JS 在干扰\n常见根因类型\n类型\t示例\t修复方向\n配置问题\tscroll.x: 'max-content' 导致列宽失效\t修改配置\nCSS 优先级\t全局样式覆盖了组件样式\t提高优先级或改选择器\n组件 API 误用\t用错了 prop 或 callback 签名\t查文档，改用法\n机制不匹配\t想用 CSS 控制，但实际由 JS 控制\t改用正确的控制方式\n第三方库限制\t库不支持这种用法\t换方案或 fork\nStep 4: 最小修复\n\n只改必要的部分，不引入新复杂度。\n\n原则\n能用原生实现就不引入库\n能改配置就不改代码\n能改一处就不改多处\n改完能解释清楚为什么这样改\n反模式（禁止）\n反模式\t问题\n引入新库解决小问题\t增加依赖，可能带来新问题\n到处加 !important\t掩盖问题，后续更难维护\n在多个地方加补丁\t说明没找到根因\n改了生效但不知道为什么\t下次还会踩坑\n用 as any / @ts-ignore 绕过类型错误\t隐藏真实问题\nStep 5: 验证\n\n测试所有场景，不只是出问题的那个。\n\n验证清单\n 原问题场景修复\n 相关场景没有回归\n 边界情况（空数据、超长内容、极小/极大值）\n 不同浏览器（如果需要）\n 响应式布局（如果需要）\n失败后的处理\n\n如果验证失败，回到 Step 1 重新观察。\n\n禁止：\n\n继续在当前方向打补丁\n猜测 \"可能是这个原因\"\n没观察就尝试下一个修复\n案例：Ant Design Table 可拖拽列宽\n❌ 错误路径（实际发生的）\n问题：拖拽列宽时，某些列往左拖不动\n\n尝试 1：用 react-resizable 库 → 失败\n尝试 2：设置 minWidth/maxWidth → 失败 \n尝试 3：改 CSS table-layout → 失败\n尝试 4：改 transform → 失败\n...（反复折腾 N 次）\n最终：改 scroll.x → 成功\n\n✅ 正确路径（应该这样做）\n1. 观察：DevTools 检查 的 computed width\n → 发现 width 确实在变，但视觉没变\n\n2. 理解：搜索 \"ant design table column width not working\"\n → 发现 scroll.x: 'max-content' 会让浏览器忽略 width\n\n3. 定位：scroll.x 是根因\n\n4. 修复：scroll.x 改成列宽总和\n\n5. 验证：所有列都能正常拖拽\n\n总耗时：10 分钟（而不是 N 小时）\n\n禁止事项\n禁止不观察就动手改代码\n禁止不理解机制就引入新库\n禁止修复失败后继续猜测打补丁\n禁止改了生效但说不清为什么\n禁止跳过验证步骤直接提交\n速查表\nUI 问题 → DevTools 观察 → 理解机制 → 定位根因 → 最小修复 → 验证\n ↑ |\n └────────── 失败则回到这里 ──────────────┘" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/chrsh44e/ui-debug-methodology", "publisherUrl": "https://clawhub.ai/chrsh44e/ui-debug-methodology", "owner": "chrsh44e", "version": "1.0.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/ui-debug-methodology", "downloadUrl": "https://openagent3.xyz/downloads/ui-debug-methodology", "agentUrl": "https://openagent3.xyz/skills/ui-debug-methodology/agent", "manifestUrl": "https://openagent3.xyz/skills/ui-debug-methodology/agent.json", "briefUrl": "https://openagent3.xyz/skills/ui-debug-methodology/agent.md" } }