pseudo-longinus/quant-buddy-view

quant-buddy-view · Quant Dashboard Publishing

Distill the insights from quant-buddy-skill into a publicly shareable web dashboard. This skill does NOT handle market data queries or backtesting exploration (that's quant-buddy-skill's job). It focuses on three tasks:

1. Register a Formula Package (formula_package) — Register a set of formulas + read modes for each output with the server, obtaining a package_id + signature. When underlying data updates, the server automatically recalculates, so fetching always returns the latest results.
2. Generate Dashboard HTML (build_dashboard) — Use a spec to describe "which outputs, displayed with what charts/tables", and compile it into a live, real-time data-fetching HTML (self-contained skeleton, data fetched in real-time when opened).
3. Publish Hosting (static_page) — Upload the HTML to object storage, obtaining a public link like https://pages.quantbuddy.cn/....

When to Use This Skill vs quant-buddy-skill

• Exploration / One-off Query ("What's Moutai's price change today?", "Run a backtest on Golden Cross") → Use quant-buddy-skill.
• Need a page that can be viewed repeatedly, shared with others, and updates automatically → After exploration, switch to quant-buddy-view.

Prerequisite: Must Install quant-buddy-skill First

This skill is runtime self-contained (registration/generation/publishing only relies on the api_key in config.json, not on quant-buddy-skill's code). However, there is a hard prerequisite in the normal workflow: Before registering a formula package, each set of formulas must first be run and confirmed to produce outputs using runMultiFormulaBatchStream in quant-buddy-skill (see "Hard Rules Before Registration" below). Therefore, without quant-buddy-skill installed, you cannot correctly complete the formula verification step.

If quant-buddy-skill is not installed, install it in this priority order:

1. Priority: GitHub Install (npx skills) — quant-buddy-skill belongs to the same GitHub repository pseudo-longinus/quant-buddy-skills as this skill:

   # Fresh install (never installed before)
   npx skills add pseudo-longinus/quant-buddy-skills -g --all
   # Already installed, just need to update
   npx skills update pseudo-longinus/quant-buddy-skills -y
   # Check where it is installed and if it's installed:
   npx skills list -g --json
   

   On Windows, if you encounter symlink / EPERM errors, append --copy to the command and retry. The installation path is typically ~/.agents/skills/quant-buddy-skill.

2. Fallback: Download Zip Archive and Manually Extract (when node/npx is unavailable, or network is restricted) — Download the official quant-buddy-skill zip, extract it to the skills directory as quant-buddy-skill/ (first extract to a temporary directory, if it contains a nested quant-buddy-skill/ directory, use that inner one; retain the api_key from any existing config.json). quant-buddy-skill comes with scripts/self_update.py, which supports --url / --zip-path + --sha512 + --version for validated extraction; use it first.

Placement Layout: Place quant-buddy-skill as a sibling to quant-buddy-view:

<skills directory>/
  quant-buddy-skill/      ← Exploration / Formula Verification (runMultiFormulaBatchStream, confirmDataMulti)
  quant-buddy-view/       ← This skill: Register formula package / Generate dashboard / Publish

This sibling layout is recommended because when formula_package import (migrating old credentials) cannot find an explicit path, it defaults to looking in the sibling ../quant-buddy-skill directory as a fallback.

3. Configuration: Configure its own api_key in quant-buddy-skill (independent from this skill). Once installed, verify formulas there, then return to this skill for register.

Migration for Existing Users: Formula packages already registered in an older version of quant-buddy-skill do not need to be re-registered — use python scripts/formula_package.py import ... to import the credentials into this skill in one go and continue using the old package_id for data fetching (see tools/formula_package.md's "Import Credentials from old quant-buddy-skill").

Entry Point Selection (Determine Type First)

Agent Routing Rule: User mentions template marketplace / official templates / public templates / published templates → First use scripts/static_page.py templates / template to read online public templates; download the HTML from the download_url returned by template via direct OSS link, replace tickers, copy, formula package credentials, then upload as the user's own page. User wants a specific page format but does not mention public templates → First check local examples/ (offline fallback and template development source for online templates). User wants to go from requirement to link → See workflows/. User wants a complex custom page or to migrate old HTML → See guides/.

Type	Display Name	Entry	When to Use
Page Template	Single Stock Snapshot	examples/single-stock/	Single ticker profile page: reading summary + latest price/change/20D/60D/PE/PB/volume number cards + main price chart. Must start from spec.template.json.
Page Template	Single Stock Valuation	examples/valuation-financial-profile/	Single ticker valuation & financials page: PE/PB/PCF historical percentiles, financial trends, cash flow quality, valuation change attribution. Comes with page.template.html.
Page Template	Constituent Anomaly List	examples/index-anomaly/	Index/stock pool constituent anomaly monitoring: anomaly list + gain/loss distribution + index trend. Comes with page.template.html, dark theme, data-kernel data fetching.
Page Template	Multi-Factor Screener	examples/multi-factor-screener/	Thematic stock pool + multi-factor scoring + TopN list + backtest/rankIC + K-line + formula audit. Fixed roles RANK / BACKTEST / KLINE_*, RANK is rendered first on the initial screen.
Page Template	Commodity Daily Report	examples/commodity-daily/	Commodity futures daily report: sector long/short dominant contradictions + daily anomalies + top ticker sparklines. Comes with page.template.html.
General Workflow	Standard Live Dashboard	workflows/dashboard-end-to-end.md	User wants to "make a shareable dashboard/link" but does not specify a fixed page template.
Development Guide	Bespoke Page	guides/bespoke-page.md	Custom HTML/CSS/SVG pages that build_dashboard cannot produce, or to migrate existing HTML.
Migration Tool	Retrofit Shell	tools/retrofit_share_shell.md	Published/generated HTML needs to remove old QR codes, old headers, old footers, and update under the same page_id.

Hard Rule: When a user asks for "a profile page for a specific stock/index, individual stock profile, single ticker page", first read examples/single-stock/README.md, copy examples/single-stock/spec.template.json as the spec starting point, keeping template: "single-stock". Do not manually write a minimal spec with the old "1 price line + 4 number cards" format; build_dashboard will reject this old skeleton. Hard Rule: When a user asks "Is this stock expensive / has its fundamentals improved / valuation & financial profile / PE/PB historical percentiles / financial trends / cash flow quality" and wants a landing page or public link, first read examples/valuation-financial-profile/README.md, copy examples/valuation-financial-profile/page.template.html as a starting point, verify and register the set of formula packages required by that template. Do not fall back to a generic single-stock card page. Hard Rule: When a user asks for "constituent anomalies for a specific index/stock pool, anomaly list, leaderboard-style ranking" (e.g., "Which stocks in CSI 500 moved today?", "CSI 300 anomaly monitoring", "SSE 50 top gainers/losers"), first read examples/index-anomaly/README.md, copy examples/index-anomaly/page.template.html as a starting point, replace __INDEX_*__ placeholders, inline data-kernel.js, and then publish. Do not manually create a light-colored/generic HTML that is off-topic. Hard Rule: When a user wants a "thematic stock pool / concept stocks / industry pool + multi-factor scoring / TopN / backtest / rankIC / K-line / formula audit" stock screener workspace page, first read examples/multi-factor-screener/README.md, copy examples/multi-factor-screener/page.template.html as a starting point. Formula package roles are fixed to RANK / BACKTEST / KLINE_*. RANK must be rendered first on the initial screen; BACKTEST and KLINE_* may be lazily loaded or degraded locally. Hard Rule: When reusing a public template, the package_id + signature in the template HTML belongs to the original author. You must re-verify the formulas for the target user's context, register your own formula package, and replace the credentials in the page before publishing. Do not use the public template's original credentials directly as the data source for the user's page. Hard Rule: The subtitle and "reading summary" for a single ticker profile page can only use numerical values from the real-time data fetched during the build_dashboard construction phase (the final outputs). If a script returns "the copy does not match the real-time data results", rewrite the copy based on the returned facts before generating/uploading. Do not use old query results or manual estimates. Hard Rule: All landing pages must incorporate the assets/share-shell/ common component. The template is only responsible for the main content and getPosterData(). The header, footer, refresh button, share poster popup layer, copy link, copy/download PNG, and poster fixed header/footer are all provided by the common shell. Do not copy or modify old QR code blocks, old refresh buttons, or old share popup layers within individual templates. Hard Rule: Share posters are generated by default by the public poster.js which screenshots the main page content. Output is acceptable as a default; do not over-design. Templates can use data-qb-poster-target to mark the core screenshot area. getPosterData() should only provide title/summary and structured fallback candidates. Do not rely on the Agent to manually write poster layouts or stuff entire page content into sections. Hard Rule: When a user wants to "modify an already generated HTML / remove QR codes / remove current header/footer / adapt to fixed header/footer", prefer using scripts/retrofit_share_shell.py. Do not use long prompts instructing the Agent to manually delete DOM nodes. By default, keep the old page's main hero area, only remove the QR code card and old footer within it, then directly insert the public header/footer at the body start/end. First, generate a local migrated version for verification, then use update:true to overwrite the same page_id.

1. Register Formula Package (scripts/formula_package.py register)

   • formulas: A set of "variable_name = expression" (reusing formulas verified during exploration in quant-buddy-skill).
   • reads: A manifest of external outputs, each declaring output (output name) + read_mode (read mode).
   • Success returns package_id + signature, automatically saved locally to output/formula_packages/<package_id>.json.
   • ⚠️ signature is returned in plain text only once during registration. Lost local credentials are irrecoverable (can use refresh to rotate).

2. Generate Dashboard (scripts/build_dashboard.py)

   • Write a spec: title + panels[], each panel renders a specific output as line/bar/table/number/text/raw.
   • If a page template is hit, first copy the spec.template.json or page.template.html from the template directory, then replace assets, dates, interpretation text, and optional modules.
   • Pages fetch data in real-time (see "Data Fetching: Real-Time Fetching" below), so mode is not needed in the spec.
   • The output is written to output/pages/<slug>.html by default; passing "upload": true can generate and publish in one step.

3. Publish / Manage (scripts/static_page.py)

   • upload: Upload HTML → Returns page_id + public url. Can include title (defaults to <title>) and description (page description, ≤1000 characters, used for listing/detail display).
   • update: Replace the content of a published page. URL / page_id remain unchanged (use when you want to supplement or adjust a page already shared; visitors see the new content on refresh, no new quota consumed). Can also modify title / description only (pass empty string "" for description to clear it; if omitted, the original value is kept).
   • download: Retrieve the HTML of a published page for editing (uses credentials to get url → direct OSS download, no server bandwidth consumed), then update to overwrite after edits.
   • list / revoke: List / revoke my pages (max 200 active pages, single page ≤ 2MB).
   • thumbnail: Set/replace a purely decorative cover image for a published page (direct upload PNG/JPG, ≤2MB). Used only for <img> preview on list/detail/template walls. Does not enter HTML, does not affect data fetching, and does not count towards the active page quota. Stored in OSS keyed by page_id, still valid when converted to a template. upload / update can include thumbnail_file; after HTML success, it automatically uploads the cover. If thumbnail upload fails, only a warning is returned; the HTML upload is not rolled back.
   • templates / template: Browse / Reuse public templates — templates lists templates (regular users see only published ones); template shows a specific template's details, provides download_url, connects directly to OSS to retrieve the HTML. After replacing with the user's own tickers, copy, and formula package credentials, upload it as their own page.
   • upload / update force-check for the public share shell before publishing. Missing public header/footer are automatically inserted and compiled. Theme color can only be overridden via theme / --qb-shell-* variables. The publish is rejected if placeholders or old QR codes remain.
   • Permissions / Responsibility: Pages are private by default. is_test users can cross-download / update / thumbnail other is_test users' pages. list can pass scope=test_all to see all test user pages (regular user pages always result in FORBIDDEN). Browsing and reusing public templates is open to all users (regular users can only read published ones). Submitting, modifying, or enabling/disabling templates is restricted to is_test users. Converting an existing page to a public template is a backend (growthX) action — this skill side only "reads + reuses" templates, no write operations.

Authentication relies solely on the api_key in config.json (query data fetching does not even need the api_key, just package_id + signature). This skill does not maintain sessions / task_id.

Data Fetching: Real-Time Fetching

The dashboard fetches data in real-time: HTML embeds package_id + signature. When a visitor opens the page, it immediately calls queryFormulaPackage to pull the latest data and render it — underlying data updates trigger automatic recalculation, so the page is always up-to-date when opened. This is precisely the design goal of formula packages. The spec does not need a mode field.

• Pages are "live": Data is not baked into the HTML; it's fetched in real-time at runtime. The build phase only fetches data once for quality checks (data health + copy consistency for single tickers), and does not inline it.
• Both prerequisites are met: ① The queryFormulaPackage endpoint has CORS enabled for the page domain pages.quantbuddy.cn (the current https endpoint allows *); ② signature is made public alongside the page (formula package queries inherently use signature as a capability token, designed to be embeddable.
• ⚠️ Protocol must match: The page is published on https://, and the endpoint in config.json must also be https://. Otherwise, the browser will block the data fetch due to mixed content. The current endpoint is https://www.quantbuddy.cn/skill.

Hard Rules

1. Use @file or Environment Variables for Chinese Parameters: Passing Chinese characters directly on the command line in Windows PowerShell can lead to truncation due to GBK encoding. Always use @params.json (UTF-8) or the environment variables FP_PARAMS/BD_PARAMS/SP_PARAMS for registering formulas and writing specs.
2. Formulas Must Be Verified Before Registration (Hard Prerequisite): Each set of formulas submitted for registration must first be run and confirmed to produce outputs using runMultiFormulaBatchStream in quant-buddy-skill (the formula syntax is consistent across both, so they can be verified as-is). Only allow register if the run is successful. Do not invent unverified expressions or adopt a "register first, fix errors later" approach — the server-side test reads during registration are only a fallback and do not substitute for this step.
3. Clean Up Verification Parameters: When calling runMultiFormulaBatchStream, user_query must reflect the current user's request and the current asset. If a task_id is passed, it must be a new one for this task. When copying from an example, do not only replace formulas but leave an outdated user_query like "Guizhou Moutai factsheet". This can pollute server-side audit logs and replays.
4. signature is a Credential: Do not print it in conversations visible to end-users. The dashboard will embed it in the public HTML for real-time data fetching. Confirm this is acceptable before publishing.
5. Clearly Explain Failures: When a script returns code != 0, relay to the user "which step failed (command name) + error summary". Do not end with blank output or raw logs.

Tool Overview

Parameter Convention: All script parameters are a single positional argument containing a JSON string (or @params.json / environment variable), e.g., list '{"scope":"test_all"}'. The command line also supports --scope test_all / --key=value intuitive syntax (for simple parameters only. Complex structures like formulas and specs still require @file or environment variables to avoid GBK truncation).

Script	Command	Purpose	Documentation
scripts/formula_package.py	register / query / list / revoke / refresh	Formula package: Register data fetching capability, stream data using package credentials.	tools/formula_package.md
scripts/build_dashboard.py	(Single command)	spec → live real-time dashboard HTML	tools/build_dashboard.md
scripts/compile_bespoke_page.py	(Single command)	【Shell processing script】 Bespoke template → self-contained HTML with public share shell / logo / qr-mini / data-kernel.	guides/share-shell.md
scripts/retrofit_share_shell.py	(Single command)	【Shell processing script】 Old HTML / published page → Remove old QR codes / old header / old footer, wrap in public share shell (assets/share-shell/), can update on the original link.	tools/retrofit_share_shell.md
scripts/static_page.py	upload / update / download / list / revoke / thumbnail / templates / template	Publish / replace / download / manage static pages, get public links (update replaces content without changing the link; download retrieves HTML for editing; thumbnail sets a display cover; templates/template browse and reuse public templates; is_test users can cross-user operations).	tools/static_page.md
scripts/verify_page.mjs	(Single command)	Pre/post-publish page verification: 1440px, 390px, 320px viewports, h1, placeholders, horizontal overflow, console core errors.	—
scripts/render_cover.py	(Called by build_dashboard)	Cover rasterization and composition fallback: capture_page_cover uses system Edge/Chrome headless to screenshot a "cover mode page" as a full-page PNG; composite covers (full-width bare image / branded poster) follow browser → pure Python (cairosvg/svglib) → SVG three-level fallback. Cross-platform, zero heavy dependencies, does not affect HTML publishing.	—
scripts/render_existing_page_thumbnail.py	(Single command)	Generate cover for published/public template HTML: download or read HTML → parse embedded formula package credentials → first fetch real outputs and temporarily replace QB.query → then use system Edge/Chrome to screenshot a 1200×675 PNG. Can include upload:true to directly set thumbnail_url.	tools/static_page.md
assets/data-kernel.js	(Frontend kernel, not a script)	A shared "fetch + clean + error handling" for hand-crafted bespoke pages. Inlined into the page's <script>.	guides/bespoke-page.md
assets/share-shell/	(Common Component)	Shared header, footer, refresh button, share poster popup, poster canvas, copy link, and copy/download behavior for all landing pages.	guides/share-shell.md
examples/valuation-financial-profile/page.template.html	(Offline Reference Template, not a script)	Single stock valuation check: valuation percentiles, financial trends, valuation balance attribution.	examples/valuation-financial-profile/README.md
examples/index-anomaly/page.template.html	(Offline Reference Template, not a script)	Constituent anomaly list: anomaly list, gain/loss distribution, index sparkline.	examples/index-anomaly/README.md
examples/commodity-daily/page.template.html	(Offline Reference Template, not a script)	Commodity daily report: long/short dominance, anomaly list, sector bars, sparklines.	examples/commodity-daily/README.md

Two Production Paths: Standard dashboards use build_dashboard (declarative fast path). For design pages requiring custom layouts/SVG, hand-code the HTML. The data layer uniformly calls assets/data-kernel.js (QB.query for fetching, QB.series/lastValue/topValues for unpacking and cleaning). Avoid each page copying fetch/unpack logic and falling into the same "fake 0/gap" pitfalls. See guides/bespoke-page.md. Before publishing, use scripts/verify_page.mjs <html_file> to check the page on desktop and 390px/320px mobile viewports, ensuring no leftover QB_SHARED_ / replace_with_signature / pkg_replace placeholders, presence of <h1>, no critical horizontal overflow, and no core data-fetching script errors.

Configuration

config.json: Fill in api_key (obtained from https://www.quantbuddy.cn/login), or set the environment variable QUANT_BUDDY_API_KEY. You can create config.local.json to override endpoint / api_key, etc. (this file is not committed to the repository). formula_package.py, build_dashboard.py, and static_page.py share the same endpoint.