Merge branch 'master' into fix/web-turn-error-surface
This commit is contained in:
Ziya
@@ -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 .agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md
|
||||
2026-07-29-persistent-bash-str-replace-editor.md: a97af750bdd80ddf38dc2d126e70c245ed035f35
|
||||
2026-07-29-persistent-bash-str-replace-editor.zh.md: 0c2ab26693d90c91d5c41a128ebb77a3c6cc2e7f
|
||||
2026-07-29-persistent-bash-str-replace-editor.md: 22851078c1cc8fa9d5716afa41c8a2e2b7e7725c
|
||||
2026-07-29-persistent-bash-str-replace-editor.zh.md: cf4d18f26d11380a637d573e8ea98cb3ccfcdb59
|
||||
|
||||
@@ -18,6 +18,8 @@ Some deployments need a one-call Bash schema whose shell state survives across m
|
||||
|
||||
Both plugins are included in the Python runtime closure. The persistent Bash closure also includes the PTY service/local backend and the sandbox services required by that backend. Because `node-pty` executes a native `spawn-helper` on macOS, each packaged macOS runtime executable ships with a `-spawn-helper` sibling; Linux uses `forkpty` directly. A pinned `node-pty` patch checks `DSH_NODE_PTY_SPAWN_HELPER` first, so it remains a true override for a current external consumer that supplies a non-sibling helper. When the override is unset, the patch resolves the packaged executable sibling if present and otherwise preserves upstream lookup in ordinary Node runs. The macOS builders fail before publication when the helper is absent or not executable.
|
||||
|
||||
The shipped [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) overlay composes both plugins over the ordinary Web surface, disables its other model-facing consumers, and leaves the Web host, browser, Workspace, persistence, sandbox, and permission stack in place. The local PTY backend resolves the effective session sandbox mode when it creates the shell. While that owner has an open shell or a spawn in progress, a different permission mode is rejected before its session event commits; the editor continues through the Web filesystem sandbox.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**One combined compatibility plugin.** Rejected because neither tool requires the other and the combined name would tie reusable capabilities to one benchmark.
|
||||
@@ -30,4 +32,4 @@ Both plugins are included in the Python runtime closure. The persistent Bash clo
|
||||
|
||||
## Consequences
|
||||
|
||||
Profiles can reproduce an external agent by configuring persona and descriptions while the underlying packages remain general. Persistent Bash requires an owning Agent and real PTY backend. Shell exit, timeout, or cancellation loses state. The editor delegates security and mutation policy to the mounted filesystem stack. Runtime-wheel consumers still need no Node installation; Linux wheels contain one executable, while macOS wheels also contain its private native helper.
|
||||
Profiles can reproduce an external agent by configuring persona and descriptions while the underlying packages remain general. Persistent Bash requires an owning Agent and real PTY backend. Shell exit, timeout, or cancellation loses state. The editor delegates security and mutation policy to the mounted filesystem stack. The Core Web profile retains Web permissions but must close its persistent shell before changing modes. Runtime-wheel consumers still need no Node installation; Linux wheels contain one executable, while macOS wheels also contain its private native helper.
|
||||
|
||||
@@ -18,6 +18,8 @@
|
||||
|
||||
两个插件都进入 Python runtime 闭包。持久 Bash 的闭包还包含 PTY 服务／本地后端，以及该后端要求的沙箱服务。由于 `node-pty` 在 macOS 上会执行原生 `spawn-helper`，每个打包后的 macOS 运行时可执行文件都会携带一个 `-spawn-helper` 伴随文件；Linux 直接使用 `forkpty`。固定版本的 `node-pty` 补丁会先检查 `DSH_NODE_PTY_SPAWN_HELPER`，因此对当前提供非伴随 helper 的外部消费方而言，该变量仍是真正的覆盖项。未设置该覆盖时，补丁会在打包可执行文件的伴随文件存在时解析它，否则在普通 Node 运行中保留上游查找方式。若 helper 缺失或不可执行，macOS 构建器会在发布前失败。
|
||||
|
||||
已交付的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) 覆盖层在常规 Web 界面之上组合这两个插件，禁用该界面的其他面向模型的消费方，并保留 Web 宿主、浏览器、Workspace、持久化、沙箱与权限栈。本地 PTY 后端会在创建 shell 时解析会话的有效沙箱模式。只要该所有者仍有打开的 shell 或仍在进行中的 spawn，另一种权限模式就会在对应的会话事件提交前遭到拒绝；编辑器则继续经由 Web 文件系统沙箱运行。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**单一组合兼容插件。** 被拒绝，因为两个工具互不依赖，组合命名还会把可复用能力绑定到某个基准。
|
||||
@@ -30,4 +32,4 @@
|
||||
|
||||
## 后果
|
||||
|
||||
Profile 可以通过配置 persona 和描述复现外部 Agent，而底层包保持通用。持久 Bash 需要拥有它的 Agent 与真实 PTY 后端；shell 退出、超时或取消会丢失状态。编辑器把安全与变更策略委托给挂载的文件系统栈。运行时 wheel 包的消费方仍无需安装 Node；Linux wheel 包包含一个可执行文件，macOS wheel 包还包含其私有原生 helper。
|
||||
Profile 可以通过配置 persona 和描述复现外部 Agent，而底层包保持通用。持久 Bash 需要拥有它的 Agent 与真实 PTY 后端；shell 退出、超时或取消会丢失状态。编辑器把安全与变更策略委托给挂载的文件系统栈。Core Web profile 保留 Web 权限，但必须先关闭持久 shell 才能更改权限模式。运行时 wheel 包的消费方仍无需安装 Node；Linux wheel 包包含一个可执行文件，macOS wheel 包还包含其私有原生 helper。
|
||||
|
||||
@@ -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 .agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.md
|
||||
2026-07-31-third-party-memory-mcp-examples.md: e82d65a3a5a60cafcc47df5a6873cf5768cd8b8f
|
||||
2026-07-31-third-party-memory-mcp-examples.zh.md: ee0e9f2e1378f9787e09e32cc05dd13a3648254c
|
||||
@@ -0,0 +1,78 @@
|
||||
# Agent Note: Third-party memory MCP examples
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-31-third-party-memory-mcp-examples.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
A direct vendor integration made one provider's API, configuration, health behavior, and tool semantics part of DSH. That was too much product surface for a capability already expressible through MCP, and it would require repeating the same adaptation for every memory system. Users instead need a small, inspectable way to opt into one external memory server while preserving the generic MCP boundary.
|
||||
|
||||
The acceptance bar is stronger than "the socket connects": each reference must support a real DSH write in session A, recall from the provider in a fresh DSH session B, and use of the recalled value. At the same time, provider downloads, accounts, models, embeddings, storage initialization, and separate HTTP processes must remain upstream responsibilities.
|
||||
|
||||
## Decision
|
||||
|
||||
Ship three default-off Cordis overlay examples under `examples/mcp-memory`: Memorix, MCP Reference Memory, and Engram. Every file inserts exactly one `@deepseek-ai/dsh-mcp-client` row. None is referenced by the shipped composition, and the CLI declares the generic bridge only so an explicitly selected overlay can resolve it.
|
||||
|
||||
These third-party configurations are provided as interoperability examples only. Their inclusion does not imply endorsement, recommendation, partnership, or ongoing support by DeepSeek. There is no memory preset registry, vendor-specific DSH plugin, universal memory service, installation UI, migration layer, health checker, or reconnect controller. Another memory MCP server uses the same documented stdio or Streamable HTTP row.
|
||||
|
||||
## Responsibility boundary
|
||||
|
||||
| Concern | DSH | Upstream provider or user |
|
||||
|---|---|---|
|
||||
| Parse selected overlay | Yes | Select one file |
|
||||
| Start stdio command and stop it on plugin disposal | Yes | Install the pinned executable |
|
||||
| Connect to Streamable HTTP and discover tools | Yes | Run and supervise the HTTP service |
|
||||
| Register tools as `mcp__<serverName>__<rawName>` | Yes | Define tool schemas and behavior |
|
||||
| Account, auth, model, embedding, storage initialization | No | Yes |
|
||||
| Vendor data migration, retry, crash recovery | No | Yes |
|
||||
|
||||
The generic stdio transport scrubs ambient credential-shaped and `DSH_*` variables while inheriting other ambient variables. Baseline examples add only required overrides; optional provider secrets must be added to `config.env` or configured in the provider's own files.
|
||||
|
||||
## Pins, storage, and identity
|
||||
|
||||
| Provider | Tested contract |
|
||||
|---|---|
|
||||
| Memorix | npm `1.3.0`, tag commit `500792cad3144142293bfbb20acb4841c9f7fcfa` |
|
||||
| MCP Reference Memory | npm `2026.7.4`, package commit `6dd0a683e198783e30feabf7abaf42f925bd18b1` |
|
||||
| Engram | tag `v1.20.0`, commit `ba9e46ced152c37a7cb9e576153c41995873e2fc` |
|
||||
|
||||
Storage remains provider-owned. Memorix uses `~/.memorix/data` and Engram uses `~/.engram` by default. The Reference Memory example sets a stable `$HOME/.dsh-mcp-reference-memory.jsonl` path instead of writing into the installed npm package directory. Each provider's own environment variable can override these locations before DSH starts.
|
||||
|
||||
Project identity remains provider-owned: Memorix and Engram use the DSH working directory's Git project, with Engram optionally accepting `ENGRAM_PROJECT`.
|
||||
|
||||
## Model guidance
|
||||
|
||||
The examples do not patch `@deepseek-ai/dsh-system-prompt`: a config patch replaces a row's complete config and could erase an existing persona. The README instead offers one optional additive instruction:
|
||||
|
||||
> 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.
|
||||
|
||||
Provider tool descriptions remain authoritative.
|
||||
|
||||
## Validation contract
|
||||
|
||||
Remote CI never contacts third-party services or consumes secrets. The keyless suite parses all three overlay files, checks their generic bridge and secret boundary, replaces the upstream endpoint with the package-owned MCP fixture server, boots the real Cordis Loader, and proves tool discovery.
|
||||
|
||||
Before merge, manual evidence for every pinned provider must separately show:
|
||||
|
||||
1. DSH session A calls a write tool and receives success for a unique value.
|
||||
2. Fresh DSH session B, under the same provider storage scope, calls search or recall and returns that value without session A's transcript.
|
||||
3. Session B uses the recalled value in a subsequent answer.
|
||||
|
||||
"Fresh session" means a new DSH session in the same Host. No Host restart is required. The generic MCP client discovers asynchronously and has no automatic reconnect after a child or HTTP transport closes; validation waits for tools before the first turn and uses HMR or a Host restart only after a crash.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**One DSH plugin per provider.** Rejected because it repeats auth, configuration, lifecycle, and tool wrappers that MCP already standardizes and expands ownership for every added provider.
|
||||
|
||||
**A memory-provider preset registry.** Rejected because a registry would make third-party versions and recommendations look like a supported DSH product surface. Copyable overlays keep ownership and drift visible.
|
||||
|
||||
**Run `npx` or `go run` inside the MCP row.** Rejected after probes showed first-run npm downloads can exceed the MCP initialization timeout and an interrupted `npx` cache can become unusable. DSH starts a server process; it is not the provider package manager. Pinned installation commands are explicit prerequisites.
|
||||
|
||||
**Inject the common instruction from the generic MCP client.** Rejected because the bridge serves non-memory MCP servers too, and generic prompt mutation would reintroduce provider semantics into shared runtime code.
|
||||
|
||||
## Consequences
|
||||
|
||||
Selecting a file gives the model the provider's complete discovered MCP tool surface, with schema/token cost determined by that provider. Removing `--config` removes the memory server. Users accept each upstream license, data policy, cloud cost, and operational model directly.
|
||||
|
||||
The earlier vendor-specific change is superseded by this generic path. Future provider drift is handled by updating and revalidating a small example pin rather than adding runtime branches to DSH.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Agent Note: 第三方记忆 MCP 示例
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-31-third-party-memory-mcp-examples.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
直接集成某个提供方会使该提供方的 API、配置、健康状态行为和工具语义成为 DSH 的一部分。对于已经可以通过 MCP 表达的功能，这会让产品接口过于庞大，而且每接入一个记忆系统都需要重复同样的适配工作。用户需要的是一种精简、可检查的方式，在保留通用 MCP 边界的同时，选择启用一个外部记忆服务器。
|
||||
|
||||
验收标准不止于「套接字可以连接」：每份参考配置都必须支持 DSH 在会话 A 中实际写入，在新的 DSH 会话 B 中从提供方召回，并使用召回的值。与此同时，提供方下载、账户、模型、embedding、存储初始化和独立 HTTP 进程仍由上游负责。
|
||||
|
||||
## 决策
|
||||
|
||||
在 `examples/mcp-memory` 下交付三份默认关闭的 Cordis overlay 示例：Memorix、MCP Reference Memory 和 Engram。每个文件只插入一个 `@deepseek-ai/dsh-mcp-client` 配置项。交付组合不会引用这些文件；CLI（命令行界面）仅声明通用桥接器，使用户显式选择 overlay 时可以解析它。
|
||||
|
||||
这些第三方配置仅作为互操作参考；收录不代表 DeepSeek 的认可、推荐、合作关系或持续支持承诺。系统没有记忆预设注册表、提供方专属 DSH 插件、通用记忆服务、安装 UI、迁移层、健康检查器或重连控制器。其他记忆 MCP 服务器可以使用同一份文档中的 stdio 或 Streamable HTTP 配置项。
|
||||
|
||||
## 职责边界
|
||||
|
||||
| 事项 | DSH | 上游提供方或用户 |
|
||||
|---|---|---|
|
||||
| 解析选中的 overlay | 是 | 选择一个文件 |
|
||||
| 启动 stdio 命令，并在插件 dispose（资源释放）时将其停止 | 是 | 安装固定版本的可执行文件 |
|
||||
| 连接 Streamable HTTP 并发现工具 | 是 | 运行并监管 HTTP 服务 |
|
||||
| 以 `mcp__<serverName>__<rawName>` 注册工具 | 是 | 定义工具 schema 和行为 |
|
||||
| 账户、认证、模型、embedding、存储初始化 | 否 | 是 |
|
||||
| 提供方数据迁移、重试、崩溃恢复 | 否 | 是 |
|
||||
|
||||
通用 stdio 传输会清除环境中名称类似凭据的变量和 `DSH_*` 变量，同时继承其他环境变量。基线示例仅添加必需的覆盖项；可选的提供方密钥必须添加到 `config.env`，或配置在提供方自己的文件中。
|
||||
|
||||
## 版本固定、存储与身份
|
||||
|
||||
| 提供方 | 已测试契约 |
|
||||
|---|---|
|
||||
| Memorix | npm `1.3.0`，tag commit `500792cad3144142293bfbb20acb4841c9f7fcfa` |
|
||||
| MCP Reference Memory | npm `2026.7.4`，package commit `6dd0a683e198783e30feabf7abaf42f925bd18b1` |
|
||||
| Engram | tag `v1.20.0`，commit `ba9e46ced152c37a7cb9e576153c41995873e2fc` |
|
||||
|
||||
存储仍由提供方负责。Memorix 默认使用 `~/.memorix/data`，Engram 默认使用 `~/.engram`。Reference Memory 示例设置稳定的 `$HOME/.dsh-mcp-reference-memory.jsonl` 路径，而不是写入已安装的 npm 包（package）目录。每个提供方自己的环境变量都可以在 DSH 启动前覆盖这些位置。
|
||||
|
||||
项目身份仍由提供方负责：Memorix 和 Engram 使用 DSH 工作目录中的 Git 项目，其中 Engram 还可以选择接受 `ENGRAM_PROJECT`。
|
||||
|
||||
## 模型指导
|
||||
|
||||
示例不会修改 `@deepseek-ai/dsh-system-prompt`：配置 patch 会替换某个配置项的完整配置，可能抹除已有 persona。README 改为提供一条可选的附加指令：
|
||||
|
||||
> 用户要求记住时调用写入工具；涉及历史信息时，主动检索并使用相关记忆。
|
||||
|
||||
提供方的工具描述仍然是权威定义。
|
||||
|
||||
## 验证契约
|
||||
|
||||
远程 CI 不会访问第三方服务或消耗密钥。无密钥套件解析全部三份 overlay 文件，检查其通用桥接器和密钥边界，将上游端点替换为包自带的 MCP fixture（测试前置数据）服务器，通过真实 Cordis Loader 启动，并验证工具发现。
|
||||
|
||||
合并前，每个固定版本的提供方都必须分别提供以下人工证据：
|
||||
|
||||
1. DSH 会话 A 调用写入工具，为一个唯一值写入记忆，并收到成功结果。
|
||||
2. 新的 DSH 会话 B 在相同的提供方存储范围下调用搜索或召回，不借助会话 A 的 transcript（文本记录）便可返回该值。
|
||||
3. 会话 B 在后续回答中使用该召回值。
|
||||
|
||||
「新会话」是指同一个 Host 中新建的 DSH 会话，不需要重启 Host。通用 MCP 客户端以异步方式发现工具，子进程或 HTTP 传输关闭后不会自动重连；验证会在第一轮之前等待工具出现，并且只在崩溃后使用 HMR 或重启 Host。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**每个提供方使用一个 DSH 插件。** 不予采纳，因为这会重复 MCP 已经标准化的认证、配置、生命周期和工具包装层，并随着每增加一个提供方而扩大维护范围。
|
||||
|
||||
**记忆提供方预设注册表。** 不予采纳，因为注册表会让第三方版本和推荐看起来像受支持的 DSH 产品接口。可复制的 overlay 让所有权和版本偏移保持可见。
|
||||
|
||||
**在 MCP 配置项内运行 `npx` 或 `go run`。** 不予采纳，因为探测表明首次 npm 下载可能超过 MCP 初始化超时，而中断的 `npx` 缓存可能变得不可用。DSH 负责启动服务器进程，不是提供方的包管理器。固定版本的安装命令属于显式前置条件。
|
||||
|
||||
**由通用 MCP 客户端注入共用指令。** 不予采纳，因为该桥接器也服务于非记忆类 MCP 服务器，而且通用提示词变更会把提供方语义重新带入共享运行时代码。
|
||||
|
||||
## 后果
|
||||
|
||||
选择一个文件后，模型可以使用提供方发现到的完整 MCP 工具接口；工具 schema 和 token 成本由提供方决定。移除 `--config` 就会移除记忆服务器。用户直接接受各上游的许可证、数据政策、云服务费用和运维模式。
|
||||
|
||||
通用方案取代了早期针对特定提供方的改动。未来出现提供方版本偏移时，只需更新并重新验证一份小型示例的固定版本，不必向 DSH 添加运行时分支。
|
||||
Reference in New Issue
Block a user