Object Storage Service：在Cursor中使用OSS文檔

配置Cursor文檔資料來源

配置Cursor的@Docs資料來源，可以很方便的將本文檔給Cursor使用。

步驟詳解：

1. 開啟Cursor設定

   • 點擊功能表列中的 "Cursor" → "Settings"。

2. 導航到Docs配置

   • 在設定頁面左側導覽列中找到 "Indexing & Docs" 選項。

   • 點擊進入文檔配置頁面。

3. 添加OSS文檔源

   • 點擊 "Add Docs" 按鈕。

   • 輸入OSS官方文檔的URL：https://www.alibabacloud.com/help/en/oss/，為文檔源起一個便於識別的名稱，如 "Aliyun OSS Docs"。

     在彈出的配置表單中填寫以下資訊：

     • NAME：Aliyun OSS Docs

     • PREFIX：https://www.alibabacloud.com/help/zh/oss/

     • ENTRYPOINT：https://www.alibabacloud.com/help/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 %