README.md

---
title: Global Marine Foundation Data Agent
emoji: 🌊
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
---

# Global Marine Foundation Data Agent

Current UI release: **v3.4.0**.


## v3.4.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.

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.

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.

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.

Custom chat UI backed by CodeWhale/DeepSeek and a restricted Marine MCP bridge.

Public UI: port 7860.
Private CodeWhale Runtime: 127.0.0.1:7878.
The Runtime token never enters the browser.

## Functional sidebar

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.

Read-only sidebar endpoints:

- `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=...`

Authenticated deployments validate the Supabase bearer token on every endpoint.
The task endpoint filters server-side by the resolved authenticated user id.


## 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.


## 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.


## v2.4.0 fisheries file workflow

- 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.


## 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.


## v2.5.0 favorites workflow

- 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.


## v2.6.0 task workflow

- “我的任务”升级为任务工作台：区分处理中、已完成、失败和数据资产。
- 任务支持详情抽屉、复制任务编号、导出 JSON、携带结构化结果继续对话分析。
- 后端任务摘要增加关联会话、上传文件和数据来源字段，便于追溯任务上下文。
- 数据资产支持详情、来源/文件类型展示、下载以及一键进入对话继续分析。
- 任务和资产均增加搜索筛选，保留 v2.5.0 收藏工作流和 v2.4.1 元数据审计逻辑。

## v2.7.0 service diagnostics

- 数据服务页面新增综合健康状态、健康检查计数、平均响应时延和慢响应统计。
- Marine API `/health`、`/domains`、`/status/ocean` 与 Hugging Face Fisheries 读取增加毫秒级响应耗时。
- 新增“服务诊断详情”抽屉，集中展示逐项状态、诊断建议与失败/慢响应项。
- 支持复制诊断摘要和导出诊断 JSON，便于部署排障和路演现场快速反馈。
- 保留 v2.6.0 任务工作台、v2.5.0 收藏工作流、v2.4.1 元数据审计与既有数据集按钮行为。


## v2.8.1 项目数据包

侧边栏新增“项目数据包”。输入研究/项目描述后，系统会基于当前已接入的 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` 中保留待补充的请求清单，避免伪造数据。

## v2.8.1 项目数据包

侧边栏新增“项目数据包”。输入研究/项目描述后，系统会基于当前已接入的 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` 中保留待补充的请求清单，避免伪造数据。


## v2.8.1
- 项目数据包侧边栏入口增加静态节点 + JavaScript 自愈注入双保险。
- 新增 `/api/ui/info` 用于确认实际运行模板、版本和项目数据包功能是否加载。
- 运行时统一以 `templates/app.html` 为唯一服务模板，根目录 `app.html` 仅保持镜像一致。


## v2.8.2 单一前端模板修复
- 运行时只读取仓库根目录 `app.html`，不再依赖 `templates/app.html`。
- 修复 Hugging Face 网页上传时根目录文件已更新、嵌套模板仍停留旧版导致“版本/功能不一致”的问题。
- 应用版本改为代码内固定 `2.8.2`，不再被 Space 中遗留的 `APP_VERSION=2.8.0` 变量覆盖。
- 保留项目数据包侧栏入口及其 ZIP 按数据库分类打包功能。

## v2.9.0 项目数据方案确认

“项目数据包”升级为两阶段工作流：先分析项目并生成推荐数据方案，再由用户勾选/取消具体 Ocean 与 Fisheries 数据源，最后只打包所选来源。界面会提示 Ocean 自动导出所缺的日期/海域条件；未补充时仍可生成 ZIP，并在 Ocean 目录保留可复现的数据请求清单。后端新增 `selected_ocean_keys` 与 `selected_fisheries_names`，确保 ZIP 内容与前端确认清单一致。

## v3.1.0 数据包预估与清单预览

“项目数据包”新增生成前预估：根据 Hugging Face 实时文件树计算所选 Fisheries 候选文件数量与已知大小，并按 Ocean / Tuna-Fisheries-Dataset / squid_dataset 汇总。Ocean NetCDF 因需实际导出，预估阶段明确标记为“大小未知”，避免伪造估算值。ZIP 生成完成后可直接查看已打包文件清单，再决定是否下载；完整来源与跳过原因仍写入 `manifest.json`。


## v3.2.0 用户消息快捷操作触发方式

- 设置中新增“用户问题快捷操作”，可选择左键单击或右键单击打开复制、重试、编辑文本。
- 默认保持左键单击，升级后不改变原有操作习惯。
- 右键模式只拦截用户消息气泡上的浏览器右键菜单，页面其他区域右键行为不变。