From 4201bbceca8104f6a26013e49c44239b6a257929 Mon Sep 17 00:00:00 2001 From: Turtle Date: Thu, 13 Aug 2026 14:02:07 +0800 Subject: [PATCH] docs: use installed dsh command in publish tutorial --- docs/user/develop/basic/publish.i18n.yaml | 4 ++-- docs/user/develop/basic/publish.md | 26 +++++++++++------------ docs/user/develop/basic/publish.zh.md | 26 +++++++++++------------ 3 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/user/develop/basic/publish.i18n.yaml b/docs/user/develop/basic/publish.i18n.yaml index 694a7ff663..e640e971cb 100644 --- a/docs/user/develop/basic/publish.i18n.yaml +++ b/docs/user/develop/basic/publish.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/user/develop/basic/publish.md -publish.md: edc85b74049c5b993efb02663195fcc0001b4620 -publish.zh.md: cb824ad12eec0d706efa17b28f3bdc874ba59131 +publish.md: 8283f9e7ff0c28580343975d67c5715d17c53074 +publish.zh.md: 5a87901fe39aa00e94db81dc840e39a52e0cc88c diff --git a/docs/user/develop/basic/publish.md b/docs/user/develop/basic/publish.md index edc85b7404..8283f9e7ff 100644 --- a/docs/user/develop/basic/publish.md +++ b/docs/user/develop/basic/publish.md @@ -2,7 +2,7 @@ English | [中文](publish.zh.md) -The previous tutorials loaded a local plugin through a `--patch` overlay. This tutorial packages it as an installable **bundle**, installs it into a **profile** with `pnpm dsh plugin add`, and explains the layer order that determines the composed configuration. Complete [plugin configuration](./config.md) first. +The previous tutorials loaded a local plugin through a `--patch` overlay. This tutorial packages it as an installable **bundle**, installs it into a **profile** with `dsh plugin add`, and explains the layer order that determines the composed configuration. It assumes the `dsh` CLI is installed. Complete [plugin configuration](./config.md) first. ## Two concepts, two manifests @@ -11,11 +11,11 @@ Installation is built on two concepts. Both are described by a `package.json`, b - A **bundle** is an npm package that ships a configuration layer. Its manifest declares `dsh.bundle`, answering "what does this package contribute?": a patch file that inserts or overrides plugin rows. - A **profile** is a directory under `$DSH_HOME/profiles/` describing one runnable composition. Its manifest declares `dsh.profile`, answering "which bundles compose this setup, in what order?". -A bundle is what you author and distribute; a profile is what a user boots from this source checkout with `pnpm dsh --profile `. Nothing is both. +A bundle is what you author and distribute; a profile is what a user boots with `dsh --profile `. Nothing is both. ### The bundle manifest -From the repository root, create the package directory: +Create the package directory: ```sh mkdir -p hello-plugin @@ -59,7 +59,7 @@ Create `hello-plugin/cordis.patch.yml`. The patch is a YAML array like the `--pa name: dsh-hello-plugin ``` -A package without the `dsh.bundle` declaration still installs, but only as a plain dependency: `pnpm dsh plugin` prints a warning and activates no layer. Use that package format for a library that plugin packages import rather than a plugin users enable. +A package without the `dsh.bundle` declaration still installs, but only as a plain dependency: `dsh plugin` prints a warning and activates no layer. Use that package format for a library that plugin packages import rather than a plugin users enable. ### The profile manifest @@ -68,14 +68,14 @@ A profile directory holds two files: - `package.json` — the profile's out-of-tree plugin dependencies (managed by pnpm) plus the `dsh.profile` manifest with its ordered `bundles` list. - `cordis.patch.yml` — the user's own patch layer, applied after every bundle layer. -You never write a profile manifest by hand: `pnpm dsh plugin` creates and maintains it. The next section shows the result. +You never write a profile manifest by hand: `dsh plugin` creates and maintains it. The next section shows the result. ## Install into a profile -`pnpm dsh plugin --profile ` forwards to pnpm in the profile directory, so every pnpm verb works. From the repository root, install the package checkout: +`dsh plugin --profile ` forwards to pnpm in the profile directory, so every pnpm verb works. From the directory that contains `hello-plugin`, install the package checkout: ```sh -pnpm dsh plugin --profile demo add ./hello-plugin +dsh plugin --profile demo add ./hello-plugin ``` The first use initializes the profile (with `@deepseek-ai/dsh-base` as its first bundle), pnpm links the checkout, and `dsh` appends the bundle to `dsh.profile.bundles` because the package declares `dsh.bundle`: @@ -101,11 +101,11 @@ The first use initializes the profile (with `@deepseek-ai/dsh-base` as its first Verify the layer without booting, then boot: ```sh -pnpm dsh --profile demo --dump-config # shows a "# == dsh-hello-plugin" layer -pnpm dsh --profile demo +dsh --profile demo --dump-config # shows a "# == dsh-hello-plugin" layer +dsh --profile demo ``` -`pnpm dsh plugin --profile demo remove dsh-hello-plugin` removes both the dependency and the layer. +`dsh plugin --profile demo remove dsh-hello-plugin` removes both the dependency and the layer. ## The loading order @@ -153,7 +153,7 @@ On `--help`, the provider publishes no service, so those rows never activate. Lo Publishing to a registry is not required — users can install straight from a git host: ```sh -pnpm dsh plugin --profile demo add github:you/hello-plugin +dsh plugin --profile demo add github:you/hello-plugin ``` But a git install fetches **sources, not built artifacts**: nothing runs your `build` script, so a TypeScript package arrives without its `lib/` output and fails to load. Two things must happen, one on each side: @@ -172,8 +172,8 @@ Treat that allowance as what it is: **permission to execute the package's code o If you would rather not ask users for the allowance, distribute built artifacts instead — neither form needs any build permission: -- **Publish to npm** with `lib/` built at `pnpm publish` time; `pnpm dsh plugin add your-package` then installs prebuilt code. -- **Ship a tarball** from `pnpm pack`; users run `pnpm dsh plugin add ./hello-plugin-0.1.0.tgz`. +- **Publish to npm** with `lib/` built at `pnpm publish` time; `dsh plugin add your-package` then installs prebuilt code. +- **Ship a tarball** from `pnpm pack`; users run `dsh plugin add ./hello-plugin-0.1.0.tgz`. ## Next steps diff --git a/docs/user/develop/basic/publish.zh.md b/docs/user/develop/basic/publish.zh.md index cb824ad12e..5a87901fe3 100644 --- a/docs/user/develop/basic/publish.zh.md +++ b/docs/user/develop/basic/publish.zh.md @@ -2,7 +2,7 @@ [English](publish.md) | 中文 -前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**（bundle），用 `pnpm dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。请先完成[插件配置](./config.md)。 +前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**（bundle），用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。本文假设 `dsh` CLI 已安装。请先完成[插件配置](./config.md)。 ## 两个概念，两种 manifest @@ -11,11 +11,11 @@ - **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是"这个包贡献什么？"：一个插入或覆盖插件行的 patch 文件。 - **profile** 是位于 `$DSH_HOME/profiles/` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是"这套配置由哪些组合包按什么顺序组成？"。 -组合包是你编写并分发的东西；profile 是用户在当前源码 checkout 中用 `pnpm dsh --profile ` 启动的东西。没有东西同时是两者。 +组合包是你编写并分发的东西；profile 是用户用 `dsh --profile ` 启动的东西。没有东西同时是两者。 ### 组合包 manifest -在仓库根目录创建包目录： +创建包目录： ```sh mkdir -p hello-plugin @@ -59,7 +59,7 @@ export function apply() { name: dsh-hello-plugin ``` -没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`pnpm dsh plugin` 会打印警告，且不激活任何层。如果一个库供插件包 import，而不是供用户启用，就使用这种包格式。 +没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。如果一个库供插件包 import，而不是供用户启用，就使用这种包格式。 ### profile manifest @@ -68,14 +68,14 @@ profile 目录包含两个文件： - `package.json` — profile 的树外插件依赖（由 pnpm 管理），加上 `dsh.profile` manifest 及其有序的 `bundles` 列表。 - `cordis.patch.yml` — 用户自己的 patch 层，在每个组合包层之后应用。 -profile manifest 从不需要手写：`pnpm dsh plugin` 负责创建和维护它。下一节展示其结果。 +profile manifest 从不需要手写：`dsh plugin` 负责创建和维护它。下一节展示其结果。 ## 安装进 profile -`pnpm dsh plugin --profile ` 在 profile 目录内转发给 pnpm，因此所有 pnpm 子命令都可用。在仓库根目录安装该包的 checkout： +`dsh plugin --profile ` 在 profile 目录内转发给 pnpm，因此所有 pnpm 子命令都可用。在包含 `hello-plugin` 的目录中安装该包的 checkout： ```sh -pnpm dsh plugin --profile demo add ./hello-plugin +dsh plugin --profile demo add ./hello-plugin ``` 首次使用会初始化 profile（`@deepseek-ai/dsh-base` 作为它的第一个组合包），pnpm 链接该 checkout，而 `dsh` 因为这个包声明了 `dsh.bundle`，把它追加进 `dsh.profile.bundles`： @@ -101,11 +101,11 @@ pnpm dsh plugin --profile demo add ./hello-plugin 先不启动、只验证该层，再启动： ```sh -pnpm dsh --profile demo --dump-config # shows a "# == dsh-hello-plugin" layer -pnpm dsh --profile demo +dsh --profile demo --dump-config # shows a "# == dsh-hello-plugin" layer +dsh --profile demo ``` -`pnpm dsh plugin --profile demo remove dsh-hello-plugin` 会同时移除依赖和对应的层。 +`dsh plugin --profile demo remove dsh-hello-plugin` 会同时移除依赖和对应的层。 ## 加载顺序 @@ -153,7 +153,7 @@ pnpm dsh --profile demo 发布到注册表不是必须的——用户可以直接从 git 托管安装： ```sh -pnpm dsh plugin --profile demo add github:you/hello-plugin +dsh plugin --profile demo add github:you/hello-plugin ``` 但 git 安装拉取的是**源码，不是构建产物**：没有任何环节运行你的 `build` 脚本，因此 TypeScript 包到手时没有 `lib/` 输出，加载会失败。必须两边各做一件事： @@ -172,8 +172,8 @@ pnpm dsh plugin --profile demo add github:you/hello-plugin 如果不想让用户做这项授权，就改为分发构建产物——以下两种形式都不需要任何构建权限： -- **发布到 npm**，在 `pnpm publish` 时构建好 `lib/`；`pnpm dsh plugin add your-package` 安装的就是预构建代码。 -- **交付 tarball**：用 `pnpm pack` 打包；用户执行 `pnpm dsh plugin add ./hello-plugin-0.1.0.tgz`。 +- **发布到 npm**，在 `pnpm publish` 时构建好 `lib/`；`dsh plugin add your-package` 安装的就是预构建代码。 +- **交付 tarball**：用 `pnpm pack` 打包；用户执行 `dsh plugin add ./hello-plugin-0.1.0.tgz`。 ## 下一步