workflows.md

Targeted diagnosis and live checks

Use this reference for a failure or an explicitly needed verification, not as a prerequisite for normal implementation. Fix the requested integration; do not audit every endpoint or run repository-maintainer checks in a business project. Preserve a working framework and make the smallest relevant change.

Start from the symptom

Capture only the endpoint, model, SDK/version, status, content type, request ID, and a bounded redacted error sample. Never capture credentials, private prompts, or reasoning. Read the matching section below, not the entire deviation log. These links are dated observations, not claims that the issue still reproduces.

Symptom	Check / relevant evidence
200 with an empty model list	Not proof of authentication: invalid bearer
Missing auth produces an unexpected error	Preserve actual status and body type: missing authorization
A new model ID appears but fails	Discovery is not endpoint capability: runtime-only model
401 only for an unsupported model or [1m]	Compare a documented working control; do not rotate keys blindly: unsupported model, suffix conditions
401 with 获取第三方元数据失败 under rapid requests	Compare the dated spacing observation; the error alone does not identify the cause: rapid-request 401
SDK works for chat but embeddings fail	Check raw strings and local validation: embedding recipe
Tool continuation loses state or reasoning fields	Preserve the actual message and inspect serialization: recipe, field variation
reasoning_content is absent but thinking seems active	Check usage.completion_tokens_details.reasoning_tokens, not message.reasoning_content: field variation, alias default thinking
ecnu-max thinking will not activate	Send the documented explicit switch; effort-only activation was observed in September, not revalidated for the current backend
An effort tier fails	Use the chosen model's documented tiers; the September max observation does not apply to plus
TTS error parsing crashes	Tolerate non-JSON errors: invalid voice
PCM bytes arrive without format metadata	Configure the format explicitly: missing headers
Old max-vision notes conflict with current docs	Current docs list image understanding on both models; the September 12 fixture predates the 2026-09-18 text-only interval and the 2026-10-01 backend update
422	Inspect detail and the relevant request contract; do not retry the unchanged request
429	Check current credits/quota and the independent per-user concurrency caps (ecnu-max: 3; ecnu-plus: 5); stop parallel retries
Timeout or dropped connection after POST	Completion and debit may be unknown; do not automatically resubmit

A later release announcement does not by itself resolve a deviation. Do not change observation dates or statuses without reproducing the affected behavior.

Run only the check needed

If execution is not authorized or the key is absent, continue offline diagnosis and provide the smallest runnable check. Do not repeatedly ask for authorization already covering this account, data, destination, purpose, and cumulative budget. New scope or an explicit per-action approval requirement still needs approval.

For authorized live checks, use the existing scripts/smoke_test.py from the installed skill's directory, not an assumed script in the user's application. Check current prices first. The runner reads only ECNU_API_KEY, runs serially, disables POST retries, reserves estimated credits, and redacts reports. Its 50-credit default is a cap, not authorization; use the lower approved cap and obtain separate authorization before exceeding 50. Estimates are not actual debit. Keep the same cumulative allowance across reruns, not a new allowance per process. Token estimates use base/off-peak rates, not the current peak/holiday multiplier; include that multiplier when checking the approved allowance. Fixed-price embedding, rerank, image and TTS calls do not use peak pricing.

To inspect options without a network request:

python3 scripts/smoke_test.py --help

After approval for a model-list check and one SDK chat probe, with current estimated cost within the approved allowance, an example targeted invocation is:

python3 scripts/smoke_test.py --profile core   --case models_valid --case openai_sdk_chat   --max-credits 1 --output .live-artifacts/openai-sdk-chat.json

The example ceiling is not a current price quote or spending permission. Choose an actual case that answers the user's question. auth performs GET checks only but is not conclusive authentication proof; core, compatibility, and billable group other probes. Use --case to narrow them. Do not use all for an ordinary integration check. Image/TTS probes need authorization covering those billable operations and must not be scheduled automatically.

The runner does not yet have live cases for VL retrieval or image editing. For those tasks, adapt the minimal recipes to one authorized, serial check with synthetic or approved media; preserve the same timeout, no-retry and redaction boundaries. Offline recipe tests validate request serialization and error handling, not service availability or output quality.

Interpret the evidence

Runner result	Meaning
pass	That case's checks passed in this dated environment, not universal task quality
mismatch	The observed response differs from the checked expectation
inconclusive	No supportable conclusion, including a transport failure
skipped	No request ran; no live evidence

Keep reports under ignored .live-artifacts/. Report what was actually run and what remains unknown; a failed download does not authorize another paid generation. For a suffix fallback, retain the exact working-control and consent conditions in the linked deviation rather than silently downgrading the capability.