144 lines
3.7 KiB
Markdown
144 lines
3.7 KiB
Markdown
|
# AI 输出格式规范
|
|||
|
|
|
|||
|
|
为了让前端正确渲染大模型返回的图片、文件等内容，需要在系统提示词中定义以下格式约束。
|
|||
|
|
|
|||
|
|
## 系统提示词模板
|
|||
|
|
|
|||
|
|
将以下内容添加到你的系统提示词或 Agent 配置中：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
当你的回复中包含图片或文件引用时，请遵循以下格式规范：
|
|||
|
|
|
|||
|
|
## 图片格式
|
|||
|
|
使用 Markdown 图片语法，路径必须是本地绝对路径（以 / 开头）：
|
|||
|
|
`
|
|||
|
|
|
|||
|
|
`
|
|||
|
|
示例：
|
|||
|
|
`
|
|||
|
|
|
|||
|
|
`
|
|||
|
|
|
|||
|
|
## 文件链接格式
|
|||
|
|
使用 Markdown 链接语法，路径必须是本地绝对路径（以 / 开头）：
|
|||
|
|
[文件名](/tmp/report.pdf)
|
|||
|
|
示例：
|
|||
|
|
[下载报告](/tmp/monthly-report.pdf)
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
1. 图片和文件路径必须以 / 开头的绝对路径
|
|||
|
|
2. 图片会自动显示在对话中
|
|||
|
|
3. 文件链接点击后会自动下载
|
|||
|
|
4. 不要使用相对路径（如 ./file.png）
|
|||
|
|
5. 不要使用 http:// 或 https:// 开头的远程链接表示本地文件
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 完整示例
|
|||
|
|
|
|||
|
|
### 推荐：添加到 Hermes 配置文件
|
|||
|
|
|
|||
|
|
在你的 Hermes 配置文件（`~/.hermes/config.yaml` 或项目配置）中添加：
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
agents:
|
|||
|
|
your_agent_name:
|
|||
|
|
system_prompt: |
|
|||
|
|
你是一个智能助手。
|
|||
|
|
|
|||
|
|
当你的回复中包含图片或文件引用时，请遵循以下格式规范：
|
|||
|
|
|
|||
|
|
## 图片格式
|
|||
|
|
使用 Markdown 图片语法：
|
|||
|
|
|
|||
|
|
|
|||
|
|
## 文件链接格式
|
|||
|
|
使用 Markdown 链接语法：
|
|||
|
|
[文件名](/tmp/report.pdf)
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
- 图片和文件路径必须以 / 开头的绝对路径
|
|||
|
|
- 图片会自动显示在对话中
|
|||
|
|
- 文件链接点击后会自动下载
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 或者：在 Web UI 中配置
|
|||
|
|
|
|||
|
|
1. 打开 Hermes Web UI
|
|||
|
|
2. 进入 **Settings** → **Model Settings**
|
|||
|
|
3. 在 **System Instructions** 或 **Agent Instructions** 中添加上述提示词内容
|
|||
|
|
|
|||
|
|
## 支持的内容格式
|
|||
|
|
|
|||
|
|
| 类型 | Markdown 语法 | 前端渲染效果 |
|
|||
|
|
|------|--------------|------------|
|
|||
|
|
| 🖼️ 图片 | `
|
|||
|
|
|
|||
|
|
` | 自动显示图片，通过 download 接口加载 |
|
|||
|
|
| 📄 文件下载 | `[文件名](/tmp/file.pdf)` | 可点击链接，点击后下载文件 |
|
|||
|
|
| 🔗 外部链接 | `[文本](https://example.com)` | 在新标签页打开 |
|
|||
|
|
| 💻 代码块 | ` ```language\ncode\n``` ` | 语法高亮显示，支持一键复制 |
|
|||
|
|
|
|||
|
|
## 调试技巧
|
|||
|
|
|
|||
|
|
如果图片或文件没有正确显示，检查：
|
|||
|
|
|
|||
|
|
1. **路径格式**：确保路径以 `/` 开头（如 `/tmp/file.png`）
|
|||
|
|
2. **Markdown 语法**：确保使用正确的 Markdown 语法
|
|||
|
|
3. **文件存在**：确保文件确实存在于服务器上
|
|||
|
|
4. **下载接口**：检查 `/api/hermes/download` 接口是否正常工作
|
|||
|
|
|
|||
|
|
## 示例对话
|
|||
|
|
|
|||
|
|
### 正确格式 ✅
|
|||
|
|
|
|||
|
|
**用户**：帮我截个屏
|
|||
|
|
**AI**：
|
|||
|
|
```
|
|||
|
|
截图成功！这是当前页面的截图：
|
|||
|
|
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 错误格式 ❌
|
|||
|
|
|
|||
|
|
**AI**：
|
|||
|
|
```
|
|||
|
|
截图保存在 /tmp/screenshot.png
|
|||
|
|
```
|
|||
|
|
→ 这不会显示图片，因为没有使用 Markdown 图片语法
|
|||
|
|
|
|||
|
|
## 高级用法
|
|||
|
|
|
|||
|
|
### ContentBlock 格式
|
|||
|
|
|
|||
|
|
如果需要更复杂的消息结构，可以使用 JSON ContentBlock 格式：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
[
|
|||
|
|
{
|
|||
|
|
"type": "text",
|
|||
|
|
"text": "这是分析结果："
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"type": "image",
|
|||
|
|
"name": "screenshot.png",
|
|||
|
|
"path": "/tmp/screenshot.png",
|
|||
|
|
"media_type": "image/png"
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"type": "file",
|
|||
|
|
"name": "report.pdf",
|
|||
|
|
"path": "/tmp/report.pdf",
|
|||
|
|
"media_type": "application/pdf"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
前端会自动解析并渲染这种格式。
|
|||
|
|
|
|||
|
|
## 相关文件
|
|||
|
|
|
|||
|
|
- 前端渲染逻辑：`packages/client/src/components/hermes/chat/MarkdownRenderer.vue`
|
|||
|
|
- 下载接口：`packages/server/src/controllers/hermes/sessions.ts`
|
|||
|
|
- API 层：`packages/client/src/api/hermes/download.ts`
|