企业官网建设流程全解析

• AI 应用
• NLP
• CLI

本篇技术指南围绕本仓库根目录下的 prompt_md.prompt.md 展开，系统讲解 bilingual_book_maker（Make bilingual epub books Using AI translate）中"翻译提示词"的定制机制：包括 PromptDown 结构化提示词文件的编写格式、--prompt命令行参数的四种配置方式、{text}与{language}占位符的替换原理，以及提示词从 CLI 解析到翻译器调用的完整源码链路。读完本文，你将能够为任意书籍翻译任务编写高质量、可复现的提示词文件，并通过源码证据理解其底层运作方式。

一、关联文档速览：一个 PromptDown 格式的翻译提示词

prompt_md.prompt.md 是本项目提供的一个结构化提示词示例文件，采用 PromptDown（.md）格式书写，内容非常精炼，核心由两部分构成：

# Translation Prompt ## Developer Message You are a professional translator who specializes in accurate, natural-sounding translations that preserve the original meaning, tone, and style of the text. ## Conversation | Role | Content | |-------|---------------------------------------------------------------------------| | User | Please translate the following text into {language}:\n\n{text} |

• ## Developer Message：面向新一代 AI 模型的开发者消息（Developer Message）角色，相当于系统级指令，声明"你是一名专业译者，擅长准确、自然的翻译，并保留原文的意义、语气与风格"。
• ## Conversation：用 Markdown 表格定义一轮对话，其中User角色的内容为Please translate the following text into {language}:\n\n{text}，其中{language}与{text}是运行时替换的占位符（详见下文第四节）。

与之对应的 JSON 版本 prompt_md.json 则提供了同一套翻译策略的完整形态：它包含system角色（"You are a highly skilled translator responsible for translating the content of books in Markdown format from English into Chinese."）与user角色（一套三步翻译流程：① 忠实直译并保持 Markdown 结构；② 对照原文反思，从准确性、流畅性、简洁性三个维度提出改进建议；③ 基于反思精修译文；并以<step1_initial_translation>、<step2_reflection>、<step3_refined_translation>三个 XML 标签分别输出）。这两份文件共同展示了本项目提示词配置的两种典型载体：PromptDown Markdown 文件与** JSON 键值对**。

二、--prompt参数：四种提示词配置方式

在docs/prompt.md中，官方明确说明：要定制提示词，使用--prompt参数，其中user角色模板合法的占位符为{text}和{language}。该参数在 book_maker/cli.py 中定义，metavar为PROMPT_ARG，官方帮助文本指出："它可以是提示词模板字符串，也可以是模板文件的路径。合法占位符是{text}和{language}。"

方式一：内联模板字符串（仅 user 角色）

不需要设置system角色时，直接传入一段含占位符的文本：

--prompt "Translate {text} to {language}."

更丰富的模板示例（对应 prompt_template_sample.json 的 user 字段思路）：

Translate the given text to {language}. Be faithful or accurate in translation. Make the translation readable or intelligible. Be elegant or natural in translation. If the text cannot be translated, return the original text as is. Do not translate person's name. Do not add any additional text in the translation. The text to be translated is: {text}

方式二：TXT 模板文件（仅 user 角色）

将上述文本保存为prompt_template_sample.txt，然后传入文件路径即可，效果与内联字符串完全一致：

--prompt prompt_template_sample.txt

从源码看，parse_prompt_arg对.txt后缀的处理是"读文件全文并包装为{"user": 文件内容}"，即 TXT 文件本质就是 user 角色模板的载体。

方式三：JSON 字符串 / JSON 文件（user + system 双角色）

需要同时设置system与user角色时，使用 JSON 格式。既可以直接传 JSON 字符串：

--prompt '{"user":"Translate {text} to {language}", "system": "You are a professional translator."}'

也可以传 JSON 文件路径（例如 prompt_template_sample.json）：

--prompt prompt_template_sample.json

对应的 JSON 文件内容格式为：

{ "system": "You are a professional translator.", "user": "Translate the given text to {language}. Be faithful or accurate in translation. Make the translation readable or intelligible. Be elegant or natural in translation. If the text cannot be translated, return the original text as is. Do not translate person's name. Do not add any additional text in the translation. The text to be translated is:\n{text}" }

方式四：PromptDown Markdown 文件（推荐的结构化方式）

本项目引入 PromptDown 格式（.md文件）以支持更结构化的提示词，即本文主角 prompt_md.prompt.md：

--prompt prompt_md.prompt.md

PromptDown 文件支持两种角色声明方式（官方文档 docs/prompt.md 中同时给出了示例）：

• ## System Message（面向传统模型）：You are a professional translator who specializes in accurate translations.
• ## Developer Message（面向新一代 AI 模型）：You are a professional translator who specializes in accurate translations.

再配合## Conversation表格中定义User角色的消息内容，即构成完整的结构化提示词。prompt_md.prompt.md正是采用了Developer Message这种较新的写法。

三、PromptDown 解析原理：源码级拆解

--prompt之所以能同时接受字符串、TXT、JSON、Markdown 四种形态，全部归功于 book_maker/cli.py 中的parse_prompt_arg函数。其解析优先级与判定逻辑如下：

1. PromptDown 优先：若参数以.md结尾且文件存在，则调用第三方库promptdown的StructuredPrompt.from_promptdown_file()解析文件；
2. 角色提取顺序：developer_message优先于system_message（两者都出现时开发者消息优先），被映射为内部 prompt 的system键；随后遍历conversation中的消息，取第一个role为user的消息内容作为user键；
3. 校验：PromptDown 文件必须至少包含一条 user 消息，且 user 内容必须包含{text}占位符，否则抛出ValueError；
4. 非 Markdown 分支：若参数不以.json/.txt/.md结尾，先尝试按 JSON 字符串解析（json.loads），失败则降级为"纯模板字符串"（{"user": prompt_arg}）；若以.txt结尾则读文件全文作为 user 模板；若以.json结尾则直接json.load；
5. 最终校验：无论何种方式，得到的 prompt 字典必须包含user键且含{text}占位符，且只允许user与system两个键（prompt.keys() - {"user", "system"}必须为空），否则报错。

promptdown依赖声明于 pyproject.toml（promptdown>=0.9.0），并注册了promptdown = "promptdown_cli:main"控制台入口，说明该项目将 PromptDown 作为一等公民依赖。

四、占位符机制：{text} 与 {language} 如何被替换

提示词模板中仅有两个合法占位符，它们在翻译时被实际内容替换：

• {text}：待翻译的文本内容。它是必选占位符——parse_prompt_arg在三种分支中都会校验其存在（ValueError: prompt must contain \{text}``），缺失时直接拒绝启动。
• {language}：目标语言。它由 CLI 的--language参数决定，默认值为zh-hans（简体中文）。

目标语言值在 book_maker/cli.py 中做了归一化处理：当options.language命中 book_maker/utils.py 中LANGUAGES字典的键时，会替换为对应的人类可读语言名（例如zh-hans→simplified chinese）再传入翻译器，从而保证提示词中{language}替换后是模型易理解的自然语言。

五、环境变量方式：免参数定制提示词

除了--prompt命令行参数，还可以通过环境变量设置user与system角色的提示词内容（docs/prompt.md中明确说明）：

• BBM_CHATGPTAPI_USER_MSG_TEMPLATE：对应user角色模板；
• BBM_CHATGPTAPI_SYS_MSG：对应system角色消息。

在 book_maker/translator/chatgptapi_translator.py 中，PROMPT_ENV_MAP明确定义了这两个环境变量的映射关系；初始化时（该文件__init__中）提示词的优先级为：--prompt传入的模板 > 环境变量 > 内置默认提示词（DEFAULT_PROMPT，即"Please help me to translate,\{text}` to {language}, please return only translated content not include the origin text"）。此外还保留了历史遗留变量OPENAI_API_SYS_MSG作为system` 角色的向后兼容来源。

六、提示词在翻译链路中的完整流转

自定义提示词从命令行到真正发起 API 请求，经过如下源码链路：

1. CLI 解析：--prompt参数经parse_prompt_arg()转换为{"user": ..., "system": ...}字典（book_maker/cli.py 处作为prompt_config传入 loader）；
2. 键值映射：book_maker/utils.py 中的prompt_config_to_kwargs()将字典拆解为prompt_template（来自user键）与prompt_sys_msg（来自system键）两个参数；
3. 翻译器接收：ChatGPTAPI类构造函数接收prompt_template与prompt_sys_msg（book_maker/translator/chatgptapi_translator.py），按"显式参数 > 环境变量 > 默认值"的优先级赋值给self.prompt_template与self.prompt_sys_msg；
4. 占位符替换与请求：实际翻译时，self.prompt_template.format(...)将{text}、{language}替换为真实内容，system角色消息同样参与构建对话请求；
5. 批量翻译场景：在 book_maker/translator/base_translator.py 的_build_batch_prompt()中，自定义模板会被拼接上批量指令（要求模型用@@分隔符输出 N 段译文），system消息也会被追加批量上下文说明——这说明自定义提示词在单条与批量两种路径下都会被正确透传与增强。

七、实战示例：完整命令演示

以下命令均可在仓库根目录直接运行（需先按 docs/installation.md 安装依赖并配置相应 API Key，例如OPENAI_API_KEY或BBM_OPENAI_API_KEY）：

# 方式一：内联字符串模板 python3 make_book.py --book_name test_books/animal_farm.epub --prompt "Please translate \`{text}\` to {language}" # 方式二：TXT 模板文件（user 角色） python3 make_book.py --book_name test_books/animal_farm.epub --prompt prompt_template_sample.txt # 方式三：JSON 模板文件（user + system 角色） python3 make_book.py --book_name test_books/animal_farm.epub --prompt prompt_template_sample.json # 方式四：PromptDown Markdown 结构化提示词 python3 make_book.py --book_name test_books/animal_farm.epub --prompt prompt_md.prompt.md # 或配合 --model 指定其他 LLM 后端（如 claude、gemini、groq 等） python3 make_book.py --book_name test_books/animal_farm.epub --model chatgptapi --prompt prompt_md.prompt.md

如需快速验证提示词效果而不消耗大量 token，可追加--test（仅翻译前 10 段，段落数可用--test_num调整）。提示词加载成功后，CLI 会打印prompt config: {...}与Successfully loaded PromptDown file: ...等日志，便于确认自定义模板已生效。

八、最佳实践与注意事项

1. {text}是硬性要求：任何提示词形式都必须包含{text}占位符，否则程序直接报错退出；{language}强烈建议包含，否则模型无法获知目标语言。
2. 结构化优于内联：翻译书籍是长文本、多轮任务，建议像 prompt_md.prompt.md 与 prompt_md.json 那样把"翻译策略 + 反思 + 精修"写进提示词，配合 XML 标签或 JSON 结构化输出，可显著提升长篇译文的一致性与质量。
3. 格式保持是硬约束：参考 prompt_md.json 中的 user 模板，务必在提示词中声明"不改动 Markdown 标记结构、不增删链接、不改 URL、不动代码块内容、保留原始换行、不触碰标题末尾 permalink 与 HTML 标签"——这直接决定双语 EPUB 输出的版式完整性。
4. 键名白名单：JSON 形式的提示词只允许user与system两个键，多余键会触发ValueError。
5. 优先级记忆：命令行--prompt的优先级高于环境变量，环境变量高于内置默认提示词；未做任何定制时项目会使用DEFAULT_PROMPT兜底。
6. 批量模式的适配：使用--batch_size批量翻译时，自定义 user 模板会被自动拼接批量指令，system 消息会被附加分段说明，属预期行为，无需手工适配。

通过本文，你已经掌握了 bilingual_book_maker 提示词定制的全部四种形态、PromptDown 文件的解析源码逻辑、占位符与环境变量机制，以及提示词在翻译链路中的完整流转路径，可以据此为不同书籍、不同语言对编写高质量的定制化翻译提示词。

• AI 应用
• NLP
• CLI