在Cursor中使用OSS文档

在 Cursor 中接入 OSS 文档

当前版本的 Cursor 已下线 @Docs 外部文档源功能：Settings 中不再有添加外部文档源的入口，Indexing & Docs > Add Docs 流程、NAME / PREFIX / ENTRYPOINT 索引方式均已移除。如果此前按旧流程配置过 OSS 文档数据源，该方式已失效，需改用以下方式之一。

选择接入方式前，确认以下条件已满足：

• 方式一依赖 Cursor Agent 联网抓取页面内容，当前环境需可访问 OSS 帮助中心。

• 方式二需先将与本项目相关的 OSS 文档摘录为本地 Markdown 文件并放入代码仓库。

• 需要 Cursor 直接执行 ossutil 命令时，需已完成 OSS 访问凭证配置。

  按使用场景选择方式：

• 临时提问、快速答疑：使用方式一，在对话中粘贴文档链接即可，无需额外准备。

• 反复查阅的关键内容（如预签名 PUT、Content-Type、V4 签名、分片上传）：使用方式二，文档摘录到本地后由 Agent 直接读取，无需每次联网抓取。

• 固化本项目的 OSS 使用约定：使用方式三，通过 Rules / Skills 让 Agent 生成代码时自动遵循。

• 需要对整站帮助中心文档建立索引：方式一至方式三均不支持，可评估方式四的第三方 MCP 服务。

使用 OSS 文档答疑

接入 OSS 文档后，即可向 Cursor Agent 咨询 OSS 使用问题。

使用方法

• 打开 Cursor 的 AI 对话窗口。

• 粘贴相关 OSS 文档链接（方式一），或用 @文件名 引用已落到本地的文档（方式二），然后描述遇到的问题。

• 例如，粘贴 OSS Java SDK 文档链接后提问“如何使用 OSS Java SDK 创建客户端并配置访问凭证”。

• Agent 会结合文档内容给出准确答案，包含代码示例、配置步骤等详细信息。

  以“使用 Java SDK 创建 OSSClient 并配置访问凭证”为例，Agent 可给出如下内容。

基本依赖配置的 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 ClientBuilderConfiguration();
        // 显式声明使用 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）。上述 Java 示例与下文的 Python 示例均通过环境变量读取凭证，运行前需先完成访问凭证配置。

优化查询效果

无论使用哪种接入方式，遵循以下建议都能获得更精准的答案：

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

• 包含关键词：问题中包含 OSS 相关的关键词，如“存储空间”“对象”“权限”等。

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

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

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

使用 OSS 文档解决报错

使用阿里云 OSS SDK 上传、下载文件或执行其他操作遇到异常错误时，可以借助 Cursor 结合 OSS 文档排查错误并修复代码。以下以上传文件时出现 CRC 校验错误为例，假设使用 Python SDK 从本地文件上传对象。该示例使用 alibabacloud_oss_v2 包，与答疑章节 Java 示例的 aliyun-sdk-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.

排查方法

• 打开 Cursor 的 AI 对话窗口，粘贴与该报错相关的 OSS 文档链接（方式一）或用 @文件名 引用本地文档（方式二），描述遇到的具体报错，Agent 会结合 OSS 官方文档提供精准的错误排查过程与解决方案，帮助优化代码、解决报错。

  在 Cursor 的 AI 对话窗口中输入请帮我进行错误排查，对话上下文区域自动关联当前打开的代码文件put_object_with_file.py（即上述 Python 示例），Agent 将结合提供的文档与代码上下文排查错误并给出修复建议。

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

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

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

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

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

使用 OSS 文档生成 ossutil 命令

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

使用方法

• 打开 Cursor 的 AI 对话窗口，粘贴 ossutil 相关文档链接（方式一）或用 @文件名 引用本地文档（方式二），然后描述操作需求。

• 例如：“使用 ossutil 上传 cname-configuration.xml 文件到名为 examplebucket 的 Bucket 下”。

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

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

Listed current directory

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

Read cname-configuration.xml

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

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

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

命令执行成功后，终端回显上传结果与耗时：

Success: Total 1 file, size 3882 B, Upload done:(1 objects, 3882 B), avg 14.731 KiB/s

0.260099(s) elapsed

命令生成后，可参考《命令行工具 ossutil 2.0》文档（https://help.aliyun.com/zh/oss/developer-reference/ossutil-overview）核对参数含义，或查找上传、下载、CNAME 配置等更多场景的命令示例。