Post-mortems et culture d'ingénierie de DeeSeek Harness

Le dépôt dsh transforme chaque bug qui « n'aurait pas dû arriver mais qui est arrivé » en post-mortem, et laisse des garde-fous aux niveaux des tests, de la documentation et des règles.

Comprenez cette culture du post-mortem et cette discipline de test, et vous pourrez la mettre en pratique dans le projet d'exemple : pas seulement utiliser dsh, mais penser comme un mainteneur.

En une phrase : la valeur d'un bug ne réside pas dans le correctif d'une ligne, mais dans la raison pour laquelle le processus l'a laissé passer, et dans le garde-fou ajouté pour que des problèmes similaires échouent bruyamment la prochaine fois.


Culture rétrospective : quatre questions

Un post-mortem consigne : un bug est apparu là où il n'aurait pas dû — devant de vrais utilisateurs, dans une PR fusionnée, ou dans une version publiée.

Ce qui mérite d'être noté, c'estPourquoi notre processus l'a-t-il laissé passer ?, plutôt que simplement ce correctif d'une ligne.

C'est un compte rendu rétrospectif d'un échec, répondant à quatre questions :

Quatre questionsCe qu'il faut répondre
Qu'est-ce qui est cassé ?Un court paragraphe qui permet aux lecteurs pressés d'assimiler les points clés en trente secondes.
Quel est le mécanisme ?Énoncez la cause racine en termes simples, sans blâmer les individus.
Pourquoi tous les filets de sécurité ont échoué à le détecterIdentifiez les lacunes dans les tests, l'outillage et les conventions — pas une faute de frappe isolée.
Quelles nouvelles protections ont été ajoutéesTests, règles AGENTS.md, ADRs — faites en sorte que les bugs similaires échouent bruyamment la prochaine fois.

Tous les bugs ne méritent pas un post-mortem.

N'en rédigez un que lorsque le bug remplit les trois conditions suivantes :Caché(le mécanisme n'est pas évident ; même un ingénieur attentif devrait déployer de gros efforts pour le redéduire),Systématique(la raison pour laquelle il est passé inaperçu était une lacune dans les tests, l'outillage ou les conventions),Le coût de la redécouverte est élevé(il a consommé un temps de débogage réel, et le refera la prochaine fois).

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


Quatre cas réels

Le dépôt contient actuellement quatre post-mortems, chacun correspondant à une classe d'erreurs d'ingénierie qui ont tendance à se reproduire.

Je vais passer en revue chacun d'eux en mettant l'accent sur « pourquoi il est passé inaperçu » et « quel garde-fou a été ajouté ».

Revue 0001

Le serveur ACP plante à la connexion : l'export default supprime l'inject du plugin.

Ce qui a cassé : au moment où l'éditeur (Zed) s'est connecté, le premiersession/newSignaler simplementcannot get property "agents" without inject。

Mécanisme : le plugin a écrit un en trop.export default apply, du LoaderunwrapExportsIl a récupéré la fonction nue, et celle sur l'espace de noms...injectL'a perdu entièrement.

Pourquoi le filet de sécurité ne l'a pas détecté : 178 tests unitaires verts + 100% de couverture de lignes étaient tous là, mais chaque test était manuellementctx.plugin(...)monté, en contournant le chemin de chargement du vrai Loader.

Garde-fous ajoutés : suppression de l'export default ; ajout d'un test de fumée sans clé sur le vrai Loader ; règle : « tester le vrai chemin d'entrée — la couverture de lignes n'est pas une couverture de comportement. »

Revue 0002

L’outil d’instantané du système de fichiers a été définitivement désactivé par un objet littéral !!js.

Ce qui a cassé : sept scénarios de système de fichiers ont invoqué un outil qui n’existe pas dans le registre, renvoyant...UNKNOWN_TOOL。

Mécanisme : L’auteur utilisedisabled: !!js ...Nous voulions activer conditionnellement le plugin de système de fichiers, mais Cordis n’évalue que les expressions JSconfigà l’intérieur du plugin ; lorsqu’il lit directementdisabledl’élément de configuration, il a vu un objet truthy.

Pourquoi le filet de sécurité ne l’a pas attrapé : l’actualisation de l’instantané a traité le « rejeu déterministe » comme un « comportement correct » — elle a prouvé que la régression était reproduite de manière stable, mais n’a pas prouvé que l’outil de système de fichiers était réellement enregistré.

Garde-fous ajoutés : passage à une surcouche de système de fichiers explicite ; un garde-fou statique de configuration rejette les nœuds d’expression dans les métadonnées de configuration du Loader ; le framework d’instantané rejette les données structuréesUNKNOWN_TOOLRésultat.

Revue 0003

L’agent web a accepté un serveur de remplacement plutôt que l’interface graphique qui hébergeait sa session.

Ce qui a cassé : l’agent a modifié le code source de l’interface graphique, mais ne savait pas à quelle URL la session actuelle correspondait ni quel processus l’hébergeait.

Mécanisme : il traitait le HTTP 200 renvoyé par le serveur Vite nu comme un succès (en réalité un écran vide), puis passait à l'acceptation d'un remplacementdsh webserveur sur un autre port, sans jamais sonder le port 3081.

Pourquoi le filet de sécurité ne l'a pas intercepté : la composition Web n'a pas fourni au modèle d'informations d'identité sur l'interface graphique actuelle, l'URL canonique ou le mode d'exécution ; le premier test de régression utilisait aussi "délai d'expiration du processus" pour imiter "échec rapide", produisant un faux positif.

Ajouter une protection : StartdevicepublishSpecificationCycle : URL de retour et production réelle/DevelopmentMode (variables d'environnement + segment de zone Hintword) ; Services Vite indépendants : ServicesModeInConfigurationPhaseRejectStart ; DividerelayertruerealpathTesting couvre CLI, Hintword, runtime réel et HMR navigateur/appareil.

Revoir 0004

Les notifications d'application partielle de Landlock ont entraîné une mauvaise classification des échecs des processus enfants.

Ce qui a cassé : sur les noyaux avec une ABI Landlock plus ancienne, ripgrep se termine normalement avec le code 1 lorsqu'il n'y a aucune correspondance, mais cela a été présenté comme un échec.SANDBOX_UNAVAILABLEÉchec du bac à sable.

Mécanisme : le lanceur imprime unlandlock-run: partial enforcement (older Landlock ABI)avis inoffensif ; le harnais utilise une sous-chaîne insensible à la casselandlock-run: combinée à tout code de sortie non nul pour le classer à tort comme un échec du runner.

Pourquoi le filet de sécurité ne l'a pas intercepté : le type de résultat du bac à sable ne peut exprimer qu'un ensemble de sous-chaînes ; il ne peut pas exprimer "un échec Landlock doit se terminer avec le code 125 + une ligne de diagnostic fatal" ; la matrice de tests ne construit jamais la combinaison de "notification suivie d'une sortie non nulle du sous-processus".

Ajouter une protection :RunnerFailureRuleTransmettre des lignes d'information avec des codes de sortie autorisés, des signatures fatales par ligne et des exclusions précises ; la recherche dans le système de fichiers bascule vers...ctx.subprocessExécuter le ripgrep intégré, sans plus le faire passer par un bash en bac à sable.

En considérant les quatre cas ensemble, une leçon commune se dégage :Les tests doivent passer par le véritable chemin d'entrée。

Le montage manuel, le fait de tout simuler et le fait de traiter le rafraîchissement des snapshots comme une acceptation — tout cela rend possible « tests unitaires tous verts, produit cassé ».


Quatre couches de tests

La stratégie de tests du dépôt est en couches ; chaque couche couvre les angles morts que la couche précédente ne peut pas détecter.

NiveauCommandeCe qu'il faut capturer
Tests unitairespnpm run testVitest exécute les tests au sein des paquets, en privilégiant les cas limites, les chemins d'erreur, l'ordre des événements et les courses de concurrence.
Seuil de couverturepnpm run test:coverage100% de couverture par fichier ; les lignes non couvertes sont généralement du code mort qui devrait être supprimé.
e2e d'API réellepnpm run test:e2eAppelle les vraies API des fournisseurs avec des clés ; ignore automatiquement l’appel lorsque les clés sont absentes, ce qui garde la CI sans clé au vert.
Instantanépnpm run test:snapshot / test:webLes sorties attendues sans clé couvrent le comportement externe ; les instantanés de navigateur sont rejoués et comparés à l’aide de Chromium.

Le dépôt est celui de DeepSeek, il y a donc un principe particulier :L’inférence est bon marché ici, ne lésinez pas sur les vrais tests d’API.。

Les tests sans clé ne peuvent prouver que le chemin sous-jacent ; seule une exécution avec des clés peut prouver que l’agent fonctionne correctement avec un vrai modèle.

Les plus précieux sont les tests de fumée : démarrer un vrai exemple, envoyer un seul prompt, et inspecter le monde extérieur.

Ils attrapent la classe de problèmes « tous les tests unitaires au vert, produit cassé » que les mocks ne peuvent pas découvrir.

La couverture de lignes est une condition nécessaire, jamais suffisante.

Cela prouve qu’une ligne a été exécutée, pas que la fonctionnalité fonctionne telle que livrée.

Dans le cas 0001, une couverture de 100 % a tout de même laissé passer deux bugs d’intégration — la note de bas de page parfaite.

Un autre principe estVérifier le monde extérieur, plutôt que l’auto-déclaration。

Les assertions E2E doivent réexécuter la commande ou relire le fichier de l’extérieur ; sonder par mots-clés la propre sortie de l’agent permettrait à un agent tricheur de passer.

Vérifier que les fichiers non modifiés restent identiques octet par octet.


Discipline de documentation : un fait, un seul endroit.

La documentation du dépôt n'est pas « terminée une fois écrite » ; un mécanisme empêche la « dérive entre la documentation et le code source ».

verify-type-equivIl s'agit d'un contrôle : il utilise un analyseur TypeScript pour extraire les symboles de déclaration de type et leur JSDoc associé depuis la source, et vérifie que les blocs de code de documentation correspondent aux deux.

Lorsque vous modifiez une déclaration de type documentée ou son JSDoc, le contrôle échoue tant que vous n'avez pas mis à jour le contenu collé.

Cela garantit que les définitions de type dans la documentation correspondent toujours à la source — aucune « documentation copiée d'une version plus ancienne ».

Une autre discipline estUn fait, un seul endroit: chaque fait est maintenu dans exactement un fichier ; tous les autres fichiers y font référence.

Par exemple, la « source de vérité » du schéma de l'outil se trouve dansadding-a-tool.md, les autres pages font référence plutôt que de copier.

Les documents en chinois et en anglais sont maintenus sous forme de paires bilingues ; lors d'une mise à jour, exécutez d'abord...pnpm run gen-doc-graphsMettez à jour l'anglais, puis mettez à jour le chinois et vérifiez l'appariement.

Cela s'applique aussi à vos propres projets : gardez la « source unique de vérité » à un seul endroit ; ne dispersez pas la même configuration dans trois documents.


Exemple pratique : rédigez un résumé exécutif de trente secondes.

Chaque post-mortem commence par un résumé exécutif afin qu'un lecteur pressé puisse assimiler les points clés en trente secondes.

Essayez de rédiger un post-mortem pour une défaillance d'Agent que vous avez rencontrée dans le projet d'exemple, en utilisant le modèle ci-dessous :

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

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

La formule d'un résumé de trente secondes : ce qui a cassé → la cause racine en mots simples → pourquoi cela est passé inaperçu → une leçon à retenir à long terme.


Conclusion de la série

À ce stade, les 28 volets du tutoriel d'introduction à DeepSeek Harness se concluent.

Regardez le chemin parcouru : du premier article, où vous avez découvert les quatre garde-fous de dsh, à l'installation, à l'utilisation de l'interface Web et du SDK Python ; de l'écriture de votre premier plugin à la compréhension du cycle de vie des plugins, des services et des scopes, et du système d'événements ; de la conception de capacités avec le modèle à trois rôles et l'intégration de n'importe quel LLM, à l'empaquetage et à la publication. Enfin, ces cinq derniers articles complètent la dernière pièce du puzzle : la sécurité et la culture d'ingénierie.

Ce que vous retenez vraiment n'est pas seulement comment utiliser l'API, mais une façon de penser :

Le modèle est responsable de l'intelligence, le Harness est responsable de la fiabilité.Les contraintes ne sont pas des restrictions ; elles sont le fondement qui rend les Agents prévisibles, auditables et rejouables.

Tout est un plugin.Placez la politique aux points d'extension, pas à l'intérieur de la boucle, et le système peut évoluer sans perdre le contrôle.

Le vrai chemin d'entrée bat toutes les simulations.La couverture, les snapshots et les tests de fumée font chacun leur travail, et ensemble ils évitent le "tout est vert mais cassé".

L'échec ne fait pas peur. Ce qui fait peur, c'est de ne pas savoir pourquoi.La culture du post-mortem transforme un incident unique en un ensemble de défenses.

autres extensions