Skip to content

[Design] Web Interface + Core HTTP Server Architecture for Memo #119

Closed
Closed
[Design] Web Interface + Core HTTP Server Architecture for Memo#119
Labels
area:coreCore runtime and session statearea:docsDocumentation and docs UXarea:securityApproval, sandbox, and security policyarea:toolsBuilt-in tools and tool runtimearea:tuiTerminal UI and interaction layerneeds-triageIssue needs initial triage

Description

@minorcell
minorcell
opened on Feb 10, 2026

背景

当前 Memo 已具备 core + tools + tui 架构，但缺少面向浏览器的交互入口。现有需求是提供 memo web，并确保 Web 能力与 TUI 功能等价，同时利用 Web 形态做更好的可视化与配置管理。

目标

  1. 支持 memo web 启动本地 Web 控制台。
  2. 新增 core 的 HTTP Server 模式（本地 API + SSE 事件流）。
  3. Web 功能覆盖 TUI 核心能力：
    • 多轮对话
    • 工具调用可视化
    • 工具审批（deny / once / session）
    • /models、/context、/tools
    • history/resume
    • MCP 配置管理
    • init/config 能力（以 Web 形式呈现）
  4. 默认安全：本地访问、最小暴露面、会话鉴权。

Activity

  1. github-actions
    added
    area:coreCore runtime and session state
    area:docsDocumentation and docs UX
    area:securityApproval, sandbox, and security policy
    area:toolsBuilt-in tools and tool runtime
    area:tuiTerminal UI and interaction layer
    needs-triageIssue needs initial triage
    on Feb 10, 2026
  2. minorcell
    marked Add web interface for memo #115 as a duplicate of this issue on Feb 10, 2026

  3. minorcell commented on Feb 10, 2026

    @minorcell
    minorcell
    on Feb 10, 2026
    OwnerAuthor

    补充需求动机（非常关键）：

    我创建这个 Web 方案的核心目标之一，是让 Memo 可以通过部署或内网穿透（如 ngrok）实现“随时随地可用”，而不局限在本机终端。

    这对设计的直接影响：

    1. 远程访问是目标场景之一（但必须是显式开启，不应默认暴露）。
    2. 安全模型要区分两种模式：
      • 本地模式（默认）：127.0.0.1 + 随机 token + 严格同源。
      • 远程模式（显式开启）：0.0.0.0/公网可达 + 强认证（至少 Bearer token，建议后续支持更强方案）+ CORS 白名单 + 明确高风险告警。
    3. API 设计要天然支持前后端分离部署（Web 可以独立部署，连接本地/远程 core server）。
    4. 文档与 CLI 参数要明确远程使用路径，例如：
      • memo web --host 0.0.0.0 --port <port> --token <token>
      • 结合 ngrok 时的安全注意事项与最小暴露原则。

    建议将以上内容并入验收标准，新增“远程可用性与安全基线”检查项。

  4. minorcell commented on Feb 10, 2026

    @minorcell
    minorcell
    on Feb 10, 2026
    OwnerAuthor

    一些具体的想法：

    1. config.toml中配置web登陆密码
    2. 需要重构当前sessions的存储方案：通过project存储；比如：sessions/memo-code/*.jsonl, sessions/todolist-code/*.jsonl，这样做的好处是 web 端可以按照项目打开session
    3. http请求 + sse 即可，接口鉴权走http only（session）
    4. web：
      • 路由拦截
      • axios封装request，用于请求响应拦截
      • server可以使用nestjs（使用ts）
      • server不必做包，似乎放在core包中即可
      • 符合前端规范的、简约、交互友好的前端设计（组件库为MUI）
      • 黑白模式
      • 要足够的清晰拆解架构，方便后续拿去扩展为浏览器插件、桌面甚至手机app
      • 登陆（没有注册）
      • 新建会话
      • 设置（配置文件页面化、权限、mcp之类的）
      • 多模态的输入框（这很重要，比如正常的@、slash的页面化等等）
    5. web不做任何agent的逻辑，所有交互都和本地server打交道。

  5. minorcell commented on Feb 10, 2026

    @minorcell
    minorcell
    on Feb 10, 2026
    OwnerAuthor

    我整理了一版可执行设计稿，建议将其作为本 Issue 的实施基线。以下是可直接落地的版本（覆盖 Web 入口、Core HTTP/SSE、安全模型、session 存储重构与分阶段验收）。

    1) 目标与边界

    目标

    1. 支持 memo web 启动本地 Web 控制台。
    2. 在 @memo/core 新增 HTTP API + SSE 事件流模式。
    3. Web 覆盖 TUI 核心能力：多轮对话、工具可视化、审批、/models /context /tools、history/resume、MCP、init/config。
    4. 默认安全；远程可用但必须显式开启并满足强认证。

    非目标

    1. 不在 Web 层复写 Agent/ReAct 主流程。
    2. 第一阶段不做注册体系、多租户、RBAC。
    3. 第一阶段不允许匿名公网访问。

    2) 总体架构

    memo web (CLI)
  -> Core HTTP Server (@memo/core/server)
      -> Session Runtime (@memo/core/runtime/session)
      -> Tool Router (@memo/tools)
      -> Config + Session Store (~/.memo)
  -> Web UI (packages/web)
      -> REST API
      -> SSE

    原则：

    1. Agent 逻辑只在 core。
    2. Web 仅做交互与可视化，不做执行编排。
    3. Web 可独立部署，天然支持前后端分离。

    3) CLI 设计

    建议命令：

    memo web [--host <host>] [--port <port>] [--token <token>] [--cors-origin <origin>] [--open]

    建议参数/默认值：

    1. --host 默认 127.0.0.1
    2. --port 默认 3927
    3. --token 可选，本地模式可自动生成
    4. --cors-origin 默认同源，远程模式必须白名单
    5. --allow-remote（建议新增）用于显式开启远程访问

    远程示例：

    memo web --allow-remote --host 0.0.0.0 --port 3927 --token <strong-token> --cors-origin https://memo.example.com

    4) Core Server 模块建议（放在 @memo/core 内）

    packages/core/src/server/
  index.ts
  http_server.ts
  auth.ts
  sse.ts
  middleware/
    cors.ts
    origin.ts
    rate_limit.ts
  routes/
    auth.ts
    sessions.ts
    turns.ts
    approvals.ts
    config.ts
    models.ts
    tools.ts
    context.ts
    mcp.ts

    API 草案（v1）

    1. POST /api/v1/auth/login
    2. POST /api/v1/auth/logout
    3. GET /api/v1/auth/me
    4. GET /api/v1/sessions?project=<projectKey>&cursor=<cursor>
    5. POST /api/v1/sessions
    6. GET /api/v1/sessions/:sessionId
    7. POST /api/v1/sessions/:sessionId/turns
    8. GET /api/v1/sessions/:sessionId/events（SSE）
    9. POST /api/v1/approvals/:requestId（deny/once/session）
    10. GET /api/v1/models
    11. GET /api/v1/context
    12. GET /api/v1/tools
    13. GET /api/v1/mcp/servers
    14. POST /api/v1/mcp/servers
    15. PATCH /api/v1/mcp/servers/:name
    16. DELETE /api/v1/mcp/servers/:name
    17. GET /api/v1/config
    18. PATCH /api/v1/config

    SSE 事件建议

    session_started, turn_started, assistant_delta, tool_call_started, tool_call_finished, approval_required, approval_resolved, turn_finished, error, heartbeat

    5) 安全模型（新增“远程可用性与安全基线”）

    本地模式（默认）

    1. 127.0.0.1 绑定。
    2. 随机 token（或已配置 token）。
    3. 严格同源，不开放跨域。
    4. 登录后用 HttpOnly session cookie（SameSite=Strict）。
    5. Origin/Host 双校验。

    远程模式（显式开启）

    1. 必须 --allow-remote。
    2. 必须强 token（至少 Bearer token）。
    3. 必须 --cors-origin 白名单，禁止 *。
    4. 登录可 Bearer token，后续维持 HttpOnly session。
    5. 启动时输出高风险告警。

    ngrok 注意事项

    1. 仅在必须时开启远程模式。
    2. 强 token + 定期轮换。
    3. 最小暴露面（端口/来源最小化）。
    4. 推荐 HTTPS。

    6) Session 存储重构（按项目）

    目标路径：

    ~/.memo/sessions/projects/<projectKey>/<YYYY>/<MM>/<DD>/rollout-<timestamp>-<id>.jsonl
~/.memo/sessions/projects/<projectKey>/project.json

    projectKey 建议：basename(cwd)+短哈希（基于规范化绝对路径）。

    兼容策略：

    1. 新路径优先读取，旧路径回退读取。
    2. 保留 legacy 读取，避免历史丢失。
    3. 可选提供迁移命令：memo sessions migrate --from legacy --to projects。

    7) Web 端约束（packages/web）

    1. Vite + React + TypeScript + MUI。
    2. axios request 层统一封装（请求/响应拦截、401 跳转、错误标准化）。
    3. 路由守卫（未登录拦截）。
    4. 必备页面：登录、会话（按项目）、聊天、设置、MCP 管理、/models /context /tools。
    5. 输入框支持 @ 与 slash 页面化入口。
    6. 提供黑白主题切换。

    8) 分阶段计划

    Phase 1（Core Server MVP，本地）

    1. memo web 启动 API/SSE。
    2. 登录 + 新建会话 + 提交 turn + 接收事件闭环。
    3. 本地安全基线到位。

    Phase 2（Web Chat MVP）

    1. 登录页/会话页/聊天页打通。
    2. 工具调用可视化。
    3. 审批交互可用。

    Phase 3（能力对齐）

    1. /models /context /tools 页面化。
    2. history/resume、MCP、配置管理补齐。
    3. 按项目 session 存储上线并兼容旧数据。

    Phase 4（远程可用 + 安全加固）

    1. 远程模式显式开关。
    2. CORS 白名单 + 风险告警 + 审计日志。
    3. 补充远程部署文档（含 ngrok 安全说明）。

    9) 验收标准（建议并入 Issue）

    1. memo web 可完成浏览器多轮会话。
    2. 工具调用可视化 + 审批 deny/once/session 生效。
    3. /models /context /tools、history/resume、MCP、config 可用。
    4. session 可按项目检索与恢复，兼容旧日志。
    5. 本地默认不公网暴露，严格同源。
    6. 远程模式缺少 --allow-remote/--token/--cors-origin 任一项时启动失败。
    7. 远程链路满足强认证与会话鉴权，并有明确风险提示。

    如果认可，我可以继续补一版“接口字段级规范（request/response schema + SSE event payload）”，直接对应开发任务拆分。

  6. minorcell
    closed this as completedon Feb 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:coreCore runtime and session statearea:docsDocumentation and docs UXarea:securityApproval, sandbox, and security policyarea:toolsBuilt-in tools and tool runtimearea:tuiTerminal UI and interaction layerneeds-triageIssue needs initial triage

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions