SuperAPI AI 工具集

create-canvas-app

编程与开发

查看项目

更新于 11-13 16:38

技能介绍

用途

create-canvas-app 是 Microsoft Canvas Toolkit 的配套工具,用于在宿主已安装 create-canvas 技能的前提下生成画布应用的源码工程。它本身不替代宿主技能:原生脚手架、SDK 注册、生命周期、作用域与激活流程仍以 create-canvas 技能为准,本工具在其定制与构建阶段介入,之后再回到宿主流程做验证。

主要能力

  • 两种起步模板:省略模板参数时生成通用计数器应用;使用 --template azure-resource-groups 时生成自带认证、显式订阅选择、有界读取器、取消处理、共享 UI/智能体状态与订阅选择器的 Azure 资源组起步应用,无需自行重建这些接线。
  • 工具包来源二选一:一个带 /build 的已发布 npm 精确版本,或本地 npm-pack 打包的 tarball。不得虚构发布版本、使用标签或版本范围、自行发布包,或在安装失败后切换来源。
  • setup-toolkit.mjs 脚本:从技能目录运行,替换占位符后把原生 scaffold 的 extension.mjs 原样复制到新的输出目录,并生成应用包、源码、资源与构建检查。该步骤不执行安装、登录或资源读取。
  • 输入约束:输出目录必须位于已存在的父目录下且为全新目录;会先解析输入输出路径中的符号链接,符号链接会被拒绝,也不会合并已有项目;目标已存在(即使内容完全相同)也会被拒绝。

使用方式

  1. 调用宿主的 create-canvas 技能(skill({ skill: "create-canvas" })),若已激活则继续该次调用。
  2. 选择模板与工具包来源。
  3. 使用宿主创建的 canvas ID 与 extension.mjs,其所在目录只能包含该文件。
  4. 在技能目录运行 setup 脚本,例如:

node scripts/setup-toolkit.mjs --name my-canvas
--scaffold "<native-scaffold>/extension.mjs"
--output "<existing-parent>/my-canvas-source"
--toolkit-version "<exact-version>"
--template azure-resource-groups

也可用 --toolkit-tarball "<toolkit-package>.tgz" 替代 --toolkit-version,二者只能选其一。

  1. 按生成的 README 把 attachToolkit 导入复制的 src/extension.mjs,包裹现有 createCanvas 选项,保留原生元数据与会话接线;适配器会替换脚手架演示回调并链式处理关闭,自定义回调或关闭处理器需显式集成,不要创建第二个 provider。
  2. 依次执行 npm install、npm run build、npm test;Azure 模式还需 npm run smoke,使用已安装的 Chrome 或 CANVAS_BROWSER,不自动下载浏览器。迭代时把检查限定在生成的应用内,并保留锁文件供后续 npm ci 使用。

适用场景

适合需要基于 Canvas Toolkit 快速搭建画布应用骨架,尤其是需要接入 Azure 资源组只读浏览能力的开发场景;也适用于为测试提供带标签的 fixture 数据。

限制与注意事项

  • 源码生成不等于就绪(NOT READY)。构建只通过测试 SDK 适配器检查宿主入口的注册与工具包连接,这不是原生宿主激活;需回到宿主技能安装整个 dist/、重载 provider 并验证实际面板。
  • Azure 模式为惰性:打开时不读取配置文件、不登录、不选择默认订阅、不查询资源、不写云资源;每个面板拥有自己的作用域与结果。
  • 凭据必须保存在服务端;需取消过期工作并拒绝陈旧结果;空成功、缺失作用域、错误与取消必须保持区分。
  • UI 与智能体调用共用同一套经过校验的动作与状态,不允许原始提示转发或单独的仅聊天 Azure 实现。
  • 新 UI 使用工具包控件(ui/dom,先 ui/styles.css 后 ui/base.css)与宿主类型令牌;正文保持常规字重、标题适度,避免手工定制按钮。
  • 保持生成构建的依赖与资源布局,检查解码后的图片与控件;不要用 SVG 重写替代缺失资源。
  • 状态是临时的,持久化与关闭按宿主技能执行;面板刷新不等于 provider 重载,需查看显示的构建 ID。
  • 默认不添加遥测;如被要求,使用共享工具包收集器并遵循产品使用遥测指引,更新公开与打包 README 中的使用数据、链接共享关闭说明并审查输出通知,测试的是退出行为而非 README 措辞。
  • 工具包指南链接在导出插件中组装,不在源码树中维护副本;安装、发布与云变更仍是分开的用户决策。
  • 关于收费、价格与具体平台支持范围,资料未提供。