• 工作流自动化
• 低代码
• 桌面应用
• AI Agent
• 后端

导读

在 astron-rpa 仓库的 AI 服务（backend/ai-service）中，translate_prompt.md是一个面向"工程名称翻译"场景的精简提示词模板：它让大模型把中文工程名翻译成简短、保留原意、全小写且用下划线分隔单词的英文标识符。本篇文章将完整剖析该模板的原文、它背后的占位符替换机制（$name+safe_substitute）、Prompt 注册中心（prompt_dict/format_prompt）以及对外 HTTP 调用方式（POST /v1/chat/prompt）。读完本文，你将掌握该模板在 RPA 组件命名场景中的实际用法、完整的 curl 调用示例、请求参数含义、积分计费规则，以及如何仿照它扩展新的原子能力 Prompt。

一、模板原文与四条硬性翻译约束

模板文件位于 backend/ai-service/app/prompts/translate_prompt.md，全文如下（与仓库原文件逐字一致）：

你是一个翻译大师，你擅长把下面的中文的工程名称翻译成英文，要求简短干练，但保持原有的意思，单词和单词之间用下划线分隔，所有字母均为小写 工程名称：$name 请你只返回翻译后的结果

这份模板虽然只有 4 句有效指令，但每一句都对应一条可被大模型严格执行的约束，也是后续校验输出的依据：

其中"只返回翻译后的结果"这一句在工程上非常重要：它保证了接口响应可以直接作为标识符使用，无需再写正则清洗代码。这一点在 backend/ai-service/app/routers/v1/chat.py 的响应组装逻辑中可以看到，后端直接取data["choices"][0]["message"]["content"]放入响应体data字段返回。

二、占位符机制：$name与safe_substitute

模板中出现的$name是变量占位符，实际内容由调用方在请求参数中注入。模板文件本身不包含任何处理逻辑，真正的替换发生在 Prompt 加载工具中。

2.1 模板注册与读取

backend/ai-service/app/utils/prompt.py 维护了一个 Prompt 注册表prompt_dict，其中"translate"映射到translate_prompt.md（见 prompt.py 第 10 行）：

prompt_dict = { # 主要原子能力 "translate": "translate_prompt.md", "code_review": "code_review_prompt.md", "document_summary": "document_summary_prompt.md", "sql_generator": "sql_generator_prompt.md", "business_analysis": "business_analysis_prompt.md", "email_writer": "email_writer_prompt.md", # 招聘相关 "recruit_keywords": "recruit/recruit_keywords_prompt.md", ... }

模板文件统一存放在 backend/ai-service/app/prompts 目录下，PROMPTS_DIR通过Path(__file__).parent.parent / "prompts"动态定位，与代码位置解耦。

2.2 替换函数format_prompt

format_prompt负责把模板渲染为最终提示词，核心实现基于 Python 标准库string.Template：

def format_prompt(prompt_type: str, params: dict = {}) -> str: """格式化prompt模板""" from string import Template template_file_name = prompt_dict.get(prompt_type) if not template_file_name: raise ValueError(f"Unknown prompt type: {prompt_type}") template_file_path = PROMPTS_DIR / template_file_name if not template_file_path.exists(): raise FileNotFoundError(f"Prompt template not found: {template_file_path}") # 读取文件 content = template_file_path.read_text(encoding="utf-8") template = Template(content) return template.safe_substitute(**params)

关键点：

• 使用safe_substitute而非substitute：当params中缺少某个占位符时，safe_substitute不会抛KeyError，而是保留$name原文，避免因参数缺失导致整个请求崩溃；相对的缺点是模板中残留的$name会被原样发给大模型。
• $是模板语法保留符：如果未来在模板正文中需要书写美元金额（如"费用为 $100"），必须写成$$100转义，这一点在维护模板时需要格外注意。
• 参数以 dict 传入：对translate场景，只需{"name": "用户管理系统"}，渲染后即得到带具体工程名的完整提示词。

2.3 渲染效果示例

假设name = "用户管理系统"，渲染后的最终提示词为：

你是一个翻译大师，你擅长把下面的中文的工程名称翻译成英文，要求简短干练，但保持原有的意思，单词和单词之间用下划线分隔，所有字母均为小写 工程名称：用户管理系统 请你只返回翻译后的结果

示例模型输出（示意，非仓库实际响应）：user_management_system。最终输出的英文标识符可直接用于组件目录名、包名或环境变量名等场景。

三、对外调用方式：POST /v1/chat/prompt

翻译模板通过 AI Service 的预设 Prompt 接口对外暴露。接口定义位于 backend/ai-service/app/routers/v1/chat.py：

@router.post("/prompt") async def chat_prompt( params: ChatPromptParam, points_context: PointsContext = Depends( PointChecker( get_settings().AICHAT_POINTS_COST, PointTransactionType.AICHAT_COST ), ), ): ...

路由注册在 app/main.py：app.include_router(chat.router, prefix="/v1")，因此完整路径为POST /v1/chat/prompt。

3.1 请求参数（ChatPromptParam）

参数 Schema 定义在 backend/ai-service/app/schemas/chat.py：

class ChatPromptParam(BaseModel): model: str = Field(DEFAULT_MODEL, examples=[DEFAULT_MODEL]) stream: bool = Field(False, examples=[True]) prompt_type: str = Field( ..., examples=["translate", "code_review", "document_summary", "sql_generator", "business_analysis", "email_writer"], description="预设prompt类型", ) params: Optional[dict] = Field( None, examples=[ {"name": "用户管理系统"}, # translate ... ], description="prompt模板参数", )

3.2 完整 curl 调用示例

请求头需携带用户身份（详见下文"认证与积分"一节），示例如下：

curl -X POST "http://localhost:8010/v1/chat/prompt" \ -H "Content-Type: application/json" \ -H "X-User-Id: 2" \ -d '{ "model": "maas/deepseek-v3.2", "stream": false, "prompt_type": "translate", "params": {"name": "用户管理系统"} }'

3.3 响应结构

非流式响应经过后端二次封装，返回统一标准结构（StandardResponse定义于 backend/ai-service/app/schemas/init.py）：

{ "code": "0000", "msg": "调用 translate prompt 成功", "data": "user_management_system" }

• code："0000"表示成功，"5001"表示错误（ResCode枚举）。
• data：直接取自上游choices[0].message.content，即模型返回的翻译结果字符串。

3.4 错误处理

路由层有两类显式校验（chat.py 第 57-68 行）：

• 未知 prompt_type：params.prompt_type not in prompt_dict时返回400，并附带当前可用类型列表：

  {"detail": "Unknown prompt type: xxx. Available types: ['translate', 'code_review', ...]"}

• 模板文件缺失：format_prompt内部抛出的FileNotFoundError会被捕获并转为400。
• 上游调用异常：模型 API 超时返回504（"大模型调用超时，请稍后重试"），其他错误按上游状态码透传（见 services/chat.py）。

四、认证与积分计费机制

/v1/chat/prompt不是一个免费接口，它通过PointChecker依赖注入执行积分检查与扣费，这也是模板能力被纳入商用平台管理的一部分。

4.1 用户身份解析

用户 ID 从请求头解析，支持两种头名（见 backend/ai-service/app/dependencies/init.py）：

• 优先读取X-User-Id；
• 其次读取user_id；
• 两者都缺失时返回401 Missing X-User-Id or user_id header.。

4.2 积分检查与扣除

PointChecker（见 backend/ai-service/app/dependencies/points.py）在请求进入时：

1. 先尝试为用户发放月度积分（内部走 Redis，开销极小）；
2. 读取缓存积分，若低于本次消耗值（points < self.points_cost）返回403 Insufficient points.；
3. 返回PointsContext，在请求成功后由路由调用await points_context.deduct_points()完成扣费（chat.py 第 85 行）。

翻译能力归属于AICHAT_COST交易类型，单次扣费金额由AICHAT_POINTS_COST配置决定，默认值为100（见 backend/ai-service/app/config.py 第 19 行）。运维侧可通过环境变量调整，例如：

AICHAT_POINTS_COST=100

注意：该接口"先检查、成功后再扣费"，即调用失败（模型异常、模板缺失等）不会扣积分，只有正常返回时才产生消费记录。

五、在 RPA 工程命名场景中的实际应用

回到 astron-rpa 仓库本身，翻译模板的价值与工程命名强相关。从仓库目录结构可以观察到，engine/components 下的组件普遍采用astronverse-<模块名>的 snake_case 命名，例如astronverse-database、astronverse-browser、astronverse-encrypt、astronverse-email、astronverse-excel、astronverse-verifycode等。可以推断：当业务侧提供的是中文工程名（如"数据库组件""浏览器组件"）时，translate模板能把这些中文名规整为与上述命名风格一致的小写下划线标识符，供后续目录创建、包导入、配置文件引用使用。

典型接入方式有两种：

1. 单次调用：通过/v1/chat/prompt接口批量翻译若干工程名，人工确认后落盘；
2. 程序化嵌入：在自动化流程中，把待创建工程的中文名作为params.name动态注入，将返回结果直接用作目录/包名，实现"中文需求 → 规范标识符"的链路闭环。

由于模板强制要求"所有字母均为小写"且"单词间用下划线"，翻译结果天然满足 Python 包名、文件系统目录名、数据库表名等场景的常见约束，这也是该模板区别于普通中英翻译 Prompt 的核心设计点。

六、模板扩展指南：注册新的原子能力

translate模板是prompt_dict中"主要原子能力"的典型代表，了解它的接入方式即可按同样套路扩展新能力：

1. 新增模板文件：在 backend/ai-service/app/prompts 目录（或其子目录，如recruit/、smart/）下创建xxx_prompt.md，正文中使用$param形式声明占位符；
2. 注册类型：在 prompt.py 的prompt_dict中增加一行映射，如"my_new_ability": "my_new_ability_prompt.md"；
3. 更新 Schema 示例（可选）：在 schemas/chat.py 的paramsexamples 中补充新能力的参数示例，便于 Swagger 文档展示（默认文档地址http://localhost:8010/docs）；
4. 复用积分链路：新能力若同样走PointChecker，会沿用AICHAT_COST计费与AICHAT_POINTS_COST扣费，无需额外改动。

此外，format_prompt也被智能组件服务复用：在 app/routers/smart_component.py 中通过format_prompt(request.sceneCode, {})按场景码加载对应模板作为 system 消息。这进一步说明translate_prompt.md所处的 Prompt 体系是整个 AI Service 原子能力的通用底座，而非孤立的翻译功能。

七、使用前提与注意事项

• 运行环境：接口由 AI Service 提供，需先按 backend/ai-service/README.zh.md 配置AICHAT_BASE_URL、AICHAT_API_KEY、MySQL、Redis 等环境变量，并执行uv run python run.py dev启动（默认端口8010）。
• 依赖模型：默认模型为maas/deepseek-v3.2，不同模型对"只返回结果"指令的遵守程度可能有差异；若响应夹杂解释性文字，可考虑调低temperature（接口允许范围 0.0~2.0）以提升输出稳定性。
• 参数缺失行为：由于采用safe_substitute，若params未传name，模板中的$name会原样进入提示词，模型输出将不可控——调用方应在业务侧做好参数校验。
• 流式模式：stream: true时接口直接透传上游text/event-stream响应（见 services/chat.py），翻译结果需由调用方自行解析 SSE 数据，此时响应体不再是上述StandardResponse结构。
• 测试佐证：仓库的接口测试覆盖了非流式与流式两种调用路径（见 tests/routers/test_chat.py），可作为接入回归验证的参考。

结语

translate_prompt.md用最短的指令，把"中文工程名 → 英文 snake_case 标识符"这一高频命名需求封装为 AI Service 的原子能力：模板负责约束输出格式，prompt_dict+format_prompt负责模板注册与参数注入，/v1/chat/prompt接口负责对外服务并接入积分计费。理解这一整套链路，你就能在 astron-rpa 的 AI 服务体系中自如地复用、校验和扩展各类预设 Prompt，把大模型的输出稳定地工程化、产品化。

• 工作流自动化
• 低代码
• 桌面应用
• AI Agent
• 后端