DeeSeek Harness Postmortems und Engineering-Kultur

Das dsh-Repository verwandelt jeden Bug, der "nicht hätte passieren dürfen, aber passiert ist", in ein Postmortem und hinterlässt Guards auf Test-, Dokumentations- und Regelebene.

Verstehe diese Postmortem-Kultur und Testdisziplin, und du kannst sie im Beispielprojekt nutzbar machen: dsh nicht nur benutzen, sondern wie ein Maintainer denken.

In einem Satz: Der Wert eines Bugs liegt nicht im Einzeiler-Fix, sondern darin, warum der Prozess ihn durchgelassen hat und welcher Guard hinzugefügt wurde, damit ähnliche Probleme nächstes Mal laut fehlschlagen.


Retrospektiven-Kultur: Vier Fragen

Ein Postmortem hält fest: Ein Bug ist an einer Stelle aufgetreten, an der er nicht hätte auftreten dürfen – vor echten Nutzern, in einem gemergten PR oder in einer veröffentlichten Version.

What's worth noting isWarum ließ unser Prozess ihn durch?, statt nur diesem Einzeiler-Fix.

Es ist ein retrospektiver Bericht eines Fehlschlags, der vier Fragen beantwortet:

Vier FragenWas zu beantworten ist
Was ist kaputt?Ein kurzer Absatz, der beschäftigten Lesern ermöglicht, die Kernpunkte in dreißig Sekunden aufzunehmen.
Was ist der Mechanismus?Nenne die eigentliche Ursache in einfachen Worten, ohne Einzelne zu beschuldigen.
Warum jedes Sicherheitsnetz es nicht abfangen konnteIdentifiziere Lücken in Tests, Tooling und Konventionen – nicht nur einen einmaligen Tippfehler.
Welche neuen Schutzmaßnahmen wurden hinzugefügtTests, AGENTS.md-Regeln, ADRs – sorge dafür, dass ähnliche Bugs beim nächsten Mal lautstark fehlschlagen.

Nicht jeder Bug verdient ein Postmortem.

Schreibe nur dann eines, wenn der Bug alle drei Bedingungen erfüllt:Versteckt(der Mechanismus ist nicht offensichtlich; selbst ein sorgfältiger Entwickler müsste sich stark anstrengen, ihn erneut herzuleiten),Systematisch(der Grund, warum es entkam, war eine Lücke in Tests, Tooling oder Konventionen),Die Kosten der Wiederentdeckung sind hoch(es hat echte Debugging-Zeit gekostet und wird es beim nächsten Mal wieder tun).

事故复盘流程与测试金字塔图


Vier reale Fälle

Das Repository enthält derzeit vier Postmortems, die jeweils einer Klasse von Engineering-Fehlern entsprechen, die dazu neigt, wiederaufzutreten.

Ich werde jedes einzelne durchgehen, mit dem Fokus auf „warum es entkam“ und „welche Schutzmaßnahme hinzugefügt wurde“.

Überprüfung 0001

ACP-Server stürzt bei Verbindung ab: export default lässt das inject des Plugins weg.

Was kaputtging: In dem Moment, als der Editor (Zed) sich verband, der erstesession/newNur meldencannot get property "agents" without inject。

Mechanismus: Das Plugin schrieb ein Extra.export default apply, des LoadersunwrapExportsEs holte die nackte Funktion, und die auf dem Namespace...injectVerlor sie vollständig.

Warum das Sicherheitsnetz es nicht abfing: 178 grüne Unit-Tests + 100% Zeilenabdeckung waren alle da, aber jeder Test war manuellctx.plugin(...)gemountet, wobei der Ladepfad des echten Loaders umgangen wurde.

Schutzmaßnahmen hinzugefügt: default export entfernt; schlüsselloser Real-Loader-Smoke-Test hinzugefügt; Regel: "Teste den echten Einstiegspfad — Zeilenabdeckung ist keine Verhaltensabdeckung."

Überprüfung 0002

Das Dateisystem-Snapshot-Tool wurde dauerhaft durch ein wörtliches !!js-Objekt deaktiviert.

Was kaputtging: Sieben Dateisystem-Szenarien riefen ein Tool auf, das nicht in der Registry existiert, und gaben ... zurück.UNKNOWN_TOOL。

Mechanismus: Der Autor verwendetdisabled: !!js ...Wir wollten das Dateisystem-Plugin bedingt aktivieren, aber Cordis wertet nur JS-Ausdrücke ausconfiginnerhalb des Plugins; beim direkten Lesendisableddes Konfigurationseintrags sah es ein truthy-Objekt.

Warum das Sicherheitsnetz es nicht auffing: Die Snapshot-Aktualisierung behandelte "deterministisches Replay" als "korrektes Verhalten" – sie bewies, dass die Regression stabil reproduziert wurde, aber nicht, dass das Dateisystem-Tool tatsächlich registriert war.

Hinzugefügte Schutzmaßnahmen: Umstieg auf ein explizites Dateisystem-Overlay; ein statischer Konfigurationswächter weist Ausdrucksknoten in Loader-Konfigurationsmetadaten zurück; das Snapshot-Framework weist strukturierteUNKNOWN_TOOLErgebnis.

Überprüfung 0003

Der Web-Agent akzeptierte einen Ersatzserver, statt dass die GUI seine Sitzung hostete.

Was kaputtging: Der Agent änderte den GUI-Quellcode, wusste aber nicht, welcher URL die aktuelle Sitzung entsprach oder welcher Prozess sie hostete.

Mechanismus: Es behandelte die vom reinen Vite-Server zurückgegebene HTTP-200-Antwort als Erfolg (tatsächlich ein leerer Bildschirm) und ging dann dazu über, einen Ersatz zu akzeptierendsh webServer auf einem anderen Port, ohne jemals Port 3081 zu prüfen.

Warum das Sicherheitsnetz es nicht abfing: Die Web-Komposition stellte dem Modell keine Identitätsinformationen über die aktuelle GUI, die kanonische URL oder den Ausführungsmodus bereit; der erste Regressionstest verwendete außerdem „Prozess-Timeout“, um „Fail Fast“ vorzutäuschen, was zu einem falsch positiven Ergebnis führte.

Schutz hinzufügen: StartdevicepublishSpecificationCycle-Rückgabe-URL und tatsächliche Produktion/DevelopmentMode (Umgebungsvariablen + Hintword-Bereichssegment); unabhängiger Vite-Services-Modus in der Konfigurationsphase: Start ablehnen; Divide-Layer-True-Real-Path-Testing deckt CLI, Hintword, Laufzeit-real- und Browser-Gerät-HMR ab.

Überprüfung 0004

Landlock-Hinweise auf teilweise Durchsetzung führten dazu, dass Fehler von Kindprozessen falsch klassifiziert wurden.

Was kaputtging: Auf Kernels mit einer älteren Landlock-ABI beendet sich ripgrep bei fehlenden Treffern normal mit Code 1, aber es wurde als Fehler dargestellt.SANDBOX_UNAVAILABLESandbox-Fehler.

Mechanismus: Der Launcher gibt eine harmloselandlock-run: partial enforcement (older Landlock ABI)Meldung aus; das Harness verwendet eine Groß-/Kleinschreibung ignorierendelandlock-run: Teilzeichenfolge, kombiniert mit einem beliebigen Nicht-Null-Exit, um ihn fälschlich als Runner-Fehler zu klassifizieren.

Warum das Sicherheitsnetz es nicht abfing: Der Sandbox-Ergebnistyp kann nur eine Menge von Teilzeichenfolgen ausdrücken; er kann nicht ausdrücken, dass „ein Landlock-Fehler mit Code 125 + einer Zeile einer fatalen Diagnose beendet werden muss“; die Testmatrix konstruiert nie die Kombination aus „Benachrichtigung, gefolgt von einem Nicht-Null-Exit des Subprozesses“.

Schutz hinzufügen:RunnerFailureRuleInformationszeilen mit erlaubten Exit-Codes, fatalen Signaturen pro Zeile und präzisen Ausschlüssen mitführen; Dateisystemsuche wechselt zu...ctx.subprocessDas mitgelieferte ripgrep ausführen, es nicht mehr durch Sandbox-Bash leiten.

Wenn man die vier Fälle zusammen betrachtet, zeigt sich eine gemeinsame Lektion:Tests müssen den echten Einstiegspfad durchlaufen。

Manuelles Mounten, alles mocken und das Aktualisieren von Snapshots als Abnahme behandeln — all das macht "Unit-Tests alle grün, Produkt kaputt" möglich.


Vier Testebenen

Die Teststrategie des Repositorys ist geschichtet; jede Ebene deckt blinde Flecken ab, die die vorherige Ebene nicht erfassen kann.

StufeBefehlWas zu erfassen ist
Unit-Testingpnpm run testVitest führt paketinterne Tests aus und priorisiert dabei Edge Cases, Fehlerpfade, Ereignisreihenfolge und Nebenläufigkeitsrennen.
Coverage-Gatepnpm run test:coverage100% Abdeckung pro Datei; nicht abgedeckte Zeilen sind meist toter Code, der gelöscht werden sollte.
Echte API e2epnpm run test:e2eRuft echte Provider-APIs mit Keys auf; überspringt automatisch, wenn Keys fehlen, und hält so keylose CI grün.
Snapshotpnpm run test:snapshot / test:webKeylose erwartete Ausgaben decken externes Verhalten ab; Browser-Snapshots werden mit Chromium erneut abgespielt und verglichen.

Das Repository ist DeepSeeks eigenes, daher gibt es ein besonderes Prinzip:Inferenz ist hier günstig, spare nicht an echten API-Tests.。

Keylose Tests können nur den zugrunde liegenden Pfad beweisen; nur die Ausführung mit Keys kann beweisen, dass der Agent mit einem echten Modell korrekt funktioniert.

Die wertvollsten sind Smoke-Tests: ein echtes Beispiel starten, einen einzelnen Prompt senden und die Außenwelt überprüfen.

Sie fangen die Klasse von Problemen ab, bei der "Unit-Tests alle grün, Produkt kaputt" gilt, die Mocks nicht entdecken können.

Zeilenabdeckung ist eine notwendige Bedingung, niemals eine hinreichende.

Es beweist, dass eine Zeile ausgeführt wurde, nicht, dass das Feature wie geliefert funktioniert.

Im Fall 0001 ließ 100% Abdeckung dennoch zwei Integrationsfehler durchrutschen — die perfekte Fußnote.

Ein weiteres Prinzip istDie Außenwelt verifizieren, statt Selbstauskunft。

E2E-Assertions sollten den Befehl erneut ausführen oder die Datei extern erneut lesen; Keyword-Probing der eigenen Ausgabe des Agenten würde einen betrügerischen Agenten durchkommen lassen.

Stelle sicher, dass unveränderte Dateien Byte für Byte identisch bleiben.


Dokumentationsdisziplin: Eine Tatsache, ein Ort.

Die Dokumentation des Repositorys ist nicht "einmal geschrieben und fertig"; ein Mechanismus verhindert, dass "Dokumentation und Quelle auseinanderdriften".

verify-type-equivEs ist ein Gate: Es verwendet einen TypeScript-Parser, um Typdeklarationssymbole und die jeweils angehängten JSDoc-Kommentare aus der Quelle zu extrahieren, und stellt sicher, dass Codeblöcke in der Dokumentation mit beiden übereinstimmen.

Wenn Sie eine dokumentierte Typdeklaration oder deren JSDoc ändern, schlägt das Gate fehl, bis Sie den eingefügten Inhalt aktualisieren.

Dies garantiert, dass Typdefinitionen in der Dokumentation immer mit der Quelle übereinstimmen — keine "aus einer älteren Version kopierten Dokumente".

Eine weitere Disziplin istEine Tatsache, ein Ort: Jede Tatsache wird in genau einer Datei gepflegt; alle anderen Dateien verweisen darauf.

Zum Beispiel befindet sich die "maßgebliche Quelle" für das Tool-Schema inadding-a-tool.md, andere Seiten verweisen darauf, anstatt zu kopieren.

Chinesische und englische Dokumente werden als zweisprachige Paare gepflegt; beim Aktualisieren zuerst ausführen...pnpm run gen-doc-graphsEnglisch aktualisieren, dann Chinesisch aktualisieren und die Paarung überprüfen.

Das gilt auch für Ihre eigenen Projekte: Halten Sie die "Single Source of Truth" an einer Stelle; verteilen Sie dasselbe nicht über drei Dokumente.


Praxisbeispiel: Schreibe eine Dreißig-Sekunden-Zusammenfassung für die Geschäftsleitung.

Jede Postmortem-Analyse beginnt mit einer Zusammenfassung für die Geschäftsleitung, damit ein vielbeschäftigter Leser die Kernpunkte in dreißig Sekunden erfassen kann.

Versuche, eine Postmortem-Analyse für einen Agent-Fehler zu schreiben, der dir im Beispielprojekt begegnet ist, und nutze dabei die folgende Vorlage:

# 复盘 0005:example 演示环境的工具黑名单没有生效

## 摘要
demo 环境里模型仍能调用被禁用的 fs_write,直接写入了工作区。
根因是黑名单插件用 `tools/pre-execute` 返回了 `next()`,
而真正负责拦截的守卫注册在插件卸载之后——加载顺序错了。
逃逸原因是加载顺序没有测试覆盖,`cordis.yml` 只测了「能起来」。
新增防护:给黑名单插件补一条「顺序敏感」的装配测试,
并在 AGENTS.md 记录「pre-execute 与 guard 的注册顺序」规则。

Die Formel für eine Dreißig-Sekunden-Zusammenfassung: Was ist kaputtgegangen → Grundursache in einfachen Worten → warum ist es entkommen → eine Lehre, die du langfristig mitnehmen kannst.


Fazit der Serie

An diesem Punkt enden alle 28 Folgen des Einführungstutorials zum DeepSeek Harness.

Blicke den Weg zurück: vom ersten Artikel, in dem du die vier Schutzgeländer von dsh kennengelernt hast, über die Installation, die Nutzung der Web-UI und die Nutzung des Python-SDK; vom Schreiben deines ersten Plugins bis zum Verständnis des Plugin-Lebenszyklus, der Services und Scopes sowie des Ereignissystems; vom Entwerfen von Fähigkeiten mit dem Drei-Rollen-Muster und der Integration beliebiger LLMs bis hin zu Verpackung und Veröffentlichung. Schließlich vervollständigen diese letzten fünf Artikel das letzte Puzzleteil: Sicherheit und Engineering-Kultur.

Was du wirklich mitnimmst, ist nicht nur der Umgang mit der API, sondern eine Denkweise:

Das Modell ist für die Intelligenz verantwortlich, das Harness für die Zuverlässigkeit.Einschränkungen sind keine Beschränkungen; sie sind das Fundament, das Agents vorhersagbar, prüfbar und wiederholbar macht.

Alles ist ein Plugin.Setze Richtlinien an Erweiterungspunkten, nicht innerhalb der Schleife, und das System kann sich weiterentwickeln, ohne die Kontrolle zu verlieren.

Der echte Einstiegspfad schlägt alle Mocks.Abdeckung, Snapshots und Smoke-Tests erfüllen jeweils ihre eigene Aufgabe und verhindern gemeinsam „alles grün, aber kaputt“.

Fehler sind nicht beängstigend. Beängstigend ist, nicht zu wissen, warum.Eine Postmortem-Kultur verwandelt einen einzelnen Vorfall in eine Reihe von Abwehrmaßnahmen.

Weitere Erweiterungen