更新serena mcp的使用原则
This commit is contained in:
parent
2de531e98c
commit
4357b91446
132
CLAUDE.md
132
CLAUDE.md
@ -148,10 +148,134 @@ public class PathClickToolPlugin : ToolPlugin { }
|
||||
- `mcp__serena__get_symbols_overview`
|
||||
- `mcp__serena__find_referencing_symbols`
|
||||
- 所有其他支持`max_answer_chars`参数的serena工具
|
||||
- **执行原则**:
|
||||
- 优先使用精确搜索而非宽泛搜索以减少token消耗
|
||||
- 分步骤获取信息，避免一次性获取大量内容
|
||||
- 如遇到3k限制导致内容截断，应使用更精确的搜索条件重新查询
|
||||
|
||||
#### 查询最佳实践
|
||||
|
||||
**核心原则**: 分步定位 + 分段读取，避免一次性获取大量内容
|
||||
|
||||
##### ❌ 错误做法
|
||||
|
||||
```python
|
||||
# 错误1: 对大方法使用 include_body=true
|
||||
mcp__serena__find_symbol(
|
||||
name_path="LargeMethod",
|
||||
include_body=true, # ❌ 500行方法 → 20k+ 字符 → 必然失败
|
||||
max_answer_chars=3000
|
||||
)
|
||||
|
||||
# 错误2: 使用OR模式的宽泛搜索
|
||||
mcp__serena__search_for_pattern(
|
||||
substring_pattern="时间标签|TimeTag|预估.*时间|总时间", # ❌ 多个模式 → 178k+ 字符
|
||||
output_mode="files_with_matches"
|
||||
)
|
||||
|
||||
# 错误3: 使用通用词搜索
|
||||
mcp__serena__search_for_pattern(
|
||||
substring_pattern="Manager", # ❌ 匹配太多文件
|
||||
output_mode="content"
|
||||
)
|
||||
|
||||
# 错误4: 使用 depth=1 获取所有成员
|
||||
mcp__serena__find_symbol(
|
||||
name_path="LargeViewModel",
|
||||
include_body=false,
|
||||
depth=1, # ❌ 返回所有方法签名 → 5k+ 字符
|
||||
max_answer_chars=3000
|
||||
)
|
||||
```
|
||||
|
||||
##### ✅ 正确做法
|
||||
|
||||
**步骤1: 精确定位文件**
|
||||
|
||||
```python
|
||||
# 方式A: 搜索精确的类名或方法名（单一关键词）
|
||||
mcp__serena__search_for_pattern(
|
||||
substring_pattern="TimeTagViewModel", # ✅ 单一精确词，不用OR模式
|
||||
paths_include_glob="**/*ViewModel.cs", # ✅ 限定文件类型
|
||||
output_mode="files_with_matches"
|
||||
)
|
||||
|
||||
# 方式B: 符号查找定位（不使用depth）
|
||||
mcp__serena__find_symbol(
|
||||
name_path="TimeTagViewModel",
|
||||
include_body=false, # ✅ 只获取类本身
|
||||
depth=0, # ✅ 不获取成员，避免内容过多
|
||||
max_answer_chars=3000
|
||||
)
|
||||
```
|
||||
|
||||
**步骤2: 搜索关键方法调用**
|
||||
|
||||
```python
|
||||
# 找到关键API调用，而不是搜索通用词
|
||||
mcp__serena__search_for_pattern(
|
||||
substring_pattern="CalculateTimeMarkers", # ✅ 搜索具体API名称
|
||||
relative_path="src/UI/WPF/ViewModels/TimeTagViewModel.cs", # ✅ 限定文件
|
||||
output_mode="content",
|
||||
context_lines_before=2,
|
||||
context_lines_after=2,
|
||||
max_answer_chars=3000
|
||||
)
|
||||
```
|
||||
|
||||
**步骤3: 定位实现类**
|
||||
|
||||
```python
|
||||
# 根据步骤2找到的服务类，定位实现文件
|
||||
mcp__serena__search_for_pattern(
|
||||
substring_pattern="TimeMarkerCalculationService", # ✅ 精确类名
|
||||
paths_include_glob="**/*.cs",
|
||||
output_mode="files_with_matches"
|
||||
)
|
||||
```
|
||||
|
||||
**步骤4: 分段读取实现代码**
|
||||
|
||||
```python
|
||||
# 使用Read工具分段获取
|
||||
Read(
|
||||
file_path="src/PathPlanning/TimeMarkerCalculationService.cs",
|
||||
offset=97, # 从方法起始行
|
||||
limit=80 # 读取关键逻辑部分
|
||||
)
|
||||
|
||||
# 如需继续，读取下一段
|
||||
Read(
|
||||
file_path="...",
|
||||
offset=185, # 继续往下
|
||||
limit=20
|
||||
)
|
||||
```
|
||||
|
||||
##### 何时可以使用 include_body=true
|
||||
|
||||
- ✅ 小方法（<100行）
|
||||
- ✅ 属性定义
|
||||
- ✅ 简单类结构
|
||||
- ❌ 大型方法（>200行）
|
||||
- ❌ 复杂类定义
|
||||
- ❌ 带有 `depth=1` 的大型类
|
||||
|
||||
##### 常见错误模式总结
|
||||
|
||||
| 错误模式 | 为什么失败 | 正确做法 |
|
||||
|---------|-----------|---------|
|
||||
| `substring_pattern="A\|B\|C"` | OR模式匹配过多 | 使用单一精确关键词 |
|
||||
| `substring_pattern="总时间"` | 通用词匹配太广 | 搜索具体API名称 |
|
||||
| `depth=1` + 大型类 | 返回所有成员签名 | 使用 `depth=0` 或直接搜索方法 |
|
||||
| `include_body=true` + 大方法 | 方法体太长 | 先定位再用Read分段 |
|
||||
| 不限定文件范围 | 搜索整个代码库 | 使用 `paths_include_glob` 或 `relative_path` |
|
||||
|
||||
##### 执行原则总结
|
||||
|
||||
1. **单一精确关键词** > OR模式或通用词
|
||||
2. **限定搜索范围**: 始终使用 `paths_include_glob` 或 `relative_path`
|
||||
3. **分步骤获取信息**: 定位 → 搜索调用 → 定位实现 → 分段读取
|
||||
4. **避免使用depth**: 对于大型类，使用 `depth=0` 或直接搜索方法名
|
||||
5. **先定位后读取**: 用 `output_mode="files_with_matches"` 定位，再用 `Read` 获取
|
||||
6. **善用context参数**: 搜索时只需少量上下文（2-3行）
|
||||
7. 如遇到3k限制，使用更精确的搜索条件重新查询，而非提高限制
|
||||
|
||||
## API Documentation Search Strategy
|
||||
|
||||
|
||||
@ -8,11 +8,24 @@
|
||||
### 已完成阶段
|
||||
|
||||
#### ✅ 阶段一：UI状态管理清理
|
||||
|
||||
- **删除文件**: src/Core/UIStateMachine.cs (744行)
|
||||
- **原因**: UIStateMachine和UIState枚举完全未使用，项目实际使用PathEditState
|
||||
- **提交**: b048235
|
||||
|
||||
#### ✅ 阶段二：动画管理器合并
|
||||
|
||||
- **删除文件**: src/Core/Animation/LogisticsAnimationManager.cs (542行)
|
||||
- **迁移功能**: 碰撞排除列表缓存管理（5个方法，约200行）迁移到PathAnimationManager
|
||||
- **清理内容**:
|
||||
- 删除未使用的SavedViewpoint功能（300+行）
|
||||
- 移除AnimationControlViewModel中的_logisticsAnimationManager字段
|
||||
- 简化StartAnimationCommand构造函数参数
|
||||
- **代码减少**: 净减少342行
|
||||
- **提交**: 2de531e
|
||||
|
||||
#### ✅ 阶段三：WPF Services清理
|
||||
|
||||
- **删除文件**:
|
||||
- src/UI/WPF/Services/DataBindingBestPractices.cs (0次外部引用)
|
||||
- src/UI/WPF/Services/CrossViewModelSynchronizer.cs (仅被BestPractices使用)
|
||||
@ -21,6 +34,7 @@
|
||||
- **提交**: 52bb3da
|
||||
|
||||
#### ✅ 阶段四：向后兼容代码清理
|
||||
|
||||
- **清理位置**:
|
||||
1. PathAnimationManager.cs - AnimationCompleted旧版事件
|
||||
2. ModelSplitterManager.cs - GenerateFileName旧版重载
|
||||
@ -29,32 +43,29 @@
|
||||
- **提交**: 4ddaa06
|
||||
|
||||
#### ✅ 阶段五：文档清理
|
||||
|
||||
- **删除**: path_visualization_ui.txt (已集成到代码中)
|
||||
|
||||
### 推迟阶段
|
||||
|
||||
#### ⏸️ 阶段二：动画管理器合并（推迟）
|
||||
**原因**:
|
||||
- 功能评估比预期复杂
|
||||
- PathAnimationManager是实际使用的Transform-based动画
|
||||
- LogisticsAnimationManager主要用于碰撞排除列表缓存
|
||||
- 需要更深入的功能分析和测试
|
||||
- **提交**: [包含在阶段四提交中]
|
||||
|
||||
## 总体成果
|
||||
|
||||
### 代码统计
|
||||
- **删除文件数**: 5个
|
||||
- **删除代码行数**: 约3753行
|
||||
- **编译状态**: ✅ 成功，0错误
|
||||
- **提交数**: 4次
|
||||
|
||||
- **删除文件数**: 6个
|
||||
- **删除代码行数**: 约4,095行（阶段1,3-5: 3,753行 + 阶段2: 342行）
|
||||
- **编译状态**: ✅ 全部成功，0错误
|
||||
- **提交数**: 5次
|
||||
- **用户验证**: ✅ 程序运行正常
|
||||
|
||||
### 架构改进
|
||||
1. ✅ 消除UI状态管理的重复抽象
|
||||
2. ✅ 移除未使用的WPF性能优化工具
|
||||
3. ✅ 清除所有明确标注的向后兼容代码
|
||||
4. ⏸️ 动画管理器统一（推迟）
|
||||
|
||||
1. ✅ 消除UI状态管理的重复抽象（UIStateMachine删除）
|
||||
2. ✅ 统一动画管理架构（合并为单一PathAnimationManager）
|
||||
3. ✅ 移除未使用的WPF性能优化工具
|
||||
4. ✅ 清除所有明确标注的向后兼容代码
|
||||
|
||||
### 遵循的原则
|
||||
|
||||
- ✅ "让问题快速暴露"而非隐藏
|
||||
- ✅ "报错比静默失败好"
|
||||
- ✅ "最小化修改"
|
||||
@ -63,57 +74,78 @@
|
||||
## 编译验证
|
||||
|
||||
### 最终编译结果
|
||||
|
||||
```
|
||||
NavisworksTransportPlugin -> bin\Debug\NavisworksTransportPlugin.dll
|
||||
Build successful!
|
||||
```
|
||||
|
||||
### 警告数量
|
||||
|
||||
- 编译警告: 9个 (async/await相关警告，非本次清理引入)
|
||||
- 无新增警告
|
||||
|
||||
## 后续建议
|
||||
|
||||
### 近期可做
|
||||
1. **进一步清理UIUpdate框架**: 如果确认使用率低，可以简化或删除整个src/Core/UIUpdate目录
|
||||
2. **简化DataBindingPerformanceMonitor**: 移除详细统计功能，只保留核心监控
|
||||
|
||||
### 需要更多调查
|
||||
1. **动画管理器整合**: 需要详细测试LogisticsAnimationManager的SavedViewpoint功能是否有实际使用
|
||||
2. **PathAnimationManager优化**: 评估是否可以将碰撞排除列表缓存功能整合进来
|
||||
|
||||
### 保持现状
|
||||
|
||||
- PathInputMonitor, IdleEventManager, DocumentStateManager (使用率合理)
|
||||
- SmartDataBindingOptimizer, BindingExpressionOptimizer (有实际依赖)
|
||||
- DataBindingPerformanceMonitor (有实际使用场景)
|
||||
|
||||
### 潜在优化点（非必要）
|
||||
|
||||
1. **简化DataBindingPerformanceMonitor**: 如果性能监控功能使用率低，可考虑移除详细统计，只保留核心监控
|
||||
2. **评估UIUpdate框架**: 如果确认UIStateManager使用率低，可考虑简化整个UI更新框架
|
||||
|
||||
## Git提交历史
|
||||
|
||||
```bash
|
||||
b048235 - 阶段一：删除冗余的UIStateMachine
|
||||
2de531e - 阶段二：合并动画管理器
|
||||
52bb3da - 阶段三：删除未使用的WPF Services
|
||||
4ddaa06 - 阶段四：删除所有向后兼容代码
|
||||
[待提交] - 阶段五：删除已集成的UI文档片段
|
||||
4ddaa06 - 阶段五：删除已集成的UI文档片段（包含在阶段四）
|
||||
```
|
||||
|
||||
## 风险评估
|
||||
|
||||
- **高风险操作**: 无 (UIStateMachine完全未使用)
|
||||
- **中风险操作**: 无 (所有删除的代码都经过使用率验证)
|
||||
- **低风险操作**: 所有已完成的清理
|
||||
- **高风险操作**: 无
|
||||
- **中风险操作**: 阶段二动画管理器合并（已通过编译和用户运行时验证）
|
||||
- **低风险操作**: 阶段一、三、四、五的清理操作
|
||||
- **回滚策略**: 每阶段独立提交，可单独回滚
|
||||
- **实际验证**: ✅ 用户确认"程序运行正常"
|
||||
|
||||
## 验证checklist
|
||||
|
||||
- [x] 编译通过
|
||||
- [x] 编译通过（所有5个阶段）
|
||||
- [x] 无新增错误
|
||||
- [x] 无新增警告
|
||||
- [ ] 运行时测试 (建议用户在Navisworks中测试基本功能)
|
||||
- [ ] 路径规划功能测试
|
||||
- [ ] 动画播放功能测试
|
||||
- [ ] 碰撞检测功能测试
|
||||
- [x] 运行时测试（用户确认：程序运行正常）
|
||||
- [x] 基本功能验证（用户已在Navisworks中测试）
|
||||
- [ ] 深度功能测试（路径规划、动画播放、碰撞检测 - 建议进一步测试）
|
||||
|
||||
## 结论
|
||||
|
||||
本次清理成功移除了约3753行冗余代码和5个未使用文件，使代码库更加精简和易维护。所有清理操作遵循"最小化修改"和"让问题快速暴露"的原则，编译验证全部通过。
|
||||
**本次清理全部完成**，成功移除了约4,095行冗余代码和6个未使用文件，使代码库更加精简和易维护：
|
||||
|
||||
动画管理器合并操作因需要更深入的分析而推迟，不影响当前清理成果。
|
||||
### 主要成就
|
||||
|
||||
1. **代码精简**: 删除6个文件，净减少4,095行代码
|
||||
2. **架构优化**: 统一动画管理为单一PathAnimationManager，消除重复抽象
|
||||
3. **兼容性清理**: 移除所有明确标注的向后兼容代码
|
||||
4. **质量保证**: 所有5个阶段编译通过，用户运行时验证正常
|
||||
|
||||
### 遵循原则
|
||||
|
||||
- ✅ "让问题快速暴露" > 隐藏问题
|
||||
- ✅ "报错比静默失败好" > 容忍错误
|
||||
- ✅ "最小化修改" > 过度工程
|
||||
- ✅ "明确拒绝向后兼容性" > 妥协设计
|
||||
|
||||
### 最终状态
|
||||
|
||||
- **编译**: ✅ 全部成功（0错误，9个既有警告）
|
||||
- **运行**: ✅ 用户确认正常
|
||||
- **提交**: 5次独立Git提交，可单独回滚
|
||||
- **文档**: 完整的清理计划和总结文档
|
||||
|
||||
Loading…
Reference in New Issue
Block a user