DeepCode

DeepCode 是一个 DeepSeek 原生终端编程 Agent。它可以在本地 CLI 中理解项目、读取文件、编辑代码、运行命令、搜索代码、查看 Git 状态、保存会话、统计 token 成本，并通过权限系统保护危险操作。

DeepCode is a DeepSeek-native coding agent for your terminal. It can understand a local project, read and edit files, run commands, search code, inspect Git state, persist sessions, report token cost, and protect risky operations with a permission system.

当前中文操作手册见：docs/OPERATION_MANUAL.md。

中文

安装

DeepCode 需要 Node.js 20+，在 Windows、macOS、Linux 上都可以运行。

克隆并构建：

git clone https://github.com/jiucai0915-sys/deepcode.git
cd deepcode
npm install
npm run build
npm start

也可以用 pnpm：pnpm install && pnpm build && pnpm start。

Windows PowerShell 用法相同，只是进入目录的命令是 cd path\to\deepcode。

如果你要在新项目中初始化 DeepCode 项目说明：

npm start -- --init

首次配置

DeepCode 使用 DeepSeek API。你可以在 platform.deepseek.com 注册账号并创建 API Key。新用户通常会有平台赠送的体验额度，具体额度、有效期和计费规则以 DeepSeek 控制台显示为准。

DeepCode 支持三种配置方式。

方式一：首次启动时交互式输入

npm start

如果本机还没有全局配置，DeepCode 会提示：

DeepSeek API Key:

输入后会保存到全局配置文件：

macOS / Linux:  ~/.deepcode/config.json
Windows:        %USERPROFILE%\.deepcode\config.json

方式二：手动设置环境变量

macOS / Linux：

export DEEPSEEK_API_KEY="sk-your-api-key"
npm start

Windows PowerShell：

$env:DEEPSEEK_API_KEY = "sk-your-api-key"
npm start

也可以把 DEEPSEEK_API_KEY 写入系统环境变量。如果还没有全局配置，DeepCode 会在首次启动时把这个环境变量导入并保存到全局配置文件；如果全局配置已经存在，则优先使用全局配置。

方式三：直接编辑全局配置

文件位置：

macOS / Linux:  ~/.deepcode/config.json
Windows:        %USERPROFILE%\.deepcode\config.json

完整示例：

{
  "apiKey": "sk-your-api-key",
  "baseURL": "https://api.deepseek.com",
  "model": "deepseek-v4-flash",
  "thinking": false,
  "maxTokens": 8192,
  "maxToolRounds": 8,
  "compressionThresholdTokens": 80000,
  "commandWhitelist": [
    "node",
    "npm",
    "pnpm",
    "npx",
    "tsc",
    "git status",
    "git diff",
    "git log",
    "git branch",
    "dir",
    "ls",
    "cat",
    "type"
  ]
}

配置优先级从高到低：

1. CLI 参数，例如 --model pro --think
2. 项目级 DEEPCODE.md YAML front matter
3. 全局配置 ~/.deepcode/config.json（Windows 为 %USERPROFILE%\.deepcode\config.json）
4. 内置默认值

使用教程

下面是 5 个从简单到复杂的真实使用场景。

1. 了解项目结构

用户输入：

请查看当前项目结构，读取 package.json 和 README.md，然后告诉我这个项目是做什么的、有哪些核心模块。

Agent 会自动执行：

• list_directory 查看目录树
• read_file 读取 package.json
• read_file 读取 README.md
• 结合项目树快照进行分析

最终输出：

• 项目用途
• 技术栈
• CLI 入口
• 核心模块，如 agent、tools、config、security、project、llm
• 下一步建议

2. 写一个新功能并验证

用户输入：

在 src/utils/math.ts 里创建 add、multiply、safeDivide 三个函数，然后创建一个 Node assert 测试文件并主动运行测试，直到通过。

Agent 会自动执行：

• list_directory 判断目录是否存在
• write_file 创建源码文件，写入前创建 Git 还原点并请求确认
• write_file 创建测试文件
• run_command 主动运行测试命令
• 如果失败，继续 read_file、edit_file 或 multi_edit 修复

最终输出：

• 创建了哪些文件
• 运行了什么命令
• 测试是否通过
• 如果有 token usage，会显示本次和累计费用

3. 调试报错

用户输入：

运行当前测试，如果失败，请定位报错原因并自动修复，直到测试通过。

Agent 会自动执行：

• run_command 运行测试
• 读取 stderr/stdout
• read_file 读取相关源码或测试
• edit_file 或 multi_edit 修复
• 再次 run_command 验证

最终输出：

• 原始报错摘要
• 根因分析
• 修改了哪些代码
• 最终测试结果

4. 搜索并重构代码

用户输入：

搜索所有使用 ChangeTracker 的地方，把相关命名和注释整理得更清晰。如果需要改多个位置，使用批量编辑并保持测试通过。

Agent 会自动执行：

• search_files 搜索 ChangeTracker
• search_filenames 定位相关文件
• read_file 查看上下文
• multi_edit 对单文件多个位置做原子替换
• 如果涉及多个文件，则逐个校验后修改
• run_command 运行验证

最终输出：

• 命中的文件和行号
• 重构思路
• 修改清单
• 验证命令和结果

5. Git 工作流

用户输入：

查看当前 Git 状态和 diff，总结改动。如果没有问题，请用 conventional commit 格式提交。

Agent 会自动执行：

• git_status 查看工作区状态
• git_diff 查看未提交修改
• git_log 了解最近提交风格
• 总结改动
• git_commit 提交，提交前会请求 Level 3 确认

最终输出：

• 当前分支和工作区状态
• diff 摘要
• 提交信息
• commit hash

CLI 命令

| 命令 | 作用 | |---|---| | /help | 查看帮助 | | /model flash | 切换到 deepseek-v4-flash | | /model pro | 切换到 deepseek-v4-pro | | /think on / /think off | 开关 thinking | | /history | 查看最近 10 个 session | | /resume | 恢复上一段 session | | /undo | 基于 Git 还原点撤销上一次 DeepCode 文件改动 | | /cost | 查看当前 CLI 会话累计 token 成本 | | /config | 查看当前有效配置，API Key 会打码 | | /tools | 查看当前所有工具 | | /context | 查看注入给模型的项目上下文 | | /init | 生成 DEEPCODE.md 项目说明模板 | | /clear | 清空当前对话历史 | | /exit | 退出 |

工具清单

| 工具 | 权限等级 | 说明 | |---|---:|---| | read_file | Level 1 | 读取工作区内文件 | | list_directory | Level 1 | 列目录树，遵守 .deepcodeignore | | search_files | Level 1 | 正则搜索文件内容 | | search_filenames | Level 1 | 正则搜索文件名或相对路径 | | git_status | Level 1 | 查看 Git 状态 | | git_diff | Level 1 | 查看未提交 diff | | git_log | Level 1 | 查看最近提交 | | write_file 新建 | Level 2 | 首次确认后同类自动 | | edit_file | Level 2 | 精确替换 | | multi_edit | Level 2 | 批量精确替换 | | run_command 白名单命令 | Level 1 | 自动执行 | | run_command 非白名单命令 | Level 3 | 每次确认 | | write_file 覆写 | Level 3 | 每次确认 | | git_commit | Level 3 | 每次确认 | | 危险命令或系统路径 | Level 4 | 永远拒绝 |

DEEPCODE.md 配置详解

DEEPCODE.md 是项目级说明文件，放在项目根目录。DeepCode 启动时会读取它，并把内容注入模型上下文。它适合写：

• 项目技术栈
• 常用命令
• 编码规范
• 不要触碰的文件
• 测试约定
• 项目级模型配置
• 命令白名单

完整格式：

---
model: flash
thinking: false
maxToolRounds: 8
compressionThresholdTokens: 80000
commandWhitelist:
  - node
  - pnpm
  - git status
  - git diff
---

# Project Notes

## Project

- Name: your-project
- Purpose: Describe the project.

## Tech Stack

- Add frameworks, languages, database, services.

## Common Commands

- `pnpm build`
- `pnpm test`

## Coding Rules

- Follow existing style.
- Read files before editing.

## Safety Notes

- Do not edit generated files.
- Do not run destructive commands.

生成模板：

npm start -- --init

或在 CLI 中：

/init

示例：电商网站项目

---
model: pro
thinking: true
maxToolRounds: 12
commandWhitelist:
  - node
  - pnpm
  - pnpm build
  - pnpm test
  - git status
  - git diff
  - git log
---

# Project Notes

## Project

- Name: storefront
- Purpose: B2C 电商网站，包含商品列表、购物车、订单和支付流程。

## Tech Stack

- Next.js 14
- TypeScript
- Tailwind CSS
- Prisma
- PostgreSQL
- Stripe

## Common Commands

- `pnpm dev`
- `pnpm build`
- `pnpm test`
- `pnpm lint`

## Coding Rules

- React 组件使用函数组件和 Hooks。
- 文件命名使用 kebab-case。
- API route 必须校验输入。
- 修改 checkout、payment、order 相关代码前先读取现有测试。

## Safety Notes

- 不要修改生产支付密钥。
- 不要删除 migration。
- 不要跳过订单金额校验。

## Testing Notes

- UI 改动运行 `pnpm test`。
- 支付流程改动至少运行 checkout 相关测试。

示例：Python 后端项目

---
model: pro
thinking: true
maxToolRounds: 10
commandWhitelist:
  - python
  - pytest
  - pip
  - git status
  - git diff
  - git log
---

# Project Notes

## Project

- Name: inventory-api
- Purpose: 库存管理后端，提供商品、仓库、库存同步 API。

## Tech Stack

- Python 3.12
- FastAPI
- SQLAlchemy
- PostgreSQL
- pytest

## Common Commands

- `pytest`
- `pytest tests/test_inventory.py`
- `python -m app.main`

## Coding Rules

- API 层只处理请求和响应，不写业务逻辑。
- 业务逻辑放在 service 层。
- 数据访问放在 repository 层。
- 每个 bug fix 至少补一个 pytest 用例。

## Safety Notes

- 不要修改线上数据库连接字符串。
- 不要执行删除数据库或清空表的命令。
- migration 需要用户明确要求才可修改。

## Testing Notes

- 默认运行 `pytest`。
- 如果只改库存逻辑，优先运行 `pytest tests/test_inventory.py`。

项目感知与忽略规则

.deepcodeignore 控制 DeepCode 忽略哪些文件和目录。它会影响：

• list_directory
• search_files
• search_filenames
• 项目树上下文快照

示例：

node_modules
dist
.git
.deepcode
.deepcode-demo
.next
coverage
.turbo

权限与安全

DeepCode 使用四级权限：

• Level 1：自动执行，只读工具和白名单命令。
• Level 2：首次确认后同类自动，例如新建文件、编辑文件、批量编辑。
• Level 3：每次确认，例如非白名单命令、覆写文件、git_commit。
• Level 4：永远拒绝，例如 rm -rf、format、del /s、系统目录操作。

验证

npm run typecheck
npm run build
npm run test:unit
npm run test:integration
npm run smoke

FAQ

API Key 怎么申请？新用户有多少免费额度？

去 platform.deepseek.com 注册并创建 API Key。新用户通常会有平台赠送的体验额度，但具体额度、有效期和计费规则可能变化，请以 DeepSeek 控制台为准。

支持哪些操作系统？

已在 Windows 11 + PowerShell 和 macOS 上验证（构建、测试、CLI 启动均通过）。只要有 Node.js 20+，Linux 同样可用。路径、全局配置目录和危险路径防护都做了跨平台处理。

如何升级到最新版本？

如果是本地源码：

git pull
npm install
npm run build

如果未来从 npm 安装：

npm install -g @bakblake/deepcode@latest

遇到网络错误怎么办？

检查：

• DeepSeek API Key 是否正确
• 网络是否能访问 https://api.deepseek.com
• 账户余额或赠送额度是否可用
• 是否存在代理、防火墙或公司网络限制

如何查看 token 消耗和费用？

每次 DeepSeek API 返回 usage 时，终端会显示：

[usage] cache hit ... / miss ... / output ... tokens | cost ¥... | total ¥...

也可以输入：

/cost

Windows 中文乱码怎么解决？

在 PowerShell 中执行：

[Console]::OutputEncoding = [Text.Encoding]::UTF8
$env:LANG = "zh_CN.UTF-8"

建议使用 Windows Terminal。

和 Claude Code / Aider 的区别是什么？

DeepCode 的目标是成为 DeepSeek 原生的终端 coding agent：

• 更贴近 DeepSeek API、成本和模型特性。
• 内置人民币成本统计。
• 支持项目级 DEEPCODE.md 和 .deepcodeignore。
• 权限系统和 session 持久化从一开始就作为核心能力。
• 当前仍是原型，UI、生态、稳定性和成熟度还不如 Claude Code / Aider。

English

Installation

DeepCode needs Node.js 20+ and runs on Windows, macOS, and Linux.

git clone https://github.com/jiucai0915-sys/deepcode.git
cd deepcode
npm install
npm run build
npm start

pnpm also works: pnpm install && pnpm build && pnpm start.

On Windows PowerShell the commands are the same; only the directory path differs (cd path\to\deepcode).

To initialize project notes in a new project:

npm start -- --init

First-Time Configuration

DeepCode uses the DeepSeek API. Create an API key at platform.deepseek.com. New users usually receive trial credits, but the exact amount, expiration, and billing rules may change. Always check the DeepSeek console for the current quota.

DeepCode supports three configuration methods.

Method 1: interactive setup on first launch.

npm start

If no global config exists, DeepCode prompts:

DeepSeek API Key:

After you enter the key, DeepCode saves it to the global config file:

macOS / Linux:  ~/.deepcode/config.json
Windows:        %USERPROFILE%\.deepcode\config.json

Method 2: set DEEPSEEK_API_KEY.

macOS / Linux:

export DEEPSEEK_API_KEY="sk-your-api-key"
npm start

Windows PowerShell:

$env:DEEPSEEK_API_KEY = "sk-your-api-key"
npm start

If the global config file does not exist yet, DeepCode imports this environment variable into the global config during first launch. Existing global config still has priority.

Method 3: edit the global config file directly.

File path:

macOS / Linux:  ~/.deepcode/config.json
Windows:        %USERPROFILE%\.deepcode\config.json

Example global config:

{
  "apiKey": "sk-your-api-key",
  "baseURL": "https://api.deepseek.com",
  "model": "deepseek-v4-flash",
  "thinking": false,
  "maxTokens": 8192,
  "maxToolRounds": 8,
  "compressionThresholdTokens": 80000,
  "commandWhitelist": [
    "node",
    "npm",
    "pnpm",
    "npx",
    "tsc",
    "git status",
    "git diff",
    "git log",
    "git branch",
    "dir",
    "ls",
    "cat",
    "type"
  ]
}

Configuration priority:

1. CLI flags
2. YAML front matter in DEEPCODE.md
3. ~/.deepcode/config.json
4. Built-in defaults

Tutorial

1. Understand a Project

User prompt:

Inspect this project structure, read package.json and README.md, then explain what this project does and what the core modules are.

The agent will automatically run:

• list_directory to inspect the project tree
• read_file for package.json
• read_file for README.md
• Project-context analysis

Final output:

• Project purpose
• Tech stack
• CLI entry point
• Core modules such as agent, tools, config, security, project, and llm
• Suggested next steps

2. Build and Validate a Feature

User prompt:

Create add, multiply, and safeDivide in src/utils/math.ts, add a Node assert test, and run the test until it passes.

The agent will automatically run:

• list_directory to check whether target directories exist
• write_file to create the source file, with a Git restore point before modification
• write_file to create the test file
• run_command to run the test
• If the test fails, read_file, edit_file, or multi_edit to repair it

Final output:

• Files created
• Commands executed
• Whether validation passed
• Token usage and cost when the DeepSeek API returns usage data

3. Debug an Error

User prompt:

Run the current tests. If they fail, find the cause and fix it until the tests pass.

The agent will automatically run:

• run_command to execute the test command
• stdout/stderr analysis
• read_file for relevant source or test files
• edit_file or multi_edit to fix the issue
• run_command again to verify

Final output:

• Original error summary
• Root-cause analysis
• Files changed
• Final test result

4. Search and Refactor Code

User prompt:

Search for every ChangeTracker usage and clean up related naming and comments. Use batch edits where appropriate and keep tests passing.

The agent will automatically run:

• search_files for ChangeTracker
• search_filenames to locate related files
• read_file to inspect context
• multi_edit for batch replacements
• run_command for validation

Final output:

• Matched files and line numbers
• Refactor plan
• Change list
• Validation command and result

5. Git Workflow

User prompt:

Inspect Git status and diff, summarize the changes, and commit them with a conventional commit message if everything looks good.

The agent will automatically run:

• git_status to inspect the working tree
• git_diff to inspect uncommitted changes
• git_log to learn recent commit style
• Change summary generation
• git_commit, with Level 3 confirmation before committing

Final output:

• Current branch and working-tree status
• Diff summary
• Commit message
• Commit hash

Commands

• /help: show help
• /model flash|pro|<name>: switch model
• /think on|off: toggle thinking
• /history: list recent sessions
• /resume: resume the previous session
• /undo: undo the last DeepCode file change using a Git restore point
• /cost: show cumulative token cost
• /config: show effective config with secrets masked
• /tools: list available tools
• /context: show injected project context
• /init: create a DEEPCODE.md template
• /clear: clear conversation history
• /exit: exit

DEEPCODE.md

DEEPCODE.md is a project-level context file located at the project root. It tells DeepCode about the project stack, commands, conventions, safety rules, and model preferences.

It is useful for:

• Project stack and architecture notes
• Common commands
• Coding conventions
• Files the agent should avoid
• Testing expectations
• Project-level model settings
• Command whitelist entries

Complete format:

---
model: flash
thinking: false
maxToolRounds: 8
compressionThresholdTokens: 80000
commandWhitelist:
  - node
  - pnpm
  - git status
  - git diff
---

# Project Notes

## Project

- Name: your-project
- Purpose: Describe the project.

## Tech Stack

- Add frameworks, languages, database, services.

## Common Commands

- `pnpm build`
- `pnpm test`

## Coding Rules

- Follow existing style.
- Read files before editing.

## Safety Notes

- Do not edit generated files.
- Do not run destructive commands.

Generate one with:

npm start -- --init

Or inside the CLI:

/init

Example: E-Commerce Website

---
model: pro
thinking: true
maxToolRounds: 12
commandWhitelist:
  - node
  - pnpm
  - pnpm build
  - pnpm test
  - git status
  - git diff
  - git log
---

# Project Notes

## Project

- Name: storefront
- Purpose: B2C e-commerce website with product listing, cart, checkout, orders, and payment flow.

## Tech Stack

- Next.js 14
- TypeScript
- Tailwind CSS
- Prisma
- PostgreSQL
- Stripe

## Common Commands

- `pnpm dev`
- `pnpm build`
- `pnpm test`
- `pnpm lint`

## Coding Rules

- Use function components and Hooks for React components.
- Use kebab-case file names.
- Validate input in API routes.
- Read existing tests before changing checkout, payment, or order code.

## Safety Notes

- Do not edit production payment secrets.
- Do not delete migrations.
- Do not bypass order amount validation.

## Testing Notes

- Run `pnpm test` for UI changes.
- For payment-flow changes, run checkout-related tests at minimum.

Example: Python Backend

---
model: pro
thinking: true
maxToolRounds: 10
commandWhitelist:
  - python
  - pytest
  - pip
  - git status
  - git diff
  - git log
---

# Project Notes

## Project

- Name: inventory-api
- Purpose: Inventory-management backend that provides product, warehouse, and stock-sync APIs.

## Tech Stack

- Python 3.12
- FastAPI
- SQLAlchemy
- PostgreSQL
- pytest

## Common Commands

- `pytest`
- `pytest tests/test_inventory.py`
- `python -m app.main`

## Coding Rules

- API layer should only handle request and response logic.
- Business logic belongs in the service layer.
- Data access belongs in the repository layer.
- Every bug fix should add at least one pytest case.

## Safety Notes

- Do not edit production database connection strings.
- Do not run database deletion or table-truncation commands.
- Only edit migrations when the user explicitly asks.

## Testing Notes

- Run `pytest` by default.
- If only inventory logic changed, prefer `pytest tests/test_inventory.py`.

FAQ

How do I get an API key? Is there a free quota?

Create an account and API key at platform.deepseek.com. Trial credits are commonly available for new users, but the exact quota can change. Check the DeepSeek console for the latest amount and billing rules.

Which operating systems are supported?

DeepCode is verified on Windows 11 + PowerShell and macOS (build, tests, and CLI launch all pass). It also runs on Linux with Node.js 20+. Path handling, the global config directory, and dangerous-path protection are all cross-platform.

How do I upgrade?

From source:

git pull
npm install
npm run build

From npm once published:

npm install -g @bakblake/deepcode@latest

What if I see network errors?

Check your API key, network access to https://api.deepseek.com, account balance/trial credits, and proxy/firewall settings.

How do I see token usage and cost?

DeepCode prints usage when the API returns it. You can also run:

/cost

How do I fix Chinese mojibake on Windows?

Use Windows Terminal and run:

[Console]::OutputEncoding = [Text.Encoding]::UTF8
$env:LANG = "zh_CN.UTF-8"

How is DeepCode different from Claude Code or Aider?

DeepCode is designed around DeepSeek models and pricing. It emphasizes terminal-native coding, project notes, .deepcodeignore, RMB cost reporting, permission levels, Git-aware undo, and session persistence. It is still an early prototype and not yet as mature as Claude Code or Aider.