脚本¶

quardCRT 从 V0.5.0 开始支持脚本功能。脚本使用 Python 编写，可以调用 quardCRT 内置 API 来实现终端操作、对话框交互、屏幕匹配和文件传输等自动化流程。

本页先从实际使用角度介绍脚本功能，再给出 API 概览。

脚本适合做什么¶

常见用途包括：

自动完成设备或服务器登录流程
等待特定提示符出现后再发送下一条命令
自动化测试步骤或初始化步骤
在 quardCRT 内部启动传输任务或小型辅助工作流
通过录制人工操作生成一个脚本初稿

可用性说明¶

脚本支持依赖于包含 Python 支持的构建。如果你的发行版本没有集成 Python 运行时，脚本菜单相关功能可能会被禁用。

运行脚本¶

通过界面运行 Python 脚本的步骤如下：

打开 脚本 菜单。
选择 运行...。
选择一个 Python 脚本文件。
quardCRT 启动脚本，并在当前脚本结束或取消之前禁用 运行...。

当你通过文件选择器成功运行一个脚本后，quardCRT 还会将它加入最近脚本列表，方便后续直接从菜单再次启动。

取消正在运行的脚本¶

如果当前有脚本正在运行，可通过 脚本 菜单中的取消操作停止执行。

这在以下情况下很有用：

远端响应已经偏离预期
误启动了错误脚本
脚本等待时间超过预期

录制脚本¶

quardCRT 可以录制交互式终端操作，并生成一个可作为起点的 Python 脚本。

在 脚本 菜单中：

选择 开始录制脚本。
在当前终端会话中进行操作。
选择 停止录制脚本... 并保存生成的 .py 文件。

如果你决定不保留本次录制，可使用 取消录制脚本。

录制脚本通常会生成什么¶

生成的 Python 文件通常会包含：

crt.Screen.Synchronous = True
用于发送输入的 crt.Screen.Send(...)
用于等待提示符或输出边界的 crt.Screen.WaitForString(...)

这会给你一个可用的起点，但录制脚本并不保证可直接用于生产环境。实际使用时，通常还需要清理提示符、改进等待逻辑或删掉不必要的步骤。

仓库中的示例脚本¶

这个仓库在 test/scriptengine/ 目录下也提供了一些可以直接运行和修改的小型示例脚本。

比较适合作为起点的示例包括：

test/scriptengine/session/prompted_ssh2.py：提示输入主机、端口、用户名和密码，然后通过 SSH2 连接
test/scriptengine/session/prompted_telnet_login.py：通过 Telnet 连接，并通过等待 login、password 和 shell 提示符来完成登录流程
test/scriptengine/screen/send_command_and_capture.py：向当前活动会话发送命令，并持续读取输出直到匹配到提示符
test/scriptengine/screen/save_screen_to_file.py：将当前可见屏幕文本保存到本地文件
test/scriptengine/misc/repeat_command_logger.py：重复执行同一条命令多次，并将每一轮输出保存到日志文件
test/scriptengine/tab/send_to_all_sessions.py：向当前活动标签组中的所有会话发送同一条命令
test/scriptengine/filetransfer/zmodem_upload_dialog.py：选择本地文件并启动一次 Zmodem 上传

第一个示例¶

以下是一个最小示例，用于在消息框中显示 quardCRT 版本信息。

import sys
from quardCRT import crt

def main():
    # Display quardCRT's version
    crt.Dialog.MessageBox("quardCRT version is: " + crt.Version)

if __name__ == '__main__':
    main()

这个脚本本质上仍然是普通的 Python 文件。区别在于 quardCRT 会在运行时注入 quardCRT 模块及其自动化对象。

这个示例做了什么：

import sys：导入sys模块，用于获取命令行参数。
from quardCRT import crt：导入quardCRT的API。
def main():：定义一个main函数，用于执行脚本的主要逻辑。
# Display quardCRT's version：注释，用于解释下一行代码的作用。
crt.Dialog.MessageBox("quardCRT version is: " + crt.Version)：调用quardCRT的API，显示一个消息框，显示quardCRT的版本信息。
if __name__ == '__main__':：判断脚本是否作为主程序运行。
main()：调用main函数，执行脚本的主要逻辑。

实用的自动化模式¶

在终端自动化中，一个常见模式是：

获取当前活动的屏幕或会话。
用 crt.Screen.Send(...) 发送命令。
用 crt.Screen.WaitForString(...) 或 crt.Screen.WaitForStrings(...) 等待下一个预期提示符。
重复以上步骤直到流程结束。

这种方式通常比单纯依赖固定时间的睡眠更可靠。

API 概览¶

quardCRT的API包括以下几个部分：

crt：quardCRT的主要API。
crt.Dialog：用于显示对话框。
crt.Session：用于管理当前激活的会话。
crt.Screen：用于管理当前激活的屏幕。
crt.Window：用于管理quardCRT的窗口。
crt.Arguments：用于获取命令行参数。
crt.Clipboard：用于操作剪贴板。
crt.FileTransfer：用于操作文件传输。
crt.CommandWindow：用于操作命令窗口。
crt.Tab：用于管理标签页组。

本页后续部分会继续详细说明这些对象。

crt¶

crt是quardCRT的主要API，包括以下几个部分：

方法¶

crt.GetActiveTab() -> object：获取当前活动的标签页组。
- 返回值：Tab对象。
- 示例：
```
tab = crt.GetActiveTab()
```
- 备注：如果当前没有活动的Tab组，则获取第一个Tab组。
crt.GetLastError() -> object：获取最后一次发生的错误。
- 返回值：Error对象。
- 示例：
```
error = crt.GetLastError()
```
crt.GetLastErrorMessage() -> str：获取最后一次发生的错误信息。
- 返回值：错误信息。
- 示例：
```
message = crt.GetLastErrorMessage()
```
crt.ClearLastError()：清除最后一次发生的错误。
- 示例：
```
crt.ClearLastError()
```
crt.Sleep(milliseconds: int)：暂停脚本的执行。
- 参数：
  - milliseconds：暂停的时间，单位为毫秒。
- 示例：
```
crt.Sleep(1000)
```
crt.Cmd(cmd: str, [args:list]) -> str：执行一个quardCRT的特殊命令。
- 参数：
  - cmd：命令名称。
  - args：命令参数列表。
- 返回值：命令执行结果。
- 备注：命令名称和参数列表请参考quardCRT的命令帮助。
- 示例：
```
result = crt.Cmd("show", ["version"])
```
crt.Quit()：退出quardCRT。
- 示例：
```
crt.Quit()
```

属性¶

crt.Dialog：全局对话框对象。
crt.Session：当前会话对象。
crt.Screen：当前屏幕对象。
crt.Window：全局窗口对象。
crt.Arguments：命令行参数对象。
crt.Clipboard：剪贴板对象。
crt.FileTransfer：文件传输对象。
crt.ScriptFullName：当前脚本的完整路径。只读。
crt.ActivePrinter：当前活动的打印机名称。
crt.Version：quardCRT的版本信息。只读。

Dialog¶

Dialog用于显示对话框，全局单例，通过crt对象调用，例如：

dialog = crt.Dialog

包括以下几个部分：

方法¶

Dialog.MessageBox(message: str, [title: str, buttons: int]) -> int：显示一个消息框。
- 参数：
  - message：消息内容。
  - title：消息标题。
  - buttons：按钮类型。
- 返回值：执行结果。0表示正常，其他值表示异常。
- 备注：按钮类型包括Dialog.OK、Dialog.OK | Dialog.Cancel、Dialog.Abort | Dialog.Retry | Dialog.Ignore、Dialog.Yes | Dialog.No等。
- 示例：
```
result = crt.Dialog.MessageBox("Hello, quardCRT!", "Message", crt.Dialog.OK)
```
Dialog.Prompt(prompt: str, name: str, input: str, password: bool) -> str：显示一个输入框。
- 参数：
  - prompt：提示内容。
  - name：输入框名称。
  - input：输入框默认值。
  - password：是否密码输入。
- 返回值：输入框的值。如果用户点击取消，则返回空字符串。
- 示例：
```
value = crt.Dialog.Prompt("Please input your name:", "Name", "", False)
password = crt.Dialog.Prompt("Please input your password:", "Password", "", True)
```
Dialog.FileOpenDialog(title: str, [buttonLabel: str, directory: str, filter: str]) -> str：显示一个打开文件对话框。
- 参数：
  - title：对话框标题。
  - buttonLabel：按钮标签。
  - directory：默认目录。
  - filter：文件过滤器。
- 返回值：选择的文件路径。如果用户点击取消，则返回空字符串。
- 示例：
```
file = crt.Dialog.FileOpenDialog("Open File", "Open", "", "All Files (*.*)|*.*")
```
Dialog.FileSaveDialog(title: str, [buttonLabel: str, directory: str, filter: str]) -> str：显示一个保存文件对话框。
- 参数：
  - title：对话框标题。
  - buttonLabel：按钮标签。
  - directory：默认目录。
  - filter：文件过滤器。
- 返回值：选择的文件路径。如果用户点击取消，则返回空字符串。
- 示例：
```
file = crt.Dialog.FileSaveDialog("Save File", "Save", "", "All Files (*.*)|*.*")
```

属性¶

Dialog.OK：确定按钮。只读。
Dialog.Cancel：取消按钮。只读。
Dialog.Abort：中止按钮。只读。
Dialog.Retry：重试按钮。只读。
Dialog.Ignore：忽略按钮。只读。
Dialog.Yes：是按钮。只读。
Dialog.No：否按钮。只读。

Session¶

Session用于管理会话，通过crt对象调用或Tab获取，例如：

session = crt.Session # 获取当前会话

tab = crt.GetActiveTab()    # 获取当前活动的标签页组
if tab.Number > 0:
    session = tab.GetSession(0) # 获取标签页组的第一个会话

包括以下几个部分：

方法¶

Session.Connect(cmd: str) -> int：连接到一个主机。
- 参数：
  - cmd：命令。
- 返回值：连接结果。
- 备注：命令格式为 -<type> <arg>，例如：
  - -telnet <hostname> <port>
  - -serial <baudRate> <dataBits> <parity> <stopBits> <flowControl> <xEnable>
  - -localshell <path>
  - -raw <hostname> <port>
  - -namepipe <pipeName>
  - -ssh2 <hostname> <port> <username> <password>
  - -vnc <hostname> <port> <password>
  - -s <sessionName>
  - -clone
- 示例：
```
result = session.Connect("-ssh2 example.com 22 root 123456")
```
Session.Disconnect()：断开当前会话。
- 示例：
```
session.Disconnect()
```
Session.Log(enable: bool)：启用或禁用日志记录。
- 参数：
  - enable：是否启用日志记录。
- 示例：
```
session.Log(True)
```
Session.Lock(prompt: str, password: str, lockallsessions: int) -> int：锁定会话。
- 参数：
  - prompt：提示内容。
  - password：密码。
  - lockallsessions：是否锁定所有会话。
- 返回值：执行结果。
- 示例：
```
result = session.Lock("Please input your password:", "password", 0)
```
Session.Unlock(prompt: str, password: str, lockallsessions: int) -> int：解锁会话。
- 参数：
  - prompt：提示内容。
  - password：密码。
  - lockallsessions：是否解锁所有会话。
- 返回值：执行结果。
- 示例：
```
result = session.Unlock("Please input your password:", "password", 0)
```

属性¶

Session.Connected：会话是否连接。只读。
Session.Locked：会话是否锁定。只读。
Session.Logging：会话是否启用日志记录。只读。
Session.Id：会话的全局ID。只读。

Screen¶

Screen用于管理屏幕，通过crt对象调用或Tab获取，例如：

screen = crt.Screen # 获取当前屏幕

tab = crt.GetActiveTab()    # 获取当前活动的标签页组
if tab.Number > 0:
    screen = tab.GetScreen(0) # 获取标签页组的第一个屏幕

包括以下几个部分：

Screen.WaitForString(str: str, timeout: int, bcaseInsensitive: bool) -> str：等待屏幕出现指定的文本。
- 参数：
  - str：指定的文本。
  - timeout：超时时间。
  - bcaseInsensitive：是否忽略大小写。
- 返回值：匹配的文本。
- 示例：
```
text = screen.WaitForString("Hello, quardCRT!", 1000, False)
```
Screen.WaitForStrings(strlist: list[str], timeout: int, bcaseInsensitive: bool) -> str：等待屏幕出现指定的文本列表。
- 参数：
  - strlist：指定的文本列表。
  - timeout：超时时间。
  - bcaseInsensitive：是否忽略大小写。
- 返回值：匹配的文本。
- 示例：
```
text = screen.WaitForStrings(["Hello", "quardCRT"], 1000, False)
```
Screen.Send(str: str) -> int：发送文本到屏幕。
- 参数：
  - str：发送的文本。
- 返回值：发送的字符数。
- 示例：
```
count = screen.Send("Hello, quardCRT!")
```
Screen.Clear()：清空屏幕。
- 示例：
```
screen.Clear()
```
Screen.Get(row1: int, col1: int, row2: int, col2: int) -> str：获取屏幕指定区域的文本。
- 参数：
  - row1：起始行。
  - col1：起始列。
  - row2：结束行。
  - col2：结束列。
- 返回值：指定区域的文本。
- 示例：
```
text = screen.Get(1, 1, 10, 80)
```
Screen.Get2(row1: int, col1: int, row2: int, col2: int) -> str：获取屏幕指定区域的文本，插入换行符号。
- 参数：
  - row1：起始行。
  - col1：起始列。
  - row2：结束行。
  - col2：结束列。
- 返回值：指定区域的文本。
- 示例：
```
text = screen.Get2(1, 1, 10, 80)
```
Screen.IgnoreCase(enable: bool)：启用或禁用忽略大小写。
- 参数：
  - enable：是否启用忽略大小写。
- 示例：
```
screen.IgnoreCase(True)
```
Screen.Print()：打印屏幕内容。
- 示例：
```
screen.Print()
```
Screen.Shortcut(path: str)：截屏。
- 参数：
  - path：截屏保存的路径。
- 示例：
```
screen.Shortcut("C:\\screenshot.png")
```
Screen.SendKeys(keylist: list[str])：发送组合按键。
- 参数：
  - keylist：按键列表。
- 示例：
```
screen.SendKeys(["Ctrl", "Alt", "Del"])
```
Screen.ReadString(strlist: list[str], timeout: int, bcaseInsensitive: bool) -> str：读取文本数据，直到屏幕出现指定的文本列表。
- 参数：
  - strlist：指定的文本列表。
  - timeout：超时时间。
  - bcaseInsensitive：是否忽略大小写。
- 返回值：读取的文本。
- 示例：
```
text = screen.ReadString(["Hello", "quardCRT"], 1000, False)
```
Screen.WaitForCursor(row: int, col: int, timeout: int) -> bool：等待光标移动到指定位置。（暂未实现）
- 参数：
  - row：指定行。
  - col：指定列。
  - timeout：超时时间。
- 返回值：是否成功。
- 示例：
```
result = screen.WaitForCursor(10, 10, 1000)
```
Screen.WaitForKey(keylist: list[str], timeout: int) -> bool：等待按键输入。（暂未实现）
- 参数：
  - keylist：按键列表。
  - timeout：超时时间。
- 返回值：是否成功。
- 示例：
```
result = screen.WaitForKey(["Enter"], 1000)
```

属性¶

Screen.Synchronous：同步模式。
Screen.CurrentColumn：当前光标列。只读。
Screen.CurrentRow：当前光标行。只读。
Screen.Rows：屏幕行数。只读。
Screen.Columns：屏幕列数。只读。
Screen.IgnoreCase：是否忽略大小写。
Screen.MatchIndex：匹配的索引。只读。
Screen.Selection：选择的文本。只读。
Screen.Id：屏幕的全局ID。只读。

Window¶

Window用于管理应用窗口，全局单例，通过crt对象调用，例如：

window = crt.Window

包括以下几个部分：

方法¶

Window.Activate()：激活窗口。
- 示例：
```
window.Activate()
```
Window.Show(type: int)：显示窗口。
- 参数：
  - type：窗口显示类型。
- 示例：
```
window.Show(crt.Window.ShowNormal)
```

属性¶

Window.State：当前窗口显示类型。
Window.Active：当前窗口是否激活。
Window.Hide：隐藏窗口。只读。
Window.ShowNormal：正常显示窗口。只读。
Window.ShowMinimized：最小化窗口。只读。
Window.ShowMaximized：最大化窗口。只读。

Arguments¶

Arguments用于获取命令行参数，全局单例，通过crt对象调用，例如：

arguments = crt.Arguments

包括以下几个部分：

方法¶

Arguments.GetArg(index: int) -> str：获取指定索引的参数。
- 参数：
  - index：参数索引。
- 返回值：参数值。
- 示例：
```
arg = arguments.GetArg(0)
```

属性¶

Arguments.Count：参数数量。只读。

Clipboard¶

Clipboard用于操作剪贴板，全局单例，通过crt对象调用，例如：

clipboard = crt.Clipboard

包括以下几个部分：

属性¶

Clipboard.Text：剪贴板文本。只读。

FileTransfer¶

FileTransfer用于操作文件传输，全局单例，通过crt对象调用，例如：

filetransfer = crt.FileTransfer

包括以下几个部分：

方法¶

FileTransfer.AddToUploadList(path: str)：添加文件到zmodem上传列表。
- 参数：
  - path：文件路径。
- 示例：
```
filetransfer.AddToUploadList("C:\\example.txt")
```
FileTransfer.ClearUploadList()：清空zmodem上传列表。
- 示例：
```
filetransfer.ClearUploadList()
```
FileTransfer.ReceiveKermit() -> int：接收kermit文件。
- 返回值：是否成功。
- 示例：
```
result = filetransfer.ReceiveKermit()
```
Filetransfer.SendKermit(path: str) -> int：发送kermit文件。
- 参数：
  - path：文件路径。
- 返回值：是否成功。
- 示例：
```
result = filetransfer.SendKermit("C:\\example.txt")
```
FileTransfer.ReceiveXmodem(path: str)：接收xmodem文件。
- 参数：
  - path：文件路径。
- 返回值：是否成功。
- 示例：
```
result = filetransfer.ReceiveXmodem("C:\\example.txt")
```
FileTransfer.SendXmodem(path: str) -> int：发送xmodem文件。
- 参数：
  - path：文件路径。
- 返回值：是否成功。
- 示例：
```
result = filetransfer.SendXmodem("C:\\example.txt")
```
FileTransfer.ReceiveYmodem() -> int：接收ymodem文件。
- 返回值：是否成功。
- 示例：
```
result = filetransfer.ReceiveYmodem()
```
FileTransfer.SendYmodem(path: str) -> int：发送ymodem文件。
- 参数：
  - path：文件路径。
- 返回值：是否成功。
- 示例：
```
result = filetransfer.SendYmodem("C:\\example.txt")
```
FileTransfer.SendZmodem() -> int：发送zmodem文件。
- 返回值：是否成功。
- 示例：
```
result = filetransfer.SendZmodem()
```

属性¶

FileTransfer.DownloadFolder：下载文件夹。

CommandWindow¶

CommandWindow用于操作命令窗口，全局单例，通过crt对象调用，例如：

commandwindow = crt.CommandWindow

包括以下几个部分：

方法¶

CommandWindow.Send()：发送文本到命令窗口。

示例：

commandwindow.Text = 'Hello, quardCRT!'
commandwindow.Send()

属性¶

CommandWindow.SendCharactersImmediately：是否立即发送字符。
CommandWindow.SendToAllSessions：是否发送到所有会话。
CommandWindow.Visible：命令窗口是否可见。
CommandWindow.Text：命令窗口文本。

Tab¶

Tab用于管理标签页组，通过crt对象调用，例如：

tab = crt.GetActiveTab()    # 获取当前活动的标签页组

包括以下几个部分：

方法¶

Tab.GetScreen(index: int) -> object：获取标签页组的屏幕。
- 参数：
  - index：屏幕索引。
- 返回值：Screen对象。
- 示例：
```
screen = tab.GetScreen(0)
```
Tab.GetSession(index: int) -> object：获取标签页组的会话。
- 参数：
  - index：会话索引。
- 返回值：Session对象。
- 示例：
```
session = tab.GetSession(0)
```
Tab.Activate(index: int)：激活标签页组的指定会话。
- 参数：
  - index：会话索引。
- 示例：
```
tab.Activate(0)
```

属性¶

Tab.Number：标签页组内会话数量。只读。

脚本¶

脚本适合做什么¶

可用性说明¶

运行脚本¶

取消正在运行的脚本¶

录制脚本¶

录制脚本通常会生成什么¶

最近脚本¶

仓库中的示例脚本¶

第一个示例¶

实用的自动化模式¶

API 概览¶

crt¶

方法¶

属性¶

Dialog¶

方法¶

属性¶

Session¶

方法¶

属性¶

Screen¶

属性¶

Window¶

方法¶

属性¶

Arguments¶

方法¶

属性¶

Clipboard¶

属性¶

FileTransfer¶

方法¶

属性¶

CommandWindow¶

方法¶

属性¶

Tab¶

方法¶

属性¶