Fichiers de l’espace de travail

Un espace de travail est un dossier dont le nom se termine par .echolot, contenant de simples fichiers TOML : un par requête, environnement, serveur MCP, mock et flux. Le Finder l’affiche comme un seul document ; dans Terminal, dans Git et dans votre éditeur, c’est un dossier normal. Echolot écrit chaque fichier toujours de la même façon (clés dans un ordre fixe, rien d’écrit qui ait sa valeur par défaut) : un changement dans l’app est donc un petit changement dans le diff. Voir Git et équipes.

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

Règles pour tous les fichiersCopy Anchor Link

• Les fichiers sont en TOML 1.0, UTF-8.
• Chacun commence par echolot = 1, la version du format. Un fichier avec un numéro plus élevé a été enregistré par un Echolot plus récent ; Echolot l’indique au lieu de l’ouvrir.
• Les noms de fichier sont des slugs : lettres minuscules, chiffres et tirets, 80 caractères au plus, tirés du nom de l’élément (Sign in devient sign-in). Le nom lui-même est la clé name.
• Les chemins entre éléments sont des slugs joints par /, relatifs à requests/ : auth/sign-in, orders.
• Les champs de texte peuvent contenir des {{variables}} et des valeurs dynamiques.
• Les listes d’éléments sont des tableaux de tables TOML ([[headers]]). Tout ce qui a enabled = false est conservé mais désactivé ; sans la clé, c’est activé.

Ce qui n’entre jamais dans les fichiersCopy Anchor Link

• Les valeurs secrètes. Une variable secrète est écrite par son nom avec secret = true et sans valeur ; la valeur vit dans le trousseau de votre Mac. Les champs qui demandent un secret (un mot de passe, un mot de passe de proxy, un secret client) devraient contenir une {{variable}} qui est un secret. Echolot propose de placer dans le trousseau un mot de passe que vous saisissez, et les imports le font d’eux-mêmes. Voir secrets.
• Les jetons OAuth et les connexions MCP : dans le trousseau.
• Les valeurs que les scripts définissent avec pm.environment.set et similaires : elles durent le temps de la fenêtre ou de la commande.
• L’historique et les réponses : dans Application Support sur votre Mac, un historique par espace de travail. Voir historique.
• Votre propre disposition : la disposition des volets et leurs tailles, les onglets ouverts, l’environnement que vous avez choisi.

Un espace de travail peut donc être validé et partagé sans risque. Chaque collègue définit ses propres valeurs secrètes.

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

CertificatsCopy Anchor Link

Chaque table [[certificates]] est une règle pour un hôte :

AgentsCopy Anchor Link

[agents] définit ce que les agents IA peuvent faire dans cet espace de travail, via le serveur MCP d’Echolot et l’Assistant. Voir agents.

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

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

Les types d’action sont read, safe-send, unsafe-send, protected-send, new-host, workspace-write et destructive. Une règle plus stricte compte toujours. Une règle plus souple ne compte qu’une fois que vous lui faites confiance (l’app demande ; la ligne de commande exige --trust-workspace-policy). protected-send et new-host ne peuvent jamais être réglés sur allow.

environments/Copy Anchor Link

Un fichier par environnement ; son nom de fichier est son slug, utilisé par --env.

echolot = 1
name = "Production"
protected = true

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

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

VariablesCopy Anchor Link

Les mêmes dans workspace.toml, les environnements, les dossiers et les requêtes :

requests/Copy Anchor Link

Le dossier requests contient l’arborescence que vous voyez dans la barre latérale. Chaque dossier qu’il contient est un dossier de l’arborescence, chaque fichier de requête une requête. Le type de requête vient du suffixe du fichier :

À côté d’une requête, avec le même slug :

_folder.tomlCopy Anchor Link

Chaque dossier en a un, et requests/ lui-même aussi, pour le niveau supérieur.

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

À côté, _folder.pre.js et _folder.test.js sont les scripts du dossier ; dans requests/, ce sont ceux de l’espace de travail. Ils s’exécutent pour chaque requête qu’il contient, de celui de l’espace de travail jusqu’à celui de la requête elle-même. Un dossier qui suit une spec a aussi _spec-lock.json, ce qu’il a pris en dernier dans la spec ; laissez Echolot le gérer.

Clés de toutes les requêtesCopy 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

Requêtes HTTP (.req.toml)Copy Anchor Link

La table [body] prend l’une de trois formes :

Requêtes 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"
}"""

Requêtes gRPC (.grpc.toml)Copy Anchor Link

Requêtes WebSocket (.ws.toml)Copy Anchor Link

Requêtes Socket.IO (.sio.toml)Copy Anchor Link

Requêtes MQTT (.mqtt.toml)Copy Anchor Link

Le nom d’utilisateur et le mot de passe sont l’auth Basic de la requête.

Appels MCP (.mcp.toml)Copy Anchor Link

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

Vérifications (assertions)Copy Anchor Link

Voir scripts et tests pour savoir quelles vérifications chaque cible propose.

CapturesCopy Anchor Link

Une réponse de 400 ou plus, ou une valeur absente, laisse la variable telle quelle. Voir captures.

Réglages (settings)Copy Anchor Link

Voir réglages de requête.

AuthCopy Anchor Link

[auth] a un type, et les clés de ce type. Une requête ou un dossier sans [auth] hérite ; par défaut, l’espace de travail n’a pas d’auth.

Écrivez chaque mot de passe, jeton et clé sous forme de {{variable}} secrète. Voir auth.

mcp-servers/Copy Anchor Link

Un fichier par serveur MCP ; le nom de fichier est le slug que les appels MCP désignent.

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

Voir ajouter des serveurs.

specs/Copy Anchor Link

Les fichiers de spec tels quels : documents OpenAPI (.yaml, .yml, .json), schémas GraphQL (SDL .graphql, ou un résultat d’introspection en JSON) et fichiers protobuf (.proto). Echolot les modifie sur place et conserve votre mise en forme. Les requêtes et les mocks les désignent par leur chemin, par exemple specs/alpenglow.yaml. Voir specs.

mocks/Copy Anchor Link

Un fichier par serveur mock, et ses routes JavaScript à côté.

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 contient les routes JavaScript du mock, qui répondent avant les routes créées à la main et la spec. Pour les opérations de la spec, les réponses ne vivent jamais dans le mock : les exemples vont dans la spec. Voir mocks, routes et données fictives et routes en JavaScript.

flows/Copy Anchor Link

Un fichier par flux, <slug>.flow.toml. Echolot écrit les blocs, les liens et les notes dans un ordre fixe : déplacer un bloc change donc deux lignes.

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"

Les types de blocs et leurs réglages sont décrits dans blocs.

assistant/Copy Anchor Link

Les conversations avec l’Assistant que vous partagez dans l’espace de travail : <slug>.md à lire dans n’importe quel éditeur, et <slug>.json pour qu’Echolot les rouvre.

Autres fichiersCopy Anchor Link

Les fichiers qu’Echolot ne connaît pas sont laissés tels quels : un README, un .gitignore ou des fichiers de données peuvent donc vivre dans l’espace de travail. Les données qu’un agent ou un flux enregistre (comme exports/products.csv) vont là où on le lui a demandé, à l’intérieur de l’espace de travail.