367 lines
9.5 KiB
Markdown
367 lines
9.5 KiB
Markdown
# 第 1-14 课：Python 基础综合项目
|
||
|
||
## 一、项目名称
|
||
|
||
命令行 Agent 管理系统。
|
||
|
||
命令行程序是直接在终端中运行和操作的程序。本项目不会创建网页界面，而是通过数字菜单接收用户选择。
|
||
|
||
## 二、为什么要做综合项目
|
||
|
||
前面的课程分别学习了变量、条件判断、循环、数据结构和函数。单独完成一道小题，只需要使用其中一个知识点；真实程序通常需要把多个知识点组合起来。
|
||
|
||
本项目用于检验你能否：
|
||
|
||
1. 把一个较大的需求拆分成多个小功能；
|
||
2. 选择合适的数据结构保存信息；
|
||
3. 使用函数组织重复逻辑；
|
||
4. 使用循环让菜单持续运行；
|
||
5. 使用条件判断处理不同操作；
|
||
6. 对用户输入进行基本检查；
|
||
7. 独立完成一个可以反复操作的命令行程序。
|
||
|
||
## 三、前置知识
|
||
|
||
开始前应当掌握：
|
||
|
||
- `print()` 和 `input()`；
|
||
- 字符串、整数和布尔值；
|
||
- 比较运算与逻辑运算；
|
||
- `if...elif...else`；
|
||
- `for` 和 `while` 循环；
|
||
- 列表、字典和集合；
|
||
- 函数、参数和返回值；
|
||
- `*args` 和 `**kwargs` 的基本含义。
|
||
|
||
本项目主要使用普通参数，不会为了展示高级语法而强行使用 `*args` 或 `**kwargs`。
|
||
|
||
## 四、项目最终功能
|
||
|
||
程序启动后显示以下菜单：
|
||
|
||
```text
|
||
==============================
|
||
命令行 Agent 管理系统
|
||
1. 查看全部 Agent
|
||
2. 新增 Agent
|
||
3. 修改 Agent 状态
|
||
4. 删除 Agent
|
||
5. 查看 Agent 工具
|
||
0. 退出程序
|
||
==============================
|
||
```
|
||
|
||
用户输入菜单编号后，程序执行对应功能：
|
||
|
||
- 输入 `1`：查看全部 Agent；
|
||
- 输入 `2`：新增 Agent；
|
||
- 输入 `3`：启用或停用 Agent；
|
||
- 输入 `4`：删除 Agent；
|
||
- 输入 `5`：查看指定 Agent 的工具；
|
||
- 输入 `0`：结束程序；
|
||
- 输入其他内容：显示“无效选项，请重新输入。”。
|
||
|
||
## 五、数据结构设计
|
||
|
||
所有 Agent 使用列表保存：
|
||
|
||
```python
|
||
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 的编号、名称、模型和状态。
|
||
|
||
预期格式：
|
||
|
||
```text
|
||
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()` 加入列表并输出成功提示。
|
||
|
||
例如输入：
|
||
|
||
```text
|
||
Agent 名称：搜索助手
|
||
模型名称：gpt-5
|
||
工具：搜索,网页浏览
|
||
```
|
||
|
||
新增后的字典应为：
|
||
|
||
```python
|
||
{
|
||
"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 暂无工具。”；
|
||
- 有工具时按编号逐行输出。
|
||
|
||
预期格式：
|
||
|
||
```text
|
||
代码助手的工具：
|
||
1. 搜索
|
||
2. 终端
|
||
```
|
||
|
||
### 6.8 `main()`
|
||
|
||
职责：组织程序主流程。
|
||
|
||
执行顺序：
|
||
|
||
1. 创建初始 Agent 列表；
|
||
2. 使用 `while True` 持续显示菜单；
|
||
3. 使用 `input()` 接收菜单选项；
|
||
4. 使用 `if...elif...else` 分发功能；
|
||
5. 用户输入 `0` 时输出结束提示并使用 `break` 退出循环。
|
||
|
||
## 七、完整示例
|
||
|
||
示例文件：
|
||
|
||
```text
|
||
01_python基础/1_14_python基础综合项目/agent_manager.py
|
||
```
|
||
|
||
示例是完整可运行版本。建议先阅读讲义，再运行示例了解程序行为，最后关闭示例文件，独立完成 `practice.py`。
|
||
|
||
## 八、运行方法
|
||
|
||
在项目根目录执行示例：
|
||
|
||
```powershell
|
||
python .\01_python基础\1_14_python基础综合项目\agent_manager.py
|
||
```
|
||
|
||
运行自己的项目练习：
|
||
|
||
```powershell
|
||
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
|
||
|
||
操作：
|
||
|
||
```text
|
||
输入菜单：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 在导入文件时自动启动程序
|
||
|
||
示例最后使用：
|
||
|
||
```python
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
|
||
这是程序入口判断。本课先理解为：“直接运行当前文件时才调用 `main()`”。模块与包课程会进一步解释。
|
||
|
||
## 十二、项目小结
|
||
|
||
完成本项目后，你已经把前 13 课的知识组合成了一个完整程序：
|
||
|
||
- 字符串保存名称和模型；
|
||
- 布尔值保存启用状态；
|
||
- 列表保存多条记录和工具；
|
||
- 字典表示单个 Agent；
|
||
- 集合思想用于理解工具去重；
|
||
- 条件判断分发菜单操作；
|
||
- 循环维持程序运行并遍历数据；
|
||
- 函数拆分不同业务功能；
|
||
- 返回值传递查找结果。
|
||
|
||
## 十三、完成标准
|
||
|
||
- 所有菜单选项均能正常执行；
|
||
- 可以新增、查看、修改和删除 Agent；
|
||
- 可以查看指定 Agent 的工具；
|
||
- 重复名称不会被新增；
|
||
- 无效输入不会导致程序崩溃；
|
||
- 输入 `0` 可以正常退出；
|
||
- 每个函数只承担一个清晰职责；
|
||
- 变量名和函数名使用规范英文蛇形命名；
|
||
- 代码包含必要的中文注释；
|
||
- 九组验收测试全部通过。
|