project-validator

项目验证器

验证 apps-in-toss 项目的配置、结构和策略，涵盖 Web 和 React Native 项目。

支持的项目类型：

• 使用 @apps-in-toss/web-framework 的 Web 项目
• 使用 @apps-in-toss/granite 和 Metro 打包器的 React Native 项目
• Unity 游戏项目（使用 @apps-in-toss/web-framework 构建 WebGL）

如何使用此技能

验证 apps-in-toss 项目时，请按以下步骤操作：

1. 确定项目类型（Web 或 React Native）
2. 使用 Read 工具读取并检查相关文件
3. 对照参考文档中的架构定义
4. 向用户报告检查结果，并说明具体问题和解决方案

验证清单

项目结构

检查项目是否包含：

• ✅ 存在 package.json
• ✅ 存在 granite.config.ts
• ⚠️ 存在 src/ 目录（推荐）
• ⚠️ 存在 tsconfig.json（TypeScript 项目推荐）

package.json 验证

检查：

• ✅ 文件是有效的 JSON
• ✅ 在 dependencies 或 devDependencies 中包含 @apps-in-toss/framework、@apps-in-toss/web-framework 或 @granite-js/react-native
• ⚠️ 包含 TDS（Toss Design System）程序包（强烈推荐，以保持一致的 Toss 用户体验）：
  • 对于使用 @apps-in-toss/framework < 1.0.0 的 React Native：@toss-design-system/react-native
  • 对于使用 @apps-in-toss/framework >= 1.0.0 的 React Native：@toss/tds-react-native
  • 对于使用 @apps-in-toss/web-framework < 1.0.0 的 Web：@toss-design-system/mobile
  • 对于使用 @apps-in-toss/web-framework >= 1.0.0 的 Web：@toss/tds-mobile
• ⚠️ 包含 name 字段
• ⚠️ 包含 version 字段
• ⚠️ 包含 scripts 字段和常用脚本（dev、build 等）

granite.config.ts 验证

Web 项目

对照 web-granite-config-schema.md 检查：

必需检查项：

• ✅ 文件存在且可读取
• ✅ 从 @apps-in-toss/web-framework/config 导入 defineConfig
• ✅ 包含 export default defineConfig 语句
• ✅ 包含必需字段：
  • appName（字符串）
  • brand（包含 displayName、primaryColor、icon 的对象）
  • permissions（数组）
  • web.port（数字）
  • web.commands.dev（字符串）
  • web.commands.build（字符串）

可选推荐字段：

• ⚠️ navigationBar（对象）
• ⚠️ webViewProps（对象）
• ⚠️ outdir（字符串）

React Native 项目

对照 react-native-granite-config-schema.md 检查：

必需检查项：

• ✅ 文件存在且可读取
• ✅ 从 @granite-js/react-native/config 导入 defineConfig
• ✅ 从 @apps-in-toss/framework/plugins 导入 appsInToss
• ✅ 包含 export default defineConfig 语句
• ✅ 包含必需字段：
  • scheme（字符串）
  • appName（字符串）
• ✅ 在 plugins 数组中包含 appsInToss 插件，并包含：
  • brand（包含 displayName、primaryColor、icon 的对象）
  • permissions（数组）

可选推荐字段：

• ⚠️ navigationBar（对象）
• ⚠️ entryFile（字符串）
• ⚠️ outdir（字符串）

验证工作流

开始新项目时

1. 读取 package.json，确定项目类型和框架版本
2. 读取 granite.config.ts，确定应用类型（游戏或非游戏）
3. 确定要使用的配置架构定义：
   • Web 应用（包括 Unity 游戏）：web-granite-config-schema.md
   • React Native 应用：react-native-granite-config-schema.md
4. 对于非游戏应用：检查是否安装了 TDS 程序包（推荐安装，以提升用户体验）
5. 对于 Unity 游戏应用：检查是否安装 Unity SDK 或存在 WebGL 构建产物（参见 unity-game-validation.md）
6. 根据相应的架构定义检查所有必需字段
7. 报告任何缺失或不正确的配置
8. 根据架构定义文档提供具体解决方案

调试配置问题时

1. 询问用户遇到了什么问题
2. 阅读相关配置文件
3. 对照 schema 要求进行检查
4. 找出根本原因
5. 从常见问题与解决方案中提供解决方案

检查项目设置时

1. 系统地检查所有验证项
2. 优先报告严重错误（❌）
3. 然后报告警告（⚠️）
4. 根据最佳实践提出改进建议

报告验证结果

向用户报告验证结果时：

✅ 成功

所有必需的检查均已通过。项目配置有效。

❌ 严重错误

必需配置缺失或无效。项目可能无法正常运行。

• 以高优先级报告这些问题
• 提供具体的文件位置（例如，granite.config.ts:15）
• 根据 schema 文档提供确切的修复方法

⚠️ 警告

检测到非严重问题。项目可能可以运行，但最佳实践建议解决这些问题。

• 在严重错误之后报告这些问题
• 说明这项建议的重要原因
• 提供可选的改进建议

常见问题与解决方案

缺少框架依赖项

问题： package.json 中没有必需的框架包

Web 解决方案：

npm install @apps-in-toss/web-framework

React Native 解决方案：

npm install @granite-js/react-native @apps-in-toss/framework

缺少必需字段：appName

问题： granite.config.ts 中缺少 appName 字段

解决方案： 将 appName 添加到 granite.config.ts：

export default defineConfig({
  appName: 'my-app',
  // ...
});

缺少必需字段：brand

问题： granite.config.ts 中缺少 brand 配置

解决方案： 添加完整的 brand 对象：

export default defineConfig({
  brand: {
    displayName: 'My App',
    primaryColor: '#3182F6',
    icon: 'https://static.toss.im/icons/app-icon.png',
  },
  // ...
});

缺少必需字段：permissions

问题： granite.config.ts 中缺少 permissions 数组

解决方案： 添加 permissions 数组（可以为空）：

export default defineConfig({
  permissions: [],
  // or with specific permissions:
  permissions: [
    { name: 'clipboard', access: 'read' },
    { name: 'camera', access: 'access' },
  ],
  // ...
});

缺少 appsInToss 插件（React Native）

问题： React Native 项目没有 appsInToss 插件

解决方案： 将该插件添加到 plugins 数组：

import { appsInToss } from '@apps-in-toss/framework/plugins';

export default defineConfig({
  plugins: [
    appsInToss({
      brand: {
        displayName: 'My App',
        primaryColor: '#3182F6',
        icon: 'https://static.toss.im/icons/app-icon.png',
      },
      permissions: [],
    }),
  ],
});

导入路径错误

问题： defineConfig 使用了错误的导入路径

Web 解决方案：

import { defineConfig } from '@apps-in-toss/web-framework/config';

React Native 解决方案：

import { defineConfig } from '@granite-js/react-native/config';

缺少必需文件：granite.config.ts

问题： 项目没有 granite.config.ts 文件

解决方案： 使用相应的模板创建文件：

• Web 项目：参见 web-granite-config-schema.md
• React Native 项目：参见 react-native-granite-config-schema.md

缺少导出语句

问题： granite.config.ts 未导出配置

解决方案： 添加导出语句：

export default defineConfig({ /* config */ });

缺少 TDS（Toss Design System）包

问题： 迷你应用的 package.json 中没有 TDS 包

重要： 强烈建议使用 TDS，以确保 Toss UX 一致，并提高审核通过的机会。

React Native 解决方案：

检查 package.json 中的框架版本：

如果 @apps-in-toss/framework < 1.0.0：

npm install @toss-design-system/react-native

如果 @apps-in-toss/framework >= 1.0.0：

npm install @toss/tds-react-native

Web 解决方案：

检查 package.json 中的框架版本：

如果 @apps-in-toss/web-framework < 1.0.0：

npm install @toss-design-system/mobile

如果 @apps-in-toss/web-framework >= 1.0.0：

npm install @toss/tds-mobile

TDS 文档：

• React Native：https://tossmini-docs.toss.im/tds-react-native
• Web：https://tossmini-docs.toss.im/tds-mobile

注意： 游戏应用（appType: 'game'）可能无需满足 TDS 要求

参考文档

验证时务必查阅以下参考资料：

• web-granite-config-schema.md — Web granite.config.ts 的完整架构和示例
• react-native-granite-config-schema.md — React Native granite.config.ts 的完整架构和示例
• unity-game-validation.md — Unity WebGL 游戏项目验证指南
• Apps-in-Toss Unity 官方文档（验证要点）：
  • 平台模型与预检（overview、runtime-structure、precheck）：WebGL/WASM + JS 桥接；不支持原生插件；面向移动设备/触控的目标；文件 I/O 和套接字使用受限；AR/XR/Compute 受到限制。
  • 引擎版本（recommend-engine）：优先选择 Unity 2023.3 LTS；2022.3 稳定；2021.3 为旧版；避免在生产环境中使用 2024.2 beta。
  • 迁移流程（migration-guide）：预检 → 转换为 WebGL → 集成 Apps-in-Toss SDK → 优化 UX/性能 → 打包/监控 .ait。
  • 性能目标（perf-optimization、perf-measure）：启动时间目标 <3s（最长 <5s），移动设备平均 FPS ≥30，内存 <200MB（超过 300MB 为严重问题），首帧 <5s，耗电量约为原生应用的 90–110%。
  • 运行时/启动/加载（runtime/performance、startup-speed、loading）：采用自适应帧率/画质、批处理/实例化/LOD/剔除、池化更新；避免在首帧执行繁重工作；渐进式/优先级加载，并提供卸载路径和缓存限制；尽可能将场景切换控制在约 2s。
  • 调试（debug-exception）：将日志集中记录到 Web/Apps-in-Toss；使用带恢复机制的全局异常处理器；为 WebGL 添加应用内分析器/控制台钩子。

验证最佳实践

1. 明确具体：报告问题时，尽可能提供准确的文件路径和行号
2. 提供上下文：说明为何某个字段是必需的或建议使用的
3. 提供解决方案：务必提供架构文档中的准确代码修复方案
4. 确定优先级：先报告严重错误，再报告警告
5. 全面检查：检查所有必需字段，而不只是显而易见的字段
6. 检查 TDS 使用情况：确认是否已安装 TDS 包，并建议使用该包以确保 Toss UX 一致
7. 提供文档链接：建议使用 TDS 时，附上相关 TDS 文档链接

验证报告示例

Validating apps-in-toss project...

✅ package.json found and valid
✅ granite.config.ts found

Project Type: Web (detected @apps-in-toss/web-framework v1.2.0)
App Type: general (non-game)

❌ Critical Errors:
1. Missing required field: brand
   Location: granite.config.ts
   Fix: Add brand configuration with displayName, primaryColor, and icon

2. Missing required field: permissions
   Location: granite.config.ts
   Fix: Add permissions array (can be empty: permissions: [])

⚠️ Warnings:
1. Missing recommended field: navigationBar
   Suggestion: Add navigationBar for better UX

2. TDS package not found
   Recommendation: Install @toss/tds-mobile (for @apps-in-toss/web-framework >= 1.0.0)
   Command: npm install @toss/tds-mobile
   Benefit: Provides consistent Toss UX and improves review approval chances
   Documentation: https://tossmini-docs.toss.im/tds-mobile

Consult: references/web-granite-config-schema.md for complete examples