PathEditor/CLAUDE.md

CLAUDE.md

项目概述

PathEditor v5.0 — Windows 系统环境变量 (PATH) 编辑器，Tauri 2.x + React 19 + TypeScript + Rust workspace 构建。GUI + CLI 双模式。

构建命令

# 安装前端依赖
npm install

# 开发模式（GUI 热更新）
npx tauri dev

# 仅前端（浏览器预览，无注册表功能）
npm run dev

# 前端测试
npm test
npm run test:watch

# Rust workspace 全部检查
cargo check

# 仅核心库检查
cargo check -p path-editor-core

# CLI 构建
cargo build --release -p patheditor-cli

# 生产构建（前端）
npm run build

# 完整构建（生成 NSIS 安装包）
npx tauri build

架构

Cargo workspace 三层，前后端分离，通过 Tauri IPC 通信。

PathEditor/
├── core/                       # Rust 库 crate（零 Tauri 依赖）
│   └── src/
│       ├── registry.rs         # 注册表读写 + clean_paths
│       ├── system.rs           # check_admin、validate_path、expand_env_vars、broadcast
│       ├── backup.rs           # backup_registry、get_appdata_dir
│       ├── disabled.rs         # save/load_disabled_state
│       ├── fs.rs               # read_text_file、import_paths、export_paths
│       ├── scanner.rs          # scan_conflicts、scan_tools
│       ├── profiles.rs         # list/save/load/delete/rename_profile
│       └── lib.rs
├── gui/                        # Tauri 桌面应用（依赖 core）
│   └── src/commands/           # 薄包装：#[tauri::command] → 调用 core
├── cli/                        # CLI 命令行（依赖 core + clap）
│   └── src/main.rs             # 18 条命令
├── src/                        # React 前端 (TypeScript strict 模式)
│   ├── core/                   # 纯逻辑 — 零 React/零 Tauri 依赖
│   ├── store/                  # Zustand 状态管理
│   ├── components/             # UI 组件
│   │   ├── layout/             # AppShell、TitleBar、StatusBar、ErrorBoundary
│   │   ├── path-list/          # PathTable、MergePreview
│   │   ├── toolbar/            # ToolBar、ActionButtons、UndoRedoButtons
│   │   ├── dialogs/            # PathEdit、Help、Import、Analyze、Profile
│   │   └── ui/                 # Modal、buttons
│   ├── hooks/                  # useAppActions、useKeyboard
│   ├── i18n/                   # zh-CN / en
│   └── config/                 # default.json
├── tests/unit/                 # Vitest 前端单元测试
├── e2e/                        # Playwright E2E 测试
└── Cargo.toml                  # Workspace 根 + [workspace.package]

IPC 接口（Rust → Frontend）

Command	参数	返回值	功能
load_system_paths	—	Result<Vec<String>, String>	从 HKLM 读取系统 PATH
load_user_paths	—	Result<Vec<String>, String>	从 HKCU 读取用户 PATH
save_system_paths	paths: Vec<String>	Result<(), String>	保存系统 PATH（含 32767 字符上限）
save_user_paths	paths: Vec<String>	Result<(), String>	保存用户 PATH
check_admin	—	bool	检测管理员权限
validate_path	path: &str	bool	检查目录是否存在
expand_env_vars	path: &str	String	展开 %VAR%
broadcast_env_change	—	()	广播 WM_SETTINGCHANGE
backup_registry	custom_dir	Result<String, String>	备份注册表
get_appdata_dir	—	String	备份目录路径
save_disabled_state	system, user	Result<(), String>	持久化禁用状态
load_disabled_state	—	Result<(Vec, Vec), String>	加载禁用状态
read_text_file	path	Result<String, String>	读取文本文件
scan_conflicts	paths	Result<Vec<ConflictEntry>, String>	可执行文件冲突检测
scan_tools	paths, query	Result<Vec<ToolGroup>, String>	可执行文件清单
list_profiles	—	Result<Vec<ProfileMeta>, String>	列出配置
save_profile	name, sys, user	Result<(), String>	保存配置
load_profile	name	Result<ProfileData, String>	加载配置
delete_profile	name	Result<(), String>	删除配置
rename_profile	old, new	Result<(), String>	重命名配置

CLI 命令参考

patheditor list          [--system|--user] [--json]
patheditor add           <PATH> [--system|--user]
patheditor remove        <INDEX> [--system|--user]
patheditor edit          <INDEX> <NEW> [--system|--user]
patheditor move-up       <INDEX> [--steps N] [--system|--user]
patheditor move-down     <INDEX> [--steps N] [--system|--user]
patheditor clean         [--system|--user] [--dry-run] [--json]
patheditor enable        <INDEX> [--system|--user]
patheditor disable       <INDEX> [--system|--user]
patheditor import        <FILE> [--target system|user|both]
patheditor export        [--format json|csv|txt] [--output <FILE>]
patheditor backup
patheditor conflicts     [--json]
patheditor scan          [--query <NAME>] [--json]
patheditor check-admin   [--json]
patheditor profile       {list|save|load|apply|delete|rename}

所有修改操作在保存前重新读取注册表验证，防止覆盖其他进程的修改。

错误处理

前端

场景	处理
IPC 调用失败	Promise.allSettled 精确报告哪个 hive 保存失败
JSON 文件损坏	importFromJson try/catch，返回空结果
保存并发双击	isSaving 守卫，第二次调用直接 return
备份创建失败	.catch() 显示 warning_backup，保存继续
渲染异常	ErrorBoundary 捕获 + console.error + 重试按钮

Rust / CLI

• 注册表操作：全部返回 Result<T, String>，中文错误消息
• FFI 调用：失败时 log::warn + 返回安全回退值
• PATH 长度：写入前检查 32767 字符上限
• SAFETY 注释：所有 unsafe 块均有文档
• CLI 原子性：保存前重新读取注册表与加载值对比，不一致报错退出

关键约束

• TypeScript：strict: true，零编译错误
• Rust 工具链：stable-x86_64-pc-windows-gnu（项目已设 override）
• MinGW 兼容：.cargo/config.toml 添加 -lmcfgthread（GCC 15.2.0 运行时）
• 运行权限：需要管理员权限才能编辑系统 PATH，非管理员自动进入只读模式
• 构建产物：NSIS 安装包，约 8MB

版本号升级清单

版本号需在 4 个地方 手动修改：

文件	字段	说明
Cargo.toml	[workspace.package] version	Rust 全量自动继承（3 crate + env!("CARGO_PKG_VERSION")）
package.json	version	前端动态 import（TitleBar、import-export.ts 自动读取）
gui/tauri.conf.json	version	打包版本号
gui/tauri.conf.json	窗口 title	窗口标题栏显示
README.md	badges	文档徽章

其他位置均从上述两源头动态读取，无需单独修改:

• core/src/fs.rs / cli/src/main.rs → env!("CARGO_PKG_VERSION")
• src/components/layout/TitleBar.tsx → import { version } from '../../../package.json'
• src/core/import-export.ts → import { version } from '../../package.json'

Release 操作：

• gh release create vX.Y.Z 创建新 Release
• 安装包上传到新 Release，不要覆盖旧版本