using-llm

<!--zh
# 大模型调用技能
-->
# LLM Calling Skill

<!--zh
获取可用模型列表，并向指定模型发送对话请求，无需任何额外配置。
-->
List available models and send chat requests to any of them — no extra configuration required.

<!--zh
## 核心能力
-->
## Core Capabilities

<!--zh
- 获取当前可用的模型列表
- 以 OpenAI 格式发送对话请求（非流式）
-->
- List currently available models
- Send chat completion requests in OpenAI format (non-streaming)

<!--zh
## 使用指导

需要在代码中调用大模型时，可以使用 `sdk.llm` 提供的 SDK 函数。执行方式有两种：

- **方式一**：使用 `run_python_snippet` 工具直接执行代码片段
- **方式二**：将代码写入 `.py` 文件后，使用 `shell_exec` 执行

`create_openai_sync_client` 是 Python SDK 函数，**不是工具名称**，需要在代码中 import 后使用：

```python
# 方式一：run_python_snippet
run_python_snippet(
    python_code="""
from sdk.llm import create_openai_sync_client
client = create_openai_sync_client()
...
""",
    script_path="temp_llm_xxx.py",
    timeout=300,
)

# 方式二：写文件 + shell_exec
# 先用 write_file 写入脚本，再用 shell_exec 执行
shell_exec("python scripts/my_llm_script.py")
```

调用大模型时容易超时，建议根据任务复杂度适当调大超时时间，例如单次调用可设 `timeout=120`，多模型对比或批量推理建议设 `timeout=300` 或更大（`shell_exec` 同理）。
-->
## Usage Guide

When you need to call an LLM in code, use the SDK functions from `sdk.llm`. There are two ways to execute the code:

- **Option 1**: Use the `run_python_snippet` tool to execute a code snippet directly
- **Option 2**: Write the code to a `.py` file, then execute it with `shell_exec`

`create_openai_sync_client` is a Python SDK function, **not a tool name** — import and use it inside your code:

```python
# Option 1: run_python_snippet
run_python_snippet(
    python_code="""
from sdk.llm import create_openai_sync_client
client = create_openai_sync_client()
...
""",
    script_path="temp_llm_xxx.py",
    timeout=300,
)

# Option 2: write a .py file, then run with shell_exec
# First write the script with write_file, then execute:
shell_exec("python scripts/my_llm_script.py")
```

LLM calls can take a while — consider increasing the timeout based on complexity, e.g. `timeout=120` for a single call, `timeout=300` or more for multi-model comparisons or batch inference (applies to both options).

<!--zh
## 快速开始
-->
## Quick Start

<!--zh
### 第一步：获取可用模型列表

不确定模型 ID 时，先查询可用模型：
-->
### Step 1: List available models

When unsure of the model ID, query available models first:

```python
run_python_snippet(
    python_code="""
import json
from sdk.llm import create_openai_sync_client

client = create_openai_sync_client()
models = client.models.list()
print(json.dumps([{"id": m.id} for m in models.data], ensure_ascii=False, indent=2))
""",
    script_path="temp_list_models.py",
)
```

<!--zh
输出示例：
-->
Example output:

```json
[
  {"id": "claude-3-5-sonnet-20241022"},
  {"id": "gpt-4o"},
  {"id": "deepseek-v3"}
]
```

<!--zh
### 第二步：发送对话请求

使用真实的模型 ID 发送对话：
-->
### Step 2: Send a chat request

Use a real model ID to send a chat:

```python
run_python_snippet(
    python_code="""
from sdk.llm import create_openai_sync_client

client = create_openai_sync_client()

response = client.chat.completions.create(
    model="<模型ID>",
    messages=[
        {"role": "system", "content": "你是一个助手"},
        {"role": "user", "content": "你好"},
    ],
    extra_body={"thinking": {"type": "disabled"}},
)

print(response.choices[0].message.content)
""",
    script_path="temp_chat.py",
    timeout=120,
)
```

<!--zh
## 视觉理解 — 在消息中传入图片

使用支持视觉的模型时，可以在消息中附带图片。SDK 提供两种方式将工作区文件转换为 URL：

| 函数 | 适用场景 |
|---|---|
| `file_to_url(path)` | **优先使用**，直接返回可访问的 URL |
| `image_to_base64(path)` | `file_to_url` 失败时的备选方案，将图片编码为 base64 |

两者均支持直接传入 http/https URL，此时原样返回，不做任何处理。

> **重要 — `image_to_base64` 返回值说明**：该函数已返回完整的 data URL，格式为 `data:image/jpeg;base64,/9j/4AAQ...`，直接将返回值用作 `url` 字段即可。**禁止再手动拼接 `data:image/jpeg;base64,` 前缀**，否则会报 `Invalid base64 image_url` 错误。
-->
## Vision — Attach Images in Messages

When using a vision-capable model, images can be included in messages. The SDK provides two ways to convert a workspace file to a URL:

| Function | Use Case |
|---|---|
| `file_to_url(path)` | **Use this first** — returns a directly accessible URL |
| `image_to_base64(path)` | Fallback if `file_to_url` fails — encodes the image as base64 |

Both accept http/https URLs as input and return them unchanged.

> **IMPORTANT — `image_to_base64` return value**: The function already returns a complete data URL string like `data:image/jpeg;base64,/9j/4AAQ...`. Use the return value directly as `url`. **Do NOT prepend `data:image/jpeg;base64,` again** — doing so will cause an `Invalid base64 image_url` error.

```python
run_python_snippet(
    python_code="""
from sdk.llm import create_openai_sync_client, file_to_url, image_to_base64

client = create_openai_sync_client()

# 优先使用 file_to_url / use file_to_url first
# 路径相对于 .workspace/ 目录 / path is relative to .workspace/
image_url = file_to_url("test/screenshot.png")

# file_to_url 失败时用 image_to_base64 / fallback to image_to_base64
# image_url = image_to_base64("test/screenshot.png")
# image_to_base64 已返回完整 data URL，直接使用，禁止再拼接前缀
# image_to_base64 returns a complete data URL — use it directly, never prepend "data:...;base64," again

response = client.chat.completions.create(
    model="<视觉模型ID>",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": image_url}},
            {"type": "text", "text": "描述这张图片的内容"},
        ],
    }],
    extra_body={"thinking": {"type": "disabled"}},
)

print(response.choices[0].message.content)
""",
    script_path="temp_vision.py",
    timeout=120,
)
```

<!--zh
## 参数说明

### `client.chat.completions.create()` 常用参数
-->
## Parameter Reference

### Common Parameters for `client.chat.completions.create()`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `model` | `str` | Yes | <!--zh 模型 ID，使用第一步查询到的真实 ID --> Model ID — use a real ID from Step 1 |
| `messages` | `list` | Yes | <!--zh 对话消息列表，每项含 `role` 和 `content` --> List of messages, each with `role` and `content` |
| `temperature` | `float` | No | <!--zh 采样温度，0~2，默认 1 --> Sampling temperature, 0~2, d