pikasTech-unidesk/.agents/skills/unidesk-webdev/SKILL.md

name, description

name	description
unidesk-webdev	UniDesk Web 开发与浏览器验证技能。用户处理 UniDesk/HWLAB Cloud Web、Workbench、Performance 页、前端状态投影、Playwright、fake-server、web-probe、截图、响应式布局、Web E2E 回归或线上 Web bug 复测/提 issue 时使用。

UniDesk WebDev

本技能是 UniDesk/HWLAB Web 开发、浏览器复测和 Playwright 回归的入口。需求真相源仍是 project-management/PJ2026-01/specs/；本技能只规定如何开发、采集、复现和验收。

快速规则

• 线上 Web bug、Workbench、Performance、前端状态投影、截图、fake-server 和 web-probe 任务必须先用本技能。
• 涉及 Web 哨兵、web-probe sentinel、monitor.pikapython.com、定期/周期巡检或新建巡检时，必须同时加载 $unidesk-monitor。
• 真实用户入口验证优先；源码检查、构建通过或截图局部正常不能替代原入口验收。
• 禁止在本地或 master server 直接跑 vue-tsc / 前端全量 typecheck 作为默认验证；本地只做语法级检查和真实入口复测，完整类型检查交给 CI、PipelineRun 或明确指定的受控构建运行面。
• 桌面版 Web 截图、视觉复测和 web-probe 采样默认使用 1920x1080 视口；只有用户、issue 或 SPEC 明确指定其他尺寸时才覆盖，并在证据中写明覆盖原因。
• Web probe、Playwright、fake-server 的详细命令和历史判定口径见 references/full.md。
• 前端改动遵循仓库既有设计系统和 $frontend-design 全局 UI 规则；不要做营销式落地页替代真实工具页面。

通用 Web 设计默认

• UniDesk/HWLAB 的工具页默认是工作界面，不是营销页：首屏直接呈现可操作对象、状态和主要任务流，避免 hero、装饰卡片和说明性大段文案。
• 信息密度优先但要稳定：header 保持窄，source/file/project 等上下文选择放在顶部工具栏或状态栏下拉；计数、来源、taskRef、更新时间等元信息收敛到详情/感叹号弹窗，不长期占主版面。
• 主内容区必须占优：树、大纲、列表和导航只作为左侧辅助视图，默认约 30% 或更小，并支持折叠或调整宽度；正文、报告、trace、消息或表格等主工作内容应占页面主要空间。
• Workbench 类三栏/双栏工作区优先复用通用 bounded layout 组件或抽取通用组件后再接入新页面；不要为每个页面重新堆叠一套 aside + main + report CSS。根容器和 workspace 使用稳定高度、min-height: 0 和内部滚动，避免 document 级长页或外层横向溢出；窄桌面仍应保持可操作分栏，移动断点再退化为纵向布局。
• 新建、配置、probe、reindex 等低频表单用对话框或抽屉承载；默认版面不要常驻新建框、配置表或调试面板。高频命令保留为稳定按钮或图标按钮，并配清晰状态。
• 文档/任务类页面优先就地阅读和就地编辑：标题和正文双击或显式编辑态切换，不为常规查看单独铺满输入框；正文渲染态必须可见，不能只显示 taskRef、文件名或更新时间。
• 报告、Markdown、日志和 JSON 片段要用成熟 Markdown/代码块渲染，代码块采用浅色 Workbench 风格、可滚动且不撑破布局；不要把裸 JSON 或长日志直接挤爆页面。
• 页面状态要可深链：重要 source/file/task/report/session 选择进入 RESTful URL，并能刷新后恢复；联动其他功能只通过公共 API、稳定 id 和 URL，不把两个功能互相嵌入成强依赖。
• 设计验收必须用截图或 web-probe 样本检查真实版面：正文是否可见、主区域是否足够、弹窗是否遮挡流程、长文本是否溢出、移动/窄屏是否仍可操作。桌面默认视口是 1920x1080；项目/MDTODO/报告类页面还应按风险覆盖紧凑桌面视口（例如 960x600）的深链默认态、左侧树折叠态、右侧报告关闭态。涉及报告渲染或布局重写时还必须覆盖右侧报告栏和报告全屏态。记录 document overflow、pane 宽高、正文/报告可见性、按钮是否被遮挡，以及截图 SHA。

web-probe 证据规则

• 交互式线上验收优先使用 web-probe observe start、observe command、observe collect 和 observe analyze；web-probe script 只作为一次性探测逃生口。重复出现的高频动作（折叠侧栏、关闭报告、切换全屏、导出低码率截图、采集布局指标）必须沉淀为 observe command 或 analyzer 能力。
• Issue closeout 引用 observer id、command id、stateDir/report SHA、screenshot SHA 和关键字段摘要；不要粘贴截图二进制、完整 JSON、Secret、cookie 或无界日志。
• 取证 drill-down 先用 observe collect / observe analyze 的 bounded view；需要截图路径、SHA、traceId 或 command detail 时优先查 control.jsonl、analysis 摘要或专用 artifact view，避免直接 rg samples.jsonl，因为页面快照是超长单行 JSON，容易触发输出截断和噪声。
• Project Management/MDTODO closeout 必须区分 control 页和被动 observer 页：显式 observe command 的 command result、control URL 和对应截图是用户动作证据；observer 周期刷新或 stop 后根路由空态只能作为对照信号，不能覆盖 command result。涉及报告的验收要同时记录 reportPreviewVisible、reportFullscreenVisible、报告 deep link 和截图 SHA。
• MDTODO → Workbench launch 验收必须引用 launchWorkbenchFromMdtodo 的 command result，确认文件/任务选择、Workbench session、launch/chat 状态和 OTel trace header；不要只凭页面最终停在 Workbench URL 判断通过。
• observe analyze 的 archive/history findings 可能包含旧样本或旧规则误判；关闭用户入口问题前同时核对最新 sample 字段、DOM 几何和截图。若 top-level findings、latest sample 和 archive red 冲突，说明冲突并补工具反馈 issue，不要只凭 archive red 或单张截图下结论。

高频工作流

1. 先确认目标：repo、分支/lane、node、用户入口 URL、预期页面或 workflow。
2. 读取对应 SPEC 或 issue，明确验收口径；Workbench 和 Performance 页不要只凭局部 DOM 判断。
3. 用受控 CLI 或 Playwright wrapper 复现：优先 bun scripts/cli.ts web-probe ...，必要时用 bun scripts/playwright-cli.ts ...。
4. 修改前端代码后执行最小相关验证，再用同一原入口复测。
5. 需要关闭用户反馈/issue 时，记录真实入口证据、截图/trace/session 和失败或通过结论。

常用入口

bun scripts/cli.ts web-probe --help
bun scripts/playwright-cli.ts --help
bun scripts/cli.ts check --syntax-only

HWLAB Web probe、fake-server Playwright、fixture 采集脱敏、Workbench/Performance 判定、Web E2E 和线上复测的完整命令矩阵在 references/full.md。

何时读取 reference

• 需要 HWLAB Web probe 采集、observe/analyze、sentinel 或线上截图时，读 references/full.md 的 HWLAB Web Probe、受控 web-probe 段。
• 需要 fake-server 或 Playwright 复现时，读 Fake-Server Playwright、UniDesk Frontend E2E 段。
• 需要 Workbench/Performance 页判定口径时，读对应段落，不要凭经验补规则。