---
title: VMZhCN 系统架构与工作流概览
type: curated
permalink: main/projects/49564d35-91ae-430d-9d67-7bb8bec4c646/curated/development/vmzh-cn-系统架构与工作流概览
stable_id: 7370b9b5-c94f-40a2-a98c-5bd36be07b2f
scope: project
project_id: 49564d35-91ae-430d-9d67-7bb8bec4c646
workspace_type: development
usage_profile_id: null
preference_context: development
document_type: architecture
revision: 1
source_memory_ids: []
source_checkpoint_ids: []
source_file_ids: []
source_git_commit: 3e0661c1216b285a039518ba6d810b8394657e1d
source_git_commits:
- 3e0661c1216b285a039518ba6d810b8394657e1d
source_agent_sync_ids: []
model_connection: Sub2API
model_name: git-restore
source_count: 24
source_revisions: {}
source_dispositions:
  processed: 24
  unchanged: 0
  unsupported: 0
  skipped: 0
cited_source_ids: []
job_cited_source_ids: []
conflicts: []
supersedes: []
preferences: []
source_cursor: 196
source_hash: 0a84505c3e53c83a1d2f2e939a42b813a45b865e71febe7c7d488f60c0578b9b
prompt_version: 2026-08-12.3
schema_version: '3'
curation_job_id: null
created_at: '2026-08-27T18:35:52.911964+00:00'
updated_at: '2026-09-23T14:54:04.443544+00:00'
tags:
- 架构
- 工作流
- 实现
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

## 架构概览

项目核心由 **Python CLI (`vmzhcn.py`)** 组成，提供以下高层子命令：

| 子命令 | 功能描述 | 关键实现点 |
|--------|----------|-----------|
| `scan` | 使用 `strings` 从本地已安装的 **VMware Workstation Pro 26H1** Linux 二进制中提取全部嵌入的英文消息，生成 `*.en.vmsg` 基准文件。 | `command_scan`（source: `git:vmzhcn.py`）。 |
| `build` | 读取基准文件与 `linux‑overrides‑zh_CN.vmsg`，解析、校验占位符、合并，输出完整的中文覆盖字典。 | `command_build` 包括 `parse_vmsg`、`validate_overrides`、`merge_dictionaries`（source: `git:vmzhcn.py`）。 |
| `install` | 以 **root** 权限备份现有字典至 `/var/backups/vmzhcn/<timestamp>`，然后原子替换为新字典，确保文件所有权/权限正确。 | `command_install`（source: `git:vmzhcn.py`）。 |
| `restore` | 从备份目录恢复先前的字典，同样需要 root。 | `command_restore`（source: `git:vmzhcn.py`）。 |
| `switch` | 正常化目标 locale（仅支持 `zh_CN`、`en_US`），写入 `~/.vmware/preferences`，生成对应的桌面启动器 `.desktop`，可选调用 `update-desktop-database`。 | `command_switch`（source: `git:vmzhcn.py`）。 |
| `coverage` | 对比基准与覆盖字典，统计整体与 Linux‑specific 翻译覆盖率，按启发式分组（`translation_group`），可输出缺失键模板。 | `command_coverage`（source: `git:vmzhcn.py`）。 |
| `status` | 展示当前 VMware 根路径、字典路径、已安装消息数、VM 版本以及用户 locale 设置。 | `command_status`（source: `git:vmzhcn.py`）。 |

### 数据流顺序（典型使用场景）
1. **初次部署** → `scan` → 生成 `base-en.vmsg` → `build`（合并本地覆盖） → `install`（备份+替换） → `switch zh_CN`（用户层切换）。
2. **版本升级** → 再次 `scan` → `build`（可能出现新键） → `coverage` 检查缺口 → 翻译缺失键 → `install` → `switch`。
3. **故障恢复** → `restore` → `status` 验证。

### 关键约束（来自全局/项目偏好）
- **语言沟通**：所有交流使用中文（source: `7429c22e-50ff-458a-97c0-423c679904c7`）。
- **KISS & YAGNI**：仅实现当下需求，避免投机性依赖（source: `bf88c265-4749-4c50-85bc-4bae25298cd5`）。
- **AI 与 Git 自动化**：默认关闭（source: `3f91189b-11a1-45bb-8357-4f413dc1609d`）。
- **凭证自动获取**：所有网络/SSH/API 调用前先查询 Vaultwarden（source: `105b328f-4bda-4641-90a7-7282ef156316`）。
- **记忆管理**：项目笔记仅保存在 MemRelay（source: `1194be51-ee29-47e1-8957-ec2888007db6`）。
- **提交规范**：使用中文单句描述，`aidocs/` 永远 `.gitignore`（source: `5ed86f53-b53e-4534-8e51-d3a010069d5e`）。

**标签**: [架构], [工作流], [实现]