@qfei-design/make-ai-assistant 0.1.0

package/dist/testing.mjs

@@ -0,0 +1,132 @@
+const s = {
+  metric: {
+    schemaVersion: "1.0",
+    id: "fixture-metric",
+    kind: "metric",
+    title: "本月完成金额",
+    summary: "统计范围：本月，状态：已完成",
+    data: {
+      value: 1286420,
+      format: { style: "currency", currency: "CNY", precision: 0 },
+      delta: { value: 18.4, format: "percent", direction: "up", label: "较上月" }
+    },
+    actions: [
+      {
+        id: "metric-detail",
+        label: "查看明细",
+        intent: "open-list",
+        target: { entityKey: "example_record", filterKey: "completed" }
+      }
+    ]
+  },
+  comparison: {
+    schemaVersion: "1.0",
+    id: "fixture-comparison",
+    kind: "comparison",
+    title: "状态金额对比",
+    data: {
+      items: [
+        { id: "completed", label: "已完成", value: 1286420, format: { style: "currency", currency: "CNY", precision: 0 } },
+        { id: "pending", label: "待处理", value: 368200, format: { style: "currency", currency: "CNY", precision: 0 } }
+      ]
+    }
+  },
+  trend: {
+    schemaVersion: "1.0",
+    id: "fixture-trend",
+    kind: "trend",
+    title: "近 7 日趋势",
+    data: {
+      series: [
+        {
+          id: "amount",
+          label: "完成金额",
+          format: { style: "currency", currency: "CNY", precision: 0 },
+          points: [
+            { x: "周一", y: 18 },
+            { x: "周二", y: 26 },
+            { x: "周三", y: 22 },
+            { x: "周四", y: 35 },
+            { x: "周五", y: 42 },
+            { x: "周六", y: 28 },
+            { x: "周日", y: 46 }
+          ]
+        }
+      ]
+    }
+  },
+  ranking: {
+    schemaVersion: "1.0",
+    id: "fixture-ranking",
+    kind: "ranking",
+    title: "贡献排行",
+    data: {
+      items: [
+        { id: "one", label: "示例团队 A", value: 42e4, format: { style: "currency", currency: "CNY", precision: 0 } },
+        { id: "two", label: "示例团队 B", value: 31e4, format: { style: "currency", currency: "CNY", precision: 0 } },
+        { id: "three", label: "示例团队 C", value: 225e3, format: { style: "currency", currency: "CNY", precision: 0 } }
+      ]
+    }
+  },
+  "record-list": {
+    schemaVersion: "1.0",
+    id: "fixture-record-list",
+    kind: "record-list",
+    title: "相关记录",
+    data: {
+      entity: { key: "example_record", label: "示例记录" },
+      columns: [
+        { key: "owner", label: "负责人" },
+        { key: "amount", label: "金额", format: { style: "currency", currency: "CNY", precision: 0 } }
+      ],
+      records: [
+        { id: "record-1", title: "REC-001", values: { owner: "林小满", amount: 86e3 } },
+        { id: "record-2", title: "REC-002", values: { owner: "周一", amount: 148500 } },
+        { id: "record-3", title: "REC-003", values: { owner: "徐青", amount: 64800 } }
+      ],
+      total: 3
+    }
+  },
+  notice: {
+    schemaVersion: "1.0",
+    id: "fixture-notice",
+    kind: "notice",
+    title: "检查完成",
+    data: { tone: "success", body: "当前范围内没有发现明显异常。" }
+  }
+}, l = (r, e) => new Promise((n, i) => {
+  if (e?.aborted) {
+    i(new DOMException("Aborted", "AbortError"));
+    return;
+  }
+  const t = () => {
+    clearTimeout(a), i(new DOMException("Aborted", "AbortError"));
+  }, a = setTimeout(() => {
+    e?.removeEventListener("abort", t), n();
+  }, r);
+  e?.addEventListener("abort", t, { once: !0 });
+}), d = (r = {}) => ({
+  async *run(e, n) {
+    const i = `mock-run-${e.message.id}`, t = `mock-assistant-${e.message.id}`, a = r.response?.(e) ?? {
+      text: "我已根据当前上下文完成分析。",
+      artifacts: [s.metric]
+    }, c = [
+      { type: "message.start", runId: i, messageId: t },
+      { type: "message.delta", messageId: t, delta: a.text },
+      ...(a.artifacts ?? []).map(
+        (o) => ({ type: "artifact", messageId: t, artifact: o })
+      ),
+      { type: "message.complete", messageId: t },
+      { type: "run.complete", runId: i, threadId: e.threadId ?? "mock-thread" }
+    ];
+    for (const o of c) {
+      if (r.delayMs && await l(r.delayMs, n?.signal), n?.signal?.aborted)
+        throw new DOMException("Aborted", "AbortError");
+      yield o;
+    }
+  }
+});
+export {
+  s as artifactFixtures,
+  d as createMockAssistantTransport
+};

package/docs/artifact-v1.md

@@ -0,0 +1,101 @@
+# Artifact V1 合同
+
+## 设计原则
+
+Artifact 是后端与前端共享的、可校验的展示语义，不是前端组件调用指令。服务端只能从双方协商的 `kind` 和字段中生成结果，前端只从已注册模板白名单中选择渲染器。
+
+所有 Artifact 都包含：
+
+```ts
+interface BaseArtifact {
+  schemaVersion: "1.0";
+  id: string;
+  kind: ArtifactKind;
+  title?: string;
+  summary?: string;
+  presentation?: {
+    template?: string;
+    density?: "compact" | "comfortable";
+  };
+  actions?: ArtifactAction[];
+  meta?: Record<string, JsonValue>;
+}
+```
+
+## V1 kind
+
+| kind | 用途 | 核心数据 |
+| --- | --- | --- |
+| `metric` | 单个关键指标 | value、format、delta |
+| `comparison` | 多指标并列对比 | items |
+| `trend` | 时间或顺序趋势 | series、points |
+| `ranking` | Top N 或贡献排行 | items |
+| `record-list` | 可跳转的业务记录摘要 | entity、columns、records、total |
+| `notice` | 解释、空结果、风险或成功提示 | tone、body |
+
+## 数值格式
+
+`format` 是显示建议，不改变原值：
+
+```json
+{
+  "style": "currency",
+  "currency": "CNY",
+  "precision": 0,
+  "unit": "元"
+}
+```
+
+前端使用宿主 locale 进行格式化。无法格式化时显示原始值，不把货币、百分比或单位写死到模板。
+
+## 动作
+
+```json
+{
+  "id": "open-completed-orders",
+  "label": "查看明细",
+  "intent": "open-list",
+  "target": {
+    "entityKey": "sales_order",
+    "viewKey": "completed"
+  }
+}
+```
+
+动作是意图，不是 URL。宿主决定如何映射路由、是否允许执行以及失败提示。
+
+## 模板提示
+
+`presentation.template` 只是提示。模板不存在、不支持该 kind 或 `canRender` 不通过时，注册表忽略它并执行正常选择。后端不能通过这个字段加载代码。
+
+## 协商
+
+每次运行请求携带前端支持的 Artifact 目录：schema 版本、kind 和可选模板 id。后端只应返回交集能力；若无法形成结构化结果，返回普通助手文本。
+
+机器可读 JSON Schema 位于根目录 `artifact-v1.schema.json`。
+
+运行时 `validateArtifact` 与 JSON Schema 使用同一白名单边界：未知字段、非法可选展示
+字段和非 JSON 值都会被拒绝。通过校验的 Artifact 才能进入模板渲染，避免服务端输入在
+React 渲染阶段触发白屏。
+
+## 展示规模上限
+
+默认模板只接收适合抽屉内直接展示的摘要数据：actions 10 个、comparison 24 项、trend
+8 个 series 且每个 series 120 个点、ranking 50 项、record-list 20 列和 100 条记录。
+超过上限时，服务端应返回汇总 Artifact，并通过 `open-list` 动作交由宿主打开完整列表。
+
+运行时还按 Unicode code point 限制每个字符串 20,000 字符、JSON 最大深度 64、最多 10,000 个节点、累计
+字符串 1,000,000 字符、每条 record 最多 100 个 display value，并把验证问题限制在
+100 条以内。集合一旦超过展示规模会立即短路；深层、循环、非 plain object、Proxy
+异常、getter 异常、稀疏数组和 Artifact 整体资源超限都会作为校验失败返回，不向调用方
+泄漏运行时异常。JSON Schema 表达字段与单集合边界，整体节点/深度/累计文本预算由运行时
+校验补充执行。
+
+校验成功会返回经过结构化快照并再次校验的 Artifact，不与调用方继续共享可变对象；
+调用方后续修改原始输入不会改变已经进入会话或渲染链路的数据。
+
+同一集合内 action/item/series/record 的 `id` 和 record-list column 的 `key` 必须唯一，
+避免 React key 冲突以及同名列读取歧义。
+
+`presentation.density` 只选择内置的 compact/comfortable 密度，`action.appearance` 只选择
+primary/secondary/link 样式层级；它们都不能携带 CSS 或可执行代码。

package/docs/backend-contract.md

@@ -0,0 +1,94 @@
+# Make AI 助手后端 V1 配合合同
+
+## 接口能力
+
+后端第一版至少提供以下能力：
+
+1. 创建或继续一次 run；
+2. 通过 SSE 流式返回文本与 Artifact；
+3. 查询会话列表和会话消息；
+4. 停止正在执行的 run；
+5. 返回可观测的错误码和 request/run id。
+
+建议 Service API：
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| `POST` | `/api/assistant/runs` | 发起消息并返回 SSE |
+| `POST` | `/api/assistant/runs/:runId/cancel` | 取消生成 |
+| `GET` | `/api/assistant/threads` | 会话列表 |
+| `GET` | `/api/assistant/threads/:threadId` | 会话与历史消息 |
+| `DELETE` | `/api/assistant/threads/:threadId` | 删除会话，可放到后续版本 |
+
+宿主 UI 只调用自己的 Service `/api`，不直接调用 Make API、模型服务或透传 Make token。
+
+## Run 请求
+
+```json
+{
+  "threadId": "optional-thread-id",
+  "message": {
+    "id": "client-message-id",
+    "content": "统计本月已完成订单金额"
+  },
+  "context": {
+    "app": { "id": "app-id", "name": "销售管理" },
+    "location": { "pathname": "/orders", "routeId": "orders" },
+    "resource": { "entityKey": "sales_order", "viewKey": "default" },
+    "locale": "zh-CN",
+    "timezone": "Asia/Shanghai"
+  },
+  "capabilities": {
+    "artifactSchemaVersions": ["1.0"],
+    "artifactKinds": ["metric", "comparison", "trend", "ranking", "record-list", "notice"],
+    "templates": ["platform.metric.default"]
+  }
+}
+```
+
+后端必须从服务端身份重新确认数据权限。`context` 用于理解当前工作环境，不是授权凭据。
+
+## SSE 事件
+
+使用标准 SSE 帧，`event` 对应事件类型，`data` 是 JSON：
+
+```text
+event: message.start
+data: {"runId":"run-1","messageId":"assistant-1"}
+
+event: message.delta
+data: {"messageId":"assistant-1","delta":"本月已完成订单金额为"}
+
+event: artifact
+data: {"messageId":"assistant-1","artifact":{"schemaVersion":"1.0","id":"metric-1","kind":"metric","data":{"value":1286420,"format":{"style":"currency","currency":"CNY"}}}}
+
+event: message.complete
+data: {"messageId":"assistant-1"}
+
+event: run.complete
+data: {"runId":"run-1","threadId":"thread-1"}
+```
+
+要求：
+
+- delta 顺序稳定，同一 run 内可有多个 Artifact；
+- 服务端定期发送注释心跳，代理层不得缓冲 SSE；
+- 客户端断开或取消后及时终止下游任务；
+- Artifact 在发送前按共享 Schema 校验；
+- 错误事件包含稳定 `code`、可展示 `message`、`retryable` 和 `requestId`；
+- 正常结束、服务端取消和失败必须分别发送 `run.complete`、`run.cancelled` 或 `error`；
+- 同一流中的 `message.start`、`run.complete` 和带 id 的 `run.cancelled` 必须使用一致的
+  `runId`，同一会话中的 `messageId` 不得复用；
+- `data` 内不得重复提供 `type` 字段，事件类型只由 SSE `event` 字段决定；
+- `retryable` 必须是 JSON boolean，不能使用 `"true"` / `"false"` 字符串；
+- 客户端把终止事件前的 EOF 视为传输失败，不会把不完整响应当作成功；
+- 客户端停止时会立即关闭本地 run、忽略迟到事件，并取消底层 response reader；
+- 如果调用前 `AbortSignal` 已取消，客户端不会发出 fetch 请求；
+- 单个 SSE 事件默认不能超过 1,000,000 字符，单次累计响应文本不能超过 100,000
+  字符；需要更大载荷时应返回摘要 Artifact 和明细动作，不要扩展无界流；
+- HTTP 非成功响应只向 UI 暴露状态码，不直接展示任意后端 `message` 或内部错误细节；
+- 日志记录入口、失败和关键分支，但不记录 token、完整敏感上下文或不必要个人数据。
+
+## Mock 阶段
+
+真实接口未就绪时，前端 Mock 必须实现相同 `AssistantTransport` 和事件顺序。Mock 数据放在测试/Gallery 或宿主开发适配器，不进入平台默认业务模板。切换真实后端时只替换 transport，不改聊天组件和 Artifact 模板。

package/package.ai.json

@@ -0,0 +1,52 @@
+{
+  "packageName": "@qfei-design/make-ai-assistant",
+  "minimumRuntimeVersion": "0.1.0",
+  "readOrder": [
+    "package.ai.json",
+    "README.md",
+    "PUBLIC_API.md",
+    "recipes.json",
+    "capabilities.json"
+  ],
+  "runtime": {
+    "environment": "browser",
+    "coreIsDomFree": true,
+    "reactPeerRequiredForUi": true,
+    "ssrSupported": true
+  },
+  "install": {
+    "pnpm": "pnpm add @qfei-design/make-ai-assistant@^0.1.0",
+    "npm": "npm install @qfei-design/make-ai-assistant@^0.1.0",
+    "yarn": "yarn add @qfei-design/make-ai-assistant@^0.1.0"
+  },
+  "exports": [
+    "@qfei-design/make-ai-assistant",
+    "@qfei-design/make-ai-assistant/react",
+    "@qfei-design/make-ai-assistant/sse",
+    "@qfei-design/make-ai-assistant/testing",
+    "@qfei-design/make-ai-assistant/styles.css",
+    "@qfei-design/make-ai-assistant/artifact-v1.schema.json"
+  ],
+  "officialDocs": {
+    "readme": "README.md",
+    "publicApi": "PUBLIC_API.md",
+    "recipes": "recipes.json",
+    "capabilities": "capabilities.json"
+  },
+  "packageResponsibilities": [
+    "Artifact V1 contracts and validation",
+    "Conversation event reduction",
+    "Standard abortable SSE transport",
+    "Template registration and capability negotiation",
+    "Floating launcher, right drawer and embedded assistant panel",
+    "Platform artifact templates",
+    "Testing fixtures and mock transport"
+  ],
+  "hostResponsibilities": [
+    "Current App and route context",
+    "SSE or AG-UI transport adapter",
+    "Service authentication and server-side authorization",
+    "Safe action execution and route mapping",
+    "Optional App-specific templates and theme variables"
+  ]
+}

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "@qfei-design/make-ai-assistant",
+  "version": "0.1.0",
+  "description": "Platform-wide Make AI Assistant contracts, React shell, and context-aware artifact templates.",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react.mjs",
+      "require": "./dist/react.cjs"
+    },
+    "./sse": {
+      "types": "./dist/sse.d.ts",
+      "import": "./dist/sse.mjs",
+      "require": "./dist/sse.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing.mjs",
+      "require": "./dist/testing.cjs"
+    },
+    "./styles.css": {
+      "types": "./dist/styles.css.d.ts",
+      "default": "./dist/styles.css"
+    },
+    "./artifact-v1.schema.json": "./artifact-v1.schema.json"
+  },
+  "files": [
+    "dist",
+    "artifact-v1.schema.json",
+    "README.md",
+    "PUBLIC_API.md",
+    "package.ai.json",
+    "recipes.json",
+    "capabilities.json",
+    "docs/artifact-v1.md",
+    "docs/backend-contract.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "vite build && tsc -p tsconfig.build.json --emitDeclarationOnly && node scripts/copy-styles.mjs && node scripts/smoke-dist.mjs",
+    "gallery:build": "vite build --config examples/gallery/vite.config.ts",
+    "sprint:init": "qfei-release sprint-init",
+    "release:init": "qfei-release release-init",
+    "publish:alpha": "qfei-release publish --channel alpha",
+    "publish:beta": "qfei-release publish --channel beta",
+    "publish:latest": "qfei-release publish-latest",
+    "release:check": "qfei-release release-check",
+    "ci:init": "qfei-release ci-init",
+    "ci:check": "qfei-release ci-check"
+  },
+  "qfeiRelease": {
+    "masterBranch": "master",
+    "ciMode": "mr-verify-manual-prerelease",
+    "packageManager": "pnpm",
+    "verifyScripts": [
+      "test",
+      "typecheck",
+      "build"
+    ],
+    "latestPublishTargets": [
+      "internal",
+      "npmjs"
+    ],
+    "prereleasePublishTargets": [
+      "internal"
+    ],
+    "npmjs": {
+      "registry": "https://registry.npmjs.org/",
+      "access": "public",
+      "tokenEnv": "NPMJS_TOKEN"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0 || >=19.0.0",
+    "react-dom": ">=18.2.0 || >=19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@qfei/component-release-tools": "^0.5.1",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.6.0",
+    "vite": "^7.0.0",
+    "vitest": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "pnpm@10.20.0+sha512.cf9998222162dd85864d0a8102e7892e7ba4ceadebbf5a31f9c2fce48dfce317a9c53b9f6464d1ef9042cba2e02ae02a9f7c143a2b438cd93c91840f0192b9dd"
+}

package/recipes.json

@@ -0,0 +1,81 @@
+{
+  "packageName": "@qfei-design/make-ai-assistant",
+  "primaryGuide": "README.md",
+  "recipes": [
+    {
+      "id": "default-app-assistant",
+      "summary": "Add the default floating launcher and right drawer to a Make App.",
+      "use": [
+        "MakeAiAssistant",
+        "@qfei-design/make-ai-assistant/styles.css"
+      ],
+      "hostProvides": [
+        "MakeAssistantHostContext",
+        "AssistantTransport",
+        "ArtifactActionHandler"
+      ],
+      "readNext": ["README.md", "PUBLIC_API.md"],
+      "commonMistakes": [
+        "Calling Make API directly from the UI",
+        "Passing Make tokens through the package",
+        "Treating context as server authorization",
+        "Executing arbitrary server-generated HTML or component code"
+      ]
+    },
+    {
+      "id": "standard-sse-transport",
+      "summary": "Connect a browser or modern Node host to the standard named SSE contract.",
+      "use": [
+        "@qfei-design/make-ai-assistant/sse:createSseAssistantTransport"
+      ],
+      "hostProvides": [
+        "Service endpoint",
+        "Optional credentials and request headers"
+      ],
+      "readNext": ["README.md", "docs/backend-contract.md"],
+      "commonMistakes": [
+        "Importing the SSE implementation from the headless root",
+        "Sending Make tokens from the browser",
+        "Ending a stream without run.complete, run.cancelled or error"
+      ]
+    },
+    {
+      "id": "app-artifact-template",
+      "summary": "Register an App-specific result template without changing the platform package.",
+      "use": [
+        "ReactArtifactTemplate",
+        "platformArtifactTemplates",
+        "createPlatformArtifactRegistry"
+      ],
+      "hostProvides": [
+        "Stable template id",
+        "canRender predicate based on Artifact semantics and host context",
+        "Accessible React presentation"
+      ],
+      "readNext": ["README.md", "PUBLIC_API.md"],
+      "commonMistakes": [
+        "Registering a business-specific template as a platform default",
+        "Using a backend component name as an executable import path",
+        "Duplicating an existing template id"
+      ]
+    },
+    {
+      "id": "mock-before-backend",
+      "summary": "Develop and test the full UI before the SSE backend exists.",
+      "use": [
+        "createMockAssistantTransport",
+        "artifactFixtures"
+      ],
+      "hostProvides": [
+        "App context",
+        "Optional request-specific mock response"
+      ],
+      "readNext": ["README.md", "PUBLIC_API.md"],
+      "commonMistakes": [
+        "Building a second mock-only component path",
+        "Putting POC business fixtures into platform default templates",
+        "Changing UI event handling when switching to SSE"
+      ]
+    }
+  ]
+}