quant-buddy-view · 量化看板发布

quant-buddy-view · Publicación de paneles cuantitativos

Convierte los indicadores explorados en quant-buddy-skill en un panel web público y compartible. Este skill no realiza consultas de mercado ni backtesting (esa es la función de quant-buddy-skill); solo se encarga de tres cosas:

1. Registrar paquetes de fórmulas (formula_package) — Registra un conjunto de fórmulas + los modos de lectura de sus resultados en el servidor, obteniendo un package_id + signature. Cuando los datos subyacentes se actualizan, el servidor recalcula automáticamente y la obtención de datos siempre devuelve el resultado más reciente.
2. Generar HTML del panel (build_dashboard) — Utiliza una especificación (spec) que describe «qué resultados mostrar y con qué gráficos/tablas», y la compila en un HTML de panel en vivo que obtiene datos en tiempo real (el esqueleto es autocontenido y los datos se obtienen al abrir la página).
3. Publicar y alojar (static_page) — Sube el HTML al almacenamiento de objetos, obteniendo un enlace público como https://pages.quantbuddy.cn/....

Cuándo usar este skill vs. quant-buddy-skill

• Exploración/consultas únicas ("¿Cuánto ha subido/bajado Maotai hoy?", "Ejecuta un backtest de cruce de medias móviles") → Usa quant-buddy-skill.
• Necesitas una página que puedas ver repetidamente, compartir con otros y que se actualice automáticamente → Después de explorar, cambia a quant-buddy-view.

Requisito previo: Instalar quant-buddy-skill primero

Este skill es autocontenido en tiempo de ejecución (el registro, generación y publicación solo dependen del api_key en config.json, no del código de quant-buddy-skill). Sin embargo, el flujo de uso normal tiene un requisito estricto: antes de registrar un paquete de fórmulas, cada conjunto de fórmulas debe ejecutarse primero en quant-buddy-skill mediante runMultiFormulaBatchStream para confirmar que genera datos (consulta la «Regla estricta previa al registro» a continuación). Por lo tanto, sin quant-buddy-skill instalado, no se puede completar correctamente la verificación de las fórmulas.

Si aún no has instalado quant-buddy-skill, instálalo en el siguiente orden de prioridad:

1. Prioridad: Instalación desde GitHub (npx skills) — quant-buddy-skill y este skill pertenecen al mismo repositorio de GitHub pseudo-longinus/quant-buddy-skills:

   # Nueva instalación (nunca instalado antes)
   npx skills add pseudo-longinus/quant-buddy-skills -g --all
   # Ya instalado, solo actualizar
   npx skills update pseudo-longinus/quant-buddy-skills -y
   # Verificar dónde está instalado / si está instalado:
   npx skills list -g --json
   

   En Windows, si hay errores de enlace simbólico / EPERM, añade --copy al final del comando y reintenta. La ruta de instalación suele ser ~/.agents/skills/quant-buddy-skill.

2. Plan B: Descargar el archivo zip y descomprimirlo manualmente (cuando no tengas node/npx o haya restricciones de red) — Descarga el zip oficial de quant-buddy-skill, descomprímelo y sobrescribe la carpeta quant-buddy-skill/ en el directorio de skills (descomprime primero en un directorio temporal; si contiene un subdirectorio quant-buddy-skill/, usa el interior; conserva el api_key del config.json existente). quant-buddy-skill incluye scripts/self_update.py, que admite --url / --zip-path + --sha512 + --version para verificar y descomprimir; úsalo preferentemente.

Estructura de carpetas: Coloca quant-buddy-skill y quant-buddy-view como hermanos al mismo nivel:

<directorio de skills>/
  quant-buddy-skill/      ← Exploración / verificación de fórmulas (runMultiFormulaBatchStream, confirmDataMulti)
  quant-buddy-view/       ← Este skill: registro de paquetes de fórmulas / generación de paneles / publicación

Esta estructura de hermanos es la recomendada: cuando formula_package import (migración de credenciales antiguas) no encuentra una ruta explícita, recurre a la ruta ../quant-buddy-skill como plan de último recurso.

3. Configuración: Configura tu propia api_key en quant-buddy-skill (independiente de la de este skill). Una vez instalado, puedes verificar las fórmulas allí y luego volver a este skill para register.

Migración para usuarios existentes: Los paquetes de fórmulas ya registrados en la versión anterior de quant-buddy-skill no necesitan volver a registrarse — usa python scripts/formula_package.py import ... para importar las credenciales de una sola vez a este skill y seguir usando el antiguo package_id para obtener datos (consulta tools/formula_package.md en la sección «Migrar credenciales desde el antiguo quant-buddy-skill»).

Selección de entrada (primero determinar el tipo)

Regla de enrutamiento del agente: Si el usuario menciona Mercado de plantillas / Plantillas oficiales / Plantillas públicas / Plantillas publicadas → Usa primero scripts/static_page.py templates / template para leer las plantillas públicas en línea; desde el download_url devuelto por template, descarga el HTML directamente desde OSS, reemplaza los activos, el texto y las credenciales del paquete de fórmulas, y luego usa upload para crear la página del usuario. Si el usuario solicita una forma de página específica pero no menciona plantillas públicas → Primero mira el directorio examples/ local (plan de respaldo fuera de línea para plantillas en línea y fuente de desarrollo de plantillas). Si el usuario quiere pasar de una necesidad a un enlace → Consulta workflows/. Si el usuario quiere una página personalizada compleja o migrar un HTML antiguo → Consulta guides/.

Tipo	Nombre	Entrada	Cuándo usarlo
Plantilla de página	Resumen de acción individual	examples/single-stock/	Página de perfil de un solo activo: resumen de lectura + tarjetas de números (precio reciente, cambio %, 20d, 60d, PE, PB, volumen) + gráfico principal de precios; debe comenzar desde spec.template.json
Plantilla de página	Examen de valoración de acción individual	examples/valuation-financial-profile/	Página de valoración y finanzas de un solo activo: niveles históricos de PE/PB/PCF, tendencias financieras, calidad del flujo de caja, atribución de cambios de valoración; incluye page.template.html
Plantilla de página	Tabla de anomalías de componentes de índice	examples/index-anomaly/	Monitoreo de anomalías en componentes de índice/cartera de acciones: tabla de anomalías + distribución de ganancias/pérdidas + tendencia del índice; incluye page.template.html, diseño oscuro, obtención de datos con data-kernel
Plantilla de página	Panel de selección de múltiples factores	examples/multi-factor-screener/	Cartera de acciones temática + puntuación de múltiples factores + ranking TopN + backtest/rankIC + velas + auditoría de fórmulas; roles fijos RANK / BACKTEST / KLINE_*, RANK se renderiza primero en la pantalla de inicio
Plantilla de página	Informe diario de materias primas largas/cortas	examples/commodity-daily/	Informe diario de futuros de materias primas: contradicción dominante larga/corta por sector + anomalías del día + sparkline de los principales productos; incluye page.template.html
Flujo general	Panel estándar en vivo	workflows/dashboard-end-to-end.md	Cuando el usuario quiere «hacer un panel/ enlace compartible» pero no especifica una plantilla fija
Guía de desarrollo	Página personalizada	guides/bespoke-page.md	Cuando build_dashboard no puede producir el HTML/CSS/SVG personalizado deseado, o para migrar un HTML existente
Herramienta de migración	Envolver página antigua con shell pública	tools/retrofit_share_shell.md	Cuando un HTML ya publicado/generado necesita eliminar códigos QR antiguos, encabezados antiguos y pies de página antiguos, manteniendo el mismo page_id para actualizar

Regla estricta: Cuando el usuario solicita «una página de perfil de una acción/índice en particular, perfil de acción individual, perfil de un solo activo», lee primero examples/single-stock/README.md, copia examples/single-stock/spec.template.json como punto de partida de la especificación, y conserva template: "single-stock". No escribas manualmente una especificación mínima antigua de «1 línea de precio + 4 tarjetas de números»; build_dashboard rechazará ese esqueleto antiguo. Regla estricta: Cuando el usuario pregunta «¿Esta acción es cara? / ¿Han mejorado los fundamentos? / Perfil de valoración y finanzas / Niveles históricos de PE/PB / Tendencias financieras / Calidad del flujo de caja» y solicita una página de destino o un enlace público, lee primero examples/valuation-financial-profile/README.md, copia examples/valuation-financial-profile/page.template.html como punto de partida, verifica y registra el conjunto de paquetes de fórmulas requerido por esa plantilla; no retrocedas a una página de tarjetas single-stock común. Regla estricta: Cuando el usuario solicita «anomalías de componentes de un índice / cartera de acciones, tabla de anomalías, ranking tipo tabla de clasificación» (por ejemplo, «¿Qué acciones del CSI 500 tuvieron anomalías hoy?», «Monitoreo de anomalías del CSI 300», «Ranking de ganancias/pérdidas del SSE 50»), lee primero examples/index-anomaly/README.md, copia examples/index-anomaly/page.template.html como punto de partida, reemplaza los marcadores de posición __INDEX_*__ e incluye data-kernel.js antes de publicar; no escribas manualmente un HTML elegante/general de colores claros que no corresponda. Regla estricta: Cuando el usuario solicita una página de trabajo de selección de acciones que incluya «cartera de acciones temática / acciones conceptuales / cartera sectorial + puntuación de múltiples factores / TopN / backtest / rankIC / velas / auditoría de fórmulas», lee primero examples/multi-factor-screener/README.md, copia examples/multi-factor-screener/page.template.html como punto de partida; los roles del paquete de fórmulas son fijos: RANK / BACKTEST / KLINE_*. RANK debe renderizarse primero en la pantalla de inicio, mientras que BACKTEST y KLINE_* permiten degradación parcial. Regla estricta: Al reutilizar una plantilla pública, el package_id + signature en el HTML de la plantilla pertenece al autor original de la plantilla; debes volver a verificar las fórmulas según el objetivo actual del usuario, registrar tu propio paquete de fórmulas y reemplazar las credenciales en la página antes de publicar. No uses las credenciales originales de la plantilla pública directamente como fuente de datos para la página del usuario. Regla estricta: El subtitle y el «resumen de lectura» de una página de perfil de un solo activo solo pueden usar los valores correspondientes a los resultados finales de la obtención de datos en tiempo real (outputs) durante la construcción de build_dashboard. Si el script devuelve «el texto no coincide con los resultados de la obtención en tiempo real», reescribe el texto según los facts devueltos antes de generar/subir; no uses resultados de consultas antiguas ni estimaciones manuales. Regla estricta: Todas las páginas de destino deben integrar los componentes públicos de assets/share-shell/. La plantilla solo es responsable del contenido principal y de getPosterData(); el encabezado, el pie de página, el botón de actualización, el modal de póster para compartir, el enlace de copia, la copia/descarga de PNG y el encabezado/pie de página fijos del póster son proporcionados por el shell público; no copies ni modifiques bloques de código QR antiguos, botones de actualización antiguos o modales para compartir antiguos dentro de una plantilla individual. Regla estricta: El póster para compartir es generado por el poster.js público por defecto, tomando una captura de pantalla del cuerpo de la página; mejor que sobre a que falte. La plantilla puede usar data-qb-poster-target para marcar el área de captura de pantalla principal. getPosterData() solo proporciona el título, el resumen y un candidato de respaldo estructurado. No confíes en que el agente escriba manualmente el diseño del póster ni metas todo el contenido de la página en sections. Regla estricta: Cuando el usuario solicite «modificar un HTML ya generado / eliminar el código QR / eliminar el encabezado y pie de página actuales / adaptar el encabezado y pie de página fijos», usa preferentemente scripts/retrofit_share_shell.py. No dependas de indicaciones largas para que el agente elimine manualmente el DOM; por defecto, conserva el área principal del cuerpo de la página antigua, solo elimina la tarjeta de código QR y el pie de página antiguo, y luego inserta directamente el encabezado y pie de página públicos en la parte superior/inferior de <body>. Primero genera una versión migrada localmente para verificarla, luego usa update:true para sobrescribir el mismo page_id.

1. Registrar paquete de fórmulas (scripts/formula_package.py register)

   • formulas: Un conjunto de "nombre_variable = expresión" (usando las fórmulas verificadas durante la exploración con quant-buddy-skill).
   • reads: Lista de resultados externos, cada uno declarando output (nombre del resultado) + read_mode (modo de lectura).
   • En caso de éxito, devuelve package_id + signature, y se guarda automáticamente en output/formula_packages/<package_id>.json.
   • ⚠️ signature solo se devuelve en texto plano una vez durante el registro. Si se pierde la credencial local, no se puede recuperar (se puede usar refresh para rotar).

2. Generar panel (scripts/build_dashboard.py)

   • Escribe una especificación: title + panels[], donde cada panel muestra un output como line/bar/table/number/text/raw.
   • Si coincide con una plantilla de página, primero copia spec.template.json o page.template.html del directorio de la plantilla, y luego reemplaza los activos, la fecha, el texto de interpretación y los módulos opcionales.
   • La página obtiene datos en tiempo real (consulta «Obtención de datos: En tiempo real» más abajo), por lo que no es necesario escribir mode en la especificación.
   • El resultado se escribe por defecto en output/pages/<slug>.html; pasa "upload": true para generar y publicar en un solo paso.

3. Publicar / Gestionar (scripts/static_page.py)

   • upload: Sube HTML → devuelve page_id + URL pública; se puede incluir title (por defecto toma el <title>) y description (descripción de la página, ≤1000 caracteres, para mostrar en listas/detalles).
   • update: Reemplaza el contenido de una página ya publicada, la URL / page_id no cambian (útil cuando quieres complementar/ajustar una página ya compartida; los visitantes ven el nuevo contenido al actualizar, sin consumir una nueva cuota). También puedes cambiar solo title / description (pasa una cadena vacía "" para borrar description, no lo pases para conservar el valor original).
   • download: Descarga el HTML de una página ya publicada para editarla (la autenticación obtiene la URL → descarga directa desde OSS, sin consumir ancho de banda del servidor), luego edítala y usa update para sobrescribir.
   • list / revoke: Listar / revocar mis páginas (límite de 200 páginas activas, cada página ≤ 2MB).
   • thumbnail: Establecer / reemplazar una imagen de portada puramente decorativa para una página ya publicada (sube PNG/JPG directamente, ≤2MB). Se usa solo para la vista previa <img> en listas/detalles/paredes de plantillas, no entra en el HTML, no afecta la obtención de datos, no consume cuota de páginas activas; se almacena en OSS con el nombre del page_id, sigue siendo válida después de convertirla en plantilla. upload / update pueden incluir thumbnail_file; después de que el HTML se suba correctamente, la portada se sube automáticamente; si la miniatura falla, solo devuelve una advertencia, no revierte el HTML.
   • templates / template: Navegar / Reutilizar plantillas públicas — templates lista las plantillas (los usuarios normales solo ven las publicadas), template muestra los detalles de una plantilla y obtiene el download_url, descarga el HTML directamente desde OSS, reemplázalo con tus propios activos/texto/paquete de fórmulas y luego usa upload para crear tu propia página.
   • Antes de upload / update, se verifica forzosamente el shell público compartido. Si faltan el encabezado o pie de página públicos, se insertan y compilan automáticamente. El color del tema solo se puede anular mediante theme / variables --qb-shell-*. Si aún hay marcadores de posición o códigos QR antiguos, se rechaza la publicación.
   • Permisos / Responsabilidades: Las páginas propias son visibles solo para el propietario por defecto. Los usuarios is_test pueden descargar/actualizar/establecer miniaturas de páginas de otros usuarios is_test, y list puede pasar scope=test_all para ver todas las páginas de usuarios de prueba (las páginas de usuarios normales siempre devuelven FORBIDDEN). La navegación y reutilización de plantillas públicas está abierta a todos (los usuarios normales solo ven las publicadas). El envío, modificación, activación/desactivación de plantillas solo lo pueden hacer usuarios is_test; la conversión de una página existente en una plantilla pública es una acción del backend (growthX) — este skill solo se encarga de «leer + reutilizar» plantillas, no realiza estas operaciones de escritura.

La autenticación solo depende del api_key en config.json (las consultas de obtención de datos ni siquiera necesitan api_key, solo package_id + signature). Este skill no mantiene sesiones / task_id.

Obtención de datos: En tiempo real

Los paneles obtienen datos en tiempo real: el HTML contiene package_id + signature incrustados. Cuando un visitante abre la página, se llama instantáneamente a queryFormulaPackage para obtener los datos más recientes y renderizarlos — cuando los datos subyacentes se actualizan, se recalculan automáticamente, la página muestra lo último al abrirse, este es el propósito del diseño de los paquetes de fórmulas. La especificación no necesita un campo mode.

• La página está "viva": Los datos no están incrustados en el HTML; se obtienen en tiempo real durante la ejecución. Durante la construcción, solo se obtienen los datos una vez para una verificación de calidad (salud de los datos + coherencia del texto para un solo activo), no se incrustan.
• Dos premisas (ambas cumplidas): ① El endpoint queryFormulaPackage tiene CORS habilitado para el dominio de la página pages.quantbuddy.cn (el endpoint https actual ya tiene * habilitado). ② signature se expone con la página (la consulta del paquete de fórmulas ya usa signature como token de capacidad y está diseñada para permitir su incrustación en la página).
• ⚠️ El protocolo debe coincidir: La página se publica en https://, y el endpoint en config.json también debe ser https://; de lo contrario, el navegador bloqueará la obtención de datos por contenido mixto. El endpoint actual ya es https://www.quantbuddy.cn/skill.

Reglas estrictas

1. Los parámetros en chino deben ir a través de @file o variables de entorno: En Windows PowerShell, pasar chino directamente en la línea de comandos puede truncarse con GBK. Al registrar fórmulas o escribir especificaciones, usa siempre @params.json (UTF-8) o las variables de entorno FP_PARAMS/BD_PARAMS/SP_PARAMS.
2. Las fórmulas deben verificarse antes de registrarse (requisito estricto): Cada conjunto de fórmulas a registrar debe ejecutarse primero en quant-buddy-skill usando runMultiFormulaBatchStream y confirmar que genera datos (la sintaxis de las fórmulas es la misma en ambos lados, se pueden verificar tal cual). Solo después de ejecutarse con éxito se permite register. No inventes expresiones no verificadas ni pienses «registrar primero, ya se verá» — la lectura de prueba en el servidor durante el registro es solo un plan de respaldo, no sustituye este paso.
3. Los parámetros de verificación también deben cambiarse por completo: Al llamar a runMultiFormulaBatchStream, user_query debe reflejar la solicitud actual del usuario y el activo actual; si se pasa task_id, debe ser una nueva tarea para esta ocasión. Al copiar un ejemplo, no te limites a reemplazar formulas dejando un user_query antiguo como "Ficha técnica de Guizhou Maotai", de lo contrario, la auditoría y la reproducción del backend se contaminarán.
4. La signature es una credencial: No la imprimas en el diálogo dirigido al usuario final; el panel la escribirá en el HTML público para la obtención de datos en tiempo real; confirma que sea aceptable antes de publicar.
5. Explica los fallos claramente: Cuando el script devuelva code != 0, comunica al usuario «en qué paso falló (nombre del comando) + resumen del error», no termines con un espacio en blanco o solo registros.

Resumen de herramientas

Convención de parámetros: Todos los parámetros de los scripts son un solo argumento posicional de cadena JSON (o @params.json / variable de entorno), por ejemplo, list '{"scope":"test_all"}'. La línea de comandos también admite la escritura intuitiva --scope test_all / --key=value (solo para parámetros simples; las estructuras complejas como fórmulas, especificaciones, etc., aún deben ir a través de @file/variables de entorno para evitar el truncamiento GBK).

Script	Comando	Función	Documentación
scripts/formula_package.py	register / query / list / revoke / refresh	Paquete de fórmulas: registrar capacidad de obtención de datos, obtener datos en streaming usando las credenciales del paquete	tools/formula_package.md
scripts/build_dashboard.py	(un solo comando)	Especificación → HTML de panel en vivo en tiempo real	tools/build_dashboard.md
scripts/compile_bespoke_page.py	(un solo comando)	Script de procesamiento de shell Plantilla a medida → HTML autocontenido con shell público compartido / logo / qr-mini / data-kernel incrustados	guides/share-shell.md
scripts/retrofit_share_shell.py	(un solo comando)	Script de procesamiento de shell HTML antiguo / páginas ya publicadas → Eliminar códigos QR antiguos / encabezados antiguos / pies de página antiguos, envolver con el shell público (assets/share-shell/), se puede actualizar con el mismo enlace	tools/retrofit_share_shell.md
scripts/static_page.py	upload / update / download / list / revoke / thumbnail / templates / template	Publicar/reemplazar/descargar/gestionar páginas estáticas, obtener enlace público (update reemplaza contenido sin cambiar enlace; download descarga HTML para editarlo; thumbnail establece portada decorativa; templates/template navegan y reutilizan plantillas públicas; is_test puede hacer operaciones entre usuarios)	tools/static_page.md
scripts/verify_page.mjs	(un solo comando)	Verificación de página antes/después de publicar: viewports de 1440px, 390px, 320px, h1, marcadores de posición, desbordamiento horizontal, errores centrales de consola	—
scripts/render_cover.py	(llamado por build_dashboard)	Rasterización de portada y composición de respaldo: capture_page_cover usa el Edge/Chrome del sistema sin interfaz para capturar la «página en modo portada» como PNG de página completa; la composición de portada (imagen desnuda de página completa/póster de marca) pasa por navegador → Python puro (cairosvg/svglib) → tres capas de respaldo SVG. Multiplataforma, sin dependencias estrictas, no afecta la publicación del HTML	—
scripts/render_existing_page_thumbnail.py	(un solo comando)	Generar miniatura para HTML ya publicado/de plantilla pública: descargar o leer HTML → analizar credenciales del paquete de fórmulas incrustado → obtener primero los outputs reales y reemplazar temporalmente QB.query → luego usar el Edge/Chrome del sistema para capturar un PNG de 1200×675; se puede usar upload:true para establecer directamente el thumbnail_url	tools/static_page.md
assets/data-kernel.js	(kernel de frontend, no es un script)	Archivo compartido para páginas a medida hecho a mano: «obtención de datos + limpieza + tolerancia a fallos». Incrustado en la etiqueta <script> de la página	guides/bespoke-page.md
assets/share-shell/	(componente público)	Encabezado común, pie de página, botón de actualización, modal de póster para compartir, lienzo de póster, comportamiento de copiar enlace y copiar/descargar para todas las páginas de destino	guides/share-shell.md
examples/valuation-financial-profile/page.template.html	(plantilla de referencia fuera de línea, no es un script)	Examen de valoración de acción individual: niveles de valoración, tendencias financieras, atribución de balanza de valoración	examples/valuation-financial-profile/README.md
examples/index-anomaly/page.template.html	(plantilla de referencia fuera de línea, no es un script)	Tabla de anomalías de componentes de índice: tabla de anomalías, distribución de ganancias/pérdidas, sparkline del índice	examples/index-anomaly/README.md
examples/commodity-daily/page.template.html	(plantilla de referencia fuera de línea, no es un script)	Informe diario de materias primas largas/cortas: largas/cortas dominantes, tabla de anomalías, barras sectoriales, sparklines	examples/commodity-daily/README.md

Dos rutas de producción: Los paneles estándar usan build_dashboard (ruta rápida declarativa). Para páginas de diseño personalizado con SVG, crea el HTML a mano; la capa de datos unifica el uso de assets/data-kernel.js (QB.query para obtener datos, QB.series/lastValue/topValues para desempaquetar y limpiar). No copies fetch/desempaquetado en cada página ni caigas en los errores de "falso 0/huecos". Consulta guides/bespoke-page.md. Antes de publicar, usa scripts/verify_page.mjs <archivo_html> para verificar la vista de escritorio y las vistas móviles de 390px/320px, asegurándote de que no queden QB_SHARED_ / replace_with_signature / pkg_replace, que exista un <h1>, que no haya desbordamiento horizontal crítico ni errores centrales en el script de obtención de datos.

Configuración

config.json: Introduce api_key (obtenido de https://www.quantbuddy.cn/login), o configura la variable de entorno QUANT_BUDDY_API_KEY. Puedes crear config.local.json para sobrescribir endpoint / api_key, etc. (sin incluirlo en el repositorio). formula_package.py, build_dashboard.py y static_page.py comparten el mismo endpoint.