diff --git a/AGENTS.md b/AGENTS.md
index e9b152e..6d4b5ea 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,9 +34,9 @@
 
 | 允许并行（纯读取） | 禁止并行（产出/锁文件） |
 |---|---|
-| rg, ls, Get-Content, 读日志 | build-and-deploy, compile, deploy, run-unit-tests, 启动 NW |
+| rg, ls, Get-Content, 读日志 | build-and-deploy, compile, deploy, run-unit-tests, run-integration-tests, 启动 NW |
 
-`run-unit-tests → build-and-deploy` 是单通道流水线，不可拆分并行。
+`run-unit-tests → build-and-deploy` 是单通道流水线，不可拆分并行。`run-integration-tests.bat` 依赖主 NW 实例就绪（HTTP 18777），需先 `build-and-deploy` + 启动 NW。
 
 ### 路径
 
@@ -201,6 +201,16 @@ pwsh -NoProfile -Command "./build-and-deploy.bat"
 
 > 历史背景：早期默认 shell 有 UTF-8 乱码问题才统一用 pwsh；已配置 Git Bash 后不再需要。
 
+### 测试脚本
+
+- `./run-unit-tests.bat` — 仅单元测试（不启动 NW，TestCategory!=NavisworksIntegration）
+- `./run-integration-tests.bat [过滤器]` — 集成测试：
+  - 无参数 = 全量集成测试（`TestCategory=NavisworksIntegration`，约 1 分半）
+  - 带参数 = 子集，如 `pwsh -NoProfile -Command "./run-integration-tests.bat FullyQualifiedName~RealObjectAnimation"`
+  - **前置**：主 NW 已启动且插件 HTTP 服务就绪（127.0.0.1:18777）；未就绪会明确报错提示
+  - 脚本自动：编译测试项目、查找 MSBuild/VSTEST/MSTest adapter、追加 Navisworks API 到 PATH
+  - 注意：bat 文件必须 CRLF 行尾 + GBK 编码（cmd 解析），编辑后如出现乱码/语法错用 iconv + python 转
+
 ### edit 工具的正确格式
 
 ```json
diff --git a/run-integration-tests.bat b/run-integration-tests.bat
new file mode 100644
index 0000000..c59f924
--- /dev/null
+++ b/run-integration-tests.bat
@@ -0,0 +1,89 @@
+@echo off
+setlocal
+
+REM ============================================================
+REM  Integration tests runner (Navisworks plugin + HTTP 18777).
+REM
+REM  Usage:
+REM    run-integration-tests.bat                    -> full integration set
+REM    run-integration-tests.bat "<filter>"         -> subset (e.g. "FullyQualifiedName~RealObjectAnimation")
+REM
+REM  Prereq: main Navisworks instance loaded with plugin and
+REM          test HTTP service ready at 127.0.0.1:18777.
+REM          (start via start-navisworks.bat, or run build-and-deploy.bat
+REM          which launches Navisworks after deploy)
+REM ============================================================
+
+set FILTER=%1
+if "%FILTER%"=="" set FILTER=TestCategory=NavisworksIntegration
+
+echo Building NavisworksTransport.UnitTests (integration filter: %FILTER%)...
+
+set MSBUILD_PATH="C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"
+if not exist %MSBUILD_PATH% (
+    set MSBUILD_PATH="C:\Program Files\Microsoft Visual Studio\2022\Professional\MSBuild\Current\Bin\MSBuild.exe"
+)
+if not exist %MSBUILD_PATH% (
+    echo MSBuild not found. Please install Visual Studio 2022 or Build Tools.
+    exit /b 1
+)
+
+set VSTEST_PATH="C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\Extensions\TestPlatform\vstest.console.exe"
+if not exist %VSTEST_PATH% (
+    set VSTEST_PATH="C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\IDE\Extensions\TestPlatform\vstest.console.exe"
+)
+if not exist %VSTEST_PATH% (
+    echo vstest.console.exe not found. Please install Visual Studio 2022 test tools.
+    exit /b 1
+)
+
+REM ��̬���� MSTest adapter��������汾������Ӳ����·��ʧЧ��
+for /d %%d in ("packages\MSTest.TestAdapter.*") do set TEST_ADAPTER_BASE=%%~fd
+if not defined TEST_ADAPTER_BASE (
+    echo MSTest adapter package not found under packages\MSTest.TestAdapter.*
+    exit /b 1
+)
+set "TEST_ADAPTER_PATH=%TEST_ADAPTER_BASE%\build\net462"
+if not exist "%TEST_ADAPTER_PATH%" (
+    echo MSTest adapter net462 dir not found: %TEST_ADAPTER_PATH%
+    exit /b 1
+)
+
+set NAVISWORKS_PATH=C:\Program Files\Autodesk\Navisworks Manage 2026
+if not exist "%NAVISWORKS_PATH%\Autodesk.Navisworks.Api.dll" (
+    echo Navisworks API path not found: %NAVISWORKS_PATH%
+    exit /b 1
+)
+
+set PATH=%NAVISWORKS_PATH%;%PATH%
+
+%MSBUILD_PATH% "NavisworksTransport.UnitTests.csproj" /p:Configuration=Release /p:Platform=x64 /verbosity:minimal
+if errorlevel 1 (
+    echo Unit test build failed!
+    exit /b 1
+)
+
+REM --- ��ʵ��������飨HTTP 18777��---
+curl -s --max-time 3 http://127.0.0.1:18777/api/test/ping > "%TEMP%\nw_ping.json" 2>nul
+if errorlevel 1 goto notready
+findstr /C:"true" "%TEMP%\nw_ping.json" >nul
+if errorlevel 1 goto notready
+
+echo Main instance ready. Running integration tests (filter: %FILTER%)...
+
+goto runtests
+
+:notready
+echo.
+echo [ERROR] Main Navisworks test service not reachable at 127.0.0.1:18777.
+echo         Start it first via start-navisworks.bat (or build-and-deploy.bat).
+exit /b 1
+
+:runtests
+%VSTEST_PATH% "bin\x64\Release\NavisworksTransport.UnitTests.dll" /Platform:x64 /TestAdapterPath:%TEST_ADAPTER_PATH% /TestCaseFilter:"%FILTER%"
+if errorlevel 1 (
+    echo Integration tests failed!
+    exit /b 1
+)
+
+echo Integration tests passed!