O que x2strategy faz?

Qualquer entrada relacionada a finanças → Especificação de estratégia → Código executável → Backtest → Diagnóstico.

Capacidades

Capacidade	O que faz	Aprofundamento
paper2spec	Qualquer documento (PDF/MD/DOCX/TXT) → especificação estruturada de estratégia	references/paper2spec.md
spec2code	Especificação de estratégia → código Backtrader → validar → backtest → diagnóstico	references/spec2code.md

Formato de entrada detectado automaticamente pela extensão:

Formato	Extensão	Observações
PDF (artigos)	`.pdf`	PyMuPDF → Modo A (direto) ou Modo B (FAISS)
Markdown (rascunhos)	`.md`, `.markdown`	Leitura direta de texto
DOCX (relatórios)	`.docx`	python-docx (requer `uv sync --extra docx`)
Texto simples	`.txt`	Leitura direta

Princípios de Interação

Você é o executor. O usuário é o solicitante.

Execute ferramentas silenciosamente, apresente resultados e insights em linguagem natural.
Nunca mostre comandos CLI (uv run python scripts/...) a menos que o usuário peça.
Ofereça próximas ações de forma conversacional: "Gostaria que eu implementasse a segunda estratégia também?"

Ao relatar resultados, foque no que você encontrou, não em como:

❌ Ruim: "Executei `uv run python scripts/analyze.py paper.pdf` e obtive 3 estratégias."
✅ Bom: "Este artigo contém 3 estratégias independentes: [1] método de distância mínima, [2] estacionariedade ADF e [3] cointegração de Johansen. Qual delas devo implementar?"

Use ferramentas interativas agressivamente. Quando sua plataforma fornecer ferramentas de perguntas interativas — vscode_askQuestions (VS Code Copilot), AskUserQuestion (Claude Code) ou equivalente — use-as para TODAS as escolhas voltadas ao usuário. Ferramentas interativas apresentam opções clicáveis, o que é mais rápido e menos propenso a erros do que pedir ao usuário para digitar.

Aplique ferramentas interativas para:

Escolhas de Configuração Inicial (caminho do workspace, provedor de API, chave)
Confirmação de entrada (prosseguir / adicionar esclarecimento / ajustar configurações)
Pontos de verificação de revisão e aprovação de implementação
Resolução de needs_human_review após extração ou reparo
Seleção de resultados de pesquisa (escolher artigos de uma lista numerada)
Qualquer cenário onde o usuário escolhe entre opções

Se nenhuma ferramenta interativa estiver disponível, recorra a menus de texto numerados.

Protocolo de Marcadores de Progresso

Execute ferramentas silenciosamente, mas torne pipelines longos rastreáveis. Ao trabalhar no fluxo de oito etapas, prefixe linhas de status com um dos três marcadores estruturados para que o usuário (e qualquer analisador externo) possa acompanhar o progresso da fase sem ler a saída bruta do comando. Os marcadores carregam a disciplina; o texto ao redor permanece em linguagem natural.

Marcador	Quando emitir	Formato
`[PROGRESS]`	Entrando ou finalizando uma etapa do fluxo	`[PROGRESS] <etapa> — <status em uma linha>`
`[ARTIFACT]`	Um arquivo concreto foi escrito	`[ARTIFACT] <caminho relativo ao workspace> — <o que é>`
`[ERROR]`	Uma etapa falhou ou uma verificação não passou	`[ERROR] <etapa> — <o que falhou> — <próxima ação>`

Regras:

Um marcador por linha, no início da linha, depois linguagem simples.
Cada [ARTIFACT] deve nomear um caminho concreto relativo ao workspace que foi efetivamente escrito (isso satisfaz o contrato de Caminhos de Saída abaixo).
[ERROR] deve sempre ser seguido pelo que você fará em seguida (tentar novamente uma vez, parar e relatar, perguntar ao usuário) — nunca uma falha nua.
Marcadores complementam o relato em linguagem natural; eles não o substituem. Ainda assim, explique o que você encontrou, não como executou. Nunca mostre o comando CLI.

Exemplo:

[PROGRESS] paper2spec/extract — extraindo especificações de estratégia de content.json
[ARTIFACT] library/upsa/spec.json — 1 estratégia, 4 indicadores, 3 etapas lógicas
[PROGRESS] revisão HITL — 1 item needs_human_review em aberto, perguntando sobre resolução

Disciplina de Iteração e Repetição

Geração e reparo devem ser limitados. Traduza o limite máximo de turnos do backend (--max-turns) em disciplina do agente:

Gere uma vez, depois no máximo uma rodada de reparo com teste de fumaça. Escreva o código, valide, execute. Se falhar, aplique uma rodada de correção direcionada (veja o fluxo de triagem em references/spec2code.md) e execute novamente.
Se ainda falhar após essa rodada de reparo, pare e relate. Emita uma linha [ERROR], resuma o que falhou e a causa raiz mais provável, e pergunte ao usuário como proceder. Não continue aplicando correções incrementais.
Uma única categoria de erro em tempo de execução recebe no máximo 3 tentativas de correção. Se a mesma classe de erro persistir, a lógica da estratégia provavelmente precisa de uma abordagem fundamentalmente diferente — diga isso em vez de ajustar ainda mais.
Nunca faça loop silenciosamente. Cada repetição deve ser visível por meio de um marcador [PROGRESS] ou [ERROR] para que o usuário veja o limite funcionando.

Contrato de Primeira Resposta

Para qualquer solicitação de paper2code, pesquisa-para-código ou "use esta skill", a primeira resposta não deve prometer implementação imediata. Primeiro identifique as entradas visíveis, depois use um diálogo interativo para confirmar o status da configuração, arquivos de entrada, instruções/esclarecimentos adicionais e o escopo do fluxo de trabalho pretendido. Só prossiga após essa confirmação.

Configuração Inicial

No primeiro uso, percorra três etapas. Se uma etapa já estiver configurada, relate o valor detectado e peça ao usuário para confirmá-lo ou alterá-lo. Sempre confirme o escopo da tarefa antes da extração ou implementação. Persista todas as escolhas em .env (ignorado pelo git) para estabilidade da sessão.

Etapa 1 — Localização do Workspace

Apresente a escolha por meio de ferramenta interativa:

./library/ (padrão, recomendado)
Caminho personalizado

Escreva PAPER2SPEC_LIBRARY_PATH=/caminho/absoluto para .env. Escaneie o diretório em busca de metadata.json existente para detectar análises anteriores.

Etapa 2 — Chave de API LLM

Verifique o ambiente por DEEPSEEK_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY ou ANTHROPIC_API_KEY. Se nenhum for encontrado, apresente via ferramenta interativa:

Uma chave de API LLM é necessária para extração de estratégia e geração de código. Opções recomendadas:
  1. DeepSeek (melhor custo-benefício, cerca de ¥0.7 por artigo) → https://platform.deepseek.com
  2. OpenRouter (uma chave para acesso a vários modelos) → https://openrouter.ai/keys
Por favor, forneça sua chave de API e informe a qual provedor ela pertence.

Após recebida, escreva a chave + modelo correspondente no .env, depois verifique: uv run python -c "from paper2spec.llm import chat; print(chat('Say OK'))".

Veja references/skill-internals.md para exemplos de formato .env por provedor.

Etapa 3 — Ambiente Python

cd <caminho-da-skill>
uv sync --all-extras    # Recomendado: instala tudo

Se uv não estiver disponível: pip install -e ".[codegen,agent,dev]". Sempre use uv run para executar scripts (ativa automaticamente o venv correto).

Veja references/skill-internals.md para opções de instalação seletiva e alternativas sem uv.

Conclusão

Após configurado, confirme naturalmente com exemplos:

✅ Configuração concluída. Agora você pode me pedir tarefas diretamente, por exemplo:

  • "Analise este artigo" + anexe um arquivo PDF
  • "Pesquise artigos sobre momentum trading"
  • "Implemente esta estratégia com base neste artigo" + forneça o caminho do arquivo
  • "Escrevi um rascunho de estratégia em Markdown; extraia a especificação e gere o código"
  • "Compare as diferenças de estratégia entre estes dois artigos"

Apenas me diga o que deseja fazer, e eu cuido do resto.

Fluxo de Trabalho Único

Use um fluxo de trabalho para todas as tarefas. Não escolha entre roteadores concorrentes.

Configuração — verifique .env, caminho da biblioteca, chave de API se necessário, ambiente Python e escopo selecionado pelo usuário.
Confirmação de entrada — identifique os arquivos de artigo/especificação/dados/instruções ou resultados de pesquisa; pergunte se deseja adicionar esclarecimentos, restrições, preferências de plano selecionado, problemas conhecidos ou arquivos de referência.
paper2spec: PDF/texto para conteúdo — analise o documento selecionado em artefatos de conteúdo fundamentados.
paper2spec: extrair — extraia especificações/planos de estratégia candidatos do conteúdo mais as instruções do usuário.
paper2spec: reparar/revisar — leia references/extraction_quality.md, recupere as armadilhas do operador relevantes quando fórmulas de alto risco estiverem presentes e repare apenas o plano/especificação selecionado com evidências fundamentadas.
Revisão HITL — após o reparo, sempre inspecione needs_human_review. Se algum item existir, apresente-o através do diálogo interativo e não continue até que seja respondido ou explicitamente aceito. Se nenhum existir, ainda assim relate que a revisão não encontrou itens em aberto e peça aprovação para implementação.
spec2code — após a aprovação HITL, confirme o alvo da implementação e gere o código para esse alvo.
Validação/backtest/diagnóstico — valide o código gerado, execute verificações/backtests disponíveis, compare com saídas esperadas ou de referência, resuma discrepâncias e pergunte o que fazer a seguir.

Sem desvios: nunca encadeie silenciosamente extração → reparo → implementação. Artigos, instruções, arquivos de dados, especificações existentes ou saídas de referência fornecidos pelo usuário são evidências, não permissão para pular revisão ou HITL.

Quando logs anteriores do Copilot, VS Code ou agente forem mencionados, verifique se o caminho referenciado existe e contém os arquivos necessários antes de usá-los. Se o caminho estiver ausente, vazio ou incompleto, regenere os artefatos necessários a partir do artigo/instruções/dados originais em vez de confiar no resumo do log.

Caminhos de Saída

Os artefatos gerados por padrão vão para PAPER2SPEC_LIBRARY_PATH/<slug>/, onde <slug> é o slug do artigo ou tarefa confirmado com o usuário. Se um caminho de saída personalizado for solicitado, confirme-o antes de escrever os arquivos.

Caminhos de artefato esperados:

content.json e content.md da análise paper2spec
spec.json e spec.md da extração e reparo
operator_pitfall_context.md quando a recuperação de armadilhas for usada
strategy.py, strategy_1.py ou o nome de arquivo de implementação confirmado pelo usuário do spec2code
data/ para quaisquer dados usados pelo código de estratégia gerado
results/backtest_output.txt, results/metrics.json e results/diagnosis_report.md da validação/backtest/diagnóstico
results/portfolio_vs_assets.csv e results/portfolio_vs_assets.png comparando o valor da carteira da estratégia contra curvas de buy-and-hold com o mesmo capital para cada ação/ETF/ativo utilizado em uma imagem; as curvas dos ativos devem usar cores distinguíveis e rótulos/entradas de legenda de símbolo, e SPY e a carteira devem estar em negrito (comparando curvas de carteira com os mesmos parâmetros em 0%, 0.01% e 0.05% de comissão em uma imagem)
results/key_pred/ com um CSV e um PNG por fator observável chave usado pela estratégia

Cada atualização de status após a geração de arquivos deve nomear o caminho relativo ao workspace concreto que foi escrito.

Métricas do Spec2Code

Para cada estratégia executável, spec2code deve calcular e relatar pelo menos: índice de Sharpe, drawdown máximo, retorno total e valor do retorno/valor final da carteira. Se uma estratégia não for executável como uma estratégia conectada a um corretor, relate o motivo e ainda assim calcule as métricas que são significativas para o contrato de pesquisa/backtest confirmado.

O código gerado pelo Spec2Code deve armazenar em cache todos os dados de rede localmente, salvar diagnósticos visuais seguros para headless, plotar todos os preços dos ativos usados juntos, comparar o valor da conta da estratégia contra curvas de buy-and-hold com o mesmo capital para todos os ativos usados, incluir uma comparação de curvas de capital com comissão de 0% / 0.01% / 0.05% para estratégias de trading, e incluir um gráfico combinado de carteira vs. ativos onde todas as três curvas de carteira com comissão são plotadas com todas as curvas de buy-and-hold dos ativos.

Para estratégias de ações dos EUA, SPY deve ser incluído e destacado como a linha de base do mercado em gráficos de ativos e carteira vs. ativos. Veja references/spec2code.md e references/data_sources.md para o cache de dados necessário e contrato de visualização.

Fluxo do Pipeline do Agente

1. Configuração: confirmar ambiente, caminho da biblioteca, chaves se necessário e escopo da tarefa
2. Confirmar entradas: artigo/especificação/dados/instruções/resultado da pesquisa + esclarecimentos
3. paper2spec: analisar PDF/texto/doc para artefatos de conteúdo
4. paper2spec: extrair especificações/planos candidatos
5. paper2spec: selecionar plano/especificação alvo e reparar com extraction_quality + armadilhas correspondentes
6. HITL: inspecionar needs_human_review e resolver através de diálogo interativo
7. spec2code: confirmar contrato de saída, gerar código, validar, executar verificações/backtest
8. Diagnosticar resultados e perguntar próxima ação

Para padrões de geração de código: references/spec2code.md Para padrões Backtrader: references/backtrader_patterns.md

Ferramentas Internas

Apenas para agente. Execute silenciosamente; apresente resultados em linguagem natural.

# Documento → especificação
uv run python scripts/analyze.py <arquivo> -o library/<slug>/

# paper2spec passo a passo
uv run python scripts/parse.py <arquivo> -o content.json
uv run python scripts/extract.py content.json -o spec.json

# Contexto de armadilhas do operador correspondente para reparo/revisão
uv run python scripts/operator_pitfalls.py spec.json -o operator_pitfall_context.md

# Validar código gerado
uv run python scripts/validate_strategy.py library/<slug>/strategy_1.py

# Executar backtest
uv run python library/<slug>/strategy_1.py

# Pesquisar artigos
uv run python scripts/search.py "<consulta>" -n 5

Para flags completas, formatos de saída e gerenciamento de biblioteca: references/skill-internals.md

Configuração

Variável	Padrão	Propósito
`PAPER2SPEC_LIBRARY_PATH`	`./library`	Raiz de saída
`PAPER2SPEC_MODEL`	`openai/gpt-4o-mini`	LLM padrão (suportado pelo litellm)
`DEEPSEEK_API_KEY`	—	DeepSeek (recomendado)
`OPENROUTER_API_KEY`	—	OpenRouter (múltiplos modelos)
`OPENAI_API_KEY`	—	OpenAI direto
`PAPER2SPEC_ARXIV_MIN_INTERVAL`	`3.0`	Segundos entre solicitações ao arXiv
`PAPER2SPEC_SEARCH_MAX_RETRIES`	`3`	Repetir em HTTP 429/5xx

Qualquer modelo suportado pelo litellm funciona. A flag --model em qualquer script substitui PAPER2SPEC_MODEL.

ALAGENT-HKU/x2strategy

O que é x2strategy?

Perguntar na sua IA favorita

Documentação