前端主题工程师-前端API交互

Role

This skill owns browser-visible API interaction patterns in WelineFramework theme surfaces. It standardizes how frontend code talks to backend capabilities through theme.js, the built-in weline-api, and the worker-routed query chain instead of direct browser HTTP calls.

When To Use

• Use for theme-visible API interactions, frontend business requests, provider calls, browser-side query access, SSE or stream subscriptions, and request error handling on browser surfaces.
• Use for keywords such as weline-api, Weline.Api, resource(), graph(), stream(), theme.js, worker request chain, frontend API, browser API, query-bin, and frontend QueryProvider access.
• Use when the task changes how browser code requests, submits, refreshes, streams, or handles API data in a theme, component, or widget surface.

Source Material

• AI-ENTRY.md
• dev/ai/global-constraints.md
• app/code/Weline/Frontend/doc/AI-INDEX.md
• app/code/Weline/Theme/doc/AI-INDEX.md
• app/code/Weline/Theme/doc/开发/Theme开发总指南.md
• app/code/Weline/Theme/doc/Theme.js使用指南.md
• app/code/Weline/Frontend/doc/Weline.Api使用指南.md
• dev/ai/skills/前端主题工程师-主题模板开发/SKILL.md
• dev/ai/skills/前端主题工程师-组件与页面构建/SKILL.md

Responsibilities

• Keep all browser business requests on the official theme.js -> weline-api -> worker path.
• Treat bin-query / weline-api as the only approved frontend-backend business interface path.
• Choose the correct frontend API surface: Weline.Api.resource(), Weline.Api.graph(), Weline.Api.stream(), or low-level Weline.Api.request() helpers when appropriate.
• Keep backend protocol details hidden from business templates and module scripts.
• Preserve unified maintenance handling, HTTP error handling, retry behavior, and DEV diagnostics provided by Weline.Api.
• Enforce request examples and implementation patterns that future AIs can safely copy.

Workflow

1. Read AI-ENTRY.md, dev/ai/global-constraints.md, app/code/Weline/Frontend/doc/AI-INDEX.md, the owning module's doc/AI-INDEX.md, and the Weline API docs before touching browser request code.
2. Identify the visible surface: theme template, component JS, widget, or route-level frontend script.
3. Classify the interaction:
   • Provider-style business operation -> const Api = await Weline.Api.resource('provider')
   • Aggregated or graph-style browser query -> Weline.Api.graph()
   • Streaming or SSE-style browser subscription -> Weline.Api.stream()
   • Low-level route request with unified error handling -> Weline.Api.request()/get()/post()
4. Implement the smallest change that keeps request ownership inside the approved API surface and never handwrites worker protocol URLs.
5. Keep request-state UI, toasts, and retries aligned with framework behavior instead of recreating them ad hoc.
6. Validate from the real rendered page or interactive browser surface.

Weline Rules

• All browser-visible frontend-backend business requests must go through bin-query, via Theme theme.js and the built-in weline-api.
• For station-internal business APIs, prefer const Api = await Weline.Api.resource('provider') and then await Api.operation(params).
• Use Weline.Api.graph() for graph-style frontend data access and Weline.Api.stream() for stream or SSE-style subscriptions.
• Backend capabilities consumed by browser business flows must be exposed through QueryProvider / frontend=true operations and called through Weline.Api.*.
• Do not handwrite /api/framework/query-bin, worker protocol URLs, or direct business REST URLs in theme templates, module scripts, or API examples.
• Do not add direct browser requests with native Ajax/XHR, fetch, XMLHttpRequest, $.ajax, axios, or new EventSource(url) for Weline business flows.
• Do not keep "quick" examples, temporary fallbacks, or compatibility branches that use raw Ajax/XHR/fetch when weline-api is unavailable.
• Do not bypass Weline maintenance handling, default HTTP error handling, or unified request diagnostics unless the framework docs explicitly allow it.
• Use silent, onError, and onHttpError only when the business case genuinely needs custom handling.
• Keep examples copy-safe for other AIs and engineers: if one example would normalize a bad pattern, do not write it.

Inputs Required

• The target browser-visible page, component, or theme surface.
• The provider or backend capability being consumed.
• The interaction style: query, mutation, refresh, upload, or stream.
• The expected user-visible result and validation path.

Expected Output

• Browser request code written against the official Weline API surface.
• No direct browser-side HTTP implementation for station-internal business flows.
• Validation evidence from the rendered route or browser interaction path.

Validation

• Confirm the final code uses theme.js / weline-api rather than direct browser HTTP calls.
• Confirm provider-style business requests use Weline.Api.resource() unless graph or stream semantics are truly needed.
• Confirm stream scenarios use Weline.Api.stream() instead of raw EventSource.
• Confirm no business code handwrites /api/framework/query-bin.
• Confirm request errors are handled through framework-approved Weline.Api behavior.
• Confirm the visible interaction passes Browser smoke verification when the task changes a browser-visible flow.

Constraints

• Do not introduce alternative request helpers for the same browser business path.
• Do not expose internal worker protocol details in reusable examples.
• Do not keep temporary fallback branches like window.Weline.Api ? ... : fetch(...).
• Do not describe a browser-visible API change as verified unless the real browser flow was checked.

Shared Collaboration Contract

This specialist skill must follow 通用工程师-开发规范与代码质量 as the shared engineering and collaboration standard.

Before and during work:

• Know the Weline AI agent roster defined in the shared skill and dev/ai/agent/README.md.
• Keep work inside this specialist's ownership boundary.
• When a problem, blocker, risk, validation failure, or cross-agent issue is found, notify @Weline-技术主管.
• Do not silently expand scope to fix another agent's area.
• Include collaboration status in the final report.