dsh-switchman 1.3.1 → 1.5.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.it.md CHANGED
@@ -6,19 +6,35 @@
6
6
 
7
7
  ![dsh-switchman — il livello dell'acqua del contesto comanda lo switchman, che devia la rotta](docs/assets/hero.svg)
8
8
 
9
- > Contesto al contatore. I task si assegnano da soli.
9
+ > Contesto al contatore: ogni task trova da sé la corsia giusta.
10
10
 
11
- Un plugin per [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). Una volta installato, il tuo modello primario smette di fare tutto da solo e diventa un dispatcher: misura il livello dell'acqua, sceglie la corsia, assegna il task, controlla il lavoro. Quattro cose:
11
+ ## Perché serve
12
12
 
13
- **1. Controllo del livello dell'acqua del contesto.** A ogni turno misura i token live della sessione. Soft (50k di default) consiglia di delegare, hard (90k) stringe il budget di lettura per turno e spinge alla chiusura, force (130k) esegue il backup della sessione e la consegna alla compattazione — automaticamente. Tieni una sessione aperta tutto il giorno; il tuo contesto non affoga mai nella sua stessa cronologia. Ogni subagent dispatchato porta con sé il proprio hard cap ed esce con un riepilogo HANDOFF quando lo raggiunge.
13
+ Se lavori con DSH, col passare del tempo ti imbatti in due cose:
14
14
 
15
- **2. Dispatch a sei corsie.** economy / mechanical / main / hard / vision / review — sei corsie cognitive. Scegli i modelli candidati per corsia nella pagina delle impostazioni, ordinali dal più forte (ancoraggio opzionale a fasce S/A/B/C) e fissa un reasoning effort per route — il menu a tendina elenca i livelli che ogni modello *supporta davvero*, non tre livelli generici. Una tabella `[SWITCHMAN:POOLS]` viaggia con ogni prompt, così il modello sa a chi rivolgersi; la modalità `enforce` rifiuta seccamente i modelli fuori pool.
15
+ 1. **La sessione pesa sempre di più.** La cronologia gonfia il contesto fino a centinaia di migliaia di token: il modello inizia a dimenticare, rallenta e costa di più, e alla fine non resta che un /compact manuale — che comprime e perde dettagli nel farlo.
16
+ 2. **Il modello principale fa tutto da solo.** Leggere un file, lanciare un test, confrontare dati: è sempre lui a masticarli — lento e costoso, quando gran parte di quel lavoro spetterebbe a un modello economico.
16
17
 
17
- **3. Preferenze linguistiche.** Un menu a tendina per le risposte, uno per i commenti del codice e uno per i documenti redatti. Non impostato? Ti viene chiesto una volta, resta ricordato per sempre e ogni sessione successiva lo rispetta.
18
+ dsh-switchman è un plugin per [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). Una volta installato, il modello principale smette di «fare tutto da solo» e diventa un dispatcher: misura il livello dell'acqua, sceglie la corsia, assegna i task, verifica il risultato. Non è un nuovo modello: è un regolamento di orchestrazione agganciato a DSH più un'interfaccia di configurazione. In concreto fa sei cose:
18
19
 
19
- **4. Dottrina delegate-by-default.** Sostituisce la politica di team conservativa di serie di DSH ("crea membri del team solo su richiesta"): le minuzie restano fai-da-te (<200 righe lette, <50 modificate), il lavoro vero viene delegato di default; ogni modifica viene verificata — oltre 20 righe va a un tester, oltre 300 righe o logica centrale va a un reviewer. Di' "non usare i team" e si fa da parte all'istante.
20
+ **1. Livello dell'acqua del contesto: le sessioni lunghe non esplodono.** A ogni turno conta i token della sessione in tempo reale, e tre soglie inaspriscono a gradini: 50k (soft, regolabile) ricorda che «è ora di delegare»; 90k (hard) stringe il budget di lettura per singola chiamata e spinge verso la chiusura; 130k (force) avvia l'handover automatico — fork della sessione come copia di backup, contesto compattato, continuazione risvegliata: il task non si interrompe. Nemmeno i subagent in background ancora in corsa al momento del passaggio si perdono: id, descrizione del task e percorso del report finiscono nel documento di handover, così la sessione ripresa sa dove raccogliere i report invece di ri-assegnare lo stesso lavoro. Ogni subagent inviato porta con sé un tetto massimo indipendente e, raggiunto il limite, esce dopo aver scritto il riepilogo HANDOFF.
20
21
 
21
- Un solo modello? Vale comunque la pena — il controllo del livello dell'acqua e la dottrina non guardano a quanti modelli hai.
22
+ **2. Sei pool di dispatch: a ogni lavoro il suo modello.** Pool leggero (economy, piccoli lavori in serie), pool meccanico (mechanical, riscritture modellate), pool principale (main, coding di tutti i giorni), pool ad alta difficoltà (hard, ragionamento complesso e refactoring su larga scala), pool multimodale (vision, lettura delle immagini), pool di revisione (review, verifica indipendente). Nella pagina delle impostazioni spunti i candidati, ordini le priorità (con fasce opzionali S/A/B/C) e fichi un reasoning effort per ogni route — il menu a tendina elenca i livelli che quel modello supporta davvero, non tre livelli generici. A ogni turno il prompt del modello principale viaggia con una tabella di raccomandazioni `[SWITCHMAN:POOLS]`: si assegna il lavoro seguendo la tabella. La modalità di esecuzione ha tre stati: off / advice / enforce (enforce = i modelli fuori pool vengono rifiutati sul posto).
23
+
24
+ **3. Modalità Agent Teams: dal lavoro solitario alla squadra.** Disattivata di default: appena installato si lavora con un dispatch leggero via subagent. Nella pagina delle impostazioni, due interruttori indipendenti:
25
+
26
+ - **Modalità Agent Teams** — una volta attivata, inietta la dottrina di squadra (delega per default + verifica a livelli + disciplina del task board condiviso) e abilita automaticamente gli Agent Teams di DSH: il modello principale può arruolare compagni permanenti (`spawn_teammate`), assegnare lavori al task board condiviso (`team_task_*`) e scambiarsi messaggi con loro (`send_message`). Quando formare la squadra segue una disciplina precisa: sotto-task indipendenti parallelizzabili, lavori voluminosi e autosufficienti, livello dell'acqua del contesto principale già alto, necessità di separare i ruoli; le indagini una-tantum restano al subagent. La politica di fabbrica di DSH è «niente squadra se l'utente non la nomina»: qui si inverte in «usala quando serve». Ri-spegnendo l'interruttore, le clausole di squadra spariscono senza residui, e gli strumenti di squadra nelle sessioni in corso non vengono ritirati.
27
+ - **Sincronizzazione della whitelist dei modelli per i subagent** — DSH ha una whitelist di autorizzazione «Consenti agli agenti di scegliere i modelli per i subagent»: le route scelte nei pool ma non autorizzate vengono rifiutate se il modello principale le nomina esplicitamente (in modalità squadra, la tabella di raccomandazioni e la pagina delle impostazioni le marcano con ⚠). Con questo interruttore attivo, l'unione dei sei pool viene scritta in un colpo solo in quella whitelist — niente configurazione doppia: switchman è l'unica fonte di verità, e vi rientra anche il percorso di dispatch via fork. La whitelist scatta come snapshot alla «nuova sessione»: la sincronizzazione vale solo per le sessioni aperte dopo.
28
+
29
+ L'intestazione della sessione dà un riscontro immediato: badge ⚡ «Squadra autonoma», ◇ modello effettivo della sessione in corso; durante un handover automatico compare un avviso in tempo reale del tipo «Handover in corso · backup della sessione / compattazione del contesto / risveglio della continuazione».
30
+
31
+ **4. Preferenze linguistiche: chiede una volta, ricorda per sempre.** Un menu a tendina per ciascuna delle tre lingue — risposte, commenti nel codice, documenti — con ambito a scelta globale o per progetto (`.switchman/lang.json`). Puoi anche non impostarlo: al primo utilizzo ti viene chiesto una volta, nella lingua dell'interfaccia DSH, e da lì in poi ogni sessione lo rispetta da sé.
32
+
33
+ **5. Verifica a livelli: finita la modifica, si controlla.** Le modifiche oltre 20 righe vanno a un tester per la verifica; oltre 300 righe, o quando si toccano logica centrale / sicurezza / coerenza dei dati, subentra anche un reviewer con revisione indipendente. Il modello del reviewer si sceglie ancorandolo a quello dell'«agente che ha scritto il diff», evitandolo per quanto possibile; se nel pool proprio non si riesce, la conclusione dichiara DOWNGRADED. Basta dire «non usare le squadre» e torna subito a lavorare da solo.
34
+
35
+ **6. `/vision`: anche i modelli solo testo trattano le immagini.** Quando il modello principale non sa leggere le immagini, DSH rifiuta al varco i messaggi che le contengono. Alleghi l'immagine e digiti `/vision dov'è l'errore in questa immagine`: l'immagine viene risolta in un percorso di file e affidata alla lettura di un modello del pool multimodale, e la conclusione torna nella sessione corrente. Sopra la casella di input compare in anticipo l'avviso «il modello corrente non supporta la lettura delle immagini»; se un invio diretto dell'immagine viene rifiutato, il messaggio viene riscritto una volta in `/vision` e reinviato da solo, senza dover rifare tutto a mano; senza pool multimodale configurato, il comando rifiuta e indica come configurarlo.
36
+
37
+ Un solo modello? Vale comunque la pena installarlo — il controllo del livello dell'acqua e la verifica a livelli non guardano a quanti modelli hai, e ne giovancono allo stesso modo le sessioni lunghe con un modello unico.
22
38
 
23
39
  ## Skill incluse
24
40
 
@@ -40,23 +56,38 @@ Un solo modello? Vale comunque la pena — il controllo del livello dell'acqua e
40
56
  plugin_manager: install_bundle target=/path/to/dsh-switchman
41
57
  ```
42
58
 
59
+ oppure da un terminale tramite la CLI `dsh` — scegli il profilo che corrisponde a come esegui DSH:
60
+
61
+ ```bash
62
+ dsh plugin --profile web add dsh-switchman # Web GUI
63
+ dsh plugin --profile desktop add dsh-switchman # app desktop
64
+ ```
65
+
43
66
  2. **Riavvia DSH** — chiudi completamente l'app e riaprila (ricaricare la pagina non basta), così la tabella dei moduli client rileva il bundle.
44
67
 
45
- 3. **Apri la pagina delle impostazioni** — Settings → dsh-switchman. La prima schermata è le preferenze linguistiche: un menu a tendina per risposte / commenti / documenti, ciascuno con una riga live `current: …`. Salta pure — ti verrà chiesto una volta e verrà ricordato.
68
+ 3. **Preferenze linguistiche** — Settings → dsh-switchman, oppure la voce «Switchman Control Center» nella barra laterale della home. Nella prima schermata si sceglie prima l'ambito: globale (questo profilo) o per progetto (il `.switchman/lang.json` di ciascun progetto); poi tre menu a tendina fissano rispettivamente la lingua di risposte / commenti / documenti, ciascuno con una riga di stato «Attuale: …» sottostante. Puoi anche saltare: al primo uso ti verrà chiesto una volta e ricordato (la domanda segue la lingua dell'interfaccia DSH).
69
+
70
+ ![Preferenze linguistiche: ambito e tre lingue](docs/assets/conf-language-en.png)
71
+
72
+ 4. **Configura i pool di dispatch** — in ogni scheda di pool spunti i modelli candidati raggruppati per provider; spuntando «ordine manuale» la scheda diventa una lista di priorità numerata, da riordinare con ↑ ↓ ×, e accanto a ogni route puoi fichare il reasoning effort (predefinito «segui la corsia»; una volta fichato elenca le fasce che quel modello supporta davvero). La riga di riepilogo in alto riflette i progressi in tempo reale, per esempio «6/6 pool configurati · 2 in classifica · modalità advice».
73
+
74
+ ![Pool di dispatch: i quattro pool economy / mechanical / main / hard](docs/assets/conf-pool-1-en.png)
75
+
76
+ Il pool multimodale e quello di revisione stanno più sotto; ancora più in basso arrivano la **classifica di capacità** (l'unione dei modelli scelti nei sei pool: la numerazione è l'ordine di capacità, i più forti davanti, con fasce opzionali S/A/B/C) e la **modalità di esecuzione** (advice / enforce).
46
77
 
47
- ![Pagina impostazioni e preferenze linguistiche](docs/assets/conf-demo1.png)
78
+ ![Pool multimodale e pool di revisione, classifica di capacità e modalità di esecuzione](docs/assets/conf-pool-2-en.png)
48
79
 
49
- 4. **Compila i sei pool** — ogni scheda pool elenca i candidati raggruppati per provider; spunta quelli che vuoi. Spunta **manual order** e la scheda diventa una lista di priorità numerata con i controlli ↑ ↓ ×. Il menu effort accanto a ogni route selezionata è su *follow lane* di default; fissandolo mostra i livelli che quel modello supporta davvero (Low / High / Max…). Una riga di riepilogo traccia i progressi in tempo reale: “6/6 pool impostati · 3 in classifica · modalità advice”.
80
+ 5. **Agent Teams** — entrambi gli interruttori partono spenti: prima falla girare in puro modello subagent. Per lasciare che arruoli la squadra da sola, attiva «Modalità Agent Teams»; per risparmiare la doppia autorizzazione, attiva «Sincronizzazione della whitelist dei modelli per i subagent» — sotto l'interruttore una riga di stato del tipo «N voci sincronizzate + ora» conferma l'esito della scrittura.
50
81
 
51
- ![Pool di dispatch](docs/assets/conf-demo2.png)
82
+ ![Agent Teams: i due interruttori e lo stato di sincronizzazione della whitelist](docs/assets/conf-team-en.png)
52
83
 
53
- 5. **Classifica e watermark** — l'ordine della tabella di classifica è l'ordine di capacità (prima i più forti), con fasce opzionali S/A/B/C; la modalità di esecuzione è `off` / advice / enforce (enforce = i modelli fuori pool vengono rifiutati). Sotto, la sezione watermark irrigidisce il comportamento in base al consumo di token: tre soglie, un budget di lettura per chiamata, il comportamento della modalità hard (cap / deny), un interruttore per l'handover automatico e un cap separato per i subagent. La riga in fondo porta i comandi: `/ctx-pause` per smettere di intervenire · `/ctx-resume` per riprendere · `/ctx-handover` per fare subito backup e passaggio di consegne.
84
+ 6. **Livello dell'acqua del contesto** — le tre soglie (predefinite 50000 / 90000 / 130000), il budget di lettura per singola chiamata, il comportamento della soglia hard (passa con limitazione / blocca), l'interruttore dell'handover automatico e il tetto indipendente dei subagent stanno tutti in quest'area. Una riga di comandi in fondo: `/ctx-pause` sospende gli interventi · `/ctx-resume` li riprende · `/ctx-handover` fa subito backup e passaggio di consegne (guida la sessione fino al confine di inattività e attende la finestra di retry della compattazione: il risultato può richiedere alcuni minuti).
54
85
 
55
- ![Classifica e watermark del contesto](docs/assets/conf-demo3.png)
86
+ ![Livello dell'acqua del contesto: soglie, budget e comandi](docs/assets/conf-ctx-en.png)
56
87
 
57
- 6. **Verifica** — il badge ⚡ appare accanto al chip del preset nell'intestazione di ogni sessione; chiedi al modello “cosa dice l'ultima sezione del tuo system prompt?” — dovrebbe menzionare la dottrina dsh-switchman.
88
+ 7. **Verifica** — nell'intestazione della sessione compare il badge ⚡ «Squadra autonoma» (accanto, il ◇ mostra il modello della sessione in corso); oppure chiedi direttamente al modello «qual è il titolo dell'ultima sezione del tuo system prompt?» — la risposta dovrebbe menzionare la dottrina dsh-switchman.
58
89
 
59
- **Configurazione una tantum di db-query** (le dipendenze degli script vivono nella directory della skill):
90
+ **Configurazione una tantum di db-query** (le dipendenze degli script vivono nella directory della skill, senza sporcare il progetto):
60
91
 
61
92
  ```bash
62
93
  bash <install-dir>/skills/db-query/scripts/setup.sh
@@ -64,15 +95,16 @@ bash <install-dir>/skills/db-query/scripts/setup.sh
64
95
 
65
96
  ## Come funziona
66
97
 
67
- - La parte Host (`index.js` + `host/`) inietta tre sezioni dinamiche del system prompt, i gate di budget di lettura ed enforce, la cattura automatica delle risposte e tre comandi slash. Tutte le impostazioni sono campi volatili — le modifiche salvate valgono dall'assemblaggio del prompt successivo, senza riavvio.
68
- - La parte Client (`client.js`) renderizza il badge ⚡ accanto al chip del preset e la pagina delle impostazioni, attraverso i servizi ufficiali settings-form.
69
- - `cordis.patch.yml` ripete verbatim la lista di plugin di ogni preset di serie ed estende solo il suffisso di persona; gli strumenti Agent Teams in sé continuano a venire dal `@deepseek-ai/dsh-experimental-agent-team-profile` di serie.
98
+ - La parte Host (`index.js` + `host/`) inietta le sezioni dinamiche del system prompt (lingue / corsie / livello dell'acqua / squadra), il doppio cancello budget di lettura + enforce e i quattro comandi slash (il trio ctx più `/vision`). Ogni impostazione salvata vale già dall'assemblaggio del prompt successivo, senza riavvio.
99
+ - La parte Client (`client.js`) renderizza la pagina delle impostazioni, il badge ⚡ e l'identificativo ◇ del modello nell'intestazione della sessione e l'avviso dinamico durante l'handover, appoggiandosi ai servizi ufficiali settings-form.
100
+ - La voce «Switchman Control Center» nella barra laterale della home apre con un clic la stessa pagina di configurazione (preferenze linguistiche, pool di dispatch e classifica, livello dell'acqua) come pannello centrale; la voce nelle impostazioni resta al suo posto.
101
+ - `cordis.patch.yml` conserva integralmente la lista di plugin dei preset di fabbrica e interviene solo sul persona suffix; gli strumenti Agent Teams in sé vengono dal bundle di fabbrica e vengono abilitati automaticamente all'attivazione della modalità squadra.
70
102
 
71
103
  ## Manutenzione
72
104
 
73
- - Dopo un upgrade di DSH che cambia le liste di plugin dei preset di serie, risincronizza `cordis.patch.yml` dai nuovi `presets/*.patch.yml` (conserva il suffisso della dottrina), poi reinstalla.
74
- - Le righe di protocollo rivolte al modello (`[SWITCHMAN:LANG|POOLS|WATERMARK]`) sono deliberatamente in inglese e stabili al byte — non localizzarle.
75
- - `npm pack --dry-run` deve restare alla forma auditata di 34 file / ~111 kB (gli screenshot in `docs/` non viaggiano mai nel pacchetto).
105
+ - Dopo un upgrade di DSH che cambia la lista di plugin dei preset di serie, risincronizza `cordis.patch.yml` dai nuovi `presets/*.patch.yml` (mantieni il doctrine suffix), poi reinstalla.
106
+ - Le righe di protocollo (`[SWITCHMAN:LANG|POOLS|WATERMARK|TEAMS]`) restano deliberatamente in inglese e stabili al byte — non localizzarle.
107
+ - `npm pack --dry-run` deve restare alla forma auditata di 50 file / ~205 kB (gli screenshot in `docs/` non viaggiano nel pacchetto).
76
108
 
77
109
  ## License
78
110
 
package/README.ja.md CHANGED
@@ -4,59 +4,90 @@
4
4
 
5
5
  > **switchman ファミリー**。同じ作者、同じオーケストレーション指針:[opencode-switchman](https://github.com/mrzturn/opencode-switchman)(OpenCode 原版)· [zcode-switchman](https://github.com/mrzturn/zcode-switchman)(ZCode 移植版)· **dsh-switchman**(本リポジトリ、DeepSeek Harness 版)。
6
6
 
7
- ![dsh-switchman — コンテキスト水位が転轍士を動かし、タスクを正しいレーンへ投げ込む](docs/assets/hero.svg)
7
+ ![dsh-switchman — コンテキスト水位が転轍機を動かし、タスクを正しいレーンへ投げ込む](docs/assets/hero.svg)
8
8
 
9
9
  > コンテキストに水量計を付けると、タスクは自分でレーンを見つけます。
10
10
 
11
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH)用のプラグインです。導入すると、メインモデルは「何もかも自分でこなす」役を降りてディスパッチャーになります:水位を測り、レーンを選び、タスクを配り、仕上がりを確認する。やることは 4 つです:
11
+ ## なぜ必要か
12
12
 
13
- **1. コンテキスト水位制御。** 毎ラウンドでセッション token をリアルタイム計測します。soft(デフォルト 50k)は委譲を勧め、hard(90k)はラウンドごとの読み取り予算を引き締めてまとめに入るよう促し、force(130k)はセッションを自動バックアップして圧縮へ引き渡します。セッションを一日中回しても、コンテキストが自分の履歴で溺れることはありません。委譲された各サブエージェントは独立したハード上限を持ち、超えたら HANDOFF 要約を書いて退場します。
13
+ DSH で作業を続けていると、時間がたつうちに次の 2 つにぶつかります:
14
14
 
15
- **2. 6 レーンのディスパッチ。** economy / mechanical / main / hard / vision / review の 6 つの認知レーン:設定ページで候補モデルを選び、最強優先でランク付けし(S/A/B/C ティアのアンカーは任意)、ルートごとに思考強度をピン留めできます——ドロップダウンのレベル一覧は各モデルが*実際に*対応しているものから直接来るもので、汎用の三段階ではありません。`[SWITCHMAN:POOLS]` 推奨表がプロンプトとともに主モデルへ渡され、主モデルはそれに従って仕事を振ります。`enforce` モードではプール外モデルを即座に拒否します。
15
+ 1. **会話がどんどん重くなる。** 履歴でコンテキストが数十万 token まで膨らむと、モデルは物忘れが増え、遅くなり、高くつきます。最後には手動 /compact 一択になりますが、圧縮するたびに細部がこぼれ落ちます。
16
+ 2. **主力モデルが何もかも自分でこなす。** ファイルを 1 つ調べる、テストを回す、データを照合する——そのすべてを主力モデルが齧っています。遅い上にお金もかかり、その大半は実は安いモデルに任せられるはずの仕事です。
16
17
 
17
- **3. 言語設定。** 返信・コードコメント・ドキュメントの 3 種類に、それぞれドロップダウンを一つ。未設定なら初回に一度だけ尋ねて永久に記憶し、以後のすべてのセッションが自動で従います。
18
+ dsh-switchman は [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH)のプラグインです。導入すると、メインモデルは「何もかも自分でこなす」役からディスパッチャーへ変わります:水位を測り、レーンを選び、タスクを配り、検収を見届ける。新しいモデルではなく、DSH に載せるオーケストレーション規律と設定画面ひと組です。具体的には 6 つのことをします:
18
19
 
19
- **4. デフォルト委譲のドクトリン。** DSH 出荷時の保守的なチーム方針(「頼まれたときだけチームメイトを作る」)を置き換えます:些細な作業は自分で手を動かし(読み <200 行、変更 <50 行)、大きな仕事はデフォルトで委譲。変更は必ず検証されます——20 行超は tester へ、300 行超またはコアロジックに触れる変更は reviewer へ。「チームを使うな」と一言言えば、即座に身を引きます。
20
+ **1. コンテキスト水位:長いセッションを溢れさせない。** 毎ラウンド、セッションの token 数をリアルタイムに集計し、3 本の水位線で段階的に引き締めます:50k(soft、変更可)で「そろそろ委譲すべき」と促し、90k(hard)で 1 回あたりのファイル読み取り予算を絞って締めくくりへ誘導し、130k(force)で自動ハンドオーバー——セッションを fork して記録を残し、コンテキストを圧縮し、続きを担うセッションを起こします。タスクは途切れません。ハンドオーバーの瞬間にまだ走っているバックグラウンドのサブエージェントも失われません:id・タスク説明・レポートのパスはすべて引き継ぎ文書に書き込まれ、続行するセッションはレポートをどこから回収するかを知っていて、同じ仕事を二重に振りません。配られた各サブエージェントには独立したハード上限が付き、上限に達したら HANDOFF 要約を書いて退場します。
20
21
 
21
- モデルが一つだけ?それでも導入する価値があります——水位制御とドクトリンは、モデルの数など気にしません。
22
+ **2. 6 つのディスパッチプール:仕事に見合うモデルを選ぶ。** 軽量プール(economy、小口の大量タスク)、機械的プール(mechanical、テンプレート的な書き換え)、主力プール(main、日常のコーディング)、高難度プール(hard、難推論と大規模リファクタリング)、マルチモーダルプール(vision、画像の読み取り)、レビュープール(review、独立した検証)。設定ページで候補にチェックを入れ、優先順位を付け(S/A/B/C ティアのアンカーは任意)、ルートごとに思考強度をピン留めできます——強度のドロップダウンは各モデルが実際に対応しているレベルから直接来るもので、汎用の 3 段階ではありません。メインモデルのプロンプトには毎ラウンド `[SWITCHMAN:POOLS]` 推奨表が添えられ、表に従って仕事を振ります。実行モードは 3 態:オフ / アドバイス / 強制(強制 = プール外モデルは即座に拒否)。
23
+
24
+ **3. Agent Teams モード:単独作業からチーム運用へ。** デフォルトはオフで、導入直後は軽量な subagent ディスパッチです。設定ページには独立した 2 つのスイッチがあります:
25
+
26
+ - **エージェントチームモード**——オンにするとチーム規律(デフォルト委譲 + 段階的検証 + 共有タスクボードの規律)が注入され、DSH の Agent Teams が自動で有効になります:メインモデルは常駐チームメイトを招集し(`spawn_teammate`)、共有タスクボードに仕事を積み(`team_task_*`)、チームメイトとメッセージをやり取り(`send_message`)できます。チームを組むべきタイミングには明確な規律があります:並行して進められる独立サブタスク、量が多く自己完結した仕事、メインコンテキストの水位がすでに高いとき、役割の分離が必要なとき。単発の一点調査は引き続き subagent へ。DSH の出荷時ポリシーは「ユーザーが名指ししなければチームを作らない」ですが、ここでは「使うべきときに使う」へ反転します。スイッチをもう一度オフにすれば、チーム関連の条項は残さず消え、実行中のセッションからチームツールを引き剥がすこともありません。
27
+ - **サブエージェントモデル許可リストの同期**——DSH には「Agent によるサブエージェントのモデル選択を許可」という承認リストがあります:プールで選んでも承認されていないルートを、メインモデルが名指しでディスパッチすると拒否されます(チームモードでは、推奨表と設定ページがそのようなルートに ⚠ を付けます)。このスイッチをオンにすると、6 プールの和集合がまるごとそのリストに書き込まれます——二重設定は不要になり、switchman が唯一の事実源となり、fork ディスパッチ経路もまとめて取り込まれます。許可リストは「新規セッション」時点のスナップショットで効くため、同期はそれ以降に開いたセッションにのみ反映されます。
28
+
29
+ セッションヘッダーには分かりやすい表示が出ます:⚡「自律チーム」バッジ、◇ 現在のセッションで実際に使われているモデル。自動ハンドオーバーが進行している間は「ハンドオーバー進行中 · セッションをバックアップ / コンテキストを圧縮 / 起こして継続」というリアルタイム表示が現れます。
30
+
31
+ **4. 言語設定:一度尋ねて、ずっと覚える。** 返信・コードコメント・ドキュメントの 3 種類それぞれにドロップダウンをひとつ、スコープはグローバルまたはプロジェクト単位(`.switchman/lang.json`)を選べます。設定しなくても構いません——最初に必要になった時点で、DSH の UI 言語で一度だけ尋ねて覚え、以後のすべてのセッションが自動で従います。
32
+
33
+ **5. 段階的検証:変えたら必ず確かめる。** 20 行を超える変更は tester による検証へ、300 行を超える変更やコア・セキュリティ・データ整合性のロジックに触れる変更は、さらに reviewer による独立レビューを重ねます。レビュー担当モデルは「この diff を書いたエージェント」が使ったモデルを基準に選び、可能な限りそれを避けます。プール内でどうしても避けられない場合は、結論に DOWNGRADED と明記されます。「チームを使うな」と一言言えば、即座に単独作業へ戻ります。
34
+
35
+ **6. `/vision`:テキスト専用モデルでも画像を扱える。** メインモデルが画像を読めないとき、DSH は入り口で画像付きメッセージをそのまま拒否します。画像を貼り付けて `/vision この画像のどこがおかしいか` と入力すれば、画像はファイルパスに解決されてマルチモーダルプールのモデルに読んでもらえ、結論は現在のセッションに戻ってきます。入力ボックスの上には「現在のモデルは画像を読み取れません」というヒントが先に表示されます。画像を直接送って拒否された場合は、自動的に `/vision` 形式に書き直して一度だけ再送するので、打ち直しは不要です。マルチモーダルプールが未設定の場合、コマンドは拒否して設定案内を示します。
36
+
37
+ モデルがひとつだけ?それでも入れる価値はあります——水位制御と段階的検証はモデルの数に依存せず、単一モデルの長時間セッションでも同じように恩恵を受けられます。
22
38
 
23
39
  ## 同梱スキル
24
40
 
25
- - **db-query** — MySQL / Redis 読み取り専用検証:SQL を回してレコード照合、キャッシュキー / TTL 確認、ストア横断の整合性チェックを行い、書き込みは一切拒否します。初回使用時に初期化が必要(下記参照)。
26
- - **git-commit-message** — 規範に沿った commit 文面を生成。テキストだけ出力し、git は一切触りません。
41
+ - **db-query** — MySQL / Redis の読み取り専用検証:SQL を回してレコードを突き合わせ、キャッシュキー / TTL を確認し、ストア横断の整合性をチェックします。書き込みは一切拒否します。初回使用時に初期化が必要です(下記参照)。
42
+ - **git-commit-message** — 規範に沿った commit 文面を生成します。テキストだけを出力し、git の操作は一切代行しません。
27
43
  - **requirement-docs** — 要件分析 / PRD / 設計ドキュメントの統一規範。成果物は `docs/requirements-and-design/` にアーカイブします。
28
44
 
29
45
  ## クイックスタート
30
46
 
31
- 1. **インストール** — 任意のセッションでエージェントに実行させるか、Web プラグイン管理ページから:
47
+ 1. **インストール** — 任意のセッションでエージェントに実行させるか、Web のプラグイン管理ページから:
32
48
 
33
49
  ```
34
50
  plugin_manager: install_bundle target=dsh-switchman
35
51
  ```
36
52
 
37
- またはローカルチェックアウトから(link 方式。更新取り込み後は `remove_bundle` + `install_bundle` で再インストール):
53
+ またはローカルチェックアウトから(link 方式。更新を取り込んだ後は `remove_bundle` + `install_bundle` で再インストール):
38
54
 
39
55
  ```
40
56
  plugin_manager: install_bundle target=/path/to/dsh-switchman
41
57
  ```
42
58
 
43
- 2. **DSH を再起動** — アプリを完全に終了して開き直します(ページ再読み込みでは不十分)。クライアントモジュールのテーブルがこの bundle を取り込めるようになります。
59
+ またはターミナルから `dsh` コマンドでインストール——実行形態に合わせてプロファイルを選びます:
60
+
61
+ ```bash
62
+ dsh plugin --profile web add dsh-switchman # Web GUI
63
+ dsh plugin --profile desktop add dsh-switchman # デスクトップアプリ
64
+ ```
65
+
66
+ 2. **DSH を再起動** — アプリを完全に終了してから開き直します(ページの再読み込みでは足りません)。クライアントモジュールのテーブルがこの bundle を認識できるようになります。
67
+
68
+ 3. **言語設定** — 設定 → dsh-switchman、またはホームのサイドバーにある「Switchman ディスパッチセンター」。最初の画面でスコープを選びます:グローバル(この profile)またはプロジェクト単位(各プロジェクトの `.switchman/lang.json`)。次に 3 つのドロップダウンで、返信 / コメント / ドキュメントの言語をそれぞれ決めます。各項目の下には「現在: …」のステータス行が付きます。飛ばしても大丈夫——最初に使うときに一度だけ尋ねて記憶します(尋ねる言語は DSH の UI 言語に従います)。
69
+
70
+ ![言語設定:スコープと 3 つの言語](docs/assets/conf-language-en.png)
71
+
72
+ 4. **ディスパッチプールを設定** — 各プールカードで、プロバイダー別にグループ化された候補モデルにチェックを入れます。「手動順」にチェックすると、カードは番号付き優先リストに変わり、↑ ↓ × で順序を調整できます。各ルートの横では思考強度をピン留めできます(初期値は「レーンに従う」。ピン留めすると、そのモデルが実際に対応しているレベルが選べます)。上部のサマリー行は進捗をリアルタイムに反映します。たとえば「プール設定 6/6 · ランク付け 2 件 · モード アドバイス」。
73
+
74
+ ![ディスパッチプール:軽量 / 機械 / 主力 / 高難度の 4 プール](docs/assets/conf-pool-1-en.png)
44
75
 
45
- 3. **設定ページを開く** — 設定 → dsh-switchman。最初の画面は言語設定です:返信 / コメント / ドキュメントに対応する 3 つのドロップダウンがあり、それぞれの下に「現在: …」のステータス行が付きます。設定しなくても大丈夫——初回に一度だけ尋ねられて記憶されます。
76
+ マルチモーダルプールとレビュープールはその下にあります。さらに下には**能力ランキング**(6 プールで選んだモデルの和集合。番号が能力順、最強が先頭、S/A/B/C ティアでアンカー可能)と**実行モード**(アドバイス / 強制)があります。
46
77
 
47
- ![設定ページと言語設定](docs/assets/conf-demo1.png)
78
+ ![マルチモーダルプール・レビュープールと能力ランキング・実行モード](docs/assets/conf-pool-2-en.png)
48
79
 
49
- 4. **六つのプールを埋める** — 各プールカードにはプロバイダー別にグループ化された候補モデルが並びます。欲しいものにチェック。**手動順**にチェックすると、カードは ↑ ↓ × 操作付きの番号付き優先リストになります。選択した各ルートの横にある思考強度ドロップダウンの初期値は「レーンに従う」で、ピン留めすればそのモデルが実際に対応するレベル(Low / High / Max…)が選べます。サマリー行が進捗をリアルタイムに反映します:「プール設定 6/6 · ランク付け 3 件 · モード アドバイス」。
80
+ 5. **エージェントチーム** — 2 つのスイッチはデフォルトでオフ。まずは純粋な subagent モードで回します。自分でチームを組んでほしいときは「エージェントチームモード」を、二重の承認設定を省きたいときは「サブエージェントモデル許可リストの同期」をオンにします——スイッチの下に「N 件を同期済み + 同期時刻」のステータス行が出て、書き込み結果を確認できます。
50
81
 
51
- ![ディスパッチプールの設定](docs/assets/conf-demo2.png)
82
+ ![エージェントチーム:2 つのスイッチと許可リスト同期の状態](docs/assets/conf-team-en.png)
52
83
 
53
- 5. **能力ランクと水位** — ランキング表の番号はそのまま能力順(最強が先)で、S/A/B/C ティアのアンカーは任意。実行モードは三態です:`off` / アドバイス / enforce(enforce = プール外モデルは即拒否)。その下の水位セクションは token 使用量に応じて段階的に挙動を引き締めます:三段階のしきい値、1 回あたりの読み取り予算、hard モードの挙動(制限付き通過 / 遮断)、自動ハンドオーバー切替、サブエージェント独立上限。最下部にはコマンド行があります:`/ctx-pause` 介入を一時停止 · `/ctx-resume` 再開 · `/ctx-handover` 即時バックアップして引き継ぎ。
84
+ 6. **コンテキスト水位** — 3 段階のしきい値(デフォルト 50000 / 90000 / 130000)、1 回あたりの読み取り予算、hard 段の挙動(制限付き通過 / 遮断)、自動ハンドオーバーのスイッチ、サブエージェントの独立上限、そのすべてがこのエリアにあります。最下部にはコマンドが 1 行:`/ctx-pause` 介入を一時停止 · `/ctx-resume` 再開 · `/ctx-handover` 即座にバックアップして引き継ぐ(セッションをアイドル境界へ誘導し、圧縮のリトライ期間を待つため、結果まで数分かかることがあります)。
54
85
 
55
- ![能力ランクとコンテキスト水位](docs/assets/conf-demo3.png)
86
+ ![コンテキスト水位:しきい値・予算・コマンド](docs/assets/conf-ctx-en.png)
56
87
 
57
- 6. **検証** — どのセッションでもヘッダーのプリセット chip の横に ⚡ バッジが表示されます。モデルに「システムプロンプトの最後のセクションには何が書かれていますか」と尋ねてみてください。dsh-switchman のドクトリンに言及するはずです。
88
+ 7. **確認** — セッションヘッダーに ⚡「自律チーム」バッジが現れます(隣の ◇ に現在のセッションモデルが表示されます)。またはモデルに直接「システムプロンプトの最後のセクションのタイトルは何ですか」と尋ねてみてください。dsh-switchman の規律に言及するはずです。
58
89
 
59
- **db-query の初回セットアップ**(スクリプトの依存関係はスキルディレクトリ内に置かれます):
90
+ **db-query の初回セットアップ**(スクリプトの依存関係はスキルディレクトリ内に入るので、プロジェクトを汚しません):
60
91
 
61
92
  ```bash
62
93
  bash <install-dir>/skills/db-query/scripts/setup.sh
@@ -64,15 +95,16 @@ bash <install-dir>/skills/db-query/scripts/setup.sh
64
95
 
65
96
  ## 仕組み
66
97
 
67
- - Host 側(`index.js` + `host/`)は、動的システムプロンプトセクション 3 つ、読み取り予算と enforce の二重ゲート、回答の自動キャプチャ、スラッシュコマンド 3 つを注入します。設定はすべて volatile フィールドで、保存すれば次のプロンプト組み立てから反映され、再起動は不要です。
68
- - Client 側(`client.js`)はプリセット chip の横の ⚡ バッジと設定ページを描画します。公式の settings-form サービス経由です。
69
- - `cordis.patch.yml` は出荷時プリセットのプラグインリストをフィールド単位でそのまま写し、persona suffix だけを拡張します。Agent Teams ツール本体は引き続き出荷時の `@deepseek-ai/dsh-experimental-agent-team-profile` から供給されます。
98
+ - Host 側(`index.js` + `host/`)は、動的なシステムプロンプトセクション(言語 / レーン / 水位 / チーム)、読み取り予算と enforce の二重ゲート、4 つのスラッシュコマンド(ctx の 3 つ + `/vision`)を注入します。設定はすべて、保存した次のプロンプト組み立てから有効になり、再起動は不要です。
99
+ - Client 側(`client.js`)は設定ページ、セッションヘッダーの ⚡ バッジと ◇ モデル表示、ハンドオーバー進行中の動的表示を描画します。公式の settings-form サービス経由です。
100
+ - ホームのサイドバーにある「Switchman ディスパッチセンター」の入口は、クリック 1 回で同じ設定ページ(言語設定、ディスパッチプールとランキング、水位)を中央パネルとして開きます。元の設定入口もそのまま残ります。
101
+ - `cordis.patch.yml` は出荷時プリセットのプラグインリストを完全に保持し、persona suffix だけを拡張します。Agent Teams ツール本体は出荷時の bundle から供給され、チームモードをオンにすると自動で有効になります。
70
102
 
71
103
  ## メンテナンス
72
104
 
73
- - DSH のアップグレード後、出荷時プリセットのプラグインリストが変わっていたら、新しい `presets/*.patch.yml` から `cordis.patch.yml` を再同期し(doctrine suffix は維持)、再インストールします。
74
- - プロトコル行(`[SWITCHMAN:LANG|POOLS|WATERMARK]`)は意図的に英語・バイト安定を保っています——ローカライズしないでください。
75
- - `npm pack --dry-run` は監査済みの 34 ファイル / ~111 kB の形を維持する必要があります(`docs/` のスクリーンショットはパッケージに入りません)。
105
+ - DSH のアップグレード後に出荷時プリセットのプラグインリストが変わっていたら、新しい `presets/*.patch.yml` から `cordis.patch.yml` を再同期し(doctrine suffix は維持)、再インストールします。
106
+ - プロトコル行(`[SWITCHMAN:LANG|POOLS|WATERMARK|TEAMS]`)は意図的に英語・バイト安定を保っています——ローカライズしないでください。
107
+ - `npm pack --dry-run` は監査済みの 50 ファイル / ~205 kB の形を維持する必要があります(`docs/` のスクリーンショットはパッケージに入りません)。
76
108
 
77
109
  ## License
78
110
 
package/README.ko.md CHANGED
@@ -8,22 +8,38 @@
8
8
 
9
9
  > 컨텍스트에 수도계량기를 달면, 작업이 스스로 레인을 찾습니다.
10
10
 
11
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH) 플러그인입니다. 설치하고 나면 기본 모델은 "모든 걸 자기가 처리"하던 방식을 접고 디스패처가 됩니다: 수위를 재고, 레인을 고르고, 작업을 나눠주고, 결과를 검수합니다. 하는 일은 네 가지입니다:
11
+ ## 왜 필요한가
12
12
 
13
- **1. 컨텍스트 수위 제어.** 라운드마다 세션 token 을 실시간 계측합니다. soft(기본값 50k)는 위임을 권고하고, hard(90k)는 라운드당 읽기 예산을 줄여 마무리로 유도하며, force(130k)는 세션을 자동 백업해 압축으로 넘깁니다. 세션을 하루 종일 돌려도 컨텍스트가 자기 히스토리에 익사하는 일은 없습니다. 위임된 각 서브에이전트는 독립 하드 한도를 가지며, 넘으면 HANDOFF 요약을 남기고 퇴장합니다.
13
+ DSH 로 작업을 하다 보면 시간이 지날 때 두 가지에 부딪힙니다:
14
14
 
15
- **2. 6 레인 디스패치.** economy / mechanical / main / hard / vision / review 여섯 개의 인지 레인: 설정 페이지에서 후보 모델을 고르고, 최강 우선으로 정렬하며(S/A/B/C 티어 앵커는 선택), 라우트마다 사고 강도를 고정할 수 있습니다 — 드롭다운 레벨 목록은 각 모델이 *실제로* 지원하는 것에서 직접 나오는 것이지 일반적인 세 단계가 아닙니다. `[SWITCHMAN:POOLS]` 추천 표가 프롬프트마다 기본 모델에 전달되어 모델이 이를 보고 일을 배정합니다. `enforce` 모드에서는 풀 밖 모델을 즉시 거부합니다.
15
+ 1. **세션이 갈수록 무거워집니다.** 히스토리가 컨텍스트를 수십만 token 까지 부풀리면, 모델은 건망증이 심해지고 느려지고 비용이 올라갑니다. 결국 수동 /compact 에 기댈 수밖에 없는데, 압축할 때마다 세부 사항이 떨어져 나갑니다.
16
+ 2. **주력 모델이 모든 걸 스스로 처리합니다.** 파일 하나 조회하고, 테스트를 돌리고, 데이터를 대조하는 것까지 전부 주력 모델이 씹어 먹습니다 — 느린 데다 비용도 많이 드는데, 그 대부분은 사실 저렴한 모델에 맡겨야 할 작업입니다.
16
17
 
17
- **3. 언어 기본 설정.** 답변·코드 주석·문서 세 종류에 각각 드롭다운 하나. 미설정이면 첫 사용 때 한 번 물어보고 영구 기억하며, 이후 모든 세션이 자동으로 따릅니다.
18
+ dsh-switchman 은 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH) 플러그인입니다. 설치하고 나면 기본 모델은 "모든 걸 자기가 처리"하던 방식에서 디스패처로 바뀝니다: 수위를 재고, 레인을 고르고, 작업을 나눠주고, 검수를 확인합니다. 새로운 모델이 아니라 DSH 에 얹는 조율 규율 한 세트와 설정 화면 하나입니다. 구체적으로는 여섯 가지를 합니다:
18
19
 
19
- **4. 기본 위임 교리.** DSH 출하 시 탑재된 보수적 팀 정책("요청받을 때만 팀원 생성")을 대체합니다: 자잘한 일은 직접 손을 쓰고(읽기 <200줄, 변경 <50줄), 큰 작업은 기본적으로 위임합니다. 변경은 반드시 검증합니다 — 20줄 초과는 tester 에게, 300줄 초과 또는 핵심 로직을 건드린 변경은 reviewer 에게. "팀 쓰지 마"라고 한마디만 하면 즉시 물러납니다.
20
+ **1. 컨텍스트 수위: 긴 세션이 넘치지 않습니다.** 라운드마다 세션의 token 을 실시간으로 집계하고, 세 개의 수위선으로 단계적으로 강도를 높입니다: 50k(soft, 조정 가능)는 "이제 위임할 때"라고 알리고, 90k(hard)는 1회 파일 읽기 예산을 줄이며 마무리로 유도하고, 130k(force)는 자동 인계 — 세션을 fork 해 기록을 남기고, 컨텍스트를 압축하고, 이어받을 세션을 깨웁니다. 작업은 끊기지 않습니다. 인계 순간에 아직 실행 중이던 백그라운드 서브에이전트도 사라지지 않습니다: id, 작업 설명, 리포트 경로가 모두 인계 문서에 기록되어, 이어받은 세션은 리포트를 어디서 회수할지 알며 같은 일을 이중으로 시키지 않습니다. 나간 각 서브에이전트에는 독립 하드 한도가 붙고, 한도에 도달하면 HANDOFF 요약을 남기고 퇴장합니다.
20
21
 
21
- 모델이 하나뿐인가요? 그래도 가치가 있습니다 — 수위 제어와 교리는 모델 개수를 전혀 신경 쓰지 않습니다.
22
+ **2. 여섯 개 디스패치 풀: 일에 맞는 모델을 붙입니다.** 경량 풀(economy, 소량 반복 작업), 기계 풀(mechanical, 템플릿형 재작성), 주력 풀(main, 일상 코딩), 고난도 풀(hard, 어려운 추론과 대규모 리팩터링), 멀티모달 풀(vision, 이미지 읽기), 리뷰 풀(review, 독립 검증). 설정 페이지에서 후보에 체크하고 우선순위를 정하며(S/A/B/C 티어 앵커는 선택), 라우트마다 사고 강도를 고정할 수 있습니다 — 강도 드롭다운은 각 모델이 실제 지원하는 레벨에서 직접 나오는 것이지 범용 3단계가 아닙니다. 기본 모델의 프롬프트에는 매 라운드 `[SWITCHMAN:POOLS]` 추천 표가 붙고, 모델은 그 표대로 일을 배분합니다. 실행 모드는 세 가지: 끄기 / 조언 / 강제(강제 = 풀 밖 모델은 즉시 거부).
23
+
24
+ **3. Agent Teams 모드: 단독 작업에서 팀 운영으로.** 기본값은 꺼짐이며, 설치 직후에는 가벼운 subagent 디스패치입니다. 설정 페이지에는 독립적인 스위치 두 개가 있습니다:
25
+
26
+ - **에이전트 팀 모드** — 켜면 팀 규율(기본 위임 + 단계별 검증 + 공유 작업 보드 규율)이 주입되고, DSH 의 Agent Teams 가 자동으로 활성화됩니다: 기본 모델은 상주 팀원을 데려오고(`spawn_teammate`), 공유 작업 보드에 일을 올리고(`team_task_*`), 팀원과 메시지를 주고받습니다(`send_message`). 팀을 꾸릴 타이밍에는 명확한 규율이 있습니다: 병렬로 돌릴 수 있는 독립 서브태스크, 양이 많고 자기완결적인 작업, 기본 컨텍스트 수위가 이미 높을 때, 역할 분리가 필요할 때. 일회성 단발 조사는 여전히 subagent 로 갑니다. DSH 출하 정책은 "사용자가 지명하지 않으면 팀을 만들지 않음"이지만, 여기서는 "필요하면 쓴다"로 뒤집습니다. 스위치를 다시 끄면 팀 조항은 흔적 없이 사라지고, 실행 중인 세션에서 팀 도구를 빼앗는 일도 없습니다.
27
+ - **서브에이전트 모델 허용 목록 동기화** — DSH 에는 "Agent 가 서브에이전트 모델 선택을 허용"하는 승인 목록이 있습니다: 풀에서 골랐지만 승인되지 않은 라우트를 기본 모델이 지명 디스패치하면 거부됩니다(팀 모드에서는 추천 표와 설정 페이지가 이런 라우트에 ⚠ 를 표시). 이 스위치를 켜면 여섯 풀의 합집합이 통째로 그 목록에 기록됩니다 — 양쪽에 이중 설정할 필요가 없어지고, switchman 이 유일한 사실 원천이 되며, fork 디스패치 경로도 함께 편입됩니다. 허용 목록은 "새 세션" 시점의 스냅샷으로 적용되므로, 동기화는 그 이후에 열린 세션에만 반영됩니다.
28
+
29
+ 세션 헤더에는 직관적인 피드백이 있습니다: ⚡ "자율 팀" 배지, ◇ 현재 세션의 실제 모델. 자동 인계가 진행되는 동안에는 "인계 진행 중 · 세션 백업 / 컨텍스트 압축 / 깨워서 계속" 실시간 안내가 나타납니다.
30
+
31
+ **4. 언어 기본 설정: 한 번 물어보고, 평생 기억합니다.** 답변·코드 주석·문서 세 종류에 각각 드롭다운 하나, 범위는 전역 또는 프로젝트별(`.switchman/lang.json`)에서 고를 수 있습니다. 설정하지 않아도 됩니다 — 처음 필요해졌을 때 DSH 화면 언어로 한 번 물어보고 기억한 뒤, 이후 모든 세션이 자동으로 따릅니다.
32
+
33
+ **5. 단계별 검증: 고치면 반드시 확인합니다.** 20줄을 넘는 변경은 tester 검증으로 넘기고, 300줄을 넘거나 코어·보안·데이터 일관성 로직을 건드린 변경에는 reviewer 의 독립 리뷰를 한 겹 더 얹습니다. 리뷰 모델은 "이 diff 를 쓴 에이전트"가 쓰던 모델을 기준으로 골라 가급적 피합니다. 풀 안에서 어쩔 수 없이 피할 수 없을 때는 결론에 DOWNGRADED 로 선언합니다. "팀 쓰지 마" 한마디면 즉시 단독 작업으로 돌아갑니다.
34
+
35
+ **6. `/vision`: 텍스트 전용 모델도 이미지를 다룹니다.** 주력 모델이 이미지를 읽지 못하면 DSH 는 입구에서 이미지가 붙은 메시지를 바로 거부합니다. 이미지를 붙이고 `/vision 이 이미지 어디가 잘못됐나요` 를 입력하면, 이미지는 파일 경로로 해석되어 멀티모달 풀의 모델이 읽고 결론이 현재 세션으로 돌아옵니다. 입력창 위에는 "현재 모델은 이미지를 읽을 수 없습니다" 안내가 미리 뜹니다. 이미지를 바로 보냈다가 거부되면 `/vision` 형태로 자동으로 고쳐 한 번만 재전송하므로 다시 타이핑할 필요가 없습니다. 멀티모달 풀이 설정되지 않으면 명령은 거부하며 설정 안내를 보여줍니다.
36
+
37
+ 모델이 하나뿐인가요? 그래도 설치할 가치가 있습니다 — 수위 제어와 단계별 검증은 모델 개수와 무관하므로, 단일 모델의 긴 세션도 똑같이 이득을 봅니다.
22
38
 
23
39
  ## 번들 스킬
24
40
 
25
- - **db-query** — MySQL / Redis 읽기 전용 검증: SQL을 돌려 레코드 대조, 캐시 키 / TTL 확인, 스토어 간 일관성 검사를 하고 쓰기는 일절 거부합니다. 최초 사용 시 초기화 필요(아래 참조).
26
- - **git-commit-message** — 규범에 맞는 commit 문구 생성. 텍스트만 내보내고 git 은 절대 건드리지 않습니다.
41
+ - **db-query** — MySQL / Redis 읽기 전용 검증: SQL을 돌려 레코드를 대조하고, 캐시 키 / TTL 을 확인하며, 스토어 간 일관성을 검사합니다. 쓰기는 일절 거부합니다. 최초 사용 시 초기화가 필요합니다(아래 참조).
42
+ - **git-commit-message** — 규범에 맞는 commit 문구를 생성합니다. 텍스트만 내보내고 git 작업은 절대 대신하지 않습니다.
27
43
  - **requirement-docs** — 요구사항 분석 / PRD / 설계 문서의 통일 규범. 산출물은 `docs/requirements-and-design/` 에 아카이브합니다.
28
44
 
29
45
  ## 빠른 시작
@@ -34,29 +50,44 @@
34
50
  plugin_manager: install_bundle target=dsh-switchman
35
51
  ```
36
52
 
37
- 또는 로컬 체크아웃에서(link 방식. 업데이트 반영 후 `remove_bundle` + `install_bundle` 재설치):
53
+ 또는 로컬 체크아웃에서(link 방식. 업데이트 반영 후 `remove_bundle` + `install_bundle` 로 재설치):
38
54
 
39
55
  ```
40
56
  plugin_manager: install_bundle target=/path/to/dsh-switchman
41
57
  ```
42
58
 
59
+ 또는 터미널에서 `dsh` 명령으로 설치 — 실행 방식에 맞는 프로파일을 고르세요:
60
+
61
+ ```bash
62
+ dsh plugin --profile web add dsh-switchman # Web GUI
63
+ dsh plugin --profile desktop add dsh-switchman # 데스크톱 앱
64
+ ```
65
+
43
66
  2. **DSH 재시작** — 앱을 완전히 종료한 뒤 다시 엽니다(페이지 새로고침으로는 부족). 클라이언트 모듈 테이블이 이 bundle 을 인식하게 됩니다.
44
67
 
45
- 3. **설정 페이지 열기** — 설정 → dsh-switchman. 첫 화면은 언어 기본 설정입니다: 답변 / 주석 / 문서에 대응하는 드롭다운 3개가 있고 각 항목 아래에 "현재: …" 상태 줄이 붙습니다. 설정하지 않아도 괜찮습니다 — 첫 사용 때 한 번 물어보고 기억합니다.
68
+ 3. **언어 기본 설정** — 설정 → dsh-switchman, 또는 홈 사이드바의 "Switchman 디스패치 센터". 첫 화면에서 범위를 고릅니다: 전역(이 profile) 또는 프로젝트별(각 프로젝트의 `.switchman/lang.json`). 그다음 드롭다운 세 개로 답변 / 주석 / 문서의 언어를 각각 정합니다. 각 항목 아래에는 "현재: …" 상태 줄이 붙습니다. 건너뛰어도 괜찮습니다 — 처음 사용할 때 한 번 물어보고 기억합니다(질문 언어는 DSH UI 언어를 따릅니다).
69
+
70
+ ![언어 기본 설정: 범위와 세 가지 언어](docs/assets/conf-language-en.png)
71
+
72
+ 4. **디스패치 풀 구성** — 각 풀 카드에서 공급자별로 묶인 후보 모델에 체크합니다. "수동 순서"에 체크하면 카드가 번호식 우선순위 목록으로 바뀌고, ↑ ↓ × 로 순서를 조정합니다. 라우트마다 사고 강도를 고정할 수도 있습니다(기본값은 "레인 따르기". 고정하면 해당 모델이 실제 지원하는 레벨이 선택지로 나옵니다). 상단 요약 줄은 진행 상황을 실시간으로 반영합니다. 예: "풀 구성 6/6 · 랭킹 2개 · 모드 조언".
73
+
74
+ ![디스패치 풀: 경량 / 기계 / 주력 / 고난도 4개 풀](docs/assets/conf-pool-1-en.png)
75
+
76
+ 멀티모달 풀과 리뷰 풀은 그 아래에 있습니다. 더 아래로는 **능력 랭킹**(여섯 풀에서 선택한 모델의 합집합. 번호가 곧 능력 순서, 최강이 먼저, S/A/B/C 티어 앵커 가능)과 **실행 모드**(조언 / 강제)가 있습니다.
46
77
 
47
- ![설정 페이지와 언어 기본 설정](docs/assets/conf-demo1.png)
78
+ ![멀티모달 풀·리뷰 풀과 능력 랭킹·실행 모드](docs/assets/conf-pool-2-en.png)
48
79
 
49
- 4. **여섯 개 풀 채우기** — 각 풀 카드는 공급자별로 묶인 후보 모델을 보여줍니다. 원하는 것에 체크하세요. **수동 순서**에 체크하면 카드가 ↑ ↓ × 컨트롤이 달린 번호식 우선순위 목록으로 바뀝니다. 선택한 각 라우트 옆의 사고 강도 드롭다운 기본값은 "레인 따르기"이며, 고정하면 해당 모델이 실제 지원하는 레벨(Low / High / Max…)을 고를 수 있습니다. 요약 줄이 진행 상황을 실시간으로 반영합니다: "풀 설정 6/6 · 랭킹 3개 · 모드 조언".
80
+ 5. **에이전트 팀** — 두 스위치 모두 기본값은 꺼짐. 먼저 순수 subagent 모드로 돌려 보세요. 스스로 팀을 꾸리게 하려면 "에이전트 팀 모드"를, 양쪽 이중 승인을 없애려면 "서브에이전트 모델 허용 목록 동기화"를 켭니다 — 스위치 아래에 "N개 동기화됨 + 동기화 시각" 상태 줄이 나타나 기록 결과를 확인할 수 있습니다.
50
81
 
51
- ![디스패치 풀 설정](docs/assets/conf-demo2.png)
82
+ ![에이전트 팀: 두 스위치와 허용 목록 동기화 상태](docs/assets/conf-team-en.png)
52
83
 
53
- 5. **능력 랭킹과 수위** — 랭킹 표 번호는 곧 능력 순(최강이 먼저)이며 S/A/B/C 티어를 앵커할 수 있습니다. 실행 모드는 세 가지: `off` / 조언 / enforce(enforce = 풀 밖 모델 즉시 거부). 아래 수위 섹션은 token 사용량에 따라 단계적으로 동작을 조입니다: 세 단계 임계값, 1회당 읽기 예산, hard 모드 동작(제한 허용 / 차단), 자동 인계 토글, 서브에이전트 독립 한도. 맨 아래 한 줄 슬래시 명령: `/ctx-pause` 개입 일시 중지 · `/ctx-resume` 재개 · `/ctx-handover` 즉시 백업 후 인계.
84
+ 6. **컨텍스트 수위** — 3단계 임계값(기본값 50000 / 90000 / 130000), 1회 읽기 예산, hard 단계 동작(제한 허용 / 차단), 자동 인계 토글, 서브에이전트 독립 한도가 모두 이 영역에 있습니다. 맨 아래 한 줄의 명령: `/ctx-pause` 개입 일시 중지 · `/ctx-resume` 재개 · `/ctx-handover` 즉시 백업 후 인계(세션을 유휴 경계로 유도하고 컴팩션 재시도 창을 기다리므로 결과까지 몇 분 걸릴 수 있습니다).
54
85
 
55
- ![능력 랭킹과 컨텍스트 수위](docs/assets/conf-demo3.png)
86
+ ![컨텍스트 수위: 임계값·예산·명령](docs/assets/conf-ctx-en.png)
56
87
 
57
- 6. **검증** — 모든 세션 헤더의 프리셋 chip 옆에 ⚡ 배지가 나타납니다. 모델에게 "시스템 프롬프트 마지막 섹션에 뭐라고 쓰여 있나요?"라고 물어보세요. dsh-switchman 교리를 언급해야 합니다.
88
+ 7. **검증** — 세션 헤더에 ⚡ "자율 팀" 배지가 나타납니다(옆의 ◇ 에 현재 세션 모델이 표시됩니다). 또는 모델에게 직접 "시스템 프롬프트 마지막 섹션의 제목이 뭐예요?"라고 물어보세요. dsh-switchman 규율을 언급해야 합니다.
58
89
 
59
- **db-query 최초 사용 초기화**(스크립트 의존성은 스킬 디렉터리 안에 설치됩니다):
90
+ **db-query 최초 사용 초기화**(스크립트 의존성은 스킬 디렉터리 안에 설치되어 프로젝트를 오염시키지 않습니다):
60
91
 
61
92
  ```bash
62
93
  bash <install-dir>/skills/db-query/scripts/setup.sh
@@ -64,15 +95,16 @@ bash <install-dir>/skills/db-query/scripts/setup.sh
64
95
 
65
96
  ## 동작 방식
66
97
 
67
- - Host 쪽(`index.js` + `host/`)은 동적 시스템 프롬프트 섹션 3개, 읽기 예산과 enforce 이중 게이트, 답변 자동 캡처, 슬래시 명령 3개를 주입합니다. 모든 설정은 volatile 필드라서 저장 후 다음 프롬프트 조립부터 적용되며 재시작이 필요 없습니다.
68
- - Client 쪽(`client.js`)은 프리셋 chip 옆의 ⚡ 배지와 설정 페이지를 렌더링합니다. 공식 settings-form 서비스를 통해 이루어집니다.
69
- - `cordis.patch.yml` 은 출하 시 기본 프리셋의 플러그인 목록을 필드 단위로 그대로 복제하고 persona suffix 만 확장합니다. Agent Teams 도구 본체는 여전히 기본 탑재 `@deepseek-ai/dsh-experimental-agent-team-profile` 에서 옵니다.
98
+ - Host 쪽(`index.js` + `host/`)은 동적 시스템 프롬프트 섹션(언어 / 레인 / 수위 / 팀), 읽기 예산과 enforce 이중 게이트, 4개의 슬래시 명령(ctx 3개 + `/vision`)을 주입합니다. 설정은 모두 저장 후 다음 프롬프트 조립부터 적용되며 재시작이 필요 없습니다.
99
+ - Client 쪽(`client.js`)은 설정 페이지, 세션 헤더의 ⚡ 배지와 ◇ 모델 표시, 인계 진행 중 동적 안내를 렌더링합니다. 공식 settings-form 서비스를 통해 이루어집니다.
100
+ - 홈 사이드바의 "Switchman 디스패치 센터" 항목은 클릭 한 번으로 같은 설정 페이지(언어 기본 설정, 디스패치 풀과 랭킹, 수위)를 중앙 패널로 엽니다. 기존 설정 입구도 그대로 유지됩니다.
101
+ - `cordis.patch.yml` 은 출하 시 기본 프리셋의 플러그인 목록을 그대로 유지하고 persona suffix 만 확장합니다. Agent Teams 도구 본체는 출하 bundle 에서 오며, 팀 모드를 켜면 자동으로 활성화됩니다.
70
102
 
71
103
  ## 유지 보수
72
104
 
73
105
  - DSH 업그레이드 후 출하 시 기본 프리셋 플러그인 목록이 바뀌었다면, 새 `presets/*.patch.yml` 에서 `cordis.patch.yml` 을 다시 동기화하고(doctrine suffix 유지), 재설치합니다.
74
- - 프로토콜 줄(`[SWITCHMAN:LANG|POOLS|WATERMARK]`)은 의도적으로 영어·바이트 안정을 유지합니다 — 현지화하지 마십시오.
75
- - `npm pack --dry-run` 은 감사된 34 파일 / ~111 kB 형태를 유지해야 합니다(`docs/` 스크린샷은 패키지에 포함되지 않습니다).
106
+ - 프로토콜 줄(`[SWITCHMAN:LANG|POOLS|WATERMARK|TEAMS]`)은 의도적으로 영어·바이트 안정을 유지합니다 — 현지화하지 마십시오.
107
+ - `npm pack --dry-run` 은 감사된 43개 파일 / ~205 kB 형태를 유지해야 합니다(`docs/` 스크린샷은 패키지에 포함되지 않습니다).
76
108
 
77
109
  ## License
78
110