Chinese-Encoding-Handler

解决PowerShell环境中文文件乱码，支持自动编码检测、安全读写及终端中文显示修复。

Security Scan

The skill's documentation describes PowerShell scripts that modify files and terminal settings, but those scripts are not included in the package and there is no install or provenance—this mismatch and the potential for permanent system changes make the package suspicious.

Purpose & Capability

The SKILL.md and multiple delivery/review documents describe four core scripts (encoding-detector.ps1, safe-read.ps1, safe-write.ps1, terminal-fix.ps1) under a scripts/ directory and show test runs, but the provided file manifest contains only docs and test data—no scripts/ directory or .ps1 script files. That means the package does not actually contain the implementation it claims to provide, which is an incoherence between stated purpose and actual contents.

Instruction Scope

Runtime instructions tell the agent (or user) to execute local PowerShell scripts (e.g., .\scripts\terminal-fix.ps1 -Permanent) which read/write files and can alter terminal/profile settings. Those actions can modify system state and may require administrator privileges. The SKILL.md does not include the code, so following its instructions would require obtaining code from an external source (the SKILL.md references a GitHub repo) — this expands the runtime scope beyond the package and grants the agent discretion to fetch/execute external code.

Install Mechanism

No install spec is provided (instruction-only). Low friction normally, but because the package lacks the scripts it documents, an installer or the agent might be expected to fetch code from the referenced GitHub URL. There is no controlled install URL, release artifact, or integrity information in the package, so any ad-hoc fetch would be higher risk.

Credentials

The skill requests no environment variables or credentials, which is appropriate for a local encoding helper. However, its instructions include making permanent terminal/profile changes (writing to $PROFILE, setting code page) and running operations that may require elevated privileges. Those privileged effects are not declared or constrained in metadata, so the package asks implicitly for system-level changes without proportional disclosure or safeguards.

Persistence & Privilege

Metadata does not request 'always: true' and model invocation is allowed (normal), but the documented terminal-fix operation can persist changes to the user profile or system settings when run with -Permanent (and may require admin rights). A package that makes permanent system-level changes should include its scripts and clear provenance; here the scripts are missing, so the only way to perform persistence would be to fetch/execute external code—this combination increases risk.

What to consider before installing

Do not run any 'terminal fix' or other scripts referenced by this skill until you have the actual script files and have reviewed them yourself. Important points to consider before installing or running anything: 1) The package is documentation and tests only—there are no scripts in scripts/ as the SKILL.md claims. That means an agent or you would need to fetch code from the referenced GitHub repo (or elsewhere) before the skill can work; fetching and executing remote PowerShell without verifying source and integrity is risky. 2) The documented terminal-fix can make permanent changes to your PowerShell profile or system code page and may require administrator privileges—only allow that after inspecting the script and confirming it does only the expected, minimal changes. 3) Ask the publisher for a signed release, a direct install spec (official release URL), or include the .ps1 files in the package; verify file hashes and review the scripts for any network calls, credential exfiltration, or obfuscated logic before running. If the owner supplies the actual scripts and a clear install/release process, re-evaluation could move this to benign; currently the absence of implementation + potential for persistent system modification is why this is suspicious.

描述

中文编码处理工具包，解决 PowerShell 环境下中文文件读写乱码问题。提供自动编码检测、安全文件读写和终端显示修复功能。

触发场景

• 读取中文文件时出现乱码
• 写入中文内容后无法正常显示
• PowerShell 终端中文显示异常
• 需要自动检测文件编码
• 处理包含中文的配置文件或数据文件

使用方法

检测文件编码

.\scripts\encoding-detector.ps1 -Path "C:\path\to\file.txt"

输出示例：

文件路径：C:\path\to\file.txt
检测编码：UTF-8-BOM
置信度：100%

安全读取中文文件

.\scripts\safe-read.ps1 -Path "C:\path\to\file.txt"

带编码参数读取：

.\scripts\safe-read.ps1 -Path "C:\path\to\file.txt" -Encoding "UTF-8"

安全写入中文文件

.\scripts\safe-write.ps1 -Path "C:\path\to\file.txt" -Content "中文内容"

指定编码写入：

.\scripts\safe-write.ps1 -Path "C:\path\to\file.txt" -Content "中文内容" -Encoding "UTF-8-BOM"

修复终端显示

.\scripts\terminal-fix.ps1

永久修复（需要管理员权限）：

.\scripts\terminal-fix.ps1 -Permanent

技术细节

编码检测原理

1. BOM 检测：优先检查文件开头的字节顺序标记（BOM）

   • UTF-8-BOM: EF BB BF
   • UTF-16-LE: FF FE
   • UTF-16-BE: FE FF

2. 内容分析：无 BOM 时，通过字节分布和常见中文字符编码特征判断

   • GBK/GB2312：双字节字符特征
   • UTF-8：多字节序列特征

3. 置信度评分：根据匹配程度给出 0-100% 置信度

UTF-8-BOM 优势

• ✅ 兼容性好：Windows 程序（记事本、Excel）识别准确
• ✅ 跨平台：Linux/macOS 正常读取
• ✅ 无乱码风险：明确标识编码格式
• ⚠️ 注意：某些 Unix 工具可能不兼容 BOM

兼容性说明

系统	支持程度	备注
Windows PowerShell 5.1	✅ 完全支持	推荐 UTF-8-BOM
Windows PowerShell 7+	✅ 完全支持	默认 UTF-8
Linux/macOS	✅ 支持	建议无 BOM UTF-8
CI/CD 环境	✅ 支持	需确保终端 UTF-8

故障排除

常见问题 Q&A

Q1: 为什么读取文件还是乱码？

• 检查文件编码是否被正确识别
• 尝试手动指定 -Encoding 参数
• 使用 encoding-detector.ps1 重新检测

Q2: 写入的文件在记事本打开乱码？

• 使用 -Encoding "UTF-8-BOM" 参数
• 避免使用纯 UTF-8（无 BOM）

Q3: PowerShell 终端显示中文为方框？

• 运行 terminal-fix.ps1
• 检查终端字体是否支持中文
• 使用 -Permanent 参数永久修复

Q4: 批量处理文件时部分失败？

• 检查文件权限
• 确认文件未被其他程序占用
• 查看错误日志定位具体文件

错误代码说明

错误码	含义	解决方案
ERR-001	文件不存在	检查路径是否正确
ERR-002	权限不足	以管理员身份运行
ERR-003	编码检测失败	手动指定编码参数
ERR-004	文件被占用	关闭占用程序后重试
ERR-005	终端设置失败	检查注册表权限

相关资源

• PowerShell 编码官方文档
• UTF-8 BOM 规范
• GitHub 仓库