Clean deploy v3.3.0

#U53cc#U4ed3#U5e93#U4fee#U590d#U8bf4#U660e.md

@@ -0,0 +1,37 @@
+# 数据服务修复说明（V2.2.4）
+
+本版本以当前 `main` 为基础恢复提交 `e1879a6` 的双仓库能力，没有回退后续侧栏、设置、元数据审计和真实 CSV 分析功能。
+
+## 已修复链路
+
+- 实时文件树同时读取：
+  - `globalsquiddatabase/squid_dataset`
+  - `globalsquiddatabase/Tuna-Fisheries-Dataset`
+- `fisheries_catalog`、`fisheries_inventory` 和 `fisheries_search` 返回每个文件的 `repository`。
+- `fisheries_analyze_export` 接受 `repository`，并从同一仓库完成路径核验、下载、分析和导出。
+- UI 数据集、详情、质量检查、元数据审计和服务状态均统计两个仓库。
+- 两个仓库分别缓存文件树、提交 SHA 和下载文件，避免同路径串库。
+- ICCAT `YearC` 可作为年份字段，并分别导出筛选明细、去重明细和年度汇总。
+- 清单工具兼容 `query/source` 参数，并过滤未执行的内部工具调用标记。
+- “确认/继续”等短回复会续接15分钟内的上一项数据请求；Ocean导出未指定格式时默认NetCDF并直接执行。
+
+## 部署后测试
+
+先执行：
+
+```text
+只查询 Tuna-Fisheries-Dataset，查找 ICCAT/EFFDIS_LL2000-2024.csv，并返回真实repository和path。
+```
+
+再执行：
+
+```text
+使用刚才返回的repository和path实际读取文件，报告字段、记录数、时间范围、缺失和完全重复记录，并导出CSV。
+```
+
+结果中的 `repository` 必须为 `globalsquiddatabase/Tuna-Fisheries-Dataset`。
+# V2.2.5 数据路由与真实执行校验
+
+- 补齐 IATTC、ICCAT、IOTC、CCSBT、EFFDIS 等金枪鱼数据源关键词，避免误入无工具的 Harness。
+- 补齐 v10、u10、t2m、msl 等 Ocean 变量关键词，并在来源缺省时按变量映射到对应数据源。
+- Ocean 导出必须有真实 export 工具完成事件，并返回下载链接或明确服务端错误；不再把“正在提交”当作完成。

.codewhale/mcp.json

@@ -0,0 +1,26 @@
+{
+  "timeouts": {
+    "connect_timeout": 15,
+    "execute_timeout": 900,
+    "read_timeout": 900
+  },
+  "servers": {
+    "marine": {
+      "command": "python3",
+      "args": [
+        "/home/user/app/marine_mcp.py"
+      ],
+      "disabled": false,
+      "required": false,
+      "env": {
+        "MARINE_API_URL": "${MARINE_API_URL}",
+        "HF_TOKEN": "${HF_TOKEN}",
+        "HF_DATASET_REPO": "${HF_DATASET_REPO}",
+        "HF_DATASET_REVISION": "${HF_DATASET_REVISION}",
+        "FISHERIES_EXPORT_ROOT": "${FISHERIES_EXPORT_ROOT}",
+        "HF_FISHERIES_CACHE_ROOT": "${HF_FISHERIES_CACHE_ROOT}",
+        "PUBLIC_BASE_URL": "${PUBLIC_BASE_URL}"
+      }
+    }
+  }
+}

.dockerignore

@@ -0,0 +1,11 @@
+.git
+.git/**
+.pytest_cache
+.pytest_cache/**
+__pycache__
+**/__pycache__
+*.pyc
+*.pyo
+.env
+*.log
+.DS_Store

.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,209 +1,8 @@
-# Byte-compiled / optimized / DLL files
+.DS_Store
+.env
+*.log
 __pycache__/
-*.py[cod]
-*$py.class
-*.pem
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other info into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
 .pytest_cache/
-pytest_cache/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   having to support multiple versions of Python.
-.python-version
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/#use-with-ide
-.pdm.toml
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# IDE - VS Code
-.vscode/
-*.code-workspace
-
-# IDE - PyCharm
-.idea/
-*.iml
-
-# IDE - Sublime Text
-*.sublime-workspace
-
-# IDE - Vim
-*.swp
-*.swo
-*~
-
-# IDE - Emacs
-*~
-\#*\#
-/.emacs.desktop
-/.emacs.desktop.lock
-*.elc
-auto-save-list
-tramp
-
-# macOS
-.DS_Store
-.AppleDouble
-.LSOverride
-Icon
-._*
-.DocumentRevisions-V100
-.fseventsd
-.Spotlight-V100
-.TemporaryItems
-.Trashes
-.VolumeIcon.icns
-.com.apple.timemachine.donotpresent
-.AppleDB
-.AppleDesktop
-Network Trash Folder
-Temporary Items
-.apdisk
-
-# Windows
-Thumbs.db
-Thumbs.db:encryptable
-ehthumbs.db
-ehthumbs_vista.db
-*.stackdump
-[Dd]esktop.ini
-$RECYCLE.BIN/
-*.cab
-*.msi
-*.msix
-*.msm
-*.msp
-*.lnk
-
-# Linux
-*~
-.fuse_hidden*
-.directory
-.Trash-*
-.nfs*
-
-# Project specific
-# Add any project-specific files or directories to ignore below
+*.pyc
+*.pyo
+project-data-package-*.zip

AGENTS.md

@@ -0,0 +1,135 @@
+# Marine Foundation Data Agent
+
+Use the `marine` MCP tools for all school-server requests.
+Never search `/tmp`, the Hugging Face container, or the workspace as a substitute for the school server.
+
+## Status tools
+- `mcp_marine_marine_health`
+- `mcp_marine_marine_domains`
+- `mcp_marine_marine_status`
+
+## Data retrieval tools
+- `mcp_marine_marine_query`: check dated data availability
+- `mcp_marine_marine_subset`: create a geographic NetCDF subset on the school server
+- `mcp_marine_marine_download`: convert an export token to an HTTPS URL
+
+Current retrieval MVP supports `ocean` + `oisst`, variables `sst`, `anom`, `err`, `ice`.
+For a requested file, use query/subset and return `download_url` directly.
+Do not claim retrieval is unavailable before trying these tools.
+Never present `/tmp/...` or school-server filesystem paths as download links.
+`done` means completed tasks, not necessarily physical file count.
+Default to concise Chinese.
+
+## Multi-format export (MVP)
+Use `mcp_marine_marine_export` when the user requests a specific output format.
+Supported formats: `netcdf`, `csv`, `xlsx`, `json`, `geotiff`, `png`.
+If export/download is requested without a format, default to `netcdf` and call
+`mcp_marine_marine_export` immediately; do not ask for confirmation. A short
+confirmation continues the most recent data request in the same thread.
+Return the absolute `download_url` directly to the user.
+Do not claim a format is unavailable before attempting this tool.
+
+## Ocean multi-source retrieval V3
+
+Validated sources:
+- cmems_physics: so, thetao, uo, vo
+- cmems_surface: mlotst, zos
+- cmems_bgc: chl, no3, nppv, o2, po4, si
+- cmems_carbonate: ph, spco2
+- era5: msl, t2m, u10, v10
+- era5_accum: e, slhf, sshf, ssrd, strd, tp
+- occci: chlor_a, chlor_a_log10_bias, chlor_a_log10_rmsd, total_nobs_sum
+- oisst: sst, anom, err, ice
+
+Tools:
+- mcp_marine_marine_catalog
+- mcp_marine_marine_query
+- mcp_marine_marine_subset
+- mcp_marine_marine_export
+
+Formats: netcdf, csv, xlsx, json, geotiff, png.
+For 3-D CMEMS variables, GeoTIFF/PNG require depth.
+Always return the absolute HTTPS download_url.
+Variable-only requests are still data requests: `v10`, `u10`, `t2m` and `msl`
+map to `era5`; do not send them to a tool-free chat path.
+
+
+## Fast retrieval routing V4
+
+When the user already specifies the requested date, geographic area,
+variable/source and output format, call `mcp_marine_marine_export`
+directly.
+
+Do not call catalog or query before export unless they are actually needed.
+
+Routing:
+- ask what sources/variables exist -> catalog
+- ask only whether a date/variable exists -> query
+- ask for an actual file -> export directly
+
+If export returns `status=error`, report its `detail` directly.
+
+Never silently:
+- change the requested date
+- change the requested source
+- change the requested variable
+- clamp an out-of-range depth
+- invent another depth
+- retry using nearby data
+
+Do not guess data values or unavailable model levels.
+
+## Hugging Face fisheries data plane V1
+
+The project has TWO different data planes:
+
+1. School Marine Server:
+   - Ocean environmental/physical/BGC/atmospheric data
+   - use `mcp_marine_marine_*`
+
+2. Hugging Face Dataset:
+   - Squid: `globalsquiddatabase/squid_dataset`
+   - Tuna: `globalsquiddatabase/Tuna-Fisheries-Dataset`
+   - use:
+     - `mcp_marine_fisheries_catalog`
+     - `mcp_marine_fisheries_inventory`
+     - `mcp_marine_fisheries_search`
+     - `mcp_marine_fisheries_data_rules`
+     - `mcp_marine_fisheries_analyze_export`
+
+Never conclude that fisheries data is absent merely because the school-server
+`tuna_data` or `squid_data` task database is empty.
+
+Aggregation:
+- catch -> SUM
+- effort -> SUM only within compatible units
+- CPUE -> recompute total catch / total effort
+- never average monthly CPUE
+- never fabricate daily fisheries data from monthly/annual products
+
+
+## Fisheries live inventory fast path
+
+For squid/tuna fisheries inventory, catalog, source availability, and "what files
+are already present" questions, the UI backend injects a
+`[HF_FISHERIES_LIVE_CONTEXT]` block from both live Hugging Face Dataset main trees.
+
+When that context is present:
+- for inventory/presence questions, answer directly from it;
+- do not call `start_mcp_server`;
+- do not infer availability from planning spreadsheets;
+- for actual fields, row counts, missing/duplicate checks, time/space filters,
+  aggregation or CSV export, call `mcp_marine_fisheries_analyze_export` and pass
+  the repository returned by search/inventory;
+- when `exports` contains filtered_raw, deduplicated and annual_summary, return
+  each distinct filename and download_url exactly once;
+- inventory example: `fisheries_inventory(domain="tuna", keyword="IATTC")`;
+  IATTC, ICCAT, IOTC and CCSBT names always identify Fisheries requests;
+  never print `<function_calls>`, `<invoke>` or `<parameter>` markup as text;
+- never substitute Web, Shell, Run, JS or a subagent for the restricted
+  fisheries content tool;
+- return its `download_url` directly and never invent theoretical rows as
+  actual observations.
+
+Marine MCP is reserved for school-server Ocean data and is connected lazily only
+when an Ocean request needs it.

DEPLOY.md

@@ -0,0 +1,55 @@
+# Deployment checklist
+
+Hugging Face Space type: Docker, preferably Private while testing.
+
+Required Space Secrets:
+- `OPENCODE_GO_API_KEY` (or the same key stored as `OPENAI_API_KEY`)
+- `CODEWHALE_RUNTIME_TOKEN`
+
+Recommended Space Secret:
+- `HF_TOKEN` with read access to any private/restricted fisheries Dataset used
+  by the Space. The two default public repositories can be read without a token.
+
+Required Space Variable:
+- `MARINE_API_URL`
+
+Optional Space Variables:
+- `HF_SQUID_DATASET_REPO` (default `globalsquiddatabase/squid_dataset`)
+- `HF_TUNA_DATASET_REPO` (default `globalsquiddatabase/Tuna-Fisheries-Dataset`)
+- `HF_SQUID_DATASET_REVISION` and `HF_TUNA_DATASET_REVISION` (optional approved
+  commit SHAs; otherwise each repository's current SHA is resolved and cached)
+- `PUBLIC_BASE_URL` (normally inferred from `SPACE_HOST`)
+- `HF_FISHERIES_MAX_CSV_BYTES` and `HF_FISHERIES_MAX_ZIP_BYTES`
+
+The current temporary Marine API URL can be used for the first smoke test.
+Later replace the Quick Tunnel with a fixed Named Tunnel URL.
+
+After the Space is Running:
+1. Open `/mobile` if the root does not redirect there.
+2. Test Ocean status: `检查我的海洋数据服务器，并告诉我三个数据中心状态。`
+3. Test a real fisheries CSV read/export:
+   `实际读取 current/sprfmo_effort.csv，报告字段、记录数、缺失、重复并导出 CSV。`
+4. Test Tuna routing and export:
+   `只查询 Tuna-Fisheries-Dataset，查找并读取 ICCAT/EFFDIS_LL2000-2024.csv，报告真实字段、记录数、缺失和重复并导出 CSV。`
+   Expected exports: filtered raw detail, exact-deduplicated detail and annual
+   summary. ICCAT `YearC` must be reported as the year field.
+5. Expected model-visible tools include
+   `mcp_marine_fisheries_analyze_export`.
+6. Open the returned `/api/fisheries/download/{token}` URL and confirm the CSV
+   downloads successfully.
+
+Next server phase:
+- add `/query`
+- add `/subset`
+- add `/download/{token}`
+- add job/update APIs
+Then extend `marine_mcp.py` with corresponding tools.
+
+## v3.3.0 deployment stability
+
+- `VERSION` is the single application version source.
+- Only root `app.html` is served; do not re-create `templates/app.html`.
+- `scripts/preflight.py` runs automatically from `start.sh` and fails fast if Space metadata or the frontend entry is inconsistent.
+- For durable user favorites and project-package downloads, attach Hugging Face Persistent Storage and set:
+  - `USER_STATE_ROOT=/data/squid_user_state`
+  - `PROJECT_PACKAGE_ROOT=/data/squid_project_packages`

Dockerfile

@@ -0,0 +1,32 @@
+FROM node:22-bookworm-slim
+
+USER root
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 python3-pip python3-venv ca-certificates curl git bash procps \
+    && rm -rf /var/lib/apt/lists/*
+
+# CodeWhale is the current continuation of DeepSeek-TUI.
+RUN npm install -g codewhale@0.9.10
+
+RUN usermod -l user -d /home/user -m node && groupmod -n user node
+
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:/usr/local/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    PORT=7860 \
+    DEEPSEEK_MCP_CONFIG=/home/user/app/.codewhale/mcp.json
+
+WORKDIR /home/user/app
+
+COPY --chown=user:user requirements.txt /home/user/app/requirements.txt
+
+RUN python3 -m pip install --break-system-packages --no-cache-dir -r /home/user/app/requirements.txt
+
+COPY --chown=user:user . /home/user/app
+
+RUN chmod +x /home/user/app/start.sh
+
+USER user
+
+CMD ["/home/user/app/start.sh"]

HuggingFace_Spaces_使用指南.md

@@ -1,1380 +0,0 @@
-# Hugging Face Spaces 使用指南
-
-## 目录
-
-- [简介](#简介)
-- [第一部分:创建个人空间](#第一部分创建个人空间)
-  - [1.1 账号注册](#11-账号注册)
-  - [1.2 创建新空间](#12-创建新空间)
-  - [1.3 空间基础配置](#13-空间基础配置)
-  - [1.4 初始化设置](#14-初始化设置)
-- [第二部分:克隆他人空间](#第二部分克隆他人空间)
-  - [2.1 网页控制台克隆(推荐)](#21-网页控制台克隆推荐)
-  - [2.2 Git命令克隆](#22-git命令克隆)
-  - [2.3 克隆私有空间](#23-克隆私有空间)
-  - [2.4 依赖环境配置](#24-依赖环境配置)
-- [第三部分:使用Git推送代码](#第三部分使用git推送代码)
-  - [3.1 本地仓库初始化](#31-本地仓库初始化)
-  - [3.2 Git认证配置](#32-git认证配置)
-  - [3.3 分支管理](#33-分支管理)
-  - [3.4 提交与推送](#34-提交与推送)
-- [常见问题与解决方案](#常见问题与解决方案)
-- [最佳实践建议](#最佳实践建议)
-
----
-
-## 简介
-
-Hugging Face Spaces 是一个免费托管机器学习应用的平台,支持 Gradio、Streamlit、Docker 等多种应用框架。Spaces 的底层是一个 Git 仓库,因此可以使用标准的 Git 工具进行代码管理和推送。本指南将详细介绍如何创建、克隆和管理 Hugging Face Spaces。
-
----
-
-## 第一部分:创建个人空间
-
-### 1.1 被号注册
-
-**步骤说明:**
-
-1. 访问 Hugging Face 官网:https://huggingface.co
-2. 点击右上角"Sign Up"按钮
-3. 填写注册信息:
-   - 用户名(username)
-   - 电子邮箱
-   - 密码
-4. 验证邮箱地址
-5. 登录账号
-
-**注意事项:**
-- 用户名一旦注册不可更改
-- 建议使用常用的邮箱地址,以便接收重要通知
-
-### 1.2 创建新空间
-
-**详细步骤:**
-
-1. **访问创建页面**
-   - 登录后,访问 https://huggingface.co/new
-   - 或点击顶部导航栏的"Spaces" → "Create new Space"
-
-2. **填写基本信息**
-   
-   | 配置项 | 说明 | 示例 |
-   |--------|------|------|
-   | Owner | 仓库所有者(个人或组织) | your-username |
-   | Space name | 空间名称 | my-demo-space |
-   | License | 许可证(可选) | mit, apache-2.0 |
-   | SDK | 应用框架选择 | gradio, streamlit, docker, static |
-
-3. **选择SDK类型**
-   
-   - **Gradio**: 最常用的选择,适合创建交互式 ML 演示
-   - **Streamlit**: 适合数据科学应用和可视化
-   - **Docker**: 完全自定义环境,适合复杂应用
-   - **Static**: 纯静态 HTML 网页
-
-4. **设置可见性**
-   
-   - **Public**: 公开,所有人可见(免费额度推荐)
-   - **Protected**: 需登录访问(PRO 计划)
-   - **Private**: 私有,仅自己和团队成员可见(Enterprise 计划)
-
-5. **点击"Create Space"完成创建**
-
-**创建后的初始页面:**
-
-创建成功后,你会看到一个空的仓库页面,包含以下预设文件:
-- `README.md`: 包含空间元数据的配置文件
-
-### 1.3 空间基础配置
-
-**README.md 元数据配置:**
-
-在 `README.md` 文件顶部有一个 YAML 配置块,定义了空间的运行参数:
-
-```yaml
----
-title: Demo Space            # 空间标题
-emoji: 🚀                    # 空间图标
-colorFrom: yellow            # 主题渐变起始颜色
-colorTo: orange              # 主题渐变结束颜色
-sdk: gradio                  # SDK类型
-sdk_version: 4.44.0          # SDK版本号
-app_file: app.py             # 应用入口文件
-pinned: false                # 是否固定在首页
-license: mit                 # 许可证类型
----
-```
-
-**关键配置项详解:**
-
-| 配置项 | 必填 | 说明 | 推荐值 |
-|--------|------|------|--------|
-| `sdk` | ✓ | 应用框架 | gradio, streamlit, docker |
-| `app_file` | ✓ | 入口文件名 | app.py 或 gradio_app.py |
-| `sdk_version` | ✓ | SDK版本 | 使用最新稳定版 |
-| `python_version` | ○ | Python版本 | 3.10.13(兼容性好) |
-| `hardware` | ○ | 硬件配置 | cpu-basic(免费), l4sx1(GPU) |
-| `startup_duration_timeout` | ○ | 启动超时 | 默认10分钟,大模型建议1h |
-
-**硬件配置选项:**
-
-```yaml
-# CPU 空间(免费)
-hardware: cpu-basic
-
-# GPU 空间(付费)
-hardware: t4-small          # T4 GPU,适合轻量模型
-hardware: a10g-small        # A10G GPU
-hardware: l4sx1             # L4S GPU,适合大模型
-```
-
-### 1.4 初始化设置
-
-**Web UI 方式(适合新手):**
-
-1. **添加应用文件**
-   - 点击"Files"标签页
-   - 点击"Add file" → "Upload file"
-   - 上传 `app.py`(应用代码)
-   - 上传 `requirements.txt`(依赖文件)
-
-2. **配置依赖**
-   
-   创建 `requirements.txt` 文件,列出所有 Python 依赖:
-
-   ```txt
-   # 基础依赖示例
-   gradio>=4.44.0
-   transformers>=4.40.0
-   torch>=2.3.0
-   
-   # 可选:指定 PyTorch CUDA 版本
-   --extra-index-url https://download.pytorch.org/whl/cu121
-   torch==2.3.0+cu121
-   ```
-
-3. **添加系统依赖**
-   
-   如需安装 Debian 系统包,创建 `packages.txt`:
-
-   ```txt
-   ffmpeg
-   libsm6
-   libxext6
-   ```
-
-**终端方式(推荐):**
-
-详见第三部分的 Git 推送流程。
-
----
-
-## 第二部分:克隆他人空间
-
-### 2.1 网页控制台克隆(推荐)
-
-Hugging Face 提供便捷的网页控制台克隆功能,可以快速将他人的 Space 复制到自己的账号下,无需使用 Git 命令。
-
-**操作步骤:**
-
-1. **访问目标 Space**
-   - 登录 Hugging Face
-   - 打开想要克隆的 Space 页面
-   - 例如:https://huggingface.co/spaces/username/space-name
-
-2. **点击克隆按钮**
-   - 在 Space 页面右上角找到三个点菜单(⋮)或链接/附件按钮
-   - 点击 **"Duplicate this Space"** 选项
-
-3. **配置克隆参数**
-   
-   在弹出的配置页面,可以修改以下属性:
-
-   | 配置项 | 说明 | 修改建议 |
-   |--------|------|----------|
-   | **Owner** | 新 Space 的所有者 | 选择你的用户名或组织 |
-   | **Space name** | 新 Space 的名称 | 可自定义新名称 |
-   | **Visibility** | 可见性设置 | 选择 Public 或 Private |
-   | **Hardware** | 硬件配置 | 可根据需求选择 CPU 或 GPU |
-
-4. **完成克隆**
-   - 点击"Duplicate Space"按钮
-   - 系统自动创建完整副本,包括所有文件、配置和历史记录
-   - 克隆完成后自动跳转到新 Space 页面
-
-**克隆特点:**
-
-- ✓ **完整复制**: 包含所有代码文件(app.py, requirements.txt 等)
-- ✓ **保留配置**: README.md 元数据、SDK 设置自动保留
-- ✓ **独立运行**: 克隆后的 Space 完全独立,不影响原 Space
-- ✓ **可自定义**: 可修改硬件配置、可见性等参数
-
-**重要提示:**
-
-⚠️ **Secrets不会自动复制**: 原 Space 中的环境变量、API密钥等 Secrets 需要手动重新添加。
-
-添加 Secrets 的步骤:
-1. 进入克隆后的 Space 页面
-2. 点击"Settings"标签页
-3. 找到"Repository secrets"部分
-4. 点击"Add secret"
-5. 添加所需的环境变量(如 HF_TOKEN, API_KEY 等)
-
-**使用场景:**
-
-网页控制台克隆特别适合以下情况:
-- 快速基于他人模板创建自己的应用
-- 测试和修改公开的演示 Space
-- 学习他人的实现方式并进行定制
-- 为团队创建私有副本用于内部开发
-
-### 2.2 Git命令克隆
-
-如果你需要将 Space 克隆到本地进行修改,可以使用 Git 命令。
-
-**准备工作:**
-
-1. **安装 Git**
-   
-   ```bash
-   # macOS
-   brew install git
-   
-   # Linux (Ubuntu/Debian)
-   sudo apt-get install git
-   
-   # Windows
-   # 从 https://git-scm.com/download/win 下载安装包
-   ```
-
-2. **验证安装**
-
-   ```bash
-   git --version  # 检查 Git 版本
-   ```
-
-**标准克隆流程:**
-
-```bash
-# 1. 克隆 Space 仓库
-git clone https://huggingface.co/spaces/username/space-name
-
-# 2. 进入克隆的目录
-cd space-name
-
-# 3. 查看文件结构
-ls -la
-```
-
-**克隆不同类型的仓库:**
-
-```bash
-# 克隆模型仓库
-git clone https://huggingface.co/username/model-name
-
-# 克隆数据集仓库
-git clone https://huggingface.co/datasets/username/dataset-name
-
-# 克隆 Space
-git clone https://huggingface.co/spaces/username/space-name
-
-# 使用 SSH 克隆(需配置 SSH 密钥)
-git clone git@hf.co:username/space-name
-```
-
-**克隆后的操作:**
-
-克隆到本地后,你可以:
-- 查看代码结构和实现逻辑
-- 在本地修改并测试
-- 推送到你自己的 Space(需先创建新的 Space)
-- 学习他人的最佳实践
-
-### 2.3 克隆私有空间
-
-克隆私有 Space 需要认证配置。
-
-**步骤1:生成访问令牌(Access Token)**
-
-1. 登录 Hugging Face
-2. 访问 https://huggingface.co/settings/tokens
-3. 点击"Create new token"
-4. 填写令牌信息:
-   - **Name**: 令牌名称(如"dev-machine")
-   - **Role**: 权限类型
-     - `read`: 仅下载(克隆私有仓库)
-     - `write`: 可上传(推送代码)
-   - **Expiration**: 过期时间(建议30天)
-5. 点击"Generate token"
-6. **立即复制并保存令牌**(令牌格式:`hf_xxxxxxxxxxxx`,只显示一次)
-
-**步骤2:配置认证**
-
-**方法1:使用 Hugging Face CLI(推荐)**
-
-```bash
-# 安装 huggingface_hub CLI
-pip install huggingface_hub[cli]
-
-# 交互式登录
-huggingface-cli login
-# 输入粘贴令牌: hf_xxxxxxxxxxxxxxxxxxxxxxxx
-# 添加 Git 凭证? [Y/n] 输入 Y
-
-# 验证登录状态
-huggingface-cli whoami
-# 输出:
-# username: your-username
-# auth_token: hf_xxxxxxxxxxxxxxxxxxxx
-```
-
-**方法2:使用环境变量(适合 CI/CD)**
-
-```bash
-# 设置环境变量
-export HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxxxx"
-
-# 克隆私有仓库(自动使用 HF_TOKEN)
-git clone https://huggingface.co/spaces/username/private-space
-```
-
-**方法3:在克隆 URL 中嵌入令牌(不推荐)**
-
-```bash
-# 直接在 URL 中使用令牌
-git clone https://oauth2:hf_xxxxxxxxxxxxxxxxxxxx@huggingface.co/spaces/username/private-space
-
-# 注意:这种方式会将令牌暴露在命令历史中,不安全
-```
-
-**步骤3:克隆私有空间**
-
-```bash
-# 克隆私有空间(已配置认证后)
-git clone https://huggingface.co/spaces/username/private-space
-
-# 进入目录并查看
-cd private-space
-ls -la
-```
-
-**Windows 用户特别注意:**
-
-Windows 系统中,令牌存储位置为 `%USERPROFILE%\\.huggingface\token`,而非 Linux/Mac 的 `~/.huggingface/token`。如果 Git 推送失败,需配置 Windows 凭证管理器:
-
-```bash
-# Windows PowerShell
-git config --global credential.helper wincred
-huggingface-cli login
-```
-
-### 2.4 依赖环境配置
-
-**Python 依赖管理:**
-
-克隆后的空间通常包含 `requirements.txt`,需要在本地安装依赖:
-
-```bash
-# 进入克隆的 Space 目录
-cd space-name
-
-# 创建虚拟环境(推荐)
-python -m venv venv
-source venv/bin/activate  # Linux/Mac
-# 或 venv\Scripts\activate  # Windows
-
-# 安装依赖
-pip install -r requirements.txt
-
-# 如果包含自定义 PyTorch CUDA 版本,确保匹配本地环境
-cat requirements.txt | grep extra-index-url
-```
-
-**处理特殊依赖:**
-
-某些 Space 可能需要额外的配置:
-
-```bash
-# 1. pre-requirements.txt(优先安装的依赖)
-# 用于更新 pip 或安装前置依赖
-pip install -r pre-requirements.txt
-
-# 2. packages.txt(系统级依赖)
-# Debian 系统包,需要在 Linux 环境安装
-# macOS/Windows 无法直接安装,需手动替代方案
-
-# 3. apt-packages.txt(另一种系统依赖格式)
-sudo apt-get update && sudo apt-get install -y $(cat apt-packages.txt)
-```
-
-**检查依赖完整性:**
-
-```bash
-# 验证关键库是否安装
-pip list | grep -E "gradio|streamlit|torch|transformers"
-
-# 检查版本匹配
-pip show gradio
-pip show torch
-```
-
----
-
-## 第三部分:使用Git推送代码
-
-### 3.1 本地仓库初始化
-
-**场景1:克隆已有空间并修改**
-
-```bash
-# 1. 克隆你的 Space
-git clone https://huggingface.co/spaces/your-username/space-name
-cd space-name
-
-# 2. 查看当前状态
-git status
-git log --oneline -5  # 查看最近5次提交
-```
-
-**场景2:本地项目推送到新建的空 Space**
-
-```bash
-# 1. 本地项目目录
-cd my-local-project
-
-# 2. 初始化 Git 仓库
-git init
-
-# 3. 添加远程仓库
-git remote add origin https://huggingface.co/spaces/your-username/space-name
-
-# 4. 查看远程仓库配置
-git remote -v
-# 输出:
-# origin  https://huggingface.co/spaces/your-username/space-name (fetch)
-# origin  https://huggingface.co/spaces/your-username/space-name (push)
-```
-
-**必要文件准备:**
-
-推送前确保包含以下文件:
-
-```bash
-# 检查必要文件
-ls -la
-
-# 必须包含:
-# - README.md     (包含 YAML 元数据)
-# - app.py        (应用入口)
-# - requirements.txt (Python 依赖)
-
-# 可选文件:
-# - packages.txt   (系统依赖)
-# - LICENSE        (许可证)
-```
-
-### 3.2 Git认证配置
-
-**认证方法对比:**
-
-| 方法 | 适用场景 | 安全性 | 配置位置 |
-|------|----------|--------|----------|
-| huggingface-cli login | 本地开发 | ✓ 安全 | ~/.huggingface/token |
-| HF_TOKEN 环境变量 | CI/CD | ✓ 安全(需 masking) | 环境变量 |
-| SSH 密钥 | 频繁推送 | ✓✓ 最安全 | ~/.ssh/id_rsa |
-| URL 嵌入令牌 | 临时使用 | ✗ 不安全 | 命令历史 |
-
-**推荐配置流程:**
-
-```bash
-# 1. 生成访问令牌
-# 访问 https://huggingface.co/settings/tokens
-# 创建 "write" 类型令牌
-
-# 2. 配置 Git 凭证
-huggingface-cli login --token hf_xxxxxxxxxxxxxxxxxxxx
-
-# 3. 配置 Git 凭证持久化
-git config --global credential.helper store  # Linux/Mac
-# 或 git config --global credential.helper wincred  # Windows
-
-# 4. 验证认证
-huggingface-cli whoami
-
-# 5. 测试推送权限
-git push --dry-run  # 模拟推送,不实际提交
-```
-
-**SSH 认证配置(高级):**
-
-```bash
-# 1. 生成 SSH 密钥
-ssh-keygen -t ed25519 -C "your-email@example.com"
-# 保存到 ~/.ssh/id_ed25519_hf
-
-# 2. 添加公钥到 Hugging Face
-cat ~/.ssh/id_ed25519_hf.pub
-# 复制内容,访问 https://huggingface.co/settings/keys
-# 添加新的 SSH 密钥
-
-# 3. 配置 SSH 别名
-cat >> ~/.ssh/config << EOF
-Host hf.co
-    HostName huggingface.co
-    User git
-    IdentityFile ~/.ssh/id_ed25519_hf
-EOF
-
-# 4. 使用 SSH 推送
-git remote set-url origin git@hf.co:spaces/your-username/space-name
-git push
-```
-
-### 3.3 分支管理
-
-**Hugging Face Spaces 的分支特点:**
-
-- Spaces 仅使用 `main` 分支作为运行环境
-- 其他分支可用于开发,但不会触发 Space 构建
-- 推送到 `main` 分支会自动重建并重启 Space
-
-**分支操作示例:**
-
-```bash
-# 1. 查看当前分支
-git branch
-# * main
-
-# 2. 创建开发分支
-git checkout -b dev-feature
-
-# 3. 在开发分支提交修改
-git add app.py
-git commit -m "Add new feature"
-
-# 4. 切换回 main 分支
-git checkout main
-
-# 5. 合并开发分支
-git merge dev-feature
-
-# 6. 推送 main 分支(触发 Space 重建)
-git push origin main
-```
-
-**使用 Pull Request 流程:**
-
-```bash
-# 1. 创建功能分支
-git checkout -b feature-new-model
-
-# 2. 提交修改
-git add .
-git commit -m "Add new model integration"
-
-# 3. 推送功能分支
-git push origin feature-new-model
-
-# 4. 在 Hugging Face Web UI 创建 Pull Request
-# 访问 Space 页面 → "Pull requests" → "New pull request"
-
-# 5. 合并 PR 后,Space 自动重建
-```
-
-### 3.4 提交与推送
-
-**标准提交流程:**
-
-```bash
-# 1. 查看待提交的文件
-git status
-
-# 2. 添加文件到暂存区
-# 方式A:添加所有修改
-git add .
-
-# 方式B:添加特定文件(推荐)
-git add app.py requirements.txt README.md
-
-# ⚠️ 不要添加敏感文件
-# 检查是否有 .env, credentials.json 等
-git status | grep -E ".env|credentials|secrets"
-
-# 3. 创建提交
-git commit -m "Update app with new model"
-
-# 提交信息最佳实践:
-# - 使用简洁描述(不超过50字符)
-# - 说明修改内容,而非修改方式
-# - 示例:
-#   ✓ "Add sentiment analysis feature"
-#   ✓ "Fix memory leak in model loading"
-#   ✓ "Update transformers to 4.40.0"
-#   ✗ "Fixed stuff"
-#   ✗ "Update"
-
-# 4. 推送到远程仓库
-git push origin main
-# 或
-git push  # 如果默认分支已设置
-
-# 5. 查看推送结果
-git log --oneline -3
-```
-
-**使用 Hugging Face CLI 上传(简化流程):**
-
-```bash
-# 安装 CLI
-pip install huggingface_hub[cli]
-
-# 直接上传文件或文件夹
-huggingface-cli upload your-username/space-name ./app.py
-
-# 上传整个目录
-huggingface-cli upload your-username/space-name ./my-project
-
-# 指定提交信息
-huggingface-cli upload your-username/space-name ./model.safetensors \
-  --commit-message "Add trained model weights"
-
-# 查看上传结果
-huggingface-cli repo-files your-username/space-name
-```
-
-**自动化推送(使用 Python):**
-
-```python
-from huggingface_hub import HfApi
-import os
-
-# 初始化 API 客户端
-api = HfApi(token=os.getenv('HF_TOKEN'))
-
-# 上传单个文件
-api.upload_file(
-    path_or_fileobj="./app.py",
-    path_in_repo="app.py",
-    repo_id="your-username/space-name",
-    repo_type="space",
-    commit_message="Update application"
-)
-
-# 上传整个文件夹
-api.upload_folder(
-    folder_path="./my-project",
-    repo_id="your-username/space-name",
-    repo_type="space",
-    commit_message="Deploy new version"
-)
-```
-
----
-
-## 常见问题与解决方案
-
-### 问题1:推送时认证失败(401 Unauthorized)
-
-**原因**: Token 未配置或权限不足
-
-**解决方案**:
-
-```bash
-# 1. 检查当前认证状态
-huggingface-cli whoami
-
-# 2. 如果未认证,重新登录
-huggingface-cli login --token hf_xxxxxxxxxxxxxxxx
-
-# 3. 确认 Token 类型为 "write"
-# 访问 https://huggingface.co/settings/tokens 检查
-
-# 4. 配置 Git 凭证持久化
-git config --global credential.helper store
-
-# 5. 测试推送
-git push --dry-run
-```
-
-### 问题2:推送后 Space 启动失败
-
-**原因**: 配置文件缺失或格式错误
-
-**解决方案**:
-
-```bash
-# 1. 检查 README.md 的 YAML 配置
-head -n 20 README.md
-
-# 确保 YAML 块格式正确:
-# ---
-# title: ...
-# sdk: gradio
-# app_file: app.py
-# ---
-# (注意 "---" 分隔符)
-
-# 2. 检查 requirements.txt 格式
-cat requirements.txt
-
-# 避免常见错误:
-# ✗ 使用 Windows 换行符(CRLF)
-# ✓ 使用 Unix 换行符(LF)
-
-# 转换换行符:
-dos2unix requirements.txt  # Linux/Mac
-# 或在文本编辑器设置 LF 换行
-
-# 3. 检查 app.py 是否存在且语法正确
-python -m py_compile app.py
-
-# 4. 查看 Space 构建日志
-# 访问 Space 页面 → "Logs" 标签页
-```
-
-### 问题3:依赖安装失败
-
-**原因**: 版本冲突或平台不兼容
-
-**解决方案**:
-
-```txt
-# 修改 requirements.txt
-
-# 1. 使用灵活的版本约束
-# ✗ transformers==4.40.0  (严格版本)
-# ✓ transformers>=4.40.0  (最低版本)
-
-# 2. 处理 PyTorch CUDA 版本
-# 如果本地无 GPU,安装 CPU 版本
---extra-index-url https://download.pytorch.org/whl/cpu
-torch>=2.3.0
-
-# 3. 分离系统依赖和 Python 依赖
-# packages.txt 内容:
-ffmpeg
-libgl1-mesa-glx
-
-# 4. 检查依赖冲突
-pip check
-```
-
-### 问题4:Space 冷启动超时
-
-**原因**: 模型加载时间过长
-
-**解决方案**:
-
-```yaml
-# 在 README.md 添加超时配置
----
-title: Large Model Demo
-sdk: gradio
-startup_duration_timeout: 1h  # 增加到 1 小时
----
-```
-
-```python
-# 在 app.py 中优化模型加载
-import gradio as gr
-from transformers import pipeline
-
-# 使用缓存
-@gr.cache_resource
-def load_model():
-    return pipeline("text-generation", model="large-model")
-
-# 分步加载(如果模型组件多)
-def load_model_lazy():
-    # 首次请求时加载
-    pass
-```
-
-### 问题5:克隆私有空间权限被拒绝
-
-**原因**: Token 权限不足或已过期
-
-**解决方案**:
-
-```bash
-# 1. 检查 Token 状态
-# 访问 https://huggingface.co/settings/tokens
-# 检查 Token 是否被撤销或过期
-
-# 2. 重新生成 Token
-# 创建新的 "read" 类型 Token
-
-# 3. 清除旧 Token
-huggingface-cli logout
-
-# 4. 使用新 Token 登录
-huggingface-cli login --token hf_new_token_xxxxxx
-
-# 5. 配置 Git 凭证
-git config --global credential.helper store
-
-# 6. 再次克隆
-git clone https://huggingface.co/spaces/username/private-space
-```
-
-### 问题6:推送包含敏感文件
-
-**原因**: 误提交了 .env 或 credentials 文件
-
-**解决方案**:
-
-```bash
-# 1. 立即撤销 Token
-# 访问 https://huggingface.co/settings/tokens
-# 撤销相关 Token
-
-# 2. 从 Git 历史中删除敏感文件
-git filter-branch --force --index-filter \
-  'git rm --cached --ignore-unmatch .env credentials.json' \
-  --prune-empty --tag-name-filter cat -- --all
-
-# 3. 强制推送清理后的历史
-git push origin main --force
-
-# ⚠️ 注意:强制推送会重写历史,谨慎操作
-
-# 4. 配置 .gitignore
-cat >> .gitignore << EOF
-.env
-*.env
-credentials.json
-secrets.yaml
-*.pem
-EOF
-
-# 5. 生成新 Token
-huggingface-cli login
-```
-
-### 问题7:网页克隆后 Secrets 未复制
-
-**原因**: Hugging Face 安全机制,Secrets 需手动添加
-
-**解决方案**:
-
-```bash
-# 1. 进入克隆后的 Space
-# 访问 https://huggingface.co/spaces/your-username/cloned-space
-
-# 2. 点击 Settings 标签页
-
-# 3. 找到 Repository secrets 部分
-
-# 4. 手动添加所需 Secrets
-# 示例:
-# HF_TOKEN = hf_xxxxxxxxxxxxxxxx
-# API_KEY = your_api_key
-# DATABASE_URL = your_database_url
-
-# 5. 在代码中使用 Secrets
-import os
-hf_token = os.getenv('HF_TOKEN')
-api_key = os.getenv('API_KEY')
-```
-
-### 问题8:克隆后本地运行失败
-
-**原因**: 系统依赖缺失或环境不匹配
-
-**解决方案**:
-
-```bash
-# 1. 检查 Python 版本匹配
-python --version
-cat README.md | grep python_version
-
-# 2. 安装系统依赖
-# 查看 packages.txt
-cat packages.txt
-
-# Linux: 直接安装
-sudo apt-get install -y $(cat packages.txt)
-
-# macOS: 使用替代方案
-brew install ffmpeg libsm libxext
-
-# Windows: 手动下载安装包
-
-# 3. 检查 CUDA 版本(如使用 GPU)
-nvidia-smi
-cat requirements.txt | grep extra-index-url
-
-# 4. 创建虚拟环境并重新安装依赖
-python -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
-```
-
----
-
-## 最佳实践建议
-
-### 1. 文件组织结构
-
-**推荐的 Space 目录结构:**
-
-```
-my-space/
-├── README.md              # 元数据配置(必须)
-├── app.py                 # 应用入口(必须)
-├── requirements.txt       # Python 依赖(必须)
-├── packages.txt           # 系统依赖(可选)
-├── .gitignore             # Git 忽略规则(推荐)
-├── assets/                # 静态资源
-│   ├── logo.png
-│   └── styles.css
-├── utils/                 # 工具函数
-│   ├── __init__.py
-│   └── helpers.py
-└── tests/                 # 测试文件(可选)
-    └── test_app.py
-```
-
-### 2. README.md 配置规范
-
-**完整配置示例:**
-
-```yaml
----
-# 基本信息
-title: My ML Demo
-emoji: 🤖
-colorFrom: blue
-colorTo: green
-
-# SDK 配置
-sdk: gradio
-sdk_version: 4.44.0
-python_version: "3.10.13"
-app_file: app.py
-
-# 硬件配置
-hardware: cpu-basic        # 免费 CPU
-# 或 hardware: l4sx1      # GPU(付费)
-
-# 性能配置
-startup_duration_timeout: 15m  # 启动超时(默认)
-pinned: false               # 是否固定在首页
-
-# 许可证
-license: apache-2.0
-
-# 描述
-short_description: A machine learning demo application
-tags:
-  - machine-learning
-  - transformers
-  - gradio
----
-```
-
-### 3. requirements.txt 编写规范
-
-**示例:**
-
-```txt
-# 优先设置 PyTorch 源(如需 CUDA)
---extra-index-url https://download.pytorch.org/whl/cu121
-
-# 核心框架
-gradio>=4.44.0,<5.0.0      # 主框架(限制版本范围)
-streamlit>=1.40.0          # Streamlit 版本(如使用)
-
-# ML 库
-transformers>=4.40.0       # 灵活版本约束
-torch>=2.3.0               # PyTorch
-accelerate>=0.25.0         # 加速库
-
-# 数据处理
-datasets>=2.19.0
-numpy>=1.24.0,<2.0.0
-pandas>=2.0.0
-
-# 可选:精确版本(确保兼容)
-# transformers==4.40.0
-# torch==2.3.0+cu121
-```
-
-**版本约束最佳实践:**
-
-- 使用 `>=` 确保最低版本
-- 使用 `<` 限制上限版本,避免破坏性更新
-- 关键依赖使用精确版本 `==`,确保一致性
-- 测试兼容性后再推送到 Space
-
-### 4. Git 工作流程
-
-**推荐的开发流程:**
-
-```bash
-# 1. 本地开发(在功能分支)
-git checkout -b feature-improvement
-
-# 2. 本地测试
-python app.py  # 确保应用可运行
-
-# 3. 提交修改
-git add app.py
-git commit -m "Improve model loading performance"
-
-# 4. 推送功能分支
-git push origin feature-improvement
-
-# 5. 创建 Pull Request(在 Web UI)
-# 审核修改,确保无误
-
-# 6. 合并 PR 到 main
-# Space 自动重建
-
-# 7. 监控构建日志
-# 访问 Space → "Logs" 标签页
-
-# 8. 测试线上应用
-# 如失败,快速回滚:
-git revert HEAD
-git push origin main
-```
-
-### 5. 安全配置
-
-**敏感信息管理:**
-
-```bash
-# 1. 配置 .gitignore
-cat > .gitignore << EOF
-# 环境变量
-.env
-*.env.local
-
-# 凭证文件
-credentials.json
-secrets.yaml
-*.pem
-*.key
-
-# 缓存和临时文件
-__pycache__/
-*.pyc
-.cache/
-*.tmp
-
-# IDE 配置
-.vscode/
-.idea/
-*.swp
-EOF
-
-# 2. 使用 Space Secrets(推荐)
-# 在 Space Settings → "Repository secrets" 添加:
-# HF_TOKEN = hf_xxxxxxxx
-# API_KEY = your_api_key
-
-# 在代码中读取:
-import os
-api_key = os.getenv('API_KEY')
-```
-
-**Python 代码示例:**
-
-```python
-import os
-import gradio as gr
-
-# 从环境变量读取 Secrets(推荐)
-hf_token = os.getenv('HF_TOKEN')
-api_key = os.getenv('API_KEY')
-
-# ✗ 不要硬编码
-# hf_token = "hf_xxxxxxxxxxxxxx"  # 危险!
-
-# ✓ 使用环境变量
-if not hf_token:
-    raise ValueError("HF_TOKEN environment variable not set")
-
-# 使用 huggingface_hub 的内置认证
-from huggingface_hub import HfApi
-api = HfApi()  # 自动读取 HF_TOKEN 或 ~/.huggingface/token
-```
-
-### 6. 性能优化
-
-**模型加载优化:**
-
-```python
-# 1. 使用缓存
-import gradio as gr
-from transformers import pipeline
-
-# Gradio 缓存装饰器
-@gr.cache_resource
-def load_model():
-    return pipeline("text-generation", model="gpt2")
-
-# 2. 指定缓存目录
-from transformers import AutoModel
-import os
-
-cache_dir = "/tmp/model_cache"  # Spaces 推荐使用 /tmp
-model = AutoModel.from_pretrained(
-    "bert-base-uncased",
-    cache_dir=cache_dir
-)
-
-# 3. 懒加载(首次请求时加载)
-class ModelLoader:
-    _model = None
-    
-    @classmethod
-    def get_model(cls):
-        if cls._model is None:
-            cls._model = pipeline("sentiment-analysis")
-        return cls._model
-
-# 使用
-model = ModelLoader.get_model()
-```
-
-**requirements.txt 优化:**
-
-```txt
-# 减少依赖大小
-# ✗ 安装完整的 transformers[torch]
-# ✓ 仅安装必要组件
-transformers
-torch --index-url https://download.pytorch.org/whl/cpu  # CPU 版本更小
-
-# 使用轻量级替代
-# ✗ tensorflow>=2.0  (体积大)
-# ✓ torch>=2.0       (相对更小)
-
-# 禁用不必要的功能
-# 在 torch 安装时添加:
---no-deps torch  # 跳过可选依赖
-pip install torch --no-deps
-```
-
-### 7. 文档与注释
-
-**README.md 内容建议:**
-
-```markdown
----
-title: My ML Demo
-sdk: gradio
-app_file: app.py
----
-
-# My ML Demo
-
-## 简介
-这是一个使用 Transformers 库的情感分析演示应用。
-
-## 功能
-- 文本情感分析
-- 多语言支持(英语、中文)
-- 实时结果展示
-
-## 使用方法
-1. 输入文本
-2. 点击"分析"按钮
-3. 查看情感分类结果
-
-## 技术栈
-- Gradio 4.44.0
-- Transformers 4.40.0
-- PyTorch 2.3.0
-
-## 作者
-Your Name (@your-username)
-
-## 许可证
-Apache 2.0
-```
-
-**代码注释规范:**
-
-```python
-"""
-应用主文件:app.py
-功能:Hugging Face Spaces 情感分析演示
-作者:Your Name
-日期:2026-07-13
-"""
-
-import gradio as gr
-from transformers import pipeline
-import os
-
-# 模型加载函数(使用缓存优化性能)
-@gr.cache_resource
-def load_sentiment_model():
-    """
-    加载情感分析模型
-    返回:Transformers pipeline 对象
-    """
-    model_name = "distilbert-base-uncased-finetuned-sst-2-english"
-    
-    # 从环境变量读取 Token(如有私有模型)
-    hf_token = os.getenv('HF_TOKEN')
-    
-    # 创建 pipeline(自动处理模型下载和缓存)
-    pipe = pipeline(
-        "sentiment-analysis",
-        model=model_name,
-        token=hf_token  # 可选:访问私有模型
-    )
-    
-    return pipe
-
-# Gradio 接口定义
-def analyze_text(text):
-    """
-    分析输入文本的情感
-    参数:text(str) - 用户输入文本
-    返回:dict - 情感分析结果(标签和分数)
-    """
-    if not text:
-        return {"label": "无输入", "score": 0.0}
-    
-    # 获取模型(缓存的)
-    pipe = load_sentiment_model()
-    
-    # 执行分析
-    result = pipe(text)[0]
-    
-    return result
-
-# 创建 Gradio 应用
-demo = gr.Interface(
-    fn=analyze_text,
-    inputs=gr.Textbox(label="输入文本", placeholder="请输入要分析的文本..."),
-    outputs=gr.JSON(label="分析结果"),
-    title="情感分析演示",
-    description="使用 DistilBERT 模型进行文本情感分析"
-)
-
-# 启动应用(Spaces 自动调用)
-if __name__ == "__main__":
-    demo.launch()
-```
-
-### 8. 版本控制最佳实践
-
-**提交信息规范:**
-
-```bash
-# 提交信息格式
-git commit -m "<类型>: <简短描述>"
-
-# 类型标签:
-# feat:     新功能
-# fix:      Bug 修复
-# docs:     文档更新
-# style:    格式调整
-# refactor: 重构代码
-# test:     测试相关
-# chore:    构建/工具更新
-
-# 示例:
-git commit -m "feat: Add multi-language support"
-git commit -m "fix: Resolve model loading timeout issue"
-git commit -m "docs: Update README with usage instructions"
-git commit -m "chore: Upgrade transformers to 4.40.0"
-```
-
-**分支命名规范:**
-
-```bash
-# 功能分支
-feature-add-model
-feature-optimize-performance
-
-# 修复分支
-fix-authentication-error
-fix-memory-leak
-
-# 文档分支
-docs-readme-update
-docs-api-guide
-
-# 发布分支
-release-v1.0.0
-release-v2.0.0
-```
-
----
-
-## 附录
-
-### A.常用命令速查表
-
-| 操作 | 命令 |
-|------|------|
-| 安装 Git | `brew install git` (macOS) |
-| 克隆 Space | `git clone https://huggingface.co/spaces/user/space` |
-| 配置认证 | `huggingface-cli login --token hf_xxxx` |
-| 查看认证状态 | `huggingface-cli whoami` |
-| 添加文件 | `git add app.py requirements.txt` |
-| 提交修改 | `git commit -m "Update message"` |
-| 推送到远程 | `git push origin main` |
-| 上传文件(CLI) | `huggingface-cli upload user/space ./file` |
-| 查看远程仓库 | `git remote -v` |
-| 查看提交历史 | `git log --oneline -10` |
-
-### B.Hugging Face CLI 常用命令
-
-```bash
-# 认证管理
-huggingface-cli login              # 交互式登录
-huggingface-cli login --token hf_xxx  # Token 登录
-huggingface-cli logout             # 退出登录
-huggingface-cli whoami             # 查看当前用户
-
-# 仓库管理
-huggingface-cli repo create my-space --type space --space-sdk gradio
-huggingface-cli repo delete user/space --type space
-
-# 文件上传
-huggingface-cli upload user/space ./app.py
-huggingface-cli upload user/space ./folder --commit-message "Add files"
-
-# 文件下载
-huggingface-cli download user/model ./model.safetensors
-
-# 仓库信息
-huggingface-cli repo-info user/space --repo-type space
-```
-
-### C.环境变量说明
-
-| 变量名 | 说明 | 使用场景 |
-|--------|------|----------|
-| `HF_TOKEN` | Hugging Face 访问令牌 | CI/CD,私有仓库访问 |
-| `HF_HOME` | Hugging Face 缓存目录 | 自定义缓存位置 |
-| `HUGGINGFACE_HUB_CACHE` | Hub 缓存目录 | 模型缓存路径 |
-| `TRANSFORMERS_CACHE` | Transformers 缓存 | 模型文件缓存 |
-| `HF_DATASETS_CACHE` | 数据集缓存 | 数据集文件缓存 |
-
-### D.相关资源链接
-
-- **官方文档**: https://huggingface.co/docs
-- **Spaces 概览**: https://huggingface.co/docs/hub/spaces-overview
-- **配置参考**: https://huggingface.co/docs/hub/spaces-config-reference
-- **依赖管理**: https://huggingface.co/docs/hub/spaces-dependencies
-- **Git 操作指南**: https://huggingface.co/docs/hub/repositories-getting-started
-- **Token 设置**: https://huggingface.co/settings/tokens
-- **SSH 密钥配置**: https://huggingface.co/settings/keys
-- **Python SDK 文档**: https://huggingface.co/docs/huggingface_hub
-- **CLI 工具指南**: https://huggingface.co/docs/huggingface_hub/guides/cli
-
----
-
-**文档版本**: 2.0  
-**更新日期**: 2026-07-13  
-**基于**: Hugging Face 官方文档(2026版本)及社区最佳实践  
-**更新说明**: 移除 Git LFS 相关内容,新增网页控制台克隆功能说明

README.md

@@ -1,257 +1,227 @@
 ---
-title: Myspace
-emoji: 📊
-colorFrom: yellow
-colorTo: blue
-sdk: gradio
-sdk_version: 6.20.0
-python_version: '3.13'
-app_file: app.py
-pinned: false
-license: mit
-short_description: 测试空间
+title: Global Marine Foundation Data Agent
+emoji: 🌊
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
-
-# 渔业数据智能查询代理
-
-基于 Hugging Face **smolagents** 框架构建的自然语言查询智能代理，面向渔业科研数据场景，支持查询 logbook 捕捞日志可用性、以及 GFW 渔船作业努力量检索，通过 Gradio Web 界面提供交互式体验。
-
-## 主要功能
-
-- **自然语言查询**：用户以中文自然语言描述需求，代理自动提取参数并调用对应工具
-- **Logbook 可用性查询**：按海区、年份范围、物种、数据类型筛选捕捞日志数据
-- **GFW 作业努力量查询**：按时间（2012-2024）、空间范围、船旗国、渔具类型检索渔船作业数据
-- **CPUE 文献查询**：查询单位捕捞努力量渔获量相关研究文献，支持按海区、年份、物种等筛选
-- **SPRFMO 数据查询**：查询南太平洋区域渔业管理组织数据，支持捕捞量/努力量查询和聚合统计
-- **交互式 Web 界面**：基于 Gradio 的 Chat 界面，支持流式输出和步骤可视化
-
-## 目录结构
-
-```
-myspace/
-├── app.py                         # 主程序入口，包含 Agent 定义、Tool 类、Web 界面启动
-├── query_tools/                   # 查询工具模块目录
-│   ├── __init__.py                # 模块初始化文件
-│   ├── logbook_availability_query.py  # Logbook 数据可用性查询函数
-│   ├── query_gfw.py               # GFW 渔船作业努力量查询函数（2012-2024）
-│   ├── literature_cpue_query.py   # 文献 CPUE 数据查询函数
-│   └── query_sprfmo.py            # SPRFMO 南太平洋数据查询函数
-├── requirements.txt               # Python 依赖清单
-└── .gradio/                       # Gradio 自动生成的 SSL 证书目录
-    └── certificate.pem
-```
-
-| 文件/目录 | 说明 |
-|------|------|
-| `app.py` | 项目核心文件，包含 5 个 Tool 类（参数提取、Logbook 查询、GFW 查询、CPUE 文献查询、SPRFMO 查询）、Agent 工厂函数和 GradioUI 启动入口 |
-| `query_tools/` | 查询工具模块目录，统一管理所有数据查询工具 |
-| `query_tools/logbook_availability_query.py` | Logbook 查询模块，读取本地 CSV 数据并支持多维度筛选与文件输出 |
-| `query_tools/query_gfw.py` | GFW 查询模块，从嵌套 ZIP 中提取月度 CSV 数据并按时空范围筛选（仅支持 2012-2024 年数据） |
-| `query_tools/literature_cpue_query.py` | 文献 CPUE 数据查询模块，已集成到 Agent |
-| `query_tools/query_sprfmo.py` | SPRFMO 南太平洋数据查询模块，已集成到 Agent |
-| `requirements.txt` | 项目 Python 依赖包清单 |
-
-## 技术栈
-
-| 类别 | 技术 | 用途 |
-|------|------|------|
-| Agent 框架 | smolagents | 智能代理核心框架（ToolCallingAgent） |
-| LLM 接入 | OpenAIServerModel / DeepSeek API | 大语言模型推理，支持工具调用 |
-| Web 界面 | GradioUI (Gradio) | 交互式 Chat 界面，流式输出 |
-| 数据处理 | pandas | 数据读取、筛选、格式转换 |
-| 数据源 | Hugging Face Datasets | 远程数据集下载（huggingface_hub） |
-| 文件解析 | zipfile / openpyxl / csv | ZIP 解压、Excel/CSV 解析 |
-| 模块组织 | Python Package (query_tools) | 查询工具统一管理 |
-| 编程语言 | Python 3.12+ | 项目开发语言 |
+# Global Marine Foundation Data Agent
+
+Current UI release: **v3.3.0**.
+
+
+## v3.3.0 稳定性重构（第一阶段）
+
+- 新增根目录 `VERSION`，后端与前端统一从同一版本源渲染，避免版本号漂移。
+- 运行时仅服务根目录 `app.html`；发布包不再携带第二份 `templates/app.html`。
+- 新增 `scripts/preflight.py`，启动前检查 Hugging Face README 元数据、Docker 入口、单一模板、版本占位符与缓存污染。
+- 新增 `.dockerignore`，发布镜像排除 `.pytest_cache`、`__pycache__`、`.pyc` 等开发缓存。
+- 项目数据包下载 token 改为磁盘索引；配置 Persistent Storage 时可在 Space 重启后继续恢复未过期 ZIP。
+- `/api/ui/info` 增加版本来源、单模板状态与收藏/项目数据包存储模式，方便部署诊断。
+
+
+V2.3.0 makes the home Ocean / Tuna / Squid cards functional: they now load live catalog/inventory state, open a data-center panel, jump to filtered dataset views, and start domain-aware queries. The sidebar now adds live badges, Ocean/Tuna/Squid shortcuts, recent-conversation search, and synced favorites/task counters.
+
+V2.2.5 routes IATTC/ICCAT/IOTC/CCSBT and Ocean variable-only prompts such as
+`v10` directly to the Fisheries/Ocean data runtime. Ocean export requests are
+now accepted as complete only after the real export tool returns either an
+actual download URL or an explicit server error; progress-only claims are
+rejected instead of being shown as successful submissions.
+
+V2.2.4 keeps a 15-minute per-thread pending data request so short follow-ups
+such as “确认” or “继续” are routed back to the Ocean/Fisheries tool runtime with
+the original parameters instead of being sent to the tool-free Harness path.
+Ocean export requests without an explicit format now default to NetCDF and run
+immediately without asking for a second confirmation.
+
+V2.2.3 accepts `query` and `source` as compatibility aliases for Fisheries
+inventory calls, while retaining `domain` and `keyword` as the preferred
+schema. Literal `<function_calls>`, `<invoke>` and `<parameter>` blocks are now
+removed before browser output; a response containing only leaked tool-planning
+text fails closed instead of exposing internal markup.
+
+V2.2.2 recognizes ICCAT `YearC` as a year field and returns separately named
+filtered-raw, exact-deduplicated and annual-summary CSV exports. Repeated copies
+of the same download URL are shown only once in the chat UI.
+
+V2.2.1 restores the dual Hugging Face fisheries repository route after the
+V2.2 content-analysis refactor. Inventory, search, live UI context, file
+validation, download, analysis and export now preserve repository provenance
+for both `globalsquiddatabase/squid_dataset` and
+`globalsquiddatabase/Tuna-Fisheries-Dataset`. Repository selection is restricted
+to these two configured datasets.
+
+V2.2 adds a restricted Hugging Face fisheries content plane.  The Agent can
+now validate an exact live-tree path, pin the current Dataset commit SHA,
+download CSV/TSV or CSV/TSV members inside ZIP files within configured size
+limits, report actual fields/rows/missing values/duplicates, apply year and
+bounding-box filters, calculate monthly counts and annual sums, and return a
+tokenized CSV download URL.  It does not enable arbitrary Shell, URL, repository
+or filesystem access.  Large ZIP processing uses a streamed local cache and a
+longer MCP timeout; production-scale repeated GFW queries should still be moved
+to query-ready partitions on the school server.
+
+V1.6.1 fixes Hugging Face inventory counting: directory entries carrying
+`size=0` are no longer counted as files. Sources that are absent from the live
+main branch are labeled as not ingested rather than as read failures.
 
-## 环境要求与前置条件
+V1.7 adds Fisheries source-category filtering, ingested/missing source totals,
+classification evidence in dataset details, and a UTF-8 CSV export of the
+current live inventory.
 
-- **Python**：3.12 或更高版本
-- **Hugging Face Token**：拥有 HF 账号并在 Settings 中申请 Read 权限的 Access Token（用于访问数据集）
-- **LLM API Key**：DeepSeek API Key 或其他 OpenAI 兼容服务的 API Key
-- **数据文件**（Logbook/GFW 查询需要）：
-  - Logbook：本地需有 `../data/logbook_availability.csv` 数据文件
-  - GFW：本地需有 GFW ZIP 数据包，或自动从 `~/Desktop/资料下载/柔鱼数据/` 搜索
+V1.8 adds a live Hugging Face repository hygiene report covering zero-byte
+files, duplicate basenames, unmapped paths, large files, extension distribution
+and repository-residue files, with a downloadable JSON report. These checks do
+not claim that same-name files have identical content.
 
-## 安装与配置
+V1.9 translates common service fields and states into Chinese, adds actionable
+chat error recovery controls, task progress indicators and JSON result export,
+and introduces functional longitude-range and local/UTC display preferences.
+Conversation history and favorites remain browser-local until the Memory API
+offers stable record update/delete operations; the UI does not claim that they
+are synchronized across devices.
 
-### 1. 克隆项目
+V2.0 adds explicit dataset metadata-completeness evidence, including returned
+and missing core fields in details and comparisons. Settings now include a
+default export format, answer detail level, 10/30/50-item local history limits,
+and optional download confirmation. Static dataset catalogs are maintained in
+`sidebar_catalog.py`, while the main workspace page lives in
+`templates/app.html`; this reduces the risk of UI edits changing data-routing
+rules. Cross-device conversation and favorite synchronization remains disabled
+until stable server-side update/delete endpoints exist.
 
-```bash
-cd /your/workspace
-git clone <repository-url> testAgent
-cd testAgent
-```
+V2.1 adds a consolidated metadata audit for all configured Ocean and Fisheries
+sources. It reports evidence-based completeness, missing core fields and a
+recommended next action, and exports the audit as UTF-8 CSV. Settings also add
+a validated JSON workspace backup/restore flow for browser-local conversations,
+favorites and preferences. Backups exclude credentials, tokens and uploaded
+file contents, providing a manual cross-device migration path without claiming
+server-side synchronization.
 
-### 2. 创建虚拟环境（推荐）
+Custom chat UI backed by CodeWhale/DeepSeek and a restricted Marine MCP bridge.
 
-```bash
-conda create -n agentproject python=3.12
-conda activate agentproject
-```
+Public UI: port 7860.
+Private CodeWhale Runtime: 127.0.0.1:7878.
+The Runtime token never enters the browser.
 
-### 3. 安装依赖
+## Functional sidebar
 
-```bash
-pip install -r requirements.txt
-```
+The main UI provides six real views:
 
-依赖清单：
+- 对话助手：chat, uploads, recent conversations and generated downloads.
+- 数据集：live Ocean catalog plus the Hugging Face fisheries main-tree inventory, with Chinese labels, filters, favorites, on-demand details, live Ocean date/variable availability checks, searchable Fisheries file inventory, comparison for up to three datasets and CSV comparison export.
+- 数据服务：runtime, Marine API, Ocean/Tuna/Squid domains and Hugging Face health.
+- 我的任务：user-isolated processing tasks and generated assets, with Chinese operation/status labels, search/status filters and structured quality-check summaries.
+- 收藏：browser-persistent dataset and assistant-answer bookmarks scoped by user id.
+- 设置：font size, Enter behavior, status refresh, accent color, default view, compact/reduced-motion modes, local-history controls and deployment version information.
 
-| 包名 | 最低版本 | 用途 |
-|------|---------|------|
-| `smolagents[gradio]` | >=1.0.0 | Agent 框架 + Gradio 集成 |
-| `requests` | >=2.31.0 | HTTP 请求 |
-| `pandas` | >=2.0.0 | 数据处理 |
-| `huggingface_hub` | >=0.23.0 | HF 数据集 API |
-| `openpyxl` | >=3.1.0 | Excel 文件解析 |
-| `openai` | >=2.0.0 | OpenAI 兼容 LLM 接入 |
+Read-only sidebar endpoints:
 
-### 4. 配置常量
+- `GET /api/sidebar/datasets`
+- `GET /api/sidebar/datasets/{group}/{source_key}`
+- `POST /api/sidebar/datasets/ocean/{source_key}/availability`
+- `GET /api/sidebar/datasets/fisheries/{source_key}/files`
+- `GET /api/sidebar/datasets/quality`
+- `GET /api/sidebar/datasets/metadata-audit`
+- `GET /api/sidebar/services`
+- `GET /api/sidebar/tasks?user_id=...`
 
-编辑 `readData.py` 文件顶部的常量：
+Authenticated deployments validate the Supabase bearer token on every endpoint.
+The task endpoint filters server-side by the resolved authenticated user id.
 
-```python
-# Hugging Face 数据集访问 Token
-HF_TOKEN = "hf_你的Token"
-
-# LLM API 配置
-OPENAI_API_KEY = "sk-你的APIKey"
-OPENAI_API_BASE = "https://api.deepseek.com/v1"  # API 地址
-MODEL_ID = "deepseek-chat"                        # 模型 ID
-
-# DeepSeek 思考模式
-THINKING_MODE_ENABLED = True   # True 启用，False 禁用
-THINKING_EFFORT = "high"       # low/medium/high/max
-```
 
-**常见 API 地址配置**：
+## v2.3.1 card click reliability fix
+- Ocean/Tuna/Squid homepage cards now have direct click and keyboard handlers plus JS fallbacks.
+- Added visible v2.3.1 marker in header to verify the deployed frontend is the new build.
+- If the modal container is unavailable, card click falls back to the filtered datasets view instead of doing nothing.
 
-| 服务 | `OPENAI_API_BASE` | `MODEL_ID` |
-|------|-------------------|------------|
-| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
-| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
-| 本地 Ollama | `http://localhost:11434/v1` | 模型名称 |
-| 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | `glm-4-flash` |
 
-> **注意**：使用 DeepSeek 思考模式时必须选择 `deepseek-chat`，`deepseek-reasoner` 不支持工具调用。
+## v2.3.3 fisheries service summary fix
 
-## 本地开发启动
+- Fixed `Hugging Face Fisheries` showing `undefined` in the Data Services view.
+- The services API now exposes a stable combined repository label and repository availability counts.
+- Added frontend fallbacks so missing optional API fields never render as `undefined`.
+- Updated the visible build marker and default app version to v2.3.3.
 
-```bash
-cd /your/workspace/myspace
-python3 app.py
-```
 
-启动后终端将输出：
+## v2.4.0 fisheries file workflow
 
-```
-正在启动 GradioUI Web 界面...
-Running on local URL:  http://127.0.0.1:7860
-Running on public URL: https://xxxxx.gradio.live  (72小时有效)
-```
+- Fisheries file rows are now clickable instead of display-only.
+- Added per-file detail card with repository, file size and extension.
+- Added one-click handoff from a concrete Tuna/Squid file into the chat for analysis.
+- Added file-level favorites and copy-path actions.
+- Kept live Hugging Face inventory and existing v2.3.3 service summary behavior unchanged.
 
-浏览器打开上述地址即可使用 Chat 界面进行查询。
 
-## 生产环境部署
+## v2.4.1 metadata audit only
 
-### 方式一：直接运行
+This build is based directly on v2.4.0. It intentionally does **not** include the
+experimental dataset-card click-handler changes. The only functional change is the
+metadata audit: Ocean and Fisheries now use separate evidence rules, Fisheries
+file-content fields are shown as pending file-level verification rather than false
+0% missing metadata, and Ocean audit evidence is merged from the Marine API catalog,
+status and domains endpoints.
 
-```bash
-# 前台运行
-python3 app.py
 
-# 后台运行（使用 nohup）
-nohup python3 app.py > agent.log 2>&1 &
-```
+## v2.5.0 favorites workflow
 
-### 方式二：Docker 部署
+- Preserves the v2.4.1 metadata-audit-only behavior and all existing dataset buttons/data connections.
+- Fisheries file favorites are now a first-class `file` type instead of being mixed with dataset favorites.
+- Favorites page adds dataset/file/answer counts, type filter, search, file repository/path display, copy-path action, and one-click return to chat analysis.
+- Workspace backup/restore preserves the new file favorite type.
 
-```dockerfile
-FROM python:3.12-slim
 
-WORKDIR /app
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
+## v2.6.0 task workflow
 
-COPY . .
+- “我的任务”升级为任务工作台：区分处理中、已完成、失败和数据资产。
+- 任务支持详情抽屉、复制任务编号、导出 JSON、携带结构化结果继续对话分析。
+- 后端任务摘要增加关联会话、上传文件和数据来源字段，便于追溯任务上下文。
+- 数据资产支持详情、来源/文件类型展示、下载以及一键进入对话继续分析。
+- 任务和资产均增加搜索筛选，保留 v2.5.0 收藏工作流和 v2.4.1 元数据审计逻辑。
 
-# 暴露 Gradio 默认端口
-EXPOSE 7860
+## v2.7.0 service diagnostics
 
-CMD ["python3", "app.py"]
-```
+- 数据服务页面新增综合健康状态、健康检查计数、平均响应时延和慢响应统计。
+- Marine API `/health`、`/domains`、`/status/ocean` 与 Hugging Face Fisheries 读取增加毫秒级响应耗时。
+- 新增“服务诊断详情”抽屉，集中展示逐项状态、诊断建议与失败/慢响应项。
+- 支持复制诊断摘要和导出诊断 JSON，便于部署排障和路演现场快速反馈。
+- 保留 v2.6.0 任务工作台、v2.5.0 收藏工作流、v2.4.1 元数据审计与既有数据集按钮行为。
 
-```bash
-docker build -t fishery-agent .
-docker run -d -p 7860:7860 \
-  -e HF_TOKEN=hf_你的Token \
-  -e OPENAI_API_KEY=sk_你的Key \
-  fishery-agent
-```
 
-### 方式三：Systemd 服务
+## v2.8.1 项目数据包
 
-```ini
-[Unit]
-Description=Fishery Data Query Agent
-After=network.target
+侧边栏新增“项目数据包”。输入研究/项目描述后，系统会基于当前已接入的 Ocean、Tuna 和 Squid 数据目录推荐所需数据，并可生成 ZIP。ZIP 按数据库分类为 `Ocean/`、`Tuna-Fisheries-Dataset/`、`squid_dataset/`；同时包含 `manifest.json` 和 `README.md`。Hugging Face 渔业数据会在配置的包大小上限内复制真实仓库文件；Ocean 在描述中能够识别具体日期和海域时会调用学校 Marine API 导出真实 NetCDF，否则在 `Ocean/data_requests.json` 中保留待补充的请求清单，避免伪造数据。
 
-[Service]
-Type=simple
-User=your_user
-WorkingDirectory=/your/workspace/myspace
-ExecStart=/your/venv/bin/python3 app.py
-Restart=on-failure
-RestartSec=5
+## v2.8.1 项目数据包
 
-[Install]
-WantedBy=multi-user.target
-```
+侧边栏新增“项目数据包”。输入研究/项目描述后，系统会基于当前已接入的 Ocean、Tuna 和 Squid 数据目录推荐所需数据，并可生成 ZIP。ZIP 按数据库分类为 `Ocean/`、`Tuna-Fisheries-Dataset/`、`squid_dataset/`；同时包含 `manifest.json` 和 `README.md`。Hugging Face 渔业数据会在配置的包大小上限内复制真实仓库文件；Ocean 在描述中能够识别具体日期和海域时会调用学校 Marine API 导出真实 NetCDF，否则在 `Ocean/data_requests.json` 中保留待补充的请求清单，避免伪造数据。
 
-## 使用示例
 
-### 示例 1：查询 Logbook 数据可用性
+## v2.8.1
+- 项目数据包侧边栏入口增加静态节点 + JavaScript 自愈注入双保险。
+- 新增 `/api/ui/info` 用于确认实际运行模板、版本和项目数据包功能是否加载。
+- 运行时统一以 `templates/app.html` 为唯一服务模板，根目录 `app.html` 仅保持镜像一致。
 
-```
-用户：2010到2020年东南太平洋有哪些鱿鱼捕捞日志数据？
-```
 
-代理将调用 `logbook_query` 工具，参数提取为 `region="东南太平洋"`, `year_start=2010`, `year_end=2020`, `species="鱿鱼"`。
+## v2.8.2 单一前端模板修复
+- 运行时只读取仓库根目录 `app.html`，不再依赖 `templates/app.html`。
+- 修复 Hugging Face 网页上传时根目录文件已更新、嵌套模板仍停留旧版导致“版本/功能不一致”的问题。
+- 应用版本改为代码内固定 `2.8.2`，不再被 Space 中遗留的 `APP_VERSION=2.8.0` 变量覆盖。
+- 保留项目数据包侧栏入口及其 ZIP 按数据库分类打包功能。
 
-### 示例 2：查询 GFW 渔船作业努力量
+## v2.9.0 项目数据方案确认
 
-```
-用户：查询2012年1月太平洋区域中国渔船的作业努力量
-```
+“项目数据包”升级为两阶段工作流：先分析项目并生成推荐数据方案，再由用户勾选/取消具体 Ocean 与 Fisheries 数据源，最后只打包所选来源。界面会提示 Ocean 自动导出所缺的日期/海域条件；未补充时仍可生成 ZIP，并在 Ocean 目录保留可复现的数据请求清单。后端新增 `selected_ocean_keys` 与 `selected_fisheries_names`，确保 ZIP 内容与前端确认清单一致。
 
-代理将调用 `gfw_query` 工具，参数提取为 `year=2012`, `month=1`, `flag="CN"`，以及对应的经纬度范围。
+## v3.1.0 数据包预估与清单预览
 
-注意：GFW 查询仅支持 **2012-2024 年** 的数据，超出范围会返回错误。
+“项目数据包”新增生成前预估：根据 Hugging Face 实时文件树计算所选 Fisheries 候选文件数量与已知大小，并按 Ocean / Tuna-Fisheries-Dataset / squid_dataset 汇总。Ocean NetCDF 因需实际导出，预估阶段明确标记为“大小未知”，避免伪造估算值。ZIP 生成完成后可直接查看已打包文件清单，再决定是否下载；完整来源与跳过原因仍写入 `manifest.json`。
 
-### 示例 3：无明确工具指向的查询
 
-```
-用户：帮我查一下有什么数据可以用
-```
+## v3.2.0 用户消息快捷操作触发方式
 
-代理将根据系统提示词中加载的数据集文件列表，告知用户可用的数据和查询方式。
-
-## Agent 工具一览
-
-| 工具名 | 类名 | 功能 | 必填参数 |
-|--------|------|------|---------|
-| `parameter_extractor` | `ParameterExtractionTool` | 从自然语言提取数据集查询参数 | `user_input` |
-| `logbook_query` | `LogbookQueryTool` | 查询 Logbook 捕捞日志可用性 | 无（均为可选） |
-| `gfw_query` | `GfwQueryTool` | 查询 GFW 渔船作业努力量（2012-2024） | `year`, `month`, `lat_min`, `lat_max`, `lon_min`, `lon_max` |
-| `literature_cpue_query` | `LiteratureCpueQueryTool` | 查询 CPUE 相关文献数据 | 无（均为可选） |
-| `sprfmo_query` | `SprfmoQueryTool` | 查询 SPRFMO 南太平洋数据 | `data_type` |
-
-**注意：**
-- `logbook_query` 支持可选参数：`region`（海区）、`year_start`（起始年份）、`year_end`（结束年份）、`species`（物种）、`data_type`（数据类型）
-- `gfw_query` 仅支持查询 **2012-2024 年**的数据，超出范围会返回错误
-- `gfw_query` 支持可选参数：`flag`（船旗国）、`geartype`（渔具类型）、`min_fishing_hours`（最小捕捞小时数）
-- `literature_cpue_query` 支持可选参数：`region`（海区）、`year_start`、`year_end`、`species`、`response_variable`（响应变量）、`paper_type`（论文类型）
-- `sprfmo_query` 必须指定 `data_type`（'catch' 或 'effort'），支持可选参数：`country`（国家）、`year_start`、`year_end`、`species`（仅捕捞量）、`gear_type`（仅努力量）、`group_by`（聚合维度）
+- 设置中新增“用户问题快捷操作”，可选择左键单击或右键单击打开复制、重试、编辑文本。
+- 默认保持左键单击，升级后不改变原有操作习惯。
+- 右键模式只拦截用户消息气泡上的浏览器右键菜单，页面其他区域右键行为不变。

VERSION

@@ -0,0 +1 @@
+3.3.0

app.py

@@ -1,966 +0,0 @@
-"""
-基于 smolagents 框架的 Hugging Face 数据集自然语言查询智能代理
-
-功能：
-1. 启动时自动获取数据集文件列表，作为系统提示词告知用户可用数据
-2. 接收用户自然语言输入，从中提取数据集查询所需的参数信息
-3. 使用提取的参数从 Hugging Face 数据集获取数据（支持 ZIP/CSV/Excel 等格式）
-4. 返回结构化的查询结果
-
-依赖安装：
-    pip install 'smolagents[gradio]' requests pandas huggingface_hub openpyxl
-
-使用前：
-    1. 将文件顶部 HF_TOKEN 常量的值替换为个人 Hugging Face Settings 下申请的 Read Token（用于数据集访问）
-    2. 将文件顶部 OPENAI_API_KEY 常量的值替换为你的 OpenAI API Key（用于 LLM 接入）
-    3. 如使用第三方兼容服务，修改 OPENAI_API_BASE 常量的地址
-"""
-
-import os
-import json
-import logging
-import re
-from typing import Optional, List
-
-from huggingface_hub import HfApi
-from smolagents import Tool, ToolCallingAgent, OpenAIServerModel, GradioUI
-
-# 导入专用查询函数（从 query_tools 子模块导入）
-from query_tools.logbook_availability_query import query_logbook_availability
-from query_tools.query_gfw import query_gfw
-
-# ---------------------------------------------------------------------------
-# 日志配置（提前配置，以便在后续代码中使用）
-# ---------------------------------------------------------------------------
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s [%(levelname)s] %(name)s - %(message)s",
-)
-logger = logging.getLogger("hf_data_agent")
-
-# ===========================================================================
-# Hugging Face 数据集访问 Token（从环境变量加载）
-# ===========================================================================
-HF_TOKEN = os.getenv('HF_TOKEN')  # 从环境变量 HF_TOKEN 读取
-
-# 启动时校验 HF_TOKEN 是否存在，并给出提示
-if not HF_TOKEN:
-    logger.warning(
-        "未找到环境变量 HF_TOKEN，将无法访问 Hugging Face 数据集。"
-        "请设置环境变量: export HF_TOKEN=hf_你的Token"
-    )
-
-# ===========================================================================
-# 数据集仓库 ID
-# ===========================================================================
-HF_DATASET_REPO = "squid-lab/squid_dataset"  # Hugging Face 数据集仓库 ID
-
-# ===========================================================================
-# OpenAI 模型配置常量（从环境变量加载）
-# ===========================================================================
-OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')  # 从环境变量 OPENAI_API_KEY 读取
-OPENAI_API_BASE = os.getenv('OPENAI_API_BASE', 'https://api.deepseek.com/v1')  # 默认 DeepSeek API 地址
-MODEL_ID = os.getenv('MODEL_ID', 'deepseek-chat')
-
-# 启动时校验 OPENAI_API_KEY 是否存在，并给出提示
-if not OPENAI_API_KEY:
-    logger.warning(
-        "未找到环境变量 OPENAI_API_KEY，Agent 将无法调用 LLM。"
-        "请设置环境变量: export OPENAI_API_KEY=sk_你的Key"
-    )
-
-# 注意：deepseek-chat 和 deepseek-reasoner 将于 2026/07/24 弃用
-# 推荐使用新模型：deepseek-v4-flash（快速）或 deepseek-v4-pro（专业）
-
-# ===========================================================================
-# DeepSeek 思考模式配置（已停用）
-# ===========================================================================
-# 注意：DeepSeek 思考模式已停用，原因如下：
-# 1. deepseek-chat 和 deepseek-reasoner 将于 2026/07/24 弃用
-# 2. 新模型 deepseek-v4-flash/v4-pro 不需要特殊的思考模式适配
-# 3. 思考模式不支持 tool_choice 参数，限制 Agent 工具调用能力
-# 4. 使用标准 OpenAIServerModel 更稳定，兼容性更好
-THINKING_MODE_ENABLED = False  # 已停用思考模式
-THINKING_EFFORT = "high"  # 保留参数但不再使用
-
-
-# ===========================================================================
-# 数据集文件列表获取函数
-# ===========================================================================
-def get_dataset_file_list() -> List[str]:
-    """
-    从 Hugging Face 数据集仓库获取一级文件和文件夹名称列表。
-
-    使用 HfApi.dataset_info() 获取数据集元信息，提取 siblings 中的文件路径，
-    只保留一级目录/文件（不包含深层嵌套的文件）。
-
-    Returns:
-        一级文件和文件夹名称列表，如 ['中西太平洋WCPFC/', 'README.md', 'data.csv']
-    """
-    logger.info("正在获取数据集文件列表: %s", HF_DATASET_REPO)
-
-    try:
-        api = HfApi(token=HF_TOKEN)
-        dataset_info = api.dataset_info(repo_id=HF_DATASET_REPO)
-
-        # 提取所有文件路径
-        all_files = [sibling.rfilename for sibling in dataset_info.siblings]
-
-        # 只保留一级目录/文件（路径中不包含 '/' 的项，或者一级文件夹）
-        first_level_items = set()
-        for file_path in all_files:
-            parts = file_path.split("/")
-            # 一级文件（无子目录）
-            if len(parts) == 1:
-                first_level_items.add(parts[0])
-            # 一级文件夹（取第一部分，添加 '/' 后缀标识为文件夹）
-            else:
-                first_level_items.add(parts[0] + "/")
-
-        file_list = sorted(list(first_level_items))
-        logger.info("获取到 %d 个一级文件/文件夹: %s", len(file_list), file_list)
-        return file_list
-
-    except Exception as e:
-        logger.error("获取数据集文件列表失败: %s", e, exc_info=True)
-        return []
-
-
-def build_system_prompt_with_file_list() -> str:
-    """
-    构建包含数据集文件列表的系统提示词。
-
-    在对话启动时告知用户当前可用的数据集文件，帮助用户了解可查询的内容。
-
-    Returns:
-        格式化的系统提示词字符串
-    """
-    file_list = get_dataset_file_list()
-
-    if not file_list:
-        return (
-            "你是一个 Hugging Face 数据集查询助手。"
-            "用户可以询问数据集内容，你将帮助用户查询和获取数据。"
-            "当前无法获取数据集文件列表，请检查 HF_TOKEN 配置是否正确。"
-        )
-
-    # 格式化文件列表为提示词
-    files_str = "\n".join([f"  - {item}" for item in file_list])
-    system_prompt = (
-        "你是一个渔业数据查询助手，拥有以下工具：\n\n"
-        "1. **logbook_query** — 查询 logbook（捕捞日志）数据可用性，支持按海区、年份、物种、数据类型筛选\n"
-        "2. **gfw_query** — 查询 GFW（Global Fishing Watch）渔船作业努力量，需要指定年份（2012-2024）、月份和空间范围\n"
-        "3. **literature_cpue_query** — 查询 CPUE（单位捕捞努力量渔获量）相关文献数据，支持按海区、年份、物种、响应变量筛选\n"
-        "4. **sprfmo_query** — 查询 SPRFMO（南太平洋区域渔业管理组织）数据，支持捕捞量或努力量查询，可按国家、年份、物种等筛选\n\n"
-        "当前可查询的 Hugging Face 数据集仓库: " + HF_DATASET_REPO + "\n\n"
-        "数据集一级文件和文件夹列表:\n" + files_str + "\n\n"
-        "用户查询示例:\n"
-        "  - '2010-2020年东南太平洋有哪些鱿鱼捕捞日志数据？' → 使用 logbook_query\n"
-        "  - '查询2012年1月太平洋区域的渔船作业努力量' → 使用 gfw_query\n"
-        "  - '有哪些关于鱿鱼CPUE的研究文献？' → 使用 literature_cpue_query\n"
-        "  - '查询中国2015-2020年在南太平洋的渔获量' → 使用 sprfmo_query\n\n"
-        "请根据用户需求选择合适的工具，不要混用。\n\n"
-        "【重要】最终回答格式要求：\n"
-        "在展示查询数据后，必须附加以下信息：\n"
-        "---\n"
-        "**查询执行详情：**\n"
-        "- 使用工具：[本次调用的Tool名称]\n"
-        "- 查询参数：\n"
-        "  - 参数1名称: 参数1值\n"
-        "  - 参数2名称: 参数2值\n"
-        "  - ...（列出所有实际传入的参数）\n"
-        "---\n"
-        "请严格遵守此格式，确保用户清楚了解每次查询的具体执行过程。"
-    )
-
-    logger.info("系统提示词已构建，包含 %d 个文件/文件夹", len(file_list))
-    return system_prompt
-
-
-# ===========================================================================
-# DeepSeek 思考模式自定义模型类（已移除）
-# ===========================================================================
-# DeepSeekThinkingModel 类已被移除，原因如下：
-# 1. deepseek-chat 和 deepseek-reasoner 将于 2026/07/24 弃用
-# 2. 新模型 deepseek-v4-flash/v4-pro 使用标准 OpenAI API，无需特殊适配
-# 3. 思考模式不支持 tool_choice，限制了 Agent 的工具调用能力
-# 4. 使用标准 OpenAIServerModel 更稳定，兼容性更好
-# 现在使用标准 OpenAIServerModel，参见 create_hf_data_agent 函数
-
-
-# ===========================================================================
-# Tool 1: 参数提取 —— 从自然语言中解析出数据集查询参数
-# ===========================================================================
-class ParameterExtractionTool(Tool):
-    """从用户的自然语言描述中提取 Hugging Face 数据集查询所需的结构化参数。"""
-
-    name = "parameter_extractor"
-    description = (
-        "从用户的自然语言查询请求中提取数据集查询参数，包括："
-        "region（区域，如中西太平洋）、time_range（时间范围，如1967-2024）、"
-        "time_scale（时间尺度，如月尺度）、spatial_resolution（空间分辨率，如1x1）、"
-        "file_name（文件名）。返回 JSON 格式的参数字典。"
-    )
-    inputs = {
-        "user_query": {
-            "type": "string",
-            "description": (
-                "用户的自然语言查询请求，例如'查询中西太平洋1967-2024年月尺度1x1分辨率的渔获数据'"
-            ),
-        }
-    }
-    output_type = "string"
-
-    # --- 区域关键字映射表 ---
-    REGION_KEYWORDS = {
-        "中西太平洋": "中西太平洋WCPFC",
-        "wcpfc": "中西太平洋WCPFC",
-        "东太平洋": "东太平洋",
-        "太平洋": "中西太平洋WCPFC",
-        "印度洋": "印度洋",
-        "大西洋": "大西洋",
-        "南海": "南海",
-    }
-
-    # --- 时间尺度映射表 ---
-    TIME_SCALE_KEYWORDS = {
-        "月尺度": "月尺度",
-        "月度": "月尺度",
-        "月": "月尺度",
-        "年尺度": "年尺度",
-        "年度": "年尺度",
-        "年": "年尺度",
-        "日尺度": "日尺度",
-        "日度": "日尺度",
-        "日": "日尺度",
-    }
-
-    # --- 空间分辨率映射表 ---
-    SPATIAL_RESOLUTION_KEYWORDS = {
-        "1x1": "1x1",
-        "1度": "1x1",
-        "0.5x0.5": "0.5x0.5",
-        "0.5度": "0.5x0.5",
-        "0.1x0.1": "0.1x0.1",
-        "0.1度": "0.1x0.1",
-    }
-
-    def forward(self, user_query: str) -> str:
-        """
-        解析自然语言，提取数据集查询参数。
-
-        参数提取流程：
-        1. 识别目标区域（优先匹配关键字映射表）
-        2. 识别时间范围（起始年份-结束年份）
-        3. 识别时间尺度（月尺度/年尺度/日尺度）
-        4. 识别空间分辨率（1x1/0.5x0.5等）
-        5. 识别文件名（用户指定的具体文件名）
-        """
-        logger.info("开始提取参数，输入: %s", user_query)
-
-        try:
-            params = {
-                "region": self._extract_region(user_query),
-                "time_range": self._extract_time_range(user_query),
-                "time_scale": self._extract_time_scale(user_query),
-                "spatial_resolution": self._extract_spatial_resolution(user_query),
-                "file_name": self._extract_file_name(user_query),
-            }
-
-            # 校验必要参数：区域不能为空
-            if not params["region"]:
-                error_msg = (
-                    "无法从输入中识别目标区域，请在查询中明确指定区域。"
-                    f"支持的区域关键字: {list(self.REGION_KEYWORDS.keys())}"
-                )
-                logger.warning(error_msg)
-                return json.dumps({"error": error_msg}, ensure_ascii=False)
-
-            logger.info("参数提取成功: %s", params)
-            return json.dumps(params, ensure_ascii=False)
-
-        except Exception as e:
-            logger.error("参数提取失败: %s", e, exc_info=True)
-            return json.dumps(
-                {"error": f"参数提取过程发生错误: {str(e)}"},
-                ensure_ascii=False,
-            )
-
-    # ----- 以下为私有辅助方法，按提取维度拆分 -----
-
-    def _extract_region(self, query: str) -> Optional[str]:
-        """
-        从自然语言中识别目标区域。
-        优先级：关键字映射 → 直接匹配区域名称
-        """
-        # 优先通过关键字映射识别
-        for cn_keyword, region_name in self.REGION_KEYWORDS.items():
-            if cn_keyword.lower() in query.lower():
-                return region_name
-
-        return None
-
-    def _extract_time_range(self, query: str) -> Optional[str]:
-        """
-        从自然语言中识别时间范围。
-        匹配"XXXX-XXXX"格式或"XXXX年到XXXX年"格式。
-        """
-        # 匹配"1967-2024"格式
-        match = re.search(r"(\d{4})-(\d{4})", query)
-        if match:
-            return f"{match.group(1)}-{match.group(2)}"
-
-        # 匹配"1967年到2024年"或"1967至2024"格式
-        match = re.search(r"(\d{4})\s*(?:年到|至|-)\s*(\d{4})", query)
-        if match:
-            return f"{match.group(1)}-{match.group(2)}"
-
-        # 匹配单一年份"2024年"
-        match = re.search(r"(\d{4})\s*年", query)
-        if match:
-            year = match.group(1)
-            return f"{year}-{year}"
-
-        return None
-
-    def _extract_time_scale(self, query: str) -> Optional[str]:
-        """
-        从自然语言中识别时间尺度。
-        优先级：关键字映射 → 默认月尺度
-        """
-        for cn_keyword, scale_name in self.TIME_SCALE_KEYWORDS.items():
-            if cn_keyword in query:
-                return scale_name
-
-        return "月尺度"  # 默认月尺度
-
-    def _extract_spatial_resolution(self, query: str) -> Optional[str]:
-        """
-        从自然语言中识别空间分辨率。
-        匹配"XxX"格式或"X度"格式。
-        """
-        # 优先通过关键字映射识别
-        for cn_keyword, resolution in self.SPATIAL_RESOLUTION_KEYWORDS.items():
-            if cn_keyword in query:
-                return resolution
-
-        # 匹配"1x1"格式
-        match = re.search(r"(\d+(?:\.\d+)?)x(\d+(?:\.\d+)?)", query)
-        if match:
-            return f"{match.group(1)}x{match.group(2)}"
-
-        return "1x1"  # 默认1x1分辨率
-
-    def _extract_file_name(self, query: str) -> Optional[str]:
-        """
-        从自然语言中识别具体文件名。
-        匹配"xxx.zip"或"xxx数据"模式。
-        """
-        # 匹配".zip"结尾的文件名
-        match = re.search(r"(\S+)\.zip", query)
-        if match:
-            return f"{match.group(1)}.zip"
-
-        # 匹配"xxx文件"或"xxx数据"模式
-        match = re.search(r"(\w+)\s*(?:文件|数据)", query)
-        if match:
-            return f"{match.group(1)}.zip"
-
-        return None
-
-
-# ===========================================================================
-# Tool 2: Hugging Face 数据集获取 —— 从云端获取并解析数据
-# ===========================================================================
-# ===========================================================================
-# HFDataQueryTool 工具类（已移除）
-# ===========================================================================
-# HFDataQueryTool 已被移除，原因：
-# - 该工具的功能已整合到其他工具中，不再需要单独的数据获取工具
-# - 移除了约 350 行代码，包括文件解析、ZIP 处理、多种格式支持等
-# - Agent 现在主要使用 logbook_query 和 gfw_query 两个专用查询工具
-
-
-# ===========================================================================
-# Tool 3: Logbook 数据可用性查询
-# ===========================================================================
-class LogbookQueryTool(Tool):
-    """查询 logbook 数据可用性，支持按海区、年份、物种、数据类型筛选。"""
-
-    name = "logbook_query"
-    description = (
-        "查询 logbook（捕捞日志）数据的可用性。"
-        "支持按海区（region）、年份范围（year_start/year_end）、"
-        "物种（species）、数据类型（data_type）筛选。"
-        "返回统计摘要和预览数据。"
-    )
-    inputs = {
-        "region": {
-            "type": "string",
-            "description": "海区名称（模糊匹配），如 '东南太平洋'、'中西太平洋'。不指定则不筛选。",
-            "nullable": True,
-        },
-        "year_start": {
-            "type": "integer",
-            "description": "起始年份（包含），如 2010。不指定则不筛选。",
-            "nullable": True,
-        },
-        "year_end": {
-            "type": "integer",
-            "description": "结束年份（包含），如 2020。不指定则不筛选。",
-            "nullable": True,
-        },
-        "species": {
-            "type": "string",
-            "description": "物种名称（模糊匹配），如 '鱿鱼'。不指定则不筛选。",
-            "nullable": True,
-        },
-        "data_type": {
-            "type": "string",
-            "description": "数据类型（模糊匹配），如 '捕捞日志'。不指定则不筛选。",
-            "nullable": True,
-        },
-    }
-    output_type = "string"
-
-    def forward(
-        self,
-        region: Optional[str] = None,
-        year_start: Optional[int] = None,
-        year_end: Optional[int] = None,
-        species: Optional[str] = None,
-        data_type: Optional[str] = None,
-    ) -> str:
-        """
-        调用 query_logbook_availability 查询 logbook 数据可用性。
-
-        处理流程：
-        1. 将参数传递给 query_logbook_availability 函数
-        2. 捕获异常并返回错误信息
-        3. 将结果转为 JSON 字符串返回
-        """
-        logger.info(
-            "Logbook 查询: region=%s, year_start=%s, year_end=%s, species=%s, data_type=%s",
-            region, year_start, year_end, species, data_type,
-        )
-
-        try:
-            result = query_logbook_availability(
-                region=region if region else None,
-                year_start=year_start,
-                year_end=year_end,
-                species=species if species else None,
-                data_type=data_type if data_type else None,
-                output_format="markdown",  # 默认使用 markdown 输出，不写文件
-            )
-
-            # 格式化 summary 为可读字符串（兼容新旧版本）
-            summary_data = result.get("summary", {})
-            if isinstance(summary_data, dict):
-                # 新版本：summary 是字典，格式化为友好字符串
-                summary_str = (
-                    f"找到 {summary_data.get('records_count', 0)} 条 logbook 数据记录\n"
-                    f"覆盖年份: {summary_data.get('year_range', ['未知', '未知'])[0]}-{summary_data.get('year_range', ['未知', '未知'])[1]}\n"
-                    f"海区: {', '.join(summary_data.get('regions', ['未知']))}\n"
-                    f"物种: {', '.join(summary_data.get('species', ['未知']))}"
-                )
-            else:
-                # 旧版本：summary 已经是字符串
-                summary_str = summary_data
-
-            # 确保返回结构完整
-            complete_result = {
-                "summary": summary_str,
-                "records": result.get("records", []),
-                "preview_markdown": result.get("preview_markdown", ""),
-                "source_files": result.get("source_files", []),
-            }
-
-            return json.dumps(complete_result, ensure_ascii=False, default=str)
-
-        except Exception as e:
-            logger.error("Logbook 查询失败: %s", e, exc_info=True)
-            return json.dumps(
-                {"error": f"Logbook 查询失败: {str(e)}"},
-                ensure_ascii=False,
-            )
-
-
-# ===========================================================================
-# Tool 4: GFW 渔船作业努力量查询
-# ===========================================================================
-class GfwQueryTool(Tool):
-    """查询 GFW（Global Fishing Watch）渔船作业努力量数据。"""
-
-    name = "gfw_query"
-    description = (
-        "查询 GFW 渔船作业努力量数据。"
-        "需要指定年份（仅支持 2012-2024）、月份和空间范围（经纬度）。"
-        "可选按船旗国（flag）和渔具类型（geartype）筛选。"
-        "注意：lon_min > lon_max 表示查询范围跨越 180° 经线。"
-    )
-    inputs = {
-        "year": {
-            "type": "integer",
-            "description": "查询年份（仅支持 2012-2024），如 2012。",
-        },
-        "month": {
-            "type": "integer",
-            "description": "查询月份（1-12）。",
-        },
-        "lat_min": {
-            "type": "number",
-            "description": "最小纬度，如 -10。",
-        },
-        "lat_max": {
-            "type": "number",
-            "description": "最大纬度，如 10。",
-        },
-        "lon_min": {
-            "type": "number",
-            "description": "最小经度，如 145。大于 lon_max 时表示跨越 180° 经线。",
-        },
-        "lon_max": {
-            "type": "number",
-            "description": "最大经度，如 -175。",
-        },
-        "flag": {
-            "type": "string",
-            "description": "船旗国代码（精确匹配，不区分大小写），如 'CN'。不指定则不筛选。",
-            "nullable": True,
-        },
-        "geartype": {
-            "type": "string",
-            "description": "渔具类型（精确匹配，不区分大小写），如 'drifting_longlines'。不指定则不筛选。",
-            "nullable": True,
-        },
-        "min_fishing_hours": {
-            "type": "number",
-            "description": "最小捕捞小时数阈值，如 10。不指定则不筛选。",
-            "nullable": True,
-        },
-    }
-    output_type = "string"
-
-    def forward(
-        self,
-        year: int,
-        month: int,
-        lat_min: float,
-        lat_max: float,
-        lon_min: float,
-        lon_max: float,
-        flag: Optional[str] = None,
-        geartype: Optional[str] = None,
-        min_fishing_hours: Optional[float] = None,
-    ) -> str:
-        """
-        调用 query_gfw 查询 GFW 渔船作业努力量数据。
-
-        处理流程：
-        1. 将参数传递给 query_gfw 函数
-        2. 捕获异常并返回错误信息
-        3. 将 DataFrame 结果和 summary 转为 JSON 字符串返回
-        """
-        logger.info(
-            "GFW 查询: year=%s, month=%s, lat=[%s,%s], lon=[%s,%s], flag=%s, geartype=%s, min_fishing_hours=%s",
-            year, month, lat_min, lat_max, lon_min, lon_max, flag, geartype, min_fishing_hours,
-        )
-
-        try:
-            result_df, summary = query_gfw(
-                year=year,
-                month=month,
-                lat_min=lat_min,
-                lat_max=lat_max,
-                lon_min=lon_min,
-                lon_max=lon_max,
-                flag=flag if flag else None,
-                geartype=geartype if geartype else None,
-                min_fishing_hours=min_fishing_hours,
-            )
-
-            # 将 DataFrame 转为记录列表（限制预览条数）
-            display_limit = 100
-            records = result_df.head(display_limit).to_dict(orient="records")
-
-            output = {
-                "summary": summary,
-                "record_count": len(result_df),
-                "display_records": min(len(result_df), display_limit),
-                "data_preview": records,
-                "columns": list(result_df.columns) if not result_df.empty else [],
-            }
-
-            return json.dumps(output, ensure_ascii=False, default=str)
-
-        except FileNotFoundError as e:
-            # GFW 数据文件未找到
-            logger.error("GFW 数据文件未找到: %s", e)
-            return json.dumps(
-                {"error": f"GFW 数据文件未找到: {str(e)}"},
-                ensure_ascii=False,
-            )
-        except ValueError as e:
-            # 参数校验失败（如月份越界、纬度范围错误）
-            logger.error("GFW 查询参数错误: %s", e)
-            return json.dumps(
-                {"error": f"查询参数错误: {str(e)}"},
-                ensure_ascii=False,
-            )
-        except Exception as e:
-            logger.error("GFW 查询失败: %s", e, exc_info=True)
-            return json.dumps(
-                {"error": f"GFW 查询失败: {str(e)}"},
-                ensure_ascii=False,
-            )
-
-
-# ===========================================================================
-# Tool 5: 文献 CPUE 查询
-# ===========================================================================
-class LiteratureCpueQueryTool(Tool):
-    """查询 CPUE（单位捕捞努力量渔获量）相关文献数据。"""
-
-    name = "literature_cpue_query"
-    description = (
-        "查询 CPUE（单位捕捞努力量渔获量）相关文献数据。"
-        "支持按海区、年份范围、物种、响应变量、论文类型筛选。"
-        "返回文献统计摘要和预览数据。"
-    )
-    inputs = {
-        "region": {
-            "type": "string",
-            "description": "海区名称（模糊匹配），如 '东南太平洋'、'中西太平洋'。不指定则不筛选。",
-            "nullable": True,
-        },
-        "year_start": {
-            "type": "integer",
-            "description": "起始年份（包含），如 2010。不指定则不筛选。",
-            "nullable": True,
-        },
-        "year_end": {
-            "type": "integer",
-            "description": "结束年份（包含），如 2020。不指定则不筛选。",
-            "nullable": True,
-        },
-        "species": {
-            "type": "string",
-            "description": "物种名称（模糊匹配），如 '鱿鱼'。不指定则不筛选。",
-            "nullable": True,
-        },
-        "response_variable": {
-            "type": "string",
-            "description": "响应变量（模糊匹配），如 'CPUE'、'biomass'。不指定则不筛选。",
-            "nullable": True,
-        },
-        "paper_type": {
-            "type": "string",
-            "description": "论文类型（模糊匹配）。不指定则不筛选。",
-            "nullable": True,
-        },
-    }
-    output_type = "string"
-
-    def forward(
-        self,
-        region: Optional[str] = None,
-        year_start: Optional[int] = None,
-        year_end: Optional[int] = None,
-        species: Optional[str] = None,
-        response_variable: Optional[str] = None,
-        paper_type: Optional[str] = None,
-    ) -> str:
-        """
-        调用 query_literature_cpue 查询 CPUE 文献数据。
-
-        处理流程：
-        1. 将参数传递给 query_literature_cpue 函数
-        2. 捕获异常并返回错误信息
-        3. 将结果转为 JSON 字符串返回
-        """
-        logger.info(
-            "CPUE 文献查询: region=%s, year_start=%s, year_end=%s, species=%s, response_variable=%s, paper_type=%s",
-            region, year_start, year_end, species, response_variable, paper_type,
-        )
-
-        try:
-            # 动态导入以避免循环依赖
-            from query_tools.literature_cpue_query import query_literature_cpue
-
-            result = query_literature_cpue(
-                region=region if region else None,
-                year_start=year_start,
-                year_end=year_end,
-                species=species if species else None,
-                response_variable=response_variable if response_variable else None,
-                paper_type=paper_type if paper_type else None,
-                output_format="markdown",  # 默认使用 markdown 输出，不写文件
-            )
-
-            # 格式化 summary 为可读字符串
-            summary_data = result.get("summary", {})
-            if isinstance(summary_data, dict):
-                summary_str = (
-                    f"找到 {summary_data.get('paper_count', 0)} 篇 CPUE 相关文献\n"
-                    f"覆盖年份: {summary_data.get('year_range', ['未知', '未知'])[0]}-{summary_data.get('year_range', ['未知', '未知'])[1]}\n"
-                    f"涉及海区: {', '.join(summary_data.get('regions', ['未知']))}\n"
-                    f"涉及物种: {', '.join(summary_data.get('species', ['未知']))}\n"
-                    f"使用模型: {', '.join(summary_data.get('models', ['未知']))}"
-                )
-            else:
-                summary_str = summary_data
-
-            # 确保返回结构完整
-            complete_result = {
-                "summary": summary_str,
-                "records": result.get("records", []),
-                "preview_markdown": result.get("preview_markdown", ""),
-                "source_files": result.get("source_files", []),
-            }
-
-            return json.dumps(complete_result, ensure_ascii=False, default=str)
-
-        except Exception as e:
-            logger.error("CPUE 文献查询失败: %s", e, exc_info=True)
-            return json.dumps(
-                {"error": f"CPUE 文献查询失败: {str(e)}"},
-                ensure_ascii=False,
-            )
-
-
-# ===========================================================================
-# Tool 6: SPRFMO 南太平洋数据查询
-# ===========================================================================
-class SprfmoQueryTool(Tool):
-    """查询 SPRFMO（南太平洋区域渔业管理组织）数据。"""
-
-    name = "sprfmo_query"
-    description = (
-        "查询 SPRFMO（南太平洋区域渔业管理组织）数据。"
-        "支持查询捕捞量（catch）或努力量（effort）数据。"
-        "可按国家、年份范围、物种等筛选，支持按维度聚合统计。"
-        "空间分辨率：5x5 度；时间分辨率：年度。"
-    )
-    inputs = {
-        "data_type": {
-            "type": "string",
-            "description": "数据类型，'catch'（捕捞量）或 'effort'（努力量）。必填。",
-        },
-        "country": {
-            "type": "string",
-            "description": "国家代码或名称（如 'CHN'、'中国'、'JPN'）。不指定则不筛选。",
-            "nullable": True,
-        },
-        "year_start": {
-            "type": "integer",
-            "description": "起始年份（包含）。不指定则不筛选。",
-            "nullable": True,
-        },
-        "year_end": {
-            "type": "integer",
-            "description": "结束年份（包含）。不指定则不筛选。",
-            "nullable": True,
-        },
-        "species": {
-            "type": "string",
-            "description": "物种名称（仅捕捞量数据）。不指定则不筛选。",
-            "nullable": True,
-        },
-        "gear_type": {
-            "type": "string",
-            "description": "渔具类型（仅努力量数据）。不指定则不筛选。",
-            "nullable": True,
-        },
-        "group_by": {
-            "type": "string",
-            "description": "聚合维度，如 'year'、'country'、'species'。多个维度用逗号分隔。不指定则不聚合。",
-            "nullable": True,
-        },
-    }
-    output_type = "string"
-
-    def forward(
-        self,
-        data_type: str,
-        country: Optional[str] = None,
-        year_start: Optional[int] = None,
-        year_end: Optional[int] = None,
-        species: Optional[str] = None,
-        gear_type: Optional[str] = None,
-        group_by: Optional[str] = None,
-    ) -> str:
-        """
-        调用 query_sprfmo 查询 SPRFMO 数据。
-
-        处理流程：
-        1. 构建 filters 字典
-        2. 解析 group_by 参数
-        3. 调用 query_sprfmo 函数
-        4. 捕获异常并返回错误信息
-        5. 将结果转为 JSON 字符串返回
-        """
-        logger.info(
-            "SPRFMO 查询: data_type=%s, country=%s, year=[%s,%s], species=%s, gear_type=%s, group_by=%s",
-            data_type, country, year_start, year_end, species, gear_type, group_by,
-        )
-
-        try:
-            # 动态导入以避免循环依赖
-            from query_tools.query_sprfmo import query_sprfmo
-
-            # 构建 filters 字典
-            filters = {}
-            if country:
-                filters["country"] = country
-            if year_start is not None:
-                filters["year_start"] = year_start
-            if year_end is not None:
-                filters["year_end"] = year_end
-            if species and data_type == "catch":
-                filters["species"] = species
-            if gear_type and data_type == "effort":
-                filters["gear_type"] = gear_type
-
-            # 解析 group_by 参数
-            group_by_list = None
-            if group_by:
-                group_by_list = [g.strip() for g in group_by.split(",")]
-
-            # 调用查询函数
-            result = query_sprfmo(
-                filters=filters,
-                group_by=group_by_list,
-                metrics=data_type,  # metrics 参数直接使用 data_type
-                data_type=data_type,
-                output_format="markdown",
-            )
-
-            # 格式化 summary
-            summary_data = result.get("summary", {})
-            summary_str = (
-                f"数据类型: {summary_data.get('data_type', '未知')}\n"
-                f"总记录数: {summary_data.get('total_records', 0)}\n"
-                f"数据来源: {summary_data.get('data_source', 'SPRFMO')}\n"
-            )
-            if "year_range" in summary_data:
-                summary_str += f"年份范围: {summary_data['year_range']}\n"
-            if "total_catch" in summary_data:
-                summary_str += f"总捕捞量: {summary_data['total_catch']:.2f} kg\n"
-            if "total_effort" in summary_data:
-                summary_str += f"总努力量: {summary_data['total_effort']:.2f} 天\n"
-
-            # 确保返回结构完整
-            complete_result = {
-                "summary": summary_str,
-                "records": result.get("records", []),
-                "preview_markdown": result.get("preview_markdown", ""),
-                "source_files": result.get("source_files", []),
-                "warnings": result.get("warnings", []),
-                "metadata": result.get("metadata", {}),
-            }
-
-            return json.dumps(complete_result, ensure_ascii=False, default=str)
-
-        except FileNotFoundError as e:
-            # SPRFMO 数据文件未找到
-            logger.error("SPRFMO 数据文件未找到: %s", e)
-            return json.dumps(
-                {"error": f"SPRFMO 数据文件未找到: {str(e)}"},
-                ensure_ascii=False,
-            )
-        except Exception as e:
-            logger.error("SPRFMO 查询失败: %s", e, exc_info=True)
-            return json.dumps(
-                {"error": f"SPRFMO 查询失败: {str(e)}"},
-                ensure_ascii=False,
-            )
-
-
-# ===========================================================================
-# Agent 工厂函数：创建配置好的 ToolCallingAgent
-# ===========================================================================
-def create_hf_data_agent(
-    model_id: str = MODEL_ID,
-    api_key: Optional[str] = None,
-    api_base: Optional[str] = None,
-    max_steps: int = 5,
-) -> ToolCallingAgent:
-    """
-    创建并返回一个配置好的 Hugging Face 数据集查询智能代理。
-
-    在 Agent 启动时会自动获取数据集文件列表并作为系统提示词告知用户。
-
-    注意：DeepSeek 思考模式已停用，现在使用标准 OpenAIServerModel。
-    原因：deepseek-chat/deepseek-reasoner 将于 2026/07/24 弃用，
-          新模型 deepseek-v4-flash/v4-pro 使用标准 OpenAI API。
-
-    Args:
-        model_id: 模型 ID，默认使用文件顶部 MODEL_ID 常量
-                  推荐: deepseek-v4-flash 或 deepseek-v4-pro
-        api_key: API Key，默认使用文件顶部 OPENAI_API_KEY 常量
-        api_base: API 地址，默认使用文件顶部 OPENAI_API_BASE 常量
-        max_steps: Agent 最大推理步骤数
-
-    Returns:
-        配置好的 ToolCallingAgent 实例
-    """
-    key = api_key or OPENAI_API_KEY
-    base = api_base or OPENAI_API_BASE
-
-    # 初始化 LLM 模型（使用标准 OpenAIServerModel，已停用思考模式）
-    model = OpenAIServerModel(
-        model_id=model_id,
-        api_key=key,
-        api_base=base,
-    )
-
-    # 实例化工具（包含新增的 CPUE 文献和 SPRFMO 查询工具）
-    param_tool = ParameterExtractionTool()
-    logbook_tool = LogbookQueryTool()
-    gfw_tool = GfwQueryTool()
-    literature_cpue_tool = LiteratureCpueQueryTool()
-    sprfmo_tool = SprfmoQueryTool()
-
-    # 构建包含数据集文件列表的指令（会被插入到系统提示词中）
-    instructions = build_system_prompt_with_file_list()
-    logger.info("Agent 自定义指令: %s", instructions[:200] + "...")  # 只打印前200字符
-
-    # 创建 ToolCallingAgent，使用 instructions 参数设置自定义指令
-    # 工具列表包含5个查询工具（已移除 hf_data_tool）
-    agent = ToolCallingAgent(
-        tools=[param_tool, logbook_tool, gfw_tool, literature_cpue_tool, sprfmo_tool],
-        model=model,
-        max_steps=max_steps,
-        instructions=instructions,
-    )
-
-    logger.info("Hugging Face 数据集查询代理创建成功，模型: %s", model_id)
-    return agent
-
-
-# ===========================================================================
-# 主入口：GradioUI 交互式 Web 界面
-# ===========================================================================
-def main():
-    """
-    使用 GradioUI 启动交互式 Web 界面。
-    用户在浏览器中输入自然语言查询，代理实时展示思考过程和数据获取结果。
-    界面基于 gr.ChatInterface，支持流式输出和步骤可视化。
-    """
-    agent = create_hf_data_agent()
-
-    # GradioUI 将 agent 包装为 gr.ChatInterface Web 应用
-    # - share=True: 生成公网可访问的临时链接（72小时有效）
-    # - reset_agent_memory=False: 保留对话上下文，允许多轮交互
-    demo = GradioUI(
-        agent,
-        reset_agent_memory=False,
-    )
-
-    logger.info("正在启动 GradioUI Web 界面...")
-    demo.launch(share=True)
-
-
-if __name__ == "__main__":
-    main()

data/.gitkeep

@@ -1 +0,0 @@
-placeholder

data/logbook_availability.csv

@@ -1,246 +0,0 @@
-region,year,species,data_type,resolution,source_file,notes
-中西太平洋 WCPFC,1967,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1968,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1969,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1970,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1971,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1972,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1973,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1974,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1975,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1976,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1977,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1978,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1979,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1980,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1981,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1982,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1983,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1984,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1985,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1986,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1987,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1988,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1989,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1990,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1991,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1992,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1993,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1994,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1995,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1996,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1997,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1998,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,1999,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2000,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2001,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2002,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2003,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2004,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2005,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2006,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2007,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2008,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2009,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2010,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2011,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2012,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2013,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2014,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2015,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2016,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2017,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2018,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2019,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2020,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2021,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2022,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2023,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-中西太平洋 WCPFC,2024,柔鱼类,捕捞量（月尺度）,1°×1°,中西太平洋WCPFC 1967-2024月尺1x1/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2007,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2008,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2009,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2010,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2011,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2012,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2013,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2014,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2015,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2016,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2017,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2018,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2019,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2020,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-东南太平洋（南太平洋 SPRFMO）,2021,柔鱼类,捕捞量+捕捞努力度（年尺度）,5°×5°,SPRFMO 南太平洋 2007-2021 捕捞量+努力度 5x5 年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1998,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,1999,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2000,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2001,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2002,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2003,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2004,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2005,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2006,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2007,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2008,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2009,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2010,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2011,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2012,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2013,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2014,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2015,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2016,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2017,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2018,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2019,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2020,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2021,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2022,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2023,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,2024,柔鱼科,捕捞量（年尺度）,无空间分辨率,FAO全球柔鱼科捕捞量1998-2024年无测量分辨率.xlsx,根据 Hugging Face 数据集文件名称整理
-全球（太平洋、印度洋、大西洋、南海）,1950,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1951,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1952,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1953,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1954,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1955,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1956,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1957,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 ��球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1958,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1959,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1960,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1961,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1962,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1963,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1964,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1965,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1966,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1967,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1968,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1969,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1970,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1971,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1972,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1973,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1974,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1975,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1976,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1977,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1978,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1979,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1980,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1981,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1982,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1983,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1984,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1985,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1986,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1987,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1988,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1989,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1990,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1991,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1992,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1993,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1994,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1995,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1996,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1997,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1998,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1999,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2000,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2001,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2002,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2003,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2004,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2005,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2006,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录���称整理
-全球（太平洋、印度洋、大西洋、南海）,2007,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2008,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2009,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2010,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2011,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2012,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2013,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2014,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2015,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2016,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2017,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2018,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2019,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2020,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2021,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2022,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2023,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2024,茎柔鱼,捕捞量（年尺度）,全球年尺度,RAM Legacy 茎柔鱼 1950 - 2024 全球年尺/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1950,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1951,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1952,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1953,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1954,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1955,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1956,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1957,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1958,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1959,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1960,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1961,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1962,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1963,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1964,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1965,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1966,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1967,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1968,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1969,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1970,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1971,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1972,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1973,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1974,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1975,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1976,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1977,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1978,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1979,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1980,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1981,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1982,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1983,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1984,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1985,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1986,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1987,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1988,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1989,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1990,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1991,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1992,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1993,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1994,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1995,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1996,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1997,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1998,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,1999,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2000,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印���洋、大西洋、南海）,2001,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2002,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2003,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2004,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2005,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2006,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2007,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2008,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2009,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2010,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2011,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2012,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2013,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2014,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2015,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2016,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2017,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2018,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理
-全球（太平洋、印度洋、大西洋、南海）,2019,柔鱼科,捕捞量（年尺度）,0.5°×0.5°,我们周围的海域全球柔鱼科捕量年尺 1950-2019 0.5×0.5/,根据 Hugging Face 数据集目录名称整理

fisheries_hf.py

@@ -0,0 +1,575 @@
+"""Restricted Hugging Face fisheries file reader and CSV export helpers.
+
+The module deliberately exposes no arbitrary URL, shell, or filesystem access.
+Callers must first validate a path against the configured Dataset live tree and
+pass the expected file size to :func:`download_dataset_file`.
+"""
+from __future__ import annotations
+
+import csv
+import hashlib
+import io
+import itertools
+import json
+import os
+import re
+import secrets
+import shutil
+import time
+import zipfile
+from collections import defaultdict
+from pathlib import Path
+from typing import Any, Iterable
+from urllib.parse import quote
+
+import httpx
+
+
+HF_SQUID_DATASET_REPO = (
+    os.environ.get("HF_SQUID_DATASET_REPO")
+    or os.environ.get("HF_DATASET_REPO")
+    or "globalsquiddatabase/squid_dataset"
+).strip()
+HF_TUNA_DATASET_REPO = (
+    os.environ.get("HF_TUNA_DATASET_REPO")
+    or "globalsquiddatabase/Tuna-Fisheries-Dataset"
+).strip()
+HF_DATASET_REPOS = {
+    "squid": HF_SQUID_DATASET_REPO,
+    "tuna": HF_TUNA_DATASET_REPO,
+}
+# Backwards-compatible default used when old callers omit a repository.
+HF_DATASET_REPO = HF_SQUID_DATASET_REPO
+HF_SQUID_DATASET_REVISION = (
+    os.environ.get("HF_SQUID_DATASET_REVISION")
+    or os.environ.get("HF_DATASET_REVISION")
+    or ""
+).strip()
+HF_TUNA_DATASET_REVISION = os.environ.get("HF_TUNA_DATASET_REVISION", "").strip()
+HF_TOKEN = os.environ.get("HF_TOKEN", "").strip()
+PUBLIC_BASE_URL = os.environ.get("PUBLIC_BASE_URL", "").strip().rstrip("/")
+
+CACHE_ROOT = Path(
+    os.environ.get("HF_FISHERIES_CACHE_ROOT", "/tmp/squid_hf_fisheries_cache")
+)
+EXPORT_ROOT = Path(
+    os.environ.get("FISHERIES_EXPORT_ROOT", "/tmp/squid_fisheries_exports")
+)
+CACHE_ROOT.mkdir(parents=True, exist_ok=True)
+EXPORT_ROOT.mkdir(parents=True, exist_ok=True)
+
+MAX_CSV_BYTES = int(os.environ.get("HF_FISHERIES_MAX_CSV_BYTES", 100 * 1024 * 1024))
+MAX_ZIP_BYTES = int(os.environ.get("HF_FISHERIES_MAX_ZIP_BYTES", 1536 * 1024 * 1024))
+EXPORT_TTL_SECONDS = int(os.environ.get("FISHERIES_EXPORT_TTL_SECONDS", "86400"))
+
+_REVISION_CACHE: dict[str, dict[str, Any]] = {}
+
+YEAR_ALIASES = ("year", "yearc", "年份", "yr")
+MONTH_ALIASES = ("month", "月份", "mon")
+DATE_ALIASES = ("date", "time", "datetime", "日期", "时间", "year_month")
+LON_ALIASES = ("lon", "longitude", "decimal_longitude", "经度", "x")
+LAT_ALIASES = ("lat", "latitude", "decimal_latitude", "纬度", "y")
+
+
+def _headers() -> dict[str, str]:
+    return {"Authorization": f"Bearer {HF_TOKEN}"} if HF_TOKEN else {}
+
+
+def normalize_repository(repository: str | None = None) -> str:
+    """Resolve a safe repository selector to one of the two configured repos."""
+    value = str(repository or "squid").strip()
+    lowered = value.lower()
+    if lowered in HF_DATASET_REPOS:
+        return HF_DATASET_REPOS[lowered]
+    for repo in HF_DATASET_REPOS.values():
+        if value == repo:
+            return repo
+    raise ValueError("repository must be squid, tuna, or an exact configured repository id")
+
+
+def _revision(repository: str) -> str:
+    pinned = (
+        HF_TUNA_DATASET_REVISION
+        if repository == HF_TUNA_DATASET_REPO
+        else HF_SQUID_DATASET_REVISION
+    )
+    if pinned:
+        return pinned
+    now = time.time()
+    cache = _REVISION_CACHE.get(repository) or {}
+    cached = str(cache.get("sha") or "")
+    if cached and now - float(cache.get("ts") or 0) < 300:
+        return cached
+    url = f"https://huggingface.co/api/datasets/{repository}"
+    with httpx.Client(timeout=30.0, follow_redirects=True) as client:
+        response = client.get(url, headers=_headers())
+    if response.status_code in {401, 403}:
+        raise RuntimeError("Hugging Face Dataset 无读取权限，请检查 HF_TOKEN。")
+    response.raise_for_status()
+    body = response.json()
+    sha = str(body.get("sha") or "").strip()
+    if not re.fullmatch(r"[0-9a-fA-F]{40}", sha):
+        raise RuntimeError("无法获得 Hugging Face Dataset 的固定提交 SHA。")
+    _REVISION_CACHE[repository] = {"ts": now, "sha": sha}
+    return sha
+
+
+def _safe_cache_path(repository: str, path: str, revision: str) -> Path:
+    suffix = Path(path).suffix.lower()
+    digest = hashlib.sha256(f"{repository}:{revision}:{path}".encode()).hexdigest()
+    return CACHE_ROOT / f"{digest}{suffix}"
+
+
+def download_dataset_file(
+    path: str,
+    expected_size: int,
+    repository: str | None = None,
+) -> tuple[Path, str]:
+    """Download one validated Dataset file to a revision-keyed local cache."""
+    clean = str(path or "").strip().lstrip("/")
+    if not clean or "\x00" in clean or any(part in {"", ".", ".."} for part in clean.split("/")):
+        raise ValueError("invalid dataset path")
+    suffix = Path(clean).suffix.lower()
+    limit = MAX_ZIP_BYTES if suffix == ".zip" else MAX_CSV_BYTES
+    if suffix not in {".csv", ".tsv", ".zip"}:
+        raise ValueError("当前内容查询仅支持 CSV、TSV 和包含 CSV/TSV 的 ZIP。")
+    if expected_size <= 0:
+        raise ValueError("live tree did not provide a positive file size")
+    if expected_size > limit:
+        raise ValueError(
+            f"文件大小 {expected_size} bytes 超过在线处理上限 {limit} bytes；"
+            "请先在学校服务器生成查询就绪的分区文件。"
+        )
+
+    repository = normalize_repository(repository)
+    revision = _revision(repository)
+    target = _safe_cache_path(repository, clean, revision)
+    if target.exists() and target.stat().st_size == expected_size:
+        return target, revision
+
+    partial = target.with_suffix(target.suffix + ".part")
+    partial.unlink(missing_ok=True)
+    encoded_path = quote(clean, safe="/")
+    url = (
+        f"https://huggingface.co/datasets/{repository}/resolve/"
+        f"{revision}/{encoded_path}"
+    )
+    total = 0
+    try:
+        with httpx.stream(
+            "GET",
+            url,
+            headers=_headers(),
+            follow_redirects=True,
+            timeout=httpx.Timeout(connect=20, read=300, write=30, pool=30),
+        ) as response:
+            if response.status_code in {401, 403}:
+                raise RuntimeError("Hugging Face 文件无读取权限，请检查 HF_TOKEN。")
+            response.raise_for_status()
+            with partial.open("wb") as stream:
+                for chunk in response.iter_bytes(1024 * 1024):
+                    if not chunk:
+                        continue
+                    total += len(chunk)
+                    if total > limit:
+                        raise ValueError("download exceeded configured size limit")
+                    stream.write(chunk)
+        if total != expected_size:
+            raise RuntimeError(
+                f"文件下载不完整：expected={expected_size}, received={total}"
+            )
+        partial.replace(target)
+    except Exception:
+        partial.unlink(missing_ok=True)
+        raise
+    return target, revision
+
+
+def _decode_text(path: Path) -> tuple[str, str]:
+    raw = path.read_bytes()
+    for encoding in ("utf-8-sig", "utf-8", "gb18030"):
+        try:
+            return raw.decode(encoding), encoding
+        except UnicodeDecodeError:
+            pass
+    return raw.decode("utf-8", errors="replace"), "utf-8-replace"
+
+
+def _dialect(text: str, suffix: str = ".csv") -> str:
+    sample = text[:20000]
+    try:
+        return csv.Sniffer().sniff(sample, delimiters=",\t;|").delimiter
+    except Exception:
+        return "\t" if suffix == ".tsv" else ","
+
+
+def _column(columns: Iterable[str], aliases: Iterable[str]) -> str | None:
+    exact = {str(col).strip().lower(): str(col) for col in columns}
+    for alias in aliases:
+        if alias.lower() in exact:
+            return exact[alias.lower()]
+    return None
+
+
+def _number(value: Any) -> float | None:
+    text = str(value or "").strip().replace(",", "")
+    if not text:
+        return None
+    try:
+        return float(text)
+    except Exception:
+        return None
+
+
+def _year_month(row: dict[str, str], columns: list[str]) -> tuple[int | None, int | None]:
+    year_col = _column(columns, YEAR_ALIASES)
+    month_col = _column(columns, MONTH_ALIASES)
+    date_col = _column(columns, DATE_ALIASES)
+    year = None
+    month = None
+    if year_col:
+        value = _number(row.get(year_col))
+        if value is not None and 1800 <= int(value) <= 2200:
+            year = int(value)
+    if month_col:
+        value = _number(row.get(month_col))
+        if value is not None and 1 <= int(value) <= 12:
+            month = int(value)
+    if date_col and (year is None or month is None):
+        text = str(row.get(date_col) or "")
+        match = re.search(r"(19\d{2}|20\d{2}|21\d{2})[-/]?(0?[1-9]|1[0-2])?", text)
+        if match:
+            year = year or int(match.group(1))
+            month = month or (int(match.group(2)) if match.group(2) else None)
+    return year, month
+
+
+def _metric_columns(columns: list[str], requested: str | None = None) -> list[str]:
+    if requested:
+        wanted = [x.strip() for x in requested.split(",") if x.strip()]
+        missing = [x for x in wanted if x not in columns]
+        if missing:
+            raise ValueError(f"requested metric columns not found: {missing}")
+        return wanted
+    keys = (
+        "effort", "fishing_hour", "fishing hours", "apparent_fishing",
+        "catch", "harvest", "landing", "cpue", "value",
+    )
+    excluded = set(YEAR_ALIASES + MONTH_ALIASES + LON_ALIASES + LAT_ALIASES)
+    return [
+        col for col in columns
+        if str(col).strip().lower() not in excluded
+        and any(key in str(col).strip().lower() for key in keys)
+    ]
+
+
+def _matches_filters(
+    row: dict[str, str],
+    columns: list[str],
+    *,
+    year: int | None,
+    lon_min: float | None,
+    lon_max: float | None,
+    lat_min: float | None,
+    lat_max: float | None,
+) -> tuple[bool, int | None, int | None]:
+    row_year, row_month = _year_month(row, columns)
+    if year is not None and row_year != int(year):
+        return False, row_year, row_month
+    lon_col = _column(columns, LON_ALIASES)
+    lat_col = _column(columns, LAT_ALIASES)
+    if any(v is not None for v in (lon_min, lon_max)):
+        if not lon_col:
+            raise ValueError("经度筛选已请求，但文件中未识别到经度字段。")
+        lon = _number(row.get(lon_col))
+        if lon is None or (lon_min is not None and lon < lon_min) or (lon_max is not None and lon > lon_max):
+            return False, row_year, row_month
+    if any(v is not None for v in (lat_min, lat_max)):
+        if not lat_col:
+            raise ValueError("纬度筛选已请求，但文件中未识别到纬度字段。")
+        lat = _number(row.get(lat_col))
+        if lat is None or (lat_min is not None and lat < lat_min) or (lat_max is not None and lat > lat_max):
+            return False, row_year, row_month
+    return True, row_year, row_month
+
+
+def _create_export(filename: str, rows: Iterable[dict[str, Any]], columns: list[str]) -> dict[str, str]:
+    now = time.time()
+    for item in list(EXPORT_ROOT.iterdir())[:2000]:
+        if not item.is_dir():
+            continue
+        try:
+            meta = json.loads((item / "meta.json").read_text(encoding="utf-8"))
+            expired = float(meta.get("expires_ts") or 0) < now
+        except Exception:
+            expired = True
+        if expired:
+            shutil.rmtree(item, ignore_errors=True)
+
+    token = secrets.token_urlsafe(24)
+    safe_name = re.sub(r"[^A-Za-z0-9._-]+", "_", filename).strip("._") or "fisheries_export.csv"
+    folder = EXPORT_ROOT / token
+    folder.mkdir(parents=True, exist_ok=False)
+    target = folder / safe_name
+    with target.open("w", encoding="utf-8-sig", newline="") as stream:
+        writer = csv.DictWriter(stream, fieldnames=columns, extrasaction="ignore")
+        writer.writeheader()
+        writer.writerows(rows)
+    meta = {
+        "filename": safe_name,
+        "content_type": "text/csv; charset=utf-8",
+        "size_bytes": target.stat().st_size,
+        "created_ts": now,
+        "expires_ts": now + EXPORT_TTL_SECONDS,
+    }
+    (folder / "meta.json").write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")
+    path = f"/api/fisheries/download/{token}"
+    return {
+        "token": token,
+        "filename": safe_name,
+        "download_path": path,
+        "download_url": f"{PUBLIC_BASE_URL}{path}" if PUBLIC_BASE_URL else path,
+    }
+
+
+def _process_reader(
+    reader: csv.DictReader,
+    *,
+    source_label: str,
+    year: int | None,
+    lon_min: float | None,
+    lon_max: float | None,
+    lat_min: float | None,
+    lat_max: float | None,
+    metric_columns: str | None,
+    max_rows: int,
+    state: dict[str, Any],
+) -> None:
+    columns = [str(x or "").strip() for x in (reader.fieldnames or [])]
+    if not columns:
+        return
+    if not state["columns"]:
+        state["columns"] = columns
+        state["metrics"] = _metric_columns(columns, metric_columns)
+    elif columns != state["columns"]:
+        state["schema_variants"].append({"source": source_label, "columns": columns})
+
+    seen = state["seen"]
+    for raw in reader:
+        if state["scanned"] >= max_rows:
+            state["truncated"] = True
+            return
+        state["scanned"] += 1
+        row = {str(k or "").strip(): "" if v is None else str(v).strip() for k, v in raw.items()}
+        matched, row_year, row_month = _matches_filters(
+            row,
+            columns,
+            year=year,
+            lon_min=lon_min,
+            lon_max=lon_max,
+            lat_min=lat_min,
+            lat_max=lat_max,
+        )
+        if not matched:
+            continue
+        # Quality counts are reported for the requested result set.  This
+        # keeps large year/bbox ZIP queries bounded instead of retaining a
+        # duplicate key for every global row that was scanned and rejected.
+        key = tuple(row.get(col, "") for col in columns)
+        if key in seen:
+            state["duplicates"] += 1
+        else:
+            seen.add(key)
+        for col in columns:
+            if not row.get(col, "").strip():
+                state["missing"][col] += 1
+        state["matched"] += 1
+        state["rows"].append(row)
+        if row_year is not None:
+            state["years"].add(row_year)
+        if row_month is not None:
+            state["months"][row_month] += 1
+        if row_year is not None:
+            state["annual_counts"][row_year] += 1
+            for col in state["metrics"]:
+                value = _number(row.get(col))
+                if value is not None:
+                    state["annual_values"][(row_year, col)] += value
+
+
+def analyze_and_export(
+    local_path: Path,
+    *,
+    dataset_path: str,
+    revision: str,
+    repository: str | None = None,
+    year: int | None = None,
+    lon_min: float | None = None,
+    lon_max: float | None = None,
+    lat_min: float | None = None,
+    lat_max: float | None = None,
+    metric_columns: str | None = None,
+    max_rows: int = 2_000_000,
+) -> dict[str, Any]:
+    if lon_min is not None and not -180 <= float(lon_min) <= 180:
+        raise ValueError("lon_min 必须位于 -180 至 180。")
+    if lon_max is not None and not -180 <= float(lon_max) <= 180:
+        raise ValueError("lon_max 必须位于 -180 至 180。")
+    if lat_min is not None and not -90 <= float(lat_min) <= 90:
+        raise ValueError("lat_min 必须位于 -90 至 90。")
+    if lat_max is not None and not -90 <= float(lat_max) <= 90:
+        raise ValueError("lat_max 必须位于 -90 至 90。")
+    if lon_min is not None and lon_max is not None and float(lon_min) > float(lon_max):
+        raise ValueError("lon_min 不能大于 lon_max。")
+    if lat_min is not None and lat_max is not None and float(lat_min) > float(lat_max):
+        raise ValueError("lat_min 不能大于 lat_max。")
+
+    has_filter = year is not None or any(
+        value is not None for value in (lon_min, lon_max, lat_min, lat_max)
+    )
+    if (
+        local_path.suffix.lower() == ".zip"
+        and local_path.stat().st_size > 200 * 1024 * 1024
+        and not has_filter
+    ):
+        raise ValueError(
+            "大型 ZIP 查询必须提供 year 或经纬度范围，避免无边界解压扫描；"
+            "请补充筛选条件后重试。"
+        )
+
+    max_rows = max(1, min(int(max_rows or 2_000_000), 5_000_000))
+    state: dict[str, Any] = {
+        "columns": [], "metrics": [], "schema_variants": [], "scanned": 0,
+        "matched": 0, "duplicates": 0, "missing": defaultdict(int),
+        "years": set(), "months": defaultdict(int), "annual_counts": defaultdict(int),
+        "annual_values": defaultdict(float), "rows": [], "seen": set(), "truncated": False,
+    }
+
+    suffix = local_path.suffix.lower()
+    members: list[str] = []
+    if suffix in {".csv", ".tsv"}:
+        text, encoding = _decode_text(local_path)
+        delimiter = _dialect(text, suffix)
+        _process_reader(
+            csv.DictReader(io.StringIO(text), delimiter=delimiter),
+            source_label=dataset_path,
+            year=year, lon_min=lon_min, lon_max=lon_max,
+            lat_min=lat_min, lat_max=lat_max,
+            metric_columns=metric_columns, max_rows=max_rows, state=state,
+        )
+    else:
+        encoding = "utf-8-replace"
+        delimiter = "auto-by-member-extension"
+        with zipfile.ZipFile(local_path) as archive:
+            candidates = [
+                info for info in archive.infolist()
+                if not info.is_dir() and Path(info.filename).suffix.lower() in {".csv", ".tsv"}
+            ]
+            if year is not None:
+                preferred = [info for info in candidates if str(year) in info.filename]
+                if preferred:
+                    candidates = preferred
+            for info in candidates:
+                members.append(info.filename)
+                with archive.open(info) as binary:
+                    text_stream = io.TextIOWrapper(binary, encoding="utf-8-sig", errors="replace", newline="")
+                    sample_lines = list(itertools.islice(text_stream, 50))
+                    member_delimiter = _dialect(
+                        "".join(sample_lines),
+                        Path(info.filename).suffix.lower(),
+                    )
+                    _process_reader(
+                        csv.DictReader(
+                            itertools.chain(sample_lines, text_stream),
+                            delimiter=member_delimiter,
+                        ),
+                        source_label=info.filename,
+                        year=year, lon_min=lon_min, lon_max=lon_max,
+                        lat_min=lat_min, lat_max=lat_max,
+                        metric_columns=metric_columns, max_rows=max_rows, state=state,
+                    )
+                if state["truncated"]:
+                    break
+
+    if not state["columns"]:
+        raise ValueError("未在文件中发现可读取的 CSV/TSV 表格。")
+
+    annual_summary = []
+    for yr in sorted(state["annual_counts"]):
+        item: dict[str, Any] = {"year": yr, "record_count": state["annual_counts"][yr]}
+        for col in state["metrics"]:
+            item[f"sum_{col}"] = state["annual_values"].get((yr, col), 0.0)
+        annual_summary.append(item)
+
+    # Return three distinct, truthfully labelled artifacts when the source has
+    # a usable year field. Keep the raw-detail export as the backwards-
+    # compatible primary download_url/token/filename.
+    stamp = int(time.time())
+    source_stem = Path(dataset_path).stem or "fisheries_query"
+    raw_export = _create_export(
+        f"{source_stem}_{stamp}_filtered_raw.csv",
+        state["rows"],
+        state["columns"],
+    )
+    deduplicated_rows = []
+    exported_keys = set()
+    for row in state["rows"]:
+        key = tuple(row.get(col, "") for col in state["columns"])
+        if key in exported_keys:
+            continue
+        exported_keys.add(key)
+        deduplicated_rows.append(row)
+    deduplicated_export = _create_export(
+        f"{source_stem}_{stamp}_deduplicated.csv",
+        deduplicated_rows,
+        state["columns"],
+    )
+    exports = [
+        {"kind": "filtered_raw", **raw_export},
+        {
+            "kind": "deduplicated",
+            "record_count": len(deduplicated_rows),
+            **deduplicated_export,
+        },
+    ]
+    if annual_summary:
+        annual_columns = list(annual_summary[0])
+        annual_export = _create_export(
+            f"{source_stem}_{stamp}_annual_summary.csv",
+            annual_summary,
+            annual_columns,
+        )
+        exports.append({"kind": "annual_summary", **annual_export})
+
+    return {
+        "status": "ok",
+        "repository": normalize_repository(repository),
+        "revision": revision,
+        "dataset_path": dataset_path,
+        "encoding": encoding,
+        "delimiter": delimiter,
+        "columns": state["columns"],
+        "metric_columns": state["metrics"],
+        "scanned_row_count": state["scanned"],
+        "matched_row_count": state["matched"],
+        "scan_truncated": state["truncated"],
+        "time_range": {
+            "min_year": min(state["years"]) if state["years"] else None,
+            "max_year": max(state["years"]) if state["years"] else None,
+        },
+        "monthly_record_counts": [
+            {"month": month, "record_count": state["months"][month]}
+            for month in sorted(state["months"])
+        ],
+        "missing_values_by_column": {
+            col: int(state["missing"].get(col, 0)) for col in state["columns"]
+        },
+        "exact_duplicate_count": state["duplicates"],
+        "deduplicated_record_count": len(deduplicated_rows),
+        "annual_summary": annual_summary[:100],
+        "exports": exports,
+        "download_urls": [item["download_url"] for item in exports],
+        "zip_members_processed": members[:200],
+        "schema_variants": state["schema_variants"][:20],
+        **raw_export,
+    }

harness_safe.cordis.yml

@@ -0,0 +1,31 @@
+- id: sdk-jsonrpc-server
+  name: '@deepseek-ai/dsh-sdk-jsonrpc-server'
+  config:
+    maxTokensAsSuccess: true
+
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY
+    streamIdleTimeoutMs: 300000
+    models:
+      - id: !!js process.env.DSH_MODEL ?? 'glm-5.2'
+        contextWindow: !!js Number(process.env.DSH_CONTEXT_WINDOW ?? 128000)
+
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
+  config:
+    includeHarnessIdentity: true
+    includeRuntimeContext: false
+    persona: !!js process.env.DSH_SYSTEM_PROMPT ?? 'You are Global Marine Foundation Data Agent. Reply in Chinese by default. Only output the final answer.'
+    workspaceContext: false
+    skills:
+      enabled: false
+    toolBash: false
+    toolJobs: false
+
+- id: sessions
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: !!js process.env.DSH_SESSION_ROOT ?? '/tmp/deepseek-harness-sessions'
+    compression: none

marine_mcp.py

@@ -0,0 +1,755 @@
+"""Marine MCP bridge to the school Marine Data FastAPI."""
+from __future__ import annotations
+import os, re, time
+from typing import Any
+import httpx
+from mcp.server.mcpserver import MCPServer
+from fisheries_hf import analyze_and_export, download_dataset_file
+
+API_URL = os.environ.get("MARINE_API_URL", "").strip().rstrip("/")
+if not API_URL:
+    raise RuntimeError("MARINE_API_URL is not configured")
+
+mcp = MCPServer(
+    "Marine Data",
+    instructions=(
+        "Gateway to the user's school Marine Data Server. "
+        "Use health/domains/status for live state. "
+        "Use marine_query and marine_subset for real data retrieval. "
+        "School-server Ocean data and Hugging Face fisheries data are separate data planes. "
+        "Search both configured fisheries repositories and preserve repository provenance. "
+        "Use fisheries_analyze_export with both repository and path for actual CSV/TSV/ZIP content, filtering, statistics and CSV export. "
+        "Never invent files or values."
+    ),
+)
+
+def _get(path: str) -> dict[str, Any]:
+    with httpx.Client(timeout=60.0, follow_redirects=True) as client:
+        r = client.get(f"{API_URL}{path}")
+        r.raise_for_status()
+        return r.json()
+
+def _post(path: str, payload: dict[str, Any]) -> dict[str, Any]:
+    with httpx.Client(timeout=30.0, follow_redirects=True) as client:
+        response = client.post(
+            f"{API_URL}{path}",
+            json=payload,
+        )
+
+        if response.is_error:
+            try:
+                body = response.json()
+                detail = (
+                    body.get("detail")
+                    if isinstance(body, dict)
+                    else None
+                )
+            except Exception:
+                detail = None
+
+            if not detail:
+                detail = (
+                    response.text.strip()
+                    or response.reason_phrase
+                )
+
+            return {
+                "status": "error",
+                "http_status": response.status_code,
+                "detail": detail,
+            }
+
+        return response.json()
+
+def _domain(value: str) -> str:
+    value = value.strip().lower()
+    if value not in {"ocean", "tuna", "squid"}:
+        raise ValueError("domain must be one of: ocean, tuna, squid")
+    return value
+
+
+def _norm_domain(value: str) -> str:
+    value = value.strip().lower()
+    if value not in {"ocean", "tuna", "squid"}:
+        raise ValueError("domain must be one of: ocean, tuna, squid")
+    return value
+
+
+@mcp.tool()
+def marine_health() -> dict[str, Any]:
+    """Check whether the school Marine Data Server is reachable."""
+    return _get("/health")
+
+@mcp.tool()
+def marine_domains() -> dict[str, Any]:
+    """Return live overview for ocean, tuna and squid."""
+    return _get("/domains")
+
+@mcp.tool()
+def marine_status(domain: str = "ocean") -> dict[str, Any]:
+    """Return detailed live status for one data center."""
+    d = _domain(domain)
+    return _get("/status" if d == "ocean" else f"/status/{d}")
+
+@mcp.tool()
+def marine_catalog() -> dict[str, Any]:
+    'Return the live Ocean data catalog from the school server.'
+    return _get("/catalog")
+
+
+@mcp.tool()
+def marine_query(
+    date: str,
+    variable: str,
+    source: str,
+    domain: str = "ocean",
+) -> dict[str, Any]:
+    'Check whether a source/variable/date exists on the school Ocean server.'
+    return _post(
+        "/data/query",
+        {
+            "domain": _norm_domain(domain),
+            "source": source.strip().lower(),
+            "date": date.strip(),
+            "variable": variable.strip().lower(),
+        },
+    )
+
+@mcp.tool()
+def marine_subset(
+    date: str,
+    lon_min: float,
+    lon_max: float,
+    lat_min: float,
+    lat_max: float,
+    variable: str,
+    source: str,
+    domain: str = "ocean",
+    depth: float | None = None,
+) -> dict[str, Any]:
+    'Create a NetCDF subset from any supported Ocean source.'
+    payload = {
+        "domain": _norm_domain(domain),
+        "source": source.strip().lower(),
+        "date": date.strip(),
+        "variable": variable.strip().lower(),
+        "lon_min": float(lon_min),
+        "lon_max": float(lon_max),
+        "lat_min": float(lat_min),
+        "lat_max": float(lat_max),
+        "format": "netcdf",
+    }
+    if depth is not None:
+        payload["depth"] = float(depth)
+    result = _post("/data/export", payload)
+    path = result.get("download_path")
+    if isinstance(path, str) and path.startswith("/download/"):
+        result["download_url"] = f"{API_URL}{path}"
+    return result
+
+@mcp.tool()
+def marine_download(token: str) -> dict[str, Any]:
+    """Convert an export token into a browser HTTPS download URL."""
+    token = token.strip()
+    if not re.fullmatch(r"[A-Za-z0-9_-]{20,160}", token):
+        raise ValueError("invalid download token")
+    return {"download_url": f"{API_URL}/download/{token}"}
+
+
+
+@mcp.tool()
+def marine_fisheries_catalog() -> dict:
+    """Compatibility alias for the live Hugging Face squid catalog."""
+    return fisheries_catalog("squid")
+
+
+@mcp.tool()
+def marine_export(
+    date: str,
+    lon_min: float,
+    lon_max: float,
+    lat_min: float,
+    lat_max: float,
+    variable: str,
+    source: str,
+    format: str = "netcdf",
+    domain: str = "ocean",
+    depth: float | None = None,
+) -> dict[str, Any]:
+    'Export Ocean data as netcdf/csv/xlsx/json/geotiff/png.'
+    payload = {
+        "domain": _norm_domain(domain),
+        "source": source.strip().lower(),
+        "date": date.strip(),
+        "variable": variable.strip().lower(),
+        "lon_min": float(lon_min),
+        "lon_max": float(lon_max),
+        "lat_min": float(lat_min),
+        "lat_max": float(lat_max),
+        "format": format.strip().lower(),
+    }
+    if depth is not None:
+        payload["depth"] = float(depth)
+    result = _post("/data/export", payload)
+    path = result.get("download_path")
+    if isinstance(path, str) and path.startswith("/download/"):
+        result["download_url"] = f"{API_URL}{path}"
+    return result
+
+# ============================================================================
+# Hugging Face fisheries data bridge
+# ============================================================================
+HF_SQUID_DATASET_REPO = (
+    os.environ.get("HF_SQUID_DATASET_REPO")
+    or os.environ.get("HF_DATASET_REPO")
+    or "globalsquiddatabase/squid_dataset"
+).strip()
+HF_TUNA_DATASET_REPO = (
+    os.environ.get("HF_TUNA_DATASET_REPO")
+    or "globalsquiddatabase/Tuna-Fisheries-Dataset"
+).strip()
+HF_DATASET_REPOS = {
+    "squid": HF_SQUID_DATASET_REPO,
+    "tuna": HF_TUNA_DATASET_REPO,
+}
+HF_DATASET_REPO = HF_SQUID_DATASET_REPO
+
+_HF_TREE_CACHE: dict[str, dict[str, Any]] = {}
+
+_SQUID_CATALOG = [
+    {
+        "source": "FAO FishStatJ",
+        "resource": "全球柔鱼科捕捞量",
+        "variables": ["catch", "species", "country_or_area", "year"],
+        "time_range": "1998-2024（正式资源清单口径；实际标准层以live inventory为准）",
+        "spatial_scale": "全球；无经纬度网格",
+        "temporal_scale": "年",
+        "science_uses": ["长期捕捞量变化", "国家/地区贡献结构", "物种捕捞组成变化"],
+        "caveats": ["不能用于精细渔场位置分析", "没有努力量时不能直接得到CPUE"],
+    },
+    {
+        "source": "Sea Around Us",
+        "resource": "全球柔鱼科重建捕捞量",
+        "variables": ["reconstructed_catch", "species", "area", "year"],
+        "time_range": "1950-2019",
+        "spatial_scale": "0.5°×0.5°",
+        "temporal_scale": "年",
+        "science_uses": ["历史空间捕捞格局", "渔场重心变化", "区域热点年代际变化"],
+        "caveats": ["属于重建数据", "使用时必须说明重建口径"],
+    },
+    {
+        "source": "SPRFMO",
+        "resource": "南太平洋捕捞量与努力量",
+        "variables": ["catch", "effort", "year", "grid"],
+        "time_range": "2007-2021（后续补充以live inventory为准）",
+        "spatial_scale": "5°×5°",
+        "temporal_scale": "年/仓库后续标准层可能含月",
+        "science_uses": ["区域作业格局", "捕捞强度变化", "重算CPUE后做相对丰度分析"],
+        "caveats": ["CPUE必须用总catch÷总effort重算", "不同努力量单位不可直接相加"],
+    },
+    {
+        "source": "WCPFC",
+        "resource": "中西太平洋月度捕捞数据",
+        "variables": ["catch", "year", "month", "grid", "coverage"],
+        "time_range": "1967-2024",
+        "spatial_scale": "1°×1°",
+        "temporal_scale": "月",
+        "science_uses": ["月尺度捕捞热点", "渔场季节迁移", "与SST/锋面/ENSO做时空匹配"],
+        "caveats": ["需结合coverage解释缺测", "缺测不能直接解释为零捕捞"],
+    },
+    {
+        "source": "RAM Legacy",
+        "resource": "茎柔鱼资源评估数据",
+        "variables": ["catch", "biomass", "recruitment", "CPUE"],
+        "time_range": "1950-2024（不同种群覆盖不同）",
+        "spatial_scale": "评估种群/stock",
+        "temporal_scale": "年",
+        "science_uses": ["资源量长期变化", "补充量变化", "资源状态与捕捞压力分析"],
+        "caveats": ["不同评估模型单位/标准化口径不同", "跨种群比较前需统一数据字典"],
+    },
+    {
+        "source": "Global Fishing Watch",
+        "resource": "全球AIS表观渔船作业努力量",
+        "variables": ["apparent_fishing_hours", "vessel_presence", "flag", "gear_type"],
+        "time_range": "2012-2024",
+        "spatial_scale": "0.1°×0.1°",
+        "temporal_scale": "月",
+        "science_uses": ["渔船活动强度", "作业努力热点迁移", "与渔获/CPUE联合分析捕捞压力"],
+        "caveats": ["AIS+模型推断的表观努力量", "不能等同于捕捞量、日志努力量或资源丰度"],
+    },
+    {
+        "source": "VIIRS VBD",
+        "resource": "夜��船探测三变量",
+        "variables": ["n_detect", "avg_rade9", "pct_detect"],
+        "time_range": "2017-2024",
+        "spatial_scale": "15 arcsec 原始；仓库可能含1°标准层",
+        "temporal_scale": "月",
+        "science_uses": ["夜光作业船热点", "灯光强度与探测稳定性", "补充AIS不足区的活动证据"],
+        "caveats": ["夜光探测不是捕捞量", "必须结合cvg评估观测机会"],
+    },
+    {
+        "source": "VIIRS CVG",
+        "resource": "卫星覆盖次数/观测机会",
+        "variables": ["cvg"],
+        "time_range": "2017-2024",
+        "spatial_scale": "15 arcsec",
+        "temporal_scale": "月",
+        "science_uses": ["夜光质量控制", "覆盖偏差校正", "区域/月际可比性评估"],
+        "caveats": ["cvg不是渔船活动量", "不能当作捕捞努力量"],
+    },
+]
+
+_TUNA_SOURCE_TERMS = {
+    "WCPFC": ["wcpfc"],
+    "IATTC": ["iattc"],
+    "ICCAT": ["iccat"],
+    "IOTC": ["iotc"],
+    "CCSBT": ["ccsbt"],
+    "FAO": ["fao"],
+    "GFW": ["global fishing watch", "gfw"],
+}
+
+_DOMAIN_TERMS = {
+    "squid": [
+        "柔鱼", "鱿鱼", "squid", "ommastre", "dosidicus", "illex", "todarodes",
+        "sprfmo", "npfc", "ram legacy", "viirs", "vbd", "sea around", "sea_around", "gfw",
+    ],
+    "tuna": [
+        "金枪鱼", "tuna", "wcpfc", "iattc", "iccat", "iotc", "ccsbt",
+        "yellowfin", "bigeye", "skipjack", "albacore", "bluefin", "yft", "bet", "skj",
+    ],
+}
+
+def _hf_headers() -> dict[str, str]:
+    token = os.environ.get("HF_TOKEN", "").strip()
+    return {"Authorization": f"Bearer {token}"} if token else {}
+
+def _hf_tree(repo: str, force: bool = False) -> list[dict[str, Any]]:
+    repo = repo.strip()
+    now = time.time()
+    cache = _HF_TREE_CACHE.get(repo) or {}
+    if (
+        not force
+        and now - float(cache.get("ts") or 0) < 300
+        and cache.get("items")
+    ):
+        return list(cache["items"])
+
+    next_url = f"https://huggingface.co/api/datasets/{repo}/tree/main"
+    params: dict[str, Any] | None = {
+        "recursive": "true",
+        "expand": "false",
+        "limit": 1000,
+    }
+    items: list[dict[str, Any]] = []
+    pages = 0
+    with httpx.Client(timeout=30.0, follow_redirects=True) as client:
+        while next_url and pages < 50:
+            r = client.get(next_url, params=params, headers=_hf_headers())
+            params = None
+            pages += 1
+            if r.status_code in {401, 403}:
+                raise RuntimeError(
+                    f"无法读取 Hugging Face Dataset {repo}。请确认 Space Secret 中存在具有 Dataset 读取权限的 HF_TOKEN，"
+                    "且运行时配置已将 HF_TOKEN 传给 marine MCP 子进程。"
+                )
+            if r.status_code >= 400:
+                raise RuntimeError(
+                    f"Hugging Face Dataset tree request failed: HTTP {r.status_code} ({repo}): {r.text[:300]}"
+                )
+            data = r.json()
+            if not isinstance(data, list):
+                raise RuntimeError(f"Hugging Face Dataset tree returned an unexpected response: {repo}")
+            items.extend(x for x in data if isinstance(x, dict))
+            next_url = (r.links.get("next") or {}).get("url")
+
+    if next_url:
+        raise RuntimeError("Hugging Face Dataset 文件树超过在线分页安全上限。")
+    _HF_TREE_CACHE[repo] = {"ts": now, "items": items}
+    return items
+
+
+def _repos_for_domain(domain: str) -> list[tuple[str, str]]:
+    d = (domain or "all").strip().lower()
+    if d == "squid":
+        return [("squid", HF_SQUID_DATASET_REPO)]
+    if d == "tuna":
+        return [("tuna", HF_TUNA_DATASET_REPO)]
+    if d in {"all", "fisheries", "fishery"}:
+        return list(HF_DATASET_REPOS.items())
+    raise ValueError("domain must be one of: squid, tuna, all")
+
+
+def _hf_files(
+    domain: str = "all",
+    force: bool = False,
+) -> tuple[list[dict[str, Any]], dict[str, str]]:
+    files: list[dict[str, Any]] = []
+    errors: dict[str, str] = {}
+    for repo_domain, repo in _repos_for_domain(domain):
+        try:
+            items = _files_only(_hf_tree(repo, force=force))
+        except Exception as exc:
+            errors[repo] = str(exc)[:500]
+            continue
+        for item in items:
+            row = dict(item)
+            row["repository"] = repo
+            row["repository_domain"] = repo_domain
+            files.append(row)
+    return files, errors
+
+def _files_only(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        x for x in items
+        if str(x.get("type") or "").lower() in {"file", "blob"}
+        or (
+            not str(x.get("type") or "").strip()
+            and "path" in x
+            and "size" in x
+        )
+    ]
+
+def _human_bytes(value: Any) -> str:
+    try:
+        n = float(value or 0)
+    except Exception:
+        n = 0.0
+    units = ["B", "KB", "MB", "GB", "TB"]
+    i = 0
+    while n >= 1024 and i < len(units) - 1:
+        n /= 1024.0
+        i += 1
+    return f"{n:.2f} {units[i]}"
+
+def _domain_match(path: str, domain: str) -> bool:
+    d = (domain or "all").strip().lower()
+    if d in {"all", "fisheries", "fishery"}:
+        return True
+    terms = _DOMAIN_TERMS.get(d)
+    if not terms:
+        raise ValueError("domain must be one of: squid, tuna, all")
+    p = path.lower()
+    return any(term in p for term in terms)
+
+def _query_terms(query: str) -> list[str]:
+    q = (query or "").strip().lower()
+    aliases = {
+        "柔鱼": ["柔鱼", "鱿鱼", "squid"],
+        "鱿鱼": ["柔鱼", "鱿鱼", "squid"],
+        "金枪鱼": ["金枪鱼", "tuna"],
+        "捕捞量": ["捕捞", "catch"],
+        "努力量": ["努力", "effort", "fishing_hours", "fishing hours"],
+        "cpue": ["cpue"],
+        "渔船": ["gfw", "vessel", "ais", "viirs", "vbd"],
+        "夜光": ["viirs", "vbd", "cvg", "n_detect", "rade"],
+        "资源评估": ["ram", "assessment", "biomass", "recruitment"],
+    }
+    terms = [q] if q else []
+    for key, vals in aliases.items():
+        if key in q:
+            terms.extend(vals)
+    for token in re.split(r"[\s,，/、;；]+", q):
+        if len(token) >= 2:
+            terms.append(token)
+    out = []
+    for t in terms:
+        if t and t not in out:
+            out.append(t)
+    return out
+
+@mcp.tool()
+def fisheries_catalog(domain: str = "squid") -> dict[str, Any]:
+    """Return fisheries resources and the scientific questions they can support."""
+    d = (domain or "squid").strip().lower()
+    if d not in {"squid", "tuna", "all"}:
+        raise ValueError("domain must be one of: squid, tuna, all")
+
+    result: dict[str, Any] = {
+        "status": "ok",
+        "repositories": [repo for _, repo in _repos_for_domain(d)],
+        "data_plane": "Hugging Face Dataset",
+        "important_distinction": (
+            "HF fisheries Dataset is separate from the school-server tuna_data/squid_data task databases. "
+            "Empty school-server task databases do not mean the HF fisheries Dataset is empty."
+        ),
+        "aggregation_rules": {
+            "catch": "SUM over time/space; preserve units",
+            "effort": "SUM only within compatible units",
+            "CPUE": "recompute aggregated total catch / aggregated total effort; never average monthly CPUE",
+            "GFW": "AIS/model-derived apparent fishing effort; not catch or stock abundance",
+            "VIIRS": "night-light vessel activity evidence; use CVG for observation-opportunity QC",
+        },
+    }
+
+    if d in {"squid", "all"}:
+        result["squid_semantic_catalog"] = _SQUID_CATALOG
+
+    try:
+        items, repo_errors = _hf_files(d)
+        live = []
+        for x in items:
+            path = str(x.get("path") or "")
+            live.append({
+                "path": path,
+                "repository": x.get("repository", ""),
+                "repository_domain": x.get("repository_domain", ""),
+                "size_bytes": int(x.get("size") or 0),
+                "size": _human_bytes(x.get("size") or 0),
+            })
+        result["repository_errors"] = repo_errors
+
+        total_bytes = sum(x["size_bytes"] for x in live)
+        result["live_inventory"] = {
+            "matched_file_count": len(live),
+            "matched_size_bytes": total_bytes,
+            "matched_size": _human_bytes(total_bytes),
+            "path_preview": live[:40],
+            "preview_truncated": len(live) > 40,
+        }
+
+        if d in {"tuna", "all"}:
+            groups = {}
+            for source, terms in _TUNA_SOURCE_TERMS.items():
+                matched = [x for x in live if any(t in x["path"].lower() for t in terms)]
+                if matched:
+                    groups[source] = {
+                        "file_count": len(matched),
+                        "size": _human_bytes(sum(x["size_bytes"] for x in matched)),
+                        "examples": [x["path"] for x in matched[:6]],
+                    }
+            result["tuna_live_groups"] = groups
+            result["tuna_note"] = (
+                "Tuna availability is derived from the live HF repository tree. "
+                "Do not use a planned download list as proof that a tuna dataset is already present."
+            )
+    except Exception as exc:
+        result["live_inventory"] = {"status": "error", "detail": str(exc)}
+
+    return result
+
+@mcp.tool()
+def fisheries_inventory(
+    domain: str = "all",
+    keyword: str | None = None,
+    max_results: int = 80,
+    refresh: bool = False,
+    query: str | None = None,
+    source: str | None = None,
+) -> dict[str, Any]:
+    """Inspect both live fisheries trees.
+
+    Preferred arguments are ``domain`` (squid/tuna/all) and ``keyword``.
+    ``query`` and ``source`` are accepted as compatibility aliases because
+    some chat runtimes emit those names for inventory searches.
+    """
+    if query and not keyword:
+        keyword = str(query).strip()
+    if source:
+        source_text = str(source).strip()
+        source_lower = source_text.lower()
+        if source_lower in {"squid", "tuna", "all", "fisheries", "fishery"}:
+            domain = source_lower
+        elif source_text == HF_SQUID_DATASET_REPO:
+            domain = "squid"
+        elif source_text == HF_TUNA_DATASET_REPO:
+            domain = "tuna"
+        elif not keyword:
+            keyword = source_text
+    try:
+        items, repo_errors = _hf_files(domain, force=bool(refresh))
+    except Exception as exc:
+        return {"status": "error", "repositories": HF_DATASET_REPOS, "detail": str(exc)}
+
+    d = (domain or "all").strip().lower()
+    limit = max(1, min(int(max_results or 80), 200))
+    qterms = _query_terms(keyword or "")
+
+    matches = []
+    for x in items:
+        path = str(x.get("path") or "")
+        if d not in {"all", "fisheries", "fishery"} and x.get("repository_domain") != d:
+            continue
+        plow = path.lower()
+        if qterms and not any(t in plow for t in qterms):
+            continue
+        matches.append({
+            "path": path,
+            "repository": x.get("repository", ""),
+            "repository_domain": x.get("repository_domain", ""),
+            "size_bytes": int(x.get("size") or 0),
+            "size": _human_bytes(x.get("size") or 0),
+        })
+
+    total_bytes = sum(x["size_bytes"] for x in matches)
+    return {
+        "status": "ok",
+        "repositories": [repo for _, repo in _repos_for_domain(d)],
+        "repository_errors": repo_errors,
+        "branch": "main",
+        "domain": d,
+        "keyword": keyword,
+        "matched_file_count": len(matches),
+        "matched_size_bytes": total_bytes,
+        "matched_size": _human_bytes(total_bytes),
+        "results": matches[:limit],
+        "results_truncated": len(matches) > limit,
+        "cache_seconds": 300,
+    }
+
+@mcp.tool()
+def fisheries_search(query: str, max_results: int = 40) -> dict[str, Any]:
+    """Search real HF fisheries files by source/species/metric/path keywords."""
+    q = (query or "").strip()
+    if not q:
+        raise ValueError("query is required")
+
+    try:
+        items, repo_errors = _hf_files("all")
+    except Exception as exc:
+        return {"status": "error", "repositories": HF_DATASET_REPOS, "detail": str(exc)}
+
+    terms = _query_terms(q)
+    scored = []
+    for x in items:
+        path = str(x.get("path") or "")
+        plow = path.lower()
+        score = sum(1 for t in terms if t in plow)
+        if score:
+            scored.append((
+                score,
+                {
+                    "path": path,
+                    "repository": x.get("repository", ""),
+                    "repository_domain": x.get("repository_domain", ""),
+                    "size_bytes": int(x.get("size") or 0),
+                    "size": _human_bytes(x.get("size") or 0),
+                },
+            ))
+
+    scored.sort(key=lambda z: (-z[0], z[1]["path"]))
+    limit = max(1, min(int(max_results or 40), 100))
+    return {
+        "status": "ok",
+        "repositories": list(HF_DATASET_REPOS.values()),
+        "repository_errors": repo_errors,
+        "query": q,
+        "matched_file_count": len(scored),
+        "results": [x for _, x in scored[:limit]],
+        "results_truncated": len(scored) > limit,
+    }
+
+
+def _live_file(path: str, repository: str | None = None) -> dict[str, Any]:
+    clean = str(path or "").strip().lstrip("/")
+    if not clean:
+        raise ValueError("path is required")
+    selector = str(repository or "all").strip()
+    lowered = selector.lower()
+    if lowered in HF_DATASET_REPOS:
+        domain = lowered
+    elif selector in HF_DATASET_REPOS.values():
+        domain = next(k for k, v in HF_DATASET_REPOS.items() if v == selector)
+    elif lowered in {"", "all"}:
+        domain = "all"
+    else:
+        raise ValueError("repository must be squid, tuna, all, or an exact configured repository id")
+    items, repo_errors = _hf_files(domain)
+    exact = [item for item in items if str(item.get("path") or "") == clean]
+    if not exact:
+        raise ValueError(
+            "请求的文件不在所选 Hugging Face main 实时文件树中；"
+            "请先使用 fisheries_search 或 fisheries_inventory 确认精确路径。"
+        )
+    if len(exact) > 1:
+        repos = ", ".join(str(item.get("repository") or "") for item in exact)
+        raise ValueError(f"同一路径存在于多个仓库（{repos}），请显式指定 repository。")
+    item = exact[0]
+    return {
+        "path": clean,
+        "size_bytes": int(item.get("size") or 0),
+        "repository": str(item.get("repository") or ""),
+        "repository_domain": str(item.get("repository_domain") or ""),
+        "repository_errors": repo_errors,
+    }
+
+
+@mcp.tool()
+def fisheries_analyze_export(
+    path: str,
+    repository: str | None = None,
+    year: int | None = None,
+    lon_min: float | None = None,
+    lon_max: float | None = None,
+    lat_min: float | None = None,
+    lat_max: float | None = None,
+    metric_columns: str | None = None,
+    max_rows: int = 2_000_000,
+) -> dict[str, Any]:
+    """Read a validated HF fisheries CSV/TSV/ZIP, analyze/filter it, and export a real CSV.
+
+    The path must exactly match one configured Dataset live tree. Repository
+    may be squid, tuna, or an exact configured repository id. The tool
+    accepts optional year and bounding-box filters, reports actual columns,
+    scanned/matched rows, missing values, exact duplicates, monthly counts and
+    annual metric sums, then returns a tokenized HTTPS download URL.  It never
+    accepts arbitrary URLs, repositories, shell commands, or local paths.
+    """
+    try:
+        item = _live_file(path, repository=repository)
+        local_path, revision = download_dataset_file(
+            item["path"],
+            item["size_bytes"],
+            repository=item["repository"],
+        )
+        return analyze_and_export(
+            local_path,
+            dataset_path=item["path"],
+            revision=revision,
+            repository=item["repository"],
+            year=year,
+            lon_min=lon_min,
+            lon_max=lon_max,
+            lat_min=lat_min,
+            lat_max=lat_max,
+            metric_columns=metric_columns,
+            max_rows=max_rows,
+        )
+    except Exception as exc:
+        return {
+            "status": "error",
+            "repository": str(repository or "all"),
+            "path": str(path or ""),
+            "detail": str(exc),
+        }
+
+@mcp.tool()
+def fisheries_data_rules() -> dict[str, Any]:
+    """Return fisheries aggregation and interpretation rules."""
+    return {
+        "catch": {
+            "aggregation": "sum",
+            "rule": "时间/空间聚合采用求和，并保留原始单位。",
+        },
+        "effort": {
+            "aggregation": "sum",
+            "rule": "时间/空间聚合采用求和；fishing hours 与 vessel-days 等不同单位不可直接相加。",
+        },
+        "CPUE": {
+            "aggregation": "recompute",
+            "rule": "CPUE = 聚合后的总catch / 聚合后的总effort；禁止直接平均月度或格点CPUE。",
+        },
+        "GFW": {
+            "rule": "apparent fishing hours 是AIS+模型推断的表观作业努力量，不等同于真实捕捞量或资源丰度。",
+        },
+        "VIIRS": {
+            "rule": "n_detect/avg_rade9/pct_detect是夜光船活动指标；cvg是观测机会/覆盖质量控制变量。",
+        },
+        "missing_time": {
+            "rule": "不得把月度/年度数据伪装成逐日数据；缺失月份必须显式报告。",
+        },
+    }
+
+
+if __name__ == "__main__":
+    mcp.run()

query_tools/__init__.py

@@ -1,21 +0,0 @@
-"""
-查询工具模块包
-
-包含以下查询工具：
-- logbook_availability_query: Logbook 数据可用性查询
-- query_gfw: GFW 渔船作业努力量查询（2012-2024）
-- literature_cpue_query: 文献 CPUE 数据查询
-- query_sprfmo: SPRFMO 南太平洋数据查询
-"""
-
-from .logbook_availability_query import query_logbook_availability
-from .query_gfw import query_gfw
-from .literature_cpue_query import query_literature_cpue
-from .query_sprfmo import query_sprfmo
-
-__all__ = [
-    'query_logbook_availability',
-    'query_gfw',
-    'query_literature_cpue',
-    'query_sprfmo',
-]

query_tools/literature_cpue_query.py

@@ -1,384 +0,0 @@
-import pandas as pd
-import os
-from datetime import datetime
-
-# ============================
-# 项目路径
-# ============================
-
-BASE_DIR = os.path.dirname(
-    os.path.dirname(
-        os.path.abspath(__file__)
-    )
-)
-
-DATA_PATH = os.path.join(
-    BASE_DIR,
-    "data",
-    "literature_cpue.csv"
-)
-
-OUTPUT_DIR = os.path.join(
-    BASE_DIR,
-    "output"
-)
-
-
-# ============================
-# Markdown生成
-# ============================
-
-def dataframe_to_markdown(df, max_rows=10):
-    if df.empty:
-        return "暂无数据"
-
-    df = df.head(max_rows)
-
-    columns = df.columns.tolist()
-
-    text = "| " + " | ".join(columns) + " |\n"
-
-    text += "| " + " | ".join(
-        ["---"] * len(columns)
-    ) + " |\n"
-
-    for _, row in df.iterrows():
-        text += "| " + " | ".join(
-            str(x)
-            for x in row.tolist()
-        ) + " |\n"
-
-    return text
-
-
-# ============================
-# 年份检查
-# ============================
-
-def check_year(value, name):
-    if value is None:
-        return None
-
-    try:
-
-        return int(value)
-
-    except:
-
-        raise ValueError(
-            f"{name}必须为数字，例如2020"
-        )
-
-
-# ============================
-# CPUE文献查询函数
-# ============================
-
-def query_literature_cpue(
-        region=None,
-        year_start=None,
-        year_end=None,
-        species=None,
-        response_variable=None,
-        paper_type=None,
-        output_format="markdown"
-):
-    """
-    查询CPUE相关论文
-
-    参数:
-    ----------------
-    region:
-        海区
-
-    year_start:
-        起始年份
-
-    year_end:
-        结束年份
-
-    species:
-        物种
-
-    response_variable:
-        响应变量
-        例如 CPUE biomass
-
-    paper_type:
-        论文类型
-
-    output_format:
-        markdown/csv/excel
-
-
-    返回:
-    ----------------
-
-    summary
-
-    records
-
-    preview_markdown
-
-    csv_path
-
-    excel_path
-
-    source_files
-
-    """
-
-    try:
-
-        # ======================
-        # 参数处理
-        # ======================
-
-        year_start = check_year(
-            year_start,
-            "year_start"
-        )
-
-        year_end = check_year(
-            year_end,
-            "year_end"
-        )
-
-        if year_start and year_end:
-
-            if year_start > year_end:
-                return {
-
-                    "summary":
-                        "开始年份不能大于结束年份",
-
-                    "records": []
-
-                }
-
-        # ======================
-        # 数据检查
-        # ======================
-
-        if not os.path.exists(DATA_PATH):
-            return {
-
-                "summary":
-                    "未找到CPUE文献数据库",
-
-                "records": []
-
-            }
-
-        df = pd.read_csv(
-            DATA_PATH
-        )
-
-        # 年份转换
-
-        if "year" in df.columns:
-            df["year"] = pd.to_numeric(
-                df["year"],
-                errors="coerce"
-            )
-
-        result = df.copy()
-
-        # ======================
-        # 条件过滤
-        # ======================
-
-        filters = {
-
-            "region": region,
-
-            "species": species,
-
-            "response_variable":
-                response_variable,
-
-            "paper_type":
-                paper_type
-
-        }
-
-        for column, value in filters.items():
-
-            if value:
-                result = result[
-                    result[column]
-                    .astype(str)
-                    .str.contains(
-                        value,
-                        na=False,
-                        case=False
-                    )
-                ]
-
-        if year_start:
-            result = result[
-                result.year >= year_start
-                ]
-
-        if year_end:
-            result = result[
-                result.year <= year_end
-                ]
-
-        # ======================
-        # 无结果
-        # ======================
-
-        if result.empty:
-            return {
-
-                "summary":
-                    "没有找到符合条件的CPUE论文",
-
-                "records": [],
-
-                "preview_markdown":
-                    "暂无数据",
-
-                "source_files":
-                    [
-                        DATA_PATH
-                    ]
-
-            }
-
-        # ======================
-        # 统计摘要
-        # ======================
-
-        summary = {
-
-            "paper_count":
-                len(result),
-
-            "year_range":
-                [
-                    int(result.year.min()),
-                    int(result.year.max())
-                ],
-
-            "regions":
-                result.region.unique()
-                .tolist(),
-
-            "species":
-                result.species.unique()
-                .tolist(),
-
-            "models":
-                result.model.unique()
-                .tolist()
-
-        }
-
-        # ======================
-        # 文件输出
-        # ======================
-
-        os.makedirs(
-            OUTPUT_DIR,
-            exist_ok=True
-        )
-
-        timestamp = datetime.now() \
-            .strftime(
-            "%Y%m%d_%H%M%S"
-        )
-
-        csv_path = None
-
-        excel_path = None
-
-        if output_format in [
-            "csv",
-            "excel"
-        ]:
-            csv_path = os.path.join(
-                OUTPUT_DIR,
-                f"cpue_literature_{timestamp}.csv"
-            )
-
-            result.to_csv(
-                csv_path,
-                index=False,
-                encoding="utf-8-sig"
-            )
-
-        if output_format == "excel":
-            excel_path = os.path.join(
-                OUTPUT_DIR,
-                f"cpue_literature_{timestamp}.xlsx"
-            )
-
-            result.to_excel(
-                excel_path,
-                index=False
-            )
-
-        # ======================
-        # 返回Agent
-        # ======================
-
-        return {
-
-            "summary":
-                summary,
-
-            "records":
-                result.to_dict(
-                    orient="records"
-                ),
-
-            "preview_markdown":
-                dataframe_to_markdown(
-                    result
-                ),
-
-            "csv_path":
-                csv_path,
-
-            "excel_path":
-                excel_path,
-
-            "source_files":
-                [
-                    DATA_PATH
-                ]
-
-        }
-
-
-
-    except Exception as e:
-
-        return {
-
-            "summary":
-                f"查询CPUE文献失败:{str(e)}",
-
-            "records": []
-
-        }
-
-
-# 这是一个示例 Python 脚本。
-
-# 按 ⌃R 执行或将其替换为您的代码。
-# 按 双击 ⇧ 在所有地方搜索类、文件、工具窗口、操作和设置。
-
-
-def print_hi(name):
-    # 在下面的代码行中使用断点来调试脚本。
-    print(f'Hi, {name}')  # 按 ⌘F8 切换断点。
-
-
-# 按装订区域中的绿色按钮以运行脚本。
-if __name__ == '__main__':
-    print_hi('PyCharm')
-
-# 访问 https://www.jetbrains.com/help/pycharm/ 获取 PyCharm 帮助

query_tools/logbook_availability_query.py

@@ -1,401 +0,0 @@
-import pandas as pd
-import os
-from datetime import datetime
-
-
-# ============================
-# 自动定位项目路径
-# ============================
-
-BASE_DIR = os.path.dirname(
-    os.path.dirname(
-        os.path.abspath(__file__)
-    )
-)
-
-
-DATA_PATH = os.path.join(
-    BASE_DIR,
-    "data",
-    "logbook_availability.csv"
-)
-
-
-OUTPUT_DIR = os.path.join(
-    BASE_DIR,
-    "output"
-)
-
-
-
-# ============================
-# markdown生成函数
-# 替代 pandas.to_markdown()
-# ============================
-
-def dataframe_to_markdown(df, max_rows=10):
-
-    if df.empty:
-        return "暂无数据"
-
-
-    df=df.head(max_rows)
-
-
-    columns=df.columns.tolist()
-
-
-    md="| " + " | ".join(columns)+" |\n"
-
-    md+="| "+" | ".join(
-        ["---"]*len(columns)
-    )+" |\n"
-
-
-    for _,row in df.iterrows():
-
-        md+="| "+" | ".join(
-            str(x)
-            for x in row.tolist()
-        )+" |\n"
-
-
-    return md
-
-
-
-# ============================
-# 参数检查
-# ============================
-
-def check_year(value,name):
-
-    if value is None:
-        return None
-
-
-    try:
-        return int(value)
-
-    except:
-
-        raise ValueError(
-            f"{name}必须是年份数字，例如2020"
-        )
-
-
-
-
-# ============================
-# 主查询函数
-# ============================
-
-def query_logbook_availability(
-        region=None,
-        year_start=None,
-        year_end=None,
-        species=None,
-        data_type=None,
-        output_format="markdown"
-):
-
-    """
-    查询logbook数据可用性
-
-    返回:
-    summary
-    records
-    preview_markdown
-    csv_path
-    excel_path
-    source_files
-
-    """
-
-
-    try:
-
-        # ------------------
-        # 参数校验
-        # ------------------
-
-        year_start = check_year(
-            year_start,
-            "year_start"
-        )
-
-        year_end = check_year(
-            year_end,
-            "year_end"
-        )
-
-
-
-        if year_start and year_end:
-
-            if year_start > year_end:
-
-                return {
-
-                    "summary":
-                    "错误：开始年份不能大于结束年份",
-
-                    "records":[]
-
-                }
-
-
-
-        # ------------------
-        # 文件检查
-        # ------------------
-
-        if not os.path.exists(DATA_PATH):
-
-            return {
-
-                "summary":
-                f"找不到数据文件:{DATA_PATH}",
-
-                "records":[]
-
-            }
-
-
-
-        # ------------------
-        # 读取数据
-        # ------------------
-
-        df=pd.read_csv(
-            DATA_PATH
-        )
-
-
-        # year强制转换
-
-        if "year" in df.columns:
-
-            df["year"]=pd.to_numeric(
-                df["year"],
-                errors="coerce"
-            )
-
-
-        result=df.copy()
-
-
-
-        # ------------------
-        # 条件过滤
-        # ------------------
-
-        if region:
-
-            result=result[
-                result["region"]
-                .astype(str)
-                .str.contains(
-                    region,
-                    na=False
-                )
-            ]
-
-
-
-        if species:
-
-            result=result[
-                result["species"]
-                .astype(str)
-                .str.contains(
-                    species,
-                    na=False
-                )
-            ]
-
-
-
-        if data_type:
-
-            result=result[
-                result["data_type"]
-                .astype(str)
-                .str.contains(
-                    data_type,
-                    na=False
-                )
-            ]
-
-
-
-        if year_start:
-
-            result=result[
-                result.year>=year_start
-            ]
-
-
-
-        if year_end:
-
-            result=result[
-                result.year<=year_end
-            ]
-
-
-
-        # ------------------
-        # 无结果
-        # ------------------
-
-        if result.empty:
-
-            return {
-
-                "summary":
-                "没有找到符合条件的logbook数据",
-
-                "records":[],
-
-                "preview_markdown":
-                "暂无数据",
-
-                "source_files":
-                [
-                    DATA_PATH
-                ]
-
-            }
-
-
-
-        # ------------------
-        # 统计信息
-        # ------------------
-
-        summary={
-
-            "records_count":
-            len(result),
-
-            "year_range":
-            [
-                int(result.year.min()),
-                int(result.year.max())
-            ],
-
-            "regions":
-            result.region.unique().tolist(),
-
-            "species":
-            result.species.unique().tolist()
-
-        }
-
-
-
-        # ------------------
-        # 输出文件
-        # ------------------
-
-        os.makedirs(
-            OUTPUT_DIR,
-            exist_ok=True
-        )
-
-
-        timestamp=datetime.now()\
-            .strftime("%Y%m%d_%H%M%S")
-
-
-        csv_path=None
-        excel_path=None
-
-
-
-        if output_format in [
-            "csv",
-            "excel"
-        ]:
-
-            csv_path=os.path.join(
-                OUTPUT_DIR,
-                f"logbook_{timestamp}.csv"
-            )
-
-
-            result.to_csv(
-                csv_path,
-                index=False,
-                encoding="utf-8-sig"
-            )
-
-
-
-        if output_format=="excel":
-
-            excel_path=os.path.join(
-                OUTPUT_DIR,
-                f"logbook_{timestamp}.xlsx"
-            )
-
-
-            result.to_excel(
-                excel_path,
-                index=False
-            )
-
-
-
-        # ------------------
-        # Agent标准返回
-        # ------------------
-
-        return {
-
-
-            "summary":
-            summary,
-
-
-            "records":
-            result.to_dict(
-                orient="records"
-            ),
-
-
-            "preview_markdown":
-            dataframe_to_markdown(
-                result
-            ),
-
-
-            "csv_path":
-            csv_path,
-
-
-            "excel_path":
-            excel_path,
-
-
-            "source_files":
-            [
-                DATA_PATH
-            ]
-
-        }
-
-
-
-    except Exception as e:
-
-
-        return {
-
-            "summary":
-            f"查询失败:{str(e)}",
-
-            "records":[]
-
-        }

query_tools/query_gfw.py

@@ -1,310 +0,0 @@
-import argparse
-import io
-import tempfile
-import zipfile
-from pathlib import Path
-
-import pandas as pd
-
-
-def find_gfw_zip(gfw_zip=None):
-    """
-    查找GFW压缩包。
-
-    如果运行时指定了压缩包路径，就直接使用；
-    如果没有指定，就依次在脚本所在文件夹、当前运行目录、
-    """
-    if gfw_zip:
-        path = Path(gfw_zip).expanduser()
-        if not path.exists():
-            raise FileNotFoundError(f"指定的GFW压缩包不存在：{path}")
-        return path
-
-    search_dirs = [
-        Path(__file__).resolve().parent,
-        Path.cwd(),
-        Path.home() / "Desktop" / "资料下载" / "柔鱼数据",
-    ]
-
-    for folder in search_dirs:
-        if not folder.exists():
-            continue
-
-        files = sorted(folder.glob("GFW*.zip"))
-        if files:
-            return files[0]
-
-    raise FileNotFoundError(
-        "没有找到GFW压缩包。请把GFW zip文件与本脚本放在同一文件夹，"
-        "或运行时使用 --gfw-zip 指定文件路径。"
-    )
-
-
-def _open_year_zip_streaming(outer_zip, year_zip_path):
-    year_zip_file = tempfile.NamedTemporaryFile(delete=False, suffix=".zip")
-    try:
-        with outer_zip.open(year_zip_path, "r") as source, year_zip_file as target:
-            while True:
-                chunk = source.read(4 * 1024 * 1024)
-                if not chunk:
-                    break
-                target.write(chunk)
-    except Exception:
-        year_zip_file.close()
-        Path(year_zip_file.name).unlink(missing_ok=True)
-        raise
-
-    return zipfile.ZipFile(year_zip_file.name, "r")
-
-
-def read_gfw_month(year, month, gfw_zip=None):
-    """读取指定年份和月份的GFW月尺度数据。"""
-    if month < 1 or month > 12:
-        raise ValueError("月份必须在1到12之间")
-    if not 2012 <= year <= 2024:
-        raise ValueError("年份只允许2012到2024年")
-
-    gfw_zip = find_gfw_zip(gfw_zip)
-
-    month_csv_name = (
-        f"fleet-monthly-csvs-10-v3-{year}-{month:02d}-01.csv"
-    )
-    year_zip_name = f"fleet-monthly-csvs-10-v3-{year}.zip"
-
-    with zipfile.ZipFile(gfw_zip, "r") as outer_zip:
-        file_list = outer_zip.namelist()
-
-        # 外层压缩包中直接存在月份CSV
-        for file_name in file_list:
-            if file_name.endswith(month_csv_name):
-                with outer_zip.open(file_name) as file:
-                    return pd.read_csv(file), gfw_zip
-
-        # 月份CSV位于年度压缩包中
-        year_zip_path = None
-        for file_name in file_list:
-            if file_name.endswith(year_zip_name):
-                year_zip_path = file_name
-                break
-
-        if year_zip_path is None:
-            raise FileNotFoundError(f"没有找到{year}年的GFW数据")
-
-        with _open_year_zip_streaming(outer_zip, year_zip_path) as year_zip:
-            for file_name in year_zip.namelist():
-                if file_name.endswith(month_csv_name):
-                    with year_zip.open(file_name) as file:
-                        return pd.read_csv(file), gfw_zip
-
-    raise FileNotFoundError(f"没有找到{year}年{month}月的GFW数据")
-
-
-def query_gfw(
-    year,
-    month,
-    lat_min,
-    lat_max,
-    lon_min,
-    lon_max,
-    flag=None,
-    geartype=None,
-    min_fishing_hours=None,
-    gfw_zip=None,
-):
-    """
-    按时间和空间范围查询GFW渔船作业努力量。
-
-    lon_min大于lon_max时，表示查询范围跨越180°经线。
-    例如145°E至175°W可写为lon_min=145、lon_max=-175。
-    """
-    if lat_min > lat_max:
-        raise ValueError("最小纬度不能大于最大纬度")
-
-    data, gfw_zip = read_gfw_month(
-        year=year,
-        month=month,
-        gfw_zip=gfw_zip,
-    )
-
-    required_columns = [
-        "date",
-        "year",
-        "month",
-        "cell_ll_lat",
-        "cell_ll_lon",
-        "flag",
-        "geartype",
-        "hours",
-        "fishing_hours",
-        "mmsi_present",
-    ]
-
-    missing_columns = [
-        column for column in required_columns
-        if column not in data.columns
-    ]
-
-    if missing_columns:
-        raise ValueError(f"数据中缺少必要字段：{missing_columns}")
-
-    numeric_columns = [
-        "cell_ll_lat",
-        "cell_ll_lon",
-        "hours",
-        "fishing_hours",
-        "mmsi_present",
-    ]
-
-    invalid_value_warnings = []
-    for column in numeric_columns:
-        original_non_null_count = data[column].notna().sum()
-        data[column] = pd.to_numeric(
-            data[column],
-            errors="coerce",
-        )
-        coerced_null_count = data[column].isna().sum()
-        invalid_count = coerced_null_count - (len(data) - original_non_null_count)
-        if invalid_count > 0:
-            invalid_value_warnings.append((column, int(invalid_count)))
-
-    if invalid_value_warnings:
-        warning_parts = [
-            f"{column}: {count} 个值无法转换为数值"
-            for column, count in invalid_value_warnings
-        ]
-        print("数值转换警告：以下列存在无法解析的脏值，已按 NaN 处理 -> " + "；".join(warning_parts))
-
-    result = data[
-        (data["cell_ll_lat"] >= lat_min)
-        & (data["cell_ll_lat"] <= lat_max)
-    ].copy()
-
-    if lon_min <= lon_max:
-        result = result[
-            (result["cell_ll_lon"] >= lon_min)
-            & (result["cell_ll_lon"] <= lon_max)
-        ]
-    else:
-        result = result[
-            (result["cell_ll_lon"] >= lon_min)
-            | (result["cell_ll_lon"] <= lon_max)
-        ]
-
-    if flag:
-        result = result[
-            result["flag"].notna()
-            & (result["flag"].astype(str).str.upper() == flag.upper())
-        ]
-
-    if geartype:
-        result = result[
-            result["geartype"].notna()
-            & (result["geartype"].astype(str).str.lower() == geartype.lower())
-        ]
-
-    if min_fishing_hours is not None:
-        result = result[
-            result["fishing_hours"] >= min_fishing_hours
-        ]
-
-    result = result.sort_values(
-        by=["fishing_hours", "hours"],
-        ascending=[False, False],
-    ).reset_index(drop=True)
-
-    summary = {
-        "data_file": str(gfw_zip),
-        "year": year,
-        "month": month,
-        "lat_range": [lat_min, lat_max],
-        "lon_range": [lon_min, lon_max],
-        "flag": flag if flag else "all",
-        "geartype": geartype if geartype else "all",
-        "record_count": len(result),
-        "total_hours": round(
-            result["hours"].fillna(0).sum(),
-            4,
-        ),
-        "total_fishing_hours": round(
-            result["fishing_hours"].fillna(0).sum(),
-            4,
-        ),
-    }
-
-    return result, summary
-
-
-def save_result(result, output_file):
-    """保存查询结果。"""
-    output_path = Path(output_file).expanduser()
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-
-    result.to_csv(
-        output_path,
-        index=False,
-        encoding="utf-8-sig",
-    )
-
-    return output_path
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="查询GFW月尺度渔船作业努力量数据"
-    )
-
-    parser.add_argument("--gfw-zip", default=None)
-    parser.add_argument("--year", type=int, default=2012)
-    parser.add_argument("--month", type=int, default=1)
-    parser.add_argument("--lat-min", type=float, default=-10)
-    parser.add_argument("--lat-max", type=float, default=10)
-    parser.add_argument("--lon-min", type=float, default=145)
-    parser.add_argument("--lon-max", type=float, default=-175)
-    parser.add_argument("--flag", default=None)
-    parser.add_argument("--geartype", default=None)
-    parser.add_argument("--min-fishing-hours", type=float, default=None)
-    parser.add_argument("--output", default="GFW查询结果.csv")
-
-    args = parser.parse_args()
-
-    if args.year is not None and not 2012 <= args.year <= 2024:
-        raise ValueError("年份只允许2012到2024年")
-
-    if args.month is not None and not 1 <= args.month <= 12:
-        raise ValueError("月份只允许1到12月")
-
-    result, summary = query_gfw(
-        year=args.year,
-        month=args.month,
-        lat_min=args.lat_min,
-        lat_max=args.lat_max,
-        lon_min=args.lon_min,
-        lon_max=args.lon_max,
-        flag=args.flag,
-        geartype=args.geartype,
-        min_fishing_hours=args.min_fishing_hours,
-        gfw_zip=args.gfw_zip,
-    )
-
-    print("\n查询汇总")
-    print("-" * 40)
-
-    for key, value in summary.items():
-        print(f"{key}: {value}")
-
-    print("\n捕捞小时数最高的前10条记录")
-    print("-" * 40)
-
-    if result.empty:
-        print("没有查询到符合条件的数据")
-    else:
-        print(result.head(10).to_string(index=False))
-
-    output_path = save_result(result, args.output)
-
-    print("\n结果已保存到：")
-    print(output_path)
-
-
-if __name__ == "__main__":
-    main()

query_tools/query_sprfmo.py

@@ -1,311 +0,0 @@
-"""
-query_sprfmo.py - SPRFMO 查询函数（最简稳定版）
-"""
-
-from pathlib import Path
-import pandas as pd
-
-# ============================================================
-# 1. 路径配置
-# ============================================================
-DATA_DIR = Path(r"C:\Users\niniy\Desktop\PythonProject\SPRFMO南太平洋 5×5")
-
-# ============================================================
-# 2. 字段映射（原始 Excel 字段 → 标准字段）
-# ============================================================
-CATCH_MAP = {
-    "Year": "year",
-    "Flag": "country",
-    "Latitude": "lat",
-    "Longitude": "lon",
-    "Species": "species",
-    "NumVesels": "numvessels",
-    "Harvest_kg": "catch",
-    "Discard_kg": "discard",
-}
-
-EFFORT_MAP = {
-    "Year": "year",
-    "Fishery": "gear_type",
-    "NumDays": "effort",
-    "NumEvents": "num_events",
-    "NumVessels": "numvessels",
-}
-
-# ============================================================
-# 3. 国家代码映射
-# ============================================================
-COUNTRY_MAP = {
-    "中国": "CHN", "China": "CHN", "CHN": "CHN",
-    "日本": "JPN", "Japan": "JPN", "JPN": "JPN",
-    "韩国": "KOR", "Korea": "KOR", "KOR": "KOR",
-    "中国台湾": "TWN", "Taiwan": "TWN", "TWN": "TWN",
-    "智利": "CHL", "Chile": "CHL", "CHL": "CHL",
-    "秘鲁": "PER", "Peru": "PER", "PER": "PER",
-    "俄罗斯": "RUS", "Russia": "RUS", "RUS": "RUS",
-    "美国": "USA", "USA": "USA", "United States": "USA",
-    "新西兰": "NZL", "New Zealand": "NZL", "NZL": "NZL",
-    "澳大利亚": "AUS", "Australia": "AUS", "AUS": "AUS",
-}
-
-# ============================================================
-# 4. 主查询入口
-# ============================================================
-def query_sprfmo(filters=None, group_by=None, metrics="catch",
-                 data_type="catch", output_format="markdown"):
-    """SPRFMO 数据查询入口"""
-    if filters is None:
-        filters = {}
-    if group_by is None:
-        group_by = []
-    elif isinstance(group_by, str):
-        group_by = [group_by]
-    if isinstance(metrics, str):
-        metrics = [metrics]
-
-    warnings = []
-
-    print("\n" + "=" * 60)
-    print(f"【query_sprfmo】data_type={data_type}")
-    print(f"  filters={filters}")
-    print(f"  group_by={group_by}, metrics={metrics}")
-    print("=" * 60)
-
-    # 诊断信息
-    print(f"\n📂 数据文件夹: {DATA_DIR}")
-    print(f"   文件夹存在: {DATA_DIR.exists()}")
-    if DATA_DIR.exists():
-        all_files = list(DATA_DIR.glob("*.xlsx"))
-        print(f"   所有 Excel: {[f.name for f in all_files]}")
-        if not all_files:
-            warnings.append(f"⚠️ 文件夹下没有任何 .xlsx 文件")
-    else:
-        warnings.append(f"⚠️ 文件夹不存在: {DATA_DIR}")
-        return _error_result(f"文件夹不存在: {DATA_DIR}", warnings)
-
-    # 加载数据
-    if data_type == "catch":
-        df, source = _load_catch_data()
-    elif data_type == "effort":
-        df, source = _load_effort_data()
-    else:
-        return _error_result(f"未知 data_type: {data_type}", warnings)
-
-    # 字段翻译
-    df = _translate(df, data_type)
-    print(f"   翻译后字段: {df.columns.tolist()}")
-
-    # 国家代码翻译
-    if "country" in filters and filters["country"]:
-        c = str(filters["country"])
-        translated = COUNTRY_MAP.get(c, c)
-        filters["country"] = translated
-        if translated != c:
-            print(f"   国家翻译: '{c}' → '{translated}'")
-
-    # 筛选
-    df = _apply_filters(df, filters, data_type)
-
-    if len(df) == 0:
-        warnings.append("⚠️ 筛选后无数据，请检查筛选条件")
-
-    # 聚合
-    df = _aggregate(df, group_by, metrics, data_type)
-
-    # 返回
-    return {
-        "preview_markdown": df.to_markdown(index=False, floatfmt=".2f") if len(df) > 0 else "*（无数据）*",
-        "records": df.to_dict(orient="records"),
-        "csv_path": None,
-        "excel_path": None,
-        "summary": _build_summary(df, data_type),
-        "source_files": [source],
-        "warnings": warnings,
-        "metadata": {
-            "spatial_resolution": "5x5 degree",
-            "time_resolution": "annual",
-            "region": "South Pacific",
-            "unit": "kg" if data_type == "catch" else "days",
-        }
-    }
-
-
-# ============================================================
-# 5. 加载数据
-# ============================================================
-def _load_catch_data():
-    """加载捕捞量 Excel"""
-    files = []
-    for kw in ["捕捞", "Catch", "catch"]:
-        files.extend(DATA_DIR.glob(f"*{kw}*.xlsx"))
-    files = list(set(files))
-
-    if not files:
-        all_files = [f.name for f in DATA_DIR.glob("*.xlsx")]
-        raise FileNotFoundError(
-            f"找不到捕捞量文件（需含 '捕捞' 或 'Catch'）\n"
-            f"文件夹下所有 Excel: {all_files}"
-        )
-
-    df = pd.read_excel(files[0])
-    print(f"   ✅ 加载: {files[0].name} ({len(df)} 条)")
-    return df, str(files[0])
-
-
-def _load_effort_data():
-    """加载努力量 Excel"""
-    files = []
-    for kw in ["努力", "Effort", "effort"]:
-        files.extend(DATA_DIR.glob(f"*{kw}*.xlsx"))
-    files = list(set(files))
-
-    if not files:
-        all_files = [f.name for f in DATA_DIR.glob("*.xlsx")]
-        raise FileNotFoundError(
-            f"找不到努力量文件（需含 '努力' 或 'Effort'）\n"
-            f"文件夹下所有 Excel: {all_files}"
-        )
-
-    df = pd.read_excel(files[0])
-    print(f"   ✅ 加载: {files[0].name} ({len(df)} 条)")
-    return df, str(files[0])
-
-
-# ============================================================
-# 6. 字段翻译
-# ============================================================
-def _translate(df, data_type):
-    """原始字段 → 标准字段"""
-    fmap = CATCH_MAP if data_type == "catch" else EFFORT_MAP
-    used = {k: v for k, v in fmap.items() if k in df.columns}
-    return df.rename(columns=used)
-
-
-# ============================================================
-# 7. 筛选
-# ============================================================
-def _apply_filters(df, filters, data_type):
-    n0 = len(df)
-
-    if "year_start" in filters and filters["year_start"] is not None:
-        df = df[df["year"] >= filters["year_start"]]
-    if "year_end" in filters and filters["year_end"] is not None:
-        df = df[df["year"] <= filters["year_end"]]
-
-    if data_type == "catch":
-        if "country" in filters and filters["country"]:
-            c = str(filters["country"]).upper()
-            df = df[df["country"].astype(str).str.upper() == c]
-        if "species" in filters and filters["species"]:
-            kw = filters["species"]
-            df = df[df["species"].astype(str).str.contains(kw, case=False, na=False)]
-
-    elif data_type == "effort":
-        if "gear_type" in filters and filters["gear_type"]:
-            kw = filters["gear_type"]
-            df = df[df["gear_type"].astype(str).str.contains(kw, case=False, na=False)]
-
-    print(f"   筛选: {n0} → {len(df)} 条")
-    return df
-
-
-# ============================================================
-# 8. 聚合
-# ============================================================
-def _aggregate(df, group_by, metrics, data_type):
-    if not group_by:
-        return df
-
-    valid_g = [g for g in group_by if g in df.columns]
-    if not valid_g:
-        return df
-
-    valid_m = [m for m in metrics if m in df.columns]
-    if not valid_m:
-        return df
-
-    agg = {m: ("first" if m == "numvessels" else "sum") for m in valid_m}
-    df2 = df.groupby(valid_g, as_index=False).agg(agg)
-
-    print(f"   聚合: {len(df2)} 条")
-    return df2
-
-
-# ============================================================
-# 9. 摘要
-# ============================================================
-def _build_summary(df, data_type):
-    summary = {
-        "data_type": data_type,
-        "total_records": len(df),
-        "data_source": "SPRFMO",
-    }
-    if "year" in df.columns and len(df) > 0:
-        years = df["year"].dropna()
-        if len(years) > 0:
-            summary["year_range"] = f"{int(years.min())}-{int(years.max())}"
-    if data_type == "catch" and "catch" in df.columns:
-        summary["total_catch"] = float(df["catch"].sum())
-    elif data_type == "effort" and "effort" in df.columns:
-        summary["total_effort"] = float(df["effort"].sum())
-    return summary
-
-
-def _error_result(msg, warnings=None):
-    if warnings is None:
-        warnings = [msg]
-    return {
-        "preview_markdown": f"**错误**: {msg}",
-        "records": [],
-        "csv_path": None,
-        "excel_path": None,
-        "summary": {"data_type": None, "total_records": 0},
-        "source_files": [],
-        "warnings": warnings,
-        "metadata": {},
-    }
-
-
-# ============================================================
-# 10. 测试代码
-# ============================================================
-if __name__ == "__main__":
-    print("\n" + "🧪" * 30)
-    print("测试 query_sprfmo")
-    print("🧪" * 30)
-
-    # 测试 1
-    print("\n【测试 1】中国 2015-2020 年渔获量（按年）")
-    print("-" * 60)
-    r = query_sprfmo(
-        filters={"country": "CHN", "year_start": 2015, "year_end": 2020},
-        group_by=["year"],
-        metrics=["catch"],
-        data_type="catch",
-    )
-    print(r["preview_markdown"])
-    print("\n摘要:", r["summary"])
-    if r["warnings"]:
-        print("警告:")
-        for w in r["warnings"]:
-            print(f"  {w}")
-
-    # 测试 2
-    print("\n\n【测试 2】2018 年努力量（按渔业类型）")
-    print("-" * 60)
-    r2 = query_sprfmo(
-        filters={"year_start": 2018, "year_end": 2018},
-        group_by=["gear_type"],
-        metrics=["effort"],
-        data_type="effort",
-    )
-    print(r2["preview_markdown"])
-    print("\n摘要:", r2["summary"])
-    if r2["warnings"]:
-        print("警告:")
-        for w in r2["warnings"]:
-            print(f"  {w}")
-
-    print("\n" + "✅" * 30)
-    print("测试完成")
-    print("✅" * 30)

requirements.txt

@@ -1,6 +1,6 @@
-smolagents[gradio]>=1.0.0
-requests>=2.31.0
-pandas>=2.0.0
-huggingface_hub>=0.23.0
-openpyxl>=3.1.0
-openai>=2.0.0
+mcp[cli]>=2,<3
+httpx>=0.27,<1
+fastapi>=0.116,<1
+uvicorn[standard]>=0.35,<1
+
+deepseek-harness-sdk==0.1.0rc6

scripts/preflight.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+errors: list[str] = []
+warnings: list[str] = []
+
+
+def fail(msg: str) -> None:
+    errors.append(msg)
+
+
+def warn(msg: str) -> None:
+    warnings.append(msg)
+
+version_file = ROOT / "VERSION"
+version = version_file.read_text(encoding="utf-8").strip() if version_file.exists() else ""
+if not re.fullmatch(r"\d+\.\d+\.\d+", version):
+    fail("VERSION missing or not semantic x.y.z")
+
+readme = (ROOT / "README.md").read_text(encoding="utf-8") if (ROOT / "README.md").exists() else ""
+if not readme.startswith("---\n"):
+    fail("README.md must start with Hugging Face YAML front matter")
+else:
+    end = readme.find("\n---", 4)
+    if end < 0:
+        fail("README.md YAML front matter is not closed")
+    else:
+        meta = readme[4:end]
+        for required in ("title:", "sdk: docker", "app_port: 7860"):
+            if required not in meta:
+                fail(f"README.md metadata missing: {required}")
+
+app_html = ROOT / "app.html"
+if not app_html.exists():
+    fail("root app.html is missing")
+else:
+    html = app_html.read_text(encoding="utf-8")
+    if '__APP_VERSION__' not in html:
+        fail("app.html must use __APP_VERSION__ placeholder")
+    if 'data-view="projectPackage"' not in html:
+        fail("project data package sidebar entry is missing")
+
+ui = ROOT / "ui_server.py"
+if not ui.exists():
+    fail("ui_server.py is missing")
+else:
+    text = ui.read_text(encoding="utf-8")
+    if 'with_name("VERSION")' not in text:
+        fail("ui_server.py must load VERSION as the single version source")
+    if 'with_name("app.html")' not in text:
+        fail("ui_server.py must serve root app.html")
+    if 'templates/app.html' in text:
+        fail("ui_server.py still references templates/app.html")
+
+if (ROOT / "templates" / "app.html").exists():
+    fail("duplicate templates/app.html must not be shipped")
+
+for forbidden in (".pytest_cache", "__pycache__"):
+    matches = [p for p in ROOT.rglob(forbidden) if p.is_dir()]
+    if matches:
+        fail(f"forbidden cache directory present: {matches[0].relative_to(ROOT)}")
+if list(ROOT.rglob("*.pyc")):
+    fail("compiled .pyc files must not be shipped")
+
+for name in ("Dockerfile", "start.sh", "requirements.txt"):
+    if not (ROOT / name).exists():
+        fail(f"deployment file missing: {name}")
+
+if version and f"Current UI release: **v{version}**" not in readme:
+    warn("README current release line is not synchronized with VERSION")
+
+for msg in warnings:
+    print(f"[preflight] WARNING: {msg}")
+if errors:
+    for msg in errors:
+        print(f"[preflight] ERROR: {msg}", file=sys.stderr)
+    sys.exit(1)
+print(f"[preflight] OK: v{version}; single template; clean deployment tree")

sidebar_catalog.py

@@ -0,0 +1,116 @@
+"""Sidebar dataset catalog and Chinese display metadata.
+
+Keep static routing/catalog data outside ``ui_server.py`` so UI work does not
+accidentally alter the Ocean/Fisheries data-plane rules.
+"""
+
+FISHERY_TERMS = (
+    "柔鱼", "鱿鱼", "squid", "金枪鱼", "tuna", "wcpfc", "sprfmo", "npfc",
+    "iattc", "iccat", "iotc", "ccsbt", "effdis", "金枪鱼委员会",
+    "fao", "sea around", "ram legacy", "ram", "gfw", "global fishing watch",
+    "viirs", "vbd", "捕捞", "努力量", "cpue", "渔船", "资源评估", "biomass",
+    "recruitment",
+)
+
+OCEAN_TOOL_TERMS = (
+    "cmems", "era5", "oisst", "oc-cci", "occci", "sst", "海温", "温度",
+    "盐度", "thetao", "流速", "uo", "vo", "mlotst", "混合层", "zos",
+    "海面高度", "bgc", "叶绿素", "chlor", "chlor_a", "spco2", "碳酸盐",
+    "v10", "u10", "t2m", "msl", "slhf", "sshf", "ssrd", "strd", "tp",
+    "no3", "nppv", "o2", "po4", "anom", "10米风", "10 米风", "经向风", "纬向风",
+    "ocean 数据",
+    "ocean数据", "海洋环境", "学校海洋数据", "海洋数据服务器",
+)
+
+OCEAN_STATUS_TERMS = (
+    "三个数据中心", "ocean 状态", "ocean状态", "下载进度", "当前状态和存储量",
+    "海洋数据中心",
+)
+
+HF_SOURCE_ALIASES = {
+    "WCPFC": ("wcpfc", "中西太平洋"),
+    "SPRFMO": ("sprfmo", "南太平洋区域渔业"),
+    "NPFC": ("npfc", "北太平洋渔业"),
+    "FAO": ("fao",),
+    "Sea Around Us": ("sea around", "sea_around"),
+    "RAM Legacy": ("ram legacy", "ram_legacy", "/ram", "ram "),
+    "GFW": ("gfw", "global fishing watch"),
+    "VIIRS": ("viirs", "vbd"),
+    "IATTC": ("iattc", "美洲热带金枪鱼"),
+    "ICCAT": ("iccat", "大西洋金枪鱼"),
+    "IOTC": ("iotc", "印度洋金枪鱼"),
+    "CCSBT": ("ccsbt", "南方蓝鳍金枪鱼"),
+}
+
+OCEAN_CATALOG = (
+    ("cmems_physics", "CMEMS Physics", "CMEMS 海洋物理", ("so", "thetao", "uo", "vo")),
+    ("cmems_surface", "CMEMS Surface", "CMEMS 海表参数", ("mlotst", "zos")),
+    ("cmems_bgc", "CMEMS BGC", "CMEMS 生物地球化学", ("chl", "no3", "nppv", "o2", "po4", "si")),
+    ("cmems_carbonate", "CMEMS Carbonate", "CMEMS 碳酸盐系统", ("ph", "spco2")),
+    ("era5", "ERA5", "ERA5 大气再分析", ("msl", "t2m", "u10", "v10")),
+    ("era5_accum", "ERA5 Accumulation", "ERA5 累积量与通量", ("e", "slhf", "sshf", "ssrd", "strd", "tp")),
+    ("occci", "OC-CCI", "海色气候变化倡议", ("chlor_a", "chlor_a_log10_bias", "chlor_a_log10_rmsd", "total_nobs_sum")),
+    ("oisst", "OISST", "最优插值海表温度", ("sst", "anom", "err", "ice")),
+)
+
+OCEAN_SOURCE_DETAILS = {
+    "cmems_physics": {"description": "CMEMS 海洋物理三维场，供温度、盐度与海流分析。", "data_shape": "三维海洋场；部分导出格式需要指定深度"},
+    "cmems_surface": {"description": "CMEMS 海表与上层海洋参数，供混合层和海面高度分析。", "data_shape": "二维海表 / 上层海洋场"},
+    "cmems_bgc": {"description": "CMEMS 生物地球化学场，包含营养盐、叶绿素、溶解氧和初级生产力。", "data_shape": "三维生物地球化学场；部分导出格式需要指定深度"},
+    "cmems_carbonate": {"description": "CMEMS 海洋碳酸盐系统数据，供海洋酸化与碳循环分析。", "data_shape": "海表 / 三维变量以学校服务器实际产品为准"},
+    "era5": {"description": "ERA5 大气再分析瞬时场，包含气压、近地面气温和风场。", "data_shape": "二维大气表面场"},
+    "era5_accum": {"description": "ERA5 累积量与通量，包含降水、蒸发、辐射和热通量。", "data_shape": "二维大气表面累积 / 通量场"},
+    "occci": {"description": "ESA Ocean Colour CCI 海色数据，供叶绿素及观测质量分析。", "data_shape": "二维海表遥感场"},
+    "oisst": {"description": "NOAA 最优插值海表温度，包含海温、距平、误差和海冰浓度。", "data_shape": "二维海表格点场"},
+}
+
+FISHERIES_SOURCE_DETAILS = {
+    "WCPFC": "中西部太平洋金枪鱼及相关渔业统计与空间数据。",
+    "SPRFMO": "南太平洋公海渔业捕捞量与努力量资料。",
+    "NPFC": "北太平洋公海渔业统计与管理资料。",
+    "FAO": "联合国粮农组织全球捕捞产量统计。",
+    "Sea Around Us": "全球历史重建捕捞量及空间分布数据。",
+    "RAM Legacy": "全球渔业种群评估、资源量与补充量数据。",
+    "GFW": "基于 AIS 与模型推断的全球表观捕捞活动数据。",
+    "VIIRS": "夜光船探测和卫星观测机会数据；不能直接等同于捕捞量。",
+    "IATTC": "东太平洋金枪鱼区域渔业管理资料。",
+    "ICCAT": "大西洋金枪鱼及相关物种渔业资料。",
+    "IOTC": "印度洋金枪鱼及相关物种渔业资料。",
+    "CCSBT": "南方蓝鳍金枪鱼养护与资源评估资料。",
+}
+
+OCEAN_VARIABLE_NAMES_ZH = {
+    "so": "盐度", "thetao": "海水温度", "uo": "东向流速", "vo": "北向流速",
+    "mlotst": "混合层深度", "zos": "海面高度", "chl": "叶绿素", "no3": "硝酸盐",
+    "nppv": "净初级生产力", "o2": "溶解氧", "po4": "磷酸盐", "si": "硅酸盐",
+    "ph": "酸碱度", "spco2": "海表二氧化碳分压", "msl": "海平面气压",
+    "t2m": "2米气温", "u10": "10米东向风", "v10": "10米北向风", "e": "蒸发",
+    "slhf": "潜热通量", "sshf": "感热通量", "ssrd": "地表太阳辐射",
+    "strd": "地表热辐射", "tp": "总降水", "chlor_a": "叶绿素a",
+    "chlor_a_log10_bias": "叶绿素偏差", "chlor_a_log10_rmsd": "叶绿素均方根差",
+    "total_nobs_sum": "有效观测数", "sst": "海表温度", "anom": "温度距平",
+    "err": "估计误差", "ice": "海冰浓度",
+}
+
+HF_SOURCE_NAMES_ZH = {
+    "WCPFC": "中西部太平洋渔业委员会", "SPRFMO": "南太平洋区域渔业管理组织",
+    "NPFC": "北太平洋渔业委员会", "FAO": "联合国粮农组织",
+    "Sea Around Us": "海洋环绕我们数据库", "RAM Legacy": "RAM 渔业资源评估数据库",
+    "GFW": "全球渔业观察", "VIIRS": "可见光红外成像辐射仪",
+    "IATTC": "美洲热带金枪鱼委员会", "ICCAT": "大西洋金枪鱼养护委员会",
+    "IOTC": "印度洋金枪鱼委员会", "CCSBT": "南方蓝鳍金枪鱼养护委员会",
+}
+
+HF_SOURCE_CATEGORIES = {
+    "WCPFC": ("tuna", "金枪鱼区域组织"), "IATTC": ("tuna", "金枪鱼区域组织"),
+    "ICCAT": ("tuna", "金枪鱼区域组织"), "IOTC": ("tuna", "金枪鱼区域组织"),
+    "CCSBT": ("tuna", "金枪鱼区域组织"), "SPRFMO": ("squid", "柔鱼及区域渔业组织"),
+    "NPFC": ("squid", "柔鱼及区域渔业组织"), "FAO": ("general", "综合渔业统计"),
+    "Sea Around Us": ("general", "综合渔业统计"), "RAM Legacy": ("general", "资源评估数据"),
+    "GFW": ("observation", "捕捞活动观测"), "VIIRS": ("observation", "船舶活动遥感观测"),
+}
+
+EXPECTED_METADATA_FIELDS = (
+    "time_range", "temporal_resolution", "spatial_resolution", "spatial_coverage",
+    "depth_range", "units", "updated_at",
+)

skills/marine-data/SKILL.md

@@ -0,0 +1,60 @@
+# Marine Data
+
+Use Marine MCP for the user's school marine data platform.
+
+Status:
+- `mcp_marine_marine_health`
+- `mcp_marine_marine_domains`
+- `mcp_marine_marine_status`
+
+Retrieval:
+- `mcp_marine_marine_query`
+- `mcp_marine_marine_subset`
+- `mcp_marine_marine_download`
+
+Current retrieval MVP: ocean/OISST, `sst`, `anom`, `err`, `ice`, geographic NetCDF subset with expiring HTTPS URL.
+For “1998-07-01, 120–130E, 20–30N SST, NetCDF”, query first, then subset, then return the resulting `download_url`.
+Do not inspect the HF container for school-server data and do not invent files.
+
+Multi-format export:
+- `mcp_marine_marine_export`
+- formats: netcdf, csv, xlsx, json, geotiff, png
+- return the absolute HTTPS `download_url`
+
+## Ocean multi-source V3
+Use mcp_marine_marine_catalog for source/variable discovery.
+Sources: cmems_physics, cmems_surface, cmems_bgc, cmems_carbonate, era5, era5_accum, occci, oisst.
+Formats: netcdf, csv, xlsx, json, geotiff, png.
+Use depth for GeoTIFF/PNG when the variable has a depth dimension.
+Return the absolute HTTPS download_url.
+
+## HF fisheries data plane
+Use `mcp_marine_fisheries_catalog`, `mcp_marine_fisheries_inventory`,
+`mcp_marine_fisheries_search`, `mcp_marine_fisheries_data_rules`, and
+`mcp_marine_fisheries_analyze_export` for
+squid/tuna catch, effort, CPUE, vessel activity, stock assessment and RFMO data.
+
+Use `mcp_marine_fisheries_analyze_export` whenever the user asks for actual
+columns, row counts, missing/duplicate checks, filters, aggregation or CSV
+export.  It validates the exact path against the live HF tree, pins the current
+commit SHA, supports CSV/TSV and CSV/TSV members in ZIP, and returns a tokenized
+download URL.  Do not ask for Shell/Run/JS approval as a substitute.
+
+HF fisheries Dataset and the school-server tuna/squid task databases are separate.
+Do not infer HF absence from an empty school-server task DB.
+
+
+## Fisheries live inventory fast path
+
+For squid/tuna fisheries inventory, catalog, source availability, and "what files
+are already present" questions, the UI backend injects a
+`[HF_FISHERIES_LIVE_CONTEXT]` block from the live Hugging Face Dataset main tree.
+
+When that context is present:
+- answer inventory/presence questions directly from it;
+- do not call `start_mcp_server`;
+- use the content tool for actual data reads/analysis/export;
+- do not infer availability from planning spreadsheets.
+
+Marine MCP is reserved for school-server Ocean data and is connected lazily only
+when an Ocean request needs it.

start.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Fail fast on broken Space metadata, duplicate templates, or stale cache artifacts.
+python3 /home/user/app/scripts/preflight.py
+
+# ============================================================
+# Required non-model settings
+# ============================================================
+
+: "${CODEWHALE_RUNTIME_TOKEN:?Missing CODEWHALE_RUNTIME_TOKEN secret}"
+: "${MARINE_API_URL:?Missing MARINE_API_URL variable}"
+
+# ============================================================
+# Model key
+#
+# We do NOT require or use DEEPSEEK_API_KEY.
+# Prefer the dedicated OpenCode Go secret.
+# Fall back to OPENAI_API_KEY only if you chose to store the same
+# OpenCode Go key under that name in Hugging Face.
+# ============================================================
+
+MODEL_API_KEY="${OPENCODE_GO_API_KEY:-${OPENAI_API_KEY:-}}"
+
+if [ -z "${MODEL_API_KEY}" ]; then
+  echo "[startup] ERROR: no OpenCode Go key was injected."
+  echo "[startup] Expected one of: OPENCODE_GO_API_KEY or OPENAI_API_KEY"
+  echo "[startup] Available environment variable names containing KEY/API:"
+  env | cut -d= -f1 | grep -E 'KEY|API' | sort || true
+  exit 1
+fi
+
+# ============================================================
+# Force CodeWhale to OpenCode Go -> GLM-5.3
+# ============================================================
+
+export OPENCODE_GO_API_KEY="${MODEL_API_KEY}"
+export CODEWHALE_PROVIDER="opencode-go"
+export CODEWHALE_MODEL="glm-5.2"
+export OPENCODE_GO_MODEL="glm-5.2"
+
+unset OPENAI_BASE_URL OPENAI_MODEL CODEWHALE_BASE_URL || true
+export OPENCODE_GO_BASE_URL="https://opencode.ai/zen/go/v1"
+
+# ============================================================
+# Web / Runtime
+# ============================================================
+
+export PORT="${PORT:-7860}"
+export CODEWHALE_INTERNAL_URL="http://127.0.0.1:7878"
+export FISHERIES_EXPORT_ROOT="${FISHERIES_EXPORT_ROOT:-/tmp/squid_fisheries_exports}"
+export HF_FISHERIES_CACHE_ROOT="${HF_FISHERIES_CACHE_ROOT:-/tmp/squid_hf_fisheries_cache}"
+if [ -z "${PUBLIC_BASE_URL:-}" ] && [ -n "${SPACE_HOST:-}" ]; then
+  export PUBLIC_BASE_URL="https://${SPACE_HOST}"
+fi
+
+# ============================================================
+# Build private Marine MCP runtime configuration
+# ============================================================
+
+RUNTIME_MCP_CONFIG="/tmp/codewhale-marine-mcp.json"
+export RUNTIME_MCP_CONFIG
+
+python3 - <<'PY_MCP_CONFIG'
+import json
+import os
+from pathlib import Path
+
+env = {
+    "MARINE_API_URL": os.environ["MARINE_API_URL"],
+    "HF_SQUID_DATASET_REPO": (
+        os.environ.get("HF_SQUID_DATASET_REPO")
+        or os.environ.get("HF_DATASET_REPO")
+        or "globalsquiddatabase/squid_dataset"
+    ),
+    "HF_TUNA_DATASET_REPO": (
+        os.environ.get("HF_TUNA_DATASET_REPO")
+        or "globalsquiddatabase/Tuna-Fisheries-Dataset"
+    ),
+    "FISHERIES_EXPORT_ROOT": os.environ.get(
+        "FISHERIES_EXPORT_ROOT", "/tmp/squid_fisheries_exports"
+    ),
+    "HF_FISHERIES_CACHE_ROOT": os.environ.get(
+        "HF_FISHERIES_CACHE_ROOT", "/tmp/squid_hf_fisheries_cache"
+    ),
+    "HF_SQUID_DATASET_REVISION": (
+        os.environ.get("HF_SQUID_DATASET_REVISION")
+        or os.environ.get("HF_DATASET_REVISION", "")
+    ),
+    "HF_TUNA_DATASET_REVISION": os.environ.get("HF_TUNA_DATASET_REVISION", ""),
+    "PUBLIC_BASE_URL": os.environ.get("PUBLIC_BASE_URL", ""),
+}
+
+hf_token = os.environ.get("HF_TOKEN", "").strip()
+if hf_token:
+    env["HF_TOKEN"] = hf_token
+
+cfg = {
+    "timeouts": {
+        "connect_timeout": 15,
+        "execute_timeout": 900,
+        "read_timeout": 900,
+    },
+    "servers": {
+        "marine": {
+            "command": "python3",
+            "args": ["/home/user/app/marine_mcp.py"],
+            "disabled": False,
+            "required": False,
+            "env": env,
+        }
+    },
+}
+
+p = Path(os.environ["RUNTIME_MCP_CONFIG"])
+p.write_text(
+    json.dumps(cfg, ensure_ascii=False, indent=2) + "\n",
+    encoding="utf-8",
+)
+p.chmod(0o600)
+
+print("[startup] private Marine MCP runtime config ready")
+PY_MCP_CONFIG
+
+# Legacy CodeWhale MCP-config variable name.
+# This only points to the MCP config file; it does NOT select DeepSeek.
+export DEEPSEEK_MCP_CONFIG="${RUNTIME_MCP_CONFIG}"
+
+# ============================================================
+# Startup information
+# ============================================================
+
+echo "[startup] CodeWhale:"
+codewhale --version
+echo "[startup] provider=${CODEWHALE_PROVIDER}"
+echo "[startup] model=${CODEWHALE_MODEL}"
+echo "[startup] endpoint=${OPENAI_BASE_URL:-}"
+echo "[startup] OpenCode Go key present=yes"
+
+# ============================================================
+# Start CodeWhale Runtime
+# ============================================================
+
+codewhale app-server --http \
+  --host 127.0.0.1 \
+  --port 7878 \
+  --auth-token "${CODEWHALE_RUNTIME_TOKEN}" &
+
+CW_PID=$!
+trap 'kill "$CW_PID" 2>/dev/null || true' EXIT INT TERM
+
+for i in $(seq 1 60); do
+  if curl -fsS --max-time 2 \
+    http://127.0.0.1:7878/health \
+    >/dev/null 2>&1; then
+    echo "[startup] private CodeWhale Runtime ready"
+    break
+  fi
+
+  kill -0 "$CW_PID" 2>/dev/null || {
+    echo "[startup] CodeWhale exited"
+    exit 1
+  }
+
+  sleep 1
+done
+
+# ============================================================
+# Marine API health check
+# ============================================================
+
+curl -fsS --max-time 12 "${MARINE_API_URL%/}/health" || true
+echo
+
+# ============================================================
+# Start Squid Agent Web UI
+# ============================================================
+
+exec uvicorn ui_server:app \
+  --host 0.0.0.0 \
+  --port "${PORT}" \
+  --proxy-headers

tests/test_data_routing_and_export_guard.py

@@ -0,0 +1,86 @@
+import ast
+import re
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_helpers():
+    source = ROOT / "ui_server.py"
+    tree = ast.parse(source.read_text(encoding="utf-8"))
+    names = {
+        "_is_fisheries_prompt",
+        "_needs_ocean_mcp",
+        "_is_ocean_export_request",
+        "_apply_ocean_export_defaults",
+        "_ocean_export_execution_error",
+    }
+    functions = [
+        node for node in tree.body
+        if isinstance(node, ast.FunctionDef) and node.name in names
+    ]
+    catalog = {}
+    exec((ROOT / "sidebar_catalog.py").read_text(encoding="utf-8"), catalog)
+    namespace = {
+        "re": re,
+        "_FISHERY_TERMS": catalog["FISHERY_TERMS"],
+        "_OCEAN_TOOL_TERMS": catalog["OCEAN_TOOL_TERMS"],
+        "_OCEAN_STATUS_TERMS": catalog["OCEAN_STATUS_TERMS"],
+    }
+    exec(
+        compile(ast.Module(body=functions, type_ignores=[]), str(source), "exec"),
+        namespace,
+    )
+    return namespace
+
+
+helpers = load_helpers()
+
+
+class DataRoutingTests(unittest.TestCase):
+    def test_tuna_commissions_route_to_fisheries(self):
+        route = helpers["_is_fisheries_prompt"]
+        for source in ("IATTC", "ICCAT", "IOTC", "CCSBT", "EFFDIS_LL2000-2024"):
+            self.assertTrue(route(f"查询 {source} 当前已入库数据"), source)
+
+    def test_variable_only_v10_routes_to_ocean(self):
+        route = helpers["_needs_ocean_mcp"]
+        self.assertTrue(route("导出1998年1月4日135E-140E的v10数据"))
+        self.assertFalse(route("provide a normal conversation response"))
+
+    def test_variable_only_v10_gets_era5_and_netcdf_defaults(self):
+        routed = helpers["_apply_ocean_export_defaults"](
+            "导出1998年1月4日135E-140E的v10数据"
+        )
+        self.assertIn("source=era5", routed)
+        self.assertIn("format=netcdf", routed)
+        self.assertIn("mcp_marine_marine_export", routed)
+
+    def test_export_without_real_tool_completion_is_rejected(self):
+        guard = helpers["_ocean_export_execution_error"]
+        error = guard(
+            "导出1998年1月4日的v10数据",
+            export_tool_completed=False,
+            tool_result_text="",
+            final_answer="正在向 Ocean 服务器提交，请稍后查询状态。",
+        )
+        self.assertIn("未实际执行", error)
+
+    def test_export_with_real_download_url_is_accepted(self):
+        guard = helpers["_ocean_export_execution_error"]
+        error = guard(
+            "导出1998年1月4日ERA5 v10数据",
+            export_tool_completed=True,
+            tool_result_text=(
+                '{"status":"ok","download_url":'
+                '"https://ocean.example/download/abc-123"}'
+            ),
+            final_answer="导出完成。",
+        )
+        self.assertEqual(error, "")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_fisheries_hf.py

@@ -0,0 +1,128 @@
+import csv
+import sys
+import tempfile
+import unittest
+import zipfile
+from pathlib import Path
+from unittest.mock import MagicMock
+
+sys.modules.setdefault("httpx", MagicMock())
+import fisheries_hf
+
+
+CSV_TEXT = """year,month,lon,lat,effort,flag
+2022,12,141,2,9,A
+2023,1,141,2,1.5,A
+2023,2,142,3,2.5,B
+2023,2,142,3,2.5,B
+2023,3,150,3,8,C
+"""
+
+
+class FisheriesHFTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+        fisheries_hf.EXPORT_ROOT = self.root / "exports"
+        fisheries_hf.EXPORT_ROOT.mkdir()
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def _check(self, path: Path):
+        result = fisheries_hf.analyze_and_export(
+            path,
+            dataset_path="current/test" + path.suffix,
+            revision="a" * 40,
+            repository="tuna",
+            year=2023,
+            lon_min=140,
+            lon_max=145,
+            lat_min=0,
+            lat_max=5,
+        )
+        self.assertEqual(result["status"], "ok")
+        self.assertEqual(
+            result["repository"],
+            "globalsquiddatabase/Tuna-Fisheries-Dataset",
+        )
+        self.assertEqual(result["scanned_row_count"], 5)
+        self.assertEqual(result["matched_row_count"], 3)
+        self.assertEqual(result["time_range"], {"min_year": 2023, "max_year": 2023})
+        self.assertEqual(result["exact_duplicate_count"], 1)
+        self.assertEqual(result["missing_values_by_column"]["effort"], 0)
+        self.assertEqual(result["monthly_record_counts"], [
+            {"month": 1, "record_count": 1},
+            {"month": 2, "record_count": 2},
+        ])
+        self.assertEqual(result["annual_summary"][0]["record_count"], 3)
+        self.assertAlmostEqual(result["annual_summary"][0]["sum_effort"], 6.5)
+        self.assertEqual(result["deduplicated_record_count"], 2)
+        self.assertEqual(
+            [item["kind"] for item in result["exports"]],
+            ["filtered_raw", "deduplicated", "annual_summary"],
+        )
+        self.assertEqual(len(result["download_urls"]), 3)
+        export = fisheries_hf.EXPORT_ROOT / result["token"] / result["filename"]
+        self.assertTrue(export.is_file())
+        with export.open(encoding="utf-8-sig", newline="") as stream:
+            rows = list(csv.DictReader(stream))
+        self.assertEqual(len(rows), 3)
+        for item in result["exports"]:
+            exported = fisheries_hf.EXPORT_ROOT / item["token"] / item["filename"]
+            self.assertTrue(exported.is_file())
+
+    def test_csv_filter_quality_and_export(self):
+        path = self.root / "sample.csv"
+        path.write_text(CSV_TEXT, encoding="utf-8")
+        self._check(path)
+
+    def test_zip_csv_member_filter_and_export(self):
+        path = self.root / "sample.zip"
+        with zipfile.ZipFile(path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+            archive.writestr("monthly_2023.csv", CSV_TEXT)
+        self._check(path)
+
+    def test_rejects_invalid_bbox(self):
+        path = self.root / "sample.csv"
+        path.write_text(CSV_TEXT, encoding="utf-8")
+        with self.assertRaisesRegex(ValueError, "lon_min"):
+            fisheries_hf.analyze_and_export(
+                path,
+                dataset_path="current/test.csv",
+                revision="a" * 40,
+                lon_min=181,
+            )
+
+    def test_repository_allowlist(self):
+        self.assertEqual(
+            fisheries_hf.normalize_repository("squid"),
+            "globalsquiddatabase/squid_dataset",
+        )
+        self.assertEqual(
+            fisheries_hf.normalize_repository("tuna"),
+            "globalsquiddatabase/Tuna-Fisheries-Dataset",
+        )
+        with self.assertRaisesRegex(ValueError, "repository"):
+            fisheries_hf.normalize_repository("someone/other-dataset")
+
+    def test_iccat_yearc_alias(self):
+        path = self.root / "iccat.csv"
+        path.write_text(
+            "YearC,effort\n2023,2\n2023,3\n2024,4\n",
+            encoding="utf-8",
+        )
+        result = fisheries_hf.analyze_and_export(
+            path,
+            dataset_path="ICCAT/processed/EFFDIS_LL2000-2024.csv",
+            revision="b" * 40,
+            repository="tuna",
+        )
+        self.assertEqual(result["time_range"], {"min_year": 2023, "max_year": 2024})
+        self.assertEqual(result["annual_summary"][0]["year"], 2023)
+        self.assertEqual(result["annual_summary"][0]["sum_effort"], 5.0)
+        self.assertEqual(len(result["exports"]), 3)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_followup_routing.py

@@ -0,0 +1,60 @@
+import ast
+import re
+import unittest
+from pathlib import Path
+
+
+def load_helpers():
+    source = Path(__file__).resolve().parents[1] / "ui_server.py"
+    tree = ast.parse(source.read_text(encoding="utf-8"))
+    names = {
+        "_is_confirmation_prompt",
+        "_is_ocean_export_request",
+        "_apply_ocean_export_defaults",
+    }
+    functions = [
+        node for node in tree.body
+        if isinstance(node, ast.FunctionDef) and node.name in names
+    ]
+    namespace = {
+        "re": re,
+        "_needs_ocean_mcp": lambda prompt: any(
+            term in str(prompt).lower()
+            for term in ("era5", "ocean", "sst", "cmems", "oisst")
+        ),
+    }
+    exec(
+        compile(ast.Module(body=functions, type_ignores=[]), str(source), "exec"),
+        namespace,
+    )
+    return namespace
+
+
+helpers = load_helpers()
+
+
+class FollowupRoutingTests(unittest.TestCase):
+    def test_short_confirmation_variants(self):
+        confirm = helpers["_is_confirmation_prompt"]
+        for value in ("确认", "好的", "继续", "OK", "yes"):
+            self.assertTrue(confirm(value))
+        self.assertFalse(confirm("确认一下ERA5数据范围"))
+
+    def test_missing_format_defaults_to_netcdf(self):
+        apply_defaults = helpers["_apply_ocean_export_defaults"]
+        prompt = "导出1998年1月4日ERA5 v10数据"
+        routed = apply_defaults(prompt)
+        self.assertIn("format=netcdf", routed)
+        self.assertIn("mcp_marine_marine_export", routed)
+
+    def test_explicit_format_is_preserved(self):
+        apply_defaults = helpers["_apply_ocean_export_defaults"]
+        prompt = "导出1998年1月4日ERA5 v10数据，格式csv"
+        routed = apply_defaults(prompt)
+        self.assertIn(prompt, routed)
+        self.assertNotIn("format=netcdf", routed)
+        self.assertIn("mcp_marine_marine_export", routed)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_marine_inventory_aliases.py

@@ -0,0 +1,85 @@
+import os
+import sys
+import types
+import unittest
+
+
+os.environ.setdefault("MARINE_API_URL", "http://example.invalid")
+
+if "httpx" not in sys.modules:
+    httpx = types.ModuleType("httpx")
+    httpx.Client = object
+    httpx.Timeout = object
+    sys.modules["httpx"] = httpx
+
+if "mcp.server.mcpserver" not in sys.modules:
+    mcp_package = types.ModuleType("mcp")
+    mcp_server_package = types.ModuleType("mcp.server")
+    mcp_server_module = types.ModuleType("mcp.server.mcpserver")
+
+    class MCPServer:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def tool(self):
+            return lambda function: function
+
+        def run(self):
+            pass
+
+    mcp_server_module.MCPServer = MCPServer
+    sys.modules["mcp"] = mcp_package
+    sys.modules["mcp.server"] = mcp_server_package
+    sys.modules["mcp.server.mcpserver"] = mcp_server_module
+
+import marine_mcp
+
+
+class FisheriesInventoryAliasTests(unittest.TestCase):
+    def setUp(self):
+        self.original_hf_files = marine_mcp._hf_files
+
+        def fake_hf_files(domain="all", force=False):
+            rows = [
+                {
+                    "type": "file",
+                    "path": "IATTC/sample.csv",
+                    "size": 120,
+                    "repository": marine_mcp.HF_TUNA_DATASET_REPO,
+                    "repository_domain": "tuna",
+                },
+                {
+                    "type": "file",
+                    "path": "current/sprfmo_effort.csv",
+                    "size": 80,
+                    "repository": marine_mcp.HF_SQUID_DATASET_REPO,
+                    "repository_domain": "squid",
+                },
+            ]
+            if domain in {"tuna", "squid"}:
+                rows = [x for x in rows if x["repository_domain"] == domain]
+            return rows, {}
+
+        marine_mcp._hf_files = fake_hf_files
+
+    def tearDown(self):
+        marine_mcp._hf_files = self.original_hf_files
+
+    def test_query_alias_becomes_keyword(self):
+        result = marine_mcp.fisheries_inventory(query="IATTC")
+        self.assertEqual(result["matched_file_count"], 1)
+        self.assertEqual(result["keyword"], "IATTC")
+
+    def test_source_alias_becomes_keyword(self):
+        result = marine_mcp.fisheries_inventory(source="IATTC")
+        self.assertEqual(result["matched_file_count"], 1)
+        self.assertEqual(result["keyword"], "IATTC")
+
+    def test_source_tuna_becomes_domain(self):
+        result = marine_mcp.fisheries_inventory(source="tuna")
+        self.assertEqual(result["domain"], "tuna")
+        self.assertEqual(result["matched_file_count"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_output_sanitizer.py

@@ -0,0 +1,42 @@
+import ast
+import re
+import unittest
+from pathlib import Path
+
+
+def load_sanitizer():
+    source = Path(__file__).resolve().parents[1] / "ui_server.py"
+    tree = ast.parse(source.read_text(encoding="utf-8"))
+    function = next(
+        node
+        for node in tree.body
+        if isinstance(node, ast.FunctionDef) and node.name == "_sanitize_final_answer"
+    )
+    namespace = {"re": re}
+    exec(compile(ast.Module(body=[function], type_ignores=[]), str(source), "exec"), namespace)
+    return namespace["_sanitize_final_answer"]
+
+
+sanitize = load_sanitizer()
+
+
+class OutputSanitizerTests(unittest.TestCase):
+    def test_rejects_literal_function_call_markup(self):
+        raw = '''我需要查询数据，让我调用工具。<function_calls>
+<invoke name="mcp_marine_fisheries_inventory">
+<parameter name="query">IATTC</parameter>
+</invoke>
+</function_calls>'''
+        self.assertEqual(sanitize(raw), "")
+
+    def test_keeps_final_answer_and_removes_trailing_markup(self):
+        raw = '''【FINAL】IATTC 数据已确认存在。
+<function_calls><invoke name="x"></invoke></function_calls>'''
+        self.assertEqual(sanitize(raw), "IATTC 数据已确认存在。")
+
+    def test_keeps_normal_answer(self):
+        self.assertEqual(sanitize("【FINAL】正常回答"), "正常回答")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_release_stability.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_version_is_single_source():
+    version = (ROOT / "VERSION").read_text(encoding="utf-8").strip()
+    ui = (ROOT / "ui_server.py").read_text(encoding="utf-8")
+    html = (ROOT / "app.html").read_text(encoding="utf-8")
+    assert version == "3.3.0"
+    assert 'with_name("VERSION")' in ui
+    assert "__APP_VERSION__" in html
+
+
+def test_single_frontend_template():
+    assert (ROOT / "app.html").exists()
+    assert not (ROOT / "templates" / "app.html").exists()
+    ui = (ROOT / "ui_server.py").read_text(encoding="utf-8")
+    assert 'with_name("app.html")' in ui
+    assert "templates/app.html" not in ui
+
+
+def test_hf_space_metadata_is_valid_shape():
+    readme = (ROOT / "README.md").read_text(encoding="utf-8")
+    assert readme.startswith("---\n")
+    meta_end = readme.find("\n---", 4)
+    assert meta_end > 0
+    meta = readme[4:meta_end]
+    assert "sdk: docker" in meta
+    assert "app_port: 7860" in meta