[0514] 首选项配置文件固定位置

CLAUDE.md

@@ -57,6 +57,17 @@
 例如分支 `da/1113/backward` 对应 `devel/1113.md`。开始工作前先按分支定位
 任务文档,完成后把本次改动(What/Why/How/涉及文件)追加到文档里。
 
+## 首选项（preferences）存储
+
+首选项相关改动遵循以下约定：
+
+1. 首选项统一存放于 `$TEXMACS_HOME_PATH/system/preferences.json`（不按版本分目录），
+   `get_tm_preference_path ()` 返回固定路径，不拼接版本号；
+2. 不得假设统一位置一定存在配置文件（首次运行/全新安装可能没有），缺失时应按默认值处理；
+3. Mogan 不保留跨版本配置迁移：历史遗留的旧版本目录（`system/<版本>/`）中的首选项文件
+   不会被读取，也不做合并迁移。改首选项格式或读写逻辑时，只需保证新格式自身可读写，
+   不必兼容旧版本目录中的文件。
+
 ## 提交规范
 
 1. 一个 PR 至少分为两个 commit（如果分支上已有 commit，此规则不适用）：

devel/0514.md

@@ -0,0 +1,52 @@
+# [0514] 首选项统一存放位置
+
+## 1 相关文档
+- [0515.md](0515.md) — 首选项配置文件改为 JSON 格式（本任务依赖其引入的 JSON 读写与 nlohmann_json 库能力）
+
+## 2 任务相关的代码文件
+- `src/System/Misc/tm_sys_utils.cpp` — `get_tm_preference_path()` 由 `system/<XMACS_VERSION>/` 改为统一位置
+  `system/preferences.json`（不再随版本号变化）
+- `src/System/Config/preferences.cpp` — 简化 `load_user_preferences`：只读统一位置 JSON，删除跨版本迁移逻辑
+- `tests/System/Config/preferences_test.cpp` — 删除迁移用例
+- `CLAUDE.md` — 更新「首选项（preferences）与旧版本配置文件兼容性」规范
+
+## 3 如何测试
+
+### 3.1 确定性测试（单元测试）
+```bash
+xmake b preferences_test && xmake r preferences_test
+```
+用例：写入含特殊字符的值 → 保存 → 统一位置 `preferences.json` 合法 JSON 且转义正确 → 重新加载取回原值；
+文件缺失（首次运行）→ 走默认值。
+
+### 3.2 非确定性测试（交互验证）
+1. 修改任意首选项（如界面语言）→ 退出重启，确认设置保留；
+2. 查看 `$TEXMACS_HOME_PATH/system/preferences.json`，确认是合法 JSON；值含引号/反斜杠（如 Windows 路径）时不损坏；
+3. bump `XMACS_VERSION` 后重启，确认仍读同一文件、首选项不重置；
+4. 开发者菜单 "Open preferences.json" 打开文本缓冲。
+
+## 4 What
+- 首选项统一存放于 `$TEXMACS_HOME_PATH/system/preferences.json`，不再按版本分目录：
+  `get_tm_preference_path ()` 去掉版本号，一次写入后路径永久固定，版本 bump 不再影响首选项位置。
+- 删除 0515 分支早期设计中的跨版本迁移逻辑（`compare_versions`/`load_legacy_preferences`/
+  `migrate_legacy_preferences`）——Mogan 历史上即不保留个人配置，无需迁移旧版本目录。
+- `CLAUDE.md` 更新「涉及首选项改动务必适配旧版本配置文件」规范。
+
+## 5 Why
+- 旧方案首选项按版本分目录存储（`system/<XMACS_VERSION>/preferences.json`），版本号 bump 后新版本
+  读写新目录，旧首选项永远不会被读 → 用户升级后表现为「每次更新都重置」。
+- 统一位置彻底解决：所有版本读写同一个文件，路径固定，升级不丢配置；且无需为旧版本目录编写
+  迁移合并逻辑（Mogan 从未承诺保留跨版本配置）。
+- 顺带修正 0515 记录的已知问题——开发者菜单「Open preferences.json」指向的
+  `$TEXMACS_HOME_PATH/system/preferences.json` 从 stale 路径变成真实路径。
+
+## 6 How
+- `get_tm_preference_path ()`：返回 `get_texmacs_home_path () * "system/preferences.json"`，
+  不再拼接 `XMACS_VERSION`。
+- `load_user_preferences ()`：统一位置 `preferences.json` 存在 → `load_json_preferences`；否则留空
+  （默认值）；不再扫描/合并任何旧版本目录。
+- 保留 `save_user_preferences ()` 的 `merge_sort` 排序，保证 JSON 输出确定性。
+
+## 7 已知问题
+- 历史遗留的旧版本目录（`system/<版本>/preferences.scm` / `.json`）不再被读取，也不会被清理；
+  升级前已存在的个人配置不会被迁移（Mogan 一贯如此）。

src/System/Config/preferences.cpp

@@ -10,7 +10,6 @@
  ******************************************************************************/
 
 #include "preferences.hpp"
-#include "analyze.hpp"
 #include "file.hpp"
 #include "iterator.hpp"
 #include "merge_sort.hpp"
@@ -23,7 +22,6 @@
 #include <nlohmann/json.hpp>
 #include <string>
 
-using moebius::data::block_to_scheme_tree;
 using moebius::data::scm_quote;
 using moebius::data::scm_unquote;
 using nlohmann::json;

src/System/Misc/tm_sys_utils.cpp

@@ -200,8 +200,9 @@ get_tm_cache_path () {
 
 url
 get_tm_preference_path () {
-  return get_texmacs_home_path () *
-         ("system/" * string (XMACS_VERSION) * "/preferences.json");
+  // 统一存放于 system/ 下，不随版本号变化——迁移完成后路径永久固定，
+  // 避免版本 bump 导致「每次升级首选项重置」
+  return get_texmacs_home_path () * "system/preferences.json";
 }
 
 string

tests/System/Config/preferences_test.cpp

@@ -48,7 +48,7 @@ TestPreferences::test_save_load_roundtrip () {
   set_env ("TEXMACS_HOME_PATH", string (home.path ().toUtf8 ().constData ()));
   load_user_preferences (); // 复位全局首选项状态
 
-  // save_string 不建父目录，先建 system/<版本>/
+  // save_string 不建父目录，先建 system/（统一存放位置）
   url prefs_file= get_tm_preference_path ();
   make_dir (head (prefs_file));