AI 提示词质量审计引擎·专业版

输入 / 输出

• 输入：任意中文或英文提示词文本。
• 输出：total（0-100）、grade（优秀/良好/及格/待优化/空提示词）、
  scores（clarity/constraints/examples/format 各 0-25）、
  issues（问题清单）、suggestions（逐条改写建议）、length。

评级阈值

• ≥85 优秀；70-84 良好；55-69 及格；<55 待优化；空输入为"空提示词"。

使用示例

from prompt_audit import audit_prompt
r = audit_prompt("你是一名文案，请帮我写一条短视频口播脚本，要求吸引人。")
print(r["total"], r["grade"], r["issues"])

引擎代码：prompt_audit.py

# -*- coding: utf-8 -*-
"""
AI 提示词质量审计引擎（专业版）
四维度评分（每维 0-25，总分 100）：
  clarity     明确性：角色/任务动作/具体对象场景
  constraints 约束：边界/限制/禁止/长度/数量/范围
  examples    示例：输入输出样例 / few-shot
  format      输出格式：JSON/表格/Markdown/列表/字数/结构
评级：>=85 优秀；70-84 良好；55-69 及格；<55 待优化
"""
from __future__ import annotations

# 每个维度：(关键词/正则信号, 命中档位)
ROLE = ["你是", "你扮演", "作为", "你的角色", "你的身份", "你是一位", "你是一名",
        "act as", "you are", "role", "扮演", "假设你是", "请你充当"]
ACTION = ["写", "生成", "撰写", "分析", "总结", "翻译", "提取", "计算", "检查", "改写",
          "优化", "润色", "分类", "打分", "评估", "制作", "设计", "整理", "判断", "对比",
          "write", "generate", "analyze", "summarize", "translate", "extract", "create"]
SCENE = ["场景", "情况", "背景", "面向", "针对", "用于", "行业", "客户", "用户", "目标",
         "scenario", "context", "audience", "background", "用途"]

CONSTRAINT = ["不要", "禁止", "不得", "不能", "必须", "仅限", "限制", "约束", "不超过",
              "不低于", "字数", "长度", "范围", "边界", "条件", "前提", "避免", "严禁",
              "within", "must", "do not", "don't", "limit", "max", "minimum", "avoid"]

EXAMPLE = ["例如", "例子", "示例", "样例", "举例", "输入", "输出", "模板", "范例",
           "for example", "e.g.", "such as", "sample", "few-shot", "instance", "如下"]

FORMAT = ["JSON", "json", "表格", "Markdown", "markdown", "列表", "格式", "分点", "条目",
          "分段", "标题", "Excel", "csv", "CSV", "缩进", "分条", "结构化", "字段",
          "table", "bullet", "分点列出", "输出为", "以.形式", "列出来"]


def _count(text, words):
    return sum(1 for w in words if w.lower() in text.lower())


def _dim_score(hit_count):
    # 命中 0 个 ->0；1 个 ->15；2 个及以上 ->25
    if hit_count <= 0:
        return 0
    if hit_count == 1:
        return 15
    return 25


def audit_prompt(text):
    """审计提示词，返回评分、等级、问题与建议。"""
    if text is None or not str(text).strip():
        return {
            "total": 0, "grade": "空提示词",
            "scores": {"clarity": 0, "constraints": 0, "examples": 0, "format": 0},
            "issues": ["提示词为空，无法审计。"],
            "suggestions": ["请先写出明确的任务目标、角色与输出要求。"],
            "length": 0,
        }

    t = str(text)
    low = t.lower()
    length = len(t.strip())

    # 明确性：角色/动作/场景三类信号各计分
    role_hits = _count(t, ROLE)
    action_hits = _count(t, ACTION)
    scene_hits = _count(t, SCENE)
    clarity = 0
    clarity += 20 if role_hits > 0 else 0
    clarity += 3 if action_hits > 0 else 0
    clarity += 2 if scene_hits > 0 else 0
    # 有动作但无角色，明确性仍给部分
    if role_hits == 0 and action_hits > 0:
        clarity = max(clarity, 10)
    clarity = min(25, clarity)

    constraints = _dim_score(_count(t, CONSTRAINT))
    examples = _dim_score(_count(t, EXAMPLE))
    format_score = _dim_score(_count(t, FORMAT))

    scores = {"clarity": clarity, "constraints": constraints,
              "examples": examples, "format": format_score}
    total = sum(scores.values())

    if total >= 85:
        grade = "优秀"
    elif total >= 70:
        grade = "良好"
    elif total >= 55:
        grade = "及格"
    else:
        grade = "待优化"

    issues, suggestions = [], []
    if role_hits == 0:
        issues.append("缺少角色设定（没有告诉 AI 扮演什么身份/专家）。")
        suggestions.append("开头加角色，例如：你是一名资深外贸业务员。")
    if action_hits == 0:
        issues.append("缺少明确的任务动作，AI 不知道要做什么。")
        suggestions.append("用明确动词开头，如：生成、分析、分类、改写。")
    if constraints == 0:
        issues.append("缺少约束条件（边界、长度、禁止项）。")
        suggestions.append("补充限制，如：不超过300字、不要编造数据、仅用中文。")
    if examples == 0:
        issues.append("没有输入输出示例，复杂任务易跑偏。")
        suggestions.append("给 1-3 个示例，展示期望的输入与输出样式。")
    if format_score == 0:
        issues.append("没有指定输出格式。")
        suggestions.append("明确格式，如：以 JSON 输出、表格呈现、分 3 条列出。")
    if length < 15:
        issues.append("提示词过短，难以承载完整需求。")
        suggestions.append("补充角色、任务、约束与格式四要素。")

    if not issues:
        suggestions.append("四要素齐全，可直接用于生产；复杂任务建议再加 1-2 个反例。")

    return {
        "total": total,
        "grade": grade,
        "scores": scores,
        "issues": issues,
        "suggestions": suggestions,
        "length": length,
    }

边界处理（已覆盖）

• 空字符串、None、纯空白：返回 0 分与"空提示词"，不抛异常；
• 中英文提示词均可识别（内置中英信号词）；
• 总分恒等于四维之和且上限 100；
• 四要素齐全时问题清单为空，给出"可直接用于生产"的建议。

断言测试结果

• 四要素齐全提示词：100 分、优秀、无问题；
• 缺示例缺格式的提示词、极简提示词：评级与缺失项正确；
• 有动作无角色的提示词：明确性按动作给分、约束/格式判定正确；
• 英文提示词可识别；空输入边界正确。
• 共 14 项断言全部通过。

接入建议

• 作为提示词质量门禁接在 Dify/扣子/自建平台调用大模型之前，低于阈值先提示补全；
• 对团队历史提示词批量跑一遍，按 issues 分布定位最常缺失的要素，做专项培训。