feat(docs): 为全部模型添加注释

- resolve #9

Author: molanp

README.md

@@ -3,6 +3,7 @@
 ![Supported MCSManager Versions](https://img.shields.io/badge/Supported%20MCSManager%20Versions-10.x-blue)
 ![Python Version](https://img.shields.io/badge/Python%20Version-%3E%3D3.7-blue)
 ![PyPI Downloads](https://img.shields.io/pypi/dm/mcsmapi)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/molanp/mcsmapi)
 
 English|[Chinese Simplified](README_zh-cn.md)
 

README_zh-cn.md

@@ -3,6 +3,7 @@
 ![Supported MCSManager Versions](https://img.shields.io/badge/Supported%20MCSManager%20Versions-10.x-blue)
 ![Python Version](https://img.shields.io/badge/Python%20Version-%3E%3D3.7-blue)
 ![PyPI Downloads](https://img.shields.io/pypi/dm/mcsmapi)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/molanp/mcsmapi)
 
 简体中文|[English](README.md)
 

mcsmapi/apis/daemon.py

@@ -52,6 +52,7 @@ def instances(self, daemonId: str, page: int = 0, page_size: int = 10, instance_
         - 由于根据 MCSM 源代码的测试无法获取有效数据，目前无法完成该功能的开发。
         - 如果你有具体的实现思路，请在 issue 中提出
         - 可供参考 MCSM 源码: [daemon_router.ts 第 32 行](https://github.com/MCSManager/MCSManager/blob/master/panel%2Fsrc%2Fapp%2Frouters%2Fdaemon_router.ts#L32-L32)
+        - 模型定义代码: https://github.com/MCSManager/MCSManager/blob/master/frontend%2Fsrc%2Fservices%2Fapis%2Findex.ts#L86-L86
         - 测试地址示例:
             `http://localhost:23333/api/service/remote_service_instances?apikey=xxx&daemonId=xxx&page=0&page_size=10&status=3&instance_name=`
         """

mcsmapi/models/daemon.py

@@ -4,13 +4,17 @@
 
 
 class CpuMemChart(BaseModel):
+    """节点资源使用率信息"""
+
     """cpu使用率"""
     cpu: float = 0
     """内存使用率"""
     mem: float = 0
 
 
 class ProcessInfo(BaseModel):
+    """节点进程详细信息"""
+
     """远程节点使用的cpu资源(单位: byte)"""
     cpu: int = 0
     """远程节点使用的内存资源(单位: byte)"""
@@ -20,13 +24,17 @@ class ProcessInfo(BaseModel):
 
 
 class InstanceInfo(BaseModel):
+    """实例统计信息"""
+
     """运行中实例数量"""
     running: int = 0
     """全部实例数量"""
     total: int = 0
 
 
 class SystemInfo(BaseModel):
+    """节点系统信息"""
+
     """系统类型"""
     type: str = ""
     """主机名"""
@@ -56,6 +64,8 @@ class SystemInfo(BaseModel):
 
 
 class DaemonModel(BaseModel):
+    """节点详细信息"""
+
     """远程节点版本"""
     version: str = ""
     """远程节点的基本信息"""
@@ -158,6 +168,8 @@ def deleteInstance(self, uuids: list[str], deleteFile=False) -> list[str]:
 
 
 class DaemonConfig(BaseModel):
+    """节点配置信息"""
+
     """远程节点的ip"""
     ip: str = "localhost"
     """远程节点的端口"""

mcsmapi/models/file.py

@@ -4,6 +4,8 @@
 
 
 class FileItem(BaseModel):
+    """文件信息"""
+
     """文件名称"""
     name: str = ""
     """文件大小(单位: byte)"""
@@ -149,6 +151,8 @@ def download(self) -> str:
 
 
 class FileList(BaseModel):
+    """文件列表"""
+
     """文件信息列表"""
     items: List[FileItem]
     """当前页数"""

mcsmapi/models/image.py

@@ -3,113 +3,205 @@
 
 
 class DockerConfig(BaseModel):
+    """容器配置"""
+
     """容器名称"""
     containerName: str = ""
     """镜像名称"""
     image: str = ""
     """容器分配内存(单位: MB)"""
     memory: int = 0  # in MB
-    ports: List[str] = ["25565:25565/tcp"]
+    """容器端口映射"""
+    ports: List[str] = []  # ["25565:25565/tcp"]
+    """额外挂载卷路径"""
     extraVolumes: List[str] = []
+    """容器可使用的最大磁盘空间(单位: MB)"""
     maxSpace: Optional[int] = None
+    """网络配置，可以是网络名称或ID"""
     network: Optional[Union[str, int]] = None
+    """容器的 IO 限制"""
     io: Optional[Union[str, int]] = None
+    """网络模式(例如: bridge, host)"""
     networkMode: str = "bridge"
+    """网络别名列表"""
     networkAliases: List[str] = []
-    cpusetCpus: str = ""
+    """绑定的 CPU 核心"""
+    cpusetCpus: str = ""  # 例如 `0,1`
+    """CPU 使用率(单位: %)"""
     cpuUsage: int = 100
+    """工作目录"""
     workingDir: str = ""
+    """环境变量设置"""
     env: List[str] = []
 
 
 class DockerImageItem(BaseModel):
+    """Docker 镜像信息"""
+
+    """镜像唯一 ID"""
     Id: str = ""
+    """父镜像 ID"""
     ParentId: str = ""
-    RepoTags: List[str] = []
+    """镜像仓库标签"""
+    RepoTags: List[str] = []  # 例如 ["ubuntu:latest"]
+    """镜像摘要"""
     RepoDigests: List[str] = []
+    """镜像创建时间(Unix 时间戳)"""
     Created: int = 0
+    """镜像大小(单位: 字节)"""
     Size: int = 0
+    """镜像的虚拟大小"""
     VirtualSize: int = 0
+    """共享存储空间大小"""
     SharedSize: int = 0
+    """镜像标签"""
     Labels: dict[str, str] = {}
+    """依赖该镜像运行的容器数量"""
     Containers: int = 0
 
 
 class DockerContainerItemPort(BaseModel):
+    """Docker 容器端口映射"""
+
+    """容器内部端口"""
     PrivatePort: int = 0
+    """映射到宿主机的端口"""
     PublicPort: Optional[int] = None
+    """端口类型(tcp/udp)"""
     Type: str = ""
 
 
 class DockerContainerItemNetworkSettingsNetwork(BaseModel):
+    """Docker 容器网络设置信息"""
+
+    """网络 ID"""
     NetworkID: str = ""
+    """网络端点 ID"""
     EndpointID: str = ""
+    """网关地址"""
     Gateway: str = ""
+    """分配的 IP 地址"""
     IPAddress: str = ""
+    """IP 地址前缀长度"""
     IPPrefixLen: int = 0
+    """IPv6 网关地址"""
     IPv6Gateway: str = ""
+    """IPv6 地址"""
     GlobalIPv6Address: str = ""
+    """IPv6 地址前缀长度"""
     GlobalIPv6PrefixLen: int = 0
+    """MAC 地址"""
     MacAddress: str = ""
 
 
 class DockerContainerItemNetworkSettings(BaseModel):
+    """Docker 容器的网络配置信息"""
+
+    """容器连接的所有网络"""
     Networks: dict[str, DockerContainerItemNetworkSettingsNetwork] = {}
 
 
 class DockerContainerItemMount(BaseModel):
+    """容器挂载点信息"""
+
+    """挂载名称"""
     Name: str = ""
+    """源路径"""
     Source: str = ""
+    """目标路径"""
     Destination: str = ""
+    """驱动类型"""
     Driver: str = ""
+    """挂载模式"""
     Mode: str = ""
+    """是否允许读写"""
     RW: bool = False
+    """传播模式"""
     Propagation: str = ""
 
 
 class DockerContainerItemHostConfig(BaseModel):
+    """Docker 宿主机配置"""
+
+    """网络模式"""
     NetworkMode: str = ""
 
 
 class DockerContainerItem(BaseModel):
+    """Docker 容器详细信息"""
+
+    """容器 ID"""
     Id: str = ""
+    """容器名称列表"""
     Names: List[str] = []
+    """运行的镜像名称"""
     Image: str = ""
+    """镜像 ID"""
     ImageID: str = ""
+    """容器启动命令"""
     Command: str = ""
+    """容器创建时间(Unix 时间戳)"""
     Created: int = 0
+    """容器状态"""
     State: str = ""
+    """容器运行状态描述"""
     Status: str = ""
+    """端口映射信息"""
     Ports: List[DockerContainerItemPort] = []
+    """容器标签信息"""
     Labels: dict[str, str] = {}
+    """读写层大小(单位: 字节)"""
     SizeRw: int = 0
+    """根文件系统大小(单位: 字节)"""
     SizeRootFs: int = 0
+    """宿主机配置"""
     HostConfig: DockerContainerItemHostConfig = DockerContainerItemHostConfig()
-    NetworkSettings: DockerContainerItemNetworkSettings = (
-        DockerContainerItemNetworkSettings()
-    )
+    """容器网络配置"""
+    NetworkSettings: DockerContainerItemNetworkSettings = DockerContainerItemNetworkSettings()
+    """容器挂载信息"""
     Mounts: List[DockerContainerItemMount] = []
 
 
 class DockerNetworkItemIPAMConfig(BaseModel):
+    """Docker 网络 IPAM 配置信息"""
+
+    """子网地址"""
     Subnet: str = ""
 
 
 class DockerNetworkItemIPAM(BaseModel):
+    """Docker 网络的 IP 地址管理"""
+
+    """驱动类型"""
     Driver: str = ""
+    """IPAM 配置"""
     Config: List[DockerNetworkItemIPAMConfig] = []
 
 
 class DockerNetworkItem(BaseModel):
+    """Docker 网络详细信息"""
+
+    """网络名称"""
     Name: str = ""
+    """网络 ID"""
     Id: str = ""
+    """网络创建时间"""
     Created: str = ""
+    """网络作用范围(local/global)"""
     Scope: str = ""
+    """网络驱动类型"""
     Driver: str = ""
+    """是否启用 IPv6"""
     EnableIPv6: bool = False
+    """是否为内部网络"""
     Internal: bool = False
+    """是否可附加"""
     Attachable: bool = False
+    """是否为入口网络"""
     Ingress: bool = False
+    """IPAM 配置信息"""
     IPAM: DockerNetworkItemIPAM = DockerNetworkItemIPAM()
-    Options: dict[str, str]
-    Containers: Optional[dict[str, dict]] = {}
+    """网络选项"""
+    Options: dict[str, str] = {}
+    """连接到此网络的容器信息"""
+    Containers: Optional[dict[str, dict]] = {}