Metadata-Version: 2.4
Name: deepcraft-agent
Version: 0.1.0
Summary: DeepSeek-powered AI coding agent — Claude Code alternative
Project-URL: Homepage, https://github.com/liyuan1161/deepcraft
Project-URL: Repository, https://github.com/liyuan1161/deepcraft.git
Author-email: "元哥 (liyuan1161)" <1158084418@qq.com>
License: MIT
Keywords: ai,cli,coding-agent,deepseek,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.28
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# DeepCraft

**DeepSeek-powered AI coding agent** — Claude Code 替代方案，开源、轻量、可扩展。

[![CI](https://github.com/liyuan1161/deepcraft/actions/workflows/ci.yml/badge.svg)](https://github.com/liyuan1161/deepcraft/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.12%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/)

## 为什么用 DeepCraft

| 特性 | DeepCraft | Claude Code |
|------|-----------|-------------|
| 大模型 | DeepSeek（国产，便宜）| Claude（海外，贵）|
| 协议 | 标准 MCP + Skills | MCP + 自定义 |
| 依赖 | 零 MCP 第三方库 | heavy SDK |
| 开源 | MIT | 闭源 |
| 代码量 | ~5,000 行 | 数万行 |

## 四层架构

```
┌─────────────────────────────────┐
│ A2A：SubAgent 并行委派          │  ← 任务分解
├─────────────────────────────────┤
│ Skills：Markdown 知识注入       │  ← 领域知识
├─────────────────────────────────┤
│ MCP：JSON-RPC 远程工具          │  ← 能力扩展
├─────────────────────────────────┤
│ Function Call：ReAct 本地工具   │  ← 基础调用
└─────────────────────────────────┘
```

## 快速开始

### 安装

```bash
pip install deepcraft        # PyPI（即将上线）
# 或
git clone https://github.com/liyuan1161/deepcraft.git
cd deepcraft && pip install -e ".[dev]"
```

### 配置

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

# 可选：接入 GitHub MCP Server
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
export DEEPCRAFT_MCP_SERVERS="github:npx -y @modelcontextprotocol/server-github"
```

### 运行

```bash
# 交互 REPL
deepcraft

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

### REPL 命令

| 命令 | 说明 |
|------|------|
| `/help` | 帮助 |
| `/status` | token 用量、工具数量 |
| `/mode react` | 切换 ReAct 模式 |
| `/mode plan` | 切换 Plan-Execute 模式 |
| `/mode sub` | 切换 SubAgent 模式 |
| `/mcp` | 列出 MCP 工具 |
| `/mcp connect <name> <cmd>` | 动态连接 MCP Server |
| `/clear` | 清除对话 |
| `/quit` | 退出 |

## 能力矩阵

| 能力 | 状态 |
|------|------|
| ReAct 循环（DeepSeek 流式 + Function Call）| ✅ |
| MCP 协议（手写 JSON-RPC 2.0，零依赖）| ✅ |
| GitHub MCP 集成（26 个工具透明调用）| ✅ |
| Skills 系统（Markdown 知识注入）| ✅ |
| Plan-Execute 模式 | ✅ |
| SelfCorrector 自动纠错 | ✅ |
| SubAgent 并行委派 | ✅ |
| 安全三道防线（危险命令/路径穿越/死循环）| ✅ |
| 模式自动选择器 | ✅ |

## 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 + .env）
├── agent/
│   ├── loop.py            # ReAct 主循环
│   ├── llm.py             # DeepSeek API（65 行）
│   ├── context.py         # 上下文 + token 管理
│   ├── types.py           # 共享类型
│   ├── planner.py         # Plan-Execute
│   ├── corrector.py       # 自我纠错
│   ├── subagent.py        # 子代理委派
│   ├── modes.py           # 模式选择
│   ├── repl.py            # REPL 交互
│   ├── mcp/client.py      # MCP Client（368 行手写）
│   ├── skills/loader.py   # Skills 加载
│   └── tools/             # 工具系统
│       ├── base.py        # BaseTool + Registry
│       ├── file.py        # 文件操作
│       ├── terminal.py    # 终端沙箱
│       └── git_tool.py    # Git 操作
├── tests/                 # 58 个测试
├── docs/                  # 8 篇文章
└── examples/              # MCP demo
```

## 质量

```
ruff   ✅ All checks passed
mypy   ✅ 30 files, strict, 0 issues
pytest ✅ 58/58 passed
CI     ✅ GitHub Actions (3.12 + 3.13)
```

## 文档

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

| # | 主题 | 一句话 |
|---|------|--------|
| 1 | [Agent 架构全景](docs/agent-architecture-deep-dive.md) | 看懂 Agent |
| 2 | [代码实战拆解](docs/deepcraft-implementation-deep-dive.md) | 写出 Agent |
| 3 | [自主 Agent](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-retrospective.md) | 回望 Agent |

## 作者

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