Initial commit: skills library
- 70 skills with code and documentation - Add .gitignore (ignore __pycache__, output/, temp/, venv/) - Clean up test intermediates and caches
This commit is contained in:
hmo
@@ -0,0 +1,437 @@
|
||||
---
|
||||
name: file-reader
|
||||
description: 文件读写编辑技能。读取、创建、编辑 docx/xlsx/pdf/pptx 等文件，特别处理中文编码问题。
|
||||
---
|
||||
|
||||
# 文件读写编辑技能
|
||||
|
||||
## 概述
|
||||
|
||||
支持对 Word、Excel、PDF、PPT 四类办公文档进行**读取、创建、编辑**操作。
|
||||
特别针对 WPS/Office 创建的中文文档编码问题提供解决方案。
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 读取 `.docx` / `.xlsx` / `.pdf` / `.pptx` 文件内容
|
||||
- 创建新的办公文档（报告、表格、演示文稿、PDF）
|
||||
- 编辑已有文档（修改内容、格式、公式等）
|
||||
- 中文编码乱码问题处理
|
||||
- PDF 合并/拆分/OCR/加水印
|
||||
- Excel 公式模型构建
|
||||
|
||||
---
|
||||
|
||||
## 一、Word 文档（docx）
|
||||
|
||||
### 1.1 读取
|
||||
|
||||
```bash
|
||||
# 使用内置脚本（自动处理中文编码）
|
||||
python .opencode/skills/file-reader/scripts/file_reader.py <file.docx>
|
||||
```
|
||||
|
||||
内容保存到 `temp/docx_output.txt`，确保中文在 Windows 终端也能正确查看。
|
||||
|
||||
**中文编码原理**：WPS 创建的 docx 内部 XML 可能是 GBK 编码但声明为 UTF-8，直接用 python-docx 会乱码。脚本直接从 zip 包读取 XML 并正确处理编码。
|
||||
|
||||
### 1.2 创建新文档
|
||||
|
||||
使用 `docx-js`（Node.js）生成，安装：`npm install -g docx`
|
||||
|
||||
```javascript
|
||||
const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell,
|
||||
ImageRun, Header, Footer, AlignmentType, HeadingLevel, BorderStyle,
|
||||
WidthType, ShadingType, PageNumber, PageBreak, LevelFormat,
|
||||
TableOfContents, PageOrientation } = require('docx');
|
||||
const fs = require('fs');
|
||||
|
||||
const doc = new Document({
|
||||
styles: {
|
||||
default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt
|
||||
paragraphStyles: [
|
||||
{ id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal",
|
||||
quickFormat: true,
|
||||
run: { size: 32, bold: true, font: "Arial" },
|
||||
paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } },
|
||||
]
|
||||
},
|
||||
sections: [{
|
||||
properties: {
|
||||
page: {
|
||||
size: { width: 12240, height: 15840 }, // US Letter (DXA单位, 1440=1英寸)
|
||||
margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }
|
||||
}
|
||||
},
|
||||
children: [/* 内容 */]
|
||||
}]
|
||||
});
|
||||
|
||||
Packer.toBuffer(doc).then(buf => fs.writeFileSync("output.docx", buf));
|
||||
```
|
||||
|
||||
**关键规则**：
|
||||
- 页面尺寸必须显式设置（默认 A4，US Letter 需指定 12240x15840）
|
||||
- 横向：传纵向尺寸 + `orientation: PageOrientation.LANDSCAPE`（内部自动交换）
|
||||
- 禁止用 `\n` 换行，用多个 `Paragraph`
|
||||
- 禁止用 Unicode 项目符号，用 `LevelFormat.BULLET` + numbering config
|
||||
- `PageBreak` 必须放在 `Paragraph` 内
|
||||
- `ImageRun` 必须指定 `type`（png/jpg 等）
|
||||
- 表格必须同时设置 `columnWidths` 和每个 cell 的 `width`，且用 `WidthType.DXA`（百分比在 Google Docs 会坏）
|
||||
- 表格着色用 `ShadingType.CLEAR`（不是 SOLID，否则全黑）
|
||||
- 目录 TOC 要求标题用 `HeadingLevel`，且样式中包含 `outlineLevel`
|
||||
|
||||
### 1.3 编辑已有文档
|
||||
|
||||
采用 XML 解包→编辑→重打包 三步法：
|
||||
|
||||
```bash
|
||||
# 步骤1：解包
|
||||
python scripts/office/unpack.py document.docx unpacked/
|
||||
|
||||
# 步骤2：编辑 unpacked/word/ 下的 XML 文件
|
||||
# 直接用 Edit 工具做字符串替换，不要写 Python 脚本
|
||||
|
||||
# 步骤3：重打包
|
||||
python scripts/office/pack.py unpacked/ output.docx --original document.docx
|
||||
```
|
||||
|
||||
**修订标记（Tracked Changes）**：
|
||||
```xml
|
||||
<!-- 插入 -->
|
||||
<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
|
||||
<w:r><w:t>新文本</w:t></w:r>
|
||||
</w:ins>
|
||||
|
||||
<!-- 删除（注意用 delText 不是 t） -->
|
||||
<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
|
||||
<w:r><w:delText>被删文本</w:delText></w:r>
|
||||
</w:del>
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
- 替换整个 `<w:r>` 元素，不要在 run 内部插入修订标签
|
||||
- 保留原始 `<w:rPr>` 格式块
|
||||
- 新内容中的引号用 XML 实体：`“`（"）`”`（"）`’`（'）
|
||||
- 删除整段时需在 `<w:pPr><w:rPr>` 中也加 `<w:del/>`，否则接受修订后留空段
|
||||
|
||||
---
|
||||
|
||||
## 二、PDF 文档（pdf）
|
||||
|
||||
### 2.1 读取
|
||||
|
||||
```bash
|
||||
# 使用 pypdf 读取并保存到文件（避免终端中文乱码）
|
||||
python -c "
|
||||
from pypdf import PdfReader
|
||||
r = PdfReader('<file.pdf>')
|
||||
with open('temp/pdf_output.txt', 'w', encoding='utf-8') as f:
|
||||
for i, p in enumerate(r.pages):
|
||||
f.write(f'--- Page {i+1} ---\n')
|
||||
f.write(p.extract_text() + '\n\n')
|
||||
"
|
||||
```
|
||||
|
||||
**提取表格**（pdfplumber 更强）：
|
||||
```python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("doc.pdf") as pdf:
|
||||
for page in pdf.pages:
|
||||
tables = page.extract_tables()
|
||||
for table in tables:
|
||||
for row in table:
|
||||
print(row)
|
||||
```
|
||||
|
||||
### 2.2 合并与拆分
|
||||
|
||||
```python
|
||||
from pypdf import PdfReader, PdfWriter
|
||||
|
||||
# 合并多个 PDF
|
||||
writer = PdfWriter()
|
||||
for f in ["doc1.pdf", "doc2.pdf"]:
|
||||
for page in PdfReader(f).pages:
|
||||
writer.add_page(page)
|
||||
with open("merged.pdf", "wb") as out:
|
||||
writer.write(out)
|
||||
|
||||
# 拆分为单页
|
||||
reader = PdfReader("input.pdf")
|
||||
for i, page in enumerate(reader.pages):
|
||||
w = PdfWriter()
|
||||
w.add_page(page)
|
||||
with open(f"page_{i+1}.pdf", "wb") as out:
|
||||
w.write(out)
|
||||
```
|
||||
|
||||
### 2.3 创建新 PDF
|
||||
|
||||
使用 `reportlab`：
|
||||
|
||||
```python
|
||||
from reportlab.lib.pagesizes import letter
|
||||
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
|
||||
from reportlab.lib.styles import getSampleStyleSheet
|
||||
|
||||
doc = SimpleDocTemplate("report.pdf", pagesize=letter)
|
||||
styles = getSampleStyleSheet()
|
||||
story = [
|
||||
Paragraph("报告标题", styles['Title']),
|
||||
Spacer(1, 12),
|
||||
Paragraph("正文内容..." * 20, styles['Normal']),
|
||||
PageBreak(),
|
||||
Paragraph("第二页", styles['Heading1']),
|
||||
]
|
||||
doc.build(story)
|
||||
```
|
||||
|
||||
**陷阱**：禁止在 reportlab 中使用 Unicode 上下标字符（₀₁₂ ⁰¹²），内置字体不支持会渲染成黑块。用 `<sub>` `<super>` 标签代替。
|
||||
|
||||
### 2.4 OCR 扫描件
|
||||
|
||||
```python
|
||||
# 依赖：pip install pytesseract pdf2image
|
||||
import pytesseract
|
||||
from pdf2image import convert_from_path
|
||||
|
||||
images = convert_from_path('scanned.pdf')
|
||||
for i, img in enumerate(images):
|
||||
text = pytesseract.image_to_string(img, lang='chi_sim') # 中文用 chi_sim
|
||||
print(f"Page {i+1}:\n{text}\n")
|
||||
```
|
||||
|
||||
### 2.5 其他操作
|
||||
|
||||
```python
|
||||
from pypdf import PdfReader, PdfWriter
|
||||
|
||||
# 旋转页面
|
||||
page = PdfReader("input.pdf").pages[0]
|
||||
page.rotate(90)
|
||||
|
||||
# 添加水印
|
||||
watermark = PdfReader("watermark.pdf").pages[0]
|
||||
for page in PdfReader("doc.pdf").pages:
|
||||
page.merge_page(watermark)
|
||||
|
||||
# 加密
|
||||
writer.encrypt("user_password", "owner_password")
|
||||
```
|
||||
|
||||
**命令行工具**：
|
||||
```bash
|
||||
pdftotext -layout input.pdf output.txt # 提取文本（保留布局）
|
||||
qpdf --empty --pages f1.pdf f2.pdf -- out.pdf # 合并
|
||||
pdfimages -j input.pdf prefix # 提取图片
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、PPT 演示文稿（pptx）
|
||||
|
||||
### 3.1 读取
|
||||
|
||||
```bash
|
||||
# 文本提取
|
||||
python -m markitdown presentation.pptx
|
||||
|
||||
# 缩略图预览
|
||||
python scripts/thumbnail.py presentation.pptx
|
||||
|
||||
# 原始 XML
|
||||
python scripts/office/unpack.py presentation.pptx unpacked/
|
||||
```
|
||||
|
||||
### 3.2 创建新演示文稿
|
||||
|
||||
使用 `pptxgenjs`（Node.js），安装：`npm install -g pptxgenjs`
|
||||
|
||||
无模板时从头创建，有模板时用解包→编辑→打包流程。
|
||||
|
||||
### 3.3 编辑已有文件
|
||||
|
||||
```bash
|
||||
# 1. 分析模板
|
||||
python scripts/thumbnail.py presentation.pptx
|
||||
|
||||
# 2. 解包→编辑→打包
|
||||
python scripts/office/unpack.py presentation.pptx unpacked/
|
||||
# 编辑 XML...
|
||||
python scripts/office/pack.py unpacked/ output.pptx --original presentation.pptx
|
||||
```
|
||||
|
||||
### 3.4 设计规范
|
||||
|
||||
**配色**：不要默认蓝色，根据主题选择配色方案。深色背景用于首尾页，浅色用于内容页。
|
||||
|
||||
**字体搭配**（标题/正文）：Georgia+Calibri、Arial Black+Arial、Cambria+Calibri
|
||||
|
||||
**字号规范**：
|
||||
|
||||
| 元素 | 字号 |
|
||||
|------|------|
|
||||
| 幻灯片标题 | 36-44pt 加粗 |
|
||||
| 章节标题 | 20-24pt 加粗 |
|
||||
| 正文 | 14-16pt |
|
||||
| 注释 | 10-12pt |
|
||||
|
||||
**常见错误**：
|
||||
- 不要重复相同布局，要变换排版
|
||||
- 正文左对齐，仅标题居中
|
||||
- 每页必须有视觉元素（图、图标、图表），拒绝纯文字幻灯片
|
||||
- 禁止标题下划线（AI 生成痕迹明显）
|
||||
- 设置 text box `margin: 0` 或偏移以对齐装饰线与文字边缘
|
||||
|
||||
### 3.5 QA 检查（必须执行）
|
||||
|
||||
```bash
|
||||
# 内容检查
|
||||
python -m markitdown output.pptx
|
||||
|
||||
# 视觉检查：转图片后逐页审查
|
||||
python scripts/office/soffice.py --headless --convert-to pdf output.pptx
|
||||
pdftoppm -jpeg -r 150 output.pdf slide
|
||||
|
||||
# 检查残留占位符
|
||||
python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum"
|
||||
```
|
||||
|
||||
**检查清单**：元素重叠、文字溢出、间距不均、低对比度、占位符残留。
|
||||
**至少完成一轮 修复→验证 循环才能交付。**
|
||||
|
||||
---
|
||||
|
||||
## 四、Excel 电子表格（xlsx）
|
||||
|
||||
### 4.1 读取
|
||||
|
||||
```bash
|
||||
# 使用内置脚本（自动处理中文编码）
|
||||
python .opencode/skills/file-reader/scripts/file_reader.py <file.xlsx> # 列出所有sheets
|
||||
python .opencode/skills/file-reader/scripts/file_reader.py <file.xlsx> <sheet_idx> # 读指定sheet（默认前20行）
|
||||
python .opencode/skills/file-reader/scripts/file_reader.py <file.xlsx> <sheet_idx> <max_rows> # 指定行数
|
||||
```
|
||||
|
||||
**中文编码原理**：直接读取 xlsx 内部 XML（sharedStrings.xml），使用 UTF-8 解码，绕过 openpyxl 可能的编码问题。
|
||||
|
||||
**pandas 分析**：
|
||||
```python
|
||||
import pandas as pd
|
||||
df = pd.read_excel('file.xlsx') # 默认第一个sheet
|
||||
all_sheets = pd.read_excel('file.xlsx', sheet_name=None) # 所有sheet
|
||||
df.describe() # 统计摘要
|
||||
```
|
||||
|
||||
### 4.2 创建与编辑
|
||||
|
||||
```python
|
||||
from openpyxl import Workbook, load_workbook
|
||||
from openpyxl.styles import Font, PatternFill, Alignment
|
||||
|
||||
# 创建新文件
|
||||
wb = Workbook()
|
||||
ws = wb.active
|
||||
ws['A1'] = '标题'
|
||||
ws['A1'].font = Font(bold=True, size=14)
|
||||
ws.column_dimensions['A'].width = 20
|
||||
|
||||
# 编辑已有文件
|
||||
wb = load_workbook('existing.xlsx')
|
||||
ws = wb['Sheet1']
|
||||
ws['B2'] = '=SUM(B3:B10)'
|
||||
|
||||
wb.save('output.xlsx')
|
||||
```
|
||||
|
||||
### 4.3 公式规范（铁律）
|
||||
|
||||
> **必须用 Excel 公式，禁止在 Python 中算好再硬编码到单元格！**
|
||||
|
||||
```python
|
||||
# ❌ 错误：Python 计算后写死值
|
||||
total = df['Sales'].sum()
|
||||
sheet['B10'] = total # 写死 5000
|
||||
|
||||
# ✅ 正确：写 Excel 公式
|
||||
sheet['B10'] = '=SUM(B2:B9)'
|
||||
sheet['C5'] = '=(C4-C2)/C2'
|
||||
sheet['D20'] = '=AVERAGE(D2:D19)'
|
||||
```
|
||||
|
||||
公式写入后必须重新计算：
|
||||
```bash
|
||||
python scripts/recalc.py output.xlsx
|
||||
```
|
||||
|
||||
脚本返回 JSON，如果 `status` 为 `errors_found`，根据 `error_summary` 修复后重新计算。
|
||||
|
||||
### 4.4 财务模型规范
|
||||
|
||||
**颜色编码**：
|
||||
- 蓝色文字 (0,0,255)：硬编码输入值
|
||||
- 黑色文字 (0,0,0)：公式和计算
|
||||
- 绿色文字 (0,128,0)：跨 sheet 引用
|
||||
- 红色文字 (255,0,0)：外部文件链接
|
||||
- 黄色背景 (255,255,0)：关键假设
|
||||
|
||||
**数字格式**：
|
||||
- 年份格式化为文本（避免 2024 变成 2,024）
|
||||
- 货币用 `$#,##0`，标题注明单位
|
||||
- 零值显示为 `-`
|
||||
- 负数用括号 `(123)` 不用减号
|
||||
- 百分比默认 `0.0%`
|
||||
|
||||
### 4.5 注意事项
|
||||
|
||||
- openpyxl 单元格索引从 1 开始
|
||||
- `data_only=True` 读取计算值，但保存后公式会永久丢失
|
||||
- pandas 读取时指定 `dtype={'id': str}` 避免类型推断问题
|
||||
- 假设值放单独单元格，公式用引用，不要内嵌常量
|
||||
- 跨 sheet 引用格式：`Sheet1!A1`
|
||||
- 检查公式错误：`#REF!`、`#DIV/0!`、`#VALUE!`、`#NAME?`
|
||||
|
||||
---
|
||||
|
||||
## 五、中文编码问题总结
|
||||
|
||||
| 文件类型 | 问题根源 | 解决方案 |
|
||||
|---------|---------|---------|
|
||||
| xlsx | WPS 内部 XML 可能是 GBK 但声明 UTF-8 | 直接读 zip 内 XML，正确解码 |
|
||||
| docx | 同上 | 直接读 word/document.xml，尝试 UTF-8/GBK |
|
||||
| pdf | 提取的中文在 Windows 终端乱码 | 保存到 UTF-8 文件再读取 |
|
||||
| pptx | 类似 docx | 用 markitdown 或解包 XML |
|
||||
|
||||
---
|
||||
|
||||
## 六、依赖安装
|
||||
|
||||
```bash
|
||||
# Python 核心（读取）
|
||||
pip install python-docx openpyxl pypdf pdfplumber
|
||||
|
||||
# PDF 创建与 OCR
|
||||
pip install reportlab pytesseract pdf2image
|
||||
|
||||
# PPT 文本提取
|
||||
pip install "markitdown[pptx]" Pillow
|
||||
|
||||
# Node.js（文档创建）
|
||||
npm install -g docx # Word 创建
|
||||
npm install -g pptxgenjs # PPT 创建
|
||||
|
||||
# 系统工具（可选）
|
||||
# LibreOffice - PDF转换、公式重算
|
||||
# Poppler (pdftoppm/pdftotext/pdfimages) - PDF处理
|
||||
# Tesseract - OCR
|
||||
```
|
||||
|
||||
## 七、输出文件位置
|
||||
|
||||
| 文件类型 | 默认输出路径 |
|
||||
|---------|------------|
|
||||
| xlsx 读取 | `temp/xlsx_output.txt` |
|
||||
| docx 读取 | `temp/docx_output.txt` |
|
||||
| pdf 读取 | `temp/pdf_output.txt` |
|
||||
|
||||
保存到文件是为了确保中文在 Windows 终端乱码时仍可正确查看。
|
||||
Reference in New Issue
Block a user