gaaiyun/joinquant-skill

JoinQuant Skill

Gere código de estratégia quantitativa que roda na plataforma JoinQuant sem modificações.

Quando Usar Esta Skill

Sim:

• Backtest de ações / paper trading / live trading no JoinQuant (聚宽)
• Estratégias de rotação de ETF, seleção multifatorial, momentum, reversão à média
• Estratégias de futuros (期货) no JoinQuant
• Estratégias de margem de negociação (融资融券)
• Revisão de código de estratégia / lint para detectar APIs alucinadas e violações de future function
• Traduzir uma ideia de estratégia em chamadas da API JoinQuant

Não:

• Análise de dados local sem JoinQuant (use jqdatasdk diretamente, ou pandas/numpy)
• Backtest de estratégias em outras plataformas (vectorbt, backtrader, vn.py — use essas skills)
• Treinamento puro de modelos de machine learning (nenhuma API específica do JoinQuant necessária)
• Live trading em APIs de corretoras que não sejam a negociação simulada do JoinQuant (CTP, Interactive Brokers, etc. precisam de skills diferentes)

Modo Padrão

A maioria das solicitações dos usuários se enquadra em um dos três padrões. Detecte o padrão primeiro e então direcione:

Padrão	Gatilho	Ação
Código rápido	"帮我写一个 X 策略" / "用聚宽实现 Y"	Escolher template, preencher partes específicas do usuário, retornar código pronto para colar
Pergunta sobre API	"聚宽里 get_price 的 fq 参数是什么意思" / "set_option 都有哪些选项"	Carregar references/XX-*.md correspondente e responder com base nele
Revisão de código	"帮我审一下我这段聚宽代码" / colar código existente	Executar strategy_lint.py mentalmente (ou realmente chamá-lo), apontar APIs alucinadas e proteções ausentes

Divulgação Progressiva: 14 Categorias de API

NÃO carregue todas as referências de uma vez (294KB total, consumiria contexto). Combine o padrão da solicitação do usuário e carregue apenas o arquivo de categoria relevante:

Categoria	Arquivo de referência	Acionado por palavras-chave
Configuração da estratégia	references/01-strategy-setup.md	initialize, set_benchmark, set_option, set_order_cost, set_slippage, run_daily, run_weekly, run_monthly
Obtenção de dados	references/02-data-getters.md	get_price, attribute_history, history, get_current_data, get_fundamentals, get_money_flow, get_concept, get_industry
Biblioteca de fatores jqlib	references/03-jqlib.md	alpha101, alpha191, technical_analysis, jqfactor
Processamento de dados	references/04-data-processing.md	get_factor_values, calc_factor_history, neutralize, winsorize, standardlize
Otimização de portfólio	references/05-portfolio-optimization.md	optimizer, max_sharpe, min_variance, target_return, mean_variance
Funções de negociação	references/06-trading.md	order, order_value, order_target, order_target_value, cancel_order, get_open_orders
Objetos	references/07-objects.md	Order, Position, Portfolio, OrderCost, OrderStyle, MarketOrderStyle, LimitOrderStyle
Outras funções	references/08-misc-functions.md	record, log, write_file, send_message
Múltiplos portfólios	references/09-multi-portfolio.md	set_subportfolios, SubPortfolioConfig, transfer_cash
Tick	references/10-tick-strategy.md	tick, get_ticks, every_tick
Margem de negociação	references/11-margin-trading.md	margincash_open, margincash_close, marginsec_open, marginsec_close, set_margin_rate
Futuros	references/12-futures.md	get_dominant_future, futures, set_future_commission
Análise de atribuição	references/13-attribution-analysis.md	brinson, factor analysis, attribution
Mecanismo do motor	references/14-strategy-engine.md	撮合, 复权, 滑点, 税费, 风险指标, alpha, beta, sharpe, max drawdown

Se o usuário mencionar um nome de função que não está em nenhuma lista de palavras-chave, use scripts/api_search.py <palavra-chave> para encontrá-lo em todas as referências.

Templates

5 templates prontos para produção em templates/:

Template	Quando usar
01-basic-single-stock.py	Usuários iniciantes, ação única, crossover de média móvel simples. O "hello world" do JoinQuant.
02-multi-factor.py	Seleção multifatorial (PE / valor de mercado / momentum), rebalanceamento mensal. A estrutura de estratégia "real" mais comum.
03-etf-rotation.py	Rotação de ETF por ranking de momentum. Popular entre investidores de varejo.
04-momentum-stock.py	Momentum transversal no pool de ações, rebalanceamento semanal.
05-mean-reversion.py	Reversão à média de Bollinger / RSI. Sensível à volatilidade.

Ao gerar código, comece a partir de um template, modifique, não escreva do zero. Motivos:

1. Os templates já incluem o código padrão (set_benchmark, set_option, set_order_cost, set_slippage)
2. Os templates têm temporização correta (run_daily / run_weekly com argumento de tempo adequado)
3. Os templates evitam armadilhas de future function (divisão baseada em contagem em vez de data)

Ferramenta de Lint

Antes de retornar o código gerado ao usuário, execute mentalmente (ou realmente) strategy_lint.py:

python scripts/strategy_lint.py <estrategia_do_usuario.py>

Verificações críticas:

• ❌ Chamadas de API alucinadas (ex.: jqdata.get_stock_data() não existe)
• ❌ Future function: uso de get_price ou attribute_history não baseado em contagem com datas futuras fixas
• ❌ Ausência de set_option('use_real_price', True) (obrigatório para backtest preciso)
• ❌ Ausência de set_order_cost(...) e set_slippage(...)
• ❌ Ordem colocada em before_trading_start / after_trading_end (proibido, será rejeitado)
• ❌ Uso de APIs obsoletas (update_universe etc.)
• ⚠️ Recomendar variáveis globais g. para estado entre barras em vez de globais de módulo
• ⚠️ Recomendar dimensionamento consciente de cluster para ativos de alta correlação

Coisas Que Não Podem Ser Perdidas na Geração

Ao aconselhar sobre uma estratégia, nunca perca:

• Sempre defina use_real_price=True. O preço pré-ajustado tradicional tem viés de future function. Isso é inegociável.
• set_order_cost e set_slippage são obrigatórios. Sem eles, o backtest não é realista e enganará o usuário.
• O argumento de tempo do run_daily é importante. 'open' executa às 09:30, 'every_bar' executa a cada barra (minuto ou diário). A escolha errada causa temporização de execução incorreta.
• g. é o único estado global seguro. Globais de nível de módulo podem vazar entre execuções em alguns ambientes JoinQuant.
• order_value > order para gerenciamento de capital. Calcular o número de ações manualmente é propenso a erros com desdobramentos.
• order_target_value para rebalanceamento, nunca calcule "valor atual - valor alvo" você mesmo.
• Não faça pip install nada dentro do JoinQuant. A plataforma é isolada (sandbox); apenas suas bibliotecas pré-instaladas funcionam.

Fluxo de Trabalho

Uma sessão típica de estratégia de ponta a ponta:

1. Usuário descreve a ideia em linguagem natural
2. IA: escolher template correspondente (ex.: 03-etf-rotation.py)
3. IA: fazer 2-3 perguntas esclarecedoras:
   - Escopo do pool de ativos (componentes do índice / lista personalizada)
   - Frequência de rebalanceamento (diária / semanal / mensal)
   - Controle de risco (stop loss / limite de posição / neutralidade setorial)
4. IA: gerar código de estratégia modificando o template
5. IA: executar lint mental (ou real) — corrigir problemas
6. Usuário: colar no editor online JoinQuant, clicar em 编译运行
7. Se houver erros: recarregar references/XX-*.md relevantes, corrigir
8. Usuário: revisar curva de backtest, iterar

Para estratégias de alto risco (live trading), adicionalmente:

• Consultar references/14-strategy-engine.md para slippage, comissão, métricas de risco
• Consultar references/11-margin-trading.md se envolver alavancagem
• Discutir explicitamente o risco do modelo (overfitting, mudança de regime, realismo dos custos de transação)

Arquivos

Arquivo	Função
README.md	Introdução do projeto
WORKFLOW.md	Desenvolvimento de estratégia de ponta a ponta (✅ completo)
INSTALL_CN.md	Guia de instalação em chinês (✅ completo)
api文档/api.txt	Documentos originais da API de 294KB (backup bruto)
references/01-14-*.md	14 arquivos de categoria de divulgação progressiva (✅ todos completos)
templates/01-05-*.py	5 templates de produção (✅ completos)
scripts/strategy_lint.py	Ferramenta de lint — híbrido de lista branca/negra (✅ operacional)
scripts/strategy_scaffold.py	Gerar esqueleto a partir de descrição (✅ operacional)
scripts/api_search.py	Pesquisar API por palavra-chave (✅ operacional)
examples/case-mean-reversion/	Caso de ponta a ponta: reversão à média RSI (✅)
examples/case-etf-rotation/	Caso de ponta a ponta: rotação mensal de ETF (✅)
examples/bad-strategy-for-lint-test.py	Amostra de teste negativo para regressão de lint (✅)
factors/	(v2) Biblioteca de fatores estilo Barra, 7 categorias
factor_lab/	(v2) Análise de fator único IC / agrupamento / decaimento
research_importer/	(v2) PDF de pesquisa de corretora → código JoinQuant
jqskill_mcp/	(v2) Servidor MCP expondo todas as capacidades da skill
tests/	pytest (50+ testes passando após v2)

Esta skill está na versão 0.5.0 a partir de 2026-04-19. Todas as 14 referências + 5 templates + 3 scripts + 13 testes + WORKFLOW + 2 exemplos completos.