# WebMain 职责拆分

日期：2026-08-14

# 问题

WebMain 同时承担服务启动、会话编排、HTTP 编解码、工件安全读取和核心事件到 SSE 的转换。后续增加端点时容易让入口类继续膨胀，也会使工件或 SSE 的行为难以单独验证。

# 拆分结果

• WebMain：保留应用装配、模型/会话运行状态、路由注册，以及 chat、暂停、交互恢复等需要协调 AgentLoop 的用例。
• WebHttp：集中 CORS、OPTIONS、JSON、SSE 写入、查询参数和整数解析；是无状态 HTTP 协议工具。
• ArtifactController：负责 /api/artifacts、预览大小上限、MIME 推断和工作区路径边界；同时向 SSE 工具卡提供同一套工件元数据规则。
• WebSseEventWriter：负责 AgentEvent 到浏览器 SSE 事件的映射、公共 event envelope，以及工具卡的实时工件元数据。

# 保持不变的契约

• 所有现有 API 路径、状态码、CORS 策略和 SSE 事件名/字段保持不变。
• 工件读取仍强制限制在 workspaceRoot 内，不会因 PIAGENTNO_SANDBOX 放宽。
• SSE 仍携带 eventId、runId、sessionId、timestamp，工具完成事件仍可包含实时 artifact。

# 验证

• mvn -pl pi-agent-v1 test：通过（当前模块没有测试源码）。
• mvn -pl pi-agent-v1 package -DskipTests：通过。
• Mock 服务冒烟：GET /api/status 返回 200；POST /api/chat 可连续收到 agentstart、turnstart、messageupdate、usage、turnend SSE 事件。