wangshiyao/thrift-related
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

使用文档更新

Browse Source
This commit is contained in:
zhang hongbo 2026-01-14 10:37:44 +08:00
parent ad4bb00349
commit cca235bb9a
6 changed files with 82 additions and 1028 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
PythonWorkSpace/IntegratedTool/PROJECT.md
View File

@ -1,188 +0,0 @@
# Thrift 完整流程工具 - 项目结构
## 文件说明
```
IntegratedTool/
├── integrated_pipeline.py # 主程序
├── pipeline_config.json # 配置文件（自动生成）
├── requirements.txt # Python 依赖
├── README.md # 使用说明
├── cfg_txt_example.json # 配置示例
├── 启动工具.bat # 快速启动
├── 安装依赖.bat # 安装依赖包
├── 打包集成工具.bat # 打包为 EXE
└── gen-py/ # 临时目录（自动清理）
```
## 快速开始
### 1. 安装依赖
```bash
安装依赖.bat
```
或手动安装：
```bash
pip install openpyxl thrift pyinstaller
```
### 2. 启动工具
```bash
启动工具.bat
```
或直接运行：
```bash
python integrated_pipeline.py
```
### 3. 配置路径
首次运行需要配置以下路径：
- cfg_txt.json 配置文件
- Thrift 编译器 (thrift.exe)
- Thrift 文件路径（生成的 .thrift 存放位置）
- C# 输出路径（临时）
- Bytes 输出路径（临时）
- Config 路径（Excel 文件夹）
- Unity C# 路径（最终目标）
- Unity Bytes 路径（最终目标）
### 4. 执行流程
点击"开始执行完整流程"按钮
## 打包为 EXE
### 自动打包
```bash
打包集成工具.bat
```
### 手动打包
```bash
pyinstaller --onefile --noconsole --name=ThriftPipeline ^
--hidden-import=openpyxl ^
--hidden-import=thrift ^
--hidden-import=thrift.protocol.TBinaryProtocol ^
--hidden-import=thrift.transport.TTransport ^
integrated_pipeline.py
```
打包后的 EXE 位于：`../../IntegratedToolEXE/ThriftPipeline.exe`
## 执行流程详解
### 阶段1：生成 Thrift 文件
- 读取 cfg_txt.json 配置
- 遍历每个 Excel 文件
- 解析表头和类型
- 生成对应的 .thrift 文件
### 阶段2：编译到 C#
- 调用 thrift.exe 编译器
- 使用参数：`-strict -v -r --gen netstd:unity,serial,async_postfix`
- 生成 Unity C# 代码
### 阶段3：生成 Bytes 文件
- 编译 Thrift 到 Python（gen-py）
- 读取 Excel 数据
- 使用 TBinaryProtocol 序列化
- 生成 .bytes 二进制文件
### 阶段4：清理 Extensions
- 删除多余的 .Extensions.cs 文件
- 保留 AllConfigs.Extensions.cs
### 阶段5：复制 C# 到 Unity
- 将所有 .cs 文件复制到 Unity C# 目录
- 覆盖旧文件
### 阶段6：复制 Bytes 到 Unity
- 将所有 .bytes 文件复制到 Unity Bytes 目录
### 阶段7：清理临时文件
- 删除 gen-py 目录
## 配置文件格式
### cfg_txt.json
```json
{
"file_list": [
{
"in_file": "Music.xlsx", // Excel 文件名
"out_file": "Music.txt", // 输出文件名（决定结构名）
"sheet_name": "Music" // Sheet 名称
}
]
}
```
### pipeline_config.json（自动生成）
```json
{
"cfg_json_path": "path/to/cfg_txt.json",
"compiler_path": "path/to/thrift.exe",
"thrift_dir": "path/to/thrift-files",
"csharp_output_dir": "path/to/csharp-output",
"bytes_output_dir": "path/to/bytes-output",
"config_dir": "path/to/excel-files",
"unity_csharp_dir": "path/to/unity/csharp",
"unity_bytes_dir": "path/to/unity/bytes"
}
```
## Excel 格式要求
```
| Id | AssetName | ... | <- 第1行：字段名
| int | string | ... | <- 第2行：类型
| 1 | music_01 | ... | <- 第3行起：数据
| 2 | music_02 | ... |
```
## 类型映射
- int → i32
- long → i64
- float/double → double
- string → string
- bool → bool
## 报告说明
每次执行完成后生成报告文件：
- 文件名：`report_YYYYMMDD_HHMMSS.txt`
- 位置：工具所在目录
- 内容：每个步骤的状态、时间、详细数据
## 常见问题
### Q: gen-py 目录会一直存在吗？
A: 不会，每次执行完自动清理。下次运行重新生成。
### Q: 为什么需要临时的 C# 和 Bytes 输出目录？
A: 方便检查生成结果，确认无误后再复制到 Unity。
### Q: AllConfigs.Extensions.cs 为什么要保留？
A: 因为 AllConfigs 引用了其他配置，需要这个扩展类。
### Q: 能否跳过某些步骤？
A: 目前不支持，建议完整执行。如需单独步骤，使用其他专用工具。
### Q: 报告文件能删除吗？
A: 可以，不影响工具运行。建议保留最近几次的报告便于排查问题。
## 技术栈
- **GUI**: tkinter
- **Excel**: openpyxl
- **Thrift**: Apache Thrift
- **序列化**: TBinaryProtocol
- **打包**: PyInstaller
## 开发者信息
- 版本：v1.0
- 创建日期：2026-01-11
- Python 版本：3.7+

134
PythonWorkSpace/IntegratedTool/README.md
View File

@ -1,134 +0,0 @@
# Thrift 完整流程工具使用说明
## 功能概述
这是一个集成所有步骤的完整工具，从 Excel 配置到 Unity 部署一键完成。
## 执行流程
### 步骤1：生成 Thrift 文件
- 根据 `cfg_txt.json` 配置读取 Excel 文件
- 自动解析 Excel 表头和类型
- 生成对应的 `.thrift` 文件
### 步骤2：编译到 C#
- 使用 `thrift.exe` 编译器
- 生成 Unity 可用的 C# 代码
- 参数：`-strict -v -r --gen netstd:unity,serial,async_postfix`
### 步骤3：生成 Bytes 文件
- 临时生成 `gen-py` Python 代码
- 使用 Thrift Binary Protocol 序列化
- 生成 `.bytes` 二进制文件
### 步骤4：清理 Extensions
- 删除多余的 `.Extensions.cs` 文件
- **只保留** `AllConfigs.Extensions.cs`
### 步骤5：复制 C# 到 Unity
- 复制所有 `.cs` 文件到 Unity C# 目录
- 覆盖原有文件
### 步骤6：复制 Bytes 到 Unity
- 复制所有 `.bytes` 文件到 Unity Bytes 目录
- 使用复制而非移动，方便检查
### 步骤7：清理临时文件
- 删除 `gen-py` 目录
## 配置说明
所有路径配置会保存在 `pipeline_config.json`，下次打开自动加载。
### 必需配置
1. **cfg_txt.json** - 配置文件，包含 Excel 和 Sheet 映射
2. **Thrift 编译器** - `thrift.exe` 路径
3. **Thrift 文件路径** - 生成的 `.thrift` 文件存放位置
4. **C# 输出路径** - 编译生成的 C# 代码临时存放
5. **Bytes 输出路径** - 生成的 `.bytes` 文件临时存放
6. **Config 路径** - Excel 文件 (`.xlsx`) 所在目录
7. **Unity C# 路径** - Unity 项目中的 C# 代码目标目录
8. **Unity Bytes 路径** - Unity 项目中的 Bytes 文件目标目录
## cfg_txt.json 格式
```json
{
"file_list": [
{
"in_file": "Music.xlsx",
"out_file": "Music.txt",
"sheet_name": "Music"
}
]
}
```
## 执行报告
每次执行完成后会生成详细报告：
- 文件名：`report_YYYYMMDD_HHMMSS.txt`
- 包含每个步骤的状态、时间、详细数据
- 方便排查问题
## 使用方法
### 开发模式
```bash
python integrated_pipeline.py
```
### 打包为 EXE
```bash
打包集成工具.bat
```
打包后的 EXE 位于：`../../IntegratedToolEXE/ThriftPipeline.exe`
## 注意事项
1. **首次运行** - 需要正确配置所有路径
2. **Excel 格式** - 第1行字段名，第2行类型，第3行开始数据
3. **类型映射** - int→i32, long→i64, float/double→double, string→string
4. **AllConfigs** - 因为包含其他配置的引用，只保留其 Extensions 文件
5. **gen-py 清理** - 每次运行都会重新生成，完成后自动清理
6. **文件覆盖** - Unity 目录中的文件会被新文件覆盖
## 故障排查
### 问题：找不到 thrift 模块
- 确保安装了 `thrift` Python 包：`pip install thrift`
### 问题：编译失败
- 检查 `thrift.exe` 路径是否正确
- 查看日志中的错误信息
### 问题：Bytes 生成失败
- 检查 Excel 文件格式是否正确
- 确保字段名与 Thrift 定义匹配
### 问题：报告中显示某步骤失败
- 查看详细日志找到具体错误
- 根据错误信息修复对应问题
## 技术细节
### Binary Protocol 序列化
- 使用 Thrift 的 `TBinaryProtocol`
- 紧凑的二进制格式，比 JSON 小很多
- Unity 使用相同协议反序列化
### 为什么需要 gen-py
- Thrift 序列化需要对应语言的类定义
- Python 需要 `gen-py`，C# 需要 `.cs` 文件
- 这是 Thrift 框架的设计，无法绕过
### 文件命名规则
- Thrift 文件：`{StructName}.thrift`
- C# 文件：`{StructName}.cs` 和 `{StructName}.Extensions.cs`
- Bytes 文件：`{StructName}.bytes`
## 版本历史
- v1.0 - 初始版本，集成完整流程

82
PythonWorkSpace/IntegratedTool/使用文档.md Normal file
View File

@ -0,0 +1,82 @@
# IntegratedTool 使用文档
## 重要提示
**选择完路径后，下次打开工具会默认选择上次选择的位置。**
## 路径配置说明
请按照以下说明配置各个路径：
### 1. cfg_txt.json 路径
选择 Docs 项目中的配置文件：
```
Docs/tool/cfg/cfg_txt.json
```
### 2. Thrift 编译器路径
选择 thrift-related 项目中的编译器：
```
thrift-related/compiler/exe/thrift.exe
```
### 3. Thrift 文件路径
选择 thrift 源文件目录：
```
thrift-related/thrift-files/meowment
```
### 4. C# 输出路径
选择编译后的 C# 代码输出目录：
```
thrift-related/compiled_output/csharp
```
### 5. Bytes 输出路径
选择二进制文件输出目录：
```
thrift-related/binary_output
```
### 6. Config 路径
选择配置文件目录：
```
Docs/config
```
### 7. Unity C# 路径
选择 Unity 主项目中的 C# 代码目录：
```
主项目/Assets/Scripts/thrift/gen-netstd
```
### 8. Unity Bytes 路径
选择 Unity 主项目中的资源数据目录：
```
主项目/Assets/Resources/ConfigData
```
### 9. DR 输出路径
选择 Unity 主项目中的 DR 生成代码目录：
```
主项目/Assets/GameMain/Scripts/DR_Generated
```
## 执行流程
配置完所有路径后，点击 **"开始执行完整流程"** 按钮。
工具将自动完成以下步骤：
1. 编译 Thrift 文件
2. 生成 C# 代码
3. 生成二进制配置文件
4. 复制文件到 Unity 项目
5. 生成 DR 代码
## 故障排查
如果执行过程中出现问题，请查看 **错误日志** 获取详细的错误信息。
---
**注意：** 确保所有路径都存在且可访问，否则流程可能会失败。

210
PythonWorkSpace/IntegratedTool/数量差异说明.md
View File

@ -1,210 +0,0 @@
# 📊 文件数量差异说明
## 执行流程中的数量关系
### 步骤1: 生成 Thrift 文件
```
配置文件数量: 84 个 (来自 cfg_txt.json)
+ AllConfigs: 1 个 (自动生成)
= 总计: 85 个 thrift 文件
```
### 步骤2: 编译到 C#
```
输入: 85 个 thrift 文件
输出: 86+ 个 C# 文件
原因:
- 每个 thrift 文件生成 1 个主 .cs 文件
- 每个 thrift 文件生成 1 个 .Extensions.cs 文件
- AllConfigs 特殊，可能生成额外的 Extensions
实际位置:
E:\WorkSpace\thrift-related\compiled_output\csharp\Byway\Thrift\Data\
```
**为什么是 Byway\Thrift\Data?**
因为 thrift 文件头部定义了：
```thrift
namespace netstd Byway.Thrift.Data
```
### 步骤3: 生成 Bytes 文件
```
输入: 84 个配置 (cfg_txt.json)
输出: 83 或 84 个 bytes 文件
可能原因:
1. 某个配置的 Excel 读取失败
2. 某个配置的数据为空
3. 某个配置的序列化失败
注意: AllConfigs 不生成 bytes！
```
### 步骤4: 清理 Extensions
```
目标目录: csharp\Byway\Thrift\Data\
操作: 删除所有 .Extensions.cs，但保留 AllConfigs.Extensions.cs
预期删除: 84 个 (84个配置的 Extensions)
保留: 1 个 (AllConfigs.Extensions.cs)
```
**之前为什么是 0?**
因为代码在错误的目录查找（csharp/ 而不是 csharp/Byway/Thrift/Data/）
### 步骤5: 复制 C# 到 Unity
```
源目录: csharp\Byway\Thrift\Data\
复制: 所有 .cs 文件
预期数量:
- 85 个主文件 (84 + AllConfigs)
- 1 个 Extensions (AllConfigs.Extensions.cs)
= 86 个文件
```
**之前为什么是 0?**
同样的路径问题
### 步骤6: 复制 Bytes 到 Unity
```
源目录: binary_output\
复制: 所有 .bytes 文件
数量: 83 或 84 个 (取决于步骤3的成功率)
注意: 这里会复制 AllConfigs.bytes（如果存在）
```
## 🔍 数量差异原因分析
### 正常情况
```
步骤1: 85 个 thrift (84 配置 + 1 AllConfigs)
步骤2: 86 个 C# (85 主文件 + 1 AllConfigs.Extensions)
步骤3: 84 个 bytes (只有配置，不含 AllConfigs)
步骤4: 删除 84 个 Extensions
步骤5: 复制 86 个 C#
步骤6: 复制 84 个 bytes
```
### 步骤3少1个的可能原因
#### 1. 某个配置失败
查看报告中的 `failed_files` 列表
#### 2. AllConfigs.bytes 被意外生成
AllConfigs 不在 cfg_txt.json 中，不应该生成 bytes
#### 3. Excel 文件问题
- 文件不存在
- Sheet 名称错误
- 数据格式错误
- 数据为空
## 📋 验证清单
### 检查步骤3的详细日志
```
【步骤3】生成 Bytes 文件
✓ Music.bytes (1234 bytes)
✓ Sound.bytes (5678 bytes)
...
✗ XXX: 错误信息 <-- 找这个！
```
### 检查 bytes 输出目录
```bash
dir E:\WorkSpace\thrift-related\binary_output\*.bytes /b
```
计数是否匹配？
### 检查 cfg_txt.json
```json
{
"file_list": [
// 数一数有多少个配置
]
}
```
应该是 84 个
### 对比文件列表
```bash
# Thrift 文件（应该85个）
dir E:\WorkSpace\thrift-related\thrift-files\*.thrift /b | find /c /v ""
# C# 文件（应该86个）
dir E:\WorkSpace\thrift-related\compiled_output\csharp\Byway\Thrift\Data\*.cs /b | find /c /v ""
# Bytes 文件（应该84个）
dir E:\WorkSpace\thrift-related\binary_output\*.bytes /b | find /c /v ""
```
## 🎯 正确的报告示例
```
====================================================================================================
开始时间: 2026-01-11 14:29:14
结束时间: 2026-01-11 14:29:27
1. [✓] 生成Thrift文件 - 2026-01-11 14:29:17
total: 85
config_files: 84
allconfigs: 1
files: 前20个配置名称列表
2. [✓] 编译到C# - 2026-01-11 14:29:22
success: 85
failed: 0
total: 85
cs_files_count: 86
3. [✓] 生成Bytes文件 - 2026-01-11 14:29:27
success: 84
failed: 0
total: 84
success_files: 前20个成功文件
4. [✓] 清理Extensions - 2026-01-11 14:29:27
deleted: 84
files: 删除的文件列表
5. [✓] 复制C#到Unity - 2026-01-11 14:29:27
count: 86
sample_files: 前10个文件
6. [✓] 复制Bytes到Unity - 2026-01-11 14:29:27
count: 84
sample_files: 前10个文件
```
## 💡 常见问题
### Q: 为什么 C# 文件比 thrift 多1个？
A: AllConfigs 会生成额外的 .Extensions.cs 文件
### Q: 为什么不生成 AllConfigs.bytes？
A: AllConfigs 不在 cfg_txt.json 中，而且它是一个容器，不需要单独的 bytes
### Q: bytes 少1个怎么办？
A: 查看详细日志，找到失败的配置，检查：
- Excel 文件是否存在
- Sheet 名称是否正确
- 数据是否有效
- 类型转换是否正确
### Q: 如何找到缺失的文件？
A: 对比 thrift 文件列表和 bytes 文件列表：
```python
thrift_files = set(os.listdir(thrift_dir))
bytes_files = set(os.listdir(bytes_dir))
thrift_names = {f.replace('.thrift', '') for f in thrift_files if f != 'AllConfigs.thrift'}
bytes_names = {f.replace('.bytes', '') for f in bytes_files}
missing = thrift_names - bytes_names
print(f"缺失的: {missing}")
```

240
PythonWorkSpace/IntegratedTool/部署完成.md
View File

@ -1,240 +0,0 @@
# 🎉 Thrift 完整流程工具 - 部署完成
## ✅ 已创建的文件
### 核心程序
- ✅ `integrated_pipeline.py` - 主程序（666行）
- ✅ `pipeline_config.json` - 配置文件（自动生成）
### 配置和示例
- ✅ `cfg_txt_example.json` - 配置文件示例
- ✅ `requirements.txt` - Python 依赖列表
### 文档
- ✅ `README.md` - 用户使用说明
- ✅ `PROJECT.md` - 项目详细文档
### 脚本
- ✅ `启动工具.bat` - 快速启动
- ✅ `安装依赖.bat` - 安装 Python 依赖
- ✅ `打包集成工具.bat` - 打包为 EXE
### 构建配置
- ✅ `build_integrated_tool.json` - 打包配置
## 🚀 快速使用
### 第一次使用
1. **安装依赖**
```bash
双击运行：安装依赖.bat
```
2. **启动工具**
```bash
双击运行：启动工具.bat
```
3. **配置路径**（首次需要）
- cfg_txt.json 配置文件
- Thrift 编译器
- Thrift 文件路径
- C# 输出路径
- Bytes 输出路径
- Config 路径（Excel）
- Unity C# 路径
- Unity Bytes 路径
4. **执行流程**
点击"🚀 开始执行完整流程"
### 打包为 EXE
```bash
双击运行：打包集成工具.bat
```
输出位置：`../../IntegratedToolEXE/ThriftPipeline.exe`
## 📋 完整流程说明
```
[步骤1] 生成 Thrift 文件
├─ 读取 cfg_txt.json
├─ 遍历 Excel 文件
├─ 解析表头和类型
└─ 生成 .thrift 文件
[步骤2] 编译到 C#
├─ 调用 thrift.exe
├─ 参数：-strict -v -r --gen netstd:unity,serial,async_postfix
└─ 生成 C# 代码
[步骤3] 生成 Bytes 文件
├─ 编译 Thrift 到 Python（gen-py）
├─ 读取 Excel 数据
├─ TBinaryProtocol 序列化
└─ 生成 .bytes 文件
[步骤4] 清理 Extensions
├─ 删除多余的 .Extensions.cs
└─ 保留 AllConfigs.Extensions.cs
[步骤5] 复制 C# 到 Unity
└─ 复制所有 .cs 文件（覆盖）
[步骤6] 复制 Bytes 到 Unity
└─ 复制所有 .bytes 文件
[步骤7] 清理临时文件
└─ 删除 gen-py 目录
```
## 📊 执行报告
每次执行完成自动生成报告：
- 文件名：`report_YYYYMMDD_HHMMSS.txt`
- 包含每个步骤的状态、时间、详细数据
- 方便排查问题
## 🔧 配置文件说明
### cfg_txt.json（必需）
```json
{
"file_list": [
{
"in_file": "Music.xlsx",
"out_file": "Music.txt",
"sheet_name": "Music"
}
]
}
```
### Excel 格式要求
```
行1: 字段名 | Id | AssetName | ...
行2: 类型 | int | string | ...
行3+: 数据 | 1 | music_01 | ...
```
## 💡 核心功能
### ✅ 自动化
- 一键完成所有步骤
- 自动清理临时文件
- 自动生成详细报告
### ✅ 智能化
- 路径记忆功能
- 自动类型推断
- 错误详细提示
### ✅ 安全性
- 使用复制而非移动
- 保留中间产物便于检查
- 详细日志记录
## 🎯 关键特性
1. **完全集成** - 从 Excel 到 Unity 一站式
2. **自动清理** - gen-py 用完即删
3. **智能清理** - 只保留 AllConfigs.Extensions.cs
4. **详细报告** - 每步状态和数据清晰可查
5. **路径记忆** - 配置一次，永久使用
6. **可打包** - 可生成独立 EXE
## 📦 依赖包
```
openpyxl>=3.0.0 # Excel 读写
thrift>=0.16.0 # Thrift 序列化
pyinstaller>=5.0.0 # 打包工具
```
## ⚠️ 重要提示
1. **首次运行** - 必须配置所有路径
2. **Excel 格式** - 严格按照格式（行1字段/行2类型/行3数据）
3. **AllConfigs** - 只保留其 Extensions 文件，其他配置的 Extensions 都删除
4. **gen-py** - 每次运行都重新生成，完成后自动清理
5. **覆盖文件** - Unity 目录的文件会被新文件覆盖
## 🐛 故障排查
### 找不到模块
```bash
pip install openpyxl thrift
```
### 编译失败
- 检查 thrift.exe 路径
- 查看日志错误信息
### Bytes 生成失败
- 检查 Excel 格式
- 确保字段名匹配
### 某步骤失败
- 查看报告文件
- 根据错误信息修复
## 📂 目录结构
```
IntegratedTool/ # 工具源码目录
├── integrated_pipeline.py # 主程序
├── 启动工具.bat # 快速启动
├── 安装依赖.bat # 安装依赖
├── 打包集成工具.bat # 打包 EXE
└── README.md # 说明文档
IntegratedToolEXE/ # EXE 输出目录（打包后生成）
└── ThriftPipeline.exe # 独立可执行文件
```
## 🎓 技术原理
### Thrift Binary Protocol
- 使用 `TBinaryProtocol` 序列化
- 紧凑的二进制格式
- Unity 用相同协议反序列化
### 为什么需要 gen-py
- Thrift 序列化需要类定义
- Python 需要 gen-py，C# 需要 .cs
- 这是 Thrift 框架的设计
### 类型映射
- int → i32
- long → i64
- float/double → double
- string → string
- bool → bool
## ✨ 相比单独工具的优势
| 功能 | 单独工具 | 集成工具 |
|-----|---------|---------|
| 生成 Thrift | ❌ 手动 | ✅ 自动 |
| 编译 C# | ✅ 支持 | ✅ 自动 |
| 生成 Bytes | ✅ 支持 | ✅ 自动 |
| 清理 Extensions | ❌ 手动 | ✅ 自动 |
| 部署到 Unity | ❌ 手动 | ✅ 自动 |
| 清理临时文件 | ❌ 手动 | ✅ 自动 |
| 生成报告 | ❌ 无 | ✅ 详细 |
| 一键执行 | ❌ 多步 | ✅ 一键 |
## 🎊 总结
此工具实现了：
✅ **7个步骤全自动化**
✅ **路径配置永久记忆**
✅ **详细执行报告**
✅ **智能错误处理**
✅ **可打包为独立EXE**
✅ **完整的文档说明**
让 Thrift 配置管理变得简单高效！🚀

256
PythonWorkSpace/IntegratedTool/问题排查.md
View File

@ -1,256 +0,0 @@
# 🔧 问题排查清单
## ✅ 已修复的问题
### 1. UI 变量命名不一致
**问题**: `AttributeError: 'IntegratedPipeline' object has no attribute 'xxx_var'`
**原因**: UI 变量使用了错误的命名（`csharp_output_var` 应该是 `csharp_output_dir_var`）
**修复**: 统一所有变量命名为 `{attr_name}_var` 格式
✅ 已修复变量：
- `csharp_output_dir_var`
- `bytes_output_dir_var`
- `unity_csharp_dir_var`
- `unity_bytes_dir_var`
### 2. 类型转换问题
**问题**: Excel 数据类型可能导致序列化失败
**修复**: 在 step3 中添加了完整的类型转换逻辑
- int/i32/i16/i8 → int()
- long/i64 → int()
- float/double → float()
- bool → bool()
- string → str()
### 3. 错误处理增强
**修复**:
- 日志输出添加 try-catch
- 验证路径时显示所有错误而非单个
- Excel 读取添加更多异常处理
## 🔍 可能的问题和解决方案
### 问题1: 找不到 thrift 模块
```
ModuleNotFoundError: No module named 'thrift'
```
**解决方案**:
```bash
pip install thrift
```
### 问题2: 找不到 openpyxl 模块
```
ModuleNotFoundError: No module named 'openpyxl'
```
**解决方案**:
```bash
pip install openpyxl
```
或运行：`安装依赖.bat`
### 问题3: tkinter 不可用
```
ModuleNotFoundError: No module named 'tkinter'
```
**解决方案**:
- Windows: tkinter 通常已包含在 Python 安装中
- 如果缺失，重新安装 Python 并勾选 "tcl/tk and IDLE"
### 问题4: Excel 文件读取失败
```
✗ Excel 不存在: xxx.xlsx
```
**检查**:
1. Config 路径（xlsx）是否正确
2. cfg_txt.json 中的 `in_file` 名称是否正确
3. Excel 文件是否存在于 Config 目录
### 问题5: Thrift 编译失败
```
✗ 编译失败: xxx.thrift
```
**检查**:
1. thrift.exe 路径是否正确
2. 生成的 .thrift 文件语法是否正确
3. 查看详细日志中的错误信息
### 问题6: Bytes 生成失败
```
✗ xxx: 错误信息
```
**常见原因**:
1. Excel 字段名与 Thrift 定义不匹配
2. 数据类型不匹配
3. gen-py 生成失败
**排查步骤**:
1. 检查 Excel 第一行字段名是否正确
2. 检查 Excel 第二行类型定义
3. 查看 gen-py 目录是否正确生成
4. 检查详细错误日志
### 问题7: AllConfigs.Extensions.cs 被删除
```
找不到 AllConfigs.Extensions.cs
```
**原因**: 步骤4 会删除多余的 Extensions 文件
**验证**: 确保 AllConfigs.Extensions.cs 被保留，其他 Extensions 被删除
### 问题8: Unity 目录权限问题
```
PermissionError: [Errno 13] Permission denied
```
**解决方案**:
1. 关闭 Unity 编辑器
2. 检查文件是否被占用
3. 以管理员权限运行工具
### 问题9: 路径包含中文或特殊字符
**症状**: 各种奇怪的错误
**解决方案**: 尽量使用英文路径，避免空格和特殊字符
### 问题10: cfg_txt.json 格式错误
```
JSONDecodeError: Expecting value
```
**检查**:
1. JSON 格式是否正确
2. 是否有多余的逗号
3. 引号是否配对
**正确格式**:
```json
{
"file_list": [
{
"in_file": "Music.xlsx",
"out_file": "Music.txt",
"sheet_name": "Music"
}
]
}
```
## 📋 使用前检查清单
### 必需文件/路径
- [ ] cfg_txt.json 配置文件存在
- [ ] thrift.exe 编译器存在
- [ ] Excel 文件存在于 Config 目录
- [ ] 所有目录路径已配置
### 必需依赖
- [ ] Python 3.7+ 已安装
- [ ] openpyxl 已安装
- [ ] thrift 已安装
- [ ] tkinter 可用
### Excel 格式检查
- [ ] 第1行：字段名
- [ ] 第2行：类型（int/string/double等）
- [ ] 第3行起：数据
- [ ] 字段名与预期一致
### cfg_txt.json 检查
- [ ] JSON 格式正确
- [ ] in_file 文件存在
- [ ] sheet_name 正确
## 🛠️ 快速测试
运行测试脚本：
```bash
测试工具.bat
```
这会检查：
1. Python 版本
2. 所有依赖包
3. 自动启动工具
## 📞 调试技巧
### 查看详细日志
工具窗口底部有完整的执行日志，包含：
- 每个步骤的状态
- 处理的文件数量
- 详细错误信息
### 查看报告文件
每次执行后生成 `report_YYYYMMDD_HHMMSS.txt`，包含：
- 所有步骤的时间戳
- 成功/失败状态
- 详细统计数据
### 手动验证
1. 检查 thrift 文件生成是否正确
2. 检查 C# 文件是否生成
3. 检查 bytes 文件大小是否合理
4. 检查 Unity 目录文件是否更新
## ⚡ 性能优化
### 大量文件处理
- 预计时间：1个配置约 1-2 秒
- 100个配置约 2-3 分钟
### 如果太慢
1. 检查网络连接（如有）
2. 关闭防病毒软件实时扫描
3. 使用 SSD 存储
## 🎯 最佳实践
1. **首次运行**: 先用少量配置测试
2. **备份**: 执行前备份 Unity 项目
3. **验证**: 执行后检查报告文件
4. **清理**: 定期删除旧的报告文件
5. **更新**: 保持 Python 依赖包最新
## 📝 日志说明
### 正常日志
```
【步骤1】生成 Thrift 文件
✓ 生成: Music.thrift
✓ 生成: AllConfigs.thrift
生成完成: 2 个 thrift 文件
```
### 错误日志
```
【步骤1】生成 Thrift 文件
✗ 失败 Music: Excel 不存在
✗ 步骤1失败: xxx
```
## 🔄 重试策略
如果某步骤失败：
1. 查看日志找到具体错误
2. 修复问题（如路径、文件等）
3. 可以重新运行完整流程
4. gen-py 会自动清理和重新生成
## ✨ 成功标志
执行成功后会看到：
- ✅ 所有步骤标记为成功
- ✅ 生成报告文件
- ✅ Unity 目录更新
- ✅ 弹出"完成"消息框