HansaChat

Documentation

Výstup JSON a automatizácia

Výstupná obálka, návratové kódy, formáty a bezpečné vzory pre skripty.

CLI je navrhnuté na čítanie skriptami a agentmi. Predvoleným výstupom je JSON; tabuľky a JSON po riadkoch sú voliteľné.

Obálka

Každý úspešný príkaz vypíše na stdout jeden objekt JSON:

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

Hodnota changed hovorí, či príkaz niečo skutočne zmenil — false znamená, že požadovaný stav už existoval. data obsahuje výsledok: zoznamy kanálov alebo správ, správu s obsahom ako skutočným vnoreným JSON, potvrdenia príkazov.

Chyby smerujú na stderr ako JSON a stdout sa nikdy nedotknú:

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

Návratové kódy

Kód Význam
0 Úspech vrátane no-op (changed: false)
1 Interná chyba
2 Chyba použitia alebo konfigurácie
3 Vyžaduje sa autentifikácia alebo zlyhala
4 Prístup zamietnutý alebo zlyhala podmienka
5 Nenájdené alebo konflikt
6 Časový limit, nedostupnosť alebo obmedzenie frekvencie

Odolný vzor pre skript:

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

Výstupné formáty

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

Užitočné globálne voľby

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

Premenná prostredia HANSA_CONFIG premiestni celý kontextový súbor, vďaka čomu môžu paralelné úlohy používať izolované kontexty. Poskytovanie tokenov bez kľúčenky a správanie kľúčenky sú popísané v článku Autentifikácia a workspacy.

Bezpečnostné poznámky

  • Prihlasovacie údaje žijú len v kľúčenke operačného systému alebo v prostredí procesu — nikdy vo výstupe, v logoch ani v kontextovom súbore.
  • Diagnostika --verbose filtruje hlavičky autorizácie, zadané prihlasovacie údaje a odpovede na obnovenie.
  • Všetky identifikátory sa vydávajú ako reťazce JSON, časové značky ako UTC RFC3339; obsah správ sa zobrazuje ako skutočný vnorený JSON, nie ako reťazec v úvodzovkách.