内容
# 资产精灵
一套完整的、本地的模型上下文协议（MCP）服务器，使用纯 Dart 编写，用于自动化、审计和优化 Flutter 项目资产和本地化结构。将其连接到 Cursor 或 Claude Desktop 等 AI 客户端，让 AI 直接与项目的资产和翻译结构交互。
<img width="302" height="994" alt="AssetGenie in Action" src="https://github.com/user-attachments/assets/0858bc99-c10b-43a0-a8d4-05b9be17d558" />
## 🚀 功能特点
资产精灵向 LLM 上下文暴露了三个强大的工具：
### 1. `assetgenie_audit_health`
扫描项目的 `pubspec.yaml` 和物理文件夹，以识别资产异常：
- 标记在 `pubspec.yaml` 中声明的缺失物理文件。
- 标记未在 `pubspec.yaml` 中声明的物理资产（未声明资产）。
- 确定超过可配置文件大小阈值（默认：500 KB）的重资产。
- 通过在 `lib/` 源代码中搜索引用，自动检查未使用的物理文件。
### 2. `assetgenie_sync_localization`
安全地更新或注入翻译键到本地应用程序资源包（`.arb`）文件中：
- 在无需手动复制/粘贴的情况下追加新翻译。
- 标准化格式并将元数据键（`@key`）分组在其各自属性旁边。
- 按照标准 ARB 指南对键进行字母排序。
### 3. `assetgenie_generate_constants`
从物理资产文件中自动生成干净、现代的 Dart 常量：
- 递归遍历物理资产文件夹。
- 将文件路径转换为结构化的 `camelCase` 变量名。
- 动态解决标识符冲突和保留关键字。
- 在 `lib/generated/` 中编写一个安全的配置类 `Assets`，以防止拼写错误和硬编码字符串值。
## 🛠️ 安装与设置
确保您的系统上已安装 [Dart SDK](https://dart.dev/get-dart)。
1. 克隆仓库：
```bash
git clone https://github.com/aditzeb/AssetGenie.git
cd AssetGenie
```
2. 下载软件包依赖项：
```bash
dart pub get
```
3. 运行验证/测试以确保一切就绪：
```bash
dart test test/assetgenie_test.dart
```
## 🔌 连接到 LLMs 和 IDE（MCP 客户端）
要在您喜欢的 AI 助手或开发环境中使用资产精灵，请将其配置为本地 stdio MCP 服务器。
### 1. Antigravity IDE
Antigravity 会自动发现其全局 MCP 配置文件中配置的 MCP 服务器：
- **Windows**: `C:\Users\<Your-Username>\.gemini\antigravity-ide\mcp_config.json`
- **macOS / Linux**: `~/.gemini/antigravity-ide/mcp_config.json`
在 `"mcpServers"` 对象下添加以下内容：
```json
{
"mcpServers": {
"assetgenie": {
"command": "dart",
"args": [
"run",
"C:\\path\\to\\AssetGenie\\bin\\main.dart"
]
}
}
}
```
### 2. JetBrains IntelliJ IDEA / Android Studio
要将资产精灵的功能带入 IntelliJ IDEA 或 Android Studio，您可以使用 **Continue** 插件或 **Cline / Roo Cline** 插件。
#### 选项 A：使用 Continue（通过 config.yaml）
将以下内容添加到您的全局 Continue 配置（`~/.continue/config.yaml` 或 `C:\Users\<Your-Username>\.continue\config.yaml`）中的 `mcpServers` 块下：
```yaml
mcpServers:
- name: assetgenie
type: stdio
command: dart
args:
- "run"
- "C:\\path\\to\\AssetGenie\\bin\\main.dart"
```
> [!NOTE]
> 请确保在聊天面板中将 Continue 切换到 **Agent Mode** 以启用工具执行。
#### 选项 B：使用 Cline / Roo Cline
将以下内容添加到您的设置文件（`roo_cline_mcp_settings.json`）：
```json
{
"mcpServers": {
"assetgenie": {
"command": "dart",
"args": [
"run",
"C:\\path\\to\\AssetGenie\\bin\\main.dart"
]
}
}
}
```
### 3. VS Code
您可以通过应用与 JetBrains IDE 相同的配置，在 VS Code 中使用 **Continue**、**Cline** 或 **Roo Cline** 扩展。
- Cline 设置存储在 `C:\Users\<Your-Username>\AppData\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`（Windows）或 `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`（macOS）。
### 4. Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json` 配置文件中：
- **Windows**: `C:\Users\<Your-Username>\AppData\Roaming\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"assetgenie": {
"command": "dart",
"args": [
"run",
"C:\\path\\to\\AssetGenie\\bin\\main.dart"
]
}
}
}
```
### 5. Cursor / Windsurf
前往 **设置** -> **功能** -> **MCP**，点击 **添加新 MCP 服务器**：
- **名称**: `AssetGenie`
- **类型**: `stdio`
- **命令**: `dart run C:\path\to\AssetGenie\bin\main.dart`
## 📖 工具模式详情
### 1. `assetgenie_audit_health`
- `project_path`（字符串，必填）：Flutter 根目录的绝对路径。
- `max_size_kb`（数字，可选）：KB 大小阈值（默认：500）。
### 2. `assetgenie_sync_localization`
- `project_path`（字符串，必填）：Flutter 根目录的绝对路径。
- `locale`（字符串，必填）：目标语言代码（例如 `'en'`，`'de'`）。
- `kv_pairs`（对象，必填）：翻译对的 JSON 映射（例如 `{ "loginButton": "Sign In" }`）。
### 3. `assetgenie_generate_constants`
- `project_path`（字符串，必填）：Flutter 根目录的绝对路径。
- `output_filename`（字符串，可选）：目标文件名（默认：`'generated_assets.dart'`）。
## 📄 许可证
该项目是开源的，遵循 MIT 许可证。有关更多详细信息，请参见 [LICENSE](LICENSE)。
