Metadata-Version: 2.4
Name: deepcraft-agent
Version: 0.33.0
Summary: DeepCraft — an autonomous LLM-powered coding agent with builtin skills, REPL, checkpoint/rollback, semantic search, sub-agent delegation, Docker sandbox, and browser-based Web IDE.
Author-email: liyuan <liyuan116@gmail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License: MIT
Project-URL: Homepage, https://github.com/liyuan1161/deepcraft
Project-URL: Repository, https://github.com/liyuan1161/deepcraft
Project-URL: Issues, https://github.com/liyuan1161/deepcraft/issues

# DeepCraft

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

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![ruff](https://img.shields.io/badge/ruff-0-ok)](https://github.com/astral-sh/ruff)
[![mypy](https://img.shields.io/badge/mypy-strict-ok)](https://mypy-lang.org/)
[![pytest](https://img.shields.io/badge/pytest-58%2F58-green)](https://pytest.org)
[![lines](https://img.shields.io/badge/lines-14,000-blue)]()

## 为什么用 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 本地工具       │  ← 基础调用
└─────────────────────────────────────┘
```

## 快速开始

### 安装

```bash
pip install deepcraft-agent        # PyPI
# 或 Homebrew
brew tap liyuan1161/tap && brew install deepcraft-agent
# 或 macOS：下载 DMG 拖到 Applications 双击即用 🍎
# 或源码
```

### 配置

```bash
export DEEPSEEK_API_KEY=sk-your-key-here

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

### 运行

```bash
# 交互 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/覆盖率 |

## 项目结构

```\ndeepcraft/                    # 14,000 行 / 65 个 Python 文件
├── 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](docs/USAGE.md)**

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

| # | 文章 | 一句话 |
|---|------|--------|
| 1 | [Agent 架构全景](docs/agent-architecture-deep-dive.md) | 看懂 Agent |
| 2 | [代码实战拆解](docs/deepcraft-implementation-deep-dive.md) | 写出 Agent |
| 3 | [高级自治能力](docs/deepcraft-advanced-autonomy.md) | 升级 Agent |
| 4 | [MCP 协议实战](docs/deepcraft-mcp-protocol.md) | 扩展 Agent |
| 5 | [Skills 系统设计](docs/deepcraft-skills-system.md) | 武装 Agent |
| 6 | [安全设计与沙箱](docs/deepcraft-security-design.md) | 守护 Agent |
| 7 | [工程化实践](docs/deepcraft-engineering-practices.md) | 铸剑 Agent |
| 8 | [上下文压缩](docs/deepcraft-context-compression.md) | 减负 Agent |
| 9 | [长期记忆系统](docs/deepcraft-memory-system.md) | 记忆 Agent |
| 10 | [A2A 多 Agent 协作](docs/deepcraft-a2a-multi-agent.md) | 协作 Agent |
| 11 | [全面回顾](docs/deepcraft-retrospective.md) | 回望 Agent |
| 12 | [对话分支](docs/v0.23-branching.md) | 分叉 Agent |
| 13 | [UX 优化](docs/v0.26-ux-polish.md) | 打磨 Agent |
| 14 | [Tab 补全](docs/v0.27-tab-completion.md) | 加速 Agent |
| 15 | [Skills + IDE](docs/v0.28-skills-ide.md) | 升维 Agent |

📖 [完整书籍 (PDF)](docs/deepcraft.pdf) · [版本日志](CHANGELOG.md) · [路线图](docs/ROADMAP.md)

## 作者

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

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

**深耕方向：** 智能监控 · 智能出行 · 音视频技术 · LLM Agent  
**技术栈：** Python / Go / 分布式系统 / AI Agent 架构  
📧 liyuan@glazero.com · 🐙 [github.com/liyuan1161](https://github.com/liyuan1161)

## License

MIT — [liyuan1161](https://github.com/liyuan1161)

