feng3d-cli 0.0.1 → 0.0.3

package/dist/versions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../src/versions.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;CAyBX,CAAC;AAEX;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgC9B"}
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../src/versions.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;CA6BX,CAAC;AAEX;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoC9B"}

package/dist/versions.js

@@ -22,6 +22,9 @@ export const VERSIONS = {
     'cross-env': '7.0.3',
     // 文档
     typedoc: '^0.28.4',
+    // Git hooks
+    husky: '^9.1.7',
+    'lint-staged': '^15.2.10',
 };
 /**
  * 获取 devDependencies 配置
@@ -49,6 +52,9 @@ export function getDevDependencies(options = {}) {
     if (options.includeTypedoc !== false) {
         deps.typedoc = VERSIONS.typedoc;
     }
+    // 默认包含 husky 和 lint-staged
+    deps.husky = VERSIONS.husky;
+    deps['lint-staged'] = VERSIONS['lint-staged'];
     return deps;
 }
 //# sourceMappingURL=versions.js.map

package/dist/versions.js.map

@@ -1 +1 @@
-{"version":3,"file":"versions.js","sourceRoot":"","sources":["../src/versions.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACpB,gBAAgB;IAChB,UAAU,EAAE,OAAO;IACnB,KAAK,EAAE,QAAQ;IAEf,YAAY;IACZ,MAAM,EAAE,QAAQ;IAChB,YAAY,EAAE,QAAQ;IACtB,kCAAkC,EAAE,QAAQ;IAC5C,2BAA2B,EAAE,QAAQ;IACrC,mBAAmB,EAAE,SAAS;IAC9B,OAAO,EAAE,SAAS;IAElB,OAAO;IACP,MAAM,EAAE,QAAQ;IAChB,qBAAqB,EAAE,QAAQ;IAC/B,WAAW,EAAE,UAAU;IAEvB,OAAO;IACP,IAAI,EAAE,QAAQ;IACd,MAAM,EAAE,OAAO;IACf,WAAW,EAAE,OAAO;IAEpB,KAAK;IACL,OAAO,EAAE,SAAS;CACZ,CAAC;AAEX;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAI/B,EAAE;IAEF,MAAM,IAAI,GAA2B;QACjC,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC;QACpC,kCAAkC,EAAE,QAAQ,CAAC,kCAAkC,CAAC;QAChF,2BAA2B,EAAE,QAAQ,CAAC,2BAA2B,CAAC;QAClE,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC;QAClC,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,mBAAmB,EAAE,QAAQ,CAAC,mBAAmB,CAAC;QAClD,IAAI,EAAE,QAAQ,CAAC,IAAI;KACtB,CAAC;IAEF,IAAI,OAAO,CAAC,aAAa,KAAK,KAAK,EACnC,CAAC;QACG,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IAClC,CAAC;IAED,IAAI,OAAO,CAAC,eAAe,EAC3B,CAAC;QACG,IAAI,CAAC,qBAAqB,CAAC,GAAG,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAClE,CAAC;IAED,IAAI,OAAO,CAAC,cAAc,KAAK,KAAK,EACpC,CAAC;QACG,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IACpC,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC"}
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../src/versions.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACpB,gBAAgB;IAChB,UAAU,EAAE,OAAO;IACnB,KAAK,EAAE,QAAQ;IAEf,YAAY;IACZ,MAAM,EAAE,QAAQ;IAChB,YAAY,EAAE,QAAQ;IACtB,kCAAkC,EAAE,QAAQ;IAC5C,2BAA2B,EAAE,QAAQ;IACrC,mBAAmB,EAAE,SAAS;IAC9B,OAAO,EAAE,SAAS;IAElB,OAAO;IACP,MAAM,EAAE,QAAQ;IAChB,qBAAqB,EAAE,QAAQ;IAC/B,WAAW,EAAE,UAAU;IAEvB,OAAO;IACP,IAAI,EAAE,QAAQ;IACd,MAAM,EAAE,OAAO;IACf,WAAW,EAAE,OAAO;IAEpB,KAAK;IACL,OAAO,EAAE,SAAS;IAElB,YAAY;IACZ,KAAK,EAAE,QAAQ;IACf,aAAa,EAAE,UAAU;CACnB,CAAC;AAEX;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAI/B,EAAE;IAEF,MAAM,IAAI,GAA2B;QACjC,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC;QACpC,kCAAkC,EAAE,QAAQ,CAAC,kCAAkC,CAAC;QAChF,2BAA2B,EAAE,QAAQ,CAAC,2BAA2B,CAAC;QAClE,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC;QAClC,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,mBAAmB,EAAE,QAAQ,CAAC,mBAAmB,CAAC;QAClD,IAAI,EAAE,QAAQ,CAAC,IAAI;KACtB,CAAC;IAEF,IAAI,OAAO,CAAC,aAAa,KAAK,KAAK,EACnC,CAAC;QACG,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IAClC,CAAC;IAED,IAAI,OAAO,CAAC,eAAe,EAC3B,CAAC;QACG,IAAI,CAAC,qBAAqB,CAAC,GAAG,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAClE,CAAC;IAED,IAAI,OAAO,CAAC,cAAc,KAAK,KAAK,EACpC,CAAC;QACG,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IACpC,CAAC;IAED,2BAA2B;IAC3B,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;IAC5B,IAAI,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IAE9C,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,68 +1,85 @@
 {
-    "name": "feng3d-cli",
-    "version": "0.0.1",
-    "description": "feng3d 项目通用标准，包含代码规范、配置模板和 CLI 工具",
-    "homepage": "https://github.com/feng3d-labs/feng3d-cli",
-    "author": "feng",
-    "license": "MIT",
-    "type": "module",
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "bin": {
-        "feng3d-cli": "./dist/cli.js"
+  "name": "feng3d-cli",
+  "version": "0.0.3",
+  "description": "feng3d 项目通用标准，包含代码规范、配置模板和 CLI 工具",
+  "homepage": "https://feng3d.com/feng3d-cli/",
+  "author": "feng",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "feng3d-cli": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        },
-        "./eslint": {
-            "types": "./dist/eslint.d.ts",
-            "import": "./dist/eslint.js"
-        }
-    },
-    "scripts": {
-        "build": "tsc",
-        "dev": "tsc -w",
-        "test": "vitest run",
-        "test:watch": "vitest",
-        "lint": "eslint . --ext .js,.ts --max-warnings 0",
-        "lintfix": "npm run lint -- --fix",
-        "update-rules": "node dist/cli.js update --all",
-        "prepublishOnly": "npm run lint && npm test && npm run build",
-        "publish:manual": "npm publish"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/feng3d-labs/feng3d-cli.git"
-    },
-    "files": [
-        "dist",
-        "templates"
-    ],
-    "dependencies": {
-        "ali-oss": "^6.22.0",
-        "chalk": "^5.3.0",
-        "commander": "^12.1.0",
-        "fs-extra": "^11.2.0"
-    },
-    "devDependencies": {
-        "@eslint/js": "^9.0.0",
-        "@types/fs-extra": "^11.0.4",
-        "@types/node": "^22.10.2",
-        "@typescript-eslint/eslint-plugin": "8.32.1",
-        "@typescript-eslint/parser": "8.32.1",
-        "eslint": "9.26.0",
-        "globals": "^14.0.0",
-        "rimraf": "6.0.1",
-        "tslib": "^2.8.1",
-        "typedoc": "^0.28.4",
-        "typescript": "5.8.3",
-        "typescript-eslint": "^8.32.1",
-        "vite": "^6.3.5",
-        "vitest": "^3.1.3"
+    "./eslint": {
+      "types": "./dist/eslint.d.ts",
+      "import": "./dist/eslint.js"
     }
+  },
+  "scripts": {
+    "clean": "rimraf \"{lib,dist,public}\"",
+    "build": "tsc",
+    "dev": "tsc -w",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "types": "tsc",
+    "watch": "tsc -w",
+    "lint": "eslint . --ext .js,.ts --max-warnings 0",
+    "lintfix": "npm run lint -- --fix",
+    "docs": "typedoc",
+    "upload_oss": "npm run build && npm run docs && node dist/cli.js oss_upload_dir",
+    "update": "npm run build && node dist/cli.js update && npm install",
+    "release": "npm run clean && npm run lint && npm run build && npm run docs && npm publish",
+    "prepublishOnly": "npm run lint && npm test && npm run build",
+    "publish:manual": "npm publish",
+    "prepare": "husky",
+    "postinstall": "npm run build && node dist/cli.js update || exit 0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/feng3d-labs/feng3d-cli.git"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "schemas"
+  ],
+  "dependencies": {
+    "ali-oss": "^6.22.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.10.2",
+    "@typescript-eslint/eslint-plugin": "8.32.1",
+    "@typescript-eslint/parser": "8.32.1",
+    "eslint": "9.26.0",
+    "globals": "^14.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.2.10",
+    "rimraf": "6.0.1",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.4",
+    "typescript": "5.8.3",
+    "typescript-eslint": "^8.32.1",
+    "vite": "^6.3.5",
+    "vitest": "^3.1.3",
+    "cross-env": "7.0.3"
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "eslint --fix --max-warnings 0"
+    ]
+  }
 }

package/schemas/feng3d.schema.json

@@ -0,0 +1,191 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "feng3d.schema.json",
+    "title": "feng3d 项目配置",
+    "description": "feng3d 项目配置文件，用于自定义项目规范和 CLI 行为",
+    "type": "object",
+    "properties": {
+        "$schema": {
+            "type": "string",
+            "description": "JSON Schema 引用"
+        },
+        "name": {
+            "type": "string",
+            "description": "项目名称"
+        },
+        "eslint": {
+            "type": "object",
+            "description": "ESLint 配置选项",
+            "properties": {
+                "enabled": {
+                    "type": "boolean",
+                    "description": "是否启用 ESLint",
+                    "default": true
+                },
+                "ignores": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "额外需要忽略的目录",
+                    "default": []
+                },
+                "rules": {
+                    "type": "object",
+                    "description": "额外的规则覆盖",
+                    "additionalProperties": true,
+                    "default": {}
+                }
+            },
+            "additionalProperties": false
+        },
+        "vitest": {
+            "type": "object",
+            "description": "Vitest 测试配置选项",
+            "properties": {
+                "enabled": {
+                    "type": "boolean",
+                    "description": "是否启用 vitest",
+                    "default": true
+                },
+                "testTimeout": {
+                    "type": "number",
+                    "description": "测试超时时间（毫秒，0 表示无限制）",
+                    "default": 0,
+                    "minimum": 0
+                }
+            },
+            "additionalProperties": false
+        },
+        "typedoc": {
+            "type": "object",
+            "description": "TypeDoc 文档配置选项",
+            "properties": {
+                "enabled": {
+                    "type": "boolean",
+                    "description": "是否启用 typedoc",
+                    "default": true
+                },
+                "outDir": {
+                    "type": "string",
+                    "description": "文档输出目录",
+                    "default": "public/docs"
+                }
+            },
+            "additionalProperties": false
+        },
+        "oss": {
+            "type": "object",
+            "description": "OSS 上传配置",
+            "properties": {
+                "localDir": {
+                    "type": "string",
+                    "description": "本地目录",
+                    "default": "./public"
+                },
+                "ossDir": {
+                    "type": "string",
+                    "description": "OSS 目录（默认使用 package.json 的 name）",
+                    "default": ""
+                }
+            },
+            "additionalProperties": false
+        },
+        "templates": {
+            "type": "object",
+            "description": "项目模板选项",
+            "properties": {
+                "examples": {
+                    "type": "boolean",
+                    "description": "是否创建示例目录",
+                    "default": true
+                },
+                "test": {
+                    "type": "boolean",
+                    "description": "是否创建测试目录",
+                    "default": true
+                }
+            },
+            "additionalProperties": false
+        },
+        "update": {
+            "type": "object",
+            "description": "更新配置（指定 feng3d-cli update 时默认更新哪些项目）",
+            "properties": {
+                "config": {
+                    "type": "boolean",
+                    "description": "是否更新 feng3d.json 配置",
+                    "default": true
+                },
+                "eslint": {
+                    "type": "boolean",
+                    "description": "是否更新 ESLint 配置",
+                    "default": true
+                },
+                "gitignore": {
+                    "type": "boolean",
+                    "description": "是否更新 .gitignore",
+                    "default": true
+                },
+                "cursorrules": {
+                    "type": "boolean",
+                    "description": "是否更新 .cursorrules",
+                    "default": true
+                },
+                "publish": {
+                    "type": "boolean",
+                    "description": "是否更新 npm publish workflow",
+                    "default": true
+                },
+                "pages": {
+                    "type": "boolean",
+                    "description": "是否更新 GitHub Pages workflow",
+                    "default": true
+                },
+                "pullRequest": {
+                    "type": "boolean",
+                    "description": "是否更新 Pull Request CI workflow",
+                    "default": true
+                },
+                "typedoc": {
+                    "type": "boolean",
+                    "description": "是否更新 typedoc.json",
+                    "default": true
+                },
+                "test": {
+                    "type": "boolean",
+                    "description": "是否更新 test/_.test.ts",
+                    "default": true
+                },
+                "deps": {
+                    "type": "boolean",
+                    "description": "是否更新依赖版本",
+                    "default": true
+                },
+                "husky": {
+                    "type": "boolean",
+                    "description": "是否更新 husky pre-commit hook",
+                    "default": true
+                },
+                "license": {
+                    "type": "boolean",
+                    "description": "是否更新 LICENSE 文件",
+                    "default": true
+                },
+                "vscode": {
+                    "type": "boolean",
+                    "description": "是否更新 .vscode/settings.json",
+                    "default": true
+                },
+                "tsconfig": {
+                    "type": "boolean",
+                    "description": "是否更新 tsconfig.json",
+                    "default": true
+                }
+            },
+            "additionalProperties": false
+        }
+    },
+    "additionalProperties": false
+}
+

package/templates/.cursorrules

@@ -1,79 +1,159 @@
-# Cursor 项目规则
-
-## Git 提交信息规范
-
-当生成 Git 提交信息时：
-
-1. **语言**：始终使用简体中文
-
-2. **格式**：遵循约定式提交（Conventional Commits）格式
-   ```
-   <类型>(<范围>): <简短描述>
-
-   [可选的详细说明]
-
-   [可选的脚注]
-   ```
-
-3. **提交类型**（中文描述）：
-   - `feat`: 新增功能
-   - `fix`: 修复问题
-   - `refactor`: 代码重构（不改变功能）
-   - `perf`: 性能优化
-   - `style`: 代码格式调整（不影响代码含义）
-   - `docs`: 文档更新
-   - `test`: 测试相关
-   - `chore`: 构建过程或辅助工具的变动
-   - `build`: 构建系统或外部依赖项的更改
-   - `ci`: CI 配置文件和脚本的更改
-
-4. **范围**（可选）：可以是模块、组件或功能区域
-
-5. **提交信息要求**：
-   - 第一行简短描述，不超过 50 个字符
-   - 使用祈使句，如"添加"、"修复"、"优化"
-   - 描述要清晰、具体、有意义
-
-## 代码风格
-
-- 优先使用 TypeScript
-- 遵循现有代码的命名约定和格式
-- 添加必要的中文注释以提高代码可读性
-- 使用 ESLint 保持代码格式一致
-- 提交前必须通过 lint 检查
-- 避免使用 `any` 类型，优先使用明确的类型定义
-
-## 命名规范
-
-- **变量和函数**：使用驼峰命名（camelCase）
-- **类和接口**：使用帕斯卡命名（PascalCase）
-- **常量**：使用全大写下划线分隔（UPPER_SNAKE_CASE）
-- **文件名**：使用小写字母和连字符（kebab-case）或与导出的主要类/函数同名
-
-## 注释规范
-
-- 公共 API 必须添加 JSDoc 注释
-- 复杂逻辑必须添加中文注释说明
-- 临时解决方案或待优化代码必须添加 TODO 注释
-- 注释应该解释"为什么"而不是"是什么"
-
-## 模块结构
-
-- 避免使用默认导出，优先使用命名导出
-- 每个文件应该有一个明确的职责
-- 每个文件应该不超过 300 行代码
-- 相关功能应该组织在同一个目录下
-
-## 测试规范
-
-- 新功能必须包含相应的测试
-- 修复 bug 时必须添加回归测试
-- 测试覆盖率应该保持在合理水平（建议 > 80%）
-- 测试应该清晰、独立、可重复
-
-## Agent 规则
-
-- 没有正确修复问题时重新修复时，尽量还原上次修改的内容后再进行修复
-- 每次完成代码修改后，必须检查并处理编译错误
-- 确保所有测试通过后再告知用户任务完成
-
+# Cursor 项目规则
+
+## Git 提交信息规范
+
+当生成 Git 提交信息时：
+
+1. **语言**：始终使用简体中文
+
+2. **格式**：遵循约定式提交（Conventional Commits）格式
+   ```
+   <类型>(<范围>): <简短描述>
+   
+   [可选的详细说明]
+   
+   [可选的脚注]
+   ```
+
+3. **提交类型**（中文描述）：
+   - `feat`: 新增功能
+   - `fix`: 修复问题
+   - `refactor`: 代码重构（不改变功能）
+   - `perf`: 性能优化（图形渲染项目重点关注）
+   - `style`: 代码格式调整（不影响代码含义）
+   - `docs`: 文档更新
+   - `test`: 测试相关
+   - `chore`: 构建过程或辅助工具的变动
+   - `build`: 构建系统或外部依赖项的更改
+   - `ci`: CI 配置文件和脚本的更改
+
+4. **范围**（可选）：可以是模块、组件或功能区域，如 `webgl`、`webgpu`、`test` 等
+
+5. **提交信息要求**：
+   - 第一行简短描述，不超过 50 个字符
+   - 使用祈使句，如"添加"、"修复"、"优化"
+   - 描述要清晰、具体、有意义
+   - 如有必要，添加详细说明，解释"为什么"而不是"是什么"
+   - 性能优化提交应说明优化点和预期效果
+
+6. **示例**：
+   ```
+   feat(webgl): 添加深度测试功能
+   
+   - 实现深度缓冲区管理
+   - 添加深度测试配置选项
+   - 更新相关文档
+   ```
+   
+   ```
+   perf(webgpu): 优化纹理上传性能
+   
+   - 使用批量上传减少 GPU 调用次数
+   - 预期性能提升 30%
+   ```
+
+## 代码风格
+
+- 优先使用 TypeScript
+- 遵循现有代码的命名约定和格式
+- 添加必要的中文注释以提高代码可读性
+- 使用 ESLint 和 Prettier 保持代码格式一致
+- 提交前必须通过 lint 检查
+- 避免使用 `any` 类型，优先使用明确的类型定义
+
+## 命名规范
+
+- **变量和函数**：使用驼峰命名（camelCase）
+- **类和接口**：使用帕斯卡命名（PascalCase）
+- **常量**：使用全大写下划线分隔（UPPER_SNAKE_CASE）
+- **文件名**：使用小写字母和连字符（kebab-case）或与导出的主要类/函数同名，优先使用函数名
+
+## 注释规范
+
+- 公共 API 必须添加 JSDoc 注释
+- 复杂逻辑必须添加中文注释说明
+- 临时解决方案或待优化代码必须添加 TODO 注释
+- 注释应该解释"为什么"而不是"是什么"
+
+## 代码组织结构
+
+- **配置文件结构**：在配置文件中（如 `vite.config.js`、`test_vite.config.js` 等），应按照以下顺序组织代码：
+  - **文件头部**：导入语句、配置变量（可更改的设置）、主要执行逻辑（如 `export default defineConfig()`）
+  - 其次是导出函数以及类应该放在文件前面
+  - 再其次是私有函数和类应该放在文件后面
+  - **文件尾部**：函数定义（所有辅助函数和工具函数）
+  
+  这样可以让配置文件的主要配置和执行逻辑一目了然，而将实现细节放在后面。
+
+- **模块结构**：
+  - 避免使用默认导出，优先使用命名导出
+  - 避免不必要的导出
+  - 每个文件应该有一个明确的职责
+  - 每个文件应该不超过 300 行代码
+  - 相关功能应该组织在同一个目录下
+  - 使用清晰的目录结构（如 `src/utils/`、`src/types/` 等）
+  - 每个模块应该有清晰的职责边界
+  - 模块间依赖应该明确且最小化
+  - 公共 API 应该稳定，变更需要充分讨论
+
+- **渲染相关代码**：
+  - Shader 代码应单独文件管理
+  - 渲染管线相关代码应组织在专门的目录
+  - 资源管理代码应与渲染逻辑分离
+
+## 性能优化规范
+
+- **内存管理**：
+  - 及时释放 GPU 资源（纹理、缓冲区等）
+  - 避免内存泄漏，特别是在渲染循环中
+  - 使用对象池复用频繁创建的对象
+
+- **渲染优化**：
+  - 减少 draw call 数量
+  - 合理使用批处理（batching）
+  - 避免在渲染循环中进行不必要的计算
+  - 使用缓存避免重复计算
+
+- **类型安全**：
+  - 避免使用 `any` 类型
+  - 为 GPU 资源提供明确的类型定义
+  - 使用类型守卫确保运行时类型安全
+
+## 错误处理
+
+- 优先使用明确的错误类型
+- 提供有意义的错误消息
+- 避免静默失败，除非有明确的业务需求
+
+## 代码审查规范
+
+- 所有代码变更必须经过代码审查
+- 审查重点：
+  - 代码逻辑正确性
+  - 性能影响
+  - 类型安全
+  - 测试覆盖
+  - 文档完整性
+
+## 文档规范
+
+- 公共 API 必须包含完整的 JSDoc 注释
+- 复杂算法或业务逻辑必须添加说明文档
+- README 文件应该保持更新
+- 重大变更应该更新 CHANGELOG
+
+## 测试规范
+
+- 新功能必须包含相应的测试
+- 修复 bug 时必须添加回归测试
+- 关键渲染功能必须包含测试
+- 性能关键路径应包含性能测试
+- 使用 WebGL/WebGPU 测试框架进行渲染测试
+- 测试覆盖率应该保持在合理水平（建议 > 80%）
+- 测试应该清晰、独立、可重复
+
+## agent 规则
+
+- 没有正确修复问题时重新让修复时，尽量还原上次修改的内容后再进行修复
+- 每次完成代码修改后，必须检查并处理编译错误（使用 ReadLints 工具或运行测试）
+- 确保所有测试通过后再告知用户任务完成

package/templates/.github/workflows/pages.yml

@@ -0,0 +1,60 @@
+# 将文档发布到 GitHub Pages
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  release:
+    types: [published]  # 发布新版本时触发
+  workflow_dispatch:  # 支持手动触发
+
+# 设置 GITHUB_TOKEN 的权限
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# 只允许一个并发部署
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build docs
+        run: npm run docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './public'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+