make-ai-assistant

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Make AI Assistant

This Skill owns the host integration contract, not the package's internal UI or state machine. The Make App host owns identity, bounded page context, one authenticated raw-byte transport, explicit Service routes, and deployment configuration. This Skill's Make App v1 reference is aligned with the Agent Public API v1 OpenAPI revision

60bbbcfe90c6defce46a0ed715e008fa4db20deb

and the package's public v1 entry points. The Skill version and npm package version are independent; verify the actual installed version before implementation.

本 Skill 负责宿主集成契约，不负责包的内部 UI 或状态机。Make App 宿主负责身份、有界页面上下文、单一经过身份验证的原始字节传输、显式服务路由以及部署配置。本 Skill 的 Make App v1 参考实现与 Agent Public API v1 OpenAPI 修订版

60bbbcfe90c6defce46a0ed715e008fa4db20deb

以及包的公开 v1 入口点保持一致。Skill 版本与 npm 包版本相互独立；请在实施前验证实际安装的版本。

Workflow

工作流程

Inspect the target host's package manager, authenticated shell and identity, shared auth adapter, UI/Service routes, permission checks, runtime origin, tests, and existing assistant integration. Preserve stable call chains.
Read
```
references/package-integration.md
```
. For a new installation or a requested latest upgrade, query the configured registry, install the latest published package in the consumer UI workspace, and verify its exact lockfile version, public export map and declarations. If the installed version does not expose this Skill's required public contract, stop with the missing export/type and version; do not synthesize compatibility from another project or package prose.
Use the versioned Make App AI Chat contract in
```
references/make-app-protocol.md
```
, including schemas, limits, extensible public errors and the pinned backend revision. Check the current backend contract/deployed behavior before claiming production readiness. If that check is unavailable or differs, retain the documented v1 implementation but report runtime compatibility as unverified; never infer an older API from another project.
For a full integration, read the package, host, protocol, stream/attachment, UI, and test references below. For a targeted fix, read only the relevant references. Use TDD: failing contract/behavior test, minimal implementation, then refactor with tests green.
Use only public imports and import
```
styles.css
```
once. Create the public
```
/client
```
with a host-authenticated
```
AuthenticatedTransport
```
, discover the unique current-App
```
app_internal
```
Agent across complete pagination, then
```
await createMakeAppAssistantTransport({ client, agentId, signal })
```
. The SDK owns v1 DTOs, decoding, retries, uploads, SSE and UI transport mapping. For every new Make App, apply
```
make-app-observability
```
to this authenticated transport: JSON, SSE and binary requests send
```
traceparent
```
and matching
```
X-Log-Id
```
headers; never place tracing context in a query parameter.
Expose only the 18 documented Make App v1 Service operations. Validate App scope, method/path/query/body, a single same-origin HTTP(S) Origin for every non-GET/HEAD request, sizes and upstream target before forwarding.
Keep package UI internals package-owned. Use public props/theme variables for host placement and presentation; never copy its reducer, stream parser, upload engine, task list, composer or CSS.
Run the static audit, focused UI/Service tests, typecheck, build and an authenticated existing-route smoke test. A static preflight pass cannot prove all 18 Service operations, runtime correctness or deployment readiness.

For a Skill contract release, complete the independent forward test in

references/testing-and-pitfalls.md

before declaring this guidance ready.

bash

node skills/make-ai-assistant/scripts/audit-make-ai-assistant-project.mjs <project-root> \
  --expected-package-version=<resolved-exact-version>

The expected version is the actual installed resolution, not a range. A claim of broader model-input support needs separate deployed-model evidence. Verify published same-origin requests and response streaming against the target Dev App before reporting an integration complete.

检查目标宿主的包管理器、经过身份验证的 shell 与身份、共享身份验证适配器、UI/服务路由、权限检查、运行时源、测试以及现有助手集成。保留稳定的调用链。
阅读
```
references/package-integration.md
```
。对于全新安装或要求的最新升级，请查询配置的 registry，在消费端 UI 工作区中安装最新发布的包，并验证其确切的 lockfile 版本、公开导出映射和声明。如果安装的版本未公开本 Skill 所需的公开契约，请停止并说明缺失的导出/类型及版本；不要从其他项目或包文档中拼凑兼容性。
使用
```
references/make-app-protocol.md
```
中带版本的 Make App AI Chat 契约，包括 schema、限制、可扩展的公开错误以及固定的后端修订版。在宣称生产就绪前，请检查当前后端契约/已部署的行为。如果无法进行该检查或结果存在差异，请保留文档记录的 v1 实现，但需说明运行时兼容性未经验证；切勿从其他项目推断旧版 API。
对于完整集成，请阅读下方的包、宿主、协议、流/附件、UI 和测试参考文档。对于定向修复，仅阅读相关参考即可。采用 TDD 模式：先编写失败的契约/行为测试，再做最小化实现，最后在测试通过后进行重构。
仅使用公开导入，且仅导入一次
```
styles.css
```
。使用经过宿主身份验证的
```
AuthenticatedTransport
```
创建公开的
```
/client
```
，通过完整分页发现当前应用唯一的
```
app_internal
```
Agent，然后执行
```
await createMakeAppAssistantTransport({ client, agentId, signal })
```
。SDK 负责 v1 DTO、解码、重试、上传、SSE 以及 UI 传输映射。对于每个新的 Make App，都要为此经过身份验证的传输应用
```
make-app-observability
```
：JSON、SSE 和二进制请求需发送
```
traceparent
```
及匹配的
```
X-Log-Id
```
头；切勿将追踪上下文放在查询参数中。
仅公开 18 个已记录的 Make App v1 服务操作。在转发前，需验证应用范围、方法/路径/查询/请求体、每个非 GET/HEAD 请求的单一同源 HTTP(S) 源、大小以及上游目标。
包的 UI 内部逻辑归包所有。使用公开的 props/主题变量进行宿主放置和展示；切勿复制其 reducer、流解析器、上传引擎、任务列表、编辑器或 CSS。
运行静态审计、针对性 UI/服务测试、类型检查、构建以及经过身份验证的现有路由冒烟测试。静态预检通过并不能证明所有 18 个服务操作、运行时正确性或部署就绪性。

对于 Skill 契约发布，在宣布本指南可用前，需完成

references/testing-and-pitfalls.md

中的独立正向测试。

bash

node skills/make-ai-assistant/scripts/audit-make-ai-assistant-project.mjs <project-root> \
  --expected-package-version=<resolved-exact-version>

预期版本是实际安装的解析版本，而非版本范围。若宣称支持更广泛的模型输入，需要单独的已部署模型证据。在报告集成完成前，请针对目标 Dev App 验证已发布的同源请求和响应流式传输。

Reference map

参考文档对照表

Topic	Read
Package resolution, public types and React props	`references/package-integration.md`
Make App host composition, Agent discovery and identity	`references/make-app-host-integration.md`
Make App v1 18-operation API and Service boundary	`references/make-app-protocol.md`
SDK stream recovery and file/image behavior	`references/make-app-stream-and-attachments.md`
Package UI, theme and accessibility	`references/ui-and-templates.md`
Tests and delivery gates	`references/testing-and-pitfalls.md`

主题	阅读文档
包解析、公开类型与 React props	`references/package-integration.md`
Make App 宿主组成、Agent 发现与身份	`references/make-app-host-integration.md`
Make App v1 18 项操作 API 与服务边界	`references/make-app-protocol.md`
SDK 流恢复与文件/图片行为	`references/make-app-stream-and-attachments.md`
包 UI、主题与可访问性	`references/ui-and-templates.md`
测试与交付门禁	`references/testing-and-pitfalls.md`

Hard boundaries and handoffs

严格边界与职责交接

Browser Make App requests use same-origin
```
/api/make/app/ai/v1/**
```
. The SDK appends
```
/v1
```
to its path-free version base; do not append it twice. Local preview upstream uses
```
make_api_origin + /api/make/app/ai/v1/**
```
; published Service uses the configured Make Gateway origin plus
```
/make/app/ai/v1/**
```
. Never add a separate Agent Gateway origin, token or hard-coded Agent ID.
The selected App Agent must have
```
agentType === "app_internal"
```
and an exact current
```
appKey
```
. Ignore channel and unknown Agent types, but fail on zero or multiple matching App-internal Agents. Read every page before accepting one.
```
AuthenticatedTransport.request
```
performs one credentialed same-origin I/O and yields status, headers and raw
```
AsyncIterable<Uint8Array>
```
; it never reads a browser token or unwraps SSE/bytes as JSON. Set
```
retryOwner
```
to exactly one owner. Preserve 201/202/204,
```
Make-AI-Api-Version
```
, AbortSignal and 401/403 login/permission handling.
Capabilities are fetched by the package at adapter creation. They gate optional UI features and supply model input kinds/limits; they are not authorization. Upload availability does not prove the model can interpret a file or image. The current Make App adapter does not carry Artifact; do not add unsupported context, Artifact or negotiation fields or promise Artifact UI.
App, tenant or user changes abort old discovery and dispose the old client. A panel close is local UI state, not a remote run cancellation. Keep a retryable launcher on Agent/capabilities discovery failure.
```
makeui
```
owns surrounding App shell and external placement; this Skill and the package own assistant-internal behavior/styles.
```
make-app-service
```
owns the explicit proxy, validation and safe errors.
```
make-app-auth
```
owns unified login and the narrow AI raw-byte bridge rule.
```
make-app-permission
```
owns access and action authorization.
```
make-app-runtime
```
owns preview/published origins and build contracts.
```
make-env-setup
```
owns Skill installation/sync;
```
makecli
```
owns platform inspection, not runtime Service requests.
Keep page context bounded and non-secret. Never treat it as authorization or execute server-provided HTML, JSX, CSS, JavaScript or unvalidated action URLs. Testing mocks are opt-in and cannot establish backend readiness.

浏览器端 Make App 请求使用同源
```
/api/make/app/ai/v1/**
```
。SDK 会在其无路径的版本基址后追加
```
/v1
```
；请勿重复追加。本地预览上游使用
```
make_api_origin + /api/make/app/ai/v1/**
```
；已发布的服务使用配置的 Make Gateway 源加上
```
/make/app/ai/v1/**
```
。切勿添加单独的 Agent Gateway 源、token 或硬编码的 Agent ID。
所选的应用 Agent 必须满足
```
agentType === "app_internal"
```
且与当前
```
appKey
```
完全匹配。忽略通道和未知 Agent 类型，但如果匹配的应用内部 Agent 数量为零或多个，则报错。在确认接受前，请遍历所有分页。
```
AuthenticatedTransport.request
```
执行一次带凭证的同源 I/O，并返回状态、头信息和原始
```
AsyncIterable<Uint8Array>
```
；它不会读取浏览器 token，也不会将 SSE/字节解包为 JSON。将
```
retryOwner
```
设置为唯一所有者。保留 201/202/204 状态码、
```
Make-AI-Api-Version
```
头、AbortSignal 以及 401/403 登录/权限处理逻辑。
能力（Capabilities）由包在创建适配器时获取。它们用于控制可选 UI 功能并提供模型输入类型/限制；它们并非授权机制。支持上传并不代表模型能够解析文件或图片。当前的 Make App 适配器不支持 Artifact；请勿添加不支持的上下文、Artifact 或协商字段，也不要承诺提供 Artifact UI。
应用、租户或用户变更会中止旧的发现过程并销毁旧客户端。关闭面板是本地 UI 状态，而非取消远程运行。在 Agent/能力发现失败时，保留可重试的启动器。
```
makeui
```
负责外围应用外壳和外部放置；本 Skill 及对应包负责助手内部的行为/样式。
```
make-app-service
```
负责显式代理、验证和安全错误。
```
make-app-auth
```
负责统一登录和受限的 AI 原始字节桥接规则。
```
make-app-permission
```
负责访问和操作授权。
```
make-app-runtime
```
负责预览/已发布源及构建契约。
```
make-env-setup
```
负责 Skill 安装/同步；
```
makecli
```
负责平台检查，而非运行时服务请求。
保持页面上下文有界且不包含机密信息。切勿将其视为授权依据，也不要执行服务器提供的 HTML、JSX、CSS、JavaScript 或未经验证的操作 URL。测试 mock 是可选的，不能作为后端就绪的依据。