Arbeitsbereichsdateien

Ein Arbeitsbereich ist ein Ordner mit der Endung .echolot und einfachen TOML-Dateien darin: eine je Anfrage, Umgebung, MCP-Server, Mock und Flow. Der Finder zeigt ihn als ein Dokument; im Terminal, in Git und in deinem Editor ist er ein normaler Ordner. Echolot schreibt jede Datei jedes Mal gleich (Schlüssel in fester Reihenfolge, nichts, was seinen Standardwert hat), sodass eine Änderung in der App im Diff klein bleibt. Siehe Git und Teams.

Alpenglow.echolot/
  workspace.toml                     der Arbeitsbereich: ID, Name, Variablen, Auth, Agenten, Proxy, Zertifikate
  environments/
    staging.toml                     eine Umgebung
  requests/
    _folder.toml                     die Reihenfolge der obersten Ebene
    _folder.pre.js                   das Pre-Request-Skript des Arbeitsbereichs (und _folder.test.js)
    auth/
      _folder.toml                   ein Ordner: Name, Reihenfolge, Doku, Variablen, Auth
      sign-in.req.toml               eine HTTP-Anfrage
      sign-in.body.json              ihr Body
      sign-in.pre.js                 ihr Pre-Request-Skript
      sign-in.test.js                ihr Test-Skript
    catalog/
      search-products.gql.toml       eine GraphQL-Anfrage
      search-products.graphql        ihre Abfrage
  mcp-servers/
    alpenglow-mcp.toml               ein MCP-Server
  specs/
    alpenglow.yaml                   ein OpenAPI-Dokument
    shop.graphql                     ein GraphQL-Schema
    inventory.proto                  eine Protobuf-Datei
  mocks/
    shop.toml                        ein Mock-Server: Einstellungen und Routen
    shop.js                          seine Routen in JavaScript
  flows/
    place-test-order.flow.toml       ein Flow
  assistant/
    checking-orders.md               eine geteilte Unterhaltung mit dem Assistenten, zum Lesen
    checking-orders.json             dieselbe, zum Öffnen in der App

Regeln für jede DateiCopy Anchor Link

• Dateien sind TOML 1.0, UTF-8.
• Jede beginnt mit echolot = 1, der Version des Formats. Eine Datei mit einer höheren Zahl wurde von einem neueren Echolot gesichert; Echolot meldet das, statt sie zu öffnen.
• Dateinamen sind Slugs: Kleinbuchstaben, Ziffern und Bindestriche, höchstens 80 Zeichen, aus dem Namen des Elements gebildet (Sign in wird zu sign-in). Der Name selbst steht im Schlüssel name.
• Pfade zwischen Elementen sind durch / verbundene Slugs, relativ zu requests/: auth/sign-in, orders.
• Textfelder können {{variables}} und dynamische Werte enthalten.
• Listen von Dingen sind TOML-Arrays aus Tabellen ([[headers]]). Alles mit enabled = false bleibt erhalten, ist aber abgeschaltet; ohne den Schlüssel ist es an.

Was nie in die Dateien kommtCopy Anchor Link

• Geheime Werte. Eine geheime Variable wird mit ihrem Namen und secret = true ohne Wert geschrieben; der Wert liegt im Schlüsselbund deines Macs. Felder, die ein Secret brauchen (ein Passwort, ein Proxy-Passwort, ein Client-Secret), sollten eine {{variable}} enthalten, die ein Secret ist. Echolot bietet an, ein Passwort, das du tippst, in den Schlüsselbund zu verschieben, und Importe tun das von selbst. Siehe Secrets.
• OAuth-Tokens und MCP-Anmeldungen: im Schlüsselbund.
• Werte, die Skripte mit pm.environment.set und Ähnlichem setzen: Sie halten für das Fenster oder den Befehl.
• Verlauf und Antworten: in Application Support auf deinem Mac, ein Verlauf je Arbeitsbereich. Siehe Verlauf.
• Dein eigenes Layout: die Anordnung der Bereiche und ihre Größen, die geöffneten Tabs, die Umgebung, die du gewählt hast.

Ein Arbeitsbereich lässt sich also gefahrlos committen und teilen. Ein Teammitglied setzt seine eigenen geheimen Werte.

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

ZertifikateCopy Anchor Link

Jede Tabelle [[certificates]] ist eine Regel für einen Host:

AgentenCopy Anchor Link

[agents] legt fest, was KI-Agenten in diesem Arbeitsbereich dürfen, über den MCP-Server von Echolot und den Assistenten. Siehe Agenten.

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

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

Die Arten von Aktionen sind read, safe-send, unsafe-send, protected-send, new-host, workspace-write und destructive. Eine strengere Regel gilt immer. Eine lockerere gilt erst, wenn du ihr vertraust (die App fragt nach; die Befehlszeile braucht --trust-workspace-policy). protected-send und new-host lassen sich nie auf allow setzen.

environments/Copy Anchor Link

Eine Datei je Umgebung; ihr Dateiname ist ihr Slug, den --env verwendet.

echolot = 1
name = "Production"
protected = true

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

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

VariablenCopy Anchor Link

In workspace.toml, Umgebungen, Ordnern und Anfragen gleich:

requests/Copy Anchor Link

Der Ordner requests enthält den Baum, den du in der Seitenleiste siehst. Jeder Ordner darin ist ein Ordner des Baums, jede Anfragedatei eine Anfrage. Die Art der Anfrage ergibt sich aus der Endung der Datei:

Neben einer Anfrage, mit demselben Slug:

_folder.tomlCopy Anchor Link

Jeder Ordner hat eine, und requests/ selbst auch, für die oberste Ebene.

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

Daneben sind _folder.pre.js und _folder.test.js die Skripte des Ordners; in requests/ sind es die des Arbeitsbereichs. Sie laufen für jede Anfrage darin, von der des Arbeitsbereichs abwärts bis zur Anfrage selbst. Ein Ordner, der einer Spec folgt, hat außerdem _spec-lock.json, was er zuletzt aus der Spec übernommen hat; überlass sie Echolot.

Schlüssel jeder AnfrageCopy 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

HTTP-Anfragen (.req.toml)Copy Anchor Link

Die Tabelle [body] nimmt eine von drei Formen an:

GraphQL-Anfragen (.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"
}"""

gRPC-Anfragen (.grpc.toml)Copy Anchor Link

WebSocket-Anfragen (.ws.toml)Copy Anchor Link

Socket.IO-Anfragen (.sio.toml)Copy Anchor Link

MQTT-Anfragen (.mqtt.toml)Copy Anchor Link

Benutzername und Passwort sind die Basic-Auth der Anfrage.

MCP-Aufrufe (.mcp.toml)Copy Anchor Link

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

AssertionsCopy Anchor Link

Welche Prüfungen jedes Ziel anbietet, steht unter Skripte und Tests.

ErfassungenCopy Anchor Link

Eine Antwort ab 400 oder ein Wert, der nicht da ist, lässt die Variable, wie sie war. Siehe Erfassungen.

EinstellungenCopy Anchor Link

Siehe Anfrageeinstellungen.

AuthCopy Anchor Link

[auth] hat einen type und die Schlüssel dieses Typs. Eine Anfrage oder ein Ordner ohne [auth] übernimmt; der Standard des Arbeitsbereichs ist keine Auth.

Schreibe jedes Passwort, jedes Token und jeden Schlüssel als geheime {{variable}}. Siehe Auth.

mcp-servers/Copy Anchor Link

Eine Datei je MCP-Server; der Dateiname ist der Slug, den MCP-Aufrufe nennen.

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

Siehe Server hinzufügen.

specs/Copy Anchor Link

Spec-Dateien, wie sie sind: OpenAPI-Dokumente (.yaml, .yml, .json), GraphQL-Schemas (.graphql-SDL oder ein Introspektionsergebnis als JSON) und Protobuf-Dateien (.proto). Echolot bearbeitet sie an Ort und Stelle und behält deine Formatierung. Anfragen und Mocks nennen sie mit ihrem Pfad, etwa specs/alpenglow.yaml. Siehe Specs.

mocks/Copy Anchor Link

Eine Datei je Mock-Server und daneben seine JavaScript-Routen.

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 enthält die Routen des Mocks in JavaScript, die vor den von Hand angelegten Routen und der Spec antworten. Für die Operationen der Spec stehen Antworten nie im Mock: Beispiele gehören in die Spec. Siehe Mocks, Routen und Beispieldaten und Routen per Skript.

flows/Copy Anchor Link

Eine Datei je Flow, <slug>.flow.toml. Echolot schreibt Blöcke, Verbindungen und Notizen in fester Reihenfolge, sodass das Verschieben eines Blocks zwei Zeilen ändert.

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"

Die Arten von Blöcken und ihre Einstellungen stehen unter Blöcke.

assistant/Copy Anchor Link

Unterhaltungen mit dem Assistenten, die du im Arbeitsbereich teilst: <slug>.md zum Lesen in jedem Editor und <slug>.json, damit Echolot sie wieder öffnen kann.

Weitere DateienCopy Anchor Link

Dateien, die Echolot nicht kennt, bleiben unangetastet, sodass eine README, eine .gitignore oder Datendateien im Arbeitsbereich liegen können. Daten, die ein Agent oder ein Flow sichert (etwa exports/products.csv), landen dort, wo darum gebeten wurde, innerhalb des Arbeitsbereichs.