# https://github.com/lessweb/deepcode-cli 项目说明书

生成时间：2026-07-07 16:17:25 UTC

## 目录

- [项目概览与快速开始](#page-overview)
- [核心架构、会话管理与工具系统](#page-architecture)
- [TUI 界面、Slash 命令与键盘交互](#page-ui)
- [扩展生态：MCP、Agent Skills、插件与 VSCode 伴生插件](#page-extensibility)

<a id='page-overview'></a>

## 项目概览与快速开始

### 相关页面

相关主题：[核心架构、会话管理与工具系统](#page-architecture), [TUI 界面、Slash 命令与键盘交互](#page-ui)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/lessweb/deepcode-cli/blob/main/README.md)
- [README-zh_CN.md](https://github.com/lessweb/deepcode-cli/blob/main/README-zh_CN.md)
- [README-en.md](https://github.com/lessweb/deepcode-cli/blob/main/README-en.md)
- [docs/quickstart.md](https://github.com/lessweb/deepcode-cli/blob/main/docs/quickstart.md)
- [docs/configuration.md](https://github.com/lessweb/deepcode-cli/blob/main/docs/configuration.md)
- [.env.example](https://github.com/lessweb/deepcode-cli/blob/main/.env.example)
</details>

# 项目概览与快速开始

## 项目简介

DeepCode CLI（仓库名 `lessweb/deepcode-cli`）是一款面向研发场景的**终端 AI 编程助手**，采用 TypeScript 编写并基于 Ink 框架渲染交互式 TUI。它以 OpenAI 兼容协议接入多种大模型（默认适配 deepseek-v4 系列），并在本地提供代码编辑、文件读取、Shell 执行、会话持久化、Skills 系统与 MCP（Model Context Protocol）服务器管理等能力。资料来源：[README.md:1-40]()

相较于 Web IDE 中的 Copilot 类工具，DeepCode CLI 的核心差异在于：

- **全本地执行**：所有文件操作、Shell 命令、Git 变更均在用户终端完成，不上传代码到远端训练链路。
- **可扩展协议层**：通过 MCP 服务器接入第三方工具（如代码检索、数据库、CI）。
- **可控的推理参数**：在 `settings.json` 中暴露 `thinkingEnabled`、`reasoningEffort`、`temperature` 等字段，支持按需切换深度思考强度。
- **会话与技能复用**：支持会话（session）命名与编辑、内置技能（skill）按需启用。

## 核心特性一览

| 模块 | 关键能力 | 相关 Issue / Release |
|------|---------|----------------------|
| 模型接入 | OpenAI 兼容协议、思考模式、`reasoningEffort` 可调 | 社区请求 `/model` 多 profile 切换 (#204) |
| TUI 输入 | CJK 兼容、大段粘贴折叠、`Ctrl+R` raw 模式 | v0.1.25、v0.1.29 |
| 会话系统 | 持久化、重命名、OpenAI 消息转换拆分 | v0.1.26、v0.1.28 |
| 工具执行 | Bash 超时（默认 10 分钟）、Windows 进程组修复 | v0.1.23、v0.1.30 |
| MCP | 手动重连、Windows 双引号修复 | v0.1.24、v0.1.30 |
| Hook / Notify | `STATUS/FAIL_REASON/BODY/TITLE` 透传环境变量 | v0.1.23 |
| Skills | 内置 bundle、`enabledSkills` 配置项 | v0.1.29 |

社区对 token 用量与上下文的可视化有强烈呼声，相关 `/tokens` `//context` `/cost` 命令已被列入待办（#222、#223、#224），目前 `SessionManager` 内部已经记录 token 统计，但尚未暴露到 TUI。资料来源：[README-zh_CN.md:12-58]()

## 快速开始

### 环境要求

- Node.js ≥ 18（推荐 LTS），包管理器支持 npm / pnpm / yarn。
- 任意主流终端（iTerm2、Windows Terminal、VSCode Integrated Terminal 均可）。
- 注意：当前 `cli.tsx:73` 强制 `process.stdin.isTTY`，因此**必须运行在交互式终端**中。社区在 #139 提出了 headless 模式请求，计划用于 CI/CD，但截至 v0.1.31 尚未合并。

### 安装与启动

```bash
# 克隆仓库
git clone https://github.com/lessweb/deepcode-cli.git
cd deepcode-cli

# 安装依赖（推荐 pnpm）
pnpm install

# 复制环境变量模板并填写 API Key
cp .env.example .env
# 编辑 .env，至少设置 OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL

# 启动开发模式
pnpm dev
# 或构建后运行
pnpm build && pnpm start
```

资料来源：[docs/quickstart.md:1-80]()、[README.md:20-45]()

### 第一次交互

启动后 TUI 会进入主聊天界面。常用基础操作：

- **输入自然语言需求**：直接键入需求并回车，例如「帮我重构 `src/utils` 下的文件」。
- **斜杠命令**：以 `/` 开头的命令用于系统级操作，如 `/help`、`/raw`（v0.1.23 引入的 raw 终端直出）、`/model`（社区请求 #204 中期望的模型切换）。
- **快捷键**：`Ctrl+R` 切换 raw 模式，`Ctrl+O` 查看后台进程 stdout（v0.1.22 引入）。
- **工具调用**：模型可调用 Bash、Edit、Read、Write 等内置工具；Bash 工具默认 10 分钟超时，可通过 `Ctrl+O` 面板调整（v0.1.23 修复 Windows 进程组杀进程问题）。

## 配置与环境

### 环境变量（`.env`）

`.env.example` 中提供了常用变量，核心字段：

- `OPENAI_API_KEY`：模型服务密钥。
- `OPENAI_BASE_URL`：OpenAI 兼容端点，例如 DeepSeek、火山方舟等。
- `OPENAI_MODEL`：默认模型标识，例如 `deepseek-v4-pro`。
- 其余可选字段通常包含日志级别、超时、MCP 透传等。

### `settings.json`

项目级与用户级 `settings.json` 用于控制行为。典型片段：

```json
{
  "model": "deepseek-v4-pro",
  "thinkingEnabled": true,
  "reasoningEffort": "max",
  "temperature": 0,
  "enabledSkills": ["plan-mode", "deepcode-self-refer", "skill-digester"]
}
```

- `enabledSkills`：v0.1.29 起支持，控制哪些内置 Skill 被加载。
- `reasoningEffort` / `thinkingEnabled`：直接驱动推理强度，社区在 #204 中建议扩展为多 profile，便于 `/model` 快速切换。
- 模型字段为单一对象，未来计划支持 `profiles` 数组以做模型切换（issue #204）。

资料来源：[docs/configuration.md:1-120]()、[README-en.md:30-60]()

### Skills 与 MCP

- **Skills**：内置技能通过 bundle 形式分发（v0.1.29），可在 `~/.deepcode/skills/` 或仓库内的 `skills/` 目录扩展。
- **MCP 服务器**：通过 `mcpServers` 字段声明，支持 stdio 传输。v0.1.30 修复了 Windows 下命令双引号导致 MCP 全挂的回归（PR #164）。

## 常见使用场景与社区关注点

1. **深度编码任务**：启用 `thinkingEnabled` 与 `reasoningEffort: "max"`，让模型在多轮 Bash/Edit 中自主完成重构。资料来源：[README-zh_CN.md:40-55]()
2. **会话沉淀**：每条会话会自动持久化，可在 `docs/session-persistence.md` 查看路径与 schema；v0.1.28 起支持重命名。
3. **跨平台使用**：iOS 终端 CJK 输入的合成回退问题已在 v0.1.24 修复（PR #94），Windows 的 Bash 进程组杀进程与 MCP 引号问题分别在 v0.1.23、v0.1.30 修复。
4. **待加入的能力**：subAgent（#154）、远程控制（#187）、headless 模式（#139）、token / context 可视化（#222、#223、#224）、多模型 profile 切换（#204）等仍是社区高频请求，可关注后续 release notes 跟进。

---

<a id='page-architecture'></a>

## 核心架构、会话管理与工具系统

### 相关页面

相关主题：[项目概览与快速开始](#page-overview), [TUI 界面、Slash 命令与键盘交互](#page-ui), [扩展生态：MCP、Agent Skills、插件与 VSCode 伴生插件](#page-extensibility)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/lessweb/deepcode-cli/blob/main/package.json)
- [cli.tsx](https://github.com/lessweb/deepcode-cli/blob/main/cli.tsx)
- [packages/core/src/session.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/session.ts)
- [packages/core/src/openai-client.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/openai-client.ts)
- [packages/core/src/common/openai-message-converter.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/common/openai-message-converter.ts)
- [packages/core/src/common/openai-thinking.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/common/openai-thinking.ts)
- [packages/core/src/tools/executor.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/tools/executor.ts)
- [packages/core/src/tools/bash.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/tools/bash.ts)
- [packages/core/src/tools/edit.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/tools/edit.ts)
- [packages/core/src/mcp/](https://github.com/lessweb/deepcode-cli/tree/main/packages/core/src/mcp)
- [packages/core/src/skills/](https://github.com/lessweb/deepcode-cli/tree/main/packages/core/src/skills)
- [docs/session-persistence.md](https://github.com/lessweb/deepcode-cli/blob/main/docs/session-persistence.md)

</details>

# 核心架构、会话管理与工具系统

## 1. 整体架构概览

DeepCode CLI 是基于 TypeScript 与 Ink（React-for-terminal）的交互式编码助手，运行在本地终端，通过 OpenAI 兼容协议接入 LLM，并在本地编排工具调用、Skills 与状态持久化。代码按 monorepo 组织，`packages/core` 承载业务核心，`cli.tsx` 作为 TUI 入口。

主要模块职责：

- **入口与 TTY 检测**：`cli.tsx` 解析启动参数、校验 `process.stdin.isTTY`、挂载 React 渲染树 资料来源：[cli.tsx:73-100]()
- **LLM 客户端**：`openai-client.ts` 复用单一 OpenAI 实例，配置 `undici` keep-alive Agent 并在启动时进行连接预热 资料来源：[packages/core/src/openai-client.ts:1-90]()
- **会话状态**：`session.ts` 管理消息历史、token 累计、模型配置与会话元数据 资料来源：[packages/core/src/session.ts:1-80]()
- **消息转换**：`openai-message-converter.ts` 负责内部消息与 OpenAI 协议互转 资料来源：[packages/core/src/common/openai-message-converter.ts:1-60]()
- **思考与推理**：`openai-thinking.ts` 翻译 `thinkingEnabled` / `reasoningEffort` 到具体 API 字段 资料来源：[packages/core/src/common/openai-thinking.ts:1-80]()
- **工具执行器**：`tools/executor.ts` 调度模型返回的工具调用 资料来源：[packages/core/src/tools/executor.ts:1-120]()
- **MCP 集成**：`packages/core/src/mcp/` 以子进程方式拉起 Model Context Protocol 服务器 资料来源：[packages/core/src/mcp/index.ts:1-100]()

## 2. 会话管理与模型协作

`SessionManager` 是整个系统的状态中枢，负责维护消息序列、token 用量、模型配置与会话元数据（名称、创建时间）。v0.1.28 将 OpenAI 协议转换逻辑从 SessionManager 中剥离为独立的 `openai-message-converter.ts`，降低模块耦合，使消息格式演进不再影响会话核心 资料来源：[packages/core/src/session.ts:80-200]()。

为避免反复实例化造成的握手开销，`openai-client.ts` 复用单一 OpenAI 客户端并引入 `undici` keep-alive Agent，在启动时进行连接预热（connection warmup），显著降低首请求延迟 资料来源：[packages/core/src/openai-client.ts:40-90]()。

会话清理曾在 v0.1.26 修复一处内存泄漏，并通过回归测试覆盖：`SessionManager.dispose()` 必须正确释放消息缓冲、计时器与 MCP 子进程句柄 资料来源：[packages/core/src/session.ts:200-260]()。

v0.1.28 起会话名称支持在线编辑；v0.1.29 起持久化行为由 `docs/session-persistence.md` 文档规范，确保跨进程恢复字段一致 资料来源：[docs/session-persistence.md:1-40]()。

`openai-thinking.ts` 将 `settings.json` 中的 `thinkingEnabled` 与 `reasoningEffort` 翻译为对应 API 的 `reasoning_effort` / `thinking` 字段，深度思考与推理强度由该层统一控制 资料来源：[packages/core/src/common/openai-thinking.ts:30-80]()。

## 3. 工具执行系统

模型在响应中发出的所有工具调用统一由 `tools/executor.ts` 调度。执行器维护待执行队列、单条消息的多 `tool_calls` 策略、失败重试与结果回填到消息历史。主要内置工具：

- **Bash**：执行 shell 命令，支持超时机制（默认 10 分钟，可在 `Ctrl+O` 界面调整）。v0.1.23 修复了 Windows 下无法杀死进程组的问题，使用进程组 + `taskkill` / `kill -KILL` 兜底 资料来源：[packages/core/src/tools/bash.ts:1-150]()。
- **Edit**：原子化的文件字符串替换。v0.1.27 取消了 `findClosestMatch` 返回，直接调用 `inferOldStringNotFoundReasonWithLLM` 生成更精准的失败提示 资料来源：[packages/core/src/tools/edit.ts:1-120]()。

MCP（Model Context Protocol）作为外部工具扩展点，通过 `mcp/` 子模块以子进程方式拉起服务。v0.1.30 修复了 Windows 下 `spawn` 的双重引号转义缺陷；v0.1.24 新增 `/mcp` 命令的手动重连能力 资料来源：[packages/core/src/mcp/index.ts:1-100]()。

## 4. 数据流与扩展生态

整个会话的数据流可抽象为「用户输入 → 会话 → 模型 → 工具 → 会话」的单向闭环，所有结果通过 SessionManager 统一回写消息历史，保证下次请求携带完整上下文。

```mermaid
flowchart LR
  U[用户输入] --> P[PromptInput]
  P --> S[SessionManager]
  S --> C[OpenAI Client]
  C -->|stream| M[Model]
  M -->|tool_calls| E[Tool Executor]
  E --> B[Bash]
  E --> Ed[Edit]
  E --> MC[MCP Servers]
  B --> S
  Ed --> S
  MC --> S
  S --> U
```

资料来源：[packages/core/src/session.ts:80-200]()，[packages/core/src/tools/executor.ts:30-90]()

扩展能力方面：

- **Skills**：v0.1.29 引入 bundled built-in skills（如 `deepcode-self-refer`、`skill-digester`），通过 `settings.json` 中的 `enabledSkills` 启用；v0.1.30 新增 plan-mode skill 资料来源：[packages/core/src/skills/index.ts:1-80]()。
- **斜杠命令**：`/raw`（v0.1.23）让终端消息直出，绕过 TUI 渲染层；`/tokens`、`/context`、`/cost`（#222–#224）正在评审，用于可视化 token 与上下文用量；`/mcp`（v0.1.24）手动重连 MCP 服务器。
- **模型配置**：当前 `settings.json` 仅支持单组模型字段，社区已在 #204 请求支持多 profile 切换（`/model` 命令），以便在同一会话中快速切换不同模型组合。

**已知限制与社区关注点**：

- 强制 TTY 限制：当前 `cli.tsx:73` 要求 `process.stdin.isTTY`，阻断 headless / CI 场景（#139）
- 暂不支持 subAgent（#154），与 superpowers 工作流存在集成缺口
- 多模型 profile 切换尚未落地（#204）
- Token / context / cost 可视化命令仍在评审中（#222、#223、#224）
- 远程控制（手机扫码接管会话）已被提议，参考 Claude Code `/rc` 实现（#187）

资料来源：[cli.tsx:73-100]()，[package.json:1-120]()

---

<a id='page-ui'></a>

## TUI 界面、Slash 命令与键盘交互

### 相关页面

相关主题：[项目概览与快速开始](#page-overview), [核心架构、会话管理与工具系统](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cli/src/ui/views/App.tsx](https://github.com/lessweb/deepcode-cli/blob/main/packages/cli/src/ui/views/App.tsx)
- [packages/cli/src/ui/views/AppContainer.tsx](https://github.com/lessweb/deepcode-cli/blob/main/packages/cli/src/ui/views/AppContainer.tsx)
- [packages/cli/src/ui/views/PromptInput.tsx](https://github.com/lessweb/deepcode-cli/blob/main/packages/cli/src/ui/views/PromptInput.tsx)
- [packages/cli/src/ui/views/WelcomeScreen.tsx](https://github.com/lessweb/deepcode-cli/blob/main/packages/cli/src/ui/views/WelcomeScreen.tsx)
- [packages/cli/src/ui/views/SlashCommandMenu.tsx](https://github.com/lessweb/deepcode-cli/blob/main/packages/cli/src/ui/views/SlashCommandMenu.tsx)
- [packages/cli/src/ui/views/UndoSelector.tsx](https://github.com/lessweb/deepcode-cli/blob/main/packages/cli/src/ui/views/UndoSelector.tsx)
</details>

# TUI 界面、Slash 命令与键盘交互

## 1. TUI 架构概览

DeepCode CLI 的终端界面基于 React + Ink 渲染栈构建，采用"视图（views）+ 容器（containers）+ 命令（commands）"三层架构。`App.tsx` 作为顶层渲染根节点，挂载欢迎屏、对话流、提示输入框与状态栏；`AppContainer.tsx` 则负责聚合会话状态、模型配置、Skill 列表与后台任务，向下层视图以 props / context 形式注入数据。

社区反馈表明该 TUI 体验被广泛认可：issue #139 中用户特别称赞"TUI 体验非常好，deepseek-v4 的深度思考和推理强度控制也特别好用"。同时需注意 `cli.tsx` 在启动时强制检查 `process.stdin.isTTY`，无 TTY 时直接退出，这也是社区提出 headless/CI 模式请求（#139）的直接原因。

资料来源：[packages/cli/src/ui/views/App.tsx]()、[packages/cli/src/ui/views/AppContainer.tsx]()

## 2. Slash 命令菜单系统

`SlashCommandMenu.tsx` 是 Slash 命令的入口组件，承担命令补全、过滤、键盘上下选中与回车执行四项职责。当用户在 `PromptInput` 中以 `/` 起首输入时，菜单渲染可用命令清单。

内置命令类别（基于发行说明与 issue 证据）：

| 命令 | 功能 | 出处 |
|------|------|------|
| `/model` | 切换 settings.json 中声明的多个模型 profile | issue #204 |
| `/tokens` `/context` `/cost` | 查看 token 消耗、上下文占用与成本估算 | issues #222–224 |
| `/raw` | 切换终端原始输出模式，绕过 UI 渲染 | v0.1.23 |
| `/skills` 启用集合 | 通过 `settings.json` 中的 `enabledSkills` 控制 | v0.1.29 |

社区已提出 `/rc`（remote-control）远程控制命令的需求（#187），并借鉴 Claude Code 与 Codex 的扫码配对体验；该能力属于菜单系统未来扩展方向。

资料来源：[packages/cli/src/ui/views/SlashCommandMenu.tsx]()

## 3. 提示输入框与输入处理

`PromptInput.tsx` 是用户主要交互面，承担多行编辑、光标定位、Busy 状态显示与粘贴处理四项核心职责。v0.1.29（PR #171）专门修复了"提示输入的换行、光标定位与 busy 状态显示"问题，反映该组件稳定性一直是维护重点。

输入层关键能力：

- **大段粘贴折叠**：v0.1.25（PR #102）引入 bracketed paste 协议，并对超大粘贴内容折叠为 marker，避免破坏 TUI 布局。
- **CJK 输入修正**：v0.1.24（PR #94）修复 iOS 终端上 backspace 包拆分导致的 CJK 合成 bug。
- **Raw 模式切换**：`Ctrl+R` 作为 v0.1.29 引入的快捷键，可在需要时退出 Ink 的转义序列处理。

资料来源：[packages/cli/src/ui/views/PromptInput.tsx]()

## 4. 辅助界面与键盘交互

`WelcomeScreen.tsx` 在会话开始前展示项目摘要、当前模型与提示示例，帮助用户快速进入任务。`UndoSelector.tsx` 提供对历史编辑操作的选择性回滚，配合 Edit 工具使用。

关键键盘绑定（已合入版本）：

- `Ctrl+O`：实时后台进程 stdout 查看器（v0.1.22，PR #75）。
- `Ctrl+R`：切换 raw 模式（v0.1.29）。
- `Enter` / `Tab`：在 `SlashCommandMenu` 中确认或补全命令。

```mermaid
flowchart TD
    A[App.tsx] --> B[AppContainer.tsx]
    B --> C[WelcomeScreen.tsx]
    B --> D[SlashCommandMenu.tsx]
    B --> E[PromptInput.tsx]
    B --> F[UndoSelector.tsx]
    E -- "/" 触发 --> D
    E -- Ctrl+R --> G[Raw 模式]
    B -- Ctrl+O --> H[Stdout 查看器]
```

整体而言，TUI 层通过"输入—命令—视图"三段式闭环承载用户与模型之间的交互，所有面向用户的快捷键与命令均集中在上述六个视图组件内，便于扩展与回归测试。资料来源：[packages/cli/src/ui/views/UndoSelector.tsx]()、[packages/cli/src/ui/views/WelcomeScreen.tsx]()

---

<a id='page-extensibility'></a>

## 扩展生态：MCP、Agent Skills、插件与 VSCode 伴生插件

### 相关页面

相关主题：[核心架构、会话管理与工具系统](#page-architecture), [TUI 界面、Slash 命令与键盘交互](#page-ui)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/src/mcp/mcp-manager.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/mcp/mcp-manager.ts)
- [packages/core/src/mcp/mcp-client.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/mcp/mcp-client.ts)
- [packages/core/src/mcp/mcp-server-types.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/mcp/mcp-server-types.ts)
- [packages/core/templates/skills/bundled/deepcode-self-refer/SKILL.md](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/templates/skills/bundled/deepcode-self-refer/SKILL.md)
- [packages/core/templates/skills/bundled/plan/SKILL.md](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/templates/skills/bundled/plan/SKILL.md)
- [packages/core/templates/skills/bundled/skill-digester/SKILL.md](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/templates/skills/bundled/skill-digester/SKILL.md)
- [packages/core/templates/skills/bundled/skill-writer/SKILL.md](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/templates/skills/bundled/skill-writer/SKILL.md)
- [packages/core/src/settings/settings-types.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/settings/settings-types.ts)
- [packages/core/src/skills/skill-loader.ts](https://github.com/lessweb/deepcode-cli/blob/main/packages/core/src/skills/skill-loader.ts)
</details>

# 扩展生态：MCP、Agent Skills、插件与 VSCode 伴生插件

DeepCode CLI 的扩展能力围绕三层结构展开：`MCP`（Model Context Protocol）外部工具服务器、`Agent Skills` 技能包、以及运行时尚可注入的轻量插件钩子。本页解析这三层的设计契约、加载链路与配置入口，并简要说明与 VSCode 配套边界。社区关注度较高的 token/context 命令（#222/#223/#224）和多模型切换（#204）虽与扩展生态相邻，但属于会话观测与模型配置维度，不在本页展开。

## MCP（Model Context Protocol）外部工具网关

`mcp-manager.ts` 作为 MCP 服务器的聚合管理器，负责在启动阶段解析用户配置中的 MCP 声明、惰性构造 transport 并在工具调用请求到达时按 server 名路由到对应子客户端。资料来源：[packages/core/src/mcp/mcp-manager.ts:1-120]()。

`mcp-client.ts` 封装了与单个 MCP 服务器进程（stdio / pipe）之间的 JSON-RPC 通信、工具列表拉取与 `tools/call` 调用；它同时维护断连状态机，在 v0.1.24 起提供手动重连入口（`/mcp reconnect`）以便用户在不重启 CLI 的前提下恢复服务。资料来源：[packages/core/src/mcp/mcp-client.ts:30-180]()、`v0.1.24: feat: MCP 服务器手动重连功能`。

Windows 平台上 spawn 的双引号嵌套问题在 v0.1.30 通过统一引号转义工具修复，并对 cmd 元字符做了规避测试，所有 MCP 服务器因此可在 Windows 终端原生运行。资料来源：[packages/core/src/mcp/mcp-manager.ts:200-260]()、`v0.1.30: fix(mcp): fix Windows MCP spawn double-quoting`。[packages/core/src/mcp/mcp-server-types.ts]() 中定义了 `MCPServerConfig`、`MCPServerStatus` 等共享类型，使上游 TUI 与下游 client 共用同一种枚举语义。

## Agent Skills 技能系统

Skills 是一组模板化的「系统提示词 + 工作流」片段，由 LLM 在隐式或显式触发时按需加载。仓库内置了四个 `bundled` 技能：

| 技能 | 触发场景 | 关键职责 |
|------|---------|---------|
| `deepcode-self-refer` | 当问题涉及 DeepCode 自身能力、命令、配置 | 引用官方文档段落，避免幻觉 |
| `plan` | 用户要求先规划再执行 | 强制先生成实施计划供审阅 |
| `skill-digester` | 用户提供外部 skill 文件需要消化 | 解析、压缩并入当前上下文 |
| `skill-writer` | 用户要求新建或修改一个 skill | 遵循仓库约定的 SKILL.md 骨架产出 |

资料来源：[packages/core/templates/skills/bundled/deepcode-self-refer/SKILL.md:1-40]()、[packages/core/templates/skills/bundled/plan/SKILL.md:1-30]()、[packages/core/templates/skills/bundled/skill-digester/SKILL.md:1-35]()、[packages/core/templates/skills/bundled/skill-writer/SKILL.md:1-50]()。

`skill-loader.ts` 在启动时按目录树扫描用户技能目录与内置 `bundled` 目录，合并后根据 `settings.json` 中的 `enabledSkills` 白名单进行过滤；未启用的技能在 prompt 中不被引用。资料来源：[packages/core/src/skills/skill-loader.ts:40-120]()、`v0.1.29: feat: implement enabledSkills support in settings.json`。

```mermaid
flowchart LR
  Settings[settings.json<br/>enabledSkills] --> Loader[skill-loader]
  Bundled[templates/skills/bundled] --> Loader
  User[~/.deepcode/skills] --> Loader
  Loader --> Active[激活技能集合]
  Active --> Prompt[系统提示词注入]
  UserInput[用户输入] -->|隐式匹配| Prompt
  Prompt --> LLM[(LLM 调用)]
```

v0.1.29 起所有内置技能都会随 npm 包一起发布，避免运行前还需额外克隆仓库；v0.1.30 又新增了「隐式调用」支持，即 LLM 可在不显式打出 `/skill` 前缀的情况下自动唤起匹配的技能。

## 插件钩子与 VSCode 伴生

除 MCP 与 Skills 之外，DeepCode CLI 还通过 `notify` hook 让外部脚本接收会话事件。v0.1.23 将 `STATUS`、`FAIL_REASON`、`BODY`、`TITLE` 作为环境变量传给用户配置的 hook，便于用户接入 VSCode 任务通知、企业 IM 机器人等下游系统。资料来源：[packages/core/src/hooks/notify-hook.ts]()`、`v0.1.23: feat(notify): pass STATUS, FAIL_REASON, BODY, TITLE as env vars to notify hook`。

至于仓库命名中提到的 VSCode「伴生插件」，当前主分支内仅提供 CLI 单体；官方尚未发布独立 VSCode 扩展包（社区 #187 也明确把「远程控制」功能请求与远程会话绑定而非 VSCode 插件）。建议关注者将 `notify` hook 视作与 VSCode Task / Cursor IDE 集成的最简入口，待后续官方插件出现后再调整工作流。

## 启用顺序与排错要点

1. 先在 `settings.json` 写入 `mcpServers` 与 `enabledSkills`，CLI 重启后生效；
2. 启动日志中的 `[mcp]` 行可确认每个 MCP server 是否握手成功；
3. 技能未命中时检查 `enabledSkills` 是否包含对应 id，以及其 `SKILL.md` 的 frontmatter 触发词是否被新版本调整；
4. Windows 下若 MCP 工具全部不可用，请确认 v0.1.30 之后的引号修复版本号。资料来源：[packages/core/src/mcp/mcp-manager.ts:260-300]()、[packages/core/src/skills/skill-loader.ts:120-180]()。

通过上述三层契约，DeepCode CLI 把「工具接入」「能力注入」「外部协作」解耦，使用户既能按需加载 MCP 服务器，又能用 Skills 沉淀团队流程，再以 hook 桥接到编辑器与通知链。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：lessweb/deepcode-cli

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：**Title:** Support multiple model profiles in settings.json for quick switching via `/model`。

## 1. 配置坑 · 来源证据：**Title:** Support multiple model profiles in settings.json for quick switching via `/model`

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：**Title:** Support multiple model profiles in settings.json for quick switching via `/model`
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lessweb/deepcode-cli/issues/204 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/lessweb/deepcode-cli | host_targets=mcp_host, claude_code, claude, chatgpt

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/lessweb/deepcode-cli | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/lessweb/deepcode-cli | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/lessweb/deepcode-cli | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/lessweb/deepcode-cli | no_demo; severity=medium

## 7. 安全/权限坑 · 来源证据：feat: add /tokens /context /cost commands to show token usage and context size

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: add /tokens /context /cost commands to show token usage and context size
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lessweb/deepcode-cli/issues/224 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 安全/权限坑 · 来源证据：feat: add /tokens and /context commands to show token usage and context size

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: add /tokens and /context commands to show token usage and context size
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lessweb/deepcode-cli/issues/222 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/lessweb/deepcode-cli | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/lessweb/deepcode-cli | release_recency=unknown

<!-- canonical_name: lessweb/deepcode-cli; human_manual_source: deepwiki_human_wiki -->