grauwolf32/contractor

# Contractor `contractor` 是一个用于使用 LLM 从源代码生成和丰富 OpenAPI 规范的 CLI 工具。 ## 功能 目前提供以下管道： * `build` — 从项目代码构建或更新 OpenAPI 规范 * `enrich` — 根据项目结构和实现丰富现有的 OpenAPI 产物 CLI 以 `contractor` 命令安装。 ## 需求 * Python `>=3.10,<3.15` * Poetry * 运行的 LiteLLM 代理 * 具有 OpenAI 兼容 API 的 LLM 后端 ## 开始之前 在运行 `contractor` 之前，您需要： 1. 启动 LiteLLM 代理 2. 配置它 3. 确保所需模型通过后端可用 4. 使用 Poetry 安装项目依赖 在这个仓库中，LiteLLM 通常通过以下方式启动： ``` deploy/litellm/run.sh ``` 这不是强制性的。您可以以任何方便的方式启动代理，只要满足以下条件： * 应用程序可以访问 LiteLLM * 配置中的模型名称与传递给 `--model` 的名称匹配 ## LiteLLM 配置示例 文件 `litellm_config.yaml`： ``` model_list: - model_name: lm-studio-nemotron litellm_params: model: openai/nvidia/nemotron-3-nano api_key: lm-studio api_base: http://localhost:1234/v1 tpm: 100000 rpm: 10 - model_name: lm-studio-openai litellm_params: model: openai/openai/gpt-oss-20b api_key: lm-studio api_base: http://localhost:1234/v1 tpm: 100000 rpm: 10 - model_name: lm-studio-qwen3.5 litellm_params: model: openai/qwen/qwen3.5-35b-a3b api_key: lm-studio api_base: http://localhost:1234/v1 tpm: 100000 rpm: 10 litellm_settings: num_retries: 3 request_timeout: 300 ``` ### 这里的关键点 * `model_name` — 之后在 CLI 中通过 `--model` 使用的名称 * `api_base` — OpenAI 兼容的 API 端点 * `request_timeout: 300` — 对长时间运行的任务很有用 * `num_retries: 3` — 错误时的重试次数 ## 通过 Podman 运行 LiteLLM 代理的示例 ``` podman run --rm -d \ -v $(pwd)/litellm_config.yaml:/app/config.yaml \ -e LITELLM_MASTER_KEY="sk-litellm-changeme" \ -e LITELLM_SALT_KEY="sk-random-hash-changeme" \ --network="host" \ "ghcr.io/berriai/litellm:main-stable" \ --config /app/config.yaml ``` 如果仓库已经包含现成的脚本，您可以使用它： ``` deploy/litellm/run.sh ``` ## 安装 ``` poetry install python -c "from tree_sitter_language_pack import download_all;download_all();" ``` 安装后，CLI 可通过以下方式使用： ``` poetry run contractor --help ``` 如果 Poetry 环境已激活，您可以简单地运行： ``` contractor --help ``` ## 使用方法 ### 一般格式 ``` contractor \ --pipeline \ --project-path \ --folder-name \ --user-id \ --model ``` ### 参数 * `--pipeline` — 管道名称 目前可用：`build`、`enrich` * `--project-path` — 项目目录的路径 * `--folder-name` — 项目内将用于任务模板的路径 默认值：`/` * `--artifact` — 现有 OpenAPI 文件的路径 需要输入产物的管道使用，如 `enrich` * `--user-id` — 运行器的用户标识符 默认值：`cli-user` * `--model` — LiteLLM 配置中的模型名称 默认值：`lm-studio-qwen3.5` ## 示例 ### 从项目代码构建 OpenAPI ``` contractor \ --pipeline build \ --project-path /path/to/project \ --folder-name /src \ --model lm-studio-qwen3.5 ``` 最好将项目放在一个单独的隔离文件夹中，以免代理意外进入相邻项目。 ### 丰富现有的 OpenAPI 文件 ``` contractor \ --pipeline enrich \ --project-path /path/to/project \ --folder-name /src \ --artifact /path/to/openapi.yaml \ --model lm-studio-qwen3.5 ``` ## 输入参数验证 CLI 会验证： * `--project-path` 存在且是一个目录 * `--folder-name` 在 `--project-path` 内存在 * `--artifact` 存在且是一个文件 * `--artifact` 仅针对需要它的管道提供 之后，新管道将自动出现在 `--pipeline` 中。 ## 主要项目部分 * `contractor/main.py` — CLI 入口点 * `contractor/agents/` — 代理 * `contractor/runners/` — 管道运行器 * `contractor/tasks/` — YAML 任务定义 * `contractor/tools/` — 代理工具 * `contractor/utils/` — 工具函数 重要的是，相应的模型确实可以通过后端获得。 ## 典型运行场景 1. 启动带有模型的后端 2. 启动 LiteLLM 代理 3. 安装依赖： poetry install 4. 检查 CLI： poetry run contractor --help 5. 运行所需的管道： poetry run contractor \ --pipeline build \ --project-path /path/to/project \ --model lm-studio-qwen3.5 ## 故障排除 ### `contractor: command not found` 使用： ``` poetry run contractor --help ``` 或激活 Poetry 虚拟环境。 ### 模型错误 检查以下内容： * LiteLLM 代理正在运行 * 传递给 `--model` 的名称与 `litellm_config.yaml` 中的 `model_name` 匹配 * 后端确实可以通过 `api_base` 访问 ### `--artifact` 错误 对于 `enrich`，您需要提供一个现有文件： ``` --artifact /path/to/openapi.yaml ``` ### 长时间响应或超时 您可以： * 在 LiteLLM 配置中增加 `request_timeout` * 选择不同的模型 * 通过 `--folder-name` 限制分析范围 ## 开发 安装依赖： ``` poetry install ``` 运行测试： ``` poetry run pytest ``` 检查： ``` poetry run ruff check . poetry run mypy . ``` ## 添加新管道 管道列表集中在 `contractor/main.py` 的管道注册表中。 要添加新管道，只需： 1. 实现一个返回 `TaskRunner` 的函数 2. 将其添加到 `get_pipelines()` 示例： ``` def get_pipelines() -> dict[str, PipelineSpec]: return { "build": PipelineSpec(builder=oas_building_pipeline), "enrich": PipelineSpec(builder=oas_enrichment_pipeline, requires_artifact=True), "my-new-pipeline": PipelineSpec(builder=my_new_pipeline), } } ```

标签：API开发工具, API文档生成, API规范管理, DLL 劫持, LiteLLM, OpenAI兼容API, OpenAPI规范, Python, RESTful API, 代码生成, 大语言模型, 开发效率工具, 提示词优化, 无后门, 渗透测试工具, 自动化文档, 规范丰富, 逆向工具