@coze-arch/cli
Coze Coding 的项目模板与本地运行 CLI。发布包名为 @coze-arch/cli，命令为
coze-dev。
安装
npm install -g @coze-arch/cli
coze-dev --help
也可以不全局安装：
npx @coze-arch/cli --help
初始化项目
coze-dev init my-app --template <template> --app-name my-app
coze-dev init --help
init 默认会渲染模板、安装依赖、初始化 Git、创建初始提交并启动开发服务。按需使用
--skip-install、--skip-git、--skip-commit、--skip-dev 跳过这些步骤。模板名称和
参数以 coze-dev init --help 的实时输出为准；未声明的参数会以 kebab-case 转为
camelCase 后传给模板。
在项目中运行
初始化产物根目录的 .coze 是统一命令契约：
coze-dev dev # 读取 dev.run
coze-dev build # 读取 deploy.build
coze-dev start # 读取 deploy.run
coze-dev validate # 读取 dev.validate
dev 和 build 在执行前会尝试应用模板补丁；补丁失败会记录调试信息，但不会阻止主命令。
子进程日志默认写入 ~/.coze-logs/dev.log，可用 --log-file <path> 覆盖。
Web 云盘开发
Vite、Next.js、Nuxt 的 Unix 开发 wrapper 在 COZE_DRIVE_ROOT（默认 /Coze/Drive）内通过
rsync 同步源码到本机临时目录 coze-web-<uid>/<source-path-hash>/，再安装依赖和执行。
prepare/dev 使用 dev 子目录，validate 使用独立的 check 子目录，避免类型生成干扰热更新。
依赖和开发编译产物留在本地；只有安装成功且云盘依赖输入未变化时才回写锁文件。所有修复仍在云盘完成。
dev 的 detached 进程持续同步，框架只监听本地镜像；同步失败或依赖输入变化时停止服务。
本地镜像仅用于 [dev].build/run/validate；部署配置、build.sh 和 start.sh 保持原流程。
普通本地目录和 Windows PowerShell 入口保持原流程。rsync 由开发环境提供，[dev].deps 仅作声明。
存量项目通过 coze-dev patch --dry-run / coze-dev patch 升级，沿用 patch 总开关。
仅升级完整匹配旧模板的三个 Unix 开发脚本并保留端口；自定义开发脚本、命令和同名 helper 会跳过。
只更新开发插件不会替换存量项目脚本。
Windows 与 WSL
原生 Windows（process.platform === "win32"）优先使用 .coze 中非空的 Windows
覆盖命令；未配置时回退默认命令。WSL 被识别为 Linux，始终执行默认命令。
| CLI 命令或场景 | 默认字段 | Windows 覆盖字段 |
|---|---|---|
coze-dev dev | dev.run | dev.run_win |
coze-dev build | deploy.build | deploy.build_win |
coze-dev start | deploy.run | deploy.run_win |
coze-dev validate | dev.validate | dev.validate_win |
coze-dev deploy 的本地打包 | dev.pack | dev.pack_win |
已支持 Windows 的内置 Web 与 Phaser 模板将覆盖命令映射到 PowerShell 脚本，例如：
[dev]
run = ["bash", "./scripts/dev.sh"]
run_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/dev.ps1"]
[deploy]
build = ["bash", "./scripts/build.sh"]
build_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/build.ps1"]
部署
coze-dev deploy 内置于同一 CLI。认证优先读取
~/.coze/desktop/runtime.beta.json，其次读取 ~/.coze/desktop/runtime.json；
CLI 会依次验证候选 Token，收到 401 时继续尝试下一项，再回退到
COZE_API_TOKEN 和 ~/.coze/cli/config.json 登录态：
coze-dev deploy auth login
coze-dev deploy doctor
coze-dev deploy --source-root . --yes --wait
完整的应用、环境变量、Pages 和小程序命令说明见 部署文档。
dev.pack_win 是自定义模板可选的 Windows 打包覆盖；当前 Expo、Taro 和 Pi Agent 模板
不承诺 Windows 支持。
模板开发
模板位于 src/__templates__/，每个模板通过 template.config.ts 定义参数和渲染钩子，
.coze 定义生成项目的运行命令。新增模板或修改模板目录后执行：
npm run prebuild
模板开发细节见 模板开发指南。仓库开发依赖由 Rush 管理，不要在本包目录单独执行 npm install 或 pnpm install。
本地开发与验证
源码入口支持直接运行，无需先构建：
node src/cli.js --help
npm run test
npm run build
端到端模板验证使用 npm run test:e2e，会真实安装模板依赖并启动服务。发布前需完成该验证。
Web 镜像集成测试使用 npm run test:integration:web，依赖 Node.js、bash、rsync 和临时
loopback 监听权限；包管理器和框架命令使用替身，验证目录、同步、锁文件与进程生命周期，
不替代真实框架 E2E。