web
Guide agents modifying Observal's Vite/React/TanStack Router web frontend, query hooks, auth storage, registry/admin/traces/insights pages, theme tokens, type centralization, and UI verification.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- web
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- description
- Guide agents modifying Observal's Vite/React/TanStack Router web frontend, query hooks, auth storage, registry/admin/traces/insights pages, theme tokens, type centralization, and UI verification.
- disable-model-invocation
- true
02 资源文件 4
- 参考文档references/api-hooks-and-types.md7.5 KB
- 参考文档references/frontend-architecture.md10.3 KB
- 参考文档references/troubleshooting.md6.6 KB
- 参考文档references/ui-testing.md6.3 KB
03 SKILL.md 正文
Observal Web Frontend Router
Use this sub-skill when the task touches the Observal web UI: Vite/React route files, lazy page modules, shared UI components, TanStack Query hooks, auth/session storage, registry/admin/traces/insights pages, theme tokens, frontend type contracts, or Playwright/screenshot verification.
Do not use this sub-skill for CLI command semantics, FastAPI route/business logic, database migrations, harness adapter/session-parser behavior, telemetry hook delivery, release policy, or cross-repo contribution workflow. Route those to the owning sub-skill.
Route the request
- Architecture, route ownership, page/component layout, navigation, theme tokens: read
references/frontend-architecture.md. - API wrapper, TanStack Query hooks, auth storage/refresh, server-fetched harness data, type placement: read
references/api-hooks-and-types.md. - Verification commands, E2E selection, screenshot expectations, and expected signals: read
references/ui-testing.md. - Install, import, auth/API, config, optional dependency, telemetry/harness, and workflow failure recovery: read
references/troubleshooting.md.
Non-negotiable rules
- The frontend is a Vite SPA with React 19 and TanStack Router; it is not Next.js.
- File routes live under
web/src/routes/; complex routes usually lazy-load modules underweb/src/pages/. Do not editweb/src/routeTree.gen.tsby hand. - Use TanStack Query hooks. Add reusable API calls to
web/src/lib/api.ts, wrap them in the closestweb/src/hooks/use-*-api.tsmodule, and export reusable hooks throughweb/src/hooks/use-api.tswhen appropriate. - Do not hardcode harness lists or capabilities in frontend code. Use server data from
/api/v1/config/harnessesthroughuseHarnesses(). - Keep shared API response types in
web/src/lib/types.tsor one of the files it reexports. Avoid inline shared response types in components. - Auth storage is deliberately split: access token in
sessionStorage, refresh token and cached profile fields inlocalStorage. Do not widenlocalStorageuse unless the auth model is intentionally changed. - Use semantic OKLCH theme tokens from
web/src/app.cssand the theme provider. Do not add raw hex/rgb colors or external font CDNs to components. - For user-visible UI changes, provide targeted verification and screenshots for touched states before claiming completion.
Default work loop
- Identify the owning route/page/component/hook from the architecture reference.
- If new server data is needed, update API types,
api.ts, query hook module, and query invalidation before wiring components. - Add or change route files with TanStack Router helpers and typed
validateSearchwhere query params matter. - Use shared layout, loading, empty, error, table, registry, review, traces, and shadcn/ui primitives instead of one-off patterns.
- Run the bundled static helper, then the smallest safe frontend checks for the change.
- Escalate instead of patching around missing backend contracts, CLI command changes, harness telemetry gaps, or deployment policy decisions.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.