Metadata-Version: 2.4
Name: ww3tool
Version: 0.1.1
Summary: WW3Tool - WAVEWATCH III workflow toolkit (CLI / Shell REPL / Desktop GUI / MCP server)
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: netCDF4
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: cartopy
Requires-Dist: Pillow
Requires-Dist: scipy
Requires-Dist: scikit-image
Requires-Dist: opencv-python
Requires-Dist: paramiko
Requires-Dist: requests
Requires-Dist: PyYAML
Requires-Dist: pyfiglet
Provides-Extra: gui
Requires-Dist: PyQt6; extra == "gui"
Requires-Dist: PyQt6-WebEngine; extra == "gui"
Requires-Dist: PyQt6-Fluent-Widgets; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

# WW3Tool 封装指南

把 WW3Tool 封装成多种形态，让日常使用和 AI 客户端调用都像 `mysql` / `git`
一样简单：

| 形态 | 入口 | 适合谁 |
| --- | --- | --- |
| CLI 全局命令 | `ww3tool`（安装后任意目录可用） | 人（终端）与脚本 |
| MCP server | 34 个 `ww3tool_*` tools + `list_commands`（stdio） | Claude / Cursor 等 AI 客户端 |

所有形态都复用仓库根的 `run.py` 统一入口，venv 引导、依赖检查、语言切换
完全一致，**不需要改动任何现有代码**（打包形态下仅需 `WW3TOOL_ROOT` 指向资源）。

---

## 一、安装方式

### 1. 一键脚本（推荐给其他人）

macOS / Linux（bash）：

```bash
curl -fsSL https://raw.githubusercontent.com/ZxyGch/WW3Tool/master/public/packaging/remote-install.sh | bash
```

Windows（PowerShell 5.1+ / PowerShell 7+）：

```powershell
irm https://raw.githubusercontent.com/ZxyGch/WW3Tool/master/public/packaging/install.ps1 | iex
```

自动完成：浅克隆仓库到 `~/.ww3tool`（Windows 为 `%USERPROFILE%\.ww3tool`）→
把 `ww3tool` 命令放入 PATH（优先 `~/.local/bin`，其次 `/usr/local/bin`；
Windows 上生成 `ww3tool.cmd` 包装器，调用 `python` 运行 `run.py`）→
首次运行自动建 venv 装依赖。
可覆盖：`WW3TOOL_REPO_URL`、`WW3TOOL_INSTALL_DIR`、`WW3TOOL_BIN_DIR`。

### 2. pip install（所有平台同一条指令）

```bash
pip install ww3tool
# 需要桌面 GUI 时：pip install "ww3tool[gui]"
# 尚未发布到 PyPI 时（直接装 GitHub 主干）：pip install git+https://github.com/ZxyGch/WW3Tool.git
```

安装后 `ww3tool` 命令直接可用。**wheel 自包含**：params.yml 模板、翻译
（public/languages）、namelist 模板（public/6.07_nml、7.14_nml）、网格生成器
（meshgen 瘦身子集）、依赖清单全部打进包，无需 clone 仓库、无需设置
`WW3TOOL_ROOT`。首次运行会自动建 venv 并安装依赖（需几分钟与网络）。

### 3. Homebrew

已发布 tap：`ZxyGch/homebrew-ww3tool`，直接使用：

```bash
brew tap ZxyGch/ww3tool && brew trust zxygch/ww3tool && brew install ww3tool
# 或一步到位（自动 tap，首次仍需 trust）：brew install ZxyGch/ww3tool
```

> Homebrew 6+ 对第三方 tap 默认不信任，首次使用需 `brew trust`（一次性）。

也可不发布直接本地装：`brew install ./public/packaging/Formula/ww3tool.rb`

formula 会把运行所需资源（meshgen / public / params.yml 模板）连同代码
一起装进 Cellar，命令链接到 `/opt/homebrew/bin/ww3tool`，**无需**
`WW3TOOL_ROOT`。巨型目录（`WW3/`、`WW3-6.07.1/`、`workSpace/`）不随包分发。

### 4. 已 clone 仓库的场景

```bash
./public/packaging/install.sh   # 把仓库内 public/packaging/ww3tool 软链到 PATH（可 --prefix 指定目录）
```

### 各方式对比

| 方式 | 命令 | 需 clone 仓库 | 资源(meshgen等) | WW3TOOL_ROOT |
| --- | --- | --- | --- | --- |
| **pip** | **一条指令，三平台相同** | 不需要 | 随包 | 不需要 |
| curl \| bash | 一条命令（macOS/Linux） | 自动（~/.ww3tool） | 随仓库 | 不需要 |
| irm \| iex | 一条命令（Windows） | 自动（~/.ww3tool） | 随仓库 | 不需要 |
| brew | tap + trust + install | 自动（Cellar） | 随包 | 不需要 |
| install.sh | 一条命令 | 已 clone | 随仓库 | 不需要 |

> **通用要求**：Python 3.9+（pip 方式随 Python 自带；curl/pip 方式使用系统
> `python3`；Windows 的 irm/iex 方式使用 `python` 或 `py -3`；brew 方式使用
> Homebrew 的 `python@3.12`）。首次运行会自动建 venv 装依赖，需几分钟与网络。

---

## 二、使用（CLI 命令）

```bash
ww3tool --help                          # 命令参考
ww3tool shell workdir/example           # 交互式 REPL
ww3tool workdir my_workdir              # 从模板创建工作目录
ww3tool run-workflow my_workdir         # 完整预处理
ww3tool validate my_workdir             # 校验配置
ww3tool local-run my_workdir            # 本地跑 WW3
ww3tool upload --confirm my_workdir     # 上传到远程
```

所有子命令与 `python3 run.py` 完全等价，从任何目录调用均可。

---

## 三、MCP server

把 CLI 子命令暴露为 MCP tools（工具名 `ww3tool_<子命令>`，如
`ww3tool_run_workflow`、`ww3tool_plot_wave_maps`）。工具与参数 schema
**运行时从 `build_parser()` 自动提取**，CLI 增加命令后 MCP 自动同步。
交互式命令 `ssh` 不通过 MCP 提供，仅 CLI 使用。

### 1. 初始化（新环境只需一次）

```bash
./public/packaging/mcp/setup.sh        # 创建 mcp/.venv（Python 3.12）并安装 mcp SDK
```

### 2. 通用 stdio 配置

任意支持 MCP 的客户端，注册一个 stdio server，`command` 指向
`launch.sh` 即可（内容见 `public/packaging/mcp/config.example.json`）：

```json
{
  "mcpServers": {
    "ww3tool": {
      "command": "/绝对路径/WW3Tool/public/packaging/mcp/launch.sh",
      "args": []
    }
  }
}
```

把 `/绝对路径/WW3Tool` 换成实际仓库路径。各客户端放置位置：

- **Claude Desktop**：`~/Library/Application Support/Claude/claude_desktop_config.json` 的 `mcpServers` 字段
- **Cursor**：项目根 `.cursor/mcp.json`（或用 `cursor mcp add` 命令添加）
- **VS Code / Copilot**、**Cherry Studio** 等：在各自的 MCP 设置里按同样格式添加

### 3. 工具清单（35 个）

- `list_commands`：列出全部命令及用途（帮助 LLM 选工具）
- `ww3tool_workdir / validate / config / print_params`：配置管理
- `ww3tool_prepare_forcing / generate_grid / prepare_ww3 / recommend_cfl /
  recommend_grid / run_workflow / local_run / merge_forcing`：预处理
- `ww3tool_plot_wave_maps / plot_spectrum / plot_jason3 / plot_jason3_swh /
  download_jason3 / plot_ndbc / download_ndbc`：后处理与绘图
- `ww3tool_connect_test / slurm_idle / confirm_slurm / upload /
  submit / check_status / queue_status / download_results / download_log /
  clear_remote / cancel_job / ntfy_watch / ntfy_watch_job / list_files`：远程运维
  （`ssh` 为交互式命令，仅 CLI 使用）

### 4. 使用约定（重要）

- **工作目录**：多数工具带 `workdir` 参数（含 `params.yml` 的目录）。
  建议总是显式传入；省略时使用 server 进程启动时的当前目录，结果不可预期。
- **退出码**：每个工具返回
  `[exit code N] --- stdout --- ... --- stderr --- ...`，
  LLM 应依据 `exit code` 判断成败（0 成功；1 运行异常；2 配置错误；
  3 破坏性操作缺 `--confirm`）。
- **破坏性操作**：`upload`、`clear_remote` 等工具保留了 CLI 的 `confirm`
  布尔参数，必须显式传 `True` 才会执行。
- **长任务**：`local_run`、`submit`、`download_results` 等可能运行很久。
  工具内建 1 小时超时（超时返回 exit code 124），客户端超时也请放宽
  （或改用 CLI 执行这类任务）。

### 5. 冒烟测试

```bash
public/packaging/mcp/.venv/bin/python public/packaging/mcp/tests/smoke_test.py
```

会真实走一遍 `initialize → tools/list → tools/call`（含创建一个临时
工作目录并执行 `ww3tool_config` / `ww3tool_validate`）。

---

## 四、发布清单（把"给其他人用"变成现实）

仓库已指向 https://github.com/ZxyGch/WW3Tool（默认分支 `master`），并已发布
`v0.1.0` tag；Homebrew tap（`ZxyGch/homebrew-ww3tool`）的 formula 已指向该 tag
并填入真实 `sha256`。**以后每次发版：**

1. **打 tag 并推送**（tag 是稳定锚点，日常 push 不影响已发布的 formula）：
   ```bash
   git tag v0.1.1 && git push origin v0.1.1
   curl -sL https://github.com/ZxyGch/WW3Tool/archive/refs/tags/v0.1.1.tar.gz | shasum -a 256
   ```
2. **更新 tap 仓库** `ZxyGch/homebrew-ww3tool` 的 `ww3tool.rb`：
   把 `url` 换成新 tag、`sha256` 换成新值，推送。
3. **发布到 PyPI**（让 `pip install ww3tool` 在**所有平台**可用）：
   ```bash
   python3 -m pip install --upgrade build twine
   python3 -m build            # 生成 dist/ww3tool-<ver>.tar.gz + .whl
   TWINE_USERNAME=__token__ TWINE_PASSWORD=<PyPI API token> \
     python3 -m twine upload dist/*
   ```
   > PyPI API token：https://pypi.org/manage/account/token/（先注册账号并验证邮箱）。
   > wheel 自包含运行资源（meshgen 瘦身子集 / public 子集 / params.yml），
   > 安装后无需 `WW3TOOL_ROOT`。上传前先在干净 venv 验证：
   > `python3 -m venv /tmp/t && /tmp/t/bin/pip install dist/ww3tool-*.whl && /tmp/t/bin/ww3tool --help`。

---

## 五、常见问题

- **`ww3tool` 提示 command not found**：确认安装目录在 PATH 中，
  或手动 `export PATH="$HOME/.local/bin:$PATH"`。
- **pip 安装后 `workdir` 报缺模板**：设置 `export WW3TOOL_ROOT=/path/to/WW3Tool`。
- **MCP 客户端连不上**：先跑冒烟测试确认 server 正常；再检查配置里的
  `command` 是否为**绝对路径**且 `launch.sh` 有执行权限。
- **MCP 调用报 `Dependency check failed`**：项目 `.venv` 依赖不全，
  用 `python3 run.py --help` 触发一次自动安装即可。
- **`pip install .` 生成 build/、*.egg-info/**：构建产物，已加入 `.gitignore`。
