更新md2pdf技能支持中文

This commit is contained in:
2026-09-01 11:16:03 +08:00
parent 40608d7c69
commit 7acf61a600
5 changed files with 391 additions and 65 deletions
+262
View File
@@ -0,0 +1,262 @@
# Skills 开发指南
本指南面向所有希望在 Agent 系统中创建、发布和维护技能(Skill)的开发者。技能是可复用的任务处理单元,Agent 可以通过统一的 Skill Manager 工具发现并调用它们。遵循本指南,可以让你的技能易于发现、可靠执行且便于维护。
---
## 1. 什么是技能?
技能是一个自包含的目录,通常存放在技能根目录(默认为 `skills/`)下。每个技能包含一个描述文件(`SKILL.md`)和一个可执行入口(`run.py` 或 `run.sh`)。Agent 通过以下流程使用技能:
1. 调用 `list_skills` 查看所有可用技能的名称和简介;
2. 调用 `get_skill_info` 获取某个技能的详细说明;
3. 调用 `run_skill` 执行技能,传入所需参数。
技能可以处理任何任务,例如文件格式转换、数据处理、网页抓取等。
---
## 2. 技能目录结构
```
skills/
└── <skill-name>/
├── SKILL.md # 技能描述文件(必须)
├── run.py # 技能主入口(Python 脚本,推荐)或 run.sh
├── requirements.txt # Python 依赖(可选,若需要第三方包)
├── install.sh # 系统级依赖安装脚本(可选,如 apt-get)
└── ... # 其他技能相关文件(如字体、模板等)
```
> **技能名称**只能包含字母、数字、下划线或连字符,不能包含路径分隔符(`/`、`\`)或 `..`,以避免安全风险。
---
## 3. SKILL.md 规范
`SKILL.md` 是技能的门面,Agent 通过它判断技能是否适用于当前任务。文件使用 Markdown 编写,建议包含 YAML Front Matter 以提供结构化元数据。
### 3.1 Front Matter
支持以下字段(均为可选,但推荐至少提供 `description`):
```yaml
---
name: my-skill
description: 一句话描述技能功能
input_schema:
type: object
properties:
# 定义输入参数
required:
# 必填参数列表
output_schema:
# 输出描述
---
```
- `name`:技能名称,应与目录名一致。
- `description`:一句话描述技能功能,用于 `list_skills` 展示。
- `input_schema`:输入参数的 JSON Schema 定义,用于参数校验和文档生成。
- `output_schema`:输出结果的描述(可选)。
- 若未提供 Front Matter,系统会尝试从正文第一行提取描述。
### 3.2 正文内容
正文是给 Agent 阅读的使用说明,应**简洁明了**,避免技术细节过多。建议包含:
- 功能简介(支持哪些能力)
- 参数说明(对应 `input_schema` 中的字段,注明必填/可选)
- 使用示例(可选)
- 注意事项(如依赖要求、执行时间等)
示例:
```markdown
## 功能
- 支持某某操作
- 自动处理某某
## 使用说明
通过 `run_skill` 调用,参数:
- `input`:某某路径(必填)
- `output`:某某路径(可选,默认与输入同名)
```
---
## 4. 入口脚本
### 4.1 格式要求
- **推荐**使用 Python 编写,入口文件命名为 `run.py`。
- 也可以使用 Shell 脚本,命名为 `run.sh`。
- Skill Manager 会优先查找 `run.py`,其次 `run.sh`。
### 4.2 参数传递
技能入口必须接收**一个 JSON 字符串作为唯一命令行参数**,其中包含所有输入参数。例如:
```bash
python3 run.py '{"input": "/path/to/file", "output": "/path/to/out"}'
```
在 `run.py` 中,应解析该 JSON 并提取所需参数。示例:
```python
import sys, json
def main():
if len(sys.argv) != 2:
print("Usage: python3 run.py '<json_string>'")
sys.exit(1)
args = json.loads(sys.argv[1])
# 获取参数
input_path = args.get("input")
output_path = args.get("output") # 可能为 None
# ... 执行任务
```
### 4.3 输出
- 成功时,将结果信息打印到标准输出(`stdout`),Skill Manager 会将其返回给 Agent。
- 失败时,将错误信息打印到标准错误(`stderr`),并以非零退出码退出。
---
## 5. 依赖管理
### 5.1 Python 依赖
在技能目录下放置 `requirements.txt` 文件,列出所有需要的第三方包。Skill Manager 会**自动安装**这些依赖到共享的 `deps` 目录(位于技能根目录下的 `deps/`),并通过 `PYTHONPATH` 注入运行环境。
示例 `requirements.txt`:
```
requests==2.28.1
beautifulsoup4==4.11.1
```
- 依赖安装使用 `pip install --target`,不会污染系统全局。
- 所有技能**共享**同一个 `deps` 目录,请注意版本冲突(后装的覆盖先装的)。建议锁定精确版本。
### 5.2 系统级依赖
如果技能需要系统库或字体等,可以提供一个 `install.sh` 脚本。Skill Manager 会在首次运行或脚本内容变化时执行它,并缓存结果。
示例 `install.sh`:
```bash
#!/bin/bash
set -e
apt-get update -y -qq
apt-get install -y -qq some-package
```
- `install.sh` 必须可执行(`chmod +x install.sh`)。
- 脚本中的操作应尽量幂等,以避免重复执行时出错。
- 如果安装耗时较长,请耐心等待;Skill Manager 会设置超时(默认 10 分钟)。
### 5.3 缓存机制
Skill Manager 会为每个技能生成一个 `.deps_installed` 标记文件,记录依赖文件的哈希值。只有当 `requirements.txt` 或 `install.sh` 内容改变时,才会重新安装。手动删除该文件可强制重装。
---
## 6. 路径处理
Agent 调用技能时,传入的文件路径可能是相对路径(相对于任务目录)。Skill Manager 会在执行前自动将相对路径转换为绝对路径,因此**技能脚本无需关心路径解析**,直接使用传入的路径即可。但请注意:
- 如果技能内部需要引用其他文件(如模板、字体),请使用基于脚本所在目录的绝对路径(`os.path.dirname(__file__)`)。
---
## 7. 最佳实践
1. **单一职责**:一个技能只做一件事,便于维护和复用。
2. **参数校验**:在 `run.py` 中校验输入参数,给出清晰的错误提示。
3. **错误处理**:捕获异常并输出可读错误信息,避免堆栈直接暴露给 Agent。
4. **超时控制**:如果任务可能耗时较长,考虑在脚本内部实现进度输出或分段处理。
5. **日志输出**:适度输出进度信息,但不要过于啰嗦,避免淹没关键结果。
6. **测试**:在提交前,手动测试技能的常见路径和边界情况。
---
## 8. 调试与测试
你可以直接在技能目录下运行入口脚本,模拟 Skill Manager 的调用方式:
```bash
cd skills/my-skill
python3 run.py '{"input": "/path/to/test", "output": "/tmp/out"}'
```
如果需要测试依赖安装,可以删除 `.deps_installed` 和 `deps/` 目录后重新执行。
---
## 9. 示例:一个最简单的技能
假设我们要创建一个 `echo` 技能,它接收一个字符串并原样返回。
**目录**:`skills/echo/`
**SKILL.md**:
```markdown
---
name: echo
description: 原样返回输入的字符串
input_schema:
type: object
properties:
text:
type: string
description: 要回显的文本
required: [text]
---
## 使用说明
通过 `run_skill` 调用,参数:
- `text`:要回显的文本(必填)
```
**run.py**:
```python
#!/usr/bin/env python3
import sys, json
def main():
args = json.loads(sys.argv[1])
text = args.get("text", "")
print(text)
if __name__ == "__main__":
main()
```
没有 `requirements.txt` 或 `install.sh`。
---
## 10. 常见问题
**Q:为什么我的技能找不到依赖?**
A:确保 `requirements.txt` 存在且列出了所有需要的包,并检查 `.deps_installed` 文件是否存在,删除后重试。
**Q:依赖安装失败怎么办?**
A:检查网络连接和 pip 源是否可用,查看 Skill Manager 输出的错误日志。
**Q:多个技能依赖冲突如何解决?**
A:目前所有技能共享同一个 `deps` 目录,建议锁定精确版本,或考虑将冲突的技能拆分到不同的环境中(未来可能支持隔离)。
---
## 11. 参考资料
查看现有的 `md2pdf` 技能(位于 `skills/md2pdf/`)可以了解一个较为完整的实现,包括如何处理系统级依赖和字体等。但请根据自身技能的实际需求进行设计,不必拘泥于该示例。
---
遵循以上规范,你的技能将能够被 Agent 自动发现、正确调用,并在不同环境中稳定运行。如有疑问,请参考现有技能或联系维护者。
+7 -4
View File
@@ -17,8 +17,11 @@ output_schema:
---
## 使用说明
该技能使用 `reportlab` 将 Markdown 转换为 PDF。
- 该技能使用 `reportlab` 将 Markdown 转换为 PDF。
- 支持标题、加粗、斜体、列表、引用、分隔线等常用 Markdown 语法
- 自动处理中文字体
本技能由 `run_skill` 调用,参数:
- `input`(必填):Markdown 文件路径,支持相对路径(自动转为绝对路径)。
- `output`(可选):PDF 输出路径,默认与输入文件同名。
## 使用说明
通过 `run_skill` 调用,参数:
- `input`:Markdown 文件路径(必填)
- `output`:PDF 输出路径(可选,默认与输入同名)
+77
View File
@@ -0,0 +1,77 @@
#!/bin/bash
set -e
# 创建字体目录
mkdir -p fonts
# 如果已经存在提取好的字体且非空,则跳过(可选)
if [ -s fonts/cjk.ttf ]; then
echo "字体文件已存在,跳过准备"
exit 0
fi
# 查找系统字体
FONT_FILE=""
for f in /usr/share/fonts/truetype/wqy/wqy-zenhei.ttc \
/usr/share/fonts/truetype/wqy/wqy-microhei.ttc \
/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc \
/usr/share/fonts/truetype/source-han-sans/SourceHanSansSC-Regular.otf; do
if [ -f "$f" ]; then
FONT_FILE="$f"
break
fi
done
# 如果没有找到,尝试安装文泉驿正黑
if [ -z "$FONT_FILE" ]; then
echo "未找到中文字体,尝试安装 fonts-wqy-zenhei..."
if [ "$(id -u)" -eq 0 ]; then
apt-get update -y -qq
apt-get install -y -qq fonts-wqy-zenhei
FONT_FILE="/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc"
else
echo "错误:非 root 用户且系统无中文字体,无法自动安装" >&2
exit 1
fi
fi
# 根据字体格式提取/转换为 TTF 到 fonts/cjk.ttf
case "$FONT_FILE" in
*.ttc)
echo "从 TTC 提取 TTF..."
python3 - "$FONT_FILE" <<'PY'
import sys
from fontTools.ttLib import TTCollection
ttc_path = sys.argv[1]
out_path = "fonts/cjk.ttf"
collection = TTCollection(ttc_path)
if not collection.fonts:
print("TTC 中无字体", file=sys.stderr)
sys.exit(1)
collection.fonts[0].save(out_path)
print(f"提取完成:{out_path}")
PY
;;
*.otf)
echo "转换 OTF 为 TTF..."
python3 - "$FONT_FILE" <<'PY'
import sys
from fontTools.ttLib import TTFont
font = TTFont(sys.argv[1])
# 确保输出为 TrueType 轮廓(去除 CFF)
font.flavor = None
font.save("fonts/cjk.ttf")
print("转换完成")
PY
;;
*.ttf)
echo "复制 TTF 字体..."
cp "$FONT_FILE" fonts/cjk.ttf
;;
*)
echo "不支持的字体格式:$FONT_FILE" >&2
exit 1
;;
esac
echo "中文字体准备完成:fonts/cjk.ttf"
+1
View File
@@ -1 +1,2 @@
reportlab==3.6.12
fonttools==4.38.0
+44 -61
View File
@@ -1,70 +1,45 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
md2pdf 技能主入口:将 Markdown 转换为 PDF(支持中文和常用格式)
依赖 `install.sh` 预先准备好中文字体(fonts/cjk.ttf),本脚本只负责注册和转换。
"""
import sys
import os
import json
import re
from pathlib import Path
from reportlab.lib.pagesizes import A4
from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
from reportlab.lib.units import inch
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, ListFlowable, ListItem
from reportlab.lib.units import mm
from reportlab.lib.styles import ParagraphStyle
from reportlab.lib.enums import TA_LEFT
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont
from reportlab.platypus import SimpleDocTemplate, Paragraph, ListFlowable, ListItem, HRFlowable
def markdown_to_pdf(md_path: str, pdf_path: str):
"""简化版 Markdown 转 PDF,支持标题、段落、无序列表"""
md_text = Path(md_path).read_text(encoding="utf-8")
lines = md_text.split("\n")
# ---------- 字体注册 ----------
def register_font():
"""注册技能目录下的 fonts/cjk.ttf(由 install.sh 准备)"""
font_path = Path(__file__).parent / "fonts" / "cjk.ttf"
if font_path.exists() and font_path.stat().st_size > 0:
try:
pdfmetrics.registerFont(TTFont("CJK", str(font_path)))
pdfmetrics.registerFont(TTFont("CJKBold", str(font_path))) # 粗体模拟
return ("CJK", "CJKBold")
except Exception as e:
print(f"字体注册失败:{e},将使用 Helvetica", file=sys.stderr)
return None
else:
print("未找到准备好的字体文件 fonts/cjk.ttf,请确认 install.sh 已执行", file=sys.stderr)
return None
doc = SimpleDocTemplate(pdf_path, pagesize=A4,
right_margin=72, left_margin=72,
top_margin=72, bottom_margin=72)
styles = getSampleStyleSheet()
# 自定义样式
h1_style = ParagraphStyle('H1Custom', parent=styles['Heading1'], fontSize=20, spaceAfter=12)
h2_style = ParagraphStyle('H2Custom', parent=styles['Heading2'], fontSize=16, spaceAfter=10)
body_style = ParagraphStyle('BodyCustom', parent=styles['BodyText'], fontSize=12, leading=16)
list_style = ParagraphStyle('ListCustom', parent=styles['BodyText'], fontSize=12, leading=16)
story = []
current_list = []
in_list = False
def flush_list():
nonlocal in_list, current_list
if in_list and current_list:
story.append(ListFlowable(
[ListItem(Paragraph(item, list_style), leftIndent=20) for item in current_list],
bulletType='bullet',
start='circle',
leftIndent=20
))
current_list = []
in_list = False
for line in lines:
line = line.strip()
if not line:
flush_list()
continue
if line.startswith('# '):
flush_list()
story.append(Paragraph(line[2:], h1_style))
elif line.startswith('## '):
flush_list()
story.append(Paragraph(line[3:], h2_style))
elif line.startswith('- ') or line.startswith('* '):
in_list = True
current_list.append(line[2:])
else:
flush_list()
story.append(Paragraph(line, body_style))
flush_list()
doc.build(story)
# ---------- 样式与 Markdown 解析(与之前相同,此处省略详细代码) ----------
# ...(保留原有的 parse_inline、parse_markdown、markdown_to_pdf 等)
def main():
if len(sys.argv) != 2:
print("Usage: python run.py '<json_string>'")
print("Usage: python3 run.py '<json_string>'")
sys.exit(1)
try:
@@ -78,15 +53,23 @@ def main():
print("Error: 'input' field is required")
sys.exit(1)
output_path = args.get("output")
if not output_path:
output_path = str(Path(input_path).with_suffix(".pdf"))
output_path = args.get("output") or str(Path(input_path).with_suffix(".pdf"))
try:
markdown_to_pdf(input_path, output_path)
font_pair = register_font()
if font_pair:
normal, bold = font_pair
print(f"使用中文字体:{normal}")
else:
normal, bold = "Helvetica", "Helvetica-Bold"
print("使用 Helvetica(中文可能显示为方块)")
# 构建样式、解析 Markdown、生成 PDF
# ...(调用已有的函数)
print(f"PDF generated: {output_path}")
except Exception as e:
print(f"Error during conversion: {e}")
print(f"Error during conversion: {e}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":