@qfei-design/make-ai-assistant 0.1.0

package/PUBLIC_API.md

@@ -0,0 +1,120 @@
+# Public API Contract
+
+## Entrypoints
+
+- `@qfei-design/make-ai-assistant`：headless Artifact、会话、模板注册和 transport 合同。
+- `@qfei-design/make-ai-assistant/react`：React 助手壳、ArtifactRenderer 和平台模板。
+- `@qfei-design/make-ai-assistant/sse`：基于 Fetch、ReadableStream 的浏览器/现代 Node SSE transport；公开声明不要求 TypeScript `DOM` lib。
+- `@qfei-design/make-ai-assistant/testing`：Mock transport 和通用 fixtures，仅用于开发、测试与 Gallery。
+- `@qfei-design/make-ai-assistant/styles.css`：助手壳与默认模板样式。
+- `@qfei-design/make-ai-assistant/artifact-v1.schema.json`：服务端与工具使用的机器可读 Schema。
+
+禁止宿主从 `src`、`dist` 或包内部路径导入。
+
+## Headless exports
+
+- `validateArtifact` / `parseArtifact`
+- `createArtifactTemplateRegistry`
+- `extendArtifactTemplateRegistry`
+- `resolveArtifactTemplate`
+- `createArtifactCapabilities`
+- `createAssistantConversationState`
+- `appendUserMessage`
+- `reduceAssistantEvent`
+- `parseAssistantEvent`
+- `AssistantTransport`
+- `AssistantEvent`
+- `MakeAiArtifact` 及所有 V1 Artifact 类型
+- `MakeAssistantHostContext`
+- `ArtifactAction` / `ArtifactActionHandler`
+- `ArtifactActionErrorHandler`
+
+根入口没有 React 或 DOM 类型依赖，可以在 Service、测试和协议工具中使用。需要直接使用
+Fetch SSE 实现时，从 `/sse` 入口导入 `createSseAssistantTransport`。
+
+## React exports
+
+- `MakeAiAssistant`：默认浮动入口与右侧抽屉；支持受控开关和自定义 launcher。
+- `AssistantPanel`：不带 Drawer 的嵌入式会话面板。
+- `ArtifactRenderer`：注册表驱动的单 Artifact 渲染器。
+- `createPlatformArtifactRegistry`
+- `platformArtifactTemplates`
+- `ReactArtifactTemplate`
+- `ReactArtifactTemplateRegistry`
+- `formatArtifactValue`
+
+`ArtifactRenderer`、`AssistantPanel` 和 `MakeAiAssistant` 支持 `onActionError`。当宿主
+`onAction` 同步抛错或返回 rejected Promise 时，包会把错误、动作和上下文交还给
+`onActionError`；未提供回调时只记录不含敏感上下文的失败日志，不产生未处理的
+Promise rejection。`onActionError` 自身同步抛错或返回 rejected Promise 时也会被包隔离，
+不会污染宿主的全局未处理异常。
+
+## AssistantTransport
+
+```ts
+interface AssistantTransport {
+  run(
+    request: AssistantRunRequest,
+    options?: { signal?: AbortSignal },
+  ): AsyncIterable<AssistantEvent>;
+}
+```
+
+传输边界支持中断。UI 在停止时会立即回到可输入状态、忽略迟到事件，并尝试关闭
+AsyncIterator，因此即使自定义 transport 没有及时响应 `AbortSignal`，也不会一直卡在
+streaming。真实实现可以读取 fetch SSE，也可以把 AG-UI runtime 事件归一化为包事件。
+UI 不直接请求固定 URL。
+
+`/sse` 的 `createSseAssistantTransport` 实现 `docs/backend-contract.md` 中的标准命名 SSE
+事件；宿主只配置 Service endpoint、credentials、可选 headers 和单事件字符上限
+`maxEventCharacters`（默认 1,000,000）。公开 `SseFetch`、headers 和 credentials 类型由包
+自身声明，可在只启用 `ES2022` + Node types 的 TypeScript 项目中消费。非标准或旧协议由
+宿主 adapter 转换。
+
+SSE 流必须以 `run.complete`、`run.cancelled` 或 `error` 结束。连接在终止事件前关闭会
+被视为可重试的 transport 错误，避免 UI 永久停留在 streaming 状态。终止事件、解析
+失败、超限、Abort 和消费者提前结束都会取消并释放 response reader。
+
+用户输入与单次响应文本默认各限制为 100,000 字符。Artifact 的集合、字符串、JSON
+深度/节点/累计文本和校验问题数量也有固定预算；超限输入会被拒绝，不会继续遍历或
+进入 React 模板。React UI 会在消费任意 `AssistantTransport` 时再次调用
+`parseArtifact`，自定义 transport 也不能绕过运行时白名单。
+
+自定义 transport 抛出的任意异常不会直接展示给用户；UI 只展示包自身的可控校验/
+限制消息或通用“连接失败，请重试”，完整内部错误应由宿主在 transport 边界记录。
+
+单个 run 最多接收 20 条 assistant message 和 50 个 Artifact。根入口、`/sse` 和
+`/testing` 可在没有安装 React 的 headless/Node 工程中单独使用；React 与 ReactDOM 是
+可选 peer，只有使用 `/react` 时才需要安装。
+
+自定义 transport 必须保持 `message.start -> delta/artifact -> message.complete` 的消息
+顺序，并保证同一会话内 message id、同一 run 内 Artifact id 唯一，且 run id 前后一致；
+UI 会拒绝孤立、迟到、重复或跨 run 混入的事件，避免静默丢数据和 React key 冲突。
+输入和流式文本长度按 Unicode code point 计算，与 Artifact 字符上限语义一致。
+
+所有 transport 事件在进入 UI 前都会由 headless `parseAssistantEvent` 检查事件类型、
+字段白名单、必填值、identifier 长度与 Artifact；宿主 adapter 也可以直接复用该函数。
+
+## Host responsibilities
+
+Host app provides context, transport, action execution, permission checks, Service routes, authentication and routing. The package provides the presentation runtime and contracts, but does not access Make API and does not execute server-generated HTML.
+
+Artifact 的 `action.target` 只是 JSON 意图。宿主必须根据当前权限和支持能力验证后再执行。
+组件只说明上下文会随请求发送；数据权限以宿主服务端重新鉴权的结果为准，包本身不作
+权限承诺。
+
+`presentation.density` 会映射为默认 Artifact 的 compact/comfortable 密度，
+`action.appearance` 会映射为 primary/secondary/link 视觉层级；两者都只是已校验的样式语义，
+不会触发动态代码。独立使用 `AssistantPanel` 或 `ArtifactRenderer` 时仍会获得包级主题变量、
+盒模型和键盘焦点样式。
+
+模板注册表会在运行时拒绝未知 kind、非有限 priority 以及非法 render/canRender 回调，
+并把注册项复制冻结；调用方不能在注册后通过突变改变全局模板选择。
+
+## Compatibility
+
+- npm 包版本与 Artifact schemaVersion 独立；
+- 当前只接受 `schemaVersion: "1.0"`；
+- 未注册模板安全降级；
+- `presentation.template` 不会触发代码加载；
+- 新模板不得复用已有 id。

package/README.md

@@ -0,0 +1,125 @@
+# @qfei-design/make-ai-assistant
+
+面向 Make Console 与所有 Make App 的 AI 助手前端包。它提供统一的右下角浮动入口、右侧抽屉、流式会话状态、版本化 Artifact 协议、平台默认结果模板和 App 扩展机制。
+
+## Install
+
+```bash
+pnpm add @qfei-design/make-ai-assistant@^0.1.0
+```
+
+## Quick start
+
+```tsx
+import { MakeAiAssistant } from "@qfei-design/make-ai-assistant/react";
+import "@qfei-design/make-ai-assistant/styles.css";
+
+export function AppAssistant() {
+  return (
+    <MakeAiAssistant
+      context={{
+        app: { id: "sales-app", name: "销售管理" },
+        location: { pathname: window.location.pathname },
+        locale: "zh-CN",
+        timezone: "Asia/Shanghai",
+      }}
+      transport={assistantTransport}
+      suggestions={["总结当前页面", "找出需要关注的记录"]}
+      onAction={(action) => hostActionAdapter.execute(action)}
+      onActionError={(error, action) => hostActionAdapter.reportFailure(error, action)}
+    />
+  );
+}
+```
+
+`MakeAiAssistant` 默认渲染右下角动效入口和右侧抽屉。宿主可以使用 `open` / `onOpenChange` 受控管理开关，也可以用 `AssistantPanel` 嵌入自己的容器。
+
+## Package provides
+
+- Artifact V1 类型、运行时校验与 JSON Schema；
+- Artifact 模板注册、能力协商和稳定降级；
+- 纯会话 reducer 与 `AssistantTransport` 合同；
+- `/sse` 入口提供可直接配置 endpoint 的 `createSseAssistantTransport`；
+- `MakeAiAssistant`、`AssistantPanel` 和 `ArtifactRenderer`；
+- metric、comparison、trend、ranking、record-list、notice 六类默认模板；
+- Mock transport 与 Gallery fixtures；
+- 可由宿主覆盖的 `--make-ai-*` CSS 主题变量。
+
+## Host app provides
+
+- 当前 App、路径、Entity/Record/View 等最小上下文；
+- 实现 `AssistantTransport` 的 Mock、SSE 或 AG-UI 适配器；
+- Artifact 动作到宿主路由、命令与权限检查的映射；
+- Service `/api`、认证、数据查询、模型运行和服务端权限校验；
+- 可选的 App 领域模板和主题变量。
+
+The package does not access Make API, does not hold or forward Make tokens, and does not execute server-generated HTML, JSX, CSS, or JavaScript.
+
+React/ReactDOM 是 UI 入口的可选 peer dependency；只使用根入口、`/sse` 或 `/testing`
+的 Service/Node 工具不需要安装 React。
+
+只使用 `AssistantPanel` 做嵌入式接入，或单独使用 `ArtifactRenderer` 时，同一个
+`styles.css` 入口仍会提供默认主题变量、盒模型、可见焦点和 reduced-motion 处理。
+
+## Artifact template extension
+
+```tsx
+import {
+  createPlatformArtifactRegistry,
+  platformArtifactTemplates,
+  type ReactArtifactTemplate,
+} from "@qfei-design/make-ai-assistant/react";
+
+const appTemplate: ReactArtifactTemplate = {
+  id: "sales.metric.target-progress",
+  kinds: ["metric"],
+  priority: 50,
+  canRender: (artifact, context) =>
+    context.app.id === "sales-app" && artifact.meta?.semantic === "target-progress",
+  render: (artifact) => <SalesTargetProgress artifact={artifact} />,
+};
+
+const registry = createPlatformArtifactRegistry([
+  ...platformArtifactTemplates,
+  appTemplate,
+]);
+```
+
+后端可以通过 `presentation.template` 请求某个已协商模板；若不匹配，前端会按优先级和 `canRender` 选择其他安全模板。
+模板注册时会校验 kind、priority 和回调类型，并保存只读快照。
+
+## Transport
+
+`AssistantTransport.run()` 接收消息、上下文和前端能力目录，返回 `AsyncIterable<AssistantEvent>`。Mock、原生 SSE 和 AG-UI 都应适配到同一合同，因此更换后端不会改 UI。
+
+标准 SSE 后端可直接使用：
+
+```ts
+import { createSseAssistantTransport } from "@qfei-design/make-ai-assistant/sse";
+
+const assistantTransport = createSseAssistantTransport({
+  endpoint: "/api/assistant/runs",
+  credentials: "include",
+  maxEventCharacters: 1_000_000,
+});
+```
+
+需要兼容已有事件协议时，在宿主内实现薄 adapter；不要修改聊天组件或复制 Artifact 模板。
+
+流必须以 `run.complete`、`run.cancelled` 或 `error` 终止；异常断流会进入可重试错误状态。
+停止生成会立即解除输入锁定并丢弃迟到事件；标准 SSE transport 会同步取消底层 reader。
+`/sse` 的公开类型不依赖 TypeScript `DOM` lib，现代 Node 宿主也可直接消费。
+调用前已经取消的 `AbortSignal` 不会触发网络请求。
+助手只发送宿主提供的上下文，实际数据权限始终由宿主 Service 在服务端重新校验。
+
+生产接口建议和 SSE 事件定义见仓库 `docs/backend-contract.md`。AG-UI 在这里是可选的前后端事件协议，不是生成 React 组件的 UI 库。
+
+## Validation
+
+```bash
+pnpm test
+pnpm typecheck
+pnpm build
+```
+
+发布统一走 GitLab CI；不要从功能分支本地执行 npm publish。

package/artifact-v1.schema.json

@@ -0,0 +1,318 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qfei-design.github.io/make-ai-assistant/artifact-v1.schema.json",
+  "title": "Make AI Assistant Artifact V1",
+  "oneOf": [
+    { "$ref": "#/$defs/metric" },
+    { "$ref": "#/$defs/comparison" },
+    { "$ref": "#/$defs/trend" },
+    { "$ref": "#/$defs/ranking" },
+    { "$ref": "#/$defs/recordList" },
+    { "$ref": "#/$defs/notice" }
+  ],
+  "$defs": {
+    "base": {
+      "type": "object",
+      "required": ["schemaVersion", "id", "kind", "data"],
+      "properties": {
+        "schemaVersion": { "const": "1.0" },
+        "id": { "type": "string", "minLength": 1, "maxLength": 20000 },
+        "kind": { "type": "string" },
+        "data": { "type": "object" },
+        "title": { "type": "string", "maxLength": 20000 },
+        "summary": { "type": "string", "maxLength": 20000 },
+        "presentation": {
+          "type": "object",
+          "properties": {
+            "template": { "type": "string", "minLength": 1, "maxLength": 20000 },
+            "density": { "enum": ["compact", "comfortable"] }
+          },
+          "additionalProperties": false
+        },
+        "actions": {
+          "type": "array",
+          "maxItems": 10,
+          "items": { "$ref": "#/$defs/action" }
+        },
+        "meta": { "$ref": "#/$defs/jsonObject" }
+      },
+      "additionalProperties": false
+    },
+    "jsonValue": {
+      "anyOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string", "maxLength": 20000 },
+        {
+          "type": "array",
+          "maxItems": 10000,
+          "items": { "$ref": "#/$defs/jsonValue" }
+        },
+        { "$ref": "#/$defs/jsonObject" }
+      ]
+    },
+    "jsonObject": {
+      "type": "object",
+      "maxProperties": 10000,
+      "propertyNames": { "maxLength": 20000 },
+      "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+    },
+    "format": {
+      "type": "object",
+      "properties": {
+        "style": { "enum": ["decimal", "currency", "percent"] },
+        "currency": { "type": "string", "minLength": 1, "maxLength": 20000 },
+        "precision": { "type": "integer", "minimum": 0, "maximum": 20 },
+        "unit": { "type": "string", "maxLength": 20000 }
+      },
+      "additionalProperties": false
+    },
+    "action": {
+      "type": "object",
+      "required": ["id", "label", "intent", "target"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 20000 },
+        "label": { "type": "string", "minLength": 1, "maxLength": 20000 },
+        "intent": { "enum": ["navigate", "open-record", "open-list", "invoke"] },
+        "target": { "$ref": "#/$defs/jsonObject" },
+        "appearance": { "enum": ["primary", "secondary", "link"] }
+      },
+      "additionalProperties": false
+    },
+    "metric": {
+      "allOf": [
+        { "$ref": "#/$defs/base" },
+        {
+          "properties": {
+            "kind": { "const": "metric" },
+            "data": {
+              "type": "object",
+              "required": ["value"],
+              "properties": {
+                "value": { "type": ["number", "string"], "maxLength": 20000 },
+                "format": { "$ref": "#/$defs/format" },
+                "delta": {
+                  "type": "object",
+                  "required": ["value"],
+                  "properties": {
+                    "value": { "type": "number" },
+                    "format": { "enum": ["decimal", "percent"] },
+                    "direction": { "enum": ["up", "down", "flat"] },
+                    "label": { "type": "string", "maxLength": 20000 }
+                  },
+                  "additionalProperties": false
+                },
+                "context": { "type": "string", "maxLength": 20000 }
+              },
+              "additionalProperties": false
+            }
+          }
+        }
+      ]
+    },
+    "comparisonItem": {
+      "type": "object",
+      "required": ["id", "label", "value"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 20000 },
+        "label": { "type": "string", "minLength": 1, "maxLength": 20000 },
+        "value": { "type": ["number", "string"], "maxLength": 20000 },
+        "format": { "$ref": "#/$defs/format" },
+        "hint": { "type": "string", "maxLength": 20000 }
+      },
+      "additionalProperties": false
+    },
+    "comparison": {
+      "allOf": [
+        { "$ref": "#/$defs/base" },
+        {
+          "properties": {
+            "kind": { "const": "comparison" },
+            "data": {
+              "type": "object",
+              "required": ["items"],
+              "properties": {
+                "items": {
+                  "type": "array",
+                  "minItems": 1,
+                  "maxItems": 24,
+                  "items": { "$ref": "#/$defs/comparisonItem" }
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        }
+      ]
+    },
+    "trend": {
+      "allOf": [
+        { "$ref": "#/$defs/base" },
+        {
+          "properties": {
+            "kind": { "const": "trend" },
+            "data": {
+              "type": "object",
+              "required": ["series"],
+              "properties": {
+                "series": {
+                  "type": "array",
+                  "minItems": 1,
+                  "maxItems": 8,
+                  "items": {
+                    "type": "object",
+                    "required": ["id", "label", "points"],
+                    "properties": {
+                      "id": { "type": "string", "minLength": 1, "maxLength": 20000 },
+                      "label": { "type": "string", "minLength": 1, "maxLength": 20000 },
+                      "format": { "$ref": "#/$defs/format" },
+                      "points": {
+                        "type": "array",
+                        "minItems": 1,
+                        "maxItems": 120,
+                        "items": {
+                          "type": "object",
+                          "required": ["x", "y"],
+                          "properties": {
+                            "x": { "type": ["number", "string"], "maxLength": 20000 },
+                            "y": { "type": "number" }
+                          },
+                          "additionalProperties": false
+                        }
+                      }
+                    },
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        }
+      ]
+    },
+    "ranking": {
+      "allOf": [
+        { "$ref": "#/$defs/base" },
+        {
+          "properties": {
+            "kind": { "const": "ranking" },
+            "data": {
+              "type": "object",
+              "required": ["items"],
+              "properties": {
+                "items": {
+                  "type": "array",
+                  "minItems": 1,
+                  "maxItems": 50,
+                  "items": {
+                    "type": "object",
+                    "required": ["id", "label", "value"],
+                    "properties": {
+                      "id": { "type": "string", "minLength": 1, "maxLength": 20000 },
+                      "label": { "type": "string", "minLength": 1, "maxLength": 20000 },
+                      "value": { "type": "number" },
+                      "format": { "$ref": "#/$defs/format" },
+                      "description": { "type": "string", "maxLength": 20000 }
+                    },
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        }
+      ]
+    },
+    "recordList": {
+      "allOf": [
+        { "$ref": "#/$defs/base" },
+        {
+          "properties": {
+            "kind": { "const": "record-list" },
+            "data": {
+              "type": "object",
+              "required": ["entity", "columns", "records"],
+              "properties": {
+                "entity": {
+                  "type": "object",
+                  "required": ["key"],
+                  "properties": {
+                    "key": { "type": "string", "minLength": 1, "maxLength": 20000 },
+                    "label": { "type": "string", "maxLength": 20000 }
+                  },
+                  "additionalProperties": false
+                },
+                "columns": {
+                  "type": "array",
+                  "minItems": 1,
+                  "maxItems": 20,
+                  "items": {
+                    "type": "object",
+                    "required": ["key", "label"],
+                    "properties": {
+                      "key": { "type": "string", "minLength": 1, "maxLength": 20000 },
+                      "label": { "type": "string", "minLength": 1, "maxLength": 20000 },
+                      "format": { "$ref": "#/$defs/format" }
+                    },
+                    "additionalProperties": false
+                  }
+                },
+                "records": {
+                  "type": "array",
+                  "maxItems": 100,
+                  "items": {
+                    "type": "object",
+                    "required": ["id", "values"],
+                    "properties": {
+                      "id": { "type": "string", "minLength": 1, "maxLength": 20000 },
+                      "title": { "type": "string", "maxLength": 20000 },
+                      "values": {
+                        "type": "object",
+                        "maxProperties": 100,
+                        "propertyNames": { "maxLength": 20000 },
+                        "additionalProperties": {
+                          "anyOf": [
+                            { "type": "string", "maxLength": 20000 },
+                            { "type": "number" },
+                            { "type": "boolean" },
+                            { "type": "null" }
+                          ]
+                        }
+                      },
+                      "action": { "$ref": "#/$defs/action" }
+                    },
+                    "additionalProperties": false
+                  }
+                },
+                "total": { "type": "integer", "minimum": 0 }
+              },
+              "additionalProperties": false
+            }
+          }
+        }
+      ]
+    },
+    "notice": {
+      "allOf": [
+        { "$ref": "#/$defs/base" },
+        {
+          "properties": {
+            "kind": { "const": "notice" },
+            "data": {
+              "type": "object",
+              "required": ["tone", "body"],
+              "properties": {
+                "tone": { "enum": ["info", "success", "warning", "danger"] },
+                "body": { "type": "string", "minLength": 1, "maxLength": 20000 }
+              },
+              "additionalProperties": false
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/capabilities.json

@@ -0,0 +1,60 @@
+{
+  "packageName": "@qfei-design/make-ai-assistant",
+  "catalogVersion": 1,
+  "features": [
+    {
+      "id": "artifact-core",
+      "name": "Artifact V1 core",
+      "category": "core",
+      "status": "experimental",
+      "summary": "Versioned semantic result contract, runtime validation and JSON Schema.",
+      "docPath": "PUBLIC_API.md",
+      "relatedExports": ["validateArtifact", "parseArtifact", "MakeAiArtifact"]
+    },
+    {
+      "id": "artifact-registry",
+      "name": "Artifact template registry",
+      "category": "core",
+      "status": "experimental",
+      "summary": "Deterministic template selection, extension and capability negotiation.",
+      "docPath": "PUBLIC_API.md",
+      "relatedExports": ["createArtifactTemplateRegistry", "resolveArtifactTemplate", "createArtifactCapabilities"]
+    },
+    {
+      "id": "react-shell",
+      "name": "React assistant shell",
+      "category": "ui",
+      "status": "experimental",
+      "summary": "Floating launcher, right-side drawer, embedded panel and streaming conversation UI.",
+      "docPath": "README.md",
+      "relatedExports": ["MakeAiAssistant", "AssistantPanel"]
+    },
+    {
+      "id": "platform-templates",
+      "name": "Platform Artifact templates",
+      "category": "ui",
+      "status": "experimental",
+      "summary": "Default metric, comparison, trend, ranking, record-list and notice renderers.",
+      "docPath": "PUBLIC_API.md",
+      "relatedExports": ["ArtifactRenderer", "createPlatformArtifactRegistry", "platformArtifactTemplates"]
+    },
+    {
+      "id": "sse-transport",
+      "name": "SSE transport",
+      "category": "integration",
+      "status": "experimental",
+      "summary": "Abortable fetch SSE adapter for the standard Make AI Assistant event contract.",
+      "docPath": "PUBLIC_API.md",
+      "relatedExports": ["@qfei-design/make-ai-assistant/sse:createSseAssistantTransport", "AssistantTransport"]
+    },
+    {
+      "id": "mock-transport",
+      "name": "Testing adapter",
+      "category": "testing",
+      "status": "experimental",
+      "summary": "Protocol-compatible mock transport and generic fixtures for App integration before backend readiness.",
+      "docPath": "README.md",
+      "relatedExports": ["createMockAssistantTransport", "artifactFixtures"]
+    }
+  ]
+}