@coze-arch/cli 0.0.1-alpha.e8683e → 0.0.1-alpha.e89608

package/lib/__templates__/taro/src/presets/h5-styles.ts

@@ -0,0 +1,142 @@
+/**
+ * H5 端特殊样式注入
+ * 如无必要，请勿修改本文件
+ */
+
+const H5_BASE_STYLES = `
+/* H5 端隐藏 TabBar 空图标（只隐藏没有 src 的图标） */
+.weui-tabbar__icon:not([src]),
+.weui-tabbar__icon[src=''] {
+  display: none !important;
+}
+
+.weui-tabbar__item:has(.weui-tabbar__icon:not([src])) .weui-tabbar__label,
+.weui-tabbar__item:has(.weui-tabbar__icon[src='']) .weui-tabbar__label {
+  margin-top: 0 !important;
+}
+
+/* Vite 错误覆盖层无法选择文本的问题 */
+vite-error-overlay {
+  /* stylelint-disable-next-line property-no-vendor-prefix */
+  -webkit-user-select: text !important;
+}
+
+vite-error-overlay::part(window) {
+  max-width: 90vw;
+  padding: 10px;
+}
+
+.taro_page {
+  overflow: auto;
+}
+
+::-webkit-scrollbar {
+  width: 4px;
+  height: 4px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: rgba(0, 0, 0, 0.2);
+  border-radius: 2px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: rgba(0, 0, 0, 0.3);
+}
+
+/* H5 导航栏页面自动添加顶部间距 */
+body.h5-navbar-visible .taro_page {
+  padding-top: 44px;
+}
+`;
+
+const PC_WIDESCREEN_STYLES = `
+/* PC 宽屏适配 - 基础布局 */
+@media (min-width: 769px) {
+  html {
+    font-size: 15px !important;
+  }
+
+  body {
+    background-color: #f3f4f6 !important;
+    display: flex !important;
+    justify-content: center !important;
+    align-items: center !important;
+    min-height: 100vh !important;
+  }
+}
+`;
+
+const PC_WIDESCREEN_PHONE_FRAME = `
+/* PC 宽屏适配 - 手机框样式（有 TabBar 页面） */
+@media (min-width: 769px) {
+  .taro-tabbar__container {
+    width: 375px !important;
+    max-width: 375px !important;
+    height: calc(100vh - 40px) !important;
+    max-height: 900px !important;
+    background-color: #fff !important;
+    transform: translateX(0) !important;
+    box-shadow: 0 0 20px rgba(0, 0, 0, 0.1) !important;
+    border-radius: 20px !important;
+    overflow: hidden !important;
+    position: relative !important;
+  }
+
+  .taro-tabbar__panel {
+    height: 100% !important;
+    overflow: auto !important;
+  }
+}
+
+/* PC 宽屏适配 - 手机框样式（无 TabBar 页面，通过 JS 添加 no-tabbar 类） */
+@media (min-width: 769px) {
+  body.no-tabbar #app {
+    width: 375px !important;
+    max-width: 375px !important;
+    height: calc(100vh - 40px) !important;
+    max-height: 900px !important;
+    background-color: #fff !important;
+    box-shadow: 0 0 20px rgba(0, 0, 0, 0.1) !important;
+    border-radius: 20px !important;
+    overflow: hidden !important;
+    position: relative !important;
+    transform: translateX(0) !important;
+  }
+
+  body.no-tabbar #app .taro_router {
+    height: 100% !important;
+    overflow: auto !important;
+  }
+}
+`;
+
+function injectStyles() {
+  const style = document.createElement('style');
+  style.innerHTML =
+    H5_BASE_STYLES + PC_WIDESCREEN_STYLES + PC_WIDESCREEN_PHONE_FRAME;
+  document.head.appendChild(style);
+}
+
+function setupTabbarDetection() {
+  const checkTabbar = () => {
+    const hasTabbar = !!document.querySelector('.taro-tabbar__container');
+    document.body.classList.toggle('no-tabbar', !hasTabbar);
+  };
+
+  checkTabbar();
+
+  const observer = new MutationObserver(checkTabbar);
+  observer.observe(document.body, { childList: true, subtree: true });
+}
+
+export function injectH5Styles() {
+  if (TARO_ENV !== 'h5') return;
+
+  injectStyles();
+  setupTabbarDetection();
+}

package/lib/__templates__/taro/src/presets/index.tsx

@@ -0,0 +1,18 @@
+import { useLaunch } from '@tarojs/taro';
+import { PropsWithChildren } from 'react';
+import { injectH5Styles } from './h5-styles';
+import { devDebug } from './dev-debug';
+import { H5Container } from './h5-container';
+
+export const Preset = ({ children }: PropsWithChildren) => {
+  useLaunch(() => {
+    devDebug();
+    injectH5Styles();
+  });
+
+  if (TARO_ENV === 'h5') {
+    return <H5Container>{children}</H5Container>;
+  }
+
+  return <>{children}</>;
+};

package/lib/__templates__/taro/stylelint.config.mjs

@@ -0,0 +1,4 @@
+/** @type {import('stylelint').Config} */
+export default {
+  extends: "stylelint-config-standard",
+};

package/lib/__templates__/taro/template.config.js

@@ -0,0 +1,68 @@
+
+
+
+
+
+
+
+
+
+const description = `Taro（小程序 + H5）：\`coze init \${COZE_WORKSPACE_PATH} --template taro\`
+- 适用：微信小程序、H5 跨端应用
+- 前后端分离架构：Taro 4 + NestJS
+- 支持微信小程序和 H5 双端构建
+- 使用 TailwindCSS + weapp-tailwindcss 实现跨端样式`;
+
+export const paramsSchema = {
+  type: 'object',
+  properties: {
+    appName: {
+      type: 'string',
+      minLength: 1,
+      pattern: '^[a-z0-9-]+$',
+      description:
+        'Application name (lowercase, alphanumeric and hyphens only)',
+    },
+    port: {
+      type: 'number',
+      default: 5000,
+      minimum: 1024,
+      maximum: 65535,
+      description: 'H5 development server port',
+    },
+    serverPort: {
+      type: 'number',
+      default: 3000,
+      minimum: 1024,
+      maximum: 65535,
+      description: 'NestJS backend server port',
+    },
+  },
+  required: [],
+  additionalProperties: false,
+};
+
+const config = {
+  description: description,
+  paramsSchema,
+  defaultParams: {
+    port: 5000,
+    serverPort: 3000,
+    appName: 'coze-mini-program',
+  },
+  onBeforeRender: async context => {
+    console.log(`Creating Taro project: ${context.appName}`);
+    return context;
+  },
+  onAfterRender: async (context, outputPath) => {
+    console.log(`\nProject created at: ${outputPath}`);
+    console.log('\nConfiguration:');
+    console.log('  - Framework: Taro 4 + NestJS');
+    console.log('  - TypeScript: enabled');
+    console.log('  - Platforms: H5, WeChat Mini Program');
+    console.log(`  - H5 Port: ${context.port}`);
+    console.log(`  - Server Port: ${context.serverPort}`);
+  },
+};
+
+export default config;

package/lib/__templates__/taro/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "es2017",
+    "module": "ESNext",
+    "removeComments": false,
+    "preserveConstEnums": true,
+    "moduleResolution": "bundler",
+    "experimentalDecorators": true,
+    "noImplicitAny": false,
+    "allowSyntheticDefaultImports": true,
+    "outDir": "lib",
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "strictNullChecks": true,
+    "sourceMap": true,
+    "rootDir": ".",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "resolveJsonModule": true,
+    "typeRoots": [
+      "node_modules/@types"
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["./src", "./types", "./config"],
+  "compileOnSave": false
+}

package/lib/__templates__/taro/types/global.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="@tarojs/taro" />
+
+declare const PROJECT_DOMAIN: string | undefined;
+declare const TARO_ENV: "weapp" | "h5" | undefined;
+
+declare module '*.png';
+declare module '*.gif';
+declare module '*.jpg';
+declare module '*.jpeg';
+declare module '*.svg';
+declare module '*.css';
+declare module '*.less';
+declare module '*.scss';
+declare module '*.sass';
+declare module '*.styl';
+
+declare namespace NodeJS {
+  interface ProcessEnv {
+    /** NODE 内置环境变量, 会影响到最终构建生成产物 */
+    NODE_ENV: 'development' | 'production',
+    /** 当前构建的平台 */
+    TARO_ENV: 'weapp' | 'swan' | 'alipay' | 'h5' | 'rn' | 'tt' | 'qq' | 'jd' | 'harmony' | 'jdrn'
+    /**
+     * 当前构建的小程序 appid
+     * @description 若不同环境有不同的小程序，可通过在 env 文件中配置环境变量`TARO_APP_ID`来方便快速切换 appid， 而不必手动去修改 dist/project.config.json 文件
+     * @see https://taro-docs.jd.com/docs/next/env-mode-config#特殊环境变量-taro_app_id
+     */
+    TARO_APP_ID: string
+  }
+}
+
+

package/lib/__templates__/templates.json

@@ -26,6 +26,17 @@
         "additionalProperties": false
       }
     },
+    {
+      "name": "native-static",
+      "description": "Native Static（纯静态）：`coze init ${COZE_WORKSPACE_PATH} --template native-static`\n- 适用：纯静态 HTML/CSS/JS 项目、静态网站\n- 使用 Python http.server 作为开发服务器\n- 不需要 Node.js 环境，适合简单静态内容",
+      "location": "./native-static",
+      "paramsSchema": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+        "additionalProperties": false
+      }
+    },
     {
       "name": "nextjs",
       "description": "Next.js（复杂项目）：`coze init ${COZE_WORKSPACE_PATH} --template nextjs`\n- 适用：全栈应用、复杂多页面等复杂项目\n- 使用默认nextjs项目规范\n    - **目录规范**： 默认开启src目录（打开--src-dir选项）：项目文件（如 app 目录、pages 目录、components 等）初始化到 src/ 目录下。\n    - **项目理解加速**：初始可以依赖项目下 `package.json` 文件理解项目类型，如果没有或无法理解退化成阅读其他文件。\n    - **UI设计与组件规范**：Next.js项目**必须默认**采用 shadcn/ui 风格和规范，`shadcn/ui`组件默认完整的预装在`src/components/ui/`目录下",
@@ -51,6 +62,70 @@
         "additionalProperties": false
       }
     },
+    {
+      "name": "nuxt-vue",
+      "description": "Nuxt.js（服务端 + Vue）：`coze init ${COZE_WORKSPACE_PATH} --template nuxt-vue`\n- 适用：全栈应用、需要服务端接口能力的 Vue 项目\n- 特点：\n    - **服务端能力**：内置服务端 API 路由，可直接创建后端接口\n    - **Vue 3**：基于最新的 Vue 3 Composition API\n    - **Vite**：使用 Vite 作为构建工具，开发体验极佳\n    - **TypeScript**：完整的 TypeScript 支持\n    - **文件路由**：基于文件系统的自动路由\n    - **项目理解加速**：可依赖项目下 `package.json` 和 `nuxt.config.ts` 理解项目配置",
+      "location": "./nuxt-vue",
+      "paramsSchema": {
+        "type": "object",
+        "properties": {
+          "appName": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z0-9-]+$",
+            "description": "Application name (lowercase, alphanumeric and hyphens only)"
+          },
+          "port": {
+            "type": "number",
+            "default": 5000,
+            "minimum": 1024,
+            "maximum": 65535,
+            "description": "Development server port (for Nuxt dev server)"
+          },
+          "hmrPort": {
+            "type": "number",
+            "default": 6000,
+            "minimum": 1024,
+            "maximum": 65535,
+            "description": "Hot Module Replacement (HMR) port"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "taro",
+      "description": "Taro（小程序 + H5）：`coze init ${COZE_WORKSPACE_PATH} --template taro`\n- 适用：微信小程序、H5 跨端应用\n- 前后端分离架构：Taro 4 + NestJS\n- 支持微信小程序和 H5 双端构建\n- 使用 TailwindCSS + weapp-tailwindcss 实现跨端样式",
+      "location": "./taro",
+      "paramsSchema": {
+        "type": "object",
+        "properties": {
+          "appName": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z0-9-]+$",
+            "description": "Application name (lowercase, alphanumeric and hyphens only)"
+          },
+          "port": {
+            "type": "number",
+            "default": 5000,
+            "minimum": 1024,
+            "maximum": 65535,
+            "description": "H5 development server port"
+          },
+          "serverPort": {
+            "type": "number",
+            "default": 3000,
+            "minimum": 1024,
+            "maximum": 65535,
+            "description": "NestJS backend server port"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      }
+    },
     {
       "name": "vite",
       "description": "Vite（简单项目）：`coze init ${COZE_WORKSPACE_PATH} --template vite`\n- 适用：轻量级 SPA、纯前端交互、仪表盘等轻量级项目。",

package/lib/__templates__/vite/README.md

@@ -1,6 +1,12 @@
 # <%= appName %>
 
-这是一个基于 TypeScript + Vite + Tailwind CSS 的轻量级 Web 应用项目，由扣子编程 CLI 创建。
+这是一个基于 Koa + Vite + TypeScript + Tailwind CSS 的全栈 Web 应用项目，由扣子编程 CLI 创建。
+
+**核心特性：**
+- 🚀 前端：Vite + TypeScript + Tailwind CSS
+- 🔧 后端：Koa + TypeScript，提供 RESTful API
+- 🔥 开发模式：Vite HMR + Koa API，单进程启动
+- 📦 生产模式：Koa 静态服务 + API，高性能部署
 
 ## 快速开始
 
@@ -33,19 +39,147 @@ coze start
 ## 项目结构
 
 ```
-├── index.html              # HTML 入口文件
-├── src/
-│   ├── index.ts           # 应用入口（初始化）
-│   ├── main.ts            # 主逻辑文件
-│   └── index.css          # 全局样式（包含 Tailwind 指令）
-├── vite.config.ts         # Vite 配置
-├── tailwind.config.ts     # Tailwind CSS 配置
-└── tsconfig.json          # TypeScript 配置
+├── server/                # 后端服务器目录
+│   ├── index.ts          # Koa 服务器入口
+│   ├── routes/           # API 路由目录
+│   │   └── index.ts      # 路由定义
+│   └── vite.ts           # Vite 集成逻辑
+├── src/                   # 前端源码目录
+│   ├── index.ts          # 前端应用入口（初始化）
+│   ├── main.ts           # 前端主逻辑文件
+│   └── index.css         # 全局样式（包含 Tailwind 指令）
+├── index.html            # HTML 入口文件
+├── vite.config.ts        # Vite 配置
+├── tailwind.config.ts    # Tailwind CSS 配置
+└── tsconfig.json         # TypeScript 配置
 ```
 
+**目录说明：**
+
+- **`server/`** - 后端服务器代码
+  - `index.ts` - 服务器主入口，负责创建和启动 Koa 应用
+  - `routes/` - API 路由模块，支持按功能拆分路由
+  - `vite.ts` - Vite 开发服务器和静态文件服务集成
+
+- **`src/`** - 前端应用代码
+  - 所有前端相关代码都在这里
+
+**工作原理：**
+
+- **开发模式** (`coze dev`)：
+  - 运行 `server/index.ts` 启动 Koa 服务器
+  - Vite 以 middleware 模式集成到 Koa
+  - 前端支持 HMR（热模块替换）
+  - 后端 API 和前端在同一进程，端口 <%= port %>
+
+- **生产模式** (`coze start`)：
+  - `coze build` 构建前端 → `dist/` 目录
+  - `coze build` 构建后端 → `dist-server/index.js` (CommonJS 格式)
+  - 运行 `dist-server/index.js` 启动生产服务器
+  - Koa 服务静态文件 + API 路由
+  - 单一 Node.js 进程，轻量高效
+
 ## 核心开发规范
 
-### 1. 样式开发
+### 1. 后端 API 开发
+
+**添加新的 API 路由**
+
+在 `server/routes/index.ts` 中添加路由：
+
+```typescript
+// GET 请求示例
+router.get('/api/users', async (ctx) => {
+  ctx.body = {
+    users: [
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+    ],
+  };
+});
+
+// POST 请求示例
+router.post('/api/users', async (ctx) => {
+  const userData = ctx.request.body;
+  // 处理业务逻辑
+  ctx.body = {
+    success: true,
+    user: userData,
+  };
+});
+
+// 动态路由参数
+router.get('/api/users/:id', async (ctx) => {
+  const userId = ctx.params.id;
+  ctx.body = {
+    id: userId,
+    name: 'User ' + userId,
+  };
+});
+```
+
+**拆分路由模块**（推荐）
+
+当路由变多时，可以按功能拆分：
+
+```typescript
+// server/routes/users.ts
+import Router from '@koa/router';
+
+const router = new Router();
+
+router.get('/api/users', async (ctx) => {
+  // 用户列表逻辑
+});
+
+router.post('/api/users', async (ctx) => {
+  // 创建用户逻辑
+});
+
+export default router;
+```
+
+然后在 `server/index.ts` 中注册：
+
+```typescript
+import usersRouter from './routes/users';
+
+// 注册路由
+app.use(usersRouter.routes()).use(usersRouter.allowedMethods());
+```
+
+**前端调用 API**
+
+```typescript
+// GET 请求
+async function getUsers() {
+  const response = await fetch('/api/users');
+  const data = await response.json();
+  console.log(data);
+}
+
+// POST 请求
+async function createUser(name: string) {
+  const response = await fetch('/api/users', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ name }),
+  });
+  const data = await response.json();
+  console.log(data);
+}
+```
+
+**API 最佳实践**
+
+- ✅ 所有 API 路由以 `/api` 开头，避免与前端路由冲突
+- ✅ 使用 RESTful 设计：GET 查询、POST 创建、PUT 更新、DELETE 删除
+- ✅ 返回统一的响应格式：`{ success: boolean, data?: any, error?: string }`
+- ✅ 添加错误处理和参数验证
+
+### 2. 样式开发
 
 **使用 Tailwind CSS**
 
@@ -219,17 +353,32 @@ console.log(apiUrl); // https://api.example.com
 
 ## 技术栈
 
-- **构建工具**: Vite 6.x
+**前端：**
+- **构建工具**: Vite 7.x
 - **语言**: TypeScript 5.x
 - **样式**: Tailwind CSS 3.x
+
+**后端：**
+- **框架**: Koa 2.x
+- **路由**: @koa/router 13.x
+- **中间件**: koa-bodyparser, koa-static
+
+**工具：**
 - **包管理器**: pnpm 9+
+- **运行时**: Node.js 18+
+- **开发工具**: tsx (TypeScript 执行器)
 
 ## 参考文档
 
+**前端：**
 - [Vite 官方文档](https://cn.vitejs.dev/)
 - [TypeScript 官方文档](https://www.typescriptlang.org/zh/docs/)
 - [Tailwind CSS 文档](https://tailwindcss.com/docs)
 
+**后端：**
+- [Koa 官方文档](https://koajs.com/)
+- [Koa Router 文档](https://github.com/koajs/router)
+
 ## 重要提示
 
 1. **必须使用 pnpm** 作为包管理器
@@ -237,3 +386,32 @@ console.log(apiUrl); // https://api.example.com
 3. **使用 Tailwind CSS** 进行样式开发，支持响应式和暗色模式
 4. **环境变量必须以 `VITE_` 开头** 才能在客户端代码中访问
 5. **开发时使用 `coze dev`**，支持热更新和快速刷新
+6. **API 路由以 `/api` 开头**，避免与前端路由冲突
+7. **单进程架构**：开发和生产环境都是前后端在同一进程中运行
+
+## 常见问题
+
+**Q: 如何分离前后端端口？**
+
+如果需要前后端分离部署，可以：
+- 前端：使用 `npx vite` 单独启动（默认端口 5173）
+- 后端：修改 `server.ts`，移除 Vite middleware，单独启动
+
+**Q: 如何添加数据库？**
+
+```bash
+# 安装数据库客户端（以 PostgreSQL 为例）
+pnpm add pg
+pnpm add -D @types/pg
+
+# 在 server.ts 中使用
+import { Pool } from 'pg';
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+```
+
+**Q: 如何部署？**
+
+1. 运行 `coze build` 构建前后端
+2. 将整个项目上传到服务器
+3. 运行 `pnpm install --prod`
+4. 运行 `coze start` 启动服务

package/lib/__templates__/vite/_gitignore

@@ -5,6 +5,7 @@ node_modules/
 
 # Production build
 dist/
+dist-server/
 build/
 out/
 

package/lib/__templates__/vite/eslint.config.mjs

@@ -5,5 +5,10 @@ import { defineConfig, globalIgnores } from 'eslint/config';
 export default defineConfig([
   eslint.configs.recommended,
   ...tseslint.configs.recommended,
-  globalIgnores(['dist/**', 'node_modules/**']),
+  globalIgnores([
+    'dist/**',
+    'dist-server/**',
+    'node_modules/**',
+    'scripts/**',
+  ]),
 ]);

package/lib/__templates__/vite/package.json

@@ -1,7 +1,7 @@
 {
   "name": "<%= appName %>",
   "version": "1.0.0",
-  "description": "Vanilla TypeScript application with Vite (HTML + CSS + TS)",
+  "description": "Vanilla TypeScript application with Koa + Vite (HTML + CSS + TS + Node API)",
   "scripts": {
     "build": "bash ./scripts/build.sh",
     "dev": "bash ./scripts/dev.sh",
@@ -10,13 +10,29 @@
     "start": "bash ./scripts/start.sh",
     "ts-check": "tsc -p tsconfig.json"
   },
+  "dependencies": {
+    "@koa/router": "^12.0.1",
+    "@supabase/supabase-js": "2.95.3",
+    "dotenv": "^17.2.3",
+    "koa": "^2.15.3",
+    "koa-bodyparser": "^4.4.1",
+    "koa-static": "^5.0.0"
+  },
   "devDependencies": {
+    "@types/koa": "^2.15.0",
+    "@types/koa__router": "^12.0.4",
+    "@types/koa-bodyparser": "^4.3.12",
+    "@types/koa-static": "^4.0.4",
+    "@types/node": "^22.10.5",
     "autoprefixer": "^10.4.20",
-    "coze-coding-dev-sdk": "^0.7.3",
+    "coze-coding-dev-sdk": "^0.7.16",
+    "esbuild": "^0.24.2",
     "eslint": "^9",
     "only-allow": "^1.2.2",
     "postcss": "^8.4.49",
     "tailwindcss": "^3.4.17",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8",
     "vite": "^7.2.4"
@@ -27,7 +43,8 @@
   },
   "pnpm": {
     "overrides": {
-      "esbuild": "^0.27.2"
+      "esbuild": "^0.27.2",
+      "is-generator-function": "1.0.10"
     }
   }
 }