Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ This directory is the entry point for the repository's shared documentation. The
| [Development guidance](../AGENTS.md) | Product direction and enduring principles | Architecture principles or product boundaries change |
| [Contributing](../CONTRIBUTING.md) | Label taxonomy, how to pick labels, and what a PR must satisfy | Process, labels, or submission requirements change |
| [Unified project architecture](architecture/unified-project.md) | Business objects, shared entry points, and interaction rules | Object responsibilities, commands, persistence, or interaction rules change |
| [Workspace modes RFC (中文)](architecture/workspace-modes-rfc.zh-CN.md) | Proposed Agent-focused mode and a 1:2 chat/canvas layout, UI sketches, switching behavior, and acceptance | The mode design or its acceptance criteria change |
| [Test contracts](architecture/test-contracts.md) | Test/production boundaries, how to avoid stale assertions and environment-dependent red runs | Test infrastructure, capability gates, or contract ownership change |
| [Capability mapping contract](architecture/capability-contract.md) | Evidenced upstream vocabulary, the `(operation, profile) → capability` table, the untranslatable declarations, and how it feeds discovery | Upstream vocabulary, capability ids, or discovery matching change |
| [Roadmap](development/roadmap.md) | Capability dependencies and delivery criteria | Scope, dependencies, or acceptance criteria change |
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
244 changes: 244 additions & 0 deletions docs/architecture/workspace-modes-rfc.zh-CN.md

Large diffs are not rendered by default.

7 changes: 4 additions & 3 deletions docs/development/i18n.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# 中英双语界面

界面语言在 `zh-CN` 与 `en-US` 之间切换。中文是默认语言,也是词条键的基准;英文必须覆盖同一组键。
界面语言在 `zh-CN` 与 `en-US` 之间切换。中文是词条键的基准;英文必须覆盖同一组键。

## 语言选择

- 用户可以在画布左上角的「中文 | EN」开关直接切换,也可以使用「设置 → 界面语言」。
- 用户在「设置 → 界面语言」保存的选择优先。
- 两种创作模式都可以在「设置 → 通用 → 语言」切换语言。纯净模式的设置入口在顶栏;画布模式在左下角,宽窗口下也保留左上角的「中文 | EN」开关。
- 用户保存的语言选择优先,切换创作模式不会改变语言。
- 没有保存值时,浏览器语言以 `zh` 开头使用 `zh-CN`,以 `en` 开头使用 `en-US`,其他语言使用英文 `en-US`。
- 选择保存在 `localStorage` 的 `opendirector.locale.v1`,并同步到 `<html lang>` 与 `data-locale`。
- 界面语言不影响 Agent 回复语言。Agent 始终跟随用户最新提问的语言,不参考当前界面语言。
Expand Down Expand Up @@ -96,6 +96,7 @@ npm run check:i18n
| 模型与服务 | [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) |
| 画布工作区 | [canvasWorkspace.ts](../../src/i18n/messages/zh-CN/canvasWorkspace.ts) | [canvasWorkspace.ts](../../src/i18n/messages/en-US/canvasWorkspace.ts) |
| 创作模式 | [workspaceModes.ts](../../src/i18n/messages/zh-CN/workspaceModes.ts) | [workspaceModes.ts](../../src/i18n/messages/en-US/workspaceModes.ts) |
| 生成器 | [generation.ts](../../src/i18n/messages/zh-CN/generation.ts) | [generation.ts](../../src/i18n/messages/en-US/generation.ts) |
| 音色库 | [voiceLibrary.ts](../../src/i18n/messages/zh-CN/voiceLibrary.ts) | [voiceLibrary.ts](../../src/i18n/messages/en-US/voiceLibrary.ts) |
| 时间线 | [timeline.ts](../../src/i18n/messages/zh-CN/timeline.ts) | [timeline.ts](../../src/i18n/messages/en-US/timeline.ts) |
Expand Down
6 changes: 6 additions & 0 deletions docs/development/lessons.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,12 @@ When work exposes a consequential risk or a recurring problem, add a lesson or u

- **Color profile follow-up:** [PR #287's P3 review](https://github.com/ThinkFlowLab/OpenDirector/pull/287#pullrequestreview-5870014881) found that a correct full-size PNG did not prove correct thumbnails: the library JPEG and the asset/history WebP used separate encoders that both omitted ICC. Check every displayed rendition and the actual embedded profile, not only dimensions or successful decoding. Preserve RGB profiles through resizing, but do not attach a non-RGB source profile after converting its channels to RGB. / **颜色配置补充:** 同一素材的全尺寸 PNG 正确,并不能证明素材库 JPEG 和资产/版本历史 WebP 正确。逐条检查显示路径的实际 ICC;缩放保留 RGB 配置,转换通道后不能继续附带非 RGB 源配置。

## Asynchronous readiness must preserve newer focus

- **Trigger:** Opening chat by default or retaining it while changing projects, when its data finishes loading after the user has focused another control.
- **Evidence:** [PR #380](https://github.com/ThinkFlowLab/OpenDirector/pull/380) reproduced delayed assistant reads closing the project picker and ending new-project renaming. Project creation and opening succeeded; the chat's readiness effect moved focus and triggered the other controls' dismissal handlers.
- **Check:** Hold the assistant read until the project picker or name editor is active, then release it and verify that both the control and its focus remain. Preserve focus requested by explicitly opening chat or changing conversations, while respecting a later user focus change. Distinguish a controlled reproduction from proof of the original CI event order.

## Baseline failures still need tracking

- **Trigger:** A relevant test fails and comparison shows that it also fails on the baseline.
Expand Down
18 changes: 15 additions & 3 deletions docs/guides/user-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,23 @@

[English](user-guide.md) · [简体中文](user-guide.zh-CN.md) · [Back to README](../../README.md)

## Choose a creation mode

Use **Agent mode** and **Canvas mode** in the top bar to switch layouts. OpenDirector starts in Canvas mode when no preference is saved, and remembers your choice in this browser.

- **Agent mode** centers the chat so you can describe a goal and work with the assistant. Press `Shift` twice to focus the input. To inspect or edit nodes and the timeline, switch to Canvas mode.
- **Canvas mode** places chat on the left and the canvas on the right, with a default 1:2 split. Drag the divider to resize the chat, or double-click it to restore the default width. Use **Collapse AI chat** to hide the chat and **Chat with AI** to bring it back.
- In a narrow window, Canvas mode shows one area at a time. Use **Show canvas** and **Chat with AI** to switch between them.

Both modes share the same project, conversation, draft and attachments. Switching modes preserves the canvas view and keeps replies and generation tasks running without submitting them again.

Change the interface language in **Settings → General → Language**. Agent mode has a settings button in the top bar; Canvas mode has one at the bottom left. The assistant's reply language follows your question.

## Connect models

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.
Open **Settings → Model connections**. Add models for chat, image, video, or audio generation as needed.

For optional Kling 4.0 and Flash video generation, follow [Generate videos with Kling](kling-video.md). Both support text, first-frame, and image-reference generation. Standard Kling 4.0 also supports first-and-last frames. Adding the service preserves your existing model selection.

Expand Down Expand Up @@ -137,13 +149,13 @@ Codex web search citations appear as numbered source links when the search resul

Click a source number to view its full URL in a bordered information card, then choose **Copy link** or **Open link**. Close the card with the button at its top right, by pressing `Esc`, or by clicking outside it.

Click **Chat with AI** at the bottom right, select a chat model, and describe what you want to create. You can upload, drag and drop, or paste assets, or type `@` to reference canvas content. The assistant can save text as requested and call configured generation models to create assets.
Use the chat in either creation mode, select a chat model, and describe what you want to create. If the chat is collapsed in Canvas mode, click **Chat with AI** to reopen it. You can upload, drag and drop, or paste assets, or type `@` to reference canvas content. The assistant can save text as requested and call configured generation models to create assets.

Use **New conversation** at the top of the panel to start a separate chat. **Conversation history** lets you search and switch between this canvas's conversations. Switching saves your draft and restores the selected conversation's messages, reference attachments, and model choices; the active conversation also survives a page reload. Wait for uploads or replies to finish, or stop the reply, before switching.

- Press `Enter` to send, or `Shift+Enter` for a new line.
- You can stop the response while it is being generated.
- Click the collapse button at the top right to hide the chat panel. Drag its left edge to resize it.
- In Canvas mode, click **Collapse AI chat** to hide the chat panel. Drag its right edge to resize it, or double-click the edge to restore the default width.

Asset generation may continue after the reply ends. Check its progress in **Generation history**.

Expand Down
18 changes: 15 additions & 3 deletions docs/guides/user-guide.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,23 @@

[English](user-guide.md) · [简体中文](user-guide.zh-CN.md) · [返回首页](../../README.zh-CN.md)

## 选择创作模式

在顶栏点击“纯净模式”或“画布模式”切换布局。没有保存过选择时,默认进入画布模式;之后会记住你在当前浏览器中的选择。

- **纯净模式**:对话居中,直接向助手描述创作目标。连按两次 `Shift` 可聚焦输入框。需要查看或编辑节点、时间线时,切到画布模式。
- **画布模式**:左边聊天,右边画布,默认按 1:2 分栏。拖动分隔线调整对话宽度,双击恢复默认宽度。点击“收起 AI 对话”隐藏对话框,点击“与 AI 对话”恢复。
- 窗口较窄时,画布模式一次显示一个区域,通过“查看画布”和“与 AI 对话”切换。

两种模式共用当前项目、会话、输入草稿和附件。切换会保留画布视角,正在进行的回复和生成任务会继续,不会重新提交。

界面语言在“设置 → 通用 → 语言”中切换。纯净模式的设置入口在顶栏,画布模式在左下角。助手的回复语言跟随你的提问。

## 接入模型

选择外部 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。

点击左下角齿轮进入“设置”,打开“模型接入”,按用途添加对话、图片、视频或音频模型。
打开“设置 → 模型接入”,按用途添加对话、图片、视频或音频模型。

需要接入可灵 4.0 或 Flash 时,参阅[使用可灵生成视频](kling-video.zh-CN.md)。两个型号均支持文生、首帧和图片参考,标准版 4.0 额外支持首尾帧。添加后保留已有模型选择。

Expand Down Expand Up @@ -137,13 +149,13 @@ Codex 网页检索引用在具有匹配来源时显示为编号链接;复制

点击来源编号可在带边框的信息卡片中查看完整链接,再选择“复制链接”或“打开链接”。可通过卡片右上角的关闭按钮、按 `Esc` 或点击卡片外部关闭。

点击右下角“与 AI 对话”,选择对话模型后输入创作要求。可上传、拖放、粘贴素材,或输入 `@` 引用画布中的内容。助手可按要求保存文本,并调用已配置的生成模型制作素材。
两种创作模式都可以使用对话。选择对话模型后输入创作要求;画布模式中若对话框已收起,点击“与 AI 对话”恢复。可上传、拖放、粘贴素材,或输入 `@` 引用画布中的内容。助手可按要求保存文本,并调用已配置的生成模型制作素材。

点击对话框顶部“新建”开始独立会话;点击“历史会话”可搜索并切换当前画布的旧会话。切换前会保存草稿,切回后恢复消息、参考附件和模型选择,刷新页面仍保留当前会话。回复或参考上传进行中,请先等待完成或停止回复后再切换。

- `Enter` 发送,`Shift+Enter` 换行。
- 回复过程中可停止输出。
- 点击右上角收起按钮隐藏对话框;拖动左边缘调整宽度。
- 画布模式中,点击“收起 AI 对话”隐藏对话框;拖动右边缘调整宽度,双击恢复默认宽度。

素材生成可能在回复结束后继续进行,可在“生成历史”查看进度。

Expand Down
3 changes: 3 additions & 0 deletions scripts/verify_creation_browser.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,9 @@ try {
await prompt.fill("Based on @");
await prompt.press("Enter");
await prompt.locator("[data-reference]").waitFor();
// Selecting the target can pan the source outside the visible canvas.
await page.getByRole("button", { name: "Zoom options", exact: true }).click();
await page.getByRole("button", { name: /^Fit all content/ }).click();
await source.locator(".cw-node-title").dblclick();
await page
.getByRole("textbox", { name: "Node name", exact: true })
Expand Down
19 changes: 13 additions & 6 deletions src/canvas/AgentPicker.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -281,15 +281,22 @@ export function AgentPicker({
}, [open, editing, editingModel, setup]);
useLayoutEffect(() => {
if ((!editing && !editingModel) || !submenu.current || !menu.current) return;
const bounds = menu.current.getBoundingClientRect();
const layer = submenu.current;
layer.style.left = `${Math.max(8, bounds.left - 310)}px`;
layer.style.bottom = `${window.innerHeight - bounds.bottom}px`;
const position = () => {
const bounds = menu.current!.getBoundingClientRect();
const left = bounds.right + 310 <= window.innerWidth - 8 ? bounds.right + 10 : bounds.left - 310;
layer.style.left = `${Math.max(8, Math.min(left, window.innerWidth - 308))}px`;
layer.style.bottom = `${window.innerHeight - bounds.bottom}px`;
};
position();
layer.showPopover();
const reposition = () => { setEditing(null); setEditingModel(null); };
window.addEventListener("resize", reposition);
const observer = new ResizeObserver(position);
const host = menu.current.closest(".cw-assistant-panel");
if (host) observer.observe(host);
window.addEventListener("resize", position);
return () => {
window.removeEventListener("resize", reposition);
observer.disconnect();
window.removeEventListener("resize", position);
};
}, [editing, editingModel]);
function keys(event: KeyboardEvent<HTMLDivElement>) {
Expand Down
6 changes: 4 additions & 2 deletions src/canvas/AssistantConversations.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ export function AssistantConversations({
onRefresh,
onChange,
onClose,
collapsible = true,
}: {
activeId?: string;
hasMessages: boolean;
Expand All @@ -30,6 +31,7 @@ export function AssistantConversations({
onRefresh: () => void;
onChange: (id?: string, create?: boolean) => Promise<boolean>;
onClose: () => void;
collapsible?: boolean;
}) {
const t = useT();
const [open, setOpen] = useState(false);
Expand Down Expand Up @@ -148,7 +150,7 @@ export function AssistantConversations({
>
<CanvasIcon name="history" size={18} />
</TooltipButton>
<TooltipButton
{collapsible && <TooltipButton
className="cw-assistant-collapse"
label={t("assistant.sessions.collapse")}
tooltipSide="bottom"
Expand All @@ -157,7 +159,7 @@ export function AssistantConversations({
onClick={onClose}
>
<CanvasIcon name="collapse" size={18} />
</TooltipButton>
</TooltipButton>}
</div>
</header>
{open && (
Expand Down
25 changes: 22 additions & 3 deletions src/canvas/AssistantPanel.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ export function AssistantPanel({
visibleNodes,
selectedNodes,
open,
collapsible = true,
layout,
selectionRequest,
onClose,
Expand All @@ -76,6 +77,7 @@ export function AssistantPanel({
visibleNodes: CanvasNode[];
selectedNodes: CanvasNode[];
open: boolean;
collapsible?: boolean;
layout: AssistantLayout;
selectionRequest: number;
onClose: () => void;
Expand Down Expand Up @@ -173,8 +175,24 @@ export function AssistantPanel({
chat.setContent(content, projectReferences.assets);
}, [projectReferences.assets]);

const previouslyOpen = useRef(open);
const openFocusTarget = useRef<Element | null>(null);
useEffect(() => {
if (open && chat.loaded) editor.current?.focus();
if (open && !previouslyOpen.current)
openFocusTarget.current = document.activeElement;
previouslyOpen.current = open;
if (!open) {
openFocusTarget.current = null;
return;
}
if (!chat.loaded) return;
const active = document.activeElement;
// Loading a default-open chat must not dismiss a project menu or rename.
// An explicit open retains focus intent until the user chooses another control.
if (active === document.body || active?.closest("#canvas-assistant") ||
active === openFocusTarget.current)
editor.current?.focus();
openFocusTarget.current = null;
}, [open, chat.loaded, value.conversationId]);
const displayedAssets = [
...new Map(
Expand Down Expand Up @@ -346,7 +364,7 @@ export function AssistantPanel({
event.preventDefault();
event.stopPropagation();
if (mediaPreview) setMediaPreview(null);
else onClose();
else if (collapsible) onClose();
}
}}
onDragOver={(event) => {
Expand Down Expand Up @@ -385,6 +403,7 @@ export function AssistantPanel({
}
onChange={changeConversation}
onClose={onClose}
collapsible={collapsible}
/>
<div
className="cw-assistant-log"
Expand Down Expand Up @@ -782,7 +801,7 @@ export function AssistantPanel({
)}
</div>
</div>
{!layout.mobile && (
{collapsible && !layout.mobile && (
<div
className="cw-assistant-resizer"
role="separator"
Expand Down
Loading
Loading