PythonLearn/01_python基础/1_14_python基础综合项目

第 1-14 课：Python 基础综合项目

一、项目名称

命令行 Agent 管理系统。

命令行程序是直接在终端中运行和操作的程序。本项目不会创建网页界面，而是通过数字菜单接收用户选择。

二、为什么要做综合项目

前面的课程分别学习了变量、条件判断、循环、数据结构和函数。单独完成一道小题，只需要使用其中一个知识点；真实程序通常需要把多个知识点组合起来。

本项目用于检验你能否：

1. 把一个较大的需求拆分成多个小功能；
2. 选择合适的数据结构保存信息；
3. 使用函数组织重复逻辑；
4. 使用循环让菜单持续运行；
5. 使用条件判断处理不同操作；
6. 对用户输入进行基本检查；
7. 独立完成一个可以反复操作的命令行程序。

三、前置知识

开始前应当掌握：

• print() 和 input()；
• 字符串、整数和布尔值；
• 比较运算与逻辑运算；
• if...elif...else；
• for 和 while 循环；
• 列表、字典和集合；
• 函数、参数和返回值；
• *args 和 **kwargs 的基本含义。

本项目主要使用普通参数，不会为了展示高级语法而强行使用 *args 或 **kwargs。

四、项目最终功能

程序启动后显示以下菜单：

==============================
命令行 Agent 管理系统
1. 查看全部 Agent
2. 新增 Agent
3. 修改 Agent 状态
4. 删除 Agent
5. 查看 Agent 工具
0. 退出程序
==============================

用户输入菜单编号后，程序执行对应功能：

• 输入 1：查看全部 Agent；
• 输入 2：新增 Agent；
• 输入 3：启用或停用 Agent；
• 输入 4：删除 Agent；
• 输入 5：查看指定 Agent 的工具；
• 输入 0：结束程序；
• 输入其他内容：显示“无效选项，请重新输入。”。

五、数据结构设计

所有 Agent 使用列表保存：

agents = [
    {
        "name": "代码助手",
        "model": "gpt-5",
        "enabled": True,
        "tools": ["搜索", "终端"],
    },
    {
        "name": "聊天助手",
        "model": "o3",
        "enabled": False,
        "tools": ["搜索"],
    },
]

选择这种结构的原因：

• 列表适合保存数量可以增加或减少的多条 Agent 记录；
• 每个 Agent 有多个不同含义的字段，适合使用字典；
• tools 是一组可以按顺序展示的工具，适合使用列表。

六、程序功能拆分

不要把所有代码都写进一个 while 循环。项目应拆分为以下函数。

6.1 print_menu()

职责：输出操作菜单。

• 参数：无；
• 返回值：无；
• 主要操作：使用多条 print() 输出菜单。

6.2 print_agents(agents)

职责：输出全部 Agent。

• 参数：Agent 列表；
• 返回值：无；
• 空列表时输出“当前没有 Agent。”；
• 非空时输出每个 Agent 的编号、名称、模型和状态。

预期格式：

1. 代码助手｜模型：gpt-5｜状态：启用
2. 聊天助手｜模型：o3｜状态：停用

6.3 find_agent_by_name(agents, name)

职责：按名称查找 Agent。

• 参数：Agent 列表和需要查找的名称；
• 找到时：返回对应的 Agent 字典；
• 未找到时：返回 None；
• 本函数只负责查找，不负责输出提示。

6.4 add_agent(agents)

职责：接收输入并新增 Agent。

执行顺序：

1. 输入 Agent 名称，并使用 strip() 清理两侧空白；
2. 名称为空时输出“Agent 名称不能为空。”并结束本次操作；
3. 调用 find_agent_by_name() 检查名称是否重复；
4. 名称重复时输出“该 Agent 已存在。”并结束本次操作；
5. 输入模型名称；
6. 输入工具，多个工具使用英文逗号分隔；
7. 使用 split(",") 拆分工具；
8. 清理每个工具两侧空白，并去掉空字符串；
9. 创建 Agent 字典，新 Agent 默认启用；
10. 使用 append() 加入列表并输出成功提示。

例如输入：

Agent 名称：搜索助手
模型名称：gpt-5
工具：搜索,网页浏览

新增后的字典应为：

{
    "name": "搜索助手",
    "model": "gpt-5",
    "enabled": True,
    "tools": ["搜索", "网页浏览"],
}

6.5 change_agent_status(agents)

职责：修改指定 Agent 的启用状态。

执行顺序：

1. 输入 Agent 名称；
2. 调用 find_agent_by_name() 查找；
3. 未找到时输出“未找到该 Agent。”；
4. 找到时使用 not 反转 enabled；
5. 输出修改后的中文状态。

6.6 delete_agent(agents)

职责：删除指定 Agent。

执行顺序：

1. 输入 Agent 名称；
2. 调用 find_agent_by_name() 查找；
3. 未找到时输出“未找到该 Agent。”；
4. 找到时使用 remove() 删除整个 Agent 字典；
5. 输出“Agent 已删除。”。

6.7 print_agent_tools(agents)

职责：输出指定 Agent 的工具。

• 未找到 Agent 时输出“未找到该 Agent。”；
• 工具列表为空时输出“该 Agent 暂无工具。”；
• 有工具时按编号逐行输出。

预期格式：

代码助手的工具：
1. 搜索
2. 终端

6.8 main()

职责：组织程序主流程。

执行顺序：

1. 创建初始 Agent 列表；
2. 使用 while True 持续显示菜单；
3. 使用 input() 接收菜单选项；
4. 使用 if...elif...else 分发功能；
5. 用户输入 0 时输出结束提示并使用 break 退出循环。

七、完整示例

示例文件：

01_python基础/1_14_python基础综合项目/agent_manager.py

示例是完整可运行版本。建议先阅读讲义，再运行示例了解程序行为，最后关闭示例文件，独立完成 practice.py。

八、运行方法

在项目根目录执行示例：

python .\01_python基础\1_14_python基础综合项目\agent_manager.py

运行自己的项目练习：

python .\01_python基础\1_14_python基础综合项目\practice.py

程序等待输入时，在终端输入菜单编号并按回车。

九、建议开发顺序

不要一次写完整个项目。按照以下顺序逐步完成并运行：

1. 定义初始 Agent 列表；
2. 完成并测试 print_menu()；
3. 完成并测试 print_agents()；
4. 完成并测试 find_agent_by_name()；
5. 完成新增功能；
6. 完成状态修改功能；
7. 完成删除功能；
8. 完成工具查看功能；
9. 最后编写 main() 菜单循环；
10. 按验收用例完整测试。

每完成一个函数就运行一次，可以更早发现问题。

十、验收测试

测试一：查看初始数据

操作：输入 1。

预期：显示代码助手和聊天助手，状态分别为启用和停用。

测试二：新增 Agent

操作：

输入菜单：2
名称：搜索助手
模型：gpt-5
工具：搜索,网页浏览

再次输入 1，预期显示三条 Agent 数据。

测试三：拒绝重复名称

再次新增“搜索助手”，预期输出“该 Agent 已存在。”，列表数量不增加。

测试四：修改状态

输入 3 并选择“聊天助手”，预期状态由停用变为启用。

测试五：查看工具

输入 5 并选择“代码助手”，预期依次显示“搜索”和“终端”。

测试六：删除 Agent

输入 4 并删除“聊天助手”，再次查看列表时不再显示它。

测试七：无效名称

查询、修改或删除一个不存在的名称，程序应显示提示且不崩溃。

测试八：无效菜单

输入 9 或任意未知内容，预期输出“无效选项，请重新输入。”，随后继续显示菜单。

测试九：退出程序

输入 0，预期输出“程序已退出。”并正常结束。

十一、常见错误

11.1 在函数内部重新创建列表

功能函数应修改 main() 传入的同一个列表。不要在 add_agent() 中重新创建一个无关列表。

11.2 查找失败后仍继续操作

如果 Agent 不存在，应使用提前返回结束函数，否则继续读取字典可能产生错误。

11.3 把布尔值保存为字符串

启用状态应使用 True 或 False，不要使用字符串 "True" 或 "False"。

11.4 忘记清理用户输入

名称和工具建议使用 strip()，否则多余空格可能导致名称匹配失败。

11.5 菜单无法退出

处理选项 0 时必须执行 break，否则 while True 会继续运行。

11.6 在导入文件时自动启动程序

示例最后使用：

if __name__ == "__main__":
    main()

这是程序入口判断。本课先理解为：“直接运行当前文件时才调用 main()”。模块与包课程会进一步解释。

十二、项目小结

完成本项目后，你已经把前 13 课的知识组合成了一个完整程序：

• 字符串保存名称和模型；
• 布尔值保存启用状态；
• 列表保存多条记录和工具；
• 字典表示单个 Agent；
• 集合思想用于理解工具去重；
• 条件判断分发菜单操作；
• 循环维持程序运行并遍历数据；
• 函数拆分不同业务功能；
• 返回值传递查找结果。

十三、完成标准

• 所有菜单选项均能正常执行；
• 可以新增、查看、修改和删除 Agent；
• 可以查看指定 Agent 的工具；
• 重复名称不会被新增；
• 无效输入不会导致程序崩溃；
• 输入 0 可以正常退出；
• 每个函数只承担一个清晰职责；
• 变量名和函数名使用规范英文蛇形命名；
• 代码包含必要的中文注释；
• 九组验收测试全部通过。