feat(skills): update media-delivery

media-delivery/SKILL.md

@@ -21,6 +21,17 @@ Hermes detects the `MEDIA:` prefix, validates the path against security rules, a
 
 ---
 
+## Quick Reference (常见问题速查)
+
+| 问题现象 | 可能原因 | 解决方案 |
+|---------|---------|---------|
+| `Skipping unsafe MEDIA directive path` | Windows 路径格式错误 | 使用 `C:/...` 而非 `/c/...` |
+| 文件存在但无法下载 | 中文/空格/特殊字符 | 用尖括号 `](</path/文件.docx>)` |
+| 文件找不到 | 不在允许目录 | 移到 `~/.hermes/cache/<type>/` |
+| 下载失败无报错 | 文件名含中文/空格 | 重命名为英文 或 用尖括号 |
+
+---
+
 ## 1. Path Validation
 
 The gateway's `validate_media_delivery_path()` function enforces:
@@ -93,6 +104,82 @@ MEDIA:C:/Users/Administrator/.hermes/cache/documents/report.pdf
 
 ---
 
+## 2.5 空格与中文文件名处理 (CRITICAL)
+
+**文件名包含空格、中文或特殊字符时，Markdown 链接无法正确解析。**
+
+### 问题示例
+
+```markdown
+# ❌ 失败 - 中文文件名
+[申请表.docx](/home/lcai/.hermes/cache/documents/申请表.docx)
+
+# ❌ 失败 - 空格文件名  
+[my report.pdf](/home/lcai/.hermes/cache/documents/my report.pdf)
+
+# ✅ 成功 - 使用尖括号包裹
+[申请表.docx](</home/lcai/.hermes/cache/documents/申请表.docx>)
+[my report.pdf](</home/lcai/.hermes/cache/documents/my report.pdf>)
+```
+
+### 规则总结
+
+| 文件名特征 | 无尖括号 | 有尖括号 | 推荐做法 |
+|-----------|---------|---------|---------|
+| 纯英文无空格 | ✅ | ✅ | 任意格式 |
+| 英文有空格 | ❌ | ✅ | **必须用尖括号** |
+| 含中文 | ❌ | ✅ | **必须用尖括号** |
+| 含特殊字符 `()[]#?` | ❌ | ✅ | **必须用尖括号** |
+
+### 三种解决方案
+
+#### 方案 A: 使用尖括号（推荐用于中文文件名）
+```markdown
+[2026 年申请表](</home/lcai/.hermes/cache/documents/2026 年申请表.docx>)
+```
+
+#### 方案 B: 重命名为英文（最佳兼容性）
+```bash
+# 重命名文件
+mv "2026 年申请表.docx" "2026-Application-Form.docx"
+```
+然后发送：
+```markdown
+[2026 年申请表](/home/lcai/.hermes/cache/documents/2026-Application-Form.docx)
+```
+
+#### 方案 C: URL 编码（高级）
+```python
+import urllib.parse
+filename = "2026 年申请表.docx"
+encoded = urllib.parse.quote(filename, safe='')
+# 输出: 2026%20%E5%B9%B4%E7%94%B3%E8%AF%B7%E8%A1%A8.docx
+```
+```markdown
+[申请表](/home/lcai/.hermes/cache/documents/2026%20%E5%B9%B4%E7%94%B3%E8%AF%B7%E8%A1%A8.docx)
+```
+
+### 最佳实践
+
+1. **优先使用英文文件名**：避免所有兼容性问题
+   ```bash
+   # 推荐命名
+   mv "2026 年湖南省未来产业创新发展优秀典型案例申请表.docx" \
+      "2026-Hunan-Innovation-Application.docx"
+   ```
+
+2. **如果必须用中文，始终用尖括号**：
+   ```markdown
+   [文件](</path/to/文件.docx>)  # ✅ 正确
+   [文件](/path/to/文件.docx)    # ❌ 错误
+   ```
+
+3. **避免特殊字符**：
+   - ✅ `2026-申请表_v1.docx`
+   - ❌ `2026 年 (最终版)[确认].docx`
+
+---
+
 ## 3. File-Type Detection
 
 The gateway auto-detects the content type from the file extension:
@@ -313,7 +400,7 @@ MEDIA:C:/Users/YourUsername/.hermes/cache/documents/data.csv
 
 ## 6. Diagnostic Checklist
 
-If MEDIA delivery fails:
+If MEDIA delivery fails, check in this order:
 
 1. **Check gateway logs**: 
    ```bash
@@ -330,9 +417,19 @@ If MEDIA delivery fails:
 
 4. **Verify location**: file must be under `~/.hermes/cache/<type>/` or another safe root
 
-5. **Check file permissions**: must be a regular file (not a symlink to a denied location)
+5. **Check filename for Chinese/special characters**:
+   - If filename contains 中文、空格 or `()[]#?`, **must use angle brackets**:
+     ```markdown
+     [文件](</path/to/文件.docx>)
+     ```
+   - Or rename to English:
+     ```bash
+     mv "文件.docx" "file.docx"
+     ```
+
+6. **Check file permissions**: must be a regular file (not a symlink to a denied location)
 
-6. **Try restarting gateway**: 
+7. **Try restarting gateway**: 
    ```bash
    hermes gateway restart
    ```

media-delivery/references/windows-media-path-debugging.md

+# Windows MEDIA Protocol — Reproduction & Debugging
+
+> **Source:** conversation about file delivery issues on Windows/Linux (2026-07-15, 2026-07-22)
+> **Symptoms:** 
+>   - Windows: "Skipping unsafe MEDIA directive path" 
+>   - Linux/Windows: Chinese filename files fail to download via Markdown links
+
+## Issue 1: Windows Path Format (Path.resolve() Quirk)
+
+### Reproduction Steps
+
+1. File created at `C:\Users\Administrator\markdown-test.md`
+2. Sent `MEDIA:/c/Users/Administrator/markdown-test.md` — **rejected**
+3. Copied to `/tmp/markdown-test.md`, sent `MEDIA:/tmp/markdown-test.md` — **rejected** (not in cache dir)
+4. Copied to `~/.hermes/cache/documents/markdown-test.md`, sent `MEDIA:/c/Users/Administrator/.hermes/cache/documents/markdown-test.md` — **rejected**
+5. Finally determined via log inspection that Python's `Path.resolve()` on Windows treats `/c/Users/` as a **relative path** (`\c\Users\...` off C: drive)
+
+### Key Log Output
+
+```
+WARNING gateway.platforms.base: Skipping unsafe MEDIA directive path: /c/Users/Administrator/some-file.md
+```
+
+### Verification Script
+
+```python
+# Run this to check if a path resolves on your Windows machine
+from pathlib import Path
+
+path = Path("C:/Users/Administrator/.hermes/cache/documents/test.md")
+try:
+    resolved = path.resolve(strict=True)
+    print(f"✅ Resolves to: {resolved}")
+except FileNotFoundError:
+    print(f"❌ File not found (Path sees: {path})")
+```
+
+### Correct vs Incorrect Paths (Windows)
+
+| Format | Terminal (bash) | Python/Validation | Works? |
+|--------|-----------------|-------------------|--------|
+| `/c/Users/...` | ✅ Yes | ❌ Relative path | ❌ |
+| `C:/Users/...` | ✅ Yes | ✅ Absolute path | ✅ |
+| `C:\Users\...` | ⚠️ Needs escaping | ✅ Absolute path | ✅ |
+| `~/Users/...` | ⚠️ Depends on shell | ❌ Not absolute | ❌ |
+
+### Validated Working Approach (Windows)
+
+```bash
+# 1. Copy to cache directory
+cp /path/to/file ~/.hermes/cache/documents/
+
+# 2. Send with Windows path format (NOT /c/... format)
+#    In your response: MEDIA:C:/Users/<user>/.hermes/cache/documents/file.md
+```
+
+---
+
+## Issue 2: Chinese Filenames / Special Characters (Markdown Parsing)
+
+### Symptom
+
+File exists, MEDIA path is valid, but user cannot download the file via Markdown link.
+
+### Root Cause
+
+Markdown parsers struggle with paths containing:
+- Chinese characters (中文)
+- Spaces
+- Special characters (`()`, `[]`, `#`, `?`, etc.)
+
+### Reproduction
+
+```markdown
+# ❌ Fails - Chinese filename without angle brackets
+[2026 年申请表.docx](/home/lcai/.hermes/cache/documents/2026 年申请表.docx)
+
+# ✅ Works - Same filename with angle brackets
+[2026 年申请表.docx](</home/lcai/.hermes/cache/documents/2026 年申请表.docx>)
+```
+
+### Verification Steps
+
+1. **Check file exists**:
+   ```bash
+   ls -la "/home/lcai/.hermes/cache/documents/2026 年申请表.docx"
+   ```
+
+2. **Test Python path resolution**:
+   ```python
+   from pathlib import Path
+   path = Path("/home/lcai/.hermes/cache/documents/2026 年申请表.docx")
+   print(f"Exists: {path.exists()}")
+   print(f"Resolved: {path.resolve()}")
+   ```
+
+3. **Try different Markdown formats**:
+   - Without angle brackets: `[name](/path/文件.docx)` ❌
+   - With angle brackets: `[name](</path/文件.docx>)` ✅
+   - URL-encoded: `[name](/path/2026%20%E5%B9%B4.docx)` ⚠️ (platform-dependent)
+
+### Solutions
+
+#### Option A: Use Angle Brackets (Recommended for Chinese names)
+```markdown
+[申请表](</home/lcai/.hermes/cache/documents/申请表.docx>)
+```
+
+#### Option B: Rename to English (Best for compatibility)
+```bash
+mv "2026 年申请表.docx" "2026-Application-Form.docx"
+```
+Then send:
+```markdown
+[申请表](/home/lcai/.hermes/cache/documents/2026-Application-Form.docx)
+```
+
+#### Option C: URL Encode (Advanced)
+```python
+import urllib.parse
+filename = "2026 年申请表.docx"
+encoded = urllib.parse.quote(filename, safe='')
+print(f"Encoded: {encoded}")
+# Output: 2026%20%E5%B9%B4%E7%94%B3%E8%AF%B7%E8%A1%A8.docx
+```
+Then use in Markdown:
+```markdown
+[申请表](/home/lcai/.hermes/cache/documents/2026%20%E5%B9%B4%E7%94%B3%E8%AF%B7%E8%A1%A8.docx)
+```
+
+---
+
+## Debugging Checklist
+
+When MEDIA delivery fails, check in this order:
+
+1. **File exists?**
+   ```bash
+   ls -la /path/to/file
+   ```
+
+2. **Correct path format?**
+   - Windows: Must be `C:/...` NOT `/c/...`
+   - Linux: Absolute path required
+
+3. **In allowed directory?**
+   - Must be under `~/.hermes/cache/<type>/` or other safe root
+   - Check: `~/.hermes/cache/documents/`, `~/.hermes/cache/images/`, etc.
+
+4. **Chinese/special characters in filename?**
+   - Try with angle brackets: `](</path/文件.docx>)`
+   - Or rename to English
+
+5. **Check gateway logs**:
+   ```bash
+   hermes gateway logs | grep -i "media\|unsafe\|skip"
+   ```
+
+6. **Test Python resolution**:
+   ```python
+   from pathlib import Path
+   p = Path("/your/path")
+   print(f"Resolved: {p.resolve(strict=True)}")
+   ```
+
+---
+
+## Common Error Messages & Fixes
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Skipping unsafe MEDIA directive path` | Path not in allowed dir OR wrong format (Windows `/c/...`) | Move to cache dir OR use `C:/...` format |
+| `File not found` | Path doesn't resolve correctly | Check file exists, verify path format |
+| Download fails but no error | Chinese/special chars in filename | Use angle brackets `<>` or rename to English |
+| `Not a regular file` | Path is a directory or symlink | Ensure path points to actual file |
+
+---
+
+## Related Documentation
+
+- Main skill: `media-delivery` (see "中文文件名和特殊字符处理" section)
+- Hermes docs: https://hermes-agent.nousresearch.com/docs
\ No newline at end of file

media-delivery/references/windows-medio-path-debugging.md

-# Windows MEDIA Protocol — Reproduction & Debugging
-
-> **Source:** conversation about Weixin file delivery on Windows (2026-07-15)
-> **Symptom:** MEDIA paths always rejected with "Skipping unsafe MEDIA directive path"
-
-## Reproduction Steps
-
-1. File created at `C:\Users\Administrator\markdown-test.md`
-2. Sent `MEDIA:/c/Users/Administrator/markdown-test.md` — rejected
-3. Copied to `/tmp/markdown-test.md`, sent `MEDIA:/tmp/markdown-test.md` — rejected
-4. Copied to `~/.hermes/document_cache/markdown-test.md`, sent `MEDIA:/c/Users/Administrator/.hermes/document_cache/markdown-test.md` — rejected
-5. Finally determined via log inspection that Python's `Path.resolve()` on Windows treats `/c/Users/` as a relative path (`\c\Users\...` off C: drive)
-
-## Key Log Output
-
-```
-WARNING gateway.platforms.base: Skipping unsafe MEDIA directive path: /c/Users/Administrator/some-file.md
-```
-
-## Verification Script
-
-```python
-# Run this to check if a path resolves on your Windows machine
-from pathlib import Path
-
-path = Path("C:/Users/Administrator/.hermes/cache/documents/test.md")
-try:
-    resolved = path.resolve(strict=True)
-    print(f"✅ Resolves to: {resolved}")
-except FileNotFoundError:
-    print(f"❌ File not found (Path sees: {path})")
-```
-
-## Validated Working Approach
-
-```bash
-# 1. Copy to cache directory
-cp /path/to/file ~/.hermes/cache/documents/
-
-# 2. Send with Windows path format
-#    In your response: MEDIA:C:/Users/<user>/.hermes/cache/documents/file.md
-```
-
-## Correct vs Incorrect Paths
-
-| Format | Terminal (bash) | Python/Validation | Works? |
-|--------|-----------------|-------------------|--------|
-| `/c/Users/...` | ✅ Yes | ❌ Relative path | ❌ |
-| `C:/Users/...` | ✅ Yes | ✅ Absolute path | ✅ |
-| `C:\Users\...` | ⚠️ Needs escaping | ✅ Absolute path | ✅ |
-| `~/Users/...` | ⚠️ Depends on shell | ❌ Not absolute | ❌ |