Modelscope Studio

# ModelScope 创空间部署 Skill

将本地项目一键部署到 ModelScope 创空间，支持自动创建、代码同步、启动运行和日志分析修复。

## 前置条件

### 1. MODELSCOPE_API_TOKEN

整个流程依赖此令牌（MCP 服务获取、Git 推送、环境变量配置），必须最先确认。

```bash
# 1. 先检查环境变量
echo $MODELSCOPE_API_TOKEN

# 2. 如果环境变量为空，尝试从 git remote 中提取（可能之前配置过）
git remote -v 2>/dev/null | grep modelscope.cn
```

如果环境变量为空但 git remote 中包含形如 `https://oauth2:<token>@www.modelscope.cn/studios/...` 的地址，从中提取 `<token>` 部分作为 `MODELSCOPE_API_TOKEN` 使用。

两者都没有时，引导用户：
1. 访问 https://modelscope.cn/my/myaccesstoken 获取令牌
2. `export MODELSCOPE_API_TOKEN=your_token`

### 2. 获取并配置 ModelScope MCP 服务

MCP 尚未配置前不能使用 MCP 工具，必须通过 curl 调用 HTTP API 获取部署链接。

#### 2.1 查询已有部署链接

```bash
curl -s -X GET \
  "https://modelscope.cn/openapi/v1/mcp/servers/modelscope/modelscope-mcp-server?get_operational_url=true" \
  -H "Authorization: Bearer ${MODELSCOPE_API_TOKEN}" \
  -H "Content-Type: application/json"
```

检查返回 JSON 中 `data.operational_urls`：
- 数组非空 → 取第一个条目，检查 `expiration` 字段：
  - 如果 `expiration` 早于当前时间，说明链接已过期 → 进入 2.2 重新部署
  - 未过期 → 提取 `url`、`auth_required`、`transport_type`，跳到 2.3
- 数组为空或不存在 → 进入 2.2

如果请求失败（HTTP 非 200 或 `success: false`），检查 Token 是否正确，提示用户重新获取。

#### 2.2 部署 MCP 服务（仅在 2.1 无可用链接时）

```bash
curl -s -X POST \
  "https://modelscope.cn/openapi/v1/mcp/servers/modelscope/modelscope-mcp-server/deploy" \
  -H "Authorization: Bearer ${MODELSCOPE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"transport_type": "sse"}'
```

从返回 JSON 的 `data.url` 提取部署链接。如果部署失败，向用户展示错误信息并建议稍后重试。

#### 2.3 写入本地 MCP 配置

根据当前使用的 IDE 把获取到的 URL 写入配置文件。如果 `auth_required` 为 `true`，需要添加 Authorization header，因为服务端会校验令牌身份：

配置模板：
```json
{
  "mcpServers": {
    "studio-mcp": {
      "type": "sse",
      "url": "<从 API 返回的 url>",
      "headers": {
        "Authorization": "Bearer <MODELSCOPE_API_TOKEN 的值>"
      }
    }
  }
}
```

> `auth_required` 为 `false` 时可省略 `headers` 部分。

各 IDE 配置位置：
- **Kiro**：写入 `.kiro/settings/mcp.json`
- **Cursor**：写入项目根目录 `.cursor/mcp.json` 或全局配置
- **Qoder**：打印配置信息，提示用户手动添加到 MCP 设置
- 其他客户端：按文档添加对应 `transport_type` 的 MCP 服务，不清楚怎么配置时请用户手动操作

配置完成后调用 MCP 工具 `getCurrentUser` 验证连接。如果 MCP 配置后工具调用不生效（连接超时、工具不可用等），改用 HTTP API 直接调用创空间相关接口完成全部操作，见底部「HTTP API 速查」。

### 3. Git 环境

创空间代码通过 Git 同步，确保已安装 Git 并配置用户信息。

## 部署流程

### Step 1: 检查本地 Git 仓库

先检查项目是否已关联创空间，这决定后续是创建还是更新：

```bash
[ -d .git ] && git remote -v 2>/dev/null | grep modelscope.cn/studios
```

- 已有创空间远程地址 → 从 URL 提取 `owner` 和 `repo_name`，跳到 Step 3
- 没有 → 继续 Step 2

### Step 2: 分析项目并获取用户信息

#### 2.1 确定 SDK 类型

分析项目结构：

| 类型 | 检测条件 | 入口文件 | 必需配置 |
|-----|---------|---------|---------|
| `gradio` | `app.py` 导入 gradio | `app.py` | `sdk_version`, `base_image` |
| `streamlit` | `app.py` 使用 streamlit | `app.py` | `base_image` |
| `docker` | 存在 `Dockerfile` | `Dockerfile` | 无（端口必须 7860） |
| `static` | 存在 `index.html`（已构建） | `index.html` | 无 |

选择建议：
- `static` 不支持构建步骤，文件必须已构建并提交
- 需要构建的前端项目（如 `npm run build`）使用 `docker`
- 不确定时推荐 `docker`

> ⚠️ 选择 `docker` 类型时，必须提醒用户：需先在魔搭平台完成阿里云账号绑定并通过实名认证，否则无法构建 Docker 镜像。详见：https://modelscope.cn/docs/studios/docker

#### 2.2 获取用户信息

```
调用 getCurrentUser → 获取 username 作为 owner
```

`repo_name` 从项目目录名或用户指定获取。

### Step 3: 创建或更新创空间

检查创空间是否已存在：
```
调用 getStudio: owner, repo_name
```

**不存在 → 创建：**

> 创建前主动询问用户：「创空间设为公开还是私有？」用户不回答或无所谓则默认 `private: true`。

```
调用 createStudio:
- owner, repo_name, sdk_type, display_name, description
- private: 用户选择（默认 true）
- base_image: 仅 gradio/streamlit 需要
- sdk_version: 仅 gradio 需要
```

**已存在 → 更新：**
```
调用 updateStudioSettings:
- owner, repo_name
- sdk_type, base_image, sdk_version 等（按需）
```

配置参考：
- `base_image`: 推荐各项版本最新的镜像
- `sdk_version`: 推荐最新版
- `hardware`: 免费 `platform/2v-cpu-16g-mem`，xGPU 需申请（https://models