Harness plugin docs (ours vs upstream)

English | 中文

This page is the delta. Cordis and Harness plugin APIs live in official DeepSeek Harness docs. This repository does not vendor deepseek-harness and does not copy those tutorials. Package identity, homes, layout, and gates stay in conventions.md. How to create / install stays in workflow.md § Create.

If an official page disagrees with a pinned @deepseek-ai/* package, the pin in versions.json dshRc (currently 0.1.1-rc.2) wins.

Official docs (read, do not copy)

Need	English	中文
First Harness plugin (apply, inject, ctx.effect)	Your first plugin	第一个插件
Fiber lifecycle, HMR, dispose	Plugins and lifecycle	插件与生命周期
Cordis ideas (ctx, services, events)	Cordis primer	Cordis 入门
Hands-on Cordis (harness repo scratch dir)	Cordis tutorial	Cordis 教程
Tool DSL	Build a tool	开发工具
Plugin config	Plugin configuration	插件配置

The Cordis tutorial and “your first plugin” assume a harness checkout. Use them for API shape only.

Do not follow from the official first-plugin path

Official tutorial	This repo
Clone deepseek-harness; mkdir scratch-plugin	Do not clone or vendor the harness. pnpm new <slug> → plugins/<slug>/
Absolute path to src/*.ts in a cordis.yml overlay	Profile loads lib/. Git install is #path:plugins/<slug>. prepare / tsdown stay inside the package
pnpm dsh web --patch … on 3080	Develop in a dedicated topic worktree. Live sandbox uses link-plugin + pnpm dev → xtz --sandbox on 3081 only in the clean-main hub or a bounded transfer. Never steal official 3080
node --import tsx / no build	Build lib/. @deepseek-ai/* stays external (deps.neverBundle: true)
import { … } from '@deepseek-ai/dsh-tools'	Do not value-import dsh-tools. Register a plain tool object on ctx.tools
Hand-written overlay id / file path	Four names agree: directory, package.json name, cordis.patch.yml name, patch id
Config examples in the harness tree	Exported Schemastery Config on the plugin

Pits official pages do not cover

• Isolated Git #path:plugins/<slug> must prepare without this monorepo (pnpm check:path).
• Deterministic gates run in the topic worktree without 3081. In the clean-main hub or a bounded transfer, pnpm dev rebuilds lib/ and restarts host output on :3081; Client lib/client.js is host HMR (hard-refresh if the UI did not update).
• process.cwd() under pnpm dev is this checkout. Bind-then-work plugins wait for the user to confirm the target (conventions.md § Onboarding and first work).
• Two homes. Plugin source stays in its dedicated topic worktree; link-plugin targets that checkout's .dsh-home, while live 3081 normally belongs to the clean-main hub. Do not link: this repo into ~/.dsh.

Add a row here only when the same upstream-vs-us trap repeats. Do not paste Cordis API tables into this file.