browser/openspec/changes/polish-platform-interaction-design/tasks.md

1. Interaction Audit and Acceptance Criteria

• 1.1 Audit 首页、服务器管理、插件市场、用户管理、AI 提供商管理, and server detail against the accepted interaction polish requirements.
• 1.2 Identify any visible overlap, clipped labels, weak hierarchy, unclear primary actions, missing empty/error/loading states, or color-only status cues.
• 1.3 Confirm the implementation scope remains platform_web polish only and does not add billing, cloud host sales, provider marketplace workflows, direct run access, or plugin transport shortcuts.
• 1.4 Map every planned UI change to shared route components, shared theme primitives, or documented shared CSS additions.

2. Shared Theme and Layout Polish

• 2.1 Reuse or extend theme/tokens.ts and theme/base.css for any new shared materials, frames, command states, tables, drawers, dialogs, or responsive primitives.
• 2.2 Preserve black mecha as the default theme and magical-girl as the alternate theme, with distinct token-driven materials and readable translucent surfaces.
• 2.3 Keep grouped large-entry navigation, large icon badges, bold Chinese labels, expandable child rows, active frames, and single-column/double-column density behavior.
• 2.4 Keep full-workspace decorative effects centralized in components/MagicalParticleLayer.tsx; do not add page-local fixed decorative DOM/CSS motifs.
• 2.5 Keep framed repeated items at 8px-or-less radii unless a native pill/circle control shape is required.

3. First-Party Route Polish

• 3.1 Polish 首页 hierarchy so loaded platform overview, resource/health signals, game/plugin counts, and refresh/recovery affordance are clear at desktop and mobile widths.
• 3.2 Polish 服务器管理 so server identity, lifecycle state, run assignment, filters, creation entry point, and drill-in affordance are scannable without a fixed left-list/right-detail layout.
• 3.3 Polish 插件市场 so plugin identity, installed state, manifest reference, lifecycle capabilities, permissions, bridge actions, and validation state are readable and safe.
• 3.4 Polish 用户管理 so API-connected account rows, role/status cues, create/edit affordances, and loading/empty/error states are clear and not color-only.
• 3.5 Polish AI 提供商管理 so provider status, relay mode, model/default-model details, and redacted key references are readable without exposing raw keys.

4. Server Detail Workflow Polish

• 4.1 Polish server detail header and tabs so server name, ID, plugin version, run node, lifecycle state, and tab navigation remain visible across desktop and mobile widths.
• 4.2 Polish lifecycle command states so start/stop controls have clear labels, disabled/progress behavior, confirmations or feedback where appropriate, and operation-history visibility.
• 4.3 Polish logs, config, plugin controls, AI assistant, artifacts, and operation history surfaces with meaningful loaded/empty/error states, safe logical IDs, readable timestamps, and traceable outcomes.
• 4.4 Confirm server detail and plugin controls remain platform-mediated and do not expose raw host paths, sockets, credentials, direct run URLs, or plugin-owned transports.

5. Browser Walkthrough and Automated Acceptance

• 5.1 Run a browser walkthrough at a desktop viewport across 首页、服务器管理、插件市场、用户管理、AI 提供商管理, server detail, lifecycle controls, plugin controls, logs/config/AI/operation-history tabs, and record evidence.
• 5.2 Run a browser walkthrough at a mobile viewport across the same required first-party areas and server detail workflow surfaces, and record evidence.
• 5.3 Verify both black mecha and magical-girl themes preserve readable surfaces, distinct theme treatments, navigation clarity, and background visibility.
• 5.4 Run LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance scripts/browser-acceptance.sh and record the evidence path.

6. Verification and Stream Update

• 6.1 Run cd platform_web && npm run typecheck && npm test && npm run build and record evidence.
• 6.2 Run scripts/check-structure.sh and record evidence.
• 6.3 Run openspec validate polish-platform-interaction-design --strict and record evidence.
• 6.4 If structural theme rules or shared style contracts change, update platform_web/theme/README.md and any relevant tests in the same change.
• 6.5 Update openspec/changes/architecture-delivery-stream/delivery-plan.md and openspec/changes/architecture-delivery-stream/NEXT_CHANGE.md after implementation evidence exists.

7. Management Header Density Correction

• 7.1 Replace large framed management summary KPI cards in 插件市场、用户管理, and AI 提供商管理 with compact contextual status chips.
• 7.2 Add regression tests proving those management headers render page-summary-chip instead of metric-card.
• 7.3 Run focused frontend tests, scripts/check-structure.sh, and openspec validate polish-platform-interaction-design --strict; record evidence.

8. Human Workflow Polish Follow-up

• 8.1 Replace duplicate 用户管理 status/deactivation buttons with one status selector flow and explicit confirmation when disabling access.
• 8.2 Add user invitation, review, server-scope, and role-impact guidance without adding new backend authorization semantics.
• 8.3 Replace AI provider icon-only row actions with readable action labels and a compact "more" menu for lower-frequency enable/retire actions.
• 8.4 Add AI provider setup guidance: presets, secret-reference help, save-before validation, saved-configuration testing, and model discovery fill-in.
• 8.5 Add 系统维护 triage entry points for endpoint heartbeat/capacity, failed jobs, and related server/log navigation links.
• 8.6 Run focused frontend tests and typecheck; use the existing 5173 browser instance to spot-check the changed pages.

Evidence

• platform_web/pages/UsersPage.tsx: added explicit loading, API fallback error, empty-state, and accessible row action labels for 用户管理.
• platform_web/pages/AiProvidersPage.tsx: added an explicit empty-state for filtered AI provider lists while preserving redacted apiKeyRef display.
• platform_web/pages/ServersPage.tsx: polished create workflow feedback with an inline result strip.
• platform_web/pages/PluginsPage.tsx: polished plugin detail framing and action strip behavior.
• platform_web/theme/base.css: hardened shared action strips, server toolbars, catalog cards, plugin detail panels, result strips, responsive grids, and table/workspace min-width behavior.
• platform_web/acceptance/browser-acceptance.mjs: expanded browser acceptance to record desktop/mobile walkthroughs for black mecha and magical-girl themes, route marker checks, visible-layout checks, API-backed route proof, plugin controls, and operation-history proof.
• Header density correction evidence: platform_web/components/PageFrame.tsx and platform_web/pages/AiProvidersPage.tsx now render management summary counts as page-summary-chip; platform_web/pages/PluginsPage.test.tsx, platform_web/pages/UsersPage.test.tsx, and platform_web/pages/AiProvidersPage.test.tsx assert those headers no longer render metric-card.
• Focused frontend evidence: cd platform_web && npm test -- PluginsPage.test.tsx UsersPage.test.tsx AiProvidersPage.test.tsx, cd platform_web && npm run typecheck, and cd platform_web && npm run build passed for the header density correction.
• Browser evidence: LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance scripts/browser-acceptance.sh passed; evidence file /private/tmp/browser-local-debug-acceptance/browser-acceptance/browser-acceptance-evidence.json records 7 required routes plus 4 walkthrough scenarios: desktop/mobile black mecha and desktop/mobile magical-girl.
• Frontend evidence: cd platform_web && npm run typecheck, cd platform_web && npm test (11 files / 49 tests), and cd platform_web && npm run build passed.
• Structure evidence: scripts/check-structure.sh passed.
• OpenSpec evidence: openspec validate polish-platform-interaction-design --strict passed.
• Human workflow polish evidence: platform_web/pages/UsersPage.tsx now uses one status selector/apply path, keeps disable confirmation, renames create flow to 邀请用户, and shows invite/review/server-scope/role-impact guidance.
• AI provider workflow evidence: platform_web/pages/AiProvidersPage.tsx now shows row actions as 测试 / 模型 / 编辑 / 更多, moves enable/retire into the more menu, adds provider presets, secret-reference help, 保存前检查, saved-configuration testing, and saved-model discovery fill-in.
• Maintenance triage evidence: platform_web/pages/MaintenancePage.tsx now loads endpoints, jobs, servers, and audit events to show node heartbeat/capacity detail, recent failed jobs, retry dispatch, related server links, and log-chain entry copy.
• Human workflow verification: cd platform_web && npm test -- UsersPage.test.tsx AiProvidersPage.test.tsx ConsolePages.test.tsx, cd platform_web && npm run typecheck, and cd platform_web && npm run build passed. scripts/check-structure.sh passed. openspec validate polish-platform-interaction-design --strict passed; only PostHog telemetry flushing failed due restricted network after validation succeeded.
• Browser spot-check evidence: existing http://127.0.0.1:5173 was opened and logged in with the local test operator. #/aiProviders showed readable row actions and edit dialog guidance with no clipped target buttons and no api.example.test; #/users showed 邀请用户, 审核申请, 绑定服务器范围, 角色影响, 应用状态, no duplicate “停用用户” label, and no clipped target buttons; #/maintenance showed 系统维护, 节点详情, 最近失败任务, heartbeat/status context, and the follow-up commit adds visible 维护排障入口 / 查看相关服务器 / 查看日志链路 copy for empty-data states.