@coze-arch/cli 0.0.35 → 0.0.36-alpha.844e20

package/README.md

@@ -19,6 +19,17 @@ rush update
 
 ## 使用
 
+### 部署应用
+
+```bash
+coze-dev deploy auth login
+coze-dev deploy code deploy --source-root . --yes --wait
+```
+
+完整命令、参数和示例见 [部署命令文档](./docs/deploy.md)。部署命令与其它
+`coze-dev` 能力共享 `~/.coze/cli/config.json` 登录态，也支持通过
+`COZE_API_TOKEN` 提供固定运行时凭证。
+
 ### 初始化项目
 
 ```bash

package/docs/deploy.md

@@ -0,0 +1,168 @@
+# coze-dev deploy
+
+`coze-dev` 内置的部署命令，复用主 Coze CLI 保存在
+`~/.coze/cli/config.json` 中的登录状态。
+
+## 安装与运行
+
+```bash
+npm install -g @coze-arch/cli
+coze-dev deploy auth login
+coze-dev deploy auth status
+coze-dev deploy doctor
+```
+
+默认输出 JSON，可通过 `--format text` 切换为文本输出。
+
+首次部署不需要手动查找 `space_id` 或 `project_id`。当 `.coze [project]` 没有
+`project_id` 时，CLI 会复用已配置的 Space；如果尚未配置，会查询当前账号
+可用的 Space、自动选择第一个并保存，然后根据 `.coze` 的
+`[project].project_type` 创建当前源码目录专属的普通编程 Project。
+映射与部署服务端对 `.coze` 的解析保持一致：`agent`→Agent、`workflow`/`automation`→Automation、
+`app`→App、`skill`→Skill、`web`/`backend`→GeneralWeb、`miniapp`/`miniprogram`→WechatMiniProgram；
+其他值或未声明 `project_type` 时创建通用 General Project。不会复用共享的 CLIBilling Project。
+
+> Project 类型不只是元信息：它决定注入运行时的 `COZE_PROJECT_TYPE`、是否为该 Project 开通
+> Postgres、以及流量网关是否强制入站鉴权。类型建错时部署照样成功，但服务可能起不来 —— 例如
+> agent 模板靠 `COZE_PROJECT_TYPE` 选择要加载的图，并在启动时读取 `PGDATABASE_URL`。
+> 类型在创建 Project 时一次性确定，之后再改 `.coze project_type` 不会改变已有 Project 的类型。
+
+指定 PPE 泳道时，增加全局参数 `--lane`。CLI 会为所有部署 API 请求发送
+`x-tt-env` 和 `x-use-ppe: 1`，该参数只对当前命令生效：
+
+```bash
+coze-dev deploy --lane ppe_deploy code app list
+coze-dev deploy --lane ppe_deploy code deploy --source-root .
+```
+
+## 命令
+
+```text
+coze-dev deploy context show
+coze-dev deploy auth login|status|logout
+coze-dev deploy context use --space-id <space_id>
+coze-dev deploy doctor
+coze-dev deploy code app list [--page-size <n>] [--page-token <token>] [--all]
+coze-dev deploy code app show --app-id <app_id>
+coze-dev deploy code app rename <name> --app-id <app_id> --yes
+coze-dev deploy code app delete --app-id <app_id> --yes
+coze-dev deploy code app analytics|metrics --app-id <app_id> [--time-range <range>]
+coze-dev deploy code app usage --app-id <app_id> --bill-month <YYYY-MM>
+coze-dev deploy [--lane <ppe_lane>] code deploy [--source-root <directory>] [--app-id <app_id>] [--application-type <type>] [--name <name>] [--connector-id <id>]
+coze-dev deploy code deploy status|list|online|rollback-check|cancel|rollback|stop|resume|pause
+coze-dev deploy code deploy logs|log-count|count|build-log|config
+coze-dev deploy code domain list [--unit-type dev|prod]
+coze-dev deploy code domain add <domain>
+coze-dev deploy code domain set-prefix <prefix> --app-id <app_id> --yes
+coze-dev deploy code mini-program status|bind|submit-code|unbind
+```
+
+`code app list` 是真分页：一次只返回一页（`--page-size` 默认 20、上限 100），`has_more` 为真时用返回的 `next_page_token` 取下一页；要一次拿到名下全部应用用 `--all`，它会自己翻到底。
+
+部署确认阶段不传 `--yes`；确认后使用相同参数增加 `--yes`，需要等待终态时再增加
+`--wait`。CLI 会为每次请求自动生成一个 40 位十六进制源码快照 ID，用于兼容 V2 接口的
+`commit_hash` 字段，用户无需指定。该 ID 不代表 Git commit；源码目录无需由 Git 管理，
+打包时始终读取目录的最新内容。CLI 会把当前源码目录专属的 `project_id` 和唯一 `app_id`
+写入 `.coze [project]`，ID 使用引号包裹的十进制字符串。后续类型一致时自动复用该
+Application；类型不一致时创建新 Application、覆盖 `app_id` 并提示。也可用 `--project-id`
+或 `--app-id` 显式指定已有资源，显式指定时不会额外创建 Project。
+
+首次部署的应用名称可通过 `--name` 指定；显式参数优先于 `.coze` 的
+`[project].name`。Pages 部署没有 `.coze` 时，CLI 会先生成最小配置再写入绑定。
+
+```toml
+[project]
+name = "Phaser 游戏"
+project_type = "web"
+project_id = "987654321"
+app_id = "123456789"
+```
+
+Pages 首次部署没有 `app_id`，必须显式指定交付类型。Pages 将
+`--source-root` 视为项目根目录：根目录已有 `index.html` 时直接打包；否则读取 `.coze`，
+要求 `project.template = "nextjs"` 且 `deploy.build` 为非空命令数组。CLI 不在本地安装
+依赖或执行 Pages 构建，只上传源码；Deploy 服务在 Sandbox 中注入 Next.js 静态导出配置，
+执行 `deploy.build`，并要求最终产出 `out/index.html`：
+
+```bash
+coze-dev deploy code deploy --source-root . --application-type pages
+coze-dev deploy code deploy --source-root . --application-type pages --yes --wait
+```
+
+创建成功后 CLI 会把 Pages Application 写入 `.coze`；后续可继续传
+`--application-type pages` 自动复用，或显式传 `--app-id`。
+
+V2 接口的所有参数均通过 POST JSON body 发送，不会放入 URL。确认非 Pages 部署后，CLI
+会执行 `.coze` 中可选的 `dev.pack` 命令，将
+本地部署内容打成无根目录的 `tar.gz`，再通过 `source_package_base64` 上传。Pages 部署
+统一上传源码根目录：已有 `index.html` 时服务端跳过构建，没有时由服务端按 Snapshot 中的
+`.coze deploy.build` 构建。打包由 CLI 自带的 Node.js 脚本执行，并排除 `.coze`、`.env`、
+`.git`、`.venv`、`.codegraph`、`node_modules`、`.next`、`site-packages` 和 `__pycache__`。
+`scripts/package-project.py` 仍随源码和 npm 包保留，仅作为 Python 参考备份与行为对照，
+生产打包链路不会调用 Python。
+
+服务和小程序部署会读取源码根目录的 `.env` 并加密上传；`COZE_` 前缀为平台保留，CLI
+会过滤这类变量，避免覆盖部署运行时由平台注入的配置。
+
+本地环境变量可通过以下命令管理，默认操作当前目录的 `.env`，也可通过
+`--source-root` 指定项目目录；这些命令不会请求部署服务：
+
+```bash
+coze-dev deploy code env list
+coze-dev deploy code env set API_KEY "secret value"
+coze-dev deploy code env delete API_KEY
+coze-dev deploy code env list --source-root ./projects/example
+```
+
+`env set` 和 `env delete` 不允许操作 `COZE_` 前缀的保留变量。
+
+小程序部署可重复指定渠道：微信为 `10000127`，抖音为 `10000126`：
+
+```bash
+coze-dev deploy code deploy --source-root . --application-type mini_program \
+  --connector-id 10000127 --yes --wait
+```
+
+绑定小程序 AppID 时，默认从源码目录 `.coze [project]` 读取该目录的 `project_id`：
+
+```bash
+coze-dev deploy code mini-program bind \
+  --platform wechat \
+  --mini-app-id wx123 \
+  --redirect-url https://code.coze.cn/coding/auth/callback/miniprogram
+```
+
+返回 `bind_status=1` 时，打开 `need_authorize_data.auth_url` 完成授权。回调页会自动
+提交授权码；无回调页的调用方也可使用 `mini-program submit-code` 手动提交。
+
+`code deploy status` 和 `list` 会返回 `deploy_detail[].deploy_log_key`。只有一个日志
+key 时，`code deploy build-log --deploy-id <id>` 会自动解析；存在多个 key 时按错误
+详情中的 `available_keys` 选择一个并传 `--key`。
+
+应用维度的管理和观测命令均支持 `--app-id`；省略时从当前目录的 `.coze [project]` 读取：
+
+```bash
+coze-dev deploy code app rename "新应用名称" --app-id <app_id> --yes
+coze-dev deploy code deploy online --app-id <app_id>
+coze-dev deploy code deploy rollback-check --app-id <app_id> --deploy-id <history_id>
+coze-dev deploy code deploy log-count --app-id <app_id>
+coze-dev deploy code deploy count --app-id <app_id>
+coze-dev deploy code app metrics --app-id <app_id> --time-range week
+coze-dev deploy code app usage --app-id <app_id> --bill-month 2026-08
+coze-dev deploy code domain list --app-id <app_id> --unit-type dev
+```
+
+`domain list` 默认查询 Prod 域名；传 `--unit-type dev` 查询开发态预览域名。
+审核 Unit 是内部流水线槽位，不支持从 CLI 查询。
+
+`code domain set-prefix` 改的是**系统分配的默认域名**（`<prefix>.coze.site`）里的 prefix，
+后缀不变；`code domain add` 加进来的自定义域名不受影响 —— 那类域名服务端只有 create/delete，
+域名串本身改不了。改完旧默认域名立刻不再指向本应用，已经发出去的链接会失效，所以必须传 `--yes`。
+前缀的长度、保留词、是否被占用由服务端判定，CLI 只拦形态明显不合法的值（大写、首尾连字符等）。
+这是**权益能力**：账号没有对应权益时服务端会直接拒绝。
+
+`code app delete` 删除应用，终态不可撤销，必须传 `--yes`。服务端**只接受已停服的应用**：
+仍在服务时会返回一条带当前状态的错误，先跑 `code deploy stop --yes` 再删。CLI 不会替你先停 ——
+停服会真的把线上服务摘掉，那一步要由你自己确认。删除会一并停掉该应用名下的部署单元、
+软删它的域名并清理残留的函数；已删除的应用再删一次是幂等成功。删完记得把 `.coze [project]`
+里的 `app_id` 去掉，否则同目录下一次 `code deploy` 会打到这个已删除的应用上被服务端拒。

package/lib/__templates__/phaser/.coze

@@ -0,0 +1,13 @@
+[project]
+requires = ["nodejs-24"]
+project_type = "game"
+game_type = "phaser"
+
+[dev]
+build = ["bash", "./scripts/prepare.sh"]
+run = ["bash", "./scripts/dev.sh"]
+validate = ["bash", "./scripts/validate.sh"]
+
+[deploy]
+build = ["bash", "./scripts/build.sh"]
+run = ["bash", "./scripts/start.sh"]

package/lib/__templates__/phaser/README.md

@@ -0,0 +1,37 @@
+# <%= appName %>
+
+这是一个基于 Phaser、Vite 和 TypeScript 的 2D 游戏项目，由扣子编程 CLI 创建。
+
+## 快速开始
+
+```bash
+coze-dev dev
+```
+
+开发服务器默认运行在 [http://127.0.0.1:<%= port %>](http://127.0.0.1:<%= port %>)。
+
+```bash
+coze-dev validate  # TypeScript 类型检查
+coze-dev build     # 生产构建
+coze-dev start     # 预览生产构建
+```
+
+## 文件结构
+
+```text
+├── assets/                     # 图片、序列帧、视频和音频
+├── debug-runtime/              # 调试 Flow
+├── src/assets.ts               # 素材 key 与路径
+├── src/main.ts                 # 游戏入口
+├── src/scene/BootScene.ts      # 启动与全量加载
+├── src/utils/asset-loader.ts   # 批量和单素材加载
+├── src/types.ts                # 类型定义
+└── vite.config.ts              # Bridge 注入与素材目录映射
+```
+
+- 素材按类型放在 `assets/`，并登记到 `src/assets.ts` 对应的分类表。
+- 序列帧只登记文件夹；Loader 从 `manifest.json` 读取帧数和帧率。
+- `BootScene` 加载游戏素材；运行时可用 `loadAsset(this, key)` 单独加载。
+- 开发和生产都使用稳定的 `assets/...` 路径，生产构建原样复制素材目录。
+
+`IMAGES`、`IMAGE_SEQUENCES`、`VIDEOS` 和 `AUDIOS` 是四个素材分类表。

package/lib/__templates__/phaser/_gitignore

@@ -0,0 +1,22 @@
+node_modules/
+dist/
+coverage/
+
+.env
+.env.*
+!.env.example
+
+*.log
+*.tsbuildinfo
+.vite/
+.cache/
+node-compile-cache/
+
+.DS_Store
+._*
+.idea/
+.vscode/
+
+.coze-logs/
+.codegraph/
+.preview/

package/lib/__templates__/phaser/_npmrc

@@ -0,0 +1,14 @@
+loglevel=error
+registry=https://registry.npmmirror.com
+
+strictStorePkgContentCheck=false
+verifyStoreIntegrity=false
+network-concurrency=16
+fetch-retries=3
+fetch-timeout=60000
+strict-peer-dependencies=false
+auto-install-peers=true
+lockfile=true
+prefer-frozen-lockfile=true
+resolution-mode=highest
+update-notifier=false

package/lib/__templates__/phaser/assets/image_sequence/coze-game-loading/manifest.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": "1.0",
+  "id": "coze-game-loading",
+  "type": "image_sequence",
+  "properties": {
+    "fps": 12.0,
+    "frame_count": 24
+  },
+  "name": "Coze Game Loading",
+  "sources": []
+}

package/lib/__templates__/phaser/debug-runtime/flow-graph.json

@@ -0,0 +1,20 @@
+{
+  "schema_version": 1,
+  "graphs": [
+    {
+      "id": "main",
+      "label": "主流程",
+      "nodes": [
+        {
+          "id": "start",
+          "label": "开始游戏",
+          "input_schema": {
+            "type": "object",
+            "properties": {}
+          }
+        }
+      ],
+      "transitions": []
+    }
+  ]
+}

package/lib/__templates__/phaser/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= appName %></title>
+  </head>
+  <body>
+    <main id="game" aria-label="Phaser game canvas"></main>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/lib/__templates__/phaser/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "<%= appName %>",
+  "version": "1.0.0",
+  "description": "Phaser 3 game with Vite and TypeScript",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "pnpm typecheck && vite build",
+    "dev": "vite",
+    "preinstall": "npx only-allow pnpm",
+    "preview": "vite preview",
+    "start": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "validate": "pnpm typecheck"
+  },
+  "dependencies": {
+    "phaser": "^3.90.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/serve-static": "^2.2.0",
+    "only-allow": "^1.2.2",
+    "serve-static": "^2.2.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.2.0"
+  },
+  "packageManager": "pnpm@9.0.0",
+  "engines": {
+    "pnpm": ">=9.0.0"
+  }
+}