AI Agents · 课时

参数解析与帮助文本

Q: 「参数解析与帮助文本」这节课中我会学到什么？

必需参数与可选参数、类型验证和自动生成的帮助信息。 你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

必需参数与可选参数、类型验证和自动生成的帮助信息。

参数解析与帮助文本 是 CoddyKit 上的免费 AI Agents 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。

良好的 CLI 设计始于良好的参数设计

设计良好的 CLI 代理参数接口，应当让用户仅凭 --help 就能了解如何使用该工具。每个参数都应具有清晰的名称、类型、默认值和说明。

名称不当或缺少文档的参数会让工具难以使用，也难以维护。

必需参数与可选参数

必需参数必须提供；如果缺少这些参数，CLI 会报错退出。可选参数具有 default= 值，可以省略。如何区分两者会影响工具的用户体验。

import argparse

parser = argparse.ArgumentParser(description='AI Agent CLI')

# Required: no default, must be provided
parser.add_argument(
    '--query', '-q',
    type=str,
    required=True,
    help='Question to send to the agent'
)

# Optional: has a default, can be omitted
parser.add_argument(
    '--model', '-m',
    type=str,
    default='gpt-4o-mini',
    help='Model name (default: gpt-4o-mini)'
)

parser.add_argument(
    '--max-tokens',
    type=int,
    default=1000,
    help='Maximum tokens in response (default: 1000)'
)

args = parser.parse_args(['--query', 'test'])
print(args.query, args.model, args.max_tokens)

类型验证

type= 参数会自动转换字符串输入并对其进行验证。您可以使用 int、float、bool 等内置类型，也可以使用自定义函数执行更复杂的验证。

import argparse

def positive_int(value: str) -> int:
    n = int(value)
    if n <= 0:
        raise argparse.ArgumentTypeError(f'{value} must be a positive integer')
    return n

parser = argparse.ArgumentParser()
parser.add_argument('--temperature', type=float, help='LLM temperature 0.0-2.0')
parser.add_argument('--max-results', type=positive_int, default=5,
                    help='Number of results to return (must be > 0)')
parser.add_argument('--timeout', type=float, default=30.0,
                    help='Request timeout in seconds')

# These would be rejected with helpful error messages:
# --temperature abc     -> invalid float value
# --max-results -1      -> must be positive integer
args = parser.parse_args(['--temperature', '0.7', '--max-results', '3'])
print(args.temperature, args.max_results)

使用 choices 限制有效值

choices=[...] 参数会将参数限制在一组固定的允许值中。argparse 会自动完成验证，并在帮助文本中列出这些选项。

import argparse

parser = argparse.ArgumentParser()

parser.add_argument(
    '--format',
    choices=['json', 'text', 'markdown'],
    default='text',
    help='Output format: json, text, or markdown'
)

parser.add_argument(
    '--model',
    choices=['gpt-4o', 'gpt-4o-mini', 'claude-3-5-sonnet', 'gemini-1.5-flash'],
    default='gpt-4o-mini',
    help='Model to use'
)

# Error if invalid value given:
# python agent.py --format xml
# agent.py: error: argument --format: invalid choice: 'xml'
# (choose from 'json', 'text', 'markdown')
args = parser.parse_args(['--format', 'json'])
print(args.format)  # 'json'

使用 store_true 的布尔标志

布尔标志是存在与否的切换项，不需要提供值。使用 action='store_true'，即可在标志存在时将其设为 True，不存在时设为 False。

import argparse

parser = argparse.ArgumentParser()

parser.add_argument(
    '--verbose', '-v',
    action='store_true',
    help='Enable verbose output showing agent reasoning steps'
)

parser.add_argument(
    '--no-cache',
    action='store_true',
    help='Disable response caching'
)

parser.add_argument(
    '--dry-run',
    action='store_true',
    help='Parse arguments but do not run the agent'
)

# Usage: python agent.py --query 'test' --verbose
args = parser.parse_args(['--verbose'])
print(f'verbose={args.verbose}')    # True
print(f'no_cache={args.no_cache}')  # False
print(f'dry_run={args.dry_run}')    # False

metavar：控制帮助文本显示

默认情况下，argparse 会在帮助文本中以大写形式显示参数名称：--query QUERY。使用 metavar= 可以显示更有信息量的占位符，例如 QUESTION 或 URL。

import argparse

parser = argparse.ArgumentParser()

parser.add_argument(
    '--query',
    type=str,
    metavar='QUESTION',  # shown in help as: --query QUESTION
    required=True,
    help='Natural language question for the agent'
)

parser.add_argument(
    '--url',
    type=str,
    metavar='URL',       # shown in help as: --url URL
    help='URL to scrape and summarize'
)

parser.add_argument(
    '--temperature',
    type=float,
    metavar='0.0-2.0',   # shown in help as: --temperature 0.0-2.0
    default=0.7
)

# Help output:
# --query QUESTION    Natural language question for the agent
# --url URL           URL to scrape and summarize
print('metavar makes help text more informative')

使用 nargs 接收多个值

使用 nargs='+' 接收一个或多个值，或使用 nargs='*' 接收零个或多个值。这对于向代理传递 URL、标签或文件路径列表很有用。

import argparse

parser = argparse.ArgumentParser()

parser.add_argument(
    '--urls',
    nargs='+',       # one or more URLs
    metavar='URL',
    help='URLs to analyze (space-separated)'
)

parser.add_argument(
    '--tags',
    nargs='*',       # zero or more tags
    default=[],
    help='Optional tags for filtering results'
)

# Usage: python agent.py --urls https://a.com https://b.com --tags ai research
args = parser.parse_args(
    ['--urls', 'https://a.com', 'https://b.com', '--tags', 'ai']
)
print(args.urls)  # ['https://a.com', 'https://b.com']
print(args.tags)  # ['ai']

使用 add_subparsers() 添加子命令

子命令（例如 git commit、git push）可以为每个命令提供自己的一组参数。在 argparse 中使用 add_subparsers() 定义子命令。

import argparse

parser = argparse.ArgumentParser(description='AI Agent CLI')
subparsers = parser.add_subparsers(dest='command', help='Available commands')

# 'ask' subcommand
ask_parser = subparsers.add_parser('ask', help='Ask the agent a question')
ask_parser.add_argument('question', type=str, help='Question to ask')
ask_parser.add_argument('--model', default='gpt-4o-mini')

# 'search' subcommand
search_parser = subparsers.add_parser('search', help='Research a topic')
search_parser.add_argument('topic', type=str, help='Topic to research')
search_parser.add_argument('--depth', type=int, default=3, choices=[1, 2, 3])

args = parser.parse_args(['ask', 'What is Python?', '--model', 'gpt-4o'])
print(args.command)   # 'ask'
print(args.question)  # 'What is Python?'
print(args.model)     # 'gpt-4o'

编写良好的帮助文本

良好的帮助文本应回答三个问题：此参数的作用是什么、哪些值有效，以及默认值是什么？请从用户的角度而不是实现者的角度编写帮助文本。

import argparse

parser = argparse.ArgumentParser(
    description='AI Research Agent — answers questions using web search and LLMs.',
    epilog='Example: python agent.py --query "What is quantum computing?" --format json'
)

# Bad help text:
parser.add_argument('--t', type=float, help='t value')  # cryptic

# Good help text:
parser.add_argument(
    '--temperature',
    type=float,
    default=0.7,
    metavar='0.0-2.0',
    help='Sampling temperature for the LLM. Lower = more focused, higher = more creative. (default: 0.7)'
)

print('Good help text explains what, how, and default value')

为复杂 CLI 创建参数组

当 CLI 包含许多参数时，请使用 add_argument_group() 按主题将它们分组。这样可以让 --help 输出更易于阅读。

import argparse

parser = argparse.ArgumentParser(description='AI Agent CLI')

# Group 1: required inputs
required_group = parser.add_argument_group('Required')
required_group.add_argument('--query', required=True, help='Question to ask')

# Group 2: LLM settings
llm_group = parser.add_argument_group('LLM Settings')
llm_group.add_argument('--model', default='gpt-4o-mini', help='Model name')
llm_group.add_argument('--temperature', type=float, default=0.7)
llm_group.add_argument('--max-tokens', type=int, default=1000)

# Group 3: output settings
output_group = parser.add_argument_group('Output')
output_group.add_argument('--format', choices=['text', 'json'], default='text')
output_group.add_argument('--verbose', action='store_true')

print('Argument groups organize --help output by category')

环境变量回退值

允许参数在未提供时回退到环境变量。这样，用户无需每次都输入参数，就能在 Shell 配置文件中设置默认值。

import argparse
import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-demo-key'

parser = argparse.ArgumentParser()

parser.add_argument(
    '--api-key',
    type=str,
    default=os.environ.get('OPENAI_API_KEY'),
    help='OpenAI API key (default: $OPENAI_API_KEY env var)'
)

parser.add_argument(
    '--model',
    type=str,
    default=os.environ.get('AGENT_MODEL', 'gpt-4o-mini'),
    help='Model to use (default: $AGENT_MODEL or gpt-4o-mini)'
)

args = parser.parse_args([])

if not args.api_key:
    parser.error('--api-key is required (or set OPENAI_API_KEY environment variable)')

print(f'Model: {args.model}')

知识检查：参数解析

检查您对 CLI 参数解析技术的理解。

回顾：参数解析与帮助文本

现在，您已经了解如何构建完整且易于使用的 CLI 参数接口：

对必需参数使用 required=True，对可选参数使用 default=
使用 type= 和自定义验证函数验证输入类型
使用 choices=[...] 限制可用值
对布尔标志使用 action='store_true'
使用 metavar= 和清晰的 help= 字符串提升帮助文本的可读性
使用 nargs='+' 接收多个值
为复杂 CLI 使用子命令和参数组
对常用设置回退到环境变量

常见问题解答

「参数解析与帮助文本」课时是免费的吗？

是的 — 「参数解析与帮助文本」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。

「参数解析与帮助文本」这节课中我会学到什么？

必需参数与可选参数、类型验证和自动生成的帮助信息。你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Agents 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「参数解析与帮助文本」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Agents 课中编写并运行代码吗？

能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Agents