发布、启动与开发调试教程
从本地开发到 PyPI 发布的一份可执行手册，同时覆盖普通 CLI、Hermes 风格 TUI、LLM Provider、鉴权示例和 Agent JSONL 工作流。
最短启动命令
uv sync --extra dev --extra tui
uv run lingtest --help
uv run lingtest tui
发布结论
每次版本发布都必须生成新的 dist。使用 uv build --clear 清掉旧包后重新构建，避免把旧版本 wheel/sdist 一起上传。
1. 如何用 UV 启动当前项目
1
同步环境
在仓库根目录执行。开发依赖包含 pytest、Ruff、Twine；TUI 依赖包含 Textual、LangGraph 和 SQLite checkpointer。
uv sync --extra dev --extra tui
2
检查 CLI
uv run lingtest --version
uv run lingtest --help
uv run lingtest providers
providers 只显示环境变量是否已配置，不打印 API Key。
3
选择启动方式
人类用户
uv run lingtest tui
Agent / CI
uv run lingtest workflow workflow.json `
--events jsonl --result result.json
单步 CLI
uv run lingtest generate examples/openapi.yaml `
--strategy deterministic -o cases.yaml
Windows 路径可使用正斜杠，也可对带空格路径加双引号。HTML 报告默认只打印绝对路径；只有传入 --open-browser 或在 TUI 输入 /report open 才启动浏览器。
2. 如何开发调试 lingtest-cli
常用质量命令
uv run pytest
uv run pytest tests/test_orchestration.py -vv
uv run pytest tests/test_tui.py -vv
uv run ruff check src tests
uv run ruff format --check src tests
直接调试 Python 模块
uv run python -m lingtest.cli --help
uv run python -m pdb -m lingtest.cli generate examples/openapi.yaml `
--strategy deterministic -o cases.json
推荐在 IDE 中把模块设为 lingtest.cli，工作目录设为仓库根目录。因为项目使用 src layout，不要直接运行 src/lingtest/cli.py；通过 UV 启动可以确保使用锁定环境和正确的可编辑安装。
LLM Provider
$env:OPENAI_API_KEY = "..."
$env:DEEPSEEK_API_KEY = "..."
$env:KIMI_API_KEY = "..."
$env:DASHSCOPE_API_KEY = "..."
uv run lingtest providers
自定义 OpenAI-compatible 服务写入 .lingtest/providers.json，只保存 model_name、url 和 api_key_env，不要保存真实密钥。
3. 从 PRD 到接口报告
uv run lingtest analyze PRD.docx -o analysis.json
uv run lingtest ai-generate PRD.docx -o functional-cases.html
uv run lingtest generate openapi.yaml --strategy auto `
--functional-cases functional-cases.html -o api-cases.yaml
uv run lingtest script api-cases.yaml `
--auth-example examples/auth_example.py `
--auth-plan-mode standalone -o tests/test_api_generated.py
uv run lingtest run api-cases.yaml --base-url http://localhost:8000 `
-o report.html --json-output report.json --junit junit.xml
| 策略 | 行为 | 是否调用 LLM |
|---|---|---|
| deterministic | 精确解析标准 OpenAPI | 否 |
| ai | 把 Word/文档内容交给模型生成场景 | 是 |
| auto | OpenAPI 结构化解析 + AI 补充；Word 使用 AI | 按输入决定 |
鉴权 Python 示例在生成阶段只做 AST 静态分析，不会被 import 或执行。签名类鉴权应由用户维护受控 hook；LingTest 校验项目内路径、函数名和 SHA-256，在明确授权运行测试后才加载。
4. 发布到 PyPI
1
确定版本号
同时修改 pyproject.toml 和 src/lingtest/__init__.py，确保版本一致。PyPI 不允许覆盖已经上传的同名版本。
2
更新锁文件并运行门禁
uv lock
uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
3
重新生成 dist
uv build --clear
uv run twine check dist/*
--clear 会先清理输出目录中的旧制品，再生成当前版本的 wheel 与 sdist。
4
检查包内容
Get-ChildItem dist
uv run python -m zipfile -l dist/lingtest_cli-0.4.0-py3-none-any.whl
将示例版本号替换为当前版本，确认源码、README、Skill 和依赖元数据符合预期。
5
发布
$env:UV_PUBLISH_TOKEN = "pypi-..."
uv publish
你已经设置 UV_PUBLISH_TOKEN 时，不要在命令行重复写出 token。发布属于不可覆盖的外部操作，只应在测试、Ruff、build 和 Twine 全部通过后执行。
6
发布后验证
uvx --from lingtest-cli==0.4.0 lingtest --version
uvx --from "lingtest-cli[tui]==0.4.0" lingtest --help
确认 PyPI 安装到的是新版本，普通 CLI 与 TUI extra 都能解析。随后提交版本 commit、创建相同版本的 Git tag，再推送。
不要复用旧 dist。即使源码只改了一行，也要 bump 版本并执行 uv build --clear。否则可能上传旧包、混合多个版本，或者因 PyPI 文件名已存在而失败。