| name | bat-encoding-standards |
| description | BAT 脚本标准化生成技能。AI 在编写、修改、生成 .bat 文件前必须主动调用本 Skill 加载规范。确保 UTF-8 编码、首行切 65001、子 bat 禁止重复 chcp、必须模拟双击自测。 |
BAT 脚本标准化生成技能
触发条件（关键字的强制响应）
关键字自检列表
AI 在收到用户消息或任务后，必须首先检查消息中是否包含以下任一关键字：
| 关键字 | 触发动作 |
|---|
.bat | 立即调用本 Skill |
bat 且上下文涉及批处理 | 立即调用本 Skill |
批处理 | 立即调用本 Skill |
脚本 且上下文涉及 Windows 命令 | 立即调用本 Skill |
cmd 且上下文涉及文件执行 | 立即调用本 Skill |
强制调用规则
- 命中任意关键字 → 必须先调用本 Skill，再回答或动手
- 没有例外——即使你觉得"这只是个小改动"、"只是改一行"、"先回答再处理"，也必须先调 Skill
- 反向触发器：即使你的思考过程中自己生成了
.bat 操作方案（而非用户提出），也要立即触发
- 本技能不会自动启用——依赖上述关键字检查机制和 auto-experience-trigger 的同源场景识别
核心背景（必须理解）
存在开发环境与用户本地环境编码差异，这是所有 BAT 编码 Bug 的根源：
| 环境 | 终端编码 | 说明 |
|---|
| Trae IDE 内嵌终端 | UTF-8（65001） | AI 开发测试的环境 |
| 用户本地 CMD（双击） | GBK（936） | 用户实际运行的环境 |
| SearchReplace 工具写入 | UTF-8 | 文件保存方式固定 |
关键推论：
- AI 在 IDE 终端测试通过 ≠ 用户双击运行正常
- AI 无法在 IDE 中复现用户本地乱码问题
- 必须以「用户双击运行」为最终验证标准
核心规则
0. 最高优先级：禁止中文（强制执行）
.bat 文件中禁止出现任何中文字符（包括注释、echo 输出、title、提示信息）- 所有文本使用纯 ASCII/英文
- 原因：
- Write 工具保存文件使用 LF 换行（非 CRLF），CMD 解析含中文的 LF 换行 bat 文件时必乱码
- Write + Python 生成器（CRLF）可以解决，但流程复杂易出错
- 纯英文 = 编码问题归零，UTF-8 和 GBK 下英文字符编码一致
- 任何情况下不得在
.bat 文件中写入中文，包括：
echo 中文title 中文set /p "=中文"REM 中文注释- 所有位置的文字
1. 固定编码：UTF-8
- 所有
.bat 文件保持 UTF-8 编码（无 BOM）
- 禁止转换为 GBK/ANSI 格式（避免 SearchReplace 工具重新保存为 UTF-8 导致编码错乱）
- 文件中的中文直接书写（UTF-8 原生支持中文，IDE 显示正常）
2. 入口文件首行编码切换（强制）
- 入口批处理文件（用户双击执行的 .bat）首行必须固定如下：
@echo off
chcp 65001 >nul 2>&1
- 禁止简化省略
2>&1，禁止写成 >nul 不带错误重定向
- 必须放在第二行（
@echo off 之后、任何其他命令之前）
3. 子 bat 禁止重复 chcp
- 被入口文件
call 或 start 调用的子 bat 文件，禁止包含 chcp 命令
- 编码切换只执行一次，子 bat 继承入口的 UTF-8 环境
- 违反此规则会导致编码回退冲突，引发中文乱码
4. 被调用的 Python 脚本添加编码声明
- 被
.bat 调用的 .py 文件，文件头部必须固定添加：
- 确保 Python 脚本在处理中文输出时不会产生编码异常
5. emoji 处理
- UTF-8 编码原生支持 emoji，可以正常使用
- 但如果目标环境是
cmd.exe 较旧版本，emoji 可能显示为方框
- 推荐使用 ASCII 替代方案确保兼容：
[ok] 替代 ✅[x] 替代 ❌[!] 替代 ⚠️[info] 替代 📋[path] 替代 📍[py] 替代 🐍
强制自测要求（核心约束）
禁止仅在 IDE 内嵌终端完成自测
必须 模拟用户在本地直接双击 bat 文件 的行为，在原生独立 CMD 窗口中执行验证。
验证方法：
# 在独立的 cmd.exe 进程中运行（模拟双击）
Start-Process cmd.exe -ArgumentList "/c 目标.bat & pause" -Wait
# 或者直接文件资源管理器中双击目标.bat
验收标准：
凡是 IDE 运行正常、本地双击出现中文乱码、参数异常、子进程调用失败的脚本，一律判定为不合格，必须重新修复。
标准模板
入口启动脚本模板
@echo off
chcp 65001 >nul 2>&1
title Project Name - Description
setlocal enabledelayedexpansion
echo ========================================
echo Title
echo ========================================
echo.
REM ------ Pre-checks ------
if not exist "some_path" (
echo [x] Check failed description
pause
exit /b 1
)
REM ------ Main Logic ------
echo [1/3] Step one...
call some_command
if errorlevel 1 (
echo [x] Step one failed
pause
exit /b 1
)
echo [ok] Step one done
echo.
echo [2/3] Step two...
python main.py --param value
echo [ok] Step two done
echo.
echo [3/3] Launch complete...
echo.
echo ========================================
echo [ok] All operations completed!
echo ========================================
pause
子脚本模板（无 chcp）
@echo off
REM Sub bat: no chcp, inherit parent encoding
setlocal enabledelayedexpansion
REM Handle parameters when called by entry bat
set "INPUT_FILE=%~1"
set "OUTPUT_DIR=%~2"
echo [info] Processing: %INPUT_FILE%
python script.py "%INPUT_FILE%" "%OUTPUT_DIR%"
if errorlevel 1 (
echo [x] Processing failed
exit /b 1
)
echo [ok] Processing done
exit /b 0
Python 调用规范
@echo off
chcp 65001 >nul 2>&1
REM Python script header MUST have # -*- coding: utf-8 -*-
python script.py
if errorlevel 1 (
echo [x] Script execution failed
pause
exit /b 1
)
验证清单
编写/修改 .bat 文件后逐项检查：
常见错误模式
| 错误模式 | 正确做法 |
|---|
| 文件保存为 GBK/ANSI | 保持 UTF-8 编码 |
chcp 65001 >nul 省略 2>&1 | 写全 chcp 65001 >nul 2>&1 |
在子 bat 中重复写 chcp | 删除子 bat 中的 chcp |
| 调用 Python 脚本未声明编码 | Python 文件头部加 # -*- coding: utf-8 -*- |
| 仅在 IDE 终端测试就认为通过 | 必须模拟双击，在独立 CMD 中验证 |
使用 :: 写中文注释 | 用 REM 写中文注释（:: 在 setlocal 块内可能出错） |
工作原理
编码链路
文件编码 (UTF-8)
↓
入口 bat → chcp 65001 → CMD 切换到 UTF-8 模式
↓
子 bat / Python 脚本 → 继承 UTF-8 环境输出正确中文
为什么不用 GBK？
- SearchReplace 工具和 Write 工具自动以 UTF-8 保存文件
- 强制转换为 GBK 后，工具再次编辑时又变回 UTF-8 → 文件编码错乱 → 乱码
- Trae IDE 内嵌终端使用 UTF-8（65001）→ GBK 文件在 IDE 中显示乱码
- UTF-8 是通用编码标准，跨平台兼容性更好
为什么入口必须 chcp 65001？
- 用户 Windows 10+ 已有良好的 UTF-8 支持
chcp 65001 >nul 2>&1 将 CMD 窗口切换到 UTF-8 模式- 后续所有 echo 输出、参数传递、子进程输出都与文件 UTF-8 编码一致
2>&1 确保即使 chcp 执行失败（如旧系统），也不会中断脚本执行
为什么子 bat 禁止重复 chcp？
chcp 会切换当前进程的代码页call 调用子 bat 在同一进程中执行- 子 bat 再次
chcp 可能导致编码回退到 GBK → 后续输出乱码
- 编码切换应当由入口文件统一管理
历史教训（经验总结）
此规范源于多次调试 BAT 编码问题积累的经验，记录典型坑点以防重犯：
-
GBK 转换陷阱：将 bat 文件从 UTF-8 转为 GBK 后，AI 工具（SearchReplace/Write）再次编辑会以 UTF-8 重新保存，产生「UTF-8+GBK 混合」的畸形编码，中文显示为类似 缁熶竴 的乱码。
-
IDE 测试陷阱：AI 在 IDE 终端（UTF-8）测试通过后，用户双击（GBK CMD）必然乱码。AI 无法在 IDE 中复现乱码，导致误判为「已修复」。
-
chcp 省略陷阱：写 chcp 65001 >nul 省略 2>&1，在极少数场景下 chcp 失败的错误输出会污染管道。
-
子 bat 递归陷阱：入口 bat 调用的子 bat 中如果再次写 chcp 65001，会导致同一个 CMD 进程编码被重复切换，产生不可预测的行为。
-
Python 编码陷阱：Python 3 默认输出使用 UTF-8，与 CMD 的 GBK 模式不匹配。脚本头部加 # -*- coding: utf-8 -*- 统一声明。
-
chcp 删除陷阱：修改现有 bat 文件时误删或覆盖掉 chcp 65001 >nul 2>&1 行（尤其是用 Write 工具完整重写时），导致双击 bat 时 CMD 以 GBK 编码读取 UTF-8 文件，中文全部乱码。修复时必须保证第2行恢复 chcp 65001 >nul 2>&1。
-
SearchReplace 编码陷阱：在 UTF-8 编码的 bat 文件上使用 SearchReplace 工具匹配包含中文的 old_str 时，工具内部编码处理可能产生错乱，导致中文被「双重编码」变为乱码。正确的修改方式：使用 Python 生成 bat 文件（见第8条），禁止在 .bat 上使用 SearchReplace 修改含中文的行。
-
Write+SearchReplace 双重破坏陷阱：Write 工具写入 bat 文件时使用 LF 换行（而非 Windows 标准的 CRLF），而 SearchReplace 工具进一步修改时会再次破坏换行格式（可能产生双重 CRLF 或混合换行）。CMD 在解析 LF 换行的 bat 文件时，遇到括号块（if/else 等）可能解析错乱，产生看似乱码的报错。
正确的 BAT 文件修改方法（核心流程）：
❌ 错误做法：Write 直接写 bat → SearchReplace 修改 → 编码/换行双重破坏
✅ 正确做法：Write 写 Python 生成器 → Python 生成 bat → 删除生成器
Python 生成器的标准写法：
path = r'目标.bat'
lines = []
lines.append('@echo off')
lines.append('chcp 65001 >nul 2>&1')
text = '\r\n'.join(lines) + '\r\n'
with open(path, 'w', encoding='utf-8', newline='\r\n') as f:
f.write(text)
关键约束：
- 必须先删除旧 bat 文件（清除历史编码污染）
encoding='utf-8' → 确保 UTF-8 无 BOMnewline='\r\n' → 确保 CRLF 换行（Windows 标准）- 用
lines 列表逐行构建内容 → 避免字符串拼接遗漏换行
- 运行生成器后立即删除它 → 不给用户留垃圾文件
-
模板参照原则：修改 bat 文件前，先找一个用户本地能正常运行的 bat 文件作为参照模板，严格模仿其风格，包括：
- 换行方式（CRLF ✅ vs 其他 ❌）
%ERRORLEVEL% vs if errorlevel 的选择（与模板一致）- 缩进风格
@echo off / chcp 65001 / title 等头部格式- 注释风格（
:: 或 REM）
