项目结构调整

2025-11-15 14:31:47 +08:00
parent a77ae6fac1
commit ec1d6f0cee
12 changed files with 2242 additions and 110 deletions
--- a/.claude/file_organization.json
+++ b/.claude/file_organization.json
@@ -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"
+  }
+}
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -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": []
--- a/.claude/templates/bug_fix_template.md
+++ b/.claude/templates/bug_fix_template.md
@@ -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/`
--- a/.claude/templates/feature_update_template.md
+++ b/.claude/templates/feature_update_template.md
@@ -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/`
--- a/.claude/templates/release_notes_template.md
+++ b/.claude/templates/release_notes_template.md
@@ -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}}/`