Deep Copilot

Deep Copilot 是一个 VS Code 扩展，在侧边栏提供基于大语言模型的对话式编程辅助。它通过 DeepSeek API（兼容 OpenAI 协议）与模型交互，支持文件读写、代码搜索、Shell 命令执行等工具调用，结果以流式方式实时渲染。扩展无运行时 npm 依赖，基于 VS Code Extension API 与 Node.js 内置模块实现，无需在宿主机额外部署任何服务。

Deep Copilot is a VS Code extension that provides LLM-based conversational coding assistance through the sidebar. It interacts with models via the DeepSeek API (OpenAI-compatible protocol), supporting tool calls for file read/write, code search, and shell command execution — all streamed in real time. The extension has no runtime npm dependencies and is built on the VS Code Extension API and Node.js built-ins; no additional service deployment is required.

🔑 API Keys Required · 需要配置的 API Key

开始使用前只需准备以下 Key（最少只需第一个）：
You only need the following keys to get started — at minimum just the first one:

如何填入 · How to set them

中文：

1. 安装扩展后，点击侧边栏活动栏的 🐋 图标打开 Deep Copilot 面板
2. 点击面板右下角 🔑 按钮 → 粘贴 DeepSeek API Key → 保存
3. 若需要联网搜索，在同一弹窗里继续填入 Tavily API Key

English:

1. After installing, click the 🐋 icon in the activity bar to open the Deep Copilot panel
2. Click the 🔑 button in the bottom-right of the panel → paste your DeepSeek API Key → save
3. For web search, fill in your Tavily API Key in the same dialog

国内用户：若 api.deepseek.com 连接不稳定，在 🔑 弹窗中将 Base URL 改为 https://api.deepseeki.com。
China users: if api.deepseek.com is slow, set Base URL to https://api.deepseeki.com in the 🔑 dialog.

📑 Table of Contents · 目录

• API Keys · 需要配置的 Key
• Highlights · 亮点
• Quick Start · 快速开始
• Build from Source · 源码构建
• Configuration · 配置
• Keybindings · 快捷键
• Tools · 工具列表
• Architecture · 架构
• Project Structure · 项目结构
• Development · 开发
• Troubleshooting · 故障排查
• Changelog · 更新日志
• Star History
• License

✨ Highlights · 亮点

🚀 Quick Start · 快速开始

Option 1 — VS Code Marketplace · 从扩展商城安装（推荐）

1. Open VS Code → Extensions (Ctrl/Cmd+Shift+X) → Search Deep Copilot → Install. 打开 VS Code → 扩展面板（Ctrl/Cmd+Shift+X）→ 搜索 Deep Copilot → 安装。

Option 2 — Install the prebuilt VSIX · 安装预构建 VSIX

# 从 GitHub Releases 下载最新版 / Download from GitHub Releases:
# https://github.com/ZhouChaunge/DeepCopilot/releases

code --install-extension deep-copilot-0.41.6.vsix

Or in VS Code: Extensions view → ⋯ menu → Install from VSIX... and pick the file. 或在扩展面板右上角 ⋯ → Install from VSIX... 选择文件。

Step 2 — Set the API key · 配置 API Key

1. Click the 🐋 Deep Copilot icon in the activity bar to open the chat panel.点击活动栏中的 🐋 Deep Copilot 图标，打开聊天面板。
2. Click the 🔑 button at the bottom right of the panel, paste your DeepSeek API key.点击面板右下角 🔑 按钮，粘贴你的 DeepSeek API Key。
3. Start chatting! 开始对话！

🛠 Build from Source · 源码构建

Prerequisites · 前置依赖

Steps · 构建步骤

# 1. Clone the repo · 克隆仓库
git clone https://github.com/ZhouChaunge/DeepCopilot.git
cd DeepCopilot

# 2. Install dependencies · 安装依赖
#    (only devDependencies: esbuild + vsce + @types — runtime is pure VS Code API)
#    （只有开发依赖；运行时仅用 VS Code API，无运行时 npm 依赖）
npm install

# 3. Build the bundle · 编译为单文件
npm run build
# -> outputs out/extension.js (~105 KB minified)
# -> 产出 out/extension.js（约 105 KB，已压缩）

# 4. Package as VSIX · 打包 VSIX
npm run package
# -> outputs deep-copilot-0.41.6.vsix
# -> 产出 deep-copilot-0.41.6.vsix

# 5. Install locally · 本地安装
code --install-extension deep-copilot-0.41.6.vsix --force

Watch mode · 监听模式（开发期）

npm run watch
# Rebuilds out/extension.js on every src/ change.
# 修改 src/ 任何文件即增量重建 out/extension.js。
# Then: F5 in VS Code (with the repo opened) launches the Extension Development Host.
# 然后在 VS Code 里按 F5 启动“扩展开发宿主”加载本地构建。

What gets built · 构建产物说明

🇬🇧 Everything required to compile is in the repo. out/ and *.vsix are reproducible artifacts. 🇨🇳 编译所需文件全部在仓库里。out/ 和 *.vsix 是可重现的产物，已 .gitignore。

⚙️ Configuration · 配置

All settings live under the deepseekAgent.* namespace in settings.json. 所有设置都在 settings.json 的 deepseekAgent.* 命名空间下。

Approval Modes · 审批模式

Issue #89 · Autopilot 与危险命令：autopilot 模式下，命中危险命令正则（rm -rf、git reset --hard、git push --force …）的 shell 调用会静默放行，并写入 SHELL_DANGER_AUTO_APPROVE 审计日志，不再弹模态确认框；其他模式中，同一条命令在一次会话内被批准过一次后也会缓存，不会重复弹框。若把 run_shell 加入 autoApproveTools，效果等同于显式承担 shell 风险，请仅在受信任工作区开启。

⌨️ Keybindings · 快捷键

🧰 Tools · 工具列表

Deep Copilot exposes a small, deliberately-minimal tool set to the model: Deep Copilot 给模型暴露的工具集刻意保持精简：

🇬🇧 Tool definitions live in src/tools/schema.js; execution in src/tools/exec.js.

🇨🇳 工具定义见 src/tools/schema.js，执行实现见 src/tools/exec.js。

🏗️ Architecture · 架构

┌──────────────────────────────────────────────────────────┐
│                  VS Code Extension Host                  │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │ src/extension.js  (activate / commands)            │  │
│  └────────────────────────────────────────────────────┘  │
│                          │                               │
│                          ▼                               │
│  ┌────────────────────────────────────────────────────┐  │
│  │ src/chat/provider.js  (ChatViewProvider)           │  │
│  │   • Webview ↔ Extension message bus                │  │
│  │   • Per-session run map  (parallel sessions)       │  │
│  │   • Persisted history    (globalState)             │  │
│  │   • Plan / Todos state                             │  │
│  └────────────────────────────────────────────────────┘  │
│            │                            │                │
│            ▼                            ▼                │
│  ┌──────────────────┐        ┌────────────────────────┐  │
│  │ src/api/         │        │ src/tools/             │  │
│  │  deepseek.js     │        │  schema.js  (defs)     │  │
│  │  • SSE streaming │        │  exec.js    (runtime)  │  │
│  │  • Tool calls    │        │  • read/write/list     │  │
│  │  • Reasoning     │        │  • grep / shell        │  │
│  └──────────────────┘        │  • approval gating     │  │
│                              └────────────────────────┘  │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │ src/webview/html.js   (HTML shell injected)        │  │
│  │ media/chat.js + chat.css   (UI runtime + styles)   │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘
                          │  HTTPS (SSE)
                          ▼
              ┌────────────────────────┐
              │  DeepSeek Platform     │
              │  api.deepseek.com      │
              │  (OpenAI-compatible)   │
              └────────────────────────┘

Key design points · 关键设计

• 🇬🇧 No backend. Everything runs inside the VS Code extension host. The single bundle out/extension.js is approx 94 KB. 🇨🇳 无后端。 全部跑在 VS Code 扩展主机里，单文件构建产物 out/extension.js 仅约94KB。
• 🇬🇧 Per-session run map. provider._runs: Map<sessionId, Run> lets you switch sessions while a task is running; the run keeps producing events that get buffered and replayed when you return. 🇨🇳 按会话隔离的 run 表。 provider._runs 让你在任务跑着时切到别的会话，事件继续缓冲，切回来自动回放。
• 🇬🇧 Streaming via SSE. src/api/deepseek.js parses data: frames and forwards delta, reasoning, tool_calls, usage to the provider. 🇨🇳 SSE 流式。 src/api/deepseek.js 解析 data: 帧，把 delta / reasoning / tool_calls / usage 转发给 provider。
• 🇬🇧 Auto-compaction. Once estimated tokens exceed compactBudgetTokens, older tool results are dropped before the next round. 🇨🇳 自动压缩。 估算 token 超过 compactBudgetTokens 时，下一轮前丢弃较老的工具结果。
• 🇬🇧 Approval is enforced server-side (in the extension), not just UI. A model-issued write_file will not execute unless the policy or user explicitly allows it. 🇨🇳 审批在扩展端强制执行（不仅是 UI 层）：模型发出的 write_file 必须经策略或用户放行才会真的写盘。

📁 Project Structure · 项目结构

.
├── esbuild.config.js          # esbuild bundler config · 打包配置
├── package.json               # extension manifest + scripts · 清单与脚本
├── package-lock.json          # locked deps · 锁定依赖
├── README.md                  # this file · 本文件
├── LICENSE                    # MIT
├── media/                     # webview assets (loaded as static files)
│   ├── chat.css               #   ↳ all UI styles · 全部 UI 样式
│   └── chat.js                #   ↳ webview runtime (markdown, tool cards, streaming)
├── imgs/
│   ├── logo_black_bg.png      #   ↳ extension icon + webview logo
│   ├── logo_black_bg.svg      #   ↳ activity bar icon (vector)
│   ├── logo.png               #   ↳ marketplace icon (white background)
│   ├── logo_white_bg.svg      #   ↳ activity bar icon (white variant)
│   ├── logo_white_bg.png      #   ↳ logo (base)
│   └── screenshot.png         # README screenshot · README 截图
└── src/                       # extension source · 扩展源码
    ├── extension.js           #   ↳ activate() entry · 入口
    ├── errors.js              #   ↳ error → friendly bilingual card
    ├── logger.js              #   ↳ debug log writer (.deep-copilot/logs/)
    ├── pricing.js             #   ↳ token → CNY cost calculator
    ├── hooks.js               #   ↳ post-tool hooks runner (.deepcopilot/hooks.json)
    ├── mcp.js                 #   ↳ MCP stdio client (McpClient + McpManager)
    ├── api/
    │   └── deepseek.js        #   ↳ SSE chat client (OpenAI-compatible)
    ├── chat/
    │   ├── provider.js        #   ↳ ChatViewProvider (the brain)
    │   └── openFile.js        #   ↳ "open file at line" helper
    ├── prompts/
    │   └── system.js          #   ↳ system prompt builder (+DEEPCOPILOT.md +user memory)
    ├── tools/
    │   ├── schema.js          #   ↳ tool JSON-schema definitions
    │   └── exec.js            #   ↳ tool runtime (file IO, ripgrep, shell)
    ├── utils/
    │   ├── i18n.js            #   ↳ zh-cn / en strings + locale detection
    │   └── paths.js           #   ↳ path safety / workspace root resolution
    └── webview/
        └── html.js            #   ↳ generates the webview HTML shell

🇨🇳 编译入口：src/extension.js → esbuild → out/extension.js（package.json 中 main 字段指向 out/extension.js）。

🇬🇧 Build entry: src/extension.js → esbuild → out/extension.js (referenced by main in package.json).

💻 Development · 开发

Run the dev host · 启动扩展开发宿主

git clone https://github.com/ZhouChaunge/DeepCopilot.git
cd DeepCopilot
npm install
code .
# Press F5 inside VS Code → Extension Development Host opens
# 在 VS Code 里按 F5 → 弹出扩展开发宿主窗口

Live edit cycle · 改一改试一试

npm run watch     # esbuild watch — rebuilds on save · 保存即重建
# In the dev host: Ctrl+R / Cmd+R reloads the window after a rebuild
# 在宿主窗口里按 Ctrl+R / Cmd+R 重载即可看到效果

Debug logs · 调试日志

• Output panel → Deep Copilot channel Output 面板 → 选择 Deep Copilot 频道
• Or open via command palette: Deep Copilot: Open Debug Log 或命令面板：Deep Copilot: Open Debug Log
• Files: <workspace>/.deep-copilot/logs/session-*.log 日志文件：<工作区>/.deep-copilot/logs/session-*.log

Workspace-specific instructions · 工作区级提示词

Create a DEEPCOPILOT.md at the workspace root and Deep Copilot will inject its content into the system prompt for every request in this workspace — useful for project conventions, build commands, "do/don't" lists.

在工作区根目录新建 DEEPCOPILOT.md，其内容会自动并入系统提示词，用来声明项目约定、构建命令、do/don't 等。

User memory · 用户记忆

Create ~/.deepcopilot/memory.md for cross-project preferences that apply everywhere — preferred coding style, always/never rules, personal shortcuts. It is injected (capped at 4 KB) into every system prompt.

在家目录新建 ~/.deepcopilot/memory.md，写入跨项目的个人偏好（代码风格、禁忌事项等），Deep Copilot 会在每次对话时自动注入（最多 4KB）。

MCP servers · MCP 工具服务器

Add external tool servers via VS Code settings:

"deepseekAgent.mcp.servers": [
  { "name": "my-db", "command": "npx", "args": ["my-db-mcp-server"] }
]

Tools appear as mcp__my-db__<toolName> alongside built-in tools. Any MCP-compatible stdio server works.

通过 VS Code 设置连接外部 MCP 工具服务器，工具以 mcp__<server>__<toolName> 格式出现。任何兼容 MCP stdio 协议的服务器均可接入。

Post-tool hooks · 工具后置钩子

Create .deepcopilot/hooks.json in your workspace:

{ "hooks": [
  { "event": "after_tool", "tool": "write_file",
    "run": "npm test", "on_failure": "inject_error", "timeout_ms": 30000 }
]}

The hook's stdout/stderr is appended to the tool result so the model can react — e.g., auto-fix test failures immediately after writing a file.

在工作区创建 .deepcopilot/hooks.json，每次写文件后自动跑 npm test，测试输出注入模型上下文让其自动修复。

Style & conventions · 代码风格

• Plain JavaScript (no TypeScript) — keep the bundle tiny. 纯 JavaScript（不用 TypeScript），保持产物极小。
• No runtime dependencies — only VS Code API + Node built-ins. 无运行时依赖，只用 VS Code API 与 Node 内置模块。
• Webview side communicates via postMessage; never imports vscode. Webview 端通过 postMessage 通信，不引用 vscode。

🔧 Troubleshooting · 故障排查

📜 Changelog · 更新日志

v0.41.6 — Archive 纯导出 · 值守任务不提前退出

• 中文：①Issue #169：Archive 语义改为「纯导出」——点「存档」只会在 .deep-copilot/archives/ 下生成 Markdown 快照，会话本身保持原状（不再软隐藏、不会被切走、同一会话连点两次会生成两个 md）；出错或取消保存不再错误地改动 archived 状态。另加一次性迁移 _migrateArchivedFlagIfNeeded：由 globalState['deepseekAgent.archiveSemanticsV2Migrated'] 守护，升级后首次启动自动把旧版本软隐藏的会话全部还原到侧边栏，失败走 Logger.info('ARCHIVE_V2_MIGRATION_FAILED', ...)，不阻塞激活。②值守任务不提前退出——在之前的状态下，如果后台任务（例如训练）是在更早的 turn 启动的，BG_WAIT_SKIPPED_MODEL_DONE 守卫会在模型说完「我会持续监控」之后立刻结束会话。本版本新增 run._monitoredBgJobs 跟踪集：模型调用 read_terminal(terminal: "deepseek-job-*") 读取某个后台任务后，该 jobId 被记为「当前运行在主动监控」；agent-loop 的提前退出守卫同时检查该集合，只要被监控的 bg job 仍在跑，turn 就会继续等待、走快照，直到任务结束事件抵达或命中 4h 本轮预算。③迁移错误调用 Logger（取代 console.warn），为 deepseekAgent.enableDebugLog 下的 Deep Copilot Debug 输出面板补齐一致的错误上下文。④.vscodeignore 补上 .tmp-*.json/.txt/.md 过滤，防止 PR 评论缓存等临时文件被打进 VSIX。
• English: ①Issue #169 — Archive becomes pure export: clicking "Archive" only writes a Markdown snapshot under .deep-copilot/archives/ and leaves the session completely untouched (no more soft-hide, no more current-session-swap, clicking twice on the same session simply produces two snapshots); failure paths and save-dialog cancellation no longer mutate archived state. A one-shot idempotent migration _migrateArchivedFlagIfNeeded (guarded by globalState['deepseekAgent.archiveSemanticsV2Migrated']) flips every legacy archived: true session back to false on first launch so previously-hidden sessions reappear in the sidebar. Failure routes through Logger.info('ARCHIVE_V2_MIGRATION_FAILED', ...) instead of blocking activation. ②Watchdog turn stays on duty: when a background job (training, build, dev server) was started in an earlier turn, run._sessionStartedBgJobs is empty in the current turn, so the BG_WAIT_SKIPPED_MODEL_DONE guard used to terminate the conversation right after the model promised to keep monitoring. The agent now tracks every deepseek-job-* terminal the model inspects via read_terminal in run._monitoredBgJobs; the agent-loop guard refuses to end the turn while any such monitored job is still alive, so the loop keeps polling and emitting 4-minute snapshots until the job finishes or the 4 h per-turn budget elapses. ③Routes migration failures through Logger (replacing console.warn) so diagnostics respect deepseekAgent.enableDebugLog and surface in the "Deep Copilot Debug" output channel. ④.vscodeignore now filters .tmp-*.json/.txt/.md, preventing local PR-review scratch caches from accidentally leaking into the shipped VSIX.

v0.41.0 — Context Window 优化套件 · 会话切换闪屏修复

• 中文：①Issue #142：上下文窗口管理重构——结构感知截断（保留最新工具结果完整内容，旧轮次保留摘要骨架）；同文件多次读取自动去重（仅保留最后一次完整内容，先前版本折叠为 <file path=... read-collapsed='true'/> 占位）；超阈值时启用滚动摘要（rolling summary）按需调用模型把更早的对话压缩成结构化摘要节点；MCP 工具支持 per-server 显式 opt-out；大文件读取附带 read-large-file hint 提醒模型按需 grep 而非整文件读入。②新增三个斜杠命令：/compact [focus] 立即压缩当前会话历史（可附主题词偏置摘要方向，自动读取 .deepcopilot/compact.md 或 CLAUDE.md 作为项目级 compact 指令）；/context 弹出当前会话的 token 占用细分（system / messages / tools / files / hints）；/fork [name] 把当前会话从某条消息派生为新会话，保留上下文起点。③底部 Context Ring 指示器：替换原状态点（#foot .dot），在底部状态栏右下角新增环形进度（#ft-ctx），颜色随上下文占用阈值 <60% 绿 → <85% 黄 → 橙 → 红渐变；点击展开 popover 显示与 /context 一致的细分；事件源 ctxUsage 来自 agent-loop 每轮回写。④Issue #143：会话切换闪屏 / 滚动条抖动修复——切走再切回正在运行的会话时，缓冲事件被同步重放，每个事件触发一次 requestAnimationFrame 滚动，导致明显闪烁。修复：_loadSession 用 setTimeout(..., 0) 把事件重放推到下一个宏任务，并以 replayStart / replayEnd 信封包裹；webview 端新增 _replaying 标志，在重放期间 ascroll() 静默，结束时一次性滚到底。⑤Anthropic / OpenAI 客户端小幅清理；errors.js 文案微调；file-read.js 增加大文件提示输出；session-store.js 适配 rolling summary 节点的持久化与回放。
• English: ①Issue #142 — context-window overhaul: structure-aware truncation (latest tool results kept verbatim, older turns collapsed to summary skeletons); per-file dedup (multiple reads of the same path keep only the latest payload; earlier ones become <file path=... read-collapsed='true'/> placeholders); rolling-summary fallback that compresses older history into structured summary nodes when thresholds are crossed; MCP tools support per-server explicit opt-out; large-file reads now ship a read-large-file hint nudging the model to grep first. ②Three new slash commands: /compact [focus] force-compacts the active session (focus biases the summarisation; merges project-level .deepcopilot/compact.md / CLAUDE.md hints); /context opens a breakdown popover (system / messages / tools / files / hints); /fork [name] forks the current session from a message into a brand-new one with that context as origin. ③Footer context ring: replaces the legacy status dot with a ring indicator (#ft-ctx) whose colour ramps green → yellow → orange → red across 60/85/100% thresholds; click opens the same breakdown shown by /context. ④Issue #143 — session-switch flash / scrollbar jitter: switching away from and back to a running session previously replayed buffered events in a tight loop, each one scheduling its own RAF scroll-to-bottom. Fix: _loadSession defers replay via setTimeout(..., 0) and wraps the burst with replayStart / replayEnd envelopes; the webview adds a _replaying flag that silences ascroll() during the burst and performs a single final scroll on replayEnd. ⑤Minor cleanups in the Anthropic / OpenAI clients, errors.js copy tweaks, file-read.js large-file notice, and session-store.js adapts to persist / replay rolling-summary nodes correctly.

v0.40.4 — Pending Edits Panel · 待审编辑面板

• 中文：①新增「待审编辑」面板：参考 GitH