InspireSkill

让 AI Agent 直接在本地 CLI 里完成启智平台的全部操作。

本项目建立的意义

在本项目开始筹办之初，对于所有 SII 的学生，启智平台是科研实验链路里最慢的那一环：每次申请资源、新建 Notebook、新建训练任务、同步代码都要反复点点点，SSH 等更进一步的功能更是遥遥无期。

本着过渡到大 Agent 时代、将一切重复性机械工作交给 Agent 的初衷，我们创办了 InspireSkill 项目，旨在将启智平台 GUI 打平为 CLI，并建立了 CLI + Skill 的一体化系统，让 InspireSkill 成为所有 Agent 开箱即用的工具、让你的 Codex / Claude Code / Cursor / OpenCode / ZCode / Kimi Code / Kimi Work / Qoder / Qoder Work / Antigravity / OpenClaw / Pi / DeepSeek Harness 成为进行科研工作的唯一入口。

建立和维护本项目的过程并非易事，InspireSkill 也并非只是将启智平台的网页 API 打平重构为 CLI 的简单工作，在维护本项目的过程中，设计高于平台语义的高层功能、寻找启智平台中细枝末节的 API 并将其优雅融入 CLI 系统中、尤其是维护一个易于 Agent 阅读且包含平台所有特性的文档系统都给我们带来了不小于 CLI 本身的麻烦。

在长时间的开发与维护中，以 @realZillionX 和 @JingYiJun 为首的开发团队始终秉持着注重细节与优雅的开发者精神，最终构建出一个令人满意的项目。时至今日，我们可以自豪地说：InspireSkill 所包含的功能，只有你想不到，没有我们做不到。它们包括但不限于：对 HDD / SSD / QB-ILM 等项目路径的优雅维护、翻转镜像的可见范围、将平台内部源入口交给 Agent（从而使在不可上网区配置镜像成为可能）、联网 Notebook 的 SSH 板块、受限 Notebook 的 JupyterTerminal 执行路径、空闲 8 卡整节点总量的查询、低优任务占用总量的查询、将 Notebook / 训练任务的资源视图 / 事件 / 聚合日志交给 Agent。

对初次使用者的简单介绍

InspireSkill 是启智平台的本地 Agent 工具套件。你可以继续在熟悉的 Codex、Claude Code、Cursor 等客户端中写代码、管 Git，同时让 Agent 直接通过命令行调度启智算力。项目包含三部分：

• inspire CLI：把资源查询、Notebook 连接、GPU Job / HPC / Ray 提交、Serving 部署、TensorBoard 曲线读取、镜像与模型管理整合为命令行工具。所有资源直接按名称和本地账号别名寻址，支持 --json 结构化输出。
• SKILL.md 与 references/：配套的 Agent 技能手册，涵盖工作负载选型、资源与配额查询、任务观察和结果验收流程。安装脚本会自动将其部署到本机已安装的 Agent 客户端中。
• Python SDK：随 inspire-skill 包一同安装的同步（InspireClient）与异步（InspireAsyncClient）Python 客户端，方便在脚本、评测流水线或后端服务中直接调用平台接口。

在对话中告诉 Agent 你的实验目标，它就可以自动查询可用 Workspace、配额与镜像，同步共享盘代码与数据，提交训练或处理任务，并通过事件、日志、监控指标和 TensorBoard 追踪训练进展，最后清理闲置资源。

为什么不直接使用 QWorks？

启智推出的 QWorks 是独立的桌面客户端，要求用户迁移到它自带的对话界面中，也无法直接复用 Codex、Claude Code、Cursor 等工具已有的订阅套餐。InspireSkill 则以 CLI + Skill 的形式接入你现有的 Agent 工具链：

快速上手

支持 macOS、Linux 和 Windows（无需 WSL）。具体命令参数请以 inspire --help 和各子命令的 --help 为准。

安装

macOS / Linux

需要 bash、curl、tar、Python 3.10+，以及 uv（推荐）或 pipx。如未安装 uv，请先执行第一行：

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

安装脚本会从 PyPI 安装 inspire-skill，并将 SKILL.md 与 references/ 写入自动检测到的 Agent 客户端目录。可通过 bash -s -- --harness codex,claude 指定目标客户端；--no-cli 仅安装 Skill 文档，--no-schedule 跳过 macOS 每日更新检查。

Windows

需要 Python 3.10+、uv（推荐）或 pipx，以及系统自带的 OpenSSH 客户端。在仓库根目录运行 install.ps1：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install.ps1

脚本会自动检测本机 Agent 客户端；-SkipPlaywright 跳过浏览器运行时安装，-SkipSkill 仅安装 CLI，-Version <x.y.z> 安装指定版本。安装完成后可运行 inspire --version 和 inspire --help 验证。

账号与初始化

账号配置按本地别名（<name>）保存在 ~/.inspire/accounts/<name>/config.toml，与具体代码仓库无关。account add 会引导填写平台登录名（手机号、学号或邮箱）、密码、平台地址及代理；未在配置文件中保存密码时，也可通过环境变量 INSPIRE_PASSWORD 传入。

inspire account add <name>
inspire account check
inspire init
inspire resources availability --workspace 分布式训练空间 --include-cpu

inspire init 用于校验并补全账号配置。在校园网外访问平台时，请先参考下文代理配置完成网络设置。

多账号管理可使用 inspire account use <name> 切换默认账号、inspire account current 查看当前默认账号、inspire account rename <old> <new> 重命名别名。所有命令均支持通过 --account <name> 临时指定单次命令使用的账号（如 inspire --account <name> notebook list --workspace CPU资源空间），切换账号不会清理已有的登录 Session、SSH 连接或本地缓存。

更新与卸载

inspire update                  # 升级 CLI 并同步最新 Skill 文档
inspire update --check          # 仅检查是否有新版本
inspire update --cli-only       # 仅升级 CLI 与浏览器运行时
inspire update --skill-only     # 仅更新 SKILL.md 与 references/
inspire uninstall               # 卸载 CLI 与已安装的 Skill 文档

inspire uninstall 默认保留 ~/.inspire 下的账号配置和 Playwright 浏览器缓存；如需一并清除，可分别加上 --purge 和 --purge-runtime（仓库中的 INSPIRE.md 不会被删除）。若 CLI 环境损坏无法运行，也可使用安装脚本的 --uninstall 参数卸载。

Windows 原生环境提示

• 运行 Get-Command ssh -All 确认实际调用的 ssh.exe 路径；系统 OpenSSH 与 Git for Windows 自带 OpenSSH 对 ProxyCommand 的处理存在差异。
• Windows PowerShell 5.1 的 >> 默认输出 UTF-16LE 编码，会导致 OpenSSH 无法解析配置文件。写入 SSH 配置时请使用：inspire notebook ssh-config <notebook> | Out-File -Encoding utf8 -Append $env:USERPROFILE\.ssh\config（PowerShell 7+ 可直接使用 >>）。
• 若遇到 UNPROTECTED PRIVATE KEY FILE 报错，请收紧 %USERPROFILE%\.ssh 目录的 ACL 权限。文件传输可直接使用 inspire notebook scp，无需额外安装 rsync。

能力一览

点击展开各模块说明。完整子命令、参数与示例请查看 inspire <group> <subcommand> --help。

Python SDK：让启智能力进入你的程序

inspire-skill 内置了完整的 Python SDK。InspireClient 提供同步接口，InspireAsyncClient 提供基于 asyncio 的原生异步接口；两者与 CLI 共享账号配置与资源模型，覆盖 Workspace、Project、Image、Dataset、Model、Notebook、GPU Job、HPC、Ray、Serving 和 TensorBoard，无需在代码中拼接命令或解析终端文本。

from inspire import InspireClient

with InspireClient(account="research") as client:
    client.login()
    for job in client.jobs.list("分布式训练空间", limit=10).items:
        print(job.name, job.status)

异步客户端支持 async with、asyncio.gather 并发查询、事件与日志流式迭代、远程命令执行（exec / exec_stream）以及 Notebook 文件上传下载（upload / download）。完整 API 说明与示例请参考 Python SDK 文档。

支持的 Agent Harness

安装脚本会自动把 SKILL.md 与 references/ 部署到本机已安装的 Agent 客户端目录中：

通用 Skill 与项目资产约定（INSPIRE.md）

• 安装后的 SKILL.md 是通用操作手册。日常任务主要使用 CPU资源空间 和 分布式训练空间；创建任务时显式指定 workspace、project、group、quota 和 image。
• 如果某个代码仓库有需要跨会话、跨成员复用的远端共享盘路径、基底镜像、模型或数据集版本，可以在仓库根目录维护一份可选的 INSPIRE.md（详见 references/assets.md）。
• 如需在本地自定义已安装的 SKILL.md 或 references/，升级时可使用 inspire update --cli-only 避免覆盖本地文档修改。

🔧 维护承诺

启智平台的调度策略、计算组划分与接口细节会随平台迭代变化。维护者 @realZillionX 会持续跟进上游变更并保持 CLI 与文档同步。每次发布新版本后，运行 inspire 命令会在 stderr 提示更新，执行 inspire update 即可一键升级（详见上方更新与卸载）。

如遇到平台行为变更或命令异常，欢迎在 Issue Tracker 提交反馈并附上 inspire --debug <cmd> 的输出（CLI 会自动脱敏密码、Cookie、Token 与代理凭据）。

代理配置

在校园网外访问 *.sii.edu.cn 时，可在 Clash Verge 中新建一个 SII Proxy 策略组，加入组织提供的代理节点与 DIRECT，并将规则 DOMAIN-SUFFIX,sii.edu.cn,SII Proxy 置于通用规则之前（在校园网内直连时切换为 DIRECT）。然后将账号配置中的 proxy 设为本机实际的 Mixed Port 地址，例如 http://127.0.0.1:<mixed-port>。

如果使用启智官方提供的 aTrust VPN，可参考 Docker-aTrust 将 aTrust 运行在 Docker 容器中，在宿主机暴露本地 SOCKS5 / HTTP 代理端口后接入上述分流规则。

账号 proxy 也可以直接写 socks5://127.0.0.1:<port>。CLI 的 HTTP 请求会自动改用 socks5h://，由代理端解析域名，因此只能在 VPN 内解析的平台域名也能访问；浏览器仍使用原地址。远程 Shell / exec 的 WebSocket 目前只支持 HTTP(S) 代理，需要这些功能时请配置 HTTP 代理端口。

账号配置中的 proxy 优先于 Shell 环境变量；未设置账号 proxy 时，HTTP_PROXY / HTTPS_PROXY / ALL_PROXY 仍会生效，直连环境下可通过 NO_PROXY=.sii.edu.cn 绕过系统代理。可随时运行 inspire account check --details 检查当前生效的代理配置与路由状态。

代理凭据（Host / User / Password）请向所在实验室或组织管理员获取，切勿提交到公开仓库或对话记录中。

开发与贡献

项目由 @realZillionX 维护：

• 直接提交 PR：文档修正、手册补充、已知平台字段适配或小型 Bugfix 欢迎直接提交 PR；长期协作者（如 @JingYiJun）跟进的平台适配改动在通过测试与 Review 后可快速合入。
• 先提交 Issue：涉及工作流调整、跨模块重构或多命令行为变更时，建议先在 Issues 描述场景并附上脱敏后的 inspire --debug <cmd> 日志，对齐方案后再编码。

开发环境与提交检查说明见 CONTRIBUTING.md。

文档索引

• SKILL.md：Agent 技能主入口，包含核心操作模型、执行闭环与参考文档路由。
• references/assets.md：INSPIRE.md 持久资产约定与生命周期管理。
• references/resources.md：Workspace、计算组、配额规格、实时余量、用量归因与本地缓存。
• references/paths.md：共享盘作用域、存储池、挂载隔离与远端路径规范。
• references/dataset.md：数据广场检索、版本与权限核验、--dataset 只读挂载。
• references/internal-sources.md：联网准备流程、内部软件源配置与镜像固化策略。
• references/notebook.md：Notebook 创建、SSH / JupyterTerminal 连接、文件流转、HTTP 代理与保存镜像。
• references/compute-workloads.md：GPU Job、CPU HPC、Ray、Serving、API Key、TensorBoard、批量提交与任务观察。
• references/workflows.md：跨 CPU 准备、数据处理、GPU 训练与部署的多阶段项目工作流。
• references/image.md：镜像目录、外部镜像注册、可见性级别与清理规则。
• references/model.md：Model Registry 模型注册、版本检查、最小部署规格与删除预检。
• references/sdk.md：Python SDK 同步与异步客户端、资源模型与完整方法参考。
• references/dev/browser-api.md：CLI 维护者参考，记录 /api/v2 接口契约、认证与登录保护、分页与 scoping、各路由 Action 表、创建字段合同及数据广场协议。
• CONTRIBUTING.md：开发环境、测试要求与贡献指南。
• cli/：CLI 与 Python SDK 源码（入口为 cli/inspire/cli/main.py）。
• scripts/install.sh / scripts/install.ps1：跨平台安装脚本。
• scripts/scan_v2_surface.py：前端产物 /api/v2 接口扫描与 discovery 对账工具。

License

LICENSE（MIT）

Acknowledgements

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

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