---
name: sophnet-oss
description: 将本地文件路径转换为可下载链接（24小时有效）。当用户要求把文件转成链接、获取文件URL、分享文件时使用。
---

# File Path to URL

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

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

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

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

## 前置条件

- Python 包：`sophnet-tools`（需预先安装在系统 Python 环境中）

## Usage

当用户要求将文件路径转换为 URL 时：

1. **提取文件路径**：从用户输入或日志中提取（见下文「路径提取」）。
2. **运行脚本**：

```bash
python3 {baseDir}/scripts/upload_file.py \
  --file /absolute/path/to/file \
  --timeout 120
```

## Parameters

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

## 输出

脚本输出结构化键值对：

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

失败时：
```
FILE_PATH=/absolute/path/to/file
UPLOAD_STATUS=failed
ERROR=错误描述
```

**转换成功后，向用户展示为（固定模板，不可修改结构）：**

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

文件路径：/absolute/path/to/file
下载链接：<完整 DOWNLOAD_URL，一字不改>

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

## 路径提取

当用户通过聊天提供文件时，从日志中查找以下模式：

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

取 `->` 右侧的绝对路径传入脚本。优先从上述日志中取解析后的路径，再回退到用户输入。

## 示例流程

用户："把这个文件转成链接" / "给我这个文件的 URL"

1. 从日志 pattern（`Resolved relative path: "..." -> "/absolute/..."`）或用户输入提取文件路径
2. 执行：`python3 {baseDir}/scripts/upload_file.py --file /absolute/path/to/file --timeout 120`
3. 解析输出，按固定模板向用户展示下载链接

## 注意事项

- 返回的 URL 有效期为 **24 小时**
- 任意类型文件均可转换（无扩展名限制）
- 大文件可增大 `--timeout`（默认 120 秒）
- 始终使用绝对路径以保证可靠
- **严格串行执行**：禁止并发、禁止拆分子任务、禁止后台运行，一次只转换一个文件
- **不修改签名 URL**：`DOWNLOAD_URL` 必须原样使用，不截取、不"美化"、不修改任何参数

## ⚠️ 禁止操作

- 禁止派生子会话（sessions_spawn）
- 禁止并发转换多个文件
- 禁止将任务拆分为多个步骤
- 禁止使用后台进程
- 禁止修改 `DOWNLOAD_URL` 中的任何字符（含查询参数）
