dsh-test-drive 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.pt.md ADDED
@@ -0,0 +1,229 @@
1
+ <div align="center">
2
+
3
+ # 🧪 dsh-test-drive
4
+
5
+ **Testes isolados de instalação e inicialização para plugins do DeepSeek Harness.**
6
+
7
+ *Instale, teste, verifique e limpe em um perfil descartável — seu `~/.dsh` real permanece intocado.*
8
+
9
+ [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
10
+ [![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
11
+ [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
12
+ [![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-test-drive/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-test-drive/actions)
13
+ [![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-test-drive?label=version)](https://github.com/PerryLink/dsh-test-drive/releases)
14
+ [![npm version](https://img.shields.io/npm/v/dsh-test-drive)](https://www.npmjs.com/package/dsh-test-drive)
15
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-test-drive)](https://www.npmjs.com/package/dsh-test-drive)
16
+
17
+ [English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
18
+
19
+ </div>
20
+
21
+ ---
22
+
23
+ ## Compatibility (Compatibilidade)
24
+
25
+ | Componente | Versão |
26
+ |---|---|
27
+ | DeepSeek Harness | `0.1.0-rc.6` (dependências peer fixadas) |
28
+ | Node.js | `^22.19.0 \|\| >=24.0.0` |
29
+ | Gerenciador de pacotes | `pnpm@11.7.0` |
30
+ | Plataforma | Windows / macOS / Linux (plugin apenas host) |
31
+ | Ferramentas externas | CLI `dsh` no PATH (autodetecção, shims npm analisados), `pnpm` no PATH |
32
+
33
+ ## What you get (O que você obtém)
34
+
35
+ - Ferramenta `test_drive` — um alvo pelo pipeline completo: `dsh plugin add` → verificação do patch com `--dump-config` → inicialização headless (varredura de marcadores FAILED + tarefa opcional de uma frase) → `dsh plugin remove` → limpeza em quarentena. Retorna o registro estruturado de forma síncrona, ou `{ kind: 'background', jobId }` com `background: true`.
36
+ - Comando `/testdrive` — lote de alvos separados por espaços/vírgulas como tarefa em segundo plano `drive-batch` sobre `ctx.jobs`, produzindo um relatório matricial (JSON + Markdown).
37
+ - Ferramenta `drive_report` — busca qualquer execução (`tdr_...`), matriz (`tdm_...`) ou a matriz mais recente; renderizada em Markdown.
38
+ - Resultados estruturados — cada registro carrega o discriminador `schema: "dsh-test-drive/v1"` com campos de primeira classe: `stages.install.status` (`pass`/`fail`), `stages.smoke.status` (`pass`/`fail`/`boot-ok`/`skipped`), `durationMs` por etapa, `summary`/`outputTail` saneados e um `verdict` geral (`pass`/`fail`/`partial`/`unknown`). Este é o contrato legível por máquina consumido pelos pontuadores (dsh-score).
39
+ - Segurança por construção — cada diretório temporário é criado por este plugin sob um prefixo dedicado `dsh-test-drive-`, registrado em um registro de propriedade ativo e removido apenas pela escada dry-run → renomear para quarentena → excluir. O perfil do host nunca é lido nem gravado.
40
+
41
+ ## Quick start (Início rápido)
42
+
43
+ ### Canal git
44
+
45
+ ```sh
46
+ dsh plugin --profile web add github:PerryLink/dsh-test-drive#<commit-sha>
47
+ ```
48
+
49
+ O primeiro `add` falha porque o pnpm bloqueia a compilação `prepare` do pacote; copie a chave exata que o pnpm imprimiu no `pnpm-workspace.yaml` do perfil e execute novamente:
50
+
51
+ ```yaml
52
+ allowBuilds:
53
+ 'dsh-test-drive': true
54
+ ```
55
+
56
+ ### Canal npm
57
+
58
+ ```sh
59
+ dsh plugin --profile web add dsh-test-drive
60
+ ```
61
+
62
+ Pacotes pré-compilados não precisam de permissão de compilação. Reinicie o perfil e use `test_drive` / `/testdrive` em uma sessão.
63
+
64
+ ## Install & uninstall (Instalação e desinstalação)
65
+
66
+ ```sh
67
+ dsh plugin --profile web add dsh-test-drive # instalar (npm) — ou a forma git acima
68
+ dsh plugin --profile web remove dsh-test-drive # desinstalar
69
+ ```
70
+
71
+ ## Configuration (Configuração)
72
+
73
+ Todas as chaves são opcionais (padrões exibidos); valores inválidos falham ruidosamente no carregamento.
74
+
75
+ | Chave | Padrão | Descrição |
76
+ |---|---|---|
77
+ | `profileName` | `headless` | Modelo de perfil inicializado dentro de cada DSH_HOME descartável (bundles base + headless). |
78
+ | `dshBin` | `""` | Caminho absoluto que substitui o executável dsh; vazio autodetecta `dsh` no PATH. |
79
+ | `headlessTask` | `"Reply with exactly: ok"` | Tarefa de uma frase para a etapa de inicialização; vazio pula a etapa. |
80
+ | `forwardEnv` | `[]` | NOMES de variáveis de ambiente (nunca valores) repassados aos processos filhos do perfil de teste. |
81
+ | `allowBuilds` | `true` | Permite uma compilação `prepare` de git bloqueada no perfil de teste e tenta a instalação mais uma vez. |
82
+ | `installTimeoutMs` | `600000` | Prazo da etapa `dsh plugin add`. |
83
+ | `configTimeoutMs` | `60000` | Prazo da etapa `--dump-config`. |
84
+ | `smokeTimeoutMs` | `300000` | Prazo da etapa de inicialização headless. |
85
+ | `uninstallTimeoutMs` | `120000` | Prazo da etapa `dsh plugin remove`. |
86
+ | `outputTailBytes` | `8000` | Limite da cauda de saída saneada registrada por etapa. |
87
+ | `keepTempDirs` | `false` | Mantém os diretórios temporários em caso de falha para análise forense (a propriedade é abandonada; você limpa). |
88
+ | `maxBatchTargets` | `20` | Limite de lote do `/testdrive`. |
89
+ | `batchConcurrency` | `1` | Concorrência do lote (serial evita contenção no armazenamento pnpm). |
90
+
91
+ ## Tools & surfaces (Ferramentas e superfícies)
92
+
93
+ ### `test_drive`
94
+
95
+ ```
96
+ test_drive(target: string, headlessTask?: string, background?: boolean)
97
+ ```
98
+
99
+ - `target` — especificação git (`github:owner/repo#sha`, `git+https://...`), nome npm, caminho local ou tarball `.tgz`.
100
+ - Retorna o registro estruturado completo; exemplo abaixo.
101
+ - `background: true` inicia uma tarefa `drive-batch` e retorna seu id.
102
+
103
+ ### `/testdrive <alvos...>`
104
+
105
+ Inicia uma tarefa de lote em segundo plano; o progresso flui pela saída da tarefa e a última linha nomeia o id da matriz para o `drive_report`.
106
+
107
+ ### `drive_report(id?)`
108
+
109
+ Retorna um registro de execução (`tdr_...`), uma matriz (`tdm_...`) ou — sem id — a matriz mais recente.
110
+
111
+ ### Exemplo de resultado estruturado
112
+
113
+ ```json
114
+ {
115
+ "schema": "dsh-test-drive/v1",
116
+ "run": { "runId": "tdr_9f2c...", "startedAt": "2026-08-16T00:00:00.000Z",
117
+ "finishedAt": "2026-08-16T00:00:45.120Z", "durationMs": 45120,
118
+ "harnessVersion": "0.1.0-rc.6", "pluginVersion": "0.1.0",
119
+ "platform": "win32", "node": "v22.22.3" },
120
+ "target": { "kind": "repo", "spec": "github:owner/dsh-click#abc123",
121
+ "resolved": { "packageName": "dsh-click", "packageVersion": "0.1.0",
122
+ "hasBundleManifest": true } },
123
+ "isolation": { "tempDshHome": true, "tempWorkspace": true, "tempStore": true,
124
+ "hostHomeTouched": false },
125
+ "stages": {
126
+ "install": { "status": "pass", "exitCode": 0, "durationMs": 30412, "attempts": 2,
127
+ "summary": "install ok after allowBuilds allowance", "outputTail": "",
128
+ "allowBuildsNeeded": true },
129
+ "config": { "status": "pass", "exitCode": 0, "durationMs": 2310, "attempts": 1,
130
+ "summary": "dump ok (exit 0)", "outputTail": "",
131
+ "patchEffective": true, "layers": ["dsh-click"] },
132
+ "smoke": { "status": "boot-ok", "exitCode": 1, "durationMs": 4123, "attempts": 1,
133
+ "summary": "booted without loader failures; headless task did not complete (credentials/model unreachable)",
134
+ "outputTail": "", "bootFailed": false, "taskCompleted": false },
135
+ "uninstall": { "status": "pass", "exitCode": 0, "durationMs": 5123, "attempts": 1,
136
+ "summary": "remove ok (exit 0)", "outputTail": "" },
137
+ "cleanup": { "status": "pass", "quarantined": true, "removed": true,
138
+ "summary": "owned temp root quarantined and removed" }
139
+ },
140
+ "verdict": "pass",
141
+ "verdictReason": "install, patch, boot, and uninstall verified; headless task inconclusive (see smoke.summary)"
142
+ }
143
+ ```
144
+
145
+ Regras de veredicto: falha de instalação ou de inicialização (`smoke.fail`) ⇒ `fail`; instalação aprovada + patch efetivo + inicialização limpa (`pass`/`boot-ok`) + desinstalação aprovada ⇒ `pass`; instalado mas sem alguma garantia posterior ⇒ `partial`; caso contrário ⇒ `unknown`.
146
+
147
+ ## Permissions & data (Permissões e dados)
148
+
149
+ - Apenas serviços públicos são consumidos: `ctx.subprocess`, `ctx.jobs`, `ctx.storageDomain`, `ctx.tools`, `ctx.commands`.
150
+ - Os relatórios são armazenados no domínio de armazenamento `test_drive` (tabelas `runs`, `matrices`; ponteiro de matriz mais recente). Quando a composição não tem `storageDomain` (ex.: o perfil headless oficial), as ferramentas continuam funcionando e a persistência é desativada com motivo registrado.
151
+ - Os processos filhos herdam um ambiente **sem credenciais**: segredos do host nunca chegam ao perfil testado, a menos que você os nomeie explicitamente em `forwardEnv`. Os valores nunca são registrados.
152
+ - Todas as strings de relatório/log passam por saneadores puros: literais de token, credenciais em URL e cabeçalhos bearer são redigidos, caminhos raiz temporários são substituídos por `<testdrive-temp>` e as caudas são limitadas por bytes.
153
+
154
+ ## Security boundaries (Limites de segurança)
155
+
156
+ - **Isolamento.** Cada teste roda dentro de uma raiz `mkdtemp` nova sob o diretório temporário do SO: um `DSH_HOME` descartável, um diretório de trabalho descartável e um armazenamento pnpm redirecionado. O código do plugin testado só roda nesse perfil; seu perfil do host permanece intacto.
157
+ - **Propriedade.** Um registro ativo guarda cada raiz criada por esta instância. A limpeza recusa qualquer caminho que não seja um filho direto registrado do diretório temporário do SO com o prefixo `dsh-test-drive-` — sem varreduras de `%TEMP%`, sem prefixos alheios, sem caminhos do diretório real.
158
+ - **Escada de limpeza.** Antes de qualquer mutação, o plano dry-run completo é registrado (caminhos absolutos). A exclusão primeiro renomeia a raiz para um diretório `dsh-test-drive-quarantine-<ts>`, verifica e então exclui; falhas deixam o diretório em quarentena e são reportadas, nunca descartadas em silêncio. A limpeza roda em um `finally` em sucesso, falha, timeout e aborto, e novamente no desmonte do plugin.
159
+ - **`allowBuilds` é uma permissão real.** Permitir a compilação `prepare` de um pacote git executa o código desse pacote no momento da instalação. A permissão fica restrita ao perfil descartável, mas teste apenas alvos confiáveis e fixe commits.
160
+ - **A inicialização headless é sem chave por padrão.** A verificação de inicialização não precisa de credenciais; concluir a tarefa precisa. Repasse credenciais explicitamente (`forwardEnv`) e nunca as registre.
161
+
162
+ ## Known limitations (Limitações conhecidas)
163
+
164
+ - Instalar alvos de registro/git requer acesso à rede a partir dos processos `dsh`/pnpm filhos.
165
+ - A tarefa de inicialização precisa de credenciais do modelo para chegar a `pass`; sem elas, reporta o honesto `boot-ok`.
166
+ - Em composições sem `storageDomain`, os relatórios não são persistidos (`drive_report` falha honestamente).
167
+ - `dsh` deve ser localizável no PATH (ou configure `dshBin`); no Windows o shim `.cmd`/`.bat` do npm é analisado automaticamente; uma resolução `.ps1` pede `dshBin`.
168
+ - Os lotes rodam em série por padrão; aumentar `batchConcurrency` só afeta a contenção de disco do armazenamento pnpm, não a corretude.
169
+
170
+ ## Development (Desenvolvimento)
171
+
172
+ ```sh
173
+ pnpm install
174
+ pnpm run typecheck && pnpm run typecheck:ci && pnpm test
175
+ pnpm run build && pnpm run verify:self-contained && pnpm run verify:artifacts && pnpm pack
176
+ ```
177
+
178
+ - `typecheck` resolve `@deepseek-ai/*` pelo checkout local do harness; `typecheck:ci` verifica contra os tipos publicados `0.1.0-rc.6`.
179
+ - Os testes usam a pilha real `Context`/`Session`/`ToolRuntime`/`LocalJobRegistry`/armazenamento com um provedor de subprocesso roteirizado.
180
+ - End-to-end com CLI real (requer rede + `dsh` no PATH): `DSH_TESTDRIVE_E2E=1 pnpm run test:e2e` — testa o checkout deste próprio pacote pelo loop real de instalação e inicialização.
181
+ - Lançamento: `node scripts/release.mjs <x.y.z>` (sobe versão, carimba o CHANGELOG, repete a porta, commit + tag; nunca faz push).
182
+
183
+ ## Topics
184
+
185
+ `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `plugin-testing`, `install-smoke`, `compatibility-matrix`, `ci`
186
+
187
+ ## Contributors (Contribuidores)
188
+
189
+ [PerryLink](https://github.com/PerryLink) — design e implementação.
190
+
191
+ ## PerryLink DSH Plugin Family
192
+
193
+ Este projeto é um dos [29 complementos do DeepSeek Harness](https://github.com/PerryLink) mantidos por [PerryLink](https://github.com/PerryLink). Se este ajuda você, os outros provavelmente também ajudarão:
194
+
195
+ | Plugin | One-liner |
196
+ |---|---|
197
+ | [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | Auto-revisão com segundo modelo na cadeia de aprovação, falha fechada por padrão |
198
+ | [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | Agentes filhos em segundo plano e duráveis com barra lateral Web, mensagens e interrupção |
199
+ | [dsh-budget](https://github.com/PerryLink/dsh-budget) | Governança de custos para DeepSeek Harness: orçamentos, carbono e latência em um painel. |
200
+ | [dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind) | Equivalente ao /rewind do Claude Code: instantâneos, bifurcações e restauração de uma vez |
201
+ | [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | Migra sessões, memória, skills e CLAUDE.md do Claude Code para o DSH |
202
+ | [dsh-click](https://github.com/PerryLink/dsh-click) | Controle de desktop nativo multiplataforma para DeepSeek Harness — Windows primeiro. |
203
+ | [dsh-composer-history](https://github.com/PerryLink/dsh-composer-history) | Histórico de entrada estilo terminal para o compositor web: setas, busca Ctrl+R |
204
+ | [dsh-defend](https://github.com/PerryLink/dsh-defend) | Defesa contra injeção de prompt, jailbreak e vazamento de segredos para DeepSeek Harness. |
205
+ | [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | Guarda de disciplina de engenharia: sabatina de requisitos, portões de teste, revisão adversária |
206
+ | [dsh-draw](https://github.com/PerryLink/dsh-draw) | Roteamento unificado de geração de imagens estáticas para DeepSeek Harness. |
207
+ | [dsh-fast](https://github.com/PerryLink/dsh-fast) | Diagnóstico de desempenho somente leitura para DeepSeek Harness. |
208
+ | [dsh-github](https://github.com/PerryLink/dsh-github) | Integração de PR/issues do GitHub para DSH, toda escrita com aprovação |
209
+ | [dsh-library](https://github.com/PerryLink/dsh-library) | Base de conhecimento documental local para DeepSeek Harness. |
210
+ | [dsh-local-ai](https://github.com/PerryLink/dsh-local-ai) | Integração de modelos locais (Ollama) para DeepSeek Harness. |
211
+ | [dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions) | Diagnóstico, formatação, completação, ações e renomeação LSP via servidores de linguagem |
212
+ | [dsh-mask](https://github.com/PerryLink/dsh-mask) | Middleware de mascaramento de PII para DeepSeek Harness — anonimiza antes do modelo e restaura na camada de exibição. |
213
+ | [dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel) | Painel MCP somente leitura: comando /mcp + aba de configurações com status, ferramentas e erros |
214
+ | [dsh-memento](https://github.com/PerryLink/dsh-memento) | Memória entre sessões com porta de aprovação: seam ctx.memory + SQLite + ferramenta memory |
215
+ | [dsh-observe](https://github.com/PerryLink/dsh-observe) | Exportador de observabilidade OpenTelemetry e Langfuse para DeepSeek Harness. |
216
+ | [dsh-output-styles](https://github.com/PerryLink/dsh-output-styles) | Troca de estilos em tempo de execução equivalente ao outputStyles do Claude Code |
217
+ | [dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules) | Regras declarativas allow/deny/ask estilo Claude Code com auditoria |
218
+ | [dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide) | Base de conhecimento de desenvolvimento de plugins como skill de agente sob demanda |
219
+ | [dsh-score](https://github.com/PerryLink/dsh-score) | Pontuação de qualidade multidimensional para plugins do DeepSeek Harness. |
220
+ | [dsh-session-pin](https://github.com/PerryLink/dsh-session-pin) | Fixa sessões na barra lateral Web com ordenação durável |
221
+ | [dsh-session-sync](https://github.com/PerryLink/dsh-session-sync) | Sincronização de sessões entre dispositivos para DeepSeek Harness — um espelho git dedicado do seu armazenamento de sessões. |
222
+ | [dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security) | Pacote de skills de auditoria de segurança: varredura de segredos, revisão de dependências e cadeia de suprimentos |
223
+ | [dsh-talk](https://github.com/PerryLink/dsh-talk) | Loop de sessão com voz para DeepSeek Harness: fale e ouça a resposta. |
224
+ | **[dsh-test-drive](https://github.com/PerryLink/dsh-test-drive)** | Testes isolados de instalação e inicialização para plugins do DeepSeek Harness. |
225
+ | [dsh-translate](https://github.com/PerryLink/dsh-translate) | Tradução de parâmetros entre fornecedores e reparo determinístico de JSON para DeepSeek Harness. |
226
+
227
+ ## License (Licença)
228
+
229
+ [Apache-2.0](LICENSE)
package/README.zh.md ADDED
@@ -0,0 +1,229 @@
1
+ <div align="center">
2
+
3
+ # 🧪 dsh-test-drive
4
+
5
+ **面向 DeepSeek Harness 插件的隔离式安装冒烟实测。**
6
+
7
+ *在一次性 profile 中完成安装、冒烟、验证与清理——绝不触碰你真实的 `~/.dsh`。*
8
+
9
+ [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
10
+ [![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
11
+ [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
12
+ [![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-test-drive/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-test-drive/actions)
13
+ [![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-test-drive?label=version)](https://github.com/PerryLink/dsh-test-drive/releases)
14
+ [![npm version](https://img.shields.io/npm/v/dsh-test-drive)](https://www.npmjs.com/package/dsh-test-drive)
15
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-test-drive)](https://www.npmjs.com/package/dsh-test-drive)
16
+
17
+ [English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
18
+
19
+ </div>
20
+
21
+ ---
22
+
23
+ ## Compatibility(兼容性)
24
+
25
+ | 组件 | 版本 |
26
+ |---|---|
27
+ | DeepSeek Harness | `0.1.0-rc.6`(peer 依赖钉版) |
28
+ | Node.js | `^22.19.0 \|\| >=24.0.0` |
29
+ | 包管理器 | `pnpm@11.7.0` |
30
+ | 平台 | Windows / macOS / Linux(纯 host 插件) |
31
+ | 外部工具 | PATH 上的 `dsh` CLI(自动探测,可解析 npm shim)、PATH 上的 `pnpm` |
32
+
33
+ ## What you get(你能得到什么)
34
+
35
+ - `test_drive` 工具 —— 单个目标跑完整流水线:`dsh plugin add` → `--dump-config` patch 校验 → headless 引导冒烟(FAILED 标记扫描 + 可选一句任务)→ `dsh plugin remove` → 隔离清理。同步返回结构化记录;传 `background: true` 则返回 `{ kind: 'background', jobId }`。
36
+ - `/testdrive` 命令 —— 把空格/逗号分隔的目标列表作为 `drive-batch` 后台任务(`ctx.jobs`)批量跑,产出矩阵报告(JSON + Markdown)。
37
+ - `drive_report` 工具 —— 按 id 取回任意单次记录(`tdr_...`)、矩阵(`tdm_...`)或最新矩阵;以 Markdown 渲染。
38
+ - 结构化结果 —— 每条记录带判别符 `schema: "dsh-test-drive/v1"`,关键字段均为一级字段:`stages.install.status`(`pass`/`fail`)、`stages.smoke.status`(`pass`/`fail`/`boot-ok`/`skipped`)、各阶段 `durationMs`、脱敏后的 `summary`/`outputTail` 以及总判定 `verdict`(`pass`/`fail`/`partial`/`unknown`)。这是下游评分方(dsh-score)消费的机器可读契约。
39
+ - 结构安全 —— 每个临时目录都由本插件以专属前缀 `dsh-test-drive-` 创建、登记在活跃所有权注册表中,且只经「dry-run → 隔离改名 → 删除」阶梯清理。宿主机 profile 永不被读取或写入。
40
+
41
+ ## Quick start(快速开始)
42
+
43
+ ### git 通道
44
+
45
+ ```sh
46
+ dsh plugin --profile web add github:PerryLink/dsh-test-drive#<commit-sha>
47
+ ```
48
+
49
+ 首次 `add` 会因 pnpm 拦截该包的 `prepare` 构建而失败;把 pnpm 打印的精确键复制进 profile 的 `pnpm-workspace.yaml` 后重跑:
50
+
51
+ ```yaml
52
+ allowBuilds:
53
+ 'dsh-test-drive': true
54
+ ```
55
+
56
+ ### npm 通道
57
+
58
+ ```sh
59
+ dsh plugin --profile web add dsh-test-drive
60
+ ```
61
+
62
+ 预构建包无需构建许可。重启 profile 后,即可在会话中使用 `test_drive` / `/testdrive`。
63
+
64
+ ## Install & uninstall(安装与卸载)
65
+
66
+ ```sh
67
+ dsh plugin --profile web add dsh-test-drive # 安装(npm)——或上面的 git 形式
68
+ dsh plugin --profile web remove dsh-test-drive # 卸载
69
+ ```
70
+
71
+ ## Configuration(配置)
72
+
73
+ 所有键均可选(下列为默认值);非法值在加载期响亮失败。
74
+
75
+ | 键 | 默认值 | 说明 |
76
+ |---|---|---|
77
+ | `profileName` | `headless` | 每次一次性 DSH_HOME 内初始化的 profile 模板(base + headless bundles)。 |
78
+ | `dshBin` | `""` | dsh 可执行文件的绝对路径覆盖;为空则自动探测 PATH 上的 `dsh`。 |
79
+ | `headlessTask` | `"Reply with exactly: ok"` | 引导冒烟阶段的一句任务;为空则跳过该阶段。 |
80
+ | `forwardEnv` | `[]` | 转发进测试 profile 子进程的环境变量**名**(绝不转发值)。 |
81
+ | `allowBuilds` | `true` | 在测试 profile 中放行被拦截的 git `prepare` 构建并重试一次安装。 |
82
+ | `installTimeoutMs` | `600000` | `dsh plugin add` 阶段时限。 |
83
+ | `configTimeoutMs` | `60000` | `--dump-config` 阶段时限。 |
84
+ | `smokeTimeoutMs` | `300000` | headless 引导冒烟阶段时限。 |
85
+ | `uninstallTimeoutMs` | `120000` | `dsh plugin remove` 阶段时限。 |
86
+ | `outputTailBytes` | `8000` | 每阶段记录的脱敏输出尾部上限(字节)。 |
87
+ | `keepTempDirs` | `false` | 失败时保留临时目录供取证(所有权被放弃,由你清理)。 |
88
+ | `maxBatchTargets` | `20` | `/testdrive` 批上限。 |
89
+ | `batchConcurrency` | `1` | 批并发度(串行可避免 pnpm-store 争用)。 |
90
+
91
+ ## Tools & surfaces(工具与界面)
92
+
93
+ ### `test_drive`
94
+
95
+ ```
96
+ test_drive(target: string, headlessTask?: string, background?: boolean)
97
+ ```
98
+
99
+ - `target` —— git 规格(`github:owner/repo#sha`、`git+https://...`)、npm 包名、本地路径或 `.tgz` 压缩包。
100
+ - 返回完整结构化记录,样例见下。
101
+ - `background: true` 启动一个 `drive-batch` 任务并返回其 id。
102
+
103
+ ### `/testdrive <目标...>`
104
+
105
+ 启动一个后台批任务;进度经任务输出流式推送,最后一行给出供 `drive_report` 使用的矩阵 id。
106
+
107
+ ### `drive_report(id?)`
108
+
109
+ 返回单次记录(`tdr_...`)、矩阵(`tdm_...`),或不传 id 时返回最新矩阵。
110
+
111
+ ### 结构化结果样例
112
+
113
+ ```json
114
+ {
115
+ "schema": "dsh-test-drive/v1",
116
+ "run": { "runId": "tdr_9f2c...", "startedAt": "2026-08-16T00:00:00.000Z",
117
+ "finishedAt": "2026-08-16T00:00:45.120Z", "durationMs": 45120,
118
+ "harnessVersion": "0.1.0-rc.6", "pluginVersion": "0.1.0",
119
+ "platform": "win32", "node": "v22.22.3" },
120
+ "target": { "kind": "repo", "spec": "github:owner/dsh-click#abc123",
121
+ "resolved": { "packageName": "dsh-click", "packageVersion": "0.1.0",
122
+ "hasBundleManifest": true } },
123
+ "isolation": { "tempDshHome": true, "tempWorkspace": true, "tempStore": true,
124
+ "hostHomeTouched": false },
125
+ "stages": {
126
+ "install": { "status": "pass", "exitCode": 0, "durationMs": 30412, "attempts": 2,
127
+ "summary": "install ok after allowBuilds allowance", "outputTail": "",
128
+ "allowBuildsNeeded": true },
129
+ "config": { "status": "pass", "exitCode": 0, "durationMs": 2310, "attempts": 1,
130
+ "summary": "dump ok (exit 0)", "outputTail": "",
131
+ "patchEffective": true, "layers": ["dsh-click"] },
132
+ "smoke": { "status": "boot-ok", "exitCode": 1, "durationMs": 4123, "attempts": 1,
133
+ "summary": "booted without loader failures; headless task did not complete (credentials/model unreachable)",
134
+ "outputTail": "", "bootFailed": false, "taskCompleted": false },
135
+ "uninstall": { "status": "pass", "exitCode": 0, "durationMs": 5123, "attempts": 1,
136
+ "summary": "remove ok (exit 0)", "outputTail": "" },
137
+ "cleanup": { "status": "pass", "quarantined": true, "removed": true,
138
+ "summary": "owned temp root quarantined and removed" }
139
+ },
140
+ "verdict": "pass",
141
+ "verdictReason": "install, patch, boot, and uninstall verified; headless task inconclusive (see smoke.summary)"
142
+ }
143
+ ```
144
+
145
+ 判定规则:安装失败或启动失败(`smoke.fail`)⇒ `fail`;安装通过 + patch 生效 + 启动干净(`pass`/`boot-ok`)+ 卸载通过 ⇒ `pass`;已安装但后续保证缺失 ⇒ `partial`;其余 ⇒ `unknown`。
146
+
147
+ ## Permissions & data(权限与数据)
148
+
149
+ - 只消费公开服务:`ctx.subprocess`、`ctx.jobs`、`ctx.storageDomain`、`ctx.tools`、`ctx.commands`。
150
+ - 报告存于 `test_drive` storage-domain(表 `runs`、`matrices`;latest-matrix 指针)。组合中没有 `storageDomain` 时(如官方 headless profile),工具照常工作,报告持久化被禁用并记录原因。
151
+ - 子进程继承的是**已剥离凭据**的环境:除非你在 `forwardEnv` 中显式点名,宿主机密钥永远不会进入被测 profile;值永不落日志。
152
+ - 所有报告/日志字符串都经纯函数脱敏:令牌字面量、URL 凭据与 bearer 头被涂红,临时根路径被替换为 `<testdrive-temp>`,输出尾部按字节封顶。
153
+
154
+ ## Security boundaries(安全边界)
155
+
156
+ - **隔离**:每次实测在 OS 临时目录下全新 `mkdtemp` 根内进行:一次性 `DSH_HOME`、一次性工作目录、重定向的 pnpm store。被测插件代码只在那个 profile 中运行;宿主机 profile 不受影响。
157
+ - **所有权**:活跃注册表记录本插件实例创建的每个根目录。清理会拒绝任何「非注册的、不在 OS 临时目录直接子级、不携带 `dsh-test-drive-` 前缀」的路径——不扫 `%TEMP%` 全量、不碰他人前缀、不碰真实家目录。
158
+ - **清理阶梯**:任何变更前先打印完整 dry-run 计划(绝对路径)。删除先把根目录改名为 `dsh-test-drive-quarantine-<时间戳>` 隔离目录,核验后再删;失败则目录保持隔离并如实上报,绝不静默丢弃。成功、失败、超时、中止的所有路径都在 `finally` 中执行清理,插件卸载时再次清扫。
159
+ - **`allowBuilds` 是真实权限**:放行 git 包的 `prepare` 构建意味着在安装时执行该包的代码。放行范围仅限一次性 profile,但仍只测你信任的目标,并固定 commit。
160
+ - **headless 冒烟默认无密钥**:启动检查不需要凭据;完成一句任务才需要。要转发凭据请显式配置 `forwardEnv`,且绝不记录其值。
161
+
162
+ ## Known limitations(已知限制)
163
+
164
+ - 安装 registry/git 目标需要子进程 `dsh`/pnpm 具备网络访问。
165
+ - 冒烟任务需要模型凭据才能到 `pass`;没有时如实上报 `boot-ok`。
166
+ - 没有 `storageDomain` 的组合不持久化报告(`drive_report` 会诚实报错)。
167
+ - `dsh` 必须能在 PATH 上定位(或配置 `dshBin`);Windows 下自动解析 npm 的 `.cmd`/`.bat` shim,若只解析到 `.ps1` 会要求配置 `dshBin`。
168
+ - 批默认串行执行;提高 `batchConcurrency` 只影响 pnpm-store 磁盘争用,不影响正确性。
169
+
170
+ ## Development(开发)
171
+
172
+ ```sh
173
+ pnpm install
174
+ pnpm run typecheck && pnpm run typecheck:ci && pnpm test
175
+ pnpm run build && pnpm run verify:self-contained && pnpm run verify:artifacts && pnpm pack
176
+ ```
177
+
178
+ - `typecheck` 经本地 harness checkout 解析 `@deepseek-ai/*`;`typecheck:ci` 对照已发布的 `0.1.0-rc.6` 类型检查。
179
+ - 测试使用真实 `Context`/`Session`/`ToolRuntime`/`LocalJobRegistry`/storage 栈 + 脚本化 subprocess provider。
180
+ - 真实 CLI 端到端(需网络 + PATH 上的 `dsh`):`DSH_TESTDRIVE_E2E=1 pnpm run test:e2e` —— 用真实安装冒烟循环实测本包自身 checkout。
181
+ - 发布:`node scripts/release.mjs <x.y.z>`(升版本、CHANGELOG 落日期、重跑门禁、commit + tag;不 push)。
182
+
183
+ ## Topics
184
+
185
+ `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `plugin-testing`, `install-smoke`, `compatibility-matrix`, `ci`
186
+
187
+ ## Contributors(贡献者)
188
+
189
+ [PerryLink](https://github.com/PerryLink) —— 设计与实现。
190
+
191
+ ## PerryLink DSH Plugin Family
192
+
193
+ 本项目是由 [PerryLink](https://github.com/PerryLink) 维护的 [29 个 DeepSeek Harness 插件](https://github.com/PerryLink)之一。如果这个对你有用,其他插件很可能也会:
194
+
195
+ | Plugin | One-liner |
196
+ |---|---|
197
+ | [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | 审批链上的第二模型自动审查,默认失败关闭 |
198
+ | [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | 持久化后台子代理,带 Web UI 侧边栏、消息与打断 |
199
+ | [dsh-budget](https://github.com/PerryLink/dsh-budget) | DeepSeek Harness 的成本治理:预算、碳排与延迟一屏呈现。 |
200
+ | [dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind) | Claude Code /rewind 等价物:快照、会话分叉、一次性恢复 |
201
+ | [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | 将 Claude Code 会话、记忆、技能与 CLAUDE.md 迁入 DSH |
202
+ | [dsh-click](https://github.com/PerryLink/dsh-click) | 跨平台原生桌面控制(DeepSeek Harness),Windows 优先。 |
203
+ | [dsh-composer-history](https://github.com/PerryLink/dsh-composer-history) | Web 输入框的终端式输入历史:方向键、Ctrl+R 搜索 |
204
+ | [dsh-defend](https://github.com/PerryLink/dsh-defend) | DeepSeek Harness 的提示注入、越狱与密钥泄露防护。 |
205
+ | [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | 工程纪律门禁:需求质询、测试门禁、对抗式审查 |
206
+ | [dsh-draw](https://github.com/PerryLink/dsh-draw) | DeepSeek Harness 的统一静态图像生成路由。 |
207
+ | [dsh-fast](https://github.com/PerryLink/dsh-fast) | DeepSeek Harness 的只读性能诊断。 |
208
+ | [dsh-github](https://github.com/PerryLink/dsh-github) | DSH 的 GitHub PR/issue 集成,每次写入都经审批门 |
209
+ | [dsh-library](https://github.com/PerryLink/dsh-library) | DeepSeek Harness 的本地文档知识库。 |
210
+ | [dsh-local-ai](https://github.com/PerryLink/dsh-local-ai) | DeepSeek Harness 的本地模型(Ollama)接入。 |
211
+ | [dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions) | 经语言服务器的 LSP 诊断、格式化、补全、代码操作与重命名 |
212
+ | [dsh-mask](https://github.com/PerryLink/dsh-mask) | DeepSeek Harness 的 PII 脱敏中间件——数据到模型前匿名化,展示层还原。 |
213
+ | [dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel) | 只读 MCP 运行时面板:/mcp 命令 + 带状态、工具与错误的设置页 |
214
+ | [dsh-memento](https://github.com/PerryLink/dsh-memento) | 带审批门的跨会话记忆:ctx.memory 接缝 + SQLite + memory 工具 |
215
+ | [dsh-observe](https://github.com/PerryLink/dsh-observe) | DeepSeek Harness 的 OpenTelemetry 与 Langfuse 可观测导出器。 |
216
+ | [dsh-output-styles](https://github.com/PerryLink/dsh-output-styles) | Claude Code outputStyles 等价的运行时样式切换 |
217
+ | [dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules) | Claude Code 风格声明式 allow/deny/ask 权限规则,带审计 |
218
+ | [dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide) | 按需 agent 技能形式的插件开发知识库 |
219
+ | [dsh-score](https://github.com/PerryLink/dsh-score) | DeepSeek Harness 插件的多指标质量评分。 |
220
+ | [dsh-session-pin](https://github.com/PerryLink/dsh-session-pin) | 在 Web 侧边栏置顶会话,顺序持久化 |
221
+ | [dsh-session-sync](https://github.com/PerryLink/dsh-session-sync) | DeepSeek Harness 的跨设备会话同步——会话存储的专用 git 镜像。 |
222
+ | [dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security) | 安全审计技能包:密钥扫描、依赖与供应链审查 |
223
+ | [dsh-talk](https://github.com/PerryLink/dsh-talk) | DeepSeek Harness 的语音优先会话闭环:对它说,听它答。 |
224
+ | **[dsh-test-drive](https://github.com/PerryLink/dsh-test-drive)** | DeepSeek Harness 插件的隔离式安装冒烟实测。 |
225
+ | [dsh-translate](https://github.com/PerryLink/dsh-translate) | DeepSeek Harness 的厂商参数翻译与确定性 JSON 修复。 |
226
+
227
+ ## License(许可证)
228
+
229
+ [Apache-2.0](LICENSE)
package/SECURITY.md ADDED
@@ -0,0 +1,55 @@
1
+ # Security Policy
2
+
3
+ ## Reporting a vulnerability
4
+
5
+ Please report vulnerabilities privately through the GitHub Security Advisory
6
+ interface: **Security → Report a vulnerability** on
7
+ [github.com/PerryLink/dsh-test-drive](https://github.com/PerryLink/dsh-test-drive/security/advisories/new).
8
+
9
+ **Sanitize before you paste.** Logs, transcripts, and reproductions must be
10
+ redacted first: remove tokens, API keys, passwords, authorization headers,
11
+ personal data, and full machine-local paths. Never include secrets in the
12
+ report body; describe them by kind and position instead.
13
+
14
+ ## What to expect
15
+
16
+ - First response (acknowledgment): typically within 7 days.
17
+ - The reporter receives credit in the advisory and release notes unless they
18
+ ask to stay anonymous.
19
+ - Fixes are released through the normal release flow with a
20
+ `SECURITY:`-tagged changelog entry and a GitHub Security Advisory.
21
+
22
+ ## Security model of this plugin
23
+
24
+ `dsh-test-drive` deliberately executes third-party plugin code (the tested
25
+ target) inside throwaway profiles. Its own boundaries are:
26
+
27
+ - **Isolation:** every drive runs in a fresh `mkdtemp` root under the OS temp
28
+ directory (throwaway `DSH_HOME`, working directory, and pnpm store). The
29
+ host profile is never read or written.
30
+ - **Ownership:** cleanup touches only directories this plugin instance created
31
+ and still tracks — direct children of the OS temp directory carrying the
32
+ `dsh-test-drive-` prefix. It never scans the temp directory or foreign
33
+ prefixes.
34
+ - **Cleanup ladder:** a dry-run plan is logged before any mutation; removal
35
+ goes rename-to-quarantine first, then delete; failures are reported, never
36
+ silently dropped.
37
+ - **Credential hygiene:** child processes inherit a credential-scrubbed
38
+ environment; the only way a secret reaches a tested profile is an explicit
39
+ `forwardEnv` name, and values are never logged.
40
+ - **`allowBuilds`:** allowing a git package's `prepare` build runs that
41
+ package's code at install time. The allowance is scoped to the throwaway
42
+ profile, but treat it as a real permission: only test targets you trust and
43
+ pin commits.
44
+
45
+ ## Out of scope
46
+
47
+ The tested plugin's own behavior is not a vulnerability of this package — the
48
+ point of the tool is to measure exactly that in isolation. Report issues in
49
+ this plugin's driver, isolation, cleanup, or reporting code.
50
+
51
+ ## Acknowledgments & disclosure
52
+
53
+ Fixes follow coordinated disclosure: the advisory goes out with the release
54
+ that contains the fix. Security researchers who follow this policy are
55
+ thanked in the advisory and the changelog.
@@ -0,0 +1,15 @@
1
+ # Third-Party Notices
2
+
3
+ `dsh-test-drive` is licensed under the [Apache License 2.0](LICENSE). The
4
+ runtime imports only `node:` builtins and `@deepseek-ai/*` peer packages; the
5
+ dependencies below are build/runtime tooling installed alongside the package.
6
+
7
+ | Package | Version range | License | Purpose |
8
+ |---|---|---|---|
9
+ | [typescript](https://github.com/microsoft/TypeScript) | `^5.9.0` | Apache-2.0 | Declarations and type checking in `scripts/prepare.mjs`. |
10
+ | [tsdown](https://github.com/rolldown/tsdown) | `^0.22.14` | MIT | ESM bundling of `src/` into `lib/` in `scripts/prepare.mjs`. |
11
+ | [zod](https://github.com/colinhacks/zod) | `^4.4.3` | MIT | Domain record schemas validated at the storage-domain durable boundary. |
12
+
13
+ Peer dependencies (`@deepseek-ai/cordis`, `@deepseek-ai/schemastery`, and the
14
+ pinned `@deepseek-ai/dsh-*` packages) are provided by the DeepSeek Harness
15
+ installation and carry their own notices.
@@ -0,0 +1,45 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ # dsh-test-drive bundle patch: mount the isolated install-smoke test-drive plugin.
3
+ #
4
+ # Every configuration key is listed below with its default, commented out —
5
+ # uncomment only the keys you override (defaults come from the Schemastery
6
+ # Config schema; see README § Configuration for the full table).
7
+ - insert:
8
+ - id: test-drive
9
+ name: dsh-test-drive
10
+ config:
11
+ # Profile template initialized inside each throwaway DSH_HOME.
12
+ # 'headless' = base + headless bundles (boot smoke + one-shot tasks).
13
+ # profileName: headless
14
+
15
+ # Absolute path to a dsh executable override; empty auto-detects the
16
+ # `dsh` on PATH (npm shims are parsed automatically).
17
+ # dshBin: ""
18
+
19
+ # Headless task text for the boot-smoke stage; empty skips the stage.
20
+ # headlessTask: "Reply with exactly: ok"
21
+
22
+ # Environment VARIABLE NAMES (never values) forwarded from the host
23
+ # into test-profile child processes, e.g. DEEPSEEK_API_KEY. Default []
24
+ # keeps host credentials out of every tested profile.
25
+ # forwardEnv: []
26
+
27
+ # Whether a blocked git `prepare` build is allowlisted in the test
28
+ # profile's pnpm-workspace.yaml and the install retried once.
29
+ # allowBuilds: true
30
+
31
+ # Per-stage timeouts in milliseconds.
32
+ # installTimeoutMs: 600000
33
+ # configTimeoutMs: 60000
34
+ # smokeTimeoutMs: 300000
35
+ # uninstallTimeoutMs: 120000
36
+
37
+ # Cap on the sanitized output tail recorded per stage, in bytes.
38
+ # outputTailBytes: 8000
39
+
40
+ # Keep temp dirs on failure instead of quarantining them (forensics).
41
+ # keepTempDirs: false
42
+
43
+ # Batch limits for /testdrive.
44
+ # maxBatchTargets: 20
45
+ # batchConcurrency: 1