Cordis 插件工具包hinayoung23/dsh-cordis-plugin-kit

DSH Cordis 插件工具包

中文

面向 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 为 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 执行以及超时进程树清理问题。生成的项目支持空格和 Unicode 路径；Git 以 LF 行尾执行钩子。CI 覆盖 Windows/Linux 以及 Node.js 22/24。未添加任何生产依赖。钩子需要 Git for Windows；运行时检查需要目标项目的 @deepseek-ai/cordis 开发依赖。

功能特性

- 35 条内置离线 Cordis、DSH、Node.js 和自动化规则，支持分类过滤和 JSON 输出
- 生成可安装的 DSH bundle、生命周期测试、质量预算、Git 钩子、agent 指令和 CI 适配器
- 静态检查从不执行目标代码：manifest、bundle patch、inject、effect、Config、事件、工具契约、密钥和危险 API
- 使用项目现有的包管理器运行测试，并带有超时和输出限制
- 使用目标项目实际的 Cordis 版本，在隔离的子进程中执行 apply / dispose
- 反复加载和卸载插件，测量 p50/p95 延迟和堆增长，并强制执行项目级预算
- 在保存时运行防抖检查，并在提交、推送和打包时逐步加强门禁；watcher 仅在 pnpm dev 运行期间存活
- 在 GitHub、GitLab、Gitee 以及任何支持 Node.js 的 runner 上使用同一个平台中立的 ci 核心
- 当安装到 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 使用均衡自动化：它创建一个本地 Git 仓库，配置仓库本地的 core.hooksPath=.githooks，写入 AGENTS.md，并根据 Git 远程仓库、现有流水线文件或 package.json.repository 选择 CI 适配器。它从不更改全局 Git 配置。现有的钩子路径和 CI 文件会被保留，并报告以供手动合并。

自动化工作流

| 检查点 | 触发条件 | 门禁 |
| --- | --- | --- |
| 保存 | pnpm dev，或 DSH/Codex 遵循 AGENTS.md | 静态检查、Cordis 规则、安全模式 |
| 提交 | Git pre-commit 钩子 | 严格静态检查和单元测试 |
| 推送 | Git pre-push 钩子 | 严格检查、测试、真实 Cordis apply/dispose |
| 打包 | npm/pnpm prepack | 完整运行时和性能门禁，且不进行递归打包 |
| 推送 / PR / MR | 托管 CI 流水线 | 测试、运行时、性能、安全和包审查 |

每个平台都会在 .cordis-kit/reports/ 中收到相同的报告：result.json、junit.xml、security.sarif 和 summary.md，并具有一致的非零失败语义。
监视器不是守护进程。它只在 pnpm dev 或 dsh-cordis-kit watch . 处于活动状态时运行。当没有监视器运行时，Git 钩子和远程 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

在不导入或执行目标项目代码的情况下读取该项目。默认情况下，错误会导致命令失败；--strict 还会将警告视为失败。

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；在仓库 UI 中启用一次 Gitee Go
- 通用 CI：.cordis-kit/ci/README.md 中的三个可移植命令，适用于 Jenkins、Buildkite、Drone、Woodpecker、Azure Pipelines 或内部系统

这些质量适配器不需要平台 API 令牌。运行器只需要检出、Node.js 22+ 以及依赖安装。私有注册表和私有依赖项继续使用组织现有的凭据机制。
生成器根据 lockfile 和 packageManager 选择 pnpm、Yarn 或 npm 命令；每个适配器仍将通过/失败语义委托给同一个核心。

debug
在子进程中使用目标项目已安装的 @deepseek-ai/cordis 加载入口点，然后执行完整的 Fiber apply → ACTIVE → dispose 周期。缺少注入的服务会产生 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() 探测可选服务
- 通过 ctx.effect() 持有定时器、连接、监视器、服务器、子进程及类似资源，并返回一个 disposer
- 为每个 Service 提供唯一名称，并通过声明合并暴露其类型
- 使用 namespace/action 事件名；waterfall 观察者必须调用 next()
- 使用 Standard Schema 定义 Config，避免硬编码部署特定值
- 使用稳定的 bundle patch id 和 npm 安装可解析的模块名
- 在 HMR、依赖移除或配置更新后，不留下任何监听器、服务或异步资源
- 使用参数 schema、规范输出、渲染器和执行函数定义 DSH 工具

完整规则集见 STANDARDS.zh-CN.md（目前提供中文版）。

开发验证

pnpm check
pnpm e2e
npm pack

许可证

MIT