forked from bai/curriculum-project-hub
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.
This commit is contained in:
@@ -2,62 +2,95 @@
|
||||
name: pdf-to-md
|
||||
description: >
|
||||
Convert PDF documents to Markdown bundles using the convert_pdf_to_md tool.
|
||||
Handles PDFs from Feishu messages, local workspace files, and produces
|
||||
high-quality Markdown with LaTeX formulas and extracted images.
|
||||
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 to Markdown, extract text
|
||||
from a PDF, or turn a PDF document into an editable format.
|
||||
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 `cph_hub` MCP server) calls
|
||||
Alibaba Cloud Document Mind to parse the PDF. It:
|
||||
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
|
||||
- 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
|
||||
|
||||
### PDF from a Feishu message
|
||||
### One PDF from a Feishu message
|
||||
|
||||
1. Use `feishu_read_context` to find the `file_key` of the PDF attachment.
|
||||
2. Use `feishu_download_resource` to download it into the workspace.
|
||||
3. Use `convert_pdf_to_md` with the downloaded file path and an output directory.
|
||||
3. Use `convert_pdf_to_md` with `input_path` + `output_dir`.
|
||||
|
||||
### PDF already in the workspace
|
||||
|
||||
1. Use `convert_pdf_to_md` directly with the file path and an output directory.
|
||||
1. Use `convert_pdf_to_md` with `input_path` and `output_dir`.
|
||||
|
||||
### Multiple PDFs (concurrent)
|
||||
|
||||
1. Download or locate every PDF in the workspace first.
|
||||
2. Call **`convert_pdf_to_md` once** with:
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{ "input_path": "sources/a.pdf", "output_dir": "md/a" },
|
||||
{ "input_path": "sources/b.pdf", "output_dir": "md/b" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
3. Hub submits Docmind jobs with bounded concurrency (default 3, max 8;
|
||||
optional `concurrency` argument). Prefer this over N sequential tool calls.
|
||||
4. **Each item must use a distinct `output_dir`** — the tool always writes
|
||||
`document.md` inside that directory; shared dirs overwrite each other.
|
||||
5. 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. The tool provides
|
||||
accurate formula, table, and image extraction that manual methods cannot
|
||||
match.
|
||||
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 the generated markdown back to the
|
||||
user if they requested it.
|
||||
- After conversion, use `send_file` to send generated markdown (or a zip you
|
||||
assemble) back to the user if they requested delivery.
|
||||
|
||||
## Output
|
||||
|
||||
The tool returns a list of generated files:
|
||||
Per `output_dir`:
|
||||
|
||||
- `document.md` — the main markdown file
|
||||
- `*.jpg` / `*.png` — extracted images, referenced from the markdown
|
||||
|
||||
## Cost
|
||||
|
||||
The conversion is billed per page (0.04 CNY/page ≈ $0.0056/page for the
|
||||
enhanced formula mode). The cost is automatically recorded on the run's
|
||||
usage ledger.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user