HansaChat

Documentation

Ieșire JSON și automatizare

Plicul de ieșire, codurile de ieșire, formatele și tipare de scriptare sigure.

CLI-ul este construit pentru a fi citit de scripturi și agenți. JSON este ieșirea implicită; tabelele și JSON-ul delimitat pe rânduri sunt opționale.

Plicul

Fiecare comandă reușită afișează un singur obiect JSON pe stdout:

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

changed vă spune dacă comanda a modificat efectiv ceva — o valoare false înseamnă că starea dorită exista deja. data conține rezultatul: liste de canale sau mesaje, un mesaj cu conținutul său ca JSON imbricat real, confirmări de comandă.

Erorile merg la stderr ca JSON și nu ating niciodată stdout:

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

Coduri de ieșire

Cod Semnificație
0 Reușită, inclusiv o operațiune fără efect (changed: false)
1 Eroare internă
2 Eroare de utilizare sau de configurare
3 Autentificare necesară sau eșuată
4 Acces refuzat sau precondiție neîndeplinită
5 Negăsit sau conflict
6 Expirare, indisponibil sau limitare de rată

Un model de script robust:

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

Formate de ieșire

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

Opțiuni globale utile

--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

Variabila de mediu HANSA_CONFIG reloca întregul fișier de context, ceea ce le permite joburilor paralele să utilizeze contexte izolate. Furnizarea de token-uri headless și comportamentul lanțului de chei sunt descrise în autentificare.

Note de securitate

  • Datele de autentificare se află doar în lanțul de chei al sistemului de operare sau în mediul procesului — niciodată în ieșire, jurnale sau fișierul de context.
  • Diagnosticarea --verbose filtrează anteturile de autorizare, datele de autentificare introduse și răspunsurile de reînnoire.
  • Toți identificatorii sunt emiși ca șiruri JSON, marcajele de timp ca UTC RFC3339; conținutul mesajului apare ca JSON imbricat real, nu ca un șir între ghilimele.