Introduction¶

As of October 4, 2026, the need to integrate agent development with data analysis continues to grow. DeepSeek Harness (DSH) provides an “everything is a plugin” architecture, allowing developers to extend model interaction capabilities over data sources through plugins. MaxCompute (ODPS), as Alibaba Cloud’s big data computing service, has complex data structures and relatively high execution costs. Executing SQL directly inside an agent introduces security and cost risks. The dingxin-tech/dsh-maxcompute plugin aims to address these problems. By wrapping the maxc CLI, it provides DSH with metadata browsing, cost-controlled SQL execution, and background job management capabilities.

Installation and Prerequisites¶

Before using this plugin, ensure the required dependencies are installed on the system.

1. Install the aliyun-odps-console (maxc) CLI:

    pip install aliyun-odps-console

2. Configure authentication. The plugin itself does not handle credentials; authentication is completed through the maxc configuration:

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

    # 或从环境变量读取
    maxc auth login --from-env

3. Install the plugin:

    npm install dsh-maxcompute

DSH reads the dsh.bundle.patch field in package.json, loads cordis.patch.yml, and wires together the plugin’s three-layer architecture (tool layer, maxc provider layer, core layer).

Core Features and Architecture¶

The plugin implements its features through a three-layer architecture:
* maxcompute-tools: 9 model-facing native tools, including read-only protection and cost gating.
* maxcompute-maxc: Implements service interfaces by invoking maxc commands through child processes.
* maxcompute-core: Defines purely typed service contracts.

Key capabilities include:
* Metadata browsing: Supports listing tables, inspecting table schemas, listing partitions, and row-limited previews.
* Cost-controlled SQL execution: Estimates scanned volume via dry-run before execution and supports configuring a scan threshold to prevent unexpected high costs.
* Background job management: Supports polling, canceling, and exporting results of asynchronous jobs.

Configuration Options¶

The plugin manages runtime behavior through configuration files. The following are the key configuration items:

Note: Read-only protection (readonly) is monotonic; once enabled, later configuration layers cannot re-allow write operations.

Available Tools¶

The plugin provides the following tool functions for direct invocation by DSH models:

• mc_list_tables: Lists tables in a project, with prefix filtering support.
• mc_describe_table: Gets table column schema, partition columns, size, and comments.
• mc_list_partitions: Lists values of specified partitions in a partitioned table.
• mc_sample_table: Performs a row-limited preview of a table (safe operation).
• mc_explain_sql: Dry-run execution that estimates only SQL scanned volume and cost.
• mc_run_sql: Executes SQL (constrained by read-only protection and cost gating).
• mc_job_status: Polls asynchronous job status, progress, and Logview URL.
• mc_job_result: Retrieves asynchronous job results, supports file export.
• mc_job_cancel: Cancels a running job.

Typical Usage¶

The following shows a typical invocation flow in DSH interaction scenarios.

1. Browse project metadata

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

2. Estimate SQL cost
Before executing an expensive query, estimate the cost first:

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

3. Execute SQL safely
Execute the query based on the cost estimation and limit returned rows:

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

4. Manage background jobs
For long-running jobs:

// 检查作业状态
mc_job_status
// 返回: Job ID, Status, Progress, Logview URL

Notes¶

• Depends on maxc CLI: The plugin depends on the maxc command-line tool from aliyun-odps-console; ensure it is installed and available in the system PATH.
• Authentication: Credentials are stored in the maxc configuration and cannot be directly read by the plugin process, reducing the risk of credential leakage.
• Read-only lock: Once readonly is enabled in the configuration, it is irreversible; evaluate carefully.
• License: This project uses the MIT License.

Summary¶

The plugin provides DSH with a standard interface for interacting with MaxCompute. Through a layered architecture and strict configuration options, it supports metadata queries and SQL analysis while safeguarding data security (read-only protection) and controlling computing costs (scan threshold). Developers can replace the maxc provider layer as needed to adapt to internal gateways.