create-yichong-canva

调用 @canva/cli@latest 创建官方 hello_world 工程，然后接入 yichong-canva2、输入/进度/结果三段式页面和公共 Footer。需要 Node.js 22 或更高版本。

0.1.7 更新：接入 SDK 2.2.0 的账户错误状态，超时后停止圆圈并支持重试；保持原 Footer 样式和正常文案。自动告警在 SDK 内完成，模板不重复上报。

0.1.8 新增公共行为统计（配套 SDK 2.4.0 或更高版本）：三段式与 Footer 直接使用 client.reportUsage，兼容现有 GET 埋点接口。生成操作通过 operation_id 关联开始、最终结果与插入；未编辑输入的失败重试另发新操作并带 retry_of。页面事件防止 StrictMode 重放重复计数；取消后的迟到结果不再记成功。默认演示带 mode: "demo"，不冒充真实 AI 使用；未改动 Footer 样式、固定文案和翻译 ID。

Provider 自动记录账户与应用会话事件，脚手架不重复记录。仅上报行为名称、固定属性和耗时，不记录文本输入、结果、文件 URL 或原始错误；上报失败不影响业务。本地测试可在生成的配置中使用 usageReporting: { enabled: false }。默认安装兼容范围 ^2.6.0 的 SDK（0.3.0 起）；指定 --sdk-version 时需使用 2.4.0 或更高版本，本地开发也可通过 --sdk-path 指向对应 SDK。

0.1.6 更新：补充模板中的详细注释和生成应用的接入说明，与 [email protected] 的上传进度及兼容行为同步。该历史版本默认安装 yichong-canva2@latest（0.2.0 起改为 ^2.4.0），并调用 @canva/cli@latest 创建官方工程；已有应用不会自动更新。

本地开发时使用

在 new_canva 仓库根目录运行：

npm ci --prefix package/create-yichong-canva

node package/create-yichong-canva/bin/create-yichong-canva.mjs "My App" \
  --channel my_app \
  --sdk-path package/yichong-canva2 \
  --directory apps/my-app

官方 CLI 会保留其登录和分发类型选择流程。只在本地生成、不在 Canva 注册应用时，添加 --offline --yes。本地 SDK 需要先安装开发依赖，命令会自动构建它并打包；新应用依赖随工程保存的 tarball，避免通过源码链接引入第二份 React。

新增的预测接口从 [email protected] 提供。开发时可以使用 --sdk-path；不传该参数时按 ^2.4.0 安装工具包。

0.1.1 增加生成应用的 AGENTS.md 使用约定：保留官方说明，追加直接调用工具包接口的规则，避免纯转发包装。生成的接入说明也包含 [email protected] 新增的 reportError 示例。

0.1.2 补齐默认三段式：src/pages/index.tsx → progress.tsx → result.tsx，通过 src/app.tsx 的简单状态切换。默认运行可取消的本地文本演示，并支持真实 Canva 文本插入；业务流程放在 src/generation/generate.ts，不自动调用模型或扣费。

0.1.3 调整三段式布局：首页紧凑表单，进度页整屏居中，结果页以预览和操作为主。Footer 在输入/结果页按钮下方以居中小字和内联定价链接呈现，跟随内容滚动；处理中隐藏。

0.1.4 修正进度条：使用官方默认 medium（16px）进度条、官方渐变、圆角及 Box/Rows 布局。三页容器统一保留四边 16px 内边距，不使用左侧零留白和强制滚动条占位。省略真实进度时显示每秒增加剩余量 10% 的等待动画，不显示百分比数字、不据此判定成功；真实 progress 优先，卸载时清除定时器。通过 title / message 配置业务文案，默认文案为 Working / Completing the demo action.。

进度页使用官方主进度条和居中信息组；动画速度、阶段文案、取消或返回历史、结果操作随业务而异。Footer 限定在输入页，结果页默认 Start over；进度操作仅在提供回调时显示，支持 cancelText 区分 Cancel 与 Go to history。

Footer 文案统一为七种账户状态模板，并在生成的 AGENTS.md 中固定句式、message ID、额度含义和链接用途。appConfig 仅配置应用展示名与计量单位，默认从创建名称和 credit/credits 初始化。订阅本期额度与按需余额分开显示；管理订阅进入 dashboard，按需购买进入 credits 页签。本地演示不显示消费提示。

账户故障处理（0.1.7）

Footer 读取工具包的 accountError，首次登录超时停止圆圈并保留原登录重试入口；刷新失败保留已有账户文案和余额，增加错误提示和刷新重试按钮。没有修改正常七种额度文案、样式、padding 或支付链接行为。

超时、取消、有限重试、告警去重和飞书上报全部在工具包 Provider 内实现，Footer 不重复上报。模板、示例测试、生成的 AGENTS.md 和使用说明已同步。配套 SDK 为 [email protected] 或更高版本；本地开发可用 --sdk-path ../yichong-canva2 验证。已有应用需升级 SDK 并同步 Footer 错误分支。

发布后的命令

npx create-yichong-canva@latest "My App" --channel my_app

# 不传名称和渠道时，交互询问这两个参数
npx create-yichong-canva@latest

本地开发使用上述源码入口。发布时先发布包含新接口的 SDK，再发布这个创建工具。

创建流程

1. 校验名称、渠道和新目录；现有目录不接管、不覆盖。
2. 如使用本地 SDK，先构建它。
3. 通过子进程调用 npm exec --yes --package=@canva/cli@latest -- canva apps create ...。每次重新解析官方 latest，不依赖已有全局 CLI；官方依赖版本继续由官方模板决定。
4. 保留官方依赖、配置、入口与 README，补入 Provider 配置、接口示例和三段式页面，将官方 hello_world 的业务 App 和对应测试替换为三段式示例。添加工具包依赖，并按 TSX 语法树包裹 App。在根目录生成 YiChong 的 AGENTS.md 使用约定；官方模板已有该文件时保留原文并追加。
5. 安装依赖并运行官方项目的 lint:types。不自动执行模型、扣费或发布操作。

官方的国际化、UI Provider、intent、热更新代码、React 和 Canva 依赖保留。YiChongAppProvider 只是应用中的配置组件，内部复用一个 YiChongCanvaProvider。业务继续直接使用 useYiChongCanva()。

生成的 AGENTS.md 要求直接调用工具包的原方法名和参数，例如 client.createSpecifyPrediction({ ... })、client.getPrediction({ id })；避免新增 createCoverApi 这样的纯转发包装。restorePhoto 等组织实际业务流程的函数可以保留。

文件上传也直接调用 client.uploadFile({ file, onUploadProgress })，继续复用 ai.imgkits.com 的现有 Cloudflare R2 接口，无需新增后端。SDK 2.1.0 提供进度回调：单次按字节、分片按已完成片数计算；total 已知时，业务用 loaded / total 更新进度页。100% 仍需等待上传响应或分片合并成功，只有 uploadFile 返回结果才进入下一阶段。公开地址采用后端的 endpointBaseUrl，旧分片初始化缺少该字段时通过现有签名接口补取。两张上传时序图及完整示例见 工具包上传说明。

参数见 --help。--no-install 可以跳过最后的安装和类型检查；--app-id 可以给离线工程预填 App ID；--sdk-version 可以选择已发布版本或 tag；--distribution public|private 会传给官方 CLI。

官方入口结构不符合支持的模板，或官方未来新增与三段式同名的业务文件/目录时会停止接入并保留工程。创建或安装失败时返回非零状态，并显示可以修复的工程路径。命令只创建新工程，不自动改写已经创建的应用。

验证

npm ci
npm test

自动测试用模拟的子进程验证参数、接入、官方文件保留、目录保护和失败处理，不访问真实 Canva 账号。真实官方 CLI 的离线创建、依赖安装和构建另行验证。

组件行为回归使用已安装依赖的官方 Canva 工程提供 React、UI Kit 和 Jest；在临时目录通过真正的接入逻辑生成后运行，原应用不会被修改。SDK 与 Canva API 全部 mock，不发送生产埋点：

npm run test:template -- ../../apps/ai-cover-generator

可换成其它具有 tsconfig.json、eslint.config.mjs、declarations、src/utils/test_render.tsx 的已安装官方工程。测试不借用该工程的 Jest 配置，使用干净官方 fixture 验证补丁。覆盖三段式、StrictMode 事件去重、取消与迟到结果、重试关联、插入与定价实际结果、七种固定 Footer 文案；它不验证真实统计服务器是否入库。

0.4.0 失败提示

• 默认安装 yichong-canva2@^2.7.0。
• app.tsx 的失败提示改由 describeFailure 按顺序取：getDisplayMessage(error)（后端分级后的用户文案）→ isPolicyBlocked(error) 的违规提示 → 演示的 INVALID_INPUT → 兜底。不再直接显示 error.message。
• 结果页插入失败只显示翻译文案，不显示 Canva SDK 的英文原文。
• Footer、QuotaAlert 的计量单位优先用 client.pricingUnit（定价语言包，随定价同步、按界面语言翻译），拿不到再用 config.ts 的 unitConfig。test_client 补 pricingUnit: null，footer.test.tsx 补两个用例。
• 生成的 AGENTS.md 增加「失败提示」一节；app.test.tsx 增加可展示 / 不可展示 / SDK 本地错误 / 内容违规的用例。
• 设计见 new_canva/docs/前端设计-错误文案msg分级.md。

0.3.1 插入失败带原因

• 结果页的 insert_fail 带 error: { stage: "insert", cause }，插入失败的原因进新通道；Canva 的 NOT_FOUND / USER_OFFLINE 由工具包自动记为预期内，不触发告警。
• 错误告警由新通道发到飞书群，应用里不再为生成、插入失败单独调用 reportError；审核接口出错放行这类不会出现在失败事件里的情况仍用 reportError。
• 新通道默认开启（config.ts 的 telemetry: { enabled: true }）。生成、插入失败只靠新通道上报，关掉就既不进后台也不发飞书。发布前在 USA 后台「Canva 行为统计 → 应用登记」登记应用（渠道 = productName），否则事件会被拒收。本地演示（mode: "demo"）和本地联调的事件记为 dev，后台不显示。

0.3.0 新通道埋点

• 默认安装 yichong-canva2@^2.6.0。生成的 src/yichong/config.ts 增加 telemetry: { enabled: false }，新通道默认关闭；开启后工具包在旧统计和飞书上报之外额外发一份 canva.v1 事件，旧通道不变。
• generate(input, { signal, operationId, timer })：示例用 timer.run("local_render", ...) 计时，失败抛 StageError（空输入为 INVALID_INPUT，expected）。
• app.tsx 的终态事件带 timings，generate_fail 带 error（只进新通道）；QuotaAlert 显示时用 client.track 发 quota_blocked。
• 新增根目录 telemetry.catalog.json（自定义事件目录，空模板）。
• 打开新通道前，先在 USA 后台（https://admin.imgkits.com/canva-telemetry/registry）登记应用：App ID、渠道（= config.ts 的 productName）、名称。没登记或渠道不一致的应用，事件会被采集服务拒收。
• src/utils/test_client.ts 的假客户端补 track 和 canUseLimit。
• 设计文档：new_canva/docs/canva-telemetry/。

0.2.1 支付链接与测试环境

• 支付链接按 profile.review === false || canAcceptPayments 判断是否可点（pay_link.tsx 的 usePaymentLinksEnabled()，Footer、QuotaAlert、PayLink 共用）。开发者后台关闭「Enable payments」时，正常运行（review 为 false）的用户仍看到可点链接；审核期或旧账户且平台不允许支付时，各行保留，<link> 片段就地换成 {action} in your web browser。0.2.0 只看 canAcceptPayments，会把链接整行隐藏、只留一句浏览器提示。
• QuotaAlert 增加余额不够本次（一次消耗多个）的四个 quota.insufficient.* 显式 ID，新增 getQuotaState(client, cost) 按与 canUseLimit 一致的口径算余额。
• .app 滚动层加 data-scroll-container。
• Jest：yichong-canva2 映射到 dist/index.js 并由 @swc/jest 转换（transformIgnorePatterns 只放开这个包）；test_client.ts 保留 SDK 真实导出；setup 增补 TextDecoder、URL.createObjectURL / revokeObjectURL、ResizeObserver。已有冲突的映射或 transformIgnorePatterns 会停止，不覆盖。
• 配套 [email protected] 只补 profile.review 等类型；模板用类型收窄，2.5.0 也能编译。

0.2.0 创建参数与旧应用迁移

官方基础工程始终使用 @canva/cli@latest。工具包依赖默认改为 ^2.4.0，避免自动跨大版本；--sdk-version 仍可指定已发布版本或 tag，--sdk-path 用于验证尚未发布的源码。发布 SDK 2.5.0 后再更新内置范围。

node package/create-yichong-canva/bin/create-yichong-canva.mjs "Fantasy Map" \
  --from-legacy apps/legacy_app/fantasy-map \
  --directory apps/fantasy-map-next --yes --no-install

node package/create-yichong-canva/bin/create-yichong-canva.mjs "My App" \
  --channel my_app --app-id AATESTAPP123 \
  --base-url https://www.livepolls.app/my_app \
  --app-name "My Application Display Name" --unit image --unit-plural images \
  --permission canva:asset:private:write --offline --yes

• --from-legacy 按 src/appConfig.ts、src/app_config.ts、src/config.ts 顺序静态解析一个配置对象，只取身份、展示名、消费地址和计量单位；不执行旧源码，不复制 reporting 等凭据。App ID 表达式无法解析时，仅从 .env / .env.template 提取 CANVA_APP_ID。必要字段不足时明确列出需要补的参数。
• 所有显式参数优先。CLI 名称最多 18 字符；--app-name 是 Footer 展示名，可以更长。复数未配置时默认单数加 s，不规则复数请显式设置。
• 迁移模式始终传 --offline，只继承旧 App ID，不注册另一个 Canva 应用。来源路径写进生成的 YICHONG_README.md。只读取旧目录，目标必须是新目录。
• 生成前展示身份表。没有 --yes 时需要在终端确认；非交互环境必须显式 --yes。
• --app-id 同步 config.ts、.env 和 .env.template，处理已有值、注释占位和缺失行，其余环境变量保留。
• 可重复 --permission 追加 mandatory 权限。官方与旧 manifest 的已有权限类型保留，按权限名称去重；不会把旧 optional 权限整体改为 mandatory。
• baseUrl 是消费接口地址；它不改变 SDK 固定的登录和 status 服务。

公共 QuotaAlert / PayLink 用法见生成的 YICHONG_README.md。模板演示不调用模型、不扣费。Footer 固定文案和页面 padding 保留；主滚动层使用细滚动条。

生成时补官方 Jest 的图片映射和 yichong-canva2 的 ESM 转换，并导入独立 jest.yichong.setup.ts，安全补齐 TextEncoder / TextDecoder、Blob.text、URL.createObjectURL、IntersectionObserver 和 ResizeObserver。官方 transform 规则原样保留，只在前面加一条 SDK 规则；其他配置不动；发现不支持的结构、已有文件或冲突映射时停止，不覆盖。

cd package/create-yichong-canva
npm test
npm run test:template -- ../../apps/qr-code-ai-art

模板测试必须传已安装的官方工程目录。测试只借其依赖、TypeScript 配置及渲染辅助函数；在临时目录用干净官方 Jest fixture 执行真实接入，再跑类型检查、Jest（包括 Carousel/图片 smoke）和 lint，不使用借用应用已补过的 polyfill。迁移时替换 app.test.tsx，保留 footer.test.tsx、progress.test.tsx 和 src/utils/test_client.ts 的公共回归。

styles/components.css 的 .scrollContainer 是官方模板遗留；新三段式不引用它。业务确认无引用后可删除该样式，主滚动层使用 styles/yichong.css 的 .app。