章 19 · 篇 III · 实践
智能体技能:把出版物移植到Postext
在Claude Code、Codex或任意智能体中安装postext-port技能,让它把PDF、Word、PowerPoint、EPUB、InDesign或HTML源文件转换成沿用原版面的Postext项目
简单来说
本页写给手里已有一本书或一份文档(比如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,向智能体提出要求,然后在沙盒里检查结果。
文字稿
旁白的全部内容,以及画面上出现的内容说明。
- 0:00
画面片头竖排:Postext标志下方,从右往左依次是小标题“教程 · 五个步骤”、标题“把你的出版物”“转换成 Postext”(金色),以及副标题“借助 AI 智能体,无需编程。”
- 0:03
画面右缘竖写着“你的出版物已经存在。”三张中文页面依次落下:一本书、一本手册和一份红头公文,分别标着InDesign(IDML)、Word(DOCX)和PDF。三页聚到一起,一条金色虚线箭头穿过“AI 智能体”标签,指向一个名为“我的书.postext”的文件图标;右缘换成“智能体把它转换成 Postext。”和“五个步骤,几句写清楚的要求。”
旁白你手上已经有一部出版物:一本书、一本手册、一份公文。它存在InDesign、Word或PDF里。在这个教程里,AI智能体会替你把它转换成Postext。不用写代码:五个步骤,再加几句写清楚的要求。
- 0:23
画面“计划”:旁白每说出一步,就出现一张编号卡片:01 整理文件夹、02 找齐矢量原稿、03 放一份参照样张、04 交给智能体、05 在沙盒里检查。
旁白计划是这样的:整理文件夹、找齐矢量原稿、放一份参照样张、交给智能体,最后检查结果。
- 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)…)。
旁白第一步,把所有材料放进电脑上的同一个文件夹。一个项目,一个文件夹。在里面按材料分类建子文件夹:字体、图片、插图,还有文稿。
- 0:49
画面“字体/”一行高亮,一张“字体”卡片显示一个大大的“永”字、思源宋体、思源黑体和加粗三种字样、OTF、TTF、WOFF2三种格式,以及说明“只放有权嵌入的字体:智能体只用你放进去的。”随后竖排出现“文件夹越整齐,”“要猜的越少。”,文件夹结构里的每个子文件夹都打上勾。
旁白别忘了字体。中文字体文件很大,而且大多需要授权,只放你有权嵌入的字体,比如思源宋体这样的开源字体。智能体只会用你放进去的字体。文件夹越整齐,智能体要猜的就越少。
- 1:08
画面第二步:“第二步 · 矢量原稿”“找齐原稿。”一张示意图、一张图表和一张地图以线条绘出,锚点清晰可见,随后出现三个文件图标:.ai Illustrator、.svg SVG和.pdf PDF。
旁白第二步,如果插图是矢量图,比如示意图、图表或地图,请找到原始文件:Illustrator、SVG或PDF。
- 1:19
画面两块面板显示同一张示意图:“书稿”和“模板”指向“页面”,图题“图2-1 内容与设计在这里相遇。”一块标为“从 PDF 截取 · 图的照片”,放大后变得模糊、满是像素块;另一块标为“原稿 · 图本身”,放大后依然清晰。截图面板随后暗下,原稿上的标签被重新打成英文(Manuscript、Template、Pages),四角出现裁切标记,三项打勾:“放大多少倍都清晰”“图上的文字是真正的文字”“原稿 → 付印”。
旁白从成品PDF里截出来的图,不过是那张图的照片;原稿才是图本身。有了原稿,智能体会重建每一张图,放大多少倍都清晰,图上的文字仍是真正的文字,可以翻译。付印时,原稿原封不动地送去印刷。
- 1:41
画面第三步:“第三步 · 参照样张”“展示成品应有的样子。”文件夹结构里,“样张.pdf”高亮,旁边标着“★ 放在根目录”;从中飞出一页,放大成示例课本《山地地貌》的一张竖排书页,标着“样张.pdf”。
旁白第三步很关键:在文件夹的根目录放一份文件,清楚地展示成品应有的样子。PDF最理想。
- 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。最后“猜”字被划掉,金色的“量。”亮起。
旁白智能体会从这些页面读出版式:开本、版心、每行多少字、每页多少行,还有字号、行距和标点的处理方式,再把它们写成版式规则。没有样张,它只能猜;有了样张,它就能量。
- 2:09
画面第四步:“第四步 · 智能体”“用平常的话提出要求。”一个标题为“智能体 · ~/我的书”的窗口打开,旁边是Claude Code、Codex和“或其他任何智能体”三个标签。窗口里,署名“你”的一条消息逐字打出:“安装 Postext 技能:`npx skills add drnachio/postext --skill postext-port`”,智能体回复“✓ 技能已安装:postext-port”。一张“技能 · postext-port”卡片列出:一套成熟的流程、Postext 的全部知识、检查自身工作的工具。窗口是横排的,因为中文界面从左往右读。
旁白第四步,在这个文件夹里打开你的智能体,Claude Code、Codex或者你常用的任何一个,让它安装Postext技能。技能是一套打包好的专业知识。这一个教智能体如何把出版物转入Postext,也给了它检查自己工作的工具。
- 2:29
画面下一条请求逐字打出:“用 postext-port 技能把这本书转换成 Postext。版式以 `样张.pdf` 为准,字体在 `字体/` 里,插图原稿在 `原稿/` 里:请用原稿,不要从 PDF 里截图。先只做第一章,动手之前先给我看规格表。”旁边的文件夹结构里,消息提到样张.pdf、字体/和原稿/时,它们依次亮起,随后出现一张卡片,写着“样章”和一个大大的“1”。
旁白然后用平常的话说出你的要求,告诉它样张、字体和原稿在哪里,并让它先只做一章。
- 2:42
画面十二张暗着的竖排课本页面排成网格,第一张围上金框。一个转动的箭头在它上面数着打磨的轮次(第 1 轮到第 3 轮),出现对勾后,其余十一页随之亮起。下方是:样章 → 打磨 → 推广。
旁白如果内容很长,就先做一个样章,把它打磨到完美,再推广到其余部分。
- 2:50
画面智能体提出四个问题:“照原样复刻,还是重新设计?”“哪些语言?”“印刷、屏幕,还是两者都要?”“横排还是竖排?”。一份任务清单逐项完成:清点材料、测量版式、提取文字、字体和图片、逐页对照、打包文件,随后出现文件“我的书.postext”。第三条请求逐字打出:“第一章通过了。用同样的设计转换其余各章,每一章都和 `样张.pdf` 对照,最后全部打包成一个 .postext 文件。”智能体回复“✓ 12 章 · 0 个警告 · 我的书.postext”。
旁白智能体会问你几个问题:照原样复刻还是重新设计、哪些语言、用于印刷还是屏幕、横排还是竖排。然后它测量、提取、组装、检查,最后交给你一个Postext文件。样章没问题之后,扩展到整本书只需要再提一个要求。
- 3:18
画面第五步:“第五步 · 沙盒”“逐页检查。”浏览器窗口的地址栏里打出postext.dev/zh/sandbox。指针点击侧栏的“书库”,再点“新建”和“打开.postext文件…”;文件飞入,“我的书 · 12 章 · 184 页”出现在列表顶端,Canvas视图里打开它的前几页竖排页面;视图标签依次是Canvas、HTML、PDF、书页和EPUB 3。
旁白第五步,打开postext.dev上的Postext沙盒,在“书库”里选择“新建”,打开你的文件。
- 3:26
画面侧栏换成“版面设计”面板,“书写系统”一节里是“中文默认设置”和一个“查看…”按钮。各项设置逐行打勾:语言 zh-Hans、正文字体 思源宋体、标题字体 思源黑体、首行缩进 2字、对齐 两端对齐、图题 图1-1 标题、章节编号 第一章、列表 一、(一)1.(1)①、脚注 ①,每页重新编号。
旁白如果是从零开始的中文书,“版面设计”里的“中文默认设置”可以一次套用中国大陆的排版习惯。
- 3:35
画面样张和Postext排出的页面并排放着,分别标为“样张”和“POSTEXT”。“检查”面板打开,列出三个问题:CJK行排不满(第四页)、PDF字体缺字(第七页)、标注框超出所在栏(第七页);Postext的页面上,红框标出每一处。
旁白对照样张逐页检查。“检查”面板会替你指出问题:排不满的行、字体里缺的字、超出所在栏的标注框。
- 3:45
画面两排示意页面,“样张 · PDF”和“POSTEXT · 内容流动”。在流动的那一排里,一张“图”从第一页移到第二页的栏首,一条虚线连起它的两个位置。竖排文字:“同样的规则,”“不同的页面。”“内容是流动的:某张图或某个分页可能落在别处。”随后,每对页面之间出现等号,标题为“必须一致的”:开本、版心与字格;字体与字号;图和标注框的样式;版面干净:无孤字,各栏齐平。一块带≠号的红色面板写着“手工的手艺判断”和“不是规则,排不了不断变化的内容”。
旁白有一点要记住:页面不必和你的PDF一模一样。Postext学到的是版式规则,你的内容现在是流动的,所以某张图或某个分页可能落在别处。应该一致的是品质,同样的制作水准。手工排版时,我们会做许多细小的手艺判断,它们并不是规则;而只有规则,才能排好不断变化的内容。
- 4:13
画面智能体的窗口再次出现,第四条请求逐字打出:“沙盒里第二章第7页:“提示”框被拆到了两栏,书眉也不见了。“检查”面板显示有3行排不满。请修正后重新打包。”并附上一张截图“截图-第二章-第7页.png”。随后,沙盒(检查)和智能体(修正)之间的循环转了第 1 轮到第 3 轮,警告数从3降到0,最后出现对勾和竖排的“完全正确。”
旁白然后把你看到的告诉智能体,越具体越好:哪一章、哪一页、哪里不对。附一张截图会更有帮助。打开新版本,再检查,如此反复。每一轮都更接近,直到完全正确。
- 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版本。你把内容和形式分开了:文字存在干净的章节里,设计存在模板里,版式规则都从你的原件推导而来。
- 4:47
画面一排竖排书页上方,“修订”“增补”“翻译”三个标签依次亮起:一行被高亮,一道光扫过书页;又滑入两页;随后书页翻转为同一模板排出的英文版。一条请求逐字打出:“增加一个英文版:翻译正文、图题和示意图上的文字,设计保持不变。”说明文字:“同样的规则,新的内容,页面自己排好。”接着竖排出现“一个文件,整本书。”:一个.postext图标分出四支,分别通向一张带裁切标记的页面(可付印的 PDF)、一台文字按屏幕重新排成竖行的电子阅读器(EPUB 电子书)、一个浏览器窗口(网页阅读器)和一对页面(每一页都排好)。
旁白所以当内容变化时,修订、增补或者翻译,你都不必再操心排版。Postext会按同样的规则重新排。整本书只有一个文件:可付印的PDF、EPUB电子书、网页阅读器,还有会自己排版的页面。
- 5:09
画面片尾:Postext标志、标语“为网页而生的可编程排版引擎”、postext.dev、一个写着“本视频的提示词都在简介里 ↓”的胶囊框,以及页脚“开源 · MIT · GITHUB.COM/DRNACHIO/POSTEXT”。
旁白Postext开源项目,网址postext.dev。示例提示词都在视频简介里。
YouTube上也有:在那里观看,或者看Postext播放列表。
#技能包含什么
- 一套工作流程:
- 商定需求;
- 清点源文件;
- 测量版面设计,写成规格表;
- 搭建项目框架;
- 提取内容;
- 整理成Postext Markdown;
- 准备字体和图片;
- 逐页核对;
- 打包。
- 参考资料:
- 文档格式和配置清单,两者都对照引擎核实过;
- 项目(文件包)格式;
- 每种源格式各一份操作手册;
- 一套版面设计分析方法;
- 一份已解决的版面案例目录:各有配色的篇、章首页、诗歌、边注、脚注、索引、浮动/拆分/嵌套的标注框、矢量印刷原稿、保留真实文字的图、表格单元格中的图片、横排表、双语版本等;
- 中文书籍,横排或竖排、右侧装订:在需求中要问什么(文字、地区、方向、装订),如何测量字符网格,如何读取竖排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.py | PDF的页边距、栏、栏间距和行距(即基线网格) |
pdf_extract.py | PDF → 按字体角色(字体/字号/颜色)生成的章节草稿:阅读顺序、段落、去除断词连字符、粗体/斜体、上标/下标、列表、题注 |
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.py | PDF表格 → Postext的TableModel:单元格保留对齐、粗体和底色,合并单元格保留跨度;标题行成为表格的题注和标签,横跨所有列的行成为居中的分组带,表头行按粗体或底色来数,被读成一行的两行会重新分开。pdf_extract.py也会把有线表格直接转成表格资源。 |
pandoc_to_postext.py | DOCX、PPTX、ODT、EPUB、HTML、LaTeX、Markdown、JATS、DocBook → 章节草稿,Word样式映射为标注框和段落样式 |
idml_extract.py | InDesign 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/postextclaude 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 numpybrew install pandoc popplermkdir -p ~/.cache/postext-tools && cd ~/.cache/postext-tools && npm init -y && npm i postext postext-pdf postext-citeproc react @pdf-lib/fontkit @napi-rs/canvasWord、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:导入、导出与移植比较了这两种方式。
智能体按工作流程进行:
- 需求。它询问无法推断的事项:忠实重现还是重新设计,样章还是全书,语言,印刷还是屏幕阅读,以及文字、图片和字体的版权。
- 清点与测量。它读取源文件,写出一份实测数据的规格表:成品尺寸、页边距、栏、行距、字体角色、调色板、章首页、书眉、标注框类别和排放习惯。它还把每一页分为正文流排页和组版页(标注框、标签和地图放在固定位置);在Postext 1.35及以上版本中,它把组版页按版式类型归组,每类用一个页面模板来排,所以与原书一致的版面也保留可以修改和翻译的文字;在更早的版本中,组版页超过三分之一时,它会问你要和原书一模一样的版面,还是要可以修改和翻译的文字。
- 项目。它搭建
my-book/,其中有一个build_preset.py生成器,把规格作为常量保存,并生成preset.json。 - 内容。它用合适的提取器提取章节草稿,再整理成Postext Markdown:标注框、段落样式、篇、用于章首页的标题属性、
:ref引用、表和图资源。 - 核对。它对项目做lint检查,并让
postext build --watch在解压后的项目上一直运行:修改一章或一项设置,大约一秒后查看重新绘制的页面JPEG,再接着修改,直到分页、图和标注框与源文件逐页对上。每完成一个阶段,它都运行完整的检查(postext check和lint)。PDF用于印刷检查,不是每次查看都要生成。 - 交付。它为书页视图设置书的纸张、装订和封面,然后打包出
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来改进这个技能,下一次移植就能直接受益。
