Skip to content

赵月辉 / hermes-skills

Go to a project
Commit e72c84f2 by Hermes Desktop
Options

feat(skills): update media-delivery

parent 12de1ee9
Showing with 283 additions and 54 deletions
media-delivery/SKILL.md
...@@ -21,6 +21,17 @@ Hermes detects the `MEDIA:` prefix, validates the path against security rules, a ...@@ -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 ## 1. Path Validation
The gateway's `validate_media_delivery_path()` function enforces: The gateway's `validate_media_delivery_path()` function enforces:
...@@ -93,6 +104,82 @@ MEDIA:C:/Users/Administrator/.hermes/cache/documents/report.pdf ...@@ -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 ## 3. File-Type Detection
The gateway auto-detects the content type from the file extension: The gateway auto-detects the content type from the file extension:
...@@ -313,7 +400,7 @@ MEDIA:C:/Users/YourUsername/.hermes/cache/documents/data.csv ...@@ -313,7 +400,7 @@ MEDIA:C:/Users/YourUsername/.hermes/cache/documents/data.csv
## 6. Diagnostic Checklist ## 6. Diagnostic Checklist
If MEDIA delivery fails: If MEDIA delivery fails, check in this order:
1. **Check gateway logs**: 1. **Check gateway logs**:
```bash ```bash
...@@ -330,9 +417,19 @@ If MEDIA delivery fails: ...@@ -330,9 +417,19 @@ If MEDIA delivery fails:
4. **Verify location**: file must be under `~/.hermes/cache/<type>/` or another safe root 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 ```bash
hermes gateway restart hermes gateway restart
``` ```
......
media-delivery/references/windows-media-path-debugging.md 0 → 100644
# 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 deleted 100644 → 0
# 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 | ❌ |
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment