Agent 使用技巧
2025-12-02 14:19:09 # tech #技巧 #Agent #Cursor

Project Rules

使用 Project rules 来让 Agent 遵守项目规则，确保 Agent 的行为符合项目要求。

比如说，我想要 Agent 自动提交代码的时候，能够按照一定规则来生成 Commit Message，我们可以利用 Agent 平台提供的规则来实现。

在 Agent 中，可以使用 Cmd + Shift + P 来开启命令窗口，然后输入 New Cursor Rule 来创建规则。

以下是一个 Commit message 的 rule 样例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
---
alwaysApply: true
---

# GIT 提交说明

提交的 Commit message 必须遵循以下格式：

**格式：** `[标签]分类：具体描述` 或 `[标签]具体描述`

**说明：** 分类为可选项，可根据实际情况添加

## 标签类型

- `feature` - 新功能
- `bugfix` - 错误修复
- `docs` - 文档修改
- `style` - 样式调整（代码格式、UI 样式等）
- `refactor` - 代码重构（不改变功能）
- `perf` - 性能优化
- `test` - 测试相关
- `chore` - 构建配置、依赖更新等

## 常见分类

- 工程初始化
- 配置优化
- 功能开发
- 样式调整
- 文档更新
- 性能优化
- 代码重构

## 样例

- `[feature]工程初始化：增加基础配置`
- `[feature]工程初始化：增加必要的资源`
- `[bugfix]配置优化：修复无法打包的问题`
- `[feature]功能开发：实现用户登录功能`
- `[bugfix]样式调整：修复移动端布局错位`
- `[docs]文档更新：更新 README 使用说明`
- `[style]样式调整：优化首页布局`
- `[refactor]代码重构：抽取公共组件`
- `[perf]性能优化：优化图片加载速度`
- `[chore]依赖更新：升级 hexo 版本`

你可以根据自己的情况来确定生效时机，目前 Cursor 支持：

  • 始终生效
  • 智能生效
  • 特定文件生效
  • 手动引用

由于规则是会占用 token 数量， 所以建议走智能生效的形式，即让 Agent 自行决定是否启用该规则

知识库

知识库（Knowledge Base）是 Agent 理解项目上下文的重要工具。通过构建和维护知识库，可以让 Agent 更好地理解项目架构、业务逻辑和开发规范。

知识库的作用

  • 项目理解：帮助 Agent 快速了解项目结构和技术栈
  • 代码生成：基于项目规范生成符合要求的代码
  • 问题解答：回答项目相关的技术问题
  • 文档生成：自动生成 API 文档、使用说明等

如何构建知识库

1. 代码分析

让 Agent 分析项目代码，提取关键信息：

1
2
3
4
5
请分析这个项目的架构，包括：
- 技术栈和框架
- 目录结构
- 核心模块和功能
- 设计模式和最佳实践

2. 文档整理

将项目文档、README、设计文档等整理成结构化的知识库内容。

3. 知识库模板

创建知识库模板，定义标准格式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 项目概述
- 项目名称：xxx
- 技术栈：xxx
- 主要功能：xxx

# 架构设计
- 前端：xxx
- 后端：xxx
- 数据库：xxx

# 开发规范
- 代码风格：xxx
- 命名规范：xxx
- 提交规范：xxx

使用建议

  • 定期更新：随着项目演进，及时更新知识库内容
  • 分类管理：按模块、功能分类组织知识库
  • 版本控制：将知识库纳入版本管理，追踪变更历史

MCP

MCP（Model Context Protocol）是连接 Agent 和外部工具的标准协议。通过 MCP，Agent 可以调用外部 API、访问数据库、执行系统命令等，大大扩展了 Agent 的能力边界。

MCP 的优势

  • 能力扩展：让 Agent 访问外部资源和工具
  • 标准化：统一的协议规范，易于集成
  • 安全性：可控的权限管理
  • 灵活性：支持自定义实现

自行实现 MCP

基本结构

MCP 服务通常包含以下组件：

  1. Server：MCP 服务器，处理 Agent 的请求
  2. Tools：定义可用的工具和操作
  3. Resources：提供可访问的资源
  4. Prompts：预定义的提示模板

实现示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// mcp-server.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'my-mcp-server',
  version: '1.0.0',
});

// 定义工具
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'get_weather',
      description: '获取指定城市的天气信息',
      inputSchema: {
        type: 'object',
        properties: {
          city: { type: 'string' }
        }
      }
    }
  ]
}));

// 处理工具调用
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'get_weather') {
    const city = request.params.arguments?.city;
    // 调用天气 API
    return { content: [{ type: 'text', text: '天气信息...' }] };
  }
});

部署和配置

  1. 开发 MCP 服务：按照 MCP 协议实现服务端
  2. 配置 Agent：在 Agent 配置中添加 MCP 服务器地址
  3. 测试验证：确保工具调用正常工作

三方 MCP

常用 MCP 服务

  • GitHub MCP：访问 GitHub API，管理仓库、Issues、PR 等
  • Database MCP：连接数据库，执行查询和操作
  • File System MCP：文件系统操作，读写文件
  • Web Search MCP：网络搜索功能
  • API MCP：调用任意 REST API

使用方式

  1. 安装 MCP 服务：通过包管理器或直接安装
  2. 配置连接：在 Agent 配置中指定 MCP 服务器
  3. 调用工具：Agent 可以自动识别并使用 MCP 提供的工具

示例：GitHub MCP

1
2
3
4
5
6
7
8
# agent-config.yml
mcp_servers:
  github:
    url: "https://mcp.github.com"
    tools:
      - create_issue
      - list_repositories
      - create_pull_request

Agent 可以直接使用这些工具：

1
请帮我创建一个新的 Issue，标题是"优化性能"

组合知识库和 MCP 实现自动化分析

知识库和 MCP 可以完美结合，实现强大的自动化分析能力。知识库提供项目上下文，MCP 提供外部工具能力，两者结合可以完成复杂的分析任务。

应用场景

1. 代码质量分析

流程：

  1. 知识库提供代码规范和最佳实践
  2. MCP 调用代码分析工具（如 ESLint、SonarQube）
  3. Agent 结合两者生成分析报告

示例：

1
2
3
4
5
基于项目知识库中的代码规范，使用 MCP 工具分析当前代码，
生成代码质量报告，包括：
- 代码规范检查结果
- 潜在问题和建议
- 性能优化建议

2. 依赖分析

流程：

  1. 知识库记录项目依赖和版本要求
  2. MCP 调用包管理器 API 检查依赖
  3. Agent 分析依赖关系和安全漏洞

示例：

1
2
检查项目依赖，对比知识库中的版本要求，
识别过时依赖和安全漏洞，生成升级建议

3. 文档自动生成

流程：

  1. 知识库提供文档模板和规范
  2. MCP 读取代码和注释
  3. Agent 生成符合规范的文档

示例：

1
2
基于知识库中的 API 文档模板，使用 MCP 读取代码注释，
自动生成完整的 API 文档

最佳实践

  1. 知识库优先：先建立完善的知识库，提供上下文基础
  2. MCP 补充：使用 MCP 获取实时数据和执行操作
  3. 迭代优化：根据分析结果不断优化知识库内容
  4. 权限控制：合理设置 MCP 工具权限，确保安全性

Template

Template（模板）是 Agent 代码生成的核心工具。通过定义代码模板，可以确保生成的代码符合项目规范，提高代码质量和一致性。

Template 的优势

  • 一致性：确保生成的代码风格统一
  • 效率：快速生成符合规范的代码
  • 可维护性：模板集中管理，易于更新
  • 复用性：一次定义，多次使用

Template 类型

1. 代码模板

定义常用代码片段的模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// template: react-component.tsx
import React from 'react';

interface {{ComponentName}}Props {
  // 属性定义
}

export const {{ComponentName}}: React.FC<{{ComponentName}}Props> = (props) => {
  return (
    <div className="{{component-name}}">
      {/* 组件内容 */}
    </div>
  );
};

2. 文件模板

定义完整文件的模板结构：

1
2
3
4
5
6
7
8
9
10
11
# template: api-endpoint.ts
import { Request, Response } from 'express';

export const {{endpointName}} = async (req: Request, res: Response) => {
  try {
    // 业务逻辑
    res.json({ success: true, data: {} });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
};

3. 项目结构模板

定义项目初始化模板：

1
2
3
4
5
6
7
project-template/
├── src/
│   ├── components/
│   ├── utils/
│   └── types/
├── tests/
└── docs/

使用方式

1. 创建模板

在项目中创建 .cursor/templates/ 目录，存放模板文件：

1
2
3
4
5
.cursor/
└── templates/
    ├── component.tsx.template
    ├── api.ts.template
    └── test.ts.template

2. 模板变量

使用 {{变量名}} 定义可替换的变量：

1
2
3
4
5
6
7
8
// template
export class {{ClassName}} {
  private {{propertyName}}: {{Type}};
  
  constructor({{propertyName}}: {{Type}}) {
    this.{{propertyName}} = {{propertyName}};
  }
}

3. 调用模板

Agent 可以根据上下文自动选择合适的模板：

1
请创建一个用户管理组件，使用 React 和 TypeScript

Agent 会：

  1. 识别需要使用组件模板
  2. 提取变量（组件名、属性等）
  3. 填充模板生成代码

模板管理

1. 版本控制

将模板纳入版本管理，追踪变更：

1
2
git add .cursor/templates/
git commit -m "[docs]添加新的组件模板"

2. 分类组织

按功能、类型分类组织模板：

1
2
3
4
5
6
7
8
templates/
├── frontend/
│   ├── react/
│   └── vue/
├── backend/
│   ├── express/
│   └── nestjs/
└── common/

3. 文档说明

为每个模板添加说明文档：

1
2
3
4
5
6
# component.tsx.template

用途：生成 React 函数组件
变量：
- ComponentName: 组件名称（PascalCase）
- component-name: CSS 类名（kebab-case）

最佳实践

  1. 保持简洁：模板不要过于复杂，保持可读性
  2. 参数化：将可变部分提取为变量
  3. 文档化：为模板添加清晰的说明
  4. 测试验证：确保模板生成的代码可以正常运行
  5. 定期更新：随着项目演进，及时更新模板

示例：完整的组件模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// .cursor/templates/react-component.tsx.template
import React, { useState, useEffect } from 'react';
import './{{ComponentName}}.css';

/**
 * {{ComponentDescription}}
 * 
 * @param props - 组件属性
 */
export const {{ComponentName}}: React.FC<{{ComponentName}}Props> = (props) => {
  const [state, setState] = useState<{{StateType}}>({{initialState}});

  useEffect(() => {
    // 副作用逻辑
  }, []);

  return (
    <div className="{{component-name}}" data-testid="{{component-name}}">
      {/* 组件内容 */}
    </div>
  );
};

export default {{ComponentName}};

通过合理使用 Template，可以大幅提升代码生成效率和质量。

上一页
2025-12-02 14:19:09 # tech #技巧 #Agent #Cursor
下一页