AgentKit Studio
Contributing

Development environment

Take AgentKit Studio from a fresh clone to a running dev host — Node and pnpm versions, DSH checkout, make setup, data isolation, and common failures.

This page takes the repository from "just cloned" to "edit one line and see the result." Every command is copy-pasteable; the targets and defaults come from Makefile, package.json, and .node-version.

Prerequisites

DependencyVersionSource of truth
Node.js24.22.1 (security baseline: 22.23.4+ / 24.22.1+ / 26.12.1+).node-version, scripts/node-version.mjs
pnpm10.33.2packageManager in package.json
Git, Make, C toolchainAny recent versionmake setup compiles DSH native modules
Node development headersinclude/node/node_api.h must existscripts/development-doctor.mjs

Native Windows is not supported

The Make targets depend on POSIX process groups and a POSIX shell. Use WSL2 on Windows; make setup exits with an error on native Windows.

One-time setup

# 1. Enable Corepack so pnpm matches packageManager
corepack enable

# 2. Install this repository's dependencies
pnpm install --frozen-lockfile

# 3. Prepare the DSH host: clone the pinned baseline, apply patches, build, install the plugin
make setup DSH_ROOT=../deepseek-harness

# 4. Start the development host
make dev DSH_ROOT=../deepseek-harness

DSH_ROOT must point outside this repository. The Makefile default is $(abspath ../../deepseek-harness), which resolves from agentengine/agentkit-studio to a sibling checkout under agent-sdk.

What make setup does

make setup is a sequential composite target; any failing step stops the run:

StepCommandPurpose
1node scripts/development-doctor.mjs --tools-onlyValidate the Node version, dev headers, and git/make/cc/pnpm
2pnpm install --frozen-lockfileInstall dependencies; a stale lockfile fails here
3make dsh-bootstrapClone DSH at the pinned ref into DSH_ROOT, verify commit, install its dependencies
4node scripts/prepare-development.mjsApply the patch series; an existing checkout is never reset
5node scripts/build-product-host.mjs --script build:officialBuild the DSH host artifacts
6make profile-installPack the current plugin and install it into the DSH_PROFILE profile
7make doctorRe-check baseline, patches, artifacts, and the installed profile

Keep the DSH checkout outside the repository

dsh-bootstrap does exactly two things: clone when the checkout is missing, then verify HEAD equals the commit in dsh-pin.json. It never copies DSH sources into this repository and never resets an existing checkout.

# Show the pinned DSH baseline
node scripts/check-dsh-pin.mjs

The printed version, commit, ref, patchDirectory, patchedTree, and maintenanceSource are the entire build input. check-dsh-pin also verifies that engines.dsh in package.json, requiredDsh in studio.plugin.json, the patch manifest, and pnpm-lock.yaml all agree — any drift fails the check.

Isolate the data directories

A development runtime writes state into two directories. Point them at temporary paths so your daily profile stays clean:

VariableContentsSuggested value
DSH_HOMEDSH host data, including profiles/<name>A temporary directory outside the repository
AGENTKIT_HOMEStudio's own runtime dataA temporary directory outside the repository
DSH_PROFILEWhich profile to use (defaults to agentkit-studio)Keep the default or create a new one
DSH_HOST / DSH_WEB_PORTDevelopment host bind address (defaults to 127.0.0.1:3098)Change these on a port conflict
export DSH_HOME="$(mktemp -d)/dsh"
export AGENTKIT_HOME="$(mktemp -d)/agentkit"
make dev DSH_ROOT=../deepseek-harness

Why isolation is mandatory

profile-install writes into DSH_HOME, and prepare-development changes the working tree of the DSH checkout. With temporary directories you can delete the whole experiment and start over without touching an installed desktop build.

The daily development loop

What you are verifyingCommandNotes
Browser UImake devRepack the plugin → install the profile → start the web host
Repack onlymake profile-installPacks, then installs by digest
Source-linked pluginpnpm build:clientRequired after editing src/client/
Desktopmake desktop-devBuild Electron inputs and start the dev runtime
Environmentmake doctorRead-only diagnostics; resets nothing

dist/ is generated. Git ignores it, but the files allowlist in package.json ships it — do not hand-edit it and do not commit it.

Common failures

SymptomCauseFix
Node.js … 低于安全基线Runtime predates the security baselineInstall 24.22.1 or newer per .node-version
Studio 需要 pnpm@10.33.2Corepack not enabled or wrong versionRun corepack enable and retry
DSH checkout 不是 … 基线Checkout HEAD differs from the pinned commitRe-clone, or use a fresh DSH_ROOT
DSH 原生模块需要 Node 开发头文件Node installed without include/nodeUse an official distribution or add the headers
已存在但不是 Git checkoutDSH_ROOT points at a plain directoryEmpty that directory or choose another path
Port already in useDSH_WEB_PORT conflictmake dev DSH_WEB_PORT=3099
Patch apply result mismatchCheckout has extra changesUse an isolated DSH_ROOT; the tool preserves your state instead of resetting

Cleaning up

# Remove local packaging output (files under .artifacts)
make clean

# Experiment: delete the isolated directories
rm -rf "$DSH_HOME" "$AGENTKIT_HOME"

Next: run Gates and verification to confirm your change passes the full check before you commit.

On this page