dsh-plugin-dev-kb 1.3.0 → 1.5.1

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,9 @@ 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.
+
+Declare the DSH releases the bundle supports with an `engines.dsh` SemVer range, for example `"engines": { "dsh": ">=0.2.0 <0.3.0" }`. Installation and profile startup refuse a bundle whose range the running DSH does not satisfy; without `engines.dsh`, they check its `@deepseek-ai/dsh*` peer dependency ranges instead ([rule](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/app-boot/README.md#profiles)).
 
 ### The profile manifest
 
@@ -72,7 +75,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 --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.
+You never write a profile manifest by hand: `dsh --profile <name> --from-default-profile <template>` can create or reset 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 +105,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 +171,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
@@ -24,20 +25,17 @@ export DSH_GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
 printf '%s\n' "$DSH_GITHUB_WEBHOOK_SECRET"
 ```
 
-From a development checkout:
+Install both experimental packages into the Web profile first. Profiles do not install peers automatically; the GitHub adapter needs the webhook runtime explicitly:
 
 ```sh
+dsh plugin --profile web add @deepseek-ai/dsh-webhook @deepseek-ai/dsh-webhook-github
 export DSH_GITHUB_REVIEW_WORKSPACE=/path/to/deepseek-harness
-pnpm dsh web --patch apps/cli/config/examples/github-review/cordis.yml
+dsh web --patch "${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@deepseek-ai/dsh-webhook-github/examples/github-review/cordis.yml"
 ```
 
-An installed DSH uses the same overlay through an absolute path:
+The adapter distributes the example, which loads from the profile's installation directory so its rule module can resolve profile-installed peers. Do not run the rule from an arbitrary directory outside the profile. To customize it, copy both example files to `$DSH_HOME/profiles/web/github-review/`, edit the configuration, and point `--patch` at that copy of `cordis.yml`; use `~/.dsh` when `DSH_HOME` is unset.
 
-```sh
-dsh web --patch /absolute/path/to/github-review/cordis.yml
-```
-
-For a permanent profile, place `github-ready-review-rule.mjs` beside `$DSH_HOME/profiles/web/cordis.patch.yml`, append the rows from `cordis.yml` to that patch, and start with `dsh web`. The shipped CLI already contains both webhook packages; the overlay alone activates them.
+The repository example lives under `packages/experimental/webhook-github/examples/github-review/`. The CLI does not install webhook packages or list them as Official plugins; installing the packages and supplying the overlay are separate steps.
 
 ## Expose the dedicated endpoint
 
@@ -67,7 +65,7 @@ Active:       yes
 
 ## Rule behavior
 
-The rule accepts only source `primary-github`, repository `deepseek-harness/deepseek-harness`, event `pull_request`, and action `ready_for_review`. It passes the exact head SHA plus selected PR fields to the review prompt, labeling the JSON as untrusted metadata and forbidding file, branch, PR, or GitHub mutation.
+The rule accepts only source `primary-github`, repository `deepseek-ai/deepseek-harness`, event `pull_request`, and action `ready_for_review`. It passes the exact head SHA plus selected PR fields to the review prompt, labeling the JSON as untrusted metadata and forbidding file, branch, PR, or GitHub mutation.
 
 The Session request selects the `standard` agent preset and `read-only` permission preset. `workspacePath` is canonicalized through `WorkspaceRegistry.create()`, so the first matching delivery creates the Web Workspace when absent and later deliveries reuse it.
 
@@ -91,7 +89,7 @@ It can also map repositories to different local paths:
 
 ```js
 const workspacePath = {
-  'deepseek-harness/deepseek-harness': '/path/to/deepseek-harness',
+  'deepseek-ai/deepseek-harness': '/path/to/deepseek-harness',
   'deepseek-harness/dsh-sdk': '/path/to/dsh-sdk',
 }[payload.repository.full_name]
 if (workspacePath === undefined) return null

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.
 

package/kb/site/en/guide/plugin-market.md

@@ -0,0 +1,151 @@
+---
+editSource: "docs/user/guide/plugin-market.md"
+rawMarkdownPath: "en/guide/plugin-market.md"
+---
+
+# Plugin markets
+
+## Summary
+
+A plugin market is one JSON index file that lists installable DSH bundles with their titles, icons, authors, and versions. Turn on the experimental **Custom plugin markets** bundle to browse markets in a **Discover** tab on the Plugins page and install a listed version after a confirmation. To publish a market, write or generate an index file and serve it, together with its icon files, from any static host.
+
+## Table of Contents
+
+- [Turn on Discover](#turn-on)
+- [Browse and install](#browse-and-install)
+- [Publish an index](#publish-an-index)
+- [Generate an index with the reference generator](#generate-an-index)
+- [Index format reference](#index-format)
+- [Further Exploration](#further-exploration)
+
+<a id="turn-on"></a>
+## Turn on Discover
+
+Open **Plugins**, select **More** beside **Experimental plugins**, find **Custom plugin markets**, and switch it on. A **Discover** tab appears next to **Installed**, and Creator mode gains the read-only `plugin_market` tool. Switching the bundle off removes both again.
+
+DSH ships no index source. Select **Discover**, choose **Add index source**, and enter the URL of an index file. A URL must use `http:` or `https:` and must not contain a user name, password, or `#` fragment. Anyone on the network path can change an `http:` index, including the install specs it lists, so use `https:` for a market reached over a network you do not control. Each source belongs to the current profile.
+
+<a id="browse-and-install"></a>
+## Browse and install
+
+The market menu at the left of the toolbar switches between sources and opens **Manage index sources…**, where each source shows its last error. Search matches names, authors, keywords, and titles, descriptions, categories, and labels in every language, and tolerates typos; results come in best-match order until you choose another. The **Labels** menu, category pills, and **Sort** menu use the categories, labels, and sort keys that the market declares, and **Publish date** sorts by each plugin's latest version.
+
+Each card shows the plugin's recommended version: the highest version compatible with the running DSH that is not a prerelease, or the highest compatible prerelease when the plugin lists no version without a prerelease tag. **Install** opens a confirmation with that version's source: the npm package and registry, or the Git repository, commit, and directory. Confirming starts the normal plugin installation, including its compatibility and registry checks; nothing is installed without that confirmation.
+
+Select a card to open its page. The **Versions** list shows every listed version with its compatibility and offers **Install** for any version DSH accepts, including older releases and prereleases. A card that shows **Installed**, **Update available**, or **Provided by DSH** opens the installed bundle instead.
+
+Markets are third-party content. A market chooses each plugin's title, description, icon, author, and source; DSH checks the file format but not those claims. Add only sources you trust, and check the source in the confirmation before installing.
+
+<a id="publish-an-index"></a>
+## Publish an index
+
+An index is a UTF-8 JSON file, at most 128 MiB by default, served with a 2xx status and without redirects. Put it on any static host, for example GitLab Pages, GitHub Pages, or an object store behind https.
+
+Icons can be inline or separate files. An inline icon is a base64 `data:` URL in the index; it needs no extra request but makes the index larger. A separate icon is a URL. A relative icon resolves against the index URL, the way an image in a web page resolves against the page: for an index at `https://market.example/dsh/index.json`, `"icon": "icons/foo.svg"` loads `https://market.example/dsh/icons/foo.svg`. Publishing the index and an `icons/` directory side by side therefore works on any host without editing the file. An absolute icon URL on another origin (scheme, host, and port) must use `https:`.
+
+This is a minimal index with one npm plugin and one plugin from a Git monorepo:
+
+```json
+{
+  "format": 1,
+  "title": { "en": "Team plugins", "zh": "团队插件" },
+  "plugins": [
+    {
+      "name": "dsh-plugin-foo",
+      "title": "Foo",
+      "description": "Adds the foo tool",
+      "icon": "icons/foo.svg",
+      "author": "Jane Doe",
+      "homepage": "https://github.com/jane/dsh-plugin-foo#readme",
+      "repository": { "url": "https://github.com/jane/dsh-plugin-foo" },
+      "versions": [
+        { "version": "1.1.0", "publishTimestamp": 1790476800, "source": { "type": "npm" }, "engines": { "dsh": ">=0.2.0-rc.2" } },
+        { "version": "1.0.0", "publishTimestamp": 1788000000, "source": { "type": "npm" } }
+      ]
+    },
+    {
+      "name": "@team/dsh-bar",
+      "versions": [
+        {
+          "version": "0.3.0",
+          "publishTimestamp": 1789000000,
+          "source": {
+            "type": "git",
+            "url": "https://gitlab.example.com/team/dsh-plugins",
+            "commit": "3f9c2e1d8a4b6c0e7f1a2b3c4d5e6f708192a3b4",
+            "path": "packages/bar"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+DSH rejects the whole index when any rule below is violated and shows the reason, with the JSON path of the offending value, under the source in **Manage index sources…**.
+
+<a id="generate-an-index"></a>
+## Generate an index with the reference generator
+
+The repository includes a [reference generator](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/plugin-market-generator/README.md) that builds an index from a plain list. Write one npm package name or https Git repository URL per line; blank lines and lines starting with `#` are ignored:
+
+```text
+@team/dsh-foo
+https://gitlab.example.com/team/dsh-plugins
+```
+
+Run it from a DSH checkout:
+
+```sh
+pnpm --filter @deepseek-ai/dsh-plugin-market-generator start --input plugins.txt --output site/index.json --title "Team plugins"
+```
+
+For an npm package, the index lists every version that is not deprecated and declares `dsh.bundle`. For a Git repository, it finds the bundle packages on the default branch and lists their versions at `vX.Y.Z`, `X.Y.Z`, and `<name>@X.Y.Z` tags, plus each package's version on the default branch. Titles, descriptions, icons, authors, and homepages come from each plugin's highest version. Paths are relative to the directory where you run pnpm.
+
+The generator only downloads and reads files; it never installs packages or runs their code. It keeps a cache in `.plugin-market-cache` next to the list, so a repeated run downloads only new versions and commits. Publish the output directory, `index.json` together with its `icons/` directory, as described above.
+
+<a id="index-format"></a>
+## Index format reference
+
+Text fields marked `LocalizedText` are a string or an object of strings keyed by lowercase language ids, such as `{ "en": "Foo", "zh": "甲" }`; an object must contain `en`. Members DSH does not know are ignored.
+
+| Index field | Required | Meaning |
+|---|---|---|
+| `format` | yes | `1`. |
+| `title`, `description` | `title` only | Market name and description, `LocalizedText`. |
+| `metadata.categories`, `metadata.labels` | no | Objects mapping an id to `{ "title": LocalizedText }`. |
+| `metadata.sortKeys` | no | Object mapping an id to `{ "title": LocalizedText, "order": "asc" \| "desc" }`; `order` is the initial direction. |
+| `plugins` | yes | Plugins in the market's default order. |
+
+| Plugin field | Required | Meaning |
+|---|---|---|
+| `name` | yes | npm package name, unique in the index. |
+| `title`, `description` | no | `LocalizedText`; the card shows `name` without a title. |
+| `icon` | no | Inline `data:` URL (SVG, PNG, JPEG, or WebP, at most 32 KiB) or URL, as described above. |
+| `author` | no | Display text. |
+| `homepage` | no | Absolute `https:` or `http:` URL of a page about the plugin; the plugin page links it. |
+| `repository` | no | `{ "url": string, "directory"?: string }`: the source repository's web page, and the package directory inside it. The plugin page links it as **Source code**. |
+| `metadata.category` | no | One declared category id. |
+| `metadata.labels` | no | Declared label ids. |
+| `metadata.sortKeys` | no | Object mapping declared sort-key ids to numbers, such as downloads or ratings. |
+| `versions` | yes | At least one version, in any order. |
+
+| Version field | Required | Meaning |
+|---|---|---|
+| `version` | yes | Exact SemVer version, unique within the plugin. |
+| `publishTimestamp` | yes | Publish time in Unix seconds. |
+| `source` | yes | `{ "type": "npm", "registry"?: url }`, or `{ "type": "git", "url": https-url, "commit": 40-hex-sha, "path"?: directory }`. |
+| `engines.dsh` | no | SemVer range of DSH versions this version runs on; absent means any. |
+
+DSH installs an npm version as `name@version`, asking `registry` first when present, and a Git version as `git+<url>.git#<commit>` with `&path:/<path>` for a package in a subdirectory. `engines.dsh` should match the package's own `engines.dsh`, which DSH checks again at installation; a package without one is checked against its `@deepseek-ai/dsh*` peer dependencies instead. The [format note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-10-02-plugin-market-index-format.md) defines every rule.
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Discover tab reference](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/ui-plugin-market/README.md) describes the tab's controls and states.
+- [Plugin market service](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/plugin-market/README.md) covers fetch limits, caching, and the `plugin_market` tool.
+- [Index validator](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/util/plugin-market-index/README.md) is the library generators can use to check an index before publishing it.
+
+## Dev Note
+
+None.