deepcraft-agent 0.30.0

DeepSeek-powered AI coding agent — SubAgent with timeout, retry, validation

DeepCraft

多 Provider AI Coding Agent — Claude Code 开源替代，轻量、高效、可扩展。

为什么用 DeepCraft

特性	DeepCraft	Claude Code
大模型	DeepSeek / OpenAI / Anthropic / Ollama	Claude only
协议	标准 MCP + Skills + A2A	MCP + 自定义
依赖	零 MCP 第三方库	heavy SDK
开源	MIT	闭源
代码量	~14,000 行（65 个 Python 文件）	数万行
记忆	长期记忆 + 跨会话记忆（BM25 检索 + 时效衰减）	单 session
多 Agent	route / pipeline / broadcast	❌

四层架构

┌─────────────────────────────────────┐
│ A2A：多 Agent 协作引擎              │  ← route / pipeline / broadcast
├─────────────────────────────────────┤
│ Skills：Markdown 知识注入           │  ← 领域知识
├─────────────────────────────────────┤
│ MCP：JSON-RPC 远程工具              │  ← 能力扩展
├─────────────────────────────────────┤
│ Function Call：ReAct 本地工具       │  ← 基础调用
└─────────────────────────────────────┘

快速开始

安装

pip install deepcraft-agent        # PyPI
# 或
git clone https://github.com/liyuan1161/deepcraft.git
cd deepcraft && pip install -e ".[dev]"
# 或 macOS：下载 DMG 拖到 Applications 双击即用 🍎

配置

export DEEPSEEK_API_KEY=sk-your-key-here

# 可选：多 Provider
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

运行

# 交互 REPL
deepcraft

# 单次任务
deepcraft run "搜索 GitHub 上 deepcraft 的仓库"

# Web UI + SSE 流式 API
deepcraft serve --port 8000

能力矩阵

能力	状态	版本
ReAct 循环（流式 + Function Call）	✅	v0.1
MCP 协议（手写 JSON-RPC 2.0，零依赖）	✅	v0.2
Skills 系统（Markdown 知识注入）	✅	v0.2
Plan-Execute 模式 + SelfCorrector 纠错	✅	v0.3
SubAgent 并行委派 + 安全三道防线	✅	v0.3
三层上下文压缩	✅	v0.4
会话录制/回放	✅	v0.5
长期记忆系统（跨 session 持久化）	✅	v0.6
多 Provider 切换 + A2A 多 Agent 协作	✅	v0.7
Web UI + SSE 流式 API	✅	v0.8
Web Search + Diff 精确编辑	✅	v0.9
代码库索引（AST 扫描 + 缓存）	✅	v0.10
Prompt 缓存层级（fixed/session/sliding）	✅	v0.11
Docker 沙箱（Safe/Whitelist/Offline 模式）	✅	v0.12
RAG 知识库（语义分块 + TF-IDF 检索）	✅	v0.13
测试自动生成（pytest 骨架）	✅	v0.14
自主执行模式（Plan→Execute→Report）	✅	v0.15
原子重构（多文件变更 + 失败全量回滚）	✅	v0.16
符号导航（跳转定义/引用/重命名/悬停）	✅	v0.17
可视 Diff 引擎（unified/并排/git diff）	✅	v0.18
PR 工作流（create/list/status/merge）	✅	v0.19
Code Review 引擎（规则 + Agent 审查）	✅	v0.20
BM25 语义搜索（升级 TF-IDF）	✅	v0.21
跨会话记忆（LLM 提取 + BM25 检索 + 时效衰减）	✅	v0.22
对话分支（保存/切换/对比上下文路径）	✅	v0.23
上下文感知型智能体（环境自适应）	✅	v0.24
多轮对话优化 + 工具调用稳定性	✅	v0.25
UX 优化（工具透明化/启动并行化/上下文预警/语义索引缓存）	✅	v0.26
Tab 补全（命令/文件路径）+ System Prompt 重构	✅	v0.27
Skills 可见化 + 会话摘要 + Git 染色 + Monaco 离线 + 终端 stdin	✅	v0.28

REPL 命令

会话管理

命令	说明
/quit /exit /q	退出
/help	显示全部命令
/clear	清除对话历史
/status	Token 用量、工具数、模式、轮次
/cache	显示 Prompt 缓存层级与预算

模式切换

命令	说明
/mode react	ReAct 模式（默认）
/mode plan	Plan-Execute 模式
/mode sub	SubAgent 并行委派
/mode auto	关键词自动选择（推荐）

文件操作

命令	说明
read_file(path)	读取文件
write_file(path, content)	写入文件
search_files(pattern)	搜索文件内容或文件名

代码分析与导航

命令	说明
/diff <file> [vs_file]	Unified diff（与 HEAD 对比或两文件对比）
/diff-side <a> <b>	并排 diff 视图
/diff-review	展示所有未提交变更
/def <symbol>	跳转到符号定义
/refs <symbol>	查找所有引用（最多 30 条）
/rename <old> <new>	跨文件重命名
/hover <file:line>	查看符号签名与文档
/index	显示代码库索引统计

重构

命令	说明
/refactor <描述>	原子重构：输入变更 → 预览 → 确认执行，失败全量回滚
/checkpoint	手动保存文件快照
/rollback [N]	回滚到第 N 号快照
/checkpoints	列出所有快照

搜索与知识

命令	说明
/search <query>	BM25 语义搜索
/search index <id> <content>	索引单个文档
/search stats	显示索引统计
/knowledge	查看知识库状态
/knowledge add <path>	添加文档到 RAG 知识库
/knowledge search <query>	搜索知识库（TF-IDF + 语义分块）
/knowledge clear	清空知识库

记忆系统

命令	说明
/mem search <query>	搜索跨会话记忆（BM25 + 时效衰减）
/mem save <key> <value>	保存记忆事实
/mem stats	显示记忆统计
/mem consolidate	去重与合并记忆
/memory save <key> <value>	保存长期记忆（持久化文件）
/memory search <query>	搜索长期记忆
/memory list	列出所有长期记忆
/memory clear	清除所有长期记忆

PR 工作流

命令	说明
/pr create <title>	从当前分支创建 PR
/pr list [open|closed|all]	列出 PR
/pr status <N>	查看 PR CI 状态
/pr merge <N> [squash|merge|rebase]	合并 PR

Code Review

命令	说明
/review pr <N>	交互式 PR 审查（逐文件）
/review approve <N> [msg]	批准 PR
/review comment <N> <file:line> <msg>	行级评论
/review request-changes <N> <msg>	请求修改
/review summary <N>	快速审查摘要

多 Agent 协作

命令	说明
/agent list	列出 Agent 节点
/agent create <name> <role>	创建节点
/agent run <name> <task>	在节点上执行任务
/mesh route <task>	自动路由到最优 Agent
/mesh pipeline a,b <task>	链式执行 (a → b)
/mesh broadcast a,b <task>	并行执行

MCP

命令	说明
/mcp	列出已连接 MCP Server
/mcp connect <name> <command|url>	动态连接 MCP Server

测试

命令	说明
/test-gen <path>	自动生成 pytest 测试骨架

Docker 沙箱

命令	说明
/sandbox run <cmd>	在 Docker 沙箱中执行命令
/sandbox status	显示沙箱状态
/sandbox mode <mode>	切换沙箱模式（default/restricted/offline）

导出与回放

命令	说明
/export md [path]	导出对话为 Markdown
/export json [path]	导出对话为 JSON
/record start	开始会话录制
/record stop	停止录制
/record status	查看录制状态
/replay <path>	回放已录制的会话

自主执行

命令	说明
/auto <task>	自主执行：Planner → 循环执行 → 生成报告

Builtin Skills

Agent 根据对话内容自动激活对应技能：

Skill	触发词	内容
code_review	代码审查、code review	四维审查（安全/性能/质量/可维护）
python_style	python 规范、type hints	PEP 8、类型标注、Pythonic
git_workflow	git 工作流、commit	分支策略、提交格式、PR 规范
api_design	api 设计、REST	URL/状态码/分页/认证
testing	测试、pytest	fixture/mock/async/覆盖率

项目结构

├── cli.py                    # CLI 入口（click）
├── config.py                 # 配置管理（env + YAML）
├── config_cli.py             # config 子命令（list/get/set）
├── memory.py                 # 长期记忆系统
├── agent/
│   ├── loop.py               # ReAct 主循环（295 行）
│   ├── repl.py               # REPL 交互界面（1,275 行 / 56 条命令）
│   ├── llm.py                # DeepSeek API 封装（78 行）
│   ├── context.py            # 上下文 + Token 压缩
│   ├── types.py              # 共享类型定义
│   ├── planner.py            # Plan-Execute 模式
│   ├── corrector.py          # SelfCorrector 自动纠错
│   ├── subagent.py           # 子代理并行委派
│   ├── autonomous.py         # 自主执行模式
│   ├── mesh.py               # A2A 多 Agent 协作
│   ├── modes.py              # 模式自动选择
│   ├── github_client.py      # GitHub REST API 客户端
│   ├── code_index.py         # 代码库索引（AST + 缓存）
│   ├── prompt_cache.py       # Prompt 缓存层级
│   ├── symbol_index.py       # 符号索引
│   ├── refactor.py           # 原子重构引擎
│   ├── diff_view.py          # Diff 视图引擎
│   ├── code_review.py        # Code Review 引擎
│   ├── pr_workflow.py        # PR 工作流
│   ├── semantic_search.py    # BM25 语义搜索
│   ├── session_memory.py     # 跨会话记忆
│   ├── knowledge.py          # RAG 知识库
│   ├── test_gen.py           # 测试自动生成
│   ├── sandbox.py            # Docker 沙箱
│   ├── mcp/
│   │   ├── client.py         # MCP JSON-RPC Client（400 行手写）
│   │   └── http_client.py    # HTTP/SSE 传输
│   ├── skills/
│   │   └── loader.py         # Skills 加载器（164 行）
│   └── tools/                # 28 个工具类
│       ├── base.py           # BaseTool + ToolRegistry
│       ├── file.py           # 文件读写搜索
│       ├── terminal.py       # 终端沙箱
│       ├── git_tool.py       # Git 操作
│       ├── web_search.py     # Web 搜索 + 页面抓取
│       ├── search_replace.py # Diff 精确编辑
│       ├── refactor.py       # 原子重构工具
│       ├── symbol_nav.py     # 符号导航工具
│       ├── diff_view.py      # Diff 可视化工具
│       ├── pr_tools.py       # PR 工作流工具
│       ├── code_review.py    # Code Review 工具
│       ├── semantic_search.py# BM25 搜索工具
│       ├── session_memory.py # 跨会话记忆工具
│       ├── knowledge.py      # 知识库工具
│       ├── test_gen.py       # 测试生成工具
│       ├── sandbox.py        # 沙箱工具
│       └── checkpoint.py     # 快照回滚工具
├── providers/                # 多 Provider 适配
│   ├── deepseek.py           # DeepSeek
│   ├── openai.py             # OpenAI
│   ├── anthropic.py          # Anthropic (Claude)
│   └── ollama.py             # Ollama 本地模型
├── session/                  # 会话录制/回放
├── server/                   # Web UI + SSE API
│   ├── app.py                # FastAPI 应用
│   └── runner.py             # Agent → SSE 事件流
├── static/
│   └── index.html            # 暗色主题 Web UI
├── tests/                    # 58 个测试用例
├── docs/                     # 23 篇文章 + 使用手册
├── packaging/                # macOS 安装程序
│   └── macos/                # DMG + .app 构建
└── examples/                 # MCP demo

质量

ruff   ✅ All checks passed (0 issues)
mypy   ✅ strict mode, 0 issues
pytest ✅ 58/58 passed

文档

📖 完整命令速查 → docs/USAGE.md

系列文章（~75,000 字）：

#	文章	一句话
1	Agent 架构全景	看懂 Agent
2	代码实战拆解	写出 Agent
3	高级自治能力	升级 Agent
4	MCP 协议实战	扩展 Agent
5	Skills 系统设计	武装 Agent
6	安全设计与沙箱	守护 Agent
7	工程化实践	铸剑 Agent
8	上下文压缩	减负 Agent
9	长期记忆系统	记忆 Agent
10	A2A 多 Agent 协作	协作 Agent
11	全面回顾	回望 Agent
12	对话分支	分叉 Agent
13	UX 优化	打磨 Agent
14	Tab 补全	加速 Agent
15	Skills + IDE	升维 Agent

📖 完整书籍 (PDF) · 版本日志 · 路线图

作者

元哥（liyuan1161） — 全栈工程师，10 年+ 一线研发经验。

经历	角色	领域
🛡️ Glazero	智能监控	AI 安全
☁️ 腾讯云	T11 工程师	云计算基础设施
🚗 滴滴出行	资深研发工程师	智能出行
🎬 优酷大文娱	技术专家	音视频

深耕方向： 智能监控 · 智能出行 · 音视频技术 · LLM Agent
技术栈： Python / Go / 分布式系统 / AI Agent 架构
📧 [e-mail] · 🐙 github.com/liyuan1161

License

MIT — liyuan1161