senior-prompt-engineer

高级提示词工程师

基于评测驱动的提示词工程、RAG 质量度量以及 Agent 工作流验证。本文内容按设计与模型无关：各项技术按其作用来描述，而不是按其被观察到的模型代际来划分；工具本身不硬编码模型 ID 或定价。如需获取美元金额，请自行提供你所用服务商的当前费率。

操作规则

1. 没有基线，绝不修改提示词。 先采集指标（--analyze --output baseline.json），然后将每次迭代与该基线进行对比。
2. 先建评测集，再做优化。 至少需要 10–20 个带预期输出的代表性用例。如果用户没有评测集，请先与其共同构建，再动提示词。凭感觉做优化是头号失败模式。
3. 优先使用平台功能，而非提示词技巧。 如果服务商提供原生结构化输出 / JSON Schema 强制约束、工具调用 API 或提示词缓存，应优先使用这些功能，而不是依赖“只回复 JSON”之类的咒语式提示。提示词层面的格式约束只是后备方案，而非默认选择。
4. 当代模型所需的脚手架更少。 不要习惯性地添加思维链模板、角色设定或少样本示例——前沿模型在存在冗余脚手架时往往表现更差。只有当评测集表明某个要素确实有帮助时，才添加它。
5. 成本数字必须由用户提供。 请查询服务商当前的每百万 Token 定价，并通过 --price-per-mtok 传入（切勿信任缓存的价格表，包括你自己记忆中的价格）。

工具（精确的命令行，全部基于标准库）

1. 提示词优化器 — scripts/prompt_optimizer.py

静态分析：Token 估算、清晰度/结构评分（0–100）、歧义与冗余检测、少样本示例提取。

# Full analysis (human-readable report)
python3 scripts/prompt_optimizer.py prompt.txt --analyze

# Save machine-readable baseline for later comparison
python3 scripts/prompt_optimizer.py prompt.txt --analyze --json --output baseline.json

# Token estimate; cost only if you supply your provider's current rate
python3 scripts/prompt_optimizer.py prompt.txt --tokens --model claude --price-per-mtok 3.00

# Whitespace/redundancy-trimmed version
python3 scripts/prompt_optimizer.py prompt.txt --optimize --output optimized.txt

# Extract Input/Output few-shot pairs to JSON
python3 scripts/prompt_optimizer.py prompt.txt --extract-examples --output examples.json

# Compare a revision against the saved baseline
python3 scripts/prompt_optimizer.py optimized.txt --analyze --compare baseline.json

--model 接受任意字符串；仅推断分词器系列（名称中包含 "claude" 时为 3.5 字符/Token，否则为 4.0）。成功时退出码为 0，文件缺失时退出码为 1。

2. RAG 评估器 — scripts/rag_evaluator.py

基于两个 JSON 文件衡量检索与事实依据质量（格式见 --help 输出）。

python3 scripts/rag_evaluator.py --contexts retrieved.json --questions eval_set.json
python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --k 10 --json
python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --output report.json --verbose
python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --compare baseline_report.json

报告上下文相关性、precision@k、覆盖率、答案忠实度和事实依据性。将相关性低于 0.80 视为检索问题（分块 / 嵌入 / 过滤），而非提示词问题——在改写生成提示词之前先修复检索。

3. Agent 编排器 — scripts/agent_orchestrator.py

校验 Agent 配置（YAML/JSON）：工具连接、缺失的必需配置、循环风险、Token 估算。

python3 scripts/agent_orchestrator.py agent.yaml --validate
python3 scripts/agent_orchestrator.py agent.yaml --visualize --format mermaid
python3 scripts/agent_orchestrator.py agent.yaml --estimate-cost --runs 100 \
    --input-price-per-mtok 3.00 --output-price-per-mtok 15.00

若不提供两个价格参数，--estimate-cost 仅报告 Token 估算值。配置中的 model: 字段仅供参考，接受任意模型名称。

工作流

提示词优化（评估门控）

1. 基线： python3 scripts/prompt_optimizer.py current_prompt.txt --analyze --json --output baseline.json
2. 诊断：根据报告检查：模糊动词（"analyze"、"handle"）、冗余模块、缺失的输出约定、token 浪费。
3. 每次只应用一项修改，按以下杠杆效果从高到低的顺序进行：

   症状	修复方法
   输出格式错误/无法解析	若 API 支持，使用原生结构化输出 / JSON Schema；否则在提示词中明确写出 Schema
   多次运行结果不一致	收紧指令，并添加 2–3 个对比示例（其中一个近似错误样例，展示不应该怎么做）
   遗漏边界情况	显式列举边界情况，并添加"不确定时执行 X"的规则
   重复调用时 token 膨胀	将稳定前缀（系统规则、示例）前置，以便应用提示词缓存；精简冗余内容
   困难案例推理错误	要求在消费方忽略的草稿字段中进行分步推理，或使用模型提供方的扩展思考模式

4. 重新分析并对比： python3 scripts/prompt_optimizer.py revised.txt --analyze --compare baseline.json
5. 评估门控（发布前必须通过）： 在评估集上运行修订后的提示词，将每个用例的通过/失败结果写入 eval_results.json，然后进行断言：

   python3 scripts/prompt_optimizer.py revised.txt --analyze --json --output revised.json \
     && python3 -c "
   import json, sys
   r = json.load(open('revised.json')); b = json.load(open('baseline.json'))
   ok = r['clarity_score'] >= b['clarity_score'] and r['token_count'] <= b['token_count'] * 1.10
   sys.exit(0 if ok else 1)"
   echo "gate exit=$?"   # 0 = ship; 1 = regression, iterate again
   

   将此结构性门控与任务级评估配合使用：修订版本不得丢失任何先前通过的评估用例（无回归规则）。

Few-Shot 示例设计

1. 首先定义任务约定（输入结构、输出结构、边界情况策略）。
2. 从零示例开始并进行测量，当前的模型通常不需要示例。仅针对评估中暴露出的失败集群添加示例。
3. 添加时：最多 3–5 个，按由简单到边界再到反例（即不应提取的内容）排序，格式与真实输出约定完全一致。
4. 验证一致性：python3 scripts/prompt_optimizer.py prompt_with_examples.txt --extract-examples --output examples.json，并检查每个提取的示例对是否都能按照你的 Schema 解析。
5. 重新运行评估集；如果某个用例仅因与某个示例相似而通过，则向评估集中添加一个留出的变体。

结构化输出设计

1. 先编写 JSON Schema（类型、枚举、必填项、maxLength）。
2. 优先使用 API 原生约束：结构化输出 / response-schema / 工具调用参数可以保证输出结构，提示词文本则无法保证。
3. 回退方案（API 不支持 Schema）：将 Schema 按字段逐条规则写入提示词，并附上一个有效示例，同时指示"仅输出 JSON 对象"。
4. 门控：将 10 个评估输出通过 Schema 校验器处理（至少使用 python3 -c "import json,sys; [json.loads(l) for l in sys.stdin]"）；必须 10/10 可以解析，否则返回第 2 步。

RAG 调优循环

1. 构建 questions.json（包含 id、问题、参考答案），并将当前的检索结果保存到 contexts.json。
2. python3 scripts/rag_evaluator.py --contexts contexts.json --questions questions.json --output rag_baseline.json
3. 优先修复最低的指标：相关性 → 分块 / 嵌入 / 元数据过滤；忠实性 → 增加依据性指令、"仅根据上下文作答"以及引用要求；覆盖度 → 检索 k 值 / 查询扩展。
4. 门控：python3 scripts/rag_evaluator.py --contexts new_contexts.json --questions questions.json --compare rag_baseline.json，每个指标都必须 ≥ 基线；任何回退都会阻止此次修改。

Agent 配置审查

1. python3 scripts/agent_orchestrator.py agent.yaml --validate：必须以 VALIDATION PASSED 退出；修复所有错误和警告（缺失的工具配置、无界迭代、循环风险）。
2. 检查上下文控制：每个工具描述不超过 1–2 句话，工具数量以完成任务所需的最少为准，稳定的系统提示词放在最前面（利于缓存），并设置迭代上限和提前退出条件。
3. 预算：使用当前价格运行 --estimate-cost --runs N；如果每次运行成本超出预算，先减少工具或上下文，再考虑降级模型。

参考资料

文件	内容	用户询问以下内容时加载
references/prompt_engineering_patterns.md	10 种提示词模式，附输入/输出示例	"用哪种模式？"、少样本设计、任务分解、元提示
references/llm_evaluation_frameworks.md	评估指标、评分方法、A/B 测试	"如何评估？"、"衡量质量"、"比较提示词"
references/agentic_system_design.md	Agent 架构（ReAct、Plan-Execute、工具调用）	"构建 Agent"、"工具调用"、"多 Agent"

相关技能

• engineering-team/skills/senior-ml-engineer — 模型部署与服务（本技能止步于提示词与评估层）
• engineering/rag-architect — RAG 系统架构（本技能衡量 RAG 质量；该技能负责设计流水线）
• engineering/agent-designer — 完整的 Agent 系统设计（本技能校验配置；该技能负责设计架构）