feat: initial commit - Jhonny Editor
- Adicionado estrutura completa do projeto - Configurado MCP server para Premiere Pro - Adicionado documentação e skills - Configurado Gitignore para o projeto
This commit is contained in:
João Henrique
@@ -0,0 +1,366 @@
|
||||
# Plano de Desenvolvimento — Primeira Etapa
|
||||
|
||||
## Scanner e leitura da timeline via MCP
|
||||
|
||||
## Status
|
||||
|
||||
Plano de desenvolvimento da primeira etapa. Este documento organiza a implementação futura; não autoriza a criação imediata de código sem que cada fase esteja preparada e validada.
|
||||
|
||||
## Objetivo
|
||||
|
||||
Construir o primeiro fluxo funcional do sistema capaz de ler a timeline ativa do Premiere por meio do MCP e transformá-la em uma representação interna confiável.
|
||||
|
||||
Ao final desta etapa, o sistema deverá conseguir:
|
||||
|
||||
1. comunicar-se com o MCP;
|
||||
2. verificar a disponibilidade do Premiere;
|
||||
3. ler a sequência ativa, faixas e clipes;
|
||||
4. converter respostas externas em objetos do domínio;
|
||||
5. validar dados incompletos ou inválidos;
|
||||
6. executar a descoberta por meio do `Scanner`;
|
||||
7. registrar erros e informações relevantes;
|
||||
8. testar todo o fluxo sem depender do Premiere real.
|
||||
|
||||
## Limites da etapa
|
||||
|
||||
### Incluído
|
||||
|
||||
- conexão e chamadas técnicas ao MCP;
|
||||
- sessão e erros da integração;
|
||||
- leitura da timeline, sequência, faixas e clipes;
|
||||
- conversores de dados externos;
|
||||
- entidades e objetos de valor necessários;
|
||||
- contrato de acesso ao editor;
|
||||
- contexto, pipeline e descoberta da timeline;
|
||||
- configuração mínima do scanner;
|
||||
- logs técnicos e de fluxo;
|
||||
- testes unitários, de integração simulada e de conversores;
|
||||
- fixtures baseadas em respostas reais do MCP.
|
||||
|
||||
### Não incluído
|
||||
|
||||
- corte, exclusão ou movimentação de clipes;
|
||||
- qualquer escrita no Premiere;
|
||||
- plano de edição;
|
||||
- decisão automática;
|
||||
- transcrição;
|
||||
- análise visual;
|
||||
- análise de áudio;
|
||||
- detecção de cenas;
|
||||
- detecção de retakes;
|
||||
- uso obrigatório de provider de IA;
|
||||
- otimizações prematuras ou execução paralela.
|
||||
|
||||
## Estrutura planejada
|
||||
|
||||
```text
|
||||
engine/
|
||||
├── arquitetura/
|
||||
│ └── documentação da arquitetura
|
||||
├── scanner/
|
||||
│ ├── coordenacao/
|
||||
│ ├── contratos/
|
||||
│ ├── modelos/
|
||||
│ ├── configuracao/
|
||||
│ └── descoberta/
|
||||
├── integracoes/
|
||||
│ └── premiere/
|
||||
│ ├── cliente_mcp.py
|
||||
│ ├── sessao_mcp.py
|
||||
│ ├── erros_mcp.py
|
||||
│ ├── leitura/
|
||||
│ ├── conversores/
|
||||
│ └── contratos/
|
||||
├── dominio/
|
||||
│ ├── entidades/
|
||||
│ └── objetos_de_valor/
|
||||
├── configuracao/
|
||||
├── persistencia/
|
||||
├── logging/
|
||||
└── testes/
|
||||
```
|
||||
|
||||
## Fases de desenvolvimento
|
||||
|
||||
### Fase 0 — Preparação e confirmação arquitetural
|
||||
|
||||
**Objetivo:** garantir que o desenho está coerente antes da implementação.
|
||||
|
||||
**Atividades:**
|
||||
|
||||
- revisar `scanner.md`, `integracao-com-premiere.md` e `leitura-da-timeline-via-mcp.md`;
|
||||
- revisar a skill `boas-praticas-oo.md`;
|
||||
- confirmar que todos os identificadores internos serão em PT-BR;
|
||||
- definir os contratos antes das implementações concretas;
|
||||
- confirmar que o scanner não terá dependência direta do MCP;
|
||||
- identificar quais classes são realmente necessárias na primeira versão.
|
||||
|
||||
**Entrega:** arquitetura aprovada e sem responsabilidades sobrepostas.
|
||||
|
||||
### Fase 1 — Descoberta da API real do MCP
|
||||
|
||||
**Objetivo:** conhecer o contrato externo antes de criar adaptadores definitivos.
|
||||
|
||||
**Atividades:**
|
||||
|
||||
- identificar como o MCP é iniciado;
|
||||
- verificar como a conexão é estabelecida;
|
||||
- listar as ferramentas disponíveis;
|
||||
- identificar ferramentas para projeto, sequência, faixas e clipes;
|
||||
- registrar argumentos, respostas e erros;
|
||||
- observar formato dos identificadores e dos tempos;
|
||||
- capturar respostas reais anonimizadas para fixtures;
|
||||
- confirmar se a comunicação é síncrona ou assíncrona;
|
||||
- confirmar se existe estado de sessão.
|
||||
|
||||
**Regra:** nomes de ferramentas e campos externos não serão inventados. Eles ficarão isolados na integração.
|
||||
|
||||
**Entrega:** inventário do MCP e conjunto inicial de fixtures reais.
|
||||
|
||||
### Fase 2 — Contratos e modelos do domínio
|
||||
|
||||
**Objetivo:** definir as interfaces internas antes dos adaptadores.
|
||||
|
||||
**Contratos:**
|
||||
|
||||
- `ContratoDeAcessoAoEditor`;
|
||||
- contrato de etapa do scanner;
|
||||
- contrato de conversor, quando necessário.
|
||||
|
||||
**Entidades:**
|
||||
|
||||
- `Projeto`;
|
||||
- `Sequencia`;
|
||||
- `Timeline`;
|
||||
- `Faixa`;
|
||||
- `Clipe`.
|
||||
|
||||
**Objetos de valor:**
|
||||
|
||||
- `IntervaloDeTempo`;
|
||||
- `TipoDeFaixa`;
|
||||
- `TipoDeMidia`;
|
||||
- identificadores internos e externos, se necessário.
|
||||
|
||||
**Invariantes mínimas:**
|
||||
|
||||
- intervalo não pode iniciar antes de zero;
|
||||
- fim não pode ser anterior ao início;
|
||||
- identificadores devem ser preservados;
|
||||
- posição na timeline e posição na origem são distintas;
|
||||
- clipe pode estar offline sem invalidar toda a timeline;
|
||||
- nome não é identificador único.
|
||||
|
||||
**Entrega:** modelo interno independente de MCP e editor.
|
||||
|
||||
### Fase 3 — Cliente e sessão MCP
|
||||
|
||||
**Objetivo:** encapsular a comunicação técnica externa.
|
||||
|
||||
**Classes:**
|
||||
|
||||
- `ClienteMCP`;
|
||||
- `SessaoMCP`;
|
||||
- `ErroMCP`;
|
||||
- `ErroDeConexaoMCP`;
|
||||
- `ErroDeFerramentaMCP`;
|
||||
- `ErroDeRespostaMCP`;
|
||||
- `FerramentaMCPNaoEncontrada`.
|
||||
|
||||
**Responsabilidades:**
|
||||
|
||||
- conectar e desconectar;
|
||||
- informar estado da conexão;
|
||||
- chamar ferramentas;
|
||||
- controlar timeout;
|
||||
- retornar resposta bruta;
|
||||
- traduzir falhas técnicas em erros específicos;
|
||||
- registrar logs técnicos.
|
||||
|
||||
**Restrições:**
|
||||
|
||||
- não criar entidades de domínio;
|
||||
- não conhecer timeline, clipe, cena ou retake;
|
||||
- não decidir qual ferramenta usar para uma regra de negócio;
|
||||
- não misturar leitura e escrita.
|
||||
|
||||
**Entrega:** comunicação técnica testável com cliente simulado.
|
||||
|
||||
### Fase 4 — Leitura estruturada do Premiere
|
||||
|
||||
**Objetivo:** oferecer operações de alto nível para o restante do sistema.
|
||||
|
||||
**Classes iniciais:**
|
||||
|
||||
- `AcessoAoEditor`;
|
||||
- `AcessoATimeline`;
|
||||
- `AcessoAClipes`.
|
||||
|
||||
**Operações iniciais:**
|
||||
|
||||
- obter timeline ativa;
|
||||
- obter sequência ativa;
|
||||
- obter faixas;
|
||||
- obter clipes;
|
||||
- obter detalhes de um clipe.
|
||||
|
||||
Essas classes poderão começar com uma fachada simples e ser divididas somente quando houver crescimento real de responsabilidade.
|
||||
|
||||
**Entrega:** leitura sem que o scanner conheça nomes de ferramentas MCP.
|
||||
|
||||
### Fase 5 — Conversão e validação
|
||||
|
||||
**Objetivo:** transformar respostas externas em objetos internos confiáveis.
|
||||
|
||||
**Classes:**
|
||||
|
||||
- `ConversorDeTimeline`;
|
||||
- `ConversorDeFaixas`;
|
||||
- `ConversorDeClipes`.
|
||||
|
||||
**Atividades:**
|
||||
|
||||
- normalizar nomes de campos;
|
||||
- converter tempos e identificadores;
|
||||
- aplicar valores padrão seguros;
|
||||
- validar campos obrigatórios;
|
||||
- preservar campos externos relevantes;
|
||||
- tratar tipos desconhecidos;
|
||||
- diferenciar resposta incompleta de timeline vazia;
|
||||
- gerar erros de validação estruturados.
|
||||
|
||||
**Entrega:** timeline de domínio construída a partir de fixtures externas.
|
||||
|
||||
### Fase 6 — Núcleo do scanner
|
||||
|
||||
**Objetivo:** executar a descoberta por meio do fluxo arquitetural definido.
|
||||
|
||||
**Classes:**
|
||||
|
||||
- `ContextoDeAnalise`;
|
||||
- `Analisador`;
|
||||
- `ResultadoDaAnalise`;
|
||||
- `StatusDaAnalise`;
|
||||
- `ErroDeAnalise`;
|
||||
- `DescobertaDaTimeline`;
|
||||
- `PipelineDoScanner`;
|
||||
- `AnalisadorDeTimeline`.
|
||||
|
||||
**Fluxo:**
|
||||
|
||||
```text
|
||||
AnalisadorDeTimeline
|
||||
↓
|
||||
ContextoDeAnalise
|
||||
↓
|
||||
PipelineDoScanner
|
||||
↓
|
||||
DescobertaDaTimeline
|
||||
↓
|
||||
ContratoDeAcessoAoEditor
|
||||
↓
|
||||
Timeline do domínio
|
||||
↓
|
||||
Contexto atualizado
|
||||
```
|
||||
|
||||
Na primeira versão, o pipeline poderá conter somente `DescobertaDaTimeline`.
|
||||
|
||||
**Entrega:** scanner capaz de retornar o contexto com a timeline lida.
|
||||
|
||||
### Fase 7 — Testes e integração simulada
|
||||
|
||||
**Objetivo:** garantir comportamento sem depender do Premiere real.
|
||||
|
||||
**Implementar:**
|
||||
|
||||
- `AcessoAoEditorSimulado`;
|
||||
- fixtures de projeto, sequência, faixas e clipes;
|
||||
- testes do cliente MCP;
|
||||
- testes dos acessos de leitura;
|
||||
- testes dos conversores;
|
||||
- testes das entidades e objetos de valor;
|
||||
- testes do pipeline;
|
||||
- testes da descoberta;
|
||||
- testes de integração simulada.
|
||||
|
||||
**Cenários obrigatórios:**
|
||||
|
||||
- timeline válida;
|
||||
- timeline vazia;
|
||||
- nenhuma sequência ativa;
|
||||
- sequência sem clipes;
|
||||
- mídia offline;
|
||||
- resposta incompleta;
|
||||
- intervalo inválido;
|
||||
- ferramenta inexistente;
|
||||
- timeout;
|
||||
- MCP indisponível;
|
||||
- campos adicionais desconhecidos.
|
||||
|
||||
**Entrega:** suíte automatizada reproduzível.
|
||||
|
||||
### Fase 8 — Validação com Premiere real
|
||||
|
||||
**Objetivo:** confirmar o fluxo contra o ambiente real.
|
||||
|
||||
**Atividades:**
|
||||
|
||||
- conectar ao MCP real;
|
||||
- listar ferramentas e comparar com o inventário;
|
||||
- ler projeto e sequência reais;
|
||||
- comparar resposta real com fixtures;
|
||||
- validar faixas e clipes;
|
||||
- testar projeto vazio;
|
||||
- testar mídia offline;
|
||||
- verificar logs sem dados sensíveis;
|
||||
- confirmar que nenhuma ferramenta de escrita foi chamada.
|
||||
|
||||
**Entrega:** relatório de validação da leitura real.
|
||||
|
||||
## Critérios de conclusão
|
||||
|
||||
A primeira etapa estará concluída quando:
|
||||
|
||||
- o scanner depender apenas de contratos internos;
|
||||
- o MCP estiver isolado no módulo de integração;
|
||||
- a timeline ativa puder ser lida do Premiere;
|
||||
- faixas e clipes forem convertidos para o domínio;
|
||||
- intervalos da timeline e da origem forem preservados separadamente;
|
||||
- mídia offline for representada sem interromper toda a leitura;
|
||||
- timeline vazia for tratada como resultado válido quando apropriado;
|
||||
- erros técnicos e de validação forem distinguíveis;
|
||||
- o fluxo puder ser executado com integração simulada;
|
||||
- os testes automatizados estiverem passando;
|
||||
- os logs forem úteis e seguros;
|
||||
- nenhuma alteração for feita na timeline;
|
||||
- todos os identificadores internos respeitarem PT-BR;
|
||||
- a implementação estiver aderente à skill de boas práticas OO.
|
||||
|
||||
## Ordem resumida
|
||||
|
||||
```text
|
||||
Arquitetura
|
||||
↓
|
||||
API real do MCP
|
||||
↓
|
||||
Contratos e domínio
|
||||
↓
|
||||
ClienteMCP
|
||||
↓
|
||||
AcessoAoEditor
|
||||
↓
|
||||
Conversores
|
||||
↓
|
||||
Contexto e pipeline
|
||||
↓
|
||||
DescobertaDaTimeline
|
||||
↓
|
||||
Testes simulados
|
||||
↓
|
||||
Validação com Premiere real
|
||||
```
|
||||
|
||||
## Regra final
|
||||
|
||||
O MCP é o mecanismo de comunicação com o editor. O scanner é o módulo que organiza a descoberta. O domínio representa os dados. Os conversores isolam formatos externos. Nenhuma dessas responsabilidades deve ser concentrada em uma única classe.
|
||||
Reference in New Issue
Block a user