@@ -1,4 +1,11 @@
-import { useEffect, useRef, useState, type RefObject } from "react";
+import {
+  useEffect,
+  useRef,
+  useState,
+  type FormEvent,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type RefObject,
+} from "react";
 import { useNavigate, useRouteLoaderData } from "react-router";
 import { FileText, Info, LayoutDashboard, MessageSquare, Pencil, X } from "lucide-react";
 import { Button } from "./ui/button";
@@ -36,6 +43,7 @@ export function CommandPalette({
   finalFocus?: RefObject<HTMLElement | null>;
 }) {
   const [query, setQuery] = useState("");
+  const hasExplicitCommandSelectionRef = useRef(false);
   const fallbackFinalFocusRef = useRef<HTMLElement | null>(null);
   const finalFocusRef = finalFocus ?? fallbackFinalFocusRef;
   const navigate = useNavigate();
@@ -64,17 +72,48 @@ export function CommandPalette({
   }, [finalFocusRef, onOpenChange, open]);
 
   useEffect(() => {
-    if (!open) setQuery("");
+    if (!open) {
+      setQuery("");
+      hasExplicitCommandSelectionRef.current = false;
+    }
   }, [open]);
 
-  function submit(event: React.FormEvent) {
-    event.preventDefault();
+  function search() {
     const value = query.trim();
     if (!value) return;
     onOpenChange(false);
     void navigate(`/search?q=${encodeURIComponent(value)}`);
   }
 
+  function submit(event: FormEvent) {
+    event.preventDefault();
+    search();
+  }
+
+  function updateQuery(value: string) {
+    hasExplicitCommandSelectionRef.current = false;
+    setQuery(value);
+  }
+
+  function handleCommandKeyDown(event: ReactKeyboardEvent<HTMLDivElement>) {
+    if (!(event.target instanceof HTMLInputElement)) return;
+
+    const isComposing = event.nativeEvent.isComposing || event.keyCode === 229;
+    if (isComposing) return;
+
+    if (["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) {
+      hasExplicitCommandSelectionRef.current = Boolean(
+        event.currentTarget.querySelector('[cmdk-item]:not([aria-disabled="true"])'),
+      );
+      return;
+    }
+
+    if (event.key !== "Enter" || hasExplicitCommandSelectionRef.current) return;
+
+    event.preventDefault();
+    search();
+  }
+
   function go(to: string) {
     onOpenChange(false);
     void navigate(to);
@@ -91,12 +130,12 @@ export function CommandPalette({
           <DialogTitle>搜索和快速操作</DialogTitle>
           <DialogDescription>搜索话题、用户，或跳转到常用页面。</DialogDescription>
         </DialogHeader>
-        <Command label="搜索命令">
+        <Command label="搜索命令" onKeyDown={handleCommandKeyDown}>
           <div data-slot="command-search-row" className="flex min-w-0 items-center gap-1 p-1 pb-0">
             <form onSubmit={submit} className="min-w-0 flex-1">
               <CommandInput
                 value={query}
-                onValueChange={setQuery}
+                onValueChange={updateQuery}
                 placeholder="搜索话题、用户，或输入关键词..."
                 aria-label="搜索命令"
                 autoFocus
 
@@ -18,6 +18,13 @@ afterEach(() => {
 });
 
 describe("异步反馈", () => {
+  function renderSearch(initialEntry = "/search") {
+    const router = createMemoryRouter([{ path: "*", element: <Search /> }], {
+      initialEntries: [initialEntry],
+    });
+    return { ...render(<RouterProvider router={router} />), router };
+  }
+
   it("announces Turnstile readiness and verification", async () => {
     let options: Record<string, unknown> = {};
     window.turnstile = {
@@ -57,4 +64,46 @@ describe("异步反馈", () => {
     await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
     expect(await screen.findByText('未找到与 "node" 相关的内容')).toBeInTheDocument();
   });
+
+  it.each(["keyboard", "button"])(
+    "normalizes and submits a search with the %s path",
+    async (submission) => {
+      const user = userEvent.setup();
+      apiFetch.mockResolvedValue({ success: true, data: [] });
+      const { router } = renderSearch();
+      const input = screen.getByRole("textbox", { name: "搜索话题" });
+
+      await user.type(input, "  node js  ");
+      if (submission === "keyboard") {
+        await user.keyboard("{Enter}");
+      } else {
+        await user.click(screen.getByRole("button", { name: "搜索" }));
+      }
+
+      await waitFor(() =>
+        expect(new URLSearchParams(router.state.location.search).get("q")).toBe("node js"),
+      );
+      await waitFor(() =>
+        expect(apiFetch).toHaveBeenCalledWith(
+          "/api/v1/search?q=node%20js&engine=local",
+          expect.objectContaining({ signal: expect.any(AbortSignal) }),
+        ),
+      );
+    },
+  );
+
+  it.each(["", "   "])("ignores an empty search query %p", async (query) => {
+    const user = userEvent.setup();
+    const { router } = renderSearch();
+    const input = screen.getByRole("textbox", { name: "搜索话题" });
+
+    if (query) await user.type(input, query);
+    await user.keyboard("{Enter}");
+
+    expect(router.state.location.pathname).toBe("/search");
+    expect(router.state.location.search).toBe("");
+    expect(apiFetch).not.toHaveBeenCalled();
+    expect(input).toHaveValue(query);
+    expect(input).toBeEnabled();
+  });
 });
@@ -1,8 +1,8 @@
-import { render, screen, waitFor, within } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { createMemoryRouter, MemoryRouter, RouterProvider } from "react-router";
 import { renderToString } from "react-dom/server";
-import { describe, expect, it } from "vite-plus/test";
+import { describe, expect, it, vi } from "vite-plus/test";
 import { Footer, Header, Layout } from "~/components/Layout";
 import { CommandPalette } from "~/components/CommandPalette";
 import { AdminLayout } from "~/components/AdminLayout";
@@ -109,7 +109,87 @@ describe("公开导航收束", () => {
     expect(await screen.findByRole("status")).toHaveTextContent("没有匹配的快捷命令");
   });
 
-  it.each([375, 1280])(
+  it.each([
+    ["绝对不存在的命令", "绝对不存在的命令"],
+    ["node", "node"],
+    ["  node js  ", "node js"],
+  ])(
+    "searches for %p with Enter instead of activating an implicit command",
+    async (query, expected) => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+      const { router } = renderWithRoot(<CommandPalette open onOpenChange={onOpenChange} />);
+      const input = screen.getByRole("combobox", { name: "搜索命令" });
+
+      await user.type(input, query);
+      await user.keyboard("{Enter}");
+
+      await waitFor(() => expect(router.state.location.pathname).toBe("/search"));
+      expect(new URLSearchParams(router.state.location.search).get("q")).toBe(expected);
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    },
+  );
+
+  it("resets explicit command selection when the query changes", async () => {
+    const user = userEvent.setup();
+    const { router } = renderWithRoot(<CommandPalette open onOpenChange={() => {}} />);
+    const input = screen.getByRole("combobox", { name: "搜索命令" });
+
+    await user.keyboard("{ArrowDown}");
+    await user.type(input, "node");
+    await user.keyboard("{Enter}");
+
+    await waitFor(() => expect(router.state.location.pathname).toBe("/search"));
+    expect(new URLSearchParams(router.state.location.search).get("q")).toBe("node");
+  });
+
+  it("keeps Enter available for search when arrow navigation has no matching command", async () => {
+    const user = userEvent.setup();
+    const { router } = renderWithRoot(<CommandPalette open onOpenChange={() => {}} />);
+    const input = screen.getByRole("combobox", { name: "搜索命令" });
+
+    await user.type(input, "绝对不存在的命令");
+    await user.keyboard("{ArrowDown}{Enter}");
+
+    await waitFor(() => expect(router.state.location.pathname).toBe("/search"));
+    expect(new URLSearchParams(router.state.location.search).get("q")).toBe("绝对不存在的命令");
+  });
+
+  it.each(["", "   "])("ignores an empty command search %p", async (query) => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    const { router } = renderWithRoot(<CommandPalette open onOpenChange={onOpenChange} />);
+    const input = screen.getByRole("combobox", { name: "搜索命令" });
+
+    if (query) await user.type(input, query);
+    await user.keyboard("{Enter}");
+
+    expect(router.state.location.pathname).toBe("/");
+    expect(router.state.location.search).toBe("");
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    expect(input).toHaveValue(query);
+    expect(input).toBeEnabled();
+  });
+
+  it("does not submit or activate a command while an IME composition is active", async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    const { router } = renderWithRoot(<CommandPalette open onOpenChange={onOpenChange} />);
+    const input = screen.getByRole("combobox", { name: "搜索命令" });
+    await user.type(input, "节点");
+
+    fireEvent.keyDown(input, { key: "Enter", code: "Enter", isComposing: true });
+
+    expect(router.state.location.pathname).toBe("/");
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    expect(input).toHaveValue("节点");
+
+    await user.keyboard("{Enter}");
+    await waitFor(() => expect(router.state.location.pathname).toBe("/search"));
+    expect(new URLSearchParams(router.state.location.search).get("q")).toBe("节点");
+  });
+
+  it.each([375, 768, 1280, 1440])(
     "allocates a non-overlapping search row and touch-safe close control at %ipx",
     (width) => {
       window.innerWidth = width;
 
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-11-09
@@ -0,0 +1,91 @@
+# Design
+
+## Context
+
+参见 `proposal.md` 的问题说明。页头 `CommandPalette` 同时承载两种操作：提交自由文本搜索，以及从 `cmdk` 列表执行快捷操作。当前输入框位于原生 `<form>` 内，但 `cmdk` 根组件在冒泡阶段对 Enter 调用 `preventDefault()`，导致表单 `onSubmit` 不运行；若筛选后存在隐式选中项，Enter 还会执行该项。
+
+`/search` 是现有 feed archetype 路由，查询词由 URL `q` 参数驱动，随后调用既有 `/api/v1/search?q=...&engine=local`。本次设计保持该 URL 和请求边界不变。UI 继续复用 `Layout`、`FeedPage`、Field、Input、Button、Dialog 和 Command 组合，不修改 design token、响应式结构或 primitive API。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 在 `CommandPalette` consumer 层区分“直接提交搜索”和“明确选择快捷操作”。
+- 让 Enter 和按钮提交共用同一套 trim、空值判断与 URL 构造规则。
+- 在事件处理顺序中正确保护输入法组合文本。
+- 用行为测试覆盖 `cmdk` 拦截 Enter 的真实集成路径，而不是只测试提交函数。
+
+**Non-Goals:**
+
+- 不改变搜索接口、结果数据、搜索范围、排序或错误反馈。
+- 不把站内搜索语义写入通用 Command/Input primitive。
+- 不升级、替换或 fork `cmdk`，也不新增搜索抽象层。
+
+## Decisions
+
+### 1. 在 CommandPalette consumer 层抢先处理搜索 Enter
+
+在 `CommandPalette` 的 Command 事件边界观察键盘操作。当事件来自搜索输入、不是输入法组合状态、查询词非空，且用户没有通过方向键明确移动快捷项选择时，处理器将阻止 `cmdk` 的默认 Enter 行为并调用统一搜索提交函数。`cmdk` 会先调用 consumer 提供的键盘处理器，再检查 `defaultPrevented`，因此该边界可以避免隐式快捷项执行。
+
+```mermaid
+flowchart TD
+  A[搜索输入收到 Enter] --> B{正在输入法组合?}
+  B -- 是 --> C[保留组合确认行为]
+  B -- 否 --> D{关键词 trim 后非空?}
+  D -- 否 --> E[不发起搜索]
+  D -- 是 --> F{用户明确移动过快捷项选择?}
+  F -- 是 --> G[交给 cmdk 执行当前快捷项]
+  F -- 否 --> H[阻止 cmdk 默认行为]
+  H --> I[关闭面板并导航到 /search?q=...]
+```
+
+选择意图只由当前查询周期内的方向键导航建立；搜索词变化后重置。鼠标或触控直接激活 `CommandItem` 继续走现有 `onSelect`。
+
+**拒绝的替代方案：**
+
+- 只依赖 `<form onSubmit>`：`cmdk` 已经取消 Enter 默认行为，无法修复根因。
+- 在输入框每次 Enter 都搜索：会破坏现有方向键选择快捷操作的键盘能力。
+- 修改共享 `components/ui/command.tsx`：搜索优先是 CNode CommandPalette 的领域行为，写入 primitive 会影响其他 Command 使用者并违反 primitive ownership。
+- 将“搜索关键词”渲染为动态 CommandItem：可以利用 `cmdk` 选择模型，但会改变列表结构、筛选排序和辅助技术播报，修复范围更大。
+
+### 2. 搜索提交使用单一函数，表单作为可访问回退边界
+
+CommandPalette 内部用一个提交函数完成 trim、空值判断、关闭面板和 React Router 导航；表单 `onSubmit` 与键盘拦截路径调用相同逻辑。`/search` 页面继续使用原生表单提交事件，使 Enter 和 Button `type="submit"` 进入同一个 handler。
+
+URL 继续通过路由 API 写入 `q`，并在构造导航 URL 时编码查询值。不引入额外本地搜索状态或请求层改动。
+
+**拒绝的替代方案：**
+
+- 为 Enter 和按钮维护两个处理函数：容易产生 trim、空查询和 URL 编码差异。
+- 使用 `window.location` 全页跳转：会丢失 React Router 客户端导航和现有 transition 行为。
+
+### 3. IME 判断先于搜索和快捷操作判断
+
+键盘处理器首先检查原生 composition 状态，并兼容浏览器用于组合输入的 key code。组合中的 Enter 不调用 `preventDefault()`、不关闭 overlay、不导航；组合结束后的下一次 Enter 才按普通规则处理。
+
+**拒绝的替代方案：**
+
+- 仅监听 `compositionend` 后设置延时状态：增加竞态和计时依赖，没有必要。
+- 仅检查 React 合成事件字段：底层 `cmdk` 读取原生事件，统一参考原生 composition 状态更接近实际冲突点。
+
+### 4. 测试覆盖事件竞争和两个入口的行为一致性
+
+CommandPalette 测试使用真实 Command、输入框和 memory router：输入无匹配关键词按 Enter、输入可模糊匹配快捷项的关键词按 Enter、方向键明确选项后按 Enter、空查询，以及 composition Enter。搜索页测试验证 Enter 与按钮都更新 `q` 并触发同一查询。
+
+视觉结构没有变化，因此不新增截图基线；实施验收仍在桌面和移动 viewport 检查 overlay、焦点、Escape、关闭控件及结果状态，并检查浏览器 console。
+
+## Risks / Trade-offs
+
+- [明确选择状态没有在查询变化时重置] → 在输入值变化、面板关闭和重新打开时重置，并用“方向键后继续输入再 Enter”的测试覆盖。
+- [IME Enter 被误提交] → 在 consumer handler 最前检查 `nativeEvent.isComposing` 和兼容信号，并增加 composition 回归测试。
+- [键盘快捷操作失效] → 保留方向键建立明确选择后由 `cmdk` 处理 Enter，并保留现有快捷操作测试。
+- [事件处理依赖 `cmdk` 当前调用顺序] → 集成测试直接挂载真实 `cmdk@1.1.1`；不 mock Command primitive。未来升级依赖时同一测试将暴露变化。
+- [额外选择意图状态增加复杂度] → 状态只存在于 CommandPalette，不进入全局 store 或通用 primitive。
+
+## Migration Plan
+
+1. 实施 Web consumer 行为和回归测试，不执行数据迁移或接口发布。
+2. 运行目标测试、Web test/typecheck/build，并在可行时运行 `pnpm verify`。
+3. 按 `cnode-deploy` 流程等待 CI 镜像构建完成、部署现有 Compose 服务，并验证生产健康状态。
+4. 在生产环境分别验证无匹配关键词、可模糊匹配关键词、方向键快捷项、Escape/焦点恢复和移动端搜索。
+5. 如出现回归，按现有部署流程回滚到前一个不可变镜像；无数据库或 API 回滚步骤。
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+schema: spec-driven`
	`2`	`+created: 2026-11-09`