ahang1598 向日葵远程控制
通过 awesun-cli 命令行工具管理向日葵远程控制设备，支持设备管理、远程桌面、命令执行、文件传输、端口转发等操作。
前置安装
首次使用需全局安装 CLI 工具：
npm install -g @aweray/awesun-cli
账号管理
必须先登录才能使用其他命令。
# 扫码登录（推荐，--url 返回登录 URL 而不是打开浏览器）
awesun-cli login --qrcode --url
# 用户名密码登录
awesun-cli login --user <username>
# 检查登录状态
awesun-cli login status
# 登出
awesun-cli logout
# 清除所有缓存凭证登出
awesun-cli logout --clean
工具能力
1. 设备管理工具
| 命令 | 描述 |
|---|---|
device ls |
分页列出所有设备，返回设备基本信息（remote_id、设备名、在线状态等） |
device search <keyword> |
根据关键词模糊搜索设备，支持设备名称模糊匹配 |
device info <remote-id> |
查询指定设备的详细信息（设备状态、系统信息、网络信息等） |
device add |
添加新设备到设备列表，需指定名称和描述 |
device update <remote-id> |
更新设备的元数据信息（名称、描述等） |
device rm <remote-id> |
从设备列表中移除指定设备 |
device grant |
管理设备访问权限（添加/移除/批量授权） |
device shutdown <remote-id> |
远程关闭指定设备 |
device restart <remote-id> |
远程重启指定设备 |
device wakeup <remote-id> |
远程唤醒指定设备（需设备支持网络唤醒） |
典型使用流程：
# 1. 搜索设备获取 remote_id
awesun-cli device search "办公室" --limit 10
# 2. 查看设备详情
awesun-cli device info 12345
# 3. 远程关机
awesun-cli device shutdown 12345
shutdown/restart不带密码会提示输入访问密码；加--username会提示输入系统密码。
2. 远程会话管理工具
| 命令 | 描述 |
|---|---|
session connect |
发起与指定设备的远程会话连接。返回 session_id 用于后续操作 |
session disconnect <session-id> |
断开指定的远程会话 |
session status <session-id> |
查询远程会话的连接状态 |
session ls |
查询当前所有活跃的远程会话列表 |
session screenshot <session-id> |
对远程会话截图，保存到指定路径 |
session exec <session-id> <cmd> |
在 cmd2(Windows) 或 ssh(Linux/Mac) 会话中执行命令 |
连接类型说明（--type 参数）：
| 类型 | 说明 |
|---|---|
desktop |
远程桌面控制（可执行鼠标键盘操作） |
file |
远程文件管理（浏览/上传/下载/删除等） |
ssh |
Linux/Mac 远程 SSH 终端 |
cmd |
Windows 远程命令行 |
forward |
端口转发 |
连接密码规则：
--fastcode <CODE>: 提示输入访问密码--remote-id <ID>: 默认提示输入访问密码--remote-id <ID> --username <USER>: 提示输入系统密码
典型使用流程：
# 1. 搜索设备
awesun-cli device search "办公室电脑" --limit 1
# 假设返回 remote_id: 12345
# 2. 建立远程桌面连接
awesun-cli session connect --type desktop --remote-id 12345
# 返回 session_id: abc123xyz
# 3. 查看活跃会话
awesun-cli session ls
# 4. 断开连接
awesun-cli session disconnect abc123xyz
3. 桌面控制工具
用于在远程桌面会话中执行自动化操作，坐标使用归一化值(0.0-1.0)。仅在 type=desktop 的会话中可用。
| 命令 | 描述 |
|---|---|
desktop mouse move |
移动鼠标到指定归一化坐标，不进行点击 |
desktop mouse click |
模拟鼠标点击（左键/右键/中键），支持双击 |
desktop mouse drag |
模拟鼠标拖拽，从起点拖拽到终点 |
desktop mouse scroll |
模拟鼠标滚轮，支持方向和次数 |
desktop type |
在远程桌面中输入文本 |
desktop paste |
将文本粘贴到远程桌面 |
desktop key combo |
模拟组合键（如 Ctrl+Alt+Del） |
desktop key press |
按下或释放按键序列 |
典型使用流程（自动化操作）：
# 1. 建立远程桌面连接获取 session_id
awesun-cli session connect --type desktop --remote-id 12345
# 返回 session_id: abc123xyz
# 2. 截图查看当前状态
awesun-cli session screenshot abc123xyz --output /tmp/screen.png
# 3. 根据截图识别坐标，执行操作
# 点击某个位置
awesun-cli desktop mouse click abc123xyz --x 0.5 --y 0.5 --button left
# 输入文本
awesun-cli desktop type abc123xyz "Hello World"
# 按回车
awesun-cli desktop key press abc123xyz --keys enter --press down
awesun-cli desktop key press abc123xyz --keys enter --press up
# 组合键 Ctrl+C
awesun-cli desktop key combo abc123xyz --keys ctrl,c
4. 远程文件管理工具
仅在 type=file 的会话中可用。
| 命令 | 描述 |
|---|---|
file ls |
浏览远程设备文件目录，支持路径和关键词过滤 |
file mkdir |
在远程设备上创建新文件夹 |
file rm |
删除远程文件或文件夹（-r 递归删除） |
file mv |
重命名/移动远程文件或文件夹 |
file transfer |
创建文件传输任务，支持上传(up)和下载(down) |
file transfer status |
查询文件传输任务的状态和进度 |
file transfer cancel |
取消正在进行的文件传输任务 |
典型使用流程（文件传输）：
# 1. 建立文件会话
awesun-cli session connect --type file --remote-id 12345
# 返回 session_id: file_session_001
# 2. 浏览远程目录
awesun-cli file ls file_session_001 --path /home/user/documents
# 3. 下载文件
awesun-cli file transfer file_session_001 \
--type down \
--remote /home/user/documents/report.pdf \
--local ~/Downloads/report.pdf
# 返回 transfer_id
# 4. 监控传输进度
awesun-cli file transfer status file_session_001 --transfer-id <transfer-id>
# 5. 如需取消传输
awesun-cli file transfer cancel file_session_001 --transfer-id <transfer-id>
注意事项：
- 文件操作仅在
type=file的会话中可用 - 删除文件/文件夹前，先用
file ls确认路径正确 - 传输任务创建后需定期查询状态直到完成或失败
5. 远程命令执行工具
| 命令 | 描述 |
|---|---|
session exec |
在远程设备上执行命令。需先建立 cmd(Windows) 或 ssh(Linux/Mac) 会话 |
典型使用流程：
# 1. 建立 SSH 会话
awesun-cli session connect --type ssh --remote-id 12345
# 返回 session_id: ssh_session_001
# 2. 执行远程命令
awesun-cli session exec ssh_session_001 "ls -la /var/log"
# 3. 获取 SSH 连接地址（用于手动连接）
awesun-cli ssh address ssh_session_001
6. 端口转发工具
| 命令 | 描述 |
|---|---|
forward config |
配置端口转发通道，将远程设备端口映射到本地 |
典型使用流程：
# 1. 建立端口转发会话
awesun-cli session connect --type forward --remote-id 12345
# 返回 session_id: forward_session_001
# 2. 配置端口转发（通过 channels JSON 配置）
awesun-cli forward config forward_session_001 --channels '{"local_port":18080,"remote_port":8080}'
# 现在可以通过 localhost:18080 访问远程设备的 8080 端口
完整场景示例
场景1：远程桌面自动化操作
# 1. 搜索设备
awesun-cli device search "办公室电脑" --limit 1
# 假设返回 remote_id: 12345
# 2. 建立远程桌面连接
awesun-cli session connect --type desktop --remote-id 12345
# 返回 session_id: desktop_session_001
# 3. 截图查看当前状态
awesun-cli session screenshot desktop_session_001 --output /tmp/screen.png
# 4. Read 工具读取截图内容，识别目标坐标
# 5. 执行一系列自动化操作
# 点击开始菜单 (左下角，归一化坐标)
awesun-cli desktop mouse click desktop_session_001 --x 0.01 --y 0.99 --button left
# 输入"记事本"搜索
awesun-cli desktop type desktop_session_001 "notepad" --delay 100
# 按回车打开
awesun-cli desktop key combo desktop_session_001 --keys enter
# 6. 完成后断开连接
awesun-cli session disconnect desktop_session_001
场景2：批量文件下载
# 1. 搜索设备
awesun-cli device search "服务器" --limit 1
# 假设返回 remote_id: 12345
# 2. 建立文件会话
awesun-cli session connect --type file --remote-id 12345
# 返回 session_id: file_session_001
# 3. 浏览远程日志目录
awesun-cli file ls file_session_001 --path /var/logs
# 4. 下载日志文件
awesun-cli file transfer file_session_001 \
--type down \
--remote /var/logs/app.log \
--local ~/Downloads/app.log
# 返回 transfer_id: transfer_001
# 5. 监控传输状态直到完成
awesun-cli file transfer status file_session_001 --transfer-id transfer_001
场景3：远程诊断
# 1. 搜索设备并建立 SSH 会话
awesun-cli session connect --type ssh --remote-id 12345
# 返回 session_id: ssh_session_001
# 2. 执行诊断命令
awesun-cli session exec ssh_session_001 "df -h"
awesun-cli session exec ssh_session_001 "free -m"
awesun-cli session exec ssh_session_001 "top -b -n 1 | head -20"
awesun-cli session exec ssh_session_001 "systemctl status nginx"
# 3. 断开连接
awesun-cli session disconnect ssh_session_001
工具调用最佳实践
1. ID 依赖与上下文管理
- 信任上下文：对话历史中已获取的 remote_id 或 session_id 视为有效，避免重复查询
- 链路完整性：确保命令输出中的 ID 准确传递到后续命令，避免断链
- 异常重试：仅当命令返回 ID 无效错误时，才重新执行查询流程
2. 会话建立准则
- 会话复用优先：执行远程操作前，先检查上下文是否有有效 session_id
- 桌面类型限制：仅在
type=desktop的会话中使用desktop系列命令 - 文件类型限制：仅在
type=file的会话中使用file系列命令 - 命令执行限制：
session exec仅在type=cmd或type=ssh的会话中可用
3. 截图策略
- 首次操作或界面变更后必须截图
- 连续操作且界面未变时禁止重复截图，基于上一次截图坐标直接执行
- 单次截图应尽可能识别出当前任务所需的所有目标坐标
4. 登录前置检查
- 所有命令执行前必须确认已登录（
awesun-cli login status） - 未登录时先引导用户扫码或用户名密码登录
全局选项
| 选项 | 说明 |
|---|---|
--output / -o |
输出格式: table（默认）, json, yaml, wide |
--verbose / -v |
详细日志模式，用于调试 |
--help / -h |
显示命令帮助 |
环境信息
- 日志目录:
~/awesun-cli/log/ - 后台守护进程: 需要时自动启动，可通过
awesun-cli stop-daemon停止 - 清除缓存:
awesun-cli config clean-cache - 输出结果解析推荐使用
-o json格式
辅助参考
截图与桌面控制
执行桌面自动化操作需要先从截图中识别目标坐标，详细指南参见：
references/ui-locator.md: 从截图中识别 UI 元素位置的视觉引导，输出归一化坐标references/ui-patterns.md: UI 元素特征对照表（按钮、输入框、图标、导航等识别要点）
坐标工具
# 像素坐标 → 归一化坐标
python3 scripts/coordinates.py norm <pixel_x> <pixel_y> <width> <height>
# 验证归一化坐标有效性
python3 scripts/coordinates.py validate <x> <y>