shuck-file

🇨🇳 中文

shuck-file

输入任意文件，输出 Markdown——只读取重要内容。

shuck-file 可将文档转换为简洁的 Markdown，供 AI Agent 和大模型使用。小文件会直接输出；大文件则返回包含章节摘要、令牌数量和可执行后续步骤的文档地图，让 Agent 只提取所需内容。

为什么选择 shuck-file？

AI Agent 需要一个具备上下文感知能力的桥梁：

• 小文件 → shuck report.docx → 在标准输出中输出完整 Markdown
• 大文件 → shuck report.docx → 返回包含章节和提取选项的文档地图
• 定向提取 → shuck report.docx --sections s1,s3 → 仅提取所需内容
• 搜索 → shuck report.docx --grep "revenue" → 无需通读全文即可查找

支持的格式

格式	扩展名	库	保留内容
Word	.docx	python-docx	标题、粗体/斜体、列表、表格
PDF	.pdf	pdfplumber	文本内容、分页符
Excel	.xlsx	openpyxl	所有工作表均以 Markdown 表格形式输出
PowerPoint	.pptx	python-pptx	标题、文本、表格、演讲者备注
CSV	.csv	stdlib	所有行和列均以表格形式输出

安装

通过 pip（推荐）

pip install shuck-file

这会安装 shuck CLI 命令和 MCP 服务。

从源代码安装

git clone https://github.com/Shan-Zhu/shuck-file.git
cd shuck-file
pip install -e .

快速开始

# Convert a document
shuck report.docx

# Force full output (bypass map mode)
shuck large-report.pdf --all

# Search within a document
shuck report.pdf --grep "revenue"

用法

自动路由（默认）

小文件会直接输出，大文件则返回文档地图。

# Small file → direct Markdown output
shuck document.pdf

# Large file → document map with sections table + next steps
shuck large-report.pdf

提取选项

# Force full output (bypass map mode)
shuck report.pdf --all

# Extract specific sections
shuck report.pdf --sections s1,s3

# Tables only
shuck report.pdf --tables-only

# Search within document
shuck report.pdf --grep "revenue"

# Token budget (smart compression)
shuck report.pdf --budget 4000

# Combinations work
shuck report.pdf --sections s2,s3 --budget 2000

Excel/CSV 专用选项

# Column headers and types
shuck data.xlsx --schema-only

# Headers + first N rows
shuck data.xlsx --sample 5

高级用户子命令

# Force map mode (even on small files)
shuck probe document.docx

# Force full extraction (alias for --all)
shuck pull document.docx

输出控制

# Write to file
shuck document.pdf -o output.md

# Write to directory (auto-named)
shuck document.pdf -d ./converted/

# Skip YAML frontmatter
shuck document.pdf --no-frontmatter

# List supported formats
shuck --formats

地图模式输出

文件较大时，shuck 会返回文档地图：

# Document Map: quarterly-report.pdf

**6 pages | ~12,400 tokens | 6 sections**

## Sections

| # | Title | Type | Tokens | Density |
|---|-------|------|--------|---------|
| s1 | Executive Summary | narrative | 450 | high |
| s2 | Q3 Financial Results | mixed | 2,800 | high |
| s3 | Revenue Breakdown | tabular | 3,200 | high |
| ...

## Next Steps

- `shuck quarterly-report.pdf --all` -- full document (~12,400 tokens)
- `shuck quarterly-report.pdf --sections s1,s2` -- high-density (~3,250 tokens)
- `shuck quarterly-report.pdf --grep "..."` -- search for keywords

MCP 服务

shuck-file 内置 MCP（Model Context Protocol）服务，可供任何兼容 MCP 的 AI 工具使用。

Claude Code

claude mcp add shuck-file -- shuck-file

也可以添加到项目的 .mcp.json 中：

{
  "mcpServers": {
    "shuck-file": {
      "command": "shuck-file",
      "args": []
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "shuck-file": {
      "command": "shuck-file",
      "args": []
    }
  }
}

Windsurf

添加到 MCP 配置中：

{
  "mcpServers": {
    "shuck-file": {
      "command": "shuck-file",
      "args": []
    }
  }
}

任意 MCP 客户端

shuck-file 通过 mcp.servers 入口点注册为 MCP 服务。提供的工具：

• shuck — 将文档转换为 Markdown，并支持所有选项（模式、章节、grep、预算等）
• list_formats — 列出支持的文档格式

Claude Code 插件

安装为 Claude Code 插件，以使用 /shuck 技能：

claude plugin add /path/to/shuck-file

架构

src/shuck_file/
├── cli.py                # CLI entrypoint
├── server.py             # MCP Server (FastMCP)
├── core/
│   ├── router.py          # Auto-routing logic
│   ├── segmenter.py       # Document segmentation
│   ├── mapper.py          # Map mode renderer
│   ├── budget.py          # Smart compression
│   ├── grep.py            # In-document search
│   ├── frontmatter.py     # YAML frontmatter
│   └── models.py          # Data models
├── extractors/
│   ├── base.py            # Base extractor ABC
│   ├── docx_ext.py        # Word extractor
│   ├── pdf_ext.py         # PDF extractor
│   ├── xlsx_ext.py        # Excel extractor
│   ├── pptx_ext.py        # PowerPoint extractor
│   └── csv_ext.py         # CSV extractor
plugin/                    # Claude Code plugin wrapper
tests/
├── test_extractors.py
├── test_router.py
├── test_segmenter.py
├── test_budget.py
└── test_grep.py

许可证

MIT