# 笔临 P4 交互式写作设计规格

**版本**：1.0  
**日期**：2026-07-08  
**范围**：P4 严格（选项 A）— 仅实装「交互式写作」全流程（§6.5.1）  
**前置**：P2.1 + P3 已交付（v0.3.0，`8ce35a1`）  
**参考**：`design/readme.md` v1.1 §6.5.1、`design/ui_pc.html` AI 面板交互写作原型

**目标版本**：v0.4.0

---

## 1. 背景与目标

### 1.1 阶段定位

v0.3.0 已交付 AI 对话模式；「交互 / 自动 / 向导」写作 Tab 仍为占位。本阶段实装 **交互式写作**：以场景为单位的剧情走向建议 → 场景生成 → 命名暂停 → 微调确认 → 循环 → 成章落盘，全流程状态持久化并可恢复。

### 1.2 已确认决策（Brainstorming 2026-07-08）

| 维度 | 决策 |
|------|------|
| 范围 | **P4 严格**：仅 §6.5.1 交互式写作；自动 / 向导仍占位 |
| 实现方案 | **方案 1**：专用状态机 + 独立 DB 表 + 逐步 IPC |
| 成章落盘 | 当前活跃卷 **新建章节**，`origin=interactive`，合并全部场景后自动打开编辑器 |
| 命名暂停 | **完整实装**：生成中暂停，5 选项 + 自定义输入，选定后续写 |
| 状态持久化 | **schema v4**，`interactive_flows` / `interactive_scenes`，重启可恢复 |
| 启动门槛 | **硬拦截**：无章节正文且无大纲/设定时 Tab 禁用 |
| AI 后端 | **LM Studio**（延续 P3），`http://127.0.0.1:1234`，`gemma-4-e4b-it` |
| 测试原则 | **禁止 Mock**；集成 / E2E 打真实 LM Studio |
| 测试超时 | 本地模型慢，Vitest AI 用例 **180–240s**，Playwright 全局 **180s**，交互 E2E **300s** |
| 工程 | `test-results/` 加入 `.gitignore` |

### 1.3 验收标准

用户能完成：

1. 在有足够上下文的书籍中进入「交互写作」Tab（门槛不满足时 Tab 禁用并提示）
2. 确认 / 编辑 AI 上下文后，收到 3 条剧情走向建议（每条 ≥50 字说明）
3. 选择走向（可附补充指令）后，流式生成一个场景（600–1500 字）
4. 生成中若 AI 要求命名，流程暂停并展示 5 个命名选项；选定后自动续写完成场景
5. 对场景输入微调指令，AI 针对当前场景修订（不重写全章）
6. 满意后进入下一场景循环，或点击「结束本章」
7. 结束时在当前活跃卷创建新章节，内容为全部场景合并 HTML，标记为交互初稿，编辑器自动打开
8. 关闭应用并重启后，未完成的交互流程恢复到上次步骤
9. 切换回「对话」模式时，同会话聊天历史仍可见；再次进入交互模式时流程按规格重新初始化

### 1.4 本规格不实现（明确排除）

| 项 | 归属 |
|----|------|
| §6.5.2 自动写作 | P4.1+ |
| §6.5.3 向导式写作 | P4.1+ |
| §6.3 文风学习与风格滑杆 | P4.1+ |
| §6.6 大纲生成章节骨架 | P4.1+ |
| §6.7 知识抽取与审核工作流 | P4.1+ |
| §6.4 Skill / MCP | P4+ |
| 命名结果自动写入设定库 | 本阶段仅写入正文 |
| 导入导出、驾驶舱等 | P5+ |

---

## 2. 架构

### 2.1 进程模型

```
┌──────────────────────────────────────────────────────────────┐
│ 主进程                                                        │
│  · schema v4：interactive_flows / interactive_scenes         │
│  · chapters.origin 列（manual | interactive）                  │
│  · InteractiveWritingService（步骤机 + 持久化）                 │
│  · InteractivePromptBuilder（各步 prompt / JSON 约束）        │
│  · AiClientService（复用：JSON 步非流式，场景步流式 SSE）        │
│  · AiContextBuilder（复用）                                    │
│  · IPC：interactive:* + interactive:streamChunk 事件           │
└────────────────────────────┬─────────────────────────────────┘
                             │ contextBridge
┌────────────────────────────▼─────────────────────────────────┐
│ 渲染进程                                                       │
│  · AiPanel：writingMode=interactive 时挂载 InteractivePanel    │
│  · InteractivePanel：步骤 UI（走向卡片、命名暂停、场景预览）     │
│  · useInteractiveStore：IPC + 流式缓冲                          │
│  · ContextEditorModal（复用，上下文确认步）                     │
└──────────────────────────────────────────────────────────────┘
```

**约束**（延续 P0–P3）：

- 渲染进程禁止直接 `fetch` AI API
- 流式通过 `webContents.send` 推送，不阻塞 IPC invoke
- 交互流程绑定 `ai_session_id`；`ai_messages` 仍记录关键轮次作审计

### 2.2 步骤机

| Step | 名称 | AI | 持久化字段 |
|------|------|-----|-----------|
| `context_confirm` | 上下文确认 | 无 | `context_json` |
| `plot_suggest` | 剧情走向 | JSON ×3 | — |
| `plot_select` | 用户选择 | 无 | `plot_selection_json` |
| `scene_generate` | 场景生成 | 流式 | 可能写入 `naming_pending_json` |
| `naming_pause` | 命名暂停 | 流式续写 | `naming_pending_json` 清空后 |
| `scene_review` | 场景确认/微调 | 流式（可选） | — |
| `loop` | 下一场景 | 回到 `plot_suggest` | `interactive_scenes` 追加 |
| `completed` | 成章完成 | 无 | `status=completed` |

切换到交互模式：调用 `interactive:start`，创建或重置 `flow`（`status=in_progress`）。切换离开交互模式不删除 flow；再次 `start` 时重新初始化。

### 2.3 Schema v4（每本书 `.sqlite`）

```sql
-- schema-v4.sql
ALTER TABLE chapters ADD COLUMN origin TEXT NOT NULL DEFAULT 'manual';

CREATE TABLE IF NOT EXISTS interactive_flows (
    id                   TEXT PRIMARY KEY,
    session_id           TEXT NOT NULL,
    step                 TEXT NOT NULL,
    status               TEXT NOT NULL DEFAULT 'in_progress',
    context_json         TEXT NOT NULL DEFAULT '{}',
    plot_selection_json  TEXT,
    naming_pending_json  TEXT,
    created_at           TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at           TEXT NOT NULL DEFAULT (datetime('now')),
    FOREIGN KEY (session_id) REFERENCES ai_sessions(id) ON DELETE CASCADE
);

CREATE TABLE IF NOT EXISTS interactive_scenes (
    id           TEXT PRIMARY KEY,
    flow_id      TEXT NOT NULL,
    sort_order   INTEGER NOT NULL DEFAULT 0,
    content_html TEXT NOT NULL DEFAULT '',
    plot_label   TEXT NOT NULL DEFAULT '',
    refined_count INTEGER NOT NULL DEFAULT 0,
    created_at   TEXT NOT NULL DEFAULT (datetime('now')),
    FOREIGN KEY (flow_id) REFERENCES interactive_flows(id) ON DELETE CASCADE
);

CREATE INDEX IF NOT EXISTS idx_interactive_flows_session ON interactive_flows(session_id);
CREATE INDEX IF NOT EXISTS idx_interactive_scenes_flow ON interactive_scenes(flow_id, sort_order);
```

`migrate.ts`：`version 3 → 4` 应用上述 DDL。

---

## 3. 共享类型

```typescript
export type InteractiveStep =
  | 'context_confirm'
  | 'plot_suggest'
  | 'plot_select'
  | 'scene_generate'
  | 'naming_pause'
  | 'scene_review'
  | 'completed'

export type InteractiveFlowStatus = 'in_progress' | 'completed' | 'abandoned'
export type ChapterOrigin = 'manual' | 'interactive'

export interface PlotOption {
  id: 'A' | 'B' | 'C'
  label: string
  summary: string
}

export interface NamingPause {
  elementType: string
  context: string
  options: string[] // 长度 5
}

export interface PlotSelection {
  optionIds: Array<'A' | 'B' | 'C'>
  userNote?: string
}

export interface InteractiveScene {
  id: string
  sortOrder: number
  contentHtml: string
  plotLabel: string
  refinedCount: number
}

export interface InteractiveFlow {
  id: string
  sessionId: string
  step: InteractiveStep
  status: InteractiveFlowStatus
  scenes: InteractiveScene[]
  namingPending?: NamingPause | null
  contextSummary?: string
}

export interface InteractiveGateResult {
  eligible: boolean
  reason?: 'no_chapter' | 'no_outline_or_setting'
}

export interface InteractiveStreamChunkEvent {
  flowId: string
  phase: 'scene' | 'refine' | 'naming_resume'
  delta: string
  done: boolean
}
```

`Chapter` 接口增加可选 `origin?: ChapterOrigin`（读取时填充，默认 `manual`）。

---

## 4. IPC 接口

### 4.1 通道列表

| 通道 | 说明 |
|------|------|
| `interactive:checkGate` | 门槛检查 |
| `interactive:getFlow` | 按 session 恢复 flow |
| `interactive:start` | 初始化 / 重置流程 |
| `interactive:confirmContext` | 保存上下文 binding，进入 plot_suggest |
| `interactive:suggestPlots` | AI 返回 3 条走向 |
| `interactive:selectPlot` | 记录用户选择 |
| `interactive:generateScene` | 开始场景流式生成 |
| `interactive:resolveNaming` | 命名选择后续写 |
| `interactive:refineScene` | 场景微调（流式） |
| `interactive:acceptScene` | 确认场景，写入 scenes 表 |
| `interactive:finishChapter` | 合并场景 → 新建章节 |
| `interactive:abort` | 中止当前 AI 请求 |

事件：`interactive:streamChunk` → `InteractiveStreamChunkEvent`

### 4.2 门槛逻辑（`checkGate`）

`eligible = true` 当满足任一：

- 存在至少 1 章，`stripHtml(content).trim().length > 0`
- `outline_items` 表非空
- `settings` 表非空

否则 `eligible = false`，`reason` 区分无章节正文 vs 无大纲设定。

### 4.3 成章逻辑（`finishChapter`）

1. 校验 `activeVolumeId` 存在（来自调用方或书籍默认第一卷）
2. 按 `sort_order` 合并 `interactive_scenes.content_html`，段落间插入空行
3. `chapter.create(volumeId, title ?? '交互初稿')`，`origin='interactive'`，`status='draft'`
4. `flow.status = 'completed'`，`step = 'completed'`
5. 创建 `type='ai'` 快照（标签「交互写作成章」）
6. 返回 `{ chapterId }`

---

## 5. Prompt 策略

`InteractivePromptBuilder` 为各步构建 `ChatMessage[]`：

### 5.1 走向建议（`suggestPlots`）

- System：你是小说创作助手；基于上下文给出 3 个互斥剧情走向；仅返回 JSON
- 格式：`{ "plots": [{ "id": "A", "label": "...", "summary": "..." }] }`
- 约束：恰好 3 条；`summary` ≥50 汉字
- 非流式；解析失败重试 1 次（追加「仅返回 JSON，不要 markdown」）

### 5.2 场景生成（`generateScene`）

- 注入：上下文块 + 已确认场景摘要 + 选定走向 + 用户补充
- 若需新命名：先返回单行 JSON  
  `{"type":"naming_required","elementType":"角色","context":"...","options":["名1",...,"名5"]}`
- 否则流式输出场景 HTML（`<p>` 段落，600–1500 字）
- 交互步 `max_tokens` 覆盖为 **4096**（不改全局 `aiConfig.maxTokens`）

### 5.3 命名续写（`resolveNaming`）

- User：用户选定名称 `{chosen}`，请继续完成当前场景
- 流式输出剩余正文

### 5.4 场景微调（`refineScene`）

- User：在保持情节连贯前提下，按指令修改当前场景：`{instruction}`
- 流式输出完整修订后场景（覆盖当前草稿）

---

## 6. 错误处理

| 场景 | 行为 |
|------|------|
| AI 超时 | `IpcError` recoverable；toast「AI 响应超时」；留在当前步，可重试 |
| JSON 解析失败 | 自动重试 1 次；仍失败则 toast + 留在 `plot_suggest` |
| 流式中断 | 保留已收 delta；提供「重新生成」 |
| 无活跃卷 | `finishChapter` 返回错误码，提示创建卷 |
| 切换书籍 | DB 状态保留；`getFlow` 恢复 |
| 云端后端 + 离线 | 与 P3 一致禁用输入；LM Studio 不受影响 |
| `interactive:abort` | 中止 fetch；不清除 flow 状态 |

---

## 7. UI 规格

### 7.1 入口

- `AiPanel` 模式 Tab：`interactive` 可点击；`auto` / `wizard` 仍 `feature.comingSoon`
- 挂载时 `checkGate`；`!eligible` → Tab `disabled` + `title` 提示
- `writingMode === 'interactive'` 时主区渲染 `InteractivePanel`

### 7.2 InteractivePanel 布局

1. **步骤指示器** — 上下文 → 走向 → 场景 → 确认  
2. **主内容**（按 `flow.step`）  
   - `context_confirm`：摘要 +「编辑上下文」+「开始交互」  
   - `plot_suggest` / `plot_select`：`PlotOptionCard` ×3，多选 + 补充输入  
   - `scene_generate` / `naming_pause`：流式预览；命名时覆盖为选项列表 + 自定义  
   - `scene_review`：全文预览 + 微调输入 +「下一场景」/「结束本章」  
3. **底栏** — 主操作按钮；与 `ai-offline-banner` 联动  

样式参考 `design/ui_pc.html`：`.ai-mode-tab`、`.plot-opt`、`.opt-label`。

### 7.3 成章后导航

`finishChapter` 成功 → `openBook` → `setSelectedChapter(chapterId)` → `setView('editor')` → toast `interactive.chapterCreated`。

---

## 8. 工程配套

### 8.1 `.gitignore`

```
test-results/
```

### 8.2 测试超时配置

| 位置 | 值 |
|------|-----|
| `playwright.config.ts` `timeout` | `180_000` |
| E2E 交互用例 `test.setTimeout` | `300_000` |
| E2E 助手回复 `expect` | `120_000` |
| Vitest `IT-INT-01/02/03` | `180_000` / `240_000` / `240_000` |
| 现有 `IT-AI-01` | 保持 `90_000` 或升至 `180_000` |
| 现有 `IT-NAME-01` | 保持 `180_000` |

### 8.3 LM Studio 前置

与 P3 相同：`BILIN_AI_BASE_URL` / `BILIN_AI_MODEL` 环境变量由主进程 `global-settings` 读取；渲染进程不使用 `process.env`。

---

## 9. 测试要求

### 9.1 单元 / 集成（Vitest，禁止 Mock）

| 用例 ID | 场景 | 超时 |
|---------|------|------|
| IT-INT-01 | `suggestPlots` 返回 3 条合法 JSON | 180s |
| IT-INT-02 | `generateScene` 流式正文非空 | 240s |
| IT-INT-03 | naming JSON → `resolveNaming` 后续有内容 | 240s |
| IT-INT-04 | `acceptScene` ×2 + `finishChapter` 创建 `origin=interactive` 章节 | 60s |
| IT-INT-05 | `checkGate` 门槛 true/false 分支 | 5s |
| IT-MIG-04 | schema v3→v4 迁移 | 5s |

### 9.2 E2E（Playwright + Electron）

| 用例 ID | 场景 | 超时 |
|---------|------|------|
| E2E-INT-01 | 选走向 → 生成 → 接受 → 结束本章 → 编辑器有内容 | 300s |
| E2E-INT-02 | 空书交互 Tab 禁用 | 30s |
| E2E-INT-03 | 重启后恢复 flow 步骤 | 300s |

文件：`e2e/interactive-writing.spec.ts`

---

## 10. 文件清单（实现参考）

| 文件 | 职责 |
|------|------|
| `src/main/db/schema-v4.sql` | v4 DDL |
| `src/main/db/migrate.ts` | v3→v4 |
| `src/main/db/repositories/interactive.repo.ts` | flow / scene CRUD |
| `src/main/services/interactive-writing.service.ts` | 步骤机 |
| `src/main/services/interactive-prompt-builder.service.ts` | Prompt |
| `src/main/ipc/handlers/interactive.handler.ts` | IPC |
| `src/shared/ipc-channels.ts` | 新通道 |
| `src/shared/types.ts` | 交互类型 + `ChapterOrigin` |
| `src/preload/index.ts` | API + 事件 |
| `src/renderer/components/ai/InteractivePanel.tsx` | 主 UI |
| `src/renderer/components/ai/PlotOptionCard.tsx` | 走向卡片 |
| `src/renderer/stores/useInteractiveStore.ts` | 状态 |
| `e2e/interactive-writing.spec.ts` | E2E |
| `tests/main/interactive-*.test.ts` | 集成测试 |

---

## 11. 规格自检

| 检查项 | 结果 |
|--------|------|
| Placeholder 扫描 | 自动/向导明确排除至 P4.1+；无 TBD |
| 内部一致性 | 步骤机、IPC、DB、UI 步骤名称一致 |
| 范围 | 单阶段可交付 v0.4.0 |
| 歧义 | 成章=新建章节+interactive origin；门槛=硬拦截 |

---

*本规格为笔临 P4 子项目。自动写作、知识抽取等各自在后续 spec 中增量修订。*