---
name: sophnet-oss
description: Convert a local file path to a downloadable URL (valid for 24 hours). Use when users want to turn a file path into a shareable link, get a URL for a file, or need a temporary URL to access a local file.
---

# File Path to URL

将本地文件路径转换为可访问的下载 URL，链接有效期为 24 小时。

## Signed URL（签名链接）完整性

`DOWNLOAD_URL` 由 OSS **预签名**生成，**查询串（`?` 及之后的参数）即访问凭证**。在本次 skill 的全流程中：

- **必须**使用脚本输出的 `DOWNLOAD_URL` **完整字符串**（一字不改）填入下文展示模板中的下载链接，或原样写入下游。
- **禁止**去掉 `?` 及后续查询参数、禁止截取签名片段、禁止尝试「换成更短的裸 URL」或做任何 URL「美化」。
- 签名 URL 的参数中，**`x-oss-signature-version` 和 `x-oss-credential` 不可省略**，分别为签名算法的版本标识和访问凭证标识，缺失任一参数均会导致签名校验失败。
- 若裸域名路径在无签名时可访问，那是偶然行为；本 skill **不以裸链为准**，仅以脚本输出的带签名 URL 为准。
- 向用户展示时沿用下文「转换成功后」的固定格式即可；**不要改模板结构**，只保证链接内容为完整签名 URL。

## Processing Mode

**STRICT SERIAL PROCESSING ONLY** - This skill must execute in a single, sequential operation:

- **NO sub-tasks** - Never spawn background sessions or use sessions_spawn
- **NO task splitting** - Complete the conversion in one continuous run
- **NO parallel execution** - Convert one file at a time

## Prerequisites

- Python packages: sophnet-tools

## Usage

When a user wants to convert a file path to a URL:

1. **Extract file path** from user input or recent logs (see Path Extraction below).
2. **Run the script** using uv from workspace or skill directory:

```bash
uv run --with sophnet-tools \
  python {baseDir}/scripts/upload_file.py \
  --file /absolute/path/to/file \
  --timeout 120
```

## Parameters

- `--file`: 要转换为 URL 的本地文件路径（必填）
- `--timeout`: 请求超时秒数（默认 120，大文件可适当增大）

## Output

The script outputs structured key-value pairs:

```
FILE_PATH=/absolute/path/to/file
UPLOAD_STATUS=uploaded
DOWNLOAD_URL=https://...signed-url...
```

On failure:

```
FILE_PATH=/absolute/path/to/file
UPLOAD_STATUS=failed
ERROR=error description
```

**转换成功后，向用户展示为：**

```
文件路径已转换为可访问链接：

文件路径：/absolute/path/to/file
下载链接：https://...signed-url...

⏰ 链接有效期：24小时
```

## Path Extraction

When users provide files through chat, look for log patterns like:

```
Resolved relative path: "media/inbound/images/xxx.pdf" -> "/absolute/path/to/workspace/media/inbound/images/xxx.pdf"
```

Extract the absolute path (right side of `->`) for use with the script.

对于用户提供或引用的文件，优先从上述日志中取解析后的绝对路径，再传入脚本做路径转 URL。

## Example Workflow

User: "把这个文件转成链接" / "给我这个文件的 URL"

1. Extract file path from logs (pattern: `Resolved relative path: "..." -> "/absolute/..."`) or user input
2. Run: `uv run --with sophnet-tools python {baseDir}/scripts/upload_file.py --file /absolute/path/to/file --timeout 120`
3. Parse the output and display the URL to the user

## Notes

- 返回的 URL 有效期为 **24 小时**
- 任意类型文件均可转换（无扩展名限制）
- 大文件可增大 `--timeout`（默认 120 秒）
- 始终使用绝对路径以保证可靠

## ⚠️ FORBIDDEN OPERATIONS

**Do NOT:**

- Spawn sub-agent sessions (sessions_spawn)
- Run multiple parallel conversions
- Split the task into separate operations
- Use background processes

**ONLY:**

- Run the script once with the file path
- Return the URL to the user in a single response
