dsh-cordis-plugin-kit

DSH Cordis Plugin Kit

中文 | English

中文

面向 DeepSeek Harness/Cordis 插件开发的离线规范、脚手架与质量门工具。它把常用开发约定和 Cordis 特有的生命周期、依赖注入、服务、事件、配置及 HMR 规则固化为可执行检查，避免每次开发都重新查阅在线教程。

质量门可以发现已知模式和回归，但任何静态或动态工具都不能数学上保证代码绝无功能、性能或安全问题。高风险插件仍需要人工审查、真实依赖集成测试和针对业务的威胁建模。

当前兼容基线：DeepSeek Harness 0.1.2-rc.1、@deepseek-ai/cordis 4.0.2。

0.2.1 修复 Windows 下 npm/pnpm/yarn 的 .cmd 启动问题及超时后的子进程清理；生成项目支持含空格和中文的路径，Git hooks 由 Git 执行并保留 LF 换行。CI 覆盖 Windows/Linux、Node.js 22/24；本包没有新增生产依赖。Windows 使用 Git hooks 需要安装 Git for Windows。运行时检查仍需要目标项目安装 @deepseek-ai/cordis 开发依赖。

功能

• 内置 35 条离线 Cordis/DSH/Node.js/自动化规范，可按分类或 JSON 输出
• 生成可安装 DSH bundle、生命周期测试、质量预算、Git hooks、代理指令和 CI 适配文件
• 不执行代码的静态检查：manifest、bundle patch、inject、effect、Config、事件、工具契约、秘密和危险 API
• 使用项目原有包管理器执行测试，并提供超时与输出上限
• 在隔离子进程中使用目标项目的真实 Cordis 版本执行 apply / dispose
• 重复加载与卸载，测量 p50/p95 延迟及堆增长，按项目预算阻断交付
• 保存时执行防抖快速检查，提交/推送/打包时自动升级质量门；开发监听器只随 pnpm dev 运行，不安装系统常驻进程
• 统一 ci 核心兼容 GitHub、GitLab、Gitee 及任意可运行 Node.js 的流水线
• 安装到 DSH 后提供 ctx.cordisPluginKit 规范、静态检查和显式质量门服务
• 零生产依赖

安装

作为开发工具安装：

pnpm add -D dsh-cordis-plugin-kit

作为 DSH bundle 安装：

dsh plugin --profile web add dsh-cordis-plugin-kit

快速开始

npx dsh-cordis-plugin-kit init ./my-cordis-plugin --name my-cordis-plugin --ci auto
cd my-cordis-plugin
pnpm install
pnpm check
pnpm dev

init 默认使用 balanced 自动化模式：创建本地 Git 仓库，配置版本库级 core.hooksPath=.githooks，生成 AGENTS.md，并根据 Git remote、现有流水线或 package.json.repository 选择 CI。不会修改全局 Git 配置。目标已设置其他 hooksPath 或已有 CI 文件时会保留原内容并给出合并提示。

自动工作流

关键节点	触发方式	检查内容
保存	pnpm dev 文件监听，或 DSH/Codex 按 AGENTS.md 调用	静态、Cordis 规则、安全模式
提交	Git pre-commit hook	严格静态检查、单元测试
推送	Git pre-push hook	严格检查、测试、真实 Cordis apply/dispose
打包	npm/pnpm prepack	完整运行时与性能门；避免递归打包
push / PR / MR	托管平台流水线	测试、运行时、性能、安全和包内容复核

检查结果统一写入 .cordis-kit/reports/：result.json、junit.xml、security.sarif 和 summary.md。失败时所有平台使用同一个非零退出码语义。

监听器不是后台服务。它只在显式运行 pnpm dev / dsh-cordis-kit watch . 时存在，退出终端即停止。即使未启动监听器，Git hooks 和远端 CI 仍是不可绕过的后续质量门。

已有项目可以直接检查：

npx dsh-cordis-plugin-kit standards
npx dsh-cordis-plugin-kit check . --strict
npx dsh-cordis-plugin-kit test . --timeout 60000
npx dsh-cordis-plugin-kit debug . --provide tools,systemPrompt
npx dsh-cordis-plugin-kit perf . --iterations 50 --max-apply-ms 80
npx dsh-cordis-plugin-kit checkpoint pre-push .
npx dsh-cordis-plugin-kit ci .

命令

standards

读取包内固化的规范，不访问网络：

dsh-cordis-kit standards --category lifecycle
dsh-cordis-kit standards --json

check

只读取目标项目，不导入或执行目标代码。默认 error 导致失败；--strict 会让 warning 也导致失败。

dsh-cordis-kit check . --strict
dsh-cordis-kit check . --json

test

静态质量门通过后，根据 pnpm-lock.yaml、yarn.lock 或 npm 选择项目现有包管理器执行测试。命令使用参数数组启动，不经过 shell。

checkpoint、watch 与 ci

dsh-cordis-kit checkpoint save .
dsh-cordis-kit checkpoint pre-commit .
dsh-cordis-kit checkpoint pre-push .
dsh-cordis-kit checkpoint release .
dsh-cordis-kit watch . --debounce 800
dsh-cordis-kit ci .

checkpoint 按关键节点逐级增加检查；watch 对源码和 Cordis/DSH 配置保存进行防抖检查并忽略依赖、构建产物和自身报告；ci 始终执行平台无关的完整质量门。

为已有项目生成或补充托管平台适配：

dsh-cordis-kit automation setup . --ci auto
dsh-cordis-kit ci setup . --provider auto
dsh-cordis-kit ci setup . --provider github
dsh-cordis-kit ci setup . --provider gitlab,gitee
dsh-cordis-kit ci setup . --provider all

• GitHub：.github/workflows/cordis-quality.yml
• GitLab：.gitlab-ci.yml；若已存在则生成 .cordis-kit/ci/gitlab.include.yml，不覆盖用户文件
• Gitee Go：.workflow/MasterPipeline.yml、BranchPipeline.yml、PRPipeline.yml；仓库需先在网页端开通一次 Gitee Go
• 通用 CI：.cordis-kit/ci/README.md 中的三条平台无关命令，可用于 Jenkins、Buildkite、Drone、Woodpecker、Azure Pipelines 或企业内部系统

这些适配不需要平台 API Token；只需流水线具备检出代码、Node.js 22+ 和安装依赖的能力。私有 npm 源或私有依赖仍按企业原有凭据管理方式配置。 生成器会依据 lockfile 和 packageManager 自动选择 pnpm、Yarn 或 npm 的安装/执行命令；质量判定仍由同一个核心完成。

debug

使用目标项目安装的 @deepseek-ai/cordis 在子进程中加载入口，执行一次完整 Fiber apply → ACTIVE → dispose。缺少 inject 服务时会显示 PENDING；可用 --provide serviceA,serviceB 提供惰性测试替身。

perf

从 cordis-kit.json 读取预算，重复创建和销毁 Fiber：

{
  "entry": "./index.js",
  "config": {},
  "provide": [],
  "performance": {
    "iterations": 30,
    "maxApplyP95Ms": 50,
    "maxDisposeP95Ms": 50,
    "maxHeapGrowthKb": 1024
  }
}

运行时命令会执行目标插件代码，应只用于你信任的项目。子进程默认 30 秒超时，静态 check 则始终不执行代码。

Cordis 专项质量门

• 必需服务通过 inject 声明；可选服务在使用处通过 ctx.get() 探测
• 定时器、连接、watcher、服务器、子进程等资源必须归属 ctx.effect() 并提供 disposer
• Service 使用唯一服务名并通过声明合并提供类型
• 事件采用 namespace/action；waterfall 观察者必须调用 next()
• Config 必须是 Standard Schema，部署可变参数不得硬编码
• bundle patch 使用稳定 id，模块名适合 npm 安装解析
• HMR、依赖消失和配置更新后不得残留监听器、服务或异步资源
• DSH 工具同时具备参数 schema、规范输出、render 和执行函数

完整规则见 STANDARDS.zh-CN.md。

开发验证

pnpm check
pnpm e2e
npm pack

许可证

MIT

English

DSH Cordis Plugin Kit provides offline standards, scaffolding, and quality gates for DeepSeek Harness/Cordis plugin development. It turns general development conventions and Cordis-specific lifecycle, dependency injection, service, event, configuration, and HMR rules into executable checks, so developers do not need to revisit the online tutorials for every plugin.

Quality gates can detect known patterns and regressions, but no static or dynamic tool can mathematically guarantee that code is free of functional, performance, or security issues. High-risk plugins still require manual review, integration tests with real dependencies, and application-specific threat modeling.

Current compatibility baseline: DeepSeek Harness 0.1.2-rc.1 and @deepseek-ai/cordis 4.0.2.

Version 0.2.1 fixes Windows npm/pnpm/yarn .cmd execution and timeout process-tree cleanup. Generated projects support spaces and Unicode paths; Git executes hooks with LF line endings. CI covers Windows/Linux and Node.js 22/24. No production dependencies were added. Hooks require Git for Windows; runtime checks require the target project's @deepseek-ai/cordis development dependency.

Features

• 35 built-in offline Cordis, DSH, Node.js, and automation rules, with category filtering and JSON output
• Generate an installable DSH bundle, lifecycle tests, quality budgets, Git hooks, agent instructions, and CI adapters
• Static checks that never execute target code: manifest, bundle patch, inject, effect, Config, events, tool contracts, secrets, and dangerous APIs
• Run tests with the project's existing package manager, with timeout and output limits
• Execute apply / dispose in an isolated child process using the target project's actual Cordis version
• Repeatedly load and unload plugins, measure p50/p95 latency and heap growth, and enforce project-level budgets
• Run debounced checks on save and progressively stronger gates on commit, push, and package; the watcher only lives while pnpm dev is running
• Use one platform-neutral ci core on GitHub, GitLab, Gitee, and any Node.js-capable runner
• Provide standards, static checks, and explicit quality gates through ctx.cordisPluginKit when installed in DSH
• Zero production dependencies

Installation

Install as a development tool:

pnpm add -D dsh-cordis-plugin-kit

Install as a DSH bundle:

dsh plugin --profile web add dsh-cordis-plugin-kit

Quick Start

npx dsh-cordis-plugin-kit init ./my-cordis-plugin --name my-cordis-plugin --ci auto
cd my-cordis-plugin
pnpm install
pnpm check
pnpm dev

By default, init uses balanced automation: it creates a local Git repository, configures repository-local core.hooksPath=.githooks, writes AGENTS.md, and selects a CI adapter from Git remotes, existing pipeline files, or package.json.repository. It never changes global Git configuration. Existing hooks paths and CI files are preserved and reported for manual merging.

Automated Workflow

Checkpoint	Trigger	Gate
Save	pnpm dev, or DSH/Codex following AGENTS.md	Static, Cordis rules, security patterns
Commit	Git pre-commit hook	Strict static checks and unit tests
Push	Git pre-push hook	Strict checks, tests, real Cordis apply/dispose
Package	npm/pnpm prepack	Full runtime and performance gate without recursive packing
Push / PR / MR	Hosted CI pipeline	Tests, runtime, performance, security, and package review

Every platform receives the same reports in .cordis-kit/reports/: result.json, junit.xml, security.sarif, and summary.md, with consistent non-zero failure semantics.

The watcher is not a daemon. It only runs while pnpm dev or dsh-cordis-kit watch . is active. Git hooks and remote CI remain as later enforcement layers when no watcher is running.

Run the quality gates directly against an existing project:

npx dsh-cordis-plugin-kit standards
npx dsh-cordis-plugin-kit check . --strict
npx dsh-cordis-plugin-kit test . --timeout 60000
npx dsh-cordis-plugin-kit debug . --provide tools,systemPrompt
npx dsh-cordis-plugin-kit perf . --iterations 50 --max-apply-ms 80
npx dsh-cordis-plugin-kit checkpoint pre-push .
npx dsh-cordis-plugin-kit ci .

Commands

standards

Read the bundled standards without accessing the network:

dsh-cordis-kit standards --category lifecycle
dsh-cordis-kit standards --json

check

Read the target project without importing or executing its code. Errors fail the command by default; --strict also treats warnings as failures.

dsh-cordis-kit check . --strict
dsh-cordis-kit check . --json

test

After the static quality gate passes, select the project's existing package manager from pnpm-lock.yaml, yarn.lock, or npm and run its test suite. The command is launched with an argument array and never through a shell.

checkpoint, watch, and ci

dsh-cordis-kit checkpoint save .
dsh-cordis-kit checkpoint pre-commit .
dsh-cordis-kit checkpoint pre-push .
dsh-cordis-kit checkpoint release .
dsh-cordis-kit watch . --debounce 800
dsh-cordis-kit ci .

checkpoint adds progressively stronger gates at development milestones. watch debounces source and Cordis/DSH configuration saves while ignoring dependencies, build output, and its own reports. ci always executes the full platform-neutral gate.

Generate adapters for an existing repository:

dsh-cordis-kit automation setup . --ci auto
dsh-cordis-kit ci setup . --provider auto
dsh-cordis-kit ci setup . --provider github
dsh-cordis-kit ci setup . --provider gitlab,gitee
dsh-cordis-kit ci setup . --provider all

• GitHub: .github/workflows/cordis-quality.yml
• GitLab: .gitlab-ci.yml; if it already exists, the tool writes .cordis-kit/ci/gitlab.include.yml without overwriting user content
• Gitee Go: .workflow/MasterPipeline.yml, BranchPipeline.yml, and PRPipeline.yml; enable Gitee Go once in the repository UI
• Generic CI: three portable commands in .cordis-kit/ci/README.md for Jenkins, Buildkite, Drone, Woodpecker, Azure Pipelines, or internal systems

No platform API token is required for these quality adapters. The runner only needs a checkout, Node.js 22+, and dependency installation. Private registries and private dependencies continue to use the organization's existing credential mechanism. The generator selects pnpm, Yarn, or npm commands from the lockfile and packageManager; every adapter still delegates pass/fail semantics to the same core.

debug

Load the entry point in a child process with the target project's installed @deepseek-ai/cordis, then execute a complete Fiber apply → ACTIVE → dispose cycle. Missing injected services produce a PENDING state; use --provide serviceA,serviceB to supply lazy test stubs.

perf

Read budgets from cordis-kit.json and repeatedly create and dispose Fibers:

{
  "entry": "./index.js",
  "config": {},
  "provide": [],
  "performance": {
    "iterations": 30,
    "maxApplyP95Ms": 50,
    "maxDisposeP95Ms": 50,
    "maxHeapGrowthKb": 1024
  }
}

Runtime commands execute target plugin code and should only be used with projects you trust. Child processes have a 30-second timeout by default; the static check command never executes target code.

Cordis-Specific Quality Gates

• Declare required services through inject; probe optional services with ctx.get() at the point of use
• Own timers, connections, watchers, servers, child processes, and similar resources through ctx.effect() and return a disposer
• Give each Service a unique name and expose its types through declaration merging
• Use namespace/action event names; waterfall observers must call next()
• Define Config with Standard Schema and avoid hardcoding deployment-specific values
• Use a stable bundle patch id and a module name that npm installation can resolve
• Leave no listeners, services, or asynchronous resources behind after HMR, dependency removal, or configuration updates
• Define DSH tools with an argument schema, specification output, renderer, and execution function

See STANDARDS.zh-CN.md for the complete rule set (currently available in Chinese).

Development Verification

pnpm check
pnpm e2e
npm pack

License

MIT