diff --git a/docs/development/i18n.md b/docs/development/i18n.md index e70dc2355..fc0837253 100644 --- a/docs/development/i18n.md +++ b/docs/development/i18n.md @@ -92,6 +92,7 @@ npm run check:i18n | --- | --- | --- | | 通用、错误 | [common.ts](../../src/i18n/messages/zh-CN/common.ts) | [common.ts](../../src/i18n/messages/en-US/common.ts) | | 设置、主题 | [settings.ts](../../src/i18n/messages/zh-CN/settings.ts) | [settings.ts](../../src/i18n/messages/en-US/settings.ts) | +| 首次设置 | [firstRun.ts](../../src/i18n/messages/zh-CN/firstRun.ts) | [firstRun.ts](../../src/i18n/messages/en-US/firstRun.ts) | | 画布与项目 | [canvas.ts](../../src/i18n/messages/zh-CN/canvas.ts) | [canvas.ts](../../src/i18n/messages/en-US/canvas.ts) | | 模型与服务 | [models.ts](../../src/i18n/messages/zh-CN/models.ts) | [models.ts](../../src/i18n/messages/en-US/models.ts) | | 画布外壳 | [canvasShell.ts](../../src/i18n/messages/zh-CN/canvasShell.ts) | [canvasShell.ts](../../src/i18n/messages/en-US/canvasShell.ts) | diff --git a/docs/development/ui-performance.md b/docs/development/ui-performance.md index b28186432..e852fbb75 100644 --- a/docs/development/ui-performance.md +++ b/docs/development/ui-performance.md @@ -6,6 +6,7 @@ Design for the time between a user action and the point when they can continue w - **Keep direct manipulation responsive.** Update typing, selection, dragging, panning, and scrubbing on the next available frame. Keep synchronous I/O and expensive work out of input handlers. Coalesce transient updates and persist edits at meaningful boundaries. - **Keep navigation focused.** Load the data needed for the destination to become usable. Defer previews, secondary panels, and capability discovery until needed. Reuse valid results, combine duplicate requests, and cancel view-specific work when the view changes. +- **Avoid redundant clicks.** If a user action already identifies what to open or use, go directly there. Do not show an intermediate page whose only forward action repeats the same intent, or require a second click to select the single item the user just saved for that action. Keep steps that collect input, offer a meaningful choice, or confirm a consequential action. - **Protect foreground actions.** Limit background concurrency so discovery, polling, and media loading leave capacity for navigation and edits. Preserve focus, selection, and drafts across background updates. - **Show meaningful progress.** Acknowledge actions promptly. For work that takes around a second or longer, show the current stage and keep unrelated controls usable. Offer cancellation when the operation supports it. - **Preserve correctness.** Measure readiness after required state is loaded and controls are actionable. Keep save, conflict, and task status tied to authoritative receipts. diff --git a/docs/guides/user-guide.md b/docs/guides/user-guide.md index ac928883a..cedd46390 100644 --- a/docs/guides/user-guide.md +++ b/docs/guides/user-guide.md @@ -4,6 +4,8 @@ ## Connect models +On the welcome screen, select **Get started**. Set up a language model for the built-in assistant or choose an existing harness. Then check one or more tasks. Each checked task shows its saved models or opens its setup form if you have none. **Start creating** places a node for each checked task on the same canvas. **Import media** opens the file picker. **Open an example canvas** opens an editable example project directly, with download progress in step two. Cancelling keeps your task selections. You can add more models in Settings anytime. + For external agent harnesses (Codex, OpenCode, Claude Code, DeepSeek Harness and JiuwenSwarm), OpenDirector checks the backend's `PATH` first, then common CLI installation directories. These include user bins, npm/nvm, Bun, Volta, Windows Scoop and Python Scripts, and macOS Homebrew and user Python bins. It also checks Codex desktop installs, OpenCode's `.opencode/bin`, Claude's `.claude/local`, and configured npm, pipx and uv bin directories. It checks known directories without scanning the whole disk. Finding a CLI does not establish authentication or configuration readiness. For other locations, add the CLI directory to the backend's `PATH` and restart the backend. The Default agent continues to use the bundled OpenCode. Click the gear at the bottom left to open **Settings**, then open **Model connections**. Add models for chat, image, video, or audio generation as needed. diff --git a/docs/guides/user-guide.zh-CN.md b/docs/guides/user-guide.zh-CN.md index 8b4a0f1ef..f823f1bee 100644 --- a/docs/guides/user-guide.zh-CN.md +++ b/docs/guides/user-guide.zh-CN.md @@ -4,6 +4,8 @@ ## 接入模型 +首次打开时,在欢迎页选择「开始设置」。为内置助手配置一个语言模型,或选择已有的 Harness。接着勾选一项或多项任务。每个勾选项可以选用已有模型,缺模型时直接显示对应的配置表单。点击「开始创作」后,画布会为每项任务添加一个节点。点「导入素材」可直接选文件,点「打开示例画布」可直接进入可编辑的示例项目,下载进度在第二步显示。取消时会保留已勾选的任务。之后可随时在设置中添加其他模型。 + 选择外部 Agent harness(Codex、OpenCode、Claude Code、DeepSeek Harness 和 JiuwenSwarm)时,OpenDirector 优先检查后端的 `PATH`,再查找常见 CLI 安装目录,包括用户命令目录、npm/nvm、Bun、Volta、Windows Scoop 与 Python Scripts,以及 macOS Homebrew 和用户 Python 命令目录。同时检查 Codex 桌面版、OpenCode 的 `.opencode/bin`、Claude 的 `.claude/local`,以及配置的 npm、pipx 和 uv 命令目录。检测仅访问已知目录,不扫描整个磁盘;找到 CLI 后仍需检查认证与配置是否就绪。其他安装位置可加入后端的 `PATH`,然后重启后端。Default Agent 仍使用应用内置的 OpenCode。 点击左下角齿轮进入“设置”,打开“模型接入”,按用途添加对话、图片、视频或音频模型。 diff --git a/scripts/check-browser-manifest.mjs b/scripts/check-browser-manifest.mjs index 951bebed9..aad6866b6 100644 --- a/scripts/check-browser-manifest.mjs +++ b/scripts/check-browser-manifest.mjs @@ -52,8 +52,8 @@ for (const entry of entries) { const FIXTURE_LANES = ["extendedFixture", "extendedHttpFixture"]; const KNOWN_LANES = new Set(["gate", "extended", ...FIXTURE_LANES, "production", "perf", "manual"]); // Static harness pages do not open the workspace, so they do not see the welcome dialog. -// The bilingual defaults test exercises the welcome dialog itself. -const welcomeExempt = new Set(["assistant_activity.mjs", "bilingual_defaults.mjs"]); +// These scenarios exercise the welcome dialog itself. +const welcomeExempt = new Set(["assistant_activity.mjs", "bilingual_defaults.mjs", "first_run.mjs"]); for (const entry of entries) { const text = entry.file === undefined ? "" : fs.readFileSync(path.join(browserDir, entry.file), "utf8"); const importsSrc = text.includes('"/src/'); diff --git a/scripts/run-browser-suite.mjs b/scripts/run-browser-suite.mjs index 04fe0a89b..48291194c 100644 --- a/scripts/run-browser-suite.mjs +++ b/scripts/run-browser-suite.mjs @@ -73,6 +73,7 @@ const workflows = [ args: ["--full-creation"], env: { PYTHON: "python" }, }, + { name: "first-run setup", script: "tests/browser/first_run.mjs" }, ]; const failures = []; diff --git a/src/assets/welcome/README.md b/src/assets/welcome/README.md new file mode 100644 index 000000000..eb23a6ec4 --- /dev/null +++ b/src/assets/welcome/README.md @@ -0,0 +1,3 @@ +# Welcome artwork + +These are two screenshots of the actual OpenDirector canvas. For each locale, six clips from [*We Can Still Win*](../../../docs/guides/assets/dota2-short-film.mp4) were imported into an isolated sample project and added to its timeline. The screenshots are encoded as WebP without compositing and bundled to work offline. diff --git a/src/assets/welcome/canvas-en-US.webp b/src/assets/welcome/canvas-en-US.webp new file mode 100644 index 000000000..56ad696d1 Binary files /dev/null and b/src/assets/welcome/canvas-en-US.webp differ diff --git a/src/assets/welcome/canvas-zh-CN.webp b/src/assets/welcome/canvas-zh-CN.webp new file mode 100644 index 000000000..5ac2bd6c7 Binary files /dev/null and b/src/assets/welcome/canvas-zh-CN.webp differ diff --git a/src/backend/creationProjection.ts b/src/backend/creationProjection.ts index 24c4bdd7b..dc7e4de75 100644 --- a/src/backend/creationProjection.ts +++ b/src/backend/creationProjection.ts @@ -95,6 +95,7 @@ export class CreationProjection { private importHandles = new Map(); private timelineImportSources = new Map(); private masks = new Map>(); + private pendingSpecIds = new Map(); readonly client: CreationClient; constructor(client: CreationClient) { this.client = client; @@ -936,8 +937,11 @@ export class CreationProjection { node: CanvasNode, current?: GenerationSpec, ): GenerationSpecInput { + const id = current?.id ?? this.pendingSpecIds.get(node.id) ?? crypto.randomUUID(); + // Preserve the batch payload when an unacknowledged draft save is retried. + if (!current) this.pendingSpecIds.set(node.id, id); const common = { - id: current?.id ?? crypto.randomUUID(), + id, projectId: this.client.id, revision: current?.revision ?? 1, purpose: current?.purpose ?? "draft", @@ -2109,6 +2113,7 @@ export class CreationProjection { // Business acknowledgement cannot be undone by a view preference failure. this.basis = this.client.snapshot; this.baseline = document; + this.pendingSpecIds.clear(); if (options.saveView === false) return operations.length > 0; await this.saveView(document); return operations.length > 0; diff --git a/src/backend/models.ts b/src/backend/models.ts index d8a2b1e81..498a66fab 100644 --- a/src/backend/models.ts +++ b/src/backend/models.ts @@ -109,6 +109,7 @@ export function useBackendModels() { const [models, setModels] = useState([]); const modelsRef = useRef([]); const epoch = useRef(0); + const latestRefresh = useRef(0); const querySequence = useRef(0); const latestQuery = useRef(new Map()); const alive = useRef(true); @@ -136,6 +137,8 @@ export function useBackendModels() { }, []); const refresh = useCallback(async () => { const initialEpoch = ++epoch.current; + latestRefresh.current = initialEpoch; + setLoading(true); try { const [list, general] = await Promise.all([ request("/model-configs").then((list) => { @@ -156,7 +159,7 @@ export function useBackendModels() { setConnected(false); setError(errorMessage(failure)); } finally { - if (alive.current) setLoading(false); + if (alive.current && initialEpoch === latestRefresh.current) setLoading(false); } }, [storeModels]); const refreshAvailability = useCallback( @@ -302,6 +305,7 @@ export function useBackendModels() { ); await refresh(); void refreshAvailability(saved.map((model) => model.id)); + return saved; }; const removeService = async (id: string) => { epoch.current += 1; diff --git a/src/canvas/ModelPicker.tsx b/src/canvas/ModelPicker.tsx index dc80c9ff5..364285f5b 100644 --- a/src/canvas/ModelPicker.tsx +++ b/src/canvas/ModelPicker.tsx @@ -1,5 +1,5 @@ import { ModelLogo } from "./ModelLogo"; -import { useState, type ReactNode } from "react"; +import { useId, useState, type ReactNode } from "react"; import { CanvasIcon } from "./CanvasIcon"; import { useT } from "../i18n/I18nProvider.tsx"; @@ -40,6 +40,7 @@ export function ModelPicker({ fetchLabel?: string; }) { const t = useT(); + const manualFieldId = useId(); const [query, setQuery] = useState(""); const [onlySelected, setOnlySelected] = useState(false); const [manualOpen, setManualOpen] = useState(false); @@ -114,12 +115,12 @@ export function ModelPicker({ {manualOpen && (
-