插件开发知识库PerryLink/dsh-plugin-guide

🐳 dsh-plugin-guide
- 1024 商店渠道：npm i -g dsh1024 一次，然后 dsh1024 plugin --profile web add dsh-plugin-guide（计入 deepseek1024.com 安装排名）。
Gitee

构建 DeepSeek Harness 插件所需的一切。

官方文档存档 · Cordis 入门 · 社区深度解析 · 久经考验的陷阱 · 智能体技能 · CLI 工具链

官方仓库。 这是 dsh-plugin-guide 唯一的官方仓库，由 PerryLink 维护。其他账号下的同名仓库均无关联。

License
DSH plugin
dsh-doctor
Node
CI
Version
npm version
npm downloads

English · 简体中文 · Español · Português · हिन्दी

兼容性

| 层面 | 状态 |
|---|---|
| Harness | DeepSeek Harness dsh-v0.1.5-rc.2（适配于 2026-09-09）：会话信封保留其可忽略字段，仅用于已存储日志的读取兼容性——Session.append 仍无法写入该字段，因此审计门禁行为保持不变。已于 2026-09-11 针对 dsh-v0.1.5-rc.2 master 检出进行验证（完整门禁链 + profile 安装冒烟测试）。 |
| Node | ^22.19.0 || >=24.0.0（DeepSeek Harness 运行时） |
| 平台 | 全部（纯 ESM 包；无原生代码，无网络） |
| 模型 | 任意（无模型交互） |

你将获得

dsh-plugin-guide 是 DSH 插件开发知识库加上 CLI 工具链，打包为一个可安装的 bundle。知识库注册为 dsh-plugin-guide 智能体技能（在每个会话目录中可见，按需加载工作流步骤、官方文档和社区深度解析）；dsh-plugin-dev CLI 在其之上增加了三个机械层。

- 插件契约与硬性规则 —— effects/disposers、waterfall next()、模型可见 ⟺ 已记录、Schemastery 配置。
- 官方文档存档 — 官方仓库文档的逐字副本（英文 + 中文），在最后一次验证快照时与上游逐字节一致。
- Cordis 入门 — 五个核心概念与机制时间线（repository-plugin 于 0809 引入，0811 移除；两条安装渠道）。
- 20+ 真实世界陷阱，附根因 + 修复方案（cordis 双副本、tsconfig 三件套、多帧 zstd 会话、Windows 目录联接、过期的 npm latest……）。
- 社区深度剖析 — 归档了 114 个社区仓库（其中 15 个深度剖析），外加一份完整的来源索引，每个事实都可追溯到其出处。
- CLI 工具链 — dsh-plugin-dev new / check / verify：脚手架、静态检查与打包验证 DSH 插件；每项检查都可回溯到它所执行的技能章节。

知识库

| 路径 | 说明 |
|---|---|
| SKILL.md | dsh-plugin-guide 智能体技能：硬性规则 + 基于任务的开发路径 |
| package.json · cordis.patch.yml · index.js | 可安装的 DSH 包：dsh.bundle.patch 清单 + 注册该技能的入口点 |
| guide/plugin-dev-guide.md | 完整开发指南（10 章） |
| guide/quick-reference.md | 单页速查表（5 种语言） |
| guide/links.md | 精选 URL 索引：官方开发文档（站点 ↔ 本地副本）+ 社区文档链接 |
| references/official-docs/ | 官方仓库文档的逐字副本（英文 + 中文） |
| references/.md | 研究报告：仓库文档、网站、Cordis、论文、社区生态、114 仓库归档（15 个深度剖析） |
| scripts/ | 幂等下载脚本 + 完整性检查器 + 主题快照生成器 |
| bin/ · src/cli/ · dist/ | dsh-plugin-dev CLI：脚手架、检查器、验证器（TypeScript，tsdown 打包） |
| templates/ | TS + JS 脚手架骨架：契约模板、Config、测试、cordis.patch.yml、五种语言的 README |
| downloads/ | 原始快照 — 由 scripts/ 生成，不提交 |

CLI 工具链

该包附带零运行时依赖的 dsh-plugin-dev CLI（bin/ → tsdown 打包的 dist/dsh-plugin-dev.js）。每项检查都会引用它所执行的技能章节，因此智能体可以持续手动审计。

dsh-plugin-dev new  [--lang ts|js] [--dir ] [--force] [--git]
dsh-plugin-dev check [--cwd ] [--json] [--strict]
dsh-plugin-dev verify [--cwd ] [--dsh ] [--pnpm ]

| 子命令 | 功能 |
|---|---|
| new  | 搭建 TS 或 JS 插件仓库：src/index.ts 契约模板、Schemastery Config、测试、tsdown/vitest、带注释的 cordis.patch.yml、五种语言的 README。幂等；未加 --force 时拒绝非空目标。 |
| check | 静态检查：cordis.patch.yml 有效性、package.json 元数据（dsh.bundle.patch 指针、peer 依赖、engines、files 白名单）、五种语言 README 一致性、工程红线模式。输出可供 CI 消费的 JSON。 |
| verify | pnpm pack，然后在一个干净的 mkdtemp DSH_HOME 配置文件中安装/启动/卸载该 bundle（与 verify:self-contained 保持一致）。失败时会报告日志尾部以及建议。 |

CLI 配置

CLI 没有硬编码的可调参数——每一项都是一个标志或环境变量。

| 可调参数 | 标志 | 环境变量 | 默认值 |
|---|---|---|---|
| 模板目录 | — | DSH_PLUGIN_DEV_TEMPLATES | /templates |
| dsh 二进制文件 | --dsh | DSH_PLUGIN_DEV_DSH | dsh |
| pnpm 二进制文件 | --pnpm | DSH_PLUGIN_DEV_PNPM | pnpm |
| 安装/打包超时 | --timeout | DSH_PLUGIN_DEV_TIMEOUT | 300000 ms |
| 无头冒烟测试超时 | --smoke-timeout | DSH_PLUGIN_DEV_SMOKE_TIMEOUT | 120000 ms |

上游路线图

dsh-plugin-dev 是官方插件开发 CLI 的上游候选（计划项 C12）：脚手架/检查器/验证器是机械层，而 SKILL.md + guide/ 则保持为认知层。

快速开始

1. install the bundle into your profile
dsh plugin --profile web add "github:PerryLink/dsh-plugin-guide#main"

or from npm (published releases)
dsh plugin --profile web add dsh-plugin-guide

2. restart and verify the row
dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-guide'

然后只需向你的 agent 提问：“使用 dsh-plugin-guide 技能为我构建一个……插件。”*

或者直接驱动 CLI：

npx dsh-plugin-guide new hello-plugin            # scaffold a TS plugin repo
npx dsh-plugin-guide check --json                # static-check it
npx dsh-plugin-guide verify                      # pack + clean-profile smoke

安装与卸载

- git 渠道（最新的 main）：dsh plugin --profile web add github:PerryLink/dsh-plugin-guide# —— 固定一个提交以保证可复现性；入口点是纯 ESM JS，无需构建步骤。
- npm 渠道（已发布的版本）：dsh plugin --profile web add dsh-plugin-guide。
- tarball 渠道：在本仓库中运行 pnpm pack，然后执行 dsh plugin --profile web add ./dsh-plugin-guide-.tgz。
- 卸载：dsh plugin --profile web remove dsh-plugin-guide。

作为普通 agent 技能复制

你也可以将整个文件夹复制到你的 agent 技能目录中（相对路径保持不变）：

Windows (PowerShell)
pwsh -File scripts/install-skill.ps1
-Target "$env:USERPROFILE\.deepseek\skills\dsh-plugin-guide"   # or \.agents\skills\dsh-plugin-guide

macOS / Linux
pwsh -File scripts/install-skill.ps1 -Target ~/.deepseek/skills/dsh-plugin-guide   # or /.agents/skills/dsh-plugin-guide

安装程序会跳过 downloads/（生成的）和 .github/，然后逐字节验证每个复制的文件。手动对整个文件夹执行 Copy-Item -Recurse 也可以。

配置
该技能包不暴露任何 Schemastery Config——它将知识库注册为 agent 技能，没有任何可调参数。dsh-plugin-dev CLI 从标志和 DSH_PLUGIN_DEV_* 环境变量读取其可调参数（参见 CLI 工具链）。

工具与界面

| 界面 | 类型 | 说明 |
|---|---|---|
| dsh-plugin-guide | 技能 | 通过 ctx.skills 注册；按需加载 SKILL.md + ./guide/ + ./references/ |
| dsh-plugin-dev | bin（CLI） | new / check / verify 子命令；不是 DSH 插件行 |

权限与数据

- 权限：在其 workshop 清单中声明 filesystem:read。
- 数据：只读——读取其自身捆绑的 guide/ 和 references/ 文件。无网络请求、无写入、无模型调用。

安全边界

- 只读知识库。 该捆绑包只读取自身文件；它从不写入、从不调用网络、从不调用模型。
- 官方文档为逐字副本。 references/official-docs/ 在此处从不编辑；请向上游报告问题，并且仅使用 scripts/sync-official-docs.ps1 重新同步。
- 分发边界。 捆绑的第三方内容保留其上游许可证；参见 NOTICE.md（例如 downloads/ 仅限本地；awesome-dsh-plugins 不得再分发）。

已知限制

- 官方文档是快照。 当上游变动时，使用 scripts/sync-official-docs.ps1 重新同步；新鲜度戳记和提交哈希引用 references/official-docs/SNAPSHOT.md。
- downloads/ 是生成的，而非提交的。 原始快照（社区仓库归档、Discussions、文章）必须在使用前用脚本生成。
- awesome-dsh-plugins 内容仅限本地。 其上游声明了内部使用限制，因此它不会随仓库再分发。

保持更新

pwsh -File scripts/sync-official-docs.ps1                     # 从本地检出逐字复制文档
pwsh -File scripts/download-sources.ps1                       # 官方网站/文档、Cordis、论文
pwsh -File scripts/download-community-repos.ps1               # 社区仓库（codeload tarball）
pwsh -File scripts/download-community-articles.ps1            # 中/英/HN 社区文章
pwsh -File scripts/archive-discussions.ps1                    # 官方 Discussions（需要 $env:GH_TOKEN）
pwsh -File scripts/gen-topic-snapshot.ps1 -OutDir        # dsh-plugin 主题普查
pwsh -File scripts/verify-kit.ps1 -Checkout         # 关键路径 + 链接扫描 + 文档漂移

开发

技能包（index.js）是纯 ESM，无构建步骤；dsh-plugin-dev CLI 是由 tsdown 构建的 TypeScript。门禁：

pnpm install --frozen-lockfile
pnpm run typecheck && pnpm run typecheck:ci
pnpm test
pnpm run build
pnpm run verify:artifacts        # 自用自检 + 脚手架冒烟（无网络）
pnpm run verify:self-contained   # 打包 + 干净配置安装/启动/卸载冒烟
pnpm packpowershell
pwsh -File scripts/verify-kit.ps1   # 关键路径 + 链接扫描（使用 -Checkout  时还包括文档漂移检查）

主题

dsh、deepseek-harness、dsh-plugin、cordis、agent-skill、plugin-development、knowledge-base、cli、scaffold、checker

贡献者

- PerryLink — 创建者与维护者：知识库内容、可安装包转换、生态系统提交以及社区工程。
- 日常维护由 DeepSeek Harness 智能体协助（它们没有 GitHub 账号，此处列出是为了透明，而非作为贡献者）。

PerryLink DSH 插件家族

本项目是由 PerryLink 维护的 40 个 DeepSeek Harness 插件之一。如果这个对你有帮助，其他的很可能也会：

| 插件 | 一句话简介 |
|---|---|
| dsh-auto-review | 审批链上的第二模型自动审查，默认故障关闭 | |
| dsh-background-agents | 持久后台子智能体，带 Web UI 侧边栏、消息传递与中断 | |
| dsh-budget | DeepSeek Harness 的成本治理：预算、碳排与延迟集于一个面板。 | |
| dsh-checkpoint-rewind | 等同于 Claude Code /rewind：快照、会话分叉、一键恢复 | |
| dsh-claude-move | 将 Claude Code 会话、记忆、技能和 CLAUDE.md 迁移到 DSH | |
| dsh-click | 面向 DeepSeek Harness 的跨平台原生桌面控制——Windows 优先。 | |
| dsh-composer-history | Web 编辑器的终端风格输入历史：方向键、Ctrl+R 搜索 | |
| dsh-data-quality | 数据集质量检查与引用交叉核对（此处消费的可选数值桥接） | |
| dsh-defend | 面向 DeepSeek Harness 的提示注入、越狱与机密泄露防御。 | |
| dsh-doublecheck | 工程纪律守卫：需求拷问、测试门禁、对抗性审查 | |
| dsh-draw | 面向 DeepSeek Harness 的统一静态图像生成路由。 | |
| dsh-fast | 面向 DeepSeek Harness 的只读性能诊断。 | |
| dsh-fund-research | 面向中国公募基金的确定性研究报告 | |
| dsh-github | 面向 DSH 的 GitHub PR/issue 集成，每次写入均需审批 | |
| dsh-industry-research | 行业研究编排，通过本插件的 ctx.researchReport.assemble 封存其交付物 | |
| dsh-library | 面向 DeepSeek Harness 的本地文档知识库。 | |
| dsh-local-ai | 面向 DeepSeek Harness 的本地模型（Ollama）集成。 | |
| dsh-lsp-actions | 基于语言服务器的 LSP 诊断、格式化、补全、代码操作与重命名 | |
| dsh-mask | PII 脱敏中间件：在模型边界处匿名化，在展示层还原 | |
| dsh-mcp-panel | 只读 MCP 运行时面板：/mcp 命令 + 设置标签页，显示状态、工具与错误 | |
| dsh-memento | 需审批的跨会话记忆：ctx.memory 接缝 + SQLite + memory 工具 | |
| dsh-observe | 面向 DeepSeek Harness 的 OpenTelemetry 与 Langfuse 可观测性导出器。 | |
| dsh-output-styles | 等同于 Claude Code outputStyles 的运行时风格切换 | |
| dsh-permission-rules | Claude Code 风格的声明式 allow/deny/ask 权限规则，带审计 | |
| dsh-reach | 多渠道审批/提问桥接：微信/Telegram/飞书，会话控制台 | |
| dsh-research-report | 可验证的研究报告引擎：内容寻址的证据账本与封存版本 | |
| dsh-score | 面向 DeepSeek Harness 插件的多维度质量评分。 | |
| dsh-session-pin | 在 Web 侧边栏中固定会话，并保持持久排序 | |
| dsh-session-sync | 面向 DeepSeek Harness 的跨设备会话同步——你的会话存储的专用 git 镜像。 | |
| dsh-skill-pack-security | 安全审计技能包：密钥扫描、依赖与供应链审查 | |
| dsh-talk | 面向 DeepSeek Harness 的语音优先会话循环：与它对话，听它回答。 | |
| dsh-test-drive | 面向 DeepSeek Harness 插件的隔离安装与冒烟测试试驾。 | |
| dsh-ticktick | TickTick/滴答清单任务桥接：会话头部面板 + 11 个工具 | |
| dsh-translate | 面向 DeepSeek Harness 的厂商参数转换与确定性 JSON 修复。 | |
| dsh-wechat | 微信 ↔ DSH 桥接（腾讯 iLink 机器人）：文本/图片/文件/语音，聊天内审批 |
| dsh-autotier | 自动进行强/廉价模型层级路由，具备确定性风险防护和 /tier 命令 | |
| dsh-catalog | PerryLink 系列的 DSH Desktop Market 标准目录源 | |
| dsh-cert-mcp | 只读 MCP 服务器，公开认证注册表：等级、快照和五维证据 | |
| dsh-kit | 一键安装核心系列组件的入门包 | |
| dsh-plugin-certification | 社区认证注册表，提供可复现检查的等级和徽章 | |
| dsh-plugin-kit | 面向 PerryLink DSH 插件的共享零运行时依赖工具包 | |
| dsh-plugin-portal | 零依赖静态门户，将整个插件系列渲染为单个页面 | |
| dsh-plugin-upgrade-015 | 合并的 0.1.3-alpha.1 → 0.1.5-rc.1 升级通道卡片，外加零依赖接缝扫描器 | |
| dsh-team-rooms | 跨会话团队房间：共享消息总线、任务板和时间线 | |
| dsh-plugin-doctor | 面向 DSH 插件的零依赖静态 + 沙箱冒烟检测器 | |

免责声明

由社区维护，并非 DeepSeek 官方产品。DeepSeek Harness 处于开发者预览阶段，会发布破坏性变更；如有疑问，references/official-docs/ 中的官方文档为准。

从 DSH Desktop Market 安装

所有 PerryLink 插件均可在内置的 DSH Desktop Market 中浏览：Market → Sources → add source → 粘贴 https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → 选择它。安装仍需通过 Market 的 npm 身份验证和你的确认。

许可证

Apache License 2.0 © 2026 dsh-plugin-guide 贡献者 — 我们自己的文本（SKILL.md、guide/、references/、scripts/、本 README）采用 Apache-2.0；捆绑的第三方内容记录在 NOTICE.md 中。