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 每日更新检查。

未检测到 Agent 客户端时，脚本仍会安装 CLI，跳过 Skill 文件并提示；安装 Agent 后运行 inspire update，或重新运行脚本并传入 --harness <name> 补装。若同时传入 --no-cli 且未检测到或指定客户端，则报错退出。

Python 包首次下载约 90 MB，Playwright Chromium 运行时约 150 MB（随平台、版本和缓存而变化），慢速网络下可能需要数分钟。可用 --index-url URL 为本次 CLI 安装指定较近的 PyPI 镜像，例如：

curl -fsSL https://raw.githubusercontent.com/realZillionX/InspireSkill/main/scripts/install.sh | bash -s -- --index-url https://mirrors.aliyun.com/pypi/simple/

脚本不会自动切换镜像。未指定参数时保留已有环境变量：uv 使用 UV_DEFAULT_INDEX（优先）或 UV_INDEX_URL，pipx 使用 PIP_INDEX_URL；显式参数覆盖本次安装的索引。日志显示自定义索引时会移除 URL 中的用户名和密码。该参数只影响 Python 包下载，不改变 Chromium 或 Skill 文件的下载源。

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 验证。

未检测到客户端时仍可完成 CLI 安装，Skill 不会安装；安装 Agent 后运行 inspire update 补装。PowerShell 对应的镜像参数为 -IndexUrl URL，环境变量优先级与上述说明一致，例如：

.\scripts\install.ps1 -IndexUrl https://mirrors.aliyun.com/pypi/simple/

账号与初始化

Run inspire login --account <name> to create a local account and authorize it with the official OAuth device flow. Without --account, login uses the active account, or creates default when no accounts exist. Connection settings live in ~/.inspire/accounts/<name>/config.toml; access and rotating refresh tokens live in web_session.json. Passwords are neither stored nor read from configuration or environment variables. account add remains the compatible account creation entry point.

For data plaza catalogue access, use inspire login --cas feishu and scan the QR with Feishu, or inspire login --cas sms --phone NUMBER. Bare --cas asks for the method in a terminal (default: Feishu); scripts and JSON mode must specify a method. Feishu requires Playwright Chromium; the command renders the QR to stderr, prints its private PNG path, refreshes it as needed, and removes the PNG on completion or failure. Install missing Chromium with inspire update --cli-only.

SMS login requires a mobile phone number (11 digits starting with 1, optionally +86), not a student ID. Interactive login prompts for the SMS code, allowing three attempts. Noninteractive login sends a code and exits successfully; complete within ten minutes with inspire login --cas sms --phone NUMBER --sms-code CODE, using the same --account. Neither the phone number nor the SMS code is saved. The private pending state contains only CAS cookies and form controls.

CAS credentials are stored separately in the account’s private cas_session.json. After CAS login, the CLI automatically approves OAuth device authorization; if approval cannot be completed, it prints the normal URL/code and waits for manual approval. Plain login also tries a valid stored CAS session first. Platform requests continue to use Bearer tokens. When refresh credentials expire or are refused, a valid CAS session can silently obtain new tokens; otherwise run login again. --json returns metadata including cas (stored and just validated) and cas_method, never credentials.

inspire logout --account <name> --yes 与 inspire account remove <name> --yes 等价：删除整个本地账号目录，包括令牌、配置及 bridge/tunnel 状态，平台工作负载继续运行。删除活动账号后不再保留活动指针。首个账号默认激活，--use 强制激活、--no-use 阻止激活；登录已有账号默认不切换活动账号。login 的 --base-url / --proxy 仅用于新配置，已有配置不会被覆盖。

inspire login --account <name>
inspire account check                    # 实时验证 OAuth 与 CAS，显示有效期和刷新结果
inspire account check --offline          # 只读本地状态，不联网或刷新
inspire init
inspire resources availability --workspace 分布式训练空间 --include-cpu

account check 和 account list 会显示 OAuth 访问／刷新令牌的到期时间和 CAS（数据广场）登录状态；--offline 不验证平台认证（JSON authenticated: null），有效或可自动刷新时退出 0，其余情况返回认证错误码。

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.}