DeeSeek Harness: Revisión de Incidentes y Cultura de Ingeniería
El repositorio dsh convierte cada bug «que no debería haber aparecido pero apareció» en una revisión de incidente (postmortem), y deja protecciones a nivel de pruebas, documentación y reglas.
Si comprendes esta cultura de revisión y disciplina de pruebas, podrás aplicarla en el proyecto ejemplo: no solo sabrás usar dsh, sino que pensarás como un mantenedor.
En una frase: el valor de un bug no está en la línea de corrección, sino en por qué el proceso lo dejó pasar y qué protecciones se añadieron para que la próxima vez un problema similar falle de forma explícita.
Cultura de revisión: cuatro preguntas
Una revisión de incidentes documenta: un bug apareció donde no debía (usuarios reales, PRs fusionados, versiones publicadas).
Lo que importa espor qué nuestro proceso lo dejó pasar, y no solo la línea de la corrección.
Es un registro retrospectivo de fallos que responde a cuatro preguntas:
| Cuatro preguntas | Qué responder |
|---|---|
| Qué se rompió | Con un párrafo breve para que un lector ocupado capte lo esencial en treinta segundos |
| Cuál fue el mecanismo | Explicar la causa raíz con claridad, sin culpar a personas |
| Por qué ninguna red de seguridad lo detuvo | Identificar las brechas en pruebas, herramientas y convenciones, no un error tipográfico puntual |
| Qué protecciones se añadieron | Pruebas, reglas de AGENTS.md, ADR, para que la próxima vez un bug similar falle de forma explícita |
No todos los bugs merecen una revisión.
Solo se escribe cuando el bug cumple tres condiciones a la vez:Oculto(el mecanismo no es evidente; incluso un ingeniero cuidadoso debe reconstruirlo con esfuerzo),Sistémico(la causa de escape es una brecha en pruebas, herramientas o convenciones),Costo alto de redescubrimiento(consume tiempo real de depuración, y la próxima vez será igual).
Cuatro casos reales
El repositorio tiene actualmente cuatro revisiones de incidentes, cada una correspondiente a un tipo de error de ingeniería propenso a repetirse.
A continuación se presentan una por una, con énfasis en «por qué escapó» y «qué protecciones se añadieron».
Revisión 0001
El servidor ACP se bloquea al conectar: export default pierde el inject del plugin.
Qué se rompió: en cuanto el editor (Zed) se conecta, el primer
session/newreportacannot get property "agents" without inject。Mecanismo: el plugin escribió un export default de más
export default apply, y el import del LoaderunwrapExportsobtuvo la función desnuda, y el inject del namespaceinjectse perdió por completo.Por qué la red de seguridad no lo detuvo: 178 pruebas unitarias en verde + 100% de cobertura de líneas, pero todas pasan mediante
ctx.plugin(...)montaje manual, evitando la ruta de carga del Loader real.Protecciones añadidas: eliminar el default export; agregar una prueba de humo del Loader real que no requiere key; regla «prueba las rutas de entrada reales; la cobertura de líneas no equivale a la cobertura de comportamiento».
Revisión 0002
La utilidad de instantáneas del sistema de archivos fue deshabilitada permanentemente por un objeto literal !!js.
Qué se rompió: siete escenarios del sistema de archivos llamaron a una herramienta inexistente en el registro, y devolvió
UNKNOWN_TOOL。Mecanismo: el autor usó
disabled: !!js ...para habilitar condicionalmente el plugin del sistema de archivos, pero Cordis soloconfigevalúa expresiones JS en su interior; al leer directamentedisabledel elemento de configuración, ve un objeto truthy.Por qué la red de seguridad no lo detuvo: la actualización de instantáneas confundió «reproducción determinista» con «comportamiento correcto»: demostró que la regresión se reproducía de forma estable, pero no que la herramienta del sistema de archivos se hubiera registrado realmente.
Protecciones añadidas: cambiar a un overlay explícito del sistema de archivos; un guardián de configuración estática rechaza nodos de expresión en los metadatos de configuración del Loader; el marco de instantáneas rechaza resultados
UNKNOWN_TOOLestructurados.
Revisión 0003
El agente web aceptó un servidor alternativo, en lugar de la GUI que alojaba su sesión.
Qué se rompió: el agente modificó el código fuente de la GUI, pero no sabía a qué URL correspondía la sesión actual ni qué proceso la alojaba.
Mecanismo: tomó el HTTP 200 devuelto por Vite desnudo como éxito (cuando en realidad era una pantalla en blanco), y luego fue a aceptar el servidor alternativo en otro puerto
dsh webservidor, sin sondear nunca el puerto 3081.Por qué la red de seguridad no lo detuvo: la composición web no proporcionó al modelo la identidad de la GUI actual, la URL canónica ni el modo de ejecución; la primera prueba de regresión además usó «tiempo de espera del proceso» para hacerse pasar por «fallo rápido», generando un falso positivo.
Protecciones añadidas: el lanzador publica la URL de bucle local canónica y el modo real de producción/desarrollo (variables de entorno + sección del prompt); el modo de servidor Vite independiente se niega a iniciar en la fase de configuración; pruebas por capas de rutas reales cubren CLI, prompts, hechos de tiempo de ejecución y HMR del navegador.
Revisión 0004
Una notificación de aplicación parcial de Landlock provocó que los fallos de subprocesos se clasificaran erróneamente.
Qué se rompió: en kernels con ABI de Landlock más antigua, ripgrep termina normalmente con código de salida 1 cuando no hay coincidencias, pero se presentaba como
SANDBOX_UNAVAILABLEfallo de la sandbox.Mecanismo: el lanzador imprime una notificación inofensiva
landlock-run: partial enforcement (older Landlock ABI); el harness usa una subcadena que no distingue mayúsculas de minúsculaslandlock-run:para combinar la notificación con cualquier salida distinta de cero, clasificándola erróneamente como fallo del runner.Por qué la red de seguridad no lo detuvo: el tipo de resultado de la sandbox solo puede expresar un conjunto de subcadenas, no puede expresar «un fallo de Landlock debe tener código de salida 125 + una línea de diagnóstico fatal»; la matriz de pruebas nunca construye la combinación «notificación seguida de una salida de subproceso distinta de cero».
Protecciones añadidas:
RunnerFailureRulellevar códigos de salida permitidos, firmas fatales línea por línea y líneas informativas con exclusiones precisas; la búsqueda en el sistema de archivos cambió actx.subprocessejecutar ripgrep empaquetado, sin pasar por bash dentro de la sandbox.
Al ver los cuatro casos en conjunto, se puede resumir una lección común:Las pruebas deben recorrer las rutas de entrada reales。
Montaje manual, burlar todo, usar la actualización de instantáneas como aceptación: todo esto hace posible que «las unidades estén en verde, pero el producto esté roto».
Cuatro capas de pruebas
La estrategia de pruebas del repositorio es por capas; cada capa cubre los puntos ciegos que la capa anterior no puede detectar.
| Nivel | Comando | Qué detecta |
|---|---|---|
| Pruebas unitarias | pnpm run test | vitest ejecuta pruebas dentro del paquete, priorizando límites, rutas de error, orden de eventos y condiciones de carrera. |
| Puerta de cobertura | pnpm run test:coverage | Cobertura del 100% por archivo; las líneas no cubiertas suelen ser código muerto que debería eliminarse. |
| e2e con API real | pnpm run test:e2e | Llamar a la API real del proveedor con credenciales; si faltan, se omite automáticamente, manteniendo la CI sin claves en verde. |
| Instantáneas | pnpm run test:snapshot / test:web | La salida esperada sin claves cubre el comportamiento externo; las instantáneas de navegador se comparan mediante reproducción con Chromium. |
El repositorio es de DeepSeek, por lo que hay un principio especial:La inferencia es barata aquí; no escatimes en pruebas con API real.。
Las pruebas sin claves solo demuestran la vía subyacente; solo ejecutando con claves se demuestra que el agente puede trabajar correctamente con el modelo real.
Las más valiosas son las pruebas de humo: arrancar un ejemplo real, enviar un prompt y verificar el mundo exterior.
Capturan problemas como «pruebas unitarias en verde, producto roto» que los mocks no pueden detectar.
La cobertura de líneas es una condición necesaria, nunca suficiente.
Demuestra que las líneas se ejecutaron, no que la funcionalidad funcione según lo esperado en la entrega.
En el caso 0001, la cobertura del 100% aún dejó pasar dos bugs de integración; es la mejor nota al pie.
Otro principio esverificar el mundo exterior, no el autoinforme。
Las aserciones e2e deben volver a ejecutar el comando o releer el archivo desde el exterior; detectar palabras clave en la salida del propio agente permite que agentes tramposos pasen.
Los archivos que no se modificaron deben coincidir byte a byte en las aserciones.
Disciplina de documentación: un hecho, un hogar
La documentación del repositorio no se termina al escribir; hay un mecanismo para evitar la «deriva entre documentación y código fuente».
verify-type-equivEs una puerta de control: utiliza un analizador de TypeScript para extraer del código fuente los símbolos de las declaraciones de tipos y sus JSDoc adjuntos, y verifica que los bloques de código de la documentación coincidan con ambos.
Cuando modificas una declaración de tipo documentada o su JSDoc, la puerta falla hasta que actualices el contenido pegado.
Esto garantiza que las definiciones de tipos en la documentación siempre coincidan con el código fuente; nunca aparece «la documentación copia una versión anterior».
Otra disciplina esun hecho, un hogarCada hecho se mantiene en un solo archivo, y el resto de archivos lo referencian.
Por ejemplo, la «fuente de verdad» del esquema de la herramienta está enadding-a-tool.md, otras páginas lo referencian sin copiarlo.
Los documentos en chino e inglés se mantienen mediante pares bilingües; al actualizar, primero se ejecutapnpm run gen-doc-graphsse actualiza el inglés, luego se actualiza el chino y se verifica el emparejamiento.
Esto también aplica a tus propios proyectos: coloca la «fuente de verdad» en un solo lugar, no dejes que la misma configuración esté dispersa en tres documentos.
Ejemplo práctico: escribe un resumen ejecutivo de treinta segundos
Cada retrospectiva comienza con un resumen ejecutivo para que los lectores ocupados absorban los puntos clave en treinta segundos.
Intenta revisar una incidencia de Agent que encontraste en el proyecto ejemplo, siguiendo la siguiente plantilla:
# 复盘 0005:ejemplo 演示环境的工具黑名单没有生效 ## 摘要 demo 环境里模型仍能调用被禁用的 fs_write,直接写入了工作区。 根因是黑名单插件用 `tools/pre-execute` 返回了 `next()`, 而真正负责拦截的守卫注册在插件卸载之后——加载顺序错了。 逃逸原因是加载顺序没有测试覆盖,`cordis.yml` 只测了「能起来」。 新增防护:给黑名单插件补一条「顺序敏感」的装配测试, 并在 AGENTS.md 记录「pre-execute 与 guard 的注册顺序」规则。
La fórmula del resumen de treinta segundos: qué falló → explica la causa raíz en palabras sencillas → por qué escapó → la lección que se puede aplicar a largo plazo.
Conclusión de la serie
Hasta aquí, terminan los 28 artículos del tutorial de introducción a DeepSeek Harness.
Mirando hacia atrás en este camino: desde el artículo 1, conociendo las cuatro salvaguardas de dsh, hasta aprender a instalar, usar la Web UI y el Python SDK; desde escribir el primer plugin, hasta comprender el ciclo de vida de los plugins, servicios y ámbitos, y el sistema de eventos; desde usar el modo de tres roles para diseñar capacidades e integrar cualquier LLM, hasta empaquetar y publicar; estos últimos cinco artículos completan la última pieza del rompecabezas: la seguridad y la cultura de ingeniería.
Lo que realmente te llevas no es solo el uso de la API, sino una forma de pensar:
El modelo se encarga de la inteligencia, Harness se encarga de la confiabilidad.Las restricciones no son limitaciones, sino la base que hace que el Agent sea predecible, auditable y reproducible.
Todo es un plugin.Coloca las políticas en los puntos de extensión, no dentro del bucle principal, para que el sistema pueda evolucionar sin perder el control.
Las rutas de entrada reales superan a cualquier mock.La cobertura, las instantáneas y las pruebas de humo cumplen cada una su función, y juntas previenen el «todo en verde pero roto».
Las fallas no dan miedo; lo que da miedo es no saber por qué ocurrieron.La cultura de retrospectiva convierte un incidente en un sistema de protección.
Otras extensiones