dsh-plugin-dev-kb 1.1.0 → 1.4.0

package/kb/site/develop/cordis-tutorial/07-into-the-harness.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/07-into-the-harness.zh.md"
+rawMarkdownPath: "develop/cordis-tutorial/07-into-the-harness.md"
 ---
 
 # 7. 进入 harness

package/kb/site/develop/cordis-tutorial/index.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/index.zh.md"
+rawMarkdownPath: "develop/cordis-tutorial/index.md"
 ---
 
 # Cordis 教程

package/kb/site/develop/framework/events.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/framework/events.zh.md"
+rawMarkdownPath: "develop/framework/events.md"
 ---
 
 # 事件系统

package/kb/site/develop/framework/index.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/framework/index.zh.md"
+rawMarkdownPath: "develop/framework/index.md"
 ---
 
 # 插件与生命周期
@@ -100,7 +101,7 @@ await fiber.dispose()
 
 ## HMR（热模块替换）
 
-通过 `cordis.yml` 加载 `@deepseek-ai/cordis-plugin-hmr` 后，修改插件源文件会触发：
+通过 `cordis.yml` 加载 `@deepseek-ai/dsh-hmr` 后，修改插件源文件会触发：
 
 1. 卸载旧插件（清理所有注册）
 2. 重新加载新代码

package/kb/site/develop/framework/service.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/framework/service.zh.md"
+rawMarkdownPath: "develop/framework/service.md"
 ---
 
 # 服务与依赖

package/kb/site/develop/practice/dynamic-cordis.md

@@ -1,17 +1,18 @@
 ---
 editSource: "docs/user/develop/practice/dynamic-cordis.zh.md"
+rawMarkdownPath: "develop/practice/dynamic-cordis.md"
 ---
 
-# 用 Cordis 工具扩展运行中的智能体
+# 通过提示词配置持久化插件
 
-本实战指南启用 [`@deepseek-ai/dsh-tool-cordis`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/extensions/tool-cordis/README.zh.md)。智能体可以检查当前 Cordis 进程，并在内存中挂载或卸载模型编写的插件。临时插件会在卸载或进程退出时消失，并可能影响同一进程中的其他会话。
+创造模式提供 [Plugin Manager](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/plugin-manager/README.zh.md) 和只读[运行时检查](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/extensions/tool-cordis/README.zh.md)。插件配置属于当前 profile，影响其会话，并在进程重启后保留。
 
-## 运行
+## 连接 MCP 服务器
 
-使用仓库内 overlay 启动浏览器界面：
+启动 Web profile 并选择创造模式。准备一个可访问且提供 `ping` 的 Streamable HTTP MCP 服务器，将其实际端点填入以下提示词：
 
-```sh
-pnpm dsh web --patch apps/cli/config/examples/cordis/cordis.yml
-```
+> 将 `<endpoint>` 处的 MCP 服务器配置到当前 profile，命名为 `demo`。立即启用它的工具，然后调用它的 ping 工具并告诉我结果。
 
-该命令需要模型凭据。[Cordis 工具参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/extensions/tool-cordis/README.zh.md)定义了四类约定：工具参数、存续时间、清理行为和安全性。
+agent 编写纯配置组合包，在 patch 中插入 `@deepseek-ai/dsh-mcp-client`，再通过 `plugin_manager install_bundle` 安装。启用 HMR 时，工具会出现在同一个运行中的会话里。同时检查管理结果（`application: applied`）和成功的 `mcp__demo__ping` 调用。返回 `restart-required` 的已保存条目尚未激活；失败条目需要修复配置。
+
+修改配置前先读取组合包 patch。使用 Plugin Manager 停用条目或移除组合包。可接受的配置及连接失败行为见 [MCP client 参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.zh.md)。

package/kb/site/develop/practice/index.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/practice/index.zh.md"
+rawMarkdownPath: "develop/practice/index.md"
 ---
 
 # 能力的三种角色设计

package/kb/site/develop/practice/llm-adapter.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/practice/llm-adapter.zh.md"
+rawMarkdownPath: "develop/practice/llm-adapter.md"
 ---
 
 # LLM 适配器
@@ -148,7 +149,7 @@ ctx.llm.registerAdapter(['my-provider'], adapter)
 
 仓库中包含以下两个完整实现：
 
-- `packages/llm/llm-deepseek/` — DeepSeek API 适配器（OpenAI 兼容格式）
+- `packages/llm/llm-deepseek/` — 使用 Messages API 的 DeepSeek 适配器
 - `packages/llm/llm-pi-ai/` — Pi AI 适配器（不同的 API 格式）
 
 对比这两个已交付的适配器，可以看到同一套 harness 契约如何在不同提供方 SDK 之上实现。

package/kb/site/en/develop/basic/config.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/basic/config.md"
+rawMarkdownPath: "en/develop/basic/config.md"
 ---
 
 # Plugin configuration

package/kb/site/en/develop/basic/index.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/basic/index.md"
+rawMarkdownPath: "en/develop/basic/index.md"
 ---
 
 # Your first plugin

package/kb/site/en/develop/basic/publish.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/basic/publish.md"
+rawMarkdownPath: "en/develop/basic/publish.md"
 ---
 
 # Package and install a plugin
@@ -63,7 +64,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: `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.
+`patch` also accepts an ordered list of files, for example `["./base.patch.yml", "./web.patch.yml"]`; the launcher applies them in that order as one layer, and each file's relative plugin paths resolve beside that file. 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
 
@@ -72,7 +73,7 @@ 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: `dsh plugin` creates and maintains it. The next section shows the result.
+You never write a profile manifest by hand: `dsh --profile <name> --from-default-profile <template>` can create one from a shipped application template, while `dsh plugin` creates a base-backed profile and maintains its installed bundle list. The [CLI behavior reference](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md#profile-boot) owns the creation rules; the next section shows the plugin path.
 
 ## Install into a profile
 
@@ -102,6 +103,12 @@ The first use initializes the profile (with `@deepseek-ai/dsh-base` as its first
 }
 ```
 
+A linked checkout keeps its own `node_modules`. Declare dsh packages whose instances the plugin must share with the host under both `peerDependencies` and `devDependencies`, as the harness packages do. At that manifest's lookup position, peers present in the running dsh's runtime resolution use the installation's copy; the devDependency copy serves your type checker and standalone tests. Keep independently versioned third-party dependencies and stateless dsh utilities under `dependencies`.
+
+Ordinary linked imports follow Node's ancestor order and check each directory's current peer declarations. A nearer physical package wins before a higher peer declaration. A link target can lack `package.json`; ancestor peers still apply, even without a physical `node_modules` beside that manifest. Explicit `require.resolve(..., { paths })` is always native, including paths inside a profile. These rules are shared by npm, Desktop, and source launches; they do not invalidate loaded modules or validate peer version ranges. See the [resolution rules](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md) for scope and file-query behavior.
+
+Linking a broad checkout does not apply peer interception to the running installation's own package directories. Links whose targets stay inside the profile, including its pnpm store, remain profile-owned installation content rather than external linked roots. Overlapping external links do not change lookup order: each request still starts from its importer's directory.
+
 Verify the layer without booting, then boot:
 
 ```sh
@@ -162,7 +169,7 @@ 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:
 
-- **The author** ships a `prepare` script — pnpm runs it after a git install — that builds the published entry points from source, self-contained: it must not assume dev-only context such as a sibling monorepo checkout. [turtle-ui](https://github.com/deepseek-harness/turtle-ui) is a working example: its `prepare` runs a dedicated tsdown config that transpiles `src/` without project references or type checking.
+- **The author** ships a `prepare` script — pnpm runs it after a git install — that builds the published entry points from source, self-contained: it must not assume dev-only context such as a sibling monorepo checkout. A dedicated tsdown config can transpile `src/` without project references or type checking.
 - **The user** allowlists the build. pnpm ≥10 refuses to run a git dependency's `prepare` script until it is explicitly allowed, so the first `add` fails; `dsh` points at the fix — copy the exact package key pnpm printed into the profile's `pnpm-workspace.yaml`:
 
   ```yaml

package/kb/site/en/develop/basic/tool.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/basic/tool.md"
+rawMarkdownPath: "en/develop/basic/tool.md"
 ---
 
 # Build a tool

package/kb/site/en/develop/cordis-tutorial/01-first-plugin.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/01-first-plugin.md"
+rawMarkdownPath: "en/develop/cordis-tutorial/01-first-plugin.md"
 ---
 
 # 1. Your first plugin

package/kb/site/en/develop/cordis-tutorial/02-lifecycle-and-effects.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/02-lifecycle-and-effects.md"
+rawMarkdownPath: "en/develop/cordis-tutorial/02-lifecycle-and-effects.md"
 ---
 
 # 2. Lifecycle and effects

package/kb/site/en/develop/cordis-tutorial/03-services.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/03-services.md"
+rawMarkdownPath: "en/develop/cordis-tutorial/03-services.md"
 ---
 
 # 3. Services

package/kb/site/en/develop/cordis-tutorial/04-events.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/04-events.md"
+rawMarkdownPath: "en/develop/cordis-tutorial/04-events.md"
 ---
 
 # 4. Events

package/kb/site/en/develop/cordis-tutorial/05-config.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/05-config.md"
+rawMarkdownPath: "en/develop/cordis-tutorial/05-config.md"
 ---
 
 # 5. Configuration
@@ -69,6 +70,33 @@ ValidationError: invalid config:
 
 The plugin's fiber goes to FAILED, and this tutorial's launcher exits with status 1 after printing the error. A plugin should also reject schema-valid config that names an unavailable resource or provider as soon as it can resolve that reference.
 
+<a id="volatile-fields"></a>
+## Volatile fields
+
+Use `.volatile()` for a field that the plugin reads during each operation. A change to that field updates its stable reference without remounting the plugin. Read it with `.get()`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/cordis-plugin-loader'
+import Schema from '@deepseek-ai/schemastery'
+
+export const Config = Schema.object({
+  greeting: Schema.string().default('Hello').volatile(),
+})
+
+export function apply(ctx: Context, config: ReturnType<typeof Config>) {
+  ctx.on('loader/volatile-update', () => {
+    console.log(config.greeting.get())
+  })
+}
+```
+
+A direct `Config(raw)` call also returns references. An optional field without a default still has a reference; `.get()` returns `undefined` when it is absent. Keep the reference, or capture its value for one operation, including across `await`. Do not retain that value for later operations. Object and array values are detached, recursively frozen snapshots of plain data; functions, class instances, and cycles are rejected.
+
+Loader compares raw config while ignoring schema-declared volatile fields. A volatile-only change is parsed through the plugin’s `internal/config` hook and validated; when every ordinary effective value still matches, Loader commits the new values into the running references and emits one instance-local `loader/volatile-update` with the changed paths as arrays of keys, bypassing the target plugin’s `internal/update`. Equal values do not notify. An invalid candidate is logged and leaves the running references unchanged until the next activation. A changed ordinary effective value, including a changed expression result, and simultaneous ordinary-field changes retain the existing update flow, leaving old references unchanged and unnotified. Group/Include still dispatch child updates. Direct `fiber.update()`, code replacement, and dependency replacement retain their lifecycle; `noSave` still controls direct-update persistence. Notifications use ordinary `emit` without awaiting resource reconfiguration.
+
+Declare volatile fields at fixed object paths, or mark an entire object or array volatile. Independent references inside arrays, dictionaries, union or intersect branches, lazy schemas, transforms, or another volatile value are rejected. Configuration files store ordinary values; `simplify()` unwraps references. Serialized schemas preserve their field types, defaults, roles, and volatile marker for schema-driven forms. Existing settings consumers continue to use their own settings interfaces.
+
 ## Computed config values
 
 The loader used in this repo supports a `!!js` tag for config values that must be computed at load time:

package/kb/site/en/develop/cordis-tutorial/06-composition-and-hmr.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/06-composition-and-hmr.md"
+rawMarkdownPath: "en/develop/cordis-tutorial/06-composition-and-hmr.md"
 ---
 
 # 6. Composition and HMR
@@ -24,7 +25,7 @@ Groups nest a sub-list of entries that load and unload as one unit, and `isolate
 
 ## Hot module replacement
 
-Because unloading releases effects ([chapter 2](./02-lifecycle-and-effects.md)) and loading follows dependencies ([chapter 3](./03-services.md)), HMR can replace a running plugin by unloading and loading it. The `@deepseek-ai/cordis-plugin-hmr` plugin watches your files and does exactly that on save.
+Because unloading releases effects ([chapter 2](./02-lifecycle-and-effects.md)) and loading follows dependencies ([chapter 3](./03-services.md)), HMR can replace a running plugin by unloading and loading it. The `@deepseek-ai/dsh-hmr` plugin watches your files and does exactly that on save.
 
 In `tmp/cordis-tutorial`, write `cordis.yml`:
 
@@ -34,7 +35,7 @@ In `tmp/cordis-tutorial`, write `cordis.yml`:
 - id: timer
   name: '@deepseek-ai/cordis-plugin-timer'
 - id: hmr
-  name: '@deepseek-ai/cordis-plugin-hmr'
+  name: '@deepseek-ai/dsh-hmr'
   config:
     root: ['.']
 - id: hello

package/kb/site/en/develop/cordis-tutorial/07-into-the-harness.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/07-into-the-harness.md"
+rawMarkdownPath: "en/develop/cordis-tutorial/07-into-the-harness.md"
 ---
 
 # 7. Into the harness

package/kb/site/en/develop/cordis-tutorial/index.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/index.md"
+rawMarkdownPath: "en/develop/cordis-tutorial/index.md"
 ---
 
 # Cordis tutorial

package/kb/site/en/develop/framework/events.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/framework/events.md"
+rawMarkdownPath: "en/develop/framework/events.md"
 ---
 
 # Event system

package/kb/site/en/develop/framework/index.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/framework/index.md"
+rawMarkdownPath: "en/develop/framework/index.md"
 ---
 
 # Plugins and lifecycle
@@ -100,7 +101,7 @@ await fiber.dispose()
 
 ## Hot replacement (HMR)
 
-With `@deepseek-ai/cordis-plugin-hmr` loaded from `cordis.yml`, editing a plugin source file triggers:
+With `@deepseek-ai/dsh-hmr` loaded from `cordis.yml`, editing a plugin source file triggers:
 
 1. Unload the old plugin and clean up its registrations.
 2. Load the new code.

package/kb/site/en/develop/framework/service.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/framework/service.md"
+rawMarkdownPath: "en/develop/framework/service.md"
 ---
 
 # Services and dependencies

package/kb/site/en/develop/practice/dynamic-cordis.md

@@ -1,17 +1,18 @@
 ---
 editSource: "docs/user/develop/practice/dynamic-cordis.md"
+rawMarkdownPath: "en/develop/practice/dynamic-cordis.md"
 ---
 
-# Extend a running agent with Cordis tools
+# Configure persistent plugins from a prompt
 
-This practice guide enables [`@deepseek-ai/dsh-tool-cordis`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/extensions/tool-cordis/README.md). The agent can inspect its current Cordis process and mount or unmount model-authored plugins in memory. Temporary plugins disappear when they are unmounted or the process exits and may affect other sessions in the same process.
+Creator mode provides [Plugin Manager](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/plugin-manager/README.md) and read-only [runtime inspection](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/extensions/tool-cordis/README.md). Plugin configuration belongs to the current profile, affects its sessions, and survives process restarts.
 
-## Run it
+## Connect an MCP server
 
-Start the browser interface with the checked-in overlay:
+Start the Web profile and select Creator mode. With a reachable Streamable HTTP MCP server that exposes `ping`, send this prompt using its actual endpoint:
 
-```sh
-pnpm dsh web --patch apps/cli/config/examples/cordis/cordis.yml
-```
+> Configure the MCP server at `<endpoint>` in this profile as `demo`. Make its tools available now, then call its ping tool and tell me the result.
 
-The command requires a model credential. The [Cordis tool reference](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/extensions/tool-cordis/README.md) defines the tool arguments, lifetime, cleanup, and safety contracts.
+The agent writes a configuration-only bundle whose patch inserts `@deepseek-ai/dsh-mcp-client`, then installs it with `plugin_manager install_bundle`. With HMR enabled, the tools appear in the same running session. Verify both the management result (`application: applied`) and a successful `mcp__demo__ping` call. A saved entry with `restart-required` has not activated yet; a failed entry needs configuration repair.
+
+Read the bundle patch before editing its configuration. Use Plugin Manager to disable entries or remove the bundle. See the [MCP client reference](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md) for accepted configuration and connection failure behavior.

package/kb/site/en/develop/practice/index.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/practice/index.md"
+rawMarkdownPath: "en/develop/practice/index.md"
 ---
 
 # Three-role capability design

package/kb/site/en/develop/practice/llm-adapter.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/practice/llm-adapter.md"
+rawMarkdownPath: "en/develop/practice/llm-adapter.md"
 ---
 
 # LLM adapters
@@ -148,7 +149,7 @@ The first argument lists provider routes handled by the adapter. `GenerateOption
 
 The repository contains complete implementations:
 
-- `packages/llm/llm-deepseek/` — DeepSeek API adapter using the OpenAI-compatible format
+- `packages/llm/llm-deepseek/` — DeepSeek adapter using the Messages API
 - `packages/llm/llm-pi-ai/` — Pi AI adapter using a different API format
 
 Compare the two shipped adapters to see the same harness contract implemented over different provider SDKs.

package/kb/site/en/guide/github-review.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/guide/github-review.md"
+rawMarkdownPath: "en/guide/github-review.md"
 ---
 
 # Create review Sessions from GitHub webhooks

package/kb/site/en/guide/mcp-memory.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/guide/mcp-memory.md"
+rawMarkdownPath: "en/guide/mcp-memory.md"
 ---
 
 # Connect a third-party memory MCP server

package/kb/site/en/guide/network-proxy.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/guide/network-proxy.md"
+rawMarkdownPath: "en/guide/network-proxy.md"
 ---
 
 # Run DSH behind a network proxy
@@ -68,7 +69,7 @@ Node reads that variable only at process start, so export it before running `dsh
 Not every request DSH makes goes through the proxy:
 
 - **Anything on this machine.** Loopback is always direct: `localhost`, the whole `127.0.0.0/8` range, `::1`, and `0.0.0.0`. A proxy cannot usefully reach a service that only listens locally.
-- **Code the model writes.** The workflow and code-runtime workers never receive the proxy settings, so a script the model authors cannot read a proxy URL that may carry a password. Such a script reaches the network only if it configures that itself.
+- **Code the model writes.** Workflow workers and Node ptc-runtime processes receive no proxy settings, so model-authored scripts cannot read a proxy URL that may carry a password. Direct requests must configure any required proxy themselves and remain subject to the execution sandbox.
 - **Usage telemetry.** The OTLP exporter uses Node's own HTTP client rather than the one a proxy configures, so telemetry connects directly and simply fails where direct egress is blocked. Nothing you do in DSH depends on it. Set `DSH_TELEMETRY_MODE=DISABLED` to turn it off entirely.
 - **`web_fetch` to a literal private address.** A URL naming an address like `http://10.0.0.5/` is refused rather than handed to the proxy, the same refusal it gets with no proxy configured.