feat(skills): update media-delivery

media-delivery/SKILL.md

@@ -115,6 +115,47 @@ The gateway auto-detects the content type from the file extension:
 - Voice messages supported via `MEDIA_VOICE` type
 - Path validation is strict — files MUST be in a cache directory and path MUST resolve through Python
 
+### 中文文件名和特殊字符处理 (CRITICAL)
+
+**当文件名包含中文、空格或特殊字符时，Markdown 链接可能无法正确解析。**
+
+#### 问题示例
+```markdown
+[2026 年湖南省未来产业创新发展优秀典型案例申请表.docx](/home/lcai/.hermes/cache/documents/2026 年湖南省未来产业创新发展优秀典型案例申请表.docx)
+```
+❌ **失败**：中文字符导致 Markdown 解析器无法正确识别路径
+
+#### 解决方案：使用尖括号包裹路径
+```markdown
+[2026 年湖南省未来产业创新发展优秀典型案例申请表.docx](</home/lcai/.hermes/cache/documents/2026 年湖南省未来产业创新发展优秀典型案例申请表.docx>)
+```
+✅ **成功**：尖括号 `<>` 告诉 Markdown 解析器这是一个完整的路径字符串
+
+#### 规则总结
+| 文件名类型 | 推荐格式 | 示例 |
+|-----------|---------|------|
+| 纯英文、无空格 | 普通格式 | `[file.pdf](/path/to/file.pdf)` |
+| 包含中文 | **必须用尖括号** | `[文件.docx](</path/to/文件.docx>)` |
+| 包含空格 | **必须用尖括号** | `[my file.pdf](</path/to/my file.pdf>)` |
+| 包含特殊字符 | **必须用尖括号** | `[文件 (1).pdf](</path/to/文件 (1).pdf>)` |
+
+#### 最佳实践
+1. **优先使用英文文件名**：避免兼容性问题
+   ```bash
+   # 重命名文件
+   mv "2026 年湖南省未来产业创新发展优秀典型案例申请表.docx" "2026-Hunan-Innovation-Application.docx"
+   ```
+
+2. **如果必须使用中文文件名，始终用尖括号包裹**：
+   ```markdown
+   [申请表](</home/lcai/.hermes/cache/documents/申请表.docx>)
+   ```
+
+3. **验证文件可访问性**：在发送前检查文件是否存在
+   ```bash
+   ls -la "/home/lcai/.hermes/cache/documents/2026 年湖南省未来产业创新发展优秀典型案例申请表.docx"
+   ```
+
 ### Telegram
 - MEDIA protocol fully supported
 - Images, video, audio, documents all work
@@ -237,22 +278,36 @@ MEDIA:C:/Users/YourUsername/.hermes/cache/documents/data.csv
    - ✅ `error-log-2026-07-22-143052.txt`
    - ❌ `temp.txt`
 
-2. **Clean up old cache files**: Periodically remove files older than 24 hours
+2. **Avoid Chinese/special characters in filenames when possible**:
+   - ✅ `2026-Hunan-Innovation-Application.docx`
+   - ❌ `2026 年湖南省未来产业创新发展优秀典型案例申请表.docx`
+   
+   If you must use Chinese names, **always wrap the path in angle brackets**:
+   ```markdown
+   [申请表](</path/to/申请表.docx>)
+   ```
+
+3. **Clean up old cache files**: Periodically remove files older than 24 hours
    ```bash
    find ~/.hermes/cache -type f -mtime +1 -delete
    ```
 
-3. **Verify file exists before sending**:
+4. **Verify file exists before sending**:
    ```python
    python -c "from pathlib import Path; print('✅' if Path('path').exists() else '❌')"
    ```
 
-4. **For large files**: Check platform limits
+5. **For large files**: Check platform limits
    - WeChat: ~100MB
    - Telegram: ~2GB
    - Discord: ~25MB (free), ~500MB (Nitro)
 
-5. **Don't send sensitive data**: Never place credentials, tokens, or private keys in cache directories
+6. **Don't send sensitive data**: Never place credentials, tokens, or private keys in cache directories
+
+7. **Test with Chinese filenames**: If a file with Chinese characters fails to download, try:
+   - Renaming to English
+   - Using angle brackets: `](</path/to/文件.docx>)`
+   - Checking if the file actually exists at the path
 
 ---
 

media-delivery/references/macos-gateway-media-issue.md

+# macOS MEDIA Protocol — Gateway Initialization Issue
+
+> **Source:** conversation about file delivery on macOS (2026-07-22)  
+> **Symptom:** MEDIA paths returned as plain text instead of files, even after correct path and cache directory setup
+
+## Problem Description
+
+When using the MEDIA protocol on macOS after a gateway restart, the MEDIA directive is not being parsed by the gateway. Instead of sending the file as an attachment, the gateway returns the literal text `MEDIA:/path/to/file` to the user.
+
+## Reproduction Steps
+
+1. File exists in cache directory: `~/.hermes/cache/documents/test.md`
+2. Send `MEDIA:/Users/username/.hermes/cache/documents/test.md`
+3. User receives plain text instead of downloadable file
+4. Gateway logs show no MEDIA-related entries
+5. Restart gateway with `hermes gateway restart`
+6. MEDIA protocol starts working correctly
+
+## Root Cause
+
+The MEDIA protocol parser in the gateway may not be fully initialized after a session starts or after a gateway restart. This appears to be a timing/initialization issue specific to the macOS gateway implementation.
+
+## Detailed Diagnostic Steps
+
+1. **Verify file exists in cache directory**:
+   ```bash
+   ls -lh ~/.hermes/cache/documents/test.md
+   ```
+
+2. **Check gateway status**:
+   ```bash
+   ps aux | grep -i "hermes.*gateway"
+   ```
+
+3. **Examine gateway logs for MEDIA-related entries**:
+   ```bash
+   tail -100 ~/.hermes/logs/gateway.log | grep -i "media\|extract\|file"
+   ```
+
+4. **Check gateway error logs**:
+   ```bash
+   tail -100 ~/.hermes/logs/gateway.error.log
+   ```
+
+5. **Inspect `extract_media()` implementation** (located at `gateway/platforms/base.py:3605`):
+   - Uses `MEDIA_TAG_CLEANUP_RE` to extract tags
+   - Validates paths with `validate_media_delivery_path()`
+   - Masks protected regions (code blocks, inline code, blockquotes)
+
+6. **Verify configuration**:
+   ```bash
+   grep -r "MEDIA\|media" ~/.hermes/config.yaml
+   ```
+
+## Solution
+
+1. **After gateway restart, wait 5-10 seconds** for full initialization before using MEDIA protocol
+2. **If MEDIA paths are returned as text, restart the gateway**:
+   ```bash
+   hermes gateway restart
+   sleep 10
+   ```
+3. **Verify gateway is ready** by checking worker status:
+   ```bash
+   hermes worker status
+   ```
+4. **Retry the MEDIA directive** after restart
+
+## Key Code Paths
+
+- **MEDIA tag extraction**: `gateway/platforms/base.py:extract_media()` (line 3605)
+- **Path validation**: `gateway/platforms/base.py:validate_media_delivery_path()`
+- **Extension allowlist**: `gateway/platforms/base.py:MEDIA_DELIVERY_EXTS` (line 1455)
+- **Cleanup regex**: `gateway/platforms/base.py:MEDIA_TAG_CLEANUP_RE` (line 1491)
+
+## Supported Extensions (from `MEDIA_DELIVERY_EXTS`)
+
+Images: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, `.tiff`, `.svg`  
+Video: `.mp4`, `.mov`, `.avi`, `.mkv`, `.webm`  
+Audio: `.mp3`, `.wav`, `.ogg`, `.opus`, `.m4a`, `.flac`  
+Documents: `.pdf`, `.docx`, `.doc`, `.odt`, `.rtf`, `.txt`, `.md`, `.epub`  
+Spreadsheets: `.xlsx`, `.xls`, `.ods`, `.csv`, `.tsv`, `.json`, `.xml`, `.yaml`, `.yml`  
+Presentations: `.pptx`, `.ppt`, `.odp`, `.key`  
+Archives: `.zip`, `.tar`, `.gz`, `.tgz`, `.bz2`, `.xz`, `.7z`, `.rar`  
+Web: `.html`, `.htm`
+
+## Verification
+
+After restart, MEDIA protocol should work correctly:
+```bash
+# Copy file to cache
+cp /path/to/file ~/.hermes/cache/documents/
+
+# Send with MEDIA directive
+MEDIA:/Users/username/.hermes/cache/documents/file.md
+```
+
+User should receive a downloadable file, not plain text.
+
+## Prevention
+
+- Always verify MEDIA protocol is active before sending files
+- After any gateway restart, test with a small file first
+- Check gateway logs if MEDIA delivery fails:
+  ```bash
+  grep "MEDIA\|media" ~/.hermes/logs/gateway.log
+  ```
+- If MEDIA tags are returned as text, wait 5-10 seconds and retry
+
+## Related Issues
+
+- Issue #34517: MEDIA tag cleanup regex mismatch with extract_local_files
+- Issue #34632: Windows path format (`C:/` vs `/c/`)
+- Issue #35695: MEDIA tags in code blocks should not be extracted
+- Windows path format issues (use `C:/...` not `/c/...`)
+- Strict mode path validation failures
+- File permission issues