dsh-maxcompute

MaxCompute (ODPS) data analysis plugin for DSH (DeepSeek Harness): metadata browsing, cost-gated SQL execution, background jobs and result export — all backed by the maxc CLI.

Architecture

┌─────────────────────────────────────────────────────┐
│  maxcompute-tools (consumer)                        │
│  9 model-facing tools + readonly guard + cost gate  │
├─────────────────────────────────────────────────────┤
│  maxcompute-maxc (provider)                         │
│  Implements MaxComputeService via maxc subprocess   │
├─────────────────────────────────────────────────────┤
│  maxcompute-core (contract)                         │
│  Pure types — zero runtime registration             │
└─────────────────────────────────────────────────────┘
                    ↓ execFile
              maxc <args> --json

Auth lives in maxc's own config — this plugin never sees credentials.

Prerequisites

One-liner — installs the maxc CLI if missing (prebuilt dist from OSS, no Python needed), then runs interactive auth:

npx dsh-maxcompute setup

Extra args are forwarded to maxc auth login (e.g. npx dsh-maxcompute setup --from-env). To run any maxc command through the managed binary: npx dsh-maxcompute maxc <args...>. Prefer your own install (pip install maxc-cli or Alibaba Cloud CLI)? Just make sure maxc is on PATH — the plugin resolves it automatically.

Install

npm install dsh-maxcompute

DSH reads the dsh.bundle.patch field in package.json and loads cordis.patch.yml, which wires the three layers. Each row can be replaced by id from a later patch layer (profile / home / --patch overlay).

Configuration

Layer	Key	Type	Default	Description
maxcompute-maxc	maxcBin	string	auto	Path to the maxc binary; defaults to auto-resolution (env ALIBABA_CLOUD_MAXC_EXEC_PATH → managed copy → PATH → OSS download)
maxcompute-maxc	project	string	—	Default project override (--project)
maxcompute-maxc	timeoutMs	number	600000	Kill a foreground maxc process after this many ms
maxcompute-tools	readonly	boolean	true	Deny DDL/DML/SET/TUNNEL at the guard layer
maxcompute-tools	dryRunScanGBThreshold	number	10	Refuse mc_run_sql when estimated scan exceeds this
maxcompute-tools	maxPreviewRows	number	50	Default row cap for previews returned to the model

The readonly guard is monotonic: once enabled it cannot be re-allowed by later listeners.

Tools

Tool	Description
mc_list_tables	List tables in a project, optional prefix filter
mc_describe_table	Column schema, partition columns, size, comment
mc_list_partitions	List partition values for a partitioned table
mc_sample_table	Row-limited preview (always safe)
mc_explain_sql	Dry-run cost estimate — call before expensive queries
mc_run_sql	Execute SQL (readonly guard + cost gate)
mc_job_status	Poll an async job's state / progress / logview
mc_job_result	Fetch results, optionally export to file
mc_job_cancel	Cancel a running job

Example session

User:    帮我看看 odps_demo 项目里有哪些表
Model:   → mc_list_tables(project="odps_demo")
         found 42 tables: dwd_trade_detail, dws_user_profile, ...

User:    查一下 dwd_trade_detail 昨天的成交额
Model:   → mc_explain_sql(sql="SELECT ... WHERE dt='20260819'")
         estimated scan: 2.3 GB — under the 10 GB threshold
         → mc_run_sql(sql="SELECT ...", maxRows=50)
         total GMV: ¥1,234,567.89

Development

git clone https://github.com/dingxin-tech/dsh-maxcompute.git
cd dsh-maxcompute
npm install

npm run build      # tsc
npm run typecheck  # tsc --noEmit
npm test           # vitest

Replacing the provider

To swap maxc for an in-house gateway, create a patch layer that re-inserts row id maxcompute-maxc with your own module providing the same maxcompute service. The tools layer depends only on the service contract from maxcompute-core.

License

MIT