diff --git a/tests/unit/usage-doc/opencode-usage-doc.test.tsx b/tests/unit/usage-doc/opencode-usage-doc.test.tsx
new file mode 100644
index 000000000..f0adc8baa
--- /dev/null
+++ b/tests/unit/usage-doc/opencode-usage-doc.test.tsx
@@ -0,0 +1,125 @@
+/**
+ * @vitest-environment happy-dom
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { ReactNode } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { NextIntlClientProvider } from "next-intl";
+import { describe, expect, test, vi } from "vitest";
+import { UsageDocContent } from "@/app/[locale]/usage-doc/page";
+import { locales } from "@/i18n/config";
+
+// 测试环境不加载 next-intl/navigation -> next/navigation 的真实实现（避免 Next.js 运行时依赖）
+vi.mock("@/i18n/routing", () => ({
+ Link: ({ children }: { children: ReactNode }) => children,
+}));
+
+function loadUsageMessages(locale: string) {
+ return JSON.parse(
+ fs.readFileSync(path.join(process.cwd(), "messages", locale, "usage.json"), "utf8")
+ );
+}
+
+function renderWithIntl(locale: string, node: ReactNode) {
+ const container = document.createElement("div");
+ document.body.appendChild(container);
+ const root = createRoot(container);
+ const usageMessages = loadUsageMessages(locale);
+
+ act(() => {
+ root.render(
+
+ {node}
+
+ );
+ });
+
+ return {
+ unmount: () => {
+ act(() => root.unmount());
+ container.remove();
+ },
+ };
+}
+
+describe("UsageDoc - OpenCode 配置教程", () => {
+ test("OpenCode 段落应位于 Gemini CLI 之后、Droid 之前", () => {
+ const { unmount } = renderWithIntl("en",
);
+
+ const h2Ids = Array.from(document.querySelectorAll("h2")).map((el) => el.id);
+
+ expect(h2Ids).toContain("gemini");
+ expect(h2Ids).toContain("opencode");
+ expect(h2Ids).toContain("droid");
+ expect(h2Ids.indexOf("gemini")).toBeLessThan(h2Ids.indexOf("opencode"));
+ expect(h2Ids.indexOf("opencode")).toBeLessThan(h2Ids.indexOf("droid"));
+
+ unmount();
+ });
+
+ test("应提供单份 opencode.json 示例，且包含 cch 端点与所有要求模型", () => {
+ const { unmount } = renderWithIntl("en",
);
+
+ const text = document.body.textContent || "";
+
+ expect(text).toContain('"$schema": "https://opencode.ai/config.json"');
+ expect(text).toContain('"baseURL": "http://localhost:23000/v1"');
+
+ expect(text).toContain('"npm": "@ai-sdk/anthropic"');
+ expect(text).toContain('"npm": "@ai-sdk/openai"');
+ expect(text).toContain('"npm": "@ai-sdk/google"');
+ expect(text).not.toContain("@ai-sdk/openai-compatible");
+
+ expect(text).toContain("claude-haiku-4-5-20251001");
+ expect(text).toContain("claude-sonnet-4-5-20250929");
+ expect(text).toContain("claude-opus-4-5-20251101");
+
+ expect(text).toContain("gpt-5.2");
+
+ expect(text).toContain("gemini-3-pro-preview");
+ expect(text).toContain("gemini-3-flash-preview");
+
+ unmount();
+ });
+
+ test("应包含官方安装方式示例（curl/npm/bun/brew/paru，以及 Windows 包管理器）", () => {
+ const { unmount } = renderWithIntl("en",
);
+
+ const text = document.body.textContent || "";
+
+ expect(text).toContain("curl -fsSL https://opencode.ai/install | bash");
+ expect(text).toContain("npm install -g opencode-ai");
+ expect(text).toContain("bun add -g opencode-ai");
+ expect(text).toContain("brew install anomalyco/tap/opencode");
+ expect(text).toContain("paru -S opencode-bin");
+
+ expect(text).toContain("choco install opencode");
+ expect(text).toContain("scoop bucket add extras");
+ expect(text).toContain("scoop install extras/opencode");
+
+ unmount();
+ });
+
+ test("5 语言 messages/ 需包含 OpenCode 段落的关键翻译键", () => {
+ for (const locale of locales) {
+ const usageMessages = loadUsageMessages(locale);
+
+ expect(usageMessages).toHaveProperty("opencode.title");
+ expect(usageMessages).toHaveProperty("opencode.description");
+ expect(usageMessages).toHaveProperty("opencode.installation.title");
+ expect(usageMessages).toHaveProperty("opencode.installation.script.title");
+ expect(usageMessages).toHaveProperty("opencode.installation.npm.title");
+ expect(usageMessages).toHaveProperty("opencode.installation.bun.title");
+ expect(usageMessages).toHaveProperty("opencode.installation.macos.homebrew.title");
+ expect(usageMessages).toHaveProperty("opencode.installation.linux.homebrew.title");
+ expect(usageMessages).toHaveProperty("opencode.installation.linux.paru.title");
+ expect(usageMessages).toHaveProperty("opencode.installation.windows.note");
+ expect(usageMessages).toHaveProperty("opencode.configuration.title");
+ expect(usageMessages).toHaveProperty("opencode.startup.title");
+ expect(usageMessages).toHaveProperty("opencode.commonIssues.title");
+ }
+ });
+});
diff --git a/tests/unit/usage-doc/usage-doc-page.test.tsx b/tests/unit/usage-doc/usage-doc-page.test.tsx
new file mode 100644
index 000000000..1ddebb80f
--- /dev/null
+++ b/tests/unit/usage-doc/usage-doc-page.test.tsx
@@ -0,0 +1,108 @@
+/**
+ * @vitest-environment happy-dom
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { ReactNode } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { NextIntlClientProvider } from "next-intl";
+import { describe, expect, test, vi } from "vitest";
+import UsageDocPage from "@/app/[locale]/usage-doc/page";
+
+vi.mock("@/i18n/routing", () => ({
+ Link: ({
+ href,
+ children,
+ ...rest
+ }: {
+ href: string;
+ children: ReactNode;
+ className?: string;
+ }) => (
+
+ {children}
+
+ ),
+}));
+
+function loadUsageMessages(locale: string) {
+ return JSON.parse(
+ fs.readFileSync(path.join(process.cwd(), "messages", locale, "usage.json"), "utf8")
+ );
+}
+
+async function renderWithIntl(locale: string, node: ReactNode) {
+ const container = document.createElement("div");
+ document.body.appendChild(container);
+ const root = createRoot(container);
+ const usageMessages = loadUsageMessages(locale);
+
+ await act(async () => {
+ root.render(
+
+ {node}
+
+ );
+ });
+
+ return {
+ unmount: async () => {
+ await act(async () => root.unmount());
+ container.remove();
+ },
+ };
+}
+
+describe("UsageDocPage - 目录/快速链接交互", () => {
+ test("应渲染 skip links，且登录态显示返回仪表盘链接", async () => {
+ Object.defineProperty(window, "scrollTo", {
+ value: vi.fn(),
+ writable: true,
+ });
+
+ document.cookie = "auth-token=test-token";
+
+ const { unmount } = await renderWithIntl("en",
);
+
+ expect(document.querySelector('a[href="#main-content"]')).not.toBeNull();
+ expect(document.querySelector('a[href="#toc-navigation"]')).not.toBeNull();
+
+ const dashboardLink = document.querySelector('a[href="/dashboard"]');
+ expect(dashboardLink).not.toBeNull();
+
+ await unmount();
+ });
+
+ test("目录项点击后应触发平滑滚动", async () => {
+ const scrollToMock = vi.fn();
+ Object.defineProperty(window, "scrollTo", {
+ value: scrollToMock,
+ writable: true,
+ });
+
+ const { unmount } = await renderWithIntl("en",
);
+
+ const tocNav = document.querySelector("#toc-navigation nav");
+ expect(tocNav).not.toBeNull();
+
+ let tocButtons = tocNav?.querySelectorAll("button") ?? [];
+ for (let i = 0; i < 10 && tocButtons.length === 0; i++) {
+ await act(async () => {
+ await new Promise((r) => setTimeout(r, 0));
+ });
+ tocButtons = tocNav?.querySelectorAll("button") ?? [];
+ }
+
+ expect(tocButtons.length).toBeGreaterThan(0);
+
+ await act(async () => {
+ (tocButtons[0] as HTMLButtonElement).click();
+ });
+
+ expect(scrollToMock).toHaveBeenCalled();
+
+ await unmount();
+ });
+});