Skip to content

Latest commit

 

History

History
290 lines (226 loc) · 6.59 KB

PROJECT_STRUCTURE.md

File metadata and controls

290 lines (226 loc) · 6.59 KB

WediskAgent 项目结构

WediskAgent/
├── src/
│   └── main/
│       ├── java/                          # Java源代码
│       │   ├── WediskAgent.java          # AI Agent核心代码（YAML驱动）
│       │   ├── WeworkWediskAPI.java      # 基础API封装
│       │   └── WeworkWediskAdvanced.java # 高级API功能
│       └── resources/                     # 资源文件（配置等）
│
├── configs/                               # YAML配置文件目录
│   ├── README.md                         # 配置文件使用说明
│   ├── simple-config.yaml                # 简单项目配置模板
│   ├── project-config.yaml               # 完整项目配置模板
│   └── ai-project-config.yaml            # AI项目配置模板
│
├── scripts/                               # 运行脚本
│   ├── README.md                         # 脚本使用说明
│   ├── run-agent.sh                      # 单项目运行脚本
│   └── batch-create.sh                   # 批量创建脚本
│
├── docs/                                  # 文档目录
│   └── WEWORK_README.md                  # 企业微信API详细文档
│
├── target/                                # Maven编译输出（.gitignore）
│   ├── wedisk-agent.jar                  # 可执行JAR文件
│   └── ...
│
├── pom.xml                                # Maven项目配置
├── README.md                              # 项目主文档
├── QUICK_START.md                         # 快速开始指南
├── LICENSE                                # MIT许可证
├── .gitignore                             # Git忽略配置
└── PROJECT_STRUCTURE.md                   # 本文件

📂 目录说明

/src/main/java/ - 源代码目录

WediskAgent.java

  • 功能: AI Agent核心引擎
  • 特性:
    • 读取和解析YAML配置文件
    • 递归创建目录结构
    • 权限自动配置
    • 生成执行报告
  • 依赖: Gson, SnakeYAML

WeworkWediskAPI.java

  • 功能: 企业微信微盘API基础封装
  • 特性:
    • 获取access_token
    • 创建微盘空间
    • 创建文件夹
    • 多级目录创建
  • 适用: 快速开始和简单场景

WeworkWediskAdvanced.java

  • 功能: 企业微信微盘API高级功能
  • 特性:
    • 批量目录结构创建
    • 文件重命名/移动/删除
    • 文件信息查询
    • 权限管理
  • 适用: 复杂场景和高级需求

/configs/ - 配置文件目录

存放项目的YAML配置文件，支持：

  • ✅ 多层嵌套目录结构定义
  • ✅ 权限配置
  • ✅ 项目元信息
  • ✅ 注释说明

配置文件命名规范:

  • 小写字母 + 连字符
  • 描述性名称
  • 示例: bank-system-config.yaml

模板文件:

  • simple-config.yaml - 小型项目（15个目录）
  • project-config.yaml - 中大型项目（45+目录）
  • ai-project-config.yaml - AI/ML项目专用

/scripts/ - 脚本目录

提供便捷的运行脚本：

run-agent.sh

  • 单项目运行
  • 自动环境检查
  • 自动编译JAR
  • 显示执行报告

batch-create.sh

  • 批量创建多个项目
  • 统计执行结果
  • 错误汇总

/docs/ - 文档目录

技术文档和API参考：

  • 企业微信API详细说明
  • 错误码参考
  • 最佳实践

/target/ - 编译输出

Maven编译生成的文件：

  • wedisk-agent.jar - 可执行JAR文件
  • 编译的.class文件
  • 依赖库

⚠️ 此目录不应提交到Git（已在.gitignore中）

📝 核心文件说明

pom.xml

Maven项目配置文件，定义：

  • 项目坐标信息
  • 依赖管理（Gson, SnakeYAML）
  • 编译插件配置
  • 打包配置（生成可执行JAR）

README.md

项目主文档，包含：

  • 项目介绍和特性
  • 完整使用指南
  • 配置说明
  • 故障排查
  • 最佳实践
  • FAQ

QUICK_START.md

快速开始指南，适合：

  • 新用户快速上手
  • 5分钟入门教程
  • 常见场景示例

.gitignore

Git忽略规则，包括：

  • 编译输出（target/）
  • IDE配置（.idea/等）
  • 生成的报告文件
  • 敏感配置文件

LICENSE

MIT开源许可证

🔧 开发相关

添加新功能

  1. 修改Java代码

    vim src/main/java/WediskAgent.java

  2. 重新编译

    mvn clean package

  3. 测试

    ./scripts/run-agent.sh configs/simple-config.yaml

添加新配置模板

  1. 创建配置文件

    vim configs/new-template.yaml

  2. 测试配置

    ./scripts/run-agent.sh configs/new-template.yaml

  3. 更新文档

    vim configs/README.md

添加新脚本

  1. 创建脚本

    touch scripts/new-script.sh
chmod +x scripts/new-script.sh

  2. 更新脚本文档

    vim scripts/README.md

📦 打包发布

生成可执行JAR

mvn clean package

生成的文件：

  • target/wedisk-agent.jar - 带依赖的可执行JAR

发布检查清单

  • 代码编译通过
  • 测试用例通过
  • 文档更新完整
  • 配置模板验证
  • 脚本测试通过
  • CHANGELOG更新

🎯 最佳实践

代码组织

  1. 保持单一职责

    • WediskAgent.java - 只负责YAML解析和流程编排
    • WeworkWediskAPI.java - 只负责API调用
    • WeworkWediskAdvanced.java - 只负责高级功能

  2. 配置与代码分离

    • 所有项目配置在YAML文件中
    • 凭证通过环境变量传递

  3. 文档与代码同步

    • 代码变更必须更新文档
    • 配置模板必须有说明

目录规范

  1. 配置文件

    • 分类存放（按项目类型）
    • 命名规范一致
    • 注释清晰完整

  2. 脚本文件

    • 添加执行权限
    • 包含错误处理
    • 输出友好提示

  3. 文档文件

    • Markdown格式
    • 结构清晰
    • 示例丰富

🚀 扩展建议

功能扩展

  • Web UI界面
  • REST API服务
  • 配置文件可视化编辑器
  • 目录结构导出功能
  • 增量更新支持

集成扩展

  • CI/CD平台集成
  • 项目管理工具集成
  • VS Code插件
  • IDEA插件

文档扩展

  • 视频教程
  • 交互式文档
  • 多语言支持
  • API参考文档

📞 技术支持

项目结构设计原则: 简单、清晰、易于扩展和维护