merge: promote beta for desktop 0.3.10

Author: wnagchi

AGENTS.md

@@ -51,6 +51,19 @@
 - Preferred threshold: keep a single source file around 600 lines.
 - Floating range: 500-700 lines is acceptable when module cohesion is still clear and the file is not becoming hard to maintain.
 - Hard threshold: when a source file exceeds 700 lines, refactoring and modularization are mandatory before continuing feature expansion.
+- Long-file splitting must improve module boundaries, not merely reduce line count.
+- Before splitting a long file, list its responsibilities and separate business rules, application orchestration, persistence/external adapters, and HTTP/API mapping.
+- Do not split an oversized file by adding loose same-level files such as generic `helper`, `utils`, `shared`, or `runtime` files without clear module ownership.
+- Extracted files must move into an explicit responsibility folder such as `domain/`, `application/`, `infrastructure/`, or `http/`, or into an existing business-stage folder with the same clarity of ownership.
+- If a directory contains more than 12 `.ts` files, create or use a lower-level module directory before adding more peer files.
+- If more than 4 files share the same feature prefix, for example `novelDirector*`, converge them into a dedicated feature directory instead of continuing the prefix-based flat layout.
+- A `utils`, `helpers`, or `shared` file that grows beyond 300 lines or is depended on by more than 3 modules must be promoted into an owned service, policy, adapter, or domain module.
+- After a split, outside modules should consume the capability through the module facade or `index.ts`; avoid deep imports into another module's internal files.
+- If a split affects workflows, prompt/runtime contracts, automatic director chains, chapter execution chains, or other major novel-production links, add or update the module README or boundary notes before continuing feature expansion.
+- For server-side architecture convergence, keep the current `server/src` structure runnable while gradually moving toward clear top-level ownership: `app/` for startup and route mounting, `platform/` for db/llm/events/runtime/config infrastructure, and `modules/` for product capabilities.
+- Server business modules should be organized around the novel completion workflow when applicable: `setup`, `planning`, `production`, `director`, `characters`, `state`, and `export`.
+- High-density server directories should be reduced incrementally. `routes` should converge into module-owned `http/` entrypoints, `services/novel` should keep only facades and stable shared entrypoints at its root, and `services/novel/director` should converge into owned submodules such as `commands`, `runtime`, `state`, `automation`, `projections`, `recovery`, and `phases`.
+- Each architecture cleanup phase should move only one coherent subsystem, preserve compatibility exports where needed, check dependency direction, and run targeted TypeScript or service-level verification before the phase is considered complete.
 
 ## Development Branch Workflow
 
@@ -139,6 +152,14 @@
 - Keep the date as the primary update identifier until the product workflow, information architecture, and release cadence are stable enough to justify a formal versioning system.
 - If multiple user-visible updates are recorded on the same date, keep them under the same date heading in `docs/releases/release-notes.md` and distinguish them by clear summary text instead of inventing temporary version numbers.
 
+## Current Product Priorities
+
+1. Stabilize auto-director recovery and chapter production chain.
+2. Keep beginner-first full-novel completion as the main product goal.
+3. Avoid introducing new workflow branches unless they simplify the main production path.
+4. Prefer fixing runtime contracts, prompt schemas, and state projections before adding UI-only patches.
+5. Do not expand Creative Hub into a general chat tool unless it directly supports novel completion.
+
 ### Future Versioning Transition
 
 - When the user later decides the product is stable enough for formal versions, versioning can transition from `date-only` to `version number + date`.

README.md

@@ -124,35 +124,23 @@
 
 完整历史更新见 [docs/releases/release-notes.md](./docs/releases/release-notes.md)。
 
-### 2026-05-13
+### 2026-05-14
 
-章节正文生成回退为整章一次性写作：系统不再把章节合同、场景卡或分场景多轮写作接入正文生成主链，避免同一章被反复生成、成本飙升或每个场景都写成一整章。
+自动导演的步骤定位和恢复提示更一致：系统会按同一份步骤目录判断当前阶段、等待确认点、可自动审批项和写入范围，减少不同入口显示不一致的问题。
 
-- 正文 writer 不再接收 `chapter_boundary`、`scene_plan` 或 `scene_contract`，章节合同信息仅保留为规划、审校、诊断和局部修复的辅助资产。
-- 篇幅控制只在生成提示中给出目标长度和可接受区间，不再因为生成后的长度超出上限而强制失败或截断正文。
-- `TASK.md` 已记录禁令：在确认新的完整方案前，不再把章节合同重新接回正文生成热路径。
+- 自动导演面板、任务详情和自动审批会使用同一套步骤与暂停点判断，方便用户理解当前卡在哪一步、下一步能否继续。
+- 旧任务里的历史阶段、节点和暂停点仍可识别，不需要迁移数据库或重建已有任务。
 
-章节生成遇到模型空返回时更稳：系统会先自动重试当前章一次；如果仍然没有正文，会停在当前章并记录清楚原因，不再把空章节当成已生成内容继续推进。
+自动导演执行详情的任务定位更清晰：从旧链接、任务中心、小说列表或跟进中心进入时，系统都会识别同一条 AI 导演执行记录，避免展示的是失败任务、操作却找不到可重试任务。
 
-- 手动单章生成和自动执行批量生成都会共用同一套空正文防线，避免空白内容写入章节正文。
-- 自动执行暂停时会保留章节、任务、模型和重试信息，方便定位是哪一章没有拿到正文，也方便从当前章继续恢复。
+- 执行详情里的继续自动执行、按任务模型重试、使用所选模型重试和跟进动作会操作当前展示的 AI 导演任务。
+- 旧的执行详情链接仍可打开，系统会自动对齐到新的导演任务参数，不影响历史通知和任务入口。
 
-自动导演候选方案可以稳定重新生成：已有两套方案后，再点击重新生成两套时，系统会真正进入新一轮候选生成，不会把上一轮候选误判成本轮已完成。
+自动导演重试和恢复更稳：当章节自动执行失败、重试、服务重启恢复交错出现时，页面会优先展示当前真实任务状态，不会把已重新排队或恢复中的任务继续显示成旧失败。
 
-- 修复候选阶段运行态复用过早生效的问题，避免后台命令在读取新 batch 前报错中断。
-- 保留已生成候选用于恢复和对比，但手动触发的重新生成、定向修正和标题重做会强制执行本次命令。
-
-角色资产工作台更容易一眼看清谁是主角：主角会在角色列表顶部独立展示，右侧编辑区也会持续标明当前正在编辑主角还是其他关系角色。
-
-- 配角列表会避开重复展示主角，并优先显示与主角关系或角色定位，方便围绕主角理解整组人物。
-- 当前角色详情顶部新增编辑摘要，突出主角目标、故事作用、关系信息和最近出场章节，减少新手在资料区来回确认的负担。
-- 桌面客户端推进到 `0.3.9`，用于发布本次正文生成回退、空章节防线、候选重新生成修复和主角识别体验优化后的 Windows 客户端包。
-
-查询小说进展时，系统会优先按真实产物判断整本书推进到哪里：规划、书级约定、角色、卷章规划、章节任务单、正文、审校、修复和状态提交都会进入同一份进展判断。
-
-- 后台任务成功、失败、排队或运行只作为补充状态展示，不会覆盖已经产出的小说事实。
-- 整本生成中断后，系统仍会说明正文写到第几章、哪些章节审校完成、哪些章节待修复，方便从可用产物继续推进。
-- 对话里询问“小说进展”或“整本生成到哪了”会走同一个事实进展入口，回答先说明真实产物进度，再补充后台任务情况。
+- 使用当前模型或原任务模型重试后，执行详情、顶部接管条和自动导演总览会对齐到同一条 AI 导演执行记录。
+- 如果章节流水线因服务重启暂停，继续或重试会恢复待处理批次，再从当前章节继续推进。
+- 桌面客户端推进到 `0.3.10`，用于发布本次自动导演任务定位、重试恢复和进展显示修复后的 Windows 客户端包。
 
 ## 功能预览
 ### 功能概览中的95%以上编写都是AI完成

client/src/api/autoDirectorFollowUps.ts

@@ -23,10 +23,10 @@ export async function listAutoDirectorFollowUps(params?: AutoDirectorFollowUpLis
   return data;
 }
 
-export async function getAutoDirectorFollowUpDetail(taskId: string) {
+export async function getAutoDirectorFollowUpDetail(directorTaskId: string) {
   try {
     const { data } = await apiClient.get<ApiResponse<AutoDirectorFollowUpDetail | null>>(
-      `/auto-director/follow-ups/${taskId}`,
+      `/auto-director/follow-ups/${directorTaskId}`,
       {
         silentErrorStatuses: [404],
       },
@@ -45,10 +45,10 @@ export async function getAutoDirectorFollowUpDetail(taskId: string) {
   }
 }
 
-export async function revalidateAutoDirectorFollowUpDetail(taskId: string) {
+export async function revalidateAutoDirectorFollowUpDetail(directorTaskId: string) {
   try {
     const { data } = await apiClient.get<ApiResponse<AutoDirectorFollowUpDetail | null>>(
-      `/auto-director/follow-ups/${taskId}/revalidation`,
+      `/auto-director/follow-ups/${directorTaskId}/revalidation`,
       {
         silentErrorStatuses: [404],
       },
@@ -68,14 +68,14 @@ export async function revalidateAutoDirectorFollowUpDetail(taskId: string) {
 }
 
 export async function executeAutoDirectorFollowUpAction(
-  taskId: string,
+  directorTaskId: string,
   input: {
     actionCode: AutoDirectorMutationActionCode;
     idempotencyKey: string;
   },
 ) {
   const { data } = await apiClient.post<ApiResponse<AutoDirectorActionExecutionResult>>(
-    `/auto-director/follow-ups/${taskId}/actions`,
+    `/auto-director/follow-ups/${directorTaskId}/actions`,
     input,
   );
   return data;

client/src/api/novel/production.ts

@@ -1,6 +1,7 @@
 import type { ApiResponse } from "@ai-novel/shared/types/api";
 import type { LLMProvider } from "@ai-novel/shared/types/llm";
 import type {
+  ArtifactSyncMode,
   CreativeDecision,
   Novel,
   NovelSnapshot,
@@ -22,6 +23,7 @@ export async function runNovelPipeline(
     skipCompleted?: boolean;
     qualityThreshold?: number;
     repairMode?: PipelineRepairMode;
+    artifactSyncMode?: ArtifactSyncMode;
     provider?: LLMProvider;
     model?: string;
     temperature?: number;

client/src/api/novelDirector.ts

@@ -23,14 +23,14 @@ import type {
 } from "@ai-novel/shared/types/novelDirector";
 import { apiClient } from "./client";
 
-export async function getDirectorTaskSnapshot(taskId: string) {
-  const { data } = await apiClient.get<ApiResponse<DirectorTaskSnapshotResponse>>(`/novels/director/tasks/${taskId}`);
+export async function getDirectorTaskSnapshot(directorTaskId: string) {
+  const { data } = await apiClient.get<ApiResponse<DirectorTaskSnapshotResponse>>(`/novels/director/tasks/${directorTaskId}`);
   return data;
 }
 
-export async function getDirectorTaskFactInspection(taskId: string) {
+export async function getDirectorTaskFactInspection(directorTaskId: string) {
   const { data } = await apiClient.get<ApiResponse<DirectorTaskFactInspectionResponse>>(
-    `/novels/director/tasks/${taskId}/fact-inspection`,
+    `/novels/director/tasks/${directorTaskId}/fact-inspection`,
   );
   return data;
 }
@@ -144,8 +144,8 @@ export async function getDirectorWorkspaceAnalysis(
   return data;
 }
 
-export async function getDirectorRuntimeSnapshot(taskId: string) {
-  const snapshot = await getDirectorTaskSnapshot(taskId);
+export async function getDirectorRuntimeSnapshot(directorTaskId: string) {
+  const snapshot = await getDirectorTaskSnapshot(directorTaskId);
   return {
     ...snapshot,
     data: {
@@ -155,8 +155,8 @@ export async function getDirectorRuntimeSnapshot(taskId: string) {
   };
 }
 
-export async function getDirectorRuntimeProjection(taskId: string) {
-  const snapshot = await getDirectorTaskSnapshot(taskId);
+export async function getDirectorRuntimeProjection(directorTaskId: string) {
+  const snapshot = await getDirectorTaskSnapshot(directorTaskId);
   return {
     ...snapshot,
     data: {
@@ -165,8 +165,8 @@ export async function getDirectorRuntimeProjection(taskId: string) {
   };
 }
 
-export async function getDirectorRuntimeEventHistory(taskId: string, options?: { limit?: number }) {
-  const snapshot = await getDirectorTaskSnapshot(taskId);
+export async function getDirectorRuntimeEventHistory(directorTaskId: string, options?: { limit?: number }) {
+  const snapshot = await getDirectorTaskSnapshot(directorTaskId);
   const events = snapshot.data?.snapshot?.recentEvents ?? [];
   const limit = options?.limit ?? events.length;
   return {
@@ -201,11 +201,11 @@ export async function getDirectorManualEditImpact(
 }
 
 export async function updateDirectorRuntimePolicy(
-  taskId: string,
+  directorTaskId: string,
   payload: DirectorRuntimePolicyUpdateRequest,
 ): Promise<ApiResponse<DirectorCommandAcceptedResponse>> {
   const { data } = await apiClient.post<ApiResponse<DirectorCommandAcceptedResponse>>(
-    `/novels/director/tasks/${taskId}/commands`,
+    `/novels/director/tasks/${directorTaskId}/commands`,
     {
       commandType: "policy_update",
       payload,
@@ -214,23 +214,23 @@ export async function updateDirectorRuntimePolicy(
   return data;
 }
 
-export async function approveDirectorGate(taskId: string): Promise<ApiResponse<DirectorCommandAcceptedResponse>> {
+export async function approveDirectorGate(directorTaskId: string): Promise<ApiResponse<DirectorCommandAcceptedResponse>> {
   const { data } = await apiClient.post<ApiResponse<DirectorCommandAcceptedResponse>>(
-    `/novels/director/tasks/${taskId}/commands`,
+    `/novels/director/tasks/${directorTaskId}/commands`,
     { commandType: "approve_gate", payload: {} },
   );
   return data;
 }
 
 export async function continueDirectorRuntime(
-  taskId: string,
+  directorTaskId: string,
   payload?: Partial<DirectorRuntimePolicyUpdateRequest> & {
     continuationMode?: "resume" | "auto_execute_range";
     batchAlreadyStartedCount?: number;
   },
 ) {
   const { data } = await apiClient.post<ApiResponse<DirectorCommandAcceptedResponse>>(
-    `/novels/director/tasks/${taskId}/commands`,
+    `/novels/director/tasks/${directorTaskId}/commands`,
     {
       commandType: "continue",
       payload: payload ?? {},

client/src/api/novelWorkflow.ts

@@ -19,18 +19,18 @@ export async function bootstrapNovelWorkflow(payload: {
   return data;
 }
 
-export async function continueNovelWorkflow(taskId: string, payload?: {
+export async function continueNovelWorkflow(directorTaskId: string, payload?: {
   continuationMode?: DirectorContinuationMode;
 }) {
-  const { data } = await apiClient.post<ApiResponse<DirectorCommandAcceptedResponse>>(`/novel-workflows/${taskId}/continue`, payload ?? {});
+  const { data } = await apiClient.post<ApiResponse<DirectorCommandAcceptedResponse>>(`/novel-workflows/${directorTaskId}/continue`, payload ?? {});
   return data;
 }
 
-export async function repairNovelWorkflowChapterTitles(taskId: string, payload?: {
+export async function repairNovelWorkflowChapterTitles(directorTaskId: string, payload?: {
   volumeId?: string;
 }) {
   const { data } = await apiClient.post<ApiResponse<DirectorCommandAcceptedResponse>>(
-    `/novel-workflows/${taskId}/repair-chapter-titles`,
+    `/novel-workflows/${directorTaskId}/repair-chapter-titles`,
     payload ?? {},
   );
   return data;

client/src/api/queryKeys.ts

@@ -93,14 +93,14 @@ export const queryKeys = {
     list: (params: string) => ["tasks", "list", params] as const,
     detail: (kind: string, id: string) => ["tasks", "detail", kind, id] as const,
     recoveryCandidates: ["tasks", "recovery-candidates"] as const,
-    autoDirectorFollowUpDetail: (taskId: string) => ["tasks", "auto-director-follow-up", taskId] as const,
-    directorTaskSnapshot: (taskId: string) => ["tasks", "director-task-snapshot", taskId] as const,
-    directorRuntime: (taskId: string) => ["tasks", "director-runtime", taskId] as const,
+    autoDirectorFollowUpDetail: (directorTaskId: string) => ["tasks", "auto-director-follow-up", directorTaskId] as const,
+    directorTaskSnapshot: (directorTaskId: string) => ["tasks", "director-task-snapshot", directorTaskId] as const,
+    directorRuntime: (directorTaskId: string) => ["tasks", "director-runtime", directorTaskId] as const,
   },
   autoDirectorFollowUps: {
     overview: ["auto-director-follow-ups", "overview"] as const,
     list: (params: string) => ["auto-director-follow-ups", "list", params] as const,
-    detail: (taskId: string) => ["auto-director-follow-ups", "detail", taskId] as const,
+    detail: (directorTaskId: string) => ["auto-director-follow-ups", "detail", directorTaskId] as const,
   },
   agentRuns: {
     list: (params: string) => ["agent-runs", "list", params] as const,

client/src/components/layout/NovelWorkspaceRail.tsx

@@ -310,7 +310,8 @@ export default function NovelWorkspaceRail(props: NovelWorkspaceRailProps) {
     const taskId = activeTask?.id ?? bookAutomationProjection?.latestTask?.id;
     if (taskId) {
       const next = new URLSearchParams(searchParams);
-      next.set("taskId", taskId);
+      next.set("directorTaskId", taskId);
+      next.delete("taskId");
       next.set("taskPanel", "1");
       navigate(`/novels/${novelId}/edit?${next.toString()}`);
       return;

client/src/lib/directorCockpitActions.ts

@@ -30,7 +30,7 @@ export function getDirectorCockpitActionHref(
     const params = new URLSearchParams();
     params.set("stage", action.target.tab);
     if (action.target.taskId) {
-      params.set("taskId", action.target.taskId);
+      params.set("directorTaskId", action.target.taskId);
     }
     if (action.type === "open_details") {
       params.set("taskPanel", "1");
@@ -39,7 +39,7 @@ export function getDirectorCockpitActionHref(
   }
   if (action.type === "open_details" && action.target.taskId) {
     const params = new URLSearchParams();
-    params.set("taskId", action.target.taskId);
+    params.set("directorTaskId", action.target.taskId);
     params.set("taskPanel", "1");
     return `/novels/${projection.novelId}/edit?${params.toString()}`;
   }

client/src/lib/directorTaskNotice.ts

@@ -57,7 +57,7 @@ export function buildStructuredOutlineRoute(
   }
   const search = new URLSearchParams();
   search.set("stage", "structured");
-  search.set("taskId", task.id);
+  search.set("directorTaskId", task.id);
   if (typeof volumeId === "string" && volumeId.trim()) {
     search.set("volumeId", volumeId.trim());
   }