Файлы рабочего пространства

Рабочее пространство — это папка с расширением .echolot с обычными файлами TOML внутри: по одному на запрос, окружение, MCP-сервер, мок и сценарий. В Finder оно выглядит как один документ; в Терминале, Git и вашем редакторе это обычная папка. Echolot каждый раз записывает каждый файл одинаково (ключи в фиксированном порядке, значения по умолчанию не пишутся), поэтому изменение в приложении даёт небольшое изменение в диффе. См. Git и команды.

Alpenglow.echolot/
  workspace.toml                     рабочее пространство: ID, название, переменные, авторизация, агенты, прокси, сертификаты
  environments/
    staging.toml                     одно окружение
  requests/
    _folder.toml                     порядок верхнего уровня
    _folder.pre.js                   скрипт рабочего пространства перед запросом (и _folder.test.js)
    auth/
      _folder.toml                   папка: название, порядок, документация, переменные, авторизация
      sign-in.req.toml               HTTP-запрос
      sign-in.body.json              его тело
      sign-in.pre.js                 его скрипт перед запросом
      sign-in.test.js                его тестовый скрипт
    catalog/
      search-products.gql.toml       запрос GraphQL
      search-products.graphql        его запрос на языке GraphQL
  mcp-servers/
    alpenglow-mcp.toml               MCP-сервер
  specs/
    alpenglow.yaml                   документ OpenAPI
    shop.graphql                     схема GraphQL
    inventory.proto                  файл protobuf
  mocks/
    shop.toml                        мок-сервер: настройки и маршруты
    shop.js                          его маршруты на JavaScript
  flows/
    place-test-order.flow.toml       сценарий
  assistant/
    checking-orders.md               общий разговор с Ассистентом, для чтения
    checking-orders.json             он же, чтобы открыть в приложении

Правила для каждого файлаCopy Anchor Link

• Файлы — TOML 1.0 в кодировке UTF-8.
• Каждый начинается с echolot = 1 — версии формата. Файл с большим номером сохранён более новым Echolot; об этом Echolot сообщает вместо того, чтобы открыть его.
• Имена файлов — slug: строчные буквы, цифры и дефисы, не более 80 символов, составленные из названия элемента (Sign in превращается в sign-in). Само название хранится в ключе name.
• Пути между элементами — это их slug, соединённые через /, относительно requests/: auth/sign-in, orders.
• Текстовые поля могут содержать {{variables}} и динамические значения.
• Списки сущностей — массивы таблиц TOML ([[headers]]). Всё, у чего enabled = false, сохраняется, но выключено; без этого ключа включено.

Что никогда не попадает в файлыCopy Anchor Link

• Секретные значения. Секретная переменная записывается по имени с secret = true и без значения; значение хранится в Связке ключей на вашем Mac. В полях, где нужен секрет (пароль, пароль прокси, секрет клиента), должна стоять {{variable}}, которая является секретом. Echolot предлагает перенести введённый вами пароль в Связку ключей, а при импорте делает это сам. См. секреты.
• Токены OAuth и входы в MCP: в Связке ключей.
• Значения, которые скрипты задают через pm.environment.set и подобное: они живут, пока открыто окно или выполняется команда.
• История и ответы: в Application Support на вашем Mac, по одной истории на рабочее пространство. См. историю.
• Ваша собственная раскладка: расположение областей и их размеры, открытые вкладки, выбранное вами окружение.

Поэтому рабочее пространство можно безопасно коммитить и передавать. Каждый участник команды задаёт свои секретные значения сам.

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

ПроксиCopy Anchor Link

СертификатыCopy Anchor Link

Каждая таблица [[certificates]] — правило для одного хоста:

АгентыCopy Anchor Link

[agents] задаёт, что ИИ-агентам разрешено делать в этом рабочем пространстве через MCP-сервер Echolot и Ассистента. См. агентов.

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

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

Виды действий: read, safe-send, unsafe-send, protected-send, new-host, workspace-write и destructive. Более строгое правило действует всегда. Более мягкое действует, только когда вы ему доверитесь (приложение спросит; командной строке нужен --trust-workspace-policy). Для protected-send и new-host нельзя задать allow.

environments/Copy Anchor Link

По одному файлу на окружение; имя файла — его slug, который используется в --env.

echolot = 1
name = "Production"
protected = true

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

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

ПеременныеCopy Anchor Link

Одинаково в workspace.toml, окружениях, папках и запросах:

requests/Copy Anchor Link

В папке requests лежит дерево, которое вы видите в боковой панели. Каждая вложенная папка — папка дерева, каждый файл запроса — запрос. Вид запроса определяется суффиксом файла:

Рядом с запросом, с тем же slug:

_folder.tomlCopy Anchor Link

Он есть у каждой папки, а также у самой requests/ — для верхнего уровня.

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

Рядом _folder.pre.js и _folder.test.js — скрипты папки; в requests/ это скрипты рабочего пространства. Они выполняются для каждого запроса внутри, от скрипта рабочего пространства вниз до собственного скрипта запроса. У папки, которая следует спецификации, есть ещё _spec-lock.json — то, что она в последний раз взяла из спецификации; пусть им занимается Echolot.

Ключи любого запросаCopy 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-запросы (.req.toml)Copy Anchor Link

Таблица [body] принимает одну из трёх форм:

Запросы 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"
}"""

Запросы gRPC (.grpc.toml)Copy Anchor Link

Запросы WebSocket (.ws.toml)Copy Anchor Link

Запросы Socket.IO (.sio.toml)Copy Anchor Link

Запросы MQTT (.mqtt.toml)Copy Anchor Link

Имя пользователя и пароль — это авторизация Basic запроса.

Вызовы MCP (.mcp.toml)Copy Anchor Link

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

ПроверкиCopy Anchor Link

О том, какие проверки доступны для каждого объекта, см. скрипты и тесты.

ЗахватыCopy Anchor Link

Ответ с кодом 400 и выше или отсутствующее значение оставляют переменную как была. См. захваты.

НастройкиCopy Anchor Link

См. настройки запроса.

АвторизацияCopy Anchor Link

У [auth] есть type и ключи этого типа. Запрос или папка без [auth] наследуют авторизацию; по умолчанию в рабочем пространстве её нет.

Записывайте каждый пароль, токен и ключ как секретную {{variable}}. См. авторизацию.

mcp-servers/Copy Anchor Link

По одному файлу на MCP-сервер; имя файла — slug, на который ссылаются вызовы MCP.

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

См. добавление серверов.

specs/Copy Anchor Link

Файлы спецификаций как есть: документы OpenAPI (.yaml, .yml, .json), схемы GraphQL (SDL в .graphql или результат интроспекции в JSON) и файлы protobuf (.proto). Echolot правит их на месте и сохраняет ваше форматирование. Запросы и моки называют их по пути, например specs/alpenglow.yaml. См. спецификации.

mocks/Copy Anchor Link

По одному файлу на мок-сервер, а рядом с ним — его маршруты на JavaScript.

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 хранятся маршруты мока на JavaScript, которые отвечают раньше маршрутов, созданных вручную, и спецификации. Для операций спецификации ответы в моке никогда не хранятся: примеры попадают в спецификацию. См. моки, маршруты и тестовые данные и маршруты на JavaScript.

flows/Copy Anchor Link

По одному файлу на сценарий, <slug>.flow.toml. Echolot записывает блоки, связи и заметки в фиксированном порядке, поэтому перемещение блока меняет две строки.

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"

Виды блоков и их настройки описаны на странице блоки.

assistant/Copy Anchor Link

Разговоры с Ассистентом, которыми вы делитесь в рабочем пространстве: <slug>.md — для чтения в любом редакторе, <slug>.json — чтобы Echolot мог открыть их снова.

Другие файлыCopy Anchor Link

Файлы, которых Echolot не знает, остаются нетронутыми, так что в рабочем пространстве могут лежать README, .gitignore или файлы с данными. Данные, которые сохраняет агент или сценарий (например, exports/products.csv), попадают туда, куда их попросили записать, внутри рабочего пространства.