---
name: oss-asset-uploader
description: 当用户明确要求把公开内容需要的本地图片、音频、视频上传到 OSS，生成公开链接或替换文章素材引用时使用。
---

# 公开媒体上传

保留本地创作能力。程序随本技能维护；账号、bucket、公开域名等留在私有配置中，文章结构读取当前项目，不假定个人旧内容目录。

## 配置和依赖

用 OSS_UPLOAD_ENV_FILE 或 --env-file 指定私有配置。默认先用 ~/.config/oss-asset-upload/.env，缺省兼容已有 ~/.local/share/codex-tools/oss-asset-upload/.env；与业务工作目录无关。明确选择的文件优先于旧进程中的同名变量，不输出凭据。

scripts/upload.sh 优先使用 OSS_UPLOAD_PYTHON，或本机旧上传工具的 Python venv；否则用 python3。依赖版本在 scripts/requirements.txt。缺依赖时说明如何在独立环境安装，不向业务项目安装包。

## 首次配置

需要 Python 3.10+。在独立环境安装 scripts/requirements.txt 中的依赖，并把 OSS_UPLOAD_PYTHON 指向该环境的 Python；不依赖作者机器上的上传工具。配置字段见 [私有配置模板](references/oss-config.env.example)，复制到仓库以外的私有文件并替换占位符，再通过 --env-file 指定。

```bash
SKILL_DIR="<已解压的 oss-asset-uploader 目录>"
python3 -m venv "$HOME/.local/share/skill-envs/oss-asset-uploader"
"$HOME/.local/share/skill-envs/oss-asset-uploader/bin/python" -m pip install -r "$SKILL_DIR/scripts/requirements.txt"
export OSS_UPLOAD_PYTHON="$HOME/.local/share/skill-envs/oss-asset-uploader/bin/python"
"$SKILL_DIR/scripts/upload.sh" --help
```

## 上传

1. 读取用户指定文件与目标文章，核实本次公开素材范围、日期和 slug。
2. 整批预检文件，先用 --dry-run 检查目标对象键和域名。无本地路径时取得可读文件位置；上传私有资料不属于本入口。
3. 按任务授权实际上传；混合批次优先 --output json。成功返回数组，中途失败返回非零和 status/completed/failed/pending 清单。
4. 失败重试复用内容哈希对象键，保留已成功清单；不要因为后续项失败就重新上传或删除全部对象。
5. 按当前站点渲染规则插入引用，保留正文/frontmatter。图片可用 Markdown，音视频支持 HTML；文字与 URL 按各自上下文转义。
6. 按实际内容任务验证公开 URL；上传完成和 HTTP 可访问分别记录。403 要报告权限/CDN 问题，不能写成已公开可用。

```bash
"<本技能目录>/scripts/upload.sh" upload "$FILE" --slug "$SLUG" --date "$DATE" --dry-run --output json
"<本技能目录>/scripts/upload.sh" upload "$FILE" --slug "$SLUG" --date "$DATE" --output json
```

先定位技能目录再替换占位符。不上传 .env、私钥、服务器资料或不在本次公开范围内的文件；不把“保留上传技能”视为对所有附件的上传授权。

本版完成配置定位、批次预检/失败清单、转义与本地 dry-run 回归；没有真实 OSS 上传或公开访问验收。