@coze-arch/cli 0.0.1-alpha.afefde → 0.0.1-alpha.b287c1

package/lib/__templates__/expo/client/declarations.d.ts

@@ -0,0 +1,5 @@
+// declarations.d.ts
+
+declare module 'expo-file-system/legacy' {
+  export * from 'expo-file-system';
+}

package/lib/__templates__/expo/client/eslint.config.mjs

@@ -1,10 +1,15 @@
-import js from "@eslint/js";
-import globals from "globals";
-import tseslint from "typescript-eslint";
-import pluginReact from "eslint-plugin-react";
-import reactHooks from "eslint-plugin-react-hooks";
-import regexp from "eslint-plugin-regexp";
-import pluginImport from "eslint-plugin-import";
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import pluginReact from 'eslint-plugin-react';
+import reactHooks from 'eslint-plugin-react-hooks';
+import regexp from 'eslint-plugin-regexp';
+import pluginImport from 'eslint-plugin-import';
+import fontawesome6 from '../eslint-plugins/fontawesome6/index.js';
+import reanimated from '../eslint-plugins/reanimated/index.js';
+import reactnative from '../eslint-plugins/react-native/index.js';
+import forbidEmoji from '../eslint-plugins/forbid-emoji/index.js';
+import restrictLinearGradient from '../eslint-plugins/restrict-linear-gradient/index.js';
 
 export default [
   {
@@ -15,19 +20,22 @@ export default [
       'src/api/**',       // 排除 src 下的自动生成 API
       '.expo/**',         // 排除 Expo 自动生成的文件
       'tailwind.config.js', // 排除 Tailwind 配置文件
+      '**/*.d.ts',
+      'eslint.config.*',
+      'metro.config.*',
     ],
   },
   regexp.configs["flat/recommended"],
   js.configs.recommended,
   ...tseslint.configs.recommended,
-  
+
   // React 的推荐配置
   pluginReact.configs.flat.recommended,
   pluginReact.configs.flat['jsx-runtime'],
   reactHooks.configs.flat.recommended,
   {
     files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
-    
+
     // 语言选项：设置全局变量
     languageOptions: {
       globals: {
@@ -52,6 +60,11 @@ export default [
 
     plugins: {
       import: pluginImport,
+      fontawesome6,
+      reanimated,
+      reactnative,
+      forbidEmoji,
+      restrictLinearGradient,
     },
     rules: {
       // 关闭代码风格规则
@@ -70,6 +83,23 @@ export default [
       'no-prototype-builtins': 'off',
       'react/react-in-jsx-scope': 'off',
       'react/jsx-uses-react': 'off',
+      'fontawesome6/valid-name': 'error',
+      'reanimated/ban-mix-use': 'error',
+      'forbidEmoji/no-emoji': 'error',
+      'restrictLinearGradient/no-linear-gradient-backgroundcolor': 'error',
+      // 禁止使用 via.placeholder.com 服务
+      'no-restricted-syntax': [
+        'error',
+        {
+          'selector': 'Literal[value=/via\\.placeholder\\.com/]',
+          'message': 'via.placeholder.com 服务不可用，禁止在代码中使用',
+        },
+        {
+          'selector': 'TemplateLiteral > TemplateElement[value.raw=/via\\.placeholder\\.com/]',
+          'message': 'via.placeholder.com 服务不可用，禁止在代码中使用',
+        },
+      ],
+      'reactnative/wrap-horizontal-scrollview-inside-view': ['error'],
     },
   },
 
@@ -91,7 +121,7 @@ export default [
       // 在 .js 文件中关闭 TS 规则
       '@typescript-eslint/no-require-imports': 'off',
       // 在 Node.js 文件中允许 require
-      '@typescript-eslint/no-var-requires': 'off', 
+      '@typescript-eslint/no-var-requires': 'off',
       'no-undef': 'off',
     },
   },

package/lib/__templates__/expo/client/hooks/{useColorScheme.ts → useColorScheme.tsx}

@@ -1,19 +1,21 @@
-import { useEffect, useState } from 'react';
+import { createContext, Dispatch, ReactNode, SetStateAction, useContext, useEffect, useState } from 'react';
 import { ColorSchemeName, useColorScheme as useReactNativeColorScheme, Platform } from 'react-native';
 
-export function useColorScheme() {
+const ColorSchemeContext = createContext<'light' | 'dark' | null | undefined>(null);
+
+const ColorSchemeProvider = function ({ children }: { children?: ReactNode }) {
   const systemColorScheme = useReactNativeColorScheme();
-  const [colorScheme, setColorScheme] = useState<ColorSchemeName>(systemColorScheme);
+  const [colorScheme, setColorScheme] = useState(systemColorScheme);
 
   useEffect(() => {
     setColorScheme(systemColorScheme);
-  }, [systemColorScheme])
+  }, [systemColorScheme]);
 
   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') {
+        if (typeof cs === 'string' && typeof setColorScheme === 'function') {
           setColorScheme(cs);
         }
       }
@@ -28,7 +30,19 @@ export function useColorScheme() {
         window.removeEventListener('message', handleMessage, false);
       }
     }
-  }, []);
+  }, [setColorScheme]);
+
+  return <ColorSchemeContext.Provider value={colorScheme}>
+    {children}
+  </ColorSchemeContext.Provider>
+};
 
+function useColorScheme() {
+  const colorScheme = useContext(ColorSchemeContext);
   return colorScheme;
 }
+
+export {
+  ColorSchemeProvider,
+  useColorScheme,
+}

package/lib/__templates__/expo/client/hooks/useSafeRouter.ts

@@ -0,0 +1,152 @@
+/**
+ * 安全路由 Hook - 完全代替原生的 useRouter 和 useLocalSearchParams
+ *
+ * 提供的 Hook：
+ * - useSafeRouter: 代替 useRouter，包含所有路由方法，并对 push/replace/navigate/setParams 进行安全编码
+ * - useSafeSearchParams: 代替 useLocalSearchParams，获取路由参数
+ *
+ * 解决的问题：
+ * 1. URI 编解码不对称 - useLocalSearchParams 会自动解码，但 router.push 不会自动编码，
+ *    当参数包含 % 等特殊字符时会拿到错误的值
+ * 2. 类型丢失 - URL 参数全是 string，Number/Boolean 类型会丢失
+ * 3. 嵌套对象无法传递 - URL search params 不支持嵌套结构
+ *
+ * 解决方案：
+ * 采用 Payload 模式，将所有参数打包成 JSON 并 Base64 编码后传递，
+ * 接收时再解码还原，确保数据完整性和类型安全。
+ *
+ * 优点：
+ * 1. 自动处理所有特殊字符（如 %、&、=、中文、Emoji 等）
+ * 2. 保留数据类型（Number、Boolean 不会变成 String）
+ * 3. 支持嵌套对象和数组传递
+ * 4. 三端兼容（iOS、Android、Web）
+ *
+ * 使用方式：
+ * ```tsx
+ * // 发送端 - 使用 useSafeRouter 代替 useRouter
+ * const router = useSafeRouter();
+ * router.push('/detail', { id: 123, uri: 'file:///path/%40test.mp3' });
+ * router.replace('/home', { tab: 'settings' });
+ * router.navigate('/profile', { userId: 456 });
+ * router.back();
+ * if (router.canGoBack()) { ... }
+ * router.setParams({ updated: true });
+ *
+ * // 接收端 - 使用 useSafeSearchParams 代替 useLocalSearchParams
+ * const { id, uri } = useSafeSearchParams<{ id: number; uri: string }>();
+ * ```
+ */
+import { useMemo } from 'react';
+import { useRouter as useExpoRouter, useLocalSearchParams as useExpoParams } from 'expo-router';
+import { Base64 } from 'js-base64';
+
+const PAYLOAD_KEY = '__safeRouterPayload__';
+const LOG_PREFIX = '[SafeRouter]';
+
+
+const getCurrentParams = (rawParams: Record<string, string | string[]>): Record<string, unknown> => {
+  const payload = rawParams[PAYLOAD_KEY];
+  if (payload && typeof payload === 'string') {
+    const decoded = deserializeParams<Record<string, unknown>>(payload);
+    if (decoded && Object.keys(decoded).length > 0) {
+      return decoded;
+    }
+  }
+  const { [PAYLOAD_KEY]: _, ...rest } = rawParams;
+  return rest as Record<string, unknown>;
+};
+
+const serializeParams = (params: Record<string, unknown>): string => {
+  try {
+    const jsonStr = JSON.stringify(params);
+    return Base64.encode(jsonStr);
+  } catch (error) {
+    console.error(LOG_PREFIX, 'serialize failed:', error instanceof Error ? error.message : 'Unknown error');
+    return '';
+  }
+};
+
+const deserializeParams = <T = Record<string, unknown>>(
+  payload: string | string[] | undefined
+): T | null => {
+  if (!payload || typeof payload !== 'string') {
+    return null;
+  }
+  try {
+    const jsonStr = Base64.decode(payload);
+    return JSON.parse(jsonStr) as T;
+  } catch (error) {
+    console.error(LOG_PREFIX, 'deserialize failed:', error instanceof Error ? error.message : 'Unknown error');
+    return null;
+  }
+};
+
+
+/**
+ * 安全路由 Hook，用于页面跳转，代替 useRouter
+ * @returns 路由方法（继承 useRouter 所有方法，并对以下方法进行安全编码）
+ * - push(pathname, params) - 入栈新页面
+ * - replace(pathname, params) - 替换当前页面
+ * - navigate(pathname, params) - 智能跳转（已存在则返回，否则 push）
+ * - setParams(params) - 更新当前页面参数（合并现有参数）
+ */
+export function useSafeRouter() {
+  const router = useExpoRouter();
+  const rawParams = useExpoParams<Record<string, string | string[]>>();
+
+  const push = (pathname: string, params: Record<string, unknown> = {}) => {
+    const encodedPayload = serializeParams(params);
+    router.push({
+      pathname: pathname as `/${string}`,
+      params: { [PAYLOAD_KEY]: encodedPayload },
+    });
+  };
+
+  const replace = (pathname: string, params: Record<string, unknown> = {}) => {
+    const encodedPayload = serializeParams(params);
+    router.replace({
+      pathname: pathname as `/${string}`,
+      params: { [PAYLOAD_KEY]: encodedPayload },
+    });
+  };
+
+  const navigate = (pathname: string, params: Record<string, unknown> = {}) => {
+    const encodedPayload = serializeParams(params);
+    router.navigate({
+      pathname: pathname as `/${string}`,
+      params: { [PAYLOAD_KEY]: encodedPayload },
+    });
+  };
+
+  const setParams = (params: Record<string, unknown>) => {
+    const currentParams = getCurrentParams(rawParams);
+    const mergedParams = { ...currentParams, ...params };
+    const encodedPayload = serializeParams(mergedParams);
+    router.setParams({ [PAYLOAD_KEY]: encodedPayload });
+  };
+
+  return {
+    ...router,
+    push,
+    replace,
+    navigate,
+    setParams,
+  };
+}
+
+/**
+ * 安全获取路由参数 Hook，用于接收方，代替 useLocalSearchParams
+ * 兼容两种跳转方式：
+ * 1. useSafeRouter 跳转 - 自动解码 Payload
+ * 2. 外部跳转（深链接、浏览器直接访问等）- 回退到原始参数
+ * @returns 解码后的参数对象，类型安全
+ */
+export function useSafeSearchParams<T = Record<string, unknown>>(): T {
+  const rawParams = useExpoParams<Record<string, string | string[]>>();
+
+  const decodedParams = useMemo(() => {
+    return getCurrentParams(rawParams) as T;
+  }, [rawParams]);
+
+  return decodedParams;
+}

package/lib/__templates__/expo/client/hooks/useTheme.ts

@@ -1,13 +1,33 @@
-import { Colors } from "@/constants/theme";
-import { useColorScheme } from "@/hooks/useColorScheme";
+import { Colors } from '@/constants/theme';
+import { useColorScheme } from '@/hooks/useColorScheme';
 
-export function useTheme() {
-  const colorScheme = useColorScheme();
-  const isDark = colorScheme === "dark";
-  const theme = Colors[(colorScheme as "light" | "dark") ?? "light"];
+enum COLOR_SCHEME_CHOICE {
+  FOLLOW_SYSTEM = 'follow-system', // 跟随系统自动变化
+  DARK = 'dark', // 固定为 dark 主题，不随系统变化
+  LIGHT = 'light', // 固定为 light 主题，不随系统变化
+};
+
+const userPreferColorScheme: COLOR_SCHEME_CHOICE = COLOR_SCHEME_CHOICE.FOLLOW_SYSTEM;
+
+function getTheme(colorScheme?: 'dark' | 'light' | null) {
+  const isDark = colorScheme === 'dark';
+  const theme = Colors[colorScheme ?? 'light'];
 
   return {
     theme,
     isDark,
   };
 }
+
+function useTheme() {
+  const systemColorScheme = useColorScheme()
+  const colorScheme = userPreferColorScheme === COLOR_SCHEME_CHOICE.FOLLOW_SYSTEM ?
+    systemColorScheme :
+    userPreferColorScheme;
+
+  return getTheme(colorScheme);
+}
+
+export {
+  useTheme,
+}

package/lib/__templates__/expo/client/metro.config.js

@@ -26,6 +26,9 @@ config.resolver.blockList = [
   // 4. 通用规则
   /.*\/__tests__\/.*/, // 排除所有测试目录
   /.*\.git\/.*/, // 排除 Git 目录
+
+  // 5. pnpm 临时目录（避免 ENOENT 错误）
+  /.*node_modules\/\.pnpm\/.*_tmp_\d+.*/,
 ];
 
 const BACKEND_TARGET = 'http://localhost:9091';

package/lib/__templates__/expo/client/package.json

@@ -15,36 +15,38 @@
     "preset": "jest-expo"
   },
   "dependencies": {
-    "@expo/metro-runtime": "^6.1.2",
-    "@expo/vector-icons": "^15.0.0",
-    "@react-native-async-storage/async-storage": "^2.2.0",
-    "@react-native-community/datetimepicker": "^8.5.0",
-    "@react-native-community/slider": "^5.0.1",
-    "@react-native-masked-view/masked-view": "^0.3.2",
-    "@react-native-picker/picker": "^2.11.0",
+    "@expo/metro-runtime": "~6.1.2",
+    "@expo/vector-icons": "^15.0.3",
+    "@react-native-async-storage/async-storage": "2.2.0",
+    "@react-native-community/datetimepicker": "8.4.4",
+    "@react-native-community/slider": "5.0.1",
+    "@react-native-masked-view/masked-view": "0.3.2",
+    "@react-native-picker/picker": "2.11.1",
     "@react-navigation/bottom-tabs": "^7.2.0",
     "@react-navigation/native": "^7.0.14",
     "dayjs": "^1.11.19",
-    "expo": "^54.0.7",
-    "expo-auth-session": "^7.0.9",
-    "expo-av": "~16.0.6",
-    "expo-blur": "~15.0.6",
+    "expo": "54.0.33",
+    "expo-auth-session": "~7.0.10",
+    "expo-av": "~16.0.8",
+    "expo-blur": "~15.0.8",
     "expo-camera": "~17.0.10",
-    "expo-constants": "~18.0.8",
-    "expo-crypto": "^15.0.7",
-    "expo-font": "~14.0.7",
-    "expo-haptics": "~15.0.6",
-    "expo-image-picker": "~17.0.7",
-    "expo-linear-gradient": "~15.0.6",
-    "expo-linking": "~8.0.7",
-    "expo-location": "~19.0.7",
-    "expo-image": "^3.0.11",
-    "expo-router": "~6.0.0",
-    "expo-splash-screen": "~31.0.8",
-    "expo-status-bar": "~3.0.7",
-    "expo-symbols": "~1.0.6",
+    "expo-constants": "~18.0.13",
+    "expo-crypto": "~15.0.8",
+    "expo-file-system": "~19.0.21",
+    "expo-font": "~14.0.11",
+    "expo-haptics": "~15.0.8",
+    "expo-image": "~3.0.11",
+    "expo-image-picker": "~17.0.10",
+    "expo-linear-gradient": "~15.0.8",
+    "expo-linking": "~8.0.11",
+    "expo-location": "~19.0.8",
+    "expo-router": "~6.0.23",
+    "expo-splash-screen": "~31.0.13",
+    "expo-status-bar": "~3.0.9",
+    "expo-symbols": "~1.0.8",
     "expo-system-ui": "~6.0.9",
     "expo-web-browser": "~15.0.10",
+    "js-base64": "^3.7.7",
     "react": "19.1.0",
     "react-dom": "19.1.0",
     "react-native": "0.81.5",
@@ -52,25 +54,26 @@
     "react-native-gesture-handler": "~2.28.0",
     "react-native-keyboard-aware-scroll-view": "^0.9.5",
     "react-native-modal-datetime-picker": "18.0.0",
-    "react-native-reanimated": "~4.1.0",
+    "react-native-reanimated": "~4.1.1",
     "react-native-safe-area-context": "~5.6.0",
     "react-native-screens": "~4.16.0",
-    "react-native-svg": "15.15.0",
+    "react-native-svg": "15.12.1",
     "react-native-toast-message": "^2.3.3",
-    "react-native-web": "^0.21.2",
-    "react-native-webview": "~13.15.0",
+    "react-native-web": "~0.21.0",
+    "react-native-webview": "13.15.0",
     "react-native-worklets": "0.5.1",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "@babel/core": "^7.25.2",
-    "babel-plugin-module-resolver": "^5.0.2",
-    "babel-preset-expo": "^54.0.9",
     "@eslint/js": "^9.27.0",
     "@types/jest": "^29.5.12",
     "@types/react": "~19.1.0",
     "@types/react-test-renderer": "19.1.0",
+    "babel-plugin-module-resolver": "^5.0.2",
+    "babel-preset-expo": "^54.0.9",
     "chalk": "^4.1.2",
+    "connect": "^3.7.0",
     "depcheck": "^1.4.7",
     "esbuild": "0.27.2",
     "eslint": "^9.39.2",
@@ -81,13 +84,12 @@
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-regexp": "^2.10.0",
     "globals": "^16.1.0",
+    "http-proxy-middleware": "^3.0.5",
     "jest": "^29.2.1",
-    "jest-expo": "~54.0.10",
+    "jest-expo": "~54.0.17",
     "react-test-renderer": "19.1.0",
     "tsx": "^4.21.0",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.32.1",
-    "connect": "^3.7.0",
-    "http-proxy-middleware": "^3.0.5"
+    "typescript-eslint": "^8.32.1"
   }
 }

package/lib/__templates__/expo/client/screens/{home → demo}/index.tsx

@@ -5,7 +5,7 @@ import { useTheme } from '@/hooks/useTheme';
 import { Screen } from '@/components/Screen';
 import { styles } from './styles';
 
-export default function HomeScreen() {
+export default function DemoPage() {
   const { theme, isDark } = useTheme();
 
   return (
@@ -15,10 +15,10 @@ export default function HomeScreen() {
       >
         <Image
           style={styles.logo}
-          source="https://lf-coze-web-cdn.coze.cn/obj/eden-cn/lm-lgvj/ljhwZthlaukjlkulzlp/coze-coding/expo/coze-loading.gif"
+          source="https://lf-coze-web-cdn.coze.cn/obj/eden-cn/lm-lgvj/ljhwZthlaukjlkulzlp/coze-coding/icon/coze-coding.gif"
         ></Image>
-        <Text style={{...styles.title, color: theme.textPrimary}}>APP 开发中</Text>
-        <Text style={{...styles.description, color: theme.textSecondary}}>即将为您呈现应用界面</Text>
+        <Text style={{...styles.title, color: theme.textPrimary}}>应用开发中</Text>
+        <Text style={{...styles.description, color: theme.textSecondary}}>请稍候，界面即将呈现</Text>
       </View>
     </Screen>
   );

package/lib/__templates__/expo/client/scripts/install-missing-deps.js

@@ -9,7 +9,7 @@ const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 
-console.log('🔍 检测缺失的依赖...\n');
+console.log('检测缺失的依赖...\n');
 
 try {
   // 运行 depcheck 并获取 JSON 输出
@@ -38,6 +38,7 @@ try {
   const ignoreFilePatterns = [
     /template\.config\.(ts|js)$/, // 模板配置文件
     /\.template\./, // 其他模板文件
+    /declarations\.d\.ts$/, // 项目配置文件
   ];
 
   // 过滤包：排除内部别名和只被模板文件引用的包
@@ -60,11 +61,11 @@ try {
   });
 
   if (missingPackages.length === 0) {
-    console.log('✅ 没有发现缺失的依赖！');
+    console.log('没有发现缺失的依赖');
     process.exit(0);
   }
 
-  console.log('📦 发现以下缺失的依赖：');
+  console.log('发现以下缺失的依赖：');
   missingPackages.forEach((pkg, index) => {
     const files = missing[pkg];
     console.log(`  ${index + 1}. ${pkg}`);
@@ -73,7 +74,7 @@ try {
     );
   });
 
-  console.log('\n🚀 开始安装...\n');
+  console.log('\n开始安装...\n');
 
   // 使用 expo install 安装所有缺失的包
   const packagesToInstall = missingPackages.join(' ');
@@ -83,22 +84,22 @@ try {
       stdio: 'inherit',
     });
 
-    console.log('\n✅ 所有缺失的依赖已安装完成！');
+    console.log('\n所有缺失的依赖已安装完成');
   } catch (installError) {
-    console.log('\n⚠️  expo install 失败，尝试使用 npm install...\n');
+    console.log('\nexpo install 失败，尝试使用 npm install...\n');
 
     execSync(`npm install ${packagesToInstall}`, {
       stdio: 'inherit',
     });
 
-    console.log('\n✅ 所有缺失的依赖已通过 npm 安装完成！');
+    console.log('\n所有缺失的依赖已通过 npm 安装完成');
   }
 } catch (error) {
   if (error.message.includes('depcheck')) {
-    console.error('❌ depcheck 未安装或运行失败');
-    console.log('💡 尝试运行: npm install -g depcheck');
+    console.error('depcheck 未安装或运行失败');
+    console.log('尝试运行: npm install -g depcheck');
   } else {
-    console.error('❌ 发生错误:', error.message);
+    console.error('发生错误:', error.message);
   }
   process.exit(1);
 }

package/lib/__templates__/expo/client/utils/index.ts

@@ -1,9 +1,31 @@
+import { Platform } from 'react-native';
 import dayjs from 'dayjs';
 import utc from 'dayjs/plugin/utc';
 dayjs.extend(utc);
 
 const API_BASE = (process.env.EXPO_PUBLIC_API_BASE ?? '').replace(/\/$/, '');
 
+/**
+ * 创建跨平台兼容的文件对象，用于 FormData.append()
+ * - Web 端返回 File 对象
+ * - 移动端返回 { uri, type, name } 对象（RN fetch 会自动处理）
+ * @param fileUri Expo 媒体库（如 expo-image-picker、expo-camera）返回的 uri
+ * @param fileName 上传时的文件名，如 'photo.jpg'
+ * @param mimeType 文件 MIME 类型，如 'image/jpeg'、'audio/mpeg'
+ */
+export async function createFormDataFile(
+  fileUri: string,
+  fileName: string,
+  mimeType: string
+): Promise<File | { uri: string; type: string; name: string }> {
+  if (Platform.OS === 'web') {
+    const response = await fetch(fileUri);
+    const blob = await response.blob();
+    return new File([blob], fileName, { type: mimeType });
+  }
+  return { uri: fileUri, type: mimeType, name: fileName };
+}
+
 /**
  * 构建文件或图片完整的URL
  * @param url 相对或绝对路径

package/lib/__templates__/expo/eslint-plugins/fontawesome6/index.js

@@ -0,0 +1,9 @@
+const validName = require('./rule')
+
+const plugin = {
+  rules: {
+    'valid-name': validName,
+  },
+};
+
+module.exports = plugin