persian-writing

波斯语写作与 RTL 文档

有两种彼此独立的问题会让波斯语输出显得像机器生成：

1. 行文听起来像 AI。 技术上没错，却生硬、书面腔十足、夸张—— 伊朗人不会那样写。
2. 版式暴露了文本的问题。 波斯语左对齐，混用了阿拉伯语的 ي/ك 字形， 拉丁数字打乱 RTL 流向，标题孤零零地落在页面底部，字体回退到 DejaVu。

只解决其中一个问题，成品仍会让母语读者截图嘲笑。本技能会同时解决这两个问题。 请按顺序完成下面两份检查清单，并在生成任何内容之前阅读与你的输出格式对应的参考文件。

步骤 0：按任务选择参考资料

任务	阅读
任何波斯语行文（始终适用）	references/writing-style.md
机械规范（始终适用）	references/orthography.md
学术内容：论文、学位论文、报告、مقاله/پایان‌نامه	references/academic.md
教育/技术内容、文档、产品页面、操作指南	references/content-structures.md
Telegram、Instagram、配文、轮播内容、reels、stories	references/social-channels.md
SEO 内容、搜索博客、落地页/广告文案、کپشن فروش	references/seo-copywriting.md
清理/规范化/拼写检查现有文本（ویرایش، پاکسازی）	references/cleanup/paknevis-rules.md + usage-patterns.md
字体选择/嵌入	references/fonts.md
Word/.docx 或 docx→PDF	references/docx-pdf.md
PowerPoint/.pptx	references/pptx.md
HTML、电子邮件模板、HTML→PDF	references/html-css.md
图像/海报（PIL）、新建 PDF（reportlab）、Excel	references/format-skills-fa.md

视觉中立——复制任何代码示例前请阅读。 本技能不设置任何样式。它只规定方向、间距、字形塑造字体和文本，不规定颜色、强调条、卡片背景或统一视觉风格。代码示例中的所有十六进制值、边框和填充都只是普通灰色/黑色占位符；它们用于说明属性应放在什么位置，而不是规定该使用什么值。默认输出为默认背景上的黑色文本，不使用强调色。颜色和视觉形式只能取自：用户的明确要求、附加的品牌/主题技能，或需要匹配的输入模板。若没有这些依据，就不要自行设计配色，也不要把某个示例中的配色沿用到另一个示例中——不加样式才是正确的默认选择，意外出现的紫色标题就是个错误。

本技能与通用 docx/pptx/pdf 技能配合使用：后者处理文件机制；本技能则针对波斯语覆盖并扩展相关规则。如果两者对 RTL 行为的规定不一致，以本技能为准——其规则源自真实波斯语文档的调试经验。如果其他启用的技能或用户指定了特定字体或颜色，则美学方面以其要求为准；本技能仍负责 RTL 机制和正字法。本技能本身不带品牌倾向：代码示例中的颜色只是占位符，Vazirmatn 只是默认字体，并非必选字体。

写作：五秒总结

完整指南见 references/writing-style.md。核心要点：

1. **动笔前先判断语体——语体错误是这项技能可能犯下的代价最高的错误。**遵循 writing-style.md 第 1 部分中的 6 步判断流程。核心规则：判断交付内容的类型，而不是用户输入时的语气（随口说一句“写份提案”，仍然需要正式提案）；如果文本面向第三方且有冲突迹象，就问一个简短的问题，不要猜；完全没有线索 → 正式但有人情味。
   • 提案、发票、报告、正式邮件、网站文案 → 正式但有人情味：使用完整书面形式（比如“会成为”，而不是口语形式）、尊称“您”，完全不用俚语——但用“是”，不用“乃”；句子简短，论断具体。有人情味 ≠ 亲昵随意：提案和合同要保留正式用语（不使用“挺不错”一类口语表达）；温度来自清晰的表达、数字，以及一句温暖的结尾（writing-style.md，“温暖陷阱”）。
   • 公务信函 → 正式语体 + 信函格式（尊称、“您好，谨致问候！”——见 writing-style.md）。
   • Instagram/Telegram、聊天、友好邮件 → 书面口语波斯语（口语化书写）：使用口语形式和语气词，如“呢”“吧”“吗”。
   • 博客、新闻通讯 → 介于两者之间：书面形式、温暖直接的语气。
   • 论文、学位论文、大学报告 → 学术语体：措辞审慎，适当保留余地，可以使用被动语态，不用客套话——参阅 references/academic.md。
   • SEO/销售文案 → 按上述内容类型选择语体，并参阅 references/seo-copywriting.md。
2. 禁用官僚腔表达：“乃”、“需要指出的是”、“为了……”、“具有特别重要的意义”、“发挥了重要作用”。
3. **禁用 AI 腔表达：**破折号（—）、三项并列的固定套路（“快速、简单又可靠”）、“不仅……而且……”、生硬附加的“这表明……”、含糊的“专家认为”、泛泛的“在当今世界”开场白、“最后可以说”式结尾。
4. **保持单一视角。**客观说明事实，直接对读者说话（用动词体现，不要反复说“您”），只有在组织确实做过某事或对此负责时才使用“我们”。在同一节内容里频繁切换这三种视角，是波斯语品牌内容最常见的问题——见 content-structures.md §1。
5. **教学与销售分开。**即使不买任何东西，解释内容也必须值得一读：先说明问题，再介绍产品；不要隐瞒主要答案；每项功能都要关联到可核验的结果；绝不删去限制条件或前提条件——正是这些内容让其余论述可信。
6. **只提出来源支持的主张。**区分事实 / 观点 / 预测 / 主张；绝不为填充某一节而编造统计数据、版本、价格或引言；发现矛盾就明确指出，不要悄悄替其消解；有疑问时问一个问题，不要猜（见 content-structures.md §3）。 改述论文内容时（尤其是学位论文各章节），只能改变措辞和结构：不得添加推论或过渡性关联；保留每个限定词（约、大多、可能、至、至少、有意义）以及来源中的所有数字；研究者自行推理的内容要标注“本文中没有这部分内容”，不要把它融入正文（见 academic.md §5.5）。
7. **母语者检验：**伊朗人会不会把这段文字截图并称作“AI 写的文本”？如果会，交付前就重写。造成这种印象的主要有两个特点：可预测性（每次都用预料中的搭配，如“特别重要”“发挥重要作用”）和均一性（每句话都长 15–20 个词，每段分量都相同）。具体细节能带来真正的变化；fa_lint.py --check --rhythm 会标记节奏平板的问题，但词汇层面的 AI 腔影响大得多——见 writing-style.md §3.5。 目标是写出真正更好的文字，而不是迎合检测器：AI 检测器并不可靠，而且经常以极高的比例误判第二语言写作者；这项技能绝不会帮助掩饰作者身份（§3.6）。
8. 数字、标点和空格必须使用波斯语格式——见下一节。

正字法：不可妥协的规则

完整规则见 references/orthography.md。以下规则适用于所有交付内容：

1. ZWNJ（半空格，U+200C） — 写作 «می‌شود»，而非 «می شود»；写作 «کتاب‌ها»，而非 «کتاب ها»；写作 «بزرگ‌تر»، «خانه‌ام»、«به‌عنوان»。在代码中使用 ‌ 或 HTML ‌。
2. 仅使用波斯字母： 使用 ی (U+06CC)，而非 ي；使用 ک (U+06A9)，而非 ك。
3. 波斯文本中使用波斯数字 ۰۱۲۳۴۵۶۷۸۹。URL、电子邮件、代码和版本号中保留拉丁数字。绝不使用阿拉伯-印度数字 ٤٥٦。
4. 使用波斯标点： ، ؛ ؟，引号使用 «گیومه»。标点前不留空格，后留一个空格。 4b. هکسره — 绝不要把添加语法格标记的 kasre 写成 «ـه»：写作 «کتابِ من»، 而非 «کتابه من»。«ـه» 结尾仅用于口语中的 «است»（«این کتابه» = «این کتاب است»）。可以尝试将其替换为 «است»；如果句子不通，就应该使用 kasre。伊朗人会将这种错误视为粗心的表现，参见 orthography.md §5.1。
5. 波斯语正文中不使用 em dash 或 en dash，改用 «،» 或重组句子。
6. 绝不要将波斯字母分开排写（这会破坏字母连接），也不要伪造粗体或斜体。
7. 波斯语行首绝不能是拉丁词。 聊天应用、GitHub、Telegram 和大多数编辑器会根据每个段落的第一个字母设置方向，因此 «React یک کتابخانه است.» 会从左向右显示，导致对齐错误、句号位于错误一侧、词语顺序混乱。这适用于每个句子、项目符号、标题、表格单元格和说明文字。改用波斯语词语开头： «کتابخانه‌ی React…»، «ابزار Docker…»، «دستور npm install…»。 对于必须以名称开头的纯文本输出，persian_cleanup.py --bidi 会添加不可见的方向标记。完整规则见 orthography.md §9。

两个脚本可机械地执行这些规则，在交付波斯语文本前请同时使用：

# 1. FIX: paknevis-style editorial pass (ZWNJ, chars, digits, punctuation, گیومه)
python3 scripts/persian_cleanup.py --edit --in text.md --out text.md
# 2. LINT: report what still needs contextual judgment (dashes, میشود forms,
#    fake tanvin, register issues) — fix these by hand
python3 scripts/fa_lint.py --check text.md

--edit 可安全用于结构化文件。处理前会暂存围栏代码块、行内代码和表格行，并在处理后逐字节原样恢复；开头缩进也绝不会被折叠。这一点很重要，因为波斯语排版规则适用于正文，却会破坏代码：它们会把 "text" 改成 «text»，把 ASCII 数字改成波斯数字，并抹平表格列所依赖的空格。只有在确实希望这些规则应用于所有内容时，才传入 protect_code=False（Python API）。无论如何，都要将文件纳入版本控制，工具虽谨慎，却并非无所不知。

persian_cleanup.py 是一套完整工具包（合并了 paknevis 和 davat）：可用于 NLP 的强力清理（--preset persian）、单项函数（--fn convert_digits）、使用内置的 453K 词频词典进行拼写检查（--edit --spellcheck），以及自定义处理流程。波斯语的「编辑」请求 → --edit（保守处理，保留内容）；「清理/规范化」→ --preset persian（移除链接、提及和表情符号）。详情见 references/cleanup/。注意：--edit 会采用 خانهٔ 的添加语法格标记样式；若要保留 خانه‌ی，请从 --steps 中移除 fix_ezafe。

字体

字体随项目提供，位于 assets/fonts/（SIL OFL，可免费商用）：

• Vazirmatn — 所有场景的默认字体：正文、UI、文档。共 9 种字重。
• Lalezar — 用于标题、封面和海报的展示字体。只有一种字重，绝不用于正文。

其他字体系列（Shabnam、Sahel、Samim、Parastoo、Tanha、Gandom）及字体搭配建议见 references/fonts.md。离线沙盒中只有随项目提供的字体，scripts/download_fonts.py 仅在可以访问 GitHub 的环境中运行。

进行任何 docx→PDF 或 pptx→PDF 转换前，请先安装字体：

bash scripts/install_fonts.sh   # copies assets/fonts → ~/.fonts, runs fc-cache
fc-list | grep -i vazir         # verify — else LibreOffice silently falls back

跳过此步骤是波斯语 PDF 出现问题的首要原因：转换会「成功」，但所有字形都会变成 DejaVu 豆腐块或彼此断开的字母。

文档：始终适用的规则

特定格式的操作指南见参考文件。以下规则通用：

1. RTL 表示 START，而不是 RIGHT。 在 OOXML 中，当 bidirectional: true 时， AlignmentType.RIGHT 会显示在视觉上的左侧。始终对齐到 START。
2. 每个波斯语文本片段都要设置 rightToLeft: true，并使用带有 hint: "cs" 的字体（Complex Script）。
3. 每个节都要设置 bidi: true。需要从右向左排列的表格： visuallyRightToLeft: true。
4. 带编号内容使用波斯数字——拉丁数字“1.” 会让段落翻转为 LTR。 推论：对于 docx，切勿使用内置的 List Number／List Bullet 样式。 它们的标记位于 numbering.xml 中，该文件不支持 bidi，因而会在错误的一侧显示拉丁数字 1.，并使用会破坏字体嵌入的 OpenSymbol 项目符号。 请将标记写成普通文本片段（«۱. »、«• »）——见 docx-pdf.md §6.1。
5. 添加内容前先修正文档默认设置。 python-docx 从拉丁文字模板开始：styles.xml 中没有波斯语字体，Word 的标题样式还带有你未指定的蓝色。创建 Document() 后立即运行 docx-pdf.md §6.1 中的 persianize_styles(doc)。页眉／页脚属于独立的 XML 部件，需要直接对其应用 RTL 设置。
6. 分页： 标题使用 keepNext + keepLines（避免标题孤行）； 卡片／文本框放入单单元格表格，并设置 cantSplit: true（避免跨页拆分）；列表最后一项后不加分隔符；分节符前不要放多余的 PageBreak（否则会出现空白页）。
7. 符号： 波斯语字体缺少许多字形。随附的 Vazirmatn/Lalezar 字体中仅验证过 • 和 ·；▪ ■ ✓ ✕ ● ◆ ⊙ 会回退到 DejaVu。对于其他符号／字体，请先检查 cmap（fonts.md 说明了方法）。

交付前验证

分两步检查。转换前先检查 .docx（可发现代码审查无法发现的问题），然后检查 PDF：

# 1. DOCX: package integrity FIRST (a file Word won't open can't be RTL-checked),
#    then section bidi, jc=right traps, cs fonts, list numbering, heading colors.
#    --fix repairs missing <w:bidi/>; --sanitize strips the Word-for-Mac template
#    artifacts python-docx inherits (the classic "file is corrupt" fingerprint).
python3 scripts/verify_docx.py output.docx --expect-font Vazirmatn --fix --sanitize

# 2. PDF: fallback fonts, blank pages, template leaks, Arabic chars
python3 scripts/verify_pdf.py output.pdf --expect-font Vazirmatn

verify_docx.py 的存在是因为设置 RTL 标记与该标记实际写入 XML 是两回事：库可能会丢弃节属性中的 bidi，而 OOXML 要求 <w:bidi/> 必须是 <w:sectPr> 的第一个子元素——若追加到其他位置，渲染器就会忽略它。验证生成文件，而非源代码。

它还会检查文件包本身：[Content_Types].xml 必须是 ZIP 中的第一个条目；每个关系 Target 都必须有效；每个 XML 部件都必须格式正确且不含控制字符。修复会写入临时文件，并在替换任何内容前进行验证，因此修复失败不会损坏文档。详情及已损坏文件的处理流程：docx-pdf.md §4.5。

它会检查：近乎空白的页面、“undefined”／模板内容泄漏、未嵌入或回退字体、提取文本中的阿拉伯字母 ي/ك，以及页数。修复所有警告后，重新生成并再次验证。对于正文，请将最终文本与母语测试对照重读——运行一次 persian_cleanup.py --edit + fa_lint.py --check，再认真朗读一遍，就能发现大多数严重问题。

文件

persian-writing/
├── SKILL.md                    ← you are here
├── references/
│   ├── writing-style.md        ← registers, Persian AI tells, colloquial patterns
│   ├── academic.md             ← نگارش علمی: papers, theses, citations, formulas
│   ├── orthography.md          ← ZWNJ, characters, digits, punctuation, ezafe
│   ├── cleanup/                ← paknevis rules, davat API, usage patterns
│   ├── fonts.md                ← catalog, personalities, pairings, embedding
│   ├── content-structures.md   ← POV, education vs promotion, body patterns
│   ├── social-channels.md      ← Telegram/Instagram craft, repurposing
│   ├── seo-copywriting.md      ← Persian SEO writing + کپی‌رایتینگ
│   ├── docx-pdf.md             ← RTL docx recipes, pagination, PDF post-processing
│   ├── pptx.md                 ← RTL PowerPoint via python-pptx / html2pptx
│   ├── html-css.md             ← RTL web, mixed-direction text, print CSS
│   └── format-skills-fa.md     ← PIL posters, reportlab PDFs, Excel RTL
├── scripts/
│   ├── persian_cleanup.py      ← FIX: edit/clean/normalize/spell-check (paknevis+davat)
│   ├── fa_lint.py              ← LINT: report issues needing contextual judgment
│   ├── verify_docx.py          ← DOCX RTL checks (+ --fix for section bidi)
│   ├── verify_pdf.py           ← post-generation PDF checks
│   ├── check_version.py        ← verify the version matches in all four places
│   ├── install_fonts.sh        ← bundled fonts → ~/.fonts (run before PDF export)
│   └── download_fonts.py       ← fetch extra families (needs GitHub access)
└── assets/
    ├── fonts/                  ← Vazirmatn + Lalezar TTFs
    └── persian_words.txt       ← 453K-word frequency dictionary (spell-check)