Skip to content

refactor(tui): 按 feature-first 重组 packages/tui 目录与边界 #212

@minorcell

Description

@minorcell

背景

当前 packages/tui/src 存在多种拆分维度并存(UI 区块、技术职责、命令域),导致目录语义不统一、模块边界模糊,维护成本逐步升高。

现状问题

  1. App.tsx 体量过大(会话编排 + 状态接线 + 命令分发 + UI 装配),成为超级容器。
  2. 目录维度混杂:bottom_pane/chatwidget/overlays(UI)+ controllers/state/review(职责)+ commands/mcp(业务域)。
  3. 组件层直接依赖业务逻辑(如 Composer 直接引用 controllers/slash),缺少中间层(hooks/services)。
  4. 命名不统一(snake_case 与 PascalCase/CamelCase 混用),影响检索与认知负担。
  5. 存在薄目录或仅转发层,增加跳转成本。

目标

将 TUI 重组为 feature-first 结构,统一边界与依赖方向:

  • 入口层:启动与装配
  • feature 层:按业务能力组织(session/composer/timeline/review/mcp)
  • shared 层:通用 UI、工具、类型

建议目录(示例)

src/
  app/
  features/
    session/
    composer/
    timeline/
    review/
    mcp/
  shared/
    ui/
    lib/
    types/

分阶段实施建议

  1. 先拆 App.tsx:抽出 useSessionRuntimeuseApprovalsuseModelSwitch 等 hooks。
  2. controllers/* 按归属迁入 feature 或 shared/lib,逐步移除“controller”语义目录。
  3. 统一命名规则(文件名风格一致)。
  4. 清理薄目录/转发层,减少无意义层级。

验收标准

  • App.tsx 明显瘦身,职责聚焦于组装 UI。
  • 目录语义一致(feature-first),新增功能可按 feature 就近落位。
  • 依赖方向清晰:UI -> feature hooks/services -> shared。
  • 文档(README/docs)同步更新,并保持现有功能行为不变。

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:coreCore runtime and session statearea:docsDocumentation and docs UXarea:toolsBuilt-in tools and tool runtimearea:tuiTerminal UI and interaction layerenhancementNew feature or requestneeds-triageIssue needs initial triage

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions