translate to english!

This commit is contained in:
2026-03-24 13:40:18 +00:00
parent 4e633163ce
commit 9ba2aab1a5
49 changed files with 2488 additions and 2488 deletions
+37 -37
View File
@@ -1,31 +1,31 @@
# Prometeu DevTools Protocol
Este documento descreve o protocolo de comunicação entre o Runtime do Prometeu e ferramentas de desenvolvimento (como o Prometeu Debugger).
This document describes the communication protocol between the Prometeu Runtime and development tools (such as the Prometeu Debugger).
## Visão Geral
## Overview
O protocolo é baseado em JSON, enviado via uma conexão de transporte (geralmente TCP). Cada mensagem é um objeto JSON em uma única linha (JSONL).
The protocol is based on JSON, sent via a transport connection (usually TCP). Each message is a JSON object on a single line (JSONL).
## Estrutura
## Structure
- **[protocol.json](./protocol.json)**: Definição formal do protocolo em formato JSON.
- **[protocol.md](README.md)**: Documentação legível para humanos descrevendo os comandos, eventos e tipos.
- **[examples/](./examples)**: Exemplos de fluxos de mensagens (handshake, breakpoints, etc.) em formato JSONL.
- **[protocol.json](./protocol.json)**: Formal definition of the protocol in JSON format.
- **[protocol.md](README.md)**: Human-readable documentation describing commands, events, and types.
- **[examples/](./examples)**: Examples of message flows (handshake, breakpoints, etc.) in JSONL format.
## Versionamento
## Versioning
O protocolo possui uma versão explícita definida no campo `protocol_version`.
The protocol has an explicit version defined in the `protocol_version` field.
- Mudanças incompatíveis (breaking changes) incrementam a versão principal.
- Novos campos em mensagens existentes devem ser opcionais sempre que possível para manter compatibilidade retroativa.
- Incompatible changes (breaking changes) increment the major version.
- New fields in existing messages should be optional whenever possible to maintain backward compatibility.
A versão atual do protocolo é: **1**
The current protocol version is: **1**
## Handshake
Ao conectar, o Runtime envia uma mensagem de handshake para o cliente.
Upon connecting, the Runtime sends a handshake message to the client.
### Runtime -> Cliente
### Runtime -> Client
```json
{
@@ -41,43 +41,43 @@ Ao conectar, o Runtime envia uma mensagem de handshake para o cliente.
}
```
### Cliente -> Runtime
### Client -> Runtime
O cliente deve responder com `start` ou `ok` para iniciar a sessão.
The client must respond with `start` or `ok` to start the session.
```json
{ "type": "start" }
```
## Requisições (Requests)
## Requests
O cliente pode enviar as seguintes requisições para controlar a execução:
The client can send the following requests to control execution:
| Nome | Parâmetros | Descrição |
| Name | Parameters | Description |
|------|------------|-----------|
| `pause` | `[]` | Pausa a execução da VM. |
| `resume` | `[]` | Retoma a execução da VM. |
| `step` | `[]` | Executa uma única instrução (PC). |
| `stepFrame` | `[]` | Executa até o próximo frame. |
| `getState` | `[]` | Retorna o estado atual da VM (`pc`, `stack_top`, `frame_index`, `app_id`). |
| `setBreakpoint` | `{"pc": number}` | Define um breakpoint no endereço especificado. |
| `clearBreakpoint` | `{"pc": number}` | Remove um breakpoint no endereço especificado. |
| `pause` | `[]` | Pauses VM execution. |
| `resume` | `[]` | Resumes VM execution. |
| `step` | `[]` | Executes a single instruction (PC). |
| `stepFrame` | `[]` | Executes until the next frame. |
| `getState` | `[]` | Returns the current VM state (`pc`, `stack_top`, `frame_index`, `app_id`). |
| `setBreakpoint` | `{"pc": number}` | Sets a breakpoint at the specified address. |
| `clearBreakpoint` | `{"pc": number}` | Removes a breakpoint at the specified address. |
## Respostas (Responses)
## Responses
Algumas requisições geram respostas específicas. Por exemplo, `getState` retorna o estado da VM.
Some requests generate specific responses. For example, `getState` returns the VM state.
## Eventos (Events)
## Events
O Runtime pode enviar eventos assíncronos para o cliente:
The Runtime can send asynchronous events to the client:
| Nome | Campos | Descrição |
| Name | Fields | Description |
|------|--------|-----------|
| `breakpointHit` | `pc`, `frame_index` | Emitido quando a execução atinge um breakpoint. |
| `log` | `level`, `source`, `msg` | Emitido quando o código em execução gera um log. |
| `telemetry` | `frame_index`, `vm_steps`, `syscalls`, `cycles` | Estatísticas de execução enviadas periodicamente. |
| `cert` | `rule`, `used`, `limit`, `frame_index` | Informações de certificação e limites de recursos. |
| `breakpointHit` | `pc`, `frame_index` | Emitted when execution hits a breakpoint. |
| `log` | `level`, `source`, `msg` | Emitted when the running code generates a log. |
| `telemetry` | `frame_index`, `vm_steps`, `syscalls`, `cycles` | Execution statistics sent periodically. |
| `cert` | `rule`, `used`, `limit`, `frame_index` | Certification information and resource limits. |
## Exemplos
## Examples
Veja a pasta `examples/` para fluxos de mensagens completos.
See the `examples/` folder for complete message flows.