@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.
Files changed (87) hide show
  1. package/.claude-plugin/marketplace.json +15 -0
  2. package/.claude-plugin/plugin.json +8 -0
  3. package/.mcp.json +8 -0
  4. package/LICENSE +21 -0
  5. package/README.de.md +480 -0
  6. package/README.es.md +480 -0
  7. package/README.fr.md +480 -0
  8. package/README.hi.md +480 -0
  9. package/README.id.md +480 -0
  10. package/README.ja.md +478 -0
  11. package/README.ko.md +480 -0
  12. package/README.md +483 -2
  13. package/README.pt.md +480 -0
  14. package/README.ru.md +480 -0
  15. package/README.th.md +480 -0
  16. package/README.tr.md +480 -0
  17. package/README.vi.md +480 -0
  18. package/README.zh-TW.md +478 -0
  19. package/README.zh.md +482 -0
  20. package/agents/ds-flash.md +17 -0
  21. package/agents/ds-pro.md +17 -0
  22. package/agy/agents/ds-flash.md +18 -0
  23. package/agy/agents/ds-pro.md +18 -0
  24. package/agy/skills/dsh-config/SKILL.md +6 -0
  25. package/agy/skills/dsh-playbook/SKILL.md +65 -0
  26. package/agy/skills/dsh-status/SKILL.md +6 -0
  27. package/codex/agents/ds-flash.toml +23 -0
  28. package/codex/agents/ds-pro.toml +23 -0
  29. package/codex/prompts/dsh-config.md +3 -0
  30. package/codex/prompts/dsh-playbook.md +60 -0
  31. package/codex/prompts/dsh-status.md +1 -0
  32. package/commands/config.md +9 -0
  33. package/commands/off.md +5 -0
  34. package/commands/on.md +5 -0
  35. package/commands/playbook.md +64 -0
  36. package/commands/status.md +5 -0
  37. package/cordis.patch.yml +4 -0
  38. package/docs/images/dsh-crew-host.png +0 -0
  39. package/docs/images/dsh-crew-jobs.png +0 -0
  40. package/docs/images/dsh-crew-logo.png +0 -0
  41. package/docs/images/dsh-crew-overview.png +0 -0
  42. package/grok/agents/ds-flash.md +19 -0
  43. package/grok/agents/ds-pro.md +19 -0
  44. package/grok/commands/dsh-config.md +9 -0
  45. package/grok/commands/dsh-playbook.md +66 -0
  46. package/grok/commands/dsh-status.md +5 -0
  47. package/lib/client.js +2684 -0
  48. package/lib/server.mjs +15417 -0
  49. package/package.json +137 -4
  50. package/scripts/build-client.mjs +23 -0
  51. package/scripts/build-mcp.mjs +43 -0
  52. package/scripts/fake-agy.sh +23 -0
  53. package/scripts/release-local.mjs +87 -0
  54. package/scripts/smoke-bundle.mjs +166 -0
  55. package/scripts/smoke-cwd.mjs +41 -0
  56. package/scripts/smoke-pack.mjs +285 -0
  57. package/scripts/smoke.mjs +79 -0
  58. package/scripts/verify-cli-workers.mjs +133 -0
  59. package/scripts/verify-wpc10-client.mjs +237 -0
  60. package/scripts/verify-wpc14-proc-endpoints.mjs +356 -0
  61. package/scripts/verify-wpc9-guardrails.mjs +432 -0
  62. package/src/cli-workers.mjs +396 -0
  63. package/src/client/index.tsx +1133 -0
  64. package/src/client/jobs-view.ts +374 -0
  65. package/src/cwd-lock.mjs +91 -0
  66. package/src/hub/index.mjs +643 -0
  67. package/src/hub-client.mjs +72 -0
  68. package/src/i18n.mjs +19 -0
  69. package/src/install/cli.mjs +34 -0
  70. package/src/install/install.mjs +577 -0
  71. package/src/jobs.mjs +289 -0
  72. package/src/multimodal.mjs +744 -0
  73. package/src/origin-guard.mjs +133 -0
  74. package/src/paths.mjs +43 -0
  75. package/src/plugin-env.mjs +65 -0
  76. package/src/proc-kill.mjs +208 -0
  77. package/src/process-info.mjs +60 -0
  78. package/src/provider-probe.mjs +35 -0
  79. package/src/server.mjs +438 -0
  80. package/src/status-shard.mjs +95 -0
  81. package/src/tier-binding.mjs +63 -0
  82. package/src/vision-route.mjs +139 -0
  83. package/src/worker-profiles.mjs +95 -0
  84. package/src/worker-question.mjs +22 -0
  85. package/statusline/statusline.sh +14 -0
  86. package/statusline/worker-segment.sh +35 -0
  87. 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 &bull; Política de Tier &amp; Escalonamento &bull; Proteções de Despacho &bull; Quadro de Jobs &bull; Sessões DSH no Host &bull; Visão &amp; Geração de Imagens (Native-First) &bull; Instalação em Um Clique</sub>
10
+ </p>
11
+
12
+ <p align="center">
13
+ <sub>npm: <code>@zoraxylia/dsh-codex-adapter</code> &middot; Versão atual do plugin: <code>0.1.0-rc.11</code> &middot; 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> &middot; <a href="./README.zh.md">简体中文</a> &middot; <a href="./README.zh-TW.md">繁體中文</a> &middot; <a href="./README.ja.md">日本語</a> &middot; <a href="./README.ko.md">한국어</a> &middot; <a href="./README.fr.md">Français</a> &middot; <a href="./README.es.md">Español</a> &middot; <a href="./README.de.md">Deutsch</a> &middot; <a href="./README.pt.md"><b>Português</b></a> &middot; <a href="./README.ru.md">Русский</a> &middot; <a href="./README.hi.md">हिन्दी</a> &middot; <a href="./README.tr.md">Türkçe</a> &middot; <a href="./README.th.md">ไทย</a> &middot; <a href="./README.vi.md">Tiếng Việt</a> &middot; <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
+ ```