feat: add SCUT Senior documentation and debugging scripts

.gitignore

@@ -84,4 +84,5 @@ apps/tools/material_converter/.work/
 apps/tools/material_converter/.ai_jobs/
 
 #private docs
-apps/scut-senior/doc/*
+apps/scut-senior/doc/*
+apps/scut-senior/docs/knowledge/*

apps/scut-senior/README.md

@@ -186,6 +186,25 @@ cd apps/scut-senior/web
 npm run dev
 ```
 
+Windows 两进程调试可直接运行（只加载 `.local/env.online`，不使用 `.ps1`）：
+
+```cmd
+cd apps\scut-senior
+scripts\debug-windows.cmd
+```
+
+一键启动 API、Vite、Funnel 并打开公网页面：
+
+```cmd
+scripts\start-all-windows.cmd
+```
+
+需要同时启用 Tailscale Funnel 时，请从管理员终端运行：
+
+```cmd
+scripts\debug-windows.cmd --funnel
+```
+
 默认 API 为 `http://127.0.0.1:8000`，Vite 开发服务器代理 `/api`。本地 SQLite、上传附件、日志和缓存写入 `apps/scut-senior/.local/`，不会提交到 Git。
 
 ## 常用命令
@@ -298,4 +317,4 @@ git sparse-checkout init --cone
 git sparse-checkout set apps/scut-senior .github README.md .gitignore .gitattributes
 git checkout master
 ```
-维护清理由进程内调度器执行，启动时补扫并按固定间隔清理到期会话、历史、反馈、私人材料、贡献记录和额度事件。清理步骤彼此隔离，单个存储步骤异常不会阻断同一轮其他步骤。
+维护清理由进程内调度器执行，启动时补扫并按固定间隔清理到期会话、历史、反馈、私人材料、贡献记录和额度事件。清理步骤彼此隔离，单个存储步骤异常不会阻断同一轮其他步骤。

apps/scut-senior/scripts/debug-windows.cmd

@@ -0,0 +1,48 @@
+@echo off
+setlocal
+
+for %%I in (git.exe) do set "GIT_EXE=%%~$PATH:I"
+if not defined GIT_EXE (
+  echo [ERROR] Git was not found on PATH.
+  exit /b 1
+)
+
+for %%I in ("%GIT_EXE%") do set "GIT_CMD_DIR=%%~dpI"
+for %%I in ("%GIT_CMD_DIR%..") do set "GIT_ROOT=%%~fI"
+set "BASH_EXE=%GIT_ROOT%\bin\bash.exe"
+for %%I in ("%~dp0..") do set "APP_ROOT=%%~fI"
+
+if not exist "%BASH_EXE%" (
+  echo [ERROR] Git Bash was not found at "%BASH_EXE%".
+  exit /b 1
+)
+if not exist "%APP_ROOT%\.local\env.online" (
+  echo [ERROR] Missing "%APP_ROOT%\.local\env.online".
+  exit /b 1
+)
+if not exist "%APP_ROOT%\api\.venv\Scripts\python.exe" (
+  echo [ERROR] Missing API virtual environment. Run uv sync first.
+  exit /b 1
+)
+if not exist "%APP_ROOT%\web\node_modules\.bin\vite.cmd" (
+  echo [ERROR] Missing Web dependencies. Run npm --prefix web ci first.
+  exit /b 1
+)
+
+if /I "%~1"=="--check" (
+  echo Environment and dependencies are ready.
+  exit /b 0
+)
+
+start "SCUT Senior API" /D "%APP_ROOT%" "%BASH_EXE%" -lc "set -a; source .local/env.online; set +a; export SCUT_SENIOR_RETRIEVAL_MODE=local_corpus; exec ./api/.venv/Scripts/python.exe -m uvicorn scut_senior_api.main:app --reload --host 127.0.0.1 --port 8000"
+start "SCUT Senior Web" /D "%APP_ROOT%\web" "%BASH_EXE%" -lc "exec ./node_modules/.bin/vite.cmd --host 0.0.0.0 --port 5173"
+
+if /I "%~1"=="--funnel" (
+  "C:\Program Files\Tailscale\tailscale.exe" funnel --bg 5173
+  "C:\Program Files\Tailscale\tailscale.exe" funnel status
+)
+
+echo API:  http://127.0.0.1:8000
+echo Web:  http://localhost:5173
+echo Test: curl.exe http://127.0.0.1:8000/api/v1/health
+endlocal

apps/scut-senior/scripts/start-all-windows.cmd

@@ -0,0 +1,49 @@
+@echo off
+setlocal
+
+for %%I in ("%~dp0..") do set "APP_ROOT=%%~fI"
+set "TAILSCALE_EXE=C:\Program Files\Tailscale\tailscale.exe"
+set "PUBLIC_URL=https://by9000p.tail26d033.ts.net/"
+
+call "%~dp0debug-windows.cmd" --check
+if errorlevel 1 exit /b 1
+
+if /I "%~1"=="--check" (
+  if not exist "%TAILSCALE_EXE%" (
+    echo [ERROR] Tailscale is not installed at "%TAILSCALE_EXE%".
+    exit /b 1
+  )
+  echo One-click startup prerequisites are ready.
+  exit /b 0
+)
+
+call "%~dp0debug-windows.cmd"
+if errorlevel 1 exit /b 1
+
+echo Configuring Tailscale Funnel for Vite on port 5173...
+"%TAILSCALE_EXE%" funnel --bg 5173 >nul 2>&1
+if errorlevel 1 (
+  echo Administrator approval is required for Tailscale Funnel.
+  powershell.exe -NoProfile -Command "Start-Process -FilePath '%TAILSCALE_EXE%' -Verb RunAs -ArgumentList 'funnel','--bg','5173' -Wait"
+  if errorlevel 1 (
+    echo [ERROR] Tailscale Funnel configuration failed.
+    exit /b 1
+  )
+)
+
+echo Waiting for API and Web readiness...
+for /L %%I in (1,1,30) do (
+  curl.exe --fail --silent --output NUL http://127.0.0.1:8000/api/v1/health 2>nul && curl.exe --fail --silent --output NUL http://127.0.0.1:5173/ 2>nul && goto ready
+  timeout /t 1 /nobreak >nul
+)
+
+echo [ERROR] Services did not become ready within 30 seconds.
+exit /b 1
+
+:ready
+echo.
+echo SCUT Senior is ready.
+echo Local:  http://localhost:5173/
+echo Public: %PUBLIC_URL%
+start "" "%PUBLIC_URL%"
+endlocal

apps/scut-senior/web/vite.config.ts

@@ -8,7 +8,7 @@ export default defineConfig(({ mode }) => {
   return {
     plugins: [vue()],
     server: {
-      allowedHosts: ["klose.tail26d033.ts.net"],
+      allowedHosts: ["by9000p.tail26d033.ts.net"],
       proxy: {
         "/api": {
           target: env.VITE_API_PROXY_TARGET || "http://127.0.0.1:8000",
@@ -21,4 +21,4 @@ export default defineConfig(({ mode }) => {
       include: ["src/**/*.test.ts"],
     },
   };
-});
+});