软件工程第二次团队作业

这个作业属于哪个课程 https://edu.cnblogs.com/campus/fzu/202501SoftwareEngineering
这个作业要求在哪里 https://edu.cnblogs.com/campus/fzu/202501SoftwareEngineering/homework/13559
这个作业的目标 构建一个具备“能说会做”特征的智能体，例如：一个可以帮用户整理任务和生成待办清单的智能助理；一个可以查询天气并自动生成出行计划的小助手；一个能根据用户命令创建或修改文件的“AI办公助理”；或者构建一个有趣的聊天智能体，会根据对话动态执行命令（调用API、生成图片、计算结果等）。
学号姓名 组长：102301609周训博 组员：102301542 曾垚，102301231林天诺，102301527彭岳喆，102301510邹晨阳，102301638丁剑勇，102301537高舒文，102301524施汉霖，102301525邱维嘉，102301641陈怀侨,102301511郑标铭，102301539陈佳铭

本地前端 AI 智能体（Agent）说明文档

一.产品概述

本地前端 AI 智能体是一个离线静态示例应用，无需依赖外部 AI 服务，可直接在浏览器中运行。该智能体具备自然语言交互能力，能够执行多种实用操作，旨在提供"会说会做"的基础智能体验，适用于课程作业演示及本地日常工具使用场景。

二.核心功能

  1. 自然语言指令解析（基于规则）

    1. 支持中文自然语言指令识别与处理

    2. 涵盖待办管理、文件操作、计算、天气查询等场景

  2. 语音播报功能

    1. 集成浏览器 TTS（文本转语音）功能

    2. 可通过开关控制是否启用语音播报

  3. 待办项管理

    1. 添加新待办事项

    2. 标记完成待办事项

    3. 导出待办列表为 txt 文件

    4. 从 txt 文件导入待办列表

  4. 文本文件操作

    1. 根据用户指令创建并下载文本文件

    2. 支持自定义文件名和文件内容

  5. 算术计算功能

    1. 解析并计算基础算术表达式

    2. 包含安全校验机制，仅允许数字和算术符号

  6. 天气查询

    1. 集成 OpenWeatherMap API 接口

    2. 支持输入城市名查询天气

    3. 提供离线示例数据，无 API Key 也可体验

    4. 支持 API Key 本地保存与管理

  7. 出行计划建议

    1. 基于天气数据自动生成出行建议

    2. 包含穿衣、交通、活动和路线等多方面建议

三.运行环境与方式

运行环境

  • 操作系统：Windows

  • 浏览器：Chrome 或 Edge

运行方式

  1. 直接运行

    1. 将 ai-agent 文件夹完整放到本地

    2. 用 Chrome/Edge 直接打开 index.html（使用 file:// 协议）

  2. 通过本地服务器运行（推荐，避免跨域问题）

    # 在项目目录启动简单静态服务（需已安装 Python）
python -m http.server 8000
# 然后在浏览器访问 http://localhost:8000/index.html

四.使用指南

基本交互

在输入框输入指令并发送，支持的指令示例：

  • 添加待办 买牛奶

  • 完成待办 1

  • 导出待办

  • 创建文件 notes.txt 内容：这是测试

  • 计算 12*3+5

  • 查询天气 北京

  • 生成出行计划 上海

天气查询与 API Key 配置

  1. 获取 OpenWeatherMap API Key

    1. 访问 https://openweathermap.org/ 注册账号并完成邮箱验证

    2. 登录后进入 Dashboard 或 Account -> API keys 页面

    3. 创建新的 API Key 并复制生成的字符串

  2. 配置 API Key

    1. 在页面侧栏的天气查询区域，粘贴 API Key 到输入框

    2. 点击"保存 API Key"按钮，Key 将存入浏览器的 localStorage

    3. 可点击"清除 Key"按钮移除本地保存的 Key

    4. 点击"测试 Key"按钮验证 Key 是否有效

  3. 使用天气查询

    1. 输入城市名（如：北京 或 Beijing,CN）

    2. 点击"查询天气"按钮获取天气信息

    3. 可点击"示例：查询天气 北京"快速体验

出行计划生成

输入"生成出行计划 [城市名]"即可获取基于天气的出行建议，系统会自动查询该城市天气并生成包括：

  • 穿衣建议（基于体感温度）

  • 出行方式建议（基于天气和风速）

  • 活动建议（基于天气状况）

  • 路线规划建议

  • 其他贴心提示

五.功能实现说明

技术架构

  • 纯前端实现，无需后端支持

  • 文件组成：

    • index.html：UI 界面与元素定义

    • styles.css：界面样式定义

    • app.js：核心业务逻辑实现

核心模块说明

  1. 消息处理模块

    1. pushMessage(text, from='agent')：处理消息显示与语音播报

    2. speak(text)：实现浏览器 TTS 功能

  2. 待办管理模块

    1. addTodo(text)：添加待办项

    2. completeTodo(idx)：完成待办项

    3. renderTodos()：渲染待办列表

    4. exportTodosTxt()：导出待办项

    5. importTodosFromFile(file)：导入待办项

  3. 文件操作模块

    1. createFileAndDownload(name, content)：创建并下载文本文件

  4. 计算模块

    1. calcExpression(expr)：解析并计算算术表达式（包含安全校验）

  5. 指令解析模块

    1. simpleAgentHandle(text)：解析用户输入的自然语言指令并分发执行

  6. 天气查询模块

    1. fetchWeatherForCity(city)：查询指定城市天气

    2. 支持真实 API 调用与离线模拟数据

  7. 出行计划模块

    1. generateTravelPlan(city)：生成出行计划入口

    2. generateAdviceFromWeather(...)：基于天气数据生成详细出行建议

六.故障排查

  1. API Key 相关问题

    1. 401/403 错误：Key 可能无效或未激活，确认 Key 正确并尝试重新生成

    2. 429 错误：达到免费配额或请求频率限制，需等待或升级计划

  2. 网络与跨域问题

    1. 网络错误或 fetch 被阻止：确认通过 HTTP(S) 访问页面，推荐使用本地静态服务器

    2. 检查是否存在防火墙或代理阻止外部请求

  3. 城市查询问题

    1. 城市未找到：确认城市名拼写正确，可使用"City,CountryCode"格式（例如：Beijing,CN）避免歧义

七.扩展建议

  1. 接入 Model Context Protocol (MCP) 或 LangChain 前端适配器

  2. 增加多轮对话状态与意图识别能力

  3. 将待办项持久化到本地 IndexedDB

  4. 扩展更多实用工具功能

  5. 优化自然语言解析能力，支持更复杂的指令

  6. 增加多语言支持

八.注意事项

  • 本项目为离线演示智能体，不调用第三方 AI 服务

  • API Key 仅保存在浏览器的 localStorage 中，不会上传到服务器

  • 不要将真实 API Key 提交到公共仓库或共享给他人

  • 在 file:// 协议下，某些浏览器可能因安全策略限制部分功能，推荐使用本地服务器运行

九.使用示例（功能演示）

409cd57e306f710592b14ee21c54c996

十.GitHub 链接

https://github.com/XunBo2023/cuddly-umbrella/tree/main/ai-agent

十一.小组分工

周训博（组长）：

统筹安排

彭岳喆，曾垚，邹晨阳：

使用浏览器的 Web Speech API 做文本转语音（TTS），并加入语音开关。

丁剑勇，高舒文，施汉霖：

实现自然语言规则解析，支持添加/完成/导出/导入待办、创建并下载文本文件、计算表达式（带安全校验）。

林天诺：

集成天气能力并拓展为“出行小助手”，支持使用 OpenWeatherMap（可选 API Key 存入 localStorage）。增加了 API Key 的保存/清除/测试按钮与友好错误提示（处理 401/403/404/429、CORS/网络问题）。在天气结果的基础上，自动生成出行建议（穿衣、交通、活动、路线、贴心提醒），并能通过 TTS 朗读。同时完成博客编写

邱维嘉，陈怀侨，郑标铭，陈佳铭:

编写了使用说明与规范文档：README.md（包含获取 Key、运行方式、故障排查）和 AGENT_SPEC.md（需求、业务流、实现说明、扩展建议）。

十二.心得体会

周训博（组长）

这次作业把一个“会说会做”的前端智能体从零搭建完成，涵盖对话 UI、浏览器 TTS、规则化命令解析、待办管理、文件生成、OpenWeatherMap 集成以及基于天气的出行计划生成。实现过程中练习了对外部 API 的鲁棒性处理（401/403/404/429、CORS）、localStorage 的 Key 管理与安全提醒，并设计了友好的错误提示与降级方案（无 Key 时的模拟数据）。撰写 README 与规范文档帮助团队复现与维护。总体收获是：工程实现要兼顾可用性与可扩展性，清晰的用户引导与错误诊断比单纯功能更能提升体验。

彭岳喆

在项目中接入浏览器的 Web Speech API（SpeechSynthesis）实现 TTS，开发过程很直接：创建 SpeechSynthesisUtterance、设置 lang、rate、pitch，再调用 speechSynthesis.speak()。需要注意兼容性检查（if ('speechSynthesis' in window））以及在发声前先调用 speechSynthesis.cancel() 避免重叠播放。不同浏览器和设备上可用的 voice 列表差异较大，导致发音风格不可控；同时监听 utterance 的 end/error 事件有助于管理 UI 状态（例如禁用播放按钮）。总体上，Web Speech API 非常适合做快速原型，能在纯前端环境下无需后端就实现“会说”能力。

曾垚

为保证良好体验，我们为 TTS 加入了显式的“语音开关”，并在 agent 回复触发时仅在开关开启状态下播放，避免自动打扰。还要注意不要在页面加载时自动播放语音以免被浏览器阻止或打断用户操作；在移动端和无声环境下应提供静音或文本替代。隐私方面，Web Speech API 在本地运行，不会把用户文本上传（浏览器厂商实现例外），比云端 TTS 更安全，但仍应在 README 提醒用户不要把敏感内容交由前端发声并避免在公共场合自动播放。对用户而言，提供音量、语速、语调调节和可选语音选择能显著提升可访问性。

邹晨阳

现有实现适合演示与本地使用，后续可以逐步增强：一是允许用户选择具体 voice（若浏览器支持），并保存偏好到 localStorage；二是增加 rate/pitch 控件与语言自动检测，提升多语言支持；三是实现更精细的播放队列管理（支持打断、排队、优先级），避免长文本阻塞界面；四是在需要更高质量发音时，提供可选的云端 TTS 后备（带开关与 Key 管理）；五是为 TTS 添加单元/集成测试（使用 headless 浏览器模拟播放事件），并把发音失败时的降级流程做得更明确。总体目标是兼顾易用性、可访问性与隐私安全，让“会说”能力既自然又可控。

丁剑勇

实现基于规则的自然语言解析时，我把重点放在可读性与可扩展性上。用正则表达式分支匹配常见命令（如“添加待办 XXX”“完成待办 1”“创建文件 name 内容：...”“计算 1+2”），简单直接且易于调试。关键技巧是编写尽量宽松但有界的模式：允许中文/英文关键词和可选参数，同时用捕获组明确提取主体内容。为计算表达式加了字符白名单（仅允许数字、空白与算术符号）以防注入执行；文件下载用 Blob + a.download 做降级兼容。遇到多义或未匹配情形时返回友好提示，便于用户修正输入或扩展新规则。

高舒文

面向最终用户时，稳健性比“识别率”更重要。解析器应对无效输入提供明确反馈：告诉用户缺少目标词或者示例格式，而不是简单报错。对于待办导入/导出，保持格式兼容（支持有无序号的纯文本行）能大幅降低用户困惑。实现上将操作视为不可逆或有风险时（例如覆盖文件或删除全部待办）加入确认提示。TTS 配合文本反馈可以提升可访问性，但需保证在语音被阻止或用户关闭时仍能以文本完成交互。最后，综合日志（控制台）用于开发阶段诊断，生产环境则应少曝露内部错误信息。

施汉霖

规则解析适合工程化快速交付，但面对复杂指令时需更强的语义理解，因此下一步可接入轻量 NLU 或 LLM 做意图分类与参数抽取，同时保留规则作为回退与安全过滤层。建议把命令解析做成可配置的规则表（JSON），方便增删规则并支持多语言。为提升安全性，计算模块可用沙箱式评估器替代 Function 执行，并记录计算历史以便审计。最后，把待办和文件操作持久化（IndexedDB/localStorage）并加入导出历史与版本控制，会让该智能体更像一个可靠的办公助理。

林天诺

在本项目中集成 OpenWeatherMap 并把天气查询扩展为出行小助手，是一次从工程实现到用户体验全面考虑的练习。实现上，我选择把天气查询放在前端完成：页面提供“可选 API Key”输入并使用 localStorage 保存。这种做法保证了演示的便捷性——用户无需后端即可使用真实数据，同时通过“保存/清除/测试 Key”三按钮，让用户自主管理凭证，并在出现 401/403/429 等常见错误时给出明确的操作建议。为提高鲁棒性，fetch 请求对不同 HTTP 状态做了区分：404 会提示“城市未找到，请尝试英文名或 City,CountryCode”；401/403 提示检查或重建 Key；429 提示配额问题；网络或 CORS 问题则建议使用本地静态服务器。若无 Key 或网络受限，系统还能返回模拟天气，保证功能链不会完全中断，提供可接受的降级体验。

出行建议模块基于天气要素（描述字符串、温度、体感温度、风速）生成多维建议：穿衣、交通方式、活动类型与路线提醒。实现策略是把规则写清晰且可扩展，例如低体感温度建议厚外套，降雨时建议公共交通并带伞，高温时提醒防晒与补水等。为了提升可访问性，所有建议既以文本输出，也可通过浏览器 Web Speech API 做 TTS 播报，并提供语音开关避免打扰。

过程中遇到的主要挑战包括城市名匹配（中文名易返回 404）、浏览器 CORS 限制以及不同浏览器对 TTS 支持差异。针对这些问题，我在 UI 和文档里加入了明确引导（如建议使用英文名或国家码、如何启动本地服务器、如何测试 Key 等），并在代码中保留可扩展点（后续可加入地理编码回退、7天预报、地图路线 API）。

总体收获很实在：一是学会在前端做稳健的第三方 API 集成，如何把错误信息转化为用户可操作的建议；二是理解“会说会做”智能体不仅要能执行，还要把执行结果以用户友好的形式呈现并提供降级方案；三是认识到隐私与安全的现实限制（Key 管理、不要明文提交凭证）。接下来我计划实现地理编码回退与持久化待办，使小助手更智能、更耐用。

邱维嘉

编写 README 与规范文档的首要目标是让读者“马上能跑起来并理解系统设计”。为此我把说明拆成几部分：快速上手（如何打开页面／启动本地服务器）、API Key 获取与保存、核心功能示例、常见故障与排查步骤、以及扩展建议。写文档时注重示例驱动：比如给出 OpenWeatherMap 申请 Key 的逐步截图式说明、示例 URL、以及在侧栏保存 Key 的操作流程，降低新用户门槛。规范文档则偏重契约化描述（输入/输出、数据形状、错误模式），便于同组成员或后续维护者快速定位代码入口与扩展点。总体经验是：短小清晰的步骤和可复制的命令远比长篇大论更有价值。

陈怀侨

面向非技术用户时，README 的可读性决定了工具的传播力。为保证可用性，我在文档中加入了三类友好设计：一是“零配置快速运行”路径（直接双击 index.html 的说明与限制警告）；二是“稳健运行”路径（推荐通过本地静态服务器启动并给出一键命令）；三是交互示例（常见自然语言指令与期望输出）。此外，将故障排查放在显眼位置并给出逐步诊断（如何用“测试 Key”按钮、如何查看浏览器控制台、如何识别 401/403/429/404）能显著减少初学者的迷茫。实践告诉我，文档应尽量把复杂操作拆成“看得懂的下一步”，并配合屏幕提示和 UI 状态同步。

郑标铭

在实现外部 API 集成时，故障比功能更常见，因此把“诊断信息”写进文档尤为关键。我在 README 中列出了常见错误码的含义与对应动作（401/403：检查或重置 Key；404：尝试英文名或 City,CountryCode；429：配额限制；Network/CORS：用本地服务器）。同时建议用户收集两类证据：侧栏 weatherStatus 的错误摘要与浏览器 Network 面板中对应请求的 Response Body。文档中还强调了隐私与安全（Key 不入仓库），并提供了清除 Key 的步骤。经验是：清楚告诉用户“去哪里看错”和“看到某错误做什么”胜过笼统的错误说明。

陈佳铭

写 AGENT_SPEC.md 的过程促使我把实现模块化并契约化：明确每个函数（如 fetchWeatherForCity、generateTravelPlan）的输入/输出与错误模式，使后续扩展（地理编码回退、本地持久化、接入 LLM）更可控。文档里列出的测试策略（手动用例与用 Puppeteer 的自动化建议）为代码质量保驾护航。后续改进建议也写入规范：把命令解析做成可配置规则表、在关键路径加入单元与集成测试、以及为重要功能添加审计日志。总体体会是：规范文档不是形式，而是减少沟通成本、加速迭代的重要资产。

posted @ 2025-10-23 21:39  woshangzaoba  阅读(38)  评论(0)    收藏  举报