# 轻量 MVC Web 重构

日期：2026-08-14

# 目标

在不引入 Spring Boot 的前提下，将 JDK HttpServer Web 层整理为轻量 MVC。保持既有 API、SSE 与工作区安全行为不变，避免 WebMain 再次成为端点和运行逻辑的集中点。

# 结构

piagent.web
├── WebMain                       启动、日志、依赖装配、路由注册
├── controller/
│   ├── SessionController         status/history/reset/sessions/model
│   ├── ChatController            chat/pause/continue/pending 的 HTTP 校验与响应
│   ├── ArtifactController        artifacts 内容和工作区边界
│   ├── TraceController           traces 查询
│   └── InteractionController     tool approvals
├── service/
│   └── AgentChatService          AgentLoop、SSE、暂停、ask_user 续跑生命周期
├── runtime/
│   └── WebRuntime                共享会话、模型、工具、Trace 与运行取消状态
└── support/
    ├── WebSseEventWriter         AgentEvent 到浏览器 SSE
    └── WebHttp                   CORS、JSON、OPTIONS、SSE 基础设施

# 约束

• Controller 不直接编排 AgentLoop；AgentChatService 负责同一会话锁、SSE 输出、取消令牌和 ask_user 恢复。
• WebRuntime 只保存 Web 运行资源，不取代 core 的协议模型，也不将 SessionStore/AgentState 搬入 web。
• ArtifactController 和 WebSseEventWriter 继续复用同一工件元数据/工作区校验，避免 HTTP 抽屉与实时工具卡出现不一致。
• 保持 JDK HttpServer：当前没有数据库事务、复杂鉴权过滤器或多版本 REST 需求，不为结构引入 Spring 运行时。
• WebMain 的路由注册按“会话管理 / 工件与链路 / 对话生命周期 / 工具审批”分组注释；注释说明状态边界，而非逐行复述 URL。

# 验证

• mvn -pl pi-agent-v1 clean test：通过。
• 后续使用 Mock 模型进行 /api/status、/api/chat SSE、/api/chat/pause 无运行返回 409 的本地冒烟。
• 回归 /api/interactions/pending?sessionId=... 的无待答场景：返回 {"pending":null}；不能使用 Map.of 构造含 null 的响应。