From cf08a1e14b925c2b6fa4cc098a27197a924944b8 Mon Sep 17 00:00:00 2001 From: Hunter Bown Date: Sun, 24 May 2026 03:37:08 -0500 Subject: [PATCH] docs(web): track FAQ route and ignore generated artifacts --- .gitignore | 2 + npm/deepseek-tui/.gitignore | 1 + web/app/[locale]/faq/page.tsx | 718 ++++++++++++++++++++++++++++++++++ 3 files changed, 721 insertions(+) create mode 100644 npm/deepseek-tui/.gitignore create mode 100644 web/app/[locale]/faq/page.tsx diff --git a/.gitignore b/.gitignore index f81c444e..7bc352dd 100644 --- a/.gitignore +++ b/.gitignore @@ -61,11 +61,13 @@ count_deps.py project_overhaul_prompt.md .codex/ .context/ +.wrangler/ # Local runtime state .deepseek/ **/session_*.json *.db +npm/*/bin/downloads/ # Companion app (tracked separately) apps/ diff --git a/npm/deepseek-tui/.gitignore b/npm/deepseek-tui/.gitignore new file mode 100644 index 00000000..f98d9c9f --- /dev/null +++ b/npm/deepseek-tui/.gitignore @@ -0,0 +1 @@ +bin/downloads/ diff --git a/web/app/[locale]/faq/page.tsx b/web/app/[locale]/faq/page.tsx new file mode 100644 index 00000000..4a3af70c --- /dev/null +++ b/web/app/[locale]/faq/page.tsx @@ -0,0 +1,718 @@ +import Link from "next/link"; +import { Seal } from "@/components/seal"; + +export async function generateMetadata({ params }: { params: Promise<{ locale: string }> }) { + const { locale } = await params; + const isZh = locale === "zh"; + return { + title: isZh ? "常见问题 · CodeWhale" : "FAQ · CodeWhale", + description: isZh + ? "CodeWhale 常见问题：安装、配置、提供商、模型、模式、安全与隐私。答案来自实际代码、文档和 GitHub 议题。" + : "CodeWhale frequently asked questions: install, config, providers, models, modes, security, and privacy. Answers sourced from real code, docs, and GitHub issues.", + }; +} + +interface FaqItem { + q: string; + a: React.ReactNode; + sources?: string[]; +} + +const faqEn: FaqItem[] = [ + { + q: "What is CodeWhale?", + a: ( + <> + CodeWhale is a terminal-native coding agent for open-source and open-weight models. It runs from the codewhale command, streams reasoning blocks, edits local workspaces with approval gates, and can auto-route each turn to the right model and thinking level. DeepSeek V4 is the first-class model path; OpenRouter is ready. Hugging Face, self-hosted, and other open-model surfaces are on the roadmap. + + ), + sources: ["README.md", "docs/ARCHITECTURE.md"], + }, + { + q: "How do I install CodeWhale?", + a: ( + <> +

Four paths, same result:

+ 
+{`# npm (recommended — no Rust toolchain needed)
+npm install -g codewhale
+
+# Cargo (needs Rust 1.88+)
+cargo install codewhale-cli --locked
+
+# Homebrew (macOS)
+brew tap Hmbown/deepseek-tui && brew install deepseek-tui
+
+# Direct download
+# https://github.com/Hmbown/CodeWhale/releases`}
+
+

+ Run codewhale to start. First run creates ~/.deepseek/ automatically. + See the full install guide for China mirrors, Docker, and troubleshooting. +

+ + ), + sources: ["README.md", "#1860", "#1914"], + }, + { + q: "What's the difference between codewhale and codewhale-tui?", + a: ( + <> + codewhale is the dispatcher CLI — it manages config, auth, updates, and launches the TUI. + codewhale-tui is the terminal UI binary that runs the agent loop. + When you type codewhale, the dispatcher spawns codewhale-tui for you. + Both are installed together; you rarely need to think about the split. + + ), + sources: ["README.md"], + }, + { + q: "Is CodeWhale the same as DeepSeek TUI? What about the rename?", + a: ( + <> + Yes. CodeWhale is the new name for what was previously called DeepSeek TUI. + The canonical command is now codewhale. Legacy deepseek and deepseek-tui commands remain as compatibility shims — they still work. + Config lives at ~/.deepseek/. DEEPSEEK_* env vars continue to work. + DeepSeek is not deprecated. The rename reflects CodeWhale's broader mission as the agentic terminal for open models across providers, not a narrowing away from DeepSeek. + + ), + sources: ["docs/REBRAND.md", "README.md"], + }, + { + q: "How do I set my API key?", + a: ( + <> + 
+{`# Method 1: Environment variable
+export DEEPSEEK_API_KEY=sk-...
+
+# Method 2: Saved config (recommended — survives shell restarts)
+codewhale auth set --provider deepseek --api-key sk-...
+
+# Method 3: config.toml
+# Add to ~/.deepseek/config.toml:
+api_key = "sk-..."
+
+# Check what's active:
+codewhale auth status    # shows config, keyring, and env-var state
+codewhale doctor         # full connectivity check`}
+
+

+ Saved config keys take precedence over environment variables. + Use codewhale auth clear --provider deepseek to remove a saved key. +

+ + ), + sources: ["#907", "#1545", "docs/CONFIGURATION.md"], + }, + { + q: "Which providers does CodeWhale support?", + a: ( + <> +

CodeWhale ships with these built-in providers:

+ +

+ Set the corresponding env var (e.g. OPENROUTER_API_KEY) and your provider in ~/.deepseek/config.toml. + Hugging Face, ZenMux, and self-hosted OpenAI-compatible endpoints are on the roadmap. +

+ + ), + sources: ["docs/CONFIGURATION.md", "#1978", "#1710"], + }, + { + q: "How do I use OpenRouter with CodeWhale?", + a: ( + <> + 
+{`# 1. Set your OpenRouter key
+export OPENROUTER_API_KEY=sk-or-v1-...
+
+# 2. In ~/.deepseek/config.toml:
+[providers.openrouter]
+api_key = "sk-or-v1-..."
+
+# 3. Run with an OpenRouter model:
+codewhale --model openrouter/deepseek/deepseek-v4-pro
+
+# Or set it as default in config.toml:
+default_text_model = "openrouter/deepseek/deepseek-v4-pro"`}
+
+

+ OpenRouter uses the same reasoning/cache parser as the native DeepSeek provider. + Model IDs follow the provider/model-id pattern (e.g. openrouter/deepseek/deepseek-v4-flash). +

+ + ), + sources: ["docs/CONFIGURATION.md", "#1978"], + }, + { + q: "Can I use self-hosted or local models (vLLM, Ollama, llama.cpp)?", + a: ( + <> + Yes. Use the vllm, sglang, or ollama providers with your local endpoint. + For OpenAI-compatible endpoints (llama.cpp server, text-generation-webui, Aphrodite, etc.), you can use the openai provider with a custom base_url. + CodeWhale also respects DEEPSEEK_ALLOW_INSECURE_HTTP=true for local HTTP endpoints. + Full Hugging Face TGI/vLLM integration is on the roadmap. + + ), + sources: ["#574", "#1303", "docs/CONFIGURATION.md"], + }, + { + q: "What are Plan, Agent, and YOLO modes?", + a: ( + <> + +

+ Press Tab to cycle modes. + Approval mode (suggest / auto / never) is orthogonal — you can be in Agent mode with auto-approval, for example. +

+ + ), + sources: ["docs/MODES.md"], + }, + { + q: "What is model auto-routing? What is Fin?", + a: ( + <> +

+ Use codewhale --model auto or /model auto to let CodeWhale decide how much model power each turn needs. +

+

+ Fin is the fast non-thinking path (deepseek-v4-flash with thinking off) used for routing decisions, summaries, RLM children, context maintenance, and other coordination work. Before the real turn is sent, Fin makes a small routing call to pick the concrete model and thinking level. +

+

+ Short/simple turns can stay on Flash with thinking off. Coding, debugging, release work, architecture, or security review can move up to Pro and/or higher thinking. Fin is local to CodeWhale — the upstream API never receives model: "auto". +

+ + ), + sources: ["README.md", "#1207"], + }, + { + q: "What is Goal mode? Is it available?", + a: ( + <> + Goal mode is a future workflow/tab direction for long-running, multi-step objectives — not the current /goal command. + The current /goal is a simple goal-setter. The full Goal mode (autonomous multi-turn task execution with checkpoint/resume) is planned but not yet implemented. + Track progress in #891. + + ), + sources: ["#891"], + }, + { + q: "Is my code safe? What sandboxing does CodeWhale use?", + a: ( + <> + CodeWhale runs entirely on your machine. No telemetry, no cloud processing of your code. + Sandbox backends: seatbelt (macOS), landlock (Linux), restricted tokens (Windows). + Workspace boundaries default to --workspace. /trust lifts them. + Approval mode is configurable per session. All credential/approval/elevation events are written to ~/.deepseek/audit.log. + + ), + sources: ["SECURITY.md", "docs/ARCHITECTURE.md"], + }, + { + q: "How do MCP servers work?", + a: ( + <> + CodeWhale is a bidirectional MCP client and server. Define servers in ~/.deepseek/mcp.json. + Tools appear as mcp_<server>_<tool>. You can also expose CodeWhale as an MCP server with codewhale mcp. + See the docs page for configuration examples. + + ), + sources: ["docs/MCP.md"], + }, + { + q: "How do I contribute?", + a: ( + <> + No CLA required. Fork, branch with conventional commits (feat:, fix:, etc.), run the local checks, open a PR. + The maintainer reads everything personally. Start with issues labeled good first issue. + See the contribute page and CONTRIBUTING.md. + + ), + sources: ["CONTRIBUTING.md"], + }, + { + q: "I'm in China — how do I install? Downloads are slow.", + a: ( + <> + Use mirror registries: + 
+{`# npm mirror
+npm config set registry https://registry.npmmirror.com
+npm install -g codewhale
+
+# Cargo mirror (Tsinghua TUNA)
+# Add to ~/.cargo/config.toml:
+[source.crates-io]
+replace-with = "tuna"
+[source.tuna]
+registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"`}
+
+

+ Prebuilt binaries are also available from GitHub Releases. + The Gitee mirror and CNB mirror may also be available. +

+ + ), + sources: ["README.md", "#1914", "docs/CNB_MIRROR.md"], + }, + { + q: "My API key was rejected or I get auth errors on first run.", + a: ( + <> +

Run codewhale doctor — it checks API key, network, sandbox, and MCP servers. Full report is written to ~/.deepseek/doctor.log.

+

Common causes:

+ + + ), + sources: ["#907", "#1545"], + }, + { + q: "What is Model Lab? When will Hugging Face integration be available?", + a: ( + <> + Model Lab is the planned open-model infrastructure layer: Hugging Face Hub API for model discovery, model cards, datasets, safetensors adapters, inference providers, and Jobs. + It is NOT fully implemented. Track progress in #1977. + Currently, you can use Hugging Face models through the OpenRouter provider or self-hosted endpoints. + + ), + sources: ["#1977", "docs/MODEL_LAB.md"], + }, + { + q: "Why is token consumption so high? / Why is cache hit rate low?", + a: ( + <> + CodeWhale sends substantial context (system prompt, project instructions, tool definitions) with each turn. + DeepSeek's prefix cache is used aggressively — the system prompt is layered to maximize cache hits. + If you see high token usage, check: are you using deepseek-v4-pro for simple queries better suited to Flash? + Model auto-routing (Fin) can help pick the right model per turn. + Cache hit rate depends on prompt stability — modifying the system prompt or switching models resets the cache. + + ), + sources: ["#1177", "#1818", "#743"], + }, + { + q: "How do I update CodeWhale?", + a: ( + <> + 
+{`# Release-binary updater (works for npm/release-binary installs)
+codewhale update
+
+# npm
+npm install -g codewhale@latest
+
+# Cargo
+cargo install codewhale-cli --locked --force
+
+# Homebrew
+brew update && brew upgrade deepseek-tui`}
+
+

+ If you installed via npm, codewhale update downloads the latest release binaries. + If a mirror is lagging, download directly from GitHub Releases. +

+ + ), + sources: ["README.md", "#1869", "#1914"], + }, +]; + +const faqZh: FaqItem[] = [ + { + q: "CodeWhale 是什么？", + a: ( + <> + CodeWhale 是一个面向开源模型的终端原生编程智能体。通过 codewhale 命令启动，流式输出推理块，在有审批门槛的情况下编辑本地工作区，并可为每个回合自动选择最合适的模型和推理深度。DeepSeek V4 是一级模型路径；OpenRouter 已就绪。Hugging Face、自托管等开放模型接口已在路线图中。 + + ), + sources: ["README.md", "docs/ARCHITECTURE.md"], + }, + { + q: "如何安装 CodeWhale？", + a: ( + <> +

四种方式，殊途同归：

+ 
+{`# npm（推荐 — 无需 Rust 工具链）
+npm install -g codewhale
+
+# Cargo（需要 Rust 1.88+）
+cargo install codewhale-cli --locked
+
+# Homebrew（macOS）
+brew tap Hmbown/deepseek-tui && brew install deepseek-tui
+
+# 直接下载
+# https://github.com/Hmbown/CodeWhale/releases`}
+
+

+ 输入 codewhale 即可启动。首次运行会自动创建 ~/.deepseek/。 + 查看 完整安装指南 了解国内镜像、Docker 和故障排除。 +

+ + ), + sources: ["README.md", "#1860", "#1914"], + }, + { + q: "codewhale 和 codewhale-tui 有什么区别？", + a: ( + <> + codewhale 是调度 CLI——管理配置、认证、更新，并启动 TUI。 + codewhale-tui 是运行智能体循环的终端 UI 二进制文件。 + 当你输入 codewhale 时，调度器会自动为你启动 codewhale-tui。 + 两者同时安装；通常你不需要关心这个区别。 + + ), + sources: ["README.md"], + }, + { + q: "CodeWhale 和 DeepSeek TUI 是什么关系？改名是怎么回事？", + a: ( + <> + CodeWhale 是 DeepSeek TUI 的新名称。当前的主命令是 codewhale。旧的 deepseek 和 deepseek-tui 命令作为兼容垫片继续有效。 + 配置仍然存放在 ~/.deepseek/。DEEPSEEK_* 环境变量继续有效。 + DeepSeek 并未被弃用。改名是为了体现 CodeWhale 更广泛的使命——成为面向所有提供商的开放模型智能体终端，而非弱化 DeepSeek 的地位。 + + ), + sources: ["docs/REBRAND.md", "README.md"], + }, + { + q: "如何设置 API 密钥？", + a: ( + <> + 
+{`# 方法 1：环境变量
+export DEEPSEEK_API_KEY=sk-...
+
+# 方法 2：保存在配置中（推荐 — 重启 Shell 后仍然有效）
+codewhale auth set --provider deepseek --api-key sk-...
+
+# 方法 3：config.toml
+# 在 ~/.deepseek/config.toml 中添加：
+api_key = "sk-..."
+
+# 查看当前状态：
+codewhale auth status    # 显示配置、密钥环和环境变量状态
+codewhale doctor         # 完整连接检查`}
+
+

+ 配置中保存的密钥优先于环境变量。 + 使用 codewhale auth clear --provider deepseek 移除已保存的密钥。 +

+ + ), + sources: ["#907", "#1545", "docs/CONFIGURATION.md"], + }, + { + q: "CodeWhale 支持哪些提供商？", + a: ( + <> +

CodeWhale 内建以下提供商：

+ +

+ 设置对应的环境变量（如 OPENROUTER_API_KEY）并在 ~/.deepseek/config.toml 中配置你的提供商。 + Hugging Face、ZenMux 和自托管 OpenAI 兼容端点正在路线图中。 +

+ + ), + sources: ["docs/CONFIGURATION.md", "#1978", "#1710"], + }, + { + q: "如何使用 OpenRouter？", + a: ( + <> + 
+{`# 1. 设置 OpenRouter 密钥
+export OPENROUTER_API_KEY=sk-or-v1-...
+
+# 2. 在 ~/.deepseek/config.toml 中：
+[providers.openrouter]
+api_key = "sk-or-v1-..."
+
+# 3. 使用 OpenRouter 模型运行：
+codewhale --model openrouter/deepseek/deepseek-v4-pro
+
+# 或在 config.toml 中设为默认：
+default_text_model = "openrouter/deepseek/deepseek-v4-pro"`}
+
+

+ OpenRouter 使用与原生 DeepSeek 提供商相同的推理/缓存解析器。 + 模型 ID 遵循 provider/model-id 格式（如 openrouter/deepseek/deepseek-v4-flash）。 +

+ + ), + sources: ["docs/CONFIGURATION.md", "#1978"], + }, + { + q: "可以使用自托管或本地模型吗（vLLM、Ollama、llama.cpp）？", + a: ( + <> + 可以。使用 vllm、sglang 或 ollama 提供商连接本地端点。 + 对于 OpenAI 兼容端点（llama.cpp server、text-generation-webui 等），可以使用 openai 提供商并设置自定义 base_url。 + CodeWhale 也支持 DEEPSEEK_ALLOW_INSECURE_HTTP=true 用于本地 HTTP 端点。 + 完整的 Hugging Face TGI/vLLM 集成正在路线图中。 + + ), + sources: ["#574", "#1303", "docs/CONFIGURATION.md"], + }, + { + q: "Plan、Agent、YOLO 三种模式有什么区别？", + a: ( + <> + +

+ 按 Tab 切换模式。 + 审批模式（建议 / 自动 / 拒绝）是独立的——例如你可以在 Agent 模式下使用自动审批。 +

+ + ), + sources: ["docs/MODES.md"], + }, + { + q: "什么是模型自动路由？Fin 是什么？", + a: ( + <> +

+ 使用 codewhale --model auto 或 /model auto 让 CodeWhale 为每个回合自动选择最合适的模型和推理深度。 +

+

+ Fin 是快速非推理路径（deepseek-v4-flash，推理关闭），用于路由决策、摘要、RLM 子任务、上下文维护等协调工作。在真实请求发送前，Fin 会做一个小的路由调用来选择具体的模型和推理级别。 +

+

+ 简短简单的请求可以留在 Flash + 推理关闭的状态。编码、调试、发布工作、架构设计或安全审查则会提升到 Pro 和/或更高的推理级别。Fin 是 CodeWhale 本地逻辑——上游 API 永远不会收到 model: "auto"。 +

+ + ), + sources: ["README.md", "#1207"], + }, + { + q: "什么是 Goal 模式？现在可用吗？", + a: ( + <> + Goal 模式是未来的工作流/标签页方向，用于长时间运行的多步目标——不是当前的 /goal 命令。 + 当前的 /goal 是一个简单的目标设置器。完整的 Goal 模式（自主多回合任务执行，支持检查点/恢复）已规划但尚未实现。 + 关注 #891 的进展。 + + ), + sources: ["#891"], + }, + { + q: "我的代码安全吗？CodeWhale 使用什么沙箱机制？", + a: ( + <> + CodeWhale 完全在你的机器上运行。无遥测，不会将你的代码上传到云端处理。 + 沙箱后端：seatbelt（macOS）、landlock（Linux）、受限令牌（Windows）。 + 工作区边界默认为 --workspace。/trust 可解除边界。 + 审批模式可按会话配置。所有凭证/审批/提权事件写入 ~/.deepseek/audit.log。 + + ), + sources: ["SECURITY.md", "docs/ARCHITECTURE.md"], + }, + { + q: "MCP 服务器如何工作？", + a: ( + <> + CodeWhale 是双向 MCP 客户端和服务器。在 ~/.deepseek/mcp.json 中定义服务器。 + 工具以 mcp_<server>_<tool> 形式呈现。你也可以通过 codewhale mcp 将 CodeWhale 暴露为 MCP 服务器。 + 查看 文档页面 了解配置示例。 + + ), + sources: ["docs/MCP.md"], + }, + { + q: "如何参与贡献？", + a: ( + <> + 无需签署 CLA。Fork、用约定式提交（feat:、fix: 等）创建分支、通过本地检查、提交 PR。 + 维护者亲自阅读每一条内容。从标记为 good first issue 的议题开始。 + 查看 贡献页面 和 CONTRIBUTING.md。 + + ), + sources: ["CONTRIBUTING.md"], + }, + { + q: "我在国内，安装很慢怎么办？", + a: ( + <> + 使用镜像源： + 
+{`# npm 镜像
+npm config set registry https://registry.npmmirror.com
+npm install -g codewhale
+
+# Cargo 镜像（清华 TUNA）
+# 在 ~/.cargo/config.toml 中添加：
+[source.crates-io]
+replace-with = "tuna"
+[source.tuna]
+registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"`}
+
+

+ 也可以从 GitHub Releases 直接下载预编译二进制。 + Gitee 镜像和 CNB 镜像也可能可用。 +

+ + ), + sources: ["README.md", "#1914", "docs/CNB_MIRROR.md"], + }, + { + q: "首次运行时提示 API 密钥被拒绝或认证错误？", + a: ( + <> +

运行 codewhale doctor——它会检查 API 密钥、网络、沙箱和 MCP 服务器。完整报告写入 ~/.deepseek/doctor.log。

+

常见原因：

+ + + ), + sources: ["#907", "#1545"], + }, + { + q: "Model Lab 是什么？Hugging Face 集成什么时候可用？", + a: ( + <> + Model Lab 是规划中的开放模型基础设施层：Hugging Face Hub API 用于模型发现、模型卡片、数据集、safetensors 适配器、推理提供商和 Jobs。 + 它尚未完全实现。关注 #1977 的进展。 + 目前，你可以通过 OpenRouter 提供商或自托管端点使用 Hugging Face 模型。 + + ), + sources: ["#1977", "docs/MODEL_LAB.md"], + }, + { + q: "为什么 token 消耗这么大？/ 缓存命中率为什么低？", + a: ( + <> + CodeWhale 每次请求都会发送大量上下文（系统提示、项目说明、工具定义）。 + DeepSeek 的前缀缓存被积极使用——系统提示按最稳定的层级排列以最大化缓存命中。 + 如果你发现 token 使用量很高，请检查：是否在简单查询中使用了 deepseek-v4-pro（更适合用 Flash）？ + 模型自动路由（Fin）可以帮助为每个回合选择合适的模型。 + 缓存命中率取决于提示的稳定性——修改系统提示或切换模型会重置缓存。 + + ), + sources: ["#1177", "#1818", "#743"], + }, + { + q: "如何更新 CodeWhale？", + a: ( + <> + 
+{`# 发布二进制更新器（适用于 npm/二进制安装）
+codewhale update
+
+# npm
+npm install -g codewhale@latest
+
+# Cargo
+cargo install codewhale-cli --locked --force
+
+# Homebrew
+brew update && brew upgrade deepseek-tui`}
+
+

+ 如果通过 npm 安装，codewhale update 会下载最新发布二进制。 + 如果镜像延迟，请从 GitHub Releases 直接下载。 +

+ + ), + sources: ["README.md", "#1869", "#1914"], + }, +]; + +export default async function FaqPage({ params }: { params: Promise<{ locale: string }> }) { + const { locale } = await params; + const isZh = locale === "zh"; + const items = isZh ? faqZh : faqEn; + + return ( + <> +
+
+ +
{isZh ? "常见问题" : "FAQ"}
+
+

+ {isZh ? ( + <>常见问题 FAQ + ) : ( + <>FAQ 常见问题 + )} +

+

+ {isZh + ? "答案来自实际代码、文档、发布说明和 GitHub 议题。每个回答下方标注了信息来源。如有未覆盖的问题，请在 GitHub 上提交 Issue。" + : "Answers sourced from real code, docs, release notes, and GitHub issues. Sources are cited below each answer. If your question isn't covered, open an issue on GitHub."} +

+
+ +
+
+ {items.map((item, i) => ( +
+ + + {String(i + 1).padStart(2, "0")} + + {item.q} + + + +
+
+ {item.a} +
+ {item.sources && item.sources.length > 0 && ( +
+ + {isZh ? "来源" : "Sources"}: + + {item.sources.map((s) => ( + {s} + ))} +
+ )} +
+
+ ))} +
+ +
+

+ {isZh + ? "没找到你的问题？" + : "Didn't find your question?"} +

+ + {isZh ? "提交 Issue →" : "Open an issue →"} + +
+
+ + ); +}