@bigduu/lotus 2026.6.3 → 2026.6.4

package/README.md

@@ -1,107 +1,184 @@
-# Lotus Frontend
+# Lotus — The Living Interface
 
-Lotus is a standalone React + Vite frontend project. It is the UI asset source for the Bodhi desktop shell and also supports browser-mode development and testing.
+> 📖 中文版请看 **[README.zh-CN.md](./README.zh-CN.md)**
 
-## Ownership
+> React + Vite UI layer for Zenith · `@bigduu/lotus`
 
-- Frontend UI and interaction logic: `src/`
-- Frontend unit/integration tests: Vitest
-- Browser E2E tests: Playwright (`e2e/`)
-- npm distribution artifact: `dist/` (package name: `@bigduu/lotus`)
+---
 
-Related projects:
-- `bodhi/`: Tauri desktop shell that consumes Lotus build output
-- `bamboo/`: Rust backend service
+## What this is
 
-## Prerequisites
+Lotus is the pane of glass between you and an AI agent. You type, it answers — but the real magic is that **you can watch it think and work**: which file it's reading, which tool it's calling, the to-do list it drew up, the diagram it sketched, all streaming onto the screen live. It turns an otherwise black-box AI into a transparent, observable teammate you can interrupt at any time.
 
-- Node.js LTS (recommended: 20+)
-- npm
-- Rust (required only when integrating with bamboo or running some E2E flows)
+---
 
-## Quick Start
+## Key capabilities at a glance
 
-```bash
-cd lotus
-npm install
-npm run dev
+| Capability | What it gives you |
+| --- | --- |
+| **Live event stream** | Token-by-token answers, reasoning and tool calls over SSE, batched per animation frame (`requestAnimationFrame`) |
+| **Command palette** | `Cmd/Ctrl + K` — one keystroke to jump to sessions, settings, themes, new tasks |
+| **Settings center** | Providers, model limits, MCP, hooks, schedules, env vars, keyword masking, metrics dashboard |
+| **Live to-do list** | The agent's plan, updating its progress as it runs |
+| **Question dialog** | Pops up when the agent needs clarification; options + free text |
+| **Mermaid rendering** | Diagrams render inline with zoom/pan and one-click AI fix |
+| **Skill management** | Browse and toggle agent skills |
+| **Multi-pane** | Split the layout to view multiple sessions side by side |
+| **Bilingual + theming** | zh-CN / en-US, light/dark, VDI safe mode |
+
+---
+
+## Architecture
+
+Lotus is a **pure frontend** (React 18 + Vite 6 + TypeScript). It carries no business backend of its own — all agent execution lives in **bamboo** (the local Rust runtime). Lotus talks to bamboo over **HTTP + SSE**: plain requests via REST (`/api/v1/...`), live output via Server-Sent Events (`/api/v1/events/{sessionId}`, auto-reconnecting through the browser's native `EventSource`). The same build artifact (`dist/`) is loaded by the **bodhi** desktop shell and is equally runnable in a plain browser for development.
+
+```mermaid
+flowchart LR
+  subgraph Browser["Browser / Bodhi WebView"]
+    UI["Lotus UI<br/>React + Vite"]
+    ES["EventSource (SSE)"]
+    REST["fetch (REST)"]
+    Store["State: Jotai + Zustand<br/>Storage: Dexie (IndexedDB)"]
+    UI --- Store
+    UI --- ES
+    UI --- REST
+  end
+  ES -- "/api/v1/events/{sessionId}" --> Bamboo
+  REST -- "/api/v1/..." --> Bamboo
+  Bamboo["bamboo<br/>local Rust agent runtime"]
 ```
 
-## Common Commands
+**Stack highlights (verified in `package.json`):**
 
-```bash
-npm run dev               # local development
-npm run type-check        # TypeScript checks
-npm run test:run          # run Vitest once
-npm run test:e2e          # run Playwright E2E
-npm run build             # build dist
-npm run pack:dry-run      # inspect npm package contents
+- **UI / components**: Ant Design 5 (`antd`, `@ant-design/icons`)
+- **State**: Jotai (`jotai`, `jotai-family`) for fine-grained streaming atoms + Zustand (`zustand`) for app/UI stores
+- **Local storage**: Dexie (IndexedDB) — `src/services/storage/StorageDb.ts`
+- **Markdown**: `react-markdown` + `remark-gfm` / `remark-breaks` + `rehype-sanitize` + `react-syntax-highlighter`
+- **Diagrams**: `mermaid` (with `react-zoom-pan-pinch` viewer)
+- **Metrics charts**: `recharts`
+- **Export**: `jspdf` + `html2canvas`
+- **i18n**: `i18next` + `react-i18next` (locales: `zh-CN`, `en-US`)
+- **Virtualization**: `@tanstack/react-virtual`
+
+**Source map (`src/`):**
+
+```text
+src/
+├── app/                  # App bootstrap, MainLayout (sidebar + panes + settings)
+├── pages/
+│   ├── ChatPage/         # The chat experience (the flagship)
+│   │   ├── streaming/    # Jotai atoms + RAF-batched streaming state
+│   │   ├── hooks/        # useAgentEventSubscription, useChatManager, ...
+│   │   ├── components/   # ~50 cards: ToolCallCard, TodoListDisplay,
+│   │   │                 #   StreamingMessageCard, PlanMessageCard, ...
+│   │   ├── conversation/ workspace/ inspector/ services/ utils/
+│   ├── SettingsPage/     # SystemSettingsPage + tabs (providers, MCP, metrics...)
+│   ├── SetupPage/  PasswordGatePage/
+├── components/           # Skill, TodoList, QuestionDialog
+├── shared/
+│   ├── components/       # CommandPalette, MermaidChart, Markdown, ResizableSplit...
+│   ├── store/            # Zustand stores (appStore, theme, settingsView, uiLayout...)
+│   ├── i18n/             # zh-CN + en-US resources
+│   ├── services/  hooks/  theme/  types/  utils/
+├── services/             # HTTP/SSE clients: api/, chat/ (AgentService), config/,
+│                         #   mcp/, metrics/, skill/, workspace/, storage/, ...
 ```
 
-## Documentation
+---
 
-- Frontend docs root: [`docs/README.md`](./docs/README.md)
-- Frontend architecture: [`docs/architecture/FRONTEND_ARCHITECTURE.md`](./docs/architecture/FRONTEND_ARCHITECTURE.md)
-- Development guides: [`docs/development/`](./docs/development/)
-- Feature docs (Command Selector, Question Dialog, Mermaid): [`docs/features/`](./docs/features/)
+## Signature deep-dives
+
+### Real-time SSE event stream
+
+This is the soul of Lotus. `src/services/chat/AgentService.ts` declares an event vocabulary mirroring bamboo's — dozens of types from `token`, `reasoning_token`, `tool_token`, through `tool_start` / `tool_complete` / `tool_error`, `task_list_updated`, `token_budget_updated`, `context_compression_status`, `sub_agent_started`, `need_clarification`, `plan_mode_entered`, and more. The UI subscribes per session via the native `EventSource` (with `withCredentials`, auto-reconnect, and `Last-Event-ID` resume) on `/api/v1/events/{sessionId}`; an account-level broadcast runs over a single long-lived feed in `accountFeed.ts`.
+
+To keep token-by-token output buttery without melting the browser, streaming state is held in **Jotai atoms** and **committed per animation frame** via `requestAnimationFrame` in `pages/ChatPage/streaming/useKeyedRafAtomState.ts` — you get a smooth typewriter effect instead of a re-render per token.
+
+### The chat experience
+
+`pages/ChatPage` isn't a text box — it's a whole vocabulary of cards. Every kind of agent activity has its own visualization: `StreamingMessageCard` (live answers), `ToolCallCard` / `ToolResultCard` / `ToolSessionCard` (the full lifecycle of a tool call), `PlanMessageCard` (plan mode), `QuestionMessageCard` (clarifications), `FileChangeViewer` (diffs of edited files), `TokenUsageDisplay` (context budget), `SessionSummaryCard` (compression summaries) — roughly 50 components in all. `MultiPaneChatView` + `ResizableSplit` let you split panes for side-by-side sessions; long lists stay smooth via `@tanstack/react-virtual`.
 
-## Integrate with Bamboo
+### Command palette
 
-Terminal 1:
+Hit `Cmd/Ctrl + K` (bound in `app/MainLayout.tsx` and `shared/components/CommandPalette/index.tsx`). It unifies two entry types: **actions** (open Provider settings, model limits, prompts, skills, MCP, workflows, hooks, schedules, sessions, metrics, keyword masking, toggle theme, new task, collapse sidebar…) and **session search** (fuzzy-jump by title, with pinned markers). Every label is i18n-driven, identical across zh/en.
+
+### Settings center
+
+`pages/SettingsPage/components/SystemSettingsPage` is a tabbed console, lazy-loaded to keep startup light. Verified tabs: **Providers** (`ProviderSettings`), **Model limits** (`ModelLimitsSettings`), **Prompts** (`SystemPromptManager`), **MCP** (server forms + management), **Workflows**, **Hooks**, **Schedules**, **Sessions**, **Env vars**, **Keyword masking**, **Notifications**, **Mermaid settings**, **Access password**, **Network**, and a `recharts`-powered **Metrics dashboard** (`UnifiedMetricsDashboard` with token charts, memory trends, model distribution, forward-endpoint distribution, and more).
+
+### Skills · questions · to-dos · Mermaid
+
+- **Skill** (`src/components/Skill`): `SkillCard` / `SkillSelector` / `SkillManager` browse agent skills, toggle enable/disable, show license tags.
+- **Question dialog** (`src/components/QuestionDialog`): pops up when the stream emits `need_clarification`, supports preset options and free text, and remembers per-session reasoning effort.
+- **To-do list** (`src/components/TodoList` + `pages/ChatPage/components/TodoListDisplay`): live progress, status icons, dependencies and notes driven by `task_list_updated` and friends; collapsible and pinnable.
+- **Mermaid** (`shared/components/MermaidChart`): lazy-loaded renderer, fits very wide diagrams to the viewport, zoom/pan via `react-zoom-pan-pinch`; on render failure exposes an `onFix` callback to hand the error back to the AI.
+
+---
+
+## Quick start
+
+**Prerequisites:** Node.js LTS (20+) and npm. A running **bamboo** backend for live agent features (see below).
 
 ```bash
-cd bamboo
-cargo run --bin bamboo -- serve --port 9562 --bind 127.0.0.1 --data-dir /tmp/bamboo-data
+npm install
+npm run dev          # Vite dev server → http://localhost:1420
 ```
 
-Terminal 2:
+**Run against bamboo** — in a second terminal, from the repo root:
 
 ```bash
-cd lotus
-npm run dev
+cargo run --manifest-path bamboo/Cargo.toml --bin bamboo -- \
+  serve --port 9562 --bind 127.0.0.1 --data-dir /tmp/bamboo-data
 ```
 
-## npm Publishing (@bigduu/lotus)
-
-`package.json` is configured with:
-- package name: `@bigduu/lotus`
-- `publishConfig.access`: `public`
-- `prepack`: automatically runs `npm run build` before publish
+Lotus defaults to the backend at `http://127.0.0.1:9562/v1` (overridable via `VITE_BACKEND_BASE_URL`; see `src/shared/utils/backendBaseUrl.ts`).
 
-Manual local publish:
+### Verified scripts (`package.json`)
 
 ```bash
-cd lotus
-npm version patch
-npm publish
+npm run dev               # Vite dev server (port 1420)
+npm run build             # tsc + vite build → dist/
+npm run preview           # preview the production build
+npm run type-check        # tsc --noEmit
+npm run lint              # eslint src   (lint:fix to autofix)
+npm run format            # prettier --write   (format:check to verify)
+
+npm run test              # vitest (watch)        test:ui / test:coverage
+npm run test:run          # vitest run (one-shot)
+npm run test:e2e          # Playwright (delegates to ./e2e)
+npm run test:e2e:browser  # Playwright against http://localhost:1420
+npm run test:e2e:with-server  # boots a throwaway bamboo, then runs Playwright
+
+npm run pack:dry-run      # inspect the npm package contents
 ```
 
-## GitHub Actions Auto Publish
+### Packaging & branding (verified)
 
-Workflow file: `.github/workflows/publish-npm.yml`
+```bash
+npm run build:bamboo-package   # build, then stage dist into bamboo as a prebuilt frontend
+npm run build:public           # rebrand (public) + build
+npm run build:internal         # rebrand (internal) + build
+npm run rebrand:check          # verify branding state
+```
 
-Triggers:
-- Tag push: `v*` or `lotus-v*`
-- Manual trigger: `workflow_dispatch`
+Published as **`@bigduu/lotus`** (`publishConfig.access: public`); `prepack` runs `npm run build` automatically.
 
-### npm Auth in Actions
+---
 
-Do not use interactive `npm login` in CI. Use an npm token:
+## The rest of the stack
 
-1. Create an npm access token that can publish `@bigduu/lotus`.
-2. In GitHub repo settings, open `Settings -> Secrets and variables -> Actions`.
-3. Add a repository secret named `NPM_TOKEN`.
-4. The workflow authenticates with `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`.
+Lotus is the UI layer within the Zenith monorepo. Sibling modules:
 
-## Project Structure
+- [`../bamboo`](../bamboo) — local-first Rust agent runtime (the execution engine Lotus talks to over HTTP + SSE)
+- [`../bodhi`](../bodhi) — desktop AI product surface (Tauri shell that loads Lotus's `dist/`)
+- [`../bodhi-server`](../bodhi-server) — Go backend (auth / persistence / billing + quota / LLM proxy)
+- [`../pavilion`](../pavilion) — official website & docs
+- [`..`](..) — Zenith root (monorepo entry, submodule pointers, release train)
 
-```text
-lotus/
-├── src/                       # React application source
-├── e2e/                       # Playwright tests
-├── scripts/                   # build/branding scripts
-├── public/                    # static assets
-├── .github/workflows/         # CI/CD
-├── vite.config.ts             # Vite configuration
-└── package.json               # package metadata and scripts
-```
+**In-module docs:**
+
+- Frontend docs root: [`docs/README.md`](./docs/README.md)
+- Frontend architecture: [`docs/architecture/FRONTEND_ARCHITECTURE.md`](./docs/architecture/FRONTEND_ARCHITECTURE.md)
+- Design spec: [`docs/DESIGN_SPEC.md`](./docs/DESIGN_SPEC.md)
+- Feature docs (Command Selector / Question Dialog / Mermaid): [`docs/features/`](./docs/features/)
+- Development guides: [`docs/development/`](./docs/development/)

package/README.zh-CN.md

@@ -0,0 +1,184 @@
+# Lotus · 莲花交互层
+
+> 📖 For English, see **[README.md](./README.md)**
+
+> Zenith 的 React + Vite UI 层 · `@bigduu/lotus`
+
+---
+
+## 这是什么
+
+Lotus 是你和 AI 智能体对话的那块「玻璃」。你打字、它回答——但更重要的是，你能**看见它在想什么、在做什么**：它正在读哪个文件、调用哪个工具、列了什么待办清单、画了什么流程图，全部实时呈现在屏幕上。它把一个原本黑箱的 AI，变成一个透明、可观察、可随时打断的工作伙伴。
+
+---
+
+## 一览能力
+
+| 能力 | 说明 |
+| --- | --- |
+| **实时事件流** | 通过 SSE 逐字渲染回答、推理、工具调用，帧级流畅（`requestAnimationFrame` 批处理） |
+| **命令面板** | `Cmd/Ctrl + K` 一键跳转会话、设置、主题、新建任务 |
+| **设置中心** | Providers、模型上限、MCP、Hooks、计划任务、环境变量、关键词脱敏、指标仪表盘 |
+| **待办清单** | 智能体的任务计划随执行实时更新进度 |
+| **追问对话** | 智能体需要澄清时弹出，支持选项与自由输入 |
+| **Mermaid 渲染** | 回答中的图表自动渲染，可缩放拖拽、错误可一键让 AI 修复 |
+| **技能管理** | 浏览、启用/停用智能体技能 |
+| **多窗格** | 可拆分布局并排查看多个会话 |
+| **双语 + 主题** | 中英文界面，明暗主题，VDI 安全模式 |
+
+---
+
+## 架构
+
+Lotus 是一个**纯前端**项目（React 18 + Vite 6 + TypeScript）。它本身不含业务逻辑后端——所有智能体的执行都发生在 **bamboo**（本地 Rust 运行时）里。Lotus 通过 **HTTP + SSE** 与 bamboo 对话：普通请求走 REST（`/api/v1/...`），实时输出走 Server-Sent Events（`/api/v1/events/{sessionId}`，由浏览器原生 `EventSource` 自动重连）。同一份构建产物（`dist/`）既被 **bodhi** 桌面外壳加载，也可在浏览器里直接开发调试。
+
+```mermaid
+flowchart LR
+  subgraph Browser["Browser / Bodhi WebView"]
+    UI["Lotus UI<br/>React + Vite"]
+    ES["EventSource (SSE)"]
+    REST["fetch (REST)"]
+    Store["State: Jotai + Zustand<br/>Storage: Dexie (IndexedDB)"]
+    UI --- Store
+    UI --- ES
+    UI --- REST
+  end
+  ES -- "/api/v1/events/{sessionId}" --> Bamboo
+  REST -- "/api/v1/..." --> Bamboo
+  Bamboo["bamboo<br/>local Rust agent runtime"]
+```
+
+**关键技术（已在 `package.json` 中验证）：**
+
+- **UI / 组件**: Ant Design 5 (`antd`, `@ant-design/icons`)
+- **状态**: Jotai (`jotai`, `jotai-family`) 用于细粒度流式原子 + Zustand (`zustand`) 用于应用/UI 存储
+- **本地存储**: Dexie (IndexedDB) — `src/services/storage/StorageDb.ts`
+- **Markdown**: `react-markdown` + `remark-gfm` / `remark-breaks` + `rehype-sanitize` + `react-syntax-highlighter`
+- **图表**: `mermaid`（配 `react-zoom-pan-pinch` 查看器）
+- **指标图表**: `recharts`
+- **导出**: `jspdf` + `html2canvas`
+- **国际化**: `i18next` + `react-i18next`（语言：`zh-CN`、`en-US`）
+- **虚拟化**: `@tanstack/react-virtual`
+
+**源码地图（`src/`）：**
+
+```text
+src/
+├── app/                  # App bootstrap, MainLayout (sidebar + panes + settings)
+├── pages/
+│   ├── ChatPage/         # The chat experience (the flagship)
+│   │   ├── streaming/    # Jotai atoms + RAF-batched streaming state
+│   │   ├── hooks/        # useAgentEventSubscription, useChatManager, ...
+│   │   ├── components/   # ~50 cards: ToolCallCard, TodoListDisplay,
+│   │   │                 #   StreamingMessageCard, PlanMessageCard, ...
+│   │   ├── conversation/ workspace/ inspector/ services/ utils/
+│   ├── SettingsPage/     # SystemSettingsPage + tabs (providers, MCP, metrics...)
+│   ├── SetupPage/  PasswordGatePage/
+├── components/           # Skill, TodoList, QuestionDialog
+├── shared/
+│   ├── components/       # CommandPalette, MermaidChart, Markdown, ResizableSplit...
+│   ├── store/            # Zustand stores (appStore, theme, settingsView, uiLayout...)
+│   ├── i18n/             # zh-CN + en-US resources
+│   ├── services/  hooks/  theme/  types/  utils/
+├── services/             # HTTP/SSE clients: api/, chat/ (AgentService), config/,
+│                         #   mcp/, metrics/, skill/, workspace/, storage/, ...
+```
+
+---
+
+## 招牌深潜
+
+### 实时事件流
+
+这是 Lotus 的灵魂。`src/services/chat/AgentService.ts` 定义了与 bamboo 一一对应的事件类型——从 `token`、`reasoning_token`、`tool_token`，到 `tool_start` / `tool_complete` / `tool_error`、`task_list_updated`、`token_budget_updated`、`context_compression_status`、`sub_agent_started`、`need_clarification`、`plan_mode_entered` 等几十种。前端用浏览器原生 `EventSource`（带 `withCredentials`、自动重连、`Last-Event-ID` 续传）订阅每个会话的 `/api/v1/events/{sessionId}`；账号级广播则走 `accountFeed.ts` 的单一长连接。
+
+为了让逐字输出既流畅又不拖垮浏览器，流式状态用 **Jotai 原子** 存储，并在 `pages/ChatPage/streaming/useKeyedRafAtomState.ts` 里用 `requestAnimationFrame` **按帧批量提交**——你看到的是丝滑的打字机效果，而不是每个 token 都触发一次重渲染。
+
+### 对话体验
+
+`pages/ChatPage` 不是一个聊天框，而是一整套「卡片」语言。每一种智能体活动都有对应的可视化组件：`StreamingMessageCard`（流式回答）、`ToolCallCard` / `ToolResultCard` / `ToolSessionCard`（工具调用全过程）、`PlanMessageCard`（计划模式）、`QuestionMessageCard`（追问）、`FileChangeViewer`（文件改动 diff）、`TokenUsageDisplay`（上下文预算）、`SessionSummaryCard`（上下文压缩摘要）等约 50 个组件。`MultiPaneChatView` + `ResizableSplit` 让你能拆分窗格并排看多个会话；长列表用 `@tanstack/react-virtual` 虚拟化保持流畅。
+
+### 命令面板
+
+按 `Cmd/Ctrl + K`（绑定在 `app/MainLayout.tsx` 与 `shared/components/CommandPalette/index.tsx`）即可呼出。它统一了两类入口：**动作**（打开 Provider 设置、模型上限、提示词、技能、MCP、工作流、Hooks、计划任务、会话、指标、关键词脱敏、切换主题、新建任务、折叠侧栏……）和**会话搜索**（按标题模糊匹配跳转，含置顶标记）。所有标签均走 i18n，中英文一致。
+
+### 设置中心
+
+`pages/SettingsPage/components/SystemSettingsPage` 是一个标签化的控制台，懒加载以保持启动轻量。已验证的标签包括：**Providers**（`ProviderSettings`）、**模型上限**（`ModelLimitsSettings`）、**提示词**（`SystemPromptManager`）、**MCP**（服务器表单与管理）、**工作流**、**Hooks**、**计划任务 / Schedules**、**会话 / Sessions**、**环境变量 / Env Vars**、**关键词脱敏 / Keyword Masking**、**通知 / Notifications**、**Mermaid 设置**、**访问密码 / Access Password**、**网络 / Network**，以及基于 `recharts` 的 **指标仪表盘 / Metrics**（`UnifiedMetricsDashboard`、token 图、内存趋势、模型分布、转发端点分布等）。
+
+### 技能、追问、待办、Mermaid
+
+- **技能 / Skill** (`src/components/Skill`): `SkillCard` / `SkillSelector` / `SkillManager` 浏览智能体技能，开关启用/停用，显示许可证标记。
+- **追问对话 / Question dialog** (`src/components/QuestionDialog`): 当事件流出现 `need_clarification` 时弹出，支持预设选项与自由文本，并记住每个会话的推理强度（reasoning effort）。
+- **待办清单 / To-do list** (`src/components/TodoList` + `pages/ChatPage/components/TodoListDisplay`): 随 `task_list_updated` 等事件实时刷新进度、状态图标、依赖与备注，可折叠、可置顶。
+- **Mermaid 渲染** (`shared/components/MermaidChart`): 懒加载渲染器，超宽图自动适配视口，`react-zoom-pan-pinch` 缩放拖拽；渲染失败时提供 `onFix` 回调，把错误交给 AI 修复。
+
+---
+
+## 快速开始
+
+**前置：** Node.js LTS (20+) 与 npm。实时智能体功能需要一个运行中的 **bamboo** 后端（见下文）。
+
+```bash
+npm install
+npm run dev          # Vite dev server → http://localhost:1420
+```
+
+**与 bamboo 联调** — 在第二个终端，从仓库根目录运行：
+
+```bash
+cargo run --manifest-path bamboo/Cargo.toml --bin bamboo -- \
+  serve --port 9562 --bind 127.0.0.1 --data-dir /tmp/bamboo-data
+```
+
+Lotus 默认连接 `http://127.0.0.1:9562/v1` 后端（可通过 `VITE_BACKEND_BASE_URL` 覆盖；见 `src/shared/utils/backendBaseUrl.ts`）。
+
+### 常用脚本（`package.json`）
+
+```bash
+npm run dev               # Vite dev server (port 1420)
+npm run build             # tsc + vite build → dist/
+npm run preview           # preview the production build
+npm run type-check        # tsc --noEmit
+npm run lint              # eslint src   (lint:fix to autofix)
+npm run format            # prettier --write   (format:check to verify)
+
+npm run test              # vitest (watch)        test:ui / test:coverage
+npm run test:run          # vitest run (one-shot)
+npm run test:e2e          # Playwright (delegates to ./e2e)
+npm run test:e2e:browser  # Playwright against http://localhost:1420
+npm run test:e2e:with-server  # boots a throwaway bamboo, then runs Playwright
+
+npm run pack:dry-run      # inspect the npm package contents
+```
+
+### 打包与品牌（已验证）
+
+```bash
+npm run build:bamboo-package   # build, then stage dist into bamboo as a prebuilt frontend
+npm run build:public           # rebrand (public) + build
+npm run build:internal         # rebrand (internal) + build
+npm run rebrand:check          # verify branding state
+```
+
+以 **`@bigduu/lotus`** 发布（`publishConfig.access: public`）；`prepack` 会自动运行 `npm run build`。
+
+---
+
+## 其余技术栈
+
+Lotus 是 Zenith 单体仓库中的 UI 层，与以下模块协作：
+
+- [`../bamboo`](../bamboo) — 本地优先的 Rust 智能体运行时（Lotus 通过 HTTP + SSE 对话的执行引擎）
+- [`../bodhi`](../bodhi) — 桌面 AI 产品界面（加载 Lotus `dist/` 的 Tauri 外壳）
+- [`../bodhi-server`](../bodhi-server) — Go 后端（认证 / 持久化 / 计费 + 配额 / LLM 代理）
+- [`../pavilion`](../pavilion) — 官方网站与文档
+- [`..`](..) — Zenith 根目录（单体仓库入口、子模块指针、发布列车）
+
+**模块内文档：**
+
+- 前端文档根目录: [`docs/README.md`](./docs/README.md)
+- 前端架构: [`docs/architecture/FRONTEND_ARCHITECTURE.md`](./docs/architecture/FRONTEND_ARCHITECTURE.md)
+- 设计规范: [`docs/DESIGN_SPEC.md`](./docs/DESIGN_SPEC.md)
+- 功能文档（Command Selector / Question Dialog / Mermaid）: [`docs/features/`](./docs/features/)
+- 开发指南: [`docs/development/`](./docs/development/)