# @coze-arch/cli

Coze Coding 的项目模板与本地运行 CLI。发布包名为 `@coze-arch/cli`，命令为
`coze-dev`。

## 安装

```bash
npm install -g @coze-arch/cli
coze-dev --help
```

也可以不全局安装：

```bash
npx @coze-arch/cli --help
```

## 初始化项目

```bash
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` 是统一命令契约：

```bash
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 脚本，例如：

```toml
[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` 登录态：

```bash
coze-dev deploy auth login
coze-dev deploy doctor
coze-dev deploy --source-root . --yes --wait
```

完整的应用、环境变量、Pages 和小程序命令说明见 [部署文档](./docs/deploy.md)。
`dev.pack_win` 是自定义模板可选的 Windows 打包覆盖；当前 Expo、Taro 和 Pi Agent 模板
不承诺 Windows 支持。

## 模板开发

模板位于 `src/__templates__/`，每个模板通过 `template.config.ts` 定义参数和渲染钩子，
`.coze` 定义生成项目的运行命令。新增模板或修改模板目录后执行：

```bash
npm run prebuild
```

模板开发细节见 [模板开发指南](./docs/how-to-dev.md)。仓库开发依赖由 Rush 管理，不要在本包目录单独执行 `npm install` 或 `pnpm install`。

## 本地开发与验证

源码入口支持直接运行，无需先构建：

```bash
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。