bat-encoding-standards

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

强制调用规则

1. 命中任意关键字 → 必须先调用本 Skill，再回答或动手
2. 没有例外——即使你觉得"这只是个小改动"、"只是改一行"、"先回答再处理"，也必须先调 Skill
3. 反向触发器：即使你的思考过程中自己生成了 .bat 操作方案（而非用户提出），也要立即触发
4. 本技能不会自动启用——依赖上述关键字检查机制和 auto-experience-trigger 的同源场景识别

核心背景（必须理解）

存在开发环境与用户本地环境编码差异，这是所有 BAT 编码 Bug 的根源：

环境	终端编码	说明
Trae IDE 内嵌终端	UTF-8（65001）	AI 开发测试的环境
用户本地 CMD（双击）	GBK（936）	用户实际运行的环境
SearchReplace 工具写入	UTF-8	文件保存方式固定

关键推论：

• AI 在 IDE 终端测试通过 ≠ 用户双击运行正常
• AI 无法在 IDE 中复现用户本地乱码问题
• 必须以「用户双击运行」为最终验证标准

核心规则

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 文件，文件头部必须固定添加：

# -*- coding: utf-8 -*-

• 确保 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 内嵌终端运行：中文显示正常
• 独立 CMD 窗口运行（模拟双击）：中文显示正常
• 调用子 bat 时：子 bat 中文参数传递正确
• 调用 Python 脚本时：Python 输出中文无乱码
• 退出后 CMD 窗口无报错信息

凡是 IDE 运行正常、本地双击出现中文乱码、参数异常、子进程调用失败的脚本，一律判定为不合格，必须重新修复。

标准模板

入口启动脚本模板

@echo off
chcp 65001 >nul 2>&1
title 项目名称 - 功能描述
setlocal enabledelayedexpansion

echo ========================================
echo   标题
echo ========================================
echo.

REM ------ 前置检查 ------
if not exist "some_path" (
    echo [x] 检查失败描述
    pause
    exit /b 1
)

REM ------ 主逻辑 ------
echo [1/3] 步骤一...
call some_command
if errorlevel 1 (
    echo [x] 步骤一失败
    pause
    exit /b 1
)
echo [ok] 步骤一完成
echo.

echo [2/3] 步骤二...
python main.py --param value
echo [ok] 步骤二完成
echo.

echo [3/3] 启动完成...
echo.

echo ========================================
echo [ok] 所有操作已完成！
echo ========================================
pause

子脚本模板（无 chcp）

@echo off
REM 子 bat：不写 chcp，继承父进程编码
setlocal enabledelayedexpansion

REM 被入口 bat 调用时处理参数
set "INPUT_FILE=%~1"
set "OUTPUT_DIR=%~2"

echo [info] 处理文件: %INPUT_FILE%
python script.py "%INPUT_FILE%" "%OUTPUT_DIR%"
if errorlevel 1 (
    echo [x] 处理失败
    exit /b 1
)
echo [ok] 处理完成
exit /b 0

Python 调用规范

@echo off
chcp 65001 >nul 2>&1
REM Python 脚本头部必须有 # -*- coding: utf-8 -*-
python script.py
if errorlevel 1 (
    echo [x] 脚本执行失败
    pause
    exit /b 1
)

验证清单

编写/修改 .bat 文件后逐项检查：

• 文件编码为 UTF-8（无 BOM）
• 入口文件 第二行 为 chcp 65001 >nul 2>&1
• 子 bat 文件 不包含 chcp 命令
• 调用 Python 脚本头部有 # -*- coding: utf-8 -*-
• 已通过 独立 CMD 窗口 验证中文显示正常（模拟双击）
• IDE 内嵌终端中文显示正常
• @echo off 和 setlocal enabledelayedexpansion 按需使用

常见错误模式

错误模式	正确做法
文件保存为 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？

1. SearchReplace 工具和 Write 工具自动以 UTF-8 保存文件
2. 强制转换为 GBK 后，工具再次编辑时又变回 UTF-8 → 文件编码错乱 → 乱码
3. Trae IDE 内嵌终端使用 UTF-8（65001）→ GBK 文件在 IDE 中显示乱码
4. 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 编码问题积累的经验，记录典型坑点以防重犯：

1. GBK 转换陷阱：将 bat 文件从 UTF-8 转为 GBK 后，AI 工具（SearchReplace/Write）再次编辑会以 UTF-8 重新保存，产生「UTF-8+GBK 混合」的畸形编码，中文显示为类似 缁熶竴 的乱码。

2. IDE 测试陷阱：AI 在 IDE 终端（UTF-8）测试通过后，用户双击（GBK CMD）必然乱码。AI 无法在 IDE 中复现乱码，导致误判为「已修复」。

3. chcp 省略陷阱：写 chcp 65001 >nul 省略 2>&1，在极少数场景下 chcp 失败的错误输出会污染管道。

4. 子 bat 递归陷阱：入口 bat 调用的子 bat 中如果再次写 chcp 65001，会导致同一个 CMD 进程编码被重复切换，产生不可预测的行为。

5. Python 编码陷阱：Python 3 默认输出使用 UTF-8，与 CMD 的 GBK 模式不匹配。脚本头部加 # -*- coding: utf-8 -*- 统一声明。

6. chcp 删除陷阱：修改现有 bat 文件时误删或覆盖掉 chcp 65001 >nul 2>&1 行（尤其是用 Write 工具完整重写时），导致双击 bat 时 CMD 以 GBK 编码读取 UTF-8 文件，中文全部乱码。修复时必须保证第2行恢复 chcp 65001 >nul 2>&1。

7. SearchReplace 编码陷阱：在 UTF-8 编码的 bat 文件上使用 SearchReplace 工具匹配包含中文的 old_str 时，工具内部编码处理可能产生错乱，导致中文被「双重编码」变为乱码。正确的修改方式：使用 Python 生成 bat 文件（见第8条），禁止在 .bat 上使用 SearchReplace 修改含中文的行。

8. Write+SearchReplace 双重破坏陷阱：Write 工具写入 bat 文件时使用 LF 换行（而非 Windows 标准的 CRLF），而 SearchReplace 工具进一步修改时会再次破坏换行格式（可能产生双重 CRLF 或混合换行）。CMD 在解析 LF 换行的 bat 文件时，遇到括号块（if/else 等）可能解析错乱，产生看似乱码的报错。

   正确的 BAT 文件修改方法（核心流程）：

   ❌ 错误做法：Write 直接写 bat → SearchReplace 修改 → 编码/换行双重破坏
   ✅ 正确做法：Write 写 Python 生成器 → Python 生成 bat → 删除生成器
   

   Python 生成器的标准写法：

   # -*- coding: utf-8 -*-
   path = r'目标.bat'
   lines = []
   lines.append('@echo off')
   lines.append('chcp 65001 >nul 2>&1')
   # ... 所有行按顺序加入 lines 列表 ...
   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 无 BOM
   • newline='\r\n' → 确保 CRLF 换行（Windows 标准）
   • 用 lines 列表逐行构建内容 → 避免字符串拼接遗漏换行
   • 运行生成器后立即删除它 → 不给用户留垃圾文件

9. 模板参照原则：修改 bat 文件前，先找一个用户本地能正常运行的 bat 文件作为参照模板，严格模仿其风格，包括：

   • 换行方式（CRLF ✅ vs 其他 ❌）
   • %ERRORLEVEL% vs if errorlevel 的选择（与模板一致）
   • 缩进风格
   • @echo off / chcp 65001 / title 等头部格式
   • 注释风格（:: 或 REM）