# AgentScope Skills Demo

这是一个最小可运行示例，演示如何：

- 使用 llama.cpp 的 OpenAI 兼容接口连接 `OpenAIChatModel`
- 为 `ReActAgent` 注册多个本地 skill
- 让智能体在任务中优先使用 skill，并通过 Python 工具执行代码
- 在 Windows 桌面上执行截图、点击、输入等 GUI 自动化操作

## 文件结构

```text
.
├── demo_with_skills.py
├── requirements.txt
└── skills/
    ├── python_hello_skill/
    │   └── SKILL.md
    └── windows_gui_operator/
        └── SKILL.md
```

运行 GUI skill 后，截图会保存在 `artifacts/screenshots/` 目录。

## 安装依赖

```bash
pip install -r requirements.txt
```

## 运行示例

```bash
python demo_with_skills.py
```

默认会进入交互式对话模式，你可以在终端中持续输入消息与模型对话：

```text
user> 你好
user> 请用 Python 打印 Hello World
user> /exit
```

脚本默认会隐藏模型的 thinking 过程，只显示最终可见回复。如果你想调试 thinking 输出，可以运行：

```bash
python demo_with_skills.py --show-thinking
```

默认模式下，工具调用过程中的 `tool_use` 和 `tool_result` JSON 也会被隐藏，只保留最终自然语言回复。

当前版本会以可读形式打印 ReAct 过程，例如 `Action` 和 `Observation`，但不会直接输出原始 thinking 块和原始 JSON。

如果你想检查模型每一轮 assistant 原始返回了什么 block，可以运行：

```bash
python demo_with_skills.py --debug-model-output
```

这会额外打印每轮模型的原始 content blocks，便于确认截图返回后模型是否真的在消费图片相关内容。

## Windows GUI Skill

新增的 `windows_gui_operator` skill 会要求智能体按 ReAct 方式执行 GUI 操作：

- 先获取当前活动窗口并截图
- 再执行鼠标或键盘动作
- 关键步骤后再次截图确认
- 对输入类操作，必要时通过剪贴板做结果确认

当前脚本已注册以下 GUI 工具：

- `save_desktop_screenshot`
- `get_mouse_position`
- `left_click`
- `type_text`
- `press_keys`
- `hotkey`
- `wait_seconds`
- `get_active_window_title`
- `get_clipboard_text`

如果当前模型支持多模态，`save_desktop_screenshot` 会把本地截图文件同时作为图片结果返回给模型，模型可以直接基于截图继续判断下一步动作。

GUI skill 默认采用“观察 -> 执行一个最小动作 -> 复查 -> 必要时重试”的单步闭环，而不是预先规划固定长步骤后一路执行。

当前版本对 Windows GUI 的约束是：桌面任务必须通过键盘和鼠标完成，不提供直接启动应用或直接打开网址的非 GUI 工具。

如果你只想发送一条消息并立即退出，可以运行：

```bash
python demo_with_skills.py --message "请用 Python 打印 Hello World"
```

如果你只想确认 skill 注册是否成功，而不立即调用远程模型，可以运行：

```bash
python demo_with_skills.py --skip-agent-run
```

如果你需要替换 llama.cpp 服务地址或模型名，可以通过环境变量覆盖：

```bash
set LLAMA_CPP_BASE_URL=http://127.0.0.1:8000/v1
set LLAMA_CPP_MODEL_NAME=your-model-name
set LLAMA_CPP_API_KEY=EMPTY
python demo_with_skills.py
```

## 说明

示例脚本默认使用以下 llama.cpp OpenAI 兼容接口配置，并支持通过环境变量覆盖：

- Base URL: `http://yyplab.site:8033/v1`
- Model: `Qwen3.5-122B-A10B-Q4_K_M-00001-of-00003.gguf`
- API Key: `EMPTY`

如果你本地的 AgentScope 版本中，文件读取工具名称与脚本里的候选名称不同，请在 `demo_with_skills.py` 中补充对应函数名。