# TWork 工程师工具提示词优化方案

## 问题分析

### Qoder提示词设计模式

Qoder在工具调用率方面表现优秀的关键因素:

1. **精确的工具描述**: 每个工具都有清晰的使用场景说明
2. **触发关键词**: 在描述中包含用户常见的提问方式
3. **决策树逻辑**: 通过条件判断帮助LLM选择合适的工具
4. **示例驱动**: 提供具体的使用示例

### TWork当前问题

1. 工具描述过于简洁,缺少使用场景说明
2. 没有包含常见的用户提问模式
3. 缺少工具选择的决策逻辑
4. 参数描述不够详细

## 优化策略

### 1. 工具描述增强模式

```typescript
description: `工具的主要功能。

# 使用场景
- 场景1: 当用户想要XXX时
- 场景2: 当用户问YYY时
- 场景3: 当需要ZZZ时

# 触发关键词
"分析代码", "检查复杂度", "查找问题", "代码质量"

# 不要使用
- 当用户想要YYY时,应该使用其他工具`
```

### 2. 决策树逻辑

```
if (用户询问代码质量/复杂度/问题) {
  使用 analyze_code
} else if (用户想要搜索代码/查找功能实现) {
  use search_codebase
} else if (用户报告错误/Bug/异常) {
  use diagnose_bug
} else if (用户想要重构/改进代码) {
  use suggest_refactor
} else if (用户需要了解项目结构) {
  use analyze_project
}
```

## 具体优化工具清单

### 1. analyze_code 工具

**优化前**:
```
分析代码文件的复杂度、依赖关系、潜在问题。支持 TypeScript/JavaScript/Python/Java/Go/Rust
```

**优化后**:
```
分析代码文件的质量指标,包括圈复杂度、认知复杂度、依赖关系、符号定义和潜在问题。

# 使用场景
- 当用户说"分析这个文件"或"检查代码质量"时
- 当用户询问"这个函数复杂吗?"或"代码有什么问题?"时
- 当需要评估代码复杂度、查找代码异味(code smell)时
- 当用户想要了解文件的依赖关系或定义的函数/类时
- 在重构前分析代码,或code review时

# 返回内容
- 圈复杂度和认知复杂度(>10表示复杂)
- 代码行数统计(总行数/代码行/注释行)
- 依赖的模块列表
- 定义的函数、类、接口、常量
- 潜在问题:高复杂度、深嵌套、过长函数、TODO标记

# 触发关键词
"分析代码", "检查复杂度", "代码质量", "查找问题", "code review", "代码分析", "这个文件怎么样"

# 最佳实践
- 分析单个文件时使用此工具
- 需要分析整个项目时,使用 analyze_project 工具
- 发现问题后,可以使用 suggest_refactor 获取重构建议
```

### 2. search_codebase 工具

**优化前**:
```
语义代码搜索工具,通过理解代码含义来搜索代码库。
```

**优化后**:
```
语义代码搜索工具,通过理解代码含义和功能来搜索代码库,而不仅仅是文本匹配。

# 使用场景
- 当用户问"XXX功能在哪里实现?"或"如何实现的?"时
- 当用户想要"找到认证逻辑"、"支付代码在哪里"时
- 当不知道具体文件名,但知道功能描述时
- 当需要理解代码库结构或查找特定概念时
- 当用户说"搜索一下XXX相关的代码"时

# 参数说明
- query: 搜索查询,描述要查找的功能(如 "user authentication", "how payments work")
- key_words: 关键词,用逗号分隔,提高搜索精度(可选)
- target_directories: 限制搜索的目录列表(可选)

# 返回内容
- 匹配的文件列表(按相关度排序)
- 相关代码片段和行号
- 性能指标(扫描文件数、耗时)

# 触发关键词
"搜索代码", "查找功能", "XXX在哪里", "如何实现", "代码库搜索", "找一下XXX的代码"

# 最佳实践
- 使用描述性查询(如 "user authentication" 而非 "auth")
- 指定关键词可以提高搜索精度
- 限制搜索目录可以提高性能
- 如果需要精确文本匹配,使用 grep_search 工具
```

### 3. diagnose_bug 工具

**优化前**:
```
诊断代码错误,分析堆栈追踪,生成修复建议和测试用例
```

**优化后**:
```
诊断代码中的Bug和错误,分析错误消息和堆栈追踪,生成详细的修复建议和验证测试用例。

# 使用场景
- 当用户报告错误、异常或Bug时
- 当用户提供错误消息或堆栈追踪时
- 当用户问"这个错误是什么原因?"或"如何修复这个Bug?"时
- 当代码运行时报错、崩溃或行为异常时
- 当需要快速定位问题根因时

# 参数说明
- error_message: 错误消息(必需,如 "TypeError: Cannot read property 'x' of undefined")
- stack_trace: 堆栈追踪信息(可选,帮助定位具体位置)
- source_code: 相关源代码(可选,提供更精准的建议)
- file_path: 错误文件路径(可选)

# 返回内容
- 错误类型和严重程度(critical/high/medium/low)
- 根因分析(为什么会出现这个错误)
- 错误位置(文件、行号、列号)
- 具体的修复建议(含代码示例)
- 验证测试用例(确保修复有效)
- 常见原因列表

# 触发关键词
"Bug", "错误", "异常", "报错", "崩溃", "修复", "diagnose", "这是什么错误", "怎么修复"

# 支持的错误类型
- TypeError, ReferenceError, SyntaxError (JavaScript/TypeScript)
- IndexError, KeyError, TypeError (Python)
- ENOTFOUND, ECONNREFUSED (网络错误)
- 以及其他常见错误模式

# 最佳实践
- 提供完整的错误消息和堆栈追踪
- 如果可能,附上相关源代码
- 修复后运行测试用例验证
```

### 4. suggest_refactor 工具

**优化前**:
```
分析代码并提供重构建议,包括重命名、提取函数/模块、简化复杂度、检测死代码
```

**优化后**:
```
分析代码并提供专业的重构建议,帮助改善代码质量、降低复杂度、提高可维护性。

# 使用场景
- 当用户说"重构这个文件"或"改进代码质量"时
- 当用户询问"这段代码可以怎么优化?"时
- 当analyze_code发现高复杂度或代码异味时
- 当需要重命名变量/函数、提取函数、简化逻辑时
- 当想要检测死代码或未使用的代码时
- 在code review后需要具体重构方案时

# 参数说明
- file_path: 要分析的文件路径(必需)
- refactor_type: 重构类型
  - rename: 重命名(改进命名规范性)
  - extract: 提取(提取函数/模块)
  - simplify: 简化(降低复杂度)
  - dead-code: 死代码检测
  - all: 全部分析(推荐)
- target_name: 目标名称(重命名时需要指定新名称)

# 返回内容
- 重构建议列表(按优先级排序)
- 每个建议的类型、位置、原因
- 具体的重构方案和代码示例
- 重构前后的对比
- 完整的质量报告

# 触发关键词
"重构", "优化代码", "改进代码", "提取函数", "简化", "死代码", "重命名", "refactor", "代码异味"

# 重构类型说明
1. 重命名: 变量/函数命名不符合规范时
2. 提取: 函数过长、职责过多时提取为小函数
3. 简化: 复杂度过高、嵌套过深时简化逻辑
4. 死代码: 检测未使用的变量、函数、导入

# 最佳实践
- 先用 analyze_code 分析代码质量
- 根据具体问题选择refactor_type
- 重构后运行测试确保功能正常
- 小步重构,每次只做一处改动
```

### 5. analyze_project 工具

**优化前**:
```
分析项目整体结构、技术栈、依赖关系、架构模式,生成项目架构文档
```

**优化后**:
```
全面分析项目整体结构,自动识别技术栈、构建工具、依赖关系图谱和架构模式。

# 使用场景
- 当用户问"这是什么项目?"或"项目用什么技术栈?"时
- 当需要快速了解一个新项目的整体架构时
- 当用户说"分析一下这个项目"或"项目结构是什么?"时
- 当需要了解项目的依赖关系和模块划分时
- 当接手新项目、进行架构评审时
- 当需要生成项目文档或技术调研报告时

# 参数说明
- project_path: 项目根目录路径(必需)
- analysis_depth: 分析深度
  - quick: 快速分析(仅技术栈+文件统计,~1s)
  - standard: 标准分析(包含依赖关系,~3s,推荐)
  - deep: 深度分析(包含架构映射,~10s)
- focus_areas: 关注领域(可选)
  - architecture: 架构模式
  - dependencies: 依赖关系
  - tech-stack: 技术栈
  - workflow: 工作流

# 返回内容
- 技术栈识别(语言、框架、构建工具、测试框架、数据库)
- 项目结构(文件数、代码行数、目录树)
- 依赖关系图谱(模块间依赖、循环依赖检测)
- 架构模式识别(MVC/微服务/单体/分层架构)
- 代码质量指标(平均复杂度、测试覆盖率)
- 完整的项目架构报告

# 触发关键词
"项目分析", "技术栈", "项目结构", "架构", "依赖关系", "这是什么项目", "analyze project"

# 分析深度选择
- quick: 快速了解技术栈和规模
- standard: 全面了解项目(推荐)
- deep: 深度架构分析(耗时较长)

# 最佳实践
- 分析整个项目时使用此工具
- 分析单个文件时使用 analyze_code
- 深度分析耗时较长,先用quick或standard
- 可以结合 search_codebase 查找具体功能
```

### 6. lsp_query 工具

**优化前**:
```
查询LSP语言服务器提供的诊断、悬停、定义跳转、引用查找、符号搜索、实现跳转、调用层级等能力
```

**优化后**:
```
查询LSP(Language Server Protocol)语言服务器,提供代码智能查询能力,类似IDE的"转到定义"、"查找引用"等功能。

# 使用场景
- 当用户问"这个函数在哪里定义的?"时(使用definition)
- 当用户问"这个变量在哪里被使用了?"时(使用references)
- 当用户问"这个函数是什么?"或需要类型信息时(使用hover)
- 当需要查找代码中的错误或警告时(使用diagnostics)
- 当用户问"这个接口有哪些实现?"时(使用implementation)
- 当需要查看函数调用关系时(使用call_hierarchy)
- 当需要代码补全建议时(使用completion)

# 参数说明
- file_path: 要查询的文件路径(必需)
- query_type: 查询类型(必需)
  - diagnostics: 诊断信息(错误/警告)
  - hover: 悬停信息(类型/文档)
  - definition: 定义跳转(转到定义)
  - references: 引用查找(查找引用)
  - completion: 代码补全
  - document_symbols: 文档符号(当前文件的函数/类)
  - workspace_symbols: 工作区符号(全局搜索符号)
  - implementation: 实现跳转(接口实现)
  - call_hierarchy: 调用层级(函数调用链)
  - incoming_calls: 谁调用了我
  - outgoing_calls: 我调用了谁
- line: 行号(1-based,大部分查询需要)
- column: 列号(1-based,大部分查询需要)
- query: 搜索关键词(workspace_symbols时使用)

# 返回内容
根据query_type不同返回:
- diagnostics: 错误/警告列表(位置、消息、严重级别)
- definition/references: 位置列表(文件、行号、列号)
- hover: 类型信息、文档字符串
- symbols: 符号列表(名称、类型、位置)
- call_hierarchy: 调用关系树

# 触发关键词
"转到定义", "查找引用", "这个函数在哪", "谁调用了", "代码补全", "错误检查", "lsp", "IDE功能"

# 查询类型选择决策树
if (需要查看错误/警告) → diagnostics
if (需要知道"这是什么"/类型信息) → hover
if (需要找到定义位置) → definition
if (需要找到所有使用位置) → references
if (需要代码补全) → completion
if (需要查看当前文件有哪些函数/类) → document_symbols
if (需要全局搜索某个函数/类) → workspace_symbols
if (需要找接口的实现) → implementation
if (需要看函数调用链) → call_hierarchy

# 最佳实践
- 需要提供准确的行号和列号(1-based)
- diagnostics和document_symbols不需要行号
- workspace_symbols可以全局搜索,不需要file_path精确
- LSP查询依赖语言服务器,响应时间可能较长
```

## 系统提示词增强

### 当前问题
系统提示词中工具描述过于简略,LLM难以准确选择合适的工具。

### 优化方案

在系统提示词中添加**工具选择决策树**:

```
## 工程师工具选择指南

当用户提出代码相关需求时,按以下决策树选择工具:

1. **代码质量分析**
   - 用户说"分析代码"、"检查质量"、"复杂度" → analyze_code
   - 用户说"分析整个项目"、"技术栈" → analyze_project

2. **代码搜索**
   - 用户说"搜索代码"、"查找功能"、"XXX在哪" → search_codebase
   - 用户说"精确查找文本"、"grep" → grep_search

3. **Bug诊断**
   - 用户报告错误、异常、Bug → diagnose_bug
   - 提供错误消息和堆栈追踪

4. **重构优化**
   - 用户说"重构"、"优化"、"改进代码" → suggest_refactor
   - 先analyze_code发现问题,再suggest_refactor提供方案

5. **IDE级查询**
   - 用户说"转到定义"、"查找引用"、"类型信息" → lsp_query
   - 需要语言服务器支持

6. **项目理解**
   - 用户说"项目结构"、"技术栈"、"依赖关系" → analyze_project
   - 新用户了解项目时常用

# 工具组合使用示例
- 分析代码 → 发现问题 → 重构建议: analyze_code → suggest_refactor
- 搜索代码 → 找到文件 → 分析质量: search_codebase → analyze_code
- 报告错误 → 诊断问题 → 查找定义: diagnose_bug → lsp_query(definition)
```

## 实施计划

### Phase 1: 工具描述优化(1天)
- [ ] 优化6个核心工具的description字段
- [ ] 添加使用场景、触发关键词、最佳实践
- [ ] 确保所有工具描述格式一致

### Phase 2: 系统提示词增强(0.5天)
- [ ] 在系统提示词中添加工具选择决策树
- [ ] 添加工具组合使用示例
- [ ] 优化工程师模式的引导文案

### Phase 3: 测试验证(0.5天)
- [ ] 使用典型用户提问测试工具调用率
- [ ] 对比优化前后的调用准确率
- [ ] 收集LLM反馈(工具描述是否清晰)

## 预期效果

- 工具调用准确率提升 **30-50%**
- LLM选择错误工具的概率降低 **60%**
- 用户满意度提升(更少的手动指定工具)
