HansaChat

Documentation

JSON изход и автоматизация

Изходен конверт, кодове за изход, формати и надеждни шаблони за скриптове.

CLI е създаден да бъде четен от скриптове и агенти. JSON е изходът по подразбиране; таблиците и JSON разделени по редове са по избор.

Конвертът

Всяка успешна команда отпечатва един JSON обект на stdout:

{
  "ok": true,
  "schema_version": "1",
  "workspace": "yourworkspace",
  "domain": "yourworkspace.hansa.chat",
  "changed": false,
  "data": { }
}

changed ви казва дали командата действително е променила нещо — false означава, че желаното състояние вече е съществувало. data съдържа резултата: списъци с канали или съобщения, съобщение с неговото съдържание като истински вложен JSON, потвърждения на команди.

Грешките отиват на stderr като JSON и никога не докосват stdout:

{
  "ok": false,
  "schema_version": "1",
  "error": { "code": "unauthenticated", "message": "…", "retryable": false }
}

Кодове за изход

Код Значение
0 Успех, включително no-op (changed: false)
1 Вътрешна грешка
2 Грешка в употребата или в конфигурацията
3 Необходимо е удостоверяване или то се провали
4 Отнето разрешение или неизпълнено предусловие
5 Не е намерено или конфликт
6 Изтекло време, недостъпност или ограничение по честота

Надежден шаблон за скрипт:

if hansa chat channels ensure --name Deploy --type public >/dev/null 2>&1; then
  echo "channel ready"
fi

Формати на изхода

hansa chat channels list -o json    # default, one envelope
hansa chat channels list -o jsonl   # one JSON object per line
hansa chat channels list -o table   # aligned text columns for humans

Полезни глобални флагове

--workspace <alias-or-domain>   # override the workspace for one command
--timeout 30s                   # network timeout
--config /path/config.json      # custom context file (default: OS config dir)
--verbose                       # diagnostics to stderr, secrets filtered

Променливата на средата HANSA_CONFIG премества целия контекстен файл, което позволява на паралелните задачи да използват изолирани контексти. Подаването на headless токени и поведението на ключодържателя са описани в Удостоверяване и работни пространства.

Бележки за сигурността

  • Данните за удостоверяване живеят само в ключодържателя на ОС или в средата на процеса — никога в изхода, в дневниците или в контекстния файл.
  • Диагностиката с --verbose филтрира заглавните редове за оторизация, входните данни за удостоверяване и отговорите за обновяване.
  • Всички идентификатори се издават като JSON низове, а времевите отпечатъци като UTC RFC3339; съдържанието на съобщенията се появява като истински вложен JSON, а не като низ в кавички.