SmarterCode DeepSeek

⚠️ IMPORTANT NOTE — Production & Preview Features

The Copilot Integration (using DeepSeek as a VS Code Language Model Chat Provider) is already at production level and ready for daily use.

However, this extension also contains several experimental features that are still under active development:

• Vault & Iterative Workflow — Persistent memory and structured multi-step workflows are available as a preview of what's coming. These are functional but may see breaking changes as we refine them.
• Custom Chat — A standalone DeepSeek chat interface is being prepared to replace the Copilot integration in the future. (Running through Copilot currently consumes more tokens/usage than calling DeepSeek directly, making a dedicated chat more efficient.)
• Heavy Optimisations & Workflows — Major performance improvements and advanced workflow capabilities are in the pipeline.

Feedback and contributions are welcome — they help shape the final features!

Table of Contents

1. Overview
2. Copilot Integration
3. Vault-Based Persistent Memory
4. Iteration Flow (Workflow-Based Interaction)
5. Sidebar Explorer
6. ToDo Browser
7. Writeback Engine (Auto-Apply Diff Patches)
8. Context Tag System
9. Multi-Vault Architecture
10. Configuration Reference
11. Commands Reference
12. Architecture Overview
13. Build & Install

1. Overview

SmarterCode DeepSeek is a VS Code extension that brings DeepSeek's language models (V4 Flash & V4 Pro) directly into your editor. It goes beyond a simple chat wrapper by providing:

• Copilot integration — DeepSeek as a first-class VS Code Language Model Chat Provider, usable via the @deepseek chat participant and model selector.
• Persistent project memory — An embedded Obsidian-style vault of Markdown notes that forms an evolving knowledge base your project.
• Iterative workflow engine — Structured, multi-step interaction flows that collect context tags, files, and objectives before submitting to DeepSeek, with support for iterative refinement.
• Context tag system — Tag-based context injection that automatically includes relevant vault notes in every request.
• Diff-based writeback — DeepSeek can propose file changes as unified diffs, and the extension applies them automatically.
• ToDo browser — Aggregate and manage TODO items from both vault notes and source code.

2. Copilot Integration

The extension registers DeepSeek as a VS Code Language Model Chat Provider and a Chat Participant, making DeepSeek models available throughout VS Code's built-in chat interface.

How It Works

VS Code Chat UI
      │
      ▼
Copilot Chat API (vscode.lm.chat)
      │
      ▼
DeepSeekChatProvider (provider/index.ts)
      │
      ├── provideLanguageModelChatInformation() → Exposes model definitions
      ├── provideLanguageModelChatResponse()  → Streams responses
      └── provideTokenCount()                 → Token counting

Registration

• Vendor ID: deepseek
• Chat Participant: @deepseek (id: smartercode.deepseekParticipant)
• Models: deepseek-v4-flash and deepseek-v4-pro

Features

• Full tool-calling support — DeepSeek can invoke VS Code tools (e.g., readFile, grepSearch, terminal commands) as part of its response.
• Vision support — Images sent through VS Code chat are proxied to a vision model for description, then injected into context.
• Reasoning cache — Reasoning content (reasoning_content) is cached across conversation turns and re-injected for context coherence.
• Tool stabilization — An experimental mode that stabilizes tool lists by injecting preflight calls and detecting tool drift across turns.
• Replay engine — Supports segment-based replay markers for debugging and reproducing conversations.
• Request dumping — Raw Copilot payloads and DeepSeek wire requests are dumped to .dump/ for debugging (controlled by deepseek-copilot.debugMode).

Usage

1. Set your API key via the DeepSeek: Set API Key command.
2. Open VS Code Chat (Ctrl+Shift+I / Cmd+Shift+I).
3. Select DeepSeek V4 Flash or DeepSeek V4 Pro from the model dropdown.
4. Or type @deepseek in chat to invoke the dedicated participant.

Chat Participant Fallback

When invoked in the chat participant (@deepseek), the extension either opens the DeepSeek chat panel (for simple prompts like "open") or confirms the participant is active and directs you to use the full feature set.

3. Vault-Based Persistent Memory

The vault is an embedded Obsidian-style Markdown note collection that serves as the project's persistent memory. Every note is a .md file with YAML frontmatter, stored in a configurable vault directory (default: .vault/ at the workspace root).

Vault Structure

.vault/
├── 01-memory-ops/       # Starter folder: operational memory
├── 10-projects/         # Starter folder: project notes
├── 20-shared-systems/   # Starter folder: shared system documentation
├── workflows/           # Custom workflow YAML definitions
├── reports/             # Response outputs from DeepSeek
└── *.md                 # Any Markdown note files

Note Format

---
id: my-note
tags: [architecture, backend]
type: design-doc
related: [other-note]
---

# My Note

Content here...

Frontmatter Fields

Vault Indexing

On startup, the extension scans all .md files in the vault and builds three indexes:

• Tag Index — Maps each tag to the list of file paths that carry it.
• ID Index — Maps each note ID to its file path.
• Type Index — Maps each type value to file paths (reserved for future use).

The vault is auto-reindexed whenever files are added, removed, or modified via a FileSystemWatcher.

System Prompt from Vault

You can place a custom system prompt in your vault and point to it via the deepseek.systemPromptPath setting. The path is relative to the vault root.

4. Iteration Flow (Workflow-Based Interaction)

The Iteration Flow (DeepSeek: Iteration Flow command) is the extension's flagship interaction mode. It replaces single-turn chat with a structured, multi-step workflow that collects all necessary context before submitting to DeepSeek.

Workflow Steps

Step 1 — Objective

• Select context tags (multi-select from vault tags).
• Write your objective or question in a text input.
• Optionally choose a model variant.

Step 2 — Files

• Select additional workspace files to include as context.
• Pre-populated via context menu commands (see below).

Step 3 — DeepSeek Submit

• Resolves selected tags to vault notes.
• Extracts suggestedFiles from note frontmatter.
• Merges all files and notes into a context bundle.
• Submits to DeepSeek API and streams the response.

Step 4 — Response

• Displays the model's response.
• Detects adjustment-request YAML blocks for iterative refinement.
• Applies unified diff patches to workspace files.
• Saves response to {vaultRoot}/reports/response-raw.txt and .html.

Workflow Header Menu (⋮)

The workflow header provides a kebab menu (⋮) with the following actions:

Iterative Refinement Loop

If DeepSeek's response contains a YAML block with adjustment-request including:

• updated-objective
• files-needed
• clarifications-needed

...the workflow prompts for clarifications and restarts, enabling an adjustment loop where you iteratively refine the objective and files until satisfied.

Context Menu Triggers

Explorer context menu (deepseek.startIterationFlow):

• Right-click a file → Opens Iteration Flow with that file pre-selected.
• Right-click a folder → Opens Iteration Flow with all files in that folder.
• Multi-select → Opens Iteration Flow with all selected items.

Editor context menu (deepseek.addSelectionToIterationFlow):

• Select code in the editor, right-click → Opens Iteration Flow with filename, line numbers, and selected code pre-populated as the objective.

Custom Workflows

You can define custom workflow YAML files in {vaultRoot}/workflows/new-objective.yaml. The extension checks for this file at startup and uses it instead of the embedded default workflow.

Active Flow Injection

While an Iteration Flow is running, you can inject additional files, tags, or objective text into the active flow via the sidebar explorer's "Add to Iteration Flow" context menu action.

5. Sidebar Explorer

The DeepSeek Explorer sidebar (activity bar icon) provides a hierarchical view of:

Vault Files

• Tree view of all Markdown notes in the workspace vault, organized by folder structure.
• Click to open a note in the editor.
• Context menu: Open, Delete, Add to Iteration Flow, More Actions.

Global Vault Files (if configured)

• Separate tree section for notes from an external global vault.
• Same interactions as workspace vault files.

Tags

• Flat list of all @tag entries found in vault notes (both workspace and global).
• Click a tag to see its associated notes.

TODOs

• Parses project-memory.md files in the vault for TODO sections.
• Recognizes - [x] (done) and - (pending) checklist items.
• Groups by parent folder for easy navigation.
• Click to open the file at the specific line.
• Supports "Send Issues to DeepSeek Chat" action from the ToDo Browser.

Workflows

• Lists all .yaml/.yml workflow files from {vaultRoot}/workflows/.
• Click to open and run a saved workflow.
• Context menu: Open Workflow, Save Workflow.

6. ToDo Browser

The ToDo Browser (DeepSeek: Open ToDo Browser) aggregates TODO items from two scopes:

Memory TODOs

Scans vault Markdown files for sections matching:
next\s*(?:actions?|steps?)|todo|to-do|requests?

Parses:

• - [x] text — completed items
• - text — pending bullet items

Source TODOs

Scans workspace source files (configurable via .gitignore) for:

• TODO: and FIXME: comments in code.
• Supports common comment syntax (//, #, /* */, <!-- -->).

Features

• Filter by scope (memory vs. source).
• Toggle done/completed view.
• Click any item to jump to the exact file and line.
• "Send Issues to DeepSeek Chat" action passes selected TODOs as context.

7. Writeback Engine (Auto-Apply Diff Patches)

The Writeback Engine enables DeepSeek to propose and apply changes to workspace files automatically. When DeepSeek outputs a unified diff inside a diff fenced code block, the engine parses and applies it.

Supported Formats

Unified Diff:

--- a/src/file.ts
+++ b/src/file.ts
@@ -10,6 +10,7 @@
 some context line
+new line
 another context line

Note Creation:

[CREATE_NOTE id=my-note tags=architecture,backend type=decision]
# Note content here
[END_NOTE]

How It Works

1. Parse fenced diff blocks from the response.
2. Parse unified diff hunks with context matching.
3. Apply hunks in reverse order (bottom-to-top) to maintain line numbers.
4. Handle edge cases like new file creation (/dev/null → new path) and file deletion.

Response Storage

All responses are saved to {vaultRoot}/reports/ as:

• response-raw.txt — raw markdown response
• response-{timestamp}.html — styled HTML rendering

8. Context Tag System

Tags are the primary mechanism for selective context injection. Each vault note carries one or more tags, and you control which tags are active.

How It Works

1. Tag Selection — You select active tags via:
   • The status bar item (click to open tag picker).
   • The DeepSeek: Set Context Tags command.
   • The Iteration Flow's Objective step.
2. Note Resolution — On each request, active tags are resolved to vault notes via resolveTagsToNotes().
3. Context Bundle — Resolved notes are assembled into a context bundle and injected into the system prompt.

Smart Features

• @base tag — Always automatically included. Use this for foundational notes like interaction-rules.md.
• Default context tags — Configure via deepseek.defaultContextTags setting.
• Natural language intent parsing — In chat mode, you can say "add @database" or "focus on @frontend" to modify context.
• Max notes limit — Configurable via deepseek.maxContextNotes (default: 10).
• Max note length — Notes are truncated to deepseek.maxNoteLength characters (default: 4000).

Status Bar Indicator

$(comment-discussion) deepseek-v4-flash | CTX: @base, @architecture

Click the status bar item to open the tag picker.

9. Multi-Vault Architecture

The extension supports two vaults simultaneously:

Workspace Vault (default)

• Located at {workspaceRoot}/.vault (configurable).
• Scoped to the current project.
• Version-control friendly.

Global Vault (optional)

• Configured via deepseek.globalVaultPath.
• Absolute path to an external vault outside the workspace.
• Notes appear under "Global Vault Files" in the sidebar.
• Tags are merged with workspace vault tags for context selection.

Use Cases

• Workspace vault — Project-specific decisions, architecture notes, API documentation.
• Global vault — Personal coding standards, reusable templates, cross-project conventions.

10. Configuration Reference

All settings are under the deepseek.* and deepseek-copilot.* namespaces.

Core Settings (deepseek.*)

Copilot Debug Settings (deepseek-copilot.*)

Internal Copilot Settings (advanced)

11. Commands Reference

Primary Commands

Context & Vault Commands

Sidebar & Explorer Commands

Context Menu Triggers

API Commands (for programmatic use)

ToDo Browser

12. Architecture Overview

┌──────────────────────────────────────────────────────┐
│                    VS Code Extensions Host             │
│                                                        │
│  ┌──────────────────────────────────────────────┐     │
│  │              extension.ts (activate)          │     │
│  │                                                │     │
│  │  ┌─────────────┐  ┌──────────────────┐       │     │
│  │  │ AuthManager  │  │ VaultManager      │       │     │
│  │  │ (auth.ts)    │  │ (vaultManager.ts) │       │     │
│  │  └──────┬──────┘  └────────┬─────────┘       │     │
│  │         │                  │                   │     │
│  │  ┌──────▼──────┐  ┌───────▼────────┐         │     │
│  │  │ DeepSeek    │  │ IndexEngine     │         │     │
│  │  │ ChatProvider│  │ (indexEngine.ts)│         │     │
│  │  │(provider/   │  └───────┬────────┘         │     │
│  │  │  index.ts)  │          │                   │     │
│  │  └──────┬──────┘  ┌───────▼────────┐         │     │
│  │         │         │ ContextSelector │         │     │
│  │         │         │(contextSelector)│         │     │
│  │         │         └───────┬────────┘         │     │
│  │         │                 │                   │     │
│  │  ┌──────▼──────────────────▼────────┐         │     │
│  │  │   DeepSeekClient                  │         │     │
│  │  │   (deepseekClient.ts)             │         │     │
│  │  └──────────────┬───────────────────┘         │     │
│  │                 │                              │     │
│  │  ┌──────────────▼────────────┐                 │     │
│  │  │   WritebackEngine          │                 │     │
│  │  │   (writebackEngine.ts)     │                 │     │
│  │  └───────────────────────────┘                 │     │
│  │                                                │     │
│  │  ┌─────────────┐  ┌──────────────────┐        │     │
│  │  │ SidebarTree  │  │ ObjectiveWorkflow │       │     │
│  │  │(sidebarTree) │  │(objectiveWorkflow│       │     │
│  │  └─────────────┘  │      .ts)         │       │     │
│  │                    └──────────────────┘        │     │
│  └──────────────────────────────────────────────┘     │
│                                                        │
│  ┌──────────────────────────────────────────────┐     │
│  │         DeepSeek API (chat.deepseek.com)      │     │
│  │         or Local Inference Server              │     │
│  └──────────────────────────────────────────────┘     │
└──────────────────────────────────────────────────────┘

Key Design Decisions

1. Dual Provider Architecture — The extension registers both a LanguageModelChatProvider (for Copilot integration) and a standalone DeepSeekClient (for the Iteration Flow). Each has independent configuration and request pipelines.

2. Vault as File System — The vault is stored as plain Markdown files on disk, making it version-control friendly and editable with any tool.

3. Tag-Based Context Injection — Instead of relying on full-text search, tags provide explicit, user-controlled context selection. The @base tag ensures foundational notes are always included.

4. Workflow Execution Plan — The Iteration Flow uses a reusable workflow execution framework from shared/vscode-components/, supporting custom YAML-defined workflows beyond the embedded default.

5. Unified Diff Writeback — Code changes are applied via unified diff patches parsed directly from model responses, enabling automated code modification with human oversight.

13. Build & Install

Prerequisites

• Node.js 18+
• VS Code 1.85+

Build

cd vscode-extensions/vscode-deepseek
npm install
npm run compile

Package & Install

Run build-install.bat from the extension folder:

build-install.bat

This runs vsce package (which triggers vscode:prepublish → precompile → compile), then code --install-extension on the resulting .vsix.

If shared components have changed (shared/vscode-components/), vsce package automatically runs prepare:shared-components to materialize the latest build.

After install, reload VS Code: Ctrl+Shift+P → Developer: Reload Window

Extension Structure

vscode-deepseek/
├── src/
│   ├── extension.ts           # Activation, command registrations, DI wiring
│   ├── auth.ts                # API key management via SecretStorage
│   ├── consts.ts              # Constants & model definitions
│   ├── types.ts               # TypeScript types
│   ├── logger.ts              # Output channel logger
│   ├── i18n.ts                # Internationalization (Chinese/English)
│   ├── deepseekClient.ts      # Standalone DeepSeek API client (Iteration Flow)
│   ├── vaultManager.ts        # Vault file management & frontmatter parsing
│   ├── indexEngine.ts         # Tag/id/type index building
│   ├── contextSelector.ts     # Active tag selection & intent parsing
│   ├── sidebarTree.ts         # DeepSeek Explorer tree provider
│   ├── todoBrowser.ts         # ToDo aggregation webview
│   ├── writebackEngine.ts     # Unified diff parser & file patcher
│   ├── objectiveWorkflow.ts   # Iteration Flow workflow definition
│   ├── client/
│   │   ├── core.ts            # Copilot provider HTTP client
│   │   └── error.ts           # Error handling utilities
│   └── provider/
│       ├── index.ts           # DeepSeekChatProvider (Copilot integration)
│       ├── convert.ts         # Message/tool format conversion
│       ├── schema.ts          # Schema validation
│       ├── debug/             # Request dumping & diagnostics
│       ├── replay/            # Conversation replay engine
│       ├── tools/             # Tool stabilization & limits
│       └── vision/            # Vision proxy for image input
├── vendor/                    # Materialized shared components
├── imgs/                      # Extension icons
├── scripts/                   # Build scripts
├── package.json
├── tsconfig.json
└── build-install.bat