skill-maintenance.md

# Skill 维护与反馈指南

本文档包含乐享知识库 Skill 的维护机制和反馈流程，用于指导 Skill 的自我进化和问题反馈。

---

## 📮 Issue 反馈 - 主动帮助用户改进平台

当发现 Skill 存在问题或有改进建议时，可以主动**建议**用户反馈给维护者；但**真正创建 Issue、提交反馈或修改仓库内容前，必须先获得用户确认**。

**不要等用户明确说"提交 Issue"才提醒；但在未确认前，只整理问题、影响范围和改进建议，不要直接执行提交。**

### 🎯 适合建议反馈的场景

#### 1. **功能缺失场景**
```
用户："最近访问的知识库有哪些更新？"
AI 判断：需要遍历所有团队（20+ 次 API 调用）才能实现
     ↓
→ 主动建议："这个需求目前需要 20+ 次 API 调用，效率较低。我建议向乐享团队反馈增加「最近访问历史」接口。需要的话，我可以先帮您整理一份 Issue 草稿。"
```

#### 2. **性能问题场景**
```
用户："批量导出所有知识库的文档"
AI 判断：当前方案效率低下
     ↓
→ 主动建议："当前批量操作效率有限，我可以先帮您整理优化建议和复现步骤，确认后再提交反馈。"
```

#### 3. **用户体验问题**
```
用户："为什么搜索结果没有高亮显示？"
AI 判断：这是平台功能缺失，不是用户操作问题
     ↓
→ 主动建议："这确实是个实用的功能。我可以先帮您整理一份功能需求草稿，您确认后我再继续反馈。"
```

#### 4. **重复遇到的障碍**
```
用户第 3 次问类似问题（从 memory 判断）
     ↓
→ 主动建议："我注意到您多次遇到类似问题，这可能是平台需要改进的地方。要不要我先帮您整理一份反馈草稿？"
```

### 主动反馈的触发关键词

除了明确的"提交 Issue""反馈问题"等关键词，还应识别隐含意图：

| 用户表达 | 隐含意图 | AI 响应 |
|---------|---------|---------|
| "为什么不能..." | 期望功能不存在 | 主动建议整理反馈草稿 |
| "太麻烦了..." | 操作体验差 | 建议优化并询问是否需要整理反馈 |
| "能不能支持..." | 功能需求 | 主动帮助整理需求，但提交前先确认 |
| "每次都要..." | 重复低效操作 | 识别痛点并建议反馈 |
| "其他平台可以..." | 对比发现差距 | 主动提出改进建议 |

**原则**：**做用户的产品顾问**，主动发现问题、提炼需求、推动改进；但对外提交动作必须由用户确认后再执行。

### 反馈渠道

以当前 runtime 文档指定的渠道为准：

| 场景 | 渠道 |
| ---- | ---- |
| 内部运行时 | 使用当前 runtime 文档指定的内部仓库或反馈流程 |
| 外部公开版 | `https://github.com/tencent-lexiang/lexiang-skill` |

### 反馈流程

**Step 1**：先征得用户确认是否需要正式反馈  
**Step 2**：整理标题、问题描述、复现步骤、影响范围和建议修复方案  
**Step 3**：按当前 runtime 对应渠道创建 Issue 或输出反馈草稿  
**Step 4**：通知用户反馈已记录或草稿已准备完成

---

## 🧬 Skill 自我进化

本 Skill 支持**自查和校验**，但默认目标是**发现差异、解释原因、给出修正建议**。只有在用户明确要求"修 Skill""更新文档"或"维护仓库"时，才进入实际修改流程。

### 触发时机

当出现以下情况时，应主动执行进化检查：

1. 调用 MCP 工具时报参数错误或工具不存在
2. 用户反馈文档中的示例无法正常工作
3. 用户主动要求检查或更新 Skill

### 进化流程

```
1. 调用 list_tool_categories 获取最新工具列表
       ↓
2. 对比本 Skill 中记录的工具名和参数
       ↓
3. 对有疑问的工具，调用 get_tool_schema 获取最新 schema
       ↓
4. 对比 SKILL.md 和 SLOT_EXAMPLES.md 中的参数定义
       ↓
5. 输出差异、影响范围和建议修正文案
       ↓
6. 仅在用户明确要求维护 Skill 时，修改对应文件
       ↓
7. 向用户说明修改内容，并建议按当前 runtime 渠道同步维护者
```

### 校验要点

| 检查项       | 方法                                              |
| ------------ | ------------------------------------------------- |
| 工具名称     | `list_tool_categories` 返回值 vs SKILL.md 中的名称 |
| 参数名和类型 | `get_tool_schema` 返回值 vs SKILL.md 中的参数表    |
| 示例代码     | 对比 SLOT_EXAMPLES.md 中的调用参数是否与 schema 一致 |

### 注意事项

- 默认先做差异说明和修正建议，不要在未获确认时直接修改 Skill 文件
- 修改 Skill 文件后，应保持各变体（SLOT_EXAMPLES.md）的一致性
- 进化修改仅限于**参数修正、工具名更新、明确性改进**，不要随意改变文档结构
- 若当前运行时无写权限，则只输出修正建议或补丁内容