Tauri 2 + React 19：前端位于 src/，Rust 后端位于 src-tauri/，插件位于 packages/。推荐 Harness 内核：0.2.1-rc.2；最低支持内核：0.1.7-rc.1。更早内核不再支持，旧兼容日志只记录历史，不构成当前支持承诺；本轮范围见当前兼容记录。
修改前先读 AGENTS.md 与路由规范。禁止查看受限归档目录，插件改动期间禁止执行构建。
| 工具 | 要求 / 来源 |
|---|---|
| Node.js | 托管运行时要求 22.22.0+，CI 使用 Node 22.x（清单、CI 配置） |
| pnpm | 11.7.0，由 package.json 固定 |
| Rust | 1.93+，推荐当前 stable；本地修补的通知 crate 声明了该最低版本。 |
| 平台 | 编译工具链 |
|---|---|
| Windows | MSVC C++ 构建工具与 WebView2 |
| macOS | Xcode 16+、Swift 6；通知后端不能仅靠 Command Line Tools 编译（Cargo.toml） |
| Linux | WebKit2GTK 4.1 开发库；CI 安装 libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf（CI） |
macOS 运行时最低版本为 12+，Web 界面需要 Safari 17.4+ 能力。Linux 运行问题的处理见在线文档。
在仓库根目录执行：
| 命令 | 用途 |
|---|---|
pnpm install |
安装工作区依赖 |
pnpm dev |
仅启动 Vite 前端 |
pnpm dev:plugins |
监听插件；修改时复用已有 watcher |
pnpm tauri dev |
调试桌面端；通过 beforeDevCommand 启动 Vite |
pnpm dev:desktop |
插件监听与桌面组合命令；& 行为取决于 shell |
pnpm typecheck |
前端 TypeScript 检查 |
pnpm lint |
ESLint |
跨平台开发建议分别在两个终端运行插件 watcher 与 pnpm tauri dev。
pnpm typecheck 通过 tsconfig.typecheck.json 检查工作区包源码，因此全新检出后只需 pnpm install，不依赖生成的声明文件或插件 watcher。构建和运行时仍通过包 exports 解析；CI 会单独构建共享包并验证其产物入口。
构建保护： AGENTS.md 禁止在插件改动期间执行构建。pnpm build:plugins、pnpm build、pnpm build:debug、pnpm tauri build 仅用于明确的产物准备 / 发布；pnpm build 还会触发插件 prebuild。
package.json 中的测试脚本对应以下显式非 watch 命令（测试规范）：
| 脚本 | 直接执行命令 |
|---|---|
test |
node node_modules/vitest/vitest.mjs run |
test:unit |
node node_modules/vitest/vitest.mjs run --project unit |
test:e2e:plugin |
node node_modules/vitest/vitest.mjs run --project plugin |
test:e2e:desktop |
node node_modules/vitest/vitest.mjs run --project desktop |
E2E 需要已准备好的夹具与运行时，桌面测试还需要 Debug 二进制。请遵循插件测试指南与桌面测试指南；不要仅为验证文档或插件修改触发构建。
Rust 检查（仓库根目录）：
cargo check --manifest-path src-tauri/Cargo.toml --locked
cargo test --manifest-path src-tauri/Cargo.toml --all-features --locked文档修改使用 git diff --check。测试数据必须隔离，不能使用真实用户档案。
桌面端启动时对兼容的托管聊天包施加补丁（#1114）：聊天和进程组的跟随滚动在 DSH 文档根节点存在 data-reduce-motion 或系统开启 prefers-reduced-motion: reduce 时，通过原有 jump 即时落位并取消正在进行的平滑滚动。常规启动、早启动与 --patch-core 均覆盖；缺文件或上游锚点变化时记录日志并跳过，不修改未知版本。
该属性由部署方设置；本补丁不默认禁用动画，不注入 CSS，也不实现 ?reduce-motion=0 或浏览器记忆。官方页面没有该属性且系统未要求减弱时，原有平滑行为保持不变。部署方应在 DSH 页面 / 帧 内设置；临时验证可在对应控制台执行 document.documentElement.setAttribute('data-reduce-motion', '')。属性值为 0 或 false 仍表示存在；恢复用 document.documentElement.removeAttribute('data-reduce-motion')，且系统偏好也必须关闭。手动设置不跨刷新保存，下一次跟随调用才读取新状态。
回归测试对比原版与生产替换体；Rust 测试执行真实 apply_at 文件产物上的同一套 JavaScript 契约。它们验证逻辑，不代表 M5 / 多屏 GPU 实测，也不覆盖完整浏览器分页界面；性能结论仍需同设备前后对照。
#1187 报告 macOS WKWebView 里滚动与指针移动慢半拍，同一页面在 Chrome 正常。兼容聊天包用 [data-conversation-scroll]:has(.EvIC1a_root[data-chat-following-tail]) 决定 overflow-anchor: none，跟随期间滚动容器内每次节点移除都会让 WebKit 对整棵会话子树重做选择器匹配。桌面端补丁在 ScrollFollow.bind / setFollowing 里把跟随意图镜像到外层 [data-conversation-scroll]，规则换成普通属性选择器。同一滚动容器可能有多个跟随实例（主会话、过程分组），属性由仍在前台跟随的实例共同决定，只在结果变化时写；解绑时按剩余实例重算。最佳努力、幂等、锚点缺失跳过与上文一致；回归测试对原版与补丁后的类跑同一套镜像契约。
| 模式 | Harness 数据 | Store | 默认回环端口 |
|---|---|---|---|
| Debug | ~/.dsh.dev |
.store.dev.dat |
3081 |
| Release | ~/.dsh |
.store.dat |
3080 |
- Debug 的运行时、内核与依赖位于
<AppData>/dev/；日志为<AppData>/dev/logs/dsh-web.dev.log。 - Debug 忽略继承的
DSH_HOME，固定使用~/.dsh.dev，不迁移正式版数据或修改生产 CLI PATH。 - 正式版数据目录由用户级
DSH_HOME决定（未设置时是~/.dsh）。Windows 安装器可直接设置该变量；三个平台的「设置 → 数据目录」都能复制数据、校验副本、把旧目录改名保底并改写变量；回滚会用该改名目录还原到原位置。 - 该变量的持久化方式按平台不同：Windows 写
HKCU\Environment；macOS 写~/Library/LaunchAgents/dsh-tauri.env.plist，由 LaunchAgent 在登录时重放launchctl setenv（plist 自带的EnvironmentVariables键到不了 Finder/Dock 启动的应用）；Linux 写~/.config/environment.d/dsh-tauri.conf与~/.profile里的标记块。由 launchd 或显示管理器启动的 GUI 应用不继承登录 shell 的环境，因此应用启动时还会自己从磁盘回读一次该变量。 - 端口可配置，占用时可能回退；不保证并行启动时始终使用上述值。
- 档案隔离的是配置，不是操作系统权限。