# Agent 开发模板

> 所有 Agent 必须采用"规范获取指引"模式
> 版本: v1.0.0 | 创建日期: 2026-01-16

---

## 🎯 设计原则

**Agent 的职责是引导 AI 获取规范，而不是嵌入完整规范。**

| 应该包含 | 不应该包含 |
|----------|------------|
| MCP 工具调用示例 | 完整的代码示例 |
| 规范 ID 列表 | 详细的规则说明 |
| 简要提示（10-20行） | 大段代码块 |
| 问题诊断指引 | 常用模式的完整实现 |

---

## 📋 标准结构

```markdown
# [框架/技术] 开发代理

> 此 Agent 引导 AI 通过 MCP 工具获取 npm 包中的详细规范
> 版本: vX.X.X | 最后更新: YYYY-MM-DD

---

## 🔴 问题诊断优先（最高优先级）

**当用户描述任何问题时，必须首先调用：**

\`\`\`
troubleshoot({ problem: "用户描述的问题" })
\`\`\`

---

## 📚 规范获取指引

**⚠️ 核心原则：写代码前，必须先通过 MCP 工具获取规范！**

### 按文件类型获取

| 场景 | MCP 调用 |
|------|----------|
| xxx 文件 | \`get_standard_by_id({ id: 'xxx-standard' })\` |

### 按使用的库获取

| 库 | MCP 调用 |
|----|----------|
| xxx-lib | \`get_standard_by_id({ id: 'xxx-lib' })\` |

### 智能获取（推荐）

\`\`\`
get_compact_standards({ currentFile: "当前文件路径" })
\`\`\`

---

## 🎯 快速提示

> 以下是简要提示，**详细规范请通过上述 MCP 工具获取**

### 必须遵守（3-5条）

- ✅ 规则1
- ✅ 规则2

### 禁止（3-5条）

- ❌ 禁止1
- ❌ 禁止2

---

## 📤 统一输出契约

> Agent 首轮输出必须尽量遵循统一结构，便于上层编排 Agent 继续追问或分流

### 必须包含

1. `Task Classification`
2. `Evidence`
3. `Next Action`
4. `Loaded Standards`

### 字段要求

- `Task Classification`：明确任务类型与是否跨域
- `Evidence`：列出触发判断的关键词、文件线索、测量结果或用户描述
- `Next Action`：只给当前最小下一步
- `Loaded Standards`：只列本轮实际需要加载的标准 ID

### 推荐格式

\`\`\`markdown
## Task Classification
problem-diagnosis + vue3

## Evidence
- 用户描述样式失效与错位
- 当前目标文件为 `.vue`
- 涉及 Element Plus 表单

## Next Action
先执行 `troubleshoot`，再补加载 `vue3-composition` 与 `element-plus`

## Loaded Standards
- problem-diagnosis
- vue3-composition
- element-plus
\`\`\`

---

## 📋 可用规范列表

通过 \`get_standard_by_id({ id: 'xxx' })\` 获取：

- \`standard-id-1\` - 描述
- \`standard-id-2\` - 描述

---

## 🛠️ 增强工具使用指南

> MTA 集成了以下增强工具，在特定场景下应主动使用

### 知识图谱记忆

当需要跨会话记住信息时使用：

| 场景 | 工具调用 |
|------|----------|
| 记住用户偏好/项目信息 | \`create_entities + add_observations\` |
| 查询历史记忆 | \`search_nodes\` 或 \`read_graph\` |
| 建立概念关联 | \`create_relations\` |

### 顺序思考

当面对复杂问题时使用：

| 场景 | 工具调用 |
|------|----------|
| 复杂问题分解 | \`sequentialthinking\` |
| 多步骤规划 | \`sequentialthinking\` |
| 需要修订推理 | \`sequentialthinking({ isRevision: true })\` |

---

**维护团队**: MTA工作室  
**设计理念**: Agent 只提供获取指引，详细规范由 MCP 工具从 npm 包动态获取
```

---

## ✅ 检查清单

新建 Agent 时，确保：

- [ ] 第一节是"问题诊断优先"
- [ ] 第二节是"规范获取指引"（包含 MCP 调用表格）
- [ ] 包含"统一输出契约"
- [ ] "快速提示"不超过 20 行
- [ ] 没有大段代码示例（超过 10 行的代码块）
- [ ] 列出了所有可用的规范 ID
- [ ] 文件总行数不超过 150 行

---

## 🚫 反面示例

```markdown
# ❌ 错误：嵌入完整规范

## Vue 3 规范

### Composition API

\`\`\`vue
<script setup lang="ts">
import { ref, computed, onMounted } from 'vue'

// 30 行完整代码示例...
</script>
\`\`\`

### 表单处理

\`\`\`typescript
// 又是 20 行完整代码...
\`\`\`
```

```markdown
# ✅ 正确：指引获取

## 📚 规范获取指引

| 场景 | MCP 调用 |
|------|----------|
| Vue 组件 | \`get_standard_by_id({ id: 'vue3-composition' })\` |

## 🎯 快速提示

- ✅ 使用 Composition API
- ✅ Props 必须定义类型
- ❌ 禁止 Options API

> 详细规范请通过 MCP 工具获取
```

---

**此模板适用于所有 Agent，包括现有的和未来添加的。**