From a5a9746277c635a748258072e06f6e3910ac906e Mon Sep 17 00:00:00 2001 From: "HYD@OVERTON" Date: Tue, 8 Sep 2026 00:57:15 +0800 Subject: [PATCH 1/2] docs: explain Windows and WSL development environments --- docs/development.i18n.yaml | 4 ++-- docs/development.md | 8 ++++++++ docs/development.zh.md | 8 ++++++++ 3 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml index 71b047fa7a..259d794ad3 100644 --- a/docs/development.i18n.yaml +++ b/docs/development.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/development.md -development.md: 37028720ff2487a81caecb8b2e2c6e5bc26b2df5 -development.zh.md: 01e3e88605cb4f9ea0b14df4a0099f436c48c5e9 +development.md: ce8f1e7746562e696c96e6359ec9fcfde596d6e2 +development.zh.md: 61325cf256fbcfe4afc508b9c6894191c486a881 diff --git a/docs/development.md b/docs/development.md index 37028720ff..ce8f1e7746 100644 --- a/docs/development.md +++ b/docs/development.md @@ -13,6 +13,14 @@ The setup tutorial takes a new contributor from prerequisites to a checked check - Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension. - Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests. +### Windows and WSL 2 + +On Windows, you can develop with native tools or use WSL 2 for a Linux environment. WSL 2 is useful for verifying Linux behavior and for using Linux toolchains when native dependency compilation or filesystem permissions obstruct Windows development. Each environment needs its own runtime, build tools, and permissions; WSL is optional. + +Keep the checkout, installed dependencies, and toolchain in the same operating system environment. For WSL 2, store the checkout in the Linux filesystem; for native Windows tools, use the Windows filesystem. Accessing files across the two filesystems adds overhead to I/O-intensive operations such as Git, dependency installation, and builds. See Microsoft's [file storage and performance guidance](https://learn.microsoft.com/en-us/windows/wsl/filesystems#file-storage-and-performance-across-file-systems). + +Install dependencies separately in each environment because native binaries and links can differ between operating systems. Test results apply to the environment where the tests ran; Windows-specific behavior still needs native Windows validation. + ### First-time setup Install dependencies from the repo root: diff --git a/docs/development.zh.md b/docs/development.zh.md index 01e3e88605..61325cf256 100644 --- a/docs/development.zh.md +++ b/docs/development.zh.md @@ -15,6 +15,14 @@ - Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。 - 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。 +### Windows 与 WSL 2 + +在 Windows 上，可以使用原生工具开发，也可以通过 WSL 2 使用 Linux 环境。需要验证 Linux 行为，或原生依赖编译、文件系统权限阻碍 Windows 开发时，WSL 2 提供了使用 Linux 工具链的途径。每种环境都需要准备相应的运行时、编译工具和权限；WSL 是可选项。 + +将检出目录、已安装的依赖和工具链放在同一操作系统环境中。使用 WSL 2 时，将检出目录放在 Linux 文件系统中；使用 Windows 原生工具时，则使用 Windows 文件系统。跨两种文件系统访问会给 Git、依赖安装和构建等 I/O 密集型操作增加开销。参见微软的[文件存储与性能指南](https://learn.microsoft.com/en-us/windows/wsl/filesystems#file-storage-and-performance-across-file-systems)。 + +在每种环境中分别安装依赖，因为不同操作系统使用的原生二进制和链接可能不同。测试结果适用于执行测试的环境；Windows 特有行为仍需在原生 Windows 上验证。 + ### 首次搭建 在仓库根目录安装依赖： From 76235ecfb70e62ecb6a404496b482691f374b439 Mon Sep 17 00:00:00 2001 From: "HYD@OVERTON" Date: Tue, 8 Sep 2026 09:36:19 +0800 Subject: [PATCH 2/2] docs: align Chinese WSL use cases with English --- docs/development.i18n.yaml | 2 +- docs/development.zh.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml index 259d794ad3..8959b05a1d 100644 --- a/docs/development.i18n.yaml +++ b/docs/development.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/development.md development.md: ce8f1e7746562e696c96e6359ec9fcfde596d6e2 -development.zh.md: 61325cf256fbcfe4afc508b9c6894191c486a881 +development.zh.md: 85e95946dfd7210201f0807880d5ed1a92859356 diff --git a/docs/development.zh.md b/docs/development.zh.md index 61325cf256..85e95946df 100644 --- a/docs/development.zh.md +++ b/docs/development.zh.md @@ -17,7 +17,7 @@ ### Windows 与 WSL 2 -在 Windows 上，可以使用原生工具开发，也可以通过 WSL 2 使用 Linux 环境。需要验证 Linux 行为，或原生依赖编译、文件系统权限阻碍 Windows 开发时，WSL 2 提供了使用 Linux 工具链的途径。每种环境都需要准备相应的运行时、编译工具和权限；WSL 是可选项。 +在 Windows 上，可以使用原生工具开发，也可以通过 WSL 2 使用 Linux 环境。WSL 2 既可用于验证 Linux 行为，也可在原生依赖编译或文件系统权限阻碍 Windows 开发时提供使用 Linux 工具链的途径。每种环境都需要准备相应的运行时、编译工具和权限；WSL 是可选项。 将检出目录、已安装的依赖和工具链放在同一操作系统环境中。使用 WSL 2 时，将检出目录放在 Linux 文件系统中；使用 Windows 原生工具时，则使用 Windows 文件系统。跨两种文件系统访问会给 Git、依赖安装和构建等 I/O 密集型操作增加开销。参见微软的[文件存储与性能指南](https://learn.microsoft.com/en-us/windows/wsl/filesystems#file-storage-and-performance-across-file-systems)。