agv/agv-control-slam
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

项目结构调整

Browse Source
This commit is contained in:
CaiXiang
2025-11-15 14:31:47 +08:00
parent a77ae6fac1
commit ec1d6f0cee
12 changed files with 2242 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
.claude/file_organization.json Normal file
View File

@@ -0,0 +1,173 @@
{
"description": "文件组织和归档配置 - 定义了代码和文档的自动归类规则",
"version": "1.0.0",
"last_updated": "2025-11-15",
"directories": {
"archives": {
"bug_fixes": {
"path": "archives/bug_fixes",
"pattern": "{date}_{bug_name}",
"subdirs": ["code", "docs", "tests"],
"description": "Bug修复归档目录"
},
"updates": {
"path": "archives/updates",
"pattern": "{date}_{feature_name}",
"subdirs": ["code", "docs", "tests"],
"description": "功能更新归档目录"
},
"versions": {
"path": "archives/versions",
"pattern": "v{major}.{minor}.{patch}",
"subdirs": ["backup"],
"description": "版本归档目录"
}
},
"docs": {
"fixes": {
"path": "docs/fixes",
"description": "Bug修复文档（当前活跃）"
},
"updates": {
"path": "docs/updates",
"description": "功能更新文档（当前活跃）"
},
"guides": {
"path": "docs/guides",
"description": "使用指南和教程"
},
"protocol": {
"path": "docs/protocol",
"description": "通信协议文档"
}
},
"source": {
"src": {
"path": "src",
"description": "源代码主目录"
},
"include": {
"path": "include",
"description": "头文件目录"
},
"examples": {
"path": "examples",
"description": "示例代码"
}
}
},
"file_types": {
"code": {
"extensions": [".cpp", ".c", ".h", ".hpp", ".py"],
"default_location": "src",
"description": "代码文件"
},
"headers": {
"extensions": [".h", ".hpp"],
"default_location": "include",
"description": "头文件"
},
"docs": {
"extensions": [".md", ".txt", ".pdf"],
"default_location": "docs",
"description": "文档文件"
},
"configs": {
"extensions": [".json", ".yaml", ".yml", ".ini", ".conf"],
"default_location": ".",
"description": "配置文件"
}
},
"naming_conventions": {
"bug_fix": {
"folder": "{YYYYMMDD}_{bug_description}",
"doc": "BUG_{bug_description}_{YYYYMMDD}.md",
"example": "20251115_fix_path_tracking / BUG_path_tracking_20251115.md"
},
"feature_update": {
"folder": "{YYYYMMDD}_{feature_name}",
"doc": "UPDATE_{feature_name}_{YYYYMMDD}.md",
"example": "20251115_adaptive_lookahead / UPDATE_adaptive_lookahead_20251115.md"
},
"version": {
"folder": "v{major}.{minor}.{patch}",
"doc": "release_notes.md",
"example": "v1.2.0 / release_notes.md"
}
},
"workflow_rules": {
"bug_fix": {
"steps": [
"1. 在主代码目录 (src/, include/) 进行修复",
"2. 提交 git commit",
"3. 创建归档目录: archives/bug_fixes/{date}_{name}/{code,docs,tests}",
"4. 复制修复的代码到归档目录",
"5. 创建修复文档到归档目录",
"6. 复制文档副本到 docs/fixes/ 供快速查阅"
],
"archive_to": "archives/bug_fixes",
"doc_copy_to": "docs/fixes"
},
"feature_update": {
"steps": [
"1. 在主代码目录 (src/, include/) 开发新功能",
"2. 提交 git commit",
"3. 创建归档目录: archives/updates/{date}_{name}/{code,docs,tests}",
"4. 复制新增/修改的代码到归档目录",
"5. 创建更新文档到归档目录",
"6. 复制文档副本到 docs/updates/ 供快速查阅"
],
"archive_to": "archives/updates",
"doc_copy_to": "docs/updates"
},
"version_release": {
"steps": [
"1. 更新版本号",
"2. 编写 release_notes.md",
"3. 创建版本目录: archives/versions/vX.Y.Z/",
"4. 可选：备份完整代码到 backup/ 子目录",
"5. 创建 git tag"
],
"archive_to": "archives/versions"
}
},
"auto_categorization_rules": {
"enabled": true,
"rules": [
{
"type": "bug_fix",
"trigger_keywords": ["bug", "fix", "修复", "错误", "问题"],
"target_dir": "archives/bug_fixes",
"doc_dir": "docs/fixes"
},
{
"type": "feature",
"trigger_keywords": ["feature", "update", "新增", "功能", "更新", "add", "implement"],
"target_dir": "archives/updates",
"doc_dir": "docs/updates"
},
{
"type": "version",
"trigger_keywords": ["version", "release", "版本", "发布"],
"target_dir": "archives/versions"
}
]
},
"templates": {
"bug_fix_doc": ".claude/templates/bug_fix_template.md",
"feature_update_doc": ".claude/templates/feature_update_template.md",
"release_notes": ".claude/templates/release_notes_template.md"
},
"scripts": {
"archive_bug_fix": "scripts/archive_bug_fix.sh",
"archive_feature": "scripts/archive_feature.sh",
"create_release": "scripts/create_release.sh"
}
}

5
.claude/settings.local.json
View File

@@ -5,7 +5,10 @@
"Bash(head:*)",
"Bash(echo:*)",
"Bash(test:*)",
"Bash(test -f:*)"
"Bash(test -f:*)",
"Bash(mkdir:*)",
"Bash(chmod:*)",
"Bash(./scripts/archive_bug_fix.sh:*)"
],
"deny": [],
"ask": []

87
.claude/templates/bug_fix_template.md Normal file
View File

@@ -0,0 +1,87 @@
# Bug修复: {{BUG_DESCRIPTION}}
**日期**: {{DATE}}
**修复者**: {{AUTHOR}}
**相关Issue**: #{{ISSUE_NUMBER}}（如有）
**Git Commit**: {{COMMIT_HASH}}
---
## Bug描述
{{详细描述bug的表现，包括错误信息、异常行为等}}
## 复现步骤
1. {{步骤1}}
2. {{步骤2}}
3. {{步骤3}}
4. **观察到的错误行为**: {{描述错误}}
## 根本原因
{{分析bug的根本原因，包括代码逻辑问题、边界条件、数据异常等}}
### 问题代码位置
- 文件: `{{FILE_PATH}}`
- 行号: {{LINE_NUMBER}}
- 函数/类: `{{FUNCTION_NAME}}`
## 修复方案
{{描述如何修复这个bug，包括修改的逻辑、算法改进等}}
### 修改前代码
```cpp
{{原始代码片段}}
```
### 修改后代码
```cpp
{{修复后的代码片段}}
```
## 修改文件清单
- `{{FILE_1}}` - {{修改说明1}}
- `{{FILE_2}}` - {{修改说明2}}
- `{{FILE_3}}` - {{修改说明3}}
## 测试验证
### 测试场景
{{描述测试场景和测试数据}}
### 测试步骤
1. {{测试步骤1}}
2. {{测试步骤2}}
3. {{测试步骤3}}
### 测试结果
- ✅ {{成功的测试案例}}
- ✅ {{成功的测试案例}}
### 性能影响
{{描述修复对性能的影响，如有}}
## Git提交信息
```
Commit ID: {{COMMIT_HASH}}
Commit Message: {{COMMIT_MESSAGE}}
Branch: {{BRANCH_NAME}}
```
## 相关文档
- [{{相关文档1}}]({{LINK1}})
- [{{相关文档2}}]({{LINK2}})
## 备注
{{其他需要说明的内容、注意事项、后续改进计划等}}
---
**归档位置**: `archives/bug_fixes/{{DATE}}_{{BUG_NAME}}/`
**文档副本**: `docs/fixes/`

188
.claude/templates/feature_update_template.md Normal file
View File

@@ -0,0 +1,188 @@
# 功能更新: {{FEATURE_NAME}}
**日期**: {{DATE}}
**开发者**: {{AUTHOR}}
**相关Issue**: #{{ISSUE_NUMBER}}（如有）
**Git Commit**: {{COMMIT_HASH}}
---
## 功能概述
{{简要描述新功能的目的和价值，1-2句话说明为什么需要这个功能}}
## 需求背景
{{详细描述需求背景、使用场景、要解决的问题}}
### 用户场景
- **场景1**: {{描述使用场景1}}
- **场景2**: {{描述使用场景2}}
### 功能目标
- {{目标1}}
- {{目标2}}
- {{目标3}}
## 设计方案
{{技术设计方案描述}}
### 架构设计
{{如有架构层面的变更或新增模块，在此说明}}
```
[架构图或流程图的ASCII描述，或引用外部图片]
```
### 模块划分
- **模块1**: {{模块1功能说明}}
- **模块2**: {{模块2功能说明}}
- **模块3**: {{模块3功能说明}}
### 数据结构
```cpp
// 新增或修改的数据结构
{{数据结构定义}}
```
### API设计
```cpp
// 公开接口
{{API接口定义}}
```
#### 接口说明
| 接口名称 | 参数 | 返回值 | 功能说明 |
|---------|------|--------|---------|
| {{API1}} | {{参数}} | {{返回值}} | {{说明}} |
| {{API2}} | {{参数}} | {{返回值}} | {{说明}} |
## 实现细节
### 新增文件
- `{{FILE_1}}` - {{文件功能说明}}
- `{{FILE_2}}` - {{文件功能说明}}
### 修改文件
- `{{FILE_3}}` - {{修改内容说明}}
- `{{FILE_4}}` - {{修改内容说明}}
### 核心代码
```cpp
{{核心实现代码片段}}
```
### 算法说明
{{如涉及特定算法，详细说明算法原理和实现}}
## 使用方法
### 基本用法
```cpp
// 示例代码1: 基本使用
{{示例代码}}
```
### 高级用法
```cpp
// 示例代码2: 高级特性
{{示例代码}}
```
### 配置说明
{{如有配置参数，说明配置方法和参数含义}}
| 参数名称 | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| {{PARAM1}} | {{TYPE}} | {{DEFAULT}} | {{说明}} |
## 测试验证
### 单元测试
```cpp
// 单元测试代码
{{测试代码}}
```
### 集成测试
{{描述集成测试场景和结果}}
### 性能测试
| 测试场景 | 执行时间 | 内存占用 | 备注 |
|---------|---------|---------|------|
| {{场景1}} | {{时间}} | {{内存}} | {{说明}} |
### 测试结果
- ✅ {{测试通过项1}}
- ✅ {{测试通过项2}}
- ✅ {{测试通过项3}}
## Git提交信息
```
Commit ID: {{COMMIT_HASH}}
Commit Message: {{COMMIT_MESSAGE}}
Branch: {{BRANCH_NAME}}
```
## 依赖关系
### 外部依赖
- {{依赖库1}} - {{版本}} - {{用途}}
- {{依赖库2}} - {{版本}} - {{用途}}
### 内部依赖
- {{模块1}} - {{依赖关系说明}}
- {{模块2}} - {{依赖关系说明}}
## 兼容性说明
### API兼容性
- {{是否破坏现有API}}
- {{迁移指南（如需要）}}
### 版本兼容性
- 最低支持版本: {{VERSION}}
- 推荐版本: {{VERSION}}
## 已知问题
- {{问题1描述及临时解决方案}}
- {{问题2描述及临时解决方案}}
## 后续计划
- [ ] {{待完善的功能1}}
- [ ] {{待完善的功能2}}
- [ ] {{性能优化计划}}
## 相关文档
- [{{相关文档1}}]({{LINK1}})
- [{{相关文档2}}]({{LINK2}})
## 备注
{{其他需要说明的内容}}
---
**归档位置**: `archives/updates/{{DATE}}_{{FEATURE_NAME}}/`
**文档副本**: `docs/updates/`

201
.claude/templates/release_notes_template.md Normal file
View File

@@ -0,0 +1,201 @@
# Release Notes - v{{VERSION}}
**发布日期**: {{RELEASE_DATE}}
**版本号**: {{VERSION}}
**发布类型**: {{RELEASE_TYPE}} (Major/Minor/Patch)
---
## 版本概述
{{简要描述本版本的主要更新内容和重点特性}}
## 重要变更 ⚠️
{{列出所有重大变更、破坏性更新、需要用户注意的事项}}
- **{{变更1}}**: {{详细说明}}
- **{{变更2}}**: {{详细说明}}
## 新增功能 ✨
### {{功能类别1}}
- **{{功能1名称}}**
- 说明: {{功能描述}}
- 相关文档: [{{文档名称}}]({{链接}})
- Commit: {{commit_hash}}
- **{{功能2名称}}**
- 说明: {{功能描述}}
- 相关文档: [{{文档名称}}]({{链接}})
- Commit: {{commit_hash}}
### {{功能类别2}}
- **{{功能3名称}}**
- 说明: {{功能描述}}
- 相关文档: [{{文档名称}}]({{链接}})
- Commit: {{commit_hash}}
## Bug修复 🐛
### 严重Bug修复
- **{{Bug1名称}}**
- 问题: {{问题描述}}
- 影响: {{影响范围}}
- 修复: {{修复说明}}
- Commit: {{commit_hash}}
### 一般Bug修复
- **{{Bug2名称}}** - {{简短描述}} ({{commit_hash}})
- **{{Bug3名称}}** - {{简短描述}} ({{commit_hash}})
- **{{Bug4名称}}** - {{简短描述}} ({{commit_hash}})
## 性能优化 🚀
- **{{优化项1}}**: {{优化描述和性能提升数据}}
- **{{优化项2}}**: {{优化描述和性能提升数据}}
- **{{优化项3}}**: {{优化描述和性能提升数据}}
## 文档更新 📚
- {{文档更新1}}
- {{文档更新2}}
- {{文档更新3}}
## API变更
### 新增API
```cpp
// 新增的公开接口
{{新API定义}}
```
### 修改API
| API名称 | 变更类型 | 说明 | 迁移指南 |
|---------|---------|------|---------|
| {{API1}} | {{类型}} | {{说明}} | {{指南}} |
### 废弃API
| API名称 | 替代方案 | 移除计划版本 |
|---------|---------|------------|
| {{API1}} | {{替代}} | {{版本}} |
## 依赖更新
| 依赖库 | 旧版本 | 新版本 | 变更原因 |
|-------|--------|--------|---------|
| {{LIB1}} | {{OLD}} | {{NEW}} | {{原因}} |
| {{LIB2}} | {{OLD}} | {{NEW}} | {{原因}} |
## 兼容性说明
### 向后兼容性
- ✅ 完全兼容 v{{PREVIOUS_VERSION}}
- ⚠️ 部分不兼容（详见API变更）
- ❌ 不兼容（需要迁移）
### 系统要求
- **编译器**: {{编译器要求}}
- **操作系统**: {{OS要求}}
- **依赖库**: {{依赖要求}}
## 升级指南
### 从 v{{OLD_VERSION}} 升级
1. **备份当前版本**
```bash
{{备份命令}}
```
2. **更新代码**
```bash
{{更新命令}}
```
3. **处理API变更**
{{迁移步骤说明}}
4. **重新编译**
```bash
{{编译命令}}
```
5. **测试验证**
{{测试建议}}
### 配置迁移
{{如有配置文件格式变更，说明迁移方法}}
## 已知问题
- **{{问题1}}**: {{描述和临时解决方案}}
- **{{问题2}}**: {{描述和临时解决方案}}
## 统计数据
- **新增代码行数**: {{LINE_COUNT}}
- **修改文件数**: {{FILE_COUNT}}
- **关闭Issue数**: {{ISSUE_COUNT}}
- **Pull Request数**: {{PR_COUNT}}
- **贡献者**: {{CONTRIBUTOR_COUNT}}
## 提交历史
```
总提交数: {{COMMIT_COUNT}}
主要提交:
{{COMMIT_HASH_1}} - {{COMMIT_MESSAGE_1}}
{{COMMIT_HASH_2}} - {{COMMIT_MESSAGE_2}}
{{COMMIT_HASH_3}} - {{COMMIT_MESSAGE_3}}
...
```
## 贡献者 👥
感谢以下贡献者对本版本的贡献：
- {{CONTRIBUTOR_1}} - {{贡献说明}}
- {{CONTRIBUTOR_2}} - {{贡献说明}}
## 下一版本计划
### v{{NEXT_VERSION}} (计划中)
- [ ] {{计划功能1}}
- [ ] {{计划功能2}}
- [ ] {{计划优化项}}
## 获取此版本
### 源码下载
```bash
git clone {{REPO_URL}}
git checkout v{{VERSION}}
```
### 二进制包
- [Windows x64]({{DOWNLOAD_LINK}})
- [Linux x64]({{DOWNLOAD_LINK}})
## 反馈和支持
- **Bug报告**: {{ISSUE_URL}}
- **功能请求**: {{FEATURE_REQUEST_URL}}
- **讨论**: {{DISCUSSION_URL}}
- **文档**: {{DOCS_URL}}
---
**完整变更日志**: [v{{OLD_VERSION}}...v{{VERSION}}]({{COMPARE_URL}})
**归档位置**: `archives/versions/v{{VERSION}}/`

450
ARCHIVE_USAGE_GUIDE.md Normal file
View File

@@ -0,0 +1,450 @@
# 自动归档配置使用指南
本文档说明如何使用项目的自动归档配置和辅助脚本。
---
## 配置文件
### `.claude/file_organization.json`
这是主配置文件，定义了项目的文件组织规则，包括：
- **目录结构定义**: 归档目录、文档目录、源码目录的路径和用途
- **文件类型规则**: 不同文件扩展名的默认存放位置
- **命名规范**: Bug修复、功能更新、版本发布的命名模板
- **工作流规则**: 各类归档的标准流程
- **自动分类规则**: 根据关键词自动识别归档类型
- **模板路径**: 文档模板的位置
- **脚本路径**: 辅助脚本的位置
### 配置加载
配置文件会被以下工具自动读取：
- Claude Code AI (自动识别文件组织规则)
- 辅助脚本 (使用配置生成归档)
---
## 文档模板
模板位置: `.claude/templates/`
### 1. `bug_fix_template.md`
Bug修复文档模板，包含以下占位符：
- `{{BUG_DESCRIPTION}}` - Bug描述
- `{{DATE}}` - 日期
- `{{AUTHOR}}` - 作者
- `{{COMMIT_HASH}}` - Git提交哈希
- `{{FILE_PATH}}` - 文件路径
- 等等...
### 2. `feature_update_template.md`
功能更新文档模板，包含以下占位符：
- `{{FEATURE_NAME}}` - 功能名称
- `{{DATE}}` - 日期
- `{{AUTHOR}}` - 开发者
- `{{COMMIT_HASH}}` - Git提交哈希
- 等等...
### 3. `release_notes_template.md`
版本发布说明模板，包含以下占位符：
- `{{VERSION}}` - 版本号
- `{{RELEASE_DATE}}` - 发布日期
- `{{RELEASE_TYPE}}` - 发布类型
- `{{COMMIT_COUNT}}` - 提交数量
- 等等...
---
## 辅助脚本
脚本位置: `scripts/`
### 1. Bug修复归档脚本
**脚本**: `scripts/archive_bug_fix.sh`
**功能**:
- 自动创建Bug修复归档目录结构
- 生成Bug修复文档
- 复制文档到快速查阅目录
**使用方法**:
```bash
# 基本用法
./scripts/archive_bug_fix.sh <bug名称>
# 指定作者
./scripts/archive_bug_fix.sh <bug名称> "作者名称"
# 示例
./scripts/archive_bug_fix.sh path_tracking_error
./scripts/archive_bug_fix.sh csv_load_issue "张三"
```
**执行流程**:
1. 验证是否在项目根目录
2. 创建归档目录: `archives/bug_fixes/YYYYMMDD_<bug名称>/`
3. 创建子目录: `code/`, `docs/`, `tests/`
4. 从模板生成文档并替换占位符
5. 复制文档到 `docs/fixes/` 供快速查阅
6. 显示下一步操作提示
**创建的目录结构**:
```
archives/bug_fixes/20251115_path_tracking_error/
├── code/ # 存放修复的代码文件
├── docs/ # 存放详细文档
│ └── BUG_path_tracking_error_20251115.md
└── tests/ # 存放测试文件
docs/fixes/ # 文档快速查阅副本
└── BUG_path_tracking_error_20251115.md
```
---
### 2. 功能更新归档脚本
**脚本**: `scripts/archive_feature.sh`
**功能**:
- 自动创建功能更新归档目录结构
- 生成功能更新文档
- 复制文档到快速查阅目录
**使用方法**:
```bash
# 基本用法
./scripts/archive_feature.sh <功能名称>
# 指定开发者
./scripts/archive_feature.sh <功能名称> "开发者名称"
# 示例
./scripts/archive_feature.sh adaptive_lookahead
./scripts/archive_feature.sh dynamic_obstacle_avoidance "李四"
```
**执行流程**:
1. 验证是否在项目根目录
2. 创建归档目录: `archives/updates/YYYYMMDD_<功能名称>/`
3. 创建子目录: `code/`, `docs/`, `tests/`
4. 从模板生成文档并替换占位符
5. 复制文档到 `docs/updates/` 供快速查阅
6. 显示下一步操作提示
**创建的目录结构**:
```
archives/updates/20251115_adaptive_lookahead/
├── code/ # 存放新增/修改的代码
├── docs/ # 存放详细文档
│ └── UPDATE_adaptive_lookahead_20251115.md
└── tests/ # 存放测试文件
docs/updates/ # 文档快速查阅副本
└── UPDATE_adaptive_lookahead_20251115.md
```
---
### 3. 版本发布脚本
**脚本**: `scripts/create_release.sh`
**功能**:
- 创建版本归档目录
- 生成Release Notes
- 创建Git Tag
- 可选备份完整代码
**使用方法**:
```bash
# 基本用法
./scripts/create_release.sh <版本号>
# 指定发布类型
./scripts/create_release.sh <版本号> <Major|Minor|Patch>
# 示例
./scripts/create_release.sh 1.2.0
./scripts/create_release.sh 2.0.0 Major
./scripts/create_release.sh 1.2.1 Patch
```
**版本号格式**: X.Y.Z
- **X** (Major): 重大版本，可能包含不兼容的API变更
- **Y** (Minor): 次要版本，新增功能但向后兼容
- **Z** (Patch): 补丁版本，仅bug修复
**执行流程**:
1. 验证版本号格式和git仓库
2. 确定发布类型 (自动或手动指定)
3. 创建版本目录: `archives/versions/vX.Y.Z/`
4. 统计提交和文件变更
5. 生成Release Notes
6. 创建Git Tag
7. 可选：备份源码到归档目录
8. 显示推送tag的命令
**创建的目录结构**:
```
archives/versions/v1.2.0/
├── release_notes.md # 版本发布说明
└── backup/ # 可选：完整代码备份
└── source_code.tar.gz
```
---
## 完整工作流程
### Bug修复流程
1. **在主代码目录修复bug**
```bash
vim src/path_tracker.cpp
# 修复bug...
```
2. **提交git**
```bash
git add src/path_tracker.cpp
git commit -m "fix: 修复路径跟踪误差累积问题"
```
3. **创建归档**
```bash
./scripts/archive_bug_fix.sh path_tracking_error "你的名字"
```
4. **编辑文档**
```bash
vim archives/bug_fixes/20251115_path_tracking_error/docs/BUG_path_tracking_error_20251115.md
# 填写详细的bug信息、原因分析、修复方案等
```
5. **复制相关文件到归档**
```bash
# 复制修复的代码
cp src/path_tracker.cpp archives/bug_fixes/20251115_path_tracking_error/code/
# 如有测试文件
cp tests/test_path_tracker.cpp archives/bug_fixes/20251115_path_tracking_error/tests/
```
6. **提交归档**
```bash
git add archives/bug_fixes/ docs/fixes/
git commit -m "archive: Bug修复 - path_tracking_error"
```
---
### 功能更新流程
1. **在主代码目录开发新功能**
```bash
vim src/adaptive_lookahead.cpp
vim include/adaptive_lookahead.h
# 开发新功能...
```
2. **提交git**
```bash
git add src/adaptive_lookahead.cpp include/adaptive_lookahead.h
git commit -m "feature: 实现自适应前视距离算法"
```
3. **创建归档**
```bash
./scripts/archive_feature.sh adaptive_lookahead "你的名字"
```
4. **编辑文档**
```bash
vim archives/updates/20251115_adaptive_lookahead/docs/UPDATE_adaptive_lookahead_20251115.md
# 填写功能说明、设计方案、使用方法等
```
5. **复制相关文件到归档**
```bash
# 复制新增的代码
cp src/adaptive_lookahead.cpp archives/updates/20251115_adaptive_lookahead/code/
cp include/adaptive_lookahead.h archives/updates/20251115_adaptive_lookahead/code/
# 如有测试和示例
cp tests/test_adaptive_lookahead.cpp archives/updates/20251115_adaptive_lookahead/tests/
cp examples/example_adaptive.cpp archives/updates/20251115_adaptive_lookahead/code/
```
6. **提交归档**
```bash
git add archives/updates/ docs/updates/
git commit -m "archive: 功能更新 - adaptive_lookahead"
```
---
### 版本发布流程
1. **确保所有变更已提交**
```bash
git status
# 应该显示 "working tree clean"
```
2. **运行发布脚本**
```bash
./scripts/create_release.sh 1.2.0
```
3. **编辑Release Notes**
```bash
vim archives/versions/v1.2.0/release_notes.md
# 填写版本概述、新增功能、bug修复等
```
4. **提交归档**
```bash
git add archives/versions/
git commit -m "release: v1.2.0"
```
5. **推送tag**
```bash
git push origin v1.2.0
```
6. **在GitHub/GitLab创建Release**
- 上传编译好的二进制文件
- 复制Release Notes内容
- 发布
---
## AI辅助使用
当使用Claude Code时，AI会自动读取 `.claude/file_organization.json` 配置，并根据以下规则工作：
### 自动识别归档类型
AI会根据关键词自动识别任务类型：
- **Bug修复关键词**: bug, fix, 修复, 错误, 问题
- 文件归档到: `archives/bug_fixes/`
- 文档归档到: `docs/fixes/`
- **功能更新关键词**: feature, update, 新增, 功能, 更新, add, implement
- 文件归档到: `archives/updates/`
- 文档归档到: `docs/updates/`
- **版本发布关键词**: version, release, 版本, 发布
- 文件归档到: `archives/versions/`
### 示例对话
```
用户: 我发现了一个路径跟踪的bug，帮我修复并归档
AI: 我会帮你修复这个bug并按照项目规范归档。根据配置，我会：
1. 修复代码
2. 创建归档目录 archives/bug_fixes/YYYYMMDD_path_tracking/
3. 生成修复文档
4. 复制代码和文档到相应位置
```
```
用户: 实现一个新的自适应前视距离功能
AI: 我会实现这个新功能并归档。根据配置，我会：
1. 开发新功能代码
2. 创建归档目录 archives/updates/YYYYMMDD_adaptive_lookahead/
3. 生成功能文档
4. 创建使用示例
```
---
## 目录快速参考
```
project_root/
├── .claude/
│ ├── file_organization.json # 主配置文件
│ └── templates/ # 文档模板
│ ├── bug_fix_template.md
│ ├── feature_update_template.md
│ └── release_notes_template.md
│
├── scripts/ # 辅助脚本
│ ├── archive_bug_fix.sh # Bug修复归档
│ ├── archive_feature.sh # 功能更新归档
│ └── create_release.sh # 版本发布
│
├── archives/ # 归档目录
│ ├── bug_fixes/ # Bug修复归档
│ │ └── YYYYMMDD_bug名称/
│ │ ├── code/
│ │ ├── docs/
│ │ └── tests/
│ ├── updates/ # 功能更新归档
│ │ └── YYYYMMDD_功能名称/
│ │ ├── code/
│ │ ├── docs/
│ │ └── tests/
│ └── versions/ # 版本归档
│ └── vX.Y.Z/
│ ├── release_notes.md
│ └── backup/
│
├── docs/ # 当前文档
│ ├── fixes/ # Bug修复文档（快速查阅）
│ ├── updates/ # 功能更新文档（快速查阅）
│ ├── guides/ # 使用指南
│ └── protocol/ # 协议文档
│
├── src/ # 源代码（主工作目录）
├── include/ # 头文件（主工作目录）
└── examples/ # 示例代码（主工作目录）
```
---
## 常见问题
### Q: 为什么要同时保存到归档目录和docs目录?
A:
- **归档目录** (`archives/`): 完整归档，包含代码、文档、测试，用于长期保存和追溯
- **文档目录** (`docs/`): 文档副本，方便快速查阅最新的修复和更新
### Q: 脚本在Windows上能用吗?
A: 脚本是bash脚本，需要在Git Bash、WSL或Cygwin中运行。也可以手动执行脚本中的步骤。
### Q: 如何自定义模板?
A: 直接编辑 `.claude/templates/` 下的模板文件，使用 `{{占位符}}` 格式添加自定义字段。
### Q: AI如何知道要使用这些配置?
A: AI会自动读取 `.claude/file_organization.json` 配置文件，并根据其中的规则工作。
### Q: 可以修改归档路径吗?
A: 可以，编辑 `.claude/file_organization.json` 中的 `directories` 部分，修改路径配置。
---
## 维护建议
1. **定期检查归档**: 每月检查归档目录，确保文档完整
2. **更新模板**: 根据实际需求不断完善文档模板
3. **脚本优化**: 根据使用反馈优化脚本功能
4. **配置同步**: 团队成员保持配置文件一致
---
最后更新: 2025-11-15

276
FILE_ORGANIZATION.md Normal file
View File

@@ -0,0 +1,276 @@
# 文件组织规范
本文档定义了AGV路径跟踪项目的文件组织规范，用于管理bug修复、程序更新和版本归档。
## 目录结构
```
agv_path_tracking/
├── archives/ # 归档目录
│ ├── bug_fixes/ # Bug修复归档
│ │ └── YYYYMMDD_bug名称/ # 按日期和bug名称组织
│ │ ├── code/ # 修复的代码文件
│ │ ├── docs/ # 相关文档
│ │ └── tests/ # 测试文件
│ ├── updates/ # 功能更新归档
│ │ └── YYYYMMDD_功能名称/ # 按日期和功能名称组织
│ │ ├── code/ # 新增/修改的代码
│ │ ├── docs/ # 更新文档
│ │ └── tests/ # 测试文件
│ └── versions/ # 版本归档
│ └── vX.Y.Z/ # 按版本号组织
│ ├── release_notes.md
│ └── backup/ # 完整代码备份
├── docs/ # 项目文档
│ ├── fixes/ # Bug修复文档（当前）
│ ├── updates/ # 功能更新文档（当前）
│ ├── guides/ # 使用指南
│ └── protocol/ # 协议文档
├── src/ # 源代码（主工作目录）
├── include/ # 头文件（主工作目录）
└── examples/ # 示例代码（主工作目录）
```
## 命名规范
### 1. Bug修复命名
- **文件夹命名**: `YYYYMMDD_bug描述`
- 例如: `20251115_fix_path_tracking_error`
- **文件命名**: 保持原有文件名，或添加`_fixed`后缀
- 例如: `path_tracker_fixed.cpp`
### 2. 功能更新命名
- **文件夹命名**: `YYYYMMDD_功能描述`
- 例如: `20251115_add_adaptive_lookahead`
- **文件命名**: 清晰描述功能
- 例如: `adaptive_lookahead.cpp`
### 3. 文档命名
- **Bug修复文档**: `BUG_描述_日期.md`
- 例如: `BUG_path_tracking_error_20251115.md`
- **更新文档**: `UPDATE_功能描述_日期.md`
- 例如: `UPDATE_adaptive_lookahead_20251115.md`
## 工作流程
### Bug修复流程
1. **创建工作目录**
```bash
mkdir -p archives/bug_fixes/YYYYMMDD_bug名称/{code,docs,tests}
```
2. **在主代码目录进行修复**
- 在 `src/`, `include/` 等目录直接修复bug
- 及时提交git commit
3. **归档修复**
- 将修复的文件副本保存到 `archives/bug_fixes/YYYYMMDD_bug名称/code/`
- 创建修复文档保存到 `archives/bug_fixes/YYYYMMDD_bug名称/docs/`
- 同时在 `docs/fixes/` 创建文档副本供快速查阅
4. **文档内容应包含**
- Bug描述和复现步骤
- 根本原因分析
- 修复方案说明
- 修改的文件列表
- 测试验证结果
- 相关的git commit ID
### 功能更新流程
1. **创建工作目录**
```bash
mkdir -p archives/updates/YYYYMMDD_功能名称/{code,docs,tests}
```
2. **在主代码目录进行开发**
- 在 `src/`, `include/` 等目录添加新功能
- 及时提交git commit
3. **归档更新**
- 将新增/修改的文件副本保存到 `archives/updates/YYYYMMDD_功能名称/code/`
- 创建更新文档保存到 `archives/updates/YYYYMMDD_功能名称/docs/`
- 同时在 `docs/updates/` 创建文档副本供快速查阅
4. **文档内容应包含**
- 功能需求描述
- 设计方案
- 实现细节
- API文档（如有）
- 使用示例
- 测试结果
- 相关的git commit ID
### 版本发布流程
1. **创建版本目录**
```bash
mkdir -p archives/versions/vX.Y.Z/backup
```
2. **准备发布**
- 更新版本号
- 编写 `release_notes.md`
- 汇总本版本所有bug修复和功能更新
3. **创建备份**
- 可选：将完整代码打包到 `archives/versions/vX.Y.Z/backup/`
- 创建git tag
4. **发布说明应包含**
- 版本号和发布日期
- 新增功能列表
- Bug修复列表
- 重大变更说明
- 升级指南（如需要）
## 文档模板
### Bug修复文档模板
```markdown
# Bug修复: [Bug简短描述]
**日期**: YYYY-MM-DD
**修复者**: [姓名]
**相关Issue**: #[编号]（如有）
## Bug描述
[详细描述bug的表现]
## 复现步骤
1. [步骤1]
2. [步骤2]
3. [观察到的错误行为]
## 根本原因
[分析bug的根本原因]
## 修复方案
[描述如何修复这个bug]
## 修改文件
- `src/xxx.cpp` - [修改说明]
- `include/xxx.h` - [修改说明]
## 测试验证
[描述如何测试验证修复有效]
## Git Commit
- Commit ID: [commit_hash]
- Commit Message: [message]
## 备注
[其他需要说明的内容]
```
### 功能更新文档模板
```markdown
# 功能更新: [功能名称]
**日期**: YYYY-MM-DD
**开发者**: [姓名]
**相关Issue**: #[编号]（如有）
## 功能概述
[简要描述新功能的目的和价值]
## 需求背景
[为什么需要这个功能]
## 设计方案
[技术设计方案描述]
### 架构变更
[如有架构层面的变更，在此说明]
### API设计
[如果是库函数，描述API接口]
## 实现细节
### 新增文件
- `src/xxx.cpp` - [文件说明]
- `include/xxx.h` - [文件说明]
### 修改文件
- `src/yyy.cpp` - [修改说明]
## 使用方法
```cpp
// 示例代码
```
## 测试结果
[测试场景和结果]
## Git Commit
- Commit ID: [commit_hash]
- Commit Message: [message]
## 后续计划
[如有待完善的内容]
## 备注
[其他需要说明的内容]
```
## 最佳实践
1. **及时归档**: 完成修复或更新后立即归档，不要拖延
2. **详细文档**: 文档要详细清晰，方便他人理解和维护
3. **代码备份**: 归档时保存相关代码的副本，便于追溯
4. **版本控制**: 善用git，每次修复/更新都要commit
5. **交叉引用**: 文档中包含git commit ID，方便关联
6. **定期整理**: 定期检查归档目录，清理过时内容
7. **命名一致**: 严格遵循命名规范，保持一致性
## 快速参考
### 创建Bug修复归档
```bash
DATE=$(date +%Y%m%d)
BUG_NAME="bug_description"
mkdir -p archives/bug_fixes/${DATE}_${BUG_NAME}/{code,docs,tests}
mkdir -p docs/fixes/
# 编辑文档
vim archives/bug_fixes/${DATE}_${BUG_NAME}/docs/BUG_${BUG_NAME}_${DATE}.md
# 复制到快速查阅目录
cp archives/bug_fixes/${DATE}_${BUG_NAME}/docs/BUG_${BUG_NAME}_${DATE}.md docs/fixes/
```
### 创建功能更新归档
```bash
DATE=$(date +%Y%m%d)
FEATURE_NAME="feature_description"
mkdir -p archives/updates/${DATE}_${FEATURE_NAME}/{code,docs,tests}
mkdir -p docs/updates/
# 编辑文档
vim archives/updates/${DATE}_${FEATURE_NAME}/docs/UPDATE_${FEATURE_NAME}_${DATE}.md
# 复制到快速查阅目录
cp archives/updates/${DATE}_${FEATURE_NAME}/docs/UPDATE_${FEATURE_NAME}_${DATE}.md docs/updates/
```
### 查看归档历史
```bash
# 查看所有bug修复
ls -la archives/bug_fixes/
# 查看所有功能更新
ls -la archives/updates/
# 查看所有版本
ls -la archives/versions/
```
## 维护说明
本规范文档应该：
- 随着项目发展持续更新
- 被所有项目成员遵守
- 在项目README中引用
最后更新: 2025-11-15
```

10
README.md
View File

@@ -104,6 +104,8 @@ chmod +x build.sh
### 🎯 快速参考
- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - 快速参考指南
- [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) - 完整项目结构
- [FILE_ORGANIZATION.md](FILE_ORGANIZATION.md) - 文件组织规范 ⭐
- [ARCHIVE_USAGE_GUIDE.md](ARCHIVE_USAGE_GUIDE.md) - 归档工具使用指南 ⭐
### 📘 使用指南
- [docs/guides/START_HERE.txt](docs/guides/START_HERE.txt) - 新手入门
@@ -176,6 +178,14 @@ while (running) {
## 📝 更新日志
### 2025-11-15 - 文件组织规范
- ✅ 创建文件组织和归档配置系统
- ✅ 添加Bug修复归档脚本
- ✅ 添加功能更新归档脚本
- ✅ 添加版本发布脚本
- ✅ 创建文档模板系统
- ✅ 编写详细的使用指南
### 2025-11-14 - 项目重组
- ✅ 重新组织项目文件结构
- ✅ 文档归类到 `docs/` 目录

229
scripts/archive_bug_fix.sh Normal file
View File

@@ -0,0 +1,229 @@
#!/bin/bash
# Bug修复归档脚本
# 用途: 自动创建Bug修复归档目录结构，并生成文档模板
set -e
# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# 打印带颜色的信息
print_info() {
echo -e "${BLUE}[INFO]${NC} $1"
}
print_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
print_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# 检查是否在项目根目录
check_project_root() {
if [ ! -f "FILE_ORGANIZATION.md" ]; then
print_error "请在项目根目录运行此脚本"
exit 1
fi
}
# 显示使用说明
show_usage() {
echo "使用方法: $0 <bug名称> [作者名称]"
echo ""
echo "示例:"
echo " $0 path_tracking_error \"张三\""
echo " $0 csv_load_issue"
echo ""
echo "说明:"
echo " - bug名称使用英文和下划线，如: path_tracking_error"
echo " - 作者名称可选，默认从git config获取"
exit 1
}
# 获取当前日期
get_date() {
date +%Y%m%d
}
# 获取作者名称
get_author() {
if [ -n "$1" ]; then
echo "$1"
else
git config user.name || echo "Unknown"
fi
}
# 获取最新的commit信息
get_latest_commit() {
if git rev-parse --git-dir > /dev/null 2>&1; then
echo "$(git rev-parse --short HEAD)"
else
echo "N/A"
fi
}
# 创建归档目录
create_archive_dirs() {
local date=$1
local bug_name=$2
local archive_path="archives/bug_fixes/${date}_${bug_name}"
print_info "创建归档目录: ${archive_path}"
mkdir -p "${archive_path}/code"
mkdir -p "${archive_path}/docs"
mkdir -p "${archive_path}/tests"
mkdir -p "docs/fixes"
print_success "目录创建完成"
echo "${archive_path}"
}
# 生成文档
create_document() {
local date=$1
local bug_name=$2
local author=$3
local commit_hash=$4
local archive_path=$5
local doc_name="BUG_${bug_name}_${date}.md"
local doc_path="${archive_path}/docs/${doc_name}"
local template_path=".claude/templates/bug_fix_template.md"
print_info "生成文档: ${doc_name}"
# 如果模板存在，使用模板；否则创建基本文档
if [ -f "${template_path}" ]; then
cp "${template_path}" "${doc_path}"
# 替换模板变量
sed -i "s/{{BUG_DESCRIPTION}}/${bug_name}/g" "${doc_path}"
sed -i "s/{{DATE}}/${date}/g" "${doc_path}"
sed -i "s/{{AUTHOR}}/${author}/g" "${doc_path}"
sed -i "s/{{COMMIT_HASH}}/${commit_hash}/g" "${doc_path}"
sed -i "s/{{DATE}}_{{BUG_NAME}}/${date}_${bug_name}/g" "${doc_path}"
else
# 创建基本文档
cat > "${doc_path}" << EOF
# Bug修复: ${bug_name}
**日期**: ${date}
**修复者**: ${author}
**Git Commit**: ${commit_hash}
---
## Bug描述
[详细描述bug的表现]
## 复现步骤
1. [步骤1]
2. [步骤2]
3. [观察到的错误]
## 根本原因
[分析bug的根本原因]
## 修复方案
[描述修复方案]
## 修改文件清单
- \`file1.cpp\` - [修改说明]
## 测试验证
[测试结果]
## Git提交信息
\`\`\`
Commit ID: ${commit_hash}
\`\`\`
---
**归档位置**: \`archives/bug_fixes/${date}_${bug_name}/\`
EOF
fi
# 复制到快速查阅目录
cp "${doc_path}" "docs/fixes/${doc_name}"
print_success "文档生成完成"
echo "${doc_path}"
}
# 显示下一步操作
show_next_steps() {
local doc_path=$1
local archive_path=$2
echo ""
print_success "Bug修复归档创建完成!"
echo ""
echo "📁 归档目录: ${archive_path}"
echo "📄 文档位置: ${doc_path}"
echo "📋 快速查阅: docs/fixes/"
echo ""
print_info "下一步操作:"
echo " 1. 编辑文档: vim ${doc_path}"
echo " 2. 复制修复的代码到: ${archive_path}/code/"
echo " 3. 添加测试文件到: ${archive_path}/tests/"
echo " 4. 提交git: git add . && git commit -m \"archive: Bug修复 - ${bug_name}\""
echo ""
}
# 主函数
main() {
# 检查参数
if [ $# -lt 1 ]; then
show_usage
fi
local bug_name=$1
local author=$(get_author "$2")
# 检查项目根目录
check_project_root
# 获取信息
local date=$(get_date)
local commit_hash=$(get_latest_commit)
print_info "开始创建Bug修复归档"
print_info "Bug名称: ${bug_name}"
print_info "日期: ${date}"
print_info "作者: ${author}"
print_info "Commit: ${commit_hash}"
echo ""
# 创建目录
local archive_path=$(create_archive_dirs "${date}" "${bug_name}")
# 生成文档
local doc_path=$(create_document "${date}" "${bug_name}" "${author}" "${commit_hash}" "${archive_path}")
# 显示下一步操作
show_next_steps "${doc_path}" "${archive_path}"
}
# 运行主函数
main "$@"

251
scripts/archive_feature.sh Normal file
View File

@@ -0,0 +1,251 @@
#!/bin/bash
# 功能更新归档脚本
# 用途: 自动创建功能更新归档目录结构，并生成文档模板
set -e
# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# 打印带颜色的信息
print_info() {
echo -e "${BLUE}[INFO]${NC} $1"
}
print_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
print_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# 检查是否在项目根目录
check_project_root() {
if [ ! -f "FILE_ORGANIZATION.md" ]; then
print_error "请在项目根目录运行此脚本"
exit 1
fi
}
# 显示使用说明
show_usage() {
echo "使用方法: $0 <功能名称> [开发者名称]"
echo ""
echo "示例:"
echo " $0 adaptive_lookahead \"李四\""
echo " $0 dynamic_obstacle_avoidance"
echo ""
echo "说明:"
echo " - 功能名称使用英文和下划线，如: adaptive_lookahead"
echo " - 开发者名称可选，默认从git config获取"
exit 1
}
# 获取当前日期
get_date() {
date +%Y%m%d
}
# 获取开发者名称
get_developer() {
if [ -n "$1" ]; then
echo "$1"
else
git config user.name || echo "Unknown"
fi
}
# 获取最新的commit信息
get_latest_commit() {
if git rev-parse --git-dir > /dev/null 2>&1; then
echo "$(git rev-parse --short HEAD)"
else
echo "N/A"
fi
}
# 创建归档目录
create_archive_dirs() {
local date=$1
local feature_name=$2
local archive_path="archives/updates/${date}_${feature_name}"
print_info "创建归档目录: ${archive_path}"
mkdir -p "${archive_path}/code"
mkdir -p "${archive_path}/docs"
mkdir -p "${archive_path}/tests"
mkdir -p "docs/updates"
print_success "目录创建完成"
echo "${archive_path}"
}
# 生成文档
create_document() {
local date=$1
local feature_name=$2
local developer=$3
local commit_hash=$4
local archive_path=$5
local doc_name="UPDATE_${feature_name}_${date}.md"
local doc_path="${archive_path}/docs/${doc_name}"
local template_path=".claude/templates/feature_update_template.md"
print_info "生成文档: ${doc_name}"
# 如果模板存在，使用模板；否则创建基本文档
if [ -f "${template_path}" ]; then
cp "${template_path}" "${doc_path}"
# 替换模板变量
sed -i "s/{{FEATURE_NAME}}/${feature_name}/g" "${doc_path}"
sed -i "s/{{DATE}}/${date}/g" "${doc_path}"
sed -i "s/{{AUTHOR}}/${developer}/g" "${doc_path}"
sed -i "s/{{COMMIT_HASH}}/${commit_hash}/g" "${doc_path}"
sed -i "s/{{DATE}}_{{FEATURE_NAME}}/${date}_${feature_name}/g" "${doc_path}"
else
# 创建基本文档
cat > "${doc_path}" << EOF
# 功能更新: ${feature_name}
**日期**: ${date}
**开发者**: ${developer}
**Git Commit**: ${commit_hash}
---
## 功能概述
[简要描述新功能的目的和价值]
## 需求背景
[详细描述需求背景和使用场景]
## 设计方案
[技术设计方案描述]
### 架构设计
[架构设计说明]
### API设计
\`\`\`cpp
// 接口定义
\`\`\`
## 实现细节
### 新增文件
- \`file1.cpp\` - [文件说明]
### 修改文件
- \`file2.cpp\` - [修改说明]
## 使用方法
\`\`\`cpp
// 使用示例
\`\`\`
## 测试验证
[测试结果]
## Git提交信息
\`\`\`
Commit ID: ${commit_hash}
\`\`\`
## 后续计划
- [ ] [待完善项1]
- [ ] [待完善项2]
---
**归档位置**: \`archives/updates/${date}_${feature_name}/\`
EOF
fi
# 复制到快速查阅目录
cp "${doc_path}" "docs/updates/${doc_name}"
print_success "文档生成完成"
echo "${doc_path}"
}
# 显示下一步操作
show_next_steps() {
local doc_path=$1
local archive_path=$2
echo ""
print_success "功能更新归档创建完成!"
echo ""
echo "📁 归档目录: ${archive_path}"
echo "📄 文档位置: ${doc_path}"
echo "📋 快速查阅: docs/updates/"
echo ""
print_info "下一步操作:"
echo " 1. 编辑文档: vim ${doc_path}"
echo " 2. 复制新增/修改的代码到: ${archive_path}/code/"
echo " 3. 添加测试文件到: ${archive_path}/tests/"
echo " 4. 更新使用示例到: examples/"
echo " 5. 提交git: git add . && git commit -m \"feature: ${feature_name}\""
echo ""
}
# 主函数
main() {
# 检查参数
if [ $# -lt 1 ]; then
show_usage
fi
local feature_name=$1
local developer=$(get_developer "$2")
# 检查项目根目录
check_project_root
# 获取信息
local date=$(get_date)
local commit_hash=$(get_latest_commit)
print_info "开始创建功能更新归档"
print_info "功能名称: ${feature_name}"
print_info "日期: ${date}"
print_info "开发者: ${developer}"
print_info "Commit: ${commit_hash}"
echo ""
# 创建目录
local archive_path=$(create_archive_dirs "${date}" "${feature_name}")
# 生成文档
local doc_path=$(create_document "${date}" "${feature_name}" "${developer}" "${commit_hash}" "${archive_path}")
# 显示下一步操作
show_next_steps "${doc_path}" "${archive_path}"
}
# 运行主函数
main "$@"

373
scripts/create_release.sh Normal file
View File

@@ -0,0 +1,373 @@
#!/bin/bash
# 版本发布脚本
# 用途: 创建版本发布归档，生成release notes，创建git tag
set -e
# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# 打印带颜色的信息
print_info() {
echo -e "${BLUE}[INFO]${NC} $1"
}
print_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
print_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# 检查是否在项目根目录
check_project_root() {
if [ ! -f "FILE_ORGANIZATION.md" ]; then
print_error "请在项目根目录运行此脚本"
exit 1
fi
}
# 检查是否在git仓库中
check_git_repo() {
if ! git rev-parse --git-dir > /dev/null 2>&1; then
print_error "不在git仓库中"
exit 1
fi
}
# 显示使用说明
show_usage() {
echo "使用方法: $0 <版本号> [发布类型]"
echo ""
echo "参数:"
echo " 版本号 格式: X.Y.Z (如: 1.2.0)"
echo " 发布类型 Major | Minor | Patch (可选，默认根据版本号判断)"
echo ""
echo "示例:"
echo " $0 1.2.0"
echo " $0 1.2.0 Minor"
echo " $0 2.0.0 Major"
echo ""
echo "说明:"
echo " - Major: 重大版本更新，可能包含不兼容的API变更"
echo " - Minor: 次要版本更新，新增功能但向后兼容"
echo " - Patch: 补丁版本，仅包含bug修复"
exit 1
}
# 验证版本号格式
validate_version() {
local version=$1
if ! [[ $version =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
print_error "版本号格式错误，应为 X.Y.Z"
exit 1
fi
}
# 判断发布类型
determine_release_type() {
local version=$1
local provided_type=$2
if [ -n "$provided_type" ]; then
echo "$provided_type"
return
fi
# 自动判断
local last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
local last_version=${last_tag#v}
IFS='.' read -r -a curr_parts <<< "$version"
IFS='.' read -r -a last_parts <<< "$last_version"
if [ "${curr_parts[0]}" -gt "${last_parts[0]}" ]; then
echo "Major"
elif [ "${curr_parts[1]}" -gt "${last_parts[1]}" ]; then
echo "Minor"
else
echo "Patch"
fi
}
# 获取当前日期
get_date() {
date +%Y-%m-%d
}
# 创建版本归档目录
create_version_dirs() {
local version=$1
local version_path="archives/versions/v${version}"
print_info "创建版本归档目录: ${version_path}"
mkdir -p "${version_path}/backup"
print_success "目录创建完成"
echo "${version_path}"
}
# 获取commit统计
get_commit_stats() {
local last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$last_tag" ]; then
# 如果没有tag，统计所有commit
git rev-list --count HEAD
else
# 统计从上个tag到现在的commit
git rev-list --count ${last_tag}..HEAD
fi
}
# 获取变更的文件数
get_changed_files() {
local last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$last_tag" ]; then
git diff --name-only --diff-filter=ACMR | wc -l
else
git diff --name-only --diff-filter=ACMR ${last_tag}..HEAD | wc -l
fi
}
# 生成release notes
create_release_notes() {
local version=$1
local release_type=$2
local release_date=$3
local version_path=$4
local notes_path="${version_path}/release_notes.md"
local template_path=".claude/templates/release_notes_template.md"
print_info "生成Release Notes: ${notes_path}"
local commit_count=$(get_commit_stats)
local file_count=$(get_changed_files)
local last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
local last_version=${last_tag#v}
# 如果模板存在，使用模板
if [ -f "${template_path}" ]; then
cp "${template_path}" "${notes_path}"
# 替换模板变量
sed -i "s/{{VERSION}}/${version}/g" "${notes_path}"
sed -i "s/{{RELEASE_DATE}}/${release_date}/g" "${notes_path}"
sed -i "s/{{RELEASE_TYPE}}/${release_type}/g" "${notes_path}"
sed -i "s/{{COMMIT_COUNT}}/${commit_count}/g" "${notes_path}"
sed -i "s/{{FILE_COUNT}}/${file_count}/g" "${notes_path}"
sed -i "s/{{OLD_VERSION}}/${last_version}/g" "${notes_path}"
sed -i "s/{{PREVIOUS_VERSION}}/${last_version}/g" "${notes_path}"
else
# 创建基本release notes
cat > "${notes_path}" << EOF
# Release Notes - v${version}
**发布日期**: ${release_date}
**版本号**: ${version}
**发布类型**: ${release_type}
---
## 版本概述
[简要描述本版本的主要更新内容]
## 重要变更 ⚠️
[列出所有重大变更]
## 新增功能 ✨
- [功能1]
- [功能2]
## Bug修复 🐛
- [Bug修复1]
- [Bug修复2]
## 性能优化 🚀
- [优化项1]
- [优化项2]
## 统计数据
- **总提交数**: ${commit_count}
- **修改文件数**: ${file_count}
- **上一版本**: ${last_version}
## 升级指南
### 从 v${last_version} 升级
1. 备份当前版本
2. 更新代码
3. 重新编译
4. 测试验证
## 获取此版本
\`\`\`bash
git clone <repo_url>
git checkout v${version}
\`\`\`
---
**归档位置**: \`archives/versions/v${version}/\`
EOF
fi
print_success "Release Notes生成完成"
echo "${notes_path}"
}
# 创建git tag
create_git_tag() {
local version=$1
local tag_name="v${version}"
print_info "检查是否已存在tag: ${tag_name}"
if git rev-parse "${tag_name}" >/dev/null 2>&1; then
print_warning "Tag ${tag_name} 已存在"
read -p "是否删除并重新创建? (y/N): " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
git tag -d "${tag_name}"
print_info "已删除旧tag"
else
print_info "跳过创建tag"
return
fi
fi
print_info "创建git tag: ${tag_name}"
git tag -a "${tag_name}" -m "Release version ${version}"
print_success "Git tag创建完成"
echo ""
print_info "推送tag到远程仓库:"
echo " git push origin ${tag_name}"
}
# 可选：备份代码
backup_code() {
local version_path=$1
echo ""
read -p "是否备份完整代码到归档目录? (y/N): " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
print_info "创建代码备份..."
local backup_file="${version_path}/backup/source_code.tar.gz"
tar -czf "${backup_file}" \
--exclude='.git' \
--exclude='build' \
--exclude='archives' \
--exclude='*.o' \
--exclude='*.so' \
--exclude='*.dll' \
src/ include/ examples/ CMakeLists.txt
print_success "代码备份完成: ${backup_file}"
else
print_info "跳过代码备份"
fi
}
# 显示下一步操作
show_next_steps() {
local version=$1
local notes_path=$2
local version_path=$3
echo ""
print_success "版本发布归档创建完成!"
echo ""
echo "📁 版本目录: ${version_path}"
echo "📄 Release Notes: ${notes_path}"
echo "🏷️ Git Tag: v${version}"
echo ""
print_info "下一步操作:"
echo " 1. 编辑Release Notes: vim ${notes_path}"
echo " 2. 检查并补充版本信息"
echo " 3. 提交归档: git add archives/versions/ && git commit -m \"release: v${version}\""
echo " 4. 推送tag: git push origin v${version}"
echo " 5. 在GitHub/GitLab创建Release"
echo ""
}
# 主函数
main() {
# 检查参数
if [ $# -lt 1 ]; then
show_usage
fi
local version=$1
local release_type=$2
# 验证版本号
validate_version "${version}"
# 检查环境
check_project_root
check_git_repo
# 确定发布类型
release_type=$(determine_release_type "${version}" "${release_type}")
# 获取日期
local release_date=$(get_date)
print_info "开始创建版本发布"
print_info "版本号: ${version}"
print_info "发布类型: ${release_type}"
print_info "发布日期: ${release_date}"
echo ""
# 确认
read -p "确认创建版本 v${version}? (y/N): " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
print_info "取消操作"
exit 0
fi
# 创建版本目录
local version_path=$(create_version_dirs "${version}")
# 生成Release Notes
local notes_path=$(create_release_notes "${version}" "${release_type}" "${release_date}" "${version_path}")
# 创建Git Tag
create_git_tag "${version}"
# 可选备份
backup_code "${version_path}"
# 显示下一步操作
show_next_steps "${version}" "${notes_path}" "${version_path}"
}
# 运行主函数
main "$@"

109
src/can/CANController.h
View File

@@ -1,109 +0,0 @@
/**
* CAN 控制器封装类
* 功能：简化 CAN 设备的操作，提供易用的接口
*/
#ifndef CAN_CONTROLLER_H
#define CAN_CONTROLLER_H
#include "../../lib/ControlCAN.h"
#include <string>
#include <vector>
#include <functional>
/**
* CAN 控制器类
*/
class CANController {
public:
// 回调函数类型：接收到 CAN 数据时调用
using ReceiveCallback = std::function<void(const VCI_CAN_OBJ&)>;
/**
* 构造函数
* @param device_type 设备类型（VCI_USBCAN2 = 4）
* @param device_index 设备索引（第几个设备，从0开始）
* @param can_index CAN 通道索引（0 或 1）
*/
CANController(DWORD device_type = VCI_USBCAN2,
DWORD device_index = 0,
DWORD can_index = 0);
~CANController();
/**
* 初始化 CAN 设备
* @param baud_t0 波特率定时器0
* @param baud_t1 波特率定时器1
* @param mode 工作模式：0=正常，1=只听，2=自发自收
* @return 成功返回 true
*/
bool Initialize(BYTE baud_t0 = 0x00, BYTE baud_t1 = 0x1C, BYTE mode = 0);
/**
* 关闭 CAN 设备
*/
void Close();
/**
* 发送标准帧
* @param can_id CAN ID（11位）
* @param data 数据指针
* @param len 数据长度（最大8字节）
* @return 成功返回 true
*/
bool SendStandardFrame(UINT can_id, const BYTE* data, BYTE len);
/**
* 发送扩展帧
* @param can_id CAN ID（29位）
* @param data 数据指针
* @param len 数据长度（最大8字节）
* @return 成功返回 true
*/
bool SendExtendedFrame(UINT can_id, const BYTE* data, BYTE len);
/**
* 接收 CAN 数据（非阻塞）
* @param frames 接收缓冲区
* @param max_count 最大接收帧数
* @return 实际接收到的帧数
*/
DWORD Receive(std::vector<VCI_CAN_OBJ>& frames, DWORD max_count = 2500);
/**
* 获取接收缓冲区中的帧数量
*/
DWORD GetReceiveNum();
/**
* 清空接收缓冲区
*/
bool ClearBuffer();
/**
* 读取设备信息
*/
bool GetDeviceInfo(VCI_BOARD_INFO& info);
/**
* 设置接收回调函数
*/
void SetReceiveCallback(ReceiveCallback callback) {
m_callback = callback;
}
/**
* 是否已初始化
*/
bool IsInitialized() const { return m_initialized; }
private:
DWORD m_device_type;
DWORD m_device_index;
DWORD m_can_index;
bool m_initialized;
ReceiveCallback m_callback;
};
#endif // CAN_CONTROLLER_H