zcw-shared 1.19.0 → 1.20.0

package/README.md

@@ -9,6 +9,8 @@
 **环境无关性（Environment Agnostic）**
 - 所有函数都通过依赖注入接收环境相关的API
 - 不直接使用 `window`、`document`、`fs` 等全局对象
+- 不传入整个模块对象（包括 Node.js API、浏览器 API 和第三方 SDK）
+- 只传入实际使用的函数，使用 `Interface['method']` 精确提取类型
 - 支持 Node.js、浏览器、UniApp、微信小程序等多种运行环境
 
 **模块化架构**
@@ -16,6 +18,11 @@
 - 无统一入口文件，避免不必要的依赖
 - 清晰的类型定义和环境抽象
 
+**类型安全优先**
+- 完整的 TypeScript 类型定义
+- 从 `references/` 提取类型，避免重复定义
+- 使用 `import type` 导入类型，零运行时开销
+
 ### 目录结构
 
 ```
@@ -59,25 +66,218 @@ playground/            # 测试和验证环境
 
 ### 1. 依赖注入模式
 
-所有环境相关的操作都通过参数传入：
+所有环境相关的操作都通过参数传入，并遵循以下规则：
+
+#### 规则 1：不直接导入第三方库
+
+```typescript
+// ❌ 错误：直接导入 Vue
+import { ref, watch } from 'vue'
+
+// ✅ 正确：从 references 导入类型
+import type { Ref } from '../../references/vue.d'
+```
+
+#### 规则 2：只传入实际使用的函数，不传入整个模块
 
 ```typescript
-// ❌ 错误：直接使用环境API
-export function readFile(path: string) {
-  return fs.readFileSync(path, 'utf8')  // 直接依赖Node.js
+// ❌ 错误：传入整个模块
+import type { FileSystem, Path } from '../../references/node.d'
+
+export function myFunction(fs: FileSystem, path: Path) {
+  fs.existsSync(...)
+  path.join(...)
 }
 
-// ✅ 正确：依赖注入
-import type { FileSystem } from '../../references/node.d'
+// ✅ 正确：只传入使用的函数
+import type { FileSystem, Path } from '../../references/node.d'
+
+export interface MyFunctionDeps {
+  /** 检查文件是否存在 */
+  existsSync: FileSystem['existsSync']
+  /** 路径拼接 */
+  join: Path['join']
+}
+
+export function myFunction(deps: MyFunctionDeps) {
+  deps.existsSync(...)
+  deps.join(...)
+}
+```
+
+#### 规则 3：使用 `deps.` 前缀，不要解构
+
+```typescript
+// ❌ 错误：解构可能导致命名冲突
+export function myFunction(deps: MyFunctionDeps) {
+  const { existsSync, join } = deps  // 难以追踪来源
+  existsSync(...)
+}
+
+// ✅ 正确：使用 deps. 前缀
+export function myFunction(deps: MyFunctionDeps) {
+  deps.existsSync(...)  // 清晰明确
+  deps.join(...)
+}
+```
+
+#### 规则 4：类型定义在 references 中，使用 typeof 或索引访问提取
+
+```typescript
+// ❌ 错误：在函数中定义类型
+export interface MyFunctionDeps {
+  exec: (command: string, callback: (error: any) => void) => any
+}
+
+// ✅ 正确：从 references 提取类型
+import type { ChildProcess } from '../../references/node.d'
+import type { setTimeout } from '../../references/timer.d'
+
+export interface MyFunctionDeps {
+  exec: ChildProcess['exec']
+  setTimeout: typeof setTimeout
+}
+```
+
+#### 规则 5：每个函数维护自己完整的依赖，不要分散
+
+```typescript
+// ❌ 错误：依赖分散到多个参数
+export function myFunction(
+  path: string,
+  fsDeps: FsDeps,
+  pathDeps: PathDeps,
+  systemDeps: SystemDeps
+) { }
+
+// ✅ 正确：统一的依赖对象
+export interface MyFunctionDeps {
+  existsSync: FileSystem['existsSync']
+  readFileSync: FileSystem['readFileSync']
+  join: Path['join']
+  xmlParser: XMLParserConstructor
+}
+
+export function myFunction(path: string, deps: MyFunctionDeps) {
+  deps.existsSync(...)
+  deps.readFileSync(...)
+  deps.join(...)
+}
+```
+
+#### 规则 6：第三方 SDK 对象也要拆分
+
+不仅是 Node.js 和浏览器 API，第三方 SDK 对象（Vue、微信、UniApp 等）也要遵循同样的规则。
 
-export function readFile(path: string, fs: FileSystem) {
-  return fs.readFileSync(path, 'utf8')  // 通过参数注入
+```typescript
+// ❌ 错误：传入整个 Vue 运行时
+import type { VueRuntime } from '../../references/vue.d'
+
+export interface DynamicMountOptions {
+  vue: VueRuntime  // 包含很多未使用的方法
+}
+
+export function dynamicMount(options: DynamicMountOptions) {
+  options.vue.createVNode(...)
+  options.vue.render(...)
+}
+
+// ✅ 正确：只传入使用的函数
+import type { VueRuntime } from '../../references/vue.d'
+
+export interface DynamicMountDeps {
+  createVNode: VueRuntime['createVNode']
+  render: VueRuntime['render']
+}
+
+export function dynamicMount(deps: DynamicMountDeps) {
+  deps.createVNode(...)
+  deps.render(...)
+}
+```
+
+**常见第三方 SDK 拆分示例：**
+
+```typescript
+// 微信小程序 API
+import type { Wx } from '../../references/wechat.d'
+
+export interface WxDownloadFileDeps {
+  USER_DATA_PATH: Wx['env']['USER_DATA_PATH']
+  downloadFile: Wx['downloadFile']
+}
+
+// UniApp API
+import type { UniApp } from '../../references/uniapp.d'
+
+export interface WaitForPagesDeps {
+  getCurrentPages: UniApp['getCurrentPages']
+}
+
+// CryptoJS
+import type { CryptoJS } from '../../references/crypto-js.d'
+
+export interface GenerateLicenseDeps {
+  MD5: CryptoJS['MD5']
+}
+
+// 腾讯云 SDK
+import type { CloudBaseManager } from '../../references/tencent-cloud.d'
+
+export interface DeployTCBDeps {
+  init: CloudBaseManager['init']
+}
+```
+
+#### 完整示例
+
+```typescript
+// src/functions/android/buildProject.ts
+import type { FileSystem, Path, ChildProcess } from '../../../references/node.d'
+import type { setTimeout } from '../../../references/timer.d'
+
+export interface AndroidBuildDependencies {
+  /** 检查文件/目录是否存在 */
+  existsSync: FileSystem['existsSync']
+  /** 读取目录内容 */
+  readdirSync: FileSystem['readdirSync']
+  /** 获取文件状态 */
+  statSync: FileSystem['statSync']
+  /** 路径拼接 */
+  join: Path['join']
+  /** 获取进程平台信息 */
+  platform: string
+  /** 执行子进程命令 */
+  exec: ChildProcess['exec']
+  /** 超时设置函数 */
+  setTimeout: typeof setTimeout
+}
+
+export async function buildProject(
+  options: AndroidBuildOptions,
+  deps: AndroidBuildDependencies
+): Promise<AndroidBuildResult> {
+  // 使用 deps. 前缀访问所有依赖
+  if (!deps.existsSync(projectPath)) {
+    return { success: false, error: '路径不存在' }
+  }
+  
+  const buildPath = deps.join(projectPath, 'build.gradle')
+  const files = deps.readdirSync(projectPath)
+  
+  deps.exec(command, (error, stdout, stderr) => {
+    // ...
+  })
+  
+  deps.setTimeout(() => {
+    // ...
+  }, 1000)
 }
 ```
 
 ### 2. 类型抽象
 
-**references/** 目录定义环境API的抽象接口：
+**references/** 目录定义环境API的抽象类型（接口、类型别名等），所有基础类型都应在此定义：
 
 ```typescript
 // references/node.d.ts
@@ -85,12 +285,51 @@ export interface FileSystem {
   readFileSync(path: string, encoding?: string): string
   writeFileSync(path: string, data: any): void
   existsSync(path: string): boolean
+  readdirSync(path: string): string[]
+  statSync(path: string): { isDirectory(): boolean; isFile(): boolean }
+}
+
+export interface Path {
+  join(...paths: string[]): string
+  dirname(path: string): string
+  basename(path: string): string
+}
+
+export interface ChildProcess {
+  exec(command: string, callback?: (error: any, stdout: string, stderr: string) => void): any
 }
 
 // references/browser.d.ts
 export interface Window {
+  innerWidth: number
+  innerHeight: number
   localStorage: Storage
-  fetch: (url: string) => Promise<Response>
+  Image: new () => HTMLImageElement
+  File: new (bits: BlobPart[], name: string, options?: FilePropertyBag) => File
+}
+
+// references/dom.d.ts
+export interface Document {
+  createElement<K extends keyof HTMLElementTagNameMap>(tagName: K): HTMLElementTagNameMap[K]
+  head: HTMLElement
+}
+
+// references/vue.d.ts
+export interface Ref<T = any> {
+  value: T
+}
+
+export type InjectionKey<T> = symbol
+
+// references/timer.d.ts
+export declare const setTimeout: (callback: (...args: any[]) => void, ms?: number, ...args: any[]) => any
+export declare const clearTimeout: (timeoutId: any) => void
+
+// references/console.d.ts
+export interface Console {
+  log(message?: any, ...optionalParams: any[]): void
+  error(message?: any, ...optionalParams: any[]): void
+  warn(message?: any, ...optionalParams: any[]): void
 }
 ```
 
@@ -103,6 +342,12 @@ export interface RgbColor {
   g: number
   b: number
 }
+
+// types/android-build.d.ts
+export interface AndroidBuildOptions {
+  projectPath: string
+  buildVariant?: 'debug' | 'release'
+}
 ```
 
 ### 3. 多环境适配
@@ -111,20 +356,43 @@ export interface RgbColor {
 
 ```typescript
 // Node.js 环境
-import { convertColor } from 'shared/functions/color/convertColor'
-convertColor('#ff0000', 'rgb')  // 纯函数，无环境依赖
+import fs from 'fs'
+import path from 'path'
+import { buildProject } from 'shared/functions/android/buildProject'
 
-// 浏览器环境
-import { useStorage } from 'shared/hooks/useStorage'
-import { useLocalStorage } from 'shared/hooks/useLocalStorage'
-const storage = useStorage(useLocalStorage(window))  // 注入浏览器API
+const result = await buildProject(options, {
+  existsSync: fs.existsSync,
+  readdirSync: fs.readdirSync,
+  statSync: fs.statSync,
+  join: path.join,
+  platform: process.platform,
+  exec: require('child_process').exec,
+  setTimeout
+})
 
-// UniApp 环境
-import { buildProject } from 'shared/functions/android/buildProject'
-buildProject(projectPath, {
-  fs: uni.getFileSystemManager(),  // 注入UniApp API
-  path: uniPath,
-  process: uniProcess
+// 浏览器 Vue 环境
+import { ref, shallowRef, watch } from 'vue'
+import { useAsyncState } from 'shared/hooks/useAsyncState'
+
+// 传入 Vue 运行时函数和浏览器 API
+const { state, isLoading } = useAsyncState(
+  async () => fetch('/api/data').then(r => r.json()),
+  { 
+    immediate: true,
+    delay: 1000
+  },
+  {
+    vue: { ref, shallowRef, watch },  // Vue Composition API 函数
+    host: { setTimeout }               // 浏览器定时器
+  }
+)
+
+// 浏览器 DOM 操作
+import { getViewportRect } from 'shared/functions/dom/getViewportRect'
+
+const viewport = getViewportRect({
+  innerWidth: window.innerWidth,
+  innerHeight: window.innerHeight
 })
 ```
 
@@ -257,27 +525,24 @@ const edgeCases = [
 
 ```typescript
 import { buildProject } from 'shared/functions/android/buildProject'
-import type { FileSystem, Path } from 'shared/references/node'
 
-// 模拟文件系统
-const mockFs: FileSystem = {
+// 创建模拟的依赖函数
+const mockDeps = {
   existsSync: (path: string) => path.includes('build.gradle'),
   readFileSync: (path: string) => 'mock file content',
-  writeFileSync: (path: string, data: any) => {},
-  // ... 其他方法
-}
-
-const mockPath: Path = {
+  readdirSync: (path: string) => ['file1.txt', 'file2.txt'],
+  statSync: (path: string) => ({ isDirectory: () => false, isFile: () => true }),
   join: (...paths: string[]) => paths.join('/'),
-  // ... 其他方法
+  platform: 'darwin',
+  exec: (cmd: string, callback: any) => callback(null, 'success', ''),
+  setTimeout: (fn: () => void, delay: number) => global.setTimeout(fn, delay)
 }
 
 function testBuildProject() {
-  const result = buildProject('/mock/project', {
-    fs: mockFs,
-    path: mockPath,
-    // ... 其他依赖
-  })
+  const result = buildProject(
+    { projectPath: '/mock/project', buildVariant: 'debug' },
+    mockDeps
+  )
   console.log('构建结果:', result)
 }
 ```
@@ -330,11 +595,7 @@ npx tsx tests/*.test.ts
 
 2. **编译依赖**：改动了函数以后，因为playground中引用的是编译后的shared包，所以需要先编译shared包（`npm run build`），test中才能用到最新的代码。
 
-3. **文档同步更新**：每次新增新功能或修改现有功能后，**必须**同步更新VitePress文档：
-   - 在 `docs/api/` 目录下更新或创建对应的API文档
-   - 在 `docs/examples/` 目录下添加使用示例
-   - 确保文档中的TypeScript泛型语法使用反引号包裹（如 `Promise<\`File\`>`）以避免Vue编译错误
-   - 运行 `npm run docs:dev` 验证文档编译无误
+3. **文档同步更新**：每次新增或修改函数后，**必须**同步更新 VitePress 文档。详细规范见下方"文档规范"章节。
 
 ### 1. 添加新函数
 
@@ -348,40 +609,175 @@ types/category.d.ts
 # 3. 创建测试
 playground/tests/newFunction.test.ts
 
-# 4. 更新VitePress文档
-docs/api/category.md          # API文档
-docs/examples/category.md     # 使用示例
+# 4. 创建函数文档（必须！）
+docs/api/category/newFunction.md
+
+# 5. 创建 Playground 组件（如果是浏览器端函数）
+docs/.vitepress/components/NewFunctionPlayground.vue
 
-# 5. 验证文档编译
+# 6. 更新侧边栏配置
+docs/.vitepress/config.ts
+
+# 7. 验证文档编译
 npm run docs:dev
 
-# 6. 构建和导出
+# 8. 构建和导出
 npm run build
 ```
 
 ### 2. 函数开发模板
 
+遵循最新的依赖注入规范：
+
 ```typescript
 // src/functions/category/newFunction.ts
-import type { SomeType } from '../../types/category.d'
-import type { EnvironmentAPI } from '../../references/environment.d'
+import type { FileSystem, Path } from '../../references/node.d'
+import type { setTimeout } from '../../references/timer.d'
+import type { Console } from '../../references/console.d'
+
+/**
+ * 函数依赖接口
+ * 注意：
+ * 1. 只包含实际使用的函数
+ * 2. 使用 Interface['method'] 或 typeof 提取类型
+ * 3. 每个依赖都要有清晰的注释
+ */
+export interface NewFunctionDeps {
+  /** 检查文件是否存在 */
+  existsSync: FileSystem['existsSync']
+  /** 读取文件内容 */
+  readFileSync: FileSystem['readFileSync']
+  /** 路径拼接 */
+  join: Path['join']
+  /** 超时函数 */
+  setTimeout: typeof setTimeout
+  /** 错误日志函数 */
+  error: Console['error']
+  /** 日志输出函数 */
+  log: Console['log']
+}
 
 /**
  * 函数描述
  * 
  * @param input - 输入参数
- * @param deps - 环境依赖
+ * @param deps - 环境依赖（包含所有需要的函数）
  * @returns 返回值描述
+ * 
+ * @example
+ * ```typescript
+ * import fs from 'fs'
+ * import path from 'path'
+ * 
+ * const result = newFunction(input, {
+ *   existsSync: fs.existsSync,
+ *   readFileSync: fs.readFileSync,
+ *   join: path.join,
+ *   setTimeout,
+ *   error: console.error,
+ *   log: console.log
+ * })
+ * ```
  */
 export function newFunction(
-  input: SomeType,
-  deps: EnvironmentAPI
-): ReturnType {
-  // 实现逻辑
+  input: string,
+  deps: NewFunctionDeps
+): string {
+  // ✅ 使用 deps. 前缀访问所有依赖
+  if (!deps.existsSync(input)) {
+    deps.error('文件不存在')
+    return ''
+  }
+  
+  const content = deps.readFileSync(input, 'utf8')
+  const outputPath = deps.join(input, '../output.txt')
+  
+  deps.setTimeout(() => {
+    deps.log('处理完成')
+  }, 1000)
+  
+  return content
+}
+```
+
+**Vue Hooks 开发模板：**
+
+```typescript
+// src/hooks/useNewHook.ts
+import type { Ref } from '../../references/vue.d'
+import type { setTimeout } from '../../references/timer.d'
+
+export interface VueCompositionAPI {
+  ref: <T>(value: T) => Ref<T>
+  watch: (source: any, callback: () => void, options?: any) => void
+  onMounted: (fn: () => void) => void
+  onUnmounted: (fn: () => void) => void
+}
+
+export interface NewHookEnvironment {
+  vue: VueCompositionAPI
+  host: {
+    setTimeout: typeof setTimeout
+    clearTimeout: typeof clearTimeout
+  }
+}
+
+export function useNewHook<T>(
+  source: Ref<T>,
+  options: NewHookOptions,
+  env: NewHookEnvironment
+): NewHookReturn<T> {
+  const state = env.vue.ref<T>(initialValue)
+  
+  env.vue.watch(source, () => {
+    // 监听逻辑
+  })
+  
+  env.vue.onMounted(() => {
+    // 挂载逻辑
+  })
+  
+  env.host.setTimeout(() => {
+    // 定时器逻辑
+  }, 1000)
+  
+  return { state }
 }
 ```
 
-### 3. 构建和发布
+### 3. 代码检查清单
+
+在提交代码前，请确保：
+
+#### ✅ 依赖注入检查
+- [ ] 没有直接 `import` 第三方库（如 `vue`、`react`）
+- [ ] 没有直接使用全局对象（`window`、`document`、`global`、`process`）
+- [ ] 所有环境依赖都通过 `deps` 或 `env` 参数传入
+- [ ] 使用 `deps.` 前缀访问依赖，没有解构
+
+#### ✅ 类型定义检查
+- [ ] 类型从 `references/` 导入，使用 `import type`
+- [ ] 依赖接口命名为 `{FunctionName}Deps` 或 `{HookName}Environment`
+- [ ] 使用 `Interface['method']` 或 `typeof` 提取类型
+- [ ] 每个依赖都有清晰的 JSDoc 注释
+- [ ] 没有在函数中重复定义已存在的类型
+
+#### ✅ 函数设计检查
+- [ ] 只传入实际使用的函数，不传入整个模块对象
+- [ ] 第三方 SDK 对象（Vue、Wx、UniApp 等）也要拆分
+- [ ] 函数签名清晰，参数顺序合理
+- [ ] 错误处理完善，不会意外抛出异常
+- [ ] 有完整的 JSDoc 文档注释
+
+#### ✅ 测试和文档检查
+- [ ] 创建了对应的测试文件
+- [ ] 创建了 VitePress 文档
+- [ ] 浏览器函数创建了 Playground 组件
+- [ ] 更新了侧边栏配置
+- [ ] 运行 `npm run build` 编译成功
+- [ ] 运行 `npm run docs:dev` 文档正常显示
+
+### 4. 构建和发布
 
 ```bash
 # 类型检查
@@ -404,32 +800,862 @@ npm run publish:major  # 主要版本
 ### 函数设计
 
 1. **纯函数优先**：无副作用，相同输入产生相同输出
-2. **依赖注入**：环境相关API通过参数传入
+2. **依赖注入**：环境相关API通过 `deps` 参数传入
 3. **类型安全**：完整的TypeScript类型定义
 4. **错误处理**：优雅处理异常情况，返回null而非抛出异常
+5. **精确依赖**：只传入实际使用的函数，不传入整个模块
+6. **使用前缀**：通过 `deps.` 访问依赖，避免命名冲突
 
 ### 类型定义
 
 1. **分层设计**：业务类型放在 `types/`，环境类型放在 `references/`
-2. **接口抽象**：定义最小化的接口，只包含必要的方法
-3. **泛型支持**：提供灵活的类型参数
+2. **类型提取**：使用 `Interface['method']` 或 `typeof` 从 references 提取类型
+3. **避免重复定义**：不在函数中定义已存在于 references 的类型
+4. **完整注释**：每个依赖函数都要有清晰的注释说明用途
+5. **统一接口**：每个函数有自己完整的 `Deps` 接口，不依赖通用的 `SystemDependencies`
+
+### 依赖管理
+
+1. **不导入第三方库**：不直接 `import { ref } from 'vue'`，而是通过 `env` 对象传入
+2. **不依赖全局对象**：不直接使用 `window`、`document`、`global`
+3. **接口命名规范**：`{FunctionName}Deps`，例如 `BuildProjectDeps`、`ModifyManifestDeps`
+4. **使用 deps. 前缀**：所有依赖访问都使用 `deps.methodName()`，不解构
 
 ### 测试要求
 
 1. **全面覆盖**：正常、边界、异常情况
 2. **环境模拟**：使用mock对象测试环境依赖
 3. **文档化**：测试即文档，展示函数的使用方法
+4. **依赖注入测试**：验证函数在不同依赖注入下的行为
+
+### 快速检查清单
+
+在编写新函数或修改现有函数时，快速检查以下要点：
+
+**✅ 6大核心规则：**
+1. ❌ 不直接导入第三方库 → ✅ 从 `references/` 导入类型
+2. ❌ 不传入整个模块对象 → ✅ 只传入实际使用的函数
+3. ❌ 不解构 deps 对象 → ✅ 使用 `deps.` 前缀访问
+4. ❌ 不重复定义类型 → ✅ 使用 `Interface['method']` 提取
+5. ❌ 不分散依赖到多个参数 → ✅ 统一的 `Deps` 接口
+6. ❌ 第三方 SDK 也不能整个传入 → ✅ Vue、Wx 等也要拆分
+
+**✅ 命名规范：**
+- 函数依赖接口：`{FunctionName}Deps`
+- Hook 环境接口：`{HookName}Environment`
+- Playground 组件：`{FunctionName}Playground.vue`
+
+**✅ 文档完整性：**
+- [ ] Markdown 文档（`docs/api/category/functionName.md`）
+- [ ] Playground 组件（浏览器函数必须）
+- [ ] 测试文件（`playground/tests/functionName.test.ts`）
+- [ ] 侧边栏配置已更新
+
+### 常见错误和解决方案
+
+#### ❌ 错误 1：直接导入第三方库
+```typescript
+import { ref, watch } from 'vue'  // ❌ 错误
+```
+**解决方案：**
+```typescript
+import type { Ref } from '../../references/vue.d'  // ✅ 正确
+
+export interface VueCompositionAPI {
+  ref: <T>(value: T) => Ref<T>
+  watch: (source: any, callback: () => void) => void
+}
+
+export function useMyHook(env: { vue: VueCompositionAPI }) {
+  const state = env.vue.ref(0)
+  env.vue.watch(state, () => {})
+}
+```
+
+#### ❌ 错误 2：传入整个模块对象
+```typescript
+export function myFunction(fs: FileSystem, path: Path) {  // ❌ 错误
+  fs.existsSync(...)
+}
+```
+**解决方案：**
+```typescript
+export interface MyFunctionDeps {
+  existsSync: FileSystem['existsSync']  // ✅ 正确
+}
+
+export function myFunction(deps: MyFunctionDeps) {
+  deps.existsSync(...)
+}
+```
+
+#### ❌ 错误 3：解构依赖对象
+```typescript
+export function myFunction(deps: MyFunctionDeps) {
+  const { existsSync, join } = deps  // ❌ 错误，可能命名冲突
+}
+```
+**解决方案：**
+```typescript
+export function myFunction(deps: MyFunctionDeps) {
+  deps.existsSync(...)  // ✅ 正确，清晰明确
+  deps.join(...)
+}
+```
+
+#### ❌ 错误 4：在函数中定义类型
+```typescript
+export interface MyFunctionDeps {
+  exec: (cmd: string, cb: (err: any) => void) => any  // ❌ 错误
+}
+```
+**解决方案：**
+```typescript
+import type { ChildProcess } from '../../references/node.d'
+
+export interface MyFunctionDeps {
+  exec: ChildProcess['exec']  // ✅ 正确，从 references 提取
+}
+```
+
+#### ❌ 错误 5：依赖全局对象
+```typescript
+export function myFunction(window: Window) {  // ❌ 错误
+  const width = window.innerWidth
+  window.localStorage.setItem(...)
+}
+```
+**解决方案：**
+```typescript
+import type { Window } from '../../references/browser.d'
+
+export interface MyFunctionDeps {
+  innerWidth: Window['innerWidth']  // ✅ 正确
+  setItem: (key: string, value: string) => void
+}
+
+export function myFunction(deps: MyFunctionDeps) {
+  const width = deps.innerWidth
+  deps.setItem('key', 'value')
+}
+```
+
+#### ❌ 错误 6：传入整个第三方 SDK 对象
+```typescript
+import type { VueRuntime } from '../../references/vue.d'
+import type { Wx } from '../../references/wechat.d'
+
+export interface MyFunctionDeps {
+  vue: VueRuntime  // ❌ 错误，包含很多未使用的方法
+  wx: Wx           // ❌ 错误，包含很多未使用的方法
+}
+
+export function myFunction(deps: MyFunctionDeps) {
+  deps.vue.createVNode(...)
+  deps.wx.downloadFile(...)
+}
+```
+**解决方案：**
+```typescript
+import type { VueRuntime } from '../../references/vue.d'
+import type { Wx } from '../../references/wechat.d'
+
+export interface MyFunctionDeps {
+  createVNode: VueRuntime['createVNode']        // ✅ 正确
+  downloadFile: Wx['downloadFile']              // ✅ 正确
+  USER_DATA_PATH: Wx['env']['USER_DATA_PATH']  // ✅ 嵌套属性也要精确提取
+}
+
+export function myFunction(deps: MyFunctionDeps) {
+  deps.createVNode(...)
+  deps.downloadFile(...)
+  const path = `${deps.USER_DATA_PATH}/file.txt`
+}
+```
+
+**常见第三方 SDK 对象拆分：**
+- `VueRuntime` → 只传入 `createVNode`, `render` 等实际使用的方法
+- `Wx` (微信) → 只传入 `downloadFile`, `request` 等实际使用的方法
+- `UniApp` → 只传入 `getCurrentPages` 等实际使用的方法
+- `CryptoJS` → 只传入 `MD5`, `SHA256` 等实际使用的方法
+- `CloudBaseManager` → 只传入 `init` 等实际使用的方法
+- `Sharp` (图像处理) → 已经是函数，直接作为依赖
 
 ### 文档规范
 
-1. **JSDoc注释**：详细的函数说明和参数描述
-2. **使用示例**：在测试文件中提供实际使用案例
-3. **类型导出**：确保所有相关类型都可以导入
-4. **VitePress文档**：
-   - **API文档**：在 `docs/api/` 目录下为每个模块创建详细的API文档
-   - **示例文档**：在 `docs/examples/` 目录下提供实际使用示例
-   - **语法规范**：TypeScript泛型语法必须用反引号包裹（如 `Promise<\`File\`>`）
-   - **编译验证**：确保文档能够正常编译，无Vue语法错误
+**重要：每个函数或 Hook 都必须有完整的文档！**
+
+#### 0. 文档网站开发
+
+本项目使用 VitePress 构建文档网站。
+
+**开发命令：**
+
+```bash
+# 本地开发文档网站
+npm run docs:dev
+
+# 构建生产版本
+npm run docs:build
+
+# 预览构建后的网站
+npm run docs:preview
+```
+
+**文档目录结构：**
+
+```
+docs/
+├── index.md                      # 首页
+├── guide/                        # 指南文档
+├── api/                          # API文档
+│   ├── color/                   # 按功能分类
+│   ├── string/
+│   └── utils/
+└── .vitepress/                   # VitePress配置
+    ├── config.ts                # 网站配置和侧边栏
+    ├── theme/                   # 主题配置
+    └── components/              # Playground组件
+```
+
+#### 1. 文档文件结构
+
+每个函数必须有独立的 Markdown 文档：
+
+```
+docs/api/
+├── color/
+│   ├── convertColor.md          # 每个函数一个文档
+│   ├── colorValidation.md
+│   └── ...
+├── string/
+│   ├── capitalize.md
+│   └── ...
+└── utils/
+    ├── debounce.md
+    └── ...
+```
+
+#### 2. 文档内容模板
+
+每个函数文档应按照以下结构编写（按优先级排序）：
+
+##### 必需部分
+
+```markdown
+# functionName
+
+<!-- 1. 函数描述（一句话） -->
+简短描述函数的功能和用途。
+
+<!-- 2. Playground 组件（浏览器端函数必须有） -->
+<script setup>
+import FunctionNamePlayground from '../../.vitepress/components/FunctionNamePlayground.vue'
+</script>
+
+<FunctionNamePlayground />
+
+<!-- 3. 前置依赖（如果函数有 deps 参数） -->
+## 前置依赖
+
+### 依赖参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `deps.xxx` | `Type` | 依赖说明 |
+
+### 环境要求
+
+- **第三方库名**: 用途说明
+
+\`\`\`bash
+npm install library-name
+\`\`\`
+
+<!-- 4. 函数签名 -->
+## 函数签名
+
+\`\`\`typescript
+function functionName(
+  param1: Type1,
+  param2: Type2,
+  deps?: DepsType
+): ReturnType
+
+interface FunctionNameDeps {
+  // 依赖接口定义
+}
+\`\`\`
+
+<!-- 5. 参数表格 -->
+## 参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `param1` | `Type1` | 是 | 参数说明 |
+| `param2` | `Type2` | 否 | 可选参数说明 |
+
+<!-- 6. 返回值 -->
+## 返回值
+
+| 类型 | 说明 |
+|------|------|
+| `ReturnType` | 返回值说明 |
+
+<!-- 7. 工作原理 -->
+## 工作原理
+
+1. 步骤1说明
+2. 步骤2说明
+3. 步骤3说明
+4. 返回结果
+
+补充说明...
+```
+
+##### 可选部分
+
+```markdown
+<!-- 异常（如果函数会抛出错误） -->
+## 异常
+
+| 错误类型 | 触发条件 | 错误信息 |
+|----------|----------|----------|
+| `Error` | 条件 | 错误文本 |
+```
+
+##### 文档编写注意事项
+
+- ✅ **必须包含**：函数描述、函数签名、参数表格、返回值、工作原理
+- ✅ **浏览器端函数必须有** Playground 组件
+- ✅ **有 deps 参数的函数必须有**前置依赖说明
+- ❌ **不要包含**：`## 导入` 章节（已在首页说明）
+- ❌ **不要包含**：冗长的使用示例代码
+- ❌ **不要包含**：`## 注意事项` 章节（信息整合到其他部分）
+- ✅ **使用表格**：参数、返回值、异常等都用表格展示
+- ✅ **工作原理简明扼要**：说明核心逻辑即可，不要过于详细
+
+#### 3. Playground 组件规范
+
+浏览器端函数必须创建交互式 Playground 组件：
+
+**命名规范：**
+- 文件名：`{FunctionName}Playground.vue`（首字母大小写，驼峰命名）
+- 位置：`docs/.vitepress/components/`
+
+**设计规范：**
+
+所有 Playground 组件必须遵循统一的设计语言，确保视觉一致性和用户体验：
+
+##### 视觉风格
+
+1. **容器背景**
+   ```css
+   .playground-container {
+     width: 100%;                    /* 重要：占满容器宽度 */
+     padding: 24px;
+     background: linear-gradient(135deg, #f5f7fa 0%, #ffffff 100%);
+     border-radius: 16px;
+     box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08);
+     box-sizing: border-box;        /* 重要：确保 padding 不溢出 */
+   }
+   ```
+
+2. **卡片样式**
+   ```css
+   .card {
+     background: white;
+     border-radius: 12px;
+     padding: 20px;
+     margin-bottom: 20px;
+     box-shadow: 0 2px 12px rgba(0, 0, 0, 0.06);  /* 注意：是 12px 和 0.06，不是 8px 和 0.08 */
+   }
+   ```
+
+3. **标题样式**
+   ```css
+   h4 {
+     margin: 0 0 16px 0;
+     font-size: 15px;
+     font-weight: 600;
+     color: #374151;                /* 重要：统一使用 #374151，不是 #2c3e50 */
+     text-transform: uppercase;     /* 重要：标题全部大写 */
+     letter-spacing: 0.05em;        /* 重要：增加字母间距 */
+   }
+   ```
+
+##### 配色方案
+
+1. **主色调**
+   - 主要按钮：`#3b82f6`（蓝色）
+   - 成功状态：`#10b981`（绿色）
+   - 错误状态：`#ef4444`（红色）
+   - 警告状态：`#f59e0b`（橙色）
+   - 中性按钮：`#6b7280`（灰色）
+
+2. **文本颜色**
+   - 主标题：`#374151`（15-16px）
+   - 正文：`#6b7280`（14px）
+   - 次要文本：`#9ca3af`（13px）
+
+3. **边框和背景**
+   - 边框：`#e5e7eb`（2px solid）
+   - 卡片背景：`#ffffff`
+   - 输入框背景：`#f9fafb`
+
+##### 交互元素
+
+1. **输入框**
+   ```css
+   input, textarea, select {
+     padding: 12px 14px;
+     border: 2px solid #e5e7eb;     /* 重要：使用 #e5e7eb，不是 #e0e0e0 */
+     border-radius: 8px;
+     font-size: 14px;
+     box-sizing: border-box;
+     transition: all 0.2s;
+   }
+   
+   input:focus, textarea:focus, select:focus {
+     outline: none;
+     border-color: #3b82f6;
+     box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);  /* 重要：焦点阴影 */
+   }
+   ```
+
+2. **按钮基础样式**
+   ```css
+   .btn {
+     padding: 12px 18px;            /* 注意：是 18px，不是 20px */
+     border: none;                  /* 重要：按钮无边框 */
+     border-radius: 8px;
+     font-size: 13px;               /* 注意：是 13px，不是 14px */
+     font-weight: 600;
+     cursor: pointer;
+     transition: all 0.2s;
+   }
+   
+   .btn:hover:not(:disabled) {
+     transform: translateY(-1px);   /* 重要：hover 向上移动 */
+   }
+   
+   .btn:disabled {
+     opacity: 0.5;
+     cursor: not-allowed;
+   }
+   ```
+   
+3. **小按钮样式**
+   ```css
+   .btn-small {
+     padding: 4px 12px;             /* 用于工具按钮 */
+     font-size: 12px;
+   }
+   ```
+
+4. **按钮颜色变体**
+   ```css
+   /* 主要按钮 - 蓝色 */
+   .btn-primary {
+     background: #3b82f6;
+     color: white;
+   }
+   .btn-primary:hover {
+     background: #2563eb;
+   }
+   
+   /* 次要按钮 - 灰色 */
+   .btn-secondary {
+     background: #6b7280;
+     color: white;
+   }
+   .btn-secondary:hover {
+     background: #4b5563;
+   }
+   
+   /* 成功按钮 - 绿色 */
+   .btn-success {
+     background: #10b981;
+     color: white;
+   }
+   .btn-success:hover {
+     background: #059669;
+   }
+   
+   /* 危险按钮 - 红色 */
+   .btn-danger {
+     background: #ef4444;
+     color: white;
+   }
+   .btn-danger:hover {
+     background: #dc2626;
+   }
+   
+   /* 警告按钮 - 橙色 */
+   .btn-warning {
+     background: #f59e0b;
+     color: white;
+   }
+   .btn-warning:hover {
+     background: #d97706;
+   }
+   
+   /* 信息按钮 - 青色 */
+   .btn-info {
+     background: #06b6d4;
+     color: white;
+   }
+   .btn-info:hover {
+     background: #0891b2;
+   }
+   ```
+
+##### 布局规范
+
+1. **间距系统**
+   - 组件间距：`20px`
+   - 内边距：`20-24px`
+   - 小间距：`12px`
+   - 表单元素间距：`16px`
+
+2. **圆角统一**
+   - 容器：`16px`
+   - 卡片：`12px`
+   - 输入框/按钮：`8px`
+   - 小元素：`6px`
+
+3. **响应式设计**
+   ```css
+   @media (max-width: 768px) {
+     .playground-container {
+       padding: 20px;
+     }
+     
+     .grid {
+       grid-template-columns: 1fr;
+     }
+   }
+   ```
+
+##### 特殊元素
+
+1. **统计卡片**
+   ```css
+   .stat-item {
+     display: flex;
+     flex-direction: column;
+     gap: 8px;
+     padding: 16px;
+     background: #f9fafb;
+     border-radius: 8px;
+     border: 2px solid #e5e7eb;
+     text-align: center;
+   }
+   
+   .stat-label {
+     font-size: 11px;
+     color: #6b7280;
+     font-weight: 600;
+     text-transform: uppercase;
+     letter-spacing: 0.05em;
+   }
+   
+   .stat-value {
+     font-size: 20px;              /* 统计数值使用 20px */
+     font-weight: 700;
+     color: #3b82f6;               /* 重要：统计值使用主色调 */
+     font-family: monospace;       /* 重要：数字使用等宽字体 */
+   }
+   ```
+
+2. **日志区域**（推荐使用整体框方式）
+   ```css
+   .log-content {
+     background: #f9fafb;
+     border: 2px solid #e5e7eb;
+     border-radius: 8px;
+     padding: 18px;
+     max-height: 320px;
+     overflow-y: auto;
+     font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+     font-size: 13px;
+     line-height: 1.6;
+   }
+   
+   .log-item {
+     padding: 4px 0;
+     color: #374151;
+     word-break: break-word;
+   }
+   
+   .log-empty {
+     color: #9ca3af;
+     text-align: center;
+     padding: 24px;
+     font-size: 13px;
+   }
+   ```
+
+3. **结果展示**
+   ```css
+   .result-card {
+     padding: 18px;
+     background: #f9fafb;
+     border: 2px solid #e5e7eb;
+     border-radius: 8px;
+     font-family: monospace;
+     font-size: 13px;
+     line-height: 1.6;
+   }
+   ```
+
+2. **代码块**
+   ```css
+   pre, code {
+     background: #1e293b;
+     color: #e2e8f0;
+     padding: 18px;
+     border-radius: 8px;
+     font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+     font-size: 13px;
+     line-height: 1.6;
+   }
+   ```
+
+3. **状态指示**
+   ```css
+   .status-indicator {
+     display: inline-block;
+     width: 8px;
+     height: 8px;
+     border-radius: 50%;
+     margin-right: 8px;
+   }
+   
+   .status-success { background: #10b981; }
+   .status-error { background: #ef4444; }
+   .status-warning { background: #f59e0b; }
+   .status-info { background: #3b82f6; }
+   ```
+
+##### 禁止事项
+
+1. **❌ 不使用 emoji**
+   - 不在 UI 中使用 emoji 图标
+   - 使用简洁的文字描述代替
+   - 必要时使用 Unicode 符号（如 ✓ ✗）
+
+2. **❌ 不使用渐变色背景（按钮除外）**
+   - 避免在卡片上使用渐变
+   - 使用纯色或微妙的线性渐变
+
+3. **❌ 不使用过大的字体**
+   - 标题 15-16px
+   - 正文 14px
+   - 代码 13px
+   - label 13px
+
+4. **❌ 不使用左侧色块装饰**
+   - 避免 `border-left` 彩色边框
+   - 使用统一的边框样式
+
+##### 组件模板
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { functionName } from '../../../src/functions/category/functionName'
+
+// 组件逻辑
+const input = ref('')
+const result = ref('')
+
+function handleAction() {
+  result.value = functionName(input.value)
+}
+</script>
+
+<template>
+  <div class="function-playground">
+    <!-- 配置区域 -->
+    <div class="config-section">
+      <h4>配置选项</h4>
+      <div class="input-group">
+        <label>输入</label>
+        <input v-model="input" type="text" placeholder="请输入..." />
+      </div>
+      <button @click="handleAction" class="btn-primary">执行</button>
+    </div>
+
+    <!-- 结果区域 -->
+    <div class="result-section" v-if="result">
+      <h4>结果</h4>
+      <div class="result-card">{{ result }}</div>
+    </div>
+
+    <!-- 说明区域 -->
+    <div class="description-section">
+      <h4>功能说明</h4>
+      <p>函数功能的简要说明...</p>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.function-playground {
+  width: 100%;
+  padding: 24px;
+  background: linear-gradient(135deg, #f5f7fa 0%, #ffffff 100%);
+  border-radius: 16px;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08);
+  box-sizing: border-box;
+}
+
+.config-section,
+.result-section,
+.description-section {
+  background: white;
+  border-radius: 12px;
+  padding: 20px;
+  margin-bottom: 20px;
+  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.06);
+}
+
+h4 {
+  margin: 0 0 16px 0;
+  font-size: 15px;
+  font-weight: 600;
+  color: #374151;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.input-group {
+  margin-bottom: 16px;
+}
+
+label {
+  display: block;
+  margin-bottom: 8px;
+  font-size: 13px;
+  font-weight: 600;
+  color: #6b7280;
+}
+
+input {
+  width: 100%;
+  padding: 12px 14px;
+  border: 2px solid #e5e7eb;
+  border-radius: 8px;
+  font-size: 14px;
+  box-sizing: border-box;
+  transition: all 0.2s;
+}
+
+input:focus {
+  outline: none;
+  border-color: #3b82f6;
+  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+}
+
+button {
+  padding: 12px 20px;
+  border: none;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.btn-primary {
+  background: #3b82f6;
+  color: white;
+}
+
+.btn-primary:hover:not(:disabled) {
+  transform: translateY(-1px);
+}
+
+.result-card {
+  padding: 18px;
+  background: #f9fafb;
+  border: 2px solid #e5e7eb;
+  border-radius: 8px;
+  font-family: monospace;
+  font-size: 13px;
+  line-height: 1.6;
+  color: #374151;
+}
+
+p {
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.6;
+  color: #6b7280;
+}
+
+@media (max-width: 768px) {
+  .function-playground {
+    padding: 20px;
+  }
+}
+</style>
+```
+
+**开发注意事项：**
+- ✅ 使用 `../../../src/` 导入实际函数，不要 mock
+- ✅ 文件末尾不要有多余空行
+- ✅ 所有输入框添加 `box-sizing: border-box` 和 `min-width: 0`
+- ✅ 提供实时交互效果
+- ✅ 遵循统一的设计规范
+- ✅ 使用语义化的类名
+- ✅ 添加响应式设计
+- ✅ 保持视觉一致性
+
+#### 4. 侧边栏配置
+
+在 `docs/.vitepress/config.ts` 中添加菜单项：
+
+```typescript
+{
+  text: '模块名',
+  collapsed: true,
+  items: [
+    { text: 'functionName', link: '/api/category/functionName' },
+    // ... 其他函数
+  ]
+}
+```
+
+#### 5. 文档检查清单
+
+添加新函数后，必须确认：
+
+- [ ] 函数文档已创建（`docs/api/category/functionName.md`）
+- [ ] 文档包含所有必需部分（Playground、导入、类型、说明、示例、注意事项）
+- [ ] Playground 组件已创建（浏览器端函数）
+- [ ] 组件正确导入实际函数（不是 mock）
+- [ ] 侧边栏配置已更新
+- [ ] 运行 `npm run docs:dev` 验证无 404 错误
+- [ ] 页面可以正常访问和交互
+- [ ] 组件末尾无多余空行
+
+#### 6. 常见问题
+
+**Q: 页面显示 404？**
+- 检查文件名大小写是否正确
+- 检查侧边栏配置路径是否正确
+- 检查 Playground 组件是否有语法错误
+- 清除缓存并重启开发服务器
+
+**Q: Playground 不显示？**
+- 检查组件文件名是否符合命名规范
+- 检查组件末尾是否有多余空行
+- 检查是否正确导入实际函数
+
+**Q: Node.js 端函数需要 Playground 吗？**
+- 不需要，只需要详细的代码示例即可
 
 ---