Metadata-Version: 2.4
Name: deepcraft-agent
Version: 0.18.0
Summary: DeepCraft — DeepSeek-powered AI coding agent with tools and REPL
Author-email: liyuan <liyuan@glazero.com>
License: MIT
Requires-Python: >=3.10
Requires-Dist: openai>=1.0
Requires-Dist: rich
Requires-Dist: tiktoken
Requires-Dist: pydantic>=2.0
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: pydantic-settings
Requires-Dist: platformdirs
Project-URL: Homepage, https://github.com/liyuan1161/deepcraft
Project-URL: Repository, https://github.com/liyuan1161/deepcraft
Description-Content-Type: text/markdown

# 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)

## 为什么用 DeepCraft

| 特性 | DeepCraft | Claude Code |
|------|-----------|-------------|
| 大模型 | DeepSeek / OpenAI / Anthropic / Ollama | Claude only |
| 协议 | 标准 MCP + Skills + A2A | MCP + 自定义 |
| 依赖 | 零 MCP 第三方库 | heavy SDK |
| 开源 | MIT | 闭源 |
| 代码量 | ~4,800 行 | 数万行 |
| 记忆 | 长期记忆（文件索引 + LLM 排序） | 单 session |
| 多 Agent | route / pipeline / broadcast | ❌ |

## 四层架构

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

## 快速开始

### 安装

```bash
pip install deepcraft-agent        # PyPI
# 或
git clone https://github.com/liyuan1161/deepcraft.git
cd deepcraft && pip install -e ".[dev]"
```

### 配置

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

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

# 可选：Web UI
deepcraft serve                # → http://localhost:8000
```

### 运行

```bash
# 交互 REPL
deepcraft

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

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

### REPL 命令

| 命令 | 说明 |
|------|------|
| `/help` | 帮助 |
| `/status` | token 用量、工具数量 |
| `/mode react` | 切换 ReAct 模式 |
| `/mode plan` | 切换 Plan-Execute 模式 |
| `/mode sub` | 切换 SubAgent 模式 |
| `/mcp` | 列出 MCP 工具 |
| `/mcp connect <name> <cmd>` | 动态连接 MCP Server |
| `/memory save <key> <value>` | 保存长期记忆 |
| `/memory search <query>` | 搜索长期记忆 |
| `/record start/stop` | 录制会话 |
| `/clear` | 清除对话 |
| `/quit` | 退出 |

## 能力矩阵

| 能力 | 状态 | 版本 |
|------|:--:|:--:|
| ReAct 循环（流式 + Function Call） | ✅ | v0.1 |
| MCP 协议（手写 JSON-RPC 2.0，零依赖） | ✅ | v0.2 |
| GitHub MCP 集成（26 个工具透明调用） | ✅ | v0.2 |
| Skills 系统（Markdown 知识注入） | ✅ | v0.2 |
| Plan-Execute 模式 | ✅ | v0.3 |
| SelfCorrector 自动纠错 | ✅ | v0.3 |
| SubAgent 并行委派 | ✅ | v0.3 |
| 安全三道防线（危险命令/路径穿越/死循环） | ✅ | v0.3 |
| 模式自动选择器 | ✅ | v0.3 |
| YAML 配置系统 | ✅ | v0.3 |
| 对话 JSON 导出 | ✅ | v0.3 |
| 三层上下文压缩 | ✅ | v0.4 |
| 会话录制/回放 | ✅ | v0.5 |
| 长期记忆系统（跨 session 持久化） | ✅ | v0.6 |
| 多 Provider（DeepSeek/OpenAI/Anthropic/Ollama） | ✅ | v0.7 |
| A2A 多 Agent 协作（route/pipeline/broadcast） | ✅ | v0.7 |
| Web UI + SSE 流式 API | ✅ | v0.8 |
| Web Search 工具 | ✅ | v0.9 |
| Diff-based 精确编辑 | ✅ | v0.9 |

## 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/覆盖率 |

## 项目结构

```
deepcraft/
├── cli.py                  # CLI 入口（click）
├── config.py               # 配置管理（env + YAML）
├── config_cli.py           # config 子命令（list/get/set）
├── memory.py               # 长期记忆系统
├── agent/
│   ├── loop.py             # ReAct 主循环
│   ├── llm.py              # DeepSeek API 封装（65 行）
│   ├── context.py          # 上下文 + Token 压缩
│   ├── types.py            # 共享类型定义
│   ├── planner.py          # Plan-Execute 模式
│   ├── corrector.py        # SelfCorrector 自动纠错
│   ├── subagent.py         # 子代理并行委派
│   ├── mesh.py             # A2A 多 Agent 协作引擎
│   ├── modes.py            # 模式自动选择
│   ├── repl.py             # REPL 交互界面
│   ├── mcp/
│   │   ├── client.py       # MCP JSON-RPC Client（368 行手写）
│   │   └── http_client.py  # HTTP/SSE 传输
│   ├── skills/
│   │   └── loader.py       # Skills 加载器
│   └── tools/              # 工具系统
│       ├── base.py         # BaseTool + ToolRegistry
│       ├── file.py         # 文件读写搜索
│       ├── terminal.py     # 终端沙箱
│       ├── git_tool.py     # Git 操作
│       ├── web_search.py   # Web 搜索 + 页面抓取
│       └── search_replace.py  # Diff-based 精确编辑
├── 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/                   # 11 篇系列文章
└── examples/               # MCP demo
```

## 质量

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

## 文档

11 篇系列文章（~50,000 字）：

| # | 主题 | 一句话 |
|---|------|--------|
| 1 | [Agent 架构全景](docs/agent-architecture-deep-dive.md) | 看懂 Agent |
| 2 | [SubAgent 子代理机制](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 |

📖 [完整书籍 (PDF)](docs/deepcraft.pdf)

## 作者

**元哥（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)
