重构计划：Core AI SDK 化 + Core 内建 HTTP Server + 删除 web-server

[minorcell]

Summary

本次做一次性切换（无并存期）：

1. core 的 agent 从当前自研 ReAct + openai SDK 路径，迁移为 AI SDK ToolLoopAgent 主实现。
2. token 统计从 @dqbd/tiktoken 迁移到 AI SDK usage + AI SDK tokenizer/countTokens 能力（不再使用 tiktoken）。
3. 删除 packages/web-server，在 packages/core 新增原生 Node HTTP server（轻路由）并暴露 OpenAPI 风格接口。
4. tui 与 web-ui 都改为 HTTP 客户端，统一通过 core server 交互。
5. provider 统一切到 AI Gateway。
6. 不做历史兼容

---

已确认的关键决策（锁定）

• Agent 迁移范围：全面改为 ToolLoopAgent。
• 协议形态：OpenAPI 风格 + SSE 实时流。
• 鉴权：固定共享密码。
• 切换策略：一次性切换并删除 web-server。
• Core HTTP 技术栈：Node 原生 HTTP + 轻路由（不引入 Nest/Express）。
• TUI：必须统一走 HTTP（不保留直连 createAgentSession）。
• Provider：统一切到 AI Gateway。

---

架构目标（目标态）

• core 变成唯一后端内核（agent + session runtime + HTTP API）。
• tui/web-ui 成为“薄客户端”：
  • 只负责输入、展示、状态同步；
  • 不直接持有 agent 运行逻辑。
• tools 保持工具执行域，仍由 core runtime 编排调用。
• 全部会话/事件/审批流通过 core server 统一协议输出。

---

公开接口与类型变更（Public API / Types）

A. @memo-code/core 导出新增

• startCoreHttpServer(options) / stopCoreHttpServer()
• CoreHttpServerOptions（host, port, password, memoHome, cors）
• CoreHttpServerHandle（url, close, openApiSpecPath）

B. core 的 Web 协议类型统一

复用并扩展 packages/core/src/web/types.ts，新增：

• SseEventEnvelope（统一 event, data, seq, ts）
• AuthLoginRequest/AuthLoginResponse
• OpenApiError（与 ApiEnvelope 对齐）

C. 原 createAgentSession 语义调整

• 保留 API（避免外部依赖立即断裂），但内部实现改为 AI SDK Agent runtime。
• 新增 server 专用 session manager（内存态 live session + 持久历史索引）。

D. token 计数接口演进

• TokenCounter 从 tiktoken 实现切换为 AI SDK 计数实现（或 usage 驱动 + fallback 计数）。
• 移除/废弃 createTokenCounter 的 tiktoken 依赖行为；保留同名导出时改为 AI SDK 后端实现，避免调用方大面积改名。

---

HTTP API 设计（OpenAPI + SSE）

1) 鉴权

• POST /api/auth/login
  • 入参：{ password: string }
  • 出参：{ accessToken, expiresIn }
• 后续接口统一 Authorization: Bearer <token>。
• 不做 refresh token（简化模型）；token 短期有效，过期重新输入密码登录。

2) 会话与聊天

• POST /api/chat/sessions：创建 live session
• GET /api/chat/sessions/:id：获取 live state
• DELETE /api/chat/sessions/:id：关闭 session
• POST /api/chat/sessions/:id/messages：提交输入（同步确认 accepted）
• GET /api/chat/sessions/:id/events：SSE 订阅事件流
• POST /api/chat/sessions/:id/cancel：取消当前 turn
• POST /api/chat/sessions/:id/compact：手动 compact
• POST /api/chat/sessions/:id/approval：审批响应

3) 其他域接口（与现有 web-ui 能力对齐）

• /api/sessions/*（历史列表/详情/事件）
• /api/mcp/*
• /api/skills/*
• /api/workspaces/*

4) SSE 事件

• turn.start
• assistant.chunk
• tool.action
• tool.observation
• context.usage
• approval.request
• turn.final
• session.status
• error

---

分包与目录调整

packages/core

新增（建议）：

• src/server/http_server.ts
• src/server/router.ts
• src/server/auth.ts
• src/server/sse.ts
• src/server/openapi.ts
• src/server/session_manager.ts

改造：

• src/runtime/defaults.ts：AI SDK provider + ToolLoopAgent 构建。
• src/runtime/session_runtime.ts：替换核心循环为 AI SDK agent loop 适配层。
• src/utils/tokenizer.ts：移除 tiktoken 逻辑，改 AI SDK token 统计实现。
• src/index.ts：导出 server API。

删除

• 整个 packages/web-server/

packages/tui

• cli.tsx/App.tsx 会话交互改为 HTTP client（REST + SSE）。
• web/run_web_command.ts 改为启动 core server entry（不再找 web-server build 产物）。

packages/web-ui

• 移除 ws rpc 客户端主路径，改 REST + SSE 客户端。
• 保留页面结构，替换 API adapter 层实现即可。

根构建脚本

• 移除 web:server:*、web:build 中对 @memo-code/web-server 的引用。
• 构建产物由 core 负责 server entry 打包并供 memo web 启动。

---

AI SDK 迁移细节（实现规范）

1. 引入 ai 与所需 provider 包（AI Gateway 路径）。
2. 实现 Agent：
   • 用 ToolLoopAgent 承接多步工具调用与终态输出。
   • 把现有 ToolRouter 输出工具定义映射到 AI SDK tool schema。
3. usage/token：
   • 优先用 AI SDK 返回 usage。
   • 上下文估算与 compact 阈值判断改用 AI SDK token counting 能力。
4. 模型选择：
   • 运行迁移时通过 AI Gateway 模型列表接口获取当前可用模型，写入配置默认值。
5. 保留现有 hooks 与 history JSONL 语义，避免上层行为倒退。

---

迁移顺序（一次性切换执行顺序）

1. 在 core 先落 HTTP server 骨架 + OpenAPI schema + auth + SSE 基础能力。
2. 完成 agent runtime 的 AI SDK ToolLoopAgent 替换（保持 hooks/history 输出兼容）。
3. 完成 tui HTTP 化（先打通 chat 主链路）。
4. 完成 web-ui 从 WS RPC 到 REST+SSE 的 API adapter 替换。
5. 删除 packages/web-server 与相关脚本/依赖/文档引用。
6. 全仓测试与回归。

---

测试计划与验收场景

单测

• core：
  • auth token 签发/校验/过期。
  • SSE 广播与断连清理。
  • session manager 并发输入、队列、取消、审批。
  • AI SDK agent 适配层：tool call、final、error、cancel、max tokens。
  • token usage 聚合与 compact 阈值行为。
• tui/web-ui：
  • API adapter（REST/SSE）解析与状态更新。
  • 关键交互：提交输入、审批、取消、compact。

集成测试

• 启动 core server 后：
  • 登录成功/失败。
  • 创建 session -> 发送消息 -> 收到 chunk/final。
  • 工具审批流程完整闭环。
  • session 历史可查询并与 JSONL 一致。

E2E（最小集）

1. memo web 启动后可登录并完成一轮对话。
2. TUI 通过 HTTP 模式完成一轮工具调用并收到审批。
3. 手动 compact 生效，context usage 事件正确。

验收标准

• 代码库不再包含 packages/web-server。
• core 独立提供 HTTP + OpenAPI + SSE 能力。
• tui/web-ui 均不再直接依赖旧 web-server 协议实现。
• token 统计链路中不再使用 @dqbd/tiktoken。
• 关键测试通过（core/tools/tui/web-ui 覆盖主链路）。

---

显式假设与默认值

• 默认仅监听 127.0.0.1。
• 固定共享密码来源：MEMO_SERVER_PASSWORD（无则启动失败并给出明确错误）。
• token 只做 access token（无 refresh）。
• OpenAPI 文档由 core server 在运行时提供 /api/openapi.json。
• 旧 WS RPC 协议不保留兼容层（一次性切换）。

---

本计划由 🤖 Memo Code 撰写