# YAMA 定制化开发指南

> 面向技术型客户的二次开发与品牌定制

---

## 目标读者

- 有一定编程基础的客户
- 希望打造自己品牌的服务商
- 承接远程解决方案外包的开发者

---

## 第一部分：定制化概述

### 1. 可定制内容

| 类别 | 可定制项 | 难度 | 需要重编译 |
|------|---------|------|-----------|
| 品牌外观 | 程序名称、图标、版本信息 | 简单 | 是 |
| 菜单控制 | 隐藏/显示特定菜单项 | 简单 | 是 |
| 工具栏 | 隐藏/显示特定按钮 | 简单 | 是 |
| 右键菜单 | 隐藏/显示特定功能 | 简单 | 是 |
| 界面文字 | 修改翻译/添加语言 | 中等 | 否 |
| 功能定制 | 添加新功能、修改行为 | 高级 | 是 |

### 2. 定制方式

#### 2.1 配置文件定制（推荐）

修改 `UIBranding.h` 文件重新编译。

**适合场景：**
- 品牌名称修改
- 隐藏不需要的功能
- 快速生成定制版本

#### 2.2 资源替换定制

替换图标、图片等资源文件。

**适合场景：**
- 更换程序图标
- 自定义启动画面

#### 2.3 语言文件定制

修改语言文件实现界面文字定制。

**适合场景：**
- 修改界面用语
- 添加新语言支持

#### 2.4 源码级定制

修改源代码实现深度定制。

**适合场景：**
- 添加新功能
- 修改现有行为
- 深度集成

---

## 第二部分：品牌定制

### 3. UIBranding.h 配置文件

品牌定制的核心是修改 `server/2015Remote/UIBranding.h` 文件。

**文件位置：** `server/2015Remote/UIBranding.h`

**编码要求：** UTF-8 with BOM（MSVC 要求）

#### 3.1 快速定制（4 项核心设置）

最少只需修改以下 4 项即可完成基本品牌定制：

```cpp
// 程序名称（窗口标题）
#define BRAND_APP_NAME          "YourBrand"

// 启动画面 Logo（建议大写）
#define BRAND_SPLASH_NAME       "YOURBRAND"

// 托盘图标提示
#define BRAND_TRAY_TIP          "YourBrand 远程管理"

// 版权信息
#define BRAND_COPYRIGHT         "Copyright (C) 2024 YourCompany"
```

#### 3.2 完整品牌设置

| 配置项 | 说明 | 字符限制 |
|--------|------|---------|
| `BRAND_APP_NAME` | 窗口标题、关于对话框 | 可用中文 |
| `BRAND_VERSION` | 版本号（建议 X.Y.Z 格式） | 可用中文 |
| `BRAND_SPLASH_NAME` | 启动画面 Logo 文字 | 可用中文 |
| `BRAND_TRAY_TIP` | 托盘图标悬停提示 | 可用中文 |
| `BRAND_COPYRIGHT` | 版权声明 | 可用中文 |
| `BRAND_SERVICE_DISPLAY` | Windows 服务显示名 | 可用中文 |
| `BRAND_LICENSE_DESC` | 许可证文件描述 | 可用中文 |

#### 3.3 文件和系统标识

以下配置有字符限制，仅支持 ASCII：

| 配置项 | 说明 | 限制 |
|--------|------|------|
| `BRAND_DUMP_PREFIX` | 崩溃转储文件前缀 | 仅 ASCII |
| `BRAND_EXE_NAME` | 默认 EXE 文件名 | 仅 ASCII |
| `BRAND_LICENSE_PREFIX` | 许可证文件前缀 | 仅 ASCII |
| `BRAND_DB_NAME` | 数据库文件名 | 仅 ASCII |
| `BRAND_DATA_FOLDER` | 数据目录名 | 仅 ASCII |
| `BRAND_SERVICE_NAME` | Windows 服务名（无空格） | 仅 ASCII |
| `BRAND_REGISTRY_KEY` | 注册表键名（无空格） | 仅 ASCII |

**示例：**

```cpp
#define BRAND_DUMP_PREFIX       "MyRemote"
#define BRAND_EXE_NAME          "MyRemote.exe"
#define BRAND_LICENSE_PREFIX    "MyRemote"
#define BRAND_SERVICE_NAME      "MyRemoteService"
#define BRAND_REGISTRY_KEY      "MyRemote"
```

### 4. 隐藏菜单项

通过设置宏为 `1` 可以隐藏对应菜单项。

> **完整列表**：以下仅列出常用配置项，完整列表请查看 `UIBranding.h` 文件。

#### 4.1 主菜单项（常用）

```cpp
// 文件菜单
#define HIDE_MENU_SETTINGS              0   // 参数设置
#define HIDE_MENU_WALLET                0   // 钱包
#define HIDE_MENU_NETWORK               0   // 网络

// 工具菜单
#define HIDE_MENU_INPUT_PASSWORD        0   // 输入密码
#define HIDE_MENU_IMPORT_LICENSE        0   // 导入许可证
#define HIDE_MENU_GEN_AUTH              0   // 生成授权
#define HIDE_MENU_GEN_MASTER            0   // 生成Master
#define HIDE_MENU_LICENSE_MGR           0   // 许可证管理

// 参数菜单
#define HIDE_MENU_KBLOGGER              0   // 键盘记录
#define HIDE_MENU_LOGIN_NOTIFY          0   // 登录通知

// 扩展菜单
#define HIDE_MENU_FRPS_FOR_SUB          0   // 下级FRP
```

#### 4.2 使用示例

隐藏高级功能，创建简化版本：

```cpp
// 隐藏 ShellCode 相关功能
#define HIDE_MENU_SHELLCODE_C           1
#define HIDE_MENU_SHELLCODE_BIN         1
#define HIDE_MENU_SHELLCODE_LOAD_TEST   1
#define HIDE_MENU_SHELLCODE_OBFS        1
#define HIDE_MENU_SHELLCODE_AES_C       1
#define HIDE_MENU_SHELLCODE_AES_BIN     1

// 隐藏开发相关功能
#define HIDE_MENU_V2_PRIVATEKEY         1
#define HIDE_MENU_RCEDIT                1
```

### 5. 隐藏工具栏按钮（常用）

```cpp
#define HIDE_TOOLBAR_TERMINAL           0   // 终端管理
#define HIDE_TOOLBAR_PROCESS            0   // 进程管理
#define HIDE_TOOLBAR_DESKTOP            0   // 桌面管理
#define HIDE_TOOLBAR_FILE               0   // 文件管理
#define HIDE_TOOLBAR_AUDIO              0   // 语音管理
#define HIDE_TOOLBAR_VIDEO              0   // 视频管理
#define HIDE_TOOLBAR_SERVICE            0   // 服务管理
#define HIDE_TOOLBAR_REGISTER           0   // 注册表管理
#define HIDE_TOOLBAR_KEYBOARD           0   // 键盘记录
#define HIDE_TOOLBAR_SETTINGS           0   // 参数设置
#define HIDE_TOOLBAR_BUILD              0   // 生成服务端
```

### 6. 隐藏右键菜单项（常用）

```cpp
// 远程桌面选项
#define HIDE_CTX_VIRTUAL_DESKTOP        0   // 虚拟桌面
#define HIDE_CTX_GRAY_DESKTOP           0   // 灰度桌面
#define HIDE_CTX_REMOTE_DESKTOP         0   // 远程桌面
#define HIDE_CTX_H264_DESKTOP           0   // H264桌面

// 系统操作
#define HIDE_CTX_MACHINE_SHUTDOWN       0   // 关机
#define HIDE_CTX_MACHINE_REBOOT         0   // 重启
#define HIDE_CTX_MACHINE_LOGOUT         0   // 注销

// 执行命令
#define HIDE_CTX_EXECUTE_DOWNLOAD       0   // 下载执行
#define HIDE_CTX_EXECUTE_UPLOAD         0   // 上传执行
```

---

## 第三部分：视觉定制

### 7. 图标替换

#### 7.1 图标文件位置

图标资源位于 `server/2015Remote/res/` 目录：

| 文件 | 用途 | 尺寸要求 |
|------|------|---------|
| `2015Remote.ico` | 主程序图标 | 多尺寸 ICO |
| `tray_online.ico` | 托盘在线图标 | 16x16, 32x32 |
| `tray_offline.ico` | 托盘离线图标 | 16x16, 32x32 |

#### 7.2 图标格式要求

ICO 文件应包含多种尺寸：
- 16x16（小图标、托盘）
- 32x32（标准图标）
- 48x48（大图标）
- 256x256（高清图标）

**推荐工具：**
- IcoFX
- GIMP
- 在线 ICO 生成器

#### 7.3 替换步骤

1. 准备新图标文件
2. 备份原有图标
3. 将新图标复制到 `res/` 目录，保持文件名一致
4. 重新编译程序

### 8. 启动画面定制

启动画面的 Logo 文字由 `BRAND_SPLASH_NAME` 配置：

```cpp
#define BRAND_SPLASH_NAME       "YOURBRAND"
```

**建议：**
- 使用大写字母，视觉效果更好
- 保持简短（建议 8 个字符以内）
- 可以使用中文

---

## 第四部分：界面文字定制

### 9. 语言文件机制

YAMA 使用 INI 格式的语言文件实现多语言支持。

#### 9.1 语言文件位置

**源代码位置：**
```
server/2015Remote/lang/
├── en_US.ini      # 英文翻译
├── zh_TW.ini      # 繁体中文翻译
└── (其他语言)
```

**运行时位置：** 程序会从程序同目录的 `lang/` 文件夹读取语言文件。

**发布时：** 将 `lang/` 文件夹与程序放在同一目录。

#### 9.2 文件格式

```ini
; 注释行
简体中文原文=翻译文本
另一条原文=另一条翻译
```

**编码要求：** GB2312（不是 UTF-8！）

#### 9.3 添加翻译

由于语言文件必须使用 GB2312 编码，建议使用以下方法添加翻译：

**方法 A：使用支持 GB2312 编码的编辑器**

1. 使用 Notepad++、VS Code（安装编码插件）等编辑器
2. 打开语言文件，确认编码为 GB2312
3. 添加新的翻译条目
4. 保存时确保保持 GB2312 编码

**方法 B：使用 PowerShell 命令**

```powershell
# 追加单条翻译
$gb2312 = [System.Text.Encoding]::GetEncoding('GB2312')
$content = "新功能=New Feature`r`n"
[System.IO.File]::AppendAllText('lang\en_US.ini', $content, $gb2312)
```

> **注意**：直接用记事本编辑可能导致编码错误，请使用专业编辑器。

### 10. 创建新语言包

1. 复制 `en_US.ini` 作为模板
2. 重命名为新语言代码（如 `ja_JP.ini`）
3. 翻译所有条目
4. 保存为 GB2312 编码

---

## 第五部分：开发环境

### 11. 环境要求

| 组件 | 版本要求 |
|------|---------|
| Visual Studio | 2019 或 2022 |
| Windows SDK | 10.0.19041.0 或更高 |
| C++ 标准 | C++17 |
| 工具集 | v142 (MSVC v142) |
| MFC 库 | C++ MFC for v142 build tools |

### 12. 项目结构

```
SimpleRemoter/
├── server/2015Remote/    # 主控程序源码
│   ├── UIBranding.h      # 品牌配置
│   ├── 2015RemoteDlg.cpp # 主对话框
│   ├── SettingDlg.cpp    # 设置页面
│   ├── BuildDlg.cpp      # 生成对话框
│   ├── res/              # 资源文件
│   └── lang/             # 语言文件
├── client/               # 受管端源码
├── common/               # 公共代码
├── linux/                # Linux 客户端
└── Bin/                  # 编译输出
```

### 13. 关键文件说明

| 文件 | 功能 |
|------|------|
| `UIBranding.h` | 品牌和功能开关配置 |
| `2015RemoteDlg.cpp` | 主窗口、菜单、状态栏 |
| `SettingDlg.cpp` | 设置对话框 |
| `BuildDlg.cpp` | 生成受管程序对话框 |
| `CPasswordDlg.cpp` | 授权生成对话框 |
| `FrpsForSubDlg.cpp` | FRP 代理配置 |
| `ScreenSpyDlg.cpp` | 远程桌面窗口 |
| `FileManagerDlg.cpp` | 文件管理窗口 |
| `TerminalDlg.cpp` | 远程终端窗口 |

---

## 第六部分：编译与发布

### 14. 编译脚本

使用提供的编译脚本：

```powershell
# 完整编译（先编译依赖项，再编译主控）
.\build.ps1

# 仅编译主控程序（跳过依赖项，适合快速重编译）
.\build.ps1 -ServerOnly

# 发版模式（重编译所有 + UPX 压缩）
.\build.ps1 -Publish

# Debug 模式
.\build.ps1 -Config Debug

# 编译 32 位和 64 位
.\build.ps1 -Platform all

# 清理后重编译
.\build.ps1 -Clean
```

### 15. 编译输出

| 输出文件 | 位置 |
|---------|------|
| 64 位主控 | `Bin/Yama_x64.exe` |
| 32 位主控 | `Bin/Yama_x86.exe` |

### 16. 发布准备

#### 16.1 发布检查清单

- [ ] 修改 `UIBranding.h` 中的品牌信息
- [ ] 替换程序图标（如需要）
- [ ] 使用 Release 配置编译
- [ ] 使用 `-Publish` 进行 UPX 压缩
- [ ] 测试所有功能正常
- [ ] 测试授权导入功能
- [ ] 测试受管程序生成

#### 16.2 文件清单

发布时需要包含：

```
YourBrand/
├── YourBrand.exe     # 主程序（重命名）
└── lang/             # 语言文件（可选）
    ├── en_US.ini
    └── zh_TW.ini
```

---

## 第七部分：常见定制场景

### 17. 场景一：简单品牌替换

**需求：** 更换程序名称和图标

**步骤：**
1. 修改 `UIBranding.h` 中的品牌名称
2. 替换 `res/` 目录中的图标文件
3. 编译：`.\build.ps1 -Publish`
4. 重命名输出文件

### 18. 场景二：功能精简版

**需求：** 创建只保留基本功能的精简版

**步骤：**
1. 在 `UIBranding.h` 中隐藏高级功能：

```cpp
// 隐藏开发相关
#define HIDE_MENU_SHELLCODE_C           1
#define HIDE_MENU_SHELLCODE_BIN         1
#define HIDE_MENU_V2_PRIVATEKEY         1
#define HIDE_MENU_RCEDIT                1

// 隐藏高级功能
#define HIDE_TOOLBAR_AUDIO              1
#define HIDE_TOOLBAR_VIDEO              1
#define HIDE_TOOLBAR_REGISTER           1
#define HIDE_TOOLBAR_KEYBOARD           1
```

2. 编译发布

### 19. 场景三：多品牌版本

**需求：** 为不同客户生成不同品牌的版本

**方案：**
1. 创建多个 `UIBranding.h` 副本（如 `UIBranding_ClientA.h`）
2. 编译前复制对应配置文件覆盖 `UIBranding.h`
3. 编译并重命名输出
4. 或编写脚本自动化此过程

---

## 第八部分：最佳实践

### 20. 版本管理建议

#### 20.1 分支策略

```
main (或 master)        # 上游原版
├── custom/base         # 基础定制
├── custom/clientA      # 客户 A 定制
└── custom/clientB      # 客户 B 定制
```

#### 20.2 保持同步

定期从上游合并更新：

```bash
git fetch upstream
git merge upstream/main
# 解决冲突后提交
```

### 21. 定制文档

建议记录定制内容：

| 记录项 | 说明 |
|--------|------|
| 品牌配置 | 修改了哪些 `UIBranding.h` 配置 |
| 隐藏功能 | 隐藏了哪些菜单/按钮 |
| 图标变更 | 替换了哪些图标文件 |
| 源码修改 | 如有源码修改，记录位置和原因 |

### 22. 测试清单

每次定制后测试：

- [ ] 程序能正常启动
- [ ] 品牌信息显示正确
- [ ] 图标显示正确
- [ ] 授权导入功能正常
- [ ] 受管程序生成正常
- [ ] 远程桌面功能正常
- [ ] 文件管理功能正常
- [ ] 隐藏的功能确实不显示

---

## 附录

### A. 配置项速查表

| 配置项 | 文件 | 说明 |
|--------|------|------|
| 程序名称 | `UIBranding.h` | `BRAND_APP_NAME` |
| 版本号 | `UIBranding.h` | `BRAND_VERSION` |
| 启动 Logo | `UIBranding.h` | `BRAND_SPLASH_NAME` |
| 托盘提示 | `UIBranding.h` | `BRAND_TRAY_TIP` |
| 版权信息 | `UIBranding.h` | `BRAND_COPYRIGHT` |
| 隐藏菜单 | `UIBranding.h` | `HIDE_MENU_*` |
| 隐藏工具栏 | `UIBranding.h` | `HIDE_TOOLBAR_*` |
| 隐藏右键菜单 | `UIBranding.h` | `HIDE_CTX_*` |
| 界面翻译 | `lang/*.ini` | 键值对 |

### B. 资源文件清单

| 资源 | 位置 | 格式 |
|------|------|------|
| 主程序图标 | `res/2015Remote.ico` | ICO |
| 托盘图标 | `res/tray_*.ico` | ICO |
| 工具栏图标 | `res/toolbar.bmp` | BMP |

### C. 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 编译报错 | VS 版本/工具集 | 确认使用 VS2019+ 和 v142 工具集 |
| 中文乱码 | 文件编码错误 | UIBranding.h 需 UTF-8 with BOM |
| 图标不显示 | 格式不正确 | 确认 ICO 包含多尺寸 |
| 翻译不生效 | 编码错误 | 语言文件需 GB2312 编码 |
| 菜单仍显示 | 未重编译 | 修改 UIBranding.h 后需重编译 |

### D. 注意事项

**请勿修改以下配置**（会导致功能异常）：

```cpp
// 修改会导致所有已发放许可证失效
#define BRAND_LICENSE_MAGIC     "YAMA"

// 修改会导致单实例检测失败
#define BRAND_EVENT_PREFIX      "YAMA"

// 修改会导致超管密码配置失效
#define BRAND_ENV_VAR           "YAMA_PWD"
```

---

## 技术支持

| 渠道 | 联系方式 |
|------|---------|
| QQ | 962914132 |
| Telegram | [@doge_grandfather](https://t.me/doge_grandfather) |

---

## 相关文档

- [快速部署指南](QuickStart.md) - 基础部署
- [多级网络搭建指南](NetworkSetup.md) - 网络架构
- [日常使用手册](UserManual.md) - 功能使用
- [代理商运营手册](AgentManual.md) - 授权管理