diff --git a/AGENTS.md b/AGENTS.md index 69d4c914..d12c33ae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,6 +79,7 @@ The frontend (`frontend-web/`) is a React 19 + Vite SPA: - **Routing**: React Router v7; top-level routes in `src/pages/PageRoutes.tsx`, workspace sub-routes in `src/pages/WorkspaceRoutes.tsx` - **Pages**: `ChatPage` (thread chat), `AgentChatPage` (custom agent chat), `AgentsPage`/`NewAgentPage` (agent management), `ScheduledTasksPage`/`ScheduledTaskRunDetailPage` (scheduled tasks), `LightAppManagementPage`/`LightAppListPage`/`LightAppIframeView` (轻应用中心 — register/list/embed mini-apps) +- **AI 写作·对话版（对话驱动写作台）**: a **parallel new entry** beside the classic AI-writing page (classic page/routes untouched) — route `/page/canvas/ai-writing-chat`, sidebar 「问答管理 → 课题研究(对话版)」. Page `open-canvas/pages/AIWritingChatPage.tsx` reuses the engine (`AIWritingContext` + `useStream` + `AIWritingDraftPanel`); **idle keeps the classic setup layout** (`WritingSetupChat` + collapsible form) and switches to the chat workbench once writing starts; left panel `components/ai-writing-chat/WritingChatPanel.tsx` = **unified chronological feed** (`ChatFlowTimeline.tsx`, chat bubbles anchor-interleaved into the progress timeline so triggered events render below the user's message) + button-only intervention cards (`ChatInterventionCards.tsx`, inline textareas removed) + bottom unified smart composer. Intent resolution: frontend fast path + `POST /api/ai-writing/sessions/{id}/intent` → `deerflow/agents/ai_writing/intent_router.py` (per-pause action whitelist, high-cost confidence gates, payload cleaning); supports QA bypass, clarify follow-ups, control intents, and material-stage auto re-search + pending-intent resume. Tests `tests/test_ai_writing_intent.py`; plan doc `frontend-web/docs/ai-writing-对话驱动写作台-实现方案.md`. - **轻应用中心 (Light App Center)**: a sibling of 任务管理 in the sidebar with two pages — 应用管理 (admin registers `window_open` or `iframe` mini-apps with a route-param builder: login params resolved from `localStorage.userInfo`, theme params literal) and 应用列表 (card grid of `window_open` apps, `window.open` launch). `iframe` apps are mounted under a chosen parent menu (XK/PG/TY/综合管理) and **dynamically injected into the sidebar** by `core/page-layout/use-sidebar-menu.ts` (`useSidebarMenuItems`), opening in the `LightAppIframeView` host. Client + React Query hooks in `strategy-components/api/light-apps.ts`; URL builder/constants in `strategy-components/lib/light-app.ts`. Backend: `/api/light-apps` (global/shared, admin-gated writes). - **菜单管理 (Menu Management, admin-only)**: an **overlay** over the static sidebar menu — `MenuManagementPage` (`pages/MenuManagementPage.tsx`, route `/page/strategy/admin/menu-management`, opened from the admin-only 「菜单管理」 item in the **bottom-left settings dropdown** of `components/page-sidebar.tsx`). Admins rename / 停用·启用 / reorder (↑↓ or @dnd-kit drag) / re-parent (horizontal drag **or** the edit dialog's 「移动到」parent selector) any node across 一级/二级/三级, **including injected iframe light-app nodes** (`light-app-`). The static tree (`core/page-layout/sidebar-menu.ts`) stays the source of icons/routes; only per-node deltas (`label`/`disabled`/`parentId`/`sortOrder`) persist to the backend. Merge logic in `core/page-layout/menu-overrides.ts` (`applyMenuOverrides`, applied in `use-sidebar-menu.ts` after light-app injection, before role filter; disabling a node hides its whole subtree) — strict **3-level cap** (`wouldExceedDepth`). Client `strategy-components/api/menu-overrides.ts`. Backend: `/api/menu-overrides` (global/shared; open read, admin atomic replace-all). - **敏感词管理 (Sensitive Word Management)**: configures the **展示层脱敏映射** (原始词 → 替换词). **Gated on the username `lqq`** (not the admin role) — `getAccountDisplayName().toLowerCase() === "lqq"` (username = email `@` prefix, else `user_id`, same as the profile page); the dropdown entry, the route guard, and the page-level guard all use this check. `src/lib/desensitize.ts` ships a frozen seed map `SEED_DESENSITIZE_MAP` (the deployment seed) plus a live mutable `DESENSITIZE_MAP` (initialized from the seed so `desensitize()` works before any fetch). `DesensitizeWordsLoader` (mounted in `App.tsx` `AppProviders`) fetches `/api/sensitive-words` on startup and, if non-empty, calls `replaceDesensitizeMap(...)` to make the backend config the source of truth (empty/failed → keep seed). Page `SensitiveWordsPage.tsx` (route `/page/strategy/admin/sensitive-words`, opened from the 「敏感词管理」 item in the **bottom-left settings dropdown** of `components/page-sidebar.tsx`, present in **both** full + collapsed sidebar modes) lists/adds/edits/启停/deletes words and saves the **whole set atomically** (replace-all); a 「导入种子词」 button merges any missing `SEED_DESENSITIZE_MAP` entries into the editor. Client + hooks in `strategy-components/api/sensitive-words.ts` (`wordsToMap` folds enabled rows into the runtime map). Backend: `/api/sensitive-words` (global/shared; open read, write allowed for admin **or** the `lqq` account), mirroring 菜单管理's store shape. **侧边栏 + 导航栏 menu labels are desensitized** at the data source: `useSidebarMenuItems`/`useActiveThirdLevel` (`core/page-layout/use-sidebar-menu.ts`) map every node's `label` through a desensitizer built **directly from the `/api/sensitive-words` query** (`makeDesensitizer(wordsToMap(words))`, falling back to the global seed `desensitize` while empty) — this sidesteps the `replaceDesensitizeMap` effect-timing race. Only `label` is rewritten; `path`/`id`/`icon` are untouched so routing/highlight are unaffected. All nav surfaces (`page-sidebar.tsx`, `page-sidebar-dark.tsx`, `page-sidebar-v1.tsx`, `strategy-components/Header.tsx`, `PageRoutes.tsx`) consume this hook and are covered; `MenuManagementPage` uses the raw tree so admins still edit real labels. diff --git a/CLAUDE.md b/CLAUDE.md index 52c64c90..c0c669d4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -80,6 +80,7 @@ The frontend (`frontend-web/`) is a React 19 + Vite SPA: - **Routing**: React Router v7; top-level routes in `src/pages/PageRoutes.tsx`, workspace sub-routes in `src/pages/WorkspaceRoutes.tsx` - **Pages**: `ChatPage` (thread chat), `AgentChatPage` (custom agent chat), `AgentsPage`/`NewAgentPage` (agent management), `ScheduledTasksPage`/`ScheduledTaskRunDetailPage` (scheduled tasks), `LightAppManagementPage`/`LightAppListPage`/`LightAppIframeView` (轻应用中心 — register/list/embed mini-apps) - **定时任务「JSON → HTML 模板填充」(模板数据转换器)**: a third scheduled-task execution mode. In the create/edit dialog (`ScheduledTasksPage.tsx`), selecting the built-in agent **「模板数据转换器」** (`execution_agent_name === "template-json-builder"`, `TEMPLATE_BUILDER_AGENT_ID`) reveals a 「HTML模板」 select (`useHtmlTemplates` → `GET /api/scheduled-tasks/html-templates`) + a **.json 上传** button (reads the file's text into the prompt box) and **hides** the 必须生成 HTML/Markdown switches (this mode always outputs HTML). The chosen template persists as `execution_context.template_config.template_id` (`TemplateFillConfig` in `core/scheduled-tasks/types.ts`). At run time the backend converts the source JSON (the task prompt) into that template's `DATA` structure, validates (retry-on-fail), fills the template, and stores an HTML page previewable via the existing run-detail HTML preview. The source can be **pure JSON, plain text, or text-with-embedded-JSON** — the backend pre-extracts any embedded JSON and the agent's `SOUL.md` maps it (or the plain text's semantics) to the template's schema skeleton. **Chat-page debug entry (only this agent's `AgentChatPage`)**: when `agent_id === "template-json-builder"`, the chat header shows a 「页面模板」 select + a 「渲染预览」 button — after a normal Q&A run, the button takes the **latest AI reply**, POSTs it to `POST /api/scheduled-tasks/template-fill/render` (`renderTemplateFill`), and pops a dialog rendering the filled HTML in a `sandbox="allow-scripts"` iframe plus the structure-validation status/errors/gaps — for debugging the agent's conversion effect without creating a scheduled task. Gated strictly on the agent id, so other agents' chat pages are untouched. See the backend CLAUDE.md「Template-fill mode」for the engine (`deerflow/runtime/scheduler/template_fill.py`), agent seed, dispatch, and the render API. +- **AI 写作·对话版（对话驱动写作台）**: a **parallel new entry** beside the classic AI-writing page (classic page/routes untouched) — route `/page/canvas/ai-writing-chat` (`OpenCanvasRoutes.tsx`), sidebar 「问答管理 → 课题研究(对话版)」. Page `open-canvas/pages/AIWritingChatPage.tsx` fully **reuses the engine** (`AIWritingContext` state machine + LangGraph `useStream`, `AIWritingHistoryProvider`, right-side `AIWritingDraftPanel`) but replaces the presentation: left = `components/ai-writing-chat/WritingChatPanel.tsx` (timeline + **button-only intervention cards** `ChatInterventionCards.tsx` — the five pause cards copied from `InterventionCard.tsx` with all inline textareas removed, confirm/action buttons kept — plus a bottom **unified smart composer**). Free text goes through two-level intent resolution (`open-canvas/api/ai-writing-intent.ts`): deterministic short-phrase fast path (确认/继续/重新搜索/重写大纲…; high-cost actions never fast-pathed) then `POST /api/ai-writing/sessions/{id}/intent` — the backend reads the graph checkpoint (authoritative pause point from the pending interrupt) and routes via `deerflow/agents/ai_writing/intent_router.py` (LLM + strict per-pause action whitelist aligned to the graph's real resume actions, confidence gates: finalize/force_finalize/覆盖式 re_search need ≥0.85 else clarify, payload key-whitelist cleaning). Results map to `submitIntervention`/control (暂停/继续/后台挂起)/QA bypass (`answer` rendered as a chat bubble, never touches graph state)/clarify (amber follow-up bubble with multi-turn context). **Two-state layout**: idle (未开始写作) renders the **classic setup experience unchanged** — `WritingSetupChat` + collapsible `AIWritingPanel` form under `WritingFormProvider` (same as `AIWritingPage`'s idle branch); once writing starts (or history view opens) it switches to the chat workbench. **Unified chronological feed** (`ChatFlowTimeline.tsx`): intent-layer chat bubbles are interleaved INTO the progress-event timeline by anchor (= `progressEvents.length` at message creation), so events triggered by a user message render **below** it (Google-AI-Studio-style single stream, not timeline-above/chat-below); composer-driven interventions suppress the duplicate 「我的要求」card (`suppressedRequirementIndices`). **素材不足自动续跑** only at `material_confirm` (the only pause the graph supports re-search from): needResearch caches the payload as a pending intent, submits `re_search + userQuery`, and auto-submits the pending intent when the new material-confirm pause arrives (cancellable pill). Stage chips + per-stage placeholder + 「当前交互对象」status badge. Backend tests `tests/test_ai_writing_intent.py`. Plan doc: `frontend-web/docs/ai-writing-对话驱动写作台-实现方案.md`. - **轻应用中心 (Light App Center)**: a sibling of 任务管理 in the sidebar with two pages — 应用管理 (admin registers `window_open` or `iframe` mini-apps with a route-param builder: login params resolved from `localStorage.userInfo`, theme params literal) and 应用列表 (card grid of `window_open` apps, `window.open` launch). `iframe` apps are mounted under a chosen parent menu (XK/PG/TY/综合管理) and **dynamically injected into the sidebar** by `core/page-layout/use-sidebar-menu.ts` (`useSidebarMenuItems`), opening in the `LightAppIframeView` host. Client + React Query hooks in `strategy-components/api/light-apps.ts`; URL builder/constants in `strategy-components/lib/light-app.ts`. Backend: `/api/light-apps` (global/shared, admin-gated writes). - **菜单管理 (Menu Management, admin-only)**: an **overlay** over the static sidebar menu — `MenuManagementPage` (`pages/MenuManagementPage.tsx`, route `/page/strategy/admin/menu-management`, opened from the admin-only 「菜单管理」 item in the **bottom-left settings dropdown** of `components/page-sidebar.tsx`). Admins rename / 停用·启用 / reorder (↑↓ or @dnd-kit drag) / re-parent (horizontal drag **or** the edit dialog's 「移动到」parent selector) any node across 一级/二级/三级, **including injected iframe light-app nodes** (`light-app-`). The static tree (`core/page-layout/sidebar-menu.ts`) stays the source of icons/routes; only per-node deltas (`label`/`disabled`/`parentId`/`sortOrder`) persist to the backend. Merge logic in `core/page-layout/menu-overrides.ts` (`applyMenuOverrides`, applied in `use-sidebar-menu.ts` after light-app injection, before role filter; disabling a node hides its whole subtree) — strict **3-level cap** (`wouldExceedDepth`). Client `strategy-components/api/menu-overrides.ts`. Backend: `/api/menu-overrides` (global/shared; open read, admin atomic replace-all). - **白名单管理 (Login Whitelist, admin-only)**: gates **who may log in**, run as a **blocklist (黑名单模式)**. Two pieces: a global master switch (`system_settings.json → login_whitelist.enabled`, surfaced by **admin-only** `GET|PUT /api/system-settings/login-whitelist`) + a per-user **放行** flag (`users.approved` column, migration `20260625_02`). Users **self-register** as usual and **every new account defaults to `approved=True`** — so a user who has never logged into this system before is allowed straight through; the switch only blocks users an admin has explicitly **取消放行** (`approved=False`). (`create_user`/`User`/`UserRow` all default `approved=True`; admins are always approved; existing rows are backfilled `True`.) Login interception is the single helper `enforce_user_approved(user)` in `app/gateway/routers/auth.py`, called in all three login endpoints (`/login/{local,username,token}`) **after** the account is resolved/created and **before** the JWT is issued: switch off → everyone passes; `system_role=="admin"` → always passes (anti-lockout); else `approved=False` (admin-revoked) → 403 `{code:"PENDING_APPROVAL"}` (the frontend's `extractErrorMessage` surfaces the message and login throws before writing any auth state, so no half-login). Admin approves on `pages/LoginWhitelistPage.tsx` (route `/page/strategy/admin/login-whitelist`, entry「白名单管理」in the bottom-left settings dropdown of `components/page-sidebar.tsx`, both sidebar modes): a top master-switch + a list of all registered users (`GET /api/v1/auth/users`, now carrying `approved`) with a per-row 放行 Switch (`PUT /api/v1/auth/users/{id}/approval`, admin-only; revoking only blocks the **next** login — `token_version` is left untouched, existing sessions are not force-killed). Client/hooks: switch in `strategy-components/api/login-whitelist.ts`, user list + approval in `core/auth/{api,hooks}.ts` (`useSetUserApproval`). Backend tests: `tests/test_login_approval.py`. **账号级「登录口令」(per-account password — 临时开通)**: the same page also lets an admin assign one specific account an individual **plaintext** password (`users.login_password` column, migration `20260625_04`, nullable; auto-added on startup by `_ensure_orm_columns_sync`). Once set, **that account's** username login (`POST /api/v1/auth/login/username`) **requires** `?password=` to exactly match it and that personal password **takes precedence over** the global shared-password gate (`username_login.require_password`); accounts without one keep today's shared-gate / passwordless behavior. The user then logs in via the **existing** frontend URL `#/login/<用户名>?password=xxxx` (LoginPage already forwards `?password=`; `<用户名>` = the account's email `@`-prefix). **Plaintext is intentional** — the password rides in the URL query anyway, so storing it readably lets the admin re-copy the full login link from the page; it is exposed only on the **admin-only** `GET /api/v1/auth/users` (`UserListItem.login_password`) and the new admin-only `PUT /api/v1/auth/users/{id}/login-password` (set non-empty / clear with null·empty; doesn't touch `token_version`). The whitelist page renders a per-user 「登录口令」 column with a set/修改 editor + a live 「复制登录链接」 button (`useSetUserLoginPassword` in `core/auth/hooks.ts`, `setUserLoginPassword` in `core/auth/api.ts`). Backend gate helper `_lookup_user_by_username` (lookup-only, no auto-register) in `routers/auth.py`; tests `tests/test_login_personal_password.py`. diff --git a/frontend-web/.env.development b/frontend-web/.env.development index ac6db962..3837c075 100644 --- a/frontend-web/.env.development +++ b/frontend-web/.env.development @@ -5,7 +5,7 @@ VITE_USE_REAL_DATA=true # 任务详情（登录深链 cop-task-detail）数据源：默认真实接口；改成 true 走本地假数据（consumer 外网不可达时调试用）。 -VITE_MOCK_COP_TASK_DETAIL=flase +VITE_MOCK_COP_TASK_DETAIL=true # 研判情报报告（大屏绘制智能体深链 selectSqReport）数据源：true 走本地样例假数据（真实接口未就绪时调试用）；联调通过后置 false。 VITE_MOCK_SQ_REPORT=true diff --git a/frontend-web/docs/ai-writing-对话驱动写作台-实现方案.md b/frontend-web/docs/ai-writing-对话驱动写作台-实现方案.md new file mode 100644 index 00000000..35554757 --- /dev/null +++ b/frontend-web/docs/ai-writing-对话驱动写作台-实现方案.md @@ -0,0 +1,507 @@ +# AI 写作「对话驱动写作台」实现方案（可落地版） + +> 需求：**复制**现有 AI 写作代码，新增一个独立页面（**原页面/原路由零改动**）。在新页面里 +> **大改交互流程**——去掉「素材收集 / 大纲规划 / 作家写作 / 编辑审核」四个阶段干预卡里的**输入框**， +> 只**保留原来的确认按钮**；在页面**底部新增一个统一的多行智能输入框**，具备**强意图理解**能力： +> 重新搜索、新增检索词、添加检索素材、重新规划大纲、按要求改大纲、提修改意见、审核意见、 +> 素材不足继续搜集、对写作内容提问……**覆盖现有全部交互甚至更多**。 +> +> 交互节奏不变：**一步一确认**——进行到某个专家阶段时，交互就针对该专家（阶段作用域）； +> 用户可以**点原来的确认按钮**，也可以**在底部输入框里发「继续下一步」的意图**推进。 +> 意图**拿不准时**主动向用户**发起协助/澄清**，绝不盲目触发高代价动作（定稿 / 重搜等）。 + +本文是**实现指引**，落地时按第 9 节路线图分阶段推进。文中所有文件路径、符号名均对齐当前代码。 + +--- + +## 1. 现状梳理（改造地基） + +现有 AI 写作是一套**独立 LangGraph 子系统**（不是 lead_agent），前后端都已成型、可复用。 + +### 1.1 后端 `ai_writing` graph + +- 图工厂：`offline-backend-20260512/backend/packages/harness/deerflow/agents/ai_writing/graph.py` + （`make_ai_writing_graph`，registered as `assistant_id="ai_writing"`） +- 状态：`.../ai_writing/state.py`（`AIWritingState`） +- 四个「阶段大脑」节点： + +| 阶段 | 节点 | 文件 | +|------|------|------| +| 素材收集 | `researcher` | `nodes/researcher.py` | +| 大纲规划 | `writer_outline` | `nodes/writer_outline.py` | +| 作家写作 | `writer_draft` | `nodes/writer_draft.py` | +| 编辑审核 | `editor` | `nodes/editor.py` | + +- **五个暂停点**（`interrupt()`，`Command(resume=payload)` 续跑）——这是对话改造的核心可复用资产： + +| pause_point | 语义 | 现有 action | +|-------------|------|-------------| +| `material_confirm` | 素材确认 | `confirm` / `re_search` / `enable_skill_search` | +| `outline_confirm` | 大纲确认 | `confirm` / `re_outline` | +| `draft_confirm` | 草稿确认 | `to_editor` / `finalize` / `user_revise` | +| `review_confirm` | 编辑打回确认 | `accept_review` / `force_finalize` | +| `section_help` | 素材不足求助 | `section_help`(+`sectionDecisions`) | + +- resume 载荷（`UserInterventionPayload`，`types/ai-writing.ts`）字段：`action`、`approvedMaterialIds`、 + `userQuery`（自然语言补充检索）、`editedOutline`、`outlineFeedback`、`userRevisionNotes`、 + `overrideVerdict`、`selectedIssueIndices`、`sectionDecisions`。 + **协议已同时支持「自然语言 + 结构化 action」**——这是对话层能复用的关键。 + +> 结论：**状态机 / 流式 / 暂停·续跑协议 / 持久化都可复用**，无需重写引擎。改造本质是 +> 「把分散在干预卡里的输入框，换成一个底部智能输入框 + 意图路由层」，再把意图翻译回**现有 +> `action + payload`**；仅少量新意图（对内容提问、素材不足自动回退重搜、追加审核意见）需新增能力。 + +### 1.2 前端 `open-canvas` 子系统 + +- 主页面：`frontend-web/src/open-canvas/pages/AIWritingPage.tsx` + - 路由注册：`open-canvas/routes/OpenCanvasRoutes.tsx`（`/page/canvas/ai-writing/*`）、 + `pages/WorkspaceRoutes.tsx`（`/page/workspace/ai-writing/*`）、`pages/NotebookAIWritingPage.tsx` +- 状态机 + 流式：`contexts/AIWritingContext.tsx`（`useReducer` + LangGraph `useStream`，`assistantId:'ai_writing'`） +- 事件翻译 / reducer：`hooks/useAIWritingStream.ts` +- 类型：`types/ai-writing.ts` +- **左栏面板**：`components/ai-writing/AIWritingPanel.tsx`（时间线 + 干预卡 + 状态栏；idle 时挂启动表单） +- **要改造的输入 UI**（本次重点）： + - 干预卡 `components/ai-writing/InterventionCard.tsx`：内含 + `MaterialConfirmCard`（素材：有 `MaterialsToolbar` 输入框）、 + `OutlineConfirmCard`（大纲：有 feedback textarea）、 + `DraftConfirmCard`（草稿：有「修改意见」textarea）、 + `ReviewConfirmCard`（审核：有「补充修改指令」textarea）、 + `SectionHelpCard`（素材不足：按钮组）。 + **每张卡里都既有输入框又有确认/动作按钮**——本次要**去掉输入框、保留按钮**。 + - 启动表单 `components/ai-writing/AIWritingForm.tsx`（idle 阶段的配置表单）——本次由底部输入框接管启动。 +- **已存在的对话原型**（可借鉴）：`components/ai-writing/WritingSetupChat.tsx` + （`useThreadStream` 起 lead_agent 线程 + `setup_writing` 审批卡回填表单；仅管启动前配置，不直接复用）。 +- 底部输入框可直接复用 UI 组件：`@/components/ai-elements/prompt-input` + （`PromptInput` / `PromptInputTextarea` / `PromptInputSubmit` / `PromptInputFooter`，见 `WritingSetupChat`）。 + +--- + +## 2. 目标与范围 + +### 2.1 必须满足 + +1. **复制式新增**：新目录 / 新路由 / 新侧边栏入口，**旧页面、旧路由、旧组件零改动**（「初始的不用动」）。 +2. 页面**底部单一多行智能输入框**接管全流程交互；四个阶段干预卡里的**输入框全部移除**。 +3. **保留确认按钮**：每个阶段到达暂停点时，消息流里仍渲染**产物卡 + 原来的确认/动作按钮** + （素材「确认素材」、大纲「确认大纲」、草稿「让编辑审核 / 确认定稿」、审核「按编辑意见修改 / 强制定稿」、 + 素材不足的三选一按钮）。用户**点按钮**或**在底部输入框发自然语言意图**二选一均可推进。 +4. **强意图理解**：把用户自由文本准确路由到正确动作，**覆盖现有全部交互 + 更多**（见 3.2）。 +5. **阶段作用域**：意图解析必须知道「当前停在哪个专家阶段」，把同一句话按当前阶段翻译成对应 action。 +6. **素材不足自动回退重搜**：修改意见需要的信息现有素材没有时，先重搜补素材、补完自动继续原意图。 +7. **拿不准就协助**：低置信意图**不猜着执行**，走澄清追问（clarify）或用户协助。 +8. 保留右侧草稿实时预览（可编辑）与时间线 / 进度展示。 + +### 2.2 明确不做（本期） + +- 不改旧 `AIWritingPage` 及其 `AIWritingForm` / `InterventionCard`（这两个是要在**副本**里改的）。 +- 不替换 `ai_writing` graph 四个阶段大脑逻辑，不动五个暂停点 / checkpoint / 持久化。 +- 不引新状态管理库（继续 `useReducer` + `useStream`）。 + +### 2.3 复制策略（关键决策） + +「复制一份」= **复制会被大改的表现层组件**（页面 + 干预卡 + 面板），**复用不改的引擎层**： + +| 复制（新建副本，大改） | 复用（原样，不改；仅对 `types` 做**追加式**扩展） | +|------------------------|--------------------------------------------------| +| 新页面 `AIWritingChatPage.tsx` | `contexts/AIWritingContext.tsx`（状态机 + 流式） | +| 新面板 `WritingChatPanel.tsx`（消息流 + 底部输入框） | `hooks/useAIWritingStream.ts`（事件 → state） | +| 新消息卡 `chat-cards/*`（产物卡+确认按钮，**无输入框**） | `components/ai-writing/AIWritingDraftPanel.tsx`（右侧草稿预览） | +| 新意图客户端 `api/ai-writing-intent.ts` | 各流式展示子组件（`MaterialsCard`/`OutlineCard`/`ReviewCard`/`SkillStepsCard`…） | +| （可选）新 `contexts/WritingChatContext.tsx` 包一层「pending 意图 / 澄清态」 | `types/ai-writing.ts`（**只加字段不改旧字段**，保证旧页面不受影响） | + +> **不复用、也不改** 的三个「输入框组件」：`AIWritingForm` / `InterventionCard` / `WritingFormContext`—— +> 旧页面继续用它们，新页面完全不引用它们。这样「初始的不用动」得到硬保证。 +> +> 为什么复用 `AIWritingContext` 而不复制它？它**不含任何输入框 UI**，只是「状态机 + 与后端 graph 的 +> 流式桥」，复用它**不会改动旧页面的任何呈现**（旧页面照常在自己的 Provider 实例里跑）。复用能显著 +> 降低维护成本、避免两套引擎漂移。若要绝对物理隔离，也可整目录复制 `AIWritingContext` + +> `useAIWritingStream` 到新目录——**推荐先复用**，仅当后续需要给对话态加大量图内新协议时再分叉。 + +--- + +## 3. 核心设计 + +### 3.1 三层结构 + +``` +┌──────────────────────────────────────────────────────────────┐ +│ 对话 UI 层（新） WritingChatPanel │ +│ - 消息流：用户消息 + AI 阶段产物卡（含【保留的确认按钮】）+ 进度 │ +│ - 底部：统一多行智能输入框（唯一自由输入入口） │ +│ - 右侧：草稿实时预览（复用 AIWritingDraftPanel） │ +└───────────────┬──────────────────────────────────────────────┘ + │ 用户自然语言（+ 当前 status/pausePoint 上下文） + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ 意图解析层（新，核心） POST /api/ai-writing/sessions/{id}/intent │ +│ 输出：{ intent, pausePoint, action, payload, │ +│ needResearch, researchQuery, answer, confidence, clarify }│ +└───────────────┬──────────────────────────────────────────────┘ + │ 结构化 action + payload + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ 执行层（复用现有 AIWritingContext） │ +│ idle → startWriting(AIWritingRequest) │ +│ 暂停 → submitIntervention(UserInterventionPayload) │ +│ 问答 → 旁路回答（不改写作状态） │ +│ 素材不足 → 先重搜、缓存 pending、补完自动续跑 │ +└──────────────────────────────────────────────────────────────┘ +``` + +**设计原则**：意图解析层是「翻译官」——把自由文本翻译成**执行层已经懂的指令**。能复用 +`action + payload` 的绝不新造协议；确认按钮点击**直接走执行层**（不经意图层，零延迟、零误判）。 + +### 3.2 意图分类体系（覆盖全流程 + 更多） + +按「意图 → 触发时机（当前 status/pausePoint）→ 映射执行」组织，即意图解析引擎的目标 schema。 +**「甚至更多」** = G（问答）、H（控制）、以及 B/C/D/E 里的「素材不足自动回退重搜」。 + +#### A. 启动类（status = `idle`） +| 意图 | 用户说法示例 | 映射 | +|------|-------------|------| +| `start_writing` | 「写一篇关于新能源出口的深度分析，2000 字」 | 解析成 `AIWritingRequest` → `startWriting()` | +| `start_with_outline` | 「按这个大纲写：…」 | `AIWritingRequest.userOutline` | +| `start_imitate` | 「仿照这篇样文写…」 | `writingModeType='imitate'` + `sampleText` | + +#### B. 素材类（pausePoint = `material_confirm`） +| 意图 | 示例 | 映射 | +|------|------|------| +| `confirm_materials` | 「素材可以，继续 / 下一步」 | `{action:'confirm', approvedMaterialIds}` | +| `research_again` | 「重新搜索素材」 | `{action:'re_search'}`（无 userQuery=覆盖式重检） | +| `add_material`/`add_keyword` | 「再补点关于 X 的素材」「加个关键词 Y」 | `{action:'re_search', userQuery:'X/Y'}`（追加） | +| `select_materials` | 「只用第 1、3 条」 | `{action:'confirm', approvedMaterialIds:[…]}` | +| `drop_materials` | 「去掉第 2 条」 | 同上（反选后的子集） | + +#### C. 大纲类（pausePoint = `outline_confirm`） +| 意图 | 示例 | 映射 | +|------|------|------| +| `confirm_outline` | 「大纲 OK，开始写」 | `{action:'confirm'}` | +| `reoutline` | 「重写大纲」 | `{action:'re_outline'}`（feedback 可空） | +| `revise_outline` | 「第二章拆成两节」「调整顺序」 | `{action:'re_outline', outlineFeedback:自然语言}` | + +#### D. 写作 / 草稿类（pausePoint = `draft_confirm`） +| 意图 | 示例 | 映射 | +|------|------|------| +| `to_editor` | 「交给编辑审核」 | `{action:'to_editor'}` | +| `finalize` | 「就这样定稿」 | `{action:'finalize'}` **（高代价：低置信必澄清）** | +| `revise_draft` | 「第三段太啰嗦，精简」「补个 2024 案例」 | `{action:'user_revise', userRevisionNotes:意见}` | +| `rewrite_section` | 「重写第二章」 | `user_revise` + 章节定位写进 notes | +| `change_tone/style` | 「更口语一点 / 更正式」 | `user_revise` + notes | +| `apply_review`（若已有审核结果） | 「按编辑意见改」「只接受第 1、2 条」 | `{action:'user_revise', selectedIssueIndices:[…]}` | + +#### E. 编辑审核类（pausePoint = `review_confirm`） +| 意图 | 示例 | 映射 | +|------|------|------| +| `accept_review` | 「按编辑意见改」 | `{action:'accept_review', selectedIssueIndices}` | +| `partial_accept_review` | 「只接受第 1、2 条」 | `accept_review` + `selectedIssueIndices` 子集 | +| `add_review_opinion` | 「再补一条：核查数据准确性」 | `accept_review` + `userRevisionNotes`（并入补充指令，现协议已支持） | +| `force_finalize` | 「不改了，强制定稿」 | `{action:'force_finalize', overrideVerdict:true}` **（高代价：必澄清）** | + +#### F. 素材不足求助类（pausePoint = `section_help`） +| 意图 | 映射 | +|------|------| +| `section_supplement` | `{action:'section_help', sectionDecisions:[…'supplement']}` | +| `section_loose` | `sectionDecisions:[…'loose']` | +| `section_delete` | `sectionDecisions:[…'delete']` | + +#### G. 问答类（**新**；任意 status；旁路，不改写作状态） +| 意图 | 示例 | 映射 | +|------|------|------| +| `ask_about_content` | 「第二章讲了啥？」「为什么用这个论点？」 | 意图节点直接带回 `answer`，对话流渲染（见 5.4） | +| `ask_meta` | 「现在到哪步了？」「用了哪些素材？」 | 读当前 state 直接回答，不走图 | + +#### H. 控制类（**新 / 半新**） +| 意图 | 映射 | +|------|------| +| `next_step`（通用「继续/下一步」） | 按**当前 pausePoint** 映射到该阶段的默认确认（material/outline→`confirm`，draft→`to_editor`…；等价点确认按钮） | +| `restart_stage` | 重跑当前阶段（复用 `resumeWriting()` 空 command 续跑） | +| `run_background` | 转后台自动跑：`suspendAIWritingToBackground()` | +| `cancel` | `pauseWriting()`（`stream.stop()`） | +| `unknown/clarify` | 无法判定 → 反问澄清 / 用户协助（**防误触发硬指标**） | + +### 3.3 「素材不足自动重搜」判定与回退（用户强调点） + +触发：用户在**大纲/草稿/审核**阶段提出修改意见，但意见需要的信息现有素材里没有。 + +判定来源（组合）： +1. **意图节点直接判**：把「素材摘要（keywords + 每条 title/source）」喂给意图 prompt，让它判断 + 「这条意见能否用现有素材满足」；不能 → `needResearch=true` + `researchQuery`。 +2. **执行阶段兜底**：`writer_draft` 严格模式已有 `blocked_sections` → `section_help` 暂停点， + 对话层把它翻译成「素材不足，是否重搜？」的追问。 + +回退动作（**首期纯前端实现，不动后端协议**）：`needResearch=true` 时，前端把用户的修改 +`payload` 缓存为 `pendingIntent`，先 `submitIntervention({action:'re_search', userQuery:researchQuery})` +补素材；监听到新一轮 `material_confirm`（素材追加完成）后，**自动提交** `pendingIntent`。 +需处理「重搜期间用户又改主意」→ 允许覆盖 pending。 + +--- + +## 4. 意图解析引擎：方案与契约 + +**采用方案 A：后端 LLM 意图节点（独立 REST）**，叠加高频短句**规则快路径**优化。 + +理由：`needResearch` 判定需要**完整写作上下文**（素材/大纲/草稿），后端天然持有 checkpoint state； +与 `setup_writing` 一脉相承，离线模型选择策略统一；输出 schema 稳定、前端只消费。 + +### 4.1 后端入口 + +`app/gateway/routers/ai_writing.py` 新增： + +``` +POST /api/ai-writing/sessions/{session_id}/intent +Body: { text: string, status: string, pausePoint?: string } +Resp: IntentResult（见 4.3） +``` + +实现：读该 session 的 checkpoint state（素材摘要 / 大纲纲要 / 草稿字数·章节 / 审核意见）→ +用 `ai_writing` 配置模型（复用 `intent_parser.py` 同套 `create_chat_model` + `parse_json` + +模型容错 `_model_fallback`）解析 → 返回结构化契约。**不改图拓扑**。 + +新增 prompt：`agents/ai_writing/prompts/intent_router_prompts.py` +- 输入：用户文本、`current_status`/`pause_point`、素材摘要、大纲纲要、草稿字数+章节标题、审核意见列表。 +- 输出：严格 JSON（4.3 契约）。硬要求：**只在证据充分时给高 confidence，否则给 `clarify`**； + `finalize`/`force_finalize`/`re_search` 等高代价意图**必须**高置信才不澄清。 + +### 4.2 前端快路径（先跑规则，未命中再调后端） + +`api/ai-writing-intent.ts` 里对**当前 pausePoint** 做少量确定性短语命中，直接产出 payload，省一次往返： +- 「继续/下一步/确认/可以/ok/好的」→ 当前阶段默认 `confirm`（draft 阶段=`to_editor`）。 +- 「重新搜索/重搜」（material）→ `re_search`。「重写大纲」（outline）→ `re_outline`。 +- 「定稿/强制定稿」→ **不进快路径**（高代价，一律走后端 + 可能澄清）。 +- 命中即执行；未命中 → 调后端 `intent` 接口。 + +### 4.3 意图解析输出契约 + +```jsonc +{ + "intent": "revise_draft", // 见 3.2 分类 + "pausePoint": "draft_confirm", // 需要 resume 时；否则 null + "action": "user_revise", // 映射到现有 action + "payload": { // 直接可喂 submitIntervention 的字段（camelCase） + "userRevisionNotes": "第三段精简，并补一个 2024 年的案例" + }, + "needResearch": true, // 素材是否不足 + "researchQuery": "2024 行业案例", // needResearch 时的检索意图 + "answer": null, // 问答类意图的直接回答（旁路） + "confidence": 0.86, + "clarify": null // 低置信时的反问话术（非空则不执行、只追问） +} +``` + +前端消费顺序： +1. `answer` 非空 → 对话流渲染回答（问答旁路，不动写作状态）。 +2. `clarify` 非空 **或** `confidence < 阈值(建议 0.6)` → 渲染反问气泡，等用户澄清（**防误触发**）。 +3. `needResearch=true` → 缓存 `pendingIntent=payload`，先重搜，收到新素材后自动提交。 +4. 否则 → `idle` 走 `startWriting(...)`；暂停态走 `submitIntervention({action, ...payload})`。 + +--- + +## 5. 前端改造方案 + +### 5.1 新页面与路由（复制式） + +- 新页面：`open-canvas/pages/AIWritingChatPage.tsx` + （骨架照抄 `AIWritingPage.tsx` 的 Provider 包裹与左右分栏；左栏换成 `WritingChatPanel`，右栏仍 + `AIWritingDraftPanel`；idle 不再挂 `AIWritingForm`，改由底部输入框启动）。 +- 路由注册（**新增，不动旧行**）： + - `open-canvas/routes/OpenCanvasRoutes.tsx` 加 `path="ai-writing-chat/*"`。 + - 侧边栏 `core/page-layout/sidebar-menu.ts`：在 `qa-research` 旁新增 + `{ id:"qa-research-chat", label:"AI写作(对话版)", icon:FileText, path:"/page/canvas/ai-writing-chat" }`。 + （或先不加、内部灰度直链验证。） + +### 5.2 新面板 `WritingChatPanel.tsx`（左栏主体） + +职责 = 消息流容器 + 底部输入框，替代 `AIWritingPanel` 里的「时间线 + InterventionCard + 状态栏」。 +复用 `useAIWriting()` 读 state / 调 `startWriting` / `submitIntervention` / `pauseWriting` / +`suspendAIWritingToBackground`。 + +消息流渲染（把 `ProgressEvent` / 阶段产物适配成消息卡，复用现有展示子组件）： +- 运行中：`research_progress`/`outline_chunk`/`draft_chunk`/`review_chunk` → 进度 / 流式卡 + （复用 `SkillStepsCard`/`OutlineStreamingView`/`DraftGeneratingView`/`ReviewStreamingView` 的展示部分）。 +- 到达暂停点：渲染 **产物卡 + 保留的确认按钮**（见 5.3），不再有输入框。 +- 用户消息、AI 澄清追问、问答回答：普通气泡。 + +底部输入框：直接复用 `@/components/ai-elements/prompt-input`（`PromptInput`+`PromptInputTextarea`+ +`PromptInputSubmit`），Enter 发送、Shift+Enter 换行；发送时读当前 `state.status`/`currentPause?.pausePoint` +交给意图路由（见 5.5）。运行中（非暂停点）可禁用发送或转「排队/提示当前在生成」。 + +### 5.3 新消息卡 `chat-cards/*`（**保留按钮、去掉输入框**） + +把 `InterventionCard.tsx` 的五张卡各复制一份到 `open-canvas/components/ai-writing-chat/chat-cards/`， +**删掉其中的 textarea / MaterialsToolbar 输入部分，保留产物展示 + 确认/动作按钮**： + +| 新卡 | 展示（复用） | 保留的按钮 | 删除的输入 | +|------|-------------|-----------|-----------| +| `MaterialConfirmChatCard` | `MaterialsCard`（勾选保留）+ `SkillStepsCard` | 「确认素材，规划大纲」「重新搜索」 | `MaterialsToolbar` 的 userQuery 输入框 | +| `OutlineConfirmChatCard` | `OutlineCard`（可点标题微调保留） | 「确认大纲，开始写作」 | feedback textarea + 发送 | +| `DraftConfirmChatCard` | `ReviewCard`（若有审核，勾选保留） | 「按编辑审核意见修改」「让编辑继续审核」「确认定稿」 | 「修改意见」textarea | +| `ReviewConfirmChatCard` | `ReviewCard`（勾选保留） | 「按编辑意见修改」「强制定稿」 | 「补充修改指令」textarea | +| `SectionHelpChatCard` | 章节 + 三选一按钮组 | 三选一 + 「提交并继续」 | （本就无自由输入，原样保留） | + +> 勾选态（素材/审核意见）**保留**——它是「点按钮」路径的一部分，不算自由输入框。用户想用自然语言 +> 「只用第 1、3 条」也能走底部输入框（意图层产出 `approvedMaterialIds`/`selectedIssueIndices`）。 +> 按钮点击 **直接调 `submitIntervention`**，与旧卡完全一致，零改动风险。 + +### 5.4 问答旁路（新能力） + +「对写作内容提问」不改写作 state。首期**轻量实现**：意图节点检出 `ask_*` 时读 state 直接带回 `answer`， +前端在消息流渲染为普通 AI 气泡即可（一次调用出答案）。完整版（后续）可另起只读 lead_agent 线程注入 +草稿/大纲作背景，类似 `WritingSetupChat` 的 `useThreadStream`。 + +### 5.5 交互流程（对话版）串起来 + +1. **空闲**：底部输入「写一篇关于 X 的深度分析，2000 字」→ 意图 `start_writing` → 组 `AIWritingRequest` + → `startWriting()`。（缺关键字段时先 `clarify` 追问字数/读者/类型。） +2. **运行中**：进度/流式卡渲染。 +3. **到暂停点**：渲染产物卡 + 按钮 + 一句提示「你可以点上面的按钮，或直接说：确认继续 / 补充素材 / 改大纲…」。 + - **点按钮** → 直接 `submitIntervention`（旧逻辑）。 + - **发文字** → `resolveIntent(text, status, pausePoint)`（先快路径、后后端）→ 按 4.3 消费。 +4. **问答**：任意时刻提问 → 旁路 `answer`，不打断写作。 +5. **素材不足**：`needResearch` 或 `section_help` → 追问/执行「重搜 → 自动续跑 pending 意图」。 +6. **拿不准**：`clarify`/低置信 → 反问气泡，不执行。 + +### 5.6 pending 意图 & 澄清态（新增本地状态） + +在 `WritingChatPanel`（或新 `WritingChatContext`）维护： +- `pendingIntent: UserInterventionPayload | null` —— 素材不足重搜完成后自动提交。 +- `awaitingClarify: { originalText: string } | null` —— 澄清态，用户下一句与上一句拼接再解析。 +- pending 生命周期：设置 → 提交 `re_search` → 监听 reducer 里新一轮 `awaiting_material_confirm` + （`state.status` 从 `researching` 回到 `awaiting_material_confirm`）→ 自动 `submitIntervention(pending)` → 清空。 + +--- + +## 6. 后端改造方案 + +### 6.1 意图解析入口（新增，唯一后端改动主体） + +- `app/gateway/routers/ai_writing.py`：新增 `POST /sessions/{id}/intent`（见 4.1）。 + 读 checkpoint state 用 `app.state.checkpointer` + `make_ai_writing_graph().aget_state(...)` + （参照 `ai_writing_job_executor.py` 的读法）取素材/大纲/草稿/审核摘要。 +- `agents/ai_writing/prompts/intent_router_prompts.py`：新增意图 prompt（见 4.1）。 +- 复用 `nodes/intent_parser.py` 的模型创建 / `parse_json` / `_model_fallback` 容错。 + +### 6.2 不需要改的部分 + +- 四个阶段大脑节点、五个暂停点、checkpoint、StreamBridge、持久化、sessions/transcript REST——**全不动**。 +- 「素材不足自动续跑」「问答旁路」首期都在**前端 / 意图节点**实现，**不扩 resume 协议**。 + +### 6.3 可选增强（阶段 3，按需） + +- `add_review_opinion` 完整版：`review_confirm` resume 增字段 `extra_review_notes`（首期已用现有 + `userRevisionNotes` 降级承载，够用）。 +- `resume_intent` 后端化（把「重搜完自动续跑」搬到后端，减少前端状态机复杂度）。 +- undo / 回退到上一暂停点（依赖 checkpoint 回滚）。 + +--- + +## 7. 数据流时序（改稿 + 素材不足自动重搜） + +``` +用户（draft_confirm 暂停）: "第三段补个2024年的行业案例" + │ 底部输入框 → resolveIntent(text, status='awaiting_draft_confirm', pausePoint='draft_confirm') + ▼ POST /api/ai-writing/sessions/{id}/intent { text, status, pausePoint } +后端: 读 state(素材摘要) + LLM 解析 + │ 返回 { intent:revise_draft, action:user_revise, + │ payload:{userRevisionNotes:"第三段…补2024案例"}, + │ needResearch:true, researchQuery:"2024 行业案例", confidence:0.9 } + ▼ +前端: needResearch=true → pendingIntent = payload + │ submitIntervention({action:'re_search', userQuery:"2024 行业案例"}) + ▼ LangGraph resume → researcher 追加素材 → status 回到 awaiting_material_confirm +前端: 监听到新一轮素材确认 → 自动提交 pendingIntent + │ submitIntervention({action:'user_revise', userRevisionNotes:"第三段…补2024案例"}) + ▼ writer_draft 用新素材改稿 → draft_chunk… → draft_ready → draft_confirm +前端: 消息流展示新草稿卡 + "已按你的意见改写并补充了 2024 案例" +``` + +--- + +## 8. 关键实现细节与坑 + +1. **阶段作用域**：`resolveIntent` 必须带 `state.currentPause?.pausePoint` + `state.status`—— + 同一句「重新来」在 material 是重搜、在 outline 是重写大纲。`AIWritingContext` 已有这两个字段，直接读。 +2. **确认按钮零改动**：新卡的按钮 `onClick` 原样调 `submitIntervention(payload)`，与旧卡逐字一致， + 风险最低；**只删输入框**。 +3. **防误触发**：低置信（<0.6）或 `clarify` 非空一律追问；`finalize`/`force_finalize`/`re_search` + 即使命中也要求高置信，否则澄清。绝不盲目定稿/覆盖重搜。 +4. **pending 意图队列**：素材不足是「先插重搜、再回原意图」，用 5.6 的小状态机；重搜完成前允许覆盖 pending。 +5. **问答不污染 transcript**：问答/澄清消息在前端标记 `kind:'qa'|'clarify'`，与写作进度事件区分（ + `AIWritingContext` 的 transcript 只存 progressEvents/completedInterventions，问答气泡是纯前端消息， + 默认不入 transcript，避免历史回看错乱）。 +6. **流式产物→消息卡**：复用 `OutlineStreamingView`/`DraftGeneratingView`/`ReviewStreamingView`/ + `SkillStepsCard` 的**展示部分**，套进消息容器，不重写渲染。 +7. **右侧草稿预览**：`AIWritingDraftPanel` + `DraftSync` 原样复用（`DraftSync` 依据 status/markdown + 同步右侧画布）。 +8. **离线内网**：意图模型走 `config.yaml → ai_writing` 配置模型；检索仍走技能/内网 ES，不联网。 +9. **模型选择透传**：`submitIntervention` 的 resume 已把 `state.request?.modelName` 一并回传（见 + `AIWritingContext`），新页面沿用即可。 +10. **旧页面隔离验证**：改完后回归旧 `/page/canvas/ai-writing` 与 `/page/workspace/ai-writing`、 + 笔记本嵌入页，确认零变化（新代码不 import 旧的 `AIWritingForm`/`InterventionCard`/`WritingFormContext`）。 + +--- + +## 9. 分阶段实施路线图 + +**阶段 0 — 骨架（不含意图）** +- 复制 `AIWritingChatPage` + 注册新路由 + 侧边栏入口；复用 `AIWritingContext`/`useStream`/`DraftPanel`。 +- 复制五张 `chat-cards`（删输入框、留按钮）；底部输入框先只做 idle 直发 `start_writing` + （文本原样当 `userIntent`，其余字段取默认）+ 暂停点靠按钮推进。端到端跑通。 + +**阶段 1 — 意图解析（核心）** +- 后端 `POST /sessions/{id}/intent` + `intent_router_prompts.py`，返回 4.3 契约。 +- 前端 `api/ai-writing-intent.ts`（快路径 + 后端）接入 `WritingChatPanel`，覆盖 A~F 类意图。 +- 低置信 `clarify` 澄清态（5.6）。 + +**阶段 2 — 问答旁路 + 素材不足自动重搜** +- G 类问答（意图节点直接带 `answer`）。 +- `needResearch` + pending 意图机制（前端实现重搜后自动续跑，5.6）。 + +**阶段 3 — 增强（按需）** +- `add_review_opinion` 扩协议、`resume_intent` 后端化、undo/回退、完整问答只读线程。 + +**阶段 4 — 打磨** +- 消息卡视觉、历史回看（transcript）、后台挂起入口、灰度到侧边栏。 + +--- + +## 10. 关键文件清单（落地对照） + +### 新增（前端） +- `open-canvas/pages/AIWritingChatPage.tsx` — 新页面（复制 `AIWritingPage` 骨架改造） +- `open-canvas/components/ai-writing-chat/WritingChatPanel.tsx` — 消息流 + 底部输入框 +- `open-canvas/components/ai-writing-chat/chat-cards/{MaterialConfirmChatCard,OutlineConfirmChatCard,DraftConfirmChatCard,ReviewConfirmChatCard,SectionHelpChatCard}.tsx` — 保留按钮、去掉输入框 +- `open-canvas/components/ai-writing-chat/progressToMessage.ts` — `ProgressEvent` → 消息卡适配 +- `open-canvas/api/ai-writing-intent.ts` — 意图解析客户端（快路径 + `POST …/intent`） +- （可选）`open-canvas/contexts/WritingChatContext.tsx` — pending 意图 / 澄清态 + +### 修改（前端，仅追加，不动旧逻辑） +- `open-canvas/routes/OpenCanvasRoutes.tsx` — 加一条 `ai-writing-chat/*` 路由 +- `core/page-layout/sidebar-menu.ts` — 加一个侧边栏入口（可选） +- `open-canvas/types/ai-writing.ts` — **仅追加** `IntentResult` 等新类型，不改旧字段 + +### 新增（后端） +- `app/gateway/routers/ai_writing.py` — 加 `POST /sessions/{id}/intent` +- `agents/ai_writing/prompts/intent_router_prompts.py` — 意图 prompt +- `tests/test_ai_writing_intent.py` — 意图接口单测（TDD 强制） + +### 复用（不改） +- `open-canvas/contexts/AIWritingContext.tsx`、`hooks/useAIWritingStream.ts` +- `open-canvas/components/ai-writing/{AIWritingDraftPanel,DraftSync,MaterialsCard,OutlineCard,ReviewCard,SkillStepsCard,OutlineStreamingView,DraftGeneratingView,ReviewStreamingView}.tsx` +- `agents/ai_writing/graph.py`、四个阶段节点、五个暂停点、`nodes/intent_parser.py` + +### 绝不动（保证「初始的不用动」） +- `open-canvas/pages/AIWritingPage.tsx` 及其引用的 + `components/ai-writing/{AIWritingForm,InterventionCard}.tsx`、`contexts/WritingFormContext.tsx` +- 旧路由 `/page/canvas/ai-writing`、`/page/workspace/ai-writing`、笔记本嵌入页 + +--- + +## 11. 待确认（默认取值已给出，可直接推进） + +1. 意图引擎：**后端 LLM 节点（方案 A）+ 前端短句快路径** —— 默认采用。 +2. `AIWritingContext` / `useAIWritingStream`：**复用**（不物理复制）——默认采用；需绝对隔离可改为复制。 +3. 新页面入口：**侧边栏新增「AI写作(对话版)」** —— 默认加；若要先灰度可只留直链。 +4. 「素材不足自动重搜」：**首期前端 pending 续跑**（不动后端 resume 协议）——默认采用。 +5. 问答旁路：**首期意图节点直接带 `answer`** —— 默认采用。 + +> 以上默认按「A + 复用引擎 + 侧边栏入口 + 前端 pending + 意图节点带答案」推进，如需调整请指出。 diff --git a/frontend-web/docs/ai-writing-对话驱动改造方案.md b/frontend-web/docs/ai-writing-对话驱动改造方案.md new file mode 100644 index 00000000..6a3f6032 --- /dev/null +++ b/frontend-web/docs/ai-writing-对话驱动改造方案.md @@ -0,0 +1,454 @@ +# AI 写作「对话驱动 + 意图解析」改造方案 + +> 目标：在**不动现有 AI 写作页面**的前提下，新建一个「对话驱动」的写作工作台。 +> 去掉素材收集 / 大纲规划 / 作家写作 / 编辑审核各阶段**分散的输入框/表单**， +> 用**底部一个统一的智能输入框**接管全流程交互；该输入框具备**强意图解析**能力， +> 能准确识别用户意图（重新搜索、加素材、加关键词、重写大纲、按要求改大纲、改写作、 +> 改编辑、提编辑意见、对写作内容提问……），并在**素材不足**时自动回退去重新检索素材。 + +本文只做**方案与实现指引**，不含代码改动。落地时按第 9 节的路线图分阶段推进。 + +--- + +## 1. 现状梳理（改造的地基） + +现有 AI 写作是一套**独立的 LangGraph 子系统**（不是 lead_agent），前后端都已成型。 + +### 1.1 后端：`ai_writing` graph + +- 图工厂：`offline-backend-20260512/backend/packages/harness/deerflow/agents/ai_writing/graph.py` +- 状态：`.../agents/ai_writing/state.py`（`AIWritingState` + `UserInterventionPayload`） +- 注册：`offline-backend-20260512/backend/langgraph.json` → `assistant_id = "ai_writing"` +- 执行：与 lead agent **共用** RunManager + StreamBridge + checkpointer（`app/gateway/services.py` 里 `assistant_id=="ai_writing"` 分发到 `make_ai_writing_graph`） + +节点拓扑（实际）： + +``` +sample_analyzer → intent_parser → researcher + → [cond] pause_material | writer_draft + → writer_outline → pause_outline + → writer_draft → [cond] pause_section_help | pause_draft | END + → editor → [cond] pause_draft | pause_review + → pause_review → END | writer_draft +``` + +四个「阶段大脑」节点： + +| 阶段 | 节点 | 文件 | +|------|------|------| +| 素材收集 | `researcher` | `nodes/researcher.py` | +| 大纲规划 | `writer_outline` | `nodes/writer_outline.py` | +| 作家写作 | `writer_draft` | `nodes/writer_draft.py` | +| 编辑审核 | `editor` | `nodes/editor.py` | + +五个**暂停点**（`interrupt()`，靠 `Command(resume=payload)` 续跑）： + +| pause_point | 语义 | 可用 action（现有） | +|-------------|------|---------------------| +| `material_confirm` | 素材确认 | `confirm` / `re_search` / `supplement_search` / `enable_skill_search` | +| `outline_confirm` | 大纲确认 | `confirm` / `re_outline` | +| `draft_confirm` | 草稿确认 | `to_editor` / `finalize` / `user_revise` / `custom_revise` | +| `review_confirm` | 编辑打回确认 | `accept_review` / `force_finalize` | +| `section_help` | 素材不足求助 | `supplement` / `loose` / `delete` | + +> resume 载荷字段（`UserInterventionPayload`）：`action`、`approved_material_ids`、 +> `extra_keywords`、`user_query`(自然语言补充检索)、`edited_outline`、`outline_feedback`、 +> `user_revision_notes`、`override_verdict`、`selected_issue_indices`、`section_decisions`。 +> **关键点**：现有协议已经支持「自然语言 + 结构化 action」，这是对话改造的核心可复用资产。 + +REST（业务元数据，非图执行）：`app/gateway/routers/ai_writing.py`，前缀 `/api/ai-writing` +（sessions CRUD、transcript 保存、article-types、后台挂起 `/background` + `/progress` 等）。 + +持久化：`ai_writing_sessions` 表（`transcript` 为 `PortableLongText`） ++ `ai_writing_article_types`（`deerflow/persistence/...`）。 + +配置：`config.yaml → ai_writing`（`keyword_model`、`rank_model`、`max_materials`、 +`use_builtin_agents.{researcher,outliner,writer,editor}` 等）。 + +### 1.2 前端：`open-canvas` 子系统 + +- 主页面：`frontend-web/src/open-canvas/pages/AIWritingPage.tsx` +- 路由：`/page/canvas/ai-writing`、`/page/workspace/ai-writing` +- 状态机：`contexts/AIWritingContext.tsx`（`useReducer` + LangGraph `useStream`） +- 事件翻译/reducer：`hooks/useAIWritingStream.ts` +- 类型：`types/ai-writing.ts`（`WritingStatus`、`ProgressEvent`、`UserInterventionPayload`、`AIWritingRequest`…） +- 流式：LangGraph `useStream`，`assistantId: 'ai_writing'`，`streamMode: ['values','updates','custom','messages-tuple']` +- **要去掉的输入 UI**（改造重点）： + - 启动表单 `components/ai-writing/AIWritingForm.tsx` + `WritingFormContext` + - 阶段暂停输入 `components/ai-writing/InterventionCard.tsx`（素材/大纲/草稿/审核四套内嵌表单） +- **已存在的对话原型**：`components/ai-writing/WritingSetupChat.tsx` + （用 `useThreadStream` 起一条 lead_agent 线程 + `setup_writing` 工具审批卡回填表单）—— + 这是「对话 → 结构化配置」的现成范式，可借鉴但**不直接复用**（它只管启动前配置）。 + +### 1.3 结论 + +- **状态机、流式、暂停/续跑协议、持久化都可复用**，无需重写引擎。 +- 改造本质 = **把「分散表单」换成「一个对话输入框 + 意图路由层」**， + 再把意图映射回**现有的 `action + payload`**（大部分场景）， + 少量新意图（如「对内容提问」「素材不足自动重搜」）需要**新增协议/节点**。 + +--- + +## 2. 目标与范围 + +### 2.1 必须满足 + +1. 新页面/新路由，**旧页面零改动**（用户要求「初始的不用动」）。 +2. 底部**单一对话输入框**控制所有阶段交互，移除各阶段独立输入框。 +3. **强意图解析**：准确识别用户自然语言意图并路由到正确动作，覆盖全流程 + 更多。 +4. 用户给修改意见后，**若现有素材不足以满足要求 → 自动/建议重新检索素材**再继续。 +5. 保留右侧草稿实时预览（可编辑）与时间线/进度展示。 + +### 2.2 明确不做（本期） + +- 不改旧 `AIWritingPage` 及其表单/干预卡组件。 +- 不替换底层 `ai_writing` graph 的四个阶段大脑逻辑（只加意图层与少量新协议）。 +- 不引入新的状态管理库（继续 `useReducer` + `useStream`）。 + +--- + +## 3. 核心设计 + +### 3.1 总体思路：三层结构 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 对话 UI 层（新） │ +│ - 左：消息流（用户消息 + AI 阶段产物卡片 + 进度） │ +│ - 底：统一智能输入框（唯一交互入口） │ +│ - 右：草稿实时预览（复用 AIWritingDraftPanel） │ +└───────────────┬─────────────────────────────────────────┘ + │ 用户自然语言 + ▼ +┌─────────────────────────────────────────────────────────┐ +│ 意图解析层（新，核心） │ +│ - 输入：用户文本 + 当前 WritingStatus + 上下文快照 │ +│ - 输出：{ intent, action, payload, needResearch, ... } │ +└───────────────┬─────────────────────────────────────────┘ + │ 结构化 action + payload + ▼ +┌─────────────────────────────────────────────────────────┐ +│ 执行层（复用现有） │ +│ - 空闲态：startWriting(AIWritingRequest) │ +│ - 暂停态：submitIntervention(UserInterventionPayload) │ +│ - 运行中：stream.stop() → 续跑 / 新命令 │ +│ - 提问态：旁路问答（不改写作状态） │ +└─────────────────────────────────────────────────────────┘ +``` + +**设计原则**：意图解析层是「翻译官」——把自由文本翻译成**现有执行层已经懂的指令**。 +能复用 `action + payload` 的绝不新造协议；只有现有协议表达不了的才扩展。 + +### 3.2 意图分类体系（覆盖用户全流程 + 更多） + +按「意图类别 → 触发时机（当前 status）→ 映射到的执行」组织。这是**意图解析引擎的目标 schema**。 + +#### A. 启动类（status = idle） + +| 意图 | 说明 | 映射 | +|------|------|------| +| `start_writing` | 用户描述要写什么 | 解析成 `AIWritingRequest` → `startWriting()` | +| `start_with_outline` | 用户自带大纲 | `AIWritingRequest.userOutline` | +| `start_imitate` | 样文仿写 | `writingModeType=imitate` + 样文 | + +#### B. 素材类（status ≈ awaiting_material_confirm / 运行中） + +| 意图 | 用户说法示例 | 映射 | +|------|-------------|------| +| `confirm_materials` | 「素材可以，继续」 | `material_confirm` + `confirm`（可带勾选 ids） | +| `research_again` | 「重新搜索素材」 | `material_confirm` + `re_search` | +| `add_material` / `add_keyword` | 「补充关于 X 的素材」「加个关键词 Y」 | `material_confirm` + `supplement_search`，`user_query`=X/Y | +| `use_skill_search` | 「用 XX 技能查」 | `material_confirm` + `enable_skill_search`，`user_query`=技能/来源 | +| `select_materials` | 「只用第 1、3 条」 | `confirm` + `approved_material_ids` 子集 | +| `drop_materials` | 「去掉第 2 条」 | 同上，反选后 `approved_material_ids` | + +#### C. 大纲类（status ≈ awaiting_outline_confirm） + +| 意图 | 示例 | 映射 | +|------|------|------| +| `confirm_outline` | 「大纲 OK」 | `outline_confirm` + `confirm` | +| `reoutline` | 「重写大纲」 | `outline_confirm` + `re_outline`（`outline_feedback` 可空） | +| `revise_outline` | 「第二章拆成两节」「调整顺序」 | `re_outline` + `outline_feedback`=自然语言 | +| `edit_outline_manually` | 用户直接给出新大纲文本 | 解析成 `edited_outline` | + +#### D. 写作/草稿类（status ≈ awaiting_draft_confirm / writing_draft） + +| 意图 | 示例 | 映射 | +|------|------|------| +| `to_editor` | 「交给编辑审核」 | `draft_confirm` + `to_editor` | +| `finalize` | 「就这样定稿」 | `draft_confirm` + `finalize` | +| `revise_draft` | 「第三段太啰嗦，精简」「补个案例」 | `draft_confirm` + `user_revise`，`user_revision_notes`=意见 | +| `rewrite_section` | 「重写第二章」 | `user_revise` + 定位信息（章节）写进 notes | +| `change_tone/style` | 「更口语一点」 | `user_revise` + notes | + +#### E. 编辑审核类（status ≈ awaiting_review_confirm） + +| 意图 | 示例 | 映射 | +|------|------|------| +| `accept_review` | 「按编辑意见改」 | `review_confirm` + `accept_review`（可带 `selected_issue_indices`） | +| `partial_accept_review` | 「只接受第 1、2 条意见」 | `accept_review` + `selected_issue_indices` | +| `force_finalize` | 「不改了，强制定稿」 | `review_confirm` + `force_finalize` | +| `add_review_opinion` | 「你再补一条：检查数据准确性」 | 追加自定义审核意见（见 5.3 扩展） | + +#### F. 素材不足求助类（status = awaiting_section_help） + +| 意图 | 映射 | +|------|------| +| `section_supplement` | `section_help` + `supplement`（去重搜） | +| `section_loose` | `section_help` + `loose`（放宽续写） | +| `section_delete` | `section_help` + `delete` | + +#### G. 问答类（**新**，任意 status，旁路，不改写作状态） + +| 意图 | 示例 | 映射 | +|------|------|------| +| `ask_about_content` | 「第二章讲了啥？」「为什么用这个论点？」 | 旁路问答（见 5.4） | +| `ask_meta` | 「现在进行到哪一步？」「用了哪些素材？」 | 读当前 state 直接回答，不走图 | + +#### H. 控制类（**新/半新**） + +| 意图 | 映射 | +|------|------| +| `undo/back` | 回退到上一暂停点（依赖 checkpoint 回滚，见 8.4） | +| `restart_stage` | 重跑当前阶段 | +| `run_background` | 挂起后台自动跑 → `POST /sessions/{id}/background` | +| `cancel` | `stream.stop()` | +| `unknown/clarify` | 无法判定 → 反问澄清（对话追问，不误触发） | + +> **覆盖「甚至更多」**：G（问答）、H（控制）、以及 D/E 里「素材不足自动回退重搜」都是超出原表单能力的新增。 + +### 3.3 「素材不足自动重搜」的判定与回退（用户强调的重点） + +触发场景：用户在**大纲/草稿/审核**阶段提出修改意见，但意见需要的**信息现有素材里没有**。 + +判定放在**意图解析层**输出一个 `needResearch: boolean` + `researchQuery`，判定来源二选一（推荐组合）： + +1. **意图解析 LLM 直接判断**：把「当前素材摘要（keywords + 每条 title/来源）」喂给意图解析 + prompt，让它判断「用户这条意见能否用现有素材满足」。不能 → `needResearch=true` 并给出检索词。 +2. **执行阶段兜底**：`writer_draft` 严格模式本就有 `blocked_sections` → `pause_section_help`， + 这是**已有的**素材不足闸门；对话层把它翻译成「素材不足，是否重新检索？」的对话追问。 + +回退动作：`needResearch=true` 时，先走 `material_confirm + supplement_search`（或新的 +「带目标的重搜」协议，见 8.3）补素材，**补完自动继续**用户原本的修改意图（需要在对话层 +记住「pending 修改意图」，重搜结束后再提交）。 + +--- + +## 4. 意图解析引擎：方案对比与推荐 + +| 方案 | 做法 | 优点 | 缺点 | +|------|------|------|------| +| **A. 后端 LLM 意图节点**（推荐） | 新增 `/api/ai-writing/intent/parse`（或图内新节点），后端用 LLM 把 `{text, status, contextSnapshot}` → 结构化意图 JSON | 能吃到完整 state（素材/大纲/草稿）；可判 `needResearch`；prompt/模型集中可控；离线内网可用配置模型 | 多一次网络往返（可接受，交互本就等待） | +| B. 前端调模型接口分类 | 前端直接调现有 `/api/models` 聊天做分类 | 少一层后端改动 | 前端难拿全后端 state 快照；prompt 分散；鉴权/模型选择复杂 | +| C. 规则 + LLM 混合 | 常见短句走关键词规则快路径，兜底 LLM | 快、省 token | 规则易漏、维护成本高；中文表达多样命中率低 | + +**推荐 A（后端 LLM 意图节点）**，并在其上**叠加 C 的快路径**做优化（如「确认/继续/定稿」等 +高频短句先走轻量规则，未命中再调 LLM）。理由： + +- 意图判定需要**当前写作上下文**（尤其 `needResearch` 判定），后端天然持有 state/checkpoint。 +- 与现有「配置助手 `setup_writing`」一脉相承，模型选择/离线部署策略统一。 +- 输出 schema 稳定，前端只消费结构化结果，UI 简单。 + +### 4.1 意图解析输出契约（建议） + +```jsonc +{ + "intent": "revise_draft", // 见第 3.2 分类 + "pausePoint": "draft_confirm", // 若需 resume；否则 null + "action": "user_revise", // 映射到现有 action；新意图可为新值 + "payload": { // 直接可喂 submitIntervention 的字段 + "userRevisionNotes": "第三段精简，并补一个 2024 年的案例" + }, + "needResearch": true, // 素材是否不足 + "researchQuery": "2024 行业案例", // needResearch 时的检索意图 + "answer": null, // 问答类意图的直接回答（旁路） + "confidence": 0.86, + "clarify": null // 低置信时的反问话术 +} +``` + +前端拿到后： +- `answer` 非空 → 直接在对话流渲染回答（问答旁路，不动写作状态）。 +- `clarify` 非空或 `confidence` 低 → 渲染反问，等用户澄清（**防误触发**）。 +- `needResearch=true` → 先重搜，缓存 `payload` 为 pending，重搜完再提交。 +- 否则 → `submitIntervention({action, ...payload})` 或 `startWriting(...)`。 + +--- + +## 5. 前端改造方案 + +### 5.1 新页面与路由 + +- 新目录：`frontend-web/src/open-canvas/pages/AIWritingChatPage.tsx`（或 `conversational/` 子目录）。 +- 新路由：`/page/canvas/ai-writing-chat`（在 `OpenCanvasRoutes.tsx` 注册；旧路由保留）。 +- 侧边栏：`sidebar-menu.ts` 加一个入口（如「AI 写作（对话版）」），或先不加、内部灰度。 + +### 5.2 复用 vs 新建 + +| 复用（尽量不改） | 新建 | +|------------------|------| +| `AIWritingContext` / `useAIWritingStream`（状态机 + 流式） | 统一对话输入框组件 `WritingChatComposer` | +| `AIWritingDraftPanel`（右侧草稿预览） | 消息流容器 `WritingChatThread`（渲染阶段产物为消息卡片） | +| `types/ai-writing.ts`（按需扩展） | 意图解析客户端 `api/ai-writing-intent.ts` | +| `ProgressEvent` 事件模型 | 阶段产物 → 消息卡片的适配器 `progressToMessage.ts` | +| 会话持久化 REST | 「pending 意图」暂存逻辑（重搜后续跑） | + +**不复用**：`AIWritingForm` / `WritingFormContext` / `InterventionCard`（这三个就是要去掉的表单）。 + +### 5.3 交互流程（对话版） + +1. 空闲：用户在底部输入「写一篇关于 X 的深度分析，2000 字」→ 意图解析 `start_writing` + → 组装 `AIWritingRequest` → `startWriting()`。 +2. 运行中：`ProgressEvent`（`research_progress`/`outline_chunk`/`draft_chunk`…） + → 适配成消息流里的**进度卡片/流式卡片**（复用现有流式视图组件的展示部分）。 +3. 到达暂停点：不再弹 `InterventionCard`，而是在消息流里展示**阶段产物卡片** + （素材列表 / 大纲 / 草稿 / 审核结果）+ 一句提示「你可以说：确认继续 / 补充素材 / 改大纲…」。 + 用户下一句自然语言 → 意图解析 → `submitIntervention`。 +4. 问答：任意时刻用户提问 → 旁路回答，不打断写作状态。 +5. 素材不足：意图解析 `needResearch` 或后端 `section_help` → 对话追问「素材不足，帮你重搜？」 + → 确认后重搜 → 自动续跑 pending 意图。 + +### 5.4 问答旁路（新能力） + +「对写作内容提问」不应改写作 state。两种实现： + +- **轻量（推荐先做）**：意图解析节点直接带回 `answer`（后端能读 state，一次调用出答案）。 +- **完整**：新起一条**只读**问答线程（lead_agent，context 注入当前草稿/大纲作为背景）， + 类似 `WritingSetupChat` 的 `useThreadStream` 模式，但只读不回填。 + +--- + +## 6. 后端改造方案 + +### 6.1 意图解析入口（二选一） + +- **方案 A1（推荐，独立 REST）**：`app/gateway/routers/ai_writing.py` 新增 + `POST /api/ai-writing/sessions/{id}/intent`，入参 `{text}`，后端读该 session 的 + checkpoint state（素材/大纲/草稿摘要）+ 用 `ai_writing` 配置模型解析，返回第 4.1 的契约。 + - 好处：不改图拓扑；前端拿到结果后再决定调 `startWriting`/`submitIntervention`。 +- 方案 A2（图内节点）：在图里加 `conversation_router` 节点。改动大、状态耦合高，**不推荐**首期。 + +### 6.2 意图解析 prompt + +新增 `agents/ai_writing/prompts/intent_router_prompts.py`（或复用/扩展 `intent_parser.py`）： +- 输入：用户文本、`current_status`、素材摘要（keywords + 每条 title/source）、大纲纲要、 + 草稿字数/章节标题、审核意见列表。 +- 输出：严格 JSON（第 4.1 契约）。要求模型**只在证据充分时给高 confidence**， + 否则给 `clarify`（防误触发是硬指标）。 + +### 6.3 「带目标的重搜」协议扩展（可选增强） + +现有 `supplement_search` 用 `user_query` 追加检索。为支持「改稿意见 → 缺素材 → 重搜 → 自动续跑」， +建议在 `material_confirm` 的 resume 里新增可选字段 `resume_intent`（重搜完成后要自动执行的原始意图）。 +- 前端也可**纯前端**实现（重搜完成事件回来后再自动提交缓存的 pending payload），**首期优先前端实现**，避免动后端协议。 + +### 6.4 追加自定义审核意见（`add_review_opinion`） + +`editor`/`pause_review` 目前只接受「接受/强制定稿」。要支持「你再补一条审核意见」， +需在 `review_confirm` resume 里接受 `extra_review_notes`，`editor` 或 `writer_draft` +修订时并入。首期可先降级为 `user_revise` + notes（把用户的审核诉求当作改稿意见）， +**完整版**再扩协议。 + +### 6.5 不需要改的部分 + +- 四个阶段大脑节点（researcher/writer_outline/writer_draft/editor）逻辑不动。 +- 五个暂停点、checkpoint、StreamBridge、持久化不动。 + +--- + +## 7. 数据流时序（改稿 + 素材不足自动重搜） + +``` +用户: "第三段补个2024年的行业案例" + │ + ▼ POST /api/ai-writing/sessions/{id}/intent { text } +后端: 读 state(素材摘要) + LLM 解析 + │ 返回 { intent:revise_draft, action:user_revise, + │ payload:{userRevisionNotes:...}, + │ needResearch:true, researchQuery:"2024 行业案例" } + ▼ +前端: needResearch=true → 缓存 pending=payload + │ 对话追问/直接执行: submitIntervention(material_confirm, supplement_search, user_query="2024 行业案例") + ▼ LangGraph resume → researcher 补素材 → materials_ready +前端: 收到新素材 → 自动提交 pending + │ submitIntervention(draft_confirm, user_revise, userRevisionNotes=...) + ▼ writer_draft 用新素材改稿 → draft_chunk... → draft_ready → pause_draft +前端: 消息流展示新草稿 + "已按你的意见改写并补充了案例" +``` + +--- + +## 8. 关键实现细节与坑 + +1. **暂停态识别**：对话层必须知道「现在停在哪个 pause_point」才能正确映射 action。 + `AIWritingContext` 已有 `currentPause`/`status`，直接读。 +2. **防误触发**：低置信意图一律走 `clarify` 反问，绝不猜着执行（尤其 `finalize`/`re_search` 这种代价大的）。 +3. **pending 意图队列**：素材不足重搜是「先插一段、再回原意图」，需要一个小状态机记住 pending， + 并处理「重搜后用户又改主意」的情况（重搜完成前允许覆盖 pending）。 +4. **回退/undo（H 类）**：依赖 checkpoint 回滚，`runtime/runs/worker.py` 有 `rollback` 概念， + 首期可**不做**或只做「重跑当前阶段」。 +5. **问答旁路不污染 transcript**：问答消息可标记 `kind:'qa'`，与写作进度事件区分持久化。 +6. **流式产物→消息卡片**：复用现有 `OutlineStreamingView`/`DraftStreamingPreview` 等的**展示部分**， + 套进消息气泡即可，不必重写渲染。 +7. **离线内网**：意图解析模型走 `config.yaml → ai_writing` 里的配置模型；检索仍走技能/内网 ES， + 不联网（与现有并行席位「禁 web_search」的离线策略一致）。 + +--- + +## 9. 分阶段实施路线图 + +**阶段 0 — 骨架（不含意图）** +- 新路由 + 新页面 `AIWritingChatPage`，复用 `AIWritingContext`/`useStream`/`DraftPanel`。 +- 底部对话框先只做「空闲 `start_writing` + 暂停点固定按钮」跑通端到端（相当于把干预卡换成消息）。 + +**阶段 1 — 意图解析（核心）** +- 后端 `POST /sessions/{id}/intent` + intent prompt，返回第 4.1 契约。 +- 前端接入：自然语言 → 意图 → `startWriting`/`submitIntervention`，覆盖 A~F 类意图。 +- 加高频短句规则快路径 + 低置信 `clarify` 反问。 + +**阶段 2 — 问答旁路 + 素材不足自动重搜** +- G 类问答（先用 intent 节点直接带 `answer`）。 +- `needResearch` + pending 意图机制（前端实现重搜后自动续跑）。 + +**阶段 3 — 增强协议（按需）** +- `add_review_opinion` 扩 `review_confirm` 协议、`resume_intent` 后端化、undo/回退。 + +**阶段 4 — 打磨** +- 消息卡片视觉、历史回看（复用 transcript）、后台挂起入口、灰度到侧边栏。 + +--- + +## 10. 关键文件清单（落地时对照） + +### 新增（前端） +- `open-canvas/pages/AIWritingChatPage.tsx` — 新页面 +- `open-canvas/components/ai-writing-chat/WritingChatComposer.tsx` — 统一输入框 +- `open-canvas/components/ai-writing-chat/WritingChatThread.tsx` — 消息流 +- `open-canvas/components/ai-writing-chat/progressToMessage.ts` — 事件→消息适配 +- `open-canvas/api/ai-writing-intent.ts` — 意图解析客户端 +- 路由注册：`open-canvas/OpenCanvasRoutes.tsx`（+ 可选 `sidebar-menu.ts`） + +### 新增（后端） +- `app/gateway/routers/ai_writing.py` — 加 `POST /sessions/{id}/intent` +- `agents/ai_writing/prompts/intent_router_prompts.py` — 意图 prompt +- （阶段 3）`state.py` / `nodes/*` — 扩 `review_confirm`、`resume_intent` + +### 复用（尽量不改） +- `open-canvas/contexts/AIWritingContext.tsx`、`hooks/useAIWritingStream.ts` +- `open-canvas/components/ai-writing/AIWritingDraftPanel.tsx` 及各流式展示组件 +- `open-canvas/types/ai-writing.ts`（按需扩字段） +- `agents/ai_writing/graph.py`、四个阶段节点、五个暂停点 + +### 不动 +- 旧 `open-canvas/pages/AIWritingPage.tsx` 及 `AIWritingForm`/`WritingFormContext`/`InterventionCard` + +--- + +## 11. 待确认 + +1. 意图解析引擎是否采用**推荐的方案 A（后端 LLM 节点）**？ +2. 新页面是**独立入口**（侧边栏新增）还是先**内部灰度**（仅直链）？ +3. 「素材不足自动重搜」首期是否接受**前端实现 pending 续跑**（不动后端 resume 协议）？ +4. 问答旁路首期是否接受**意图节点直接带答案**（不新起只读线程）？ + +> 以上默认按「A / 内部灰度 / 前端 pending / 意图节点带答案」推进，如需调整请指出。 diff --git a/frontend-web/public/runtime-config.js b/frontend-web/public/runtime-config.js index eeed8fc9..85cc850a 100644 --- a/frontend-web/public/runtime-config.js +++ b/frontend-web/public/runtime-config.js @@ -109,8 +109,8 @@ window.__CM_RUNTIME_CONFIG__ = { // 登录深链任务详情是否使用本地 mock：false=真实接口；true=本地 mock。 VITE_MOCK_COP_TASK_DETAIL: "false", - // 大屏绘制 selectSqReport 是否使用本地 mock：false=真实接口；true=本地 mock。 - VITE_MOCK_SQ_REPORT: "false", + // 大屏绘制 selectSqReport 是否使用本地 mock：不在运行时强制覆盖， + // 由各环境的 .env 文件决定（开发环境为 true，生产环境为 false）。 // 静态站点模式开关；一般部署业务系统时保持 false。 VITE_STATIC_WEBSITE_ONLY: "false", diff --git a/frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx b/frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx index 5f02576b..fa0fec1c 100644 --- a/frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx +++ b/frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx @@ -11,6 +11,7 @@ import { LoaderIcon, PackageIcon, SaveIcon, + SparklesIcon, UploadCloudIcon, XIcon, } from "lucide-react"; @@ -37,6 +38,7 @@ import { } from "@/components/ui/select"; import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"; import { CodeEditor } from "@/components/workspace/code-editor"; +import { MarkdownAiEditor } from "@/open-canvas/components/artifact/MarkdownAiEditor"; import { publishArtifactToKnowledge } from "@/core/agents/api"; import { useAgent } from "@/core/agents/hooks"; import { apiFetch } from "@/core/api"; @@ -216,6 +218,10 @@ export function ArtifactFileDetail({ !useWriteFileStreaming && !isSkillFile && !isMock; + // 「AI 写作」md 展示开关：只要是可编辑的 markdown 就提供「AI 写作」视图（在 源码/预览 旁多一个 + // 切换项），用户可随时切过去体验划词「AI 改写」。默认仍是「预览」，避免编辑器在内容加载期间 + // 挂载导致白屏 + 避免复杂 md(表格/公式/HTML)误入有损编辑。 + const canUseAiEditor = canEditArtifact; const [draftContent, setDraftContent] = useState(""); const [hasLocalEdits, setHasLocalEdits] = useState(false); const updateArtifact = useUpdateArtifactContent(); @@ -234,7 +240,7 @@ export function ArtifactFileDetail({ return "FILE"; }, [filepath, isSkillFile, isSpreadsheetFile, language]); - const [viewMode, setViewMode] = useState<"code" | "preview">("code"); + const [viewMode, setViewMode] = useState<"code" | "preview" | "edit">("code"); const [allowAutoViewSwitch, setAllowAutoViewSwitch] = useState(true); const [installDialogOpen, setInstallDialogOpen] = useState(false); const [showPreviewSwitchPulse, setShowPreviewSwitchPulse] = useState(false); @@ -274,13 +280,18 @@ export function ArtifactFileDetail({ return; } - if (isSupportPreview) { - setViewMode("preview"); - return; - } + if (language === "html") { + setViewMode(thread.isLoading ? "code" : "preview"); + return; + } + + if (isSupportPreview) { + setViewMode("preview"); + return; + } setViewMode("code"); - }, [isPreviewStreaming, isSupportPreview]); + }, [isPreviewStreaming, isSupportPreview, language, thread.isLoading]); useEffect(() => { if (!allowAutoViewSwitch || !isAutoPreviewLanguage) { @@ -583,28 +594,30 @@ export function ArtifactFileDetail({ {fileTypeLabel} {!hideFileName && ( - - {useWriteFileStreaming ? ( -
{getFileName(filepath)}
- ) : hasMultipleArtifacts ? ( - - ) : ( -
{getFileName(filepath)}
- )} - + + {/* markdown：隐藏文件名（仅留 MD 徽标），把横向空间让给工具栏，避免窄面板下 + 工具栏换行错位；多文件仍保留切换下拉（靠它切文件）。文件名仍可在下载/另存为时取到。 */} + {language === "markdown" && !hasMultipleArtifacts ? null : useWriteFileStreaming ? ( +
{getFileName(filepath)}
+ ) : hasMultipleArtifacts ? ( + + ) : ( +
{getFileName(filepath)}
+ )} + )} @@ -625,10 +638,19 @@ export function ArtifactFileDetail({ onValueChange={(value) => { if (value) { setAllowAutoViewSwitch(false); - setViewMode(value as "code" | "preview"); + setViewMode(value as "code" | "preview" | "edit"); } }} > + {canUseAiEditor && ( + + + + )} )} + {viewMode === "edit" && canUseAiEditor && ( + { + setDraftContent(value); + setHasLocalEdits(true); + }} + threadId={threadId} + /> + )} {isSupportPreview && viewMode === "preview" && (language === "markdown" || diff --git a/frontend-web/src/components/workspace/chats/chat-box.tsx b/frontend-web/src/components/workspace/chats/chat-box.tsx index 36260c39..295d047a 100644 --- a/frontend-web/src/components/workspace/chats/chat-box.tsx +++ b/frontend-web/src/components/workspace/chats/chat-box.tsx @@ -423,6 +423,7 @@ const ChatBox: React.FC<{ className="size-full" filepath={selectedArtifact} threadId={threadId} + allowVirtualMarkdownEdit /> @@ -437,6 +438,7 @@ const ChatBox: React.FC<{ className="size-full" filepath={selectedArtifact} threadId={threadId} + allowVirtualMarkdownEdit /> ) : hasCitationReferences ? (
diff --git a/frontend-web/src/components/workspace/skill-display-sources.tsx b/frontend-web/src/components/workspace/skill-display-sources.tsx index 8fc2f344..3993f022 100644 --- a/frontend-web/src/components/workspace/skill-display-sources.tsx +++ b/frontend-web/src/components/workspace/skill-display-sources.tsx @@ -1,4 +1,4 @@ -import { ExternalLinkIcon } from "lucide-react"; +import { ExternalLinkIcon, FileTextIcon, LoaderCircle } from "lucide-react"; import { Button } from "@/components/ui/button"; import { @@ -9,10 +9,12 @@ import { DialogTitle, } from "@/components/ui/dialog"; import type { RuntimeDisplaySource } from "@/core/skill-display/runtime"; +import { apiFetch } from "@/core/api/fetch-client"; +import { getBackendBaseURL } from "@/core/config"; import { useLocalSettings } from "@/core/settings"; import { useCitationDisplaySettings } from "@/core/system-settings/hooks"; import { cn } from "@/lib/utils"; -import { useState } from "react"; +import { useEffect, useState } from "react"; export function SkillDisplaySources({ highlightedReferenceId, @@ -51,6 +53,9 @@ export function SourceCard({ referenceTarget?: boolean; }) { const [open, setOpen] = useState(false); + const [context, setContext] = useState(null); + const [contextLoading, setContextLoading] = useState(false); + const [contextError, setContextError] = useState(null); const [settings] = useLocalSettings(); const { data: citationDisplay } = useCitationDisplaySettings(); const cleanupWords = @@ -73,6 +78,44 @@ export function SourceCard({ ].filter(Boolean); const isCitation = source.mode === "citation"; const showReferenceNumber = isCitation; + const previewTarget = parseWeKnoraPreviewUrl(source.url); + + useEffect(() => { + if (!open || !previewTarget) { + return; + } + let cancelled = false; + setContext(null); + setContextError(null); + setContextLoading(true); + const params = new URLSearchParams({ + knowledge_base_id: previewTarget.knowledgeBaseId, + chunk_id: previewTarget.chunkId, + }); + void apiFetch(`${getBackendBaseURL()}/api/weknora/source-context?${params}`) + .then(async (response) => { + const payload = (await response.json().catch(() => null)) as unknown; + if (!response.ok || !isWeKnoraSourceContextResponse(payload)) { + throw new Error(readPreviewError(payload, response.status)); + } + if (!cancelled) { + setContext(payload.data); + } + }) + .catch((error: unknown) => { + if (!cancelled) { + setContextError(error instanceof Error ? error.message : "无法加载原文上下文"); + } + }) + .finally(() => { + if (!cancelled) { + setContextLoading(false); + } + }); + return () => { + cancelled = true; + }; + }, [open, previewTarget?.chunkId, previewTarget?.knowledgeBaseId]); return ( <> @@ -114,7 +157,14 @@ export function SourceCard({ )}
{source.url && ( - + previewTarget ? ( + + + 查看原文 + + ) : ( + + ) )} @@ -141,7 +191,7 @@ export function SourceCard({ )} - {source.url && ( + {source.url && !previewTarget && ( + {count > 0 && ( + +
+ {record.materials?.map((material) => ( + + ))} +
+ + )} + + ); + } + + if (record.pausePoint === 'outline_confirm') { + const sectionCount = record.outline?.sections.length ?? 0; + return ( +
+ + +
+ {record.outline && } +
+ +
+ ); + } + + if (record.pausePoint === 'draft_confirm') { + const wordCount = record.draftWordCount ?? 0; + const title = record.draftTitle ? `《${record.draftTitle}》` : '草稿'; + const actionLabel = + record.action === 'finalize' ? '已确认定稿' : + record.action === 'user_revise' ? '已要求修改草稿' : + '已提交编辑审核'; + return ( +
+
+ +
+
+

{actionLabel}

+ {wordCount > 0 && {wordCount} 字} +
+

{title}

+ {record.reviewResult && } +
+
+
+ ); + } + + if (record.pausePoint === 'review_confirm') { + const isForce = record.action === 'force_finalize'; + return ( +
+
+ +
+
+

{isForce ? '已强制定稿' : '已采纳审核意见'}

+ {record.reviewResult && ( + + {record.reviewResult.overallScore} / 100 + + )} +
+

+ {isForce ? '忽略编辑意见，进入定稿。' : '作家将按已选审核意见重新修改。'} +

+ {record.reviewResult && } +
+
+
+ ); + } + + return null; +} + +function timelineMaterialRelevanceLabel(score: number): string { + if (score >= 0.8) return '高相关'; + if (score >= 0.5) return '中相关'; + return '低相关'; +} + +function CompletedTimelineMaterialItem({ material }: { material: AIMaterial }) { + const [open, setOpen] = useState(false); + const pct = Math.round(material.relevanceScore * 100); + const barColor = + material.relevanceScore >= 0.8 ? 'bg-green-500' + : material.relevanceScore >= 0.5 ? 'bg-orange-400' + : 'bg-red-400'; + const hasDetail = !!material.content || !!material.recUuid; + + return ( +
+ + + +
+ {material.content && ( +

+ {material.content.slice(0, 300)} + {material.content.length > 300 && '…'} +

+ )} + {material.recUuid && ( + + )} +
+ +
+ ); +} + +function ReviewMiniSummary({ review, className }: { review: ReviewResult; className?: string }) { + const issues = review.revisionNotes.slice(0, 3); + return ( +
+
+ 审核结果 + + {reviewStatusText(review)} · {review.overallScore}/100 + +
+
+ 事实 {review.factScore} + 逻辑 {review.logicScore} + 语言 {review.languageScore} +
+ {issues.length > 0 && ( +
+ {issues.map((issue, index) => ( +
+ {issueCategoryLabel(issue.category)} + {issue.issue} +
+ ))} +
+ )} +
+ ); +} + +function ChatBubble({ + msg, + onClarificationSubmit, + onSuggestionClick, + onSuggestionsDismiss, +}: { + msg: ChatFeedMessage; + onClarificationSubmit?: (messageId: string, answer: string) => void; + onSuggestionClick?: (suggestion: string) => void; + onSuggestionsDismiss?: (messageId: string) => void; +}) { + if (msg.role === 'user') { + return ( +
+
+
+
+ 我 +
+
+ +

{msg.text}

+
+
+
+ +
+
+
+ ); + } + + if (msg.kind === 'assist' && msg.clarification) { + return ; + } + + const meta = assistantBubbleMeta(msg.kind); + const Icon = meta.icon; + + return ( +
+
+ + {meta.label} + {msg.streaming && ( + + 生成中 + + )} +
+
+
+ +
+

+ {msg.text || (msg.streaming ? '正在生成回答…' : '')} + {msg.streaming && ( + + )} +

+
+
+
+ {msg.kind === 'answer' && ( + + )} +
+ ); +} + +function assistantBubbleMeta(kind: ChatKind): { + label: string; + icon: typeof Bot; + iconClass: string; + shellClass: string; + accentClass: string; +} { + if (kind === 'ack') { + return { + label: '已执行', + icon: BadgeCheck, + iconClass: 'text-emerald-600 dark:text-emerald-300', + shellClass: 'border-emerald-200/80 bg-emerald-50/40 text-emerald-950 dark:border-emerald-900/40 dark:bg-emerald-950/15 dark:text-emerald-100', + accentClass: 'bg-emerald-500', + }; + } + if (kind === 'clarify') { + return { + label: '需要补充', + icon: CircleHelp, + iconClass: 'text-amber-600 dark:text-amber-300', + shellClass: 'border-amber-200/90 bg-amber-50/45 text-amber-950 dark:border-amber-900/40 dark:bg-amber-950/20 dark:text-amber-100', + accentClass: 'bg-amber-500', + }; + } + if (kind === 'notice') { + return { + label: '系统提示', + icon: Info, + iconClass: 'text-muted-foreground', + shellClass: 'border-border bg-muted/35 text-muted-foreground', + accentClass: 'bg-muted-foreground/40', + }; + } + if (kind === 'intent') { + return { + label: '意图解析', + icon: Sparkles, + iconClass: 'text-violet-600 dark:text-violet-300', + shellClass: 'border-violet-200/80 bg-violet-50/35 text-foreground dark:border-violet-900/40 dark:bg-violet-950/15', + accentClass: 'bg-violet-500', + }; + } + if (kind === 'answer') { + return { + label: 'AI 回答', + icon: MessageSquareText, + iconClass: 'text-blue-600 dark:text-blue-300', + shellClass: 'border-blue-200/80 bg-blue-50/35 text-foreground dark:border-blue-900/40 dark:bg-blue-950/15', + accentClass: 'bg-blue-500', + }; + } + return { + label: '写作助手', + icon: Bot, + iconClass: 'text-primary', + shellClass: 'border-border bg-card text-card-foreground', + accentClass: 'bg-primary/70', + }; +} + +function AnswerSuggestionChips({ + msg, + onSuggestionClick, + onDismiss, +}: { + msg: ChatFeedMessage; + onSuggestionClick?: (suggestion: string) => void; + onDismiss?: (messageId: string) => void; +}) { + const suggestions = (msg.suggestions ?? []).filter((item) => item.trim()); + if (msg.suggestionsHidden || (!msg.suggestionsLoading && suggestions.length === 0)) { + return null; + } + + return ( +
+
+ + 可以继续问 + +
+ {msg.suggestionsLoading ? ( +
+ {[0, 1, 2].map((i) => ( + + ))} +
+ ) : ( +
+ {suggestions.map((suggestion) => ( + + ))} +
+ )} +
+ ); +} + +function ChatClarificationCard({ + msg, + onSubmit, +}: { + msg: ChatFeedMessage; + onSubmit?: (messageId: string, answer: string) => void; +}) { + const payload = msg.clarification; + const [selection, setSelection] = useState({ selectedIds: [], custom: '' }); + + const options = useMemo( + () => + (payload?.options ?? []).filter( + (option) => typeof option.label === 'string' && option.label.trim(), + ), + [payload?.options], + ); + + if (!payload) return null; + + const allowMultiple = resolveAllowMultiple(payload.allow_multiple, payload.clarification_type); + const disabled = Boolean(msg.answered); + const canUseCustom = payload.allow_custom !== false; + + const buildAnswer = (next: ClarificationSelection = selection) => { + const selected = options + .filter((option) => next.selectedIds.includes(option.id || option.label)) + .map((option) => option.label.trim()) + .filter(Boolean); + const custom = next.custom.trim(); + return [...selected, custom].filter(Boolean).join('\n'); + }; + + const canSubmit = Boolean(buildAnswer()); + + const handleOptionClick = (optionId: string) => { + if (disabled) return; + const nextIds = allowMultiple + ? selection.selectedIds.includes(optionId) + ? selection.selectedIds.filter((id) => id !== optionId) + : [...selection.selectedIds, optionId] + : [optionId]; + setSelection((prev) => ({ ...prev, selectedIds: nextIds })); + }; + + const handleSubmit = () => { + if (disabled) return; + const answer = buildAnswer(); + if (!answer) return; + onSubmit?.(msg.id, answer); + }; + + return ( +
+
+
+ +
+

需要你补充判断

+

+ {allowMultiple ? '可多选，也可以补充文字说明' : '选择一个方向，必要时补充说明'} +

+
+ {disabled && ( + 已回答 + )} +
+
+ +
+ {payload.context ? ( +

+ {payload.context} +

+ ) : null} +

{payload.question || msg.text}

+ + {options.length > 0 ? ( +
+ {options.map((option) => { + const optionId = option.id || option.label; + const selected = selection.selectedIds.includes(optionId); + return ( + + ); + })} +
+ ) : null} + + {canUseCustom ? ( +