@coze-arch/cli 0.0.8-beta.0 → 0.0.9

package/lib/__templates__/expo/AGENTS.md

@@ -7,33 +7,49 @@
 - Expo 代码在 client 目录，Express.js 代码在 server 目录
 - 本模板默认无 Tab Bar，可按需改造
 
-目录结构说明
-
-├── server/                     # 服务端代码根目录 (Express.js)
-|   ├── src/
-│   │   └── index.ts            # Express 入口文件
-|   └── package.json            # 服务端 package.json
 ├── client/                     # React Native 前端代码
 │   ├── app/                    # Expo Router 路由目录（仅路由配置）
 │   │   ├── _layout.tsx         # 根布局文件（必需，务必阅读）
-│   │   ├── home.tsx            # 首页
-│   │   └── index.tsx           # re-export home.tsx
+│   │   └── index.tsx           # 首页
 │   ├── screens/                # 页面实现目录（与 app/ 路由对应）
-│   │   └── demo/               # demo 示例页面
-│   │       ├── index.tsx       # 页面组件实现
-│   │       └── styles.ts       # 页面样式
+│   │   └── demo/               # 示例页面
+│   │       └── index.tsx
 │   ├── components/             # 可复用组件
 │   │   └── Screen.tsx          # 页面容器组件（必用）
 │   ├── hooks/                  # 自定义 Hooks
 │   ├── contexts/               # React Context 代码
-│   ├── constants/              # 常量定义（如主题配置）
 │   ├── utils/                  # 工具函数
 │   ├── assets/                 # 静态资源
 |   └── package.json            # Expo 应用 package.json
+├── server/                     # 服务端代码根目录 (Express.js)
+|   ├── src/
+│   │   └── index.ts            # 服务端入口文件
+|   └── package.json            # 服务端 package.json
 ├── package.json
 ├── .cozeproj                   # 预置脚手架脚本（禁止修改）
 └── .coze                       # 配置文件（禁止修改）
 
+## 样式方案
+
+基于 tailwindcss 进行样式开发（底层基于 Uniwind）
+
+写法示例：
+
+```tsx
+<View className="flex-1 bg-white dark:bg-gray-900 p-4"></View>
+```
+
+```tsx
+<Text
+  className="text-lg font-bold text-gray-900 dark:text-white"
+  selectionColorClassName="accent-blue-500"
+>
+  Hello World
+</Text>
+```
+
+Uniwind 官方文档：https://docs.uniwind.dev/llms.txt
+
 ## 如何进行静态校验（TSC + ESLint）
 
 ```bash
@@ -47,6 +63,157 @@ npm run lint:client
 npm run lint:server
 ```
 
+## 如何修改主题模式（跟随系统、固定暗色、固定亮色）
+
+默认为跟随系统，如果用户明确指定为“暗色”或“亮色”，需要修改 `client/components/ColorSchemeUpdater.tsx` 的 `DEFAULT_THEME` 变量为合适的值
+
+## 路由及 Tab Bar 实现规范
+
+### 方案一：无 Tab Bar（Stack 导航）
+
+适用于线性流程应用，采用简化的目录结构：
+
+```
+client/app/
+├── _layout.tsx         # 根布局（Stack 导航配置）
+├── index.tsx           # 应用入口
+├── detail.tsx          # 详情页（通过 params 传递数据）
+└── +not-found.tsx      # 404 页面
+```
+
+**根布局配置** `client/app/_layout.tsx`：
+```tsx
+import { Stack } from 'expo-router';
+
+export default function RootLayout() {
+  return (
+    <Stack screenOptions={{ headerShown: false }}>
+      <Stack.Screen name="index" />
+      <Stack.Screen name="detail" />
+    </Stack>
+  );
+}
+```
+
+**应用入口** `client/app/index.tsx`：
+```tsx
+export { default } from "@/screens/home";
+```
+> **禁止事项**：无 Tab Bar 场景下，不得创建 `(tabs)` 目录。
+
+### 方案二：有 Tab Bar（Tabs 导航）
+
+采用路由分组实现底部导航栏：
+```
+client/app/
+├── _layout.tsx              # 根布局
+├── (tabs)/
+│   ├── _layout.tsx          # Tab 导航配置
+│   ├── index.tsx            # 默认 Tab（必须存在）
+│   ├── discover.tsx         # 发现页
+│   └── profile.tsx          # 个人中心
+├── detail.tsx               # Tab 外的独立页面（通过 params 传递数据）
+└── +not-found.tsx
+```
+> **⚠️ [CRITICAL]**： `app/index.tsx` 优先级高于 `(tabs)/index.tsx`，会导致首页无 Tab Bar。**当有(tabs)/index.tsx时必须删除 `app/index.tsx`**。
+
+**根布局配置** `client/app/_layout.tsx`：
+```tsx
+import { Stack } from 'expo-router';
+
+export default function RootLayout() {
+  return (
+    <Stack screenOptions={{ headerShown: false }}>
+      <Stack.Screen name="(tabs)" />
+      <Stack.Screen name="detail" />
+    </Stack>
+  );
+}
+```
+
+**应用入口** `client/app/(tabs)/index.tsx`：
+```tsx
+export { default } from "@/screens/home";
+```
+
+**Tab 布局配置** `client/app/(tabs)/_layout.tsx`：
+
+```tsx
+import { Tabs } from 'expo-router';
+import { Platform } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { FontAwesome6 } from '@expo/vector-icons';
+import { useCSSVariable } from 'uniwind';
+
+export default function TabLayout() {
+  const insets = useSafeAreaInsets();
+  const [background, muted, accent, border] = useCSSVariable([
+    '--color-background',
+    '--color-muted',
+    '--color-accent',
+    '--color-border',
+  ]) as string[];
+
+  return (
+    <Tabs
+      screenOptions={{
+        headerShown: false,
+        tabBarStyle: {
+          backgroundColor: background,
+          borderTopWidth: 1,
+          borderTopColor: border,
+          // 移动端：标准高度 50px + 底部安全区
+          // Web端：固定60px，无需安全区
+          height: Platform.OS === 'web' ? 60 : 50 + insets.bottom,
+          // 移动端：内容区域底部 padding 防止内容被遮挡
+          paddingBottom: Platform.OS === 'web' ? 0 : insets.bottom,
+        },
+        tabBarActiveTintColor: accent,
+        tabBarInactiveTintColor: muted,
+        tabBarItemStyle: {
+          // Web 端必须显式指定 item 高度，防止 Tab Bar 高度塌陷或图标显示异常
+          height: Platform.OS === 'web' ? 60 : undefined,
+        },
+      }}
+    >
+      {/* name 必须与文件名完全一致 */}
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: '首页',
+          tabBarIcon: ({ color }) => (
+            <FontAwesome6 name="house" size={20} color={color} />
+          ),
+        }}
+      />
+      <Tabs.Screen
+        name="discover"
+        options={{
+          title: '发现',
+          tabBarIcon: ({ color }) => (
+            <FontAwesome6 name="compass" size={20} color={color} />
+          ),
+        }}
+      />
+      <Tabs.Screen
+        name="profile"
+        options={{
+          title: '我的',
+          tabBarIcon: ({ color }) => (
+            <FontAwesome6 name="user" size={20} color={color} />
+          ),
+        }}
+      />
+    </Tabs>
+  );
+}
+```
+
+**Tab 页面文件** `client/app/(tabs)/index.tsx`：
+```tsx
+export { default } from "@/screens/home";
+```
+
 ## 依赖管理与模块导入规范
 
 ### 依赖安装
@@ -83,8 +250,4 @@ import { Screen } from '../../../components/Screen';
 
 ## 本地开发
 
-运行 coze dev 可以同时启动前端和后端服务，如果端口已占用，该命令会先杀掉占用端口的进程再启动，也可以用来重启前端和后端服务
-
-```bash
-coze dev
-```
+`coze dev`：用来首次启动前后端服务，也可以用来重启前后端服务（该命令会先尝试杀掉占用端口的进程，再启动服务）

package/lib/__templates__/expo/README.md

@@ -7,33 +7,49 @@
 - Expo 代码在 client 目录，Express.js 代码在 server 目录
 - 本模板默认无 Tab Bar，可按需改造
 
-目录结构说明
-
-├── server/                     # 服务端代码根目录 (Express.js)
-|   ├── src/
-│   │   └── index.ts            # Express 入口文件
-|   └── package.json            # 服务端 package.json
 ├── client/                     # React Native 前端代码
 │   ├── app/                    # Expo Router 路由目录（仅路由配置）
 │   │   ├── _layout.tsx         # 根布局文件（必需，务必阅读）
-│   │   ├── home.tsx            # 首页
-│   │   └── index.tsx           # re-export home.tsx
+│   │   └── index.tsx           # 首页
 │   ├── screens/                # 页面实现目录（与 app/ 路由对应）
-│   │   └── demo/               # demo 示例页面
-│   │       ├── index.tsx       # 页面组件实现
-│   │       └── styles.ts       # 页面样式
+│   │   └── demo/               # 示例页面
+│   │       └── index.tsx
 │   ├── components/             # 可复用组件
 │   │   └── Screen.tsx          # 页面容器组件（必用）
 │   ├── hooks/                  # 自定义 Hooks
 │   ├── contexts/               # React Context 代码
-│   ├── constants/              # 常量定义（如主题配置）
 │   ├── utils/                  # 工具函数
 │   ├── assets/                 # 静态资源
 |   └── package.json            # Expo 应用 package.json
+├── server/                     # 服务端代码根目录 (Express.js)
+|   ├── src/
+│   │   └── index.ts            # 服务端入口文件
+|   └── package.json            # 服务端 package.json
 ├── package.json
 ├── .cozeproj                   # 预置脚手架脚本（禁止修改）
 └── .coze                       # 配置文件（禁止修改）
 
+## 样式方案
+
+基于 tailwindcss 进行样式开发（底层基于 Uniwind）
+
+写法示例：
+
+```tsx
+<View className="flex-1 bg-white dark:bg-gray-900 p-4"></View>
+```
+
+```tsx
+<Text
+  className="text-lg font-bold text-gray-900 dark:text-white"
+  selectionColorClassName="accent-blue-500"
+>
+  Hello World
+</Text>
+```
+
+Uniwind 官方文档：https://docs.uniwind.dev/llms.txt
+
 ## 如何进行静态校验（TSC + ESLint）
 
 ```bash
@@ -47,6 +63,157 @@ npm run lint:client
 npm run lint:server
 ```
 
+## 如何修改主题模式（跟随系统、固定暗色、固定亮色）
+
+默认为跟随系统，如果用户明确指定为“暗色”或“亮色”，需要修改 `client/components/ColorSchemeUpdater.tsx` 的 `DEFAULT_THEME` 变量为合适的值
+
+## 路由及 Tab Bar 实现规范
+
+### 方案一：无 Tab Bar（Stack 导航）
+
+适用于线性流程应用，采用简化的目录结构：
+
+```
+client/app/
+├── _layout.tsx         # 根布局（Stack 导航配置）
+├── index.tsx           # 应用入口
+├── detail.tsx          # 详情页（通过 params 传递数据）
+└── +not-found.tsx      # 404 页面
+```
+
+**根布局配置** `client/app/_layout.tsx`：
+```tsx
+import { Stack } from 'expo-router';
+
+export default function RootLayout() {
+  return (
+    <Stack screenOptions={{ headerShown: false }}>
+      <Stack.Screen name="index" />
+      <Stack.Screen name="detail" />
+    </Stack>
+  );
+}
+```
+
+**应用入口** `client/app/index.tsx`：
+```tsx
+export { default } from "@/screens/home";
+```
+> **禁止事项**：无 Tab Bar 场景下，不得创建 `(tabs)` 目录。
+
+### 方案二：有 Tab Bar（Tabs 导航）
+
+采用路由分组实现底部导航栏：
+```
+client/app/
+├── _layout.tsx              # 根布局
+├── (tabs)/
+│   ├── _layout.tsx          # Tab 导航配置
+│   ├── index.tsx            # 默认 Tab（必须存在）
+│   ├── discover.tsx         # 发现页
+│   └── profile.tsx          # 个人中心
+├── detail.tsx               # Tab 外的独立页面（通过 params 传递数据）
+└── +not-found.tsx
+```
+> **⚠️ [CRITICAL]**： `app/index.tsx` 优先级高于 `(tabs)/index.tsx`，会导致首页无 Tab Bar。**当有(tabs)/index.tsx时必须删除 `app/index.tsx`**。
+
+**根布局配置** `client/app/_layout.tsx`：
+```tsx
+import { Stack } from 'expo-router';
+
+export default function RootLayout() {
+  return (
+    <Stack screenOptions={{ headerShown: false }}>
+      <Stack.Screen name="(tabs)" />
+      <Stack.Screen name="detail" />
+    </Stack>
+  );
+}
+```
+
+**应用入口** `client/app/(tabs)/index.tsx`：
+```tsx
+export { default } from "@/screens/home";
+```
+
+**Tab 布局配置** `client/app/(tabs)/_layout.tsx`：
+
+```tsx
+import { Tabs } from 'expo-router';
+import { Platform } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { FontAwesome6 } from '@expo/vector-icons';
+import { useCSSVariable } from 'uniwind';
+
+export default function TabLayout() {
+  const insets = useSafeAreaInsets();
+  const [background, muted, accent, border] = useCSSVariable([
+    '--color-background',
+    '--color-muted',
+    '--color-accent',
+    '--color-border',
+  ]) as string[];
+
+  return (
+    <Tabs
+      screenOptions={{
+        headerShown: false,
+        tabBarStyle: {
+          backgroundColor: background,
+          borderTopWidth: 1,
+          borderTopColor: border,
+          // 移动端：标准高度 50px + 底部安全区
+          // Web端：固定60px，无需安全区
+          height: Platform.OS === 'web' ? 60 : 50 + insets.bottom,
+          // 移动端：内容区域底部 padding 防止内容被遮挡
+          paddingBottom: Platform.OS === 'web' ? 0 : insets.bottom,
+        },
+        tabBarActiveTintColor: accent,
+        tabBarInactiveTintColor: muted,
+        tabBarItemStyle: {
+          // Web 端必须显式指定 item 高度，防止 Tab Bar 高度塌陷或图标显示异常
+          height: Platform.OS === 'web' ? 60 : undefined,
+        },
+      }}
+    >
+      {/* name 必须与文件名完全一致 */}
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: '首页',
+          tabBarIcon: ({ color }) => (
+            <FontAwesome6 name="house" size={20} color={color} />
+          ),
+        }}
+      />
+      <Tabs.Screen
+        name="discover"
+        options={{
+          title: '发现',
+          tabBarIcon: ({ color }) => (
+            <FontAwesome6 name="compass" size={20} color={color} />
+          ),
+        }}
+      />
+      <Tabs.Screen
+        name="profile"
+        options={{
+          title: '我的',
+          tabBarIcon: ({ color }) => (
+            <FontAwesome6 name="user" size={20} color={color} />
+          ),
+        }}
+      />
+    </Tabs>
+  );
+}
+```
+
+**Tab 页面文件** `client/app/(tabs)/index.tsx`：
+```tsx
+export { default } from "@/screens/home";
+```
+
 ## 依赖管理与模块导入规范
 
 ### 依赖安装
@@ -83,8 +250,4 @@ import { Screen } from '../../../components/Screen';
 
 ## 本地开发
 
-运行 coze dev 可以同时启动前端和后端服务，如果端口已占用，该命令会先杀掉占用端口的进程再启动，也可以用来重启前端和后端服务
-
-```bash
-coze dev
-```
+`coze dev`：用来首次启动前后端服务，也可以用来重启前后端服务（该命令会先尝试杀掉占用端口的进程，再启动服务）

package/lib/__templates__/expo/client/app/+not-found.tsx

@@ -1,30 +1,15 @@
-import { View, Text, StyleSheet } from 'react-native';
+import { View, Text } from 'react-native';
 import { Link } from 'expo-router';
-import { useTheme } from '@/hooks/useTheme';
-import { Spacing } from '@/constants/theme';
 
 export default function NotFoundScreen() {
-  const { theme } = useTheme();
-
   return (
-    <View style={[styles.container, { backgroundColor: theme.backgroundRoot }]}>
-      <Text>
+    <View className="flex-1 justify-center items-center bg-background">
+      <Text className="text-foreground">
         页面不存在
       </Text>
-      <Link href="/" style={[styles.gohome]}>
+      <Link href="/" className="text-accent mt-6">
         返回首页
       </Link>
     </View>
   );
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    justifyContent: 'center',
-    alignItems: 'center',
-  },
-  gohome: {
-    marginTop: Spacing['2xl'],
-  },
-});

package/lib/__templates__/expo/client/app/_layout.tsx

@@ -1,11 +1,10 @@
-import { useEffect } from 'react';
-import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import { Stack } from 'expo-router';
 import { StatusBar } from 'expo-status-bar';
 import { LogBox } from 'react-native';
 import Toast from 'react-native-toast-message';
-import { AuthProvider } from "@/contexts/AuthContext";
-import { ColorSchemeProvider } from '@/hooks/useColorScheme';
+import { Provider } from '@/components/Provider';
+
+import '../global.css';
 
 LogBox.ignoreLogs([
   "TurboModuleRegistry.getEnforcing(...): 'RNMapsAirModule' could not be found",
@@ -14,23 +13,18 @@ LogBox.ignoreLogs([
 
 export default function RootLayout() {
   return (
-    <AuthProvider>
-      <ColorSchemeProvider>
-        <GestureHandlerRootView style={{ flex: 1 }}>
-          <StatusBar style="dark"></StatusBar>
-          <Stack screenOptions={{
-            // 设置所有页面的切换动画为从右侧滑入，适用于iOS 和 Android
-            animation: 'slide_from_right',
-            gestureEnabled: true,
-            gestureDirection: 'horizontal',
-            // 隐藏自带的头部
-            headerShown: false
-          }}>
-            <Stack.Screen name="index" options={{ title: "" }} />
-          </Stack>
-          <Toast />
-        </GestureHandlerRootView>
-      </ColorSchemeProvider>
-    </AuthProvider>
+    <Provider>
+      <Stack
+        screenOptions={{
+          animation: 'slide_from_right',
+          gestureEnabled: true,
+          gestureDirection: 'horizontal',
+          headerShown: false
+        }}
+      >
+        <Stack.Screen name="index" options={{ title: "" }} />
+      </Stack>
+      <Toast />
+    </Provider>
   );
 }

package/lib/__templates__/expo/client/components/ColorSchemeUpdater.tsx

@@ -0,0 +1,43 @@
+import { Fragment, useEffect, type ReactNode } from 'react';
+import { ColorSchemeName, Platform } from 'react-native';
+import { Uniwind } from 'uniwind'
+
+// system: 跟随系统变化
+// light: 固定为 light 主题
+// dark: 固定为 dark 主题
+const DEFAULT_THEME: 'system' | 'light' | 'dark' = 'system'
+
+const WebOnlyColorSchemeUpdater = function ({ children }: { children?: ReactNode }) {
+  useEffect(() => {
+    Uniwind.setTheme(DEFAULT_THEME);
+  }, []);
+
+  useEffect(() => {
+    function handleMessage(e: MessageEvent<{ event: string; colorScheme: ColorSchemeName; } | undefined>) {
+      if (e.data?.event === 'coze.workbench.colorScheme') {
+        const cs = e.data.colorScheme;
+        if (typeof cs === 'string') {
+          Uniwind.setTheme(cs);
+        }
+      }
+    }
+
+    if (Platform.OS === 'web') {
+      window.addEventListener('message', handleMessage, false);
+    }
+
+    return () => {
+      if (Platform.OS === 'web') {
+        window.removeEventListener('message', handleMessage, false);
+      }
+    }
+  }, []);
+
+  return <Fragment>
+    {children}
+  </Fragment>
+};
+
+export {
+  WebOnlyColorSchemeUpdater,
+}

package/lib/__templates__/expo/client/components/Provider.tsx

@@ -0,0 +1,18 @@
+import { AuthProvider } from '@/contexts/AuthContext';
+import { type ReactNode } from 'react';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { WebOnlyColorSchemeUpdater } from './ColorSchemeUpdater';
+
+function Provider({ children }: { children: ReactNode }) {
+  return <WebOnlyColorSchemeUpdater>
+    <AuthProvider>
+      <GestureHandlerRootView style={{ flex: 1 }}>
+        {children}
+      </GestureHandlerRootView>
+    </AuthProvider>
+  </WebOnlyColorSchemeUpdater>
+}
+
+export {
+  Provider,
+}

package/lib/__templates__/expo/client/components/Screen.tsx

@@ -142,7 +142,7 @@ const KeyboardAwareScrollable = ({
 
 export const Screen = ({
   children,
-  backgroundColor = '#fff',
+  backgroundColor = 'var(--background)',
   statusBarStyle = 'dark',
   statusBarColor = 'transparent',
   safeAreaEdges = ['top', 'left', 'right', 'bottom'],