docs: use installed dsh command in publish tutorial

2026-08-13 14:20:09 +08:00
parent bca790481c
commit 4201bbceca
3 changed files with 28 additions and 28 deletions
@@ -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
@@ -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/<name>` 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 <name>`. Nothing is both.
+A bundle is what you author and distribute; a profile is what a user boots with `dsh --profile <name>`. 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 <name> <args...>` forwards to pnpm in the profile directory, so every pnpm verb works. From the repository root, install the package checkout:
+`dsh plugin --profile <name> <args...>` 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

@@ -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/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是"这套配置由哪些组合包按什么顺序组成？"。

-组合包是你编写并分发的东西；profile 是用户在当前源码 checkout 中用 `pnpm dsh --profile <name>` 启动的东西。没有东西同时是两者。
+组合包是你编写并分发的东西；profile 是用户用 `dsh --profile <name>` 启动的东西。没有东西同时是两者。

 ### 组合包 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 <name> <args...>` 在 profile 目录内转发给 pnpm，因此所有 pnpm 子命令都可用。在仓库根目录安装该包的 checkout：
+`dsh plugin --profile <name> <args...>` 在 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`。

 ## 下一步