Prompt 智能

Prompt 智能提供 Prompt 版本管理 和 A/B 实验 功能。追踪 prompt 变更历史，对比不同版本的效果，自动激活表现最好的 prompt。

快速开始

1. 启用功能

在 ~/.librefang/config.toml 中添加：

[prompt_intelligence]
enabled = true

2. 创建 Prompt 版本

打开 Dashboard → Agents → 选择 agent → Prompts 按钮 → Versions 标签 → New Version。

输入 system prompt 和可选的描述。服务端自动生成 ID 和内容哈希。

3. 运行 A/B 实验

切换到 Experiments 标签 → New Experiment → 选择 2 个或更多 prompt 版本 → Create。

点击 Start 开始将流量路由到不同的变体。

4. 查看结果

点击运行中实验的 Metrics 按钮，查看各变体的成功率、延迟和成本。满意后点 Complete — 获胜变体的 prompt 会自动激活。

Prompt 版本管理

自动追踪

启用后，LibreFang 在每次请求开始时计算 agent system prompt 的哈希值。如果 prompt 内容与上次记录的版本不同，自动创建新版本并标记为 active。

这意味着任何对 agent system_prompt 的修改（无论是通过 manifest 还是 API）都会被自动捕获。

手动创建版本

通过 Dashboard 或 API 手动创建版本，用于准备 A/B 实验的变体。每个版本包含：

System prompt — 完整的 prompt 文本
Content hash — 服务端计算，用于去重
Version number — 每个 agent 自动递增
Description — 可选的描述
Active flag — 每个 agent 同时只有一个活跃版本

版本清理

当新版本创建后，如果总数超过 max_versions_per_agent（默认 50），最旧的非活跃版本会被自动删除。活跃版本永远不会被清理。

激活版本

在 Dashboard 中点击任意版本的 Activate 按钮，或调用 API：

curl -X POST http://localhost:4545/api/prompts/versions/{version_id}/activate \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id"}'

Agent 会在下一次请求时使用该版本的 system prompt。

A/B 实验

核心概念

一个实验在单个 agent 上对比两个或多个 prompt 变体。每个变体关联一个 prompt 版本。实验运行期间，请求会根据配置的流量比例路由到不同变体。

术语	说明
变体 (Variant)	实验中的一个条目，关联到特定的 prompt 版本
流量分配 (Traffic split)	每个变体接收的流量百分比（如 `[70, 30]` 表示 70/30）
成功标准 (Success criteria)	判断请求是否成功的规则

实验生命周期

Draft → Running → Paused → Running → Completed
              ↘                    ↗
               →→→ Completed →→→→→→

状态	行为
Draft	实验已配置但未激活，不路由流量
Running	请求在变体间分配，记录指标
Paused	暂停流量路由，保留指标数据
Completed	实验结束，成功率最高的变体自动激活

流量分配

流量通过加权选择分配。traffic_split 数组定义每个变体的百分比。例如两个变体配置 [70, 30]：

70% 的 session 路由到变体 A（对照组）
30% 的 session 路由到变体 B

路由是 session 一致的 — 同一个 session 始终命中同一个变体，通过 session ID 哈希保证。

成功判定

一个请求被判定为成功需要满足：

Agent 产生了非空响应
Agent 至少完成了一次迭代（执行了循环）

指标采集

Streaming 和非 streaming 请求路径都会记录每个变体的指标：

指标	说明
总请求数	路由到该变体的请求数量
成功 / 失败	按成功标准分类
成功率	成功请求的百分比
平均延迟	平均响应时间（毫秒）
平均成本	每次请求的平均成本（USD）
总成本	所有请求的累计成本

自动激活获胜者

实验标记为 Completed 时，系统自动：

对比所有变体的成功率
选择成功率最高的变体
激活其关联的 prompt 版本

无需手动操作。

Dashboard

Prompts 按钮

Agents 页面的每个 agent 卡片都有 Prompts 按钮，打开 Prompt 智能弹窗，包含两个标签：

Versions 标签：

列出所有 prompt 版本，显示版本号、活跃标识、描述和创建日期
创建新版本（输入 system prompt 和描述）
一键激活任意版本
删除非活跃版本

Experiments 标签：

列出所有实验，显示状态标识和变体数量
创建实验（选择 2+ 个 prompt 版本作为变体）
启动 / 暂停 / 完成实验
查看详细指标（成功率标识、延迟、成本）

Analytics 页面

Analytics 页面包含 模型性能 区域：

KPI 卡片：平均延迟、最快模型、最低单次成本、总调用次数
延迟对比图表（按模型展示 avg/min/max）
单次成本对比图表
性能详情表格

API 参考

Prompt 版本

端点	方法	说明
`/api/agents/{agent_id}/prompts/versions`	GET	列出 agent 的所有 prompt 版本
`/api/agents/{agent_id}/prompts/versions`	POST	创建新 prompt 版本
`/api/prompts/versions/{id}`	GET	获取指定版本
`/api/prompts/versions/{id}`	DELETE	删除版本
`/api/prompts/versions/{id}/activate`	POST	激活版本（body: `{"agent_id": "..."}`)

创建版本

curl -X POST http://localhost:4545/api/agents/{agent_id}/prompts/versions \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "你是一个高质量的编程助手。",
    "description": "注重代码质量",
    "version": 1,
    "tools": [],
    "variables": [],
    "created_by": "dashboard"
  }'

服务端自动生成 id、created_at 和 content_hash。

实验

端点	方法	说明
`/api/agents/{agent_id}/prompts/experiments`	GET	列出 agent 的实验
`/api/agents/{agent_id}/prompts/experiments`	POST	创建实验
`/api/prompts/experiments/{id}`	GET	获取实验详情
`/api/prompts/experiments/{id}/start`	POST	启动实验
`/api/prompts/experiments/{id}/pause`	POST	暂停实验
`/api/prompts/experiments/{id}/complete`	POST	完成实验（自动激活获胜者）
`/api/prompts/experiments/{id}/metrics`	GET	获取各变体指标

创建实验

curl -X POST http://localhost:4545/api/agents/{agent_id}/prompts/experiments \
  -H "Content-Type: application/json" \
  -d '{
    "name": "语气对比",
    "status": "draft",
    "traffic_split": [50, 50],
    "success_criteria": {
      "require_user_helpful": true,
      "require_no_tool_errors": true,
      "require_non_empty": true
    },
    "variants": [
      {
        "name": "Control",
        "prompt_version_id": "version-uuid-1",
        "description": "当前 prompt"
      },
      {
        "name": "Variant B",
        "prompt_version_id": "version-uuid-2",
        "description": "更简洁"
      }
    ]
  }'

获取指标

curl http://localhost:4545/api/prompts/experiments/{id}/metrics

响应示例：

[
  {
    "variant_id": "...",
    "variant_name": "Control",
    "total_requests": 142,
    "successful_requests": 128,
    "failed_requests": 14,
    "success_rate": 90.1,
    "avg_latency_ms": 1250.5,
    "avg_cost_usd": 0.0023,
    "total_cost_usd": 0.3266
  },
  {
    "variant_id": "...",
    "variant_name": "Variant B",
    "total_requests": 58,
    "successful_requests": 55,
    "failed_requests": 3,
    "success_rate": 94.8,
    "avg_latency_ms": 980.2,
    "avg_cost_usd": 0.0019,
    "total_cost_usd": 0.1102
  }
]

模型性能

端点	方法	说明
`/api/usage/by-model/performance`	GET	模型性能指标（含延迟统计）

配置参考

[prompt_intelligence]
enabled = false              # 总开关（默认关闭）
hash_prompts = true          # 计算内容哈希用于去重（默认开启）
max_versions_per_agent = 50  # 超出后自动清理旧版本（默认 50）

完整配置参考见配置文档。

数据库

Prompt 智能使用 SQLite（与 LibreFang 其他功能共用）。Migration v13 创建四张表：

表名	用途
`prompt_versions`	存储每个 agent 的 prompt 版本历史
`prompt_experiments`	实验定义和状态
`experiment_variants`	实验中的变体，关联到 prompt 版本
`experiment_metrics`	每个变体的聚合指标（请求数、延迟、成本）

Migration v14 在 usage_events 表中添加 latency_ms 列，用于模型性能追踪。

迁移在启动时自动执行，无需手动操作。