# MCP aurai-advisor 改进建议
## 问题
当前工具描述缺少**相关工具的引导说明**，导致用户（或下级 AI）不知道有其他更合适的工具可用。
**实例**：
- 用户使用 `consult_aurai` 咨询文章评审
- 用户反复手动粘贴文章内容（因为不知道有 `sync_context` 可以上传文件）
- 事实上 `sync_context` 工具支持上传 .md 文件
---
## 改进方案
### 优先级 1：在 `consult_aurai` 描述中添加相关工具引导 ⭐⭐⭐⭐⭐
**位置**：`src/mcp_aurai/server.py` 第 138 行
**当前代码**：
```python
async def consult_aurai(...) -> dict[str, Any]:
"""
请求上级AI的指导（支持交互对齐机制）
这是核心工具，当本地AI遇到编程问题时调用此工具获取上级AI的指导建议。
## [重要] 何时开始新对话？
...
"""
```
**改进为**：
```python
async def consult_aurai(...) -> dict[str, Any]:
"""
请求上级AI的指导（支持交互对齐机制）
这是核心工具，当本地AI遇到编程问题时调用此工具获取上级AI的指导建议。
---
**🔗 相关工具**：
- 📁 **sync_context**：需要上传文档或代码时使用
- 上传文章、说明文档（.md/.txt）
- **上传代码文件（避免内容被截断）** ⭐
- 将 `.py/.js` 等代码文件复制为 `.txt` 后上传
- 📊 **report_progress**：执行上级 AI 建议后，使用此工具报告进度
- 🔍 **get_status**：查看当前对话状态和迭代次数
**💡 重要提示**：
- **避免内容截断**：如果 `code_snippet` 或 `context` 内容过长，请使用 `sync_context` 上传
- **代码文件上传流程**：
1. 将代码文件复制为 .txt：`shutil.copy('script.py', 'script.txt')`
2. 上传文件：`sync_context(operation='incremental', files=['script.txt'])`
3. 告诉上级顾问：`consult_aurai(error_message='请审查已上传的 script.txt')`
---
## [重要] 何时开始新对话？
...
"""
```
---
### 优先级 2：在返回值中动态添加相关工具提示 ⭐⭐⭐⭐
**位置**：`src/mcp_aurai/server.py` 第 320 行（need_info 分支）
**改进代码**：
```python
return {
"status": "need_info",
"message": "[提示] 上级顾问认为信息不足，请回答以下问题：",
"questions_to_answer": response.get("questions", []),
"instruction": "请搜集信息，再次调用 consult_aurai，并将答案填入 'answers_to_questions' 字段。",
# ⭐ 新增：相关工具提示
"related_tools_hint": {
"sync_context": {
"description": "如果需要上传文档（.md/.txt）来补充上下文信息",
"example": "sync_context(operation='full_sync', files=['path/to/doc.md'])"
}
}
}
```
---
### 优先级 3：为 `sync_context` 添加使用示例 ⭐⭐⭐
**位置**：`src/mcp_aurai/server.py` 第 345 行
**当前代码**：
```python
async def sync_context(...) -> dict[str, Any]:
"""
同步代码上下文
在第一次调用或上下文发生重大变化时使用，让上级AI了解当前项目的整体情况。
## [注意] 文件上传限制
**files 参数只支持 .txt 和 .md 文件！**
...
"""
```
**改进为**：
```python
async def sync_context(...) -> dict[str, Any]:
"""
同步代码上下文
在第一次调用或上下文发生重大变化时使用，让上级AI了解当前项目的整体情况。
---
**🎯 典型使用场景**：
### 场景 1：上传文章供上级顾问评审
```python
sync_context(
operation='full_sync',
files=['文章.md'],
project_info={
'task': 'article_review',
'target_platform': 'GLM Coding 知识库'
}
)
consult_aurai(
problem_type='other',
error_message='请评审以下投稿文章...',
context={'请查看已上传的文章文件': '已通过 sync_context 上传'}
)
```
### 场景 2：上传代码文件（避免内容被截断）⭐ 重要
```python
# 问题：代码太长，在 context 字段中可能被截断
# 解决：将代码转换为 .txt 文件后上传
import shutil
# 步骤 1：将代码文件复制为 .txt
shutil.copy('src/main.py', 'src/main.txt')
# 步骤 2：上传文件
sync_context(
operation='incremental',
files=['src/main.txt'],
project_info={
'description': '需要调试的代码',
'language': 'Python'
}
)
# 步骤 3：告诉上级顾问文件已上传
consult_aurai(
problem_type='runtime_error',
error_message='请审查已上传的 src/main.txt 文件，帮我找出bug',
context={
'file_location': '已通过 sync_context 上传',
'expected_behavior': '应该输出...',
'actual_behavior': '实际输出...'
}
)
```
**优势**：
- ✅ 避免代码在 `context` 或 `answers_to_questions` 字段中被截断
- ✅ 利用 sync_context 的文件读取机制，完整传递内容
- ✅ 上级顾问可以完整读取代码文件
### 场景 3：项目首次初始化
```python
sync_context(
operation='full_sync',
files=['README.md', 'docs/说明文档.md'],
project_info={
'project_name': 'My Project',
'tech_stack': 'Python + FastAPI'
}
)
```
---
## [注意] 文件上传限制
**files 参数只支持 .txt 和 .md 文件！**
...
"""
```
---
### 优先级 4：创建工具关系配置（长期改进）⭐⭐⭐
**新建文件**：`src/mcp_aurai/tool_relationships.py`
```python
"""
工具关系映射配置
用于在工具描述和返回值中提供相关工具的引导
"""
TOOL_RELATIONSHIPS = {
"consult_aurai": {
"related_tools": {
"sync_context": {
"description": "上传文档（.md/.txt）补充上下文",
"when_to_use": ["需要评审文章", "需要提供文档说明", "需要上传配置指南"],
"example": "sync_context(operation='full_sync', files=['README.md'])"
},
"report_progress": {
"description": "报告执行进度",
"when_to_use": ["执行建议后", "完成修改后"],
"example": "report_progress(actions_taken='修复了bug', result='success')"
},
"get_status": {
"description": "查看当前状态",
"when_to_use": ["检查迭代次数", "查看历史记录"],
"example": "get_status()"
}
}
},
"sync_context": {
"related_tools": {
"consult_aurai": {
"description": "开始咨询上级顾问",
"when_to_use": ["同步上下文后"],
"example": "consult_aurai(problem_type='design_issue', error_message='...')"
}
}
}
}
def get_related_tools_hints(tool_name: str) -> dict:
"""获取相关工具的提示信息"""
return TOOL_RELATIONSHIPS.get(tool_name, {}).get("related_tools", {})
```
然后在工具描述中自动包含这些信息。
---
## 实施优先级
1. **立即实施**（优先级 1）：
- 在 `consult_aurai` 描述开头添加"相关工具"部分
- 在 `sync_context` 描述中添加使用场景示例
2. **短期实施**（优先级 2）：
- 在返回值中动态添加相关工具提示
3. **长期改进**（优先级 3-4）：
- 创建工具关系配置系统
- 实现自动化工具推荐
---
## 预期效果
改进后，当 AI 使用 `consult_aurai` 时：
**之前**：
```
consult_aurai(...)
→ AI 不知道有 sync_context
→ AI 手动粘贴内容
→ 浪费 token
```
**之后**：
```
consult_aurai(...)
→ 工具描述提示："需要上传文档？使用 sync_context"
→ AI 使用 sync_context 上传文件
→ 高效完成
```
---
## 测试验证
改进后，应该验证以下场景：
1. ✅ AI 在咨询文章评审时，自动使用 `sync_context` 上传文章
2. ✅ AI 在上传文档后，知道接下来使用 `consult_aurai`
3. ✅ AI 在执行建议后，知道使用 `report_progress` 报告进度
4. ✅ 返回值中的相关工具提示能帮助 AI 发现更好的工具
---
**创建日期**：2025-01-22
**改进优先级**：高
**预期工作量**：约 30 分钟（优先级 1-2）
