能力入口 · 个人维护的能力入口
中文乱码诊断与修复
在中文乱码时尽量找回可恢复的原文，同时保留原字节，避免一次错误转码把文件永久改坏。
本地诊断和可逆修复有回归证据；本次没有修真实文件。当前文件是否可无损修复，要由原字节、诊断计划与写前核验决定。先看怎么用
你不需要记住 Skill 名，直接说需求就行
什么时候用
- 中文显示成乱码
- 怀疑原编码或文件开头的编码标记损坏
- 出现替换符号或异常私用字符
- 文件可能被错误转换过两次编码
可以直接这样说
例如一个 CSV 打开后中文全是乱码。它先只读分析原字节，列出最可能的编码链和修复预览，不会立刻改文件。
最后会得到什么
只有在精确文件和修复方案都确认后才替换，并先保留原字节备份；写完会核对文件是否真按预期保存，不一致就尝试回退。另行检查只负责发现漂移，发现问题不会假装已经自动修好。
不适合这样用
- 没有原始文件字节，只剩可能已损坏的复制文本
- 信息已丢失却要求猜出原字
- 顺着目录链接修改另一个未经确认的源文件
正常时
确认乱码成因和修复预览后，先备份原文件，再只替换仍与预览时相同的那一份，并重新读取核对。
发现问题时
存在多种可能编码或预览不可信时只给修复计划，不修改文件。
入口不可用或证据不足时
原始字节不可读或备份条件不成立时停止，不用忽略/替换错误字符制造看似正常文本。
从哪里开始
在当前 AI 对话指出乱码原文件或精确目录，并说是先诊断还是要修复；AI 先给候选解释与预览，只有可证实的文件才写入。
需要准备什么
- 出现乱码的原文件或有界目录；最好说明原本应是什么语言或哪里开始损坏
- 已知原始编码时给出线索；要实际修复或恢复时说明精确目标
为什么需要这个能力
乱码可能来自 UTF-8、GBK、BOM 或二次转码。直接另存为某种编码，可能把尚可恢复的原字节永久覆盖。
从需求到结果
提供乱码文件或精确目录，原始文件比复制出来的乱码文字更有价值。AI 先只读检查原始字节，判断可能经过哪些编码转换。
先给可恢复范围、修复预览与不同解释。编码不确定或信息已丢失时不猜字，也不靠忽略错误字符制造表面正常。
精确文件和修复方案成立后，先保留原字节，再确认文件自预览以来没有变化，才完整替换并重新读取核对。
写入后不符合预期时，先核备份、原件与本次候选的绑定，再恢复原字节；若文件随后被别人改过就停止覆盖并报告冲突。后续单独检查只报告漂移，不冒充自动修好。
失败时会怎样恢复
无法确定原来是哪种编码
系统反应：先保留原文件，不直接改写。
恢复方式：展示几种可能的修复预览和各自证据，待能区分时才处理。
原来的字已被替换并永久丢失
系统反应：不凭上下文猜一个看似通顺的原文。
恢复方式：找 Git 原件、可信备份或其他可重建来源；没有就说明无法恢复。
修复后检查没通过
系统反应：保留原字节备份并停止继续改其他文件。
恢复方式：先确认备份与本次改动对应，且文件后来没有被别人改过；只有这些条件成立才恢复，否则保留双方并说明冲突。
技术身份与验证证据
Skill · mojibake-doctor · 成熟度 A（稳定）
这个 Skill 用到的名词
- Raw bytes（原始字节）
- 文件真实存储的字节，是判断编码问题的起点。
- BOM（字节顺序标记）
- 文件开头用于提示编码的特殊字节；损坏或重复会造成解析异常。
- Double transcoding（二次错误转码）
- 文本先被错误解码，再把错误字符重新编码，形成更难恢复的乱码。
- Repair plan（修复计划）
- Apply 前只读列出将怎样把原字节转换成目标编码。
- Atomic replace（原子替换）
- 新文件完整写好后一次替换旧文件，避免中途留下半文件。
专业定义
诊断 UTF-8、GBK、GB18030、BOM、替换字符、私用区和双重转码，并以预览、备份和原子替换完成可逆修复。
执行参考
下面保留 AI 和工具实际使用的参数、步骤与依赖。日常使用可以直接提出需求，不需要先手工准备这些协议。
输入
- 精确文件或目录
- 可选编码线索
输出
- scan 和 diagnosis
- 默认只读 repair plan（修复计划）
- apply 后的 verify 结果和原字节 backup
执行顺序
- 1
读取 raw bytes（原始字节）
- 2
scan 和 diagnose
- 3
先 preview
- 4
显式 apply
- 5
重新读取并 verify
操作边界
- 单文件 hash-pinned transaction（事务）
- 原字节 backup
- atomic replace
- 信息丢失时回到 Git、备份或重新生成
依赖
- 本地 Python
诊断怎样决定能不能写
scan、diagnose、repair预览和verify都只读，写入是精确单文件、源hash（内容指纹）固定的事务。必须有当前文件授权、严格可逆解码、当前SHA与诊断一致、候选hash（内容指纹）与计划一致、原字节备份和原子替换。
检测只剥离有界、完全可逆的GB18030→UTF-8链，并要求标准常用汉字评分有实质改善，不拿某项目词表作授权。两汉字候选可报中置信，但不能凭字节消除语义巧合，因此不自动修。
带BOM的UTF-16会分类与扫描，不自动重写；无BOM UTF-16与GB18030可能无法仅凭字节区分。GB18030归一必须明确--normalize-from gb18030。U+FFFD可能已经丢失信息，应找Git/备份/重新生成，不能猜回原字。
# 扫描与诊断
python scripts/mojibake_doctor.py scan --path <精确目录> --output <scan.json>
python scripts/mojibake_doctor.py diagnose --path <精确文件> --output <repair-plan.json># 已知GB18030来源才归一
python scripts/mojibake_doctor.py diagnose --path <精确文件> --output <plan.json> --normalize-from gb18030# 先预览，再执行及核验
python scripts/mojibake_doctor.py repair --plan <plan.json>
python scripts/mojibake_doctor.py repair --plan <plan.json> --apply
python scripts/mojibake_doctor.py verify --plan <plan.json>备份与恢复不会覆盖后来修改
备份默认在CODEX_HOME\MojibakeDoctor\transactions，配置数据根为CODEX_SQLITE_HOME时使用该根；两者都无稳定根则显式--transaction-root，不回退一次性或系统盘位置。
restore先核manifest（清单）与原备份hash（内容指纹），在替换前再次核当前candidate hash（内容指纹）；观察后有人修改了文件就停止恢复，保留双方，不能用“回到原件”覆盖新改动。递归不跟junction（目录联接）、symlink或reparse point。
中文.ps1保留UTF-8 BOM；Markdown/JSON/YAML/SKILL.md用UTF-8无BOM。普通中文不是乱码证据，GB18030能解码不证明含义正确；不支持文件明确skipped。诊断报告留本地，只在需要时显示片段。
# 按原事务恢复
python scripts/mojibake_doctor.py restore --manifest <transaction.json>验证状态
源码、安装、供应检查、当前任务、新任务和真实使用分别列出；一层通过不自动提升另一层。
- Source（源码）
- 当前 .agents source e734251 中的唯一源码已核对
- Install（安装）
- canonical junction（目录联接） 已安装
- Transaction（供应事务）
- 供应事务检查通过；0 个坏事务
- Current task（当前任务）
- 本轮宿主回执未知
- Fresh task（全新任务）
- 新任务回执未知
- End to end（端到端）
- 主要修复路径已验
12 项 Python 测试和专门 Skill 测试通过。
证据时间与来源
- Observed at（观察时间）
- 供应链现场：2026-09-24 12:56（中国时间）；项目场景按各项记录
- Source commit（来源提交）
e734251081dc48bdd86765372ce225b3929ce9ae- Supply command（供应验证命令）
E:\.agents\tools\Test-PersonalSkillSupply.ps1 -RequireInstalled -NoExternalEvidence -Json- Evidence basis（证据来源）
- .agents E171 release 1aa0b0a、当前 Personal Skill supply（个人能力供应链），以及本页明确标注的既有项目/Provider（固定服务入口）证据；source/install/transaction 通过不冒充 current（当前状态）/fresh/E2E
Canonical source（唯一维护源）
E:\.agents\skills\mojibake-doctor\SKILL.md该路径是维护源；用户目录中的发现入口不是第二份源码。