inspire-skill 5.1.3

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？

启智平台网页 qz.sii.edu.cn 是 Agent 日常实验链路里最慢的那一环——每次申请资源、新建 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 的代理方案都行
• 把平台网页上的常用操作都变成可复现、可串联、可自动化的命令链
• 从 SKILL.md 按需加载对应使用手册，理解调度语义、资源申请原则和验收点，不需要 Agent 在对话里反复解释平台语义

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

---

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

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

维度	InspireCode（Agent 装在 Inspire 实例里）	InspireSkill（Agent 装在本机）
Agent 生命周期	绑死在某一个 notebook 实例；实例回收 / 崩溃，对话与状态一起没	跑在本机 harness 里，与任何一个 Inspire 实例解耦
调度范围	只能操作它所在那一个实例的文件系统与运行时	一个 Agent 横跨多 workspace / notebook / HPC job / image，全平台统一编排
入口	必须打开 qz.sii.edu.cn 的实例终端	Agent 本来就在用的 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 只留本地
连接依赖	平台网页断 = Agent 断；aTrust 掉线对话就停	inspire CLI 直接操作平台；Agent 推理甚至可以完全离 SII 内网
自动化 / 可复现	对话历史锁在浏览器页面里	命令流可保存 / 回放；可读格式给 Agent 决策，结构化输出留给脚本消费

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

---

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

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

维度	Inspire-cli	qzcli_tool	InspireSkill
License / 分发	Proprietary, members-only · 源码渠道	无 LICENSE · 源码渠道	MIT · PyPI + curl | install.sh
零配置 SSH / 文件流转	需要 Agent 预配本地组件或容器公网	无统一远程执行抽象	零配置，ssh / exec / shell / scp 都直接按 notebook name 使用
平台能力覆盖	少量训练 / HPC 能力	部分 HPC + job 能力	notebook / job / HPC / Ray / Serving / Model / resources 全覆盖
事件 / 生命周期 / GPU 利用率查询	无	无	5 类 events + notebook/job/hpc/serving 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 文件	818 单元测试

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

---

快速上手

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

安装

前置：bash · curl · tar · Python 3.10+ · 已装 uv（推荐）或 pipx 任一。

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

安装、可选参数和安装后检查见 references/setup/install-and-config.md。

更新

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

升级旧版本和 installer 检测说明见 references/setup/install-and-config.md。

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

inspire account add <name>
inspire config show --compact
cd /path/to/your-repo
inspire init
inspire resources list --all --include-cpu

账号级 / 项目级配置分层、多账号和代理 setup 见 references/setup/install-and-config.md。

---

能力一览

📝 Notebook 统一入口 全链路命令化：create / list / status / start · stop / ssh connect / exec / shell / scp / install-deps / metrics / events / lifecycle。一次 notebook ssh connect <name> 建立连接，后续 exec / shell / scp / ... 都直接用 notebook name。任何镜像、任何计算组、有无公网都能直接使用远程执行和文件流转命令。	🚀 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 后台任务（平台名：分布式训练） 平台官方把 job 这一路叫"分布式训练" / distributed training；提交 job 时只要求 GPU 计算资源和启动命令，不强制程序必须是训练。inspire job 可用于一张卡、多卡、单节点、多节点等后台 GPU 任务 —— 分布式训练 / 批量推理 / 并发 worker pool 都走这里（hpc 对应 CPU Slurm）。提交统一使用 job create；需要跟日志时用 job logs --follow，健康度用 job metrics 看 GPU、显存、CPU、内存、I/O 和多 pod 负载是否同步。	📊 资源情报 resources list --all --include-cpu / resources nodes --all / resources specs — 三板斧定位哪个集群有空，支持透支式申请。
🗂 镜像管理 image list / detail / save / register / set-visibility / delete，创建 notebook、job、HPC、Ray 或 serving 时显式传 --image；hpc create --image-type 明确可见性。	🛰 模型部署 （Serving） inspire serving list / status / stop / configs / metrics —— 覆盖模型部署服务的列表、状态、可用配置、资源指标和停止操作；创建部署仍交给平台部署页面。
📦 模型注册表 （Model） inspire model list / status / versions —— 浏览 workspace 下所有模型 + 每个模型的历史版本，带 vLLM 兼容标记 / 创建时间；之前只能在平台网页里翻。	👤 身份 / 配额 / 权限 inspire user whoami / permissions / api-keys —— 一眼看清当前账号、在某 workspace 下实际授予的权限码（job.trainingJob.create 等），以及已申请的 API Key 元数据。
📈 指标、事件 & 生命周期 notebook metrics / job metrics / hpc metrics / serving metrics 读取平台 资源视图 的历史时间序列，默认输出 PNG 趋势图，--no-plot --sparkline 适合终端快速判断；job events / hpc events / notebook events / ray events 拉平台事件流，job instances / hpc instances / ray instances 看 live pod / component 清单，notebook lifecycle <name> 看一个实例的多次启停记录。	🗝 多账号（一账号一目录） inspire account add / list / use / current / remove —— 每个账号的 config.toml、SSH tunnel bridges 和登录缓存都在独立目录 ~/.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。日常 workspace 基本就是 CPU资源空间 和 分布式训练空间；资源条件不要写成隐式默认值，把 workspace、project、group、quota 和 image 组合成 workload profile，并在 inspire notebook/job/hpc/... create --profile <name> 或 batch 文件里显式使用。如果 Agent 的主战场是启智的国产卡分区、CI-情境智能 工作空间，或小组自己划走的专属资源开发空间，两条口子做定制：

1. 项目级（推荐）：改仓库根的 INSPIRE.md，并用 inspire <workload> profile set <name> ... 保存条件组；Path Conventions 只写 remote path alias。INSPIRE.md 属于当前 repo，不会被 inspire update 覆写，也方便跟组内协作。
2. Harness 级：直接编辑 ~/.claude/skills/inspire/SKILL.md 和同目录 references/（Codex / Gemini / OpenClaw / OpenCode 同理），改按需加载入口或对应使用手册。注意：inspire update 默认会覆盖 SKILL.md 和 references/；维护了本地改动后用 inspire update --cli-only 只升级 CLI 不动 skill 文件，想合并上游变更时再手动 diff。

---

🔧 维护承诺

启智平台的调度语义、资源组划分、镜像可用性会频繁变化。 InspireSkill 的维护目标是让 CLI 和使用手册始终贴近平台真实行为。

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

发现新的平台行为差异时，在 issue tracker 开一条，附 inspire --debug <cmd> 的 trace（CLI 会自动脱敏敏感登录凭据和代理信息）。反馈流程的更多细节见下方"开发与贡献"一节。

---

代理配置

不常驻 SII 的科研人员通常需要让本机代理同时转发公网和 *.sii.edu.cn 流量。仓库提供一份可选的 Clash Verge 7897 mixed-port 分流模板，见 references/setup/proxy-setup.md；但 CLI 本身不绑定 7897。代理地址通过 inspire account add 写入账号配置，并可用 inspire config show --compact 核对。

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

---

开发与贡献

项目由 @realZillionX 维护，节奏与启智平台的行为 / 调度语义紧密绑定。为了让上游变更能被最快、最一致地消化进 CLI + SKILL.md + references/，贡献入口按变更风险分层：

• 欢迎小而清楚的 PR。 文档修正、使用手册补丁、平台行为变化修复、可复现的小型 CLI bugfix 都可以直接提 PR；长期协作者（如 @JingYiJun）持续跟进平台变化，相关 PR 通过测试和基础 review 后可按快速通道合入。
• 大范围语义调整先提 Issue。 平台语义变化快，涉及工作流重写、配置边界、调度策略或多命令联动的改动，先用 Issue 描述问题场景，附上 inspire --debug <cmd> 的日志最好（CLI 会自动脱敏敏感登录凭据和代理信息）。维护者会评估后纳入后续版本，通常几天内发新版。
• 新的平台行为差异同样走 Issue；不用自己附敏感本地文件，维护者会用仓库内的开发工具复现。

这么安排的权衡：这个 skill 的价值在于与上游保持零漂移的同步。Issue 是最高效的问题信号，PR 是可落地 patch 的通道；能小步合并的就小步合并，需要统一调度的就先收敛语义再动手。

---

文档索引

• SKILL.md — 日常使用入口：CLI help 查询方式、按需加载索引和项目上下文字段。
• references/setup/install-and-config.md — 安装、更新、账号初始化和项目初始化。
• references/setup/proxy-setup.md — Clash Verge 7897 分流配置和账号级代理衔接。
• references/dev/openapi.md — CLI 维护参考：公开提交接口合约。
• references/dev/browser-api.md — CLI 维护参考：网页会话接口合约。
• references/resources-and-paths.md — 实时资源、规格三元组、共享盘作用域、存储池和项目路径。
• references/notebook.md — Notebook 创建、连接、远程执行、传文件和基底环境准备。
• references/notebook-service-proxy.md — Notebook 容器内 HTTP 服务的 proxy URL、SDK base URL 和安全边界。
• references/compute-workloads.md — GPU job、CPU HPC、Ray、serving 的适用边界、调度语义和示例。
• references/workflows.md — CPU 准备、数据处理、分布式训练三阶段项目流程。
• cli/ — CLI 源码；入口 cli/inspire/cli/main.py。
• scripts/install.sh — curl-pipe-bash 安装器。

---

License

MIT

Acknowledgements

• 启智平台团队提供的公开资料与协助。
• EmbodiedForge/Inspire-cli 提供了 CLI 的初步框架。

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