跳到主要内容

章 19 · 篇 III · 实践

智能体技能:把出版物移植到Postext

在Claude Code、Codex或任意智能体中安装postext-port技能,让它把PDF、Word、PowerPoint、EPUB、InDesign或HTML源文件转换成沿用原版面的Postext项目

更新于 2026-10-217分钟enescadefritptzhjaar

简单来说

本页写给手里已有一本书或一份文档(比如PDF、Word或InDesign文件)、想把它转成Postext的人。只要给AI助手(也叫智能体)装上一个叫“技能”的小插件,它就能完成大部分工作。这个技能教智能体怎样复制文字,并按原样重建原书的设计。本页说明怎样安装它、怎样提要求,以及怎样检查结果。一段大约五分钟的视频演示了每一步。

借助编程智能体,把现有出版物转换成Postext项目。

很多人来到Postext时手里已经有一本书:一本印刷用PDF的教材、一份Word报告、一套PowerPoint课程、一本InDesign排的产品目录,或者一本EPUB。移植它要做两件事:

  • 内容:每一章的增强Markdown,连同其中的指令和微格式。
  • 版面设计:一份配置清单,重现原书的版面规则(页面几何、基线网格、字体、章首页、书眉、标注框、浮动体、表、篇)。

大语言模型可以完成其中的大部分工作,但前提是它了解Postext的工作方式。Postext的Markdown不是CommonMark,配置里也有一些陷阱,只有页面排错时才会暴露出来。postext-port技能把这些知识,连同我们构建沙盒里每个预设时用过的工具打包在一起,让你的智能体把移植做好。

它遵循开放的Agent Skills格式,因此可用于Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、OpenCode以及许多其他智能体。

#观看教程

五分钟,不用写代码:准备文件夹,带上矢量原稿,加入一份参考PDF,向智能体提出要求,然后在沙盒里检查结果。

文字稿

旁白的全部内容,以及画面上出现的内容说明。

  1. 0:00

    画面片头竖排:Postext标志下方,从右往左依次是小标题“教程 · 五个步骤”、标题“把你的出版物”“转换成 Postext”(金色),以及副标题“借助 AI 智能体,无需编程。”

  2. 0:03

    画面右缘竖写着“你的出版物已经存在。”三张中文页面依次落下:一本书、一本手册和一份红头公文,分别标着InDesign(IDML)、Word(DOCX)和PDF。三页聚到一起,一条金色虚线箭头穿过“AI 智能体”标签,指向一个名为“我的书.postext”的文件图标;右缘换成“智能体把它转换成 Postext。”和“五个步骤,几句写清楚的要求。”

    旁白你手上已经有一部出版物:一本书、一本手册、一份公文。它存在InDesign、Word或PDF里。在这个教程里,AI智能体会替你把它转换成Postext。不用写代码:五个步骤,再加几句写清楚的要求。

  3. 0:23

    画面“计划”:旁白每说出一步,就出现一张编号卡片:01 整理文件夹、02 找齐矢量原稿、03 放一份参照样张、04 交给智能体、05 在沙盒里检查。

    旁白计划是这样的:整理文件夹、找齐矢量原稿、放一份参照样张、交给智能体,最后检查结果。

  4. 0:34

    画面第一步,节标题竖排在右缘:“第一步 · 文件夹”“一个项目,一个文件夹。”一个大文件夹“我的书/”浮在十个零散文件中间:思源宋体-Regular.otf、封面.jpg、图1-1.ai、第一章.docx、思源宋体-Bold.otf、地图.svg、照片-07.jpg、思源黑体-Bold.otf、书.idml、图表.pdf。随后打开一个显示文件夹结构的窗口,旁白每说出一类,文件就飞进对应的子文件夹:样张.pdf(成品应有的样子 → 第三步)、字体/(思源宋体、思源黑体…,.otf .ttf .woff2)、图片/(照片,.jpg .png)、原稿/(矢量原稿,.ai .svg .pdf)和文稿/(Word、InDesign(IDML)…)。

    旁白第一步,把所有材料放进电脑上的同一个文件夹。一个项目,一个文件夹。在里面按材料分类建子文件夹:字体、图片、插图,还有文稿。

  5. 0:49

    画面“字体/”一行高亮,一张“字体”卡片显示一个大大的“永”字、思源宋体、思源黑体和加粗三种字样、OTF、TTF、WOFF2三种格式,以及说明“只放有权嵌入的字体:智能体只用你放进去的。”随后竖排出现“文件夹越整齐,”“要猜的越少。”,文件夹结构里的每个子文件夹都打上勾。

    旁白别忘了字体。中文字体文件很大,而且大多需要授权,只放你有权嵌入的字体,比如思源宋体这样的开源字体。智能体只会用你放进去的字体。文件夹越整齐,智能体要猜的就越少。

  6. 1:08

    画面第二步:“第二步 · 矢量原稿”“找齐原稿。”一张示意图、一张图表和一张地图以线条绘出,锚点清晰可见,随后出现三个文件图标:.ai Illustrator、.svg SVG和.pdf PDF。

    旁白第二步,如果插图是矢量图,比如示意图、图表或地图,请找到原始文件:Illustrator、SVG或PDF。

  7. 1:19

    画面两块面板显示同一张示意图:“书稿”和“模板”指向“页面”,图题“图2-1 内容与设计在这里相遇。”一块标为“从 PDF 截取 · 图的照片”,放大后变得模糊、满是像素块;另一块标为“原稿 · 图本身”,放大后依然清晰。截图面板随后暗下,原稿上的标签被重新打成英文(Manuscript、Template、Pages),四角出现裁切标记,三项打勾:“放大多少倍都清晰”“图上的文字是真正的文字”“原稿 → 付印”。

    旁白从成品PDF里截出来的图,不过是那张图的照片;原稿才是图本身。有了原稿,智能体会重建每一张图,放大多少倍都清晰,图上的文字仍是真正的文字,可以翻译。付印时,原稿原封不动地送去印刷。

  8. 1:41

    画面第三步:“第三步 · 参照样张”“展示成品应有的样子。”文件夹结构里,“样张.pdf”高亮,旁边标着“★ 放在根目录”;从中飞出一页,放大成示例课本《山地地貌》的一张竖排书页,标着“样张.pdf”。

    旁白第三步很关键:在文件夹的根目录放一份文件,清楚地展示成品应有的样子。PDF最理想。

  9. 1:50

    画面书页上出现测量:上下两栏竖行的轮廓,栏距2字,切口24 mm,天头28 mm,每行30字,每页26行;标题、正文和图题分别标为“标题 · 思源黑体 11 pt”“正文 · 思源宋体 小五 9/15 pt”“图题 · 思源黑体 7.5 pt”;上栏每一行都画出一个个字格,相邻两行之间标着行距15 pt。旁边的“规格表.md”逐行填好:开本 185 × 260 mm(16开)· 竖排右翻;版心 上下两栏 · 每行30字 · 26行;栏距 2字(18 pt);正文 思源宋体 小五 9/15 pt,两端对齐;首行缩进 2字;标题 思源黑体 · 第一章 / 一、;标点 开明式 · GB 避头尾;图题 图1-1 黑体 7.5 pt。最后“猜”字被划掉,金色的“量。”亮起。

    旁白智能体会从这些页面读出版式:开本、版心、每行多少字、每页多少行,还有字号、行距和标点的处理方式,再把它们写成版式规则。没有样张,它只能猜;有了样张,它就能量。

  10. 2:09

    画面第四步:“第四步 · 智能体”“用平常的话提出要求。”一个标题为“智能体 · ~/我的书”的窗口打开,旁边是Claude Code、Codex和“或其他任何智能体”三个标签。窗口里,署名“你”的一条消息逐字打出:“安装 Postext 技能:`npx skills add drnachio/postext --skill postext-port`”,智能体回复“✓ 技能已安装:postext-port”。一张“技能 · postext-port”卡片列出:一套成熟的流程、Postext 的全部知识、检查自身工作的工具。窗口是横排的,因为中文界面从左往右读。

    旁白第四步,在这个文件夹里打开你的智能体,Claude Code、Codex或者你常用的任何一个,让它安装Postext技能。技能是一套打包好的专业知识。这一个教智能体如何把出版物转入Postext,也给了它检查自己工作的工具。

  11. 2:29

    画面下一条请求逐字打出:“用 postext-port 技能把这本书转换成 Postext。版式以 `样张.pdf` 为准,字体在 `字体/` 里,插图原稿在 `原稿/` 里:请用原稿,不要从 PDF 里截图。先只做第一章,动手之前先给我看规格表。”旁边的文件夹结构里,消息提到样张.pdf、字体/和原稿/时,它们依次亮起,随后出现一张卡片,写着“样章”和一个大大的“1”。

    旁白然后用平常的话说出你的要求,告诉它样张、字体和原稿在哪里,并让它先只做一章。

  12. 2:42

    画面十二张暗着的竖排课本页面排成网格,第一张围上金框。一个转动的箭头在它上面数着打磨的轮次(第 1 轮到第 3 轮),出现对勾后,其余十一页随之亮起。下方是:样章 → 打磨 → 推广。

    旁白如果内容很长,就先做一个样章,把它打磨到完美,再推广到其余部分。

  13. 2:50

    画面智能体提出四个问题:“照原样复刻,还是重新设计?”“哪些语言?”“印刷、屏幕,还是两者都要?”“横排还是竖排?”。一份任务清单逐项完成:清点材料、测量版式、提取文字、字体和图片、逐页对照、打包文件,随后出现文件“我的书.postext”。第三条请求逐字打出:“第一章通过了。用同样的设计转换其余各章,每一章都和 `样张.pdf` 对照,最后全部打包成一个 .postext 文件。”智能体回复“✓ 12 章 · 0 个警告 · 我的书.postext”。

    旁白智能体会问你几个问题:照原样复刻还是重新设计、哪些语言、用于印刷还是屏幕、横排还是竖排。然后它测量、提取、组装、检查,最后交给你一个Postext文件。样章没问题之后,扩展到整本书只需要再提一个要求。

  14. 3:18

    画面第五步:“第五步 · 沙盒”“逐页检查。”浏览器窗口的地址栏里打出postext.dev/zh/sandbox。指针点击侧栏的“书库”,再点“新建”和“打开.postext文件…”;文件飞入,“我的书 · 12 章 · 184 页”出现在列表顶端,Canvas视图里打开它的前几页竖排页面;视图标签依次是Canvas、HTML、PDF、书页和EPUB 3。

    旁白第五步,打开postext.dev上的Postext沙盒,在“书库”里选择“新建”,打开你的文件。

  15. 3:26

    画面侧栏换成“版面设计”面板,“书写系统”一节里是“中文默认设置”和一个“查看…”按钮。各项设置逐行打勾:语言 zh-Hans、正文字体 思源宋体、标题字体 思源黑体、首行缩进 2字、对齐 两端对齐、图题 图1-1 标题、章节编号 第一章、列表 一、(一)1.(1)①、脚注 ①,每页重新编号。

    旁白如果是从零开始的中文书,“版面设计”里的“中文默认设置”可以一次套用中国大陆的排版习惯。

  16. 3:35

    画面样张和Postext排出的页面并排放着,分别标为“样张”和“POSTEXT”。“检查”面板打开,列出三个问题:CJK行排不满(第四页)、PDF字体缺字(第七页)、标注框超出所在栏(第七页);Postext的页面上,红框标出每一处。

    旁白对照样张逐页检查。“检查”面板会替你指出问题:排不满的行、字体里缺的字、超出所在栏的标注框。

  17. 3:45

    画面两排示意页面,“样张 · PDF”和“POSTEXT · 内容流动”。在流动的那一排里,一张“图”从第一页移到第二页的栏首,一条虚线连起它的两个位置。竖排文字:“同样的规则,”“不同的页面。”“内容是流动的:某张图或某个分页可能落在别处。”随后,每对页面之间出现等号,标题为“必须一致的”:开本、版心与字格;字体与字号;图和标注框的样式;版面干净:无孤字,各栏齐平。一块带≠号的红色面板写着“手工的手艺判断”和“不是规则,排不了不断变化的内容”。

    旁白有一点要记住:页面不必和你的PDF一模一样。Postext学到的是版式规则,你的内容现在是流动的,所以某张图或某个分页可能落在别处。应该一致的是品质,同样的制作水准。手工排版时,我们会做许多细小的手艺判断,它们并不是规则;而只有规则,才能排好不断变化的内容。

  18. 4:13

    画面智能体的窗口再次出现,第四条请求逐字打出:“沙盒里第二章第7页:“提示”框被拆到了两栏,书眉也不见了。“检查”面板显示有3行排不满。请修正后重新打包。”并附上一张截图“截图-第二章-第7页.png”。随后,沙盒(检查)和智能体(修正)之间的循环转了第 1 轮到第 3 轮,警告数从3降到0,最后出现对勾和竖排的“完全正确。”

    旁白然后把你看到的告诉智能体,越具体越好:哪一章、哪一页、哪里不对。附一张截图会更有帮助。打开新版本,再检查,如此反复。每一轮都更接近,直到完全正确。

  19. 4:32

    画面竖排两列:“不只是”“一个 Postext 版本。”文件“我的书.postext”被一道金线一分为二。一边是“内容 · 写了什么”:chapters/zh-Hans/01-冰川.md,里面是标题“# 冰川如何塑造山谷”、一句引用:ref{id="valleys"}的文字,以及一个写着“冰川是会流动的冰。”的“提示”框。另一边是“形式 · 看起来怎样”:“模板 · 从你的原件推导而来”,列出开本 185 × 260 mm(16开),竖排;版心 2栏 × 30字 × 26行;正文 思源宋体 小五 9/15 pt;标题 思源黑体,第一章 / 一、;标点 开明式,GB 避头尾;图 图1-1,浮动到栏首。

    旁白最妙的是,你得到的不只是内容的Postext版本。你把内容和形式分开了:文字存在干净的章节里,设计存在模板里,版式规则都从你的原件推导而来。

  20. 4:47

    画面一排竖排书页上方,“修订”“增补”“翻译”三个标签依次亮起:一行被高亮,一道光扫过书页;又滑入两页;随后书页翻转为同一模板排出的英文版。一条请求逐字打出:“增加一个英文版:翻译正文、图题和示意图上的文字,设计保持不变。”说明文字:“同样的规则,新的内容,页面自己排好。”接着竖排出现“一个文件,整本书。”:一个.postext图标分出四支,分别通向一张带裁切标记的页面(可付印的 PDF)、一台文字按屏幕重新排成竖行的电子阅读器(EPUB 电子书)、一个浏览器窗口(网页阅读器)和一对页面(每一页都排好)。

    旁白所以当内容变化时,修订、增补或者翻译,你都不必再操心排版。Postext会按同样的规则重新排。整本书只有一个文件:可付印的PDF、EPUB电子书、网页阅读器,还有会自己排版的页面。

  21. 5:09

    画面片尾:Postext标志、标语“为网页而生的可编程排版引擎”、postext.dev、一个写着“本视频的提示词都在简介里 ↓”的胶囊框,以及页脚“开源 · MIT · GITHUB.COM/DRNACHIO/POSTEXT”。

    旁白Postext开源项目,网址postext.dev。示例提示词都在视频简介里。

YouTube上也有:在那里观看,或者看Postext播放列表。

用 AI 智能体修改 Postext 书:加章节、出新版、改编——教程 2在 YouTube 上观看 (在新标签页中打开) · 按下播放后才会从 YouTube 加载播放器。

#技能包含什么

  • 一套工作流程:
    1. 商定需求;
    2. 清点源文件;
    3. 测量版面设计,写成规格表;
    4. 搭建项目框架;
    5. 提取内容;
    6. 整理成Postext Markdown;
    7. 准备字体和图片;
    8. 逐页核对;
    9. 打包。
  • 参考资料:
    • 文档格式和配置清单,两者都对照引擎核实过;
    • 项目(文件包)格式;
    • 每种源格式各一份操作手册;
    • 一套版面设计分析方法;
    • 一份已解决的版面案例目录:各有配色的篇、章首页、诗歌、边注、脚注、索引、浮动/拆分/嵌套的标注框、矢量印刷原稿、保留真实文字的图、表格单元格中的图片、横排表、双语版本等;
    • 中文书籍,横排或竖排、右侧装订:在需求中要问什么(文字、地区、方向、装订),如何测量字符网格,如何读取竖排PDF,InDesign的注音和双行夹注,Word的东亚版式和从右到左的EPUB,以及如何按书中用字裁剪CJK字体(见中文排版);
    • 日文书籍,竖排、右侧装订的文库本和单行本小说,或横排的技术书:开启日文规则的语言设置(ja,不用任何中文标签),在需求中要问什么(排版方向、版面网格、注音假名、注释、底本的用字),如何按字数和行数测量版面,注音假名和傍点的标记,用aozora.py转换的青空文库文本,日本国立国会图书馆公有领域版本的扫描件,以及保留假名和竖排字形的日文字体子集(见日文排版);
    • 阿拉伯文书籍,现代的或标注元音的古典版本,从右到左排、右侧装订:让整本书转向的语言设置,在需求中要问什么(地区与数字、元音标注、诗体、目录放在书末),如何测量镜像的页面,如何从PDF、Word和维基文库读取阿拉伯文,把诗排成:::verse,每页重新编号的脚注「(١)」,以及保留连写表的阿拉伯文字体子集(见阿拉伯文排版);
    • 漫画和报纸连环漫画:把一页分成若干分格的分割表达式,带有说话人锚点和安全区的分格画面,每种语言一份由引擎嵌字的脚本(对白框、旁白框、拟声词),从右到左阅读的日本漫画和阿拉伯文版本,以及如何从无字原画加译文、从已嵌字的扫描页或从脚本加生成的画面进行移植(见漫画);
    • 特种油墨与模切:PDF或IDML来源中的专色印版和模切厂的印版与图层,每种油墨名称所提示的工艺(金属色、烫印、荧光、不透明白、上光油),并以印刷厂的规格确认,以及按模切线测量的模切形状(见特种油墨与模切);
    • 模板页:把教材、练习册和杂志的固定页面移植为页面模板,模板中的框由Markdown填充;已安装的Postext支持哪一轮移植;每个版本必须通过的检查(见模板页);
    • 印刷实物:如何读出源书的纸张、装订、封面和书脊,并把它们设为书页视图所显示的folio设置,由lint脚本检查。
  • 脚本(Python和Node),在下一节介绍。

#脚本

脚本作用
inventory.py初步查看任意源文件:几何尺寸、字体、使用中的样式、媒体、需要OCR的页面;对按PDF/X印刷的PDF,给出其输出条件和出血,以及重现它们的print设置。它还会列出PDF或IDML的专色印版及每个名称所提示的工艺,以及模切厂的印版和图层。
measure_layout.pyPDF的页边距、栏、栏间距和行距(即基线网格)
pdf_extract.pyPDF → 按字体角色(字体/字号/颜色)生成的章节草稿:阅读顺序、段落、去除断词连字符、粗体/斜体、上标/下标、列表、题注
pdf_figures.py从PDF中裁出图:原始分辨率的照片、SVG预览图、矢量PDF印刷原稿
pdf_regions.py、template_dedupe.py、anchors.py把PDF的固定版面页(课本、练习册、杂志)转成模板页:以毫米为单位定位框的页面模板;方框、页签和高亮的样式;不含文字的页面底图;去掉文字后裁出的图片;以及按阅读顺序排列的Markdown,每页一个页面块(::::page块),每个方框一个槽位。压在其他图形下面、看不见的文字会被剔除。template_dedupe.py把同类页面的模板和样式合并成一套样式库,按角色(box-light-blue、caption-of-picture)而不是按种类和顺序给框命名,并相应改写页面块。anchors.py把地图上的文字变成资源锚点和各版本的::label行。只处理一页时没有可合并的内容,pdf_regions.py extract会自己按角色给框命名(--name-frames,自postext 1.43起)。从postext 1.48起,它把页面上的线条、卡片和图形画成矢量(框与框之间的连接线、指向图片某一点的线、路径元素),不再每页用一张图;template_dedupe.py把排成行列的卡片合并为重复的网格,把页面上的每一条带合并为模块。1.50起,它还把并排的区块排成一行模块,把只有颜色不同的卡片留在同一个网格里(每张卡片指定一个有名字的外观),并让前置页和正文页共用一个基础模板,页码和页面底色在::::page块注明时才画出。从postext 1.51起,草稿需要的手工修整更少:图片只裁出图片本身(被遮住的文字、相邻的底色和白边都不再带进来),页面画在照片上的名牌留在照片上方,方框里的文字一直排到方框边缘,书眉旁的装饰跟着书眉移动,图片下方分栏排的图注各自成为一个框,书里已经命名的颜色把名字给使用它的外观,草稿上下串起来的区块只要并排,仍能排成一行模块。手工修改写在curation.json里:extract会写出一个空文件,manifest每次构建后都会应用它,所以重新构建也不会丢失。框的修补、删除和新增,装饰的删除,允许的重叠,样式的更改,补充的资源,每一项都附上理由;修改指向的模板、框或样式不存在时,构建就会停止。
extract_tables.pyPDF表格 → Postext的TableModel:单元格保留对齐、粗体和底色,合并单元格保留跨度;标题行成为表格的题注和标签,横跨所有列的行成为居中的分组带,表头行按粗体或底色来数,被读成一行的两行会重新分开。pdf_extract.py也会把有线表格直接转成表格资源。
pandoc_to_postext.pyDOCX、PPTX、ODT、EPUB、HTML、LaTeX、Markdown、JATS、DocBook → 章节草稿,Word样式映射为标注框和段落样式
idml_extract.pyInDesign IDML → 按段落样式生成的章节草稿、表和锚定图片;注音、纵中横、着重号和双行夹注转换为:ruby、:tcy、:dots和:warichu,并报告竖排文章和从右到左的装订
aozora.py青空文库文本(CP932编码的zip或.txt)→ Postext Markdown:注音假名、傍点和傍线、带缩进的标题、作为段落样式的字下げ和地付き段落、分页、按JIS X 0213解析的外字、汉文训读符号;同时返回版权与致谢信息,并报告它无法表达的内容
index_marks.py把印刷版的索引重建为:index标记:读取PDF中的索引页,在对应页面上找到每个词条,并在各章中标记相同的词语
comic_panels.py测量漫画页面:根据分格之间的纸面找出各个分格,写出split表达式(从左到右或从右到左,包括斜向的格间距)、格间距和画框,为每个分格裁出一张图片,并输出:::page骨架;在画面上叠加网格以读取说话人锚点和安全区,再把它们画回画面上以便检查
fonts.py、images.py、convert_assets.py对字体做实例化、子集化、缩放和拆分(按书中用字裁剪的中文或日文字体保留其竖排字形和度量,阿拉伯文字体保留其连写字形和tatweel);把图片转换为sRGB、裁边和拼接;把.ai/.pdf插图转换成SVG
preset_kit.py搭建项目及其生成脚本,构建preset.json,打包.postext文件,并检查配置:配置里只应放版式设计,脚本会找出写进设计元素的书中文字,以及大到沙盒放不下的配置
lint_project.py找出解析器和加载器会悄悄弄错的所有问题;对中文、日文和韩文文本,还会找出项目自带字体排不出的字符;对日文文本,会指出设成中文语言的假名文本、中文字体或中文设置、章节里残留的青空文库标记,以及没有读音的汉字索引条目;对阿拉伯文文本,会指出缺少阿拉伯语的语言设置、只有拉丁字母或没有连写表的字体、字母间距、强制断词和斜体强调;对漫画,会指出无法读取的split表达式、与分割单元数不符的分格、未知的图片、对白框样式或分格样式、格式错误的说话人锚点、项目没有附带的嵌字字体,以及各语言版本之间不一致的页面。它还会指出代理常留下的问题:没有inlineMarks的设计文字里的行内标记,固定宽度空格旁多打的普通空格,1.52 之前的引擎中标题里的 chip,用小号 chip 打大写字母而不用:smallcaps[…],以及:::toc这类单行指令后面的:::。配置项列表来自引擎本身的类型
render.mjs用真实引擎在无浏览器环境中排版项目(一个文件夹或一个.postext文件),像沙盒一样读取其配置,并输出警告。加上--jpeg时,它用引擎自己的Canvas渲染器把指定的页面(--pages 12-15)画成JPEG文件,只需一两秒,智能体不必生成PDF就能查看页面;--out写出PDF。为印刷设置的书会输出PREFLIGHT行(低分辨率图片、过细线条、多色小字、超出上限的墨量、靠近裁切线的文字),其PDF按ICC输出特性文件分色。有模切的页面会显示孔下面的页面,和拿在手里一样。
compare_pages.py把源文件页面和Postext页面并排放置,Postext页面取自渲染出的PDF或JPEG文件夹;加--score时衡量两者有多相似,再加--check时,只要检查仍报告框与框重叠,评分就失败;加上--watch DIR并与postext build … --images DIR --watch一起运行时,每当某页改变,就重写该页的对照图和分数
port_audit.py逐项比较原始 PDF 和移植后的 PDF,按内容配对文字:特殊空格、斜体(包括把正体倾斜的伪斜体)、粗体、小型大写、项目符号的大小和粗细、表格单元格的对齐和粗细,以及页码、页眉和正文的颜色。它写出 JSON 和 Markdown 两份报告,按项目和页面计数;交付前请运行
composed_check.py模板页:round读取已安装引擎的版本,说明它支持哪一轮移植、缺少哪些模板页功能;check对每个版本运行postext check和postext html,遇到以下情况就失败:框溢出、未知的模板或槽位、放不进锚点的标签、写进配置里的文字,以及HTML读取框的顺序与Markdown填充框的顺序不一致。从postext 1.48起,框被另一个框盖住或超出自己的盒子时(frameCovered、frameOutsideArea)也会失败,并在最后给出重叠的数目;源文件有意重叠的地方,连同理由记入项目的composed-check.json。拼错的设置和引擎不接受的值(unknownConfigKey、unknownConfigValue)也判为不通过,其余警告全部打印出来。--json-out FILE保存结果,同时保留报告和退出码;保存的检查未通过时,preset_kit.py pack拒绝打包
postext_md.py其他脚本导入的辅助模块,用于以Postext的Markdown方言写出文字:行内标记写成平铺的片段,转义有特殊含义的字符,把会被读成列表、标题或块的段落保留为文字

#安装

#任意智能体(skills.sh)

skills命令行工具会检测你的智能体,并为它们安装该技能:

npx skills add drnachio/postext --skill postext-port

用-a明确指定智能体,用-g全局安装(所有项目可用):

npx skills add drnachio/postext --skill postext-port -a codex -a claude-code -g

网站也发布了同一个技能,所以这样也行:

npx skills add https://postext.dev

#Claude Code插件

Postext仓库同时也是一个Claude Code插件市场。在Claude Code中执行:

/plugin marketplace add drnachio/postext
/plugin install postext@postext

或者在终端中执行:

claude plugin marketplace add drnachio/postext
claude plugin install postext@postext

#让智能体来安装

你可以让智能体代劳,例如:*“安装Postext移植技能(npx skills add drnachio/postext --skill postext-port),然后用它移植这份PDF。”*读取https://postext.dev/llms.txt的智能体会在那里找到本页和安装命令。

#脚本用到的工具

python3 -m pip install pymupdf pillow fonttools brotli numpy
brew install pandoc poppler
mkdir -p ~/.cache/postext-tools && cd ~/.cache/postext-tools && npm init -y && npm i postext postext-pdf postext-citeproc react @pdf-lib/fontkit @napi-rs/canvas

Word、PowerPoint、EPUB和HTML源文件需要Pandoc,生成源文件的页面图像需要poppler,comic_panels.py需要numpy。Node包驱动无浏览器渲染器(需要Node 22.15或更高版本);@napi-rs/canvas是预编译的画布,渲染器借助它直接把书页画成JPEG。可选工具:用于扫描件的ocrmypdf、ImageMagick,以及用于PDF/UA检查的veraPDF。

mkdir -p ~/.local/bin && curl -fL -o ~/.local/bin/postext https://github.com/drnachio/postext/releases/latest/download/postext-macos-arm64 && chmod +x ~/.local/bin/postext

选择适合你的系统的文件(postext-macos-arm64, postext-macos-x64, postext-linux-x64, postext-linux-arm64, postext-linux-x64-musl, postext-windows-x64.exe);有Node时,也可以用npx postext-cli。

工作循环用的是命令行,一个无需安装的独立可执行文件:智能体让项目保持解压状态,并让postext build --watch针对正在处理的页面一直运行,这样每次修改大约一秒后就会以JPEG的形式出现,长书也是如此。Node包是可选的:它们运行render.mjs,提供沙盒的额外检查。两者都不论配置怎么写,始终用bodyText.shapingLanguage: 'host'排版,所以某一行断开的位置可能与沙盒里不同(见与沙盒的区别)。

#使用

把源文件放进工作文件夹,然后提出移植要求。例如:

  • “把manual.pdf的第1–3章移植到Postext,重现它的双栏版面、章首页和标注框。”
  • “把course.docx转换成一本Postext图书。样式‘Nota’和‘Actividad’是标注框。”
  • “把deck.pptx做成一份Postext讲义:幻灯片变成小节,演讲者备注变成正文。”
  • “我们有这本教材的InDesign文件包(IDML + 印刷PDF)。为第1章构建西班牙语和英语的Postext预设。”

对于InDesign书,把InDesign的文件 › 打包生成的文件夹(.idml、印刷PDF、字体和链接的美术文件)交给智能体。技能根据它们推断出版式规则,IDML导入器做不到这一点:InDesign:导入、导出与移植比较了这两种方式。

智能体按工作流程进行:

  1. 需求。它询问无法推断的事项:忠实重现还是重新设计,样章还是全书,语言,印刷还是屏幕阅读,以及文字、图片和字体的版权。
  2. 清点与测量。它读取源文件,写出一份实测数据的规格表:成品尺寸、页边距、栏、行距、字体角色、调色板、章首页、书眉、标注框类别和排放习惯。它还把每一页分为正文流排页和组版页(标注框、标签和地图放在固定位置);在Postext 1.35及以上版本中,它把组版页按版式类型归组,每类用一个页面模板来排,所以与原书一致的版面也保留可以修改和翻译的文字;在更早的版本中,组版页超过三分之一时,它会问你要和原书一模一样的版面,还是要可以修改和翻译的文字。
  3. 项目。它搭建my-book/,其中有一个build_preset.py生成器,把规格作为常量保存,并生成preset.json。
  4. 内容。它用合适的提取器提取章节草稿,再整理成Postext Markdown:标注框、段落样式、篇、用于章首页的标题属性、:ref引用、表和图资源。
  5. 核对。它对项目做lint检查,并让postext build --watch在解压后的项目上一直运行:修改一章或一项设置,大约一秒后查看重新绘制的页面JPEG,再接着修改,直到分页、图和标注框与源文件逐页对上。每完成一个阶段,它都运行完整的检查(postext check和lint)。PDF用于印刷检查,不是每次查看都要生成。
  6. 交付。它为书页视图设置书的纸张、装订和封面,然后打包出my-book.postext。

在沙盒中打开结果:书库 › 新建 › 打开.postext文件…。导入时采用沙盒当前语言的章节和文字。要在Postext的本地副本中处理存放多个项目的文件夹,请设置POSTEXT_PRIVATE_PRESETS_DIR(见沙盒)。

#从代码加载结果

交付的文件并不依赖沙盒。postext包用openBundle打开它,用buildBundle排版整本书,并渲染到Canvas、HTML或PDF(见文件包)。因此,移植结果可以直接供程序使用。程序的输出需要调整时,用createBundle把它导出回.postext文件,在沙盒中微调,再加载修正后的文件。技能自带的无浏览器render.mjs既接受打包好的.postext文件,也接受项目文件夹。

#预期效果

  • 提取器产出草稿,由智能体整理。每一章都要对照原书页面审阅一遍。质量来自这一步审阅。
  • 文字留在Markdown里。配置只放版式设计,书中的每个字都在各章里,所以改错或翻译都是改Markdown。在Postext 1.35及以上版本中,组版页是配置里的页面模板,模板中的框由各章的Markdown填充:译文变长时,标注框随之增高,并把下面的框往下推;从1.37起,地图上的名称是写在Markdown里的标注。在更早的版本中,组版页用固定在原位的标注框、不含文字的整页图片和标签为真实文字的SVG图来排。报告会写明智能体用了哪一种做法,以及所用的版本。如果Postext不把文字写进配置就无法表达某样东西,智能体会停下来,把这个缺口写成议题草稿,再来问你。这个技能从不为了适应某一本书而修改引擎。
  • 所有语言共用一个文件。译本是同一个.postext文件里的一组章节,带有自己的题注和图上的标注,并在每种语言下用postext check检查。
  • 版权由你决定。对授权不明确的图片或字体,智能体会先询问再复制。有授权限制的字体标记为redistributable: false,导出的项目不会包含它们。
  • 在要紧处保持一致。目标是大多数页面的网格、字体、章首页、标注框、图的位置和分页都相同(每章误差不超过一页),而不是断行完全一致。

#所在位置

这个技能位于仓库中的plugins/postext/skills/postext-port。它涵盖了构建沙盒中所有预设(公开的和私有的)时遇到的每一种情况。如果移植时碰到它尚未涵盖的情况,请提交一个issue或pull request来改进这个技能,下一次移植就能直接受益。