feat(python基础): 完成基础综合项目

01_python基础/1_14_python基础综合项目/README.md

@@ -0,0 +1,366 @@
+# 第 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` 可以正常退出；
+- 每个函数只承担一个清晰职责；
+- 变量名和函数名使用规范英文蛇形命名；
+- 代码包含必要的中文注释；
+- 九组验收测试全部通过。