make-ai-assistant

Make AI 助手

此 Skill 负责宿主集成契约，不负责软件包内部 UI 或状态机。Make App 宿主负责身份、范围受限的页面上下文、单一经过身份验证的原始字节传输、明确的 Service 路由和部署配置。 此 Skill 中的 Make App v1 参考内容与 Agent Public API v1 OpenAPI 修订版 60bbbcfe90c6defce46a0ed715e008fa4db20deb 以及软件包的公开 v1 入口保持一致。Skill 版本与 npm 软件包版本相互独立；实施前请核实实际安装的版本。

工作流

1. 检查目标宿主的软件包管理器、经过身份验证的 Shell 和身份、共享身份验证适配器、UI/Service 路由、权限检查、运行时来源、测试以及现有助手集成。保留稳定的调用链。
2. 阅读 references/package-integration.md。对于新安装或要求升级到最新版本的情况，查询已配置的注册表，在使用方 UI 工作区安装最新发布的软件包，并核实其精确的锁文件版本、公开导出映射和声明。如果已安装的版本未公开此 Skill 所要求的契约，请指出缺失的导出项/类型和版本并停止；不要根据其他项目或软件包说明自行拼凑兼容实现。
3. 使用 references/make-app-protocol.md 中版本化的 Make App AI Chat 契约，包括架构、限制、可扩展的公开错误和固定的后端修订版。在声明已达到生产就绪状态前，检查当前后端契约/已部署行为。如果无法进行检查或两者存在差异，则保留文档中规定的 v1 实现，但报告运行时兼容性未经验证；切勿根据其他项目推断旧版 API。
4. 完整集成时，阅读以下软件包、宿主、协议、流/附件、UI 和测试参考资料。针对性修复时，仅阅读相关参考资料。使用 TDD：先编写失败的契约/行为测试，再实现最小改动，最后在测试通过的情况下重构。
5. 仅使用公开导入，并且只导入一次 styles.css。创建公开的 /client，并使用宿主身份验证的 AuthenticatedTransport；通过完整分页查找唯一的当前 App app_internal Agent，然后执行 await createMakeAppAssistantTransport({ client, agentId, signal })。SDK 负责 v1 DTO、解码、重试、上传、SSE 和 UI 传输映射。对于每个新的 Make App，都要将 make-app-observability 应用于此经过身份验证的传输：JSON、SSE 和二进制请求都要发送 traceparent 和相匹配的 X-Log-Id 标头；绝不要将追踪上下文放入查询参数。
6. 仅公开文档中规定的 18 个 Make App v1 Service 操作。转发前验证 App 范围、方法/路径/查询/请求正文、每个非 GET/HEAD 请求的单一同源 HTTP(S) Origin、大小以及上游目标。
7. 软件包 UI 内部实现由软件包负责。使用公开属性/主题变量来适配宿主布局和展示；切勿复制其 reducer、流解析器、上传引擎、任务列表、编写框或 CSS。
8. 运行静态审计、重点 UI/Service 测试、类型检查、构建以及经过身份验证的现有路由冒烟测试。静态预检通过并不能证明全部 18 个 Service 操作、运行时正确性或部署就绪状态。

发布 Skill 契约前，请先完成 references/testing-and-pitfalls.md 中独立的前向测试，再宣布此指南已就绪。

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

预期版本应为实际安装解析出的版本，而不是版本范围。关于更广泛模型输入支持的声明，需要单独提供已部署模型的证据。报告集成完成前，请在目标 Dev App 中验证已发布的同源请求和响应流传输。

参考索引

主题	阅读
包解析、公开类型和 React 属性	references/package-integration.md
Make App 宿主组合、Agent 发现和身份	references/make-app-host-integration.md
Make App v1 18 项操作 API 和 Service 边界	references/make-app-protocol.md
SDK 流恢复及文件／图像行为	references/make-app-stream-and-attachments.md
包 UI、主题和无障碍功能	references/ui-and-templates.md
测试和交付门槛	references/testing-and-pitfalls.md

严格边界和交接

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