Skip to content
Back to search

ky-markdown-rebuilder

A Codex / Claude Code skill for rebuilding visually complex documents into page-aligned Markdown.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kyriecheungyep--ky-markdown-rebuilder/badge.svg)](/listings/kyriecheungyep--ky-markdown-rebuilder)

HTML

<a href="/listings/kyriecheungyep--ky-markdown-rebuilder"><img src="/api/listings/kyriecheungyep--ky-markdown-rebuilder/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Codex

mkdir -p ~/.codex/skills
git clone https://github.com/KyrieCheungYep/ky-markdown-rebuilder.git \
  ~/.codex/skills/ky-markdown-rebuilder

Claude Code

mkdir -p ~/.claude/skills
git clone https://github.com/KyrieCheungYep/ky-markdown-rebuilder.git \
  ~/.claude/skills/ky-markdown-rebuilder

Antigravity

把仓库复制到当前 workspace,在任务中要求 Agent 按仓库内的 `SKILL.md` 执行。

更新已有安装

Codex:

git -C ~/.codex/skills/ky-markdown-rebuilder pull --ff-only

Claude Code:

git -C ~/.claude/skills/ky-markdown-rebuilder pull --ff-only

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 330 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: ky-markdown-rebuilder
  3. description: Rebuild visual documents into reliable Markdown by combining text extraction with page or screenshot alignment. Use when converting or cleaning up PDFs, slide decks, PPT/PPTX files, HTML pages, long screenshots, Word-like reports, whitepapers, course materials, business decks, scanned documents, or visually dense documents where plain text extraction may jumble layout, charts, timelines, diagrams, tables, screenshots, or logos.
  4. metadata:
  5. short-description: Rebuild visual documents into page-aligned Markdown
  6. ---
  7. # KY Markdown Rebuilder
  8. Use this skill when a document should become Markdown but the visual layout matters. The goal is not just conversion; it is content reconstruction with a reliable visual source of truth.
  9. Core principle:
  10. > Extract text first, render visual pages second, then rebuild Markdown from a page-aligned source of truth.
  11. Default deliverable principle:
  12. > Use intermediate files as working evidence, but deliver only the final calibrated Markdown and, when requested, an outline Markdown.
  13. ## Host Compatibility
  14. This package is portable across Codex, Claude Code, and Antigravity:
  15. - Codex install path: `~/.codex/skills/ky-markdown-rebuilder/`
  16. - Claude Code install path: `~/.claude/skills/ky-markdown-rebuilder/`
  17. - Antigravity: copy the package into the workspace (e.g. `<workspace>/ky-markdown-rebuilder/`) and follow SKILL.md manually
  18. - Shared assets: `scripts/` and `references/`
  19. - Codex-only UI metadata: `agents/openai.yaml`
  20. Both hosts should use the same workflow below. If a host cannot access one helper script or renderer, use its native browser/document tools for that step and keep the output contract unchanged.
  21. ## When To Use
  22. Use for:
  23. - PDF reports, PPT-style PDFs, whitepapers, course packs, proposal decks.
  24. - PPT/PPTX decks, slide exports, Keynote-like slide files.
  25. - Scanned documents and photographed books (Scanned-Document route, `transcribe` mode).
  26. - HTML pages or local web pages that need Markdown reconstruction.
  27. - Long screenshots or image-heavy documents.
  28. - Word/document files that contain diagrams, tables, screenshots, or complex layout.
  29. Do not use for simple text-only files where normal conversion is enough.
  30. ## Output Contract (LOCKED)
  31. This is a hard contract, not a suggestion. `check_output.py` enforces the exact strings below. Do not invent alternative labels, languages, heading levels, or punctuation — every past "format drift" incident came from improvising here.
  32. Language rules:
  33. 1. Structural labels are ALWAYS the exact Chinese strings defined below, regardless of the document language.
  34. 2. Body content and page titles follow the source document language (Chinese, English, Thai, or anything else). Never translate content inside the calibrated file; translation is a separate deliverable (see Filenames).
  35. 3. `## Page NN: Title` uses a half-width colon and zero-padded page numbers (minimum 2 digits). Never use a full-width colon in the heading.
  36. Document header — the first lines of every calibrated file:
  37. ```markdown
  38. # <文档标题>
  39. > 重建说明:模式 <fast|page-aligned|deep-visual|transcribe>;来源 `<源文件名>`;共 <M> 页;原图逐页查看 <N>/<M> 页。
  40. ```
  41. The `原图逐页查看 N/M` count must be TRUE: only pages opened at original resolution count. Contact-sheet thumbnails do NOT count as inspection. Never claim more inspection than actually happened; if only 10 of 50 pages were opened, write `10/50`.
  42. Page section template — identical for `## Page NN:` / `## Region NN:` / `## Screen NN:` routes; `## Sheet: 名称` uses the same four labels:
  43. ```markdown
  44. ## Page 01: <页标题,跟随原文语言>
  45. 源图:[page-01.png](pages/page-01.png)
  46. ### 页面目的
  47. - ...
  48. ### 布局地图
  49. - ...
  50. ### 按区域确认内容
  51. #### 区域 1:<位置与形态,如 左侧 2x2 卡片区>
  52. ...
  53. ### 视觉备注
  54. - ...
  55. ```
  56. Transcribe-mode page template (`transcribe` mode only — 1:1 content reproduction, no visual commentary):
  57. ```markdown
  58. ## Page 01: <页标题;无标题页用 第 01 页>
  59. 源图:[page-01.png](pages/page-01.png)
  60. <该页全部内容 1:1 转写:正文按原文语言,表格转 Markdown 表,保留空单元格与 "-" 占位>
  61. ```
  62. Contract details:
  63. - The only accepted section labels are `### 页面目的`, `### 布局地图`, `### 按区域确认内容`, `### 视觉备注` — exact spelling, H3 level, no colon suffix. English labels (`Page purpose` etc.) and bare-text labels (`页面目的:`) are contract violations. (`transcribe` mode omits the four sections entirely — never mix the two shapes in one file.)
  64. - Region subsections under 按区域确认内容 use `#### 区域 N:<位置>` (full-width colon inside this label is correct).
  65. - Source line: during validation use `源图:[page-NN.png](pages/page-NN.png)`. In the final deliverable (screenshots removed) replace with `源页:第 N 页` (PDF/scan), `源页:Slide NN` (PPT), or `源图:<原始输入文件名>` (single-image input). Every section has exactly one 源图/源页 line, directly under the `##` heading.
  66. - Screenshot links are always RELATIVE paths (`pages/page-01.png`). Absolute paths become dead links the moment the work folder moves or is cleaned; if the pages directory will not survive delivery, use 源页 notes instead of links.
  67. - Title/transition pages may keep each section to a single bullet, but all four sections stay present in page-aligned/deep-visual outputs.
  68. - 视觉备注 must be page-specific. The checker fails when the identical note line appears on 3+ pages. Do not rotate canned sentences.
  69. - Never wrap page body in a full-page code fence. Code fences are only for actual code or verbatim ASCII art. Tables become Markdown tables; the checker fails oversized fences.
  70. - Every table needs a blank line before it. A table glued to the preceding text line (`หน่วย : ล้านบาท` directly above `| ... |`) renders as plain text, not a table. `scripts/fix_tables.py` inserts the missing blank lines; the checker fails glued tables.
  71. - Chemistry/math notation uses `<sub>`/`<sup>` (e.g. H<sub>2</sub>O, Zn + H<sub>2</sub>SO<sub>4</sub>), never code fences, never bare-text approximations.
  72. - Never use HTML whitespace entities (`&nbsp;`, `&emsp;`, `&ensp;`, `&thinsp;`) to imitate the source's indentation or alignment — they render as garbage in plain-Markdown viewers. Visual indentation is layout, not content: drop it, or express structure with lists/blockquotes/tables. The checker fails any occurrence.
  73. - If the source page has no readable title, use `## Page NN: 第 NN 页` — never paste raw OCR garbage as the title.
  74. - Do not invent an H1 title. If the document has no visible title, derive one and mark it: `# <自拟标题>(自拟)`.
  75. Filenames:
  76. - Calibrated: `<source name>.calibrated.md`
  77. - Outline (only when requested): `<source name>.outline.md`
  78. - Translated deliverable (only when requested): `<source name>.calibrated.<lang>.md` (e.g. `.zh.md`). Structural labels stay Chinese, `## Page NN:` keeps the English word "Page" and the half-width colon; only body content and page titles are translated. A translated deliverable is generated from the calibrated file AND spot-checked against original page images — never from the calibrated file alone.
  79. ## Output Modes
  80. Choose the smallest mode that satisfies the user, and state it verbatim in the reconstruction note. The only legal mode names are `fast`, `page-aligned`, `deep-visual`, `transcribe`, `reading` — never invent hybrid names.
  81. | Mode | Use when | Output |
  82. | --- | --- | --- |
  83. | `fast` | The document is mostly linear text | raw conversion plus light cleanup |
  84. | `page-aligned` | Default for decks, PDFs, reports, or mixed text/visual pages | one Markdown section per page/slide/screen |
  85. | `deep-visual` | High-stakes, visually dense, or sales/solution deck material | page-aligned Markdown with per-page original-resolution inspection |
  86. | `transcribe` | Scanned books, forms, budget/reference documents where the user wants the CONTENT 1:1, not layout commentary | per-page 1:1 transcription (text + tables), no four-section template |
  87. | `reading` | User wants a readable article/report | generate only after a page-aligned source exists |
  88. For scanned documents choose between `transcribe` and `deep-visual` by asking what the user will do with the file: reading/searching/quoting the content → `transcribe` (the common case for 100+ page scans); analyzing the page design itself → `deep-visual`. Do not apply the four-section template to hundreds of pages of tables — that is bloat, not rigor.
  89. Important: never generate a `reading` version directly from raw extraction when the source is visually complex. First create or verify the page-aligned source.
  90. ## Document Routing
  91. Route by observed structure, not only by file extension. A file extension is a hint; the screenshot/rendered view and extracted structure are the source of truth.
  92. | Kind | Typical inputs | Default calibrated structure |
  93. | --- | --- | --- |
  94. | `deck` | PPT/PPTX, proposal PDFs, slide-style PDFs | `## Page NN:` with the locked four-section template |
  95. | `report` | Word/PDF reports, whitepapers, manuals | document headings plus page anchors where visual layout matters |
  96. | `scanned` | CamScanner PDFs, photographed books, image-only PDFs | Scanned-Document route (below), `transcribe` template |
  97. | `spreadsheet` | XLS/XLSX/CSV, finance models, dashboards | `## Sheet: Name`, then tables, formulas, charts, dashboard regions |
  98. | `image` | single images, long screenshots, scanned pages | `## Region NN:` with the locked four-section template |
  99. | `html` | web pages, local HTML exports | `## Screen NN:` or `## Section: Name` with DOM/visual region structure |
  100. | `mixed` | files with multiple strong forms | combine the relevant structures; do not force one template |
  101. Flexible routing rules:
  102. - Upgrade a spreadsheet to visual/dashboard treatment when it contains charts, KPI cards, slicers, pivot tables, dashboards, screenshots, or complex merged-cell layouts.
  103. - Upgrade a Word/PDF report to page-aligned treatment when it contains diagrams, tables, sidebars, screenshots, forms, or page-specific visual meaning.
  104. - Treat PPT/solution decks as `deep-visual` by default when they include product imagery, callouts, case studies, comparison matrices, or contact pages.
  105. - If one document contains multiple forms, use section-level routing. Example: a workbook may have a dashboard sheet, raw data sheets, and formula/model sheets.
  106. - Never let routing block output. If classification is uncertain, choose `mixed` and state the chosen structure in the reconstruction note.
  107. ## Scanned-Document Route (no text layer)
  108. Trigger: `pdfinfo`/pypdf shows no text layer, or extraction yields ~0 characters for a visibly full page. Default mode: `transcribe`.
  109. Engine priority — vision model first, tesseract second:
  110. 1. **Vision-model direct reading (preferred).** If the host model or its subagents can read images (Claude, Gemini/Antigravity, GPT-vision), render pages at high DPI and transcribe directly from the original-resolution page images. This beats tesseract decisively on Thai, handwriting, small fonts, and complex tables. Proven pattern for 100+ page documents: split into batches of ~10 pages, one parallel subagent per batch, each instructed to transcribe 1:1 — preserve Thai/original text exactly; convert every table to a Markdown table keeping empty cells and dash-only (`-`) placeholders; handle merged cells by the LOCKED rules (跨列=每列重复内容, 跨行=只写首行其余留空, 多行表头=第一行做表头其余行做正文首行 — see `references/visual-transcription-rules.md`) — then concatenate batches in page order and run `scripts/fix_tables.py` to normalize ragged table rows. Give every subagent an ABSOLUTE output path under `.ky-md-work/<source-name>/` (e.g. `/full/path/.ky-md-work/doc/batch_01_10.md`); relative or improvised batch paths scatter fragments that the parent must hunt down and reassemble.
  111. 2. **Tesseract fallback.** Only when no vision-capable model is available: check `tesseract --list-langs` first; if the document language pack is missing, tell the user and ASK before installing anything (e.g. `brew install tesseract-lang`) — never silently install software. OCR output must still be reconciled against original-resolution images for every page with tables, forms, or money amounts.
  112. 3. **Neither available: STOP and report.** Do not deliver a thumbnail-based "reconstruction" and do not transcribe from low-resolution contact sheets.
  113. Rules for both engines:
  114. - Tables become Markdown tables — never dump a page into a code fence. Unreliable readings (amounts, units, small labels) are marked `[?]` inline rather than silently guessed.
  115. - Degraded pages must be declared: if quota exhaustion, a crashed batch, or any fallback means some pages were NOT transcribed from original-resolution images (e.g. rebuilt from a reference file or a text dump), list those page numbers in the reconstruction note (`> 补充:第 91-99 页因配额耗尽由脚本兜底,未经视觉核对。`) and reduce the `原图逐页查看 N/M` count accordingly. Silent fallback is the single biggest trust-killer in past runs.
  116. - If a reference/companion document is provided by the user, transcribing it is NOT reconstruction: every page taken from the reference instead of the image must be flagged as `内容来自参考文件,未逐页核图`.
  117. ## Workflow
  118. 1. Preflight once per session: `python3 scripts/preflight.py`. It reports which tools exist (markitdown, pdftoppm, pdfinfo, soffice, tesseract + language packs, PIL/pypdf) so the pipeline never discovers missing tools mid-run. Plan around what is actually available; use `python3`, never `python`.
  119. 2. Establish deliverables and output path before conversion:
  120. - default: create `source.calibrated.md`;
  121. - if the user mentions `outline`, `大纲`, `大纲版`, `two files`, `两个文件`, or asks to generate a version based on the calibrated Markdown, create both `source.calibrated.md` and `source.outline.md`;
  122. - do not finish the task until every requested deliverable exists.
  123. 3. Extract a raw text Markdown draft using MarkItDown or the best local extractor. If the text layer is empty, switch to the Scanned-Document route above.
  124. 4. Render visual references into `.ky-md-work/<source-name>/pages/`:
  125. - PDF: render pages to images.
  126. - PPT/PPTX: convert to PDF, then render pages.
  127. - HTML: capture screenshots of the relevant page or viewport.
  128. - Images/long screenshots: use the source image directly or split if needed.
  129. 5. Create a manifest with page number, screenshot path, extracted title, text length, and visual-check priority (`make_manifest.py` understands both form-feed and `<!-- Slide number: N -->` page breaks).
  130. 6. Visual inspection — real rules, not theater:
  131. - contact sheets / thumbnail grids are for TRIAGE ONLY (deciding what to look at); transcribing content from a thumbnail is a contract violation;
  132. - every page ranked high or medium priority in the manifest must be opened at ORIGINAL resolution before its section is written;
  133. - in `deep-visual` and `transcribe` modes, every page with tables, diagrams, KPI numbers, or dense text must be opened at original resolution (in `transcribe` the transcription itself must come from the original-resolution image);
  134. - keep a running count of pages actually opened — it goes into the reconstruction note as `原图逐页查看 N/M 页`, truthfully.
  135. 7. Rebuild Markdown using the locked Output Contract templates. Write pages in batches after inspecting them; do not write the whole document in one pass before inspection is complete. Convert visual structures using `references/visual-transcription-rules.md`.
  136. 8. Validate with `scripts/check_output.py`:
  137. - always pass `--expected-pages N` when the page count is known and `--pages-dir` while screenshots exist;
  138. - for `page-aligned` and `deep-visual` outputs also pass `--require-visual-sections` (`transcribe` outputs must NOT pass it — they have no four-section template);
  139. - paste the checker output into your reply; a failing check blocks delivery.
  140. 9. If an outline was requested in step 2, generate `source.outline.md` from the calibrated version and re-check that both final files exist.
  141. 10. Finalize the deliverable: if the user wants no screenshot links, replace every `源图:[...](...)` line with the matching `源页:` note, then rerun `check_output.py` on the final file.
  142. 11. Cleanup — timing matters:
  143. - NEVER delete rendered pages before the deliverable message is sent; premature cleanup has forced full re-renders when the user pushed back;
  144. - after delivering, keep `.ky-md-work/<source-name>/` in place and tell the user: 中间截图与工作文件保留在 `.ky-md-work/<name>/`,确认内容无误后可以删除(或让我删除);
  145. - delete only after the user confirms or explicitly asks.
  146. ## Page Manifest
  147. Prefer creating a manifest before spending tokens on visual inspection. Use:
  148. ```bash
  149. python3 scripts/make_manifest.py --raw raw.md --pages-dir pages --out manifest.md
  150. ```
  151. The manifest should help decide which pages need visual checks. Typical fields: page number, screenshot path, extracted title, extracted text length, visual-check priority, reason.
  152. When rendering into an existing directory, prefer:
  153. ```bash
  154. python3 scripts/render_pages.py deck.pdf --out-dir deck.pages --clean
  155. ```
  156. ## Artifact Policy
  157. By default, the user should see only final deliverables next to the source file:
  158. ```text
  159. source.calibrated.md
  160. source.outline.md # only when requested
  161. ```
  162. Deliverable location is a hard rule: calibrated/outline files go NEXT TO THE SOURCE DOCUMENT, never inside the skill package folder (the directory containing SKILL.md/scripts/references). The skill folder gets overwritten wholesale on updates — any deliverable stored inside it will be destroyed. If the host copied the skill into the workspace (e.g. Antigravity), treat that folder as read-only tooling and write all outputs elsewhere.
  163. Treat the outline as a first-class requested deliverable, not as an optional summary. If requested, it must be generated in the same run as the calibrated Markdown unless the user explicitly asks to postpone it.
  164. Intermediate evidence (raw extraction, rendered pages, manifest, split pages, draft calibration files) lives in the hidden work folder:
  165. ```text
  166. .ky-md-work/<source-name>/
  167. ```
  168. Cleanup follows the timing rules in Workflow step 11: keep the work folder through delivery, announce it, delete only on user confirmation. If the final calibrated Markdown keeps local screenshot links, the pages directory must stay as long as the file references it.
  169. When the user asks for "only the final file", "only two files", or similar, do not leave raw, manifest, split, or rendered-page artifacts beside the final Markdown files — but the hidden `.ky-md-work/` folder still stays until confirmation.
  170. ## Outline Output
  171. When requested, create an outline file from the calibrated Markdown, not from raw extraction. This is mandatory when the prompt asks for an outline, a second Markdown, or two final files.
  172. Locked outline skeleton (headers always these Chinese strings; body language follows the source):
  173. ```markdown
  174. # <文档标题> - 大纲
  175. > 来源:`source.calibrated.md`(校准版);原始文档 `source.ext`。
  176. ## 1. 核心主线
  177. - ...
  178. ## 2. 结构地图
  179. | 章节 | 来源页/表 | 作用 |
  180. | --- | --- | --- |
  181. ## 3. 详细大纲
  182. ### 3.1 ...
  183. ## 4. 关键证据
  184. | 证据 | 来源 | 为什么重要 |
  185. | --- | --- | --- |
  186. ```
  187. The outline preserves the document's logic without duplicating all details: top-level sections/pages/sheets, key claims or findings, important tables/charts/diagrams and their role, open uncertainties only if the calibrated source marked them. For decks and proposals, group pages by narrative function, not merely page titles. For spreadsheets, group sheets by purpose: dashboard, raw data, assumptions, calculations, outputs, charts.
  188. ## Helper Scripts
  189. Use scripts as mechanical helpers; do not load their source unless you need to edit or troubleshoot them. Always invoke with `python3`.
  190. - `scripts/preflight.py`: report which pipeline tools exist and which are missing, with install hints. Run once per session before planning.
  191. - `scripts/render_pages.py`: render PDF/PPT/PPTX inputs into page screenshots (`--clean` removes stale images first). Handles LibreOffice headless-profile crashes internally and normalizes zero-padding to at least 2 digits.
  192. - `scripts/split_markdown_pages.py`: split raw Markdown on page breaks.
  193. - `scripts/make_manifest.py`: build a page/slide manifest from raw Markdown and screenshots. Understands form-feed and `<!-- Slide number: N -->` breaks.
  194. - `scripts/check_output.py`: enforce the Output Contract. Key flags: `--expected-pages N`, `--pages-dir DIR`, `--require-visual-sections` (page-aligned/deep-visual only).
  195. - `scripts/fix_tables.py`: pad ragged Markdown table rows to the table's max column count. Run on `transcribe` outputs after concatenating batches.
  196. ## Quality Gate
  197. A page-aligned output is not acceptable if it only summarizes each page. For visual decks and solution proposals, each page section must include enough visual guidance that a reader can reconstruct the slide's information architecture.
  198. Minimum contract per page: the locked four sections, one 源图/源页 line, region-grouped confirmed text, visual relationships (highlighted columns, center nodes, arrows, callouts, before/after areas, image roles), and an uncertainty note only when text or logos are not reliably legible.
  199. Before final delivery, verify:
  200. - Does every page section follow the locked template exactly (labels, levels, source line)?
  201. - Is the `原图逐页查看 N/M` claim in the header truthful?
  202. - Could a reader tell where the text appeared on the slide?
  203. - Are product images, diagrams, callouts, and highlighted areas described?
  204. - Are dense pages structured as tables, region groups, or ordered steps instead of loose bullets?
  205. - Did the output avoid merging adjacent slide content?
  206. - Did it avoid generic filler ("主体区域承载段落、卡片或图示信息") when the actual regions are visible?
  207. - Did it avoid rotating canned 视觉备注 sentences across pages?
  208. For `page-aligned` and `deep-visual` outputs, run:
  209. ```bash
  210. python3 scripts/check_output.py --md deck.calibrated.md --pages-dir deck.pages --expected-pages N --require-visual-sections
  211. ```
  212. ## References
  213. Load references only when needed:
  214. - `references/visual-transcription-rules.md`: how to convert diagrams, timelines, tables, screenshots, and logos to Markdown.
  215. - `references/output-formats.md`: locked templates for all routes and deliverables.
  216. - `references/token-control.md`: strategies for minimizing context use on large documents.
  217. ## Reliability Rules
  218. - Treat page-aligned Markdown as the source of truth.
  219. - Do not merge adjacent pages unless the output mode is explicitly `reading`.
  220. - Do not invent unreadable small text, logos, chart labels, or screenshot details.
  221. - Mark uncertain visual details as `无法可靠辨认` or omit them.
  222. - Never claim inspection that did not happen: reconstruction notes report the true original-resolution page count, and reference-file transcription is flagged per page.
  223. - Keep screenshot links for visual verification while intermediate evidence is retained; in deliverable-only mode, use the locked 源页 notes instead.
  224. - Prefer tables for timelines, matrices, repeated item grids, and comparison layouts.
  225. - Prefer module + relationship lists for architecture diagrams.
  226. - If you correct an OCR/reference error (e.g. a garbled patent number), list every correction in 视觉备注 so the user can audit it.
README.md · README · 239 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # KY Markdown Rebuilder
  2. 把视觉文档重建成**可核对、按页对齐、结构可靠的 Markdown**。
  3. 它不是普通的“文件转 Markdown”工具,而是一套面向 Codex、Claude Code 和 Antigravity 的文档重建 Skill:先提取文本,再渲染原始页面,最后结合页面视觉结构校准内容,并通过脚本检查页数、格式、图片链接和输出契约。
  4. 适合处理普通文本提取容易失真的资料,例如 PDF、PPT/PPTX、扫描件、长截图、报告、白皮书、课程资料、方案 deck,以及包含表格、流程图、架构图、时间线、卡片或多栏布局的文档。
  5. ## 为什么用它
  6. 普通转换工具通常只保留文本,容易出现阅读顺序错乱、跨页串内容、表格散架、图示关系丢失等问题。
  7. KY Markdown Rebuilder 使用“文本提取 + 页面渲染 + 原图核对 + 机械验收”的方式重建文档:
  8. - 每页、每张 Slide 或每个视觉区域单独成节,避免相邻页面内容混在一起。
  9. - 保留标题、分栏、卡片、表格、流程、矩阵和图示关系。
  10. - 对视觉密集页面使用原始分辨率检查,而不是从缩略图猜内容。
  11. - 扫描件优先使用视觉模型逐页转写,无法使用时才回退到 Tesseract OCR。
  12. - 无法可靠辨认的金额、单位或小字会显式标记,不静默猜测。
  13. - 输出前运行检查器;格式漂移、缺页、死链接或表格错误会阻止交付。
  14. - 如实记录真正打开原图核对的页数,不把缩略图浏览算作逐页检查。
  15. ## 支持的输入
  16. - PDF 报告、白皮书、手册、课程资料
  17. - PPT / PPTX / slide deck / 方案文件
  18. - 扫描 PDF、拍照书页、图片型文档
  19. - Word 风格报告和图文混排文档
  20. - HTML 页面、本地网页导出
  21. - 长截图和单张复杂图片
  22. - 带图表、KPI 卡片或仪表盘的表格文件
  23. 纯文本或结构简单的 Markdown 不需要使用本 Skill,直接转换更快。
  24. ## 输出模式
  25. | 模式 | 适用场景 | 结果 |
  26. | --- | --- | --- |
  27. | `fast` | 以线性文本为主的文档 | 原始转换 + 轻量清理 |
  28. | `page-aligned` | PDF、报告、普通 deck、图文混排资料 | 每页一个 Markdown 区块 |
  29. | `deep-visual` | 高风险、视觉密集、销售或解决方案 deck | 逐页原图检查 + 视觉结构重建 |
  30. | `transcribe` | 扫描书籍、表格、预算或档案资料 | 按页 1:1 转写正文和表格,不添加版式评论 |
  31. 如果需要更适合连续阅读的文章版,可以在 `page-aligned` 校准版完成后继续生成 `reading` 版本;不会直接从未经校准的原始提取结果生成。
  32. ## 默认产物
  33. 默认生成:
  34. ```text
  35. source.calibrated.md
  36. ```
  37. 如果用户要求“大纲”“outline”或“两个文件”,还会生成:
  38. ```text
  39. source.outline.md
  40. ```
  41. 如需翻译版,会单独生成:
  42. ```text
  43. source.calibrated.zh.md
  44. ```
  45. 翻译版从校准版生成,并回到原始页面抽查;不会把翻译混进原文校准文件。
  46. 中间截图、原始提取、页清单和分批草稿统一保存在:
  47. ```text
  48. .ky-md-work/<source-name>/
  49. ```
  50. 这些证据文件会保留到用户确认结果无误后再删除。
  51. ## 安装
  52. ### Codex
  53. ```bash
  54. mkdir -p ~/.codex/skills
  55. git clone https://github.com/KyrieCheungYep/ky-markdown-rebuilder.git \
  56. ~/.codex/skills/ky-markdown-rebuilder
  57. ```
  58. ### Claude Code
  59. ```bash
  60. mkdir -p ~/.claude/skills
  61. git clone https://github.com/KyrieCheungYep/ky-markdown-rebuilder.git \
  62. ~/.claude/skills/ky-markdown-rebuilder
  63. ```
  64. ### Antigravity
  65. 把仓库复制到当前 workspace,在任务中要求 Agent 按仓库内的 `SKILL.md` 执行。
  66. ### 更新已有安装
  67. Codex:
  68. ```bash
  69. git -C ~/.codex/skills/ky-markdown-rebuilder pull --ff-only
  70. ```
  71. Claude Code:
  72. ```bash
  73. git -C ~/.claude/skills/ky-markdown-rebuilder pull --ff-only
  74. ```
  75. ## 环境预检
  76. 安装后建议先运行:
  77. ```bash
  78. python3 ~/.codex/skills/ky-markdown-rebuilder/scripts/preflight.py
  79. ```
  80. 预检会报告当前环境是否具备:
  81. - `pdftoppm` / `pdfinfo`:PDF 页渲染、页数和文本层检测
  82. - `soffice`:PPT/PPTX 转 PDF
  83. - `markitdown`:原始文本提取
  84. - `tesseract`:扫描件 OCR 后备方案及已安装语言包
  85. - `PIL` / `pypdf`:图片处理和 PDF 文本层检查
  86. 并非所有输入都需要全部工具。Skill 会根据文件类型和当前环境选择可用路线,不会在任务中途静默安装依赖。
  87. ## 使用方式
  88. 在 Codex 或 Claude Code 中直接点名 Skill:
  89. ```text
  90. 使用 $ky-markdown-rebuilder,把 proposal.pdf 重建成按页对齐的 Markdown。
  91. ```
  92. 视觉密集的方案或销售 deck:
  93. ```text
  94. 使用 $ky-markdown-rebuilder,以 deep-visual 模式重建这个 PPTX,
  95. 并额外生成一份 outline。
  96. ```
  97. 扫描件 1:1 转写:
  98. ```text
  99. 使用 $ky-markdown-rebuilder,把这份扫描 PDF 按原文逐页转写成 Markdown。
  100. 表格保留为 Markdown 表格,不翻译,不要版式分析。
  101. ```
  102. 也可以直接用自然语言触发:
  103. ```text
  104. 把这个视觉结构复杂的 PDF 重建成可核对的 Markdown,保留每页结构和表格。
  105. ```
  106. ## 工作流程
  107. ```text
  108. 环境预检
  109. → 提取原始文本
  110. → 渲染逐页原图
  111. → 建立页清单并判断检查优先级
  112. → 按原图重建 Markdown
  113. → 运行输出检查器
  114. → 交付校准版 / 大纲版
  115. ```
  116. 对于无文本层的扫描件,会切换到 `transcribe` 路线:优先从原始分辨率页面直接转写;只有在视觉模型不可用时才使用 Tesseract。
  117. ## 输出质量契约
  118. `scripts/check_output.py` 会在交付前检查关键约束,包括:
  119. - 页码是否连续,页数是否完整
  120. - 每页是否有且只有一个来源行
  121. - 页面标题、固定结构标签和标点是否符合约定
  122. - 截图链接是否真实可用,链接位置是否与实际页面图片一致
  123. - 是否存在整页代码围栏、HTML 空白实体或无法渲染的表格
  124. - 是否重复使用空泛的版式套话或罐头式视觉备注
  125. - `deep-visual` / `page-aligned` 是否包含完整的页面结构信息
  126. 检查失败时不应交付结果;先修正,再重新运行检查。
  127. ## 内置脚本
  128. | 脚本 | 用途 |
  129. | --- | --- |
  130. | `scripts/preflight.py` | 检查文档处理工具和语言包 |
  131. | `scripts/render_pages.py` | 把 PDF、PPT、PPTX 渲染成逐页图片 |
  132. | `scripts/split_markdown_pages.py` | 按分页符或 Slide 标记拆分原始 Markdown |
  133. | `scripts/make_manifest.py` | 生成页码、标题、文本长度和视觉检查优先级清单 |
  134. | `scripts/check_output.py` | 检查页数、格式、链接和输出质量契约 |
  135. | `scripts/fix_tables.py` | 修复扫描件转写后列数不齐的 Markdown 表格 |
  136. 所有脚本统一使用 `python3` 调用。
  137. ## 目录结构
  138. ```text
  139. ky-markdown-rebuilder/
  140. ├── SKILL.md
  141. ├── agents/
  142. │ └── openai.yaml
  143. ├── references/
  144. │ ├── output-formats.md
  145. │ ├── token-control.md
  146. │ └── visual-transcription-rules.md
  147. └── scripts/
  148. ├── check_output.py
  149. ├── fix_tables.py
  150. ├── make_manifest.py
  151. ├── preflight.py
  152. ├── render_pages.py
  153. └── split_markdown_pages.py
  154. ```
  155. ## English
  156. KY Markdown Rebuilder is a document-reconstruction skill for Codex, Claude Code, and Antigravity. It turns visually complex PDFs, slide decks, scanned documents, long screenshots, and reports into reliable, page-aligned Markdown.
  157. Instead of trusting plain text extraction alone, it combines text extraction, page rendering, original-resolution visual inspection, structured reconstruction, and automated output validation. It also provides a dedicated `transcribe` route for image-only or scanned documents.
  158. Typical usage:
  159. ```text
  160. Use $ky-markdown-rebuilder to rebuild this PDF as page-aligned Markdown.
  161. Create an outline as a second deliverable.
  162. ```
  163. Typical output:
  164. ```text
  165. source.calibrated.md
  166. source.outline.md
  167. ```
  168. See `SKILL.md` for the complete workflow and output contract.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.