前言¶

在 2026 年 10 月 4 日，智能體開發與數據分析的融合需求日益增多。DeepSeek Harness (DSH) 提供了“一切皆插件”的架構，開發者可以通過插件擴展模型對數據源的操作能力。MaxCompute (ODPS) 作爲阿里雲的大數據計算服務，其數據結構複雜且執行成本較高。直接在智能體中執行 SQL 存在安全與成本風險。dingxin-tech/dsh-maxcompute 插件旨在解決這些問題，它通過封裝 maxc CLI，爲 DSH 提供了元數據瀏覽、成本控制的 SQL 執行以及後臺作業管理能力。

安裝與前置條件¶

使用該插件前，需確保系統已安裝必要的依賴。

1. 安裝 aliyun-odps-console (maxc) CLI：

    pip install aliyun-odps-console

2. 配置身份驗證。插件本身不處理憑據，認證通過 maxc 的配置完成：

    # OAuth 方式（推薦）
    maxc auth login --oauth

    # 或從環境變量讀取
    maxc auth login --from-env

3. 安裝插件：

    npm install dsh-maxcompute

DSH 會讀取 package.json 中的 dsh.bundle.patch 字段，加載 cordis.patch.yml 來連接插件的三層架構（工具層、maxc 提供層、核心層）。

核心功能與架構¶

該插件通過三層架構實現功能：
* maxcompute-tools：9 個面向模型的原生工具，包含只讀保護和成本門控。
* maxcompute-maxc：通過子進程調用 maxc 命令實現服務接口。
* maxcompute-core：定義純類型的服務契約。

主要功能包括：
* 元數據瀏覽：支持列出表、查看錶結構、列出分區以及行數受限的預覽。
* 成本控制的 SQL 執行：在執行前通過 dry-run 估算掃描量，並支持設置掃描閾值，防止意外的高昂成本。
* 後臺作業管理：支持異步任務的輪詢、取消及結果導出。

配置項¶

插件通過配置文件管理運行時行爲。以下爲關鍵配置項：

注意：只讀保護（readonly）是單調的，一旦啓用，後續的配置層無法重新允許寫入操作。

可用工具¶

插件提供了以下工具函數，直接供 DSH 模型調用：

• mc_list_tables：列出項目中的表，支持前綴過濾。
• mc_describe_table：獲取表的列結構、分區列、大小及註釋。
• mc_list_partitions：列出分區表指定分區的值。
• mc_sample_table：對錶進行行數受限的預覽（安全操作）。
• mc_explain_sql：Dry-run 執行，僅估算 SQL 掃描量和成本。
• mc_run_sql：執行 SQL（受只讀保護和成本門控約束）。
• mc_job_status：輪詢異步任務的狀態、進度及 Logview 地址。
• mc_job_result：獲取異步任務結果，支持導出文件。
• mc_job_cancel：取消正在運行的任務。

典型用法¶

下面展示在 DSH 交互場景中的典型調用流程。

1. 瀏覽項目元數據

// 列出 odps_demo 項目中的所有表
mc_list_tables(project="odps_demo")
// 返回: found 42 tables: dwd_trade_detail, dws_user_profile, ...

2. 估算 SQL 成本
在執行昂貴查詢前，先進行成本評估：

// 估算查詢掃描量
mc_explain_sql(sql="SELECT ... WHERE dt='20260819'")
// 返回: estimated scan: 2.3 GB — under the 10 GB threshold

3. 安全執行 SQL
基於成本評估結果執行查詢，並限制返回行數：

// 執行查詢並限制返回 50 行
mc_run_sql(sql="SELECT ...", maxRows=50)
// 返回: total GMV: ¥1,234,567.89

4. 後臺作業管理
對於長時間運行的任務：

// 檢查作業狀態
mc_job_status
// 返回: Job ID, Status, Progress, Logview URL

注意事項¶

• 依賴 maxc CLI：插件依賴 aliyun-odps-console 的 maxc 命令行工具，必須確保該工具已安裝並在系統 PATH 中。
• 身份驗證：認證憑據存儲在 maxc 的配置中，插件進程無法直接讀取，這降低了憑據泄露的風險。
• 只讀鎖：配置中的 readonly 開啓後不可逆，請謹慎評估。
• 許可證：本項目採用 MIT 許可證。

總結¶

該插件爲 DSH 提供了與 MaxCompute 交互的標準接口，通過分層架構和嚴格的配置選項，在保障數據安全（只讀保護）和控制計算成本（掃描閾值）的前提下，支持了元數據查詢和 SQL 分析。開發者可根據具體需求替換 maxc 提供層以適配內部網關。