mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-08-29 04:26:38 +00:00
refactor(repo): retire top-level examples
This commit is contained in:
Tianyi Cui
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# 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/practice/dynamic-cordis.md
|
||||
dynamic-cordis.md: 5e324f88c9fc5ac8f770749cf4ab2c97d175121d
|
||||
dynamic-cordis.zh.md: 69486cd0d2bacf7c0831e12801128be22fb209ef
|
||||
@@ -0,0 +1,15 @@
|
||||
# Extend a running agent with Cordis tools
|
||||
|
||||
English | [中文](dynamic-cordis.zh.md)
|
||||
|
||||
This practice guide enables [`@deepseek-ai/dsh-tool-cordis`](../../../../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.
|
||||
|
||||
## Run it
|
||||
|
||||
Start the browser interface with the checked-in overlay:
|
||||
|
||||
```sh
|
||||
pnpm dsh web --patch apps/cli/config/examples/cordis/cordis.yml
|
||||
```
|
||||
|
||||
The command requires a model credential. The [Cordis tool reference](../../../../packages/extensions/tool-cordis/README.md) defines the tool arguments, lifetime, cleanup, and safety contracts.
|
||||
@@ -0,0 +1,15 @@
|
||||
# 用 Cordis 工具扩展运行中的智能体
|
||||
|
||||
[English](dynamic-cordis.md) | 中文
|
||||
|
||||
本实战指南启用 [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/extensions/tool-cordis/README.zh.md)。智能体可以检查当前 Cordis 进程，并在内存中挂载或卸载模型编写的插件。临时插件会在卸载或进程退出时消失，并可能影响同一进程中的其他会话。
|
||||
|
||||
## 运行
|
||||
|
||||
使用仓库内 overlay 启动浏览器界面：
|
||||
|
||||
```sh
|
||||
pnpm dsh web --patch apps/cli/config/examples/cordis/cordis.yml
|
||||
```
|
||||
|
||||
该命令需要模型凭据。[Cordis 工具参考](../../../../packages/extensions/tool-cordis/README.zh.md)定义了四类约定：工具参数、存续时间、清理行为和安全性。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# 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/guide/github-review.md
|
||||
github-review.md: 2f777acdd0e8b4996a29a0b78262b1ba3ff9188c
|
||||
github-review.zh.md: 7518a13f3d74801dbfb4d0810c89851f4616a2ef
|
||||
@@ -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=/Users/cty/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': '/Users/cty/deepseek-harness',
|
||||
'deepseek-harness/dsh-sdk': '/Users/cty/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 again 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.
|
||||
@@ -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=/Users/cty/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': '/Users/cty/deepseek-harness',
|
||||
'deepseek-harness/dsh-sdk': '/Users/cty/dsh-sdk',
|
||||
}[payload.repository.full_name]
|
||||
if (workspacePath === undefined) return null
|
||||
```
|
||||
|
||||
## 交付语义
|
||||
|
||||
webhook runtime 不存储交付或执行状态。重复交付会再次运行规则，并可能创建另一个 Session。崩溃会丢失尚未接纳提示词的规则调用。提示词接纳后，工作由普通 Session 日志、persistence、Workspace 与 Agent 生命周期拥有。
|
||||
|
||||
webhook 密钥只验证入站 GitHub 数据。它不会向规则代码或所创建 Agent 授予出站 GitHub 访问权；规则或 Agent 需要时应单独配置该权限。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# 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/guide/mcp-memory.md
|
||||
mcp-memory.md: b7654f2d751556ab5d51f90570e7f1f7915e6ea5
|
||||
mcp-memory.zh.md: 36b26160fd29e706a98eacd57182f7a655983d24
|
||||
@@ -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. Restart or HMR is needed only after an MCP child crashes because the current generic client does not auto-reconnect; its tool registrations remain until plugin disposal or a successful re-sync, and calls can fail against the closed transport. 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.
|
||||
@@ -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 子进程崩溃后才需要重启或执行 HMR（热模块替换），因为当前的通用客户端不会自动重连；其工具注册会一直保留，直到插件 dispose（资源释放）或成功重新同步，针对已关闭传输的调用可能失败。初始发现过程是异步的，因此发送第一条验证提示词前，请等待提供方的 `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、持久化和许可仍由提供方负责。
|
||||
@@ -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/guide/python-sdk.md
|
||||
python-sdk.md: 388b259f0adbba11b7d359fcf861980cf0a3bec7
|
||||
python-sdk.zh.md: 2cc23e5cd1d7d7df5ad4b27441c54e6c3239c917
|
||||
python-sdk.md: 88cf32f60c285a4ce7c09e424532a6d9b7b00890
|
||||
python-sdk.zh.md: e443ec811a3b42034c75162b759408f1acd3486f
|
||||
|
||||
@@ -59,7 +59,7 @@ Run one task with explicit workspace and home paths:
|
||||
### Linux and macOS
|
||||
|
||||
```sh
|
||||
python examples/python-sdk-agent/minimal.py \
|
||||
python python/sdk/examples/minimal.py \
|
||||
--workspace /absolute/path/to/disposable-workspace \
|
||||
--dsh-home /absolute/path/to/example-dsh-home \
|
||||
--session-id example-001 \
|
||||
@@ -69,7 +69,7 @@ python examples/python-sdk-agent/minimal.py \
|
||||
### Windows PowerShell
|
||||
|
||||
```powershell
|
||||
python examples/python-sdk-agent/minimal.py `
|
||||
python python/sdk/examples/minimal.py `
|
||||
--workspace C:\work\disposable-workspace `
|
||||
--dsh-home C:\work\example-dsh-home `
|
||||
--session-id example-001 `
|
||||
@@ -147,4 +147,4 @@ The installed wheel still packages the full `web` profile and frontend assets. R
|
||||
|
||||
Use a fresh home when profiles, plugins, credentials, settings, and sessions must be isolated. Use a fresh session id for independent work; reuse a harness, home, and id only to continue the same durable conversation and session-owned resources.
|
||||
|
||||
The [bundle reference](../../../packages/bundle/sdk-minimal/README.md) owns the exact tree, and the [example reference](../../../examples/python-sdk-agent/README.md) owns the runnable program. The [Python SDK reference](../../../python/sdk/README.md) covers lifecycle, results, notifications, and low-level behavior; the [dsh CLI reference](../../../apps/cli/reference/README.md) covers profile layering.
|
||||
The [bundle reference](../../../packages/bundle/sdk-minimal/README.md) owns the exact tree, and the [example reference](../../../python/sdk/examples/README.md) owns the runnable program. The [Python SDK reference](../../../python/sdk/README.md) covers lifecycle, results, notifications, and low-level behavior; the [dsh CLI reference](../../../apps/cli/reference/README.md) covers profile layering.
|
||||
|
||||
@@ -59,7 +59,7 @@ $env:DEEPSEEK_API_KEY = "sk-your-key-here"
|
||||
### Linux 与 macOS
|
||||
|
||||
```sh
|
||||
python examples/python-sdk-agent/minimal.py \
|
||||
python python/sdk/examples/minimal.py \
|
||||
--workspace /absolute/path/to/disposable-workspace \
|
||||
--dsh-home /absolute/path/to/example-dsh-home \
|
||||
--session-id example-001 \
|
||||
@@ -69,7 +69,7 @@ python examples/python-sdk-agent/minimal.py \
|
||||
### Windows PowerShell
|
||||
|
||||
```powershell
|
||||
python examples/python-sdk-agent/minimal.py `
|
||||
python python/sdk/examples/minimal.py `
|
||||
--workspace C:\work\disposable-workspace `
|
||||
--dsh-home C:\work\example-dsh-home `
|
||||
--session-id example-001 `
|
||||
@@ -147,4 +147,4 @@ dsh plugin --profile sdk-minimal add file:C:/work/my-plugin-bundle
|
||||
|
||||
需要隔离 profile、插件、凭据、设置与会话时，应使用新的 home。独立工作应使用新的 session id；只有继续同一段持久对话和会话资源时，才同时复用 harness、home 与 id。
|
||||
|
||||
[组合包参考](../../../packages/bundle/sdk-minimal/README.zh.md)定义确切配置树，[示例参考](../../../examples/python-sdk-agent/README.zh.md)定义可运行程序。[Python SDK 参考](../../../python/sdk/README.zh.md)介绍生命周期、结果、通知与底层行为；[dsh CLI 参考](../../../apps/cli/reference/README.zh.md)介绍 profile 分层。
|
||||
[组合包参考](../../../packages/bundle/sdk-minimal/README.zh.md)定义确切配置树，[示例参考](../../../python/sdk/examples/README.zh.md)定义可运行程序。[Python SDK 参考](../../../python/sdk/README.zh.md)介绍生命周期、结果、通知与底层行为；[dsh CLI 参考](../../../apps/cli/reference/README.zh.md)介绍 profile 分层。
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# 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/guide/schedule.md
|
||||
schedule.md: 58cfda2e79f05129b367fad98c595a2c67a6e32e
|
||||
schedule.zh.md: 75f85b1847c8e02cbd06d21f953ea6814a71ef40
|
||||
@@ -0,0 +1,19 @@
|
||||
# Schedule session-local reminders
|
||||
|
||||
English | [中文](schedule.zh.md)
|
||||
|
||||
This overlay opts one `dsh web` process into Schedule reminders without changing the shipped default Web composition:
|
||||
|
||||
```sh
|
||||
dsh web --patch apps/cli/config/examples/schedule/cordis.yml
|
||||
```
|
||||
|
||||
The current overlay supports reminders created with a positive whole-number `after_seconds`, an absolute `at` target, or a fixed-rate `every_seconds` interval of at least 300 seconds. The model manages them through `schedule_create`, `schedule_list`, and `schedule_delete`; every result identifies delivery as `session-local`.
|
||||
|
||||
The browser attaches its IANA zone to each prompt. Time-context tells the model to interpret otherwise-unqualified dates and times in that request's browser zone. This assumption belongs to natural-language interpretation only: `schedule_create.at` must be either a strict RFC 3339 date-time with `Z` or a numeric offset, or `{ date, time, time_zone }` with an explicit `UTC` or IANA Area/Location zone. Schedule does not retain or infer a Session default zone. Daylight-saving gaps are rejected, overlaps choose the first instant, and successful records keep only the resulting UTC target.
|
||||
|
||||
The original Session log owns each reminder. A live root Agent waits until it is fully idle, then queues a normal follow-up turn in that conversation. It never steers current work and adds no separate receipt or reminder card. Closing the process or leaving the Session cold stops its in-memory timer without deleting the record; reopening that same Session restores the wait and delivers an overdue reminder. Reading cold history never activates it, and a fork does not inherit its parent's reminders.
|
||||
|
||||
Every reminders stay aligned to their creation time. If one is overdue, only its latest due occurrence is presented and the next target remains on the original fixed-rate sequence. All distinct Every records overdue at the same idle decision are combined into one follow-up with one occurrence each; missed intervals do not create a backlog. Due one-shots run before that batch. Calendar and Cron expressions are not supported.
|
||||
|
||||
Create and actual delete operations acknowledge success only after Session persistence confirms their event prefix. Schedule does not provide browser, operating-system, email, SMS, or other external notification. A durable dispatch records that the follow-up was queued; it does not acknowledge model success or user receipt.
|
||||
@@ -0,0 +1,19 @@
|
||||
# 安排会话内提醒
|
||||
|
||||
[English](schedule.md) | 中文
|
||||
|
||||
此 overlay 让一个 `dsh web` 进程显式启用 Schedule 提醒，同时不改变交付的默认 Web 组合：
|
||||
|
||||
```sh
|
||||
dsh web --patch apps/cli/config/examples/schedule/cordis.yml
|
||||
```
|
||||
|
||||
当前 overlay 支持使用正整数 `after_seconds`、绝对时间 `at` 目标，或至少 300 秒的固定速率 `every_seconds` 间隔创建提醒。模型通过 `schedule_create`、`schedule_list` 和 `schedule_delete` 管理它们；每个结果都会把交付标为 `session-local`。
|
||||
|
||||
浏览器会为每条提示词附加其 IANA 时区。Time-context 会告诉模型，把未明确限定时区的日期和时间解释为该请求的浏览器时区。此假设仅用于自然语言解释：`schedule_create.at` 必须是带 `Z` 或数值偏移量且严格符合 RFC 3339 的日期时间，或是带显式 `UTC` 或 IANA Area/Location 时区的 `{ date, time, time_zone }`。Schedule 不保留或推断 Session 默认时区。夏令时缺口会被拒绝，重叠时段选择第一个时刻；成功创建的记录只保留所得的 UTC 目标。
|
||||
|
||||
每条提醒由原 Session 日志拥有。live 根 Agent 会等待到完全 idle，再在该对话中排入一个普通 follow-up 轮次。它绝不会中途引导当前工作，也不会添加独立回执或提醒卡片。关闭进程或让 Session 保持 cold 会停止内存 timer，但不会删除记录；重新打开同一个 Session 会恢复等待并交付逾期提醒。查看 cold 历史不会激活提醒，fork 也不会继承父 Session 的提醒。
|
||||
|
||||
Every 提醒始终与其创建时刻对齐。如果提醒逾期，只会呈现最新一个到期发生时点，下一个目标仍保留在原固定速率序列上。同一次 idle 决策中逾期的所有不同 Every 记录会合并为一个 follow-up，每条记录各有一个发生时点；错过的间隔不会形成积压。已到期的一次性提醒会在该批次之前运行。不支持日历表达式和 Cron 表达式。
|
||||
|
||||
创建和实际删除操作只有在 Session persistence 确认对应事件前缀后才会确认成功。Schedule 不提供浏览器、操作系统、邮件、短信或其他外部通知。持久 dispatch 会记录 follow-up 已经入队；它不确认模型成功或用户已收到提醒。
|
||||
Reference in New Issue
Block a user