feat: initialize experimental agent repo

2026-06-30 14:03:49 +08:00
commit e83ac54a9e
75 changed files with 11690 additions and 0 deletions
@@ -0,0 +1,97 @@
+# Agent UI Protocol
+
+## Summary
+
+`agent-ui@1` is the experimental frontend protocol for Agent-driven UI. The
+Agent never returns executable frontend code. It invokes trusted opencode tools;
+the service maps those tool calls to `UIEnvelope` payloads; the frontend validates
+and renders known components, charts, and map actions.
+
+## SSE Event
+
+```text
+event: ui_envelope
+data: {
+  "session_id": "session-id",
+  "envelope_id": "env-id",
+  "created_at": 1710000000000,
+  "envelope": {}
+}
+```
+
+## Envelope Types
+
+```ts
+type UISurface = "chat_inline" | "side_panel" | "canvas" | "map_overlay";
+
+type UIEnvelope =
+  | {
+      kind: "registered_component";
+      schemaVersion: "agent-ui@1";
+      component: string;
+      surface: UISurface;
+      props: unknown;
+      data?: unknown;
+      fallbackText?: string;
+    }
+  | {
+      kind: "chart";
+      schemaVersion: "agent-ui@1";
+      grammar: "echarts-safe-subset";
+      surface: "chat_inline" | "side_panel" | "canvas";
+      spec: unknown;
+      data: unknown;
+      fallbackText?: string;
+    }
+  | {
+      kind: "map_action";
+      schemaVersion: "agent-ui@1";
+      action: string;
+      surface: "map_overlay";
+      params: unknown;
+      fallbackText?: string;
+    };
+```
+
+## Registry
+
+```text
+GET /api/v1/agent/chat/ui-registry
+```
+
+The registry returns the allowed chart grammar, registered components, and map
+actions. Unknown components/actions should be rejected by the frontend.
+
+Initial mappings:
+
+- `show_chart` -> `chart`
+- `locate_features` -> `map_action`
+- `zoom_to_map` -> `map_action`
+- `render_junctions` -> `map_action`
+- `apply_layer_style` -> `map_action`
+- `view_history` -> `registered_component: HistoryPanel`
+- `view_scada` -> `registered_component: ScadaPanel`
+
+`render_junctions` accepts only a `render_ref`. The frontend must resolve the
+full payload through:
+
+```text
+GET /api/v1/agent/chat/render-ref/:render_ref?session_id=:session_id
+```
+
+## State Persistence
+
+Assistant messages may contain:
+
+```ts
+uiEnvelopes?: Array<{
+  envelopeId: string;
+  createdAt: number;
+  envelope: UIEnvelope;
+  renderStatus: "pending" | "rendered" | "fallback" | "error";
+  error?: string;
+}>;
+```
+
+`tool_call` and `artifacts` remain deprecated compatibility/debug surfaces. New
+frontends should consume `ui_envelope` and `uiEnvelopes`.