Jesse_Chen
a6148af845
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LVapmh2oGNyr6ECHKjPJY8
70 lines
5.6 KiB
Markdown
70 lines
5.6 KiB
Markdown
# 任务书 · 拆分首页巨石组件·第二批：聊天主链路（2026-09-01）
|
||
|
||
基线：**`TASK-contract-repairs-20260901.md`（小刀轮）落地后的 `origin/staging` 最新提交**。小刀轮未落地不得开工——它会修改本轮要搬的函数区域的契约测试读取面，顺序反了两边都返工。与其它改 `page.tsx` 的轮次不得并行。
|
||
|
||
**本轮性质仍是纯搬家。** 第一批（`54269fcf`）的全部红线原样适用；本任务书只写增量。第一批的 PROGRESS 与 `tests/home-surface.ts` 拼接件是本轮的直接样板。
|
||
|
||
---
|
||
|
||
## 为什么要做（事故实证）
|
||
|
||
行号基于 `54269fcf`，按符号定位。
|
||
|
||
1. 第一批后 `page.tsx` 还有 3,505 行，其中 `Home` 内的**咨询引擎**是最大的一坨：`send`（2340–2907，约 570 行）、`restoreConsultationRecovery`（623 起）、`requestCancellation` / `confirmCancellation` / `stopResponse`（2152–2329）、`completeConsultationInterface`（2330），连同其独占的 streaming/pending/cancellation state 与 refs，合计约 1,000+ 行。
|
||
2. **会话管理簇**次之：`persistSession` / `ensureSessionMessages` / `continueInNewChat` / `renameSession` / `deleteSession` / `togglePinnedSession` / `toggleArchivedSession` / `shareSession` / `startNewChat` / `selectSession` / `selectSessionModel`（1279–1581）加 URL/popstate 胶水，约 300 行。
|
||
3. 第一批目标 ≤3,000 未达标的声明原因正是这两簇"本批不动"。现在动。
|
||
|
||
## 决策记录（产品授权，2026-09-01）
|
||
|
||
1. **允许以自定义 hook 形式整体搬移**（`frontend/src/hooks/use-consultation-run.ts`、`use-session-management.ts`）。自定义 hook 不在"不得手写 `useCallback`/`useMemo`"红线内——那条红线继续禁的是记忆化原语，不是 hook 抽取。
|
||
2. 搬移的正确性标准与第一批相同：**函数体逐行一致**（允许的差异仅：缩进、`export`、跨边界标识符经参数/返回值改道）。改名清单应为零或接近零，全部列进 PROGRESS。
|
||
3. 状态归属规则沿用第一批：仅引擎独占的 state/refs 进 hook；与 JSX 共享的由 hook 返回或经参数传入。**不得引入 context/store**；参数与返回值显式类型。
|
||
4. 第一批"useState 不下移"的星盘库草稿等结论不受本轮影响——那些 state 不在本轮范围。
|
||
|
||
## 硬红线（在第一批红线之上追加）
|
||
|
||
1. **hook 调用顺序不变**：被搬 state/refs 必须整块连续搬移、保持相对声明顺序；hook 只能无条件调用。搬完后 `Home` 内剩余 hook 与新 hook 内部的声明顺序串接起来必须与搬前逐一对应，PROGRESS 给出对应表或说明核对方式。
|
||
2. **测试重指仍走定向豁免**：新文件加入 `tests/home-surface.ts` 拼接清单与 Python 侧 `_home_surface()`；仍直接读 `page.tsx` 且其 token 被搬走的测试（动手前 `grep -rn 'app/page.tsx' frontend/tests tests` 列全量清单）只许换读取面，断言内容不变。小刀轮刚修好的两个文件必须保持全绿。
|
||
3. 目标：`page.tsx` **≤ 2,600 行**；不达标写明剩余块与原因。
|
||
4. 测试基线以开工时 `origin/staging` 实测为准（小刀轮可能加了测试数；fail=0、skipped=0 于 Docker 环境，无 Docker 逐条比对既有缺口清单）。
|
||
5. 其余同第一批：行为零变化、疑似 bug 登记 `BLOCKED.md`、`site-styles` import 结构不动、`/` 保持 `○ Static`、首屏 gzip ±2%、tsc、不改 `.gitea/workflows/**`、不动数据库、不重开 React Compiler。
|
||
|
||
让步顺序：功能与测试不回归 > 可验证的拆分 > 拆分行数目标 > 代码整洁。
|
||
|
||
## 开工前置
|
||
|
||
```bash
|
||
git fetch origin --prune
|
||
git worktree add -b codex/home-split-batch2-20260901 \
|
||
../.worktrees/home-split-batch2-20260901 origin/staging
|
||
```
|
||
|
||
确认 `origin/staging` 已包含小刀轮提交。读第一批 `PROGRESS-home-split-20260901.md` 全篇、`pre_work_error_ledger.md`、`frontend/AGENTS.md`、`BLOCKED.md` 2026-08-17 记录。
|
||
|
||
## 任务分解
|
||
|
||
### 任务 1（P0）· 咨询引擎出仓
|
||
|
||
- `send` / `stopResponse` / `requestCancellation` / `confirmCancellation` / `completeConsultationInterface` / `restoreConsultationRecovery` 及其独占 state/refs（streamingReply、pendingConsultation、consultationPhase、cancellation 系等，以实际独占性为准）整体搬入 `hooks/use-consultation-run.ts`。
|
||
- 跨边界依赖（router、composerInput、profile、sessions 写入器、rectification 胶水回调等）经显式参数传入。
|
||
|
||
### 任务 2（P1）· 会话管理出仓
|
||
|
||
- 1279–1581 的会话管理簇 + URL/popstate 胶水（含小刀轮改过的 `applySessionPopStateRef` 分支，**原样搬**）搬入 `hooks/use-session-management.ts`。
|
||
- 与任务 1 的边界：`send` 需要的 `updateSession` / `persistSession` 等由会话管理 hook 返回、经 Home 传入咨询引擎 hook，方向单一，不得互相 import。
|
||
|
||
### 任务 3（P1）· 读取面与度量
|
||
|
||
- `home-surface.ts` / `_home_surface()` 扩容；受影响测试清单（原路径 → 新路径）逐条登记。
|
||
- PROGRESS 度量表同第一批口径：行数、useState/useEffect 分布（Home 与两个 hook 分列）、首屏 gzip 对比、`/` 路由模式。
|
||
|
||
## 总验收
|
||
|
||
同第一批四条，另加：hook 顺序核对说明（红线 1）；两个新 hook 文件的函数体与搬前逐行 diff 说明（决策记录 2）；小刀轮两个 Python 文件保持全绿的 pytest 输出。
|
||
|
||
## 明确不做
|
||
|
||
- 不动 onboarding/profile 簇（1582–1835）与 rectification 胶水（1888–2075）——若第二批顺利，另行第三批。
|
||
- 不做任何行为修正（popstate 已在小刀轮完成，本轮原样搬）。
|
||
- 不引入 context/store/新依赖；不重开 React Compiler。
|