feat(skills): update media-delivery

4cb437ec · Hermes Desktop · 96452f09 · 4cb437ec
Commit 4cb437ec authored Jul 24, 2026 by Hermes Desktop
Hide whitespace changes
Inline Side-by-side

Showing with 72 additions and 52 deletions

media-delivery/SKILL.md
+72 -52

No files found.
--- a/media-delivery/SKILL.md
+++ b/media-delivery/SKILL.md
@@ -29,20 +29,68 @@ Hermes detects the `MEDIA:` prefix, validates the path against security rules, a
 | 优先级 | 方式 | 语法 | 适用场景 |
 |-------|------|------|---------|
-| **第一选择** | MEDIA 协议 | `MEDIA:/path/to/file` | 原生附件，支持 cache 和 workspace |
+| **第一选择** | MEDIA 协议 | `MEDIA:/path/to/file` | 原生附件，仅限 workspace |
 | **第二选择** | Markdown 链接 | `[name](/path/to/file)` | MEDIA 不可用时的降级方案，仅限 workspace |
+**⛔ 图片语法 `![]()` 仅用于图片文件：**
+```markdown
+# ✅ 图片文件 - 可以用图片语法
+![图片](/path/to/image.jpg)
+![截图](/path/to/screenshot.png)
+# ❌ 非图片文件 - 不要用图片语法，用 MEDIA 协议
+MEDIA:/path/to/document.pdf
+MEDIA:/path/to/spreadsheet.xlsx
+# ✅ 备选方案 - Markdown 链接
+[文档.pdf](/path/to/document.pdf)
+[表格.xlsx](/path/to/spreadsheet.xlsx)
+```
 ### 2. 空格规则
-**下载路径中绝对不能包含空格，必须将空格替换为下划线 `_`。**
+**MEDIA 协议和 Markdown 链接的路径中都不能包含裸空格。**
+处理方式（按优先级）：
+| 方案 | 做法 | 适用场景 |
+|------|------|---------|
+| **A. 复制并重命名（推荐）** | 复制文件，将空格替换为 `_` | MEDIA 和 Markdown 都适用 |
+| **B. 尖括号包裹** | 用 `<>` 包裹完整路径 | 仅限 Markdown 链接 |
+#### 方案 A：复制并重命名（推荐）
 ```bash
-# ❌ 禁止
+# 复制时将空格替换为下划线
-MEDIA:/path/my report.pdf
+cp "/原路径/my report.pdf" ~/.hermes/workspace/my_report.pdf
+# MEDIA 协议
+MEDIA:~/.hermes/workspace/my_report.pdf
+# Markdown 链接
+[my_report.pdf](/home/user/.hermes/workspace/my_report.pdf)
+```
+#### 方案 B：尖括号包裹（仅限 Markdown 链接）
+**关键：尖括号必须包裹整个路径，右括号 `)` 必须在尖括号 `>` 之后。**
+```markdown
+# ✅ 正确格式
+[文件名](</完整/路径/含空格/的文件.pdf>)
+# ❌ 错误格式 - 括号位置错误
+[文件名](</完整/路径/含空格) 的文件.pdf>
+```
+**示例**：
+```markdown
 # ✅ 正确
-cp "/原路径/my report.pdf" ~/.hermes/cache/documents/my_report.pdf
+[西安国际会展中心项目 - 否决条款提取表.xlsx](</Users/user/.hermes/workspace/西安国际会展中心项目 - 否决条款提取表.xlsx>)
-MEDIA:~/.hermes/cache/documents/my_report.pdf
+# ❌ 错误 - 右括号跑到中间
+[西安国际会展中心项目](</Users/user/.hermes/workspace/西安国际会展中心项目) - 否决条款提取表.xlsx>
 ```
 ### 3. 中文和特殊字符
@@ -59,23 +107,19 @@ MEDIA:~/.hermes/cache/documents/my_report.pdf
 ## 1. 允许的文件目录
-文件必须位于以下目录之一：
+文件必须位于以下目录之一（**只有这两个目录有权限**）：
-| 目录 | 用途 | MEDIA | Markdown |
+| 目录 | 说明 |
-|-----|------|-------|----------|
+|-----|------|
-| `~/.hermes/cache/images/` | 图片 | ✅ | ⚠️ |
+| `~/.hermes/workspace/` | 全局 workspace |
-| `~/.hermes/cache/audio/` | 音频 | ✅ | ⚠️ |
+| 会话所在的 workspace | 当前会话的工作目录 |
-| `~/.hermes/cache/videos/` | 视频 | ✅ | ⚠️ |
-| `~/.hermes/cache/documents/` | 文档 | ✅ | ⚠️ |
-| `~/.hermes/workspace/` | **工作区（推荐）** | ✅ | ✅ |
-| `~/.hermes/browser_screenshots/` | 截图 | ✅ | ⚠️ |
-| `~/.hermes/{image,audio,video,document}_cache/` | Legacy 缓存 | ✅ | ⚠️ |
-**推荐**：MEDIA 协议用 cache 或 workspace，Markdown 链接仅用 workspace。
+**MEDIA 协议和 Markdown 链接都只能使用上述目录。**
 ### 禁止的目录
 以下目录永远被拒绝：
+- `~/.hermes/cache/` 及其所有子目录（images、audio、videos、documents 等）
 - `/etc`, `/proc`, `/sys`, `/dev`, `/root`, `/boot`, `/var/log`, `/var/lib`, `/var/run`
 - `~/.ssh/`, `~/.aws/`, `~/.gnupg/`, `~/.kube/`, `~/.docker/`
 - `~/.hermes/.env`, `~/.hermes/auth.json` 等凭据文件
@@ -93,10 +137,10 @@ MEDIA:~/.hermes/cache/documents/my_report.pdf
 ```bash
 # 终端（git-bash）中可以正常使用
-cp /c/Users/Administrator/report.pdf ~/.hermes/cache/documents/
+cp /c/Users/Administrator/report.pdf ~/.hermes/workspace/
 # 响应中必须用 Windows 格式
-MEDIA:C:/Users/Administrator/.hermes/cache/documents/report.pdf
+MEDIA:C:/Users/Administrator/.hermes/workspace/report.pdf
 ```
 ---
@@ -118,7 +162,7 @@ Gateway 自动根据扩展名检测内容类型：
 | 平台 | MEDIA 支持 | 文件大小限制 | 备注 |
 |------|-----------|-------------|------|
-| 微信/WeChat | ✅ | ~100MB | 路径验证严格，必须用 cache 目录 |
+| 微信/WeChat | ✅ | ~100MB | 路径验证严格，必须用 workspace 目录 |
 | Telegram | ✅ | ~2GB | 完全支持 |
 | Discord | ✅ | 25MB (免费) / 500MB (Nitro) | 可能有文件类型限制 |
 | Slack | ✅ | 平台限制 | 可能有文件类型限制 |
@@ -131,53 +175,29 @@ Gateway 自动根据扩展名检测内容类型：
 ### 步骤 1：复制文件到允许目录
 ```bash
-# 文档
+# 复制到全局 workspace
-cp /path/to/file ~/.hermes/cache/documents/
+cp /path/to/file ~/.hermes/workspace/
-# 图片
+# 或复制到会话所在的 workspace
-cp /path/to/image ~/.hermes/cache/images/
+cp /path/to/file /path/to/session/workspace/
-# 音频/视频
-cp /path/to/audio ~/.hermes/cache/audio/
-cp /path/to/video ~/.hermes/cache/videos/
 ```
 ### 步骤 2：发送 MEDIA 指令
 **Linux/macOS:**
 ```
-MEDIA:~/.hermes/cache/documents/your-file.txt
+MEDIA:~/.hermes/workspace/your-file.txt
 ```
 **Windows:**
 ```
-MEDIA:C:/Users/YourUsername/.hermes/cache/documents/your-file.txt
+MEDIA:C:/Users/YourUsername/.hermes/workspace/your-file.txt
 ```
 **禁止使用：**
- `MEDIA:/c/Users/...`（git-bash 格式）
+- `MEDIA:/c/Users/...`（git-bash 格式，Windows 上会失败）
- `MEDIA:~/...`（波浪号不可靠）
 - `MEDIA:./...`（相对路径）
+- `MEDIA:~/.hermes/cache/...`（cache 目录无权限）
---
-## 6. 常见问题排查
-| 问题 | 原因 | 解决方案 |
-|------|------|---------|
-| `Skipping unsafe MEDIA directive path` | Windows 路径格式错误 | 使用 `C:/...` 而非 `/c/...` |
-| 文件存在但无法下载 | 路径含空格 | 复制时将空格替换为 `_` |
-| 文件找不到 | 不在允许目录 | 移到 cache 或 workspace |
-| `File is outside the session and Hermes workspaces` | 不在 workspace | 用 MEDIA 协议或拷贝到 workspace |
-| MEDIA 路径返回纯文本 | Gateway 未初始化 | 等待 5-10 秒或 `hermes gateway restart` |
-### 诊断步骤
-1. **检查 gateway 日志**：`grep "MEDIA\|media" ~/.hermes/logs/gateway.log`
-2. **验证文件存在**：`python -c "import pathlib; print(pathlib.Path('path').resolve(strict=True))"`
-3. **检查路径格式**（Windows）：必须是 `C:/...` 不是 `/c/...`
-4. **验证目录**：文件必须在允许的目录下
-5. **重启 gateway**：`hermes gateway restart`
 ---