better-dsh 0.2.3 → 0.2.4

package/dsh-docs/user/develop/practice/llm-adapter.zh.md

@@ -0,0 +1,189 @@
+# LLM 适配器
+
+[English](llm-adapter.md) | 中文
+
+本文介绍如何为 Harness 接入新的模型提供方。
+
+## 概述
+
+LLM 适配器是一个继承 `LlmAdapter` 并实现 `stream()` 方法的类，它会将 Harness 的提供方无关请求转换为具体提供方的 API 调用，并将响应转换回 Harness 分片。
+
+## 最小实现
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import Schema from '@deepseek-ai/schemastery'
+import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
+
+class MyAdapter extends LlmAdapter {
+  private apiKey: string
+
+  constructor(apiKey: string) {
+    super()
+    this.apiKey = apiKey
+  }
+
+  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    // 1. Convert options.messages to the provider format.
+    // 2. Call the streaming API.
+    // 3. Convert the response into StreamChunk values.
+  }
+}
+
+export interface Config {
+  apiKey: string
+  providers: string[]
+}
+
+export const Config: Schema<Config> = Schema.object({
+  apiKey: Schema.string().required(),
+  providers: Schema.array(Schema.string()).required(),
+})
+
+export const name = 'my-llm-adapter'
+export const inject = ['llm']
+
+export function apply(ctx: Context, config: Config) {
+  const adapter = new MyAdapter(config.apiKey)
+  ctx.llm.registerAdapter(config.providers, adapter)
+}
+```
+
+## StreamChunk 协议
+
+`stream()` 必须按以下协议生成分片：
+
+```ts
+import { brandString } from '@deepseek-ai/dsh-brand'
+import type { StreamChunk, ToolCallId } from '@deepseek-ai/dsh-llm'
+
+async function* exampleChunks(): AsyncIterable<StreamChunk> {
+  // 1. Start each content block with block-start.
+  yield { type: 'block-start', index: 0, blockType: 'text' }
+
+  // 2. Stream text through text-delta.
+  yield { type: 'text-delta', index: 0, text: 'Hello' }
+  yield { type: 'text-delta', index: 0, text: ' world' }
+
+  // 3. End each content block with block-end and the complete block.
+  yield {
+    type: 'block-end',
+    index: 0,
+    block: { type: 'text', text: 'Hello world' },
+  }
+
+  // 4. Tool-call block.
+  yield { type: 'block-start', index: 1, blockType: 'tool-call' }
+  yield {
+    type: 'tool-call-delta',
+    index: 1,
+    id: brandString<ToolCallId>('call-123'),
+    name: 'bash',
+    argumentsDelta: '{"command":"ls"}',
+  }
+  yield {
+    type: 'block-end',
+    index: 1,
+    block: {
+      type: 'tool-call',
+      id: brandString<ToolCallId>('call-123'),
+      name: 'bash',
+      arguments: '{"command":"ls"}',
+    },
+  }
+
+  // 5. Token usage.
+  yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
+
+  // 6. Finish reason.
+  yield { type: 'finish', reason: { kind: 'stop' } }
+  // Alternatively, { kind: 'tool-calls' } requests tool execution.
+}
+```
+
+### 关键规则
+
+- 每个 `block-start` 都必须有与之对应的 `block-end`。
+- `index` 从 0 开始递增，用于标识内容块的顺序。
+- `tool-call-delta` 的 `argumentsDelta` 是原始 JSON 文本的增量，可以在一个分片中完整生成，也可以分多个分片生成。
+- `finish` 必须是最后一个分片。
+- `usage` 必须在 `finish` 之前生成。
+
+## GenerateOptions
+
+`stream()` 接收仓库导出的 `GenerateOptions`。它包含模型、适配器拥有的推理强度 ID、对话历史、系统提示词、工具 schema、生成参数、停止序列和中止信号；完整字段以 `@deepseek-ai/dsh-llm` 导出的 TypeScript 类型为准。适配器必须将支持的字段映射到具体 API；如果无法支持某个字段，应抛出带稳定 code 的 `LlmError`，不得静默丢弃。
+
+请覆写 `resolveModel(provider, model, signal?)`，在一次查询中返回确切的提供方／模型身份以及可选的 `context` 和 `reasoning` 元数据。推理元数据包含有序的不透明 ID、展示名称，以及可选的配置默认值；请保留适配器给出的权威可选列表，包括其上游能力 API 返回的 `off`，不要将这些值提升为核心枚举。异步查询必须响应该可选信号，使取消和资源释放过程完全停稳。服务会校验聚合结果，并在调用 `stream()` 前拒绝显式指定但不受支持的推理强度；省略 `reasoning` 表示该模型没有可选的推理强度能力。
+
+## 注册适配器
+
+```ts ignore-check
+ctx.llm.registerAdapter(['my-provider'], adapter)
+```
+
+第一个参数是该适配器处理的提供方路由列表。`GenerateOptions.provider` 选择已注册的适配器，`GenerateOptions.model` 则传入由适配器拥有、无需在生命周期启动时注册的模型 id。适配器能够向选择器公布模型选项时，请覆写 `listModels()`。
+
+## 在 cordis.yml 中使用
+
+```yaml
+- id: my-llm
+  name: './src/my-llm-adapter.ts'
+  config:
+    apiKey: !!js process.env.MY_API_KEY
+    providers:
+      - my-provider
+
+- id: agent-loop
+  name: '@deepseek-ai/dsh-agent-loop'
+  config:
+    agents:
+      - id: main
+        provider: my-provider
+        model: my-model-v1
+```
+
+## 实战参考
+
+仓库中包含以下两个完整实现：
+
+- `packages/llm/llm-deepseek/` — DeepSeek API 适配器（OpenAI 兼容格式）
+- `packages/llm/llm-pi-ai/` — Pi AI 适配器（不同的 API 格式）
+
+对比这两个已交付的适配器，可以看到同一套 harness 契约如何在不同提供方 SDK 之上实现。
+
+## 错误处理
+
+适配器应通过带稳定 code 的 `LlmError` 抛出传输和协议故障；agent loop（智能体循环）会保留该错误及其 code，用于诊断和策略处理。不要依赖普通 `Error` 被自动转换。每个提供方 HTTP 请求还必须合并 `attributionHeaders()`，并传递 `options.signal`。
+
+```ts
+import {
+  attributionHeaders,
+  LlmAdapter,
+  LlmError,
+  type GenerateOptions,
+  type StreamChunk,
+} from '@deepseek-ai/dsh-llm'
+
+class HttpAdapter extends LlmAdapter {
+  constructor(private readonly endpoint: string) {
+    super()
+  }
+
+  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const response = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...attributionHeaders(),
+      },
+      body: JSON.stringify({ model: options.model, messages: options.messages }),
+      ...options.signal ? { signal: options.signal } : {},
+    })
+    if (!response.ok) {
+      throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
+    }
+    // A real adapter parses the response and emits the complete chunk sequence.
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+}
+```

package/dsh-docs/user/guide/github-review.md

@@ -0,0 +1,102 @@
+# Create review Sessions from GitHub webhooks
+
+English | [中文](github-review.zh.md)
+
+This opt-in overlay adds a signed GitHub endpoint to `dsh web`. When a pull request in the configured repository changes from draft to ready for review, the rule creates a titled root Session under the repository's Web Workspace and starts a read-only review prompt.
+
+## Prerequisites
+
+- A local checkout that DSH may register as a Web Workspace.
+- A high-entropy GitHub webhook secret available through the `DSH_GITHUB_WEBHOOK_SECRET` credential reference.
+- A TLS reverse proxy or tunnel that can forward one public URL to the loopback listener.
+- GitHub webhook subscription to the Pull requests event with content type `application/json`.
+
+The overlay defaults the Workspace to the launch directory and the listener to `127.0.0.1:3081`. Override them with `DSH_GITHUB_REVIEW_WORKSPACE` and `DSH_GITHUB_WEBHOOK_PORT`.
+
+## Start DSH
+
+Generate a secret and retain the same value across restarts:
+
+```sh
+export DSH_GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
+printf '%s\n' "$DSH_GITHUB_WEBHOOK_SECRET"
+```
+
+From a development checkout:
+
+```sh
+export DSH_GITHUB_REVIEW_WORKSPACE=/path/to/deepseek-harness
+pnpm dsh web --patch apps/cli/config/examples/github-review/cordis.yml
+```
+
+An installed DSH uses the same overlay through an absolute path:
+
+```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.
+
+## Expose the dedicated endpoint
+
+The main Web UI and `/api` remain on port 3080. The overlay mounts a second WebServer in an isolated realm; only `POST /github` is registered there, and every other path returns `404`.
+
+A Caddy configuration can expose only that listener:
+
+```caddyfile
+hooks.example.com {
+  route {
+    @github path /github
+    reverse_proxy @github 127.0.0.1:3081
+    respond 404
+  }
+}
+```
+
+Configure GitHub with:
+
+```text
+Payload URL:  https://hooks.example.com/github
+Content type: application/json
+Secret:       DSH_GITHUB_WEBHOOK_SECRET value
+Events:       Pull requests
+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 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.
+
+The HTTP response is intentionally weaker than the Agent outcome: `202` means the signature and JSON were accepted and rule calls were scheduled in memory. It does not mean this rule matched or that a Session was created.
+
+## Programmatic extensions
+
+`run()` is ordinary trusted JavaScript. A deployment can query an internal policy service before returning a Session request:
+
+```js
+const response = await fetch('https://policy.internal/pr-review', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ repository: payload.repository.full_name }),
+  signal,
+})
+if (!response.ok || (await response.json()).automaticReview !== true) return null
+```
+
+It can also map repositories to different local paths:
+
+```js
+const workspacePath = {
+  'deepseek-harness/deepseek-harness': '/path/to/deepseek-harness',
+  'deepseek-harness/dsh-sdk': '/path/to/dsh-sdk',
+}[payload.repository.full_name]
+if (workspacePath === undefined) return null
+```
+
+## Delivery semantics
+
+The webhook runtime stores no delivery or execution state. Repeated delivery runs the rule and may create another Session. A crash loses rule calls that have not admitted their prompt. After prompt admission, the ordinary Session log, persistence, Workspace, and Agent lifecycle own the work.
+
+The webhook secret authenticates inbound GitHub data only. It grants neither rule code nor the created Agent outbound GitHub access; configure that authority separately when a rule or Agent needs it.

package/dsh-docs/user/guide/github-review.zh.md

@@ -0,0 +1,102 @@
+# 通过 GitHub Webhook 创建评审会话
+
+[English](github-review.md) | 中文
+
+此可选 overlay 会为 `dsh web` 增加一个签名 GitHub 端点。当已配置仓库中的 pull request 从 draft 变为 ready for review 时，规则会在该仓库的 Web Workspace 下创建带标题的根 Session，并启动只读评审提示词。
+
+## 前置条件
+
+- 一个可由 DSH 注册为 Web Workspace 的本地 checkout。
+- 一个可通过 `DSH_GITHUB_WEBHOOK_SECRET` 凭据引用访问的高熵 GitHub webhook 密钥。
+- 一个可以把单个公共 URL 转发到 loopback 监听器的 TLS 反向代理或 tunnel。
+- GitHub webhook 订阅 Pull requests 事件，且 content type 为 `application/json`。
+
+overlay 默认使用启动目录作为 Workspace，并监听 `127.0.0.1:3081`。可通过 `DSH_GITHUB_REVIEW_WORKSPACE` 与 `DSH_GITHUB_WEBHOOK_PORT` 覆盖它们。
+
+## 启动 DSH
+
+生成密钥，并在重启后继续使用同一值：
+
+```sh
+export DSH_GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
+printf '%s\n' "$DSH_GITHUB_WEBHOOK_SECRET"
+```
+
+在开发 checkout 中运行：
+
+```sh
+export DSH_GITHUB_REVIEW_WORKSPACE=/path/to/deepseek-harness
+pnpm dsh web --patch apps/cli/config/examples/github-review/cordis.yml
+```
+
+安装版 DSH 通过绝对路径使用同一 overlay：
+
+```sh
+dsh web --patch /absolute/path/to/github-review/cordis.yml
+```
+
+对于永久 profile，把 `github-ready-review-rule.mjs` 放在 `$DSH_HOME/profiles/web/cordis.patch.yml` 旁边，把 `cordis.yml` 中的行追加到该 patch，然后运行 `dsh web`。随附 CLI 已经包含两个 webhook 包；只需 overlay 即可激活它们。
+
+## 暴露专用端点
+
+主 Web UI 与 `/api` 继续位于端口 3080。overlay 会在隔离 realm 中挂载第二个 WebServer；其中只注册 `POST /github`，其他路径均返回 `404`。
+
+Caddy 配置可以只暴露该监听器：
+
+```caddyfile
+hooks.example.com {
+  route {
+    @github path /github
+    reverse_proxy @github 127.0.0.1:3081
+    respond 404
+  }
+}
+```
+
+GitHub 配置如下：
+
+```text
+Payload URL:  https://hooks.example.com/github
+Content type: application/json
+Secret:       DSH_GITHUB_WEBHOOK_SECRET value
+Events:       Pull requests
+Active:       yes
+```
+
+## 规则行为
+
+规则只接受来源 `primary-github`、仓库 `deepseek-harness/deepseek-harness`、事件 `pull_request` 与动作 `ready_for_review`。它会把精确 head SHA 和选定 PR 字段传给评审提示词，把 JSON 标为不受信任的元数据，并禁止修改文件、分支、PR 或 GitHub 状态。
+
+Session 请求选择 `standard` agent preset 与 `read-only` permission preset。`workspacePath` 通过 `WorkspaceRegistry.create()` 规范化，因此第一次匹配交付会在 Workspace 不存在时创建它，后续交付会复用它。
+
+HTTP 响应刻意弱于 Agent 结果：`202` 表示签名与 JSON 已被接受，规则调用已在内存中调度。它不表示此规则已经匹配，也不表示已创建 Session。
+
+## 程序化扩展
+
+`run()` 是普通受信任 JavaScript。部署可以在返回 Session 请求前查询内部策略服务：
+
+```js
+const response = await fetch('https://policy.internal/pr-review', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ repository: payload.repository.full_name }),
+  signal,
+})
+if (!response.ok || (await response.json()).automaticReview !== true) return null
+```
+
+它还可以把仓库映射到不同本地路径：
+
+```js
+const workspacePath = {
+  'deepseek-harness/deepseek-harness': '/path/to/deepseek-harness',
+  'deepseek-harness/dsh-sdk': '/path/to/dsh-sdk',
+}[payload.repository.full_name]
+if (workspacePath === undefined) return null
+```
+
+## 交付语义
+
+webhook runtime 不存储交付或执行状态。重复交付会运行规则，并可能创建另一个 Session。崩溃会丢失尚未接纳提示词的规则调用。提示词接纳后，工作由普通 Session 日志、persistence、Workspace 与 Agent 生命周期拥有。
+
+webhook 密钥只验证入站 GitHub 数据。它不会向规则代码或所创建 Agent 授予出站 GitHub 访问权；规则或 Agent 需要时应单独配置该权限。

package/dsh-docs/user/guide/index.md

@@ -0,0 +1,30 @@
+# Use the Web UI
+
+English | [中文](index.zh.md)
+
+Start the Web UI through the [root README](../../../README.md#run); the command prints its URL. This guide begins after that server is running. The `dsh` process uses its invoking directory as the default filesystem location, but a fresh Web UI has no selected workspace until you add one.
+
+## Configure a model
+
+Open **Settings → Models**, enter a [DeepSeek API key](https://platform.deepseek.com/), and save it. The model route becomes usable immediately without restarting the server.
+
+The [model configuration guide](./providers.md) covers other providers and custom OpenAI-compatible endpoints.
+
+## Choose a workspace
+
+Click **Choose workspace**, add the project directory where you started `dsh`, and select it. The session composer remains unavailable until a workspace is selected.
+
+## Run a task
+
+Start a session and send:
+
+> Summarize this repository and identify its main packages.
+
+The agent can read and edit workspace files, run commands, delegate work, and maintain a plan. The Web UI asks before operations that require approval under the active permission policy.
+
+## Continue
+
+- [Configure models](./providers.md)
+- [Use the Python SDK](./python-sdk.md)
+- [Use other CLI modes](../../../apps/cli/README.md)
+- [Develop a plugin](../develop/basic/index.md)

package/dsh-docs/user/guide/index.zh.md

@@ -0,0 +1,30 @@
+# 使用 Web UI
+
+[English](index.md) | 中文
+
+请先按照[根目录 README](../../../README.zh.md#run) 中的说明启动 Web UI；命令会打印其访问地址。本指南从服务器已经运行的状态开始。`dsh` 进程会把启动时所在的目录作为默认文件系统位置；全新的 Web UI 则不会选中任何工作区，你需要添加一个工作区。
+
+## 配置模型
+
+打开**设置 → 模型**，输入 [DeepSeek API 密钥](https://platform.deepseek.com/)并保存。模型路由会立即可用，不需要重启服务器。
+
+[模型配置指南](./providers.zh.md)介绍其他提供方和自定义 OpenAI 兼容端点。
+
+## 选择工作区
+
+点击**选择工作区**，添加启动 `dsh` 时所在的项目目录，然后选中它。选中工作区前，会话输入框不可用。
+
+## 运行任务
+
+启动一个会话并发送：
+
+> Summarize this repository and identify its main packages.
+
+Agent（智能体）可以读取和编辑工作区文件、运行命令、委派工作并维护计划。如果根据当前权限策略，某项操作需要审批，Web UI 会先询问你。
+
+## 继续使用
+
+- [配置模型](./providers.zh.md)
+- [使用 Python SDK](./python-sdk.zh.md)
+- [使用其他 CLI 模式](../../../apps/cli/README.zh.md)
+- [开发插件](../develop/basic/index.zh.md)

package/dsh-docs/user/guide/mcp-memory.md

@@ -0,0 +1,101 @@
+# Connect a third-party memory MCP server
+
+English | [中文](mcp-memory.zh.md)
+
+These three **default-off reference configurations** connect one memory system to DSH through [`@deepseek-ai/dsh-mcp-client`](../../../packages/mcp/mcp-client/README.md). Pick one, or copy the same generic MCP row for another server.
+
+These third-party configurations are provided as interoperability examples only. Their inclusion does not imply endorsement, recommendation, partnership, or ongoing support by DeepSeek.
+
+## What DSH does
+
+DSH parses the selected Cordis overlay, starts a configured stdio command or connects to a configured Streamable HTTP URL, discovers MCP tools, and exposes them as `mcp__<serverName>__<tool>`. DSH does **not** download the server, initialize its database, choose its model or embedding provider, create a cloud account, migrate vendor data, or supervise a separate HTTP service. For stdio, the generic client launches and stops the child with the DSH plugin lifecycle; for HTTP, the upstream service must already be running.
+
+The stdio bridge deliberately removes ambient variables whose names usually identify credentials and all `DSH_*` variables before launching a child; other ambient variables remain inherited. Each example adds only the baseline override it needs. If an optional upstream feature needs another secret, add that variable to the row's `config.env` instead of putting the secret directly in YAML.
+
+## Choose one
+
+| System | Tested pin | Transport | Upstream prerequisite |
+|---|---:|---|---|
+| [Memorix](https://github.com/AVIDS2/memorix) | `memorix@1.3.0` (`500792cad3144142293bfbb20acb4841c9f7fcfa`) | stdio | Node 22.18+ and `npm install --global memorix@1.3.0` |
+| [MCP Reference Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) | `@modelcontextprotocol/server-memory@2026.7.4` (`6dd0a683e198783e30feabf7abaf42f925bd18b1`) | stdio | `npm install --global @modelcontextprotocol/server-memory@2026.7.4` |
+| [Engram](https://github.com/Gentleman-Programming/engram) | `v1.20.0` (`ba9e46ced152c37a7cb9e576153c41995873e2fc`) | stdio | Go 1.25.10+ and `go install github.com/Gentleman-Programming/engram/cmd/engram@v1.20.0`, or the matching release binary |
+
+## Enable one
+
+Pass one overlay to DSH:
+
+```sh
+dsh web --patch "$PWD/apps/cli/config/examples/mcp-memory/memorix.cordis.yml"
+```
+
+Replace the filename with `mcp-reference-memory.cordis.yml` or `engram.cordis.yml`. The path may point to a copied file anywhere on disk. No memory server is present in the shipped composition, so omitting `--patch` keeps all three disabled.
+
+To keep the selection across runs, merge the chosen file's single `insert` patch into a user patch layer — `$DSH_HOME/profiles/<name>/cordis.patch.yml` for one profile, or `$DSH_HOME/cordis.patch.yml` for every profile on the machine. Do not copy over an existing file: it may already contain unrelated user patches.
+
+## Provider setup
+
+### Memorix
+
+```sh
+npm install --global memorix@1.3.0
+dsh web --patch "$PWD/apps/cli/config/examples/mcp-memory/memorix.cordis.yml"
+```
+
+Memorix works in local heuristic mode without an LLM or embedding service. Configure optional providers in Memorix's own `~/.memorix/config.toml` or project `memorix.toml`. The example keeps Memorix's Git-project identity from the DSH working directory and uses Memorix's own `~/.memorix/data` default. Set `MEMORIX_DATA_DIR` before starting DSH to override it.
+
+### MCP Reference Memory
+
+```sh
+npm install --global @modelcontextprotocol/server-memory@2026.7.4
+dsh web --patch "$PWD/apps/cli/config/examples/mcp-memory/mcp-reference-memory.cordis.yml"
+```
+
+This reference server stores a local knowledge graph and exposes entity, relation, observation, read, search, and open tools. It needs no model or embedding service. The example stores its JSONL at `$HOME/.dsh-mcp-reference-memory.jsonl` instead of the installed npm package directory. Set `MEMORY_FILE_PATH` before starting DSH to override it.
+
+Search is case-insensitive substring matching over entity names, types, and observations, not semantic retrieval. The server does not add embeddings, automatic summarization, conflict resolution, or a forgetting policy.
+
+### Engram
+
+```sh
+go install github.com/Gentleman-Programming/engram/cmd/engram@v1.20.0
+dsh web --patch "$PWD/apps/cli/config/examples/mcp-memory/engram.cordis.yml"
+```
+
+Engram owns storage and project selection: it uses `~/.engram` by default, detects the Git project from the DSH working directory, and accepts `ENGRAM_DATA_DIR` or `ENGRAM_PROJECT` as ambient overrides.
+
+## Optional shared model instruction
+
+Add this short, vendor-neutral instruction to your existing model instructions if the server's tool descriptions do not trigger memory use reliably:
+
+> When the user asks you to remember something, call a memory write tool. When historical information may be relevant, search memory and use relevant results.
+
+This is additive guidance only. The examples do not replace DSH's system-prompt persona.
+
+## Verify write, fresh-session recall, and use
+
+Use one unique value and keep the provider's storage scope unchanged throughout:
+
+1. In DSH session A, ask: `Remember that my validation drink is lapsang-<unique suffix>.` Confirm the model called the provider's write tool and the tool returned success.
+2. Create DSH session B in the same running Host. Do not copy session A's conversation. Ask: `What is my validation drink? Check memory.` Confirm the model called the provider's search or recall tool and returned the value.
+3. Still in session B, ask: `Use that preference to suggest one drink for the meeting.` Confirm the answer uses the recalled value.
+
+A new DSH session is required; a Host restart is not. A crashed MCP child triggers automatic reconnection with backoff and a tool re-sync; tools stay listed and calls fail only during the outage, and after the reconnect budget is exhausted the tools are unregistered and reconnection stops until a reload or restart. Initial discovery is asynchronous, so wait for the provider's `mcp__...` tools before sending the first validation prompt.
+
+## Bring another MCP server
+
+Copy the same entry fields and use a unique `id` and `serverName`:
+
+```yaml
+- insert:
+    - id: memory-my-server
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: my-memory
+        transport: stdio
+        command: my-memory-mcp
+        args: []
+        env: {}
+        cwd: !!js process.cwd()
+```
+
+For a remote server, use `transport: streamable-http`, `url`, and `headers` instead. Provider-specific installation, identity, authentication, models, embeddings, persistence, and licensing remain the provider's responsibility.

package/dsh-docs/user/guide/mcp-memory.zh.md

@@ -0,0 +1,101 @@
+# 连接第三方记忆 MCP 服务
+
+[English](mcp-memory.md) | 中文
+
+这三份**默认关闭的参考配置**通过 [`@deepseek-ai/dsh-mcp-client`](../../../packages/mcp/mcp-client/README.zh.md) 将一个记忆系统连接到 DSH。请选择其中一份，或复制相同的通用 MCP 配置项来连接其他服务器。
+
+这些第三方配置仅作为互操作参考；收录不代表 DeepSeek 的认可、推荐、合作关系或持续支持承诺。
+
+## DSH 负责什么
+
+DSH 解析选中的 Cordis overlay，启动已配置的 stdio 命令或连接已配置的 Streamable HTTP URL，发现 MCP 工具，并以 `mcp__<serverName>__<tool>` 的形式公开这些工具。DSH **不负责** 下载服务器、初始化其数据库、选择模型或 embedding 提供方、创建云端账户、迁移提供方数据，也不监管独立的 HTTP 服务。对于 stdio，通用客户端会随 DSH 插件生命周期启动和停止子进程；对于 HTTP，上游服务必须已经运行。
+
+stdio 桥接器在启动子进程前会主动移除环境中名称通常表示凭据的变量和所有 `DSH_*` 变量；其余环境变量仍会继承。每份示例仅添加其基线所需的覆盖项。如果某个可选的上游功能还需要其他密钥，请将该变量添加到配置项的 `config.env`，不要把密钥直接写进 YAML。
+
+## 选择一个
+
+| 系统 | 已测试版本 | 传输方式 | 上游前置条件 |
+|---|---:|---|---|
+| [Memorix](https://github.com/AVIDS2/memorix) | `memorix@1.3.0`（`500792cad3144142293bfbb20acb4841c9f7fcfa`） | stdio | Node 22.18+，并执行 `npm install --global memorix@1.3.0` |
+| [MCP Reference Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) | `@modelcontextprotocol/server-memory@2026.7.4`（`6dd0a683e198783e30feabf7abaf42f925bd18b1`） | stdio | `npm install --global @modelcontextprotocol/server-memory@2026.7.4` |
+| [Engram](https://github.com/Gentleman-Programming/engram) | `v1.20.0`（`ba9e46ced152c37a7cb9e576153c41995873e2fc`） | stdio | Go 1.25.10+，并执行 `go install github.com/Gentleman-Programming/engram/cmd/engram@v1.20.0`，或安装匹配的发布版二进制文件 |
+
+## 启用一个
+
+将一份 overlay 传给 DSH：
+
+```sh
+dsh web --patch "$PWD/apps/cli/config/examples/mcp-memory/memorix.cordis.yml"
+```
+
+请将文件名替换为 `mcp-reference-memory.cordis.yml` 或 `engram.cordis.yml`。该路径可以指向磁盘任意位置的一份复制文件。交付组合不包含任何记忆服务器，因此不传 `--patch` 就会让这三项全部保持关闭。
+
+如果要跨次运行保留所选配置，请将对应文件中的单个 `insert` patch 合并到用户 patch 层：只对一个 profile 生效则写入 `$DSH_HOME/profiles/<name>/cordis.patch.yml`，对本机所有 profile 生效则写入 `$DSH_HOME/cordis.patch.yml`。不要覆盖已有文件，其中可能已经包含无关的用户 patch。
+
+## 提供方设置
+
+### Memorix
+
+```sh
+npm install --global memorix@1.3.0
+dsh web --patch "$PWD/apps/cli/config/examples/mcp-memory/memorix.cordis.yml"
+```
+
+Memorix 无需 LLM（大语言模型）或 embedding 服务，即可在本地启发式模式下运行。请在 Memorix 自己的 `~/.memorix/config.toml` 或项目 `memorix.toml` 中配置可选提供方。该示例沿用 DSH 工作目录中的 Git 项目标识，并使用 Memorix 自身的默认目录 `~/.memorix/data`。若要覆盖该目录，请在启动 DSH 前设置 `MEMORIX_DATA_DIR`。
+
+### MCP Reference Memory
+
+```sh
+npm install --global @modelcontextprotocol/server-memory@2026.7.4
+dsh web --patch "$PWD/apps/cli/config/examples/mcp-memory/mcp-reference-memory.cordis.yml"
+```
+
+该参考服务器存储本地知识图谱，并公开实体、关系、观察、读取、搜索和打开工具。它不需要模型或 embedding 服务。该示例将 JSONL 存储在 `$HOME/.dsh-mcp-reference-memory.jsonl`，而不是已安装的 npm 包目录中。若要覆盖该路径，请在启动 DSH 前设置 `MEMORY_FILE_PATH`。
+
+搜索只对实体名称、类型和观察进行不区分大小写的子字符串匹配，不是语义检索。该服务器不提供 embedding、自动摘要、冲突消解或遗忘策略。
+
+### Engram
+
+```sh
+go install github.com/Gentleman-Programming/engram/cmd/engram@v1.20.0
+dsh web --patch "$PWD/apps/cli/config/examples/mcp-memory/engram.cordis.yml"
+```
+
+Engram 负责存储和项目选择：它默认使用 `~/.engram`，从 DSH 工作目录检测 Git 项目，并接受 `ENGRAM_DATA_DIR` 或 `ENGRAM_PROJECT` 作为环境覆盖项。
+
+## 可选的共用模型指令
+
+如果服务器的工具描述无法可靠触发记忆使用，请将以下简短、与提供方无关的指令添加到你现有的模型指令中：
+
+> 用户要求记住某事时调用记忆写入工具；历史信息可能相关时，检索记忆并使用相关结果。
+
+这只是附加指导。示例不会替换 DSH 系统提示词中的 persona。
+
+## 验证写入、新会话召回和使用
+
+请在整个过程中使用一个唯一值，并保持提供方的存储范围不变：
+
+1. 在 DSH 会话 A 中提出：`Remember that my validation drink is lapsang-<unique suffix>.`。确认模型调用了提供方的写入工具，并且工具返回成功。
+2. 在同一个仍在运行的 Host 中创建 DSH 会话 B。不要复制会话 A 的对话。提出：`What is my validation drink? Check memory.`。确认模型调用了提供方的搜索或召回工具，并返回该值。
+3. 继续在会话 B 中提出：`Use that preference to suggest one drink for the meeting.`。确认回答使用了召回的值。
+
+必须新建 DSH 会话，但不需要重启 Host。MCP 子进程崩溃后会触发带退避的自动重连与工具重新同步；停机期间工具仍保持列出，调用只在停机期间失败；重连预算耗尽后工具会被注销，重连停止，直到重新加载或重启。初始发现过程是异步的，因此发送第一条验证提示词前，请等待提供方的 `mcp__...` 工具出现。
+
+## 接入其他 MCP 服务器
+
+复制相同的条目字段，并使用唯一的 `id` 和 `serverName`：
+
+```yaml
+- insert:
+    - id: memory-my-server
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: my-memory
+        transport: stdio
+        command: my-memory-mcp
+        args: []
+        env: {}
+        cwd: !!js process.cwd()
+```
+
+对于远程服务器，请改用 `transport: streamable-http`、`url` 和 `headers`。提供方专属的安装、身份、认证、模型、embedding、持久化和许可仍由提供方负责。