clt — 一行命令在哈佛 FASRC 集群上运行 COMSOL 作业

从你的 Mac 上一行命令在集群上运行 COMSOL 批处理作业：

cluster file3.mph

（Touch ID 提示 →）从 Windows 机器上抓取 file3.mph，用你的密码 + 自动生成的 2FA 码登录 FASRC，上传文件，提交一个异步 Slurm 作业，然后返回一个作业 ID。稍后：

cluster status          # queue overview
cluster logs            # tail the COMSOL batch log of the latest job
cluster fetch           # download out.mph + batch.log when it's done
cluster shell           # drop into an interactive shell (no re-login)
cluster code            # print the current 2FA code, e.g. for a manual login

一切只是一个无依赖的 Node 脚本（cluster.js）加上 macOS 内置工具：ssh、scp、expect、security（钥匙串）。没有 npm 包。

工作原理

Mac (cluster.js)
 ├─ Touch ID gate            (optional tiny Swift helper, compiled once)
 ├─ Keychain                 → FASRC password + TOTP seed
 ├─ TOTP in Node crypto      → the same 6-digit codes as the OpenAuth Java app
 ├─ ssh ControlMaster        → authenticate ONCE, reuse the session ~8h,
 │                             so scp/ssh/sbatch below run with zero prompts
 ├─ scp  winbox → Mac        (over an AnyDesk TCP tunnel or LAN, key auth)
 ├─ scp  Mac → cluster       (over the shared session)
 └─ ssh  sbatch              → COMSOL batch job runs asynchronously on Slurm

关键洞察是 FASRC 的“Java 2FA 应用”（OpenAuth/JAuth）就是普通的 TOTP——与 Google Authenticator 相同的算法。一旦你有了它的 base32 种子，约 15 行 Node crypto 就能生成有效的验证码，而 expect 会在当天的首次登录中自动输入密码和验证码到 ssh 提示。ControlMaster 保持该会话存活，因此其他操作永远不会再提示。

一次性设置

0. 前提条件

• macOS，Node ≥ 18（brew install node 或 nodejs.org）

• 一个启用了 OpenAuth 2FA 的 FASRC 账户

• 可选 Touch ID 门控：Xcode 命令行工具（xcode-select --install）

1. 安装命令

cd clt
npm link          # or: alias cluster="node /path/to/clt/cluster.js" in ~/.zshrc

可选的 Touch ID 门控（跳过的话脚本根本不会提示）：

swiftc -O touchid.swift -o touchid

2. ssh 配置（必需）

添加到 ~/.ssh/config（如果需要则创建），并 mkdir -p ~/.ssh/sockets：

Host fasrc
  HostName login.rc.fas.harvard.edu
  User YOUR_FASRC_USERNAME
  ControlMaster auto
  ControlPath ~/.ssh/sockets/%r@%h-%p
  ControlPersist 8h
  ServerAliveInterval 60

Host winbox
  HostName 127.0.0.1        # via the AnyDesk TCP tunnel; or the LAN IP of the PC
  Port 2222                 # the tunnel's local port (drop this line if using LAN IP)
  User YOUR_WINDOWS_USERNAME

ControlMaster 块是让一切变快的关键——没有它，每次 scp/ssh 都会要求新的密码 + OTP，工具会拒绝运行。

3. 获取你的 OpenAuth TOTP 种子

OpenAuth Java 应用使用一个 base32 密钥作为种子。两种方法获取：

• 登录 FASRC OpenAuth 自助服务页面，重新配置你的令牌。除了 Java 应用下载，它还提供 QR 码/密钥，用于手机验证器应用——复制那个 base32 字符串。

• 或者查看你已下载的 OpenAuth 包：种子存储在 jar 旁边的应用配置文件中。

注意：如果你重新配置，旧的 Java 应用的验证码会失效——新种子就是唯一的真种子（使用 cluster code 作为生成器，或者也加载到手机应用中）。

4. Windows 机器：内置 OpenSSH 服务器

AnyDesk 本身没有可脚本化的文件传输，所以我们用 scp 从 Windows 的内置 OpenSSH 服务器（Windows 10/11 可选功能——无需第三方软件）拉取文件。在 Windows 机器的管理员 PowerShell 中：

Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic

然后安装你的 Mac 公钥，这样 scp 就不需要密码（在 Mac 上 cat ~/.ssh/id_ed25519.pub；如果你没有，先 ssh-keygen -t ed25519）。陷阱： 如果你的 Windows 账户是管理员，密钥放在一个特殊文件中：

Add-Content -Path C:\ProgramData\ssh\administrators_authorized_keys -Value "ssh-ed25519 AAAA...your key..."
icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"

（对于非管理员账户，是通常的 C:\Users\you\.ssh\authorized_keys。）

5. 从 Mac 访问 Windows

选择一种：

• AnyDesk TCP 隧道（与你当前工作流匹配）：在 Mac 上的 AnyDesk 中，打开 Windows PC 的会话设置 → TCP 隧道 → 本地端口 2222 → 远程 127.0.0.1:22。隧道仅在 AnyDesk 会话连接时存在——如果你已经在用 AnyDesk，这没问题。检查你的 AnyDesk 许可证是否包含 TCP 隧道。

• 同一网络 / VPN： 在 winbox 块中将 HostName 设置为 PC 的 IP，并删除 Port 2222 行。如果实验室机器共享网络，这是最简单的。

• 完全跳过 Windows： 将 COMSOL 文件夹放入 OneDrive（哈佛提供），让它在 Mac 上同步——然后 cluster ~/OneDrive/.../file3.mph 使用本地副本，从不接触 PC。

测试：ssh winbox 应该无需密码提示就能登录 PC。

6. 存储密钥并配置

cluster setup

提示输入主机别名、Slurm 默认值、你的 FASRC 密码和 TOTP 种子。密钥存储在 macOS 钥匙串中（永远不在磁盘上，永远不在这个仓库中）。设置结束时打印一个生成的 2FA 码——在信任它之前，验证它与 Java 应用显示的是否一致。

然后在集群上确认一次（通过 cluster shell）：

• module avail comsol——在 ~/.config/clt/config.json 中设置确切的模块名

• 你的组有 COMSOL 许可证席位，并为你的实验室选择正确的分区

用法

cluster file3.mph                    # fetch from Windows, upload, submit
cluster ./local/file3.mph            # a file that exists locally skips the Windows fetch
cluster file3.mph -study std2        # extra args are passed to `comsol batch`
cluster status                       # your whole queue
cluster status 12345678              # one job, incl. finished (sacct)
cluster logs file3                   # tail batch.log
cluster fetch file3                  # → ./file3-out.mph + ./file3-batch.log

作业文件放在集群上的 ~/comsol_jobs/<名称>-<时间戳>/ 中（in.mph、out.mph、batch.log、slurm-<id>.log）。在 cluster setup 中设置一个邮箱，以便作业完成时收到消息。已提交作业的记账信息保存在 ~/.config/clt/jobs.json 中。

MCP 服务器（AI 驱动的 COMSOL）

mcp/server.mjs 将整个流水线暴露为 MCP 工具，因此 Claude（或任何 MCP 客户端）可以端到端运行 COMSOL：run_code（生成的 Java = 完整的 COMSOL API）、run_model、job_status、job_log、wait_for_job、fetch_artifacts、cancel_job、lab_fairshare。通过 .mcp.json 在项目范围内注册——在此仓库中打开一个 Claude Code 会话，工具即可使用。

服务器中强制执行安全措施（最多 4 个并发作业，≤16 个 CPU，≤64 GB，≤48 小时，允许的分区），并且 lab_fairshare 返回一个 healthy 标志，AI 被指示尊重它。使用 node mcp/smoke.mjs 验证一切——它通过工具运行一个 hello-world 模型，并检查物理结果与解析解是否一致。模型构建习惯用法和已知的 COMSOL API 陷阱在 references/ 中。

为实验室成员分叉

仓库包含零个人数据：配置在 ~/.config/clt/ 中，密钥在每个用户的钥匙串中。实验室成员只需克隆、运行 npm link、添加两个 ssh 配置块，然后使用自己的凭据运行 cluster setup。永远不要分享你的 TOTP 种子，也不要将其提交到任何地方。

新克隆的快速入门：

git clone <this repo> && cd clt
npm install          # MCP server deps (the CLI itself needs none)
npm link             # provides the `cluster` command
swiftc -O touchid.swift -o touchid    # optional Touch ID gate
cluster setup        # host aliases, Slurm defaults, secrets -> Keychain
cluster login        # verify; then `cluster help`

将研究数据保留在仓库外

references/lab/ 被 gitignore 忽略，它是 COMSOL 模型导出的存放位置。导出会嵌入未发表的几何和物理，以及包含真实姓名的绝对路径，因此绝不能发布。references/ 中跟踪的文件是通用的、可发布的示例（HelloBox、SweepBox、Inspect）加上 CONVENTIONS.md，即积累的、使生成模型工作的 COMSOL API 知识。在推送前，检查 git status 是否有多余的 .mph、.java 导出或结果 CSV。

安全说明，实话实说

• 将 TOTP 种子与密码存储在同一个 Mac 上，将 2FA 降级为“拥有你解锁的 Mac”。这可以防止远程凭据窃取，但无法防止有人在你键盘前。保持 FileVault 开启。

• Touch ID 门控只是此脚本的便利锁，不是加密——密钥由钥匙串保护。要强制每次读取密钥时显示 macOS 确认对话框，请使用无信任应用重新创建项目：security add-generic-password -U -T "" -a $USER -s clt-cluster-password -w

• 检查自动化你自己的 OTP 是否符合 FASRC 的可接受使用政策；这是个人便利自动化，种子必须保持个人化。

故障排除

• login failed——手动运行 ssh fasrc 查看实际提示，并比较 cluster code 与 Java 应用。如果你的 Mac 时钟不准，TOTP 码会错误（系统设置 → 通用 → 日期与时间 → 自动设置）。

• no ControlMaster socket——Host fasrc 块中缺少 ControlMaster 行，或者 ~/.ssh/sockets 不存在。

• Windows 获取失败——AnyDesk 会话（和隧道）是否已连接？ssh winbox 是否工作？不支持 .mph 文件名中的空格——请重命名。

• 作业立即死亡——cluster logs 通常显示许可证或模块错误；验证模块名和你组的 COMSOL 许可证。