后端开发者
从团队已有的 OpenAPI 快速得到 smoke tests，在本地修改后反复运行。
1. 产品定位
LingTest CLI 是面向 Vibe Coding 工作流的开源 AI 测试 Agent。它读取 PRD、需求说明和 OpenAPI 文档，使用 LLM 发现需求风险并生成结构化测试计划，再由确定性执行引擎运行审核后的接口用例，最终输出可复现的测试证据和失败诊断。
核心原则：AI 负责理解、扩展和诊断；确定性引擎负责执行和判定；任何 AI 输出必须经过结构校验和人工审阅；密钥不写入用例；命令退出码可用于流水线门禁；Python SDK 与 CLI 共用同一套核心逻辑。
PRD / OpenAPI → AI 分析与测试设计 → 人工审阅 → 确定性执行 → AI 诊断 → JSON / JUnit 证据
非目标
0.x 阶段不替代完整的 API 管理平台，不提供 Web 协作后台，不承担未经授权的生产流量测试，不把模型判断直接当作发布结论，也不在用户未选择 Provider 时发送文档或测试数据。
2. 目标用户与场景
测试工程师
用结构化 JSON 管理接口用例，统一输出结果，并逐步接入 AI 辅助扩展边界场景。
DevOps / CI 维护者
在 GitHub Actions、Jenkins 或 GitLab CI 中执行接口门禁并收集 JUnit 报告。
Python 工具开发者
通过公开 SDK 函数组合用例生成与执行能力，构建内部质量工具。
3. 产品价值与差异化
从需求阶段开始
传统 API runner 从已有用例开始；LingTest 在编码前检查需求歧义、矛盾、遗漏和不可测试描述，把返工风险提前暴露。
AI 与确定性分层
模型生成候选分析和用例，但 HTTP 状态、断言、退出码和报告由可重复执行的代码产生，避免用模型代替测试判定。
审阅优先
AI 结果先写入结构化 JSON，明确来源需求、优先级、步骤和预期结果；用户批准后才进入执行阶段。
本地优先与可替换模型
基础功能无需账号或云端服务；AI 层支持多家 OpenAI-compatible Provider，避免业务流程绑定单一模型供应商。
面向 CI 的证据
JSON 用于后续处理，JUnit 用于流水线展示，退出码用于质量门禁；诊断保留依据和置信度，而不是只给自然语言结论。
从 CLI 演进为 Agent
CLI 命令是未来 Agent 的稳定工具接口。Agent 可以编排分析、生成、执行和诊断，但每一步仍可单独调用、测试和审计。
4. 已实现功能
OpenAPI 3.x 读取
支持 YAML 和 JSON 文件，遍历 paths 和常见 HTTP 方法；缺少 paths 时给出明确错误。
确定性用例生成
根据 operationId、summary、参数、请求体和响应码生成用例，不需要模型 API key。
示例值推导
依次使用 example、default、enum 和类型默认值，支持 object、array、string、number、integer、boolean。
路径、查询与 Header 参数
填充路径占位符，构建 query 参数和规范中声明的 header；运行时可追加认证 Header。
HTTP 执行器
基于 HTTPX 顺序执行用例，支持 base URL、超时和运行时 Header，记录耗时与实际状态码。
可编辑中间格式
生成普通 JSON 用例文件。用户可在执行前审阅 expected_status、请求参数、body 和标题。
双格式报告
默认输出结构化 JSON；可选输出 JUnit XML，便于 CI 测试报告面板解析。
CI 退出码
全部通过返回 0，存在失败返回 1，输入或命令错误返回 2。
Python SDK 基础接口
公开 TestCase、TestResult、RunReport、generate_cases 和 run_cases。
工程化发行
采用 src layout、Hatchling、UV lock、PyPI 元数据、MIT License、pytest、Ruff 与 Twine 校验。
独立 LLM Provider
支持 OpenAI、DeepSeek、Qwen 和自定义 OpenAI-compatible 服务；无 Redis、数据库或 Web 服务依赖。
PRD 歧义分析
识别歧义、逻辑矛盾、缺失需求和可测试性风险，并输出需要产品人员回答的问题。
LLM 测试计划生成
从 PRD 或 OpenAPI 生成功能、边界、异常和 API 用例，保留优先级、步骤、预期结果和需求依据。
结构化输出校验
提取模型 JSON 并通过 Pydantic 数据契约校验；失败时携带校验错误自动修复一次。
AI 失败诊断
仅分析失败和错误用例，区分产品、测试、环境、数据和依赖问题，并保留置信度和证据。
5. 用户工作流与命令
端到端测试数据流
PRD / Requirements
|-- lingtest analyze ------> analysis.json
| (ambiguities / contradictions / risks)
|
`-- lingtest ai-generate --> ai-cases.json --> Human review
(validated plan) |
| planned in 0.3
OpenAPI YAML / JSON v
|-- lingtest ai-generate --> ai-cases.json cases.json
| (executable)
`-- lingtest generate -------------------------------^
|
Base URL + runtime headers ----------------------------+
v
lingtest run
| |
v v
report.json junit.xml
|
v
lingtest diagnose
|
v
diagnosis.json分析、AI 测试计划、确定性用例、原始执行报告和诊断报告是相互独立的产物。0.2.0 不会自动执行 AI 生成内容，也不会让诊断覆盖原始报告；人工审核后的 AI 用例到可执行用例的转换计划在 0.3 实现。
AI 需求分析与测试设计
lingtest analyze requirements.md -o analysis.json
lingtest ai-generate requirements.md -o ai-cases.json安装和生成
pipx install lingtest-cli
lingtest generate openapi.yaml -o cases.json审阅和执行
lingtest run cases.json \
--base-url https://api.example.com \
-H "Authorization:Bearer $API_TOKEN" \
--junit junit.xml \
-o report.json失败诊断
lingtest diagnose report.json -o diagnosis.json生成用例的数据契约
| 字段 | 用途 | 示例 |
|---|---|---|
id | 稳定用例标识 | get_user |
method / path | HTTP 请求目标 | GET /users/42 |
expected_status | 成功判定标准 | 200 |
headers / query | 规范推导的请求参数 | {"verbose": true} |
body | 可选 JSON 请求体 | {"name": "test"} |
工作流状态
| 状态 | 产生方式 | 进入下一阶段的条件 |
|---|---|---|
| 需求待澄清 | lingtest analyze | 高风险歧义和矛盾已由负责人处理或明确接受。 |
| 测试计划待审阅 | lingtest ai-generate | 用例有明确依据、步骤、预期结果，并删除不安全数据。 |
| 可执行用例 | lingtest generate 或未来转换命令 | 请求目标、参数、认证和断言均已确认。 |
| 执行证据 | lingtest run | 报告完整保存，失败项进入诊断或人工调查。 |
| 诊断建议 | lingtest diagnose | 根据原始日志和系统证据复核后，才能形成缺陷结论。 |
6. 技术架构
| 模块 | 职责 |
|---|---|
cli.py | Typer 命令、参数校验、输出和退出码。 |
openapi.py | 加载规范并生成确定性测试用例。 |
models.py | Pydantic 公共数据模型。 |
runner.py | HTTPX 同步执行器和结果聚合。 |
io.py | JSON 用例、JSON 报告和 JUnit XML 序列化。 |
ai/provider.py | Provider 协议、内置服务地址、认证环境变量和 OpenAI-compatible HTTP 调用。 |
ai/structured.py | JSON 提取、Pydantic 校验和一次受控修复重试。 |
ai/service.py | PRD 分析、测试计划生成和失败诊断的业务编排。 |
ai/prompts.py | 任务边界、输出 schema 和证据要求。 |
核心模块不依赖 FastAPI、Redis、Dramatiq 或数据库。未来模型 Provider、插件和并发执行器必须保持可选，避免破坏本地优先的基础安装体验。
依赖方向
CLI → Service → Provider / Structured Output → HTTPX / Pydantic。Provider 不感知命令行，业务服务不读取环境变量，确定性 runner 不依赖 AI 模块，从而允许测试替身、离线执行和后续插件替换。
7. AI 信任边界与安全模型
| 风险 | 当前控制 | 后续控制 |
|---|---|---|
| 模型输出无效或字段缺失 | JSON 提取、Pydantic 严格校验、一次修复重试，失败则退出码 2。 | 保存原始响应摘要和 schema 版本，提供离线重放。 |
| 模型编造需求 | Prompt 要求仅基于文档，并为用例保留 source_requirement。 | 需求引用定位、覆盖矩阵和无依据用例拦截。 |
| 敏感文档外发 | 只有调用 AI 命令时才发送文档；Provider 和地址由用户明确选择。 | 本地模型配置、内容脱敏、发送前预览和域名 allowlist。 |
| API Key 泄露 | 密钥仅从环境变量读取，不进入命令输出、用例和报告。 | 系统密钥环集成、日志统一脱敏和凭据扫描。 |
| AI 诊断被误当成事实 | 诊断包含分类、置信度、证据和建议；不修改原始报告。 | 人工确认状态、历史证据关联和诊断准确率评估。 |
| 未经授权执行测试 | 生成与执行分离，不自动运行 AI 用例。 | 目标 allowlist、危险方法确认、速率限制和 dry-run。 |
数据发送边界
analyze 和 ai-generate 会把文档内容发送给指定 Provider；diagnose 只发送失败或错误结果，不发送通过用例。generate 和 run 不调用 LLM。当前不提供模型响应缓存，也不持久化 API Key。
8. 数据契约与兼容策略
| 产物 | 关键内容 | 兼容承诺 |
|---|---|---|
| 需求分析 | summary、ambiguities、contradictions、missing_requirements、testability_risks | 0.x 可增加字段；删除或改义需在 changelog 标记。 |
| AI 测试计划 | risks、case_type、priority、steps、expected_result、source_requirement、可选 API 字段 | 执行前必须再次校验；AI 产物不自动视为可执行。 |
| 确定性用例 | method、path、expected_status、headers、query、body | 同一 minor 版本保持可读取；未来使用显式 schema_version。 |
| 运行报告 | started_at、base_url、status、duration、预期/实际状态和 error | 原始结果不可被 AI 诊断覆盖。 |
| 诊断报告 | failure_type、confidence、diagnosis、evidence、suggestions | 始终作为建议性派生产物保存。 |
所有 JSON 文件使用 UTF-8。运行时 Header 不写入报告。未来破坏性 schema 变化必须升级主版本或提供迁移命令。
9. 计划实现
OpenAPI 引用解析
支持本地和文档内 $ref、组合 schema、nullable、format 及更完整的 requestBody content。
配置文件与环境
增加 lingtest.toml、dev/staging 环境、变量替换、敏感值环境变量映射。
用例过滤
按 tag、operationId、路径、方法过滤；支持 include/exclude 和失败重跑。
更多断言
状态码之外增加 JSON path、schema、响应头、响应时间和包含关系断言。
认证策略
支持 OpenAPI securitySchemes、Bearer、API Key、Basic 和可插拔 token 获取。
并发与重试
提供可控并发、退避重试、速率限制；默认仍保持可预测的顺序执行。
AI 用例执行转换
把人工审核后的 AI API 用例转换为确定性 HTTP 用例，执行前再次进行 schema 和安全检查。
HTML 报告与覆盖矩阵
提供静态报告，并建立需求、用例、执行结果和诊断之间的可追踪关系。
RAG 与 pytest 导出
接入历史缺陷和测试规范，生成可维护 pytest 脚本，支持团队纳入现有测试目录。
Agent 工具编排
把分析、生成、执行和诊断暴露为可审计工具，加入预算、审批、目标 allowlist 和停止条件。
稳定 SDK 与插件协议
承诺语义化版本兼容范围，为输入解析器、断言、认证和报告定义稳定扩展点。
优先级原则
AI 已用于需求理解、测试设计和失败诊断；确定性执行仍不依赖模型。下一阶段优先打通“AI 生成、人工审核、确定性执行”，再扩展断言、并发、RAG 和 Agent 工具调用。
10. 产品成功指标
| 维度 | 指标 | 为什么重要 |
|---|---|---|
| 首次价值 | 从安装到生成第一份有效分析或用例计划所需时间。 | 决定开源用户是否愿意继续试用。 |
| 有效性 | 人工接受的歧义、风险和测试用例比例。 | 衡量 AI 输出是否减少工作，而非制造审核负担。 |
| 可追踪性 | 能够关联到原始需求的用例比例。 | 控制幻觉并支撑覆盖分析。 |
| 稳定性 | 相同输入多次生成后，结构校验成功率和关键场景保持率。 | 衡量非确定性是否处于可管理范围。 |
| 执行价值 | 生成用例中经审核后可执行、能发现真实问题的比例。 | 避免只追求用例数量。 |
| CI 适配 | 无人工交互执行成功率、报告解析成功率和平均执行时间。 | 确认工具能够进入真实工程流程。 |
项目不把 Token 消耗、生成用例总数或自然语言篇幅作为核心成功指标。首要目标是有效测试证据和用户节省的审核、设计与定位时间。
11. 质量、安全与发布标准
- 支持 Python 3.11 和 3.12；Windows、Linux、macOS 进入 CI 矩阵。
- 每个命令覆盖成功、测试失败和输入错误三类行为；公共模型保持向后兼容。
- 报告默认不保存运行时认证 Header；后续响应内容记录必须提供脱敏策略。
- 每次发布运行 pytest、Ruff、构建和 Twine 检查，并使用 Git tag 与 PyPI 版本一致。
- 遵循语义化版本；0.x 允许快速迭代，但破坏性变更必须记录在 changelog。
0.2.0 验收目标
已完成：Provider、PRD 分析、用例生成、结构校验和失败诊断均具备无网络单元测试；基础执行器保持兼容；Ruff、pytest、wheel、sdist 和 Twine 元数据检查通过。
发布门禁
版本号、Git tag 和 PyPI release 必须一致；发布前检查工作区、测试、静态检查、构建、包元数据和 README 渲染；发布后从干净环境安装并运行 lingtest --version。0.x 版本不得暗示未实现的 Agent 自主能力。
12. 开源治理与许可
项目当前使用 MIT License，目的是降低个人、企业和测试工具厂商试用、集成及二次开发的门槛。使用者必须保留版权和许可证声明，软件按原样提供且不附带担保。
MIT 不要求修改后的版本继续开源，也不提供 Apache-2.0 那样明确的专利授权条款。若项目未来出现核心商业化、专利贡献或云服务竞争保护需求，应在接受大量外部贡献前重新评估 Apache-2.0、AGPL-3.0 或开源核心加商业许可；许可证变更不能追溯撤销已经按 MIT 获得的版本权利。
贡献原则
- 贡献应包含测试，并说明对数据契约和兼容性的影响。
- 新增 Provider 不得记录或上传 API Key，不得绕过结构校验。
- 新增 AI 能力必须说明发送给第三方的数据、人工审批点和失败模式。
- 安全问题应通过私密渠道报告；建立正式流程前不要在公开 Issue 披露可利用细节。