desca — DeepSeek Vibe Coding Agent

desca（Deepseek Coding Agent）是一个面向 DeepSeek 模型生态的 终端 AI 编码助手。核心架构为单 Agent 主循环 + 工具驱动，通过 task 工具委托子 Agent 执行独立任务。

✨ 写下你的想法，desca 帮你实现。

一键安装（推荐）

curl -fsSL https://desca.opencj.cn/downloads/install | bash

安装脚本自动检测操作系统和 CPU 架构，下载最新的预编译二进制文件，安装到 ~/.desca/bin/ 并自动加入 $PATH。

然后启动 desca：

desca                          # 启动 TUI 模式
desca --help                   # 查看所有可用命令

安装特定版本：curl -fsSL https://desca.opencj.cn/downloads/install | bash -s -- --version v0.1.0
从本地二进制安装：./install --binary /path/to/desca

功能特性

🎯 Vibe Coding — 自然语言描述需求，自动完成代码搜索、方案设计、编码实现和质量验证
🤖 单 Agent 主循环 — 统一 Agent 驱动，支持 task_create 工具委托子 Agent 执行后台任务
🧠 DeepSeek 原生集成 — 基于 DeepSeek V4 模型（Flash/Pro），支持 Thinking Tokens、Prefix Cache、场景自适应参数
🖥️ OpenTUI 终端界面 — 基于 OpenTUI + SolidJS 构建，支持实时流式输出、会话管理、斜杠命令
🛠️ 工具系统 — 33 个内置工具：文件读写、代码搜索、Shell 执行、网络搜索、任务管理、交互问答、规划模式等
🔒 权限模型 — 工作目录内写操作自动放行，目录外通过 Ask 确认授权
📐 规划模式 — enter_plan_mode / exit_plan_mode 工具实现「先设计方案再动手」工作流
💾 SQLite 会话持久化 — 基于 sql.js（WASM）的会话存储，支持自动保存/恢复、重命名、搜索和上下文压缩
🧷 工具调用安全上下文 — 按完整 assistant.tool_calls + tool 响应组修复和裁剪消息历史，避免压缩后触发 Provider 400
🗜️ 离线 BPE 分词器 — 内嵌 DeepSeek V3 tokenizer.json，精确估算 token 用量
🌐 网络感知 — 内置 web_search / web_fetch 工具，支持实时信息检索
⚡ 服务端模式 — 支持以 MCP 兼容协议运行，可集成 VS Code、JetBrains 等 IDE
🧩 插件 SDK — 通过 plugin-sdk 包扩展 desca 功能

架构概览

desca/                          # TypeScript monorepo (pnpm workspaces)
├── apps/
│   ├── bot-cli/                # 旧版 CLI (GatewayClient RPC)
│   ├── desca-cli/              # CLI 入口 (bin/desca)
│   ├── server/                 # MCP 兼容服务端模式
│   ├── tui/                    # OpenTUI + SolidJS 终端 UI
│   └── web/                    # Web 前端 (Vite)
├── packages/
│   ├── agent/                  # 单 Agent 主循环 + 任务系统
│   ├── config/                 # 配置加载 + 模型注册表
│   ├── cost/                   # Token 用量追踪
│   ├── llm/                    # LLM Provider 抽象层
│   ├── mcp/                    # MCP 协议实现
│   ├── protocol/               # 共享协议类型
│   ├── session/                # SQLite 会话持久化 (sql.js)
│   ├── skills/                 # 技能管理系统
│   ├── tokenizer/              # DeepSeek V3 BPE 离线分词器
│   └── tools/                  # 33 个内置工具 + ToolRegistry
├── openclaw/                   # Agent 运行时 + 插件生态
│   ├── src/                    # 核心运行时，通道，MCP，LLM，工具，TUI
│   └── packages/               # ACP，agent-core，llm-core，plugin-sdk 等
├── docs/
│   ├── CODING_GUIDE.md         # 完整开发指引
│   ├── MODEL_PROVIDERS.md      # 模型 Provider 配置指南
│   ├── models.json             # 模型注册表数据
│   └── DEEPSEEK_OFFICIAL_DOCS.md
├── AGENTS.md                   # AI Agent 工作指令（权威指南）
├── CLAUDE.md                   # AI Agent 上下文文件
└── version.ts                  # 版本定义

包依赖关系

apps/
├── bot-cli → config, protocol
├── desca-cli → agent, config, llm, protocol
├── server  → agent, config, llm, mcp, protocol, session, skills, tools
├── tui     → agent, config, llm, session, tools
└── web     → (Vite 独立)

packages/
├── agent   → config, cost, llm, tokenizer, tools
├── config  → (独立，嵌入 models_entry.json)
├── cost    → config, tokenizer
├── llm     → config
├── mcp     → (独立)
├── protocol→ (独立)
├── session → sql.js
├── skills  → (独立)
├── tokenizer→ (独立，嵌入 tokenizer.json)
└── tools   → llm, skills

核心流程

用户输入
  → Agent.Stream(input, projectContext)
    → 构建消息：[system: 静态提示] + [context: 项目文档] + [user: 时间+目录] + [对话历史]
    → LLM.Stream() 流式响应
      ├─ 输出 reasoning → 实时推送
      ├─ 输出 text → 实时推送
      └─ 输出 tool_calls → 执行工具
        → DeepSeek thinking 模式下随 tool_calls 回放 assistant reasoning_content
        → 只读工具并行执行，写操作工具串行执行
        → stormBreaker 滑动窗口去重（6 轮窗口 ≥3 次抑制）
        → 工具结果按完整工具调用事务追加到消息历史 → 回到 LLM 调用（最多 50 轮）
    → 无 tool_calls → 输出最终回复（会话通过 SQLite 持久化）
    → 有待办未完成且持续进展 → 自动继续（最多 +10 轮）
    → 连续 2 轮无进展 → 放弃

快速开始

前置要求

Node.js 20 或更高版本
pnpm 10.22 或更高版本

安装与运行

# 克隆仓库
git clone https://github.com/ChangedenCZD/desca.git
cd desca

# 安装依赖
pnpm install

# 构建所有包
pnpm build

# 运行 CLI 模式
pnpm desca

# 运行 TUI 模式
pnpm tui

# 运行服务端模式 (MCP)
pnpm server

配置 API Key

# 必填：DeepSeek API Key
export DEEPSEEK_API_KEY=sk-your-api-key-here

配置持久化到 ~/.desca/settings.json（权限 0600）。

开发指南

常用命令

pnpm build                      # 构建所有包和应用
pnpm typecheck                  # TypeScript 类型检查
pnpm test                       # 构建 + 运行测试 (vitest)
pnpm clean                      # 清理构建产物
pnpm desca                      # 运行 CLI 模式
pnpm desca:build                # 构建发行版 (bash)
pnpm desca:build:single         # 构建单文件发行版
pnpm desca:build:skip-web       # 跳过 Web 资源构建
pnpm tui                        # 运行 TUI
pnpm tui:dev                    # TUI 开发模式 (tsx watch)
pnpm server                     # 运行服务端
pnpm web                        # 运行 Web 前端
pnpm web:build                  # 构建 Web 前端
pnpm smoke                      # 冒烟测试
pnpm smoke:daemon               # 守护进程冒烟测试
pnpm smoke:agent                # Agent 冒烟测试

项目结构说明

路径	说明
`apps/bot-cli/`	旧版 CLI（GatewayClient RPC 网关）
`apps/desca-cli/`	CLI 入口，提供 `desca` 命令
`apps/server/`	MCP 兼容服务端，支持 IDE 集成
`apps/tui/`	OpenTUI + SolidJS 终端 UI
`apps/web/`	Vite Web 前端
`packages/agent/`	核心 Agent 主循环、场景检测、任务系统
`packages/config/`	配置加载、模型注册表、Provider 配置
`packages/cost/`	Token 用量追踪，按小时持久化
`packages/llm/`	LLM Provider 抽象（DeepSeek/OpenAI/Anthropic/Gemini）
`packages/mcp/`	MCP 协议服务端实现
`packages/protocol/`	共享协议类型定义
`packages/session/`	SQLite 会话持久化（sql.js）
`packages/skills/`	技能管理系统（list/install/remove）
`packages/tokenizer/`	DeepSeek V3 BPE 离线分词器
`packages/tools/`	工具执行系统，33 个内置工具

核心技术栈

技术	用途
TypeScript (ES2022, NodeNext)	主要开发语言
pnpm workspaces	Monorepo 管理
OpenTUI	终端 UI 框架
SolidJS	响应式 UI 组件
sql.js	SQLite (WASM) 会话持久化
vitest	测试框架
Vite	Web 前端构建工具

配置说明

环境变量

变量	必填	说明
`DEEPSEEK_API_KEY`	是	DeepSeek API 密钥
`DEEPSEEK_BASE_URL`	否	API 基础地址，默认 `https://api.deepseek.com`

配置文件（~/.desca/settings.json）

{
  "apiKey": "sk-...",
  "timeout": 600000,
  "maxInputHistory": 20,
  "maxConcurrentLLM": 3,
  "model": {
    "model": "deepseek-v4-pro",
    "provider": "deepseek"
  }
}

支持的 LLM Provider

DeepSeek（原生 API）— 默认，端点 /chat/completions
OpenAI — OpenAI 兼容 API
Anthropic — Anthropic 兼容 API
Gemini — Google Gemini API
OpenRouter — OpenRouter 统一 API

内置工具（33）

工具	只读	核心能力
`read_file`	✅	行范围文件读取（带缓存）
`write_file`	❌	创建/覆盖文件（权限检查）
`edit_file`	❌	SEARCH/REPLACE 编辑
`search_replace`	❌	多文件批量搜索替换
`apply_patch`	❌	Unified diff 补丁应用
`glob`	✅	文件模式匹配
`grep`	✅	内容搜索（纯 Node.js 实现，无外部依赖）
`directory_tree`	✅	递归目录树
`list_directory`	✅	非递归目录列表
`blast_radius`	✅	修改影响范围分析（import 依赖图）
`list_symbols`	✅	文件符号列表（函数/类型+行号）
`find_references`	✅	符号引用搜索
`trace_callers`	✅	反向调用图追踪
`trace_callees`	✅	正向调用图追踪
`bash`	❌	Shell 命令执行
`diagnostics`	✅	编译诊断
`skill`	✅	技能加载
`remember` / `recall`	✅	跨会话记忆存储/读取
`web_search` / `web_fetch`	✅	网络搜索 + URL 内容获取
`todo_write`	✅	待办列表管理
`question`	✅	用户提问
`notify`	✅	桌面通知
`sleep`	✅	延时等待
`task`	❌	委托子 Agent 执行独立任务
`task_create`	❌	创建后台任务（bash/agent）
`task_update` / `task_list`	❌/✅	更新/列出任务
`task_output` / `task_stop`	✅/❌	读取输出/停止任务
`enter_plan_mode`	❌	进入规划模式（禁止写操作）
`exit_plan_mode`	❌	退出规划模式（恢复写权限）

贡献指南

Fork 本仓库并创建你的特性分支
编码：遵循 TypeScript 规范，所有导出符号必须有 JSDoc 注释
测试：确保 pnpm test 全部通过
类型检查：运行 pnpm typecheck 无错误
提交：遵循约定提交格式（feat: / fix: / docs: 等）
PR：提交 Pull Request，描述变更内容和动机

许可证

MIT License — 详见 LICENSE 文件。

用 ❤️ 和 DeepSeek 构建