Mailflow

Haga que los correos electrónicos de Outlook clásico activen de manera confiable sesiones y prompts de OpenCode, mientras proporciona al agente de OpenCode un conjunto controlado de herramientas MCP de correo.

Mailflow no vuelve a integrar la escucha de correo, reglas, invocación de sesiones, aprobación e interfaz de usuario en un gran complemento. La primera versión utiliza un Core independiente, un conector de Outlook para Windows, un adaptador HTTP de OpenCode y MCP de responsabilidad limitada; el win-console original permanece sin cambios, y se proporcionan herramientas de compatibilidad y una ruta de migración prioritaria con dry-run.

Forma final

flowchart LR
  O["Outlook Classic<br/>Windows 用户会话"] -->|"标准化邮件 / Outlook 命令"| C["Mailflow Core<br/>SQLite · 规则 · 队列 · 审批"]
  C -->|"创建 session + prompt_async"| OC["OpenCode Server"]
  OC --> A["OpenCode 会话 / Agent"]
  A -->|"stdio MCP"| M["Mailflow MCP"]
  M -->|"受 token 保护的 API"| C
  C -->|"草稿 / 导出 / 经审批发送"| O
  UI["本地中文管理台"] --> C
  WC["原 win-console"] -. "兼容工具 / 能力注册 / 可回滚迁移" .-> C

Los límites son claros:

• El conector de Outlook solo se encarga de la adaptación de datos de Outlook, la entrega confiable y las acciones nativas de Outlook; el mecanismo de transporte específico no es un contrato del Core.

• Core es la única fuente de verdad, responsable de SQLite, versiones de reglas, idempotencia, reintentos, auditoría, aprobación y comandos del conector.

• Core llama directamente a la API HTTP de OpenCode para crear sesiones y enviar prompts de forma asíncrona.

• MCP solo proporciona herramientas de lectura de correo, exportación de archivos adjuntos, borradores de respuesta y envío aprobado para el agente dentro de la sesión; no escucha la bandeja de entrada.

• El panel de administración se encarga de reglas, ejecución, aprobación y recuperación de fallos, sin depender del panel de Outlook.

¿Complemento de Outlook o complemento de OpenCode?

La primera versión no hace "complementos pesados" en ninguno de los dos lados. Esta es una elección deliberada:

Por lo tanto: el contenido de diseño ciertamente puede mostrarse en el panel de extensión de Outlook, pero el núcleo no debe colocarse allí. Los complementos VSTO/COM de Outlook clásico se ven afectados por la arquitectura de Office, la firma, la desactivación de carga y el ciclo de vida del proceso. La versión entregable actual utiliza un conector COM independiente con bandeja de sistema; cuando se agregue un panel VSTO delgado más adelante, no será necesario modificar Core, MCP ni la base de datos. El complemento de OpenCode también es una capa de experiencia opcional; la activación de sesiones ya se realiza a través de una API HTTP estable.

v0.1.0 ya incluye

• Node.js 24 + Core sin dependencias de tiempo de ejecución con SQLite integrado.

• Almacenamiento de eventos de correo, coincidencia de reglas, versiones de reglas, máquina de estados de ejecución, clave de idempotencia, arrendamiento, reintento con retroceso exponencial y dead letter.

• Creación de sesión de OpenCode y prompt_async, con soporte para estrategias por mensaje, por conversación y sesión fija.

• Envoltorio de seguridad de prompt: el contenido del correo se marca explícitamente como datos no confiables, con soporte para límites de cuerpo/archivos adjuntos.

• Servidor MCP stdio estándar, y alias de herramientas antiguas como outlook_search, outlook_read, outlook_attachments.

• Conector de Outlook Classic para Windows x64: entrega de correo, lectura/escritura nativa de Outlook, idempotencia de comandos y conciliación de envío.

• Bucle de seguridad send_unknown: 5 comprobaciones de retraso acotado, confirmación manual del panel de administración, y "generar una nueva aprobación después de confirmar que no se envió"; ninguna comprobación reenviará automáticamente.

• Los borradores de respuesta primero sincronizan Outlook y luego abren la aprobación; el hash normalizado del asunto, destinatarios y cuerpo evita el envío de borradores antiguos, el envío automático está desactivado por defecto.

• Panel de administración en chino, API REST y flujo de estado SSE.

• Importación dry-run de reglas/estado de win-console, registro de capacidades/latido y ruta de reversión explícita.

• Pruebas de Core en Linux, compilación del conector de Windows y flujo de trabajo de lanzamiento de GitHub impulsado por etiquetas.

Inicio rápido

1. Descargar

Obtenga desde GitHub Releases:

• email-workflow-0.1.0-runtime.zip: Core, MCP, panel de administración, documentación y código fuente del conector;

• email-workflow-0.1.0-outlook-classic-win-x64.zip: Conector de Windows x64 autocontenido;

• aleygey-email-workflow-0.1.0.tgz: Paquete de ejecución en formato npm.

Core requiere Node.js 24+; el conector requiere Windows x64 con Outlook de escritorio clásico.

2. Primero inicializar las claves y fusionar la configuración de seguridad de OpenCode

No inicie OpenCode primero, ni sobrescriba el opencode.json/opencode.jsonc existente con archivos de ejemplo. Primero genere .env en el directorio de descompresión del runtime:

node dist/src/cli.js init --output .env

Fusione agent.mailflow-email y mcp.mailflow de examples/opencode-mailflow-complete.json en la configuración existente de OpenCode, conservando el provider, model, agent, plugin y otros MCP existentes. Los usuarios del runtime zip deben cambiar el command en el ejemplo a la ruta absoluta de su máquina, por ejemplo:

"command": ["node", "C:\\Mailflow\\email-workflow\\dist\\src\\mcp\\cli.js"]

El ejemplo no contiene secretos incrustados. El entorno del mismo usuario que inicia OpenCode debe tener configurado MAILFLOW_MCP_TOKEN, con el mismo valor que MAILFLOW_API_TOKEN en .env; no es el token del conector:

$env:MAILFLOW_MCP_TOKEN = "<复制 .env 中 MAILFLOW_API_TOKEN 的值>"

MAILFLOW_CONNECTOR_TOKEN es solo para el conector de Outlook y debe ser diferente del token de API/MCP. init rechaza por defecto sobrescribir un .env existente.

3. Iniciar OpenCode

opencode serve --hostname 127.0.0.1 --port 4096

OpenCode debe iniciarse desde el entorno donde se acaba de configurar MAILFLOW_MCP_TOKEN para poder resolver {env:MAILFLOW_MCP_TOKEN} en el ejemplo.

4. Iniciar Mailflow Core

Modifique la dirección de OpenCode en .env según sea necesario, luego inicie en el directorio de descompresión del runtime:

node --env-file=.env dist/src/cli.js serve

La ejecución de lanzamiento requiere configurar dos tokens no vacíos y diferentes; no se admite tener un Core sin autenticación como modo de inicio predeterminado. Los valores predeterminados son OPENCODE_MAILFLOW_AGENT=mailflow-email y OPENCODE_REQUIRE_SAFE_AGENT=true, no desactive la verificación para "hacerlo funcionar primero".

Acceda a http://127.0.0.1:8798. La primera vez que ingrese al panel de administración, guarde el token de API en "Configuración".

Para ejecutar desde el código fuente:

npm ci
npm run check
npm run dev

5. Iniciar el conector de Outlook

Descomprima el conector de Windows, copie connector.example.json como:

%LOCALAPPDATA%\Mailflow\OutlookConnector\connector.json

Configure el mismo token de conector que Core, mantenga coreBaseUrl como http://127.0.0.1:8798, luego ejecute:

.\mailflow-outlook-connector.exe

Consulte el manual de operación para la configuración completa, transferencia de claves y pasos de solución de problemas.

Cómo un correo se convierte en una sesión

1. El conector envía el correo según un contrato estable; Core lo recibe, lo desduplica por ID de conector/evento; la forma interna de ingesta/recuperación del conector no entra en el contrato de negocio.

2. Core normaliza el correo, lo guarda en SQLite y ejecuta la coincidencia contra la versión fija de las reglas habilitadas.

3. Si hay coincidencia, se crea una ejecución con una clave de idempotencia estable; el worker toma el arrendamiento de la ejecución; si está fuera de línea, reintenta con retroceso exponencial.

4. El adaptador de OpenCode crea o reutiliza una sesión, y agrega la marca estable mailflow_run_id al prompt.

5. Core verifica que el agente mailflow-email de destino exista y tenga permisos de fail-closed antes de cada envío de prompt; si el agente necesita información del correo, llama de vuelta a Core a través de las herramientas MCP de solo lectura aprobadas.

6. La respuesta de IA se sincroniza primero como borrador de Outlook; la aprobación aparece solo después de una sincronización exitosa. Al aprobar, se verifican simultáneamente la versión del borrador de Core y el hash normalizado del asunto/destinatarios/cuerpo de Outlook; cada paso escribe un registro de auditoría.

Valores predeterminados de seguridad

• Core escucha solo en 127.0.0.1 por defecto; las conexiones de OpenCode solo aceptan HTTP de bucle local o HTTPS. HTTP remoto en texto plano se rechaza por defecto.

• En el primer inicio, se debe ejecutar node dist/src/cli.js init --output .env; Core exige que el token de API y el token del conector existan simultáneamente, sean diferentes entre sí, tengan al menos 32 bytes UTF-8 cada uno, y rechaza los marcadores de posición públicos de los ejemplos. MCP usa el token de API a través de MAILFLOW_MCP_TOKEN; el conector solo usa el otro conjunto de tokens.

• Todas las solicitudes de escritura de Core con cuerpo deben declarar Content-Type JSON; las solicitudes no JSON devuelven directamente 415.

• El agente predeterminado es mailflow-email. Core lee la definición del agente desde OpenCode antes de cada envío de prompt: primero debe tener un límite de denegación * catch-all, luego solo puede enumerar read/glob/grep/list dentro del workspace, denegaciones de *.env/*.env.* que cubren cualquier nivel de directorio, y las herramientas MCP de Mailflow de solo lectura nombradas explícitamente en el ejemplo. La lista blanca de MCP de solo lectura es search/get/list-attachments/get-run y los legacy search/read de solo lectura; outlook_attachments, que puede exportar archivos, no está incluida. La ausencia del agente, una respuesta de permisos no reconocible o cualquier otro allow provocarán un fail-closed.

• Las reglas se crean desactivadas por defecto; primero previsualice, luego habilite.

• El cuerpo del correo son datos, no instrucciones; los archivos adjuntos solo exponen metadatos por defecto.

• Las respuestas requieren aprobación humana. La respuesta de IA primero debe completar la sincronización del borrador de Outlook; modificar en la interfaz de aprobación invalida la aprobación anterior, pone en cola draft.update, genera una nueva aprobación después de la sincronización exitosa, y el usuario debe hacer clic en aprobar nuevamente. Después de la aprobación, si el asunto, Para/CC/CCO o el cuerpo en Outlook cambian, el hash normalizado no coincidirá y evitará el envío.

• Cuando el resultado de MailItem.Send() entre procesos es incierto, entra en send_unknown. Core solo realiza 5 comprobaciones de estado retrasadas; el panel de administración puede "Verificar Outlook", "Confirmar enviado" o "Confirmar no enviado". Después de confirmar que no se envió, la aprobación anterior se invalida y se genera una nueva aprobación, que aún requiere otro clic; el sistema nunca convierte la conciliación en un reenvío automático.

• La importación de datos antiguos es dry-run por defecto; la importación aplicada requiere --apply explícito.

El agente de solo lectura de la versión actual aún puede leer el workspace seleccionado y consultar otros correos en este Core a través de las herramientas MCP aprobadas; no es un sandbox de datos independiente por ejecución. SQLite también conserva continuamente el cuerpo del correo y las instantáneas originales; v0.1.0 no tiene una tarea de limpieza automática del período de retención. El uso en producción debe configurar un workspace/buzón de permisos mínimos dedicado, cuentas de modelo controladas, ACL de directorios de Windows, cifrado de disco completo y un período de retención de datos gestionado por operaciones; el aislamiento estricto entre proyectos/buzones requiere capacidades por ejecución en el futuro. Consulte SECURITY.md.

MAILFLOW_ALLOW_UNAUTHENTICATED_LOOPBACK=1, OPENCODE_ALLOW_INSECURE_REMOTE=1 y OPENCODE_REQUIRE_SAFE_AGENT=false son solo para diagnóstico de desarrollo local aislado, no son configuraciones de lanzamiento y no deben usarse para procesar correos reales.

No exponga Core o el servidor de OpenCode directamente a la red pública. Para implementaciones entre Windows/WSL o entre máquinas, use HTTPS, restricciones de origen y firewall. Más detalles en SECURITY.md.

win-console no desaparecerá

El repositorio antiguo no se elimina, no se sobrescribe, no se modifica el historial. Mailflow proporciona adicionalmente:

• Alias de compatibilidad para nombres de herramientas MCP antiguas;

• Registro de external-capabilities y latido;

• Informes de migración de reglas, recibos procesados, colas y checkpoint;

• Dry-run por defecto, apply explícito, SHA-256 del archivo fuente y mapeo de destino;

• Pasos para evitar doble activación durante el cambio y reversión lógica con un solo clic.

Consulte el mapeo completo elemento por elemento en docs/legacy-win-console-baseline.md.

Navegación de documentación

• Diseño completo: Interfaz de usuario, seis flujos completos, API, datos, seguridad, pruebas e implementación por fases.

• Límites de arquitectura: Por qué dividir en Core, conector, adaptador, MCP y UI opcional.

• Manual de operación: Instalación, configuración de OpenCode/MCP, copia de seguridad, migración, reversión y solución de problemas.

• Línea base de compatibilidad de win-console: Funciones antiguas, datos antiguos y requisitos de reversión.

• Notas de la versión v0.1.0.

Desarrollo y verificación

npm ci
npm run typecheck
npm test
npm run pack:release

Conector de Windows:

dotnet build connector/Mailflow.OutlookConnector/Mailflow.OutlookConnector.csproj -c Release

Dado que el COM de Outlook depende del perfil de usuario real de Windows, CI se encarga de la compilación de Windows y las pruebas no COM; antes del lanzamiento, aún se debe realizar una prueba de humo en el Outlook clásico de la máquina de destino que incluya conexión, ingesta de correo, sincronización de borradores, aprobación secundaria y envío.

Licencia

MIT