重构(scripts): 整理scripts目录，按现架构分类并迁移性能/手动测试脚本

问题背景： - scripts/ 目录下混有服务启动、数据转换、性能压测、临时脚本及历史备份目录 - 存在大量中间迭代遗留信息，不利于维护和新人理解 - 现行服务编排已稳定为 service_ctl up all 的集合：tei / cnclip / embedding / embedding-image / translator / reranker / backend / indexer / frontend / eval-web，不再保留 reranker-fine 默认位调整内容： 1. 根 scripts/ 收敛为运行、运维、环境、数据处理脚本，并新增 scripts/README.md 说明文档 2. 性能/压测/调参脚本整体迁至 benchmarks/ 目录，同步更新 benchmarks/README.md 3. 人工试跑脚本迁至 tests/manual/ 目录，同步更新 tests/manual/README.md 4. 删除明确过时内容： - scripts/indexer__old_2025_11/ - scripts/start.sh - scripts/install_server_deps.sh 5. 同步修正以下文档中的路径及过时描述： - 根目录 README.md - 性能报告相关文档 - reranker/translation 模块文档技术细节： - 性能测试不放常规 tests/ 的原因：这类脚本依赖真实服务、GPU、模型和环境噪声，不适合作为稳定回归门禁；benchmarks/ 更贴合其定位 - tests/manual/ 仅存放需要人工启动依赖、手工观察结果的接口试跑脚本 - 所有迁移后的 Python 脚本已通过 py_compile 语法校验 - 所有迁移后的 Shell 脚本已通过 bash -n 语法校验校验结果： - py_compile: 通过 - bash -n: 通过

重构(scripts): 整理scripts目录，按现架构分类并迁移性能/手动测试脚本
问题背景： - scripts/ 目录下混有服务启动、数据转换、性能压测、临时脚本及历史备份目录 - 存在大量中间迭代遗留信息，不利于维护和新人理解 - 现行服务编排已稳定为 service_ctl up all 的集合：tei / cnclip / embedding / embedding-image / translator / reranker / backend / indexer / frontend / eval-web，不再保留 reranker-fine 默认位调整内容： 1. 根 scripts/ 收敛为运行、运维、环境、数据处理脚本，并新增 scripts/README.md 说明文档 2. 性能/压测/调参脚本整体迁至 benchmarks/ 目录，同步更新 benchmarks/README.md 3. 人工试跑脚本迁至 tests/manual/ 目录，同步更新 tests/manual/README.md 4. 删除明确过时内容： - scripts/indexer__old_2025_11/ - scripts/start.sh - scripts/install_server_deps.sh 5. 同步修正以下文档中的路径及过时描述： - 根目录 README.md - 性能报告相关文档 - reranker/translation 模块文档技术细节： - 性能测试不放常规 tests/ 的原因：这类脚本依赖真实服务、GPU、模型和环境噪声，不适合作为稳定回归门禁；benchmarks/ 更贴合其定位 - tests/manual/ 仅存放需要人工启动依赖、手工观察结果的接口试跑脚本 - 所有迁移后的 Python 脚本已通过 py_compile 语法校验 - 所有迁移后的 Shell 脚本已通过 bash -n 语法校验校验结果： - py_compile: 通过 - bash -n: 通过
tangwang
1 parent 048631be
Showing 53 changed files with 191 additions and 1437 deletions Show diff stats
CLAUDE.md
benchmarks/README.md
scripts/perf_api_benchmark.py -> benchmarks/perf_api_benchmark.py
scripts/perf_cases.json.example -> benchmarks/perf_cases.json.example
scripts/benchmark_reranker_1000docs.sh -> benchmarks/reranker/benchmark_reranker_1000docs.sh
scripts/benchmark_reranker_gguf_local.py -> benchmarks/reranker/benchmark_reranker_gguf_local.py
scripts/benchmark_reranker_random_titles.py -> benchmarks/reranker/benchmark_reranker_random_titles.py
tests/reranker_performance/curl1.sh -> benchmarks/reranker/manual/curl1.sh
tests/reranker_performance/curl1_simple.sh -> benchmarks/reranker/manual/curl1_simple.sh
tests/reranker_performance/curl2.sh -> benchmarks/reranker/manual/curl2.sh
tests/reranker_performance/rerank_performance_compare.sh -> benchmarks/reranker/manual/rerank_performance_compare.sh
scripts/patch_rerank_vllm_benchmark_config.py -> benchmarks/reranker/patch_rerank_vllm_benchmark_config.py
scripts/run_reranker_vllm_instruction_benchmark.sh -> benchmarks/reranker/run_reranker_vllm_instruction_benchmark.sh
scripts/smoke_qwen3_vllm_score_backend.py -> benchmarks/reranker/smoke_qwen3_vllm_score_backend.py
scripts/benchmark_nllb_t4_tuning.py -> benchmarks/translation/benchmark_nllb_t4_tuning.py
scripts/benchmark_translation_local_models.py -> benchmarks/translation/benchmark_translation_local_models.py
scripts/benchmark_translation_local_models_focus.py -> benchmarks/translation/benchmark_translation_local_models_focus.py
scripts/benchmark_translation_longtext_single.py -> benchmarks/translation/benchmark_translation_longtext_single.py
config/config.yaml
docs/DEVELOPER_GUIDE.md
@@ -77,9 +77,11 @@ source activate.sh
 # Generate test data (Tenant1 Mock + Tenant2 CSV)
 ./scripts/mock_data.sh
  
-# Ingest data to Elasticsearch
-./scripts/ingest.sh <tenant_id> [recreate]  # e.g., ./scripts/ingest.sh 1 true
-python main.py ingest data.csv --limit 1000 --batch-size 50
+# Create tenant index structure
+./scripts/create_tenant_index.sh <tenant_id>
+
+# Build / refresh suggestion index
+./scripts/build_suggestions.sh <tenant_id> --mode incremental
 ```
  
 ### Running Services
@@ -100,10 +102,10 @@ python main.py serve --host 0.0.0.0 --port 6002 --reload
 # Run all tests
 pytest tests/
  
-# Run specific test types
-pytest tests/unit/          # Unit tests
-pytest tests/integration/   # Integration tests
-pytest -m "api"             # API tests only
+# Run focused regression sets
+python -m pytest tests/ci -q
+pytest tests/test_rerank_client.py
+pytest tests/test_query_parser_mixed_language.py
  
 # Test search from command line
 python main.py search "query" --tenant-id 1 --size 10
@@ -114,12 +116,8 @@ python main.py search &quot;query&quot; --tenant-id 1 --size 10
 # Stop all services
 ./scripts/stop.sh
  
-# Test environment (for CI/development)
-./scripts/start_test_environment.sh
-./scripts/stop_test_environment.sh
-
-# Install server dependencies
-./scripts/install_server_deps.sh
+# Run CI contract tests
+./scripts/run_ci_tests.sh
 ```
  
 ## Architecture Overview
@@ -585,7 +583,7 @@ GET /admin/stats               # Index statistics
 ./scripts/start_frontend.sh # Frontend UI (port 6003)
  
 # Data Operations
-./scripts/ingest.sh <tenant_id> [recreate]  # Index data
+./scripts/create_tenant_index.sh <tenant_id> # Create tenant index
 ./scripts/mock_data.sh                    # Generate test data
  
 # Testing
@@ -0,0 +1,17 @@
+# Benchmarks
+
+基准压测脚本统一放在 `benchmarks/`，不再和 `scripts/` 里的服务启动/运维脚本混放。
+
+目录约定：
+
+- `benchmarks/perf_api_benchmark.py`：通用 HTTP 接口压测入口
+- `benchmarks/reranker/`：reranker 定向 benchmark、smoke、手工对比脚本
+- `benchmarks/translation/`：translation 本地模型 benchmark
+
+这些脚本默认不是 CI 测试的一部分，因为它们通常具备以下特征：
+
+- 依赖真实服务、GPU、模型或特定数据集
+- 结果受机器配置和运行时负载影响，不适合作为稳定回归门禁
+- 更多用于容量评估、调参和问题复现，而不是功能正确性判定
+
+如果某个性能场景需要进入自动化回归，应新增到 `tests/` 下并明确收敛输入、环境和判定阈值，而不是直接复用这里的基准脚本。
@@ -11,13 +11,13 @@ Default scenarios (aligned with docs/搜索API对接指南 分册，如 -01 / -0
 - rerank              POST /rerank
  
 Examples:
-  python scripts/perf_api_benchmark.py --scenario backend_search --duration 30 --concurrency 20 --tenant-id 162
-  python scripts/perf_api_benchmark.py --scenario backend_suggest --duration 30 --concurrency 50 --tenant-id 162
-  python scripts/perf_api_benchmark.py --scenario all --duration 60 --concurrency 80 --tenant-id 162
-  python scripts/perf_api_benchmark.py --scenario all --cases-file scripts/perf_cases.json.example --output perf_result.json
+  python benchmarks/perf_api_benchmark.py --scenario backend_search --duration 30 --concurrency 20 --tenant-id 162
+  python benchmarks/perf_api_benchmark.py --scenario backend_suggest --duration 30 --concurrency 50 --tenant-id 162
+  python benchmarks/perf_api_benchmark.py --scenario all --duration 60 --concurrency 80 --tenant-id 162
+  python benchmarks/perf_api_benchmark.py --scenario all --cases-file benchmarks/perf_cases.json.example --output perf_result.json
   # Embedding admission / priority (query param `priority`; same semantics as embedding service):
-  python scripts/perf_api_benchmark.py --scenario embed_text --embed-text-priority 1 --duration 30 --concurrency 20
-  python scripts/perf_api_benchmark.py --scenario embed_image --embed-image-priority 1 --duration 30 --concurrency 10
+  python benchmarks/perf_api_benchmark.py --scenario embed_text --embed-text-priority 1 --duration 30 --concurrency 20
+  python benchmarks/perf_api_benchmark.py --scenario embed_image --embed-image-priority 1 --duration 30 --concurrency 10
 """
  
 from __future__ import annotations
@@ -229,7 +229,7 @@ def apply_embed_priority_params(
 ) -> None:
     """
     Merge default `priority` query param into embed templates when absent.
-    `scripts/perf_cases.json` may set per-request `params.priority` to override.
+    `benchmarks/perf_cases.json` may set per-request `params.priority` to override.
     """
     mapping = {
         "embed_text": max(0, int(embed_text_priority)),
@@ -8,7 +8,7 @@
 # Outputs JSON reports under perf_reports/<date>/reranker_1000docs/
 #
 # Usage:
-#   ./scripts/benchmark_reranker_1000docs.sh
+#   ./benchmarks/reranker/benchmark_reranker_1000docs.sh
 # Optional env:
 #   BATCH_SIZES="24 32 48 64"
 #   C1_REQUESTS=4
@@ -85,7 +85,7 @@ run_bench() {
   local c="$2"
   local req="$3"
   local out="${OUT_DIR}/rerank_bs${bs}_c${c}_r${req}.json"
-  .venv/bin/python scripts/perf_api_benchmark.py \
+  .venv/bin/python benchmarks/perf_api_benchmark.py \
     --scenario rerank \
     --tenant-id "${TENANT_ID}" \
     --reranker-base "${RERANK_BASE}" \
@@ -8,8 +8,8 @@ Runs the backend directly in a fresh process per config to measure:
 - single-request rerank latency
  
 Example:
-  ./.venv-reranker-gguf/bin/python scripts/benchmark_reranker_gguf_local.py
-  ./.venv-reranker-gguf-06b/bin/python scripts/benchmark_reranker_gguf_local.py --backend-name qwen3_gguf_06b --docs 400
+  ./.venv-reranker-gguf/bin/python benchmarks/reranker/benchmark_reranker_gguf_local.py
+  ./.venv-reranker-gguf-06b/bin/python benchmarks/reranker/benchmark_reranker_gguf_local.py --backend-name qwen3_gguf_06b --docs 400
 """
  
 from __future__ import annotations
@@ -10,10 +10,10 @@ Each invocation runs 3 warmup requests with n=400 first; those are not timed for
  
 Example:
   source activate.sh
-  python scripts/benchmark_reranker_random_titles.py 386
-  python scripts/benchmark_reranker_random_titles.py 40,80,100
-  python scripts/benchmark_reranker_random_titles.py 40,80,100 --repeat 3 --seed 42
-  RERANK_BASE=http://127.0.0.1:6007 python scripts/benchmark_reranker_random_titles.py 200
+  python benchmarks/reranker/benchmark_reranker_random_titles.py 386
+  python benchmarks/reranker/benchmark_reranker_random_titles.py 40,80,100
+  python benchmarks/reranker/benchmark_reranker_random_titles.py 40,80,100 --repeat 3 --seed 42
+  RERANK_BASE=http://127.0.0.1:6007 python benchmarks/reranker/benchmark_reranker_random_titles.py 200
 """
  
 from __future__ import annotations
@@ -73,7 +73,7 @@ def main() -&gt; int:
     p.add_argument(
         "--config",
         type=Path,
-        default=Path(__file__).resolve().parent.parent / "config" / "config.yaml",
+        default=Path(__file__).resolve().parents[2] / "config" / "config.yaml",
     )
     p.add_argument("--backend", choices=("qwen3_vllm", "qwen3_vllm_score"), required=True)
     p.add_argument(
@@ -55,13 +55,13 @@ run_one() {
   local jf="${OUT_DIR}/${backend}_${fmt}.json"
  
   echo "========== ${tag} =========="
-  "$PYTHON" "${ROOT}/scripts/patch_rerank_vllm_benchmark_config.py" \
+  "$PYTHON" "${ROOT}/benchmarks/reranker/patch_rerank_vllm_benchmark_config.py" \
     --backend "$backend" --instruction-format "$fmt"
  
   "${ROOT}/restart.sh" reranker
   wait_health "$backend" "$fmt"
  
-  if ! "$PYTHON" "${ROOT}/scripts/benchmark_reranker_random_titles.py" \
+  if ! "$PYTHON" "${ROOT}/benchmarks/reranker/benchmark_reranker_random_titles.py" \
     100,200,400,600,800,1000 \
     --repeat 5 \
     --seed 42 \
@@ -82,7 +82,7 @@ run_one qwen3_vllm_score compact
 run_one qwen3_vllm_score standard
  
 # Restore repo-default-style rerank settings (score + compact).
-"$PYTHON" "${ROOT}/scripts/patch_rerank_vllm_benchmark_config.py" \
+"$PYTHON" "${ROOT}/benchmarks/reranker/patch_rerank_vllm_benchmark_config.py" \
   --backend qwen3_vllm_score --instruction-format compact
 "${ROOT}/restart.sh" reranker
 wait_health qwen3_vllm_score compact
@@ -3,7 +3,7 @@
 Smoke test: load Qwen3VLLMScoreRerankerBackend (must run as a file, not stdin — vLLM spawn).
  
 Usage (from repo root, score venv):
-  PYTHONPATH=. ./.venv-reranker-score/bin/python scripts/smoke_qwen3_vllm_score_backend.py
+  PYTHONPATH=. ./.venv-reranker-score/bin/python benchmarks/reranker/smoke_qwen3_vllm_score_backend.py
  
 Same as production: vLLM child processes need the venv's ``bin`` on PATH (for pip's ``ninja`` when
 vLLM auto-selects FLASHINFER on T4/Turing). ``start_reranker.sh`` exports that; this script prepends
@@ -20,8 +20,8 @@ import sys
 import sysconfig
 from pathlib import Path
  
-# Repo root on sys.path when run as scripts/smoke_*.py
-_ROOT = Path(__file__).resolve().parents[1]
+# Repo root on sys.path when run from benchmarks/reranker/.
+_ROOT = Path(__file__).resolve().parents[2]
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
  
@@ -11,12 +11,12 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, List, Tuple
  
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
 if str(PROJECT_ROOT) not in sys.path:
     sys.path.insert(0, str(PROJECT_ROOT))
  
 from config.services_config import get_translation_config
-from scripts.benchmark_translation_local_models import (
+from benchmarks.translation.benchmark_translation_local_models import (
     benchmark_concurrency_case,
     benchmark_serial_case,
     build_environment_info,
@@ -22,7 +22,7 @@ from typing import Any, Dict, Iterable, List, Sequence
 import torch
 import transformers
  
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
 if str(PROJECT_ROOT) not in sys.path:
     sys.path.insert(0, str(PROJECT_ROOT))
  
@@ -11,12 +11,12 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, List
  
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
 if str(PROJECT_ROOT) not in sys.path:
     sys.path.insert(0, str(PROJECT_ROOT))
  
 from config.services_config import get_translation_config
-from scripts.benchmark_translation_local_models import (
+from benchmarks.translation.benchmark_translation_local_models import (
     SCENARIOS,
     benchmark_concurrency_case,
     benchmark_serial_case,
@@ -13,7 +13,7 @@ from pathlib import Path
  
 import torch
  
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
  
 import sys
  
@@ -114,7 +114,7 @@ field_boosts:
   qanchors: 1.0
   enriched_tags: 1.0
   enriched_attributes.value: 1.5
-  enriched_taxonomy_attributes.value: 0.3
+  # enriched_taxonomy_attributes.value: 0.3
   category_name_text: 2.0
   category_path: 2.0
   keywords: 2.0
@@ -195,7 +195,7 @@ query_config:
     - qanchors
     - enriched_tags
     - enriched_attributes.value
-    - enriched_taxonomy_attributes.value
+    # - enriched_taxonomy_attributes.value
     - option1_values
     - option2_values
     - option3_values
@@ -254,7 +254,7 @@ query_config:
   # - qanchors
   # - enriched_tags
   # - enriched_attributes
-  # - enriched_taxonomy_attributes.value
+  # - # enriched_taxonomy_attributes.value
   - min_price
   - compare_at_price
   - image_url
@@ -389,7 +389,7 @@ services:
 - **位置**：`tests/`，可按 `unit/`、`integration/` 或按模块划分子目录；公共 fixture 在 `conftest.py`。
 - **标记**：使用 `@pytest.mark.unit`、`@pytest.mark.integration`、`@pytest.mark.api` 等区分用例类型，便于按需运行。
 - **依赖**：单元测试通过 mock（如 `mock_es_client`、`sample_search_config`）不依赖真实 ES/DB；集成测试需在说明中注明依赖服务。
-- **运行**：`python -m pytest tests/`；仅单元：`python -m pytest tests/unit/` 或 `-m unit`。
+- **运行**：`python -m pytest tests/`；推荐最小回归：`python -m pytest tests/ci -q`；按模块聚焦可直接指定具体测试文件。
 - **原则**：新增逻辑应有对应测试；修改协议或配置契约时更新相关测试与 fixture。
  
 ### 8.3 配置与环境
@@ -69,7 +69,7 @@ source activate.sh
 ./run.sh all
 # 仅为薄封装：等价于 ./scripts/service_ctl.sh up all
 # 说明：
-# - all = tei cnclip embedding embedding-image translator reranker reranker-fine backend indexer frontend eval-web
+# - all = tei cnclip embedding embedding-image translator reranker backend indexer frontend eval-web
 # - up 会同时启动 monitor daemon（运行期连续失败自动重启）
 # - reranker 为 GPU 强制模式（资源不足会直接启动失败）
 # - TEI 默认使用 GPU；当 TEI_DEVICE=cuda 且 GPU 不可用时会直接失败（不会自动降级到 CPU）
@@ -126,7 +126,7 @@ cd /data/saas-search
  
 这个脚本会自动：
 1. 创建日志目录
-2. 按目标启动服务（`all`：`tei cnclip embedding embedding-image translator reranker reranker-fine backend indexer frontend eval-web`）
+2. 按目标启动服务（`all`：`tei cnclip embedding embedding-image translator reranker backend indexer frontend eval-web`）
 3. 写入 PID 到 `logs/*.pid`
 4. 执行健康检查
 5. 启动 monitor daemon（运行期连续失败自动重启）
@@ -202,7 +202,7 @@ python -m pytest -q tests/test_rerank_client.py tests/test_es_query_builder.py t
 ./scripts/service_ctl.sh restart backend
 sleep 3
 ./scripts/service_ctl.sh status backend
-./scripts/evaluation/start_eval.sh.sh batch
+./scripts/evaluation/start_eval.sh batch
 ```
  
 离线批量评估会把标注与报表写到 `artifacts/search_evaluation/`（SQLite、`batch_reports/` 下的 JSON/Markdown 等）。说明与命令见 [scripts/evaluation/README.md](../scripts/evaluation/README.md)。
@@ -129,7 +129,7 @@ instruction: &quot;Given a shopping query, rank product titles by relevance&quot;
   - 可选：embedding(text) **6005**、embedding-image **6008**、translator **6006**、reranker **6007**、tei **8080**、cnclip **51000**。
   - 端口可由环境变量覆盖：`API_PORT`、`INDEXER_PORT`、`FRONTEND_PORT`、`EVAL_WEB_PORT`、`EMBEDDING_TEXT_PORT`、`EMBEDDING_IMAGE_PORT`、`TRANSLATION_PORT`、`RERANKER_PORT`、`TEI_PORT`、`CNCLIP_PORT`。
 - **命令**：
-  - `./scripts/service_ctl.sh start [service...]` 或 `up all` / `start all`（all 含 tei、cnclip、embedding、embedding-image、translator、reranker、reranker-fine、backend、indexer、frontend、eval-web，按依赖顺序）；`stop`、`restart`、`down` 同参数；`status` 默认列出所有服务。
+  - `./scripts/service_ctl.sh start [service...]` 或 `up all` / `start all`（all 含 tei、cnclip、embedding、embedding-image、translator、reranker、backend、indexer、frontend、eval-web，按依赖顺序）；`stop`、`restart`、`down` 同参数；`status` 默认列出所有服务。
   - 启动时：backend/indexer/frontend/embedding/translator/reranker 会写 pid 到 `logs/<service>.pid`，并执行 `wait_for_health`（GET `http://127.0.0.1:<port>/health`）；reranker 健康重试 90 次，其余 30 次；TEI 校验 Docker 容器存在且 `/health` 成功；cnclip 无 HTTP 健康则仅校验进程/端口。
 - **监控常驻**：
   - `./scripts/service_ctl.sh monitor-start <targets>` 启动后台监控进程，将 targets 写入 `logs/service-monitor.targets`，pid 写入 `logs/service-monitor.pid`，日志追加到 `logs/service-monitor.log`。
@@ -153,12 +153,12 @@ instruction: &quot;Given a shopping query, rank product titles by relevance&quot;
  
 ## 三、性能测试报告摘要
  
-以下数据来自 `docs/性能测试报告.md`，测试时间 **2026-03-12**，环境：**8 vCPU**（Intel Xeon Platinum 8255C @ 2.50GHz）、**约 15Gi 可用内存**；租户 **162** 文档数约 **53**（search/search/suggestions/rerank 与文档规模相关）。压测工具：`scripts/perf_api_benchmark.py`，场景×并发矩阵，每档 **20s**。
+以下数据来自 `docs/性能测试报告.md`，测试时间 **2026-03-12**，环境：**8 vCPU**（Intel Xeon Platinum 8255C @ 2.50GHz）、**约 15Gi 可用内存**；租户 **162** 文档数约 **53**（search/search/suggestions/rerank 与文档规模相关）。压测工具：`benchmarks/perf_api_benchmark.py`，场景×并发矩阵，每档 **20s**。
  
 **复现命令（四场景×四并发）**：
 ```bash
 cd /data/saas-search
-.venv/bin/python scripts/perf_api_benchmark.py \
+.venv/bin/python benchmarks/perf_api_benchmark.py \
   --scenario backend_search,backend_suggest,embed_text,rerank \
   --concurrency-list 1,5,10,20 \
   --duration 20 \
@@ -188,7 +188,7 @@ cd /data/saas-search
  
 口径：query 固定 `wireless mouse`，每次请求 **386 docs**，句长 15–40 词随机（从 1000 词池采样）；配置 `rerank_window=384`。复现命令：
 ```bash
-.venv/bin/python scripts/perf_api_benchmark.py \
+.venv/bin/python benchmarks/perf_api_benchmark.py \
   --scenario rerank --duration 20 --concurrency-list 1,5,10,20 --timeout 60 \
   --rerank-dynamic-docs --rerank-doc-count 386 --rerank-vocab-size 1000 \
   --rerank-sentence-min-words 15 --rerank-sentence-max-words 40 \
@@ -217,7 +217,7 @@ cd /data/saas-search
 | 10   | 181   | 100%  | 8.78      | 1129.23| 1295.88| 1330.96|
 | 20   | 161   | 100%  | 7.63      | 2594.00| 4706.44| 4783.05|
  
-**结论**：吞吐约 **8 rps** 平台化，延迟随并发上升明显，符合“检索 + 向量 + 重排”重链路特征。多租户补测（文档数 500–10000，见报告 §12）表明：文档数越大，RPS 下降、延迟升高；tenant 0（10000 doc）在并发 20 出现部分 ReadTimeout（成功率 59.02%），需注意 timeout 与容量规划；补测命令示例：`for t in 0 1 2 3 4; do .venv/bin/python scripts/perf_api_benchmark.py --scenario backend_search --concurrency-list 1,5,10,20 --duration 20 --tenant-id $t --output perf_reports/2026-03-12/search_tenant_matrix/tenant_${t}.json; done`。
+**结论**：吞吐约 **8 rps** 平台化，延迟随并发上升明显，符合“检索 + 向量 + 重排”重链路特征。多租户补测（文档数 500–10000，见报告 §12）表明：文档数越大，RPS 下降、延迟升高；tenant 0（10000 doc）在并发 20 出现部分 ReadTimeout（成功率 59.02%），需注意 timeout 与容量规划；补测命令示例：`for t in 0 1 2 3 4; do .venv/bin/python benchmarks/perf_api_benchmark.py --scenario backend_search --concurrency-list 1,5,10,20 --duration 20 --tenant-id $t --output perf_reports/2026-03-12/search_tenant_matrix/tenant_${t}.json; done`。
  
 ---
  
@@ -247,5 +247,5 @@ cd /data/saas-search
  
 **关键文件与复现**：
 - 配置：`config/config.yaml`（services、rerank、query_config）、`.env`（端口与 API Key）。
-- 脚本：`scripts/service_ctl.sh`（启停与监控）、`scripts/perf_api_benchmark.py`（压测）、`scripts/build_suggestions.sh`（suggest 构建）。
+- 脚本：`scripts/service_ctl.sh`（启停与监控）、`benchmarks/perf_api_benchmark.py`（压测）、`scripts/build_suggestions.sh`（suggest 构建）。
 - 完整步骤与多租户/rerank 对比见：`docs/性能测试报告.md`。
@@ -18,13 +18,13 @@
  
 执行方式：
 - 每组压测持续 `20s`
-- 使用统一脚本 `scripts/perf_api_benchmark.py`
+- 使用统一脚本 `benchmarks/perf_api_benchmark.py`
 - 通过 `--scenario` 多值 + `--concurrency-list` 一次性跑完 `场景 x 并发`
  
 ## 3. 压测工具优化说明（复用现有脚本）
  
 为了解决原脚本“一次只能跑一个场景+一个并发”的可用性问题，本次直接扩展现有脚本：
-- `scripts/perf_api_benchmark.py`
+- `benchmarks/perf_api_benchmark.py`
  
 能力：
 - 一条命令执行 `场景列表 x 并发列表` 全矩阵
@@ -33,7 +33,7 @@
 示例：
  
 ```bash
-.venv/bin/python scripts/perf_api_benchmark.py \
+.venv/bin/python benchmarks/perf_api_benchmark.py \
   --scenario backend_search,backend_suggest,embed_text,rerank \
   --concurrency-list 1,5,10,20 \
   --duration 20 \
@@ -106,7 +106,7 @@ curl -sS http://127.0.0.1:6007/health
  
 ```bash
 cd /data/saas-search
-.venv/bin/python scripts/perf_api_benchmark.py \
+.venv/bin/python benchmarks/perf_api_benchmark.py \
   --scenario backend_search,backend_suggest,embed_text,rerank \
   --concurrency-list 1,5,10,20 \
   --duration 20 \
@@ -164,7 +164,7 @@ cd /data/saas-search
 复现命令：
  
 ```bash
-.venv/bin/python scripts/perf_api_benchmark.py \
+.venv/bin/python benchmarks/perf_api_benchmark.py \
   --scenario rerank \
   --duration 20 \
   --concurrency-list 1,5,10,20 \
@@ -237,7 +237,7 @@ cd /data/saas-search
 - 使用项目虚拟环境执行：
  
 ```bash
-.venv/bin/python scripts/perf_api_benchmark.py -h
+.venv/bin/python benchmarks/perf_api_benchmark.py -h
 ```
  
 ### 10.3 某场景成功率下降
@@ -249,7 +249,7 @@ cd /data/saas-search
  
 ## 11. 关联文件
  
-- 压测脚本：`scripts/perf_api_benchmark.py`
+- 压测脚本：`benchmarks/perf_api_benchmark.py`
 - 本次结果：`perf_reports/2026-03-12/perf_matrix_report.json`
 - Search 多租户补测：`perf_reports/2026-03-12/search_tenant_matrix/`
 - Reranker 386 docs 口径补测：`perf_reports/2026-03-12/rerank_realistic/rerank_386docs.json`
@@ -280,7 +280,7 @@ cd /data/saas-search
 cd /data/saas-search
 mkdir -p perf_reports/2026-03-12/search_tenant_matrix
 for t in 0 1 2 3 4; do
-  .venv/bin/python scripts/perf_api_benchmark.py \
+  .venv/bin/python benchmarks/perf_api_benchmark.py \
     --scenario backend_search \
     --concurrency-list 1,5,10,20 \
     --duration 20 \
@@ -498,7 +498,7 @@ curl -X GET &quot;http://localhost:6004/indexer/health&quot;
  
 #### 请求示例（完整 curl）
  
-> 完整请求体参考 `scripts/test_build_docs_api.py` 中的 `build_sample_request()`。
+> 完整请求体参考 `tests/manual/test_build_docs_api.py` 中的 `build_sample_request()`。
  
 ```bash
 # 单条 SPU 示例（含 spu、skus、options）
@@ -4,7 +4,7 @@
  
 ## 10. 接口级压测脚本
  
-仓库提供统一压测脚本：`scripts/perf_api_benchmark.py`，用于对以下接口做并发压测：
+仓库提供统一压测脚本：`benchmarks/perf_api_benchmark.py`，用于对以下接口做并发压测：
  
 - 后端搜索：`POST /search/`
 - 搜索建议：`GET /search/suggestions`
@@ -18,21 +18,21 @@
  
 ```bash
 # suggest 压测（tenant 162）
-python scripts/perf_api_benchmark.py \
+python benchmarks/perf_api_benchmark.py \
   --scenario backend_suggest \
   --tenant-id 162 \
   --duration 30 \
   --concurrency 50
  
 # search 压测
-python scripts/perf_api_benchmark.py \
+python benchmarks/perf_api_benchmark.py \
   --scenario backend_search \
   --tenant-id 162 \
   --duration 30 \
   --concurrency 20
  
 # 全链路压测（search + suggest + embedding + translate + rerank）
-python scripts/perf_api_benchmark.py \
+python benchmarks/perf_api_benchmark.py \
   --scenario all \
   --tenant-id 162 \
   --duration 60 \
@@ -45,17 +45,16 @@ python scripts/perf_api_benchmark.py \
 可通过 `--cases-file` 覆盖默认请求模板。示例文件：
  
 ```bash
-scripts/perf_cases.json.example
+benchmarks/perf_cases.json.example
 ```
  
 执行示例：
  
 ```bash
-python scripts/perf_api_benchmark.py \
+python benchmarks/perf_api_benchmark.py \
   --scenario all \
   --tenant-id 162 \
-  --cases-file scripts/perf_cases.json.example \
+  --cases-file benchmarks/perf_cases.json.example \
   --duration 60 \
   --concurrency 40
 ```
-
@@ -330,7 +330,7 @@ python -m pytest -q tests/test_rerank_client.py tests/test_es_query_builder.py t
 ./scripts/service_ctl.sh restart backend
 sleep 3
 ./scripts/service_ctl.sh status backend
-./scripts/evaluation/start_eval.sh.sh batch
+./scripts/evaluation/start_eval.sh batch
 ```
  
 评估产物在 `artifacts/search_evaluation/`（如 `search_eval.sqlite3`、`batch_reports/` 下的 JSON/Markdown）。流程与参数说明见 [scripts/evaluation/README.md](../scripts/evaluation/README.md)。
@@ -895,4 +895,3 @@ rerank_score:0.4784
 rerank_score:0.5849
     "zh": "新款女士修身仿旧牛仔短裤 – 休闲性感磨边水洗牛仔短裤，时尚舒",
     "en": "New Women's Slim-fit Vintage Washed Denim Shorts – Casual Sexy Frayed Hem, Fashionable & Comfortable"
-
@@ -98,10 +98,10 @@
  
 ### 性能与压测（沿用仓库脚本）
  
-- 接口级压测（与 `perf_reports/2026-03-12/matrix_report/` 等方法一致）：`scripts/perf_api_benchmark.py`
-  - 示例：`python scripts/perf_api_benchmark.py --scenario embed_text --duration 30 --concurrency 20`
+- 接口级压测（与 `perf_reports/2026-03-12/matrix_report/` 等方法一致）：`benchmarks/perf_api_benchmark.py`
+  - 示例：`python benchmarks/perf_api_benchmark.py --scenario embed_text --duration 30 --concurrency 20`
   - 文本/图片向量可带 `priority`（与线上 admission 语义一致）：`--embed-text-priority 1`、`--embed-image-priority 1`
-  - 自定义请求模板：`--cases-file scripts/perf_cases.json.example`
+  - 自定义请求模板：`--cases-file benchmarks/perf_cases.json.example`
 - 历史矩阵结果与说明见 `perf_reports/2026-03-12/matrix_report/summary.md`。
  
 ### 启动服务
@@ -34,5 +34,5 @@ Workload profile:
 ## Reproduce
  
 ```bash
-./scripts/benchmark_reranker_1000docs.sh
+./benchmarks/reranker/benchmark_reranker_1000docs.sh
 ```
 # Local Translation Model Benchmark Report
  
-Test script: [`scripts/benchmark_translation_local_models.py`](/data/saas-search/scripts/benchmark_translation_local_models.py)
+Test script: [`benchmarks/translation/benchmark_translation_local_models.py`](/data/saas-search/benchmarks/translation/benchmark_translation_local_models.py)
  
 Test time: `2026-03-17`
  
@@ -67,7 +67,7 @@ To model online search query translation, we reran NLLB with `batch_size=1`. In 
 Command used:
  
 ```bash
-./.venv-translator/bin/python scripts/benchmark_translation_local_models.py \
+./.venv-translator/bin/python benchmarks/translation/benchmark_translation_local_models.py \
   --single \
   --model nllb-200-distilled-600m \
   --source-lang zh \
 # NLLB T4 Product-Name Tuning Summary
  
 测试脚本：
-- [`scripts/benchmark_nllb_t4_tuning.py`](/data/saas-search/scripts/benchmark_nllb_t4_tuning.py)
+- [`benchmarks/translation/benchmark_nllb_t4_tuning.py`](/data/saas-search/benchmarks/translation/benchmark_nllb_t4_tuning.py)
  
 本轮报告：
 - Markdown：[`nllb_t4_tuning_003608.md`](/data/saas-search/perf_reports/20260318/nllb_t4_product_names_ct2/nllb_t4_tuning_003608.md)
 # Local Translation Model Benchmark Report
  
 测试脚本：
-- [`scripts/benchmark_translation_local_models.py`](/data/saas-search/scripts/benchmark_translation_local_models.py)
+- [`benchmarks/translation/benchmark_translation_local_models.py`](/data/saas-search/benchmarks/translation/benchmark_translation_local_models.py)
  
 完整结果：
 - Markdown：[`translation_local_models_extended_221846.md`](/data/saas-search/perf_reports/20260318/translation_local_models/translation_local_models_extended_221846.md)
@@ -39,7 +39,7 @@
  
 ```bash
 cd /data/saas-search
-./.venv-translator/bin/python scripts/benchmark_translation_local_models.py \
+./.venv-translator/bin/python benchmarks/translation/benchmark_translation_local_models.py \
   --suite extended \
   --disable-cache \
   --serial-items-per-case 256 \
 # Local Translation Model Benchmark Report (CTranslate2)
  
 测试脚本：
-- [`scripts/benchmark_translation_local_models.py`](/data/saas-search/scripts/benchmark_translation_local_models.py)
+- [`benchmarks/translation/benchmark_translation_local_models.py`](/data/saas-search/benchmarks/translation/benchmark_translation_local_models.py)
  
 本轮 CT2 结果：
 - Markdown：[`translation_local_models_ct2_extended_233253.md`](/data/saas-search/perf_reports/20260318/translation_local_models_ct2/translation_local_models_ct2_extended_233253.md)
@@ -46,7 +46,7 @@ from datetime import datetime
 from pathlib import Path
 from types import SimpleNamespace
  
-from scripts.benchmark_translation_local_models import (
+from benchmarks.translation.benchmark_translation_local_models import (
     SCENARIOS,
     benchmark_extended_scenario,
     build_environment_info,
 # Local Translation Model Focused T4 Tuning
  
 测试脚本：
-- [`scripts/benchmark_translation_local_models_focus.py`](/data/saas-search/scripts/benchmark_translation_local_models_focus.py)
+- [`benchmarks/translation/benchmark_translation_local_models_focus.py`](/data/saas-search/benchmarks/translation/benchmark_translation_local_models_focus.py)
  
 本轮聚焦结果：
 - Markdown：[`translation_local_models_focus_235018.md`](/data/saas-search/perf_reports/20260318/translation_local_models_ct2_focus/translation_local_models_focus_235018.md)
@@ -4,7 +4,7 @@
  
 | 脚本 | 用途 |
 |------|------|
-| `scripts/perf_api_benchmark.py` | 搜索后端、向量、翻译、重排等 HTTP 接口压测；支持 `--embed-text-priority` / `--embed-image-priority` 与 `scripts/perf_cases.json.example` |
+| `benchmarks/perf_api_benchmark.py` | 搜索后端、向量、翻译、重排等 HTTP 接口压测；支持 `--embed-text-priority` / `--embed-image-priority` 与 `benchmarks/perf_cases.json.example` |
  
 历史矩阵示例（并发扫描）：
  
@@ -25,10 +25,10 @@
  
 ```bash
 source activate.sh
-python scripts/perf_api_benchmark.py --scenario embed_text --duration 8 --concurrency 10 --timeout 30 --output perf_reports/2026-03-20_embed_text_p0.json
-python scripts/perf_api_benchmark.py --scenario embed_text --duration 8 --concurrency 10 --embed-text-priority 1 --output perf_reports/2026-03-20_embed_text_p1.json
-python scripts/perf_api_benchmark.py --scenario embed_image --duration 8 --concurrency 5 --timeout 60 --output perf_reports/2026-03-20_embed_image_p0.json
-python scripts/perf_api_benchmark.py --scenario embed_image --duration 8 --concurrency 5 --embed-image-priority 1 --output perf_reports/2026-03-20_embed_image_p1.json
+python benchmarks/perf_api_benchmark.py --scenario embed_text --duration 8 --concurrency 10 --timeout 30 --output perf_reports/2026-03-20_embed_text_p0.json
+python benchmarks/perf_api_benchmark.py --scenario embed_text --duration 8 --concurrency 10 --embed-text-priority 1 --output perf_reports/2026-03-20_embed_text_p1.json
+python benchmarks/perf_api_benchmark.py --scenario embed_image --duration 8 --concurrency 5 --timeout 60 --output perf_reports/2026-03-20_embed_image_p0.json
+python benchmarks/perf_api_benchmark.py --scenario embed_image --duration 8 --concurrency 5 --embed-image-priority 1 --output perf_reports/2026-03-20_embed_image_p1.json
 ```
  
 说明：本次为 **8 秒 smoke**，与 `2026-03-12` 矩阵的时长/并发不可直接横向对比；仅验证 `priority` 参数下服务仍返回 200 且 payload 校验通过。
@@ -25,7 +25,7 @@ Shared across both backends for this run:
  
 ## Methodology
  
-- Script: `python scripts/benchmark_reranker_random_titles.py 100,200,400,600,800,1000 --repeat 5` with **`--seed 99`** (see note below), **`--quiet-runs`**, **`--timeout 360`**.
+- Script: `python benchmarks/reranker/benchmark_reranker_random_titles.py 100,200,400,600,800,1000 --repeat 5` with **`--seed 99`** (see note below), **`--quiet-runs`**, **`--timeout 360`**.
 - Titles: default file `/home/ubuntu/rerank_test/titles.1.8w` (one title per line).
 - Query: default `健身女生T恤短袖`.
 - Each scenario: **3 warm-up** requests at `n=400` (not timed), then **5 timed** runs per `n`.
@@ -56,9 +56,9 @@ JSON aggregates (means, stdev, raw `values_ms`): same directory, `qwen3_vllm_{co
 ## Tooling added / changed
  
 - `reranker/server.py`: `/health` includes `instruction_format` when the active backend sets `_instruction_format`.
-- `scripts/benchmark_reranker_random_titles.py`: `--tag`, `--json-summary-out`, `--quiet-runs`.
-- `scripts/patch_rerank_vllm_benchmark_config.py`: surgical YAML patch (preserves newlines).
-- `scripts/run_reranker_vllm_instruction_benchmark.sh`: full matrix driver (continues if a benchmark exits non-zero; uses `--timeout 360`).
+- `benchmarks/reranker/benchmark_reranker_random_titles.py`: `--tag`, `--json-summary-out`, `--quiet-runs`.
+- `benchmarks/reranker/patch_rerank_vllm_benchmark_config.py`: surgical YAML patch (preserves newlines).
+- `benchmarks/reranker/run_reranker_vllm_instruction_benchmark.sh`: full matrix driver (continues if a benchmark exits non-zero; uses `--timeout 360`).
  
 ---
  
@@ -73,7 +73,7 @@ JSON aggregates (means, stdev, raw `values_ms`): same directory, `qwen3_vllm_{co
 | Attention | Backend forced / steered attention on T4 (e.g. `TRITON_ATTN` path) | **No** `attention_config` in `LLM(...)`; vLLM **auto** — on this T4 run, logs show **`FLASHINFER`** |
 | Config surface | `vllm_attention_backend` / `RERANK_VLLM_ATTENTION_BACKEND` 等 | **Removed**（少 YAML/环境变量分支，逻辑收敛） |
 | Code default `instruction_format` | `qwen3_vllm_score` 默认 `standard` | 与 `qwen3_vllm` 对齐为 **`compact`**（仍可在 YAML 写 `standard`） |
-| Smoke / 启动 | — | `scripts/smoke_qwen3_vllm_score_backend.py`；`scripts/start_reranker.sh` 将 **venv `bin` 置于 `PATH`**（FLASHINFER JIT 依赖 venv 内的 `ninja`） |
+| Smoke / 启动 | — | `benchmarks/reranker/smoke_qwen3_vllm_score_backend.py`；`scripts/start_reranker.sh` 将 **venv `bin` 置于 `PATH`**（FLASHINFER JIT 依赖 venv 内的 `ninja`） |
  
 Micro-benchmark (same machine, isolated): **~927.5 ms → ~673.1 ms** at **n=400** docs on `LLM.score()` steady state (~**28%**), after removing the forced attention path and letting vLLM pick **FLASHINFER**.
  
@@ -109,7 +109,7 @@ curl -sS http://127.0.0.1:6007/health
 ### 5.1 使用一键压测脚本
  
 ```bash
-./scripts/benchmark_reranker_1000docs.sh
+./benchmarks/reranker/benchmark_reranker_1000docs.sh
 ```
  
 输出目录：
@@ -144,7 +144,7 @@ qwen3_gguf_06b:
  
 ```bash
 PYTHONPATH=/data/saas-search ./.venv-reranker-gguf/bin/python \
-  scripts/benchmark_reranker_gguf_local.py --backend-name qwen3_gguf_06b --docs 400
+  benchmarks/reranker/benchmark_reranker_gguf_local.py --backend-name qwen3_gguf_06b --docs 400
 ```
  
 按服务方式启动：
@@ -117,7 +117,7 @@ HF_HUB_DISABLE_XET=1
  
 ```bash
 PYTHONPATH=/data/saas-search ./.venv-reranker-gguf/bin/python \
-  scripts/benchmark_reranker_gguf_local.py --docs 64 --repeat 1
+  benchmarks/reranker/benchmark_reranker_gguf_local.py --docs 64 --repeat 1
 ```
  
 它会直接实例化 GGUF backend，输出：
@@ -134,7 +134,7 @@ PYTHONPATH=/data/saas-search ./.venv-reranker-gguf/bin/python \
  
 - Query: `白色oversized T-shirt`
 - Docs: `64` 条商品标题
-- 本地脚本：`scripts/benchmark_reranker_gguf_local.py`
+- 本地脚本：`benchmarks/reranker/benchmark_reranker_gguf_local.py`
 - 每组 1 次，重点比较相对趋势
  
 结果：
@@ -195,7 +195,7 @@ n_gpu_layers=999
  
 ```bash
 RERANK_BASE=http://127.0.0.1:6007 \
-  ./.venv/bin/python scripts/benchmark_reranker_random_titles.py 64 --repeat 1 --query '白色oversized T-shirt'
+  ./.venv/bin/python benchmarks/reranker/benchmark_reranker_random_titles.py 64 --repeat 1 --query '白色oversized T-shirt'
 ```
  
 得到：
@@ -206,7 +206,7 @@ RERANK_BASE=http://127.0.0.1:6007 \
  
 ```bash
 RERANK_BASE=http://127.0.0.1:6007 \
-  ./.venv/bin/python scripts/benchmark_reranker_random_titles.py 153 --repeat 1 --query '白色oversized T-shirt'
+  ./.venv/bin/python benchmarks/reranker/benchmark_reranker_random_titles.py 153 --repeat 1 --query '白色oversized T-shirt'
 ```
  
 得到：
@@ -276,5 +276,5 @@ offload_kqv: true
 - `config/config.yaml`
 - `scripts/setup_reranker_venv.sh`
 - `scripts/start_reranker.sh`
-- `scripts/benchmark_reranker_gguf_local.py`
+- `benchmarks/reranker/benchmark_reranker_gguf_local.py`
 - `reranker/GGUF_INSTALL_AND_TUNING.md`
@@ -46,9 +46,9 @@ Reranker 服务提供统一的 `/rerank` API，支持可插拔后端（BGE、Jin
   - `backends/dashscope_rerank.py`：DashScope 云端重排后端
 - `scripts/setup_reranker_venv.sh`：按后端创建独立 venv
 - `scripts/start_reranker.sh`：启动 reranker 服务
-- `scripts/smoke_qwen3_vllm_score_backend.py`：`qwen3_vllm_score` 本地 smoke
-- `scripts/benchmark_reranker_random_titles.py`：随机标题压测脚本
-- `scripts/run_reranker_vllm_instruction_benchmark.sh`：历史矩阵脚本
+- `benchmarks/reranker/smoke_qwen3_vllm_score_backend.py`：`qwen3_vllm_score` 本地 smoke
+- `benchmarks/reranker/benchmark_reranker_random_titles.py`：随机标题压测脚本
+- `benchmarks/reranker/run_reranker_vllm_instruction_benchmark.sh`：历史矩阵脚本
  
 ## 环境基线
  
@@ -118,7 +118,7 @@ nvidia-smi
 ### 4. Smoke
  
 ```bash
-PYTHONPATH=. ./.venv-reranker-score/bin/python scripts/smoke_qwen3_vllm_score_backend.py --gpu-memory-utilization 0.2
+PYTHONPATH=. ./.venv-reranker-score/bin/python benchmarks/reranker/smoke_qwen3_vllm_score_backend.py --gpu-memory-utilization 0.2
 ```
  
 ## `jina_reranker_v3`
@@ -0,0 +1,53 @@
+# Scripts
+
+`scripts/` 现在只保留当前架构下仍然有效的运行、运维、环境和数据处理脚本。
+
+## 当前分类
+
+- 服务编排
+  - `service_ctl.sh`
+  - `start_backend.sh`
+  - `start_indexer.sh`
+  - `start_frontend.sh`
+  - `start_eval_web.sh`
+  - `start_embedding_service.sh`
+  - `start_embedding_text_service.sh`
+  - `start_embedding_image_service.sh`
+  - `start_reranker.sh`
+  - `start_translator.sh`
+  - `start_tei_service.sh`
+  - `start_cnclip_service.sh`
+  - `stop.sh`
+  - `stop_tei_service.sh`
+  - `stop_cnclip_service.sh`
+
+- 环境初始化
+  - `create_venv.sh`
+  - `init_env.sh`
+  - `setup_embedding_venv.sh`
+  - `setup_reranker_venv.sh`
+  - `setup_translator_venv.sh`
+  - `setup_cnclip_venv.sh`
+
+- 数据与索引
+  - `create_tenant_index.sh`
+  - `build_suggestions.sh`
+  - `mock_data.sh`
+
+- 评估与专项工具
+  - `evaluation/`
+  - `redis/`
+  - `debug/`
+
+## 已迁移
+
+- 基准压测与 smoke 脚本：迁到 `benchmarks/`
+- 手工接口试跑脚本：迁到 `tests/manual/`
+
+## 已清理
+
+- 历史备份目录：`indexer__old_2025_11/`
+- 过时壳脚本：`start.sh`
+- Conda 时代残留：`install_server_deps.sh`
+
+后续如果新增脚本，优先放到明确子目录，不再把 benchmark、manual、历史备份直接丢回根 `scripts/`。
 #!/bin/bash
 #
 # 排查「谁在调用索引服务」的脚本
-# 用法: ./scripts/trace_indexer_calls.sh
+# 用法: ./scripts/debug/trace_indexer_calls.sh
 #
  
 set -euo pipefail
@@ -1,495 +0,0 @@
-#!/usr/bin/env python3
-"""
-Import tenant2 CSV data into MySQL Shoplazza tables.
-
-Reads CSV file and generates SQL INSERT statements for SPU and SKU tables.
-Each CSV row corresponds to 1 SPU and 1 SKU.
-This script is for generating test data for tenant_id=2 from CSV files.
-"""
-
-import sys
-import os
-import csv
-import random
-import argparse
-import re
-from pathlib import Path
-from datetime import datetime, timedelta
-
-# Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-
-def escape_sql_string(value: str) -> str:
-    """
-    Escape SQL string value (replace single quotes with doubled quotes and handle special characters).
-    
-    Args:
-        value: String value to escape
-        
-    Returns:
-        Escaped string
-    """
-    if value is None:
-        return ''
-    
-    # Convert to string and handle None
-    s = str(value)
-    
-    # Replace single quotes with doubled quotes (SQL standard)
-    s = s.replace("'", "''")
-    
-    # Replace backslashes (MySQL escape)
-    s = s.replace("\\", "\\\\")
-    
-    # Remove or replace control characters that can break SQL
-    # Replace newlines and carriage returns with spaces
-    s = s.replace("\n", " ").replace("\r", " ")
-    
-    # Remove other control characters (except tab)
-    s = re.sub(r'[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F]', '', s)
-    
-    # Remove null bytes
-    s = s.replace('\x00', '')
-    
-    return s
-
-
-def generate_handle(title: str) -> str:
-    """
-    Generate URL-friendly handle from title.
-    
-    Args:
-        title: Product title
-        
-    Returns:
-        URL-friendly handle
-    """
-    # Remove special characters, convert to lowercase, replace spaces with hyphens
-    handle = re.sub(r'[^\w\s-]', '', title.lower())
-    handle = re.sub(r'[-\s]+', '-', handle)
-    handle = handle.strip('-')
-    # Limit length
-    if len(handle) > 255:
-        handle = handle[:255]
-    return handle or 'product'
-
-
-def parse_csv_row(row: dict) -> dict:
-    """
-    Parse CSV row and extract fields.
-    
-    Args:
-        row: CSV row dictionary
-        
-    Returns:
-        Parsed data dictionary
-    """
-    # Remove quotes from values if present
-    def clean_value(value):
-        if value is None:
-            return ''
-        value = str(value).strip()
-        # Remove surrounding quotes
-        if value.startswith('"') and value.endswith('"'):
-            value = value[1:-1]
-        return value
-    
-    return {
-        'skuId': clean_value(row.get('skuId', '')),
-        'name': clean_value(row.get('name', '')),
-        'name_pinyin': clean_value(row.get('name_pinyin', '')),
-        'create_time': clean_value(row.get('create_time', '')),
-        'ruSkuName': clean_value(row.get('ruSkuName', '')),
-        'enSpuName': clean_value(row.get('enSpuName', '')),
-        'categoryName': clean_value(row.get('categoryName', '')),
-        'supplierName': clean_value(row.get('supplierName', '')),
-        'brandName': clean_value(row.get('brandName', '')),
-        'file_id': clean_value(row.get('file_id', '')),
-        'days_since_last_update': clean_value(row.get('days_since_last_update', '')),
-        'id': clean_value(row.get('id', '')),
-        'imageUrl': clean_value(row.get('imageUrl', ''))
-    }
-
-
-def generate_spu_data(csv_data: dict, spu_id: int, tenant_id: str = "2") -> dict:
-    """
-    Generate SPU data from CSV row.
-    
-    Args:
-        csv_data: Parsed CSV row data
-        spu_id: SPU ID
-        tenant_id: Tenant ID (default: "2")
-        
-    Returns:
-        SPU data dictionary
-    """
-    # Parse create_time
-    try:
-        created_at = datetime.strptime(csv_data['create_time'], '%Y-%m-%d %H:%M:%S')
-    except:
-        created_at = datetime.now() - timedelta(days=random.randint(1, 365))
-    
-    updated_at = created_at + timedelta(days=random.randint(0, 30))
-    
-    # Generate handle from title
-    title = csv_data['name'] or csv_data['enSpuName'] or 'Product'
-    handle = generate_handle(title)
-    
-    # Generate tags from category and brand
-    tags_parts = []
-    if csv_data['categoryName']:
-        tags_parts.append(csv_data['categoryName'])
-    if csv_data['brandName']:
-        tags_parts.append(csv_data['brandName'])
-    tags = ','.join(tags_parts) if tags_parts else ''
-    
-    # Generate SEO fields
-    seo_title = f"{title} - {csv_data['categoryName']}" if csv_data['categoryName'] else title
-    seo_description = f"购买{csv_data['brandName']}{title}" if csv_data['brandName'] else title
-    seo_keywords = f"{title},{csv_data['categoryName']},{csv_data['brandName']}" if csv_data['categoryName'] else title
-    
-    spu = {
-        'id': spu_id,
-        'shop_id': 1,
-        'shoplazza_id': csv_data['id'] or f"spu-{spu_id}",
-        'handle': handle,
-        'title': title,
-        'brief': csv_data['name'] or '',
-        'description': f"<p>{csv_data['name']}</p>" if csv_data['name'] else '',
-        'spu': '',
-        'vendor': csv_data['supplierName'] or '',
-        'vendor_url': '',
-        'seo_title': seo_title,
-        'seo_description': seo_description,
-        'seo_keywords': seo_keywords,
-        'image_src': csv_data['imageUrl'] or '',
-        'image_width': 800,
-        'image_height': 600,
-        'image_path': f"products/{spu_id}.jpg",
-        'image_alt': title,
-        'inventory_policy': '',
-        'inventory_quantity': 0,
-        'inventory_tracking': '0',
-        'published': 1,
-        'published_at': created_at.strftime('%Y-%m-%d %H:%M:%S'),
-        'requires_shipping': 1,
-        'taxable': 0,
-        'fake_sales': 0,
-        'display_fake_sales': 0,
-        'mixed_wholesale': 0,
-        'need_variant_image': 0,
-        'has_only_default_variant': 0,
-        'tags': tags,
-        'note': '',
-        'category': csv_data['categoryName'] or '',
-        'shoplazza_created_at': created_at.strftime('%Y-%m-%d %H:%M:%S'),
-        'shoplazza_updated_at': updated_at.strftime('%Y-%m-%d %H:%M:%S'),
-        'tenant_id': tenant_id,
-        'creator': '1',
-        'create_time': created_at.strftime('%Y-%m-%d %H:%M:%S'),
-        'updater': '1',
-        'update_time': updated_at.strftime('%Y-%m-%d %H:%M:%S'),
-        'deleted': 0
-    }
-    
-    return spu
-
-
-def generate_sku_data(csv_data: dict, spu_id: int, sku_id: int, tenant_id: str = "2") -> dict:
-    """
-    Generate SKU data from CSV row.
-    
-    Args:
-        csv_data: Parsed CSV row data
-        spu_id: Associated SPU ID
-        sku_id: SKU ID (from CSV skuId)
-        tenant_id: Tenant ID (default: "2")
-        
-    Returns:
-        SKU data dictionary
-    """
-    # Parse create_time
-    try:
-        created_at = datetime.strptime(csv_data['create_time'], '%Y-%m-%d %H:%M:%S')
-    except:
-        created_at = datetime.now() - timedelta(days=random.randint(1, 365))
-    
-    updated_at = created_at + timedelta(days=random.randint(0, 30))
-    
-    # Generate random price
-    price = round(random.uniform(50, 500), 2)
-    compare_at_price = round(price * random.uniform(1.2, 1.5), 2)
-    cost_price = round(price * 0.6, 2)
-    
-    # Generate random stock
-    inventory_quantity = random.randint(0, 100)
-    
-    # Generate random weight
-    weight = round(random.uniform(0.1, 5.0), 2)
-    
-    # Use ruSkuName as title, fallback to name
-    title = csv_data['ruSkuName'] or csv_data['name'] or 'SKU'
-    
-    # Use skuId as SKU code
-    sku_code = csv_data['skuId'] or f"SKU-{sku_id}"
-    
-    sku = {
-        'id': sku_id,
-        'spu_id': spu_id,
-        'shop_id': 1,
-        'shoplazza_id': f"sku-{sku_id}",
-        'shoplazza_product_id': csv_data['id'] or f"spu-{spu_id}",
-        'shoplazza_image_id': '',
-        'title': title,
-        'sku': sku_code,
-        'barcode': f"BAR{sku_id:08d}",
-        'position': 1,
-        'price': price,
-        'compare_at_price': compare_at_price,
-        'cost_price': cost_price,
-        'option1': '',
-        'option2': '',
-        'option3': '',
-        'inventory_quantity': inventory_quantity,
-        'weight': weight,
-        'weight_unit': 'kg',
-        'image_src': csv_data['imageUrl'] or '',
-        'wholesale_price': f'[{{"price": {round(price * 0.8, 2)}, "minQuantity": 10}}]',
-        'note': '',
-        'extend': None,  # JSON field, use NULL
-        'shoplazza_created_at': created_at.strftime('%Y-%m-%d %H:%M:%S'),
-        'shoplazza_updated_at': updated_at.strftime('%Y-%m-%d %H:%M:%S'),
-        'tenant_id': tenant_id,
-        'creator': '1',
-        'create_time': created_at.strftime('%Y-%m-%d %H:%M:%S'),
-        'updater': '1',
-        'update_time': updated_at.strftime('%Y-%m-%d %H:%M:%S'),
-        'deleted': 0
-    }
-    
-    return sku
-
-
-def read_csv_file(csv_file: str) -> list:
-    """
-    Read CSV file and return list of parsed rows.
-    
-    Args:
-        csv_file: Path to CSV file
-        
-    Returns:
-        List of parsed CSV data dictionaries
-    """
-    csv_data_list = []
-    
-    with open(csv_file, 'r', encoding='utf-8') as f:
-        # Use csv.DictReader to handle quoted fields properly
-        reader = csv.DictReader(f)
-        for row in reader:
-            parsed = parse_csv_row(row)
-            csv_data_list.append(parsed)
-    
-    return csv_data_list
-
-
-def generate_sql_inserts(spus: list, skus: list, output_file: str):
-    """
-    Generate SQL INSERT statements.
-    
-    Args:
-        spus: List of SPU data
-        skus: List of SKU data
-        output_file: Output file path
-    """
-    with open(output_file, 'w', encoding='utf-8') as f:
-        f.write("-- SPU Data from tenant2 CSV\n")
-        f.write("INSERT INTO shoplazza_product_spu (\n")
-        f.write("    id, shop_id, shoplazza_id, handle, title, brief, description, spu,\n")
-        f.write("    vendor, vendor_url, seo_title, seo_description, seo_keywords,\n")
-        f.write("    image_src, image_width, image_height, image_path, image_alt,\n")
-        f.write("    inventory_policy, inventory_quantity, inventory_tracking,\n")
-        f.write("    published, published_at, requires_shipping, taxable,\n")
-        f.write("    fake_sales, display_fake_sales, mixed_wholesale, need_variant_image,\n")
-        f.write("    has_only_default_variant, tags, note, category,\n")
-        f.write("    shoplazza_created_at, shoplazza_updated_at, tenant_id,\n")
-        f.write("    creator, create_time, updater, update_time, deleted\n")
-        f.write(") VALUES\n")
-        
-        for i, spu in enumerate(spus):
-            values = (
-                f"({spu['id']}, {spu['shop_id']}, '{escape_sql_string(spu['shoplazza_id'])}', "
-                f"'{escape_sql_string(spu['handle'])}', '{escape_sql_string(spu['title'])}', "
-                f"'{escape_sql_string(spu['brief'])}', '{escape_sql_string(spu['description'])}', "
-                f"'{escape_sql_string(spu['spu'])}', '{escape_sql_string(spu['vendor'])}', "
-                f"'{escape_sql_string(spu['vendor_url'])}', '{escape_sql_string(spu['seo_title'])}', "
-                f"'{escape_sql_string(spu['seo_description'])}', '{escape_sql_string(spu['seo_keywords'])}', "
-                f"'{escape_sql_string(spu['image_src'])}', {spu['image_width']}, "
-                f"{spu['image_height']}, '{escape_sql_string(spu['image_path'])}', "
-                f"'{escape_sql_string(spu['image_alt'])}', '{escape_sql_string(spu['inventory_policy'])}', "
-                f"{spu['inventory_quantity']}, '{escape_sql_string(spu['inventory_tracking'])}', "
-                f"{spu['published']}, '{escape_sql_string(spu['published_at'])}', "
-                f"{spu['requires_shipping']}, {spu['taxable']}, "
-                f"{spu['fake_sales']}, {spu['display_fake_sales']}, {spu['mixed_wholesale']}, "
-                f"{spu['need_variant_image']}, {spu['has_only_default_variant']}, "
-                f"'{escape_sql_string(spu['tags'])}', '{escape_sql_string(spu['note'])}', "
-                f"'{escape_sql_string(spu['category'])}', '{escape_sql_string(spu['shoplazza_created_at'])}', "
-                f"'{escape_sql_string(spu['shoplazza_updated_at'])}', '{escape_sql_string(spu['tenant_id'])}', "
-                f"'{escape_sql_string(spu['creator'])}', '{escape_sql_string(spu['create_time'])}', "
-                f"'{escape_sql_string(spu['updater'])}', '{escape_sql_string(spu['update_time'])}', "
-                f"{spu['deleted']})"
-            )
-            f.write(values)
-            if i < len(spus) - 1:
-                f.write(",\n")
-            else:
-                f.write(";\n\n")
-        
-        f.write("-- SKU Data from tenant2 CSV\n")
-        f.write("INSERT INTO shoplazza_product_sku (\n")
-        f.write("    id, spu_id, shop_id, shoplazza_id, shoplazza_product_id, shoplazza_image_id,\n")
-        f.write("    title, sku, barcode, position, price, compare_at_price, cost_price,\n")
-        f.write("    option1, option2, option3, inventory_quantity, weight, weight_unit,\n")
-        f.write("    image_src, wholesale_price, note, extend,\n")
-        f.write("    shoplazza_created_at, shoplazza_updated_at, tenant_id,\n")
-        f.write("    creator, create_time, updater, update_time, deleted\n")
-        f.write(") VALUES\n")
-        
-        for i, sku in enumerate(skus):
-            # Handle extend field (JSON, can be NULL)
-            extend_value = 'NULL' if sku['extend'] is None else f"'{escape_sql_string(sku['extend'])}'"
-            
-            values = (
-                f"({sku['id']}, {sku['spu_id']}, {sku['shop_id']}, '{escape_sql_string(sku['shoplazza_id'])}', "
-                f"'{escape_sql_string(sku['shoplazza_product_id'])}', '{escape_sql_string(sku['shoplazza_image_id'])}', "
-                f"'{escape_sql_string(sku['title'])}', '{escape_sql_string(sku['sku'])}', "
-                f"'{escape_sql_string(sku['barcode'])}', {sku['position']}, "
-                f"{sku['price']}, {sku['compare_at_price']}, {sku['cost_price']}, "
-                f"'{escape_sql_string(sku['option1'])}', '{escape_sql_string(sku['option2'])}', "
-                f"'{escape_sql_string(sku['option3'])}', {sku['inventory_quantity']}, {sku['weight']}, "
-                f"'{escape_sql_string(sku['weight_unit'])}', '{escape_sql_string(sku['image_src'])}', "
-                f"'{escape_sql_string(sku['wholesale_price'])}', '{escape_sql_string(sku['note'])}', "
-                f"{extend_value}, '{escape_sql_string(sku['shoplazza_created_at'])}', "
-                f"'{escape_sql_string(sku['shoplazza_updated_at'])}', '{escape_sql_string(sku['tenant_id'])}', "
-                f"'{escape_sql_string(sku['creator'])}', '{escape_sql_string(sku['create_time'])}', "
-                f"'{escape_sql_string(sku['updater'])}', '{escape_sql_string(sku['update_time'])}', "
-                f"{sku['deleted']})"
-            )
-            f.write(values)
-            if i < len(skus) - 1:
-                f.write(",\n")
-            else:
-                f.write(";\n")
-
-
-def get_max_ids_from_db(db_config=None):
-    """
-    Get maximum IDs from database to avoid primary key conflicts.
-    
-    Args:
-        db_config: Optional database config dict with keys: host, port, database, username, password
-        
-    Returns:
-        tuple: (max_spu_id, max_sku_id) or (0, 0) if cannot connect
-    """
-    if not db_config:
-        return 0, 0
-    
-    try:
-        from utils.db_connector import create_db_connection
-        from sqlalchemy import text
-        
-        db_engine = create_db_connection(
-            host=db_config['host'],
-            port=db_config['port'],
-            database=db_config['database'],
-            username=db_config['username'],
-            password=db_config['password']
-        )
-        
-        with db_engine.connect() as conn:
-            result = conn.execute(text('SELECT MAX(id) FROM shoplazza_product_spu'))
-            max_spu_id = result.scalar() or 0
-            
-            result = conn.execute(text('SELECT MAX(id) FROM shoplazza_product_sku'))
-            max_sku_id = result.scalar() or 0
-            
-            return max_spu_id, max_sku_id
-    except Exception as e:
-        print(f"Warning: Could not get max IDs from database: {e}")
-        return 0, 0
-
-
-def main():
-    parser = argparse.ArgumentParser(description='Import tenant2 CSV data into MySQL Shoplazza tables')
-    parser.add_argument('--csv-file', required=True, help='CSV file path')
-    parser.add_argument('--tenant-id', default='2', help='Tenant ID (default: 2)')
-    parser.add_argument('--start-spu-id', type=int, default=None, help='Starting SPU ID (default: auto-calculate from DB)')
-    parser.add_argument('--output', default='tenant2_data.sql', help='Output SQL file (default: tenant2_data.sql)')
-    parser.add_argument('--db-host', help='Database host (for auto-calculating start IDs)')
-    parser.add_argument('--db-port', type=int, default=3306, help='Database port (default: 3306)')
-    parser.add_argument('--db-database', help='Database name (for auto-calculating start IDs)')
-    parser.add_argument('--db-username', help='Database username (for auto-calculating start IDs)')
-    parser.add_argument('--db-password', help='Database password (for auto-calculating start IDs)')
-    
-    args = parser.parse_args()
-    
-    print(f"Reading CSV file: {args.csv_file}")
-    csv_data_list = read_csv_file(args.csv_file)
-    print(f"Read {len(csv_data_list)} rows from CSV")
-    
-    # Auto-calculate start IDs if not provided and DB config available
-    start_spu_id = args.start_spu_id
-    if start_spu_id is None and args.db_host and args.db_database and args.db_username and args.db_password:
-        print("Auto-calculating start IDs from database...")
-        db_config = {
-            'host': args.db_host,
-            'port': args.db_port,
-            'database': args.db_database,
-            'username': args.db_username,
-            'password': args.db_password
-        }
-        max_spu_id, max_sku_id = get_max_ids_from_db(db_config)
-        start_spu_id = max_spu_id + 1
-        print(f"  Max SPU ID in DB: {max_spu_id}")
-        print(f"  Using start SPU ID: {start_spu_id}")
-    elif start_spu_id is None:
-        start_spu_id = 1
-        print(f"Using default start SPU ID: {start_spu_id}")
-    
-    # Generate SPU and SKU data
-    print(f"Generating SPU and SKU data (tenant_id={args.tenant_id})...")
-    spus = []
-    skus = []
-    spu_id = start_spu_id
-    
-    for csv_data in csv_data_list:
-        # Generate SPU
-        spu = generate_spu_data(csv_data, spu_id, args.tenant_id)
-        spus.append(spu)
-        
-        # Generate SKU - use skuId from CSV as SKU ID
-        try:
-            sku_id = int(csv_data['skuId'])
-        except:
-            # If skuId is not valid, use a generated ID
-            sku_id = 1000000 + spu_id
-        
-        sku = generate_sku_data(csv_data, spu_id, sku_id, args.tenant_id)
-        skus.append(sku)
-        
-        spu_id += 1
-    
-    print(f"Generated {len(spus)} SPUs and {len(skus)} SKUs")
-    
-    # Generate SQL file
-    print(f"Generating SQL file: {args.output}")
-    generate_sql_inserts(spus, skus, args.output)
-    print(f"SQL file generated: {args.output}")
-    print(f"  - SPUs: {len(spus)}")
-    print(f"  - SKUs: {len(skus)}")
-
-
-if __name__ == '__main__':
-    main()
-
@@ -1,277 +0,0 @@
-#!/usr/bin/env python3
-"""
-Import test data into MySQL Shoplazza tables.
-
-Reads SQL file generated by generate_test_data.py and imports into MySQL.
-"""
-
-import sys
-import os
-import argparse
-from pathlib import Path
-
-# Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from utils.db_connector import create_db_connection, test_connection
-
-
-def import_sql_file(db_engine, sql_file: str):
-    """
-    Import SQL file into database using MySQL client (more reliable for large files).
-
-    Args:
-        db_engine: SQLAlchemy database engine (used to get connection info)
-        sql_file: Path to SQL file
-    """
-    import subprocess
-    import os
-    from pathlib import Path
-    
-    # Get connection info from engine URL
-    engine_url = str(db_engine.url)
-    # Parse: mysql+pymysql://user:pass@host:port/database
-    import re
-    match = re.match(r'mysql\+pymysql://([^:]+):([^@]+)@([^:]+):(\d+)/(.+)', engine_url)
-    if not match:
-        raise ValueError(f"Cannot parse database URL: {engine_url}")
-    
-    username, password, host, port, database = match.groups()
-    
-    # Use MySQL client to execute SQL file (more reliable)
-    sql_file_path = Path(sql_file).absolute()
-    
-    # Build mysql command
-    mysql_cmd = [
-        'mysql',
-        f'-h{host}',
-        f'-P{port}',
-        f'-u{username}',
-        f'-p{password}',
-        database
-    ]
-    
-    print(f"Executing SQL file using MySQL client...")
-    print(f"  File: {sql_file_path}")
-    print(f"  Database: {host}:{port}/{database}")
-    
-    try:
-        with open(sql_file_path, 'r', encoding='utf-8') as f:
-            result = subprocess.run(
-                mysql_cmd,
-                stdin=f,
-                capture_output=True,
-                text=True,
-                timeout=300  # 5 minute timeout
-            )
-        
-        if result.returncode != 0:
-            error_msg = result.stderr or result.stdout
-            print(f"ERROR: MySQL execution failed")
-            print(f"Error output: {error_msg[:500]}")
-            raise Exception(f"MySQL execution failed: {error_msg[:200]}")
-        
-        print("SQL file executed successfully")
-        return True
-        
-    except FileNotFoundError:
-        # Fallback to SQLAlchemy if mysql client not available
-        print("MySQL client not found, falling back to SQLAlchemy...")
-        return import_sql_file_sqlalchemy(db_engine, sql_file)
-    except subprocess.TimeoutExpired:
-        raise Exception("SQL execution timed out after 5 minutes")
-    except Exception as e:
-        print(f"Error using MySQL client: {e}")
-        print("Falling back to SQLAlchemy...")
-        return import_sql_file_sqlalchemy(db_engine, sql_file)
-
-
-def import_sql_file_sqlalchemy(db_engine, sql_file: str):
-    """
-    Fallback method: Import SQL file using SQLAlchemy (for when mysql client unavailable).
-    """
-    from sqlalchemy import text
-    
-    with open(sql_file, 'r', encoding='utf-8') as f:
-        sql_content = f.read()
-    
-    # Remove comment lines
-    lines = sql_content.split('\n')
-    cleaned_lines = []
-    for line in lines:
-        stripped = line.lstrip()
-        if stripped.startswith('--'):
-            continue
-        cleaned_lines.append(line)
-    
-    sql_content = '\n'.join(cleaned_lines)
-    
-    # Split by semicolon - but we need to handle strings properly
-    # Use a state machine to track string boundaries
-    statements = []
-    current = []
-    in_string = False
-    i = 0
-    
-    while i < len(sql_content):
-        char = sql_content[i]
-        
-        if char == "'":
-            # Check for escaped quote (two single quotes)
-            if i + 1 < len(sql_content) and sql_content[i+1] == "'":
-                current.append("''")
-                i += 1  # Skip next quote
-            elif not in_string:
-                in_string = True
-                current.append(char)
-            else:
-                in_string = False
-                current.append(char)
-        else:
-            current.append(char)
-        
-        # Split on semicolon only if not in string
-        if char == ';' and not in_string:
-            stmt = ''.join(current).strip()
-            if stmt and stmt.upper().startswith('INSERT INTO'):
-                statements.append(stmt)
-            current = []
-        
-        i += 1
-    
-    # Handle last statement
-    if current:
-        stmt = ''.join(current).strip()
-        if stmt and stmt.upper().startswith('INSERT INTO'):
-            statements.append(stmt)
-    
-    print(f"Parsed {len(statements)} SQL statements")
-    print(f"Executing {len(statements)} SQL statements...")
-    
-    # Use raw connection to avoid SQLAlchemy parameter parsing
-    raw_conn = db_engine.raw_connection()
-    try:
-        cursor = raw_conn.cursor()
-        try:
-            for i, statement in enumerate(statements, 1):
-                try:
-                    # Execute raw SQL directly using pymysql cursor
-                    cursor.execute(statement)
-                    raw_conn.commit()
-                    if i % 1000 == 0 or i == len(statements):
-                        print(f"  [{i}/{len(statements)}] Executed successfully")
-                except Exception as e:
-                    print(f"  [{i}/{len(statements)}] ERROR: {e}")
-                    error_start = max(0, statement.find('VALUES') - 100)
-                    error_end = min(len(statement), error_start + 500)
-                    print(f"  Statement context: ...{statement[error_start:error_end]}...")
-                    raise
-        finally:
-            cursor.close()
-    finally:
-        raw_conn.close()
-    
-    return True
-
-
-def verify_import(db_engine, tenant_id: str):
-    """
-    Verify imported data.
-
-    Args:
-        db_engine: SQLAlchemy database engine
-        tenant_id: Tenant ID to verify
-    """
-    from sqlalchemy import text
-    
-    with db_engine.connect() as conn:
-        # Count SPUs
-        result = conn.execute(text("SELECT COUNT(*) FROM shoplazza_product_spu WHERE tenant_id = :tenant_id"), {"tenant_id": tenant_id})
-        spu_count = result.scalar()
-        
-        # Count SKUs
-        result = conn.execute(text("SELECT COUNT(*) FROM shoplazza_product_sku WHERE tenant_id = :tenant_id"), {"tenant_id": tenant_id})
-        sku_count = result.scalar()
-        
-        print(f"\nVerification:")
-        print(f"  SPUs: {spu_count}")
-        print(f"  SKUs: {sku_count}")
-        
-        return spu_count, sku_count
-
-
-def main():
-    parser = argparse.ArgumentParser(description='Import test data into MySQL')
-    
-    # Database connection
-    parser.add_argument('--db-host', required=True, help='MySQL host')
-    parser.add_argument('--db-port', type=int, default=3306, help='MySQL port (default: 3306)')
-    parser.add_argument('--db-database', required=True, help='MySQL database name')
-    parser.add_argument('--db-username', required=True, help='MySQL username')
-    parser.add_argument('--db-password', required=True, help='MySQL password')
-    
-    # Import options
-    parser.add_argument('--sql-file', required=True, help='SQL file to import')
-    parser.add_argument('--tenant-id', help='Tenant ID to verify (optional)')
-    
-    args = parser.parse_args()
-
-    print(f"Connecting to MySQL: {args.db_host}:{args.db_port}/{args.db_database}")
-    
-    # Connect to database
-    try:
-        db_engine = create_db_connection(
-            host=args.db_host,
-            port=args.db_port,
-            database=args.db_database,
-            username=args.db_username,
-            password=args.db_password
-        )
-    except Exception as e:
-        print(f"ERROR: Failed to connect to MySQL: {e}")
-        return 1
-
-    # Test connection
-    if not test_connection(db_engine):
-        print("ERROR: Database connection test failed")
-        return 1
-
-    print("Database connection successful")
-
-    # Clean existing data if tenant_id provided
-    if args.tenant_id:
-        print(f"\nCleaning existing data for tenant_id: {args.tenant_id}")
-        from sqlalchemy import text
-        try:
-            with db_engine.connect() as conn:
-                # Delete SKUs first (foreign key constraint)
-                conn.execute(text(f"DELETE FROM shoplazza_product_sku WHERE tenant_id = '{args.tenant_id}'"))
-                # Delete SPUs
-                conn.execute(text(f"DELETE FROM shoplazza_product_spu WHERE tenant_id = '{args.tenant_id}'"))
-                conn.commit()
-                print("✓ Existing data cleaned")
-        except Exception as e:
-            print(f"⚠ Warning: Failed to clean existing data: {e}")
-            # Continue anyway
-
-    # Import SQL file
-    print(f"\nImporting SQL file: {args.sql_file}")
-    try:
-        import_sql_file(db_engine, args.sql_file)
-        print("Import completed successfully")
-    except Exception as e:
-        print(f"ERROR: Failed to import SQL file: {e}")
-        import traceback
-        traceback.print_exc()
-        return 1
-
-    # Verify import if tenant_id provided
-    if args.tenant_id:
-        verify_import(db_engine, args.tenant_id)
-
-    return 0
-
-
-if __name__ == '__main__':
-    sys.exit(main())
-
@@ -1,92 +0,0 @@
-#!/bin/bash
-
-# Unified data ingestion script for saas-search
-# Ingests data from MySQL to Elasticsearch
-#
-# [LEGACY] 此脚本仅保留用于历史兼容，不建议新流程继续使用。
-# 推荐改用：
-#   1) ./scripts/create_tenant_index.sh <tenant_id>
-#   2) POST /indexer/reindex
-
-cd "$(dirname "$0")/.."
-source /home/tw/miniconda3/etc/profile.d/conda.sh
-conda activate searchengine
-
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-RED='\033[0;31m'
-NC='\033[0m'
-
-echo -e "${GREEN}========================================${NC}"
-echo -e "${GREEN}数据灌入脚本${NC}"
-echo -e "${GREEN}========================================${NC}"
-
-# Load config from .env file if it exists
-if [ -f .env ]; then
-    set -a
-    source .env
-    set +a
-fi
-
-# Parameters
-TENANT_ID=${1:-""}
-RECREATE_INDEX=${2:-"false"}
-
-DB_HOST=${DB_HOST:-"120.79.247.228"}
-DB_PORT=${DB_PORT:-"3316"}
-DB_DATABASE=${DB_DATABASE:-"saas"}
-DB_USERNAME=${DB_USERNAME:-"saas"}
-DB_PASSWORD=${DB_PASSWORD:-"P89cZHS5d7dFyc9R"}
-ES_HOST=${ES_HOST:-"http://localhost:9200"}
-BATCH_SIZE=${BATCH_SIZE:-500}
-
-echo -e "\n${YELLOW}Configuration:${NC}"
-echo "  Tenant ID: $TENANT_ID"
-echo "  Recreate Index: $RECREATE_INDEX"
-echo "  MySQL: $DB_HOST:$DB_PORT/$DB_DATABASE"
-echo "  Elasticsearch: $ES_HOST"
-echo "  Batch Size: $BATCH_SIZE"
-
-# Validate parameters
-if [ -z "$TENANT_ID" ]; then
-    echo -e "${RED}ERROR: Tenant ID is required${NC}"
-    echo "Usage: $0 <tenant_id> [recreate_index]"
-    echo "  tenant_id: Required, tenant ID"
-    echo "  recreate_index: Optional, recreate index if exists (true/false, default: false)"
-    exit 1
-fi
-
-if [ -z "$DB_PASSWORD" ]; then
-    echo -e "${RED}ERROR: DB_PASSWORD未设置，请检查.env文件或环境变量${NC}"
-    exit 1
-fi
-
-# Build command
-CMD="python scripts/ingest_shoplazza.py \
-    --db-host $DB_HOST \
-    --db-port $DB_PORT \
-    --db-database $DB_DATABASE \
-    --db-username $DB_USERNAME \
-    --db-password $DB_PASSWORD \
-    --tenant-id $TENANT_ID \
-    --es-host $ES_HOST \
-    --batch-size $BATCH_SIZE"
-
-if [ "$RECREATE_INDEX" = "true" ] || [ "$RECREATE_INDEX" = "1" ]; then
-    CMD="$CMD --recreate"
-    echo -e "\n${YELLOW}Warning: Index will be deleted and recreated!${NC}"
-fi
-
-echo -e "\n${YELLOW}Starting data ingestion...${NC}"
-eval $CMD
-
-if [ $? -eq 0 ]; then
-    echo -e "\n${GREEN}========================================${NC}"
-    echo -e "${GREEN}数据灌入完成!${NC}"
-    echo -e "${GREEN}========================================${NC}"
-else
-    echo -e "\n${RED}========================================${NC}"
-    echo -e "${RED}数据灌入失败!${NC}"
-    echo -e "${RED}========================================${NC}"
-    exit 1
-fi
@@ -1,146 +0,0 @@
-#!/usr/bin/env python3
-"""
-Shoplazza data ingestion script.
-
-Loads SPU and SKU data from MySQL and indexes into Elasticsearch using SPU transformer.
-"""
-
-import sys
-import os
-import argparse
-from pathlib import Path
-
-# Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from utils.db_connector import create_db_connection
-from utils.es_client import ESClient
-from indexer.spu_transformer import SPUTransformer
-from indexer.mapping_generator import load_mapping, DEFAULT_INDEX_NAME
-from indexer.bulk_indexer import BulkIndexer
-
-
-def main():
-    parser = argparse.ArgumentParser(description='Ingest Shoplazza SPU/SKU data into Elasticsearch')
-    
-    # Database connection
-    parser.add_argument('--db-host', required=True, help='MySQL host')
-    parser.add_argument('--db-port', type=int, default=3306, help='MySQL port (default: 3306)')
-    parser.add_argument('--db-database', required=True, help='MySQL database name')
-    parser.add_argument('--db-username', required=True, help='MySQL username')
-    parser.add_argument('--db-password', required=True, help='MySQL password')
-    
-    # Tenant and index
-    parser.add_argument('--tenant-id', required=True, help='Tenant ID (required)')
-    parser.add_argument('--es-host', default='http://localhost:9200', help='Elasticsearch host')
-    
-    # Options
-    parser.add_argument('--recreate', action='store_true', help='Recreate index if exists')
-    parser.add_argument('--batch-size', type=int, default=500, help='Batch size for indexing (default: 500)')
-    
-    args = parser.parse_args()
-
-    print(f"Starting Shoplazza data ingestion for tenant: {args.tenant_id}")
-
-    # Load mapping from JSON file
-    try:
-        mapping = load_mapping()
-        print(f"Loaded mapping configuration")
-    except Exception as e:
-        print(f"ERROR: Failed to load mapping: {e}")
-        return 1
-
-    index_name = DEFAULT_INDEX_NAME
-
-    # Connect to MySQL
-    print(f"Connecting to MySQL: {args.db_host}:{args.db_port}/{args.db_database}")
-    try:
-        db_engine = create_db_connection(
-            host=args.db_host,
-            port=args.db_port,
-            database=args.db_database,
-            username=args.db_username,
-            password=args.db_password
-        )
-    except Exception as e:
-        print(f"ERROR: Failed to connect to MySQL: {e}")
-        return 1
-
-    # Connect to Elasticsearch
-    es_host = args.es_host
-    es_username = os.environ.get('ES_USERNAME')
-    es_password = os.environ.get('ES_PASSWORD')
-    
-    print(f"Connecting to Elasticsearch: {es_host}")
-    if es_username and es_password:
-        print(f"Using authentication: {es_username}")
-        es_client = ESClient(hosts=[es_host], username=es_username, password=es_password)
-    else:
-        es_client = ESClient(hosts=[es_host])
-    
-    if not es_client.ping():
-        print(f"ERROR: Cannot connect to Elasticsearch at {es_host}")
-        return 1
-
-    # Create index if needed
-    if args.recreate:
-        if es_client.index_exists(index_name):
-            print(f"Deleting existing index: {index_name}")
-            if not es_client.delete_index(index_name):
-                print(f"ERROR: Failed to delete index '{index_name}'")
-                return 1
-
-    if not es_client.index_exists(index_name):
-        print(f"Creating index: {index_name}")
-        if not es_client.create_index(index_name, mapping):
-            print(f"ERROR: Failed to create index '{index_name}'")
-            print("Please check the mapping configuration and try again.")
-            return 1
-    else:
-        print(f"Using existing index: {index_name}")
-
-    # Initialize SPU transformer
-    print(f"Initializing SPU transformer for tenant: {args.tenant_id}")
-    transformer = SPUTransformer(db_engine, args.tenant_id)
-
-    # Transform data
-    print("Transforming SPU and SKU data...")
-    try:
-        documents = transformer.transform_batch()
-        print(f"Transformed {len(documents)} SPU documents")
-    except Exception as e:
-        print(f"ERROR: Failed to transform data: {e}")
-        import traceback
-        traceback.print_exc()
-        return 1
-
-    if not documents:
-        print("WARNING: No documents to index")
-        return 0
-
-    # Bulk index
-    print(f"Indexing {len(documents)} documents (batch size: {args.batch_size})...")
-    indexer = BulkIndexer(es_client, index_name, batch_size=args.batch_size)
-    
-    try:
-        results = indexer.index_documents(documents, id_field="spu_id", show_progress=True)
-        print(f"\nIngestion complete:")
-        print(f"  Success: {results['success']}")
-        print(f"  Failed: {results['failed']}")
-        print(f"  Time: {results.get('elapsed_time', 0):.2f}s")
-        
-        if results['failed'] > 0:
-            print(f"\nWARNING: {results['failed']} documents failed to index")
-            return 1
-        
-        return 0
-    except Exception as e:
-        print(f"ERROR: Failed to index documents: {e}")
-        import traceback
-        traceback.print_exc()
-        return 1
-
-
-if __name__ == '__main__':
-    sys.exit(main())
-
@@ -1,184 +0,0 @@
-#!/usr/bin/env python3
-"""
-重建索引并导入数据的脚本。
-
-清除旧索引，使用新的mapping重建索引，然后导入数据。
-"""
-
-import sys
-import os
-import argparse
-from pathlib import Path
-
-# Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from utils.db_connector import create_db_connection
-from utils.es_client import ESClient
-from indexer.mapping_generator import load_mapping, delete_index_if_exists, DEFAULT_INDEX_NAME
-from indexer.spu_transformer import SPUTransformer
-from indexer.bulk_indexer import BulkIndexer
-
-
-def main():
-    parser = argparse.ArgumentParser(description='重建ES索引并导入数据')
-    
-    # Database connection
-    parser.add_argument('--db-host', help='MySQL host (或使用环境变量 DB_HOST)')
-    parser.add_argument('--db-port', type=int, help='MySQL port (或使用环境变量 DB_PORT, 默认: 3306)')
-    parser.add_argument('--db-database', help='MySQL database (或使用环境变量 DB_DATABASE)')
-    parser.add_argument('--db-username', help='MySQL username (或使用环境变量 DB_USERNAME)')
-    parser.add_argument('--db-password', help='MySQL password (或使用环境变量 DB_PASSWORD)')
-    
-    # Tenant and ES
-    parser.add_argument('--tenant-id', required=True, help='Tenant ID (必需)')
-    parser.add_argument('--es-host', help='Elasticsearch host (或使用环境变量 ES_HOST, 默认: http://localhost:9200)')
-    
-    # Options
-    parser.add_argument('--batch-size', type=int, default=500, help='批量导入大小 (默认: 500)')
-    parser.add_argument('--skip-delete', action='store_true', help='跳过删除旧索引步骤')
-    
-    args = parser.parse_args()
-
-    print("=" * 60)
-    print("重建ES索引并导入数据")
-    print("=" * 60)
-
-    # 加载mapping
-    print("\n[1/4] 加载mapping配置...")
-    try:
-        mapping = load_mapping()
-        print(f"✓ 成功加载mapping配置")
-    except Exception as e:
-        print(f"✗ 加载mapping失败: {e}")
-        return 1
-
-    index_name = DEFAULT_INDEX_NAME
-    print(f"索引名称: {index_name}")
-
-    # 连接Elasticsearch
-    print("\n[2/4] 连接Elasticsearch...")
-    es_host = args.es_host or os.environ.get('ES_HOST', 'http://localhost:9200')
-    es_username = os.environ.get('ES_USERNAME')
-    es_password = os.environ.get('ES_PASSWORD')
-    
-    print(f"ES地址: {es_host}")
-    if es_username:
-        print(f"ES用户名: {es_username}")
-    
-    try:
-        if es_username and es_password:
-            es_client = ESClient(hosts=[es_host], username=es_username, password=es_password)
-        else:
-            es_client = ESClient(hosts=[es_host])
-        
-        if not es_client.ping():
-            print(f"✗ 无法连接到Elasticsearch: {es_host}")
-            return 1
-        print("✓ Elasticsearch连接成功")
-    except Exception as e:
-        print(f"✗ 连接Elasticsearch失败: {e}")
-        return 1
-
-    # 删除旧索引
-    if not args.skip_delete:
-        print("\n[3/4] 删除旧索引...")
-        if es_client.index_exists(index_name):
-            print(f"发现已存在的索引: {index_name}")
-            if delete_index_if_exists(es_client, index_name):
-                print(f"✓ 成功删除索引: {index_name}")
-            else:
-                print(f"✗ 删除索引失败: {index_name}")
-                return 1
-        else:
-            print(f"索引不存在，跳过删除: {index_name}")
-    else:
-        print("\n[3/4] 跳过删除旧索引步骤")
-
-    # 创建新索引
-    print("\n[4/4] 创建新索引...")
-    try:
-        if es_client.index_exists(index_name):
-            print(f"✓ 索引已存在: {index_name}，跳过创建")
-        else:
-            print(f"创建索引: {index_name}")
-            if es_client.create_index(index_name, mapping):
-                print(f"✓ 成功创建索引: {index_name}")
-            else:
-                print(f"✗ 创建索引失败: {index_name}")
-                return 1
-    except Exception as e:
-        print(f"✗ 创建索引失败: {e}")
-        import traceback
-        traceback.print_exc()
-        return 1
-
-    # 连接MySQL
-    print("\n[5/5] 连接MySQL...")
-    db_host = args.db_host or os.environ.get('DB_HOST')
-    db_port = args.db_port or int(os.environ.get('DB_PORT', 3306))
-    db_database = args.db_database or os.environ.get('DB_DATABASE')
-    db_username = args.db_username or os.environ.get('DB_USERNAME')
-    db_password = args.db_password or os.environ.get('DB_PASSWORD')
-
-    if not all([db_host, db_database, db_username, db_password]):
-        print("✗ MySQL连接参数不完整")
-        print("请提供 --db-host, --db-database, --db-username, --db-password")
-        print("或设置环境变量: DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD")
-        return 1
-
-    print(f"MySQL: {db_host}:{db_port}/{db_database}")
-    try:
-        db_engine = create_db_connection(
-            host=db_host,
-            port=db_port,
-            database=db_database,
-            username=db_username,
-            password=db_password
-        )
-        print("✓ MySQL连接成功")
-    except Exception as e:
-        print(f"✗ 连接MySQL失败: {e}")
-        return 1
-
-    # 导入数据
-    print("\n[6/6] 导入数据...")
-    print(f"Tenant ID: {args.tenant_id}")
-    print(f"批量大小: {args.batch_size}")
-    
-    try:
-        transformer = SPUTransformer(db_engine, args.tenant_id)
-        print("正在转换数据...")
-        documents = transformer.transform_batch()
-        print(f"✓ 转换完成: {len(documents)} 个文档")
-        
-        if not documents:
-            print("⚠ 没有数据需要导入")
-            return 0
-
-        print(f"正在导入数据到ES (批量大小: {args.batch_size})...")
-        indexer = BulkIndexer(es_client, index_name, batch_size=args.batch_size)
-        results = indexer.index_documents(documents, id_field="spu_id", show_progress=True)
-        
-        print(f"\n{'='*60}")
-        print("导入完成!")
-        print(f"{'='*60}")
-        print(f"成功: {results['success']}")
-        print(f"失败: {results['failed']}")
-        print(f"耗时: {results.get('elapsed_time', 0):.2f}秒")
-        
-        if results['failed'] > 0:
-            print(f"\n⚠ 警告: {results['failed']} 个文档导入失败")
-            return 1
-        
-        return 0
-    except Exception as e:
-        print(f"✗ 导入数据失败: {e}")
-        import traceback
-        traceback.print_exc()
-        return 1
-
-
-if __name__ == '__main__':
-    sys.exit(main())
-
@@ -1,14 +0,0 @@
-#!/bin/bash
-
-echo "Installing server security dependencies..."
-
-# Check if we're in a conda environment
-if [ -z "$CONDA_DEFAULT_ENV" ]; then
-    echo "Warning: No conda environment detected. Installing with pip..."
-    pip install slowapi>=0.1.9 anyio>=3.7.0
-else
-    echo "Installing in conda environment: $CONDA_DEFAULT_ENV"
-    pip install slowapi>=0.1.9 anyio>=3.7.0
-fi
-
-echo "Dependencies installed successfully!"
 \ No newline at end of file
@@ -1,99 +0,0 @@
-#!/bin/bash
-#
-# 从远程 ES 的 search_products_tenant_170 同步 10000 条到本机 search_products_tenant_0。
-# 请求发往本机 ES，由本机去拉远程数据；需在本机 elasticsearch.yml 配置 reindex.remote.whitelist。
-#
-# 用法:
-#   ./scripts/reindex_from_remote_tenant_170_to_0.sh
-#
-# 环境变量（可选）:
-#   LOCAL_ES_HOST    本机 ES 地址，用于创建索引和发送 _reindex（默认从 .env 的 ES_HOST 读取，应为本机）
-#   REMOTE_ES_HOST   远程 ES 地址（默认 http://120.76.41.98:9200）
-#   REMOTE_ES_USER   远程 ES 用户名（默认 essa）
-#   REMOTE_ES_PASS   远程 ES 密码（默认 4hOaLaf41y2VuI8y）
-#   MAX_DOCS         同步条数（默认 10000）
-#
-
-set -e
-
-cd "$(dirname "$0")/.."
-PROJECT_ROOT="$(pwd)"
-
-# 加载 .env
-# shellcheck source=scripts/lib/load_env.sh
-source "${PROJECT_ROOT}/scripts/lib/load_env.sh"
-load_env_file "${PROJECT_ROOT}/.env"
-
-# 本机 ES（发 _reindex 请求的目标）
-LOCAL_ES_HOST="${LOCAL_ES_HOST:-${ES_HOST:-http://localhost:9200}}"
-ES_USERNAME="${ES_USERNAME:-}"
-ES_PASSWORD="${ES_PASSWORD:-}"
-ES_INDEX_NAMESPACE="${ES_INDEX_NAMESPACE:-}"
-
-# 远程 ES（数据源）
-REMOTE_ES_HOST="${REMOTE_ES_HOST:-http://120.76.41.98:9200}"
-REMOTE_ES_USER="${REMOTE_ES_USER:-essa}"
-REMOTE_ES_PASS="${REMOTE_ES_PASS:-4hOaLaf41y2VuI8y}"
-
-MAX_DOCS="${MAX_DOCS:-10000}"
-SOURCE_INDEX="search_products_tenant_170"
-DEST_INDEX="${ES_INDEX_NAMESPACE}search_products_tenant_0"
-MAPPING_FILE="${PROJECT_ROOT}/mappings/search_products.json"
-
-# 本机 curl 认证
-AUTH_PARAM=""
-if [ -n "$ES_USERNAME" ] && [ -n "$ES_PASSWORD" ]; then
-    AUTH_PARAM="-u ${ES_USERNAME}:${ES_PASSWORD}"
-fi
-
-echo "本机 ES: $LOCAL_ES_HOST"
-echo "远程 ES: $REMOTE_ES_HOST"
-echo "源索引:  $SOURCE_INDEX"
-echo "目标索引: $DEST_INDEX"
-echo "同步条数: $MAX_DOCS"
-echo ""
-
-# 1. 若目标索引不存在，则创建
-if ! curl -s $AUTH_PARAM "${LOCAL_ES_HOST}/${DEST_INDEX}" -o /dev/null -w "%{http_code}" | grep -q 200; then
-    echo "创建目标索引: $DEST_INDEX"
-    if [ ! -f "$MAPPING_FILE" ]; then
-        echo "错误: mapping 文件不存在: $MAPPING_FILE"
-        exit 1
-    fi
-    curl -X PUT "${LOCAL_ES_HOST}/${DEST_INDEX}" \
-        -H "Content-Type: application/json" \
-        $AUTH_PARAM \
-        -d @"${MAPPING_FILE}" \
-        -w "\nHTTP: %{http_code}\n" -s | tail -1
-    echo ""
-else
-    echo "目标索引已存在: $DEST_INDEX，将写入数据（可能覆盖同 id 文档）"
-fi
-
-# 2. Reindex from remote（JSON 中的密码用 env 传入，避免 shell 转义）
-echo "执行 Reindex from remote（最多 $MAX_DOCS 条）..."
-export REMOTE_ES_HOST REMOTE_ES_USER REMOTE_ES_PASS SOURCE_INDEX DEST_INDEX MAX_DOCS
-# ES 9.x 将 wait_for_completion 放在 query 参数，不在 body
-curl -X POST "${LOCAL_ES_HOST}/_reindex?wait_for_completion=true&pretty" \
-    -H "Content-Type: application/json" \
-    $AUTH_PARAM \
-    -d @- <<EOF
-{
-  "max_docs": ${MAX_DOCS},
-  "source": {
-    "remote": {
-      "host": "${REMOTE_ES_HOST}",
-      "username": "${REMOTE_ES_USER}",
-      "password": "${REMOTE_ES_PASS}"
-    },
-    "index": "${SOURCE_INDEX}",
-    "size": 500
-  },
-  "dest": {
-    "index": "${DEST_INDEX}"
-  }
-}
-EOF
-
-echo ""
-echo "完成。校验条数: curl $AUTH_PARAM '${LOCAL_ES_HOST}/${DEST_INDEX}/_count?pretty' -H 'Content-Type: application/json' -d '{\"query\":{\"match_all\":{}}}'"
@@ -1,10 +0,0 @@
-#!/bin/bash
-
-# Service start entrypoint.
-# Delegates to unified service controller.
-
-set -euo pipefail
-
-cd "$(dirname "$0")/.."
-
-./scripts/service_ctl.sh up "$@"
@@ -0,0 +1,5 @@
+# Manual Tests
+
+`tests/manual/` 存放需要人工启动依赖服务、手动观察结果或依赖真实外部环境的试跑脚本。
+
+这类脚本不属于 `pytest` 自动回归范围，也不应与 `tests/ci` 的契约测试混为一类。
@@ -4,9 +4,9 @@
  
 用法:
   1. 先启动 Indexer 服务: ./scripts/start_indexer.sh  (或 uvicorn api.indexer_app:app --port 6004)
-  2. 执行: python scripts/test_build_docs_api.py
+  2. 执行: python tests/manual/test_build_docs_api.py
  
-  也可指定地址: INDEXER_URL=http://localhost:6004 python scripts/test_build_docs_api.py
+  也可指定地址: INDEXER_URL=http://localhost:6004 python tests/manual/test_build_docs_api.py
 """
  
 import json
@@ -15,7 +15,7 @@ import sys
 from datetime import datetime, timezone
  
 # 项目根目录
-ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 sys.path.insert(0, ROOT)
  
 # 默认使用 requests 调真实服务；若未安装则回退到 TestClient
@@ -122,7 +122,7 @@ def main():
             print("\n[错误] 无法连接 Indexer 服务:", e)
             print("请先启动: ./scripts/start_indexer.sh  或  uvicorn api.indexer_app:app --port 6004")
             if HAS_REQUESTS:
-                print("或使用进程内测试: USE_TEST_CLIENT=1 python scripts/test_build_docs_api.py")
+                print("或使用进程内测试: USE_TEST_CLIENT=1 python tests/manual/test_build_docs_api.py")
             sys.exit(1)
     else:
         if not use_http and not HAS_REQUESTS:
@@ -12,8 +12,8 @@
 - 启动脚本：[`scripts/start_translator.sh`](/data/saas-search/scripts/start_translator.sh)
 - 虚拟环境：[`scripts/setup_translator_venv.sh`](/data/saas-search/scripts/setup_translator_venv.sh)
 - 模型下载：[`scripts/download_translation_models.py`](/data/saas-search/scripts/download_translation_models.py)
-- 本地模型压测：[`scripts/benchmark_translation_local_models.py`](/data/saas-search/scripts/benchmark_translation_local_models.py)
-- 聚焦压测脚本：[`scripts/benchmark_translation_local_models_focus.py`](/data/saas-search/scripts/benchmark_translation_local_models_focus.py)
+- 本地模型压测：[`benchmarks/translation/benchmark_translation_local_models.py`](/data/saas-search/benchmarks/translation/benchmark_translation_local_models.py)
+- 聚焦压测脚本：[`benchmarks/translation/benchmark_translation_local_models_focus.py`](/data/saas-search/benchmarks/translation/benchmark_translation_local_models_focus.py)
 - 基线性能报告：[`perf_reports/20260318/translation_local_models/README.md`](/data/saas-search/perf_reports/20260318/translation_local_models/README.md)
 - CT2 扩展报告：[`perf_reports/20260318/translation_local_models_ct2/README.md`](/data/saas-search/perf_reports/20260318/translation_local_models_ct2/README.md)
 - CT2 聚焦调优报告：[`perf_reports/20260318/translation_local_models_ct2_focus/README.md`](/data/saas-search/perf_reports/20260318/translation_local_models_ct2_focus/README.md)
@@ -550,8 +550,8 @@ curl -X POST http://127.0.0.1:6006/translate \
 - 切换到 CTranslate2 后需要重新跑一轮基准，尤其关注 `nllb-200-distilled-600m` 的单条延迟、并发 tail latency 和 `opus-mt-*` 的 batch throughput。
  
 性能脚本：
-- [`scripts/benchmark_translation_local_models.py`](/data/saas-search/scripts/benchmark_translation_local_models.py)
-- [`scripts/benchmark_translation_local_models_focus.py`](/data/saas-search/scripts/benchmark_translation_local_models_focus.py)
+- [`benchmarks/translation/benchmark_translation_local_models.py`](/data/saas-search/benchmarks/translation/benchmark_translation_local_models.py)
+- [`benchmarks/translation/benchmark_translation_local_models_focus.py`](/data/saas-search/benchmarks/translation/benchmark_translation_local_models_focus.py)
  
 数据集：
 - [`products_analyzed.csv`](/data/saas-search/products_analyzed.csv)
@@ -601,14 +601,14 @@ curl -X POST http://127.0.0.1:6006/translate \
  
 ```bash
 cd /data/saas-search
-./.venv-translator/bin/python scripts/benchmark_translation_local_models.py
+./.venv-translator/bin/python benchmarks/translation/benchmark_translation_local_models.py
 ```
  
 本轮扩展压测复现命令：
  
 ```bash
 cd /data/saas-search
-./.venv-translator/bin/python scripts/benchmark_translation_local_models.py \
+./.venv-translator/bin/python benchmarks/translation/benchmark_translation_local_models.py \
   --suite extended \
   --disable-cache \
   --serial-items-per-case 256 \
@@ -620,7 +620,7 @@ cd /data/saas-search
 单模型扩展压测示例：
  
 ```bash
-./.venv-translator/bin/python scripts/benchmark_translation_local_models.py \
+./.venv-translator/bin/python benchmarks/translation/benchmark_translation_local_models.py \
   --single \
   --suite extended \
   --model opus-mt-zh-en \
@@ -639,7 +639,7 @@ cd /data/saas-search
 单条请求延迟复现：
  
 ```bash
-./.venv-translator/bin/python scripts/benchmark_translation_local_models.py \
+./.venv-translator/bin/python benchmarks/translation/benchmark_translation_local_models.py \
   --single \
   --suite extended \
   --model nllb-200-distilled-600m \