feng3d-cli 0.0.2 → 0.0.4

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

@@ -9,9 +9,9 @@
 2. **格式**：遵循约定式提交（Conventional Commits）格式
    ```
    <类型>(<范围>): <简短描述>
-
+   
    [可选的详细说明]
-
+   
    [可选的脚注]
    ```
 
@@ -19,7 +19,7 @@
    - `feat`: 新增功能
    - `fix`: 修复问题
    - `refactor`: 代码重构（不改变功能）
-   - `perf`: 性能优化
+   - `perf`: 性能优化（图形渲染项目重点关注）
    - `style`: 代码格式调整（不影响代码含义）
    - `docs`: 文档更新
    - `test`: 测试相关
@@ -27,19 +27,37 @@
    - `build`: 构建系统或外部依赖项的更改
    - `ci`: CI 配置文件和脚本的更改
 
-4. **范围**（可选）：可以是模块、组件或功能区域
+4. **范围**（可选）：可以是模块、组件或功能区域，如 `webgl`、`webgpu`、`test` 等
 
 5. **提交信息要求**：
    - 第一行简短描述，不超过 50 个字符
    - 使用祈使句，如"添加"、"修复"、"优化"
    - 描述要清晰、具体、有意义
+   - 如有必要，添加详细说明，解释"为什么"而不是"是什么"
+   - 性能优化提交应说明优化点和预期效果
+
+6. **示例**：
+   ```
+   feat(webgl): 添加深度测试功能
+   
+   - 实现深度缓冲区管理
+   - 添加深度测试配置选项
+   - 更新相关文档
+   ```
+   
+   ```
+   perf(webgpu): 优化纹理上传性能
+   
+   - 使用批量上传减少 GPU 调用次数
+   - 预期性能提升 30%
+   ```
 
 ## 代码风格
 
 - 优先使用 TypeScript
 - 遵循现有代码的命名约定和格式
 - 添加必要的中文注释以提高代码可读性
-- 使用 ESLint 保持代码格式一致
+- 使用 ESLint 和 Prettier 保持代码格式一致
 - 提交前必须通过 lint 检查
 - 避免使用 `any` 类型，优先使用明确的类型定义
 
@@ -48,7 +66,7 @@
 - **变量和函数**：使用驼峰命名（camelCase）
 - **类和接口**：使用帕斯卡命名（PascalCase）
 - **常量**：使用全大写下划线分隔（UPPER_SNAKE_CASE）
-- **文件名**：使用小写字母和连字符（kebab-case）或与导出的主要类/函数同名
+- **文件名**：使用小写字母和连字符（kebab-case）或与导出的主要类/函数同名，优先使用函数名
 
 ## 注释规范
 
@@ -57,23 +75,85 @@
 - 临时解决方案或待优化代码必须添加 TODO 注释
 - 注释应该解释"为什么"而不是"是什么"
 
-## 模块结构
-
-- 避免使用默认导出，优先使用命名导出
-- 每个文件应该有一个明确的职责
-- 每个文件应该不超过 300 行代码
-- 相关功能应该组织在同一个目录下
+## 代码组织结构
+
+- **配置文件结构**：在配置文件中（如 `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 规则
-
-- 没有正确修复问题时重新修复时，尽量还原上次修改的内容后再进行修复
-- 每次完成代码修改后，必须检查并处理编译错误
-- 确保所有测试通过后再告知用户任务完成
+## agent 规则
 
+- 没有正确修复问题时重新让修复时，尽量还原上次修改的内容后再进行修复
+- 每次完成代码修改后，必须检查并处理编译错误（使用 ReadLints 工具或运行测试）
+- 确保所有测试通过后再告知用户任务完成

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

@@ -0,0 +1,93 @@
+# 将文档发布到 GitHub Pages
+# 仅在主分支版本号发生变化时触发部署
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+      - main
+    paths:
+      - 'package.json'  # 仅在 package.json 变化时触发
+  workflow_dispatch:  # 支持手动触发
+
+# 设置 GITHUB_TOKEN 的权限
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# 只允许一个并发部署
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # 检查版本号是否变化
+  check-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version_changed: ${{ steps.check.outputs.changed }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2  # 获取最近两次提交以比较版本
+
+      - name: Check if version changed
+        id: check
+        run: |
+          # 获取当前版本
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          # 获取上一次提交的版本
+          git checkout HEAD~1 -- package.json 2>/dev/null || echo "First commit"
+          PREVIOUS_VERSION=$(node -p "require('./package.json').version" 2>/dev/null || echo "0.0.0")
+          git checkout HEAD -- package.json
+          
+          if [ "$CURRENT_VERSION" != "$PREVIOUS_VERSION" ]; then
+            echo "Version changed from $PREVIOUS_VERSION to $CURRENT_VERSION"
+            echo "changed=true" >> $GITHUB_OUTPUT
+          else
+            echo "Version unchanged: $CURRENT_VERSION"
+            echo "changed=false" >> $GITHUB_OUTPUT
+          fi
+
+  build:
+    runs-on: ubuntu-latest
+    needs: check-version
+    # 仅在版本号变化或手动触发时构建
+    if: needs.check-version.outputs.version_changed == 'true' || github.event_name == 'workflow_dispatch'
+    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
+

package/templates/.github/workflows/publish.yml

@@ -0,0 +1,128 @@
+# 当 package.json 中的版本在 npm 不存在时自动发布
+name: Publish to NPM
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  workflow_dispatch:  # 支持手动触发
+
+jobs:
+  check-version:
+    runs-on: ubuntu-latest
+    outputs:
+      should_publish: ${{ steps.check.outputs.should_publish }}
+      version: ${{ steps.check.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check if version exists on npm
+        id: check
+        run: |
+          # 获取包名和当前版本
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          echo "Package: $PACKAGE_NAME"
+          echo "Current version: $CURRENT_VERSION"
+
+          # 检查该版本是否已在 npm 上存在
+          HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://registry.npmjs.org/$PACKAGE_NAME/$CURRENT_VERSION")
+
+          if [ "$HTTP_STATUS" = "404" ]; then
+            echo "Version $CURRENT_VERSION not found on npm, will publish"
+            echo "should_publish=true" >> $GITHUB_OUTPUT
+            echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+          else
+            echo "Version $CURRENT_VERSION already exists on npm (HTTP $HTTP_STATUS)"
+            echo "should_publish=false" >> $GITHUB_OUTPUT
+          fi
+
+  publish:
+    needs: check-version
+    if: needs.check-version.outputs.should_publish == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # 获取完整历史以生成更新日志
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Run lint
+        run: npm run lint
+
+      - name: Run tests
+        run: npm test
+
+      - name: Publish to NPM
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create Git Tag
+        run: |
+          VERSION=${{ needs.check-version.outputs.version }}
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "v$VERSION" -m "Release v$VERSION"
+          git push origin "v$VERSION"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate Release Notes
+        id: release_notes
+        run: |
+          VERSION=${{ needs.check-version.outputs.version }}
+
+          # 获取上一个版本的 tag
+          PREVIOUS_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+
+          echo "Previous tag: $PREVIOUS_TAG"
+
+          # 生成更新日志
+          if [ -n "$PREVIOUS_TAG" ]; then
+            echo "## 更新内容" > release_notes.md
+            echo "" >> release_notes.md
+            echo "与 $PREVIOUS_TAG 相比的变更：" >> release_notes.md
+            echo "" >> release_notes.md
+
+            # 获取提交日志
+            git log --pretty=format:"- %s (%h)" $PREVIOUS_TAG..HEAD >> release_notes.md
+          else
+            echo "## 更新内容" > release_notes.md
+            echo "" >> release_notes.md
+            echo "首次发布" >> release_notes.md
+            echo "" >> release_notes.md
+
+            # 获取所有提交日志
+            git log --pretty=format:"- %s (%h)" >> release_notes.md
+          fi
+
+          echo "" >> release_notes.md
+
+          # 输出生成的内容
+          echo "Generated release notes:"
+          cat release_notes.md
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: v${{ needs.check-version.outputs.version }}
+          name: Release v${{ needs.check-version.outputs.version }}
+          body_path: release_notes.md
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

package/templates/.github/workflows/pull-request.yml

@@ -0,0 +1,36 @@
+# CI - 运行单元测试
+# 在合并到主分支或在主分支提交代码时执行
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  pull_request:
+    branches:
+      - master
+      - main
+
+jobs:
+  test:
+    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: Run lint
+        run: npm run lint
+
+      - name: Run unit tests
+        run: npm test
+

package/templates/.husky/pre-commit

@@ -0,0 +1,2 @@
+npx lint-staged
+

package/templates/.vscode/settings.json

@@ -0,0 +1,10 @@
+// 将设置放入此文件中以覆盖默认值和用户设置。
+{
+    // 定义函数的左大括号是否放置在新的一行。
+    "typescript.format.placeOpenBraceOnNewLineForFunctions": true,
+    // 定义控制块的左括号是否放置在新的一行。
+    "typescript.format.placeOpenBraceOnNewLineForControlBlocks": true,
+    "javascript.format.placeOpenBraceOnNewLineForFunctions": true,
+    "javascript.format.placeOpenBraceOnNewLineForControlBlocks": true
+}
+

package/templates/LICENSE

@@ -0,0 +1,15 @@
+MIT 许可证
+
+版权所有 (c) {{year}} feng
+
+特此授予任何获得本软件及相关文档文件（"软件"）副本的人免费许可，
+可以不受限制地处理本软件，包括但不限于使用、复制、修改、合并、
+发布、分发、再许可和/或销售本软件的副本，并允许向其提供本软件的
+人这样做，但须符合以下条件：
+
+上述版权声明和本许可声明应包含在本软件的所有副本或主要部分中。
+
+本软件按"原样"提供，不提供任何明示或暗示的保证，包括但不限于对
+适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权
+持有人均不对因本软件或本软件的使用或其他交易而产生的任何索赔、
+损害或其他责任负责，无论是在合同诉讼、侵权诉讼还是其他诉讼中。