msime-windows/server/AGENTS.md

AGENTS.md — server

组织级约定见 组织 AGENTS.md，仓库地图和组件之间的边界见仓库根 AGENTS.md。本文件补充本组件的实现、数据和验证规则，路径都相对于 server/。

本组件是常驻后端进程：输入引擎与候选状态、配置、词典、Named Pipe 服务，以及候选窗、悬浮工具栏、托盘菜单（msimeui Direct2D presenter）。设置窗口（MetasequoiaImeSettings.exe）由本组件的 server/src/settings/ 单独构成一个进程，不在服务端进程内。

vcpkg_installed 的解析

CMakeLists.txt 引用 vcpkg_installed 的地方（头文件目录、sqlite3.dll 拷贝）全部走 ${CMAKE_BINARY_DIR}。

不要改回 ${CMAKE_SOURCE_DIR}/build/...。 那样 binary dir 就只能叫字面的 build，本仓自带的 vcpkg-release preset（binaryDir 是 build-release）和 scripts/lcompile-release.ps1 都会找不到 vcpkg 装好的头文件与运行时 DLL。

CI 刻意构建到 build-release 而不是 build，为的就是让这条不会悄悄退回去——两者在目录名恰好是 build 时解析结果相同，所以只有构建到别处才测得出来。

测试跑在真实词库上，本地要先备好数据

tests/CMakeLists.txt 构建 MetasequoiaImeServerTests，tests/src/ 下的测试源文件规模持续增长（引用具体数字前先数一遍）。本目录 CMakeLists.txt:25 的 include(CTest) 让 BUILD_TESTING 默认为 ON，:556 据此 add_subdirectory(tests)，而 tests/CMakeLists.txt:169 用 add_test 注册同名用例。

CI 现在会真的跑它：根 .github/workflows/ci.yml 的 Server job 在 Build 之后执行 scripts/ci/test-server.ps1，那个脚本按 product-lock.json 取词库、备好数据根目录，再跑 ctest --test-dir server/build-release -C Release --timeout 120。断言失败会让 CI 变红，不再是编译通过就算数。

**关键在于这些测试依赖真实词库，不是 fixture。**引擎从数据根目录读数据，解析顺序是 METASEQUOIA_IME_DATA_DIR 环境变量 → 注册表 HKLM\Software\Metasequoia\MetasequoiaIME 的 DataDir（安装时用户选的位置）→ %LOCALAPPDATA%\metasequoiaime。装了正式版的机器上第二项会生效，所以本地跑测试必须用环境变量覆盖，否则会读到安装目录。另有 METASEQUOIA_IME_CONFIG_DIR 只改 config.toml 的位置、不搬词库，给那些既要真实词库又要隔离配置的测试用。scripts/ci/test-server.ps1 往那里放了四样东西，本地跑测试要凑齐同样的：

• msime.db、others.db、english.db——从产品锁指定的 dict-* release 下载，CI 逐个核对 SHA256SUMS.txt。词库损坏要立刻失败，而不是拖到测试里表现成「候选为空」这种难查的样子
• helpcodes/——六套辅助码方案，本仓 assets/tables 只有其中一套，得从 ../engine/helpcode/ 取全
• assets/tables/* 和 assets/config/config.toml

数据不全时的典型症状是候选查询返回空集，断言信息看起来像逻辑错误，实际是缺数据。排查测试失败前先确认数据根目录是齐的。

IPC 线格式、opcode 和语音分帧的唯一实现位于 ../engine/contracts/——引擎已内嵌进本仓，和 Server 在同一个提交里；本仓的 src/ipc/ipc.h 只保留连接状态和 Server API。不要重新复制协议定义。共享头的 ABI 断言随主工程编译，主连接必须通过 NegotiateMainPipeClient 后才能激活；旧 DLL 的未版本化 hello 仍兼容，版本化客户端会收到关联 request_id 的协议确认。

改了协议或候选逻辑，正常构建并备好数据之后自己跑一次：

# scripts/lcompile-release.ps1 默认只构建 MetasequoiaImeServer 目标（打包用的那一套），
# 不含测试可执行文件。要跑 ctest 就得显式构建全部：
.\scripts\lcompile-release.ps1 -Target ALL_BUILD
ctest --test-dir build-release -C Release --output-on-failure

uiAccess 与 Topmost 时序

MetasequoiaImeServer.manifest 用 requestedExecutionLevel level="asInvoker" uiAccess="true"，浮层才能盖在高完整性宿主之上。uiAccess 真正生效还依赖正确签名和安装在 Windows 认可的位置，清单、签名、安装路径是同一套发布约定。

进程在 src/main.cpp:90 设 DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2。

三个小窗口的置顶由 src/window/small_windows.cpp 统一管理：建窗时不带 WS_EX_TOPMOST，以 DWM cloak 状态显示在真实显示器上；第一次真正显示时 EnsureSmallWindowsTopmost 打开置顶门，候选窗、悬浮工具栏、托盘菜单按固定间隔依次提升到 HWND_TOPMOST，托盘菜单最后（同一置顶带里后置顶的在上面）。这个分阶段顺序沿用自已移除的 WebView2 时期，D2D 窗口一直按它发布；要改成一次性置顶，先在签名并安装到受信位置的构建上验证 uiAccess 下的表现。不要在布局函数里随手传 HWND_TOPMOST 绕过这道门；托盘菜单需要回到最上面时用 RaiseTrayMenuAboveSmallWindows。

隐藏候选窗用 cloak 而不是 SW_HIDE，presenter 在下一次显示时解除 cloak；悬浮工具栏在 presenter 绑定失败时只 cloak 不 hide。

Boost

CMakeLists.txt:13 的 Boost_ROOT 是有守卫的：设了 BOOST_ROOT 环境变量就用环境变量，否则回退到作者本机路径。这是有意的，不要改成只认环境变量，那会破坏作者的本地环境。CI 就是靠设这个环境变量工作的。

Boost 是静态链接但没有写进 vcpkg.json，所以只能用 classic 模式装，且 triplet 必须是 x64-windows-static-md 而不是 x64-windows-static——Boost_USE_STATIC_LIBS ON 要静态 Boost 库，而项目其余部分用动态 CRT，纯 static triplet 会让 Boost 也切到静态 CRT，链接时报 LNK2038。

生成文件

scripts/prepare_env.py 只生成本目录的 .clangd（从 scripts/config_files/.clangd 模板展开）。测试使用 Server 主工程及同一套 preset，不再生成独立的 tests/CMakePresets.json。CMakePresets.json 是原地改写 VCPKG_ROOT 与 CMAKE_TOOLCHAIN_FILE，不再从模板覆盖。

CMakeLists.txt 和 tests/CMakeLists.txt 不再由脚本生成，直接改就行。这两个文件曾经也是从 scripts/config_files/ 覆盖过来的，但模板早已落后到 147 行对 400 行、以及一个无关的通用 WinCppTemplate，跑一次脚本就会毁掉构建，因此模板已删除。

.clangd 模板用 @NAME@ 占位符，不再按固定行号替换——旧的行号索引已经漂移过一次，把 Boost 路径写到了别的 include 上。新增 include 时在模板里加占位符、并在脚本的 clangd_substitutions 里补上对应项即可；有占位符没被替换脚本会直接报错。

提交

提交信息用 type(scope): 摘要。不要添加 Co-Authored-By、Generated with 或其他 AI 生成标记。

窗口与设置窗口的维护边界

• 界面只有 Direct2D 一套：候选窗、悬浮工具栏和托盘菜单的 HWND、尺寸、位置、显示、DPI、Z-order 在 src/window/（ime_windows*.cpp 是宿主窗口过程，*_presenter.cpp 用 msimeui 绘制）。WebView2 已整体移除，appearance.ui_backend / appearance.settings_ui_backend 两个键也随之删除，不要恢复。
• 候选内容和输入状态的权威仍在 Server/引擎，presenter 只负责展示与发出用户动作；不要在界面侧复制 候选选择、翻页、输入模式或配置持久化的核心状态机。
• 设置窗口是独立进程 MetasequoiaImeSettings.exe（src/settings/）：原生创建、激活、驻留和配置 读写映射在 settings_app.cpp，界面在 src/settings/native/，图片资源在 assets/settings/（安装到 数据目录的 assets\settings\）。界面与宿主之间走 ../engine/contracts/webview/ 的消息契约：宿主推送 configSnapshot 与各类响应，界面发 configUpdate 与请求，统一进 HandleClientMessage 校验和分发， 配置读写映射只在 settings_app.cpp。每个 native_page_*.cpp 顶部注明了它当初移植自旧网页设置页的 哪个 partial / module，那些文件只在 git 历史里（ui-html/webview2/settings/ime-settings/src/）。 本地调试时可设 METASEQUOIA_IME_SETTINGS_INSTANCE=<任意名> 让开发版与已安装的设置窗口并存， 并用 METASEQUOIA_IME_CONFIG_DIR 隔离配置。旧快捷方式传来的 --d2d / --webview2 参数会被忽略。

尺寸、坐标与 DPI

• 所有涉及尺寸或坐标的代码都必须明确考虑 DPI。新增或修改窗口大小、位置、边距、间距、字体、 图标、命中区域、候选布局及屏幕边界计算时，不得默认固定像素在所有显示器上等价。
• 明确每个数值使用逻辑单位还是物理像素，并在正确的窗口/显示器 DPI 下统一换算；不要混用来自不同 DPI 空间的坐标和尺寸，也不要长期缓存可能在窗口跨屏或 DPI 变化后失效的换算结果。
• 原生窗口需处理运行时 DPI 变化（包括跨显示器移动），同步更新窗口、子窗口和相关布局；优先沿用项目已有的 DPI 获取与缩放辅助函数，避免各处自行实现不一致的换算规则。
• 涉及尺寸或布局的改动，至少检查 100%、125%、150%、200% 缩放，以及不同 DPI 显示器之间移动时 是否出现裁切、错位、模糊、点击区域偏移或窗口越出工作区。