AI 智能体综合实训项目仓库

本仓库是《AI 智能体综合实训》的统一项目仓库，用于完成 4 周主线项目：

基于知识图谱的物联网设备故障诊断智能体平台

项目从选题、可行性分析和需求分析开始，逐步完成系统架构、知识图谱、智能体、前后端、测试、部署和版本发布。

仓库地址

https://www.gitlink.org.cn/gzkoala/ai-engineering-demo

分支说明

分支	用途	维护者
master	课程 Demo 参考版本、公共脚手架和示例	课程导师
group-01	第 1 组项目成果	第 1 组
group-02	第 2 组项目成果	第 2 组
group-03	第 3 组项目成果	第 3 组

实际分支名称以教师公布的分组表为准。

• 学生只能提交到本组分支，不得修改其他小组分支。
• 学生不得直接提交到 master。
• master 由课程导师维护，作为课程 Demo 参考版本。
• 各小组的代码、文档、Issue、运行证据和 Release 均归档在本组分支。

快速开始

将 group-XX 替换为本组分支名称：

git clone https://www.gitlink.org.cn/gzkoala/ai-engineering-demo.git
cd ai-engineering-demo
git fetch origin
git switch --track origin/group-XX

开始开发前请确认：

1. 已切换到本组分支。
2. 已阅读 syllabus/project_management_guide.md。
3. 已阅读当前周的 syllabus/weekX_todo.md。
4. 已创建或认领对应的 GitLink Issue。
5. 已配置本地 .env，且 .env 未被提交。

推荐目录

project-root/
├── docs/
│   ├── project/       # 选题、可行性、项目章程、需求分析
│   ├── architecture/ # 总体架构、详细架构、功能设计
│   ├── development/  # 模块设计、接口契约、联调说明
│   ├── testing/      # 测试计划、测试报告、缺陷记录
│   ├── deployment/    # 部署运维、用户使用说明
│   └── release/      # 发布说明、验收报告、项目复盘
├── src/               # 源代码
├── tests/             # 自动化测试
├── data/              # 脱敏后的样例数据
├── evidence/          # 截图、测试输出、演示证据
├── README.md
├── requirements.txt
├── .env.example
└── CHANGELOG.md

4 周项目路线

周次	里程碑	主要成果
第 1 周	M1 知识图谱底座	立项文档、需求分析、总体架构初版、Schema、图谱、检索服务
第 2 周	M2 单智能体问答	智能体模块、Tool、接口、测试计划和集成测试报告
第 3 周	M3 多智能体协同	详细架构、四角色功能设计、容错设计、服务化接口、CI
第 4 周	M4 全栈系统发布	前端、联调、部署运维、软件测试、版本发布和项目验收

详细安排见：

• syllabus/week1_todo.md
• syllabus/week2_todo.md
• syllabus/week3_todo.md
• syllabus/week4_todo.md
• syllabus/project_management_guide.md

项目文档产出

项目文档随项目进度持续更新，不提交个人学习日志。

立项与需求

• 《项目选题登记表》
• 《项目可行性分析报告》
• 《项目章程》
• 《项目需求分析说明书》

架构与设计

• 《系统总体架构设计说明书（初版）》
• 《系统架构设计说明书（详细版）》
• 《系统功能设计说明书》
• 《知识图谱 Schema 设计说明书》
• 《智能体模块设计说明书》
• 《接口设计说明书》
• 《异常处理与容错设计说明》

开发、测试与交付

• 《图谱数据导入与质量报告》
• 《检索服务接口契约》
• 《前端功能开发说明》
• 《前后端联调说明书》
• 《软件测试计划》
• 《软件测试报告》
• 《部署与运维说明书》
• 《软件版本发布说明》
• 《项目验收报告》
• 《项目总结与复盘报告》

每日项目流程

上午站会
  → 认领 Issue
  → 课中开发与文档编写
  → Commit 提交
  → 组内 Review
  → 下午日报
  → 教师检查与问题跟踪

每天由项目经理在 GitLink 发布一条日报，至少包括：今日完成事项、对应 Issue/Commit/文档路径、运行或测试证据、未完成事项、风险和阻塞问题、明日计划。

日报格式见 syllabus/project_management_guide.md。

Issue、Commit 与 Review

每项任务或问题都应创建 Issue，并注明负责人、截止时间、输出物和验收标准。

推荐标题：

[G02][W1-D1][DOC] 完成项目可行性分析报告
[G02][W2-D3][TEST] 执行智能体集成测试
[G02][BUG] 修复诊断结果缺少证据字段

推荐 Commit 类型：

feat: 完成故障检索函数
docs: 补充项目可行性分析
test: 增加诊断链路边界测试
fix: 修复 Neo4j 查询参数问题

每次提交至少由 1 名组员检查。Review 可通过 GitLink Issue 评论、Commit 评论或 PR 留痕。

每周里程碑与版本

每周第 5 天进行阶段汇报：项目经理汇报进度，架构负责人说明设计，开发成员演示功能，测试负责人汇报质量和缺陷，最后由教师进行里程碑验收。

验收通过后，在对应小组分支创建版本 Tag 或 Release：

group-02-m1
group-02-m2
group-02-m3
group-02-v1.0.0

安全要求

• 真实 API Key、数据库密码和个人信息不得提交。
• .env 必须加入 .gitignore，只提交 .env.example。
• 截图、录屏和测试数据必须脱敏。
• 发现密钥泄露时，应立即撤销并重新生成。
• 外部代码、数据集、图片和文档必须记录来源与许可证。

最终交付标准

最终版本应包含可运行源代码、完整项目文档、README.md、.env.example、依赖清单、部署说明、自动化测试、软件测试报告、版本发布说明、项目验收报告和演示记录。

项目最终评价不仅看“程序能否运行”，还看项目是否可理解、可复现、可测试、可交接和可继续迭代。