flare-chat-core 0.2.0 → 0.2.2

package/README.md

@@ -13,3 +13,31 @@ Chat 核心能力包。
 
 1. Chat GUI 宿主层。
 2. 生成式 UI 渲染层。
+
+## 架构边界文档
+
+1. `docs/SSOT-CHAT-CORE-BOUNDARY.md`（SSOT）
+2. `docs/SSOT-CHAT-CORE-DATAFLOW.md`（引用型）
+3. `docs/CHAT-CORE-BOUNDARY.md`（引用型）
+4. `docs/CAPABILITY-INVENTORY.md`
+
+## 开发运行
+
+已移除 `playground/`，统一使用根入口：
+
+1. `npm run dev`
+2. `npm run dev:real`
+3. `npm run build`
+4. `npm run preview`
+
+## 运行模式与调试开关（Core）
+
+Core 内置运行模式机制（`src/chat-core/runtime/runtimeMode.js`）：
+
+1. `VITE_FLARE_CHAT_RUNTIME_MODE`：可选，`development` / `production`
+2. `VITE_FLARE_CHAT_DEBUG`：可选，`1` 或 `true` 开启 debug 日志
+
+规则：
+
+1. **仅在非 production 模式下允许 debug 日志输出**
+2. 即使设置了 `VITE_FLARE_CHAT_DEBUG=1`，若模式为 production 也不会输出调试日志

package/docs/CAPABILITY-INVENTORY.md

@@ -0,0 +1,42 @@
+# Chat Core Capability Inventory
+
+> Scope: `packages/flare-chat-core`  
+> SSOT: `docs/SSOT-CHAT-CORE-BOUNDARY.md`
+
+| Capability ID | What | Public API | Owner Module | Status | SSOT Ref |
+|---|---|---|---|---|---|
+| CCORE-SES-001 | Session/round state orchestration | `useChatSessionReducer`, `chatSessionInitialState` | `src/chat-core/session/useChatSessionReducer.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-INP-001 | Chat input state/actions | `useChatInput` | `src/chat-core/input/useChatInput.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-STR-001 | SSE stream runtime orchestration | `useSSEStream` | `src/chat-core/stream/useSSEStream.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-STR-002 | SSE transport client | `SSEClient` | `src/chat-core/stream/sse-client.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-STR-003 | SSE event normalization helpers | `* from stream/sse-events` | `src/chat-core/stream/sse-events.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-MSG-001 | Timeline view-model assembly | `buildTimelineItems` | `src/chat-core/messages/buildTimelineItems.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-SES-002 | Session list lifecycle orchestration | `useSessionListController` | `src/chat-core/session/useSessionListController.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-STR-004 | Stream send lifecycle controller | `useStreamSendController` | `src/chat-core/stream/useStreamSendController.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-ORC-001 | Basic send handler orchestration | `useBasicSendHandler` | `src/chat-core/orchestration/useBasicSendHandler.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-FCD-001 | Basic conversation facade orchestration | `useBasicConversationFacade` | `src/chat-core/facade/useBasicConversationFacade.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-APP-001 | Core app assembly orchestration | `useCoreChatApp` | `src/chat-core/app/useCoreChatApp.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-APP-002 | App stream runtime hook | `useAppStream` | `src/chat-core/app/useAppStream.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+| CCORE-APP-003 | App mock runtime | `createMockRuntime` | `src/chat-core/app/mockRuntime.js` | active | `docs/SSOT-CHAT-CORE-BOUNDARY.md` |
+
+## Notes
+
+1. Inventory entries track exports from `src/chat-core/index.js`.
+2. New public API must be added here before cross-package usage.
+
+## Baseline Metrics（2026-04-18）
+
+### Code volume baseline
+
+1. `src/chat-core` 子模块文件数：**13**
+2. 超过 350 行文件：**3**
+   - `stream/sse-events.js`：**969**
+   - `session/useChatSessionReducer.js`：**553**
+   - `stream/useSSEStream.js`：**356**
+3. 200~350 行文件：**2**
+   - `app/useAppStream.js`：**292**
+   - `stream/sse-client.js`：**244**
+
+### Realignment workload baseline
+
+见：`docs/CORE-APP-REALIGNMENT-WORKLOAD-2026-04-18.md`

package/docs/CHAT-CORE-BOUNDARY.md

@@ -0,0 +1,47 @@
+# Chat Core Boundary（冻结版）
+
+> 引用型文档：以 `SSOT-CHAT-CORE-BOUNDARY.md` 为准；本文仅保留结构示例。
+
+## 1. 定位
+
+`flare-chat-core` 是 **可独立运行的前端应用壳**：  
+负责路由/页面装配、会话流程编排、状态聚合、API/SSE 接入。
+
+## 2. 责任边界（做什么）
+
+1. 页面内组装 `flare-chat-ui` 组件并注入状态/动作
+2. 会话与轮次状态机（session/round lifecycle）
+3. send/stream 执行编排
+4. API/SSE 事件消费与归一
+5. 路由入口管理（`/chat`、`/chat/new`、`/chat/:sessionId`）
+
+## 3. 非职责（不做什么）
+
+1. 不实现 `chat-ui` 组件库内部视觉细节
+2. 不在组件层散落复杂业务裁决
+3. 不在前端推断 authoritative backend state
+4. 不承载后端服务职责（非 SSR/非 Node API 服务）
+
+## 4. 推荐内部结构（目标）
+
+```text
+src/
+  app/            # 路由 + 页面装配（直接调用 flare-chat-ui）
+  state/          # reducer/store/selectors
+  orchestration/  # send/stream/round 编排
+  adapters/       # API/SSE client + normalize
+  contracts/      # 前端契约与守卫
+```
+
+## 5. 设计模式（约束）
+
+1. Orchestrator（唯一编排入口）
+2. Strategy Registry（规则集中，不散落 if/else）
+3. Adapter/Port（实现可替换）
+4. Assembler（仅装配，不拍板）
+
+## 6. 与 Chat UI 协作协议
+
+1. Core App 输出：页面级 `state + actions + route-context`
+2. UI 输入：用户事件（answer/select/confirm/cancel）
+3. authoritative 字段仅来自 API/SSE contract，不在 UI/Core 本地“猜状态”

package/docs/CORE-APP-REALIGNMENT-WORKLOAD-2026-04-18.md

@@ -0,0 +1,86 @@
+# Chat Core App Realignment Workload（2026-04-18）
+
+- Status: Draft-Confirmed
+- Scope: `packages/flare-chat-core`
+- Baseline Date: 2026-04-18
+
+## 1) 目标确认（本次结论）
+
+1. `chat-core` 定位为可独立运行的前端应用壳（非 SSR、非 Node API 服务）。
+2. `chat-core` 在 `src/app` 直接组装 `flare-chat-ui` + API/SSE + 状态编排。
+3. 不引入 `src/presentation` 额外层级。
+4. `chat-ui` 保持独立组件库定位。
+
+## 2) 当前工作量基线（实测）
+
+### 2.1 关键风险文件
+
+| 文件 | 行数 | 风险 |
+|---|---:|---|
+| `src/chat-core/stream/sse-events.js` | 969 | 单文件职责混合（协议/normalize/兼容） |
+| `src/chat-core/session/useChatSessionReducer.js` | 553 | 状态与行为集中度过高 |
+| `src/chat-core/stream/useSSEStream.js` | 356 | 事件分发分支过多 |
+
+### 2.2 结构化改造工作包
+
+| Workstream | 范围 | 预计文件变更数 | 预计人天 |
+|---|---|---:|---:|
+| WS1: 目录重整 | `src/app,state,orchestration,adapters,contracts` 建立并迁移入口 | 8-12 | 1.5-2.0 |
+| WS2: SSE 事件拆分 | 拆 `sse-events.js` 为多文件并保持 API 兼容 | 6-8 | 2.0-2.5 |
+| WS3: Stream 编排降复杂度 | `useSSEStream` 分发拆表驱动/handler map | 3-5 | 1.0-1.5 |
+| WS4: Session 状态收敛 | `useChatSessionReducer` 拆分 action/reducer/selectors | 4-6 | 1.5-2.0 |
+| WS5: App 路由落地 | `/chat` `/chat/new` `/chat/:sessionId` 页面装配 | 3-4 | 0.8-1.2 |
+| WS6: 回归与文档 | smoke/build/关键流测试 + 文档收敛 | 4-6 | 1.0-1.5 |
+
+**总计估算：7.8 ~ 10.7 人天（单人）**
+
+## 3) 迭代建议（最小风险顺序）
+
+1. Iteration-1（2~3 人天）  
+   - 完成 WS1 + WS2（先拆结构，0 语义变更）
+2. Iteration-2（2~3 人天）  
+   - 完成 WS3 + WS4（降低复杂度）
+3. Iteration-3（2~4 人天）  
+   - 完成 WS5 + WS6（路由收口与验收）
+
+## 4) 验收量化标准
+
+1. 超过 350 行文件数量：**从 3 降到 ≤1**
+2. `sse-events.js`：**从 969 行降到 ≤120 行（薄入口）**
+3. 路由入口覆盖：`/chat`、`/chat/new`、`/chat/:sessionId` **100% 可运行**
+4. UI 装配路径：统一经过 `src/app`，非 `app` 路径直连率降到 **0**
+5. 构建与基础回归：`npm run build` + 关键聊天发送链路 **通过**
+
+## 5) 风险与回滚点
+
+1. 风险：SSE 拆分后事件字段兼容性回归。  
+   - 回滚点：保留原 `sse-events.js` 导出签名不变。
+2. 风险：路由引入后会话切换状态错位。  
+   - 回滚点：先保留单页入口，再逐步切换到参数路由。
+3. 风险：reducer 拆分导致 action 名称漂移。  
+   - 回滚点：冻结 action type 常量，不改对外命名。
+
+## 6) 已完成进度（2026-04-18）
+
+### 6.1 已完成
+
+1. `src/app/App.jsx` 已建立并接入根入口。
+2. 新架构占位目录已落位：`src/app`、`src/state`、`src/orchestration`、`src/adapters`、`src/contracts`。
+3. `src/index.js` 已增加新层导出，保持旧 `chat-core/*` 导出兼容。
+
+### 6.2 占位文件
+
+1. `src/app/index.js`
+2. `src/state/index.js`
+3. `src/orchestration/index.js`
+4. `src/adapters/index.js`
+5. `src/contracts/index.js`
+
+### 6.3 当前完成率（按 WS）
+
+1. WS1（目录重整）：**40%**（目录与入口占位完成，逻辑迁移未开始）
+2. WS2（SSE 拆分）：**0%**
+3. WS3（Stream 降复杂度）：**0%**
+4. WS4（Session 收敛）：**0%**
+5. WS5（路由落地）：**10%**（入口集中已完成，路由未开始）
+6. WS6（回归与文档）：**20%**（SSOT/工作量文档已更新，专项回归未开始）

package/docs/SSOT-CHAT-CORE-BOUNDARY.md

@@ -0,0 +1,73 @@
+# SSOT: Chat Core Boundary
+
+> Chat Core 规范以本文为唯一准绳（SSOT）；其他文档仅可引用，不可平行定义。
+
+- Status: Active
+- Owner: FLARE Frontend/Core
+- Scope: `packages/flare-chat-core`
+- Last Updated: 2026-04-18
+
+## 1. 定位（唯一事实来源）
+
+`flare-chat-core` 是 **可独立运行的前端应用层中枢**（App-Orchestration Shell）。  
+它负责：页面装配、路由组织、会话流程编排、API/SSE 接入与状态推进。  
+它不是 SSR 应用，也不是 Node 后端服务。
+
+## 2. 职责（必须做）
+
+1. 作为宿主应用装配 `flare-chat-ui` 组件库（页面内实际调用）
+2. 管理路由与页面入口（如 `/chat`、`/chat/new`、`/chat/:sessionId`）
+3. 会话与轮次状态管理（session/round lifecycle）
+4. send / stream / completion 执行编排
+5. API/SSE 适配与 contract normalize
+6. 输出稳定 UI 所需状态（state/selectors）并驱动渲染
+
+## 3. 非职责（禁止做）
+
+1. 不实现 `flare-chat-ui` 组件库内部视觉细节
+2. 不把 UI 组件库业务逻辑反向塞回 `chat-ui`
+3. 不承载后端基础设施（非 Node 服务）
+4. 不以 SSR 形态承接当前链路
+
+## 4. 依赖方向（硬约束）
+
+允许：
+
+`contracts -> adapters -> orchestration -> state -> app`
+
+禁止：
+
+1. `chat-ui` 反向依赖 `chat-core` 内部实现细节
+2. `state/*` 直接触网
+3. 在页面组件中散落协议解析/复杂编排
+
+## 5. 目录落地（确定版）
+
+```text
+src/
+  app/            # 路由 + 页面装配（直接调用 flare-chat-ui）
+  state/          # reducer/store/selectors
+  orchestration/  # send/stream/round 编排
+  adapters/       # API/SSE client + normalize
+  contracts/      # 前端契约与守卫
+```
+
+说明：不新增 `src/presentation` 分层，避免过度设计。
+
+## 6. 与 Chat UI 协作边界
+
+1. `chat-ui` 是独立 UI 库，只接 props/callback
+2. `chat-core` 在 `src/app` 中直接组装并调用 `chat-ui`
+3. `chat-ui` 不读取 `chat-core` 内部模块路径
+
+## 7. 与 Kernel 协作边界
+
+1. authoritative workflow state 以 kernel canonical 为准
+2. core 可做体验态管理，但不得重定义 authoritative stage/status
+3. core 不得依赖“猜测”补齐 authoritative 字段
+
+## 8. 变更治理
+
+1. 新增业务流程逻辑必须先落在 core（`orchestration/state/adapters`）
+2. 页面呈现逻辑优先在 `src/app` 装配，避免抽象过早
+3. 若职责冲突，以本 SSOT 为准，先改边界再改代码

package/docs/SSOT-CHAT-CORE-DATAFLOW.md

@@ -0,0 +1,97 @@
+# SSOT: Chat Core Data Flow
+
+> 引用型文档：本文件遵循 `SSOT-CHAT-CORE-BOUNDARY.md`，仅维护数据流说明。
+
+- Status: Active
+- Owner: FLARE Core
+- Scope: `packages/flare-chat-core`
+- Last Updated: 2026-04-18
+
+## 1) 目标
+
+定义 chat-core 作为“可运行前端应用壳”的数据流与控制点。  
+chat-core 负责装配 UI + API + 状态编排，不采用 SSR。
+
+## 2) 核心分层
+
+1. App Layer（路由与页面装配）
+2. State Layer（authoritative/ui_local 状态）
+3. Orchestration Layer（round 生命周期与执行）
+4. Adapter Layer（API/SSE 连接与 normalize）
+5. Contract Layer（event/patch/schema 守卫）
+
+## 3) 端到端数据流（单轮）
+
+1. 路由进入页面（`/chat` / `/chat/new` / `/chat/:sessionId`）
+2. 页面装配 `flare-chat-ui` 并绑定 state + actions
+3. 用户触发意图事件（text submit / chooser select / confirm）
+4. orchestration 生成并发送请求（API + SSE）
+5. adapter 接收流事件并 normalize
+6. state/reducer 应用合法事件并更新快照
+7. app 将最新 state 映射到 UI props
+8. UI 重渲染并等待下一次用户动作
+
+## 4) 状态分层（必须）
+
+### 4.1 authoritative_state（来自 API/SSE contract）
+
+包含但不限于：
+
+1. `primary_flow`（stage/status/chooser_state）
+2. `checkpoint`
+3. `question`
+4. `confirmed_fields`
+5. `missing_fields`
+6. `next_actions`
+7. `analysis`
+8. `capabilities.*`
+
+### 4.2 ui_local_state（仅体验态）
+
+包含但不限于：
+
+1. 输入框草稿
+2. 面板开关
+3. 折叠/展开
+4. loading 标记
+5. 本地 hover/焦点
+
+禁止将 authoritative 字段写入 ui_local 作为“替代真相”。
+
+## 5) 事件字典（Core 视角）
+
+### 5.1 输入事件（UI -> Core App）
+
+1. `USER_MESSAGE_SUBMITTED`
+2. `CHOOSER_ANSWER_SUBMITTED`
+3. `CONFIRM_PLAN_CLICKED`
+4. `CONTINUE_COLLECTION_CLICKED`
+5. `INTERRUPT_ROUND_REQUESTED`
+6. `RESUME_ROUND_REQUESTED`
+
+### 5.2 流事件（Adapter -> Core State）
+
+1. `STREAM_ACK`
+2. `STREAM_PATCH_EVENT`
+3. `STREAM_DONE`
+4. `STREAM_ERROR`
+
+## 6) 控制点（硬约束）
+
+1. Round Gate：同一时刻仅 1 个 active round
+2. Authority Gate：只有合法 patch/event 才可改 authoritative_state
+3. Idempotency Gate：相同 `request_id + sequence` 不重复应用
+4. Route Gate：`sessionId` 与状态不一致时先对齐，再渲染
+5. Interrupt Gate：中断后保留已积累字段，不清空历史
+
+## 7) 非法输入与降级
+
+1. 非 contract 事件：忽略，不污染 authoritative
+2. patch_scope 与 payload 不匹配：拒绝该 patch，保留当前 authoritative
+3. `final` 文本只作为内容完成信号，不作为 authoritative patch
+
+## 8) 与 UI 协作契约
+
+1. UI 只能通过 app 绑定的 action API 触发流程
+2. UI 不得直接解析原始 SSE 事件作为主状态来源
+3. UI 只消费 app 注入的 props/view-state

package/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>flare-chat-core</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "flare-chat-core",
   "private": false,
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
+  "scripts": {
+    "dev": "vite --mode development",
+    "dev:real": "VITE_FLARE_CHAT_DEV_DEFAULT_BACKEND=real npm run dev",
+    "build": "vite build --mode production",
+    "preview": "vite preview --mode production --port 9001"
+  },
   "main": "./src/index.js",
   "module": "./src/index.js",
   "exports": {
@@ -14,9 +20,25 @@
     "./chat-core/session/useChatSessionReducer.js": "./src/chat-core/session/useChatSessionReducer.js",
     "./chat-core/stream/sse-client.js": "./src/chat-core/stream/sse-client.js",
     "./chat-core/stream/sse-events.js": "./src/chat-core/stream/sse-events.js",
-    "./chat-core/stream/useSSEStream.js": "./src/chat-core/stream/useSSEStream.js"
+    "./chat-core/stream/useSSEStream.js": "./src/chat-core/stream/useSSEStream.js",
+    "./chat-core/orchestration/useBasicSendHandler.js": "./src/chat-core/orchestration/useBasicSendHandler.js",
+    "./chat-core/session/useSessionListController.js": "./src/chat-core/session/useSessionListController.js",
+    "./chat-core/stream/useStreamSendController.js": "./src/chat-core/stream/useStreamSendController.js",
+    "./chat-core/facade/useBasicConversationFacade.js": "./src/chat-core/facade/useBasicConversationFacade.js",
+    "./chat-core/app/useCoreChatApp.js": "./src/chat-core/app/useCoreChatApp.js",
+    "./chat-core/app/useAppStream.js": "./src/chat-core/app/useAppStream.js",
+    "./chat-core/app/mockRuntime.js": "./src/chat-core/app/mockRuntime.js"
   },
   "peerDependencies": {
     "react": "^18.0.0"
+  },
+  "devDependencies": {
+    "@ant-design/icons": "^6.0.0",
+    "@vitejs/plugin-react": "^5.1.1",
+    "antd": "^6.2.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "vite": "^7.2.4",
+    "flare-chat-ui": "file:../flare-chat-ui"
   }
 }

package/src/adapters/index.js

@@ -0,0 +1,6 @@
+export { SSEClient } from './sse-client.js';
+export { createSessionMessageAPI } from './session-message-api.js';
+export { useSSEStream } from '../orchestration/useSSEStream.js';
+export { useAppStream } from '../chat-core/app/useAppStream.js';
+export { createMockRuntime } from '../chat-core/app/mockRuntime.js';
+export { dispatchSSEEvent } from './sse-event-dispatcher.js';

package/src/adapters/message-api.adapter.js

@@ -0,0 +1,59 @@
+import { normalizeMessageRecord } from './session-message-api.normalizers.js';
+import { requestJsonWithRouteFallback } from './session-message-api.http.js';
+
+export function createMessageAPI(requestOptions, routeState) {
+  return {
+    async list(sessionId, params = {}) {
+      const resolvedSessionId = String(sessionId || '').trim();
+      if (!resolvedSessionId) {
+        throw new Error('sessionId is required');
+      }
+      const query = new URLSearchParams();
+      if (params.page !== undefined) query.set('page', String(params.page));
+      if (params.page_size !== undefined) query.set('page_size', String(params.page_size));
+      const suffix = query.size > 0 ? `?${query.toString()}` : '';
+      const encodedSessionId = encodeURIComponent(resolvedSessionId);
+      let response;
+      try {
+        response = await requestJsonWithRouteFallback({
+          buildPath: (mode) => (mode === 'chat'
+            ? `/chat/sessions/${encodedSessionId}/messages${suffix}`
+            : `/sessions/${encodedSessionId}/messages${suffix}`),
+          method: 'GET',
+          options: requestOptions,
+          routeMode: routeState.sessionMessageRouteMode,
+          setRouteMode: (nextMode) => {
+            routeState.sessionMessageRouteMode = nextMode;
+          },
+        });
+      } catch (error) {
+        if (Number(error?.status) !== 404) {
+          throw error;
+        }
+        const fallbackQuery = new URLSearchParams();
+        fallbackQuery.set('session_id', resolvedSessionId);
+        if (params.page !== undefined) fallbackQuery.set('page', String(params.page));
+        if (params.page_size !== undefined) fallbackQuery.set('page_size', String(params.page_size));
+        response = await requestJsonWithRouteFallback({
+          buildPath: (mode) => (mode === 'chat'
+            ? `/chat/messages?${fallbackQuery.toString()}`
+            : `/messages?${fallbackQuery.toString()}`),
+          method: 'GET',
+          options: requestOptions,
+          routeMode: routeState.messageCollectionRouteMode,
+          setRouteMode: (nextMode) => {
+            routeState.messageCollectionRouteMode = nextMode;
+          },
+        });
+      }
+      const source = Array.isArray(response?.messages)
+        ? response.messages
+        : Array.isArray(response?.data?.messages)
+          ? response.data.messages
+          : [];
+      return {
+        messages: source.map(normalizeMessageRecord),
+      };
+    },
+  };
+}

package/src/adapters/session-api.adapter.js

@@ -0,0 +1,133 @@
+import { normalizeSessionRecord } from './session-message-api.normalizers.js';
+import { requestJsonWithRouteFallback } from './session-message-api.http.js';
+
+export function createSessionAPI(requestOptions, routeState) {
+  return {
+    async list(params = {}) {
+      const query = new URLSearchParams();
+      if (params.page !== undefined) query.set('page', String(params.page));
+      if (params.page_size !== undefined) query.set('page_size', String(params.page_size));
+      if (params.status) query.set('status', String(params.status));
+      if (params.function_type) query.set('function_type', String(params.function_type));
+      if (params.project_id) query.set('project_id', String(params.project_id));
+      const suffix = query.size > 0 ? `?${query.toString()}` : '';
+      const response = await requestJsonWithRouteFallback({
+        buildPath: (mode) => (mode === 'chat' ? `/chat/sessions${suffix}` : `/sessions${suffix}`),
+        method: 'GET',
+        options: requestOptions,
+        routeMode: routeState.sessionCollectionRouteMode,
+        setRouteMode: (nextMode) => {
+          routeState.sessionCollectionRouteMode = nextMode;
+        },
+      });
+      const source = Array.isArray(response?.sessions)
+        ? response.sessions
+        : Array.isArray(response?.data?.sessions)
+          ? response.data.sessions
+          : [];
+      return {
+        sessions: source.map(normalizeSessionRecord),
+      };
+    },
+
+    async get(sessionId) {
+      const resolvedSessionId = String(sessionId || '').trim();
+      if (!resolvedSessionId) {
+        throw new Error('sessionId is required');
+      }
+      const encodedSessionId = encodeURIComponent(resolvedSessionId);
+      try {
+        const response = await requestJsonWithRouteFallback({
+          buildPath: (mode) => (mode === 'chat'
+            ? `/chat/sessions/${encodedSessionId}`
+            : `/sessions/${encodedSessionId}`),
+          method: 'GET',
+          options: requestOptions,
+          routeMode: routeState.sessionDetailRouteMode,
+          setRouteMode: (nextMode) => {
+            routeState.sessionDetailRouteMode = nextMode;
+          },
+        });
+        return normalizeSessionRecord(response?.data || response);
+      } catch (error) {
+        if (Number(error?.status) !== 404) {
+          throw error;
+        }
+        const listResponse = await requestJsonWithRouteFallback({
+          buildPath: (mode) => (mode === 'chat'
+            ? '/chat/sessions?page=1&page_size=200'
+            : '/sessions?page=1&page_size=200'),
+          method: 'GET',
+          options: requestOptions,
+          routeMode: routeState.sessionCollectionRouteMode,
+          setRouteMode: (nextMode) => {
+            routeState.sessionCollectionRouteMode = nextMode;
+          },
+        });
+        const source = Array.isArray(listResponse?.sessions)
+          ? listResponse.sessions
+          : Array.isArray(listResponse?.data?.sessions)
+            ? listResponse.data.sessions
+            : [];
+        const matched = source
+          .map(normalizeSessionRecord)
+          .find((item) => String(item?.sessionId || '').trim() === resolvedSessionId);
+        if (!matched) {
+          throw error;
+        }
+        return matched;
+      }
+    },
+
+    async create(payload = {}) {
+      const body = {
+        function_type: payload.function_type ?? 'default',
+        title: payload.title ?? '新会话',
+        project_id: payload.project_id ?? null,
+        user_id: payload.user_id ?? null,
+      };
+      const response = await requestJsonWithRouteFallback({
+        buildPath: (mode) => (mode === 'chat' ? '/chat/sessions' : '/sessions'),
+        method: 'POST',
+        body,
+        options: requestOptions,
+        routeMode: routeState.sessionCollectionRouteMode,
+        setRouteMode: (nextMode) => {
+          routeState.sessionCollectionRouteMode = nextMode;
+        },
+      });
+      return normalizeSessionRecord(response?.data || response);
+    },
+
+    async update(sessionId, payload = {}) {
+      const resolvedSessionId = String(sessionId || '').trim();
+      if (!resolvedSessionId) {
+        throw new Error('sessionId is required');
+      }
+      const body = {};
+      if (payload.title !== undefined) {
+        body.title = payload.title;
+      }
+      if (payload.status !== undefined) {
+        body.status = payload.status;
+      }
+      if (payload.function_type !== undefined) {
+        body.function_type = payload.function_type;
+      }
+      const encodedSessionId = encodeURIComponent(resolvedSessionId);
+      const response = await requestJsonWithRouteFallback({
+        buildPath: (mode) => (mode === 'chat'
+          ? `/chat/sessions/${encodedSessionId}`
+          : `/sessions/${encodedSessionId}`),
+        method: 'PATCH',
+        body,
+        options: requestOptions,
+        routeMode: routeState.sessionDetailRouteMode,
+        setRouteMode: (nextMode) => {
+          routeState.sessionDetailRouteMode = nextMode;
+        },
+      });
+      return normalizeSessionRecord(response?.data || response);
+    },
+  };
+}