AgentKit Studio
Contributing

Contributing

Entry point for working on AgentKit Studio — environment, three gate layers, DSH patch governance, docs style, and the public boundary.

AgentKit Studio is a product plugin, not a fork of DSH. It extends the official DeepSeek Harness (DSH) host and ships product capability as a plugin. That boundary decides how you contribute: change Studio's behavior, follow DSH's public contracts, and never copy the DSH source tree into this repository.

What this chapter solves

Where you are nowStart hereWhat you get
You just cloned the repository and nothing runs yetDevelopment environmentOne copy-pasteable setup path, plus how to isolate the three data directories
You changed something and do not know what to runGates and verificationWhat each of the three gate layers runs, which checks a pull request must pass, and how to localize a failure
You need to change DSH host behaviorPatch governanceThe full loop: maintenance commit → export patch → verify
You are writing or editing docsDocumentation style guidePage skeleton, terminology, link rules, and the 1:1 bilingual contract
You are unsure whether some content may be publicSecurity and public boundaryFourteen red lines and the local self-check commands

Three non-negotiable rules

  1. Single purpose. One pull request does one thing. A behavior change ships with regression coverage; a docs-only change does not also touch code. Mixed scope makes "what is the risk boundary of this change" unanswerable in review.
  2. Every fact traces to source. Each command, default value, enum, and error code must point at a concrete location in Makefile, package.json, scripts/**, ci/**, or src/**. If you cannot point at it, do not write it — every contradictory version number and count in the old docs came from writing from memory.
  3. The public boundary wins. The repository is public. Never commit credentials, customer data, personal paths, internal endpoints, or private deployment evidence. make public-surface-audit and secret-scan block this class of content in CI, historical blobs included.

Run the minimum set before you commit:

make check

This covers the static contract checks and the full unit suite.

When to add another layer

For changes that affect the release package, the patch series, or security, also run make release-check. For the layers and failure localization, see Gates and verification.

Repository map

PathContentsWhat you change here
src/Studio host services, API adapters, product pluginProduct behavior, contracts, runtime adapters
src/client/Browser modules and DSH UI extensionsInterface and interaction
src/providers/Integration for the three runtimesRuntime admission and execution paths
src/contracts/operations.mjsControl protocol, 134 operationsContract changes must update tests
patches/dsh-v0.2.2-rc.1/53 patches against the pinned DSH baselineHost compatibility fixes
host-source/Archived maintenance branch bundlesPatch provenance and verification
scripts/Development, verification, packaging, release toolingGates and automation
ci/CI-specific scripts and the Gitleaks configGate execution environment
tests/Unit, contract, and packaging regressionsRegression coverage
docs-site/Source of this siteDocumentation and navigation

What you need

DependencyVersionNotes
Node.js24.22.1Security baseline 22.23.4+ / 24.22.1+ / 26.12.1+, per .node-version
pnpm10.33.2Enabled through Corepack; must match packageManager
GitAny recent versionPatch governance needs full history; CI uses fetch-depth: 0
Make and a C toolchainAny recent versionDSH native modules compile
DSH checkoutThe pinned baselineLives outside this repository and is used to apply patches

Native Windows is not supported for these Make targets; use WSL2. Full steps are in Development environment.

The minimum docs change

Documentation changes go through gates too, but the path is shorter:

  1. Read the page skeletons and terminology in Documentation style guide and confirm the page type.
  2. Edit foo.mdx and foo.en.mdx together — 1:1 bilingual coverage is mandatory; half a pair fails the build.
  3. Run the four self-check commands under docs-site/ (pairing, leftover markers, internal information, links ending in .mdx).
  4. Run make public-surface-audit to confirm nothing crosses the boundary.
  5. Confirm git diff --check is clean before you commit.

Do not edit meta.json

Sidebar order is maintained centrally in meta.json / meta.en.json. When adding a page, confirm where it belongs in navigation instead of inserting an entry yourself — the pages order must match exactly between the two locales.

Frequently asked questions

I only want to change one line of docs. Do I need a DSH checkout? No. Docs changes only need Node.js and the repository dependencies: run pnpm install --frozen-lockfile, then edit the .mdx files under docs-site/content/docs/. A DSH checkout is only required when you need to verify against a real host.

My pull request is green locally but red in CI. Why? Three most common causes: pnpm-lock.yaml disagreeing with package.json (so --frozen-lockfile fails); a new dependency entering the browser bundle (the client gate's size budget); or a commit carrying a non-ignored temporary file or credential (the public surface audit). Work through the failure table in Gates and verification.

Must I write both Chinese and English? Yes. 1:1 bilingual coverage is a build-time constraint: a missing English page, a meta.json versus meta.en.json order mismatch, or a heading-structure difference each fail the docs-site-i18n test.

May I edit a .patch under patches/ directly? No. A patch is an export of the maintenance branch; editing it breaks the digest, manifest, and application-order checks. Use the four-step workflow in Patch governance.

How long does make check take? The static contract checks take seconds; the full unit suite depends on the machine. make release-check is minutes because it also packs and scans history. In CI the public-gate job has a 35-minute timeout.

Getting help

  • Run the minimum set in Gates and verification before asking; it surfaces most problems locally.
  • Stuck on the DSH checkout version or the patch series: see "Common failures" in Patch governance.
  • Unsure whether content crosses the boundary: read Security and public boundary, or delete it under the strictest reading.
  • Found a security vulnerability: do not open a public issue; report it privately through the channel in SECURITY.md.

On this page