AI 助理
文档备案控制台
官方文档
首页

在Cursor中使用OSS文档

更新时间：
复制 MD 格式
产品详情
我的收藏

在 Cursor 里，把 OSS 文档设成 AI 知识源，Cursor Agent 就能直接根据最新的官方文档，自动生成规范的 SDK 调用代码，生成 ossutil 使用示例，智能修复 API 调用问题，还能给出准确的配置建议。

配置Cursor文档数据源

配置Cursor的@Docs数据源，可以很方便的将本文档给Cursor使用。

步骤详解：

  1. 打开Cursor设置

    • 点击菜单栏中的 "Cursor" → "Settings"。

  2. 导航到Docs配置

    • 在设置页面左侧导航栏中找到 "Indexing & Docs" 选项。

    • 点击进入文档配置页面。

  3. 添加OSS文档源

    • 点击 "Add Docs" 按钮。

    • 输入OSS官方文档的URL：https://help.aliyun.com/zh/oss/，为文档源起一个便于识别的名称，如 "Aliyun OSS Docs"。

      在弹出的配置表单中填写以下信息：

      • NAME：Aliyun OSS Docs

      • PREFIX：https://help.aliyun.com/zh/oss/

      • ENTRYPOINT：https://help.aliyun.com/zh/oss/

      填写完成后，单击 Confirm 按钮。

    • 确认文档源已成功添加到列表中，状态显示为"Indexed"（如 Indexed 2556 pages）。单击操作栏中的查看索引页面图标（书本图标），可在弹出浮层中查看已索引的页面标题列表，确认文档已成功抓取并索引。

使用OSS文档答疑

配置完成后，在Cursor中使用OSS文档数据源进行信息索引。

使用方法：

  1. 在聊天窗口使用 @Docs

    • 打开Cursor的AI聊天窗口。

    • 输入 @Aliyun OSS Docs 后跟具体问题。

    • 例如：@Aliyun OSS Docs 如何使用OSS Java SDK创建客户端并配置访问凭证？

  2. 获取精准答案

    • AI会基于OSS文档内容提供准确的答案，包含代码示例、配置步骤等详细信息。

      基本依赖配置的 Maven dependency：

      <dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.17.4</version>
</dependency>

      环境变量方式（推荐）创建 OSSClient 的完整 Java 代码示例：

      import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;

public class OSSClientExample {
    public static void main(String[] args) throws Exception {
        // 从环境变量中获取凭证
        EnvironmentVariableCredentialsProvider credentialsProvider =
            CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        // 配置客户端
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfig
        // 显式声明使用 V4 签名算法
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);

        // 创建OSSClient实例
        OSS ossClient = OSSClientBuilder.create()
                .endpoint("your-endpoint") // 例如：https://oss-cn-hangzhou.aliyuncs.com
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region("your-region") // 例如：cn-hangzhou
                .build();

        // 使用ossClient进行操作...

        // 当OSSClient实例不再使用时，调用shutdown方法以释放资源
        ossClient.shutdown();
    }
}

      需要设置的环境变量：OSS_ACCESS_KEY_ID（您的 AccessKey ID）和 OSS_ACCESS_KEY_SECRET（您的 AccessKey Secret）。

  3. 优化查询效果

    • 具体化问题: 避免过于宽泛的问题，尽量具体到某个功能或场景。

    • 包含关键词: 在问题中包含OSS相关的关键词，如"存储空间"、"对象"、"权限"等。

    • 分步骤询问: 对于复杂操作，可以分步骤进行询问。

      # 好的查询示例
@Docs 如何使用Java SDK上传文件到OSS？
@Docs OSS跨域资源共享CORS如何配置？
@Docs OSS访问控制策略RAM权限设置方法
@Docs 我需要在Node.js项目中实现文件上传到OSS，请提供完整代码示例
@Docs 请提供OSS大文件上传的分片上传最佳实践
@Docs 请提供OSS CDN缓存配置问题的详细排查步骤

# 避免的查询方式
@Docs OSS怎么用？（过于宽泛）
@Docs 上传文件（缺少上下文）

使用OSS文档解决报错

  1. 当使用阿里云OSS SDK进行文件上传、下载或其他操作时遇到异常错误时，使用文档数据源进行错误自动修复。

    import alibabacloud_oss_v2 as oss

def main():
    # 从环境变量中加载凭证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 加载SDK的默认配置，并设置凭证提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 设置配置中的区域信息
    cfg.region = "cn-hangzhou"

    # 使用配置好的信息创建OSS客户端
    client = oss.Client(cfg)

    # 执行上传对象的请求，直接从本地文件上传
    # 指定存储空间名称、对象名称和本地文件路径
    with open('your-test-file.md', 'r') as f:
        result = client.put_object(
            oss.PutObjectRequest(
                bucket="xxx",  # 存储空间名称
                key="xxx",        # 对象名称
                body=f.read()     # 读取文件内容
            )
        )

    # 输出请求的结果信息，包括状态码、请求ID、内容MD5、ETag、CRC64校验码、版本ID和服务器响应时间
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
          f' server time: {result.headers.get("x-oss-server-time")},'
    )

    # 脚本入口，当文件被直接运行时调用main函数
if __name__ == "__main__":
    main()
    File "/Users/xxx/xxx/py_proj/myenv/lib/python3.12/site-packages/alibabacloud_oss_v2/client.py", line 275, in put_ob...
    return operations.put_object(self._client, request, **kwargs)
File "/Users/xxx/xxx/py_proj/myenv/lib/python3.12/site-packages/alibabacloud_oss_v2/operations/object_basic.py", line 44, in put_object
    op_output = client.invoke_operation(op_input, **kwargs)
File "/Users/xxx/xxx/py_proj/myenv/lib/python3.12/site-packages/alibabacloud_oss_v2/_client.py", line 327, in invoke_operation
    raise exceptions.OperationError(
alibabacloud_oss_v2.exceptions.OperationError: operation error PutObject: crc is inconsistent, client 12522791075485846984, server 16472007160000755729.

  2. 打开Cursor的Agent聊天窗口，输入 `@Aliyun OSS Docs` 后跟遇到的具体问题，AI会基于最新的OSS官方文档提供精准的错误排查过程与解决方案，优化代码，帮助您解决报错。

    在 IDE 内嵌 AI 助手对话框中输入 @Aliyun OSS Docs 请帮我进行错误排查，对话上下文区域自动关联当前代码文件 put_object_with_file.py（Lines 173-174）及知识库 Aliyun OSS Docs，AI 助手将结合文档与代码上下文进行错误排查并给出修复建议。

    例如，当上传文件时出现 CRC 校验错误 alibabacloud_oss_v2.exceptions.OperationError: operation error PutObject: crc is inconsistent，AI 助手会自动分析错误类型（CRC64 数据完整性校验失败，客户端与服务器端 CRC64 值不一致）、影响范围（PutObject、AppendObject、UploadPart），并定位根因为代码中使用文本模式 'r' 读取文件。解决方案为将 open('your-test-file.md', 'r') 改为 open('your-test-file.md', 'rb')，以二进制模式读取文件，同时提供一键应用修复按钮。

    AI 助手针对 OSS SDK 文件上传错误提供两种方案：

    1. 推荐方案：使用二进制模式 'rb' 打开文件（✅保证数据完整性、✅适用所有文件类型、✅符合最佳实践）

    2. 临时方案：创建 put_object_with_file_disable_crc.py 禁用 CRC64 校验（⚠️失去数据完整性保护、⚠️仅适用于可信环境、⚠️不推荐生产环境使用）

    CRC64 校验机制说明：SDK 默认开启 CRC64 校验，客户端和服务器端分别计算校验值并比较，文本模式打开文件可能导致换行符转换引起校验不一致，因此应始终使用二进制模式读取文件。

使用OSS文档生成ossutil命令

借助 Cursor 的 AI 能力，您可以通过自然语言描述所需操作，调用 OSS 官方文档作为数据源，自动生成并执行相关命令行操作。例如上传、下载、配置 CNAME 等。AI 会参考文档并结合当前文件目录，生成可直接运行的命令。

使用方法：

  1. 在聊天窗口使用 @Docs

    • 打开Cursor的AI聊天窗口，输入 @Aliyun OSS Docs 后跟操作描述。

    • 例如：@Aliyun OSS Docs 使用 ossutil 上传 cname-configuration.xml 文件到名为 examplebucket 的 Bucket 下

  • 结合文档生成命令并执行

    • AI 会分析：当前所在目录下是否存在 cname-configuration.xml 文件。

      首先，让我检查当前目录下的文件情况：

Listed current directory

好的，我看到cname-configuration.xml文件确实存在。现在让我查看一下这个文件的内容，以便了解它的结构：

Read cname-configuration.xml

    • 之后，根据您描述中的关键要素（如“上传”、文件名、Bucket 名称等），结合 OSS 官方文档生成对应的 ossutil 命令行示例。如果已完成访问凭证配置，Cursor 还可直接帮助您执行该命令。

      例如，执行以下 ossutil 命令将 cname-configuration.xml 文件上传到指定 Bucket：

      ossutil cp cname-configuration.xml oss://xxx/

axxxxi@JGWL9Q2JP7 ossutil-2.1.1-mac-arm64 % ossutil cp cname-configuration.xml oss://xxx/
Success: Total 1 file, size 3882 B, Upload done:(1 objects, 3882 B), avg 14.731 KiB/s

0.260099(s) elapsed
axxxxi@JGWL9Q2JP7 ossutil-2.1.1-mac-arm64 %
上一篇：OSS Connector for AI/ML快速入门下一篇：地域和Endpoint