forked from EduCraft/curriculum-project-hub

Files

T

hongjr03 db49a0d23d feat(hub): concurrent multi-PDF convert_pdf_to_md + readable skills (v0.0.40)

Teachers convert many PDFs in one tool call with bounded Docmind concurrency.
Each item keeps its own output_dir/document.md and UsageFact; failures are
per-file. Mirror role skills to .cph/runtime-skills and CPH_RUNTIME_SKILLS_DIR
so agents can Read SKILL.md instead of dead .claude/sandbox stubs.

2026-07-21 05:55:55 +00:00

3.3 KiB

Raw Blame History

name, description

name	description
pdf-to-md	Convert PDF documents to Markdown bundles using the convert_pdf_to_md tool. Handles single or multiple PDFs (concurrent batch), Feishu attachments, and local workspace files. Produces high-quality Markdown with LaTeX formulas and extracted images.

PDF to Markdown Conversion

When to use

Use this skill when the user asks to convert a PDF (or several PDFs) to Markdown, extract text from a PDF, or turn PDF documents into an editable format.

How it works

The convert_pdf_to_md tool (provided by the in-process cph_hub MCP server) calls Alibaba Cloud Document Mind to parse each PDF. It:

Extracts text in reading order (handles multi-column, scanned, and multi-language documents)
Converts mathematical formulas to LaTeX ( $...$ inline, $$...$$ block)
Extracts tables as Markdown tables
Downloads embedded images into the output directory
Writes a single document.md file plus image files per output_dir

There is no workspace .mcp.json source file. MCP tools are injected by Hub at run start. Do not look for MCP or skill source under workspace .claude/ — those paths are sandbox stubs (often character devices) and are not readable constitution.

Where this skill text lives

Prefer the Skill tool when the runtime offers it. If you need to re-read these instructions with Read:

Workspace copy (always under cwd): .cph/runtime-skills/pdf-to-md/SKILL.md
Absolute path env: $CPH_RUNTIME_SKILLS_DIR/pdf-to-md/SKILL.md

Workflow

One PDF from a Feishu message

Use feishu_read_context to find the file_key of the PDF attachment.
Use feishu_download_resource to download it into the workspace.
Use convert_pdf_to_md with input_path + output_dir.

PDF already in the workspace

Use convert_pdf_to_md with input_path and output_dir.

Multiple PDFs (concurrent)

Download or locate every PDF in the workspace first.
Call convert_pdf_to_md once with:

{
  "items": [
    { "input_path": "sources/a.pdf", "output_dir": "md/a" },
    { "input_path": "sources/b.pdf", "output_dir": "md/b" }
  ]
}

Hub submits Docmind jobs with bounded concurrency (default 3, max 8; optional concurrency argument). Prefer this over N sequential tool calls.
Each item must use a distinct output_dir — the tool always writes document.md inside that directory; shared dirs overwrite each other.
Partial failure returns per-file OK/FAIL lines; re-run only failed items.

Important rules

Always use convert_pdf_to_md for PDF→Markdown. Do NOT attempt to parse PDFs yourself with Read, Bash, Python, or any other method.
If convert_pdf_to_md fails because no capability connection is configured, tell the user to ask their organization admin to configure the Aliyun docmind credential in the admin web UI (组织后台 → 能力).
The output directory will be created if it does not exist.
After conversion, use send_file to send generated markdown (or a zip you assemble) back to the user if they requested delivery.

Output

Per output_dir:

document.md — the main markdown file
*.jpg / *.png — extracted images, referenced from the markdown

Cost

Billed per page (0.04 CNY/page ≈ $0.0056/page for enhanced formula mode). Each successful file records its own usage fact on the run ledger.

3.3 KiB Raw Blame History