---
name: remote-download-link
description: 必须使用：只要产出了任何实体成果文件（Word/PPT/Excel/PDF、图片、视频、音频、压缩包、APK/EXE、代码包、网页、脚本、报告……），在交付给用户前必须调用本技能，把文件登记进成果库并给出 hynixing 域名的强制下载链接。Hermes / DSH / Codex 三个工具通用。
---

# 远程下载链接（强制交付规范）

> 用户规则（2026-10-06 原话）：**「所有输出的软件以及成果，都可以生成一个对应的远程下载链接」**
> 「该 skill 必须具有强制执行性，只要有产出的成果就必须要调用这个 skill」。
> 本技能在 **Hermes / DSH / Codex** 里都适用，靠同一条命令 + 各自的全局规则强制执行。

## 1. 触发条件（无例外）

**只要本轮产出了任何实体文件**，交付前必须走这一步。包括但不限于：

- 文档类：`.docx .pptx .xlsx .pdf .md .txt`
- 媒体类：`.png .jpg .webp .mp4 .mov .mp3 .wav`
- 分发包：`.zip .7z .tar.gz .apk .exe .msi`
- 代码/网页/脚本：`.py .go .js .html .sh`，以及打包后的源码包
- 任何"能落盘、用户可能要拿走"的成果

**不需要**发的情况只有两种：① 用户明确说"不用给链接"；② 文件属于第 5 节的禁止清单。
**不许**因为"文件小/反正本机能打开/上次发过"就跳过——用户要的是**每一个成果都有一个链接**。

## 2. 一行命令（三个工具都一样）

```bash
/vol1/ai/_scripts/deliver-link <文件绝对路径> "<标题>" "<说明>" ["<分类>"]
```

输出（stdout 最后两行固定是这个格式，可直接 grep）：

```
DOWNLOAD: https://files.hynixing.cn/dl/<id>      ← 强制下载（attachment）
PREVIEW : https://files.hynixing.cn/raw/<id>     ← 浏览器内预览（inline）
```

- 脚本本体：`/vol1/ai/_scripts/deliver-link`（Python，shebang 指向 Hermes 自带解释器；已软链到 `/usr/local/bin/deliver-link`）
- 底层：`/vol1/ai/deliverables/publish.py`（登记到 `/vol1/ai/deliverables/catalog.json`，文件进 `files/<id>/`）
- **按 sha256 去重**：同一份文件重复发布只会返回同一个 id，不会重复占盘，可以放心重复调用。
- 退出码 0 = 成功；非 0 = 失败（文件不存在 / 空文件 / 传了目录）。

### 2.1 沙箱会话（DSH / Codex 的 workspace-write 模式）—— 自动走队列

沙箱会话**写不了** `/vol1/ai/deliverables`（报 `OSError: [Errno 30] Read-only file system`）。
`deliver-link` 遇到这种情况**会自动转队列**，你不需要换命令，照原样跑就行，只是输出变成：

```
QUEUED: <你的工作区>/.deliver-queue/20261006-205342-db57.json
RESULT: <你的工作区>/.deliver-queue/20261006-205342-db57.result.json
```

处理方式：
1. 记下 `RESULT:` 那个路径，**等约 1 分钟**（root 侧巡检器每分钟跑一次，`deliver-queue-drain.py`）；
2. `cat` 那个结果文件 → `{"ok":true,"id":...,"download":"https://files.hynixing.cn/dl/<id>",...}`；
3. 拿到 `download` 后照常交付（绝对路径 + 链接）。最多等 2 分钟；超时就照实报告失败。
4. 想立刻入队不等直发，也可以显式加 `--queue`（队列目录默认 `$PWD/.deliver-queue`）。

## 3. 交付格式（必须同时给两样）

给用户的交付消息里必须包含：

1. **完整绝对路径**（用户明确要求过：发文件必须附绝对路径）
2. **下载链接** `https://files.hynixing.cn/dl/<id>`

示例：

```
文件：/vol1/ai/projects/xxx/报告-2026-10-06.docx
下载：https://files.hynixing.cn/dl/baogao-1a2b3
```

- 大文件（>200MB）加 `--link`（建软链不复制）：`deliver-link <路径> "标题" "说明" --link`
  ⚠ 用 `--link` 时**源文件不能删、不能移**，否则链接失效。
- 需要给用户"能直接点开看"的（图片/PDF/MD）可以再补一条 `/raw/<id>` 预览链接。
- 批量产物：逐个发，或用 `publish.py scan <目录> --cat <分类>` 批量登记后取各 id。

## 4. 登录与访问（给用户说明用）

- 成果库地址：`https://files.hynixing.cn/`
- 打开需要 **Cloudflare Access 邮箱验证码**（`qingru2006@gmail.com`，24 小时内免重复登录）
- 只读、无上传口；链接给谁谁都要过 Access 登录 → **不是公开分享**。用户如果要公开分发，另说。

## 5. 禁止发布（硬规则）

- 任何**密钥/令牌/密码/凭据**（`.env`、`cf.env`、`access/` 下的东西、私钥）
- 含**个人隐私**的文件（聊天记录、身份信息、带定位的照片）
- 临时/中间产物（`/tmp` 下的草稿、日志、`__pycache__`、编译中间文件）
- 空文件（脚本会拒收）

## 6. 失败处理

- 脚本非 0 退出 → **照实报告失败原因**，绝不允许自己拼一个链接糊弄（编造链接 = 严重错误）。
- 常见失败：路径写错（必须绝对路径）、传了目录（先 `zip -r` 打包）、文件为空。
- 服务异常时可先自检：`curl -s http://127.0.0.1:8086/healthz`（本机服务 `deliverd.service`）。

## 7. 自检（发布后可选做一次）

```bash
curl -sI http://127.0.0.1:8086/dl/<id> | grep -iE "HTTP/|content-disposition"
# 期望：200 OK + Content-Disposition: attachment; filename=...
```

## 8. 各工具的落地方式

| 工具 | 怎么执行 | 强制点在哪 |
|---|---|---|
| **Hermes** | 直接 `terminal` 跑 `/vol1/ai/_scripts/deliver-link …` | 技能描述以「必须使用」开头（每轮注入技能索引）+ 长期记忆里有一条强制规则 |
| **DSH** | 跑 bash 命令（本机 root，直接可读 `/vol1/ai/**`） | 全局规则 `/vol1/ai/home/.dsh/AGENTS.md` 的「强制交付」一节 |
| **Codex** | 跑 shell 命令（环境里 `CODEX_HOME=/vol1/ai/agents/codex`） | 全局规则 `/vol1/ai/agents/codex/AGENTS.md` 的「强制交付」一节 |

> 三个工具共用**同一个脚本、同一套 id、同一个成果库** —— 在手机上看到的链接和在电脑上发的链接是同一套。

## 9. 相关

- 成果库运维/换域名：技能 `devops/hermes-deliverables-portal`（`cf-deploy.py`、`selftest-public.py`）
- 成果库服务：`deliverd.service`（Go 单文件，`127.0.0.1:8086`，隧道 `cloudflared-hermes-files`）

## 10. 维护（给 Hermes 自己看）

同一份技能在三个地方各放一份（内容必须一致，改完一起同步）：

```bash
SRC=/vol1/ai/agents/hermes/skills/productivity/remote-download-link/SKILL.md
cp $SRC /vol1/ai/home/.dsh/skills/remote-download-link/SKILL.md        # DSH
cp $SRC /vol1/ai/agents/codex/skills/remote-download-link/SKILL.md     # Codex
md5sum $SRC /vol1/ai/home/.dsh/skills/remote-download-link/SKILL.md /vol1/ai/agents/codex/skills/remote-download-link/SKILL.md
```

强制点（改技能后要确认这三处还在）：

| 位置 | 内容 |
|---|---|
| Hermes | 技能描述以「必须使用」开头 + 长期记忆里有一条「强制·交付链接」 |
| `/vol1/ai/home/.dsh/AGENTS.md` | 「## 强制交付：成果必须发远程下载链接」一节（脚本 `_scripts/install-download-link-rule.py` 幂等追加） |
| `/vol1/ai/agents/codex/AGENTS.md` | 同上 |

队列代发链路（沙箱会话用）：

- 入队：`deliver-link … --queue`（或直发失败自动转队列），请求落 `<工作区>/.deliver-queue/<ts>.json`
- 代发：`/vol1/ai/_scripts/deliver-queue-drain.py`（root），扫描根目录清单 `/vol1/ai/deliverables/queue-roots.txt`，结果写同名 `.result.json`，日志 `/vol1/ai/_logs/deliver-queue.log`
- cron：Hermes 作业「成果库队列代发（每分钟）」，脚本 `scripts/deliver_queue_drain.py`（转发到上面那个真身），`no_agent`、成功静默、失败才告警
- 端到端验收（2026-10-06 已过）：Hermes 直发 ✓｜Codex 直发 ✓｜DSH 沙箱自动队列 ✓（拿到 `dl/dl-test-dsh-46b43`）
