前言¶

在 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 提供层以适配内部网关。