structured-office-reader

Agent Skill：将 Office 文档（docx、pptx、xlsx）转换为结构化 JSON，供 Agent 读取、总结、抽取字段或传递给其他 Agent。

一行安装

复制以下命令，Agent 即可安装此技能：

git clone --depth 1 https://github.com/flyzstu/office2struct-skill.git /tmp/office2struct-skill && mkdir -p .claude/skills/office2struct && cp /tmp/office2struct-skill/SKILL.md .claude/skills/office2struct/ && cp -r /tmp/office2struct-skill/scripts .claude/skills/office2struct/ && pip install python-docx python-pptx openpyxl && rm -rf /tmp/office2struct-skill && echo "✓ office2struct skill installed"

安装后 Agent 可通过以下方式调用：

python .claude/skills/office2struct/scripts/office_to_json.py <file_path> [--format json|markdown|both]

依赖安装

pip install python-docx python-pptx openpyxl

使用

# 默认输出 JSON
python scripts/office_to_json.py path/to/file.docx

# 输出 Markdown（人工阅读）
python scripts/office_to_json.py path/to/file.xlsx --format markdown

# 同时输出 JSON 和 Markdown
python scripts/office_to_json.py path/to/file.pptx --format both

支持格式

格式	提取内容
.docx	headings, paragraphs, tables, images (placeholder)
.pptx	slides (slide_number, title, texts, bullets, tables, notes, images)
.xlsx	sheets (sheet_name, used_range, headers, rows, formulas, merged_cells)

输出格式

成功时：

{
  "ok": true,
  "file": {"path": "...", "name": "...", "type": "docx", "size_bytes": 0},
  "metadata": {},
  "content": {},
  "warnings": []
}

失败时：

{
  "ok": false,
  "error": {"code": "FILE_NOT_FOUND", "message": "..."}
}

错误码

错误码	退出码	含义
FILE_NOT_FOUND	2	文件不存在
UNSUPPORTED_FILE_TYPE	2	不支持的文件类型
READ_FAILED	1	文件读取失败
PARSE_FAILED	1	文件解析失败
EMPTY_DOCUMENT	1	文件为空
INVALID_ARGUMENT	2	参数错误
FILE_TOO_LARGE	2	文件超过 50MB

安全边界

• 不执行宏（检测到时发出 warning）
• 不执行 OCR
• 不访问外部链接
• 不修改源文件
• 不需要网络访问

测试

pip install pytest
pytest tests/ -v

许可证

MIT License