项目简介

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）按需启用。

核心特性一览

社区对 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 尚未合并。

安装与启动

# 克隆仓库
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 用于控制行为。典型片段：

{
  "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 跟进。

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 统一回写消息历史，保证下次请求携带完整上下文。

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

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 证据）：

社区已提出 /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 中确认或补全命令。

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

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 技能：

资料来源：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。

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 桥接到编辑器与通知链。

Pitfall Log / 踩坑日志

项目：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