dsh-matriarc 0.0.0-stage → 0.1.1

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 simveit
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.de.md ADDED
@@ -0,0 +1,180 @@
1
+ <p align="center">
2
+ <img src="docs/assets/mascot.svg" width="480" alt="Maskottchen von Matriarc: ein Chibi-Anime-Mädchen mit Haaren in einem Verlauf von Indigo zu Aquamarin und einer türkisfarbenen Schleife reitet winkend auf einem Orca in den Sonnenuntergang, gefolgt von ihren Walen">
3
+ </p>
4
+
5
+ <p align="center"><a href="README.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | Deutsch</p>
6
+
7
+ # Matriarc
8
+
9
+ Matriarc (Paket `dsh-matriarc`) ist ein Plugin für DeepSeek Harness (dsh). Es trennt das Gehirn von den Händen. Der Name kommt von der Matriarchin, dem ältesten Orca, die ihre Gruppe führt: Sie kennt den Weg, und die Gruppe jagt. Wenn Sie es in einer Sitzung einschalten, erhält die Sitzung ein Werkzeug, `matriarc`, und ein paar kurze Regeln. Vor jeder Aufgabe ruft die Sitzung das Werkzeug auf. Ein zweites Modell, das Gehirn, zerlegt dann Ihre Anfrage in Teilaufgaben. Die Sitzung erledigt die Arbeit danach selbst oder gibt sie so weiter, wie sie es sonst auch tut. Ist die Arbeit fertig, ruft die Sitzung das Werkzeug erneut auf. Das Gehirn prüft die Änderungen dann gegen Ihre Anfrage und seinen eigenen Plan: Es gibt sie frei, verlangt Nachbesserungen oder nennt, was nur Sie entscheiden können. Das Gehirn ist ein anderer Coding-Agent, ausgeführt von einem Subagent-Plugin, das DeepSeek Harness auf seiner Plugins-Seite anbietet. Es plant und prüft, erledigt die Arbeit aber nie selbst: der Navigator wie beim Pair Programming, während die Sitzung fährt.
10
+
11
+ **Installation:** Öffnen Sie in DeepSeek Harness „Plugins“ > „Plugin hinzufügen“, geben Sie `dsh-matriarc` ein und klicken Sie auf „Installieren“. Einzelheiten unter [Installation](#installation).
12
+
13
+ ## Voraussetzungen
14
+
15
+ - DeepSeek Harness 0.2.2-rc.3 oder eine spätere 0.2.x-Version (`engines.dsh`).
16
+ - Ein Subagent-Plugin, das einen anderen Coding-Agenten ausführt (siehe die [Liste der Subagent-Anbieter](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/subagent/README.md) von DeepSeek Harness), eingeschaltet und angemeldet. Sie installieren es auf der Seite „Plugins“ von DeepSeek Harness. Für die beste Erfahrung geben Sie diesem Plugin seinen automatischen Berechtigungsmodus, damit der Navigator im Web lesen und lesende Befehle ausführen kann. Bitten Sie einen Coding-Agenten:
17
+
18
+ > Setze in `~/.dsh/profiles/desktop/cordis.patch.yml` `config.permissionMode` meines aktiven Subagent-Plugins auf seinen automatischen Modus, keinen Bypass-Modus (siehe die README des Plugins). Fehlt der Eintrag, lege ihn mit `id` und `name` des Plugins an. Sichere die Datei und halte das YAML gültig.
19
+
20
+ Starten Sie DeepSeek Harness danach neu. Für `dsh web` liegt die Datei unter `profiles/web/`.
21
+ - Git im Ordner der Sitzung, für den Zustand des Repositorys. Ohne Git teilt das Plugin dies dem Gehirn mit und arbeitet weiter.
22
+ - Das Paket enthält fertig gebauten Code und hat keine Laufzeitabhängigkeiten. `@deepseek-ai/cordis` und `@deepseek-ai/dsh-typert-protocol` sind Peer-Abhängigkeiten, die das laufende dsh bereitstellt. Die Peer-Warnung von pnpm bei der Installation ist zu erwarten.
23
+
24
+ ## Installation
25
+
26
+ Matriarc ist auf npm als `dsh-matriarc` veröffentlicht. Keiner der folgenden Wege baut etwas auf Ihrem Rechner. Das Paket enthält den gebauten Code.
27
+
28
+ **In der App.** Öffnen Sie „Plugins“, wählen Sie „Plugin hinzufügen“, geben Sie `dsh-matriarc` in „Name oder Adresse des Pakets“ ein und klicken Sie auf „Installieren“. Das Auswahlfeld „Registrierung“ kann auf der offiziellen npm-Registry bleiben. Ist die Installation abgeschlossen, wählen Sie „Jetzt aktivieren“. Fordert der Dialog Sie auf, DSH neu zu starten, beenden Sie die App und starten Sie sie erneut.
29
+
30
+ **Über die Kommandozeile.** Beenden Sie zuerst die App, wenn Sie in das Desktop-Profil installieren, und starten Sie sie danach wieder. Das Desktop-Profil muss bereits existieren. Öffnen Sie die Desktop-App deshalb vor der ersten Installation einmal. Für `dsh web` verwenden Sie `--profile web` und starten `dsh web` neu.
31
+
32
+ ```sh
33
+ dsh plugin --profile desktop add dsh-matriarc
34
+ ```
35
+
36
+ **Der neueste Code von GitHub.** Um den aktuellen Stand des Repositorys statt des veröffentlichten Pakets zu installieren, verwenden Sie an beiden Stellen `github:simveit/dsh-matriarc`. Dafür wird Git benötigt:
37
+
38
+ ```sh
39
+ dsh plugin --profile desktop add github:simveit/dsh-matriarc
40
+ ```
41
+
42
+ Mehr ist für die Installation nicht nötig. Das Plugin fügt keine Agentenvorlage hinzu und ändert keine Einstellung des Subagent-Plugins.
43
+
44
+ Um eine neuere Version zu installieren, entfernen Sie das Plugin (siehe [Deinstallation](#deinstallation)) und fügen Sie die neuere Version hinzu. Sitzungen behalten ihren Schalter und ihren gespeicherten Plan, denn beides steht im eigenen Protokoll der Sitzung.
45
+
46
+ ## Schnellstart
47
+
48
+ 1. Stellen Sie sicher, dass unter „Plugins“ ein Subagent-Plugin eingeschaltet ist, das einen anderen Coding-Agenten ausführt (siehe [Voraussetzungen](#voraussetzungen)). Für die besten Ergebnisse nutzen Sie dessen automatischen Berechtigungsmodus.
49
+ 2. Öffnen Sie eine Sitzung in einem Git-Repository. Schalten Sie im Modellmenü unter dem Eingabefeld „Matriarc aktivieren“ ein. Sie können auch `/matriarc on` eingeben.
50
+ 3. Beschreiben Sie die Arbeit wie gewohnt. Bei jeder Nachricht außer einer reinen Frage, auch bei Folgenachrichten, ruft die Sitzung zuerst `matriarc` mit der Stufe `plan` auf. Die Werkzeugkarte bleibt offen, solange das Gehirn arbeitet. Das dauert einige Minuten.
51
+ 4. Die Sitzung erledigt die Teilaufgaben, bei eingeschalteter Agenten-Teamarbeit verteilt auf das Team, und führt den Prüfschritt jeder Teilaufgabe aus.
52
+ 5. Hat die Arbeit Dateien geändert, ruft die Sitzung vor ihrer abschließenden Antwort `matriarc` mit der Stufe `review` auf. Bei einer Nachbesserung erledigt sie die aufgeführten Teilaufgaben und bittet um eine weitere Prüfung. Bei einer Blockade fragt sie Sie. Ihre abschließende Antwort nennt das Urteil.
53
+
54
+ Ausschalten können Sie es über dieselbe Menüzeile oder mit `/matriarc off`. `/matriarc` ohne Argument zeigt, ob es eingeschaltet ist.
55
+
56
+ **Für die besten Ergebnisse:**
57
+
58
+ - Nutzen Sie das Agent-Preset „Standardmodus“. Im „PTC-Modus“ ruft die Sitzung `matriarc` in einem Code-Lauf auf, den DeepSeek Harness nach 2 bis 10 Minuten abbricht, bevor der Navigator fertig ist. Der PTC-Modus ist vorerst nicht empfohlen; eine richtige Lösung ist geplant. Wenn Sie ihn brauchen, heben Sie die Obergrenze mit einem `ptc-runtime`-Eintrag in Ihrer Profilkonfiguration an (`name: '@deepseek-ai/dsh-ptc-runtime-node'`, `config: { maxTimeoutMs: 1800000 }`); ein Code-Lauf, der mehr Zeit anfordert, darf dann bis zu 30 Minuten dauern.
59
+ - Schalten Sie bei größeren Aufgaben „Agentenzusammenarbeit aktivieren“ im selben Menü wie Matriarc ein. Die Sitzung gibt dann Teilaufgaben, die gleichzeitig laufen können, an Teammitglieder.
60
+ - Der Navigator sieht Ihre Nachrichten und das Repository, nicht das Gespräch der Sitzung. Schreiben Sie Links, Fehlermeldungen und Vorgaben in Ihre Nachricht oder in eine Datei im Repository.
61
+ - Beschreiben Sie die ganze Aufgabe in einer Nachricht. Nachrichten nach dem Plan erreichen den nächsten Plan, nicht die Prüfung.
62
+ - Committen oder stashen Sie fremde Änderungen vorher, damit die Prüfung nur die Änderungen dieser Aufgabe sieht.
63
+ - Jede Aufgabe wartet ein paar Minuten auf einen Plan. Für eine schnelle einzeilige Änderung schalten Sie Matriarc aus.
64
+
65
+ ## So funktioniert es
66
+
67
+ **Der Schalter.** „Matriarc aktivieren“ gehört zu einer einzelnen Sitzung und ist anfangs aus. Die Zeile steht im Modellmenü neben „Agentenzusammenarbeit aktivieren“. Die beiden sind voneinander unabhängig. `/matriarc on` wird in einer Subagent-Sitzung abgelehnt. Ohne Anbieter zeigt die Zeile einen kurzen Hinweis und bietet die Subagent-Plugins an, die Sie einschalten können; jedes öffnet seine Seite unter „Plugins“. Ausschalten ist immer möglich. Nur Sie ändern den Schalter, denn das Modell der Sitzung kann keine Slash-Befehle ausführen. Eine abgezweigte Sitzung (Fork) beginnt mit ausgeschaltetem Schalter und ohne Plan.
68
+
69
+ **Wer das Werkzeug sieht.** Das Werkzeug und seine Regeln gibt es nur, solange der Schalter an ist, nur für den Hauptagenten der Sitzung und nur, solange ein Anbieter für das Gehirn registriert ist. Subagenten und Teammitglieder der Sitzung sehen sie nie.
70
+
71
+ **Der Plan.** Das Plugin sendet dem Gehirn seine Planungsanweisungen (`prompts/planner.md`), Ihre Anfrage und den Zustand des Repositorys. Ihre Anfrage besteht aus allen Nachrichten, die Sie seit dem letzten erfolgreichen Plan oder seit Beginn der Sitzung eingegeben haben, im Wortlaut und in ihrer Reihenfolge. So kommt eine kurze Rückmeldung wie „ja, mach weiter“ zusammen mit dem an, worauf sie antwortet. Bilder und Dateien werden durch eine Markierung ersetzt. Der Zustand des Repositorys umfasst den Branch, den aktuellen Commit und `git status`. Das Gehirn startet im Arbeitsordner der Sitzung und liest den Code selbst. Seine Antwort kommt mit der Überschrift „Plan (<provider>)“ zurück, in diesem Klartextformat:
72
+
73
+ ```
74
+ APPROACH
75
+ Two to five sentences: how the task will be solved and why this way.
76
+
77
+ SHARED
78
+ Facts every subtask needs: file paths, names, interfaces, conventions to keep.
79
+
80
+ S1 <short title>
81
+ goal: what this subtask achieves
82
+ details: what to change and how, concrete enough to start without further research
83
+ needs: subtasks that must be finished first, or "none"
84
+ touches: files or folders it writes
85
+ done when: a check that can be run or read, such as a test command or an observable behaviour
86
+
87
+ S2 ...
88
+
89
+ DONE WHEN
90
+ The checks that show the whole task is finished.
91
+
92
+ OPEN
93
+ Only what blocks the work and has no safe default, or "none".
94
+ ```
95
+
96
+ Das Gehirn bestimmt die Zahl der Teilaufgaben. Bei einer kleinen Aufgabe ist auch eine einzige Teilaufgabe ein gültiger Plan. Das Gehirn erfährt nicht, wie die Teilaufgaben ausgeführt werden. Die Sitzung kann jederzeit einen neuen Plan anfordern. Er ersetzt den vorherigen.
97
+
98
+ **Die Arbeit.** Was zwischen den beiden Aufrufen geschieht, ist Sache der Sitzung. Eine einfache Sitzung arbeitet die Teilaufgaben der Reihe nach ab. Ist die Agentenzusammenarbeit eingeschaltet, sagen die Regeln der Sitzung, jede Teilaufgabe, die neben einer anderen laufen kann, an ein neues `subagent`-Teammitglied zu geben, alle gleichzeitig und vor der eigenen Arbeit, und nur den Rest selbst zu erledigen. Sonst sagen sie „yourself or by whatever delegation this session uses“ (selbst oder über die Delegation, die diese Sitzung nutzt).
99
+
100
+ **Die Prüfung.** Das Plugin sendet dem Gehirn eine feste Anweisung, „Review the recent changes in this repository against the request and the plan below.“ (Prüfe die jüngsten Änderungen in diesem Repository gegen die Anfrage und den folgenden Plan). Darauf folgen die Prüfanweisungen (`prompts/reviewer.md`), die Anfrage, aus der der Plan entstand, der gespeicherte Plan im Wortlaut und die Änderungen seit dem Plan. Nachrichten, die Sie nach dem Plan schreiben, erreichen die Prüfung nicht. Die Änderungen sind `git status`, der auch neue Dateien auflistet, und der Diff. Neue Dateien liest das Gehirn selbst. Sie umfassen das Repository, in dem der Plan erstellt wurde, und zusätzlich das Repository des Arbeitsordners, falls das ein anderes ist. Mit dem Argument `folders` des Aufrufs kann die Sitzung bis zu acht weitere Repositorys innerhalb ihres Arbeitsordners hinzufügen. Die gesamte Eingabe für die Prüfung bleibt unter 200.000 Zeichen. Gekürzte Stellen werden markiert, und das Gehirn liest sie von der Festplatte. Das Gehirn prüft, indem es den Diff und die Dateien liest. Es verlässt sich nicht darauf, Befehle auszuführen, und sein Urteil hängt nicht davon ab. Es schließt mit CHECKS FOR THE SESSION, den Befehlen, die die Sitzung vor ihrer abschließenden Antwort ausführen muss. Die erste Zeile seiner Antwort ist das Urteil:
101
+
102
+ | Urteil | Bedeutung | Was die Sitzung tut |
103
+ |---|---|---|
104
+ | `VERDICT: PASS` | Jedes Abschlusskriterium ist erfüllt, soweit das Lesen zeigt | Führt die Prüfschritte für die Sitzung aus und gibt dann die abschließende Antwort mit Urteil und Ergebnissen |
105
+ | `VERDICT: ADJUST` | Ein Fehler in der Korrektheit oder eine übersehene Anforderung | Führt die aufgeführten Änderungen im Format des Plans aus, führt die Prüfschritte für die Sitzung aus und bittet dann um eine weitere Prüfung |
106
+ | `VERDICT: BLOCKED` | Etwas, das nur Sie entscheiden können | Hält an und fragt Sie |
107
+
108
+ Die Zahl der Prüfrunden ist nicht begrenzt. Jedes Ergebnis trägt die Überschrift „Review N (<provider>)“. N beginnt bei einem neuen Plan wieder von vorn, so sehen Sie, wie oft die Prüfung lief. Ein fehlgeschlagener, gestoppter oder abgelaufener Lauf zählt nicht als Runde.
109
+
110
+ **Ein Lauf nach dem anderen.** Eine Sitzung führt immer nur einen Aufruf des Gehirns zur selben Zeit aus, und jeder Aufruf ist auf 30 Minuten begrenzt. Kann das Gehirn nicht laufen (die Zeit ist abgelaufen, die Höchstzahl aktiver Subagenten in DSH ist erreicht oder es ist kein Anbieter mehr registriert), liefert das Werkzeug ein normales Ergebnis. Es weist die Sitzung an, allein weiterzuarbeiten und Ihnen bei einer Prüfung mitzuteilen, dass die Arbeit nicht geprüft wurde. Kann Git nicht laufen, erfährt das Gehirn dies, und der Aufruf geht weiter. „Generierung stoppen“ beendet den Aufruf sofort. Endet ein Lauf des Gehirns mit einem Fehler, ist das Ergebnis ein Fehler mit der Meldung des Anbieters.
111
+
112
+ **Was erhalten bleibt.** Der Schalter und der letzte Plan mit seiner Zahl der Prüfungen und seinem letzten Urteil werden aus dem eigenen Protokoll der Sitzung wiederhergestellt. Sie überstehen das Kompaktieren des Verlaufs, einen Neustart der App und ein Update des Plugins.
113
+
114
+ ## Konfiguration
115
+
116
+ Version 0.1.1 hat keine Einstellungen. Das Plugin hat auf der Seite „Plugins“ keine eigene Zeile zum Konfigurieren. Was das Gehirn darf (sein Modell, sein Berechtigungsmodus, seine Sandbox), legen Sie im Subagent-Plugin und in den Einstellungen des jeweiligen Agenten fest. Matriarc ändert daran nichts. Empfohlen ist der automatische Modus (siehe [Voraussetzungen](#voraussetzungen)).
117
+
118
+ Matriarc verwendet ein Subagent-Plugin, das einen anderen Agenten außerhalb von DSH ausführt. Sind mehrere aktiviert, zeigt die Zeile „Navigator wählen“ mit einem Eintrag je Plugin; Sie können auch `/matriarc on <Navigator>` eingeben. Die Wahl gehört zur Sitzung. Ohne Wahl, oder solange das gewählte Plugin aus ist, verwendet Matriarc das erste in der Reihenfolge, in der DSH sie registriert hat, und die Zeile sagt das. `/matriarc` ohne Argument nennt das verwendete. Einen von Hand in einem Profil eingerichteten ACP-Subagent-Anbieter kann Matriarc nicht von einem Coding-Agenten unterscheiden und verwendet ihn möglicherweise.
119
+
120
+ ## Authentifizierung
121
+
122
+ Matriarc startet den anderen Coding-Agenten nie selbst und rührt dessen Anmeldung nie an. Es bittet nur den Subagent-Dienst von DSH, den Anbieter auszuführen, den DSH registriert hat. Die Anbieter-Plugins von DeepSeek führen die offiziellen Laufzeitumgebungen in eigenen, fest vorgegebenen Versionen aus. Die Authentifizierung gehört zum jeweiligen Anbieter und wird nach dessen eigenen Bedingungen in diesem Plugin eingerichtet.
123
+
124
+ ## Sicherheit
125
+
126
+ Die Sitzung kann nichts schreiben, was das Gehirn liest. Das Werkzeug hat kein Freitext-Argument. Die Eingabe des Gehirns besteht aus Ihren Nachrichten, der Ausgabe von Git, den festen Anweisungen des Plugins und für die Prüfung dem eigenen Plan des Gehirns. Die Ordner, die die Sitzung für eine Prüfung nennt, müssen in ihrem Arbeitsordner liegen, und ihre Namen werden nie in die Eingabe geschrieben. Die geprüften Änderungen sind natürlich die Arbeit der Sitzung, und das Gehirn liest sie auch als solche.
127
+
128
+ Das Plugin führt Git außerhalb der Sandbox der Sitzung aus und härtet Git deshalb ab: Repository-Hooks, Dateisystem-Monitore, Textkonvertierung, externe Diff-Programme, Filter und Netzwerk-Transporte (die das verzögerte Nachladen eines Partial Clone nutzen würde) sind abgeschaltet. Das sind die Wege, auf denen Git beim Lesen Programme aus der Konfiguration eines Repositorys startet, und die Tests des Plugins prüfen jeden davon.
129
+
130
+ Die Antwort des Gehirns ist ein Rat. Sie kommt als Ergebnis des Werkzeugs zurück, und die Sitzung handelt danach mit ihren eigenen Werkzeugen und unter ihren eigenen Freigaben. Das Gehirn läuft mit den Berechtigungen, die sein Anbieter ihm gibt. Das Plugin bittet es, keine Dateien zu ändern, kann das aber nicht erzwingen. In einem Modus, der alle Berechtigungsprüfungen überspringt, könnte es Dateien ändern. Ihre Nachrichten, der Status, die Diffs und alle Dateien, die das Gehirn liest, gehen an einen zweiten Anbieter. Das gilt auch für jedes Geheimnis, das Sie in den Chat eingefügt oder in eine Datei geschrieben haben, die Git nicht ignoriert. Jedes externe Subagent-Plugin, das Sie aktiviert haben, kann zum Navigator werden und erhält Ihre Nachrichten, den Status und die Diffs. Aktivieren Sie deshalb nur Anbieter, an die Sie das senden möchten; `/matriarc` zeigt, welcher verwendet wird. Und die Prüfung kann sich irren, in beide Richtungen: Eine Freigabe ist eine zweite Meinung, kein Beweis.
131
+
132
+ [docs/security.md](docs/security.md) beschreibt das Bedrohungsmodell, was der Code erzwingt und was auf Regeln beruht, sowie die bekannten Grenzen. Wie Sie eine Schwachstelle melden, steht in [SECURITY.md](SECURITY.md).
133
+
134
+ ## Deinstallation
135
+
136
+ Öffnen Sie in der App „Plugins“ und wählen Sie bei Matriarc „Deinstallieren“. Über die Kommandozeile:
137
+
138
+ ```sh
139
+ dsh plugin --profile desktop remove dsh-matriarc # or: --profile web
140
+ ```
141
+
142
+ Das Werkzeug, die Regeln und die Menüzeile verschwinden aus allen Sitzungen. Frühere Werkzeugkarten bleiben unverändert im Verlauf der Sitzungen. Das Plugin legt keine eigenen Dateien an, darum muss nichts weiter entfernt werden.
143
+
144
+ ## Entwicklung
145
+
146
+ Der Build verwendet Node und pnpm aus der App, es wird also nichts global installiert:
147
+
148
+ ```sh
149
+ R="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/primary-runtime/dependencies"
150
+ export PATH="$R/node/bin:$PATH"
151
+ pnpm() { node "$R/pnpm/bin/pnpm.cjs" "$@"; }
152
+ pnpm install
153
+ pnpm run build # tsc for the host (lib/), tsdown for the client (lib/client.js)
154
+ pnpm run typecheck # host, client, and host with tests
155
+ pnpm test
156
+ pnpm check # typecheck, tests, build and a pack dry run
157
+ pnpm pack # runs the build, writes dsh-matriarc-<version>.tgz
158
+ ```
159
+
160
+ Node 24 mit pnpm 11 aus einer anderen Quelle (Linux, CI) funktioniert mit derselben Lockfile.
161
+
162
+ `lib/` wird als Release-Build eingecheckt, damit eine Installation über `github:` keinen Build-Schritt braucht. Bauen Sie es mit `pnpm run build` neu und checken Sie es zusammen mit jeder Änderung an `src/` ein. Die CI prüft, ob das eingecheckte `lib/` einem frischen Build entspricht.
163
+
164
+ Um Ihren eigenen Build in der App auszuprobieren, installieren Sie die gepackte Datei (beenden Sie für das Desktop-Profil zuerst die App):
165
+
166
+ ```sh
167
+ dsh plugin --profile desktop add ./dsh-matriarc-<version>.tgz # or: --profile web
168
+ ```
169
+
170
+ tsdown läuft auf der WebAssembly-Anbindung von rolldown, weil das Node der App native Erweiterungen anderer Hersteller ablehnt. Eine Änderung am Client erfordert einen neuen Build und ein Neuladen der Seite. Eine Änderung am Host erfordert einen Neustart.
171
+
172
+ ## Feedback und Mitwirkung
173
+
174
+ Fehlerberichte, Fragen und Ideen sind als [GitHub-Issues](https://github.com/simveit/dsh-matriarc/issues) sehr willkommen. Pull Requests nehmen wir vorerst nicht an. Dies ist ein Nebenprojekt, der Maintainer möchte das Design fokussiert halten und hat keine Kapazität, Beiträge zu prüfen. Bitte eröffnen Sie stattdessen ein Issue. Was ein Issue enthalten sollte, steht in [CONTRIBUTING.md](CONTRIBUTING.md). Sicherheitsprobleme melden Sie wie in [SECURITY.md](SECURITY.md) beschrieben.
175
+
176
+ ## Lizenz
177
+
178
+ MIT, siehe [LICENSE](LICENSE). Teile stammen aus DeepSeek Harness (MIT). Das Maskottchen ist ein eigenes Kunstwerk für dieses Projekt und steht unter derselben Lizenz.
179
+
180
+ Dies ist ein unabhängiges Plugin. Es wird nicht von DeepSeek erstellt oder unterstützt.
package/README.md CHANGED
@@ -1,3 +1,180 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <img src="docs/assets/mascot.svg" width="480" alt="Matriarc mascot: a chibi anime girl with indigo-to-aqua hair and a teal bow rides an orca into the sunset and waves, with her pod of whales following behind">
3
+ </p>
2
4
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
5
+ <p align="center">English | <a href="README.zh-CN.md">简体中文</a> | <a href="README.de.md">Deutsch</a></p>
6
+
7
+ # Matriarc
8
+
9
+ Matriarc (package `dsh-matriarc`) is a plugin for the DeepSeek Harness (dsh). It separates the brain from the hands. The name comes from the matriarch, the oldest orca, who leads her pod: she knows the way, and the pod does the hunting. When you switch it on in a session, the session gets one tool, `matriarc`, and a short set of rules. Before each task, the session calls the tool and a second model, the brain, breaks your request into subtasks. The session then does the work itself, or hands it on in whatever way it normally does. When the work is done, the session calls the tool again and the brain reviews the changes against your request and its own plan: it passes them, returns adjustments, or says what only you can decide. The brain is another coding agent, run by a subagent plugin that DeepSeek Harness offers on its Plugins page. It plans and reviews, and never does the work: the navigator, as in pair programming, while the session drives.
10
+
11
+ **Install:** in DeepSeek Harness open Plugins > Add plugin, enter `dsh-matriarc` and press Install. Details in [Install](#install).
12
+
13
+ ## Requirements
14
+
15
+ - DeepSeek Harness 0.2.2-rc.3 or a later 0.2.x release (`engines.dsh`).
16
+ - A subagent plugin that runs another coding agent (see DeepSeek Harness's [list of subagent providers](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/subagent/README.md)), switched on and signed in. Install it from DeepSeek Harness's Plugins page. For the best experience, give that plugin its automatic permission mode so the navigator can read the web and run read-only commands. Ask a coding agent:
17
+
18
+ > In `~/.dsh/profiles/desktop/cordis.patch.yml`, set `config.permissionMode` of my enabled subagent plugin to its automatic mode, not a bypass mode (see the plugin's README). Add the entry with the plugin's `id` and `name` if it is missing. Back up the file and keep the YAML valid.
19
+
20
+ Then restart DeepSeek Harness. For `dsh web`, the file is under `profiles/web/`.
21
+ - Git in the session's folder, for the repository state. Without Git the plugin says so to the brain and carries on.
22
+ - The package ships prebuilt code and has no runtime dependencies. `@deepseek-ai/cordis` and `@deepseek-ai/dsh-typert-protocol` are peers that the running dsh supplies; pnpm's peer warning during install is expected.
23
+
24
+ ## Install
25
+
26
+ Matriarc is published on npm as `dsh-matriarc`. None of the forms below builds anything on your machine; the package contains the built code.
27
+
28
+ **In the app.** Open Plugins, choose Add plugin, type `dsh-matriarc` into "Package name or address" and press Install. The Registry dropdown can stay at the official npm registry. When the install is done, choose Enable now. If the dialog says to restart DSH, quit the app and start it again.
29
+
30
+ **From the command line.** Quit the app first when installing into the desktop profile, and start it again afterwards. The desktop profile must exist, so open the desktop app once before the first install. For `dsh web`, use `--profile web` and restart `dsh web`.
31
+
32
+ ```sh
33
+ dsh plugin --profile desktop add dsh-matriarc
34
+ ```
35
+
36
+ **The latest code from GitHub.** To install the current state of the repository instead of the published package, use `github:simveit/dsh-matriarc` in either place. This needs Git:
37
+
38
+ ```sh
39
+ dsh plugin --profile desktop add github:simveit/dsh-matriarc
40
+ ```
41
+
42
+ That is the whole install. The plugin adds no agent preset and changes no setting of the subagent plugin.
43
+
44
+ To install a newer version, remove the plugin (see [Uninstall](#uninstall)) and add the newer version. Sessions keep their switch and their stored plan, because both are kept in the session's own log.
45
+
46
+ ## Quick start
47
+
48
+ 1. Make sure a subagent plugin that runs another coding agent is switched on under Plugins (see [Requirements](#requirements)). For the best results, use its automatic permission mode.
49
+ 2. Open a session in a Git repository. In the model menu under the message box, switch on "Enable Matriarc". You can also type `/matriarc on`.
50
+ 3. Describe the work as usual. For every message except a plain question, follow-ups included, the session first calls `matriarc` with stage `plan`. The tool card stays open while the brain works, which takes a few minutes.
51
+ 4. The session carries out the subtasks, spread across the team when agent teamwork is on, and runs each subtask's check.
52
+ 5. When the work changed files, the session calls `matriarc` with stage `review` before its final answer. On an adjustment it does the listed subtasks and asks for another review. On a block it asks you. Its final answer names the verdict.
53
+
54
+ Switch it off with the same menu row or `/matriarc off`. `/matriarc` without an argument shows whether it is on.
55
+
56
+ **For the best results:**
57
+
58
+ - Use the "Standard mode" agent preset. In "PTC mode" the session calls `matriarc` inside a code run, which DeepSeek Harness cuts off after 2 to 10 minutes, before the navigator is done. PTC mode is not recommended for now; a proper fix is planned. If you need it, raise the ceiling with a `ptc-runtime` entry in your profile configuration (`name: '@deepseek-ai/dsh-ptc-runtime-node'`, `config: { maxTimeoutMs: 1800000 }`); a code run that asks for more time can then last up to 30 minutes.
59
+ - For larger tasks, switch on "Enable agent teamwork" in the same menu as Matriarc. The session then hands subtasks that can run at the same time to teammates.
60
+ - The navigator sees your messages and the repository, not the session's conversation. Put links, error messages and constraints into your message or into a file in the repository.
61
+ - Describe the whole task in one message. Messages written after the plan reach the next plan, not the review.
62
+ - Commit or stash unrelated changes before you start, so the review sees only this task's changes.
63
+ - Every task waits a few minutes for a plan. For a quick one-line edit, switch Matriarc off.
64
+
65
+ ## How it works
66
+
67
+ **The switch.** "Enable Matriarc" belongs to one session and starts off. The row sits in the model menu next to "Enable agent teamwork", and the two are independent. `/matriarc on` is refused in a subagent session. Without a provider the row shows a short notice and offers the subagent plugins you could switch on, each opening its page on the Plugins page. Turning the switch off always works. Only you change the switch: the session model cannot run slash commands. A fork of a session starts with the switch off and no plan.
68
+
69
+ **Who sees the tool.** The tool and its rules are there only while the switch is on, only for the session's root agent, and only while a brain provider is registered. Subagents and teammates of the session never see them.
70
+
71
+ **The plan.** The plugin sends the brain its planning instructions (`prompts/planner.md`), your request and the repository state. Your request is every message you typed since the previous successful plan, or since the start of the session, word for word and in order, so a short follow-up such as "yes, go ahead" arrives together with what it answers. Images and files are replaced by a marker. The repository state is the branch, the current commit and `git status`. The brain starts in the session's working folder and reads the code itself. Its answer comes back headed "Plan (<provider>)", in this plain-text format:
72
+
73
+ ```
74
+ APPROACH
75
+ Two to five sentences: how the task will be solved and why this way.
76
+
77
+ SHARED
78
+ Facts every subtask needs: file paths, names, interfaces, conventions to keep.
79
+
80
+ S1 <short title>
81
+ goal: what this subtask achieves
82
+ details: what to change and how, concrete enough to start without further research
83
+ needs: subtasks that must be finished first, or "none"
84
+ touches: files or folders it writes
85
+ done when: a check that can be run or read, such as a test command or an observable behaviour
86
+
87
+ S2 ...
88
+
89
+ DONE WHEN
90
+ The checks that show the whole task is finished.
91
+
92
+ OPEN
93
+ Only what blocks the work and has no safe default, or "none".
94
+ ```
95
+
96
+ The brain picks the number of subtasks; one is a valid plan when the task is small. The brain is not told how the subtasks will be carried out. The session can ask for a new plan at any time; it replaces the previous one.
97
+
98
+ **The work.** What happens between the two calls is the session's business. A plain session works through the subtasks in order. While agent teamwork is on, the rules tell the session that every subtask that can run alongside another must go to a new `subagent` teammate, all started at once before the session's own work, and that it does only the rest itself. Otherwise they say "yourself or by whatever delegation this session uses".
99
+
100
+ **The review.** The plugin sends the brain a fixed instruction, "Review the recent changes in this repository against the request and the plan below.", followed by the reviewer instructions (`prompts/reviewer.md`), the request the plan was made from, the stored plan word for word, and the changes since the plan. Messages you write after the plan do not reach the reviewer. The changes are `git status`, which lists new files, and the diff; the brain reads new files itself. They cover the repository the plan was made in, and the repository of the working folder if that is another one. The session can add up to eight more repositories inside its working folder with the call's `folders` argument. The whole review prompt stays under 200,000 characters; anything cut is marked, and the brain reads it from disk. The brain reviews by reading the diff and the files. It does not count on running commands, and its verdict does not depend on them. It ends with CHECKS FOR THE SESSION, the commands the session must run before its final answer. The first line of its answer is the verdict:
101
+
102
+ | Verdict | Meaning | What the session does |
103
+ |---|---|---|
104
+ | `VERDICT: PASS` | Every done-criterion holds, as far as reading shows | Runs the checks for the session, then gives the final answer with the verdict and the check results |
105
+ | `VERDICT: ADJUST` | A defect in correctness or a missed requirement | Carries out the listed changes, in the plan's format, runs the checks for the session, then asks for another review |
106
+ | `VERDICT: BLOCKED` | Something only you can decide | Stops and asks you |
107
+
108
+ There is no limit on review rounds. Each result is headed "Review N (<provider>)", where N restarts with a new plan, so you see how often it ran. A failed, stopped or timed-out run does not count as a round.
109
+
110
+ **One run at a time.** A session runs one brain call at a time, and each call has a 30-minute limit. When the brain cannot run (it timed out, DSH's limit of active subagents is reached, or no provider is registered any more), the tool returns a normal result that tells the session to continue on its own and, for a review, to tell you that the work was not reviewed. When Git cannot run, the brain is told so and the call continues. Stop ends the call at once. A brain run that ends with an error gives an error result with the provider's message.
111
+
112
+ **What survives.** The switch and the last plan, with its review count and last verdict, are rebuilt from the session's own log. They survive compaction, a restart of the app and an update of the plugin.
113
+
114
+ ## Configuration
115
+
116
+ Version 0.1.1 has no settings. The plugin has no row of its own to configure on the Plugins page. What the brain may do (its model, its permission mode, its sandbox) is set in the subagent plugin and in that agent's own settings, and Matriarc changes none of it. The automatic mode is recommended (see [Requirements](#requirements)).
117
+
118
+ Matriarc uses a subagent plugin that runs another agent outside DSH. With more than one enabled, the row shows "Choose the navigator" with one entry per plugin; you can also type `/matriarc on <navigator>`. The choice belongs to the session. Without a choice, or while the chosen plugin is off, Matriarc uses the first one in the order DSH registered them, and the row says so. `/matriarc` without an argument names the one in use. An ACP subagent provider set up by hand in a profile cannot be told apart from a coding agent, so Matriarc may use it.
119
+
120
+ ## Authentication
121
+
122
+ Matriarc never starts the other coding agent itself and never touches its sign-in. It only asks DSH's subagent service to run the provider DSH has registered. DeepSeek's provider plugins run the official runtimes with their own pinned versions. Authentication is the provider's own and is set up in that plugin, under the provider's own terms.
123
+
124
+ ## Security
125
+
126
+ The session cannot write anything the brain reads. The tool has no free-text argument. The brain's input is your messages, Git output, the plugin's fixed instructions and, for the review, the brain's own plan. The folders the session names for a review must lie inside its working folder, and their names are never written into the prompt. The changes under review are of course the session's work, and the brain reads them as such.
127
+
128
+ The plugin runs Git outside the session's sandbox, so it runs Git hardened: repository hooks, filesystem monitors, text conversion, external diff programs, filters and network transports (which a partial clone's lazy fetch would use) are switched off. These are the ways Git runs programs from a repository's configuration while reading, and the plugin's tests check each of them.
129
+
130
+ The brain's answer is advice. It comes back as the tool's result, and the session acts on it with its own tools and under its own approvals. The brain runs with the permissions its provider gives it: the plugin asks it to change no files but cannot enforce that, and in a mode that skips all permission checks it could. Your messages, the status and the diffs, and whatever files the brain reads, go to a second vendor, including any secret you pasted into the chat or wrote into a file that Git does not ignore. Any external subagent plugin you have enabled can become the navigator and receives your messages, the status and the diffs, so enable only providers you are willing to send that to; `/matriarc` shows which one is used. And the reviewer can be wrong, in both directions: a pass is a second opinion, not a proof.
131
+
132
+ [docs/security.md](docs/security.md) has the threat model, what the code enforces and what rests on rules, and the known limits. To report a vulnerability, see [SECURITY.md](SECURITY.md).
133
+
134
+ ## Uninstall
135
+
136
+ In the app, open Plugins and choose Uninstall on Matriarc. From the command line:
137
+
138
+ ```sh
139
+ dsh plugin --profile desktop remove dsh-matriarc # or: --profile web
140
+ ```
141
+
142
+ The tool, the rules and the menu row disappear from every session. Earlier tool cards stay in the sessions' history as they are. The plugin keeps no files of its own, so nothing else needs removing.
143
+
144
+ ## Development
145
+
146
+ The build uses the Node and pnpm inside the app, so nothing is installed globally:
147
+
148
+ ```sh
149
+ R="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/primary-runtime/dependencies"
150
+ export PATH="$R/node/bin:$PATH"
151
+ pnpm() { node "$R/pnpm/bin/pnpm.cjs" "$@"; }
152
+ pnpm install
153
+ pnpm run build # tsc for the host (lib/), tsdown for the client (lib/client.js)
154
+ pnpm run typecheck # host, client, and host with tests
155
+ pnpm test
156
+ pnpm check # typecheck, tests, build and a pack dry run
157
+ pnpm pack # runs the build, writes dsh-matriarc-<version>.tgz
158
+ ```
159
+
160
+ Node 24 with pnpm 11 from elsewhere (Linux, CI) works with the same lockfile.
161
+
162
+ `lib/` is committed as a release build, so a `github:` install needs no build step. Rebuild it with `pnpm run build` and commit it together with every change to `src/`; CI checks that the committed `lib/` matches a fresh build.
163
+
164
+ To try your own build in the app, install the packed file (quit the app first for the desktop profile):
165
+
166
+ ```sh
167
+ dsh plugin --profile desktop add ./dsh-matriarc-<version>.tgz # or: --profile web
168
+ ```
169
+
170
+ tsdown runs on rolldown's WebAssembly binding because the app's Node refuses native addons from other vendors. A client change needs a rebuild and a page reload; a host change needs a restart.
171
+
172
+ ## Feedback and contributing
173
+
174
+ Bug reports, questions and ideas are very welcome as [GitHub issues](https://github.com/simveit/dsh-matriarc/issues). We do not accept pull requests for now: this is a side project, and the maintainer wants to keep the design focused and does not have the capacity to review contributions. Please open an issue instead. See [CONTRIBUTING.md](CONTRIBUTING.md) for what to include, and [SECURITY.md](SECURITY.md) for security problems.
175
+
176
+ ## License
177
+
178
+ MIT; see [LICENSE](LICENSE). Portions derive from DeepSeek Harness (MIT). The mascot is original artwork for this project, under the same license.
179
+
180
+ This is an independent plugin. It is not made or endorsed by DeepSeek.
@@ -0,0 +1,180 @@
1
+ <p align="center">
2
+ <img src="docs/assets/mascot.svg" width="480" alt="Matriarc 吉祥物:一位靛蓝渐变到水绿色头发、戴着青绿色蝴蝶结的Q版动漫少女骑着虎鲸驶向夕阳,一边挥手,身后跟着她的鲸群">
3
+ </p>
4
+
5
+ <p align="center"><a href="README.md">English</a> | 简体中文 | <a href="README.de.md">Deutsch</a></p>
6
+
7
+ # Matriarc
8
+
9
+ Matriarc(软件包名 `dsh-matriarc`)是 DeepSeek Harness(dsh)的插件,它把“大脑”和“双手”分开。名字来自虎鲸群的母系首领,也就是带领鲸群的最年长的雌性虎鲸:她认得路,鲸群负责捕猎。在会话中打开它后,会话会获得一个工具 `matriarc` 和一小组规则。开始每项任务前,会话调用该工具,由第二个模型(即“大脑”)把你的请求拆成若干子任务。之后会话自己完成工作,或按它平常的方式交给别人完成。工作结束后,会话再次调用该工具,大脑对照你的请求和它自己的计划审查改动:通过、返回调整项,或者指出只有你才能决定的事项。大脑是另一个编程智能体,由 DeepSeek Harness 插件页面提供的子智能体插件运行。它只负责规划和审查,从不动手做事:就像结对编程中的领航员,由会话负责驾驶。
10
+
11
+ **安装:** 在 DeepSeek Harness 中打开“插件” > “添加插件”,输入 `dsh-matriarc` 并点击“安装”。详见[安装](#安装)。
12
+
13
+ ## 环境要求
14
+
15
+ - DeepSeek Harness 0.2.2-rc.3 或更高的 0.2.x 版本(`engines.dsh`)。
16
+ - 一个运行其他编程智能体的子智能体插件(参见 DeepSeek Harness 的[子智能体提供方列表](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/subagent/README.md)),已启用并完成登录。可在 DeepSeek Harness 的插件页面安装。为获得最佳体验,请将该插件设为其自动权限模式,以便领航员可以读取网页并运行只读命令。让编程智能体来改:
17
+
18
+ > 在 `~/.dsh/profiles/desktop/cordis.patch.yml` 中,把我已启用的子智能体插件的 `config.permissionMode` 设为其自动模式,不要用绕过权限的模式(见该插件的 README)。如果缺少该条目,用插件的 `id` 和 `name` 新建一个。先备份文件,并保持 YAML 有效。
19
+
20
+ 然后重启 DeepSeek Harness。`dsh web` 的文件位于 `profiles/web/`。
21
+ - 会话文件夹中可用 Git,用于获取仓库状态。没有 Git 时,插件会告知大脑并继续运行。
22
+ - 软件包附带预构建代码,没有运行时依赖。`@deepseek-ai/cordis` 和 `@deepseek-ai/dsh-typert-protocol` 是由运行中的 dsh 提供的 peer 依赖;安装时 pnpm 给出的 peer 警告属于正常现象。
23
+
24
+ ## 安装
25
+
26
+ Matriarc 以 `dsh-matriarc` 的名称发布在 npm 上。以下任何一种方式都不会在你的机器上构建代码;软件包已包含构建好的代码。
27
+
28
+ **在应用中安装。** 打开“插件”,选择“添加插件”,在“包名或地址”中输入 `dsh-matriarc`,然后点击“安装”。“安装源”保持 npm 官方源即可。安装完成后选择“立即启用”。如果对话框提示重启 DSH,请退出应用后重新启动。
29
+
30
+ **通过命令行安装。** 安装到桌面端 profile 时,请先退出应用,安装后再重新启动。桌面端 profile 必须已存在,因此首次安装前请先打开一次桌面应用。对于 `dsh web`,请使用 `--profile web` 并重启 `dsh web`。
31
+
32
+ ```sh
33
+ dsh plugin --profile desktop add dsh-matriarc
34
+ ```
35
+
36
+ **安装 GitHub 上的最新代码。** 如果要安装仓库的当前状态而不是已发布的软件包,可在上述任一处使用 `github:simveit/dsh-matriarc`。这需要 Git:
37
+
38
+ ```sh
39
+ dsh plugin --profile desktop add github:simveit/dsh-matriarc
40
+ ```
41
+
42
+ 安装到此为止。插件不添加 Agent 预设,也不改动子智能体插件的任何设置。
43
+
44
+ 要安装新版本,先移除插件(见[卸载](#卸载)),再添加新版本。会话的开关状态和已保存的计划都记录在会话自己的日志中,因此会保留下来。
45
+
46
+ ## 快速上手
47
+
48
+ 1. 确认已在插件页面启用一个运行其他编程智能体的子智能体插件(见[环境要求](#环境要求))。为获得最佳效果,请使用它的自动权限模式。
49
+ 2. 在 Git 仓库中打开一个会话。在消息框下方的模型菜单中打开“启用 Matriarc”,也可以输入 `/matriarc on`。
50
+ 3. 照常描述要做的工作。除单纯的提问外,会话对每条消息(包括后续消息)都会先以 stage `plan` 调用 `matriarc`。大脑工作期间工具卡片保持展开,通常需要几分钟。
51
+ 4. 会话执行各个子任务(开启智能体团队协作时分配给团队),并运行每个子任务的检查。
52
+ 5. 如果工作改动了文件,会话会在给出最终回答前以 stage `review` 调用 `matriarc`。若结果为调整,会话完成列出的子任务后再次请求审查;若结果为阻塞,会话会询问你。最终回答中会写明审查结论。
53
+
54
+ 用同一菜单项或 `/matriarc off` 关闭。不带参数的 `/matriarc` 显示当前是否开启。
55
+
56
+ **获得最佳效果:**
57
+
58
+ - 请使用“标准模式”Agent 预设。在“PTC 模式”下,会话会在代码运行中调用 `matriarc`,而 DeepSeek Harness 会在 2 到 10 分钟后中止代码运行,此时领航员通常还没有完成。目前不建议使用 PTC 模式,我们计划提供正式的解决方案。如果确实需要,可在 profile 配置中添加 `ptc-runtime` 条目来提高上限(`name: '@deepseek-ai/dsh-ptc-runtime-node'`,`config: { maxTimeoutMs: 1800000 }`);此后请求更长时间的代码运行最多可持续 30 分钟。
59
+ - 处理较大的任务时,在与 Matriarc 相同的菜单中打开“启用智能体团队协作”。会话随后会把可以同时进行的子任务交给队友。
60
+ - 领航员看到的是你的消息和仓库,而不是会话的对话内容。请把链接、报错信息和约束写进你的消息,或写进仓库中的文件。
61
+ - 用一条消息描述完整任务。计划之后写的消息会进入下一次计划,而不会进入审查。
62
+ - 开始前先提交或 stash 无关的改动,这样审查只看到本任务的改动。
63
+ - 每项任务都要等几分钟拿到计划。只改一行的小修改,请先关闭 Matriarc。
64
+
65
+ ## 工作原理
66
+
67
+ **开关。** “启用 Matriarc”属于单个会话,默认关闭。它位于模型菜单中“启用智能体团队协作”旁边,两者互不影响。在子智能体会话中,`/matriarc on` 会被拒绝。没有可用提供方时,菜单项会显示一条简短提示,并列出你可以启用的子智能体插件,点击即可在插件页面打开对应插件。关闭开关则始终可以操作。只有你能改变开关:会话模型无法执行斜杠命令。从会话派生(fork)出的新会话,开关为关闭状态且没有计划。
68
+
69
+ **谁能看到工具。** 只有在开关打开、只对会话的根智能体、且有大脑提供方已注册时,工具及其规则才会出现。会话的子智能体和团队成员永远看不到它们。
70
+
71
+ **计划。** 插件向大脑发送规划指令(`prompts/planner.md`)、你的请求和仓库状态。你的请求是指自上一次成功的计划以来(或自会话开始以来)你输入的每一条消息,逐字原文、按顺序排列,因此像“好的,开始吧”这样简短的后续回复会与它所回应的内容一并送达。图片和文件会被替换为占位标记。仓库状态包括分支、当前提交和 `git status`。大脑从会话的工作文件夹启动,自行阅读代码。它的回答以“Plan (<provider>)”为标题返回,采用以下纯文本格式:
72
+
73
+ ```
74
+ APPROACH
75
+ Two to five sentences: how the task will be solved and why this way.
76
+
77
+ SHARED
78
+ Facts every subtask needs: file paths, names, interfaces, conventions to keep.
79
+
80
+ S1 <short title>
81
+ goal: what this subtask achieves
82
+ details: what to change and how, concrete enough to start without further research
83
+ needs: subtasks that must be finished first, or "none"
84
+ touches: files or folders it writes
85
+ done when: a check that can be run or read, such as a test command or an observable behaviour
86
+
87
+ S2 ...
88
+
89
+ DONE WHEN
90
+ The checks that show the whole task is finished.
91
+
92
+ OPEN
93
+ Only what blocks the work and has no safe default, or "none".
94
+ ```
95
+
96
+ 子任务的数量由大脑决定;任务较小时,只有一个子任务的计划也是有效的。大脑不会被告知子任务将如何执行。会话可以随时请求新的计划,新计划会替换之前的计划。
97
+
98
+ **执行工作。** 两次调用之间发生什么由会话自己决定。普通会话按顺序完成各个子任务。开启智能体团队协作时,规则要求会话把每个可以与其他子任务同时进行的子任务交给一个新的 `subagent` 队友,在开始自己的工作之前一次性全部启动,只有其余的才自己完成。否则规则只写“由你自己完成,或通过本会话使用的任何委派方式完成”。
99
+
100
+ **审查。** 插件向大脑发送一条固定指令“Review the recent changes in this repository against the request and the plan below.”,随后是审查指令(`prompts/reviewer.md`)、制定计划时依据的请求、逐字保存的计划,以及计划之后的改动。计划之后你写的消息不会发给审查者。改动包括 `git status`(其中列出新文件)和 diff;新文件由大脑自行读取。它们覆盖制定计划时所在的仓库,以及工作文件夹所在的仓库(如果两者不同)。会话可以通过调用的 `folders` 参数再添加最多八个位于其工作文件夹内的仓库。整个审查提示词不超过 200,000 个字符;被截断的部分会有标记,大脑会从磁盘读取。大脑通过阅读 diff 和文件进行审查。它不依赖运行命令,其结论也不取决于命令。回答以 CHECKS FOR THE SESSION 结尾,即会话在最终回答前必须运行的命令。回答的第一行是审查结论:
101
+
102
+ | 结论 | 含义 | 会话的处理 |
103
+ |---|---|---|
104
+ | `VERDICT: PASS` | 从阅读来看,所有完成标准均已满足 | 运行会话检查,然后给出最终回答,并附上结论和检查结果 |
105
+ | `VERDICT: ADJUST` | 存在正确性缺陷或遗漏的需求 | 按计划格式执行列出的修改,运行会话检查,然后再次请求审查 |
106
+ | `VERDICT: BLOCKED` | 存在只有你才能决定的事项 | 停下来询问你 |
107
+
108
+ 审查轮数没有上限。每次结果的标题为“Review N (<provider>)”,N 在新计划后从头计数,方便你看出审查进行了几次。失败、被停止或超时的运行不计为一轮。
109
+
110
+ **一次一个运行。** 一个会话同一时间只运行一次大脑调用,每次调用限时 30 分钟。如果大脑无法运行(超时、达到 DSH 活跃子智能体数量上限,或提供方已不再注册),工具会返回一个正常结果,告诉会话自行继续;如果是审查,还会让会话告诉你这次工作未经审查。Git 无法运行时,会告知大脑,调用继续进行。点击“停止”会立即结束调用。大脑运行出错结束时,会返回带有提供方错误信息的错误结果。
111
+
112
+ **哪些状态会保留。** 开关状态以及最近一次计划(连同其审查次数和最近一次结论)都从会话自己的日志中重建。它们在上下文压缩、应用重启和插件更新后都会保留。
113
+
114
+ ## 配置
115
+
116
+ 0.1.1 版本没有设置项。插件在插件页面上没有自己可配置的项。大脑能做什么(模型、权限模式、沙箱)由子智能体插件以及该智能体自身的设置决定,Matriarc 不会改动其中任何一项。推荐使用自动模式(见[环境要求](#环境要求))。
117
+
118
+ Matriarc 使用在 DSH 之外运行其他智能体的子智能体插件。启用了多个时,菜单项会显示“选择领航员”,每个插件一项;也可以输入 `/matriarc on <领航员>`。该选择属于当前会话。没有选择,或所选插件已关闭时,Matriarc 使用 DSH 最先注册的那个,菜单项会说明这一点。不带参数的 `/matriarc` 会显示当前使用的是哪一个。手动在配置中设置的 ACP 子智能体提供方无法与编程智能体区分,因此 Matriarc 可能会使用它。
119
+
120
+ ## 身份验证
121
+
122
+ Matriarc 从不自行启动另一个编程智能体,也从不触碰它的登录信息。它只是请 DSH 的子智能体服务运行 DSH 已注册的提供方。DeepSeek 的提供方插件以各自锁定的版本运行官方运行时。身份验证由提供方自己负责,按提供方自己的条款在该插件中设置。
123
+
124
+ ## 安全
125
+
126
+ 会话无法写入任何会被大脑读取的内容。该工具没有自由文本参数。大脑的输入是你的消息、Git 输出、插件的固定指令,以及审查时大脑自己的计划。会话为审查指定的文件夹必须位于其工作文件夹内,而且这些文件夹的名称从不写入提示词。当然,被审查的改动本身是会话的工作成果,大脑也会这样看待它们。
127
+
128
+ 插件在会话沙箱之外运行 Git,因此以加固方式运行:仓库钩子、文件系统监视器、文本转换、外部 diff 程序、过滤器以及网络传输(部分克隆的延迟获取会用到)都被关闭。这些正是 Git 在读取时根据仓库配置运行程序的途径,插件的测试逐一检查了它们。
129
+
130
+ 大脑的回答只是建议。它作为工具结果返回,会话用自己的工具、在自己的审批规则下据此行动。大脑以其提供方赋予的权限运行:插件要求它不修改任何文件,但无法强制执行;在跳过所有权限检查的模式下,它是可以修改的。你的消息、状态、diff 以及大脑读取的任何文件都会发送给第二家厂商,其中包括你粘贴到聊天中、或写进未被 Git 忽略的文件里的任何密钥。你启用的任何外部子智能体插件都可能成为领航员,并接收你的消息、状态和 diff,因此只启用你愿意向其发送这些内容的提供方;`/matriarc` 会显示当前使用的是哪一个。此外,审查者可能出错,两个方向都有可能:通过只是第二意见,而不是证明。
131
+
132
+ [docs/security.md](docs/security.md) 包含威胁模型、哪些由代码强制执行、哪些依赖规则,以及已知的局限。如需报告漏洞,请参阅 [SECURITY.md](SECURITY.md)。
133
+
134
+ ## 卸载
135
+
136
+ 在应用中打开“插件”,在 Matriarc 上选择“卸载”。通过命令行:
137
+
138
+ ```sh
139
+ dsh plugin --profile desktop remove dsh-matriarc # or: --profile web
140
+ ```
141
+
142
+ 工具、规则和菜单项会从所有会话中消失。之前的工具卡片会原样保留在会话历史中。插件不保存任何自己的文件,因此无需再删除其他内容。
143
+
144
+ ## 开发
145
+
146
+ 构建使用应用内置的 Node 和 pnpm,因此无需全局安装任何东西:
147
+
148
+ ```sh
149
+ R="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/primary-runtime/dependencies"
150
+ export PATH="$R/node/bin:$PATH"
151
+ pnpm() { node "$R/pnpm/bin/pnpm.cjs" "$@"; }
152
+ pnpm install
153
+ pnpm run build # tsc for the host (lib/), tsdown for the client (lib/client.js)
154
+ pnpm run typecheck # host, client, and host with tests
155
+ pnpm test
156
+ pnpm check # typecheck, tests, build and a pack dry run
157
+ pnpm pack # runs the build, writes dsh-matriarc-<version>.tgz
158
+ ```
159
+
160
+ 在其他环境(Linux、CI)中使用 Node 24 和 pnpm 11,配合同一份 lockfile 也可以构建。
161
+
162
+ `lib/` 作为发布构建提交到仓库,因此 `github:` 安装无需构建步骤。每次修改 `src/` 时,请用 `pnpm run build` 重新构建并一起提交;CI 会检查提交的 `lib/` 与全新构建是否一致。
163
+
164
+ 要在应用中试用你自己的构建,请安装打包出的文件(桌面端 profile 需先退出应用):
165
+
166
+ ```sh
167
+ dsh plugin --profile desktop add ./dsh-matriarc-<version>.tgz # or: --profile web
168
+ ```
169
+
170
+ tsdown 使用 rolldown 的 WebAssembly 绑定运行,因为应用内置的 Node 拒绝加载其他厂商的原生插件。客户端改动需要重新构建并刷新页面;宿主端改动需要重启。
171
+
172
+ ## 反馈与贡献
173
+
174
+ 非常欢迎通过 [GitHub issues](https://github.com/simveit/dsh-matriarc/issues) 提交 bug 报告、问题和想法。目前我们不接受 pull request:这是一个业余项目,维护者希望保持设计的专注,也没有精力审阅贡献。请改为提交 issue。需要包含哪些信息请参阅 [CONTRIBUTING.md](CONTRIBUTING.md),安全问题请参阅 [SECURITY.md](SECURITY.md)。
175
+
176
+ ## 许可证
177
+
178
+ MIT;见 [LICENSE](LICENSE)。部分内容源自 DeepSeek Harness(MIT)。吉祥物是为本项目创作的原创作品,采用相同许可证。
179
+
180
+ 这是一个独立插件,并非由 DeepSeek 制作或认可。
@@ -0,0 +1,3 @@
1
+ - insert:
2
+ - id: dsh-matriarc
3
+ name: dsh-matriarc