Постмортемы DeeSeek Harness и инженерная культура

Репозиторий dsh превращает каждый баг, который «не должен был случиться, но случился», в постмортем и оставляет защиты на уровнях тестов, документации и правил.

Поймите эту культуру постмортемов и дисциплину тестирования, и вы сможете применить их в примере проекта: не просто использовать dsh, а думать как мейнтейнер.

Одной фразой: ценность бага не в исправлении в одну строку, а в том, почему процесс позволил ему проскочить, и какая защита была добавлена, чтобы похожие проблемы громко падали в следующий раз.


Культура ретроспектив: четыре вопроса

Постмортем фиксирует: баг появился там, где его не должно было быть — перед реальными пользователями, в смерженном PR или в выпущенной версии.

Что стоит отметить — этоПочему наш процесс позволил этому пройти?, а не просто то исправление в одну строку.

Это ретроспективный разбор неудачи, отвечающий на четыре вопроса:

Четыре вопросаЧто нужно ответить
Что сломано?Короткий абзац, который позволяет занятым читателям усвоить ключевые моменты за тридцать секунд.
В чём механизм?Сформулируйте первопричину простыми словами, не обвиняя конкретных людей.
Почему ни одна страховочная сеть не поймала этоОпределите пробелы в тестах, инструментах и соглашениях — а не разовую опечатку.
Какие новые защиты были добавленыТесты, правила AGENTS.md, ADRs — сделайте так, чтобы похожие баги в следующий раз громко заявляли о себе.

Не каждый баг заслуживает постмортема.

Пишите его, только когда баг соответствует всем трём условиям:Скрытый(механизм неочевиден; даже внимательному инженеру пришлось бы изрядно потрудиться, чтобы вывести его заново),Системный(причина, по которой он ускользнул, — пробел в тестах, инструментах или соглашениях),Цена повторного обнаружения высока(оно отняло реальное время на отладку и отнимет снова в следующий раз).

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


Четыре реальных случая

В репозитории сейчас четыре постмортема, каждый из которых соответствует классу инженерных ошибок, склонных повторяться.

Я разберу каждый из них, сосредоточившись на «почему он ускользнул» и «какая защита была добавлена».

Ревью 0001

ACP сервер падает при подключении: export default сбрасывает inject плагина.

Что сломалось: в момент, когда редактор (Zed) подключился, первыйsession/newПросто сообщитьcannot get property "agents" without inject。

Механизм: плагин записал один лишний.export default apply, LoaderunwrapExportsОн извлёк голую функцию и ту, что в пространстве имён...injectПотерял её полностью.

Почему страховочная сеть не поймала это: 178 зелёных модульных тестов + 100% покрытия строк были на месте, но каждый тест вручнуюctx.plugin(...)монтировался, минуя реальный путь загрузки Loader.

Добавлены защиты: удалён default export; добавлен smoke-тест без ключа с реальным Loader; правило: «тестируйте реальный входной путь — покрытие строк не равно покрытию поведения».

Ревью 0002

Инструмент снимков файловой системы был навсегда отключён из-за литерального объекта !!js.

Что сломалось: семь сценариев файловой системы вызывали инструмент, которого нет в реестре, возвращая...UNKNOWN_TOOL。

Механизм: автор используетdisabled: !!js ...Мы хотели условно включить плагин файловой системы, но Cordis вычисляет только JS-выраженияconfigвнутри плагина; при прямом чтенииdisabledэлемента конфигурации, он увидел truthy-объект.

Почему страховочная сеть не поймала это: обновление снимка рассматривало «детерминированное воспроизведение» как «корректное поведение» — оно доказало, что регрессия стабильно воспроизводится, но не доказало, что инструмент файловой системы действительно зарегистрирован.

Добавлены защиты: переключились на явный оверлей файловой системы; статическая защита конфигурации отклоняет узлы выражений в метаданных конфигурации Loader; фреймворк снимков отклоняет структурированныеUNKNOWN_TOOLРезультат.

Обзор 0003

Веб-агент принял заменяющий сервер вместо GUI, в котором размещалась его сессия.

Что сломалось: агент изменил исходный код GUI, но не знал, какому URL соответствовала текущая сессия или какой процесс её обслуживал.

Механизм: он воспринимал HTTP 200, возвращённый чистым сервером Vite, как успех (на самом деле пустой экран), а затем переходил к принятию заменыdsh webсервер на другом порту, так и не проверив порт 3081.

Почему страховочная сеть это не поймала: веб-композиция не предоставила модели идентификационную информацию о текущем GUI, каноническом URL или режиме работы; первый регрессионный тест также использовал "process timeout", чтобы выдать себя за "fail fast", что привело к ложноположительному результату.

Добавить защиту: StartdevicepublishSpecificationCycle возвращает URL и реальный фактический production/DevelopmentMode (переменные среды + сегмент области Hintword); Independent Vite ServicesModeInConfigurationPhaseRejectStart; DividelayertruerealpathTesting охватывает CLI, Hintword, runtime-события real и HMR браузерного устройства.

Ревью 0004

Уведомления Landlock о частичном применении приводили к неверной классификации сбоев дочерних процессов.

Что сломалось: на ядрах с более старым ABI Landlock ripgrep нормально завершается с кодом 1, когда совпадений нет, но это было представлено как сбой.SANDBOX_UNAVAILABLEСбой песочницы.

Механизм: лаунчер выводит безобидноеlandlock-run: partial enforcement (older Landlock ABI)уведомление; тестовый стенд использует нечувствительный к региструlandlock-run: подстроку в сочетании с любым ненулевым кодом завершения, чтобы неверно классифицировать это как сбой runner.

Почему страховочная сеть это не поймала: тип результата песочницы может выражать только набор подстрок; он не может выразить "сбой Landlock должен завершаться с кодом 125 + одна строка фатальной диагностики"; тестовая матрица никогда не конструирует комбинацию "уведомление, за которым следует ненулевое завершение подпроцесса".

Добавить защиту:RunnerFailureRuleПередавать информационные строки с разрешёнными кодами выхода, построчными сигнатурами фатальных ошибок и точными исключениями; поиск по файловой системе переключается на...ctx.subprocessЗапускать встроенный ripgrep, больше не пропуская его через bash в песочнице.

Рассматривая четыре случая вместе, можно извлечь общий урок:Тесты должны проходить через реальный путь входа。

Ручное монтирование, мокирование всего и отношение к обновлению снапшотов как к приёмке — всё это делает возможным «все unit-тесты зелёные, продукт сломан».


Четыре уровня тестов

Стратегия тестирования репозитория многослойна; каждый слой покрывает слепые зоны, которые не может поймать предыдущий слой.

УровеньКомандаЧто фиксировать
Модульное тестированиеpnpm run testVitest запускает внутрипакетные тесты, отдавая приоритет граничным случаям, путям ошибок, порядку событий и гонкам при конкурентном выполнении.
Порог покрытияpnpm run test:coverage100% покрытия на файл; непокрытые строки обычно являются мёртвым кодом, который следует удалить.
Реальный API e2epnpm run test:e2eВызывает реальные API провайдеров с ключами; автоматически пропускает, когда ключи отсутствуют, сохраняя зелёный CI без ключей.
Снимокpnpm run test:snapshot / test:webОжидаемые результаты без ключей покрывают внешнее поведение; браузерные снимки воспроизводятся и сравниваются с помощью Chromium.

Это собственный репозиторий DeepSeek, поэтому есть один особый принцип:Инференс здесь дёшев, не экономьте на тестах с реальными API.。

Тесты без ключей могут доказать только работу базового пути; только запуск с ключами может доказать, что агент корректно работает с реальной моделью.

Наибольшую ценность представляют дымовые тесты: запустить реальный пример, отправить один промпт и проверить внешний мир.

Они ловят класс проблем «все модульные тесты зелёные, а продукт сломан», который моки не могут обнаружить.

Покрытие строк — необходимое условие, но никогда не достаточное.

Оно доказывает, что строка была выполнена, а не то, что функциональность работает так, как поставляется.

В случае 0001 100% покрытие всё равно пропустило две интеграционные ошибки — идеальная сноска.

Ещё один принцип:Проверяй внешний мир, а не самоотчёт。

E2E-проверки должны повторно запускать команду или повторно читать файл извне; проверка по ключевым словам собственного вывода агента позволила бы жульничающему агенту пройти.

Проверять, что неизменённые файлы остаются побайтово идентичными.


Дисциплина документации: один факт — одно место.

Документация репозитория не является "готовой после написания"; механизм предотвращает "расхождение документации и исходного кода".

verify-type-equivЭто шлюз: он использует парсер TypeScript, чтобы извлечь из исходного кода символы объявлений типов и привязанный к ним JSDoc, и проверяет, что блоки кода в документации соответствуют и тому, и другому.

Когда вы меняете документированное объявление типа или его JSDoc, шлюз не проходит, пока вы не обновите вставленное содержимое.

Это гарантирует, что определения типов в документации всегда соответствуют исходному коду — никаких "документов, скопированных из старой версии".

Ещё одна дисциплина —один факт, одно место: каждый факт поддерживается ровно в одном файле; все остальные файлы ссылаются на него.

Например, "источник истины" для схемы инструмента находится вadding-a-tool.md, другие страницы ссылаются на неё, а не копируют.

Китайские и английские документы поддерживаются как двуязычные пары; при обновлении сначала запустите...pnpm run gen-doc-graphsОбновите английский, затем обновите китайский и проверьте соответствие пары.

Это относится и к вашим собственным проектам: держите "единственный источник истины" в одном месте; не разбрасывайте одну и ту же конфигурацию по трём документам.


Практический пример: напишите тридцатисекундное резюме для руководства.

Каждый постмортем начинается с резюме для руководства, чтобы занятой читатель мог усвоить ключевые моменты за тридцать секунд.

Попробуйте написать постмортем для сбоя агента, с которым вы столкнулись в примере проекта, используя приведённый ниже шаблон:

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

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

Формула тридцатисекундного резюме: что сломалось → первопричина простыми словами → почему это осталось незамеченным → урок, который можно перенести в долгосрочную перспективу.


Заключение серии

На этом завершаются все 28 выпусков вводного руководства по DeepSeek Harness.

Оглянитесь на пройденный путь: от первой статьи, изучения четырёх защитных барьеров dsh, до установки, использования Web UI и Python SDK; от написания первого плагина до понимания жизненного цикла плагинов, сервисов и областей видимости, а также системы событий; от проектирования возможностей с помощью паттерна трёх ролей и интеграции любой LLM до упаковки и выпуска. Наконец, эти последние пять статей завершают последний фрагмент головоломки: безопасность и инженерную культуру.

Что вы действительно выносите, так это не просто умение пользоваться API, а образ мышления:

Модель отвечает за интеллект, Harness — за надёжность.Ограничения — это не запреты; это основа, которая делает агентов предсказуемыми, аудируемыми и воспроизводимыми.

Всё — плагин.Размещайте политику в точках расширения, а не внутри цикла, и система сможет развиваться, не теряя контроля.

Реальный путь входа побеждает все моки.Покрытие, снимки и дымовые тесты — у каждого своя работа; вместе они предотвращают «всё зелёное, но сломано».

Сбой — это не страшно. Страшно — не знать почему.Культура постмортемов превращает отдельный инцидент в набор защитных мер.

Другие расширения