Постмортемы 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 test | Vitest запускает внутрипакетные тесты, отдавая приоритет граничным случаям, путям ошибок, порядку событий и гонкам при конкурентном выполнении. |
| Порог покрытия | pnpm run test:coverage | 100% покрытия на файл; непокрытые строки обычно являются мёртвым кодом, который следует удалить. |
| Реальный API e2e | pnpm 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 — за надёжность.Ограничения — это не запреты; это основа, которая делает агентов предсказуемыми, аудируемыми и воспроизводимыми.
Всё — плагин.Размещайте политику в точках расширения, а не внутри цикла, и система сможет развиваться, не теряя контроля.
Реальный путь входа побеждает все моки.Покрытие, снимки и дымовые тесты — у каждого своя работа; вместе они предотвращают «всё зелёное, но сломано».
Сбой — это не страшно. Страшно — не знать почему.Культура постмортемов превращает отдельный инцидент в набор защитных мер.
Другие расширения