inspire-skill 4.0.0

CLI for the Inspire training platform: notebook lifecycle, distributed/HPC job submission, SSH tunneling, image and resource ops

让 AI Agent 直接在本地 CLI 里完成启智平台的全部操作。
_{Notebook · Job · HPC · Serving · Model · Resources — 一条命令皆能。}

---

为什么要有这个 Skill？

启智平台的 Web UI qz.sii.edu.cn 是你日常实验链路里最慢的那一环——每次申请资源、新建 notebook、开 SSH、同步代码都要反复点点点。

InspireSkill 把这些步骤交给你的 AI Agent。 当 Claude Code / Codex / Gemini CLI / OpenClaw / OpenCode 识别到这个 skill，它会：

• 直接调用 inspire 命令查实时资源、开 notebook、提 HPC 任务、拉日志
• 提供可选的 Clash Verge 7897 分流模板，让公网与启智内网共存一个本地端口，取代多人共用断连的 aTrust；CLI 本身不绑定 7897，任何能同时覆盖公网与 *.sii.edu.cn 的代理方案都行
• 把 Web UI 上所有操作都变成可复现、可串联、可自动化的命令链
• 从 SKILL.md 读到完整的调度约束、资源申请原则、排障 checklist，不需要你在对话里反复解释平台语义

目标是让你的 Claude Code / Codex / Gemini CLI / OpenClaw / OpenCode 成为推进科研项目的唯一入口，不用再在浏览器里手动点。

---

为什么比 InspireCode / 在实例里装 Agent 更好？

启智官方的 InspireCode 是把 OpenCode 直接部署到某个 Inspire 实例里——要用就得打开 qz.sii.edu.cn、进那个实例、在它的 Web 终端里跟 OpenCode 对话。凡是"把 Agent 装在服务器上"的方案都是这个路数。InspireSkill 走相反路径：Agent 留在你本机，Inspire 降格为被调用的工具。

维度	InspireCode（Agent 装在 Inspire 实例里）	InspireSkill（Agent 装在本机）
Agent 生命周期	绑死在某一个 notebook 实例；实例回收 / 崩溃，对话与状态一起没	跑在本机 harness 里，与任何一个 Inspire 实例解耦
调度范围	只能操作它所在那一个实例的文件系统与运行时	一个 Agent 横跨多 workspace / notebook / HPC job / image，全平台统一编排
入口	必须打开 qz.sii.edu.cn 的 Web 终端	你本来就在用的 Claude Code / Codex / Gemini CLI / OpenClaw / OpenCode
harness / 模型选择	锁定 OpenCode + 它支持的模型	任选本机已装的 5 家 harness，模型随 harness
上下文来源	只有实例里能看到的东西；你本地代码仓库不在场	本机完整 repo + git 状态 + 编辑器 + 其他 MCP 工具（Figma / Preview / Playwright …）一起可用
计算占用	Agent 进程吃 Inspire 实例的 CPU / RAM 配额；API key 必须放在实例里	Agent 进程跑本机；Inspire 实例的 CPU / RAM 全给训练 / HPC；API key 只留本地
连接依赖	Web UI 断 = Agent 断；aTrust 掉线对话就停	inspire CLI 直打平台 API；Agent 推理甚至可以完全离 SII 内网
自动化 / 可复现	对话历史锁在浏览器 session 里	命令流可保存 / 回放；inspire --json ... 被其他脚本直接消费

一句话：InspireCode 把你搬进 Inspire，InspireSkill 把 Inspire 变成 Agent 的一把工具。

---

为什么比社区里其它启智 CLI 更值得用？

启智社区还有两条独立维护的 CLI：EmbodiedForge/Inspire-cli 和 tianyilt/qzcli_tool。差异主要在底层覆盖广度——能不能在离线训练空间零配置 SSH、能不能拿到事件 / 生命周期 / GPU 利用率这些 OpenAPI 不暴露的观测信号、能不能端到端编排 notebook + HPC + Ray + serving。

维度	Inspire-cli	qzcli_tool	InspireSkill
License / 分发	Proprietary, members-only · git+uv only	无 LICENSE · git clone only	MIT · PyPI + curl | install.sh
不联网 SSH bootstrap	五路 fallback，需要用户预配 [ssh].rtunnel_bin / sshd_deb_dir 或容器有公网	无 SSH/tunnel 抽象	零配置，kit 在 /inspire/hdd/global_public/ 上，所有用户共享
平台 API 覆盖	10 个 endpoint	13 个 endpoint	31 个 endpoint
事件 / 生命周期 / GPU 利用率查询	无	无	5 类 events + 4 类资源 metrics + run_index 生命周期
HPC / Ray / Serving / Model	仅有部分 job + notebook	仅 HPC（单层）+ job	HPC 两层模型 + Ray 弹性 + Serving + Model 全覆盖
多账号	[accounts."<user>"] 合并层	单账号	一账号一独立目录，~/.inspire/current 切换
Agent 接入	无	qzcli-mcp（1 家 harness）	Skill 格式覆盖 5 家 harness
测试	53 文件	3 文件	767 单元测试

一句话：这两条 CLI 各做了一段路；InspireSkill 把整个平台的操作面和观测面端到端铺平了，并且在离线场景下零配置可用。

---

快速上手

平台支持：macOS + Linux 一等公民。Windows 用户请用 WSL2——CLI 依赖 SSH / rsync / GPFS 目录约定 / POSIX 文件权限，Windows 原生不在 roadmap。

安装

前置：bash · curl · tar · Python 3.10+ · 已装 uv（推荐）或 pipx 任一。两个都没装就先装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

然后一行装好 InspireSkill：

curl -fsSL https://raw.githubusercontent.com/realZillionX/InspireSkill/main/scripts/install.sh | bash

不需要把仓库克隆到本地。 脚本会做这几件事：

1. 从 PyPI 用 uv tool install / pipx install 拉 inspire-skill 进隔离 venv，inspire 落到 ~/.local/bin/inspire。
2. 自动确保 ~/.local/bin 在 PATH 上（若不在，自动跑 uv tool update-shell / pipx ensurepath 改 shell rc；然后提示你 exec $SHELL 或开新终端生效）。
3. 自动探测本机 harness（Claude Code / Codex / Gemini CLI / OpenClaw / OpenCode），把 SKILL.md 与 references/ 拷贝到对应 skills 目录；Codex 额外生成 agents/openai.yaml。
4. macOS 上挂一个每日静默版本检查的 launchd agent（代理变量从你当前 shell 读取，没有就不设）。

--ref 可以钉到 branch / tag / SHA 任一种（走 git 而不是 PyPI）：

curl -fsSL .../install.sh | bash -s -- --harness claude             # 只装一家 harness
curl -fsSL .../install.sh | bash -s -- --harness claude,codex       # 多家
curl -fsSL .../install.sh | bash -s -- --no-cli                     # 仅刷 SKILL / references，不动 CLI
curl -fsSL .../install.sh | bash -s -- --no-schedule                # 不挂后台检查 agent
curl -fsSL .../install.sh | bash -s -- --ref v3.0.3                 # 钉到 tag
curl -fsSL .../install.sh | bash -s -- --ref my-feature-branch      # 或 branch
curl -fsSL .../install.sh | bash -s -- --ref 4b7423a                # 或 SHA

常见问题：

• 装完后 inspire: command not found → 安装脚本会自动把 ~/.local/bin 加到你的 shell rc，但当前 shell 还没重新加载。运行 exec $SHELL 或开新终端。
• installer failed / 镜像超时 → 中国大陆走清华镜像快很多：UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple curl ... | bash。
• 同一台机已经装过 / 想换 installer → 直接重跑 curl ... | bash 即可，脚本是幂等的；若之前用 pipx 装过、现在 uv 也装了，会自动清掉旧的 pipx 副本以避免 ~/.local/bin/inspire shim 冲突。

更新

inspire update                # CLI 包 + SKILL/references 一起升到最新
inspire update --check        # 只检查，不动
inspire update --cli-only     # 仅升 Python 包
inspire update --skill-only   # 仅刷 SKILL.md / references/

inspire update 会自动识别你这套是 uv tool 还是 pipx 装的并调用对应升级命令。首次升级到 v3.0.3+ 之后所有后续 patch 都直接 inspire update 即可；再也不用重跑 install.sh。

如果 inspire update 反馈 "this build isn't managed by uv tool / pipx"（几乎不应该发生 —— v3.0.3 已修），它会同时打印你这套是怎么装的 + 三条具体的修复路径。

从 v3.0.3 之前的版本升级（v1.x / v2.x / v3.0.0–v3.0.2）

v3.0.2 之前 inspire update 在 uv tool 装的环境上会因为 detector bug 拒绝自动升级，v3.0.3 之前 install.sh 在 --ref v<tag> 时会 404，这两段代码本身在你机器上就是坏的 —— 修好的版本得另外灌进来一次。两条路任选：

最简单：重跑 install.sh（等价于「原地强制覆盖」）：

curl -fsSL https://raw.githubusercontent.com/realZillionX/InspireSkill/main/scripts/install.sh | bash

脚本对 uv tool install / pipx install 都加了 --force，会直接覆盖旧版本不需要先卸载。SKILL.md 和 references/ 也会一并刷成最新。

或者直接调底层包管理器（如果你清楚自己是哪套）：

# uv tool 用户：
uv tool upgrade inspire-skill

# pipx 用户：
pipx upgrade inspire-skill

# 其它 venv / pip install -e 用户：
pip install -U inspire-skill

落到 v3.0.3 之后 inspire update 就能正常自动升所有未来 patch 了，这个迁移每台机器只需要做一次。

完整初始化（安装后必跑）

分两段—— 先配账号（一次），再进每个仓库配项目（每个仓库一次）：

① 账号级（和仓库无关，任意目录跑；完成后该账号可用于所有仓库）

# 建账号目录。沿途问：平台 username（默认=<name>）/ password（二次确认）/
# base URL（默认 https://qz.sii.edu.cn）/ 代理（有提示典型值）/ 是否设为活动账号。
# 想跳过交互：加 --non-interactive 并把所有字段都用 flag 给齐。
inspire account add <name>

# 核对账号配置生效
inspire config show --compact

结果写入 ~/.inspire/accounts/<name>/config.toml，包含身份（username / password）、base_url、代理等。不包含 target_dir——那是项目级的，下一步解决。

② 项目级（每个本地仓库各做一次）

cd /path/to/your-repo

# 登录平台、发现可用项目 + workspace + compute group，选当前仓库的：
# - 绑定的 Inspire 项目
# - 远端存储池（hdd / ssd / qb-ilm / qb-ilm2）→ 写入 target_dir
# 结果分两处：
#   - 账号级发现结果（workspace alias 表、compute groups）→ ~/.inspire/accounts/<name>/config.toml
#   - 本仓库的 [context] + [paths].target_dir → ./.inspire/config.toml
inspire init --discover

# 看实时空余（GPU / CPU），确认平台能连通
inspire resources list --all --include-cpu

为什么分两段：target_dir 是"远端工作目录"，每个仓库都不同，必须在仓库里跑 init --discover 才能把它落到该仓库的 .inspire/config.toml。CLI 会直接拒绝账号 config.toml 里出现 [paths]——避免把项目级状态错放到账号层（不同仓库默默相互污染）。

多账号：inspire account add <name2> 再加一个，inspire account use <name> 切换。

之后把控制权交给 Agent，它会从 SKILL.md 读到所有 workflow 规则并自动执行。

---

能力一览

📝 Notebook 统一入口 全链路命令化：create / list / status / start · stop / ssh / exec / shell / scp / refresh / forget / test / connections / install-deps / top / metrics / events / lifecycle。一次 notebook ssh <name> 就把 SSH 通路在本地缓存好，后续 exec / shell / scp / ... 都直接用 notebook name。任何镜像、任何计算组、有无公网都能直接 ssh —— rtunnel 从平台预置的 global_public 离线 kit 直接 exec（GPFS zero-copy），sshd 缺失时从 kit 的 .deb 自动 dpkg 装上，镜像里不需要预装。	🚀 HPC 任务分派 inspire hpc create -c <slurm-body> 只写 Slurm 正文 + 显式 srun，平台自动补 #SBATCH 头。两层独立：节点规格用 --quota gpu,cpu,mem（CLI 自动解析到平台 spec），slurm 调度用 --number-of-tasks / --cpus-per-task / --memory-per-cpu。
🏃 GPU 多节点任务（不止训练） inspire job 覆盖所有 GPU 多节点场景 —— 分布式训练 / 批量推理 / 并发 worker pool 全走这里（`hpc` 对应 CPU Slurm）。inspire run "<cmd>" --watch 自动选资源组 + 跟 job logs --follow；精细控制优先级 / 节点数用 job create。	📊 资源情报 resources list --all --include-cpu / resources nodes --all / resources specs — 三板斧定位哪个集群有空，支持透支式申请。
🗂 镜像管理 image save / register / list / set-default，默认镜像自动写回项目 .inspire/config.toml；hpc create --image-type 明确可见性。	🛰 模型部署 （Serving） inspire serving list / status / stop / configs —— 观测 + 止损分层：list / configs 走 Browser API，status / stop 走 OpenAPI，和 job / hpc 同构。
📦 模型注册表 （Model） inspire model list / status / versions —— 浏览 workspace 下所有模型 + 每个模型的历史版本，带 vLLM 兼容标记 / 创建时间；之前只能在 Web UI 翻。	👤 身份 / 配额 / 权限 inspire user whoami / permissions / api-keys —— 一眼看清当前账号、在某 workspace 下实际授予的权限码（job.trainingJob.create 等），以及已申请的 API Key 元数据。
📅 事件 & 生命周期 inspire job events / hpc events / notebook events / ray events 拉平台事件流；notebook lifecycle <name> 看一个实例的多次启停记录 —— 原本要翻 Web UI "详情 → 事件/生命周期"两个 tab 才看得全。	🗝 多账号（一账号一目录） inspire account add / list / use / current / remove / migrate —— 每个账号的 config.toml、SSH tunnel bridges、SSO session cache 都在独立目录 ~/.inspire/accounts/<name>/，活动账号由 ~/.inspire/current 一行决定。不再有 [accounts."<user>"] 合并层、不再有多个环境变量的优先级链；切账号 = 改一个文件。

---

支持的 Agent Harness

Harness	安装后位置	备注
Claude Code	~/.claude/skills/inspire/	默认推荐 —— Agent 可被后台命令完成事件自动唤醒
Codex CLI	~/.codex/skills/inspire/	额外生成 agents/openai.yaml
Gemini CLI	~/.gemini/skills/inspire/
OpenClaw	~/.openclaw/skills/inspire/	全局 "managed skills" 层；workspace 层 （~/.openclaw/workspace/skills/） 可覆盖
OpenCode	~/.config/opencode/skills/inspire/	遵循 XDG；$OPENCODE_CONFIG_DIR 可改根

为什么默认推 Claude Code：它的 scheduler 支持在后台 Bash 命令结束时自动唤醒 Agent。把 inspire job logs --follow <name> / 长轮询 checkpoint / inspire hpc status <name> 监视之类长 watch 挂到后台，训练或 HPC 任务跑完 Agent 自己醒过来接下一步 —— 不用你守在终端。Codex / Gemini CLI / OpenClaw / OpenCode 目前没有这个能力，做长流水的自动化会弱一档。

---

自定义 SKILL.md / INSPIRE.md

SKILL.md 装完是一份通用默认 playbook，默认口径是主力跑 分布式训练空间 下的 H100 / H200。如果你的主战场不在这儿（比如启智的国产卡 workspace CI-情境智能-国产卡 / CI-情境智能-国产卡-ssd3，或小组自己划走的专属资源开发空间），两条口子做定制：

1. 项目级（推荐）：改仓库根的 INSPIRE.md —— Path Conventions 换 remote workspace 路径，Existing Notebooks / Ongoing Jobs 里显式写国产卡机型和任务。INSPIRE.md 属于你的 repo，不会被 inspire update 覆写，也方便跟组内协作。SKILL.md §1 "项目叙述上下文" 一行详述约定。
2. Harness 级：直接编辑 ~/.claude/skills/inspire/SKILL.md（Codex / Gemini / OpenClaw / OpenCode 同理），改资源申请段落、默认镜像、常用 workspace 名。注意：inspire update 默认会覆盖 SKILL.md；维护了本地改动后用 inspire update --cli-only 只升级 CLI 不动 skill 文件，想合并上游变更时再手动 diff。

---

🔧 维护承诺

启智平台的调度语义、资源组划分、镜像可用性会频繁变化。 一旦平台侧改了而 Skill / CLI 没跟进，Agent 就会按失效的路径执行，产生错误结果。

维护者 @realZillionX 会高频率、持续跟进上游变更。每次发版后,任意 inspire <subcommand> 都会在 stderr 提醒一行,跑 inspire update 即升(用法见上面 更新 段)。

平台侧行为突变又未及时 patch 时，在 issue tracker 开一条，附 inspire --debug <cmd> 的 trace（CLI 会自动脱敏 token / cookie / proxy secrets）。反馈流程的更多细节见下方"开发与贡献"一节。

---

代理配置

不常驻 SII 的科研人员通常需要让本机代理同时转发公网和 *.sii.edu.cn 流量。仓库提供一份可选的 Clash Verge 7897 mixed-port 分流模板，见 references/proxy-setup.md；但 CLI 本身不绑定 7897，你也可以换成任意代理方案，只要 config.toml / 环境变量里的 proxy 字段指向一个能同时访问公网与 *.sii.edu.cn 的本地端口。

凭据（host / user / password）从实验室或组织管理员获取，不要提交到任何公开仓库或聊天记录。

---

开发与贡献

项目由 @realZillionX 维护，节奏与启智平台的接口 / 调度语义紧密绑定。为了让上游变更能被最快、最一致地消化进 CLI + SKILL.md + references/，合作方式有意简化：

• 不建议提 PR。 平台语义变化快（端点下线 / body schema 改名 / 权限矩阵重排），外部 PR 从提交到 review 完成的窗口里，仓库这边的 CLI / SKILL.md 往往已经跟着上游动了——合并时容易语义错位。维护者更倾向于亲自 implement 并控制上游同步节奏。
• 请提 Issue。 Bug / 端点失效 / SKILL.md 里某条规则不再适用 / CLI UX 想改进 / 新观察到的 Browser API 端点——任何想反馈的都用 Issue 描述问题场景，附上 inspire --debug <cmd> 的日志最好（CLI 自动脱敏 token / cookie）。维护者会评估后纳入后续版本，通常几天内发新版。
• 反向抓包的新发现（某端点 404 了、某字段改名了、冒出一个前端在打但 CLI 没封装的路径）同样走 Issue；不用自己附 Playwright storage_state / JSONL，维护者会用 cli/scripts/reverse_capture/ 自己复现。

这么安排的底层权衡：这个 skill 的价值在于与上游保持零漂移的同步，比起零散 PR 稳步合入，维护者按批次自己写更容易做到这点。你提的 Issue 是最高效的信号。

---

文档索引

• SKILL.md — Agent 看的主规约：认证链路、命令速查、HPC Slurm 语义、开发主流程三阶段。
• references/openapi.md — /openapi/v1 公开合约（10 条端点：train_job / hpc_jobs / inference_servings 的 create/detail/stop + cluster_nodes/list；CLI 都已封装，inference_servings 由 inspire serving 暴露）。
• references/browser-api.md — /api/v1 前端 SSO API（列表 / 事件 / 模型注册表 / 部署管理 / 用户权限 / 配额 …… 观测性几乎全在这里，OpenAPI 上没有）。
• references/proxy-setup.md — Clash Verge 7897 分流配置。
• references/troubleshooting.md — SSH bootstrap / rtunnel / HPC 异常状态对照 / 镜像保存等排障 checklist。
• references/less-used-commands.md — 不在主速查表里但 CLI 已封装的命令：serving / model / project detail|owners / user quota|api-keys。
• cli/ — CLI 源码；入口 cli/inspire/cli/main.py。
• scripts/install.sh — 面向用户的 curl-pipe-bash 安装器。

---

License

MIT

Acknowledgements

• 启智平台团队提供的 OpenAPI / Web 接口。
• EmbodiedForge/Inspire-cli 提供了 CLI 的初步框架。

_{Made for researchers who'd rather think than click.}