# dsh-plugin-kit

**Repository Path**: tufeiping/dsh-plugin-kit

## Basic Information

- **Project Name**: dsh-plugin-kit
- **Description**: DSH 插件开发脚手架，DSH 仓库：https://github.com/deepseek-ai/deepseek-harness
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DSH Plugin Kit

**DSH Plugin Kit** 是面向内部团队的 DeepSeek Harness 插件脚手架与质量门禁工具。它采用极薄的 POSIX Shell launcher 作为分发入口，并把交互式向导、模板注册、构建、审计、打包、profile 链接、隔离安装测试、发布预检和本地 Git 提交全部放在 JavaScript 核心中。

> 该工具**不替代** DSH 的 Cordis Loader、profile 机制或 `dsh plugin` 命令。它生成符合当前 DSH bundle 约定的包，并在后续步骤调用 DSH CLI 将制品加入指定 profile。[官方 packages 架构][1]明确将工具、模型、Web、会话、沙箱、调度和 UI 设计为可组合能力；本工具把这些不同扩展面转化为受治理的开发入口。

## 安装与起步

无需先发布本工具。解压或 clone 后，直接运行 launcher：

```sh
cd dsh-plugin-kit
chmod +x ./bin/dsh-plugin
./bin/dsh-plugin doctor
./bin/dsh-plugin templates
./bin/dsh-plugin create
```

需要作为本机命令使用时，可在本目录执行 `npm link` 或 `pnpm link --global`。`doctor` 会检查 Node、pnpm、npm、Git 与可选的 `dsh` 命令。目标 DSH 版本要求 Node.js `>=22.19.0`；在没有 DSH 的机器上，仍可生成、审计、构建、打包和执行静态测试，但 profile 集成测试将被明确跳过。

| 命令 | 作用 | 外部副作用 |
| --- | --- | --- |
| `templates [--json]` | 列出所有模板、类别、支持等级和目标 seam | 无 |
| `doctor` | 检查本机与 DSH 客户端构建前提 | 无 |
| `create` | 交互或非交互生成插件目录 | 写入新目录 |
| `build` | 用 Node 内置复制脚本生成 `lib/`，不隐式安装 DSH peer | 写入 `lib/` |
| `audit` | 检查 metadata、patch、LICENSE、忽略规则、client manifest 与风险等级 | 无 |
| `pack` | `audit` 后创建并检查 `.tgz` | 写入 `.artifacts/` |
| `dev link` | 将绝对路径显式 link 到目标 DSH profile | 修改目标 profile |
| `test` | 跑静态测试；在可用时使用临时 `DSH_HOME` 做隔离安装 | 临时目录；可选 profile 调用 |
| `git status` / `git commit --yes` | 检查或提交本地变更；绝不自动 push | 修改本地 Git 历史（仅 commit） |
| `publish --dry-run` / `publish --yes` | npm/pnpm 发布预检或实际发布 | 实际发布须显式 `--yes` |

## 模板能力矩阵

模板由单一注册表驱动，注册表同时决定向导选项、包清单、bundle patch、骨架代码、审计、测试与文档。因此，新增 DSH capability 时应扩展注册表，而不是继续堆叠命令分支。

| Kind | 类别 | 支持等级 | 主扩展 seam | 典型使用 |
| --- | --- | --- | --- | --- |
| `generic` | runtime | stable | `ctx.effect()`、`ctx.on()`、`ctx.waterfall()` | 组合逻辑、服务、事件监听 |
| `tool` | runtime | stable | `ctx.tools.register()` | 模型可调用业务工具 |
| `web-search` | provider | stable | `ctx.web.registerSearchProvider()` | Bocha、Exa 或内部检索搜索后端 |
| `web-fetch` | provider | advanced | fetch provider seam | 自定义网页抓取、清洗与索引 |
| `llm-adapter` | provider | advanced | `ctx.llm` adapter seam | 模型供应商、协议或重试适配 |
| `storage-adapter` | provider | advanced | storage service seam | 会话、对象、缓存与持久化后端 |
| `sandbox-provider` | provider | advanced | sandbox service seam | 隔离执行提供商 |
| `shell-executor` | provider | advanced | shell executor seam | 受策略约束的命令执行后端 |
| `subagent-strategy` | runtime | advanced | subagent service seam | 委派、预算、隔离与汇总策略 |
| `workflow` | runtime | advanced | workflow service seam | 可恢复的任务编排 |
| `hook` | runtime | stable | `ctx.on()`、`ctx.waterfall()` | 审计、策略、观测与治理 |
| `skill-pack` | content | stable | skill discovery | 可移植的 Skill 内容包 |
| `ui-surface` | client | advanced | `ctx.slots.register()`、`dsh.client` | overlay、侧栏、对话、详情和历史界面 |
| `agent-loop` | core | advanced | `ctx.agents.setFactory()` | 自定义或替换 Agent loop/factory |
| `bundle` | composition | stable | Cordis Loader patch | 组织级组合能力包 |

**stable** 表示该生成器给出了能参与当前包/patch 流程的起始实现和静态质量门禁；并不表示业务逻辑已完成。**advanced** 表示 seam 本身存在，但生成的内容是有意受限的**合同骨架**：它会生成版本兼容、风险审查和集成测试要求，避免把 client slot、执行器、存储或 Agent loop 的未完成实现误认为可安全启用的生产插件。

## 常用工作流

下面以工具、Web 搜索和 UI 三种代表类型为例。所有示例都使用 package 名而非任何真实密钥；密钥只能由部署环境或 DSH credential store 提供。

```sh
# 1. 创建模型工具
./bin/dsh-plugin create --yes \
  --name @company/dsh-tool-release-notes \
  --kind tool --mode external --profile web \
  --dir ./dsh-tool-release-notes

# 2. 创建 Web Search provider；在生成的 patch 中只保存 apiKeyEnv 名称
./bin/dsh-plugin create --yes \
  --name @company/dsh-web-search-internal \
  --kind web-search --mode external --profile web \
  --dir ./dsh-web-search-internal

# 3. 创建浏览器叠加层；也可选 sidebar/conversation/details/history
./bin/dsh-plugin create --yes \
  --name @company/dsh-client-release-status \
  --kind ui-surface --surface overlay --mode in-tree --profile web \
  --dir ./dsh-client-release-status
```

每个项目都应经过以下顺序：

```sh
cd ./dsh-tool-release-notes

dsh-plugin build
dsh-plugin audit --strict
dsh-plugin test

dsh-plugin pack
# 在支持的目标 DSH 环境运行；安装与验证使用实际 profile
# dsh-plugin dev link --profile web
# dsh-plugin test --integration --dsh /absolute/path/to/dsh --profile web
```

`build` 和默认 `test` 故意只使用 Node 内置能力，不会因为 `node_modules` 缺失而让 pnpm 隐式解析尚未固定的 DSH peer 版本。真正运行时仍必须在目标 DSH profile 或 fork 中提供与该项目兼容的 peer dependencies。`pack` 会拒绝包含 `.env`、`.credentials.yaml`、`node_modules/` 或 `.artifacts/` 的 tarball。

## UI 与 Agent loop 的特殊规则

DSH 的客户端 feature packages 与后端 runtime bundle 不是同一个扩展层。官方 `ui-layout` 使用 runtime-owned slot，并声明 `sidebar`、`conversation`、`details` 与 `shell.overlay` 等 slot；它还通过 `ctx.layout` 管理面板几何状态。[2] 因此，`ui-surface` 生成器会写入 `dsh.client` manifest、`src/client.js` 与 `CLIENT_INTEGRATION.md`。它不会谎称“仅执行 `dsh plugin add` 就能使已构建的浏览器 UI 立刻出现”。将 UI 包接入目标 DSH client build/profile、实现 React 组件、选择非冲突 slot owner、重建并验证浏览器产物，都是必需步骤。

`agent-loop` 的风险更高。官方 concrete loop 会将自身设置为 agent factory，负责 agent 的创建与恢复、工具调度、取消、会话持久化和服务生命周期。[3] 模板默认只以 `observe` 模式加载；若手工设置 `mode: replace`，生成代码会拒绝启动，直到团队完成 `AGENT_LOOP_CONTRACT.md` 中的 contract、版本固定与集成测试。这样可防止一个未实现 `create()` / `resume()` / durable events 的类意外接管真实 agent。

## 版本与兼容治理

生成项目默认记录一个 DSH 兼容带和模板 metadata，但内部推广时应由平台团队维护**版本矩阵**：将每个已推广插件与精确 DSH release、Cordis 版本、目标 profile、client build、owner 和通过的测试集绑定。外部项目使用 `peerDependencies`；纯静态构建将其标为 optional，避免构建阶段意外下载不匹配的预发布依赖。真正 profile 集成必须由 `dsh plugin --profile <name> add <specifier>` 或本工具的 `dev link` 完成。

对于 DSH fork 内开发，使用 `--mode in-tree`。生成器会给出 `IN_TREE_NOTICE.md`，但不会自动修改根 `pnpm-workspace.yaml`、TypeScript project references、client aggregate 或 profile composition。这些是影响整仓构建图的显式评审变更，不能由向导暗改。

## 安全和发布治理

生成器会写入 `.gitignore`，排除 `.env`、`.credentials.yaml`、`node_modules/`、`lib/` 和制品目录。业务配置只能引用密钥名，例如 `apiKeyEnv: BOCHA_API_KEY`；不得把 key、cookie 或 token 写入源码、patch、README、npm metadata 或 tarball。对已暴露的密钥，应先在供应商侧轮换，再继续测试或发布。

发布采用两步确认：先运行 `dsh-plugin publish --dry-run`，检查包内容和 registry 预检；确认无误后再用 `dsh-plugin publish --yes`。`git commit` 同样要求 `--yes`，且工具永不自动 `git push`、创建远程仓库、提交表单或更改真实 profile 以外的外部资源。

## 内部推广建议

建议将此仓库作为统一入口，以一个受保护分支维护模板注册表与 DSH 版本矩阵。业务团队可从 `tool`、`web-search`、`hook`、`skill-pack` 和 `bundle` 开始；provider、client UI、执行器、存储和 loop 类项目应由平台/安全审查人共同拥有。每一个 advanced 项目都必须保留生成的 `COMPATIBILITY.md`、`SECURITY.md`、`ADVANCED_REVIEW.md`，并通过目标 profile 的隔离安装测试后才可进入共享环境。

## 参考

[1] [DeepSeek Harness packages architecture](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages)

[2] [DeepSeek Harness client UI layout package](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/client/ui-layout)

[3] [DeepSeek Harness core agent-loop source](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/core/agent-loop)