Archivos del espacio de trabajo

Un espacio de trabajo es una carpeta que termina en .echolot con archivos TOML sencillos dentro: uno por solicitud, entorno, servidor MCP, mock y flujo. El Finder lo muestra como un único documento; en Terminal, en Git y en tu editor es una carpeta normal. Echolot escribe todos los archivos siempre de la misma manera (las claves en un orden fijo, sin escribir nada que tenga su valor predeterminado), así que un cambio en la app es un cambio pequeño en el diff. Consulta Git y equipos.

Alpenglow.echolot/
  workspace.toml                     the workspace: ID, name, variables, auth, agents, proxy, certificates
  environments/
    staging.toml                     one environment
  requests/
    _folder.toml                     the order of the top level
    _folder.pre.js                   the workspace's pre-request script (and _folder.test.js)
    auth/
      _folder.toml                   a folder: name, order, docs, variables, auth
      sign-in.req.toml               an HTTP request
      sign-in.body.json              its body
      sign-in.pre.js                 its pre-request script
      sign-in.test.js                its test script
    catalog/
      search-products.gql.toml       a GraphQL request
      search-products.graphql        its query
  mcp-servers/
    alpenglow-mcp.toml               an MCP server
  specs/
    alpenglow.yaml                   an OpenAPI document
    shop.graphql                     a GraphQL schema
    inventory.proto                  a protobuf file
  mocks/
    shop.toml                        a mock server: settings and routes
    shop.js                          its routes in JavaScript
  flows/
    place-test-order.flow.toml       a flow
  assistant/
    checking-orders.md               a shared Assistant conversation, to read
    checking-orders.json             the same, to open in the app

Reglas de todos los archivosCopy Anchor Link

• Los archivos son TOML 1.0, UTF-8.
• Cada uno empieza con echolot = 1, la versión del formato. Un archivo con un número más alto lo guardó una versión más reciente de Echolot, y Echolot lo dice en lugar de abrirlo.
• Los nombres de archivo son slugs: letras minúsculas, dígitos y guiones, de 80 caracteres como máximo, creados a partir del nombre del elemento (Sign in es sign-in). El nombre en sí es la clave name.
• Las rutas entre elementos son slugs unidos con /, relativas a requests/: auth/sign-in, orders.
• Los campos de texto pueden contener {{variables}} y valores dinámicos.
• Las listas de cosas son arrays de tablas de TOML ([[headers]]). Todo lo que tiene enabled = false se conserva pero está desactivado; sin la clave, está activado.

Lo que nunca va en los archivosCopy Anchor Link

• Valores secretos. Una variable secreta se escribe con su nombre y secret = true, sin valor; el valor vive en el llavero de tu Mac. Los campos que necesitan un secreto (una contraseña, la contraseña de un proxy, un secreto de cliente) deben contener una {{variable}} que sea secreta. Echolot ofrece trasladar al llavero una contraseña que escribes, y las importaciones lo hacen por sí solas. Consulta secretos.
• Los tokens OAuth y los inicios de sesión de MCP: en el llavero.
• Los valores que fijan los scripts con pm.environment.set y similares: duran lo que dure la ventana o el comando.
• El historial y las respuestas: en Application Support de tu Mac, un historial por espacio de trabajo. Consulta historial.
• Tu propia disposición: la disposición de los paneles y sus tamaños, las pestañas abiertas, el entorno que elegiste.

Así que un espacio de trabajo se puede confirmar y compartir sin riesgo. Un compañero fija sus propios valores secretos.

workspace.tomlCopy Anchor Link

# Echolot workspace. Requests live in requests/, one file each.
echolot = 1
id = "0b7d4c1e-2f6a-4e38-9c51-7a1e3d9b5f20"
name = "Alpenglow"

[[variables]]
name = "baseURL"
value = "https://demo.echolot.dev/v1"

[[variables]]
name = "token"
secret = true

ProxyCopy Anchor Link

CertificadosCopy Anchor Link

Cada tabla [[certificates]] es una regla para un host:

AgentesCopy Anchor Link

[agents] define lo que pueden hacer los agentes de IA en este espacio de trabajo, mediante el servidor MCP de Echolot y el Asistente. Consulta agentes.

[agents]
allowed-hosts = ["demo.echolot.dev"]
max-requests = 200
max-requests-per-minute = 30

[agents.rules]
unsafe-send = "ask"
destructive = "refuse"

Los tipos de acción son read, safe-send, unsafe-send, protected-send, new-host, workspace-write y destructive. Una regla más estricta siempre cuenta. Una más permisiva solo cuenta cuando confías en ella (la app pregunta; la línea de comandos necesita --trust-workspace-policy). protected-send y new-host nunca pueden ponerse en allow.

environments/Copy Anchor Link

Un archivo por entorno; su nombre de archivo es su slug, que usa --env.

echolot = 1
name = "Production"
protected = true

[[variables]]
name = "baseURL"
value = "https://api.alpenglow.example/v1"

[[variables]]
name = "password"
secret = true

VariablesCopy Anchor Link

Igual en workspace.toml, los entornos, las carpetas y las solicitudes:

requests/Copy Anchor Link

La carpeta requests contiene el árbol que ves en la barra lateral. Cada carpeta que hay en ella es una carpeta del árbol, y cada archivo de solicitud, una solicitud. El tipo de solicitud viene del sufijo del archivo:

Junto a una solicitud, con el mismo slug:

_folder.tomlCopy Anchor Link

Cada carpeta tiene uno, y también requests/ mismo, para el nivel superior.

echolot = 1
name = "Auth"
order = ["sign-in", "who-am-i", "client-credentials"]
docs = "Send \"Sign in\" first: it captures the access token into {{token}}."

Junto a él, _folder.pre.js y _folder.test.js son los scripts de la carpeta; en requests/ son los del espacio de trabajo. Se ejecutan para cada solicitud de dentro, del espacio de trabajo hacia abajo hasta la propia solicitud. Una carpeta que sigue una especificación también tiene _spec-lock.json, lo último que tomó de la especificación; deja que Echolot lo mantenga.

Claves de todas las solicitudesCopy Anchor Link

echolot = 1
name = "Sign in"
method = "POST"
url = "{{baseURL}}/auth/token"

[body]
syntax = "json"
file = "sign-in.body.json"

[[headers]]
name = "Content-Type"
value = "application/json"

[[assertions]]
target = "status"
check = "equals"
expected = "200"

[[captures]]
variable = "token"
from = "json"
path = "$.access_token"
scope = "workspace"
secret = true

Solicitudes HTTP (.req.toml)Copy Anchor Link

La tabla [body] admite una de tres formas:

Solicitudes GraphQL (.gql.toml)Copy Anchor Link

echolot = 1
name = "Search products"
url = "{{baseURL}}/graphql"
operation = "SearchProducts"
schema = "specs/shop.graphql"
query-file = "search-products.graphql"
graphql-variables = """
{
  "text": "ultralight"
}"""

Solicitudes gRPC (.grpc.toml)Copy Anchor Link

Solicitudes WebSocket (.ws.toml)Copy Anchor Link

Solicitudes Socket.IO (.sio.toml)Copy Anchor Link

Solicitudes MQTT (.mqtt.toml)Copy Anchor Link

El nombre de usuario y la contraseña son la autenticación Basic de la solicitud.

Llamadas MCP (.mcp.toml)Copy Anchor Link

echolot = 1
name = "search_catalog"
server = "alpenglow-mcp"
tool = "search_catalog"
arguments = """
{
  "query": "ultralight tent",
  "limit": 3
}"""

AsercionesCopy Anchor Link

Consulta scripts y pruebas para saber qué comprobaciones ofrece cada destino.

CapturasCopy Anchor Link

Una respuesta de 400 o más, o un valor que no está, deja la variable como estaba. Consulta capturas.

AjustesCopy Anchor Link

Consulta ajustes de la solicitud.

AutenticaciónCopy Anchor Link

[auth] tiene un type y las claves de ese tipo. Una solicitud o una carpeta sin [auth] hereda; la predeterminada del espacio de trabajo es ninguna autenticación.

Escribe cada contraseña, token y clave como una {{variable}} secreta. Consulta autenticación.

mcp-servers/Copy Anchor Link

Un archivo por servidor MCP; el nombre del archivo es el slug que nombran las llamadas MCP.

echolot = 1
name = "Alpenglow MCP"
transport = "http"
url = "https://demo.echolot.dev/mcp"

Consulta añadir servidores.

specs/Copy Anchor Link

Archivos de especificación tal cual: documentos OpenAPI (.yaml, .yml, .json), esquemas GraphQL (SDL .graphql, o el resultado de una introspección como JSON) y archivos protobuf (.proto). Echolot los edita en el sitio y conserva tu formato. Las solicitudes y los mocks los nombran por su ruta, como specs/alpenglow.yaml. Consulta especificaciones.

mocks/Copy Anchor Link

Un archivo por servidor mock, y sus rutas en JavaScript junto a él.

echolot = 1
name = "Shop"
spec = "specs/alpenglow.yaml"
port = 4010
delay = 200

[[scenarios]]
operation = "GET /products/{sku}"
status = "404"

[[routes]]
id = "e5f6a7b8"
method = "GET"
path = "/users/{id}"
summary = "One user"

[[routes.responses]]
name = "OK"
status = 200
content-type = "application/json"
headers = [{ name = "X-Request-Id", value = "{{$randomUUID}}" }]
body = """
{
  "id": "{{request.params.id}}",
  "name": "{{$randomFullName}}"
}"""

[[routes.responses]]
name = "Not found"
status = 404
content-type = "application/json"
rules = [{ source = "path", name = "id", value = "0" }]
body = """{ "error": "no user {{request.params.id}}" }"""

mocks/<slug>.js contiene las rutas del mock en JavaScript, que responden antes que las rutas creadas a mano y la especificación. Para las operaciones de la especificación, las respuestas nunca viven en el mock: los ejemplos van a la especificación. Consulta mocks, rutas y datos falsos y rutas con script.

flows/Copy Anchor Link

Un archivo por flujo, <slug>.flow.toml. Echolot escribe los bloques, las conexiones y las notas en un orden fijo, así que mover un bloque cambia dos líneas.

echolot = 1
name = "Place a test order"
description = "Places an order, then asks a person whether to keep it."

[mcp]
tool = "place_test_order"
description = "Places a test order on the demo shop, asking a person before keeping it."

[[blocks]]
id = "signin"
kind = "request"
title = "Sign in"
position = [330, 250]

[blocks.settings]
request = "auth/sign-in"

[[wires]]
from = "start.run"
to = "signin.run"

Los tipos de bloque y sus ajustes están en bloques.

assistant/Copy Anchor Link

Conversaciones con el Asistente que compartes en el espacio de trabajo: <slug>.md para leer en cualquier editor, y <slug>.json para que Echolot lo vuelva a abrir.

Otros archivosCopy Anchor Link

Los archivos que Echolot no conoce se dejan en paz, así que un README, un .gitignore o archivos de datos pueden vivir en el espacio de trabajo. Los datos que guarda un agente o un flujo (como exports/products.csv) van donde se haya pedido, dentro del espacio de trabajo.