github-desktop-zh

Github Desktop 汉化技能（Windows / macOS / Linux）

调用内置脚本自动探测 Github Desktop 安装目录，识别 loose 或 asar 打包模式，使用内置词典执行 JS 字符串字面量替换。

资源结构

GitHubDesktop-zh/
├── SKILL.md              # 本文件
├── dict/
│   └── dictionary.txt    # 汉化词典（首行可声明 # @gh-version: 3.*）
└── scripts/
    └── apply_zh.py       # 汉化脚本 v1.1.0

运行模式

脚本自动识别目标为 resources\app（loose 模式）或 resources\app.asar（asar 模式）：

asar 工具安装：npm install -g @electron/asar

执行前检查（Agent 必须执行）

在执行任何命令前，Agent 应检查：

# ① Python 版本
python --version

# ② 脚本存在性
Test-Path "{技能根目录}/scripts/apply_zh.py"

# ③ 词典存在性
Test-Path "{技能根目录}/dict/dictionary.txt"

以上任一失败即中断，告知用户缺失项。

执行命令

汉化（默认：自动探测 + 备份 + 替换 + 部署）

python "{技能根目录}/scripts/apply_zh.py" --deploy

预览（不修改任何文件，仅展示匹配统计）

python "{技能根目录}/scripts/apply_zh.py" --dry-run

回滚

python "{技能根目录}/scripts/apply_zh.py" --rollback

自定义词典

python "{技能根目录}/scripts/apply_zh.py" --deploy --dict "{用户提供的词典路径}"

手动指定 GH 路径（loose 目录或 asar 文件）

python "{技能根目录}/scripts/apply_zh.py" --deploy --src "D:\...\app"
python "{技能根目录}/scripts/apply_zh.py" --deploy --src "D:\...\app.asar"

GH 运行时强制执行

python "{技能根目录}/scripts/apply_zh.py" --deploy --force

流程断点与验证

脚本内部每个步骤失败时均会 sys.exit(1) 并打印 [ERROR]。Agent 应在执行后检查退出码和 stdout：

故障处理

词典格式

每行一条：源串>*.*<译串>*.*<分组>*.*<目标文件

• 源串/译串可用引号包裹（脚本自动剥离外层引号）
• 首行可声明版本：# @gh-version: 3.*（可选）
• 空行忽略；重复条目自动去重（按 源串+目标文件）
• 脚本按源串长度降序替换，避免短串破坏长串

安全机制

• 混合替换策略：优先字面量匹配（(["'])source\1，仅命中被相同引号包裹的完整字符串字面量）；字面量未命中时，对长度 ≥10 且含空格的 source 回退到子串匹配（UI 文本特征，误伤变量名/注释概率低）；短串保持严格字面量匹配
• BOM 保留：读写时检测并保留原文件 BOM 状态
• 备份自动清理：保留最近 5 个时间戳的备份，自动清理更旧的
• 部署后语法校验：若 node 可用，自动对 .js 文件执行 node --check，语法错误时告警
• 回滚前预备份：回滚前将当前文件备份为 .pre_rollback_*