fix(devdoc): Windows 合法资源路径 + 本地启动 bat 与说明

- 将误用 Markdown 语法的截图路径重命名为 截图1-占位说明图.png

- 新增 scripts/本地启动.bat；测试 README 补充 Windows 启动方式

- 新增 开发文档/Windows-资源命名与拉取.md

Made-with: Cursor

scripts/test/README.md

@@ -22,7 +22,10 @@ pip install -r requirements-test.txt
 pytest -v
 ```
 
-联调前请先执行 `scripts/本地启动.sh` 启动 soul-api 与 soul-admin。
+联调前请先启动 soul-api 与 soul-admin：
+
+- **macOS / Linux**：`bash scripts/本地启动.sh` 或 `./scripts/本地启动.sh`
+- **Windows**：双击或在仓库根目录执行 `scripts\本地启动.bat`（需已安装 Go、pnpm，且 Windows 10+ 自带 `curl` 用于健康检查）
 
 ---
 

scripts/本地启动.bat

@@ -0,0 +1,30 @@
+@echo off
+setlocal EnableExtensions
+cd /d "%~dp0.."
+set "ROOT=%CD%"
+
+echo ===== 1. 启动 soul-api（端口 8080）=====
+if not exist "%ROOT%\soul-api\soul-api.exe" (
+  echo 未找到 soul-api.exe，正在编译...
+  pushd "%ROOT%\soul-api" || exit /b 1
+  go build -o soul-api.exe .\cmd\server
+  if errorlevel 1 popd & exit /b 1
+  popd
+)
+
+start "soul-api" /B cmd /c "set APP_ENV=development&& set PORT=8080&& cd /d ""%ROOT%\soul-api""&& soul-api.exe"
+echo soul-api 已以后台窗口启动，本脚本继续检查健康状态…
+timeout /t 3 /nobreak >nul
+
+curl -sf http://localhost:8080/health >nul
+if errorlevel 1 (
+  echo soul-api 启动失败，请检查数据库连接与本机是否已安装 Go
+  exit /b 1
+)
+echo soul-api 健康检查通过
+
+echo.
+echo ===== 2. 启动 soul-admin（端口 5174）=====
+echo 访问 http://localhost:5174  默认账号 admin / admin123
+cd /d "%ROOT%\soul-admin" || exit /b 1
+pnpm dev

开发文档/Windows-资源命名与拉取.md

@@ -0,0 +1,25 @@
+# Windows 下开发文档与资源路径说明
+
+## 不要在仓库里用「Markdown 图片语法」当真实文件名
+
+曾出现将截图保存为类似 `…/images/![描述](./images/截图1.png`.png` 的路径：其中含 `/`、反引号等，在 Windows 上会导致 **无法克隆/拉取** 或与索引不一致。
+
+现已在 `开发文档/1、需求/修改/images/` 下改为规范文件名：**`截图1-占位说明图.png`**。
+
+## 若仍遇到 `invalid path` 拉取失败
+
+可临时放宽 NTFS 校验后拉取（本仓库已修正资源名后一般不再需要）：
+
+```bash
+git -c core.protectNTFS=false pull
+```
+
+或在当前仓库执行一次：
+
+```bash
+git config core.protectNTFS false
+```
+
+## 本地联调（Windows）
+
+除 `scripts/本地启动.sh` 外，可使用 **`scripts/本地启动.bat`** 启动 soul-api + soul-admin，详见 `scripts/test/README.md`。