dsh-mcp-panel 0.2.0

package/README.pt.md

@@ -0,0 +1,129 @@
+# dsh-mcp-panel
+
+**Painel de gerenciamento em tempo de execução, somente leitura, para o cliente MCP oficial do DeepSeek Harness: veja status, ferramentas, erros e contadores de reconexão de cada servidor MCP sem tocar na sua configuração.**
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![dsh-plugin](https://img.shields.io/badge/ecosystem-dsh--plugin-8b5cf6)](https://github.com/topics/dsh-plugin)
+[![deepseek-harness](https://img.shields.io/badge/runtime-deepseek--harness-4f46e5)](https://github.com/deepseek-ai/deepseek-harness)
+
+> 🔭 **Observabilidade em primeiro lugar.** [`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client) mantém seu estado de conexão privado — apenas logs. Este plugin mostra tudo o que *consegue* observar (configuração, registro de ferramentas, estado do Loader) e diz **"unknown"** para o que não consegue, em vez de adivinhar. Ele também propõe a costura mínima que tornaria o status real: veja a [proposta upstream](docs/upstream-proposal.md).
+
+## Compatibilidade
+
+- **Runtime**: DeepSeek Harness ≥ `0.1.0-rc.5` (as peerDependencies fixam a linha `0.1.0-rc.6`).
+- **Última verificação**: 2026-08-14 contra um checkout do código-fonte do deepseek-harness (pacotes do workspace em `0.1.0-rc.5`, mainline `7b9644f`) — `/mcp` headless de ponta a ponta mais um perfil web ao vivo; evidências em [docs/research-notes.zh.md](docs/research-notes.zh.md). Reverificado no mesmo dia contra mainline `47f9438` com o ramo da costura `mcp/status` (`feat/mcp-client-status-observability-seam`): uma linha real de `server-everything` mostra `status: connected (source: upstream-event)` através do plugin empacotado, além do fluxo de compatibilidade fiel ao lançador; registro em [docs/optimization-plan-v2.zh.md](docs/optimization-plan-v2.zh.md).
+
+## O que você ganha
+
+| Superfície | O que mostra |
+|---|---|
+| **Comando `/mcp`** | transporte, alvo, contagem de ferramentas, status de conexão, último erro, contador de reconexões — legível pelo modelo e reconstruível pelo log, bilíngue (`outputLanguage: en\|zh`) |
+| **Configurações → Plugins → aba MCP** | o mesmo snapshot somente leitura, com selos de status, listas expansíveis de ferramentas, erros sanitizados e resultados de sondas |
+| **Botão de sonda do painel** | sonda de conectividade em um clique para um servidor streamable-http a partir da aba; os resultados continuam somente do painel |
+| **Sondas passivas** | selos de alcançabilidade opcionais em segundo plano por servidor, separados do status de conexão |
+| **Atualização automática** | o host sugere um intervalo de atualização (`refreshIntervalMs`); a aba consulta e pausa enquanto oculta |
+| **`/mcp <server> disable\|enable`** | a linha exata de `cordis.patch.yml` a aplicar — uma *sugestão*, nunca uma escrita |
+| **Ferramenta `mcp_probe`** | sonda de conectividade de uso único para Streamable HTTP como tarefa em segundo plano; resultados são **somente do painel** |
+
+## Início rápido
+
+```sh
+dsh plugin --profile web add github:PerryLink/dsh-mcp-panel#v0.2.0
+```
+
+Reinicie (ou deixe a superfície web recarregar seu `cordis.patch.yml`) e execute:
+
+```text
+/mcp
+/mcp everything tools
+/mcp everything disable
+```
+
+```text
+MCP servers (1):
+- everything [mcp-everything] stdio node …/server-everything/dist/index.js
+  | 13 tools | enabled | status: unknown (source: derived) | reconnects: — | last error: —
+```
+
+Instalação manual: coloque `dsh-mcp-panel` no `node_modules` do perfil (ou no
+respaldo compartilhado `$DSH_HOME/profiles/node_modules`) e adicione a linha a `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: mcp-panel
+      name: dsh-mcp-panel
+      config:
+        probeEnabled: true
+        probeTimeoutMs: 10000
+```
+
+### Desinstalação
+
+1. Remova a linha `mcp-panel` de `cordis.patch.yml` (a superfície web a recarrega em quente; outras superfícies reiniciam).
+2. Apague o pacote do `node_modules` do perfil (ou do respaldo compartilhado `profiles/node_modules`).
+3. Confirme com `dsh web --dump-config` que nenhuma linha `mcp-panel` restou.
+
+## Honestidade por contrato
+
+- **Somente leitura.** Nenhum arquivo de configuração é gravado. `disable`/`enable` imprime uma sugestão que você aplica.
+- **Sem status falso.** Campos de conexão sem dados upstream mostram `unknown` / `—`, com `statusSource: derived`.
+- **Exibição sanitizada.** Credenciais em query strings, senhas userinfo, valores de cabeçalhos, tokens bearer e JWTs são removidos antes da renderização; os `headers` configurados nunca entram em nenhum snapshot.
+- **Resultados somente do painel.** Os detalhes das sondas ficam na aba de configurações, nunca no contexto do modelo; `/mcp` é a superfície legível pelo modelo e é totalmente reconstruível a partir do log da sessão.
+- **Sem mudanças no mcp-client.** Transporte, OAuth e protocolo permanecem intactos — a lacuna de observabilidade é coberta pela [proposta upstream](docs/upstream-proposal.md), que este plugin já consome (evento tipado `mcp/status` + serviço de consulta `mcpStatus`, detectados em tempo de execução).
+
+## Configuração
+
+| Campo | Padrão | Descrição |
+|---|---|---|
+| `probeEnabled` | `true` | Registra a ferramenta `mcp_probe` (requer `ctx.jobs` na composição) |
+| `probeTimeoutMs` | `10000` | Tempo limite por sonda |
+| `maxProbes` | `10` | Limite de registros de sonda exibidos no painel |
+| `refreshIntervalMs` | `0` | Intervalo de atualização sugerido para o painel em ms (`0` = somente sob demanda) |
+| `outputLanguage` | `en` | Idioma de saída do comando `/mcp` (`en` \| `zh` \| `es` \| `pt` \| `hi`) |
+| `passiveProbeEnabled` | `false` | Sondear periodicamente servidores streamable-http em segundo plano |
+| `passiveProbeIntervalMs` | `60000` | Intervalo da sonda passiva em milissegundos |
+
+## Permissões e dados
+
+- **Lê**: linhas do Loader, o registro de ferramentas (nomes `mcp__<server>__`) e, quando o upstream implementar, eventos `mcp/status`.
+- **Escreve**: nada. Nenhum arquivo de configuração é modificado.
+- **Rede**: apenas a sonda de uso único `mcp_probe` (e a sonda passiva opcional) envia uma requisição MCP `initialize` para os endpoints que você configurou; os cabeçalhos configurados são usados na requisição e nunca são exibidos nem registrados.
+- Sem telemetria, sem serviços externos, sem trabalho em segundo plano além dos temporizadores de sonda opcionais.
+
+## Solução de problemas
+
+- A linha não aparece? Rode `dsh web --dump-config` e confira se o insert `mcp-panel` foi aplicado com um id único.
+- O painel mostra `status: unknown (source: derived)` — esperado até a costura upstream aterrissar; veja [docs/upstream-proposal.md](docs/upstream-proposal.md).
+- O painel parece desatualizado? Defina `refreshIntervalMs` com um valor positivo (ex.: `5000`) na linha de configuração `mcp-panel` para consultar automaticamente.
+- O log de boot mostra um fiber `mcp-panel` FAILED — o pacote precisa resolver a partir do perfil (o `name: dsh-mcp-panel` simples resolve via o `node_modules` do perfil ou o respaldo compartilhado).
+- Rollback: remova a linha (ver Desinstalação).
+
+## Segurança
+
+Encontrou um problema de segurança? Abra uma issue no GitHub **sem** colar segredos, chaves ou tokens — redija tudo antes. Este plugin mantém as credenciais dos seus servidores MCP configurados apenas em memória para as requisições de sonda; elas nunca chegam a logs ou snapshots.
+
+## Como funciona
+
+- **Metade host** — um serviço Typert Remote `mcpPanel` monta o snapshot a partir de três fontes somente leitura: linhas do Loader (entradas `@deepseek-ai/dsh-mcp-client`), `ctx.tools.schemas()` agrupadas pelo namespace `mcp__<server>__`, e observações upstream `mcp/status`. O manifesto `./typert` escrito à mão registra `mcpPanel/status` no gateway; o `zod` é empacotado, então a metade host é autocontida.
+- **Metade navegador** — um bundle `dsh.client` (servido em `/plugins/dsh-mcp-panel/client.js`) monta o mesmo descritor via `ctx.remote.$mount` e registra uma entrada `settings.plugins.tab` somente leitura (`id: mcp`). O apresentador é uma função pura; os estilos têm escopo e usam tokens de tema.
+- **O comando `/mcp`** passa pelo registro de comandos padrão — cada linha cai nos eventos de sessão `command/run` + `command/done`.
+
+## Desenvolvimento
+
+```sh
+pnpm install
+pnpm run typecheck
+pnpm test          # 96 testes: extremos do sanitizador, agrupamento, tolerância de agregação, saída do comando (5 idiomas), controle de sondas, fiação do cliente, apresentador
+pnpm run build     # declarações tsc → lib/types; tsdown → lib/index.js + lib/typert.host.js + lib/client.js
+pnpm run verify:self-contained
+pnpm pack
+```
+
+Verificação contra um checkout real do harness:
+`node --import tsx/esm scripts/verify-headless.mjs` inicializa o perfil web completo em processo (porta efêmera) e imprime a saída exata de `/mcp`, `/mcp <server> tools` e `/mcp <server> disable`.
+
+## Licença
+
+[Apache License 2.0](LICENSE) © 2026 colaboradores do dsh-mcp-panel

package/README.zh.md

@@ -0,0 +1,129 @@
+# dsh-mcp-panel
+
+**DeepSeek Harness 官方 MCP 客户端的只读运行时管理面板——一眼看清每个 MCP 服务器的状态、工具、错误与重连计数，绝不改动你的配置。**
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![dsh-plugin](https://img.shields.io/badge/ecosystem-dsh--plugin-8b5cf6)](https://github.com/topics/dsh-plugin)
+[![deepseek-harness](https://img.shields.io/badge/runtime-deepseek--harness-4f46e5)](https://github.com/deepseek-ai/deepseek-harness)
+
+> 🔭 **可观测优先。** [`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client) 的连接状态是私有的——只有日志。本插件展示一切**能**观测到的事实（配置、工具注册表、Loader 状态），对观测不到的字段如实显示 **"unknown"**，绝不猜测；同时给出让状态可观测的最小上游 seam 提案（见 [upstream proposal](docs/upstream-proposal.md)）。
+
+## 兼容性
+
+- **运行时**：DeepSeek Harness ≥ `0.1.0-rc.5`（peerDependencies 固定 `0.1.0-rc.6` 包线）。
+- **最后验证**：2026-08-14，针对 deepseek-harness 源码 checkout（workspace 包 `0.1.0-rc.5`，mainline `7b9644f`）——headless `/mcp` 端到端 + 实时 web profile；证据见 [docs/research-notes.zh.md](docs/research-notes.zh.md)。同日对 mainline `47f9438` + `mcp/status` seam 分支（`feat/mcp-client-status-observability-seam`）复验：真实 `server-everything` 行经打包插件渲染 `status: connected (source: upstream-event)`，并跑通与启动器一致的全流程；记录见 [docs/optimization-plan-v2.zh.md](docs/optimization-plan-v2.zh.md)。
+
+## 你能得到什么
+
+| 界面 | 展示内容 |
+|---|---|
+| **`/mcp` 命令** | transport、目标、工具数、连接状态、最近错误、重连计数——模型可读、可日志重建，支持双语（`outputLanguage: en\|zh`） |
+| **设置 → 插件 → MCP 页签** | 同一快照的只读视图：状态徽标、可展开工具清单、脱敏错误、探测结果 |
+| **面板探测按钮** | 从页签对单个 streamable-http 服务器一键发起连通性探测；结果仍仅面板可见 |
+| **被动探测** | 可选的每服务器后台可达性徽标，与连接状态严格分离展示 |
+| **自动刷新** | 宿主建议刷新间隔（`refreshIntervalMs`）；页签轮询并在后台隐藏时暂停 |
+| **`/mcp <server> disable\|enable`** | 应应用的 `cordis.patch.yml` 确切行——只是**建议**，绝不写文件 |
+| **`mcp_probe` 工具** | 对 Streamable HTTP 端点的一次性连通性探测（后台 job），结果**仅面板可见** |
+
+## 快速上手
+
+```sh
+dsh plugin --profile web add github:PerryLink/dsh-mcp-panel#v0.2.0
+```
+
+重启（或让 web 面板热重载 `cordis.patch.yml`），然后：
+
+```text
+/mcp
+/mcp everything tools
+/mcp everything disable
+```
+
+```text
+MCP servers (1):
+- everything [mcp-everything] stdio node …/server-everything/dist/index.js
+  | 13 tools | enabled | status: unknown (source: derived) | reconnects: — | last error: —
+```
+
+手动安装：把 `dsh-mcp-panel` 放进 profile 的 `node_modules`（或共享的
+`$DSH_HOME/profiles/node_modules` 回退目录），并在 `cordis.patch.yml` 添加：
+
+```yaml
+- insert:
+    - id: mcp-panel
+      name: dsh-mcp-panel
+      config:
+        probeEnabled: true
+        probeTimeoutMs: 10000
+```
+
+### 卸载
+
+1. 从 `cordis.patch.yml` 移除 `mcp-panel` 行（web 面板会热重载；其他面板重启）。
+2. 从 profile 的 `node_modules`（或共享的 `profiles/node_modules` 回退目录）删除该包。
+3. 用 `dsh web --dump-config` 确认没有残留的 `mcp-panel` 行。
+
+## 诚实契约
+
+- **只读。** 绝不写任何配置文件；`disable`/`enable` 只是打印建议，由你自行应用。
+- **不伪造状态。** 无上游数据的连接字段显示 `unknown` / `—`，并标注 `statusSource: derived`。
+- **展示脱敏。** URL 查询串凭据、userinfo 密码、header 值、Bearer token、JWT 在渲染前全部清洗；配置中的 `headers` 从不进入任何快照。
+- **panel-only 结果。** 探测细节只进设置页签，不进模型上下文；`/mcp` 输出是模型可读面，且完全可从会话日志重建。
+- **零 mcp-client 改动。** 传输 / OAuth / 协议不动——可观测缺口由[上游提案](docs/upstream-proposal.md)覆盖，本插件已实现其消费侧（类型化的 `mcp/status` 事件 + `mcpStatus` 查询服务，运行时特性探测）。
+
+## 配置
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `probeEnabled` | `true` | 是否注册 `mcp_probe` 工具（需要组合里有 `ctx.jobs`） |
+| `probeTimeoutMs` | `10000` | 单次探测超时 |
+| `maxProbes` | `10` | 面板展示的探测记录上限 |
+| `refreshIntervalMs` | `0` | 建议的面板刷新间隔（毫秒；`0` = 仅手动刷新） |
+| `outputLanguage` | `en` | `/mcp` 命令输出语言（`en` \| `zh` \| `es` \| `pt` \| `hi`） |
+| `passiveProbeEnabled` | `false` | 是否周期性后台探测 streamable-http 服务器 |
+| `passiveProbeIntervalMs` | `60000` | 被动探测间隔（毫秒） |
+
+## 权限与数据
+
+- **读取**：Loader 条目、工具注册表（`mcp__<server>__` 名字）以及上游落地后的 `mcp/status` 事件。
+- **写入**：无。绝不修改任何配置文件。
+- **网络**：仅一次性 `mcp_probe`（及可选被动探测）向你**已配置**的端点 POST 一次 MCP `initialize` 请求；已配置 headers 仅用于该请求，从不展示或记录。
+- 无遥测、无外部服务，除可选探测定时器外无后台任务。
+
+## 故障排查
+
+- 行不见了？运行 `dsh web --dump-config`，检查 `mcp-panel` insert 是否生效且 id 唯一。
+- 面板显示 `status: unknown (source: derived)`——在上游 seam 落地前属预期；见 [docs/upstream-proposal.md](docs/upstream-proposal.md)。
+- 面板数据不更新？把 `mcp-panel` 配置行的 `refreshIntervalMs` 设为正值（如 `5000`）自动轮询。
+- 启动日志出现 FAILED 的 `mcp-panel` fiber——确认包能从 profile 解析（裸 `name: dsh-mcp-panel` 经 profile 的 `node_modules` 或共享回退目录解析）。
+- 回滚：移除该行（见「卸载」）。
+
+## 安全
+
+发现安全问题？请在 GitHub 提 issue，但**不要**粘贴密钥、key 或 token——先脱敏。本插件仅在内存中持有你所配置 MCP 服务器的凭据用于探测请求；它们从不进入日志或快照。
+
+## 工作原理
+
+- **Host 半部**——`mcpPanel` Typert Remote 服务从三个只读来源组装快照：Loader 行（`@deepseek-ai/dsh-mcp-client` 条目）、按 `mcp__<server>__` 名字空间分组的 `ctx.tools.schemas()`、以及上游 `mcp/status` 观测。手写的 `./typert` 清单把 `mcpPanel/status` 注册进网关；`zod` 被打包进产物，host bundle 自包含。
+- **浏览器半部**——`dsh.client` bundle（由 `/plugins/dsh-mcp-panel/client.js` 提供）通过 `ctx.remote.$mount` 挂载同一描述符，并注册只读的 `settings.plugins.tab` 条目（`id: mcp`）。presenter 是纯函数；样式带作用域且使用主题 token。
+- **`/mcp` 命令**走标准命令注册表——每一行都落入 `command/run` + `command/done` 会话事件。
+
+## 开发
+
+```sh
+pnpm install
+pnpm run typecheck
+pnpm test          # 96 个测试：脱敏极端用例、分组、聚合容错、命令输出（五语言）、探测门控、客户端接线、presenter
+pnpm run build     # tsc 声明 → lib/types；tsdown → lib/index.js + lib/typert.host.js + lib/client.js
+pnpm run verify:self-contained
+pnpm pack
+```
+
+对真实 harness checkout 的验证：
+`node --import tsx/esm scripts/verify-headless.mjs` 在进程内启动完整 web profile（临时端口），打印真实的 `/mcp`、`/mcp <server> tools`、`/mcp <server> disable` 输出。
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 dsh-mcp-panel contributors

package/cordis.patch.yml

@@ -0,0 +1,23 @@
+# dsh-mcp-panel bundle patch: mount the read-only MCP management panel. `name`
+# is the package name, resolved through the profile's node_modules. An
+# id-targeted override replaces the whole config row — restate every key when
+# overriding. The panel never edits any config file itself.
+- insert:
+    - id: mcp-panel
+      name: dsh-mcp-panel
+      config:
+        # One-shot Streamable HTTP connectivity probe tool (background job;
+        # results are panel-only). Set false to omit the mcp_probe tool.
+        probeEnabled: true
+        # Per-probe timeout in milliseconds.
+        probeTimeoutMs: 10000
+        # Cap on probe records shown in the panel (default 10).
+        # maxProbes: 10
+        # Suggested panel refresh interval in ms; 0 = on demand only.
+        # refreshIntervalMs: 0
+        # Output language of the /mcp command (en | zh | es | pt | hi).
+        # outputLanguage: en
+        # Periodically probe streamable-http servers in the background.
+        # passiveProbeEnabled: false
+        # Passive probe interval in milliseconds.
+        # passiveProbeIntervalMs: 60000