@zoraxylia/dsh-codex-adapter 0.0.0-stage → 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/.claude-plugin/marketplace.json +15 -0
- package/.claude-plugin/plugin.json +8 -0
- package/.mcp.json +8 -0
- package/LICENSE +21 -0
- package/README.de.md +480 -0
- package/README.es.md +480 -0
- package/README.fr.md +480 -0
- package/README.hi.md +480 -0
- package/README.id.md +480 -0
- package/README.ja.md +478 -0
- package/README.ko.md +480 -0
- package/README.md +483 -2
- package/README.pt.md +480 -0
- package/README.ru.md +480 -0
- package/README.th.md +480 -0
- package/README.tr.md +480 -0
- package/README.vi.md +480 -0
- package/README.zh-TW.md +478 -0
- package/README.zh.md +482 -0
- package/agents/ds-flash.md +17 -0
- package/agents/ds-pro.md +17 -0
- package/agy/agents/ds-flash.md +18 -0
- package/agy/agents/ds-pro.md +18 -0
- package/agy/skills/dsh-config/SKILL.md +6 -0
- package/agy/skills/dsh-playbook/SKILL.md +65 -0
- package/agy/skills/dsh-status/SKILL.md +6 -0
- package/codex/agents/ds-flash.toml +23 -0
- package/codex/agents/ds-pro.toml +23 -0
- package/codex/prompts/dsh-config.md +3 -0
- package/codex/prompts/dsh-playbook.md +60 -0
- package/codex/prompts/dsh-status.md +1 -0
- package/commands/config.md +9 -0
- package/commands/off.md +5 -0
- package/commands/on.md +5 -0
- package/commands/playbook.md +64 -0
- package/commands/status.md +5 -0
- package/cordis.patch.yml +4 -0
- package/docs/images/dsh-crew-host.png +0 -0
- package/docs/images/dsh-crew-jobs.png +0 -0
- package/docs/images/dsh-crew-logo.png +0 -0
- package/docs/images/dsh-crew-overview.png +0 -0
- package/grok/agents/ds-flash.md +19 -0
- package/grok/agents/ds-pro.md +19 -0
- package/grok/commands/dsh-config.md +9 -0
- package/grok/commands/dsh-playbook.md +66 -0
- package/grok/commands/dsh-status.md +5 -0
- package/lib/client.js +2684 -0
- package/lib/server.mjs +15417 -0
- package/package.json +137 -4
- package/scripts/build-client.mjs +23 -0
- package/scripts/build-mcp.mjs +43 -0
- package/scripts/fake-agy.sh +23 -0
- package/scripts/release-local.mjs +87 -0
- package/scripts/smoke-bundle.mjs +166 -0
- package/scripts/smoke-cwd.mjs +41 -0
- package/scripts/smoke-pack.mjs +285 -0
- package/scripts/smoke.mjs +79 -0
- package/scripts/verify-cli-workers.mjs +133 -0
- package/scripts/verify-wpc10-client.mjs +237 -0
- package/scripts/verify-wpc14-proc-endpoints.mjs +356 -0
- package/scripts/verify-wpc9-guardrails.mjs +432 -0
- package/src/cli-workers.mjs +396 -0
- package/src/client/index.tsx +1133 -0
- package/src/client/jobs-view.ts +374 -0
- package/src/cwd-lock.mjs +91 -0
- package/src/hub/index.mjs +643 -0
- package/src/hub-client.mjs +72 -0
- package/src/i18n.mjs +19 -0
- package/src/install/cli.mjs +34 -0
- package/src/install/install.mjs +577 -0
- package/src/jobs.mjs +289 -0
- package/src/multimodal.mjs +744 -0
- package/src/origin-guard.mjs +133 -0
- package/src/paths.mjs +43 -0
- package/src/plugin-env.mjs +65 -0
- package/src/proc-kill.mjs +208 -0
- package/src/process-info.mjs +60 -0
- package/src/provider-probe.mjs +35 -0
- package/src/server.mjs +438 -0
- package/src/status-shard.mjs +95 -0
- package/src/tier-binding.mjs +63 -0
- package/src/vision-route.mjs +139 -0
- package/src/worker-profiles.mjs +95 -0
- package/src/worker-question.mjs +22 -0
- package/statusline/statusline.sh +14 -0
- package/statusline/worker-segment.sh +35 -0
- package/worker.cordis.yml +77 -0
package/README.pt.md
ADDED
|
@@ -0,0 +1,480 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="./docs/images/dsh-crew-logo.png" alt="DSH Crew" width="120" />
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<h1 align="center">DSH Crew</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<strong>Um plugin do <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a>: envie trabalho para agentes DSH a partir do Claude Code / Codex / Antigravity / Grok, sem abrir mão da UI nativa de subagent do host.</strong><br />
|
|
9
|
+
<sub>UI de progresso nativa • Política de Tier & Escalonamento • Proteções de Despacho • Quadro de Jobs • Sessões DSH no Host • Visão & Geração de Imagens (Native-First) • Instalação em Um Clique</sub>
|
|
10
|
+
</p>
|
|
11
|
+
|
|
12
|
+
<p align="center">
|
|
13
|
+
<sub>npm: <code>@zoraxylia/dsh-codex-adapter</code> · Versão atual do plugin: <code>0.1.0-rc.11</code> · Testado com DSH <code>0.1.1-rc.1</code></sub>
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<a href="./README.md">English</a> · <a href="./README.zh.md">简体中文</a> · <a href="./README.zh-TW.md">繁體中文</a> · <a href="./README.ja.md">日本語</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.fr.md">Français</a> · <a href="./README.es.md">Español</a> · <a href="./README.de.md">Deutsch</a> · <a href="./README.pt.md"><b>Português</b></a> · <a href="./README.ru.md">Русский</a> · <a href="./README.hi.md">हिन्दी</a> · <a href="./README.tr.md">Türkçe</a> · <a href="./README.th.md">ไทย</a> · <a href="./README.vi.md">Tiếng Việt</a> · <a href="./README.id.md">Bahasa Indonesia</a>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
<p align="center">
|
|
21
|
+
<a href="https://github.com/ZSeven-W/dsh-crew/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ZSeven-W/dsh-crew?color=64748b" alt="Licença" /></a>
|
|
22
|
+
</p>
|
|
23
|
+
|
|
24
|
+
<br />
|
|
25
|
+
|
|
26
|
+
<p align="center">
|
|
27
|
+
<img src="./docs/images/dsh-crew-overview.png" alt="DSH Crew — página de configurações" width="100%" />
|
|
28
|
+
</p>
|
|
29
|
+
<p align="center"><sub>A página de configurações do DSH Crew — integrações do host, política de despacho, execução e a ponte multimodal</sub></p>
|
|
30
|
+
|
|
31
|
+
## Por que DSH Crew
|
|
32
|
+
|
|
33
|
+
O DSH Crew é um plugin para [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) — um harness de agente open-source. Ele torna os agentes DSH despacháveis a partir do Claude Code, Codex, Antigravity e Grok: o orchestrator mantém seu próprio modelo, o trabalho é executado em um agente DSH real com as ferramentas, o sandbox, os presets e o histórico de sessão desse harness, e o host continua exibindo-o como um subagent nativo com progresso ao vivo.
|
|
34
|
+
|
|
35
|
+
O que executa o trabalho é um agente DSH, não uma chamada de modelo pura. Os tiers (`flash` / `pro`) selecionam quanta capacidade esse agente recebe do roster configurado do harness — DeepSeek V4 Flash e V4 Pro hoje — portanto, uma mudança de modelo no DSH não exige mudança aqui.
|
|
36
|
+
|
|
37
|
+
<table>
|
|
38
|
+
<tr>
|
|
39
|
+
<td width="50%">
|
|
40
|
+
|
|
41
|
+
### 🧵 UI de Progresso Nativa
|
|
42
|
+
|
|
43
|
+
Workers aparecem como subagents regulares no Claude Code / Codex / Antigravity / Grok — contagem de despachos, etapa em execução, chamadas de ferramenta e uso de tokens aparecem no painel de tarefas do próprio host, além de um segmento de statusline do claude-hud: `⚙dsh 1▶pro 2m14s 21.7k/606 ✓3`.
|
|
44
|
+
|
|
45
|
+
</td>
|
|
46
|
+
<td width="50%">
|
|
47
|
+
|
|
48
|
+
### 🎚️ Política de Tier e Escalonamento
|
|
49
|
+
|
|
50
|
+
`flash` para trabalho mecânico, `pro` para raciocínio, `effort` de `off` a `max`. O `tier_policy` pode fixar cada despacho em um único tier na camada de ferramenta, e o `escalate_on_failure` tenta novamente uma execução flash com falha uma vez no pro — com base em evidências, não em adivinhar a dificuldade antecipadamente.
|
|
51
|
+
|
|
52
|
+
</td>
|
|
53
|
+
</tr>
|
|
54
|
+
<tr>
|
|
55
|
+
<td width="50%">
|
|
56
|
+
|
|
57
|
+
### 🏛️ Sessões DSH no Host
|
|
58
|
+
|
|
59
|
+
Com o bundle instalado em um perfil DSH, cada worker é uma sessão DSH de primeira classe: visível na Web UI, agrupada por diretório de trabalho e montada com o preset de Agent que você escolhe por tier. Sem o DSH em execução, o despacho volta para um runtime DSH standalone, então ambientes CI e headless continuam funcionando.
|
|
60
|
+
|
|
61
|
+
</td>
|
|
62
|
+
<td width="50%">
|
|
63
|
+
|
|
64
|
+
### 👁️ Visão e Geração de Imagens
|
|
65
|
+
|
|
66
|
+
Os modelos do DSH são somente texto. `describe_image` agora prefere o modelo VL da própria DeepSeek (`deepseek-v4-flash-vision-exp`) sempre que uma key estiver disponível, e depois recorre às CLIs que você já tem — Claude, Codex, Grok, Antigravity — ou qualquer API compatível com OpenAI que você configurar. `generate_image` usa o pincel das mesmas CLIs. Imagens coladas permanecem visíveis na conversa e chegam ao modelo como texto.
|
|
67
|
+
|
|
68
|
+
</td>
|
|
69
|
+
</tr>
|
|
70
|
+
<tr>
|
|
71
|
+
<td width="50%">
|
|
72
|
+
|
|
73
|
+
### 🛡️ Proteções de Despacho
|
|
74
|
+
|
|
75
|
+
Todo despacho é verificado antes de qualquer coisa ser iniciada. O aninhamento worker→worker é limitado à profundidade 3 da cadeia de origem e ciclos são recusados; um segundo worker em um workspace que outro job já detém é recusado com as informações do detentor — nunca enfileirado silenciosamente. Recusas são erros legíveis: espere ou ajuste o escopo; não contorne.
|
|
76
|
+
|
|
77
|
+
</td>
|
|
78
|
+
<td width="50%">
|
|
79
|
+
|
|
80
|
+
### 📋 Quadro de Jobs
|
|
81
|
+
|
|
82
|
+
O painel do DSH Crew também funciona como um quadro de jobs: cada job de worker — em execução ou concluído — é listado com tier, effort, progresso ao vivo e tokens; workspaces ocupados mostram seus detentores; e um job que desaparece no meio da execução (por exemplo, um restart do hub) aparece como um fantasma órfão em vez de desaparecer silenciosamente.
|
|
83
|
+
|
|
84
|
+
</td>
|
|
85
|
+
</tr>
|
|
86
|
+
<tr>
|
|
87
|
+
<td width="50%">
|
|
88
|
+
|
|
89
|
+
### 🔌 Provedores Personalizados
|
|
90
|
+
|
|
91
|
+
Traga seu próprio endpoint (Base URL + API Key + modelos) ou um modelo de comando local. Cada provedor tem um teste de conectividade que verifica alcance e autenticação e depois faz uma chamada real de visão, para você descobrir agora, não no meio da tarefa.
|
|
92
|
+
|
|
93
|
+
</td>
|
|
94
|
+
<td width="50%">
|
|
95
|
+
|
|
96
|
+
### 📦 Instalação em Um Clique
|
|
97
|
+
|
|
98
|
+
A página de configurações instala e atualiza o plugin do Claude Code, os arquivos de role do Codex e os agents, skills e comandos do Antigravity / Grok para você — registro no marketplace, allowlist de permissões, integração com HUD, caminhos absolutos renderizados para esta máquina — e também os restaura facilmente. Todos os arquivos de configuração têm backup antes de qualquer alteração.
|
|
99
|
+
|
|
100
|
+
</td>
|
|
101
|
+
</tr>
|
|
102
|
+
</table>
|
|
103
|
+
|
|
104
|
+
## Como funciona
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
Claude Code / Codex / Antigravity / Grok (orchestrator, mantém o próprio modelo)
|
|
108
|
+
└─ ds-flash / ds-pro ← shell de subagent nativo (o progresso aparece na UI de tarefas do host)
|
|
109
|
+
└─ MCP: dsh_run_worker(tier, effort, cwd, worker=)
|
|
110
|
+
├─ worker="agy"/"grok" → essa CLI externa executa a tarefa (opt-in explícito)
|
|
111
|
+
├─ hub acessível → sessão dentro do DSH (visível na Web UI, agrupada por cwd)
|
|
112
|
+
└─ caso contrário → runtime dsh-jsonrpc-agent (worker.cordis.yml)
|
|
113
|
+
└─ DeepSeek V4 Flash / Pro (DSH SDK, event stream → progresso e estatísticas de tokens)
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Uma execução, duas visões
|
|
117
|
+
|
|
118
|
+
O despacho se espalha. Abaixo, dezoito workers traduzem este README em paralelo: o host os conta como seus próprios subagents, enquanto o harness os executa como sessões reais.
|
|
119
|
+
|
|
120
|
+
<p align="center">
|
|
121
|
+
<img src="./docs/images/dsh-crew-host.png" alt="Claude Code" width="100%" />
|
|
122
|
+
</p>
|
|
123
|
+
<p align="center"><sub>No Claude Code, os workers do dsh-crew são subagents nativos; o segmento da statusline acompanha os tiers em execução, o tempo decorrido e os tokens.</sub></p>
|
|
124
|
+
|
|
125
|
+
<p align="center">
|
|
126
|
+
<img src="./docs/images/dsh-crew-jobs.png" alt="DSH Crew" width="100%" />
|
|
127
|
+
</p>
|
|
128
|
+
<p align="center"><sub>O painel do DSH Crew mostra a mesma execução pelo lado do harness: qual host despachou cada job, seu tier e effort, o progresso ao vivo e o uso de tokens.</sub></p>
|
|
129
|
+
|
|
130
|
+
<p align="center"><sub>O painel também é o quadro de jobs: jobs em execução e concluídos permanecem listados com tier, progresso e tokens, workspaces ocupados nomeiam seus detentores, e um job que desaparece no meio da execução (um restart do hub) aparece como um fantasma órfão em vez de desaparecer silenciosamente.</sub></p>
|
|
131
|
+
|
|
132
|
+
## Instalação
|
|
133
|
+
|
|
134
|
+
Instalar do npm em um perfil do DSH:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
dsh plugin --profile web add @zoraxylia/dsh-codex-adapter@latest
|
|
138
|
+
dsh web
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Ou, para desenvolvimento local a partir do código-fonte:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
dsh plugin --profile web add link:/path/to/dsh-crew
|
|
145
|
+
dsh web
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
O protocolo `link:` cria um symlink da dependência do perfil para este repositório, então cada rebuild aparece imediatamente.
|
|
149
|
+
|
|
150
|
+
### Configurar credenciais do DeepSeek (apenas standalone)
|
|
151
|
+
|
|
152
|
+
No modo hub — a instalação anterior — os workers são executados dentro da instância DSH e usam as credenciais do DeepSeek já configuradas. Nada mais para configurar.
|
|
153
|
+
|
|
154
|
+
Apenas o fallback standalone precisa de sua própria key: despachar de um host sem uma instância DSH em execução inicia um worker runtime como um processo separado. Obtenha uma API key em [platform.deepseek.com](https://platform.deepseek.com) e escreva em `~/.config/dsh-crew/.env`:
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
DEEPSEEK_API_KEY=sk-...
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### Verificar
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
node scripts/smoke.mjs
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
O smoke test despacha uma tarefa econômica por qualquer caminho disponível — o hub se uma instância DSH está em execução, caso contrário standalone — e imprime qual foi utilizado. Em cerca de dez segundos você deve ver `smoke test passed — configuration OK`. Em caso de falha o motivo é impresso, limitado ao caminho que foi testado.
|
|
167
|
+
|
|
168
|
+
Depois abra Configurações → DSH Crew e instale as integrações do host — Claude Code, Codex, Antigravity, Grok — com um clique, ou acione o mesmo instalador pela linha de comando:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
node src/install/cli.mjs claude # plugin do Claude Code: marketplace + permissões + segmento do HUD
|
|
172
|
+
node src/install/cli.mjs codex # agents + prompts do Codex
|
|
173
|
+
node src/install/cli.mjs agy # config MCP do Antigravity + agents + skills
|
|
174
|
+
node src/install/cli.mjs grok # config MCP do Grok + agents + comandos
|
|
175
|
+
node src/install/cli.mjs all # os quatro hosts de uma vez
|
|
176
|
+
# desinstale simetricamente (uninstall-claude | uninstall-codex | uninstall-agy | uninstall-grok):
|
|
177
|
+
node src/install/cli.mjs uninstall-claude
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## Contexto e terminologia
|
|
181
|
+
|
|
182
|
+
- **DSH** (DeepSeek Harness): o harness de agente open-source da DeepSeek, um agente de código na forma de Web UI, semelhante ao Claude Code, mas que utiliza modelos DeepSeek.
|
|
183
|
+
- **MCP** (Model Context Protocol): o protocolo de integração de ferramentas de IA da Anthropic, que permite que LLMs chamem ferramentas externas e fontes de dados com segurança.
|
|
184
|
+
- **Cordis bundle**: o formato de plugin do DSH; este projeto pode ser executado standalone como um serviço MCP ou instalado no DSH Web como modo hub.
|
|
185
|
+
- **tier**: tier de capacidade — qual slot do roster de modelos configurado do DSH um worker recebe. `flash` é rápido e barato (tarefas simples), `pro` raciocina com mais profundidade (problemas complexos). Hoje eles mapeiam para DeepSeek V4 Flash e V4 Pro; troque os modelos no DSH e nada muda aqui.
|
|
186
|
+
- **worker**: o agente DSH que executa o trabalho — uma sessão completa com suas próprias ferramentas, sandbox e preset, não uma chamada de modelo pura.
|
|
187
|
+
- **effort**: intensidade de raciocínio, `off` = sem raciocínio, `high` = alto investimento de raciocínio, `max` = investimento máximo de raciocínio.
|
|
188
|
+
|
|
189
|
+
## Claude Code
|
|
190
|
+
|
|
191
|
+
### Instalação
|
|
192
|
+
|
|
193
|
+
Instalação em um clique (escolha uma opção):
|
|
194
|
+
|
|
195
|
+
- **Página de configurações do DSH** (quando o modo hub está instalado): Configurações → DSH Crew → "Install to Claude Code"
|
|
196
|
+
- **Linha de comando**: `node src/install/cli.mjs all`
|
|
197
|
+
|
|
198
|
+
Ambas fazem a mesma coisa: registrar o marketplace local (diretório pai `dsh-plugins/` como raiz do marketplace) + `claude plugin install` + allowlist de permissões das ferramentas MCP + configuração do segmento de status do worker no claude-hud (backup automático do settings.json antes de alterações, idempotente). **Reinicie a sessão após a instalação para que as alterações entrem em vigor.**
|
|
199
|
+
|
|
200
|
+
### Uso
|
|
201
|
+
|
|
202
|
+
- Diretamente na conversa, diga "dispatch X to ds-flash" ou "dispatch X to ds-pro", e o subagent executa a tarefa
|
|
203
|
+
- A contagem de despachos e o progresso em tempo real aparecem na interface de tarefas do Claude Code
|
|
204
|
+
- **Segmento da linha de status do HUD**: `⚙dsh 1▶pro 2m14s 21.7k/606 ✓3` (tier atual / tempo decorrido / uso de tokens / contagem de conclusões)
|
|
205
|
+
- Para desenvolvimento local, `statusline/statusline.sh` ou `statusline/worker-segment.sh` podem ser integrados de forma independente
|
|
206
|
+
- **Tarefas de longa duração**: o CC tem limites de timeout em chamadas MCP (`MCP_TOOL_TIMEOUT` ajustável); tarefas longas podem fazer o orchestrator usar `dsh_spawn_worker` + polling com `dsh_worker_result(wait_seconds)`
|
|
207
|
+
- **Desenvolvimento e depuração locais**: `claude --plugin-dir /path/to/dsh-crew` para carregar temporariamente
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
### Comandos de sessão
|
|
211
|
+
|
|
212
|
+
Substituem os padrões globais apenas na sessão atual e são aplicados na camada de ferramentas, não por prompt:
|
|
213
|
+
|
|
214
|
+
| Comando | O que faz |
|
|
215
|
+
|---|---|
|
|
216
|
+
| `/dsh-crew:config` | Mostrar ou definir os padrões da sessão: `tier=flash\|pro`, `effort=off\|high\|max`, `mode=auto\|hub\|standalone`, `timeout=<segundos>`, `policy=auto\|flash-only\|pro-only`, `escalate=true\|false`, `origin_depth_limit=<1-32>`, `preset_flash/preset_pro=<preset id|default>`, `reset` |
|
|
217
|
+
|
|
218
|
+
| `/dsh-crew:on` · `/dsh-crew:off` | Ligar ou desligar o despacho nesta sessão (desligado é chave rígida: a ferramenta recusa) |
|
|
219
|
+
| `/dsh-crew:status` | Status ao vivo dos jobs de worker: tier, progresso, tokens, ferramenta atual |
|
|
220
|
+
| `/dsh-crew:playbook` | Boas práticas de despacho: escolher flash vs pro, briefs autocontidos, paralelismo, verificação de resultados, proteções |
|
|
221
|
+
|
|
222
|
+
## Codex
|
|
223
|
+
|
|
224
|
+
### Instalação
|
|
225
|
+
|
|
226
|
+
Recomenda-se usar o instalador (renderiza automaticamente os caminhos para esta máquina e copia os prompts `/dsh-config`, `/dsh-status` e `/dsh-playbook`):
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
node src/install/cli.mjs codex
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Ou copie manualmente (exige modificação manual dos caminhos após copiar):
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
cp codex/agents/*.toml ~/.codex/agents/ # global or project-level .codex/agents/
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Os arquivos de role já vêm pré-configurados com:
|
|
239
|
+
|
|
240
|
+
- Configuração de montagem do servidor MCP
|
|
241
|
+
- `default_tools_approval_mode = "approve"` (**obrigatório**, caso contrário as chamadas de ferramenta são canceladas automaticamente no modo exec)
|
|
242
|
+
- `tool_timeout_sec = 3600`
|
|
243
|
+
|
|
244
|
+
**Nota**: Ao copiar manualmente, os caminhos absolutos no campo `args` devem ser atualizados para corresponder ao local real da instalação; o instalador faz isso automaticamente.
|
|
245
|
+
|
|
246
|
+
### Uso
|
|
247
|
+
|
|
248
|
+
- No TUI interativo, selecione "spawn ds-pro to ..." para despachar tarefas; os painéis Active/Done mostram o progresso
|
|
249
|
+
- O modo `codex exec` também pode chamar diretamente `dsh_run_worker`
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
### Comandos de sessão
|
|
253
|
+
|
|
254
|
+
Três prompts são instalados para o Codex:
|
|
255
|
+
|
|
256
|
+
| Comando | O que faz |
|
|
257
|
+
|---|---|
|
|
258
|
+
| `/dsh-config` | Mostrar ou definir os padrões da sessão: `tier=flash\|pro`, `effort=off\|high\|max`, `mode=auto\|hub\|standalone`, `timeout=<segundos>`, `policy=auto\|flash-only\|pro-only`, `escalate=true\|false`, `origin_depth_limit=<1-32>`, `preset_flash/preset_pro=<preset id|default>`, `reset` |
|
|
259
|
+
|
|
260
|
+
| `/dsh-status` | Status ao vivo dos jobs de worker: tier, progresso, tokens, ferramenta atual |
|
|
261
|
+
| `/dsh-playbook` | Boas práticas de despacho: escolher flash vs pro, briefs autocontidos, paralelismo, verificação de resultados, proteções |
|
|
262
|
+
|
|
263
|
+
## Antigravity (agy)
|
|
264
|
+
|
|
265
|
+
### Instalação
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
node src/install/cli.mjs agy
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Registra o servidor MCP dsh-crew em `~/.gemini/config/mcp_config.json` e instala os agents `ds-flash` / `ds-pro`, além das skills `dsh-config`, `dsh-status` e `dsh-playbook`, em `~/.gemini/config/` (todos os arquivos têm backup antes). Reinicie a sessão após a instalação.
|
|
272
|
+
|
|
273
|
+
### Uso
|
|
274
|
+
|
|
275
|
+
- Escolha `ds-flash` ou `ds-pro` como o agente para despachar tarefas
|
|
276
|
+
- `dsh_worker_config` lê ou sobrescreve os padrões da sessão
|
|
277
|
+
|
|
278
|
+
### Skills de sessão
|
|
279
|
+
|
|
280
|
+
| Skill | O que faz |
|
|
281
|
+
|---|---|
|
|
282
|
+
| `/dsh-config` | Mostrar ou definir os padrões da sessão (tier / effort / mode / timeout / policy / escalation / reset) |
|
|
283
|
+
| `/dsh-status` | Status ao vivo dos jobs de worker: tier, progresso, tokens, ferramenta atual |
|
|
284
|
+
| `/dsh-playbook` | Boas práticas de despacho: escolher flash vs pro, briefs autocontidos, paralelismo, verificação de resultados, proteções |
|
|
285
|
+
|
|
286
|
+
### Ressalvas
|
|
287
|
+
|
|
288
|
+
- o agy executa workers com **aprovação total** (`--dangerously-skip-permissions` + accept-edits): o agy 1.1.16 não tem modo de permissão com escopo de workspace, então um worker headless precisa aprovar automaticamente as requisições de ferramentas.
|
|
289
|
+
|
|
290
|
+
Desinstalar: `node src/install/cli.mjs uninstall-agy`
|
|
291
|
+
|
|
292
|
+
## Grok
|
|
293
|
+
|
|
294
|
+
### Instalação
|
|
295
|
+
|
|
296
|
+
```bash
|
|
297
|
+
node src/install/cli.mjs grok
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
Escreve a seção `[mcp_servers.dsh-crew]` em `~/.grok/config.toml` e instala os agents `ds-flash` / `ds-pro`, além dos comandos `/dsh-config`, `/dsh-status` e `/dsh-playbook`, em `~/.grok/` (todos os arquivos têm backup antes).
|
|
301
|
+
|
|
302
|
+
### Uso
|
|
303
|
+
|
|
304
|
+
- Escolha `ds-flash` ou `ds-pro` como o agente para despachar tarefas
|
|
305
|
+
|
|
306
|
+
### Comandos de sessão
|
|
307
|
+
|
|
308
|
+
| Comando | O que faz |
|
|
309
|
+
|---|---|
|
|
310
|
+
| `/dsh-config` | Mostrar ou definir os padrões da sessão (tier / effort / mode / timeout / policy / escalation / reset) |
|
|
311
|
+
| `/dsh-status` | Status ao vivo dos jobs de worker: tier, progresso, tokens, ferramenta atual |
|
|
312
|
+
| `/dsh-playbook` | Boas práticas de despacho: escolher flash vs pro, briefs autocontidos, paralelismo, verificação de resultados, proteções |
|
|
313
|
+
|
|
314
|
+
### Ressalvas
|
|
315
|
+
|
|
316
|
+
- Por design de segurança, o grok não inicia servidores MCP no nível do repositório em diretórios de projeto não confiáveis (`grok mcp doctor` reporta "folder untrusted"); uma instalação global não é afetada — mude de diretório ou passe `--trust`.
|
|
317
|
+
- Workers do grok rodam com `bypassPermissions` (sempre aprovar, como a documentação do grok recomenda para automação headless); regras de deny e hooks ainda se aplicam.
|
|
318
|
+
|
|
319
|
+
Desinstalar: `node src/install/cli.mjs uninstall-grok`
|
|
320
|
+
|
|
321
|
+
## Ferramentas MCP
|
|
322
|
+
|
|
323
|
+
| Ferramenta | Descrição |
|
|
324
|
+
|---|---|
|
|
325
|
+
| `dsh_run_worker` | Despacho bloqueante de tarefa (`tier`: flash/pro, `effort`: off/high/max, `cwd`, `worker`), aguarda o resultado |
|
|
326
|
+
| `dsh_spawn_worker` | Despacho assíncrono, retorna o id do job (para fan-out paralelo); colete os resultados com `dsh_worker_result` |
|
|
327
|
+
| `dsh_worker_status` | Progresso em tempo real de todos os jobs (turn/step/ferramenta atual/token) + bloqueios consultivos de cwd |
|
|
328
|
+
| `dsh_worker_result` | Busca o resultado; pode especificar `wait_seconds` para aguardar |
|
|
329
|
+
| `dsh_worker_cancel` | Cancela o job especificado e encerra o processo do runtime |
|
|
330
|
+
| `dsh_worker_config` | Ler/definir os padrões da sessão (tier, effort, mode, timeout, policy, escalation) e listar `worker_profiles` |
|
|
331
|
+
|
|
332
|
+
O progresso também é espelhado em `~/.config/dsh-crew/status.d/` (um arquivo shard por escritor, que pode ser lido por statusline / monitoramento externo).
|
|
333
|
+
|
|
334
|
+
## Proteções de despacho
|
|
335
|
+
|
|
336
|
+
Todo despacho é verificado antes de qualquer coisa ser iniciada — recusas são erros legíveis, nunca filas silenciosas:
|
|
337
|
+
|
|
338
|
+
- **Cadeia de origem**: cada despacho acrescenta um salto à cadeia de origem worker→worker. Aninhamento mais profundo que o limite (`origin_depth_limit`, padrão 3) é recusado, assim como qualquer ciclo (o mesmo backend + cwd aparecendo duas vezes) — a proteção que impede a autoamplificação recursiva de workers.
|
|
339
|
+
- **Bloqueio consultivo de cwd**: um worker em execução por workspace. Um segundo despacho para um workspace ocupado é recusado com o id do job detentor, o backend e a hora de início — espere ele terminar, cancele-o com `dsh_worker_cancel` ou passe `allow_concurrent_cwd: true` (apenas tarefas de somente leitura).
|
|
340
|
+
|
|
341
|
+
## Playbook de despacho
|
|
342
|
+
|
|
343
|
+
Como despachar *bem* — flash vs pro, briefs autocontidos, paralelismo seguro, verificação de resultados e as proteções acima — vem empacotado como um playbook por host: `/dsh-crew:playbook` (skill do Claude Code), `/dsh-playbook` (prompt do Codex, skill do Antigravity, comando do Grok).
|
|
344
|
+
|
|
345
|
+
## Backends de CLI explícitos
|
|
346
|
+
|
|
347
|
+
`worker="agy"` / `worker="grok"` fixa um despacho naquela CLI externa (backend × modelo × effort) em vez da lógica de tier do DSH. É opt-in explícito — não há padrão, então defina-o somente quando o usuário pedir por aquela CLI. Ressalvas: o grok se recusa a iniciar servidores MCP locais ao repositório em pastas não confiáveis, e o agy executa workers com aprovação total (sem modo de permissão com escopo de workspace).
|
|
348
|
+
|
|
349
|
+
## Multimodal: visão e geração de imagens
|
|
350
|
+
|
|
351
|
+
**DeepSeek é um modelo somente texto** e não suporta entrada ou geração de imagens. Este plugin obtém essas capacidades externamente por meio de ferramentas MCP:
|
|
352
|
+
|
|
353
|
+
**Visão nativa primeiro**: quando o provedor de visão é uma CLI embutida (ou explicitamente `native`), o `describe_image` tenta primeiro o modelo VL da própria DeepSeek `deepseek-v4-flash-vision-exp` (chamada de API direta; key de `DEEPSEEK_API_KEY` ou `~/.config/dsh-crew/.env`). Qualquer falha degrada graciosamente para a cadeia de provedores de CLI abaixo, que é mantida como fallback. A geração de imagens não é afetada — o modelo nativo apenas olha para imagens.
|
|
354
|
+
|
|
355
|
+
| Ferramenta | Descrição |
|
|
356
|
+
|---|---|
|
|
357
|
+
| `describe_image` | Responde perguntas analisando imagens (capturas de tela, designs, gráficos etc.); resultados em cache por provedor + modelo + imagem + pergunta |
|
|
358
|
+
| `generate_image` | Gera imagem a partir de uma descrição em texto e salva no caminho absoluto especificado; a saída é um bitmap plano (requer OpenPencil para edição de camadas) |
|
|
359
|
+
|
|
360
|
+
**Colar imagens na sessão**: No DSH, mude o modelo para `DeepSeek (vision) ◉` para colar imagens diretamente. As imagens permanecem na sessão e são exibidas normalmente; o plugin acrescenta o texto transcrito após elas e remove as imagens antes do envio — você vê a imagem, o modelo lê o texto. A transcrição segue a mesma escada native-first: o modelo VL da DeepSeek quando há key disponível e, em seguida, o provedor de CLI que você configurou.
|
|
361
|
+
|
|
362
|
+
### Configuração
|
|
363
|
+
|
|
364
|
+
Na **página de configurações do DSH → DSH Crew → Multimodal** (ou edite diretamente `~/.config/dsh-crew/config.json`):
|
|
365
|
+
|
|
366
|
+
**Provedor de visão** (visualização de imagens):
|
|
367
|
+
|
|
368
|
+
- `native` / `deepseek-native` (o modelo VL da própria DeepSeek — tentado primeiro automaticamente para todo provedor embutido sempre que uma key estiver disponível)
|
|
369
|
+
- `claude-code` (padrão, usa haiku, barato)
|
|
370
|
+
- `codex` (usa GPT, pode especificar um modelo específico)
|
|
371
|
+
- `grok` (usa Grok)
|
|
372
|
+
- `agy` (Antigravity)
|
|
373
|
+
- `custom` (API compatível com OpenAI ou comando local)
|
|
374
|
+
- `off` (desativado)
|
|
375
|
+
|
|
376
|
+
**Provedor de geração de imagens** (geração de imagens):
|
|
377
|
+
|
|
378
|
+
- `codex` (`$imagegen`, gpt-image-2)
|
|
379
|
+
- `agy` (Nano Banana)
|
|
380
|
+
- `grok` (Imagine)
|
|
381
|
+
- `custom` (API compatível com OpenAI ou comando local)
|
|
382
|
+
- `off` (desativado)
|
|
383
|
+
|
|
384
|
+
### Provedor personalizado
|
|
385
|
+
|
|
386
|
+
Dois métodos de integração:
|
|
387
|
+
|
|
388
|
+
**API**: qualquer endpoint compatível com OpenAI
|
|
389
|
+
- Preencha Base URL, API Key e lista de modelos
|
|
390
|
+
- Visão usa `/chat/completions` com imagens base64 inline
|
|
391
|
+
- Geração de imagens usa `/images/generations`
|
|
392
|
+
- **É obrigatório especificar o "modelo de geração de imagens" para ter capacidade de geração**; caso contrário, o provedor só aparece na seleção de visão
|
|
393
|
+
|
|
394
|
+
**CLI**: modelo de comando local, com placeholders substituídos por referências seguras
|
|
395
|
+
- Visão: `{image} {question} {model}` → stdout como resposta
|
|
396
|
+
- Geração de imagens: `{prompt} {output} {size}` → o comando deve gravar o arquivo em `{output}`
|
|
397
|
+
- Preencha pelo menos um comando; o que for preenchido determina a capacidade
|
|
398
|
+
|
|
399
|
+
**Teste de conectividade**: cada provedor personalizado tem um botão de teste
|
|
400
|
+
- API: verifica alcance do endpoint, autenticação e envia uma requisição real de visão para confirmar
|
|
401
|
+
- CLI: verifica o arquivo executável e executa um comando real para confirmar
|
|
402
|
+
- Geração de imagens: valida apenas a configuração, sem gerar imagem de fato
|
|
403
|
+
|
|
404
|
+
**CLIs de assinatura emprestadas** (claude / codex / grok / agy) exigem que você esteja conectado localmente; o plugin não contorna as permissões delas por você.
|
|
405
|
+
|
|
406
|
+
## Modo hub
|
|
407
|
+
|
|
408
|
+
Este pacote também é um bundle DSH válido (`dsh.bundle` + `cordis.patch.yml`). Após instalar no perfil do DSH Web com `dsh plugin add dsh-crew`:
|
|
409
|
+
|
|
410
|
+
- **Sessões de worker se tornam cidadãs de primeira classe**: são executadas como sessões de primeira classe no host DSH (`agents.create` + waterfall de model/effort por sessão + preset padrão), aparecem na lista de sessões da Web UI e podem ser abertas a qualquer momento para ver a execução completa
|
|
411
|
+
- **Organize por diretório de trabalho**: gerencie sessões de worker por cwd na Web UI
|
|
412
|
+
- **Loopback API**:
|
|
413
|
+
- `POST/GET /_dsh/dsh-crew/jobs`: cria tarefas, lista, faz long-poll de resultados e cancela
|
|
414
|
+
- `GET /_dsh/dsh-crew/ping`: verificação de saúde (o shim MCP usa isso para detectar se o hub está em execução)
|
|
415
|
+
- `POST /_dsh/dsh-crew/install`: instalação em um clique das integrações do host — Claude Code / Codex / Antigravity / Grok (backend de `src/install/`)
|
|
416
|
+
- **Detecção automática**: o shim MCP dos hosts detecta automaticamente o hub (`DSHPLUGIN_CREW_HUB` env var, padrão `http://127.0.0.1:3080`)
|
|
417
|
+
- DSH Web em execução → os jobs entram no modo hub (`mode: "hub"`)
|
|
418
|
+
- Sem execução → volta para o runtime standalone
|
|
419
|
+
|
|
420
|
+
**Consulta de processos no Windows:** a identificação da origem e o encerramento verificado de um processo usam PowerShell/CIM. A API de processos órfãos recusa o encerramento de grupos com `unsupported-platform`, sem enviar sinais.
|
|
421
|
+
|
|
422
|
+
## Seleção de solução e limitações
|
|
423
|
+
|
|
424
|
+
### Assinantes regulares → abordagem de shell subagent (recomendada)
|
|
425
|
+
|
|
426
|
+
- **Estado atual**: o shell de subagent do Claude Code usa haiku como intermediário; cada despacho adiciona centenas a milhares de tokens
|
|
427
|
+
- **Trade-off**: use uma pequena quantidade de tokens Anthropic em troca da interface de tarefas nativa, exibição de progresso em tempo real e nenhuma configuração extra
|
|
428
|
+
- **Recomendação**: se você já assina o Claude Pro ou usa o Claude Code, use esta abordagem — conveniente e transparente
|
|
429
|
+
|
|
430
|
+
### Ambientes pay-as-you-go / CI → abordagem de router direto
|
|
431
|
+
|
|
432
|
+
- **Estado atual**: o frontmatter de subagent do Claude Code não suporta conexão direta com modelos de terceiros; o experimento de router deste repositório no scratchpad exige credenciais de API key para o Claude Code, mas o OAuth de assinatura é bloqueado upstream pela Anthropic com 403
|
|
433
|
+
- **Recomendação**:
|
|
434
|
+
- Se você usa credenciais de API key (não OAuth) e quer economizar tokens Anthropic, pode executar um router local para conexão direta com DeepSeek
|
|
435
|
+
- Ambientes CI normalmente também usam API keys; esta abordagem é mais econômica (todos os tokens DeepSeek)
|
|
436
|
+
- Exige autoteste da integração do router (não é oficialmente suportado)
|
|
437
|
+
|
|
438
|
+
### DSH Web em execução → modo hub ativado automaticamente
|
|
439
|
+
|
|
440
|
+
- **Estado atual**: se `dsh plugin add dsh-crew` foi instalado no perfil do DSH Web, os jobs são executados como sessões de primeira classe no host e aparecem na lista de sessões da Web UI
|
|
441
|
+
- **Recomendação**: durante a iteração de desenvolvimento local, recomenda-se ativar o modo hub; o progresso dos workers pode ser totalmente observado na Web UI; para colaboração entre máquinas ou ambientes sem Web UI, use a abordagem de shell do host de despacho
|
|
442
|
+
|
|
443
|
+
### Itens conhecidos
|
|
444
|
+
|
|
445
|
+
- O role do Codex pode, teoricamente, tentar `model_provider` apontando diretamente para DeepSeek (não verificado); esta ponte não depende disso
|
|
446
|
+
- A saída da geração de imagens é um bitmap plano; a edição de camadas requer OpenPencil
|
|
447
|
+
- **Dependências de runtime**: apenas `@modelcontextprotocol/sdk` e `zod`; `@deepseek-ai/*` são runtime do host (fornecidas pelo host DSH; uma instalação npm comum nunca as baixa)
|
|
448
|
+
- **O Codex deve configurar**: `default_tools_approval_mode = "approve"`, caso contrário as chamadas de ferramenta são canceladas automaticamente
|
|
449
|
+
|
|
450
|
+
## Desenvolvimento
|
|
451
|
+
|
|
452
|
+
```bash
|
|
453
|
+
pnpm install
|
|
454
|
+
node_modules/.bin/tsdown src/client/index.tsx --format cjs --platform browser \
|
|
455
|
+
--target es2022 --tsconfig tsconfig.client.json --out-dir .client-build --clean
|
|
456
|
+
node scripts/build-client.mjs # wraps the bundle for the DSH module loader
|
|
457
|
+
node scripts/smoke.mjs # dispatches one real flash task end to end
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
As dependências de runtime são apenas `@modelcontextprotocol/sdk` e `zod`; todo pacote `@deepseek-ai/*` é runtime do host fornecido pelo host DSH (documentado no campo dshHostRuntime do pacote, não em peerDependencies, então uma instalação npm comum nunca os baixa), o que mantém o plugin dentro do realm de módulo único do host.
|
|
461
|
+
|
|
462
|
+
## Ecossistema
|
|
463
|
+
|
|
464
|
+
- [DSH Android](https://github.com/ZSeven-W/dsh-android) — um emulador Android ou dispositivo USB ao vivo dentro da conversa, tudo conduzido via adb
|
|
465
|
+
- [DSH iOS](https://github.com/ZSeven-W/dsh-ios) — um simulador de iOS — e um iPhone por USB — dentro da conversa
|
|
466
|
+
- [DSH Noema](https://github.com/ZSeven-W/dsh-noema) — memória de longo prazo para DSH
|
|
467
|
+
- [DSH OpenPencil](https://github.com/ZSeven-W/dsh-openpencil) — inspecione e edite documentos de design `.op` dentro de uma conversa
|
|
468
|
+
|
|
469
|
+
## Licença
|
|
470
|
+
|
|
471
|
+
MIT
|
|
472
|
+
|
|
473
|
+
|
|
474
|
+
### `dsh_worker_probe` / `needs_input`
|
|
475
|
+
|
|
476
|
+
`dsh_worker_probe` envia uma única chamada de ferramenta sem efeitos, com prazo limitado, a uma rota configurada no DSH, sem criar workers ou alterar vínculos. Pode consumir tokens. Perguntas sem resposta param o worker com `needs_input`; obtenha a resposta humana antes de reenviar. As permissões do host são herdadas, sem novo sandbox do SO.
|
|
477
|
+
|
|
478
|
+
```js
|
|
479
|
+
dsh_worker_probe({ tier: "flash" })
|
|
480
|
+
```
|