feat: CLI Tools — curated tool catalog, detection, install, chat awareness

New sidebar page for managing system CLI tools (ffmpeg, jq, ripgrep, yt-dlp, pandoc).

Core modules:
- cli-tools-catalog.ts: static catalog of 6 curated tools + EXTRA_WELL_KNOWN_BINS
- cli-tools-detect.ts: system detection via which/where + --version (2min cache)
- cli-tools-context.ts: builds <available_cli_tools> block for chat system prompt

API routes:
- GET /api/cli-tools/catalog, /installed, /[id]/status, /[id]/detail
- POST /api/cli-tools/[id]/install (SSE streaming), /[id]/describe (AI gen)

UI components:
- CliToolsManager: installed + recommended sections with grid layout
- CliToolCard: two variants (installed/recommended) with status badges
- CliToolDetailDialog: intro, use cases, guide steps, example prompts
- CliToolInstallDialog: SSE-based install progress with live terminal log

Chat integration:
- Chat input toolbar: Terminal icon opens CLI tool picker popover
- System prompt injection: buildCliToolsContext() in /api/chat
- MessageInput: CLI popover with search, keyboard nav, locale-aware prefill
- NavRail + ChatListPanel: frosted glass (bg-sidebar/80 backdrop-blur-xl)
- SlashCommandButton: Lightning icon, unified 16px toolbar icons
- input-group: shadow-md → shadow-sm
- Model selector: searchable popover with provider grouping

Docs:
- docs/handover/cli-tools.md + apps/site/content/docs/{en,zh}/cli-tools.mdx

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 7418

apps/site/content/docs/en/cli-tools.mdx

@@ -0,0 +1,109 @@
+---
+title: CLI Tools
+description: Manage system CLI tools so Claude can automatically detect and use command-line capabilities on your machine.
+---
+
+# CLI Tools
+
+Many AI workflows require command-line tools — FFmpeg for video processing, jq for JSON parsing, ripgrep for code search. CodePilot's CLI Tools feature helps you manage these tools and lets Claude automatically know what's available on your machine.
+
+## Why This Matters
+
+When you tell Claude "convert this video to MP4," it needs to know whether FFmpeg is installed on your system. Without that knowledge, it can only offer generic advice. With it, Claude can give you a ready-to-run command.
+
+The CLI Tools feature does three things:
+
+1. **Detect** — Automatically scans your system for installed command-line tools
+2. **Recommend** — Offers a curated list of useful tools with one-click installation
+3. **Awareness** — Automatically tells Claude what tools you have during conversations, so it gives more precise answers
+
+## Opening the Tool Manager
+
+Click the **CLI Tools** icon (terminal icon) in the left navigation rail.
+
+The page has two sections:
+
+- **Installed** — Tools detected on your system, showing version and status
+- **Recommended** — Curated tools commonly used in AI workflows, ready to install
+
+## Installing Tools
+
+Find the tool you need in the Recommended section and click **Install**.
+
+If a tool supports multiple installation methods (e.g., Homebrew, npm), you'll be asked to choose. The installation progress shows real-time terminal output so you can see exactly what's happening.
+
+Currently recommended tools:
+
+| Tool | Purpose | Install via |
+|------|---------|------------|
+| FFmpeg | Audio/video transcoding, trimming, merging | Homebrew |
+| jq | JSON data parsing and transformation | Homebrew |
+| ripgrep | Ultra-fast text search (much faster than grep) | Homebrew |
+| yt-dlp | Video downloading | Homebrew / pipx |
+| pandoc | Document format conversion (Markdown, Word, PDF) | Homebrew |
+
+## Viewing Tool Details
+
+Click the **Details** button on a tool card to see:
+
+- **Introduction** — What the tool does
+- **Use Cases** — Most common scenarios
+- **Setup Guide** — Steps from installation to first use
+- **Example Prompts** — Ready-to-use prompts you can copy into a conversation
+
+Example prompts are the most practical part. For FFmpeg, you might see:
+
+> "Convert input.mov to MP4 format, keeping original quality"
+
+Click the copy button or "Send to Chat" to start a conversation with that prompt immediately.
+
+## AI-Enhanced Descriptions
+
+Installed tools support AI-generated detailed descriptions. Click the **Auto Describe** button on a tool card, and Claude will generate a bilingual description based on the tool's name and capabilities.
+
+The description is saved locally and will persist across sessions.
+
+## Using Tools in Conversations
+
+### Automatic Awareness (Recommended)
+
+After installing tools, you don't need to do anything extra. CodePilot automatically detects your installed tools before each conversation and includes them in the system prompt.
+
+This means when you say:
+
+> "Convert all .mov files in this directory to .mp4"
+
+Claude knows you have FFmpeg and gives you a ready-to-run command, instead of first asking "Do you have FFmpeg installed?"
+
+### Manual Tool Selection
+
+If you want to explicitly tell Claude to use a specific tool, click the **terminal icon** in the chat input toolbar to open the CLI tool picker.
+
+After selecting a tool:
+
+- If the input is empty, it auto-fills a guide phrase like "I want to use FFmpeg to: " — just add your specific request
+- If there's already text in the input, a tool badge is attached to the message, and Claude will prioritize that tool in its response
+
+## Best Practices
+
+### Describe the Goal, Not the Command
+
+Less effective:
+> "Run ffmpeg -i input.mov -c:v libx264 output.mp4"
+
+More effective:
+> "Convert input.mov to MP4, keep the quality, minimize file size"
+
+Let Claude choose the optimal parameters. It knows FFmpeg's encoding options better than most people.
+
+### Combine Multiple Tools
+
+CLI tools work great together. For example:
+
+> "Download the video from this YouTube link, trim the first 30 seconds, and convert to GIF"
+
+If you have yt-dlp and FFmpeg installed, Claude will chain them together into a complete workflow.
+
+### Start with Example Prompts
+
+Not sure how to use a tool? Open its detail page and start with the example prompts. They cover the most common use cases and are the fastest way to get started.

apps/site/content/docs/en/meta.json

@@ -8,6 +8,7 @@
     "providers",
     "mcp",
     "skills",
+    "cli-tools",
     "bridge",
     "assistant-workspace",
     "design-agent",

apps/site/content/docs/zh/cli-tools.mdx

@@ -0,0 +1,109 @@
+---
+title: CLI 工具
+description: 管理系统 CLI 工具，让 Claude 自动识别并使用你电脑上的命令行能力。
+---
+
+# CLI 工具
+
+很多 AI 工作流需要配合命令行工具——用 FFmpeg 处理视频、用 jq 解析 JSON、用 ripgrep 搜索代码。CodePilot 的 CLI 工具功能帮你管理这些工具，并让 Claude 自动知道你的电脑上有什么可用。
+
+## 为什么需要这个功能？
+
+当你跟 Claude 说"帮我把这个视频转成 MP4"，Claude 需要知道你的系统上是否安装了 FFmpeg。如果不知道，它只能给出通用建议；如果知道，它可以直接给你一条可以执行的命令。
+
+CLI 工具功能做了三件事：
+
+1. **检测** — 自动扫描你系统上已安装的命令行工具
+2. **推荐** — 提供精选工具列表，一键安装
+3. **感知** — 在对话中自动告诉 Claude 你有哪些工具，让它给出更精准的回答
+
+## 打开工具管理
+
+点击左侧导航栏的 **CLI Tools** 图标（终端图标）进入管理页面。
+
+页面分为两个区域：
+
+- **已安装** — 系统上检测到的工具，显示版本号和状态
+- **推荐** — 精选的常用 AI 工作流工具，可以直接安装
+
+## 安装工具
+
+在推荐区找到你需要的工具，点击 **安装** 按钮。
+
+如果工具支持多种安装方式（如 Homebrew、npm），会先让你选择。安装过程中会实时显示终端日志，你可以看到完整的安装输出。
+
+目前推荐的工具包括：
+
+| 工具 | 用途 | 安装方式 |
+|------|------|---------|
+| FFmpeg | 音视频转码、剪辑、合并 | Homebrew |
+| jq | JSON 数据解析和转换 | Homebrew |
+| ripgrep | 极速文本搜索（比 grep 快得多） | Homebrew |
+| yt-dlp | 视频下载 | Homebrew / pipx |
+| pandoc | 文档格式转换（Markdown、Word、PDF 互转） | Homebrew |
+
+## 查看工具详情
+
+点击工具卡片上的 **详情** 按钮，可以看到：
+
+- **工具简介** — 这个工具能做什么
+- **适用场景** — 最常见的使用方式
+- **操作引导** — 从安装到上手的步骤
+- **示例提示词** — 可以直接复制到对话中使用的提示词
+
+示例提示词是这个功能最实用的部分。比如 FFmpeg 的示例提示词：
+
+> "把 input.mov 转换成 MP4 格式，保持原始质量"
+
+点击旁边的复制按钮或"发送到聊天"按钮，就可以直接用这个提示词开始对话。
+
+## AI 自动完善介绍
+
+已安装的工具支持用 AI 生成更详细的介绍。点击工具卡片上的 **自动完善** 按钮，Claude 会根据工具的名称和用途生成一段中英双语的详细描述。
+
+这个描述会保存在本地，下次打开时自动显示。
+
+## 在对话中使用
+
+### 自动感知（推荐）
+
+安装好工具后，不需要做任何额外操作。CodePilot 会在每次对话时自动检测你的已安装工具，并在 system prompt 中告诉 Claude。
+
+这意味着当你说：
+
+> "帮我把这个目录下所有的 .mov 文件转成 .mp4"
+
+Claude 会知道你有 FFmpeg，直接给出可执行的命令，而不是先问你"是否安装了 FFmpeg"。
+
+### 手动选择工具
+
+如果你想明确告诉 Claude 使用某个特定工具，可以在聊天输入框的工具栏中点击 **终端图标**，打开 CLI 工具选择器。
+
+选择一个工具后：
+
+- 如果输入框为空，会自动预填一段引导文字，比如"我想用 FFmpeg 工具完成：" — 你只需补充具体需求
+- 如果输入框已有内容，会在消息上附加一个工具标记，Claude 会优先使用这个工具来回答
+
+## 最佳实践
+
+### 描述需求而不是命令
+
+不好的用法：
+> "运行 ffmpeg -i input.mov -c:v libx264 output.mp4"
+
+好的用法：
+> "把 input.mov 转成 MP4，画质保持不变，文件尽量小"
+
+让 Claude 来选择最优的参数组合。它比大多数人更了解 FFmpeg 的编码选项。
+
+### 组合多个工具
+
+CLI 工具之间可以组合使用。比如：
+
+> "从这个 YouTube 链接下载视频，然后裁剪前 30 秒，转成 GIF"
+
+如果你安装了 yt-dlp 和 FFmpeg，Claude 会把它们串联起来，给你一个完整的工作流。
+
+### 用示例提示词起步
+
+不确定怎么用一个工具？打开它的详情页，从示例提示词开始。这些提示词覆盖了最常见的使用场景，是快速上手的好方法。

apps/site/content/docs/zh/meta.json

@@ -8,6 +8,7 @@
     "providers",
     "mcp",
     "skills",
+    "cli-tools",
     "bridge",
     "assistant-workspace",
     "design-agent",

docs/handover/README.md

@@ -12,3 +12,4 @@
 | bridge-system.md | 多 IM 远程桥接系统架构（目录结构、数据流、设计决策） |
 | assistant-workspace.md | 助理工作区：人格/记忆文件、对话式引导、自动触发、确定性落盘 |
 | theme-system.md | 主题家族系统：两层架构、JSON schema、代码高亮三条渲染链、12 个主题清单 |
+| cli-tools.md | CLI 工具管理：静态 catalog、系统检测、一键安装、AI 描述、聊天上下文注入、输入框选择器 |

docs/handover/cli-tools.md

@@ -0,0 +1,139 @@
+# CLI Tools — 系统 CLI 工具管理与聊天感知
+
+## 核心思路
+
+AI 工作流中 CLI 工具（ffmpeg、jq、ripgrep 等）是重要基础设施，但用户往往不知道装什么、怎么装。本功能在侧边栏新增 "CLI Tools" 页面，提供精选工具推荐、一键安装、AI 补全描述，并在聊天时自动将已安装工具注入 system prompt，让 Claude 知道用户系统上有哪些工具可用。
+
+## 目录结构
+
+```
+src/lib/
+├── cli-tools-catalog.ts      # 静态精选 catalog（6 个核心 + EXTRA_WELL_KNOWN_BINS）
+├── cli-tools-detect.ts        # 系统检测逻辑（which/where + --version）
+├── cli-tools-context.ts       # 聊天上下文构建（system prompt 注入块）
+
+src/app/api/cli-tools/
+├── catalog/route.ts           # GET — 返回完整 catalog 列表
+├── installed/route.ts         # GET — 检测并返回已安装工具的 runtime info
+└── [id]/
+    ├── status/route.ts        # GET — 单个工具状态 + 版本
+    ├── install/route.ts       # POST — SSE 流式安装日志
+    ├── detail/route.ts        # GET — 详情弹窗数据
+    └── describe/route.ts      # POST — AI 生成双语工具描述
+
+src/components/cli-tools/
+├── CliToolsManager.tsx        # 主管理容器（已安装区 + 推荐区）
+├── CliToolCard.tsx            # 工具卡片（installed / recommended 两种 variant）
+├── CliToolDetailDialog.tsx    # 详情弹窗（简介 / 场景 / 引导 / 示例提示词）
+├── CliToolInstallDialog.tsx   # SSE 安装进度弹窗
+├── CliToolBatchDescribeDialog.tsx  # 批量 AI 描述生成
+└── CliToolExtraDetailDialog.tsx   # 额外检测工具的详情弹窗
+
+src/app/cli-tools/page.tsx     # 页面入口
+```
+
+## 数据流
+
+### 工具检测
+
+```
+页面加载 → CliToolsManager 并行请求:
+  GET /api/cli-tools/catalog    → CLI_TOOLS_CATALOG（静态数据）
+  GET /api/cli-tools/installed  → detectAllCliTools()
+    → 遍历 catalog binNames + EXTRA_WELL_KNOWN_BINS
+    → which/where 查找 → --version 提取版本
+    → 模块级缓存（TTL 2 分钟）
+→ 合并 catalog + runtime info → 分区渲染
+```
+
+### 工具安装
+
+```
+用户点击"安装" → 选择安装方式（brew/npm/pipx）
+  → POST /api/cli-tools/[id]/install { method }
+  → 服务端 spawn 子进程执行 catalog 中声明的 command
+  → SSE 流式返回 stdout/stderr
+  → CliToolInstallDialog 实时显示日志
+  → 完成后重新检测工具状态
+```
+
+安全约束：只执行 catalog 中声明的 command，不接受用户自定义命令。
+
+### AI 描述生成
+
+```
+用户点击"自动完善介绍" → POST /api/cli-tools/[id]/describe { providerId }
+  → 校验 tool.supportsAutoDescribe === true
+  → generateTextViaSdk() 生成中英双语介绍（60s 超时）
+  → 返回 { zh, en } 文本
+  → 前端存入 localStorage（key: cli-tool-desc-{id}）
+  → 刷新后从 localStorage 恢复
+```
+
+### 聊天上下文注入
+
+```
+用户发送消息 → POST /api/chat
+  → buildCliToolsContext()
+    → detectAllCliTools()（命中缓存则直接返回）
+    → 格式化已安装工具为 <available_cli_tools> XML 块
+    → 追加到 system prompt 末尾
+  → Claude 获知用户系统上可用的 CLI 工具
+```
+
+### 聊天侧 CLI 选择器
+
+```
+聊天输入框工具栏 → 点击 Terminal 图标 → popoverMode = 'cli'
+  → 异步 fetch /api/cli-tools/installed + /api/cli-tools/catalog
+  → 搜索框过滤 → 选择工具
+  → 若输入框为空：预填 "我想用 {tool} 工具完成：" (zh) / "I want to use {tool} to: " (en)
+  → 若输入框有内容：附加 CliBadge { id, name }
+  → 发送时 CliBadge → systemPromptAppend 注入到 system prompt（不显示在对话中）
+```
+
+## 类型定义
+
+关键类型在 `src/types/index.ts`：
+
+| 类型 | 用途 |
+|------|------|
+| `CliToolStatus` | `'not_installed' \| 'installed' \| 'needs_auth' \| 'ready'` |
+| `CliToolCategory` | `'media' \| 'data' \| 'search' \| 'download' \| 'document' \| 'productivity'` |
+| `InstallMethod` | `'brew' \| 'npm' \| 'pipx' \| 'cargo'` |
+| `CliToolDefinition` | 完整的工具定义（名称、binNames、摘要、分类、安装方式、详情、示例提示词） |
+| `CliToolRuntimeInfo` | 运行时检测结果（状态、版本、路径、AI 描述） |
+| `CliToolInstallMethod` | 包含 `method`、`command`、`platforms` |
+
+## 设计决策
+
+### 为什么用静态 catalog 而不是动态发现？
+
+安全性——只允许执行预审过的安装命令。可预测性——工具列表、描述、示例提示词都是策划过的内容，质量可控。
+
+### 为什么检测用 which 而不是直接运行？
+
+Electron 桌面环境中 PATH 往往不完整。通过 `getExpandedPath()`（`src/lib/platform.ts`）展开 `/usr/local/bin`、`~/.cargo/bin` 等常见路径后传给 `which`，兼容桌面和终端两种启动方式。
+
+### 为什么 AI 描述存 localStorage 而不是 DB？
+
+描述是锦上添花，不是核心数据。避免 schema 迁移负担，丢失可重新生成。
+
+### 聊天侧 CLI 选择器的 popover 模式
+
+采用 `PopoverMode = 'file' | 'skill' | 'cli' | null` 枚举，CLI 是 button-triggered（点击工具栏图标触发），与 skill 的 text-triggered（输入 `/` 触发）不同。button-triggered 弹窗的焦点策略是将焦点交给弹窗内的搜索框，而 text-triggered 弹窗焦点保留在 textarea。
+
+### EXTRA_WELL_KNOWN_BINS
+
+除 catalog 中的 6 个精选工具外，`cli-tools-catalog.ts` 还导出 `EXTRA_WELL_KNOWN_BINS` 数组——常见但不需要详情页的工具（如 python、node、go、docker 等），用于聊天上下文注入，让 Claude 知道系统上还有哪些工具。
+
+## 修改文件清单
+
+| 文件 | 改动 |
+|------|------|
+| `src/types/index.ts` | 新增 CLI tool 相关类型定义 |
+| `src/components/layout/NavRail.tsx` | navItems 增加 CLI Tools 导航项 |
+| `src/i18n/en.ts` | 新增 `nav.cliTools` + `cli_tools.*` 英文 key |
+| `src/i18n/zh.ts` | 新增 `nav.cliTools` + `cli_tools.*` 中文 key |
+| `src/app/api/chat/route.ts` | system prompt 末尾追加 CLI tools context |
+| `src/components/chat/MessageInput.tsx` | CLI 选择器弹窗 + CliBadge + systemPromptAppend |

src/__tests__/unit/provider-resolver.test.ts

@@ -479,7 +479,7 @@ describe('Provider Resolver', () => {
       const config = toAiSdkConfig(resolved);
       assert.equal(config.sdkType, 'anthropic');
       assert.equal(config.apiKey, 'key');
-      assert.equal(config.baseUrl, 'https://api.anthropic.com');
+      assert.equal(config.baseUrl, 'https://api.anthropic.com/v1');
       assert.equal(config.modelId, 'sonnet');
       assert.deepEqual(config.processEnvInjections, {});
     });