Logo

菜单

发布于 2026-01-06 0 阅读
0

🚀 使用 Qodo Command DEV 构建自定义 AI 代理，Mux 呈现的全球展示挑战赛：展示你的项目！

🚀 使用 Qodo 命令构建自定义 AI 代理

由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！

开发者们好👋

我最近试用了Qodo Command，这是一个命令行工具，它允许你直接从代码库构建、运行和自动化 AI 智能体，就像自定义 AI 助手一样，它们就存在于你的代码库中。✨

与通用 AI 工具或一次性脚本不同，Qodo 代理可配置、可版本控制，并且对持续集成 (CI) 非常友好。您只需在TOML/YAML文件中描述代理应该执行的操作，它就能在本地开发、PR 检查和 CI 流水线中始终如一地执行这些操作。这意味着您可以更智能地自动化代码审查、可靠性检查、文档审核、测试生成以及团队所需的任何其他任务。

如果你一直想要一个能够执行你项目特定标准（而不是其他人的标准）的助手，Qodo Command 就能帮你实现。🫡

本文将涵盖以下内容：

  • Qodo Command 实际有哪些功能？

  • 它对开发团队和 CI/CD 工作流程有何用处

  • 如何一步一步使用它

  • 一个实际的例子：构建一个Clean Code Description代理，通过审查文档字符串、注释和命名约定，确保你的代码库保持整洁、易读且文档齐全。

让我们开始吧！🚀

什么是Qodo Command？

Qodo Command是一款以开发者为先的 CLI，可让您在开发工作流程中创建和运行自定义 AI 代理。

你可以把它想象成一个由人工智能驱动的个人自动化引擎，但它不是使用通用提示，而是在配置文件中为代理定义可重复的规则、逻辑和行为。

Qodo Command 支持：

  • 自定义代理配置
  • CI 和自动化集成
  • 交互式 Web UI 模式
  • 通用代码生成
  • 智能公关代码审查

如果ChatGPT是你与之对话的智能助手，那么 Qodo Command 就是驻留在你的代码库中并执行你的标准的 AI 队友。

⭐️ 主要特点

  • 交互式聊天模式：直接在您的终端（qodo 聊天）上用自然语言与客服人员交谈，就像使用 Qodo Gen 聊天一样。

  • 自定义代理命令：配置您自己的代理并定义可重用的工作流程（qodo <command>）。

  • 交互式 Web UI 模式：运行 Qodo 命令，以--ui在交互式 Web UI 中与 Qodo 命令的聊天进行交互。

  • 将代理作为 HTTP API 提供服务：将任何代理转换为可调用的服务（--webhook mode）。

  • 模型控制：选择要使用的 AI 模型（Claude、GPT-4 等）--model={model-name}。

  • Agent to MCP：使用--mcp.

  • 安全集成：无需暴露 API 密钥即可使用工具。

🚀 如何安装和使用 Qodo 命令

既然您已经了解了 Qodo 命令是什么，那么让我们开始运行它吧。

npm install -g @qodo/command
Enter fullscreen mode Exit fullscreen mode
  • 要开始使用Qodo Command，您需要先登录：
qodo login
Enter fullscreen mode Exit fullscreen mode

Qodo 指挥部

登录完成后，您将在终端收到一个 API 密钥。

API 密钥也会保存在您主目录下的 .qodo 文件夹中，并且可以重复使用（例如，在 CI 中）。

  • 交互式人工智能聊天模式
qodo chat
Enter fullscreen mode Exit fullscreen mode

在此模式下，您可以发送如下提示：

Write tests for the files in the auth directory

Add better logging througout my project

Use Qodo Merge to describe the changes in my working folder
Enter fullscreen mode Exit fullscreen mode

Qodo Command 将遵循您的指示。

🛠️ 从零开始构建自定义 Qodo 代理

现在，让我们创建一个代码整洁文档代理，该代理会检查您的代码仓库，确保其符合以下要求：

✔️缺少文档字符串
✔️过时或误导性的注释
✔️命名不规范
✔️文档一致性

1️⃣创建代理配置
在项目根目录级别，创建一个名为 . 的文件clean-doc-agent.toml。该文件将包含 Qodo 命令将知道并能够调用的所有代理文件。

# Clean Code Description Agent Configuration
version = "1.0"

[commands.clean_code_description]
description = "Analyze code for clean, consistent, and accurate descriptions in docstrings, comments, and naming conventions"

instructions = """
You are an expert in code documentation and clean code practices. Your task is to:
1. Analyze code changes using Qodo Merge to identify documentation issues
2. Focus on:
   - Missing or incomplete docstrings
   - Outdated or incorrect docstrings/comments
   - Redundant or low-value comments
   - Inconsistent documentation styles
   - Poorly named functions, classes, or variables
3. Categorize findings by severity: Critical, High, Medium, Low
4. Provide clear, actionable feedback for each issue
5. Suggest improvements with concrete examples
6. Ensure that the documentation aligns with the actual behavior of the code
Return feedback that helps developers maintain a clean, readable, and maintainable codebase.
"""

arguments = [
    { name = "target_branch", type = "string", required = false, default = "main", description = "Branch to compare changes against" },
    { name = "severity_threshold", type = "string", required = false, default = "medium", description = "Minimum severity level to report (low, medium, high, critical)" },
    { name = "include_suggestions", type = "boolean", required = false, default = true, description = "Include improvement suggestions" },
    { name = "focus_areas", type = "string", required = false, description = "Comma-separated focus areas (docstrings, comments, naming)" },
    { name = "exclude_files", type = "string", required = false, description = "Comma-separated list of file patterns to exclude from analysis" }
]

tools = ["qodo_merge", "git", "filesystem"]
execution_strategy = "act"

output_schema = """
{
  "type": "object",
  "properties": {
    "summary": {
      "type": "object",
      "description": "High-level summary of documentation and naming quality issues found",
      "properties": {
        "total_issues": {"type": "number", "description": "Total number of issues identified"},
        "critical_issues": {"type": "number", "description": "Number of issues categorized as critical"},
        "high_issues": {"type": "number", "description": "Number of high severity issues"},
        "medium_issues": {"type": "number", "description": "Number of medium severity issues"},
        "low_issues": {"type": "number", "description": "Number of low severity issues"},
        "missing_docstrings": {"type": "number", "description": "Number of functions/classes missing docstrings"},
        "outdated_descriptions": {"type": "number", "description": "Number of outdated or incorrect docstrings/comments"},
        "redundant_comments": {"type": "number", "description": "Number of unnecessary or low-value comments"},
        "poor_names": {"type": "number", "description": "Number of functions, classes, or variables with unclear or inconsistent names"},
        "files_reviewed": {"type": "number", "description": "Total number of files analyzed"},
        "overall_score": {"type": "number", "minimum": 0, "maximum": 10, "description": "Overall documentation quality score (0-10)"}
      },
      "required": [
        "total_issues",
        "critical_issues",
        "high_issues",
        "medium_issues",
        "low_issues",
        "missing_docstrings",
        "outdated_descriptions",
        "redundant_comments",
        "poor_names",
        "files_reviewed",
        "overall_score"
      ]
    },
    "issues": {
      "type": "array",
      "description": "Detailed list of individual issues identified in the codebase",
      "items": {
        "type": "object",
        "properties": {
          "file": {"type": "string", "description": "Path to the file containing the issue"},
          "line": {"type": "number", "description": "Line number where the issue occurs"},
          "severity": {"type": "string", "enum": ["critical", "high", "medium", "low"], "description": "Severity level of the issue"},
          "category": {"type": "string", "description": "Category of the issue (e.g., docstring, comment, naming)"},
          "title": {"type": "string", "description": "Short title summarizing the issue"},
          "description": {"type": "string", "description": "Detailed explanation of the problem"},
          "suggestion": {"type": "string", "description": "Suggested fix or improvement"},
          "code_example": {"type": "string", "description": "Example of improved or corrected code"}
        },
        "required": ["file", "severity", "category", "title", "description"]
      }
    },
    "suggestions": {
      "type": "array",
      "description": "List of broader improvement suggestions for code cleanliness and documentation",
      "items": {
        "type": "object",
        "properties": {
          "file": {"type": "string", "description": "File path for the suggestion"},
          "type": {"type": "string", "description": "Type of suggestion (e.g., naming, docstring, structure)"},
          "description": {"type": "string", "description": "Description of the suggested improvement"},
          "implementation": {"type": "string", "description": "Recommended way to apply the suggestion"}
        },
        "required": ["file", "type", "description"]
      }
    },
    "approved": {"type": "boolean", "description": "Indicates if code meets cleanliness standards"},
    "requires_changes": {"type": "boolean", "description": "Indicates if changes are required before approval"}
  },
  "required": ["summary", "issues", "approved", "requires_changes"]
}
"""

exit_expression = "approved"
Enter fullscreen mode Exit fullscreen mode

代理文件的字段包括：

字段名称 类型 描述
description 细绳 描述您的代理的功能。
当代理以 . 模式运行时，此字段为必填项--mcp。
instructions 细绳 必填字段。
提示人工智能模型解释所需行为。
arguments 对象列表。

支持的类型：'string' | 'number' | 'boolean' | 'array' | 'object'

可以提供给代理的参数列表。

这些论据将被翻译并转发到MCP服务器。
mcpServers 细绳 代理使用的 MCP 服务器列表
tools 列表 MCP 服务器名称列表。允许您筛选代理可以使用的特定 MCP 服务器。
execution_strategy “行动”或“计划” 计划让智能体思考多步骤策略，行动则立即执行操作。
output_schema 细绳 所需代理输出的有效 JSON
exit_expression 字符串（JSONPath） 仅在output_schema指定时适用。
对于 CI 运行，此条件用于确定代理运行是成功还是失败。

我们的代理接受以下参数：

范围 类型 必需的 默认 描述
target_branch 细绳 不 "main" 用于比较更改的分支
severity_threshold 细绳 不 "medium" 最低报告严重程度（低/中/高/危）
include_suggestions 布尔值 不 true 在输出中包含改进建议
focus_areas 细绳 不 - 待审查区域列表（以逗号分隔，包括文档字符串、注释和命名规则）。
exclude_files 细绳 不 - 要从分析中排除的文件模式

2️⃣在本地运行代理
您可以通过传递可选参数来运行此代理。

# Run the agent to review code documentation
qodo clean_code_description

# Compare current changes against the main branch
qodo clean_code_description --target_branch=main

# Focus only on docstrings and naming issues
qodo clean_code_description --focus_areas=docstrings,naming
Enter fullscreen mode Exit fullscreen mode

高级配置

qodo clean_code_description \
  --target_branch=develop \
  --severity_threshold=medium \
  --focus_areas=docstrings,comments,naming \
  --exclude_files="tests/*,*.md" \
  --include_suggestions=true
Enter fullscreen mode Exit fullscreen mode

3️⃣输出格式

代理返回结构化的JSON输出：

{
  "summary": {
    "total_issues": 8,
    "critical_issues": 0,
    "high_issues": 3,
    "medium_issues": 4,
    "low_issues": 1,
    "files_reviewed": 5,
    "overall_score": 7.8,
    "missing_docstrings": 3,
    "outdated_descriptions": 2,
    "redundant_comments": 2,
    "poor_names": 1
  },
  "issues": [
    {
      "file": "src/utils/formatter.py",
      "line": 12,
      "severity": "medium",
      "category": "docstring",
      "title": "Missing function docstring",
      "description": "The function `format_name` lacks a docstring, making its behavior unclear.",
      "suggestion": "Add a concise docstring describing the purpose and parameters.",
      "code_example": "\"\"\"Format the input name by capitalizing each word.\"\"\""
    }
  ],
  "suggestions": [
    {
      "file": "src/models/user.py",
      "type": "naming",
      "description": "Rename variable `usrObj` to `user` for clarity",
      "implementation": "Use descriptive names that reflect purpose instead of type"
    }
  ],
  "approved": false,
  "requires_changes": true
}
Enter fullscreen mode Exit fullscreen mode

完整演示视频如下👇

现在，使用此代理最常见的方式是通过 GitHub Actions 自动审查拉取请求。

我们来github-action为此创建一个文件。

GitHub Actions

name: Clean Code Description Agent
on:
  pull_request:
    branches: [main, develop]

jobs:
  clean-code:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      checks: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Clean Code Description Agent
        uses: qodo-ai/command@v1
        env:
          QODO_API_KEY: ${{ secrets.QODO_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          prompt: clean_code_description
          agent-file: path/to/agent.toml
          key-value-pairs: |
            target_branch=${{ github.base_ref }}
            focus_areas=docstrings,comments,naming
            severity_threshold=medium
            include_suggestions=true
Enter fullscreen mode Exit fullscreen mode

现在每份公关稿都会由代理人自动审核✅

🎯 结语

Qodo Command 不仅仅是一个命令行工具，它更是一种将人工智能引入工程工作流程的新方式：

  • 👨‍💻 像开发工具一样在本地运行

  • 🛠 在 CI/CD 中像队友一样工作

  • ✅ 强制执行您自己的工程规则

  • 🧠 完全可定制的AI代理（无需服务器）

通过这种设置，您的仓库将有一个文档守护者监控每个 PR。

您可以访问代理存储库，其中包含代理实现示例。

谢谢！！🙏

感谢您阅读至此。如果您觉得这篇文章有用，请点赞并分享。也许其他人也会觉得它有用。💖

您可以通过X、GitHub和LinkedIn与我联系。

dev_kiran 图片

基兰·纳拉贡德

技术撰稿人和版主 @DEV ✦ 全栈开发人员 ✦ Exercism 导师 ✦ 开源贡献者 ✦ 合作请联系邮箱 :)
文章来源：https://dev.to/dev_kiran/build-custom-ai-agents-with-qodo-command-2j6d
远程办公人员是否应该根据地理位置获...
IntelliJ IDEA 中所有...