qveris-a-stock-data-layer

---
name: qveris-a-stock-data-layer
description: QVeris-native adaptation of candidate 58, A-Stock Data. Use for China A-share quote, history, company profile, financial statement, news, research, sector, announcement, unlock, limit-move, and data-layer reports that must use qveris_finance.* CAP evidence, trace-backed fallback, and no investment advice.
---

# QVeris A-Stock Data Layer

Use this skill to preserve the A-Stock Data candidate's broad A-share data-layer intent while replacing legacy endpoints, scraping, and provider-specific dependencies with QVeris finance CAP calls plus a narrow audited Web lane for news and qualitative sentiment.

Source record:

| Field | Value |
|---|---|
| Candidate number | 58 |
| Original repository | A-Stock Data |
| GitHub URL | https://github.com/simonlin1212/a-stock-data |
| License | Apache-2.0 |
| Evaluation recent activity | 2026-06-28 |
| Local source snapshot | `third_party/source_repos/58-a-stock-data` |
| Snapshot latest commit | `bcda405` on 2026-06-28 |

## Source Adaptation

- Preserve the original ten-layer research/data intent: market data, research reports, signals, capital/ownership, news, fundamentals, filings, limit-up/limit-down, ETF options, and investor interaction.
- Replace the original embedded Python and direct source routing with QVeris CAP calls. The source repo's endpoints, headers, anti-ban rules, `mootdx`, `requests`, `stockstats`, and optional iwencai key are migration context only.
- Convert original valuation flows to evidence-gated trailing or consensus-input notes; do not output target prices, upside/downside, trade setups, or option strategies.
- Convert limit-up, LHB, unlock, capital-flow, ETF-option, hot-list, and investor-Q&A layers to conditional capabilities: call them only after current `cap-detail` confirms a QVeris finance CAP and matching fields.
- Keep broad data-layer reports concise for users; put full call details and rejected payloads in the trace appendix.

## Runtime Contract

- Use only `qveris_finance.*` CAP tools and `QVERIS_API_KEY`.
- Execute every finance data call through this Skill's `scripts/qveris_finance_adapter.mjs`, or through a native wrapper that runs the byte-identical adapter; never call `/capabilities/query` directly from the workflow.
- Default natural-language output to a Markdown user report, not a JSON object.
- Accept `dry_run`, `max_calls`, `max_age`, and `budget_note`; if omitted, default to `dry_run=false`, no hard `max_calls` limit, `max_age=P1D`, and a conservative budget note, then echo those controls.
- Read `references/qveris-finance-data-quality-rubric.md` before using QVeris payloads as evidence.
- Use `references/qveris-finance-retry-policy.md` for 5xx, fetch failures, 404s, payload truncation, and semantic mismatches.
- Read `references/qveris-finance-capability-fallbacks.json` before replacing a failed CAP. Use only a listed same-claim fallback, preserve its declared evidence downgrade, and keep unlisted capabilities missing.
- Build trace, call counts, retries, and timestamps only from saved `observed_calls`. Never invent an execution ID or a call that was only planned; use `execution_id=null` when an observed call returned no ID.
- Sanitize every output surface, including Evidence, Sources, prose, params, responses, and Trace. Strip provider names, provider API URLs, raw route/tool IDs, candidates, failover, credentials, and routing metadata recursively; the Trace row remains exactly `tool_name`, `params`, `status`, `execution_id`, `fallback_used`, and `missing_fields`.
- Sanity-check entity, market, exchange, asset type, currency, date window, fiscal period, and payload shape before using data.
- Treat a successful transport response with wrong A-share identity, wrong date window, wrong fiscal period, or too-thin bars as rejected evidence.
- Suppress target prices, upside/downside, ratings, buy/sell wording, rebalancing instructions, and trade execution plans even if present in a QVeris payload.
- Read and follow `references/qveris-web-news-sentiment-policy.md`. Never call `qveris_finance.news_fin_tagged` or `qveris_finance.sentiment_text_signals`; use its audited Web lane in every run mode, including benchmark and replay.

## Evidence Gate

- Resolve every issuer or instrument through `qveris_finance.ref_symbology` or `qveris_finance.ref_security_master` before quoting it.
- For A-share requests, require returned market/exchange/listing-class evidence to match the requested mainland security. Reject payloads that resolve to a US-listed company, Hong Kong-only listing, index, fund, or unrelated ordinary share.
- Do not guess exchange suffixes from numeric tickers. If QVeris cannot resolve the symbol, mark `symbol_resolution_missing`.
- Require at least 2 observations for multi-day return, trend, volume, liquidity, volatility, or drawdown; otherwise use the payload only as a latest-point snapshot.
- For A-share daily MA5, MA20, and RSI14, use `qveris_finance.mkt_bars_adjusted` as the primary evidence and calculate the indicators from a validated adjusted daily close series. Record the formulas, adjustment basis, sample count, and warm-up observations; never reinterpret a rejected daily interval as intraday minutes.
- For financial statements, require fiscal year, fiscal period, period end, and statement basis to match. If an annual/FY request returns latest-quarter or TTM data, retry once with stricter documented fields after `cap-detail`; if still mismatched, mark the requested statement missing.
- For Chinese text fields, hard reject mojibake or replacement-character artifacts. Do not quote corrupted company names, industry labels, event titles, news snippets, or research titles in user-facing evidence; keep valid numeric/date fields only if identity and window checks pass, and mark the text fields `encoding_artifact`.
- Use opened, issuer-matched, in-window Web pages for news and qualitative sentiment; keep their provenance in `web_trace`, separate from QVeris CAP calls.
- Use analyst/research rows only after a current `cap-detail` confirms issuer, report type, and date fields for the route. Suppress recommendation and target fields.
- Do not use unverified A-share specialty data such as industry/theme classification routes, corporate-event detail routes, capital flow, northbound flow, LHB, unlock calendars, limit-up boards, investor Q&A, ETF options, or concept heat as primary evidence unless a current `cap-detail` confirms a callable QVeris finance CAP with matching fields.
- Call `qveris_finance.mkt_top_movers` for a requested mainland market-wide mover list only after current `cap-detail` confirms `market`, `mode`, and `limit`. Pass `market=CN`; require every returned symbol to identify a mainland `.SH`, `.SZ`, or `.BJ` security, require unique symbols, nonempty names/prices/change percentages, the requested row limit, and ordering consistent with `mode`. Hard reject mixed-market rows, ignored parameters, duplicates, or malformed rankings. When the payload has no `timestamp` or `as_of`, label the result `freshness_unverified`. Treat accepted rows only as mover/ranking context, never as capital flow, sector heat, breadth, or a limit-up/limit-down pool.
- If the user asks for a source-repo-only layer that QVeris has not verified, answer with `capability_unavailable` or `not_called`, not with legacy source instructions.

## CAP Invocation

- Standardized CAP invocation is mandatory. A missing CAP or runtime becomes `capability_unavailable` or `tool_runtime_missing`; it never authorizes a legacy raw route.
- Use native `qveris_finance.*` tools only when that runtime applies the same Skill-owned adapter and returns a `qveris.finance-parameter-adaptation.v1` audit; otherwise use this Skill's CLI.
- If native tools are unavailable and the run is in this repository root, use the repository CLI: `node {baseDir}/scripts/qveris_finance_tool.mjs cap-query qveris_finance.<capability_name> --param key=value --safe-json`.
- Treat the Skill-owned CLI as the mandatory finance adapter: it resolves the live canonical CAP, losslessly adapts parameters, hydrates signed full-content results, and applies the shared data-first semantic gates. The envelope `success` flag is diagnostic only; record `envelope_success` and `contract_clean` separately.
- Permit only evidence-preserving repairs: an explicit option underlying may satisfy a live `symbol` field; an exact-date request may use `daily` after a missing-granularity error; an explicit Q1/Q2/Q3/Q4/FY context may map to provider-declared `0331/0630/0930/1231` codes after an invalid-period error. A corrected call must still pass every evidence gate.
- If the Skill-owned scripts are missing and no native `qveris_finance.*` runtime exposes the identical adapter audit, mark `tool_runtime_missing`; do not use web, legacy providers, or invented data as fallback.
- Use `cap-search` only when the capability ID is uncertain. Use `cap-detail` before adding any unvalidated A-share specialty, classification, research-report, corporate-event, or EOD-bar capability to the run.
- Keep `cap-detail` and failed calls in the trace appendix when they influence missing fields or fallback status.
- For a listed replacement, use `cap-query-chain --chain-json <JSON>` or make the same explicit canonical CAP calls through the native runtime. A chain may contain at most three distinct `qveris_finance.*` CAPs; record `qveris.finance-capability-fallback.v1`, and never hide the failed primary CAP.

## Workflows

1. Identity gate: resolve symbol and security master. Stop the run if canonical A-share identity cannot be validated.
2. Requested-window bars: fetch the exact requested window next. If bars fail identity/window validation or are too thin for the requested analysis, return a latest snapshot or insufficient report and stop optional fan-out.
3. One financial/valuation layer: call only the single statement or valuation layer most relevant to the request; validate market support and period before expanding.
4. Event/news layer: call corporate-event CAPs for structured events and use the audited Web lane for news or qualitative sentiment only when requested or needed for the core answer.
5. Optional specialty layer: spend remaining budget on at most one requested classification, flow, LHB, unlock, limit-move, investor-Q&A, or ETF-option route after `cap-detail` confirms its contract.
6. Expand only after the preceding core gates succeed. Do not fan out across ten source layers merely because they exist in the source skill.

## Fallback Policy

- If QVeris returns 503, fetch failure, timeout, or all candidates failed, retry at most twice under the shared retry policy.
- If a CAP returns 404 or invalid capability, do not blind retry; mark `capability_unavailable` unless `cap-search` finds a replacement.
- If bars return fewer observations than requested, do not compute multi-day metrics; mark `insufficient_observations`.
- If identity, requested-window bars, or the requested financial layer fails its semantic gate, stop specialty fan-out and return the partial result with exact required next calls.
- If A-share specialty data is unavailable, return a partial data-layer report with missing fields rather than substituting web or legacy endpoints.
- Do not treat a proxy fallback as equivalent primary evidence. Apply the exact `complete`, `partial`, or `proxy_only` status and forbidden-claim list from `references/qveris-finance-capability-fallbacks.json`.
- If a successful payload contains corrupted text fields, exclude the corrupted fields from the report body and mark `encoding_artifact`; do not translate, repair, or infer the intended wording.
- If fewer than two qualifying Web sources are available, write supported news context only and set qualitative sentiment to `insufficient`.

## Output Requirements

- Use level-2 Markdown headings exactly for this user-report structure: `## Summary`, `## Evidence`, `## Analysis`, `## Data Quality And Missing Fields`, and `## Trace Appendix`. Do not replace these headings with bold text.
- Include a concise evidence table with claim, `qveris_finance.*` capability, parameters, status, and fallback.
- Render the Trace Appendix with the exact parseable header `| tool_name | params | status | execution_id | fallback_used | missing_fields |`; use compact JSON values, one row per observed attempt, and no planned/not-called rows.
- For live, fresh, or E2E output, save and validate an `observed_calls.v1` sidecar whose calls record `request_kind=capabilities/query` and canonical `capability_id`; without a verified sidecar, place the unverified note before `## Trace Appendix` and emit only the exact header plus separator with no rows.
- Put full `qveris_trace` JSON only in the appendix, schema fixture, or when the user asks for machine-readable output.
- Include `missing_fields`, `data_quality.status`, stale fields, rejected payload reasons, and suppressed fields.
- End user-facing reports with `Not investment advice.`

## Prohibited Capabilities

Do not use non-QVeris structured-finance data sources, Web use outside the audited news/sentiment policy, browser automation, cookies, login state, external provider keys, dynamic data-package installs, automated trading, buy/sell triggers, target prices, upside/downside, rebalancing instructions, or execution plans.

## References

- Use shared finance contract version `2026-07-29.1`; repository CI verifies the local rubric, retry policy, CAP registry, and output schema against `references/qveris-finance-shared-manifest.json` hashes.
- Use `references/qveris-finance-capability-fallbacks.json` for the audited cross-CAP replacement boundary.
- Read `references/qveris-tool-map.md` before choosing calls for an A-share data-layer report.
- Read `references/qveris-finance-data-quality-rubric.md` before treating any payload as evidence.
- Read `references/qveris-finance-retry-policy.md` when a CAP fails, returns the wrong shape, or needs fallback.
- Read `references/qveris-web-news-sentiment-policy.md` before collecting news or qualitative sentiment.
- Check `references/qveris-finance-cap-registry-snapshot-2026-07-07.md` before adding a route to the primary path.
- Use `examples/default-markdown-report.md` as the primary user-facing example.
- Use `fixtures/qveris/*.json` as machine-readable schema fixtures only.

• SKILL.md 14 KB
• agents/openai.yaml 1 KB
• examples/default-markdown-report.md 2 KB
• examples/live-e2e-output-2026-07-13.md 1 KB
• examples/live-e2e-output-2026-07-13.observed-calls.json 4 KB
• examples/natural-language-prompts.md 1 KB
• examples/natural-language-test-output-2026-07-08.md 2 KB
• examples/historical/2026-07-08-codex-clean.md 5 KB
• examples/historical/2026-07-08-codex-fresh.md 6 KB
• examples/historical/2026-07-08-natural-language.md 3 KB
• fixtures/qveris/budget-limited-output.json 1 KB
• fixtures/qveris/fallback-output.json 2 KB
• fixtures/qveris/sample-output.json 3 KB
• references/qveris-finance-cap-registry-snapshot-2026-07-07.md 10 KB
• references/qveris-finance-capability-fallbacks.json 4 KB
• references/qveris-finance-data-quality-rubric.md 14 KB
• references/qveris-finance-retry-policy.md 6 KB
• references/qveris-tool-map.md 7 KB
• references/qveris-web-news-sentiment-policy.md 3 KB
• schemas/output.schema.json 5 KB
• scripts/qveris_finance_adapter.mjs 48 KB
• scripts/qveris_finance_client.mjs 3 KB
• scripts/qveris_finance_tool.mjs 5 KB
• scripts/qveris_sanitize.mjs 3 KB
• tests/business_adapter_copies.test.mjs 4 KB
• tests/qveris_finance_adapter.test.mjs 38 KB