joaohenrique/gart
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: varredura geral, documentação por função e regra de atualização

Browse Source 
A documentação descrevia um sistema que não existe mais: 62/73 ferramentas
(são 74), writer.py e models.py como arquivos (viraram pacotes), 1032 testes
(são 1454), models_api.py descrito como "API FastAPI" (é ponte JSON) e o app
SwiftUI ausente por completo — 5.500 linhas que o usuário opera todo dia sem
uma linha de documentação.

Cada arquivo passa a ter uma função específica, com cabeçalho de escopo
dizendo o que cobre e o que NÃO cobre (com a seta para quem cobre). O objetivo
é ler só o necessário: doc fora do assunto custa tempo e processamento sem
entregar nada.

    01 arquitetura   camadas, duas portas de entrada, regras transversais
    02 módulos       mapa do engine, incluindo o pipeline de voz
    03 server/tools  as 74 tools, helpers e como criar uma nova
    08 app macOS     NOVO — build por swiftc, telas, ponte, etapa 5
    09 manutenção    NOVO — por onde começar, o que está aberto, sintoma→arquivo

CLAUDE.md ganha a seção "Documentação (MANDATORY)": tabela de roteamento
(qual arquivo abrir para cada tarefa) e a regra de que toda alteração de
código atualiza a doc no mesmo commit, com o mapa de o-que-mexeu → o-que-
atualizar. Doc velha engana mais que doc ausente.

O índice do 05_EXPERIENCIAS subiu para o topo: consultar "isso já quebrou
antes?" custava carregar 1.281 linhas antes de chegar na tabela.

Dívidas levantadas na varredura e registradas em 09 §2: etapa 6 ainda ignora
o phrase_review.json, offset de ~400ms do Whisper, MacApp sem teste, admin/
fora do lint, confirmações visuais pendentes no FCP, submódulo WHISPERX sujo.

Também corrigidos dois links quebrados no Engine/README que apontavam um
nível acima do certo.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
João Henrique
2026-08-19 22:51:33 -04:00
co-authored by Claude Opus 5
parent ffaebb3f72
commit dcdd73edb5
10 changed files with 881 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files
code/Engine/README.md
+43 -32
View File
@@ -10,12 +10,20 @@ opera **fora** do Final Cut Pro: você exporta o XML, o servidor processa o
documento como dados estruturados e devolve um XML modificado para importação.
Nada é patcheado, nenhuma API privada é usada.
Toda a análise foi feita a partir do código-fonte em `server.py` e `fcpxml/`.
Toda a análise foi feita a partir do código-fonte. Este README é a visão
geral; o detalhe módulo a módulo mora em `docs/02_MODULES.md`, que é o
documento a manter atualizado quando a estrutura mudar.
> **Guia rápido:** [01 Arquitetura](docs/01_ARCHITECTURE.md) ·
> **Começando agora?** Leia [01 Arquitetura](docs/01_ARCHITECTURE.md) e depois
> [09 Manutenção](docs/09_MANUTENCAO.md) — o primeiro diz como o sistema é
> dividido, o segundo diz por onde começar a mexer e o que está em aberto.
>
> **Guia completo:** [01 Arquitetura](docs/01_ARCHITECTURE.md) ·
> [02 Módulos](docs/02_MODULES.md) · [03 Server/Tools](docs/03_SERVER_TOOLS.md) ·
> [04 Testes & Workflow](docs/04_TESTS_AND_WORKFLOW.md) ·
> [05 Experiências](docs/05_EXPERIENCIAS.md) · [06 Boas Práticas](docs/06_BOAS_PRATICAS.md)
> [05 Experiências](docs/05_EXPERIENCIAS.md) · [06 Boas Práticas](docs/06_BOAS_PRATICAS.md) ·
> [07 Projeto Ativo no FCP](docs/07_ESTUDO_PROJETO_ATIVO_FCP.md) ·
> [08 App macOS](docs/08_APP_MACOS.md) · [09 Manutenção](docs/09_MANUTENCAO.md)
---
@@ -26,7 +34,7 @@ Toda a análise foi feita a partir do código-fonte em `server.py` e `fcpxml/`.
Python, e reescreve de volta sem perda de sidecars (object tracking,
Cinematic).
2. **Uma camada MCP de 62 ferramentas** — expõe análise, edição em lote, QC,
2. **Uma camada MCP de 74 ferramentas** — expõe análise, edição em lote, QC,
geração, exportação cross-NLE, inteligência de mídia (silêncio/beats) e
edição baseada em transcrição, tudo acessível por um cliente MCP (Claude).
@@ -40,7 +48,7 @@ Toda a análise foi feita a partir do código-fonte em `server.py` e `fcpxml/`.
| Camada | Tecnologia |
|--------|-----------|
| Linguagem | **Python 3.10+** (~7.1k linhas em `server.py` + `fcpxml/`) |
| Linguagem | **Python 3.10+** (~13k linhas em `server.py`, `server_tools/` e `fcpxml/`) |
| Protocolo MCP | **mcp** (`mcp` SDK), servidor por stdio |
| Parsing XML | **defusedxml** em todos os 4 entry points + `lxml`/`ElementTree` |
| Tempo racional | frações `numerador/denominador` no formato `"600/2400s"` |
@@ -56,26 +64,29 @@ Toda a análise foi feita a partir do código-fonte em `server.py` e `fcpxml/`.
```
G-ART/
├── server.py # MCP server — 62 tools, prompts, resources, dispatch
├── fcpxml/ # "Engine" — biblioteca Python de núcleo
│ ├── models.py # TimeValue, Timecode, Clip, Timeline, enums, QC models
│ ├── parser.py # FCPXML → objetos Python (spine, connected clips, roles)
│ ├── writer.py # Modifica e grava FCPXML (markers, trim, gaps, speed)
│ ├── rough_cut.py # Gera timelines novas (rough cuts, montages, A/B)
│ ├── diff.py # Motor de comparação de timelines
│ ├── export.py # Export DaVinci Resolve v1.9 + FCP7 XMEML v5
│ ├── media_intel.py # Detecção real de silêncio (ffmpeg) e beats (librosa)
│ ├── transcribe.py # Transcrição Whisper local + edição por transcrição
│ ├── templates.py # Templates de timeline (intro/outro, lower thirds)
│ ├── live.py # Modo Live — push_to_fcp / list_fcp_libraries
│ ├── safe_xml.py # Wrappers defusedxml + serialize_xml()
│ └── dtd.py # Validação contra DTDs oficiais da Apple
├── Engine/ # Esta documentação da arquitetura
├── admin/ # Scripts de manutenção (graphify.sh, graphify.md)
├── docs/ # WORKFLOWS, CAPABILITY-AUDIT, specs
├── examples/ # Fixture de teste (sample.fcpxml)
├── tests/ # 1032 testes / 24 suítes
└── tools/ # Pacote Python (__init__)
├── CLAUDE.md # Regras do projeto para o agente
├── admin/ # Ponte com o app (fora de code/)
│ ├── models_api.py # Entry point: docstring dos comandos + dispatch
│ └── api/ # Os 37 comandos, um módulo por assunto
└── code/
├── server.py # MCP entry point — só dispatch
├── server_tools/ # Handlers das 74 tools + _shared/
├── fcpxml/ # "Engine" — biblioteca Python de núcleo
│ ├── writer/ # PACOTE: edição/escrita (mixins por assunto)
│ ├── models/ # PACOTE: dados por família (timing, timeline…)
│ ├── parser.py # FCPXML → objetos Python
│ ├── rough_cut.py # Gera timelines novas
│ ├── voice_*.py # Pipeline de voz (features → timeline → actions)
│ ├── phrase_review.py # Revisão de frases da etapa 5
│ ├── text_layout.py # Diagramação das legendas
│ ├── live.py # Modo Live — push_to_fcp
│ ├── safe_xml.py # defusedxml + serialize_xml()
│ └── dtd.py # Validação contra DTDs da Apple
├── MacApp/Sources/ # App SwiftUI (compilado por swiftc)
├── Engine/ # Esta documentação
├── docs/ # WORKFLOWS, CAPABILITY-AUDIT, specs
├── examples/ # Fixture de teste (sample.fcpxml)
└── tests/ # 1.454 testes / 42 suítes
```
---
@@ -102,7 +113,7 @@ TimeValue(600, 2400) # "600/2400s" == 0.25s
- Soma/subtração compartilham um único caminho `_binop()` (fast-path de mesmo
denominador + alinhamento por LCM).
### 4.2 Modelos principais — `models.py`
### 4.2 Modelos principais — `models/`
| Classe | Função |
|--------|--------|
@@ -126,8 +137,8 @@ escrita. `from_xml_element` faz match estrito do atributo `completed`
| Subsistema | Módulo | Função |
|-----------|--------|--------|
| Parser | `parser.py` | FCPXML → objetos Python: espinha, connected clips, secondary storylines, roles |
| Modifier | `writer.FCPXMLModifier` | Edição index-based (clips/resources/formats dicts) do documento existente |
| Writer | `writer.FCPXMLWriter` | Gera FCPXML novo a partir de objetos Python |
| Modifier | `writer/` (`FCPXMLModifier`) | Edição index-based (clips/resources/formats dicts) do documento existente |
| Writer | `writer/generator.py` | Gera FCPXML novo a partir de objetos Python |
| Rough cut | `rough_cut.py` | Gera timelines (rough cuts, montages, A/B roll) |
| Diff | `diff.py` | Compara timelines — detecta added/removed/moved/trimmed |
| Export | `export.py` | DaVinci Resolve v1.9 + FCP7 XMEML v5 |
@@ -151,7 +162,7 @@ assíncrono:
TOOL_HANDLERS = {
"analyze_timeline": handle_analyze_timeline,
"list_clips": handle_list_clips,
# ... 62 tools
# ... 74 tools, todos em server_tools/
}
```
@@ -249,7 +260,7 @@ correção, sem depender de lembrar dos dois comandos no pre-commit.
- [docs/02_MODULES.md](docs/02_MODULES.md) — guia módulo a módulo do `fcpxml/`
(responsabilidade, tamanho, APIs públicas).
- [docs/03_SERVER_TOOLS.md](docs/03_SERVER_TOOLS.md) — a camada MCP `server.py`,
62 ferramentas, helpers e o padrão de handler.
74 ferramentas, helpers e o padrão de handler.
- [docs/04_TESTS_AND_WORKFLOW.md](docs/04_TESTS_AND_WORKFLOW.md) — suíte de testes,
fluxo de trabalho (lint + pytest), execução e estado atual do sistema.
- [docs/05_EXPERIENCIAS.md](docs/05_EXPERIENCIAS.md) — **memória de projeto**:
@@ -259,10 +270,10 @@ correção, sem depender de lembrar dos dois comandos no pre-commit.
programação** a aplicar em toda alteração/correção; inclui checklist final.
### Outros documentos
- [../CLAUDE.md](../CLAUDE.md) — visão geral, key patterns, execução e pre-commit.
- [../CLAUDE.md](../../CLAUDE.md) — visão geral, key patterns, execução e pre-commit.
- [../docs/CAPABILITY-AUDIT-2026-06.md](../docs/CAPABILITY-AUDIT-2026-06.md) —
auditoria do ecossistema e roadmap dual-mode (XML + Live).
- [../docs/WORKFLOWS.md](../docs/WORKFLOWS.md) — 8 receitas de workflow de produção.
- [../docs/specs/](../docs/specs/) — schemas de tools, estrutura FCPXML, pseudocódigo
do writer, algoritmo de rough cut, implementação do server, roadmap, modelos.
- [../admin/graphify.md](../admin/graphify.md) — pipeline de graphify do código.
- [../admin/graphify.md](../../admin/graphify.md) — pipeline de graphify do código.