awesun-skill

name	awesun-skill
description	向日葵（AweSun）远程控制 CLI 工具。提供设备列表管理、远程会话管理、远程桌面控制、远程命令执行、远程文件传输、端口转发、远程关机/重启/唤醒等功能。用户提到向日葵、AweSun、远程控制、远程连接、远程桌面、远程文件、远程截图、远程关机时必须使用此 skill。
version	1.0.0
author	Oray

向日葵远程控制

通过 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>