《【视角重塑】“提示工程即API设计”（三）：文档与代码，让你的Prompt成为团队的核心资产》

在系列的前两篇文章中，我们完成了一次认知上的飞跃：

1. 视角重塑： 我们不再是“炼丹师”，而是“API架构师”。
2. 理论构建： 我们定义了一个优秀“Prompt API”应具备的五大特性：清晰的契约、稳定的参数、可预测的输出、版本控制和错误处理。

理论的灯塔已经照亮了前路，但我们脚下仍是泥泞。一个躺在你本地v2.prompt文件里的“完美Prompt”，如果不能被团队其他成员轻松理解、复用和迭代，那它离真正的工程化资产还相去甚远。

今天，我们将走完这“最后一公里”，将理论彻底落地。我们将探讨把Prompt转化为团队核心资产的两个关键实践：文档化 (Documentation) 和 代码化 (Implementation)。

---

一、接口文档：让你的Prompt不再是“黑话”

一个无法被团队共享和复用的Prompt是无价值的。为你的核心Prompt编写一份像后端API一样清晰的“使用文档”至关重要。这份文档是团队协作的基石，也是避免重复“造轮子”的唯一解药。

别怕麻烦，一份好的文档模板能帮你节省未来百倍的沟通成本。

Markdown模板 (prompt_doc_template.md):
你可以直接复制这个模板，为你的下一个核心Prompt创建文档。

# Prompt API: code_refactor_assistant_v1.1

## 1. 目的与功能 (Purpose)
本Prompt旨在将输入的非结构化、效率低下的代码片段，重构为遵循特定设计模式（如工厂模式、策略模式）的、更清晰、更可维护的代码。

## 2. 模型兼容性 (Model Compatibility)
- 主要优化针对: GPT-4o, Claude 3 Opus
- 兼容: Gemini 1.5 Pro
- **注意**: 在低版本模型（如GPT-3.5）上可能无法严格遵循输出格式。

## 3. 输入参数 (Input Parameters)
| 参数名 | 类型 | 描述 | 是否必须 |
|---|---|---|---|
| `{{source_code}}` | String | 需要被重构的原始代码片段。 | 是 |
| `{{language}}` | String | 原始代码的编程语言 (e.g., 'Python', 'Java')。 | 是 |
| `{{target_pattern}}` | String | 希望应用的设计模式 (e.g., 'Strategy', 'Singleton')。 | 是 |

## 4. 输出模式 (Output Schema)
输出为一个严格的Markdown格式，包含三个H3标题部分：
1.  **`### 重构分析`**: 对原始代码问题的简要分析。
2.  **`### 重构后代码`**: 一个包含重构后代码的代码块。
3.  **`### 设计模式解释`**: 简要解释为什么该设计模式适用。

## 5. 错误处理 (Error States)
- 如果 `{{source_code}}` 无法被解析或包含语法错误，输出将是: `**错误：** 输入的代码存在语法问题，无法进行重构。`
- 如果 `{{target_pattern}}` 是一个无法识别的设计模式，输出将是: `**错误：** 无法识别的设计模式 '{{target_pattern}}'。`

## 6. 使用范例 (Usage Example)
**输入:**
- `{{source_code}}`: `public class Calculator { public int execute(String op, int a, int b) { if(op.equals("add")) return a+b; if(op.equals("subtract")) return a-b; ... } }`
- `{{language}}`: `Java`
- `{{target_pattern}}`: `Strategy Pattern`

**预期输出:**
... (此处省略详细的预期输出Markdown) ...

## 7. 版本历史 (Version History)
- **v1.1 (2024-07-22):** 增强了对Python代码中类型提示的处理。
- **v1.0 (2024-07-15):** 初始版本。

这份文档，就是你作为“API架构师”的交付物。它清晰、严谨，任何人拿到手都能立刻明白如何使用这个Prompt。

二、案例对比：天堂与地狱

让我们通过一个真实的任务，看看“炼丹”与“工程”的天壤之别。

• 任务： 从一篇产品发布新闻稿中，提取核心功能、目标用户和发布日期，用于自动填充到内部数据库。

• “炼丹式”工作流:

  1. 张三写了个Prompt：总结一下这个：[粘贴新闻稿全文]
  2. 结果不理想，他又试了：提取关键信息，比如功能、给谁用的、什么时候发布的。从这里：[新闻稿]
  3. 结果时好时坏，有时漏掉日期，有时格式是散文。
  4. 他把这个“感觉还行”的Prompt发给了李四。
  5. 李四用的时候发现对另一篇新闻稿效果很差，又开始了自己的“炼丹”之旅…
  • 结果： 团队里充斥着十几个不同版本的、效果不一的“总结大师”Prompt，没人知道哪个是最好的，也没人能把它稳定地集成到自动化流程里。

• “API设计式”工作流:

  1. 王五作为架构师，首先定义了需求：我们需要一个能稳定返回JSON的提取器。
  2. 他设计了一个Prompt模板，并编写了对应的API文档（就像上面那样）。
  3. 他设计的Prompt如下：

     # prompt_api: extract_news_info_v1.0
     # description: 从新闻稿中提取结构化的产品信息
     
     你是一个信息提取引擎。你的任务是从以下新闻稿中提取结构化信息。
     
     **新闻稿原文:**
     """
     {{news_article_text}}
     """
     
     **指令:**
     严格按照以下JSON格式输出，不要添加任何额外的解释或文本。如果信息在文中不存在，请使用 "Not Found" 作为对应字段的值。
     
     **输出JSON Schema:**
     {
       "product_name": "string",
       "core_features": [
         "string" // 一个包含3-5个核心功能的字符串数组
       ],
       "target_audience": "string", // 描述目标用户的字符串
       "release_date": "string" // 格式为 YYYY-MM-DD
     }
     

  4. 他将这个带注释的Prompt文件 (extract_news_info_v1.0.prompt) 和文档，一同提交到团队的Git仓库。
  • 结果： 任何需要这个功能的开发者，都能在仓库里找到这个Prompt，阅读文档，然后通过代码调用它。它的行为是可预测的，输出是稳定的，可以直接被后续程序解析使用。

三、Z轴实现：用代码管理你的Prompt API

文档和设计最终要通过代码才能发挥价值。这便是工程化的最后一环：将我们的Prompt模板和业务逻辑优雅地结合起来。

使用Python和Jinja2这样的模板引擎，是实现这一目标的最佳实践。

import jinja2
import json
# from openai import OpenAI # 假设使用OpenAI

# 1. 将Prompt模板从文件中加载
# 这是推荐的做法，让prompt和代码分离
with open('prompts/extract_news_info_v1.0.prompt', 'r') as f:
    prompt_template_str = f.read()

# 2. 准备数据和渲染模板
news_text = """
【2024年7月22日，北京】辉光科技今日发布了其革命性产品“星尘IDE”，
这款专为AI开发者设计的集成开发环境，核心功能包括“智能代码补全”、“实时Prompt调试”和“一键模型部署”。
其主要面向追求极致效率的AI工程师和数据科学家...
"""

environment = jinja2.Environment()
template = environment.from_string(prompt_template_str)
final_prompt = template.render(news_article_text=news_text)

print("--- 最终生成的Prompt ---")
print(final_prompt)
print("------------------------")

# 3. 标准化地调用LLM API
# client = OpenAI(api_key="...")
# response = client.chat.completions.create(
#     model="gpt-4o",
#     messages=[{"role": "user", "content": final_prompt}],
#     response_format={"type": "json_object"} # 强制JSON输出，双重保险
# )

# # 4. 安全地解析可预测的输出
# try:
#     extracted_data = json.loads(response.choices[0].message.content)
#     print(extracted_data)
#     # 此处可以将 extracted_data 存入数据库或用于其他业务逻辑
# except json.JSONDecodeError as e:
#     print(f"Error: LLM did not return a valid JSON. {e}")

看到这段代码，你是否感到一种熟悉的、属于软件工程师的舒适感？

• 关注点分离： Prompt模板（视图V）与调用逻辑（控制器C）完全分离。
• 可维护性： 修改Prompt无需改动Python代码，只需更新.prompt文件和文档。
• 可扩展性： 添加一个新的Prompt，就是增加一个模板文件和相应的调用函数。

这，才是可维护、可扩展的现代化AI应用开发。

---

结语：你是架构师，不是炼丹师

我们用三篇文章，完成了一次从思维到实践的彻底变革。

我们告别了那个靠运气、凭感觉的“炼丹”时代，拥抱了一套源于经典软件工程思想的、结构化的方法论。

从今天起，当你面对LLM时，请记住你的新身份：你不是在和它聊天，你是在设计一个API。

你会为它定义契约，设计参数，规划输出；你会为它编写文档，进行版本控制，并用优雅的代码将它纳入你的系统。

这不仅仅是一种技术上的升级，更是一种专业精神的体现。因为工程的本质，就是用系统化的方法，去对抗世界的不确定性。

现在，去打开你的项目，找到那个最让你头疼的Prompt，开始为它编写第一份API文档吧。你的“AI架构师”之路，就此启程。

如果你觉得这个系列对你有启发，别忘了点赞、收藏、关注，我们下篇见！