visual-primitives-mcp: Instructions file for Codex

Visual Primitives MCP — 架构文档

基于 DeepSeek《Thinking with Visual Primitives》论文的多模态视觉理解 MCP 服务器。核心创新：任务调度 + 两阶段推理——先让模型看清画面（describe），再基于完整上下文追问坐标（locate），每一步专注做好一件事。

---

1. 项目概述

将视觉模型的场景理解和坐标定位能力封装为 6 个专注 MCP 工具，通过任务调度机制实现两阶段精确空间推理。visual_describe 先理解场景 → visual_locate 再精确定位 → 两者通过共享会话上下文联动。

属性	值
运行时	Node.js >= 22.5.0
语言	TypeScript (strict)
MCP 协议	@modelcontextprotocol/sdk v1.x
HTTP 层	Hono（仅 SSE/HTTP Stream）
持久化	node:sqlite（内置）
校验	Zod
日志	pino（敏感字段脱敏）
测试	vitest（13 文件 176 用例）

---

2. 架构分层

┌──────────────────────────────┐
│         入口层 (src/)         │
│  server.ts / config.ts       │
│  types.ts                    │
├──────────────────────────────┤
│       传输层 (transport/)    │
│  factory.ts                  │
├──────────────────────────────┤
│      处理器层 (handlers/)    │
│  tool-handlers.ts (4 工具)   │
│  encodeFileBase64() 读文件   │
├──────────────────────────────┤
│       核心管道层 (core/)     │
│  ┌────────────────────────┐  │
│  │ pipeline.ts (任务调度)  │  │
│  │  describe | locate     │  │
│  │  ocr | video_analyze   │  │
│  │ parser.ts / validator  │  │
│  │ normalizer.ts          │  │
│  │ prompt-builder.ts      │  │
│  │ vision-client.ts       │  │
│  │ session-manager.ts     │  │
│  └────────────────────────┘  │
├──────────────────────────────┤
│       工具层 (utils/)        │
│  logger.ts / retry.ts        │
├──────────────────────────────┤
│       模板层 (templates/)        │
│  describe-structured.txt         │
│  locate-system.txt               │
│  ocr-system.txt                  │
└──────────────────────────────┘

---

3. 各层详解

3.1 入口层 (src/)

server.ts — 服务主入口

• 初始化链：SessionManager → VisionClient → PipelineOrchestrator → McpServer
• 注册 6 个视觉任务工具（describe/locate/ocr/video/compare/diagnose 均支持会话上下文注入）
• 根据 MCP_TRANSPORT 环境变量选择传输模式（stdio / sse / http-stream）
• Hono 仅在 SSE/HTTP Stream 模式动态加载，stdio 零开销
• 启动 60s 间隔的 TTL 会话清理定时器
• SIGINT/SIGTERM 优雅关闭：清定时器 → 关 SQLite → 退出