148 lines
5.4 KiB
Markdown
148 lines
5.4 KiB
Markdown
# Prometeu Engineering
|
|
|
|
Workspace de engenharia do **Prometeu**, um console virtual educacional e
|
|
experimental. Reúne os repositórios da plataforma e o contexto de trabalho em
|
|
[AI Engineering (AIE)](.ai-engineering/README.md): discussões, decisões, planos e
|
|
evidências de execução.
|
|
|
|
## Projetos
|
|
|
|
Os únicos projetos integrados a este workspace são os submódulos Git abaixo,
|
|
também cadastrados no AIE:
|
|
|
|
| Projeto | Responsabilidade | Tecnologia |
|
|
| --- | --- | --- |
|
|
| [runtime](runtime/README.md) | Execução da máquina: VM, periféricos, firmware, integração com o host e CLI. | Rust |
|
|
| [studio](studio/README.md) | Ambiente de desenvolvimento: interface desktop, compilador, empacotamento de assets e integração com execução e depuração. | Java, JavaFX e Gradle |
|
|
|
|
Cada submódulo mantém seu próprio histórico, especificações e comandos de
|
|
validação. Este repositório registra as revisões usadas em conjunto e organiza o
|
|
trabalho de engenharia do workspace.
|
|
|
|
## Estrutura
|
|
|
|
```text
|
|
.
|
|
├── .ai-engineering/ # Configuração, protocolo e Works do AIE
|
|
├── .gitignore # Política de arquivos e diretórios locais
|
|
├── .gitmodules # Origens dos dois submódulos
|
|
├── AGENTS.md # Instruções de engenharia para agentes
|
|
├── README.md
|
|
├── runtime/ # Submódulo da máquina e runtime
|
|
└── studio/ # Submódulo do ambiente de desenvolvimento
|
|
```
|
|
|
|
O [`.gitignore`](.gitignore) ignora os demais diretórios na raiz, inclusive novos
|
|
projetos locais. As exceções são `runtime/`, `studio/` e `.ai-engineering/`.
|
|
Os arquivos locais e temporários do AIE têm regras próprias de exclusão.
|
|
|
|
## Preparar o workspace
|
|
|
|
É necessário ter Git e acesso SSH aos repositórios definidos em
|
|
[`.gitmodules`](.gitmodules). Após clonar este repositório, execute na raiz:
|
|
|
|
```bash
|
|
git submodule update --init runtime studio
|
|
git submodule status
|
|
```
|
|
|
|
Esse comando carrega as revisões registradas pelo workspace. Após atualizar o
|
|
repositório principal, execute novamente `git submodule update --init runtime studio`
|
|
para alinhar os submódulos às revisões recebidas.
|
|
|
|
Para desenvolver, consulte os requisitos específicos de cada projeto:
|
|
|
|
- **Runtime:** Rust via `rustup`, com a versão definida em
|
|
[`rust-toolchain.toml`](runtime/rust-toolchain.toml). Veja os requisitos completos
|
|
no [README do runtime](runtime/README.md).
|
|
- **Studio:** JDK e ambiente desktop para JavaFX; o Gradle Wrapper está incluído.
|
|
Veja os requisitos e opções de instalação no [README do Studio](studio/README.md).
|
|
- **Engenharia:** CLI `aie` ou `ai-engineering` disponível no ambiente.
|
|
|
|
## Trabalhar com AIE
|
|
|
|
Antes de iniciar trabalho de engenharia, leia o [AGENTS.md](AGENTS.md), o
|
|
[guia do protocolo](.ai-engineering/README.md) e o
|
|
[manifesto](.ai-engineering/protocol.json). Consulte também as instruções locais
|
|
do projeto que será alterado.
|
|
|
|
Na raiz do workspace, consulte o estado e as próximas ações:
|
|
|
|
```bash
|
|
aie status --format json
|
|
aie next-actions --format json
|
|
aie repo list --format json
|
|
```
|
|
|
|
Selecione um Work existente que corresponda à tarefa. Se não houver, crie um
|
|
com objetivo e critérios de aceitação; associe apenas os repositórios envolvidos.
|
|
Por exemplo, para uma alteração de integração:
|
|
|
|
```bash
|
|
aie work create "Descrever a alteração de integração" --repo runtime --repo studio
|
|
```
|
|
|
|
Carregue o contexto usando o identificador retornado, substituindo `WRK-XXXX`:
|
|
|
|
```bash
|
|
aie work context WRK-XXXX --format markdown
|
|
```
|
|
|
|
Registre discussões, decisões, planos e evidências no Work correspondente.
|
|
Aprovações humanas devem ser explícitas, conforme o protocolo. A configuração
|
|
atual cadastra os dois repositórios com acesso de leitura no AIE; esse cadastro
|
|
não concede autorização de edição.
|
|
|
|
Para conferir a integridade dos registros:
|
|
|
|
```bash
|
|
aie project validate --format json
|
|
```
|
|
|
|
Se o alias `aie` não estiver disponível, use `ai-engineering` com os mesmos
|
|
argumentos. Sem a CLI, consulte os arquivos portáveis em `.ai-engineering/`.
|
|
|
|
## Desenvolvimento e validação
|
|
|
|
Execute os comandos no diretório do respectivo submódulo.
|
|
|
|
**Runtime:**
|
|
|
|
```bash
|
|
cd runtime
|
|
cargo build
|
|
make test
|
|
```
|
|
|
|
O gate de CI do runtime é `make ci-domains`; seus requisitos adicionais estão
|
|
documentados no [README do runtime](runtime/README.md).
|
|
|
|
**Studio**, a partir da raiz do workspace:
|
|
|
|
```bash
|
|
cd studio
|
|
./gradlew :prometeu-app:run
|
|
./gradlew test
|
|
```
|
|
|
|
As instruções de distribuição, cobertura e testes de integração estão no
|
|
[README do Studio](studio/README.md).
|
|
|
|
As alterações de código são commitadas no submódulo correspondente. Depois,
|
|
registre neste repositório a atualização do ponteiro de `runtime` ou `studio`,
|
|
junto aos registros de engenharia relacionados. O commit da raiz referencia um
|
|
commit do submódulo; os arquivos de código pertencem ao histórico desse projeto.
|
|
|
|
## Referências
|
|
|
|
- [Especificações da máquina](runtime/docs/specs/runtime/README.md)
|
|
- [Arquitetura da VM e runtime](runtime/docs/vm-arch/ARCHITECTURE.md)
|
|
- [Guia de especificações do Studio](studio/docs/specs/README.md)
|
|
- [Compilador](studio/docs/specs/compiler/README.md)
|
|
- [Linguagem PBS e SDK](studio/docs/specs/compiler-languages/pbs/README.md)
|
|
- [Empacotamento de assets](studio/docs/specs/packer/README.md)
|
|
- [Configuração do AIE](.ai-engineering/ai-engineering.yaml)
|
|
|
|
As especificações de cada projeto são a referência para seus contratos e
|
|
comportamentos. O README da raiz orienta a navegação e o trabalho conjunto.
|