beaver_project/docs/ui-ux/pages/skills.md

主应用：技能页 UI/UX

1. 页面定义

项目	内容
页面名称	技能管理
主路由	/skills
候选子页	/skills?tab=candidates
草稿评审子页	/skills?tab=drafts
页面实现	app-instance/frontend/app/(app)/skills/page.tsx
关键组件	PublishedSkillsTable、CandidateCard、DraftCard、SafetyReportPanel、EvalReportPanel、RawDetails、UploadSkillForm
核心任务	查看已发布技能、打开技能详情、上传技能、处理学习候选、生成草稿、提交/批准/拒绝/复检/发布草稿
测试状态	已修复并复测通过；本地与 terminaltest 生产实例均通过

2. 信息架构与组件层级

AppShell
└── main.pt-16
    └── /skills
        ├── Page Header
        │   ├── h1 Skills
        │   ├── Refresh
        │   └── Upload skill
        ├── Error Card
        ├── UploadSkillForm
        ├── SkillDetailView
        │   ├── Overview
        │   ├── Files
        │   ├── Versions
        │   └── Download / Rollback / Disable / Delete
        └── Tabs
            ├── Published
            │   ├── < md：技能卡片列表
            │   └── >= md：技能表格
            ├── Candidates
            │   └── CandidateCard
            │       ├── 状态、风险、置信度
            │       ├── 候选理由和影响范围
            │       ├── 原始候选数据
            │       └── Ignore / Synthesize draft / Regenerate
            └── Draft review
                └── DraftCard
                    ├── 状态、safety、eval badge
                    ├── 草稿说明和元数据
                    ├── Submit / Approve / Reject / Recheck / Publish
                    ├── Proposed skill body
                    ├── Publish gates
                    ├── Raw draft payload
                    ├── Safety report
                    └── Eval report

3. 布局与响应式规则

• 页面外层使用 max-w-6xl 和响应式内边距：移动端 16px，桌面端 24px。
• tabs 是受控状态，并同步到 URL：候选为 ?tab=candidates，草稿评审为 ?tab=drafts。
• runAction -> load() 后不会再把候选或草稿评审重置到 Published。
• 移动端 Published 不显示宽表格，改为技能卡片；桌面端保留表格以便扫描。
• Candidates 和 Draft review 的卡片、Markdown、JSON、长 id 都使用容器内断行和 min-w-0/max-w-full。
• 草稿评审的 eval replay cases 在移动端显示卡片，桌面端显示表格。
• 原始数据 details/summary 的点击高度为 44px。
• 主要操作按钮均达到 44px 触控目标。

4. 操作与 UX 逻辑

操作	触发方式	状态变化与反馈	UX 目的	当前结果
切换 Published	点击 Published tab	URL 移除 tab 参数	回到已发布技能列表	正常
切换 Candidates	点击 Candidates tab	URL 变为 /skills?tab=candidates	处理学习候选	正常
切换 Draft review	点击 Draft review tab	URL 变为 /skills?tab=drafts	审核和发布草稿	正常
刷新技能页	点击 Refresh	重新拉取已发布、候选、草稿数据	获取最新技能状态	正常
上传技能	点击 Upload skill	展开上传表单，上传成功后刷新	将本地技能包进入草稿评审	正常
打开技能详情	点击 Published 技能	显示 SkillDetailView	查看版本、文件和内容	正常
生成草稿	Candidates 点击 Synthesize draft	调用候选 draft 接口，刷新数据后仍停留 Candidates	不打断候选处理上下文	正常
忽略候选	Candidates 点击 Ignore	本地隐藏该候选	快速清理不处理候选	正常
送审草稿	Draft review 点击 Submit	调用 submit 接口，刷新后仍停留 Draft review	进入人工评审流程	正常
批准草稿	Draft review 点击 Approve	调用 approve 接口，刷新后仍停留 Draft review	满足发布门禁前置	正常
拒绝草稿	Draft review 点击 Reject	调用 reject 接口，刷新后仍停留 Draft review	阻止不合格草稿继续发布	正常
复检安全	Draft review 点击 Recheck	调用 safety 接口，刷新后仍停留 Draft review	获取最新安全结论	正常
发布草稿	Draft review 点击 Publish	满足门禁后调用 publish；高风险需要确认	将草稿转为已发布技能	正常
展开原始数据	点击 Raw details summary	展开/收起 JSON	为审核提供可追溯原始数据	正常

5. 响应式测试矩阵

测试日期：2026-06-04。浏览器：Playwright Chromium。环境：本地 dev server http://127.0.0.1:3080 与生产实例 terminaltest；API 使用模拟数据，真实浏览器执行点击、输入、跳转和截图。

页面	视口	横向越界	小触控目标	关键结论
Candidates	390×844	无	0	生成草稿后仍停留候选页
Draft review	390×844	无	0	送审和批准后仍停留草稿评审页
Draft review	320×568	无	0	长 draft id、Markdown、eval cases 均未撑破页面
Draft review	390×844	无	0	手机竖屏可完成审核操作
Draft review	844×390 横屏	无	0	横屏不出现页面级横向滚动
Draft review	768×1024	无	0	平板布局稳定
Draft review	1365×900	无	0	桌面布局正常

关键量化证据

• 本地技能页 QA 自动化用例 3 passed。
• 部署到 terminaltest 后，同一套技能页 QA 自动化用例 3 passed。
• 候选页点击 Synthesize draft 后 active tab 仍为 Candidates。
• 草稿评审点击 Submit 和 Approve 后 active tab 仍为 Draft review。
• Draft review 实测 320×568、390×844、844×390、768×1024、1365×900 均无页面级横向越界。
• 所有实测视口可见小触控目标数为 0。

6. 已修复问题

等级	问题	修复
P1	Candidates 和 Draft review 中执行任意异步操作后会回到 Published	tabs 从 defaultValue 改为受控 value，并同步 URL tab 参数
P1	草稿页 320px 下长 draft id、Markdown、评估表格会造成横向撑开风险	卡片、Markdown、JSON、长文本统一加容器内断行；eval cases 小屏改卡片
P2	Published 移动端使用宽表格，操作列容易隐藏	< md 改为技能卡片，>= md 保留表格
P2	多个按钮、icon 操作和 Raw details summary 触控高度不足	统一提升到 44px，icon-only 按钮补充可访问名称
P2	候选/草稿 tab 无 URL 状态，刷新或分享不能保留子页	增加 ?tab=candidates 和 ?tab=drafts

7. 剩余观察项

• 本轮自动化使用模拟数据覆盖长 id、长 Markdown、候选和草稿状态转换；真实后端极端数据仍需在后续页面联测中持续观察。
• 发布高风险草稿的确认分支没有在本轮自动化里实际确认发布，只验证了普通草稿审核路径。