> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Python SDK 管理开发环境

> 使用人工智能平台 Python SDK 创建、查询、更新、启停 VSCS 开发环境，并配置 SSH 公钥、定时策略和弹性策略。

Python SDK 可用于创建和管理 VSCS 开发环境，适合在自动化流程中准备远程开发工作区、配置 SSH 访问或批量管理环境生命周期。使用本文示例前，请先完成 [Python SDK 快速开始](./python-sdk-quickstart)，并确认当前账号具备目标资源池、镜像和 Volume 的使用权限。

## 创建开发环境

创建 VSCS 开发环境时，建议先查询可用于开发环境的镜像，并使用返回的完整镜像地址。

```python theme={null}
from siflow import SiFlow
from siflow.types.vscs import (
    CreateVscsRequest,
    DevToolsInfo,
    Instance,
    SSHToolConfig,
    VSCodeToolConfig,
    VolumeMount,
)

client = SiFlow(region="cn-beijing", cluster="auriga")

images = client.images.list_for_workload(use_case="vscs")
if not images.rows:
    raise RuntimeError("当前区域和集群没有可用于 VSCS 的镜像")

picked = images.rows[0]

res = client.vscs.create(
    request=CreateVscsRequest(
        region="cn-beijing",
        cluster="auriga",
        name="sdk-vscs-demo",
        image=picked.image,
        imageUrl=picked.imageUrl,
        resourcePool="<RESOURCE_POOL>",
        instances=[
            Instance(name="sci.c22-2", countPerPod=1),
        ],
        selectedInstance="sci.c22-2",
        devToolsInfo=DevToolsInfo(
            workspaceDir="/workspace",
            ssh=SSHToolConfig(enabled=True),
            vscode=VSCodeToolConfig(enabled=True),
        ),
        sshPubKeys=[
            "ssh-ed25519 AAAA... user@workstation",
        ],
        volumeMounts=[
            VolumeMount(
                volumeId=123,
                mountDir="/workspace",
            ),
            VolumeMount(
                volumeId=124,
                mountDir="/workspace/data",
                subPath="data",
                readOnly=False,
            ),
        ],
    )
)

print(res)
```

常用创建参数如下：

| 参数                               | 说明                                                                                                      |
| -------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `region` / `cluster`             | 区域和集群。                                                                                                  |
| `name`                           | 开发环境名称。                                                                                                 |
| `image` / `imageUrl`             | 镜像信息。`imageUrl` 是实际下发到容器的完整镜像地址，建议从 `client.images.list_for_workload(use_case="vscs")` 的返回结果中获取，不要自行拼接。 |
| `resourcePool`                   | 资源池 ID 或名称。                                                                                             |
| `instances` / `selectedInstance` | 实例规格和当前选中的规格。                                                                                           |
| `devToolsInfo`                   | 开发工具配置，可配置 VS Code Web、SSH 和工作目录。                                                                       |
| `sshPubKeys`                     | SSH 公钥列表。启用 SSH 访问时需要配置。                                                                                |
| `volumeMounts`                   | Volume 挂载配置。开启目录级权限的 Volume 需要配置 `subPath`；只读目录应设置 `readOnly=True`。                                     |
| `envVars`                        | 环境变量。                                                                                                   |
| `datasets` / `models`            | 数据集或模型挂载配置。                                                                                             |
| `timezone`                       | 容器时区。                                                                                                   |

## 查询开发环境

查询列表：

```python theme={null}
page = client.vscs.list(
    page=1,
    page_size=10,
    name="sdk-vscs-demo",
    status=["Ready"],
    resource_pool=["<RESOURCE_POOL>"],
    access_type=["ssh"],
    dev_tools_info=["ssh"],
    sort_by="createTime",
    sort_order="desc",
)

for item in page.rows:
    print(item.id, item.name, item.status)
```

查询详情：

```python theme={null}
detail = client.vscs.get(id=123)
print(detail.status, detail.url, detail.sshAddr)
```

列表接口支持按 `name`、`status`、`resource_pool`、`access_type`、`dev_tools_info`、`sort_by`、`sort_order` 和 `show_all` 等参数过滤。

## 更新开发环境

更新镜像时，应同时更新 `image` 和 `imageUrl`。其中 `imageUrl` 是实际下发到容器的字段。

```python theme={null}
from siflow.types.vscs import Instance, UpdateVscsRequest

images = client.images.list_for_workload(use_case="vscs")
if not images.rows:
    raise RuntimeError("当前区域和集群没有可用于 VSCS 的镜像")

picked = images.rows[0]

client.vscs.update(
    id=123,
    request=UpdateVscsRequest(
        image=picked.image,
        imageUrl=picked.imageUrl,
        instances=[
            Instance(name="sci.c22-4", countPerPod=1),
        ],
        selectedInstance="sci.c22-4",
    ),
)
```

更新资源、镜像或挂载配置可能影响开发环境可用性。执行前请确认当前环境中的代码、数据和临时结果已保存到持久化路径。

## 启停和删除开发环境

停止开发环境：

```python theme={null}
client.vscs.stop(id=123)
```

需要继续使用时，重新启动开发环境：

```python theme={null}
client.vscs.start(id=123)
```

需要重启环境时，根据目标选择普通重启或原地重启：

```python theme={null}
client.vscs.restart(id=123)
# 或者：client.vscs.inplace_restart(id=123)
```

确认不再需要开发环境后再删除：

```python theme={null}
client.vscs.delete(id=123)
```

停止会释放运行资源，但不会自动删除持久化存储中的文件。删除前，请确认不再需要该开发环境记录和相关配置。

## 配置定时和弹性策略

配置定时启停：

```python theme={null}
from siflow.types.vscs import ScheduleVscsRequest

client.vscs.schedule(
    request=ScheduleVscsRequest(
        id=123,
        cronEnable=True,
        cronStartTime="0 9 * * *",
        cronEndTime="0 20 * * *",
    )
)
```

配置弹性策略：

```python theme={null}
from siflow.types.vscs import AutoScaleVscsRequest

client.vscs.auto_scale(
    request=AutoScaleVscsRequest(
        id=123,
        scaleEnable=True,
        duration=10,
        gpuUsage=60,
        policyType="gpu",
    )
)
```

定时启停和弹性策略会影响开发环境运行状态。配置后，建议查询环境状态确认策略是否按预期生效。

## 管理 SSH 公钥

`update_ssh_key` 会替换当前开发环境的 SSH 公钥列表。

```python theme={null}
from siflow.types.vscs import UpdateSSHKeyRequest

client.vscs.update_ssh_key(
    id=123,
    request=UpdateSSHKeyRequest(
        sshPubKeys=[
            "ssh-ed25519 AAAA...new-key... user@workstation",
        ],
    ),
)
```

更新 SSH 公钥后，请使用新公钥对应的私钥连接开发环境。

## 查询汇总和筛选项

```python theme={null}
summary = client.vscs.summary()
filters = client.vscs.filters()
statuses = client.vscs.statuses()
dashboard = client.vscs.dashboard(
    details_limit=5,
    resource_pool="<RESOURCE_POOL>",
)

print(summary)
print(filters)
print(statuses)
print(dashboard)
```

这些接口适合用于构建自定义看板或自动化巡检脚本。

## 相关文档

* [Python SDK 快速开始](./python-sdk-quickstart)
* [使用 VS Code Server 开发环境](../development/use-vscode-server-development-environment)
* [使用 JupyterLab 开发环境](../development/use-jupyterlab-development-environment)