Защитное программирование в DeeSeek Harness: отчётность о результатах, очистка и учётные данные
После написания множества плагинов вы можете столкнуться с классом ошибок на граничных случаях, которые «невозможно воспроизвести в тестах, но которые взрываются в тот момент, когда попадают в продакшен».
Официальная документация объединяет их в «выстраданные правила категорий ошибок» — каждая из них — это ошибка, которая действительно попала в релиз или почти попала.
В этой статье рассматриваются пять наиболее важных паттернов защитного программирования: отчётность о результатах, перевод Dispose в состояние покоя, стирание учётных данных, удаление ссылок и изоляция обратных вызовов.
Одним предложением: эти паттерны предотвращают ситуацию, когда «простой граничный случай обрушивает всего агента».
Сначала взглянем на сравнительную диаграмму
На диаграмме ниже плохие примеры сравниваются бок о бок с хорошими примерами, каждый из которых взят из реальной категории ошибок.
Официальная документация называет эти паттерны правилами «обязательно прочитайте это перед написанием кода жизненного цикла, конкурентности, дочерних процессов или очистки».
Ортогональные результаты сообщаются независимо
Результат может одновременно обладать несколькими свойствами: процесс мог превысить время ожидания, но всё равно завершиться с кодом 0, потому что перехватил сигнал завершения.
Каждый независимый факт (timedOut、signal、exitCode) должен сообщаться отдельно.
Никогда не вкладывайте отчёт об одном флаге в ветку другого флага; иначе вызывающие могут принять досрочно завершённый запуск за нормальный успех.
Пример
// Запустить дочерний процесс и ортогонально сообщить о трёх независимых фактах: timedOut, signal, exitCode.
import { spawn, type ChildProcess } from 'node:child_process'
export interface RunResult {
timedOut: boolean // Независимый факт 1: истёк ли тайм-аут
signal: NodeJS.Signals | null // Независимый факт 2: был ли он завершён сигналом
exitCode: number | null // Независимый факт 3: код выхода
stdout: string
stderr: string
}
export function run(argv: string[], timeoutMs: number): Promise<RunResult> {
return new Promise((resolve, reject) => {
const child: ChildProcess = spawn(argv[0], argv.slice(1), {
stdio: ['ignore', 'pipe', 'pipe'],
})
let stdout = ''
let stderr = ''
child.stdout.on('data', (d: Buffer) => (stdout += d))
child.stderr.on('data', (d: Buffer) => (stderr += d))
// Независимый факт 1, поддерживаемый отдельно: timeout — это флаг, не связанный с кодом выхода.
let timedOut = false
const timer = setTimeout(() => {
timedOut = true
child.kill('SIGTERM') // Тайм-аут вызывает завершение
}, timeoutMs)
child.on('close', (code, signal) => {
clearTimeout(timer)
// Три поля возвращаются независимо: у процесса может быть timedOut=true и exitCode=0,
// Потому что он перехватывает SIGTERM после тайм-аута и завершается с 0.
resolve({ timedOut, signal, exitCode: code, stdout, stderr })
})
child.on('error', reject)
})
}
При таком стиле вызывающий код может комбинировать проверки:timedOutистинно, ноexitCodeЕсли это 0, это означает "принудительно завершён, но процесс замаскировал это нулём."
Если отчётность вложена, эту комбинацию невозможно выразить.
dispose должен достичь полностью остановленного состояния.
Если процесс очистки только отправляет сигнал terminate или abort и возвращается, не дожидаясь фактической остановки работы, он оставляет после себя осиротевшие процессы.
Логика очистки должна использовать асинхронный поток и ждать завершения дочернего процесса (отправить сигнал terminate, затем ждатьdone)。
Также следует закрыть реестры слушателей и реестры уведомлений перед завершением процесса, чтобы поздние события завершения не вызывали реакций.
Пример
// dispose должен полностью останавливаться: после отправки сигнала дождаться завершения дочернего процесса, а не возвращаться сразу после отправки сигнала.
import { once } from 'node:events'
import type { ChildProcess } from 'node:child_process'
export async function disposeQuiescent(child: ChildProcess): Promise<void> {
// 1. Сначала удалите слушателей, чтобы поздние события завершения не вызывали реакций.
child.removeAllListeners()
// 2. Запрос остановки: отправить сигнал завершения.
child.kill('SIGTERM')
// 3. Дождаться фактического завершения дочернего процесса; если он всё ещё не завершился после тайм-аута, перейти к SIGKILL.
// Promise.race гарантирует, что dispose не будет бесконечно зависать из-за дочернего процесса, который отказывается завершаться.
const forceKill = new Promise<void>((resolve) => {
setTimeout(() => {
child.kill('SIGKILL')
resolve()
}, 5_000)
})
await Promise.race([once(child, 'exit').then(() => undefined), forceKill])
}
Таким образом, когда dispose возвращает управление, дочерний процесс либо завершился, либо был принудительно завершён с помощью SIGKILL.
Очистка учётных данных: никогда не допускайте попадания переменных окружения в недоверенный вывод.
Запущенные команды должны использовать очищенное окружение, удаляя имена, совпадающие с*KEY*、*SECRET*、*TOKEN*или*PASSWORD*элементом.
В противном случае учётные данные тестового стенда могут утечь через вывод команды,envили утечки spill-файлов.
Временные файлы и spill-файлы следует размещать в приватном каталоге с правами 0700, использовать случайные имена файлов и открывать исключительно с доступом только для владельца ('wx'、0o600)。
Пример
// Очищайте переменные окружения перед запуском команды, чтобы учётные данные тестового стенда не утекли через вывод команды или окружение.
// Чувствительные элементы, соответствующие *KEY* *SECRET* *TOKEN* *PASSWORD*, все удаляются.
const SENSITIVE_NAME = /.*(?:KEY|SECRET|TOKEN|PASSWORD).*/i
export function scrubEnv(env: NodeJS.ProcessEnv): Record<string, string> {
const clean: Record<string, string> = {}
for (const [key, value] of Object.entries(env)) {
if (SENSITIVE_NAME.test(key)) continue // Пропускать чувствительные ключи напрямую
if (value !== undefined) clean[key] = value
}
return clean
}
// Использование:spawn(argv[0], argv.slice(1), { env: scrubEnv(process.env), ... })
В примере окружения,
DEEPSEEK_API_KEYТакие переменные должны проходить через этот путь удаления.Разрешить вывод команды,
envили файлы сброса, содержащие их, что равносильно передаче ключей любому, кто может прочитать вывод.
Удаляйте символические ссылки с помощью unlink.
Путь, который может быть символической ссылкой или соединением Windows, должен сначала использоватьlstatSync().isSymbolicLink()Проверить, затем использоватьunlinkSyncУдалить.
unlink удаляет только саму ссылку и отказывается работать с настоящими каталогами, поэтому он никогда не следует по ссылке к её цели.
Вызов junction в WindowsrmSync(link)Вызовет исключениеERR_FS_EISDIR; рекурсивное удаление может пройти через соединение внутрь его цели.
Только настоящие каталоги используют taperecursiveизrmSync。
Пример
// Удаляйте пути в виде ссылок с помощью unlink, никогда не переходите рекурсивно по ссылкам внутрь их целей.
import { lstatSync, rmSync, unlinkSync } from 'node:fs'
export function removePath(p: string): void {
// Сначала проверьте, является ли это символической ссылкой (или соединением Windows).
if (lstatSync(p).isSymbolicLink()) {
// unlink удаляет только саму ссылку и отказывается удалять фактические каталоги; он не переходит по ссылкам
unlinkSync(p)
return
}
// Только после подтверждения, что это фактический каталог, используйте rmSync с recursive.
rmSync(p, { recursive: true })
}
Изоляция исключений обратного вызова в диспетчере
Если предоставленный пользователем слушатель выбрасывает исключение, это не должно приводить к отклонению промиса, которому он принадлежит, и не должно приводить к голоданию слушателей, стоящих в очереди за ним.
Оберните цикл диспетчеризации в try/catch и логируйте ошибки.
Некорректно работающий подписчик никогда не должен нарушать основной жизненный цикл.
Пример
// Диспетчер изолирует исключения обратного вызова: плохой подписчик не может нарушить основной жизненный цикл.
export function dispatch(listeners: ReadonlyArray<() => void>): void {
for (const listener of listeners) {
try {
listener()
} catch (err) {
// Логировать и продолжать диспетчеризацию, никогда не отклонять и никогда не допускать голодания последующих слушателей.
console.error('[dispatch] ошибка слушателя:', err)
}
}
}
Этот паттерн встречается повсюду внутри dsh:session/eventсбои наблюдателя логируются и изолируются, вместо того чтобы позволять уже зафиксированным добавлениям завершаться ошибкой.
Это гарантирует, что "сбой плагина в его слушателе" не остановит весь цикл Agent.
Обзор других режимов
В официальной документации также отмечены ещё два, о которых стоит помнить:
| Mode | Правила |
|---|---|
| Обе стороны публичного контракта должны его соблюдать | При получении нескольких представлений одного и того же результата нормализуйте их перед возвратом через публичный API; потребителям не нужно догадываться, приходят ли исключения от провайдера, слоя-обёртки или из их собственной логики сборки |
| Асинхронное состояние — это не синхронное состояние | Неagent/statusилиwhenIdle()Как экземплярfollowup()результат; вызывающая сторона, которая действительно владеет запуском, должна явно определить интервал |
Тестовые аналоги этих правил (реальные точки входа, проверка фактических результатов, владение ресурсами) подробно описаны в testing.md, о чём будет рассказано в следующем посте.
Итоговая самопроверка
Защитное программирование заранее закрывает ловушки, склонные к сбоям на границах: ортогональное сообщение о результатах, полностью остановленный dispose, стирание учётных данных, безопасное удаление ссылок и изоляция исключений обратного вызова.
Вопросы для самопроверки:
| Проблема | Ссылка |
|---|---|
| У процесса истекло время ожидания, но код выхода равен 0 — что это значит? | Возможно, он перехватил сигнал завершения и самостоятельно завершился с кодом 0; timedOut и exitCode — два независимых факта. |
| В чём риск того, что при очистке дочернего процесса отправляется только SIGTERM и происходит возврат? | Это оставляет процессы-сироты; следует дождаться завершения, а затем при тайм-ауте перейти к SIGKILL. |
| Что следует использовать для удаления пути, который может быть символической ссылкой? | Сначала проверьте с помощью lstatSync, затем используйте unlinkSync; используйте rmSync recursive только для реальных каталогов. |