redline

redline

在提示词发布前捕捉回归问题。

利用现有提示词日志自动生成评测套件。

redline 将真实的提示词-响应日志转化为本地回归测试。它会挑选具有代表性的案例， 重放修改后的提示词，并在有问题的提示词触达用户之前展示行为差异。

网站 · 文档 · MCP · MCP 注册表 · 安全 · 许可证

从这里开始

从 PyPI 安装：

python -m pip install redline-ai

加载公开示例证明并运行本地引导式应用：

redline app --demo

这会生成公开演示报告，打开本地产品应用，并展示完整的导入 -> 套件 -> 评测 -> 审核工作流。该演示无需 API 密钥、私有日志、云账户或大模型评审器，即可捕捉十个合成回归问题。

想先在终端查看输出：

redline demo --public --compact

演示会在 .redline/demo 下生成 JSON、Markdown 和独立 HTML 报告。

询问 redline 接下来该做什么：

redline status --reports-dir .redline/demo/reports

status 会读取本地配置、套件、报告、历史记录和审计证据，然后打印下一条命令，而不是让你自行推断工作流。

在现有报告上打开本地引导式产品应用：

redline app --reports-dir .redline/demo/reports

该应用采用本地复制命令工作流：导入日志、生成套件、运行评测、审核回归问题、记录历史，并导出 CI/MCP 设置，浏览器不会执行 shell 命令。

在无头 CI 或远程 shell 环境中，可跳过打开浏览器，使用打印出的 HTML 路径：

redline app --reports-dir .redline/demo/reports --no-open --out .redline/app.html

首次运行故障排查

• redline: command not found：运行 python -m pip install redline-ai，然后确认 python -m pip show redline-ai。
• 应用未打开：使用 --no-open --out .redline/app.html，然后在你的环境中打开或上传该文件。
• 未找到套件：运行 redline suite logs/baseline.jsonl --out redline-suite.json。
• 验证失败：运行 redline validate redline-suite.json --strict，并修复报告中的第一个错误。
• GitHub Action 找不到套件：提交 redline-suite.json，或将 action 的 suite 输入指向你的提示词清单。

完整指南：docs/troubleshooting.md。

产品验证

redline 提供两种验证路径：快速的首次运行演示，以及规模更大的公开数据 dogfood 运行。

验证	命令或数据	结果
首次运行演示	redline demo --public --compact	在本地捕获 10 个合成回归问题，无需 API 密钥。
互联网 dogfood	从 Databricks Dolly 15k 中抽取的 100 条提示词-响应数据	发现 51 个回归问题，27 个变化用例，22 个中性对照，且没有仪表板警告。
发布门禁	测试、lint、类型检查、action 冒烟测试和发布构建	发布前验证软件包、CI、报告、仪表板和 MCP 路径。

这些截图是 100 条数据的互联网 dogfood 运行生成的本地文件。

仪表板	HTML 报告

什么是 redline？

redline 是一款面向 AI 团队的开源、本地优先评测工具。它使用你已有的日志：提示词、输出、支持工单、跟踪记录、模型响应和生产环境 JSONL 导出文件。

redline 不会让你先手动编写评测，而是根据真实行为生成第一套用例。之后，每当提示词、模型或运行器发生变化时，你都可以运行这套用例。

无需云账户，无需手动编写测试，也无需用大模型裁判来获取核心回归信号。该软件包没有运行时依赖，因此安装速度快，默认的供应链攻击面也更小。

工作原理

redline 提供三个原语，覆盖提示词回归工作流：

首次检查两个本地日志时，只需运行一条命令：

redline quick-check logs/baseline.jsonl logs/candidate.jsonl --open

它会生成临时用例集，在 .redline/quick-check 下写入 JSON/Markdown/HTML 报告和引导式本地应用，打开精简的 HTML 报告，并输出具体的行为差异。如果你想打开引导式审查工作流，而不只是查看精简报告，请使用 --open-app。

1. 日志

从已有的提示词-响应数据开始。导入 JSONL，将 Langfuse 或 Helicone 等工具的导出文件转换为所需格式，捕获 OpenAI/Anthropic SDK 调用，或添加有边界限制的 FastAPI/ASGI 中间件。

redline import downloaded.jsonl --detect
redline import downloaded.jsonl --auto-map --preview 3
redline import downloaded.jsonl --auto-map --out logs/baseline.jsonl
redline import downloaded.jsonl --input-field instruction --output-field response --preview 3
redline import downloaded.jsonl --input-field instruction --output-field response --out logs/baseline.jsonl
redline import langfuse-export.jsonl --preset langfuse --out logs/baseline.jsonl
redline suite logs/baseline.jsonl --out redline-suite.json
redline cases redline-suite.json

如果不知道字段名称，请使用 --detect。如果你不熟悉该导出文件，请使用 --preview；它会显示映射并脱敏后的样例行，但不会写入基线文件。

用例集生成过程会输出就绪度评分和改进建议。该评分衡量的是用例集的健康状况，而不是模型质量或候选版本的安全性。

2. 用例集

redline 会将行为归入确定性签名，并优先选择有代表性的用例。如果某个场景绝不能遗漏，你可以添加固定边界用例和明确要求。

redline cases redline-suite.json
redline suite add redline-suite.json --prompt "..." --response "..."

3. 评测

重放发生变化的提示词，或比较候选输出。redline 会指出出现问题的行为：缺少 JSON 键、URL、数字、表格、代码块、拒绝回答、空答案，或未满足要求。

redline eval --prompt prompts/v2.txt
redline diff redline-suite.json logs/candidate.jsonl

产品承诺

使用真实提示词日志，redline 应能在五分钟内捕获一个你不想发布的回归问题。

这项承诺的范围有意保持狭窄。redline 不是托管评测平台，不是通用评分工具，也不能取代人工判断。它是在“我改了提示词”和“这已经足够安全，可以合并”之间提供的本地安全闭环。

实际工作流

根据基线日志构建用例集：

redline suite logs/baseline.jsonl --out redline-suite.json

通过配置的运行器评测更改后的提示词文件：

redline eval --prompt prompts/v2.txt

或者比较你已经生成的候选输出：

redline diff redline-suite.json logs/candidate.jsonl

当 redline 发现阻断性变化时，它会为 CI 返回非零退出码，并打印原因：

REGRESSION case_004
- candidate missing JSON keys: owner, required_action
- candidate missing URL: https://example.com/policies/refunds

Confidence: HIGH | fix blocking cases before shipping

redline 能捕捉的问题

信号	回归示例
JSON 有效性和键	候选结果不再返回有效 JSON，或丢失 owner。
表格、列表和代码块	Markdown 表格变成普通文本；代码围栏消失。
数字、URL 和实体	退款期限、工单 ID、政策 URL 或负责人缺失。
空输出和拒绝	候选结果开始拒绝安全任务，或不返回任何内容。
内容偏移	结构相同的响应发生重大变化。
明确要求	固定用例要求或禁止使用特定字符串。

redline 默认采用确定性、本地优先的方式。对于含糊的 changed 用例，也可使用可选的评审命令；但除非你明确配置该命令，否则 redline 不会调用云端模型。

这正是它的设计目标。redline 旨在成为快速的合并拦截关卡，捕捉会破坏生产系统的回归：无效 JSON、缺少必需字段、表格丢失、答案为空、URL 丢失、拒绝行为改变，以及未满足明确要求。LLM 评审器适用于语义审查，但速度较慢、需要付费，而且在 CI 中可能不稳定。redline 让默认关卡保持确定、可复现且成本低廉；只有在结构信号不足时，才由你添加评审器。

方法详情见 docs/methodology.md。

默认情况下，套件生成不会运行统计聚类或嵌入聚类。它会根据确定性的行为特征对日志分组，例如提示词意图、响应结构、长度区间和 JSON 架构。它会先为每组选择一个代表样本，然后在用例预算允许时，添加高方差边缘样本，以及从大型组中均匀挑选、提示词各异的样本。

信任边界

redline 运行结果为绿色，表示未发现已配置的高信号结构性阻断项。这并不能证明事实准确性、语气、抗幻觉安全性、政策合规性或细微的推理质量。

由于过度信任评估工具存在危险，CLI 输出和报告会明确展示这一边界。每个报告的用例都包含一个置信度和一个信号（structural、shallow_semantic、requirement、judge 或 human_judgment），让审阅者了解 redline 作出判断的依据。对于结构检查无法证明的语义风险，请使用要求或可选的评审器。

产品功能

redline 围绕完整的提示词回归流程构建：

• redline watch：从日志、Python 函数、兼容 OpenAI/Anthropic 的 SDK 调用或 ASGI 应用中收集提示词-响应观察记录，默认在写入前尽可能对常见密钥和 PII 进行脱敏。
• redline import：将导出的团队日志规范化为 redline JSONL，默认启用相同的尽力而为脱敏。仅对已审核且只在本地使用的日志使用 --no-redact。
• RedlineMiddleware：在本地捕获有大小限制的 JSON FastAPI 或 ASGI 请求/响应对，并可选择启用跳过诊断。
• redline redact --check：扫描日志中的常见密钥和 PII，并在需要时写入清理后的副本。 脱敏依赖尽力而为的模式匹配，并非隐私保障；分享敏感日志前请先审核。
• redline cluster：在生成测试套件前检查确定性的行为特征分组。
• redline suite：根据基线日志生成具有代表性的评估套件。
• redline prompts：扫描多个提示词文件，并写入或检查可版本控制的提示词到测试套件清单。 如果 CI 中的每个提示词都应已有构建完成且有效的测试套件，请添加 --check-suites。
• redline suite add：固定手选的边缘案例，确保算法绝不会漏掉它们。
• redline budget / redline benchmark：估算测试套件或提示词清单的运行时间，不执行回放命令；写入预算产物，并可选择在超出 CI 时间预算时失败。添加 --measure-local 可对测试套件基线执行 redline 的确定性本地差异计算计时，而不调用模型。
• redline eval：通过本地应用或模型运行器回放每个测试套件案例。
• redline diff：将候选 JSONL 输出与测试套件基线进行比较。
• redline mark 和 redline accept：审核有意进行的更改并升级新基线。
• redline require：添加确定性的必须包含或禁止包含规则。
• redline audit --verify：检查本地审计记录并验证哈希链。 如果要证明本地日志尾部仍与 CI 或发布凭证中的检查点一致，请添加 --expect-last-hash 或 --expect-entries。添加 --out-checkpoint .redline/audit-checkpoint.json 可保存该凭证，之后使用 --checkpoint .redline/audit-checkpoint.json 对照验证。
• redline sbom：生成用于安全审核的 CycloneDX SBOM 发布凭证。
• redline app：打开引导式本地产品界面，用于导入日志、生成测试套件、审核回归、记录历史记录以及接入 CI/MCP。
• redline status：根据本地凭证显示项目就绪情况和下一条命令，其中包括引导式应用命令、第一个审核案例、其原因以及它的重要性。
• redline history、redline compare 和 redline dashboard：跟踪质量变化并在本地检查报告产物。仪表板会展示功能级汇总、提示词级评估行、基准凭证，以及报告来自提示词清单时的最新报告审核队列。如果同一项目中存在报告却没有基准凭证，仪表板也会发出警告。
• redline summary：检查测试套件就绪情况，或传入 redline-prompts.json，汇总多提示词的测试套件覆盖率、负责人、要求和缺失的测试套件。
• redline-mcp：让 AI 编码助手在 Claude、Codex、Cursor、Kiro 或任何 MCP 客户端中运行检查。

对于提示词文件较多的仓库，清单会成为评估计划：

redline prompts prompts/ --suite-dir suites --out redline-prompts.json
redline prompts prompts/ --suite-dir suites --out redline-prompts.json --check --check-suites
redline summary redline-prompts.json
redline validate redline-prompts.json --strict
redline budget redline-prompts.json
redline eval redline-prompts.json

清单摘要会显示所有映射测试套件的就绪情况；清单验证会检查每个映射的测试套件；清单基准测试会汇总运行时间预算；清单评估会在显示案例详情前输出提示词级汇总。大型仓库可以据此查看哪些提示词文件或功能文件夹需要优先处理。

映射的测试套件有效时，检查会打印如下就绪命令：

redline eval suites/support/triage.redline-suite.json --prompt prompts/support/triage.txt

连接你的应用

任何从标准输入读取提示词并将响应输出到标准输出的命令，都可以作为 redline 运行器：

redline init --runner stdio --copy-runner --github-action

内置适配器涵盖与提供商无关的标准输入／输出、OpenAI、Anthropic、LiteLLM、HTTP API、Python 链、JSONL 日志导入，以及 OpenAI／Anthropic SDK 捕获：

redline runners
redline runners --copy all

运行器详情请参阅 docs/runners.md。日志导入和 SDK 捕获适配器用于根据真实观测构建测试套件，而非用于 redline eval 重放。JSONL 日志适配器包含 Langfuse、Helicone、LangSmith 和 Braintrust 的预设，可用于导出的可观测性日志。

原生 AI 助手支持

redline 内置本地模型上下文协议服务：

redline-mcp

请参阅 docs/mcp.md，了解如何将 redline 接入 MCP 客户端。MCP 接口提供安全的捕获就绪情况、隐私、审计、规模、读取、快速检查、用例检查、评估和报告工具，以及 setup_redline_project、check_prompt_change、build_suite_from_logs 和 review_candidate_outputs 等工作流提示词。 在设置过程中，它还可以列出或复制运行器适配器和可选的评审模板。 唯一会修改数据的 MCP 工具受到保护：redline_mark 需要设置 allow_write: true 并提供备注，才能记录有意作出的用例判断。基线提升仅支持通过 CLI 操作。

CI 和 GitHub

创建配置和 GitHub Actions 工作流：

redline init --runner stdio --copy-runner --github-action

在其他代码仓库中将 redline 用作复合 GitHub Action：

- uses: gowtham0992/[email protected]
  with:
    prompt-path: prompts/v2.txt
    benchmark-max-seconds: "300"

对于包含多个提示词的代码仓库，将 suite 指向 redline-prompts.json。该 Action 会使用 redline prompts --check --check-suites 检查每个映射的测试套件，运行覆盖整个清单的基准测试，然后运行清单评估。

该 Action 会在 .redline/ 下写入 JSON、完整 Markdown、精简的 PR 评论 Markdown、HTML、JUnit、适用于 Slack 的 JSON、历史记录、仪表板和审计检查点等产物；将基准测试、精简评估和趋势摘要追加到 GitHub 步骤摘要中；并以评估门禁状态退出。如果测试套件的最坏情况运行时间预算增长过多时应导致 CI 失败，请设置 benchmark-max-seconds。

报告

每次 diff 和 eval 运行都可以生成：

• 供机器和仪表板使用的 JSON
• 用于详细摘要的完整 Markdown，包括提示词清单汇总
• 用于合并审查界面的精简 PR 评论 Markdown
• 可独立使用的 HTML，便于并排检查，包括特性和提示词评估表格
• 用于 CI 测试报告的 JUnit XML
• 供你控制的 CI 机器人或 webhook 集成使用的 Slack Block Kit JSON
• 针对已更改或阻塞用例的 GitHub 注释

示例：

redline diff redline-suite.json logs/candidate.jsonl \
  --out-json .redline/reports/diff.json \
  --out-md .redline/reports/diff.md \
  --out-comment .redline/reports/diff-comment.md \
  --out-html .redline/reports/diff.html \
  --out-junit .redline/reports/diff.xml \
  --out-slack .redline/reports/diff.slack.json

可选评审器

只有结构化检查不足时才使用评审器。redline 只会将有歧义的 changed 用例以 JSON 形式通过标准输入发送给配置的命令：

redline judges
redline judges --copy openai
redline judges --copy support-rubric
redline diff logs/candidate.jsonl --judge "python examples/judge_changed.py"

代码仓库示例和可安装模板：

• examples/judge_changed.py
• examples/openai_judge.sh
• examples/anthropic_judge.sh
• examples/litellm_judge.sh
• examples/judges/support_rubric.md
• examples/judges/extraction_rubric.md
• examples/judges/safety_rubric.md

校准指南请参阅 docs/judges.md。

配置

redline init 会写入 redline.json，其中包含用于编辑器自动补全的 $schema 引用。重要键如下：

键	用途
suite	套件基线路径，默认为 redline-suite.json。
input_field, output_field	提示词和响应的 JSONL 字段路径。
max_cases	为套件选取的代表性案例数量上限。
replay	eval 使用的命令；默认通过 stdin 传入提示词。{prompt} 用于小型旧版 argv 运行器；{prompt_file} 传递临时渲染提示词文件的路径。
workers	并发运行的重放案例数。
owners	可选的模式到负责人的规则，以便在回归时显示负责的团队。
approval	可选的本地防护措施；require_approver 会让 accept 记录审批人。
fail_on	会导致 diff 或 eval 失败的状态；仅用于报告的设置请使用 "none"。
reports	JSON、Markdown、PR 评论 Markdown、HTML、JUnit 和适用于 Slack 的 JSON 输出路径。
logs	观测到的提示词-响应日志路径，以及可选的中间件跳过诊断路径。
audit	用于 eval、判定、要求和已接受基线的仅追加 JSONL 审计日志路径。新条目包含操作员/审批人上下文以及本地哈希链，可通过 redline audit --verify 检查；使用预期哈希/计数检查点或 --out-checkpoint 证据文件来检测尾部截断。
judge	用于判定有歧义的 changed 案例的可选命令。

依赖套件前，请检查设置：

redline doctor --strict
redline validate redline-suite.json --strict
redline summary redline-suite.json

doctor 会显示套件是否有明确要求或已记录的判定，以便你在 CI 中依赖结构检查。 summary 会报告套件就绪度评分、行为组/案例覆盖率、负责人覆盖率、已接受的基线历史、审批人覆盖率，以及对有要求或已记录判定的案例的明确防护覆盖率，供团队在 CI 前审查套件就绪情况。 如果存在 .redline/audit-checkpoint.json，dashboard 也会显示审计检查点证据。

Dogfood 资源

公开夹具为合成数据，其结构参考公开指令/聊天数据集的模式，并记录于 examples/public_dogfood_sources.md。

python -m redline suite examples/public_dogfood_baseline.jsonl --out /tmp/redline-public-suite.json --all-cases
python -m redline diff /tmp/redline-public-suite.json examples/public_dogfood_candidate.jsonl --compact --fail-on none

针对 AI 助手会话的 dogfood，请使用 docs/ai-session-dogfood-prompts.jsonl， 并通过 scripts/normalize_ai_session_logs.py 规范化原始导出数据。 可复现的 dogfood 案例研究见 docs/case-studies.md。 适用于互联网 dogfood 的公开数据集候选项已按优先级排列，见 docs/internet-dogfood-sources.md。

在仓库检出目录中，记录公开演示：

bash scripts/demo_terminal.sh
bash scripts/demo_gif.sh .redline/launch .redline/launch/redline-demo.gif

开发

python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check .
python -m mypy redline tests scripts examples

发布或请他人试用分支前：

bash scripts/release_check.sh

项目文档

• docs/release.md：软件包、标签、PyPI 和 MCP Registry 发布流程
• docs/launch.md：公开 Alpha 发布计划
• docs/troubleshooting.md：首次运行和 CI 故障恢复
• docs/import-guides.md：Langfuse、Helicone、OpenAI chat、Datadog 和自定义日志导入指南
• docs/methodology.md：行为分组、用例选择、评分和信任边界
• docs/calibration.md：展示回归、更改用例和中性用例的小型测试样例
• docs/commands.md：精简的 CLI 命令参考
• docs/real-log-dogfood.md：优先进行脱敏的真实日志测试协议
• docs/dogfood.md：首批用户试用协议
• docs/case-studies.md：可复现的试用案例研究
• docs/internet-dogfood-sources.md：用于试用数据收集的公开提示词-响应数据集
• docs/runners.md：运行器和日志适配器设置
• docs/mcp.md：MCP 服务设置
• docs/benchmarks.md：性能规范和 CI 基准测试产物
• docs/repository.md：GitHub 仓库控制
• scripts/README.md：维护者脚本索引
• CONTRIBUTING.md：贡献者验证
• SECURITY.md：隐私和漏洞报告
• LICENSE：MIT 开源许可证

GitHub Pages 的网站源文件位于 site/，并从提交到 main 的静态资源部署。