# Get Started with Web3

[![GitHub stars](https://img.shields.io/github/stars/beihaili/Get-Started-with-Web3)](https://github.com/beihaili/Get-Started-with-Web3/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/beihaili/Get-Started-with-Web3)](https://github.com/beihaili/Get-Started-with-Web3/network/members)
[![License: MIT](https://img.shields.io/github/license/beihaili/Get-Started-with-Web3)](LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![Deploy](https://github.com/beihaili/Get-Started-with-Web3/actions/workflows/deploy.yml/badge.svg)](https://github.com/beihaili/Get-Started-with-Web3/actions/workflows/deploy.yml)

<div align="center">
  <img src="./logo.png" alt="Get Started with Web3 Logo" width="900" />
</div>

<div align="center">
  <strong>面向新手、开发者和 AI Agent 的开源双语 Web3 学习体系。</strong><br/>
  <em>11 个模块、62 讲课程、AI Tutor、徽章系统、SEO 预渲染、llms.txt 和只读 MCP server。</em>
</div>

<br/>

<div align="center">
  <a href="https://beihaili.github.io/Get-Started-with-Web3/">在线学习</a> &nbsp;|&nbsp;
  <a href="https://beihaili.github.io/Get-Started-with-Web3/zh/articles">全部文章</a> &nbsp;|&nbsp;
  <a href="https://beihaili.github.io/Get-Started-with-Web3/llms.txt">llms.txt</a> &nbsp;|&nbsp;
  <a href="README.md">English</a> &nbsp;|&nbsp;
  <a href="https://twitter.com/bhbtc1337">Twitter</a>
</div>

---

## 为什么做这个项目

Web3 的学习资料长期分散在钱包教程、协议文档、安全提醒、开发工具和碎片化文章里。这个项目把这些内容整理成一条可以持续学习、可以贡献、也可以被 AI Agent 检索和引用的开源课程路径。

如果这个项目帮你理解 Web3，请给 [GitHub 仓库点一个 star](https://github.com/beihaili/Get-Started-with-Web3)，这会让更多学习者看到它。

## 适合谁

| 角色             | 可以用它做什么                                                                       |
| ---------------- | ------------------------------------------------------------------------------------ |
| **完全新手**     | 创建钱包、完成第一笔交易、理解 Gas、识别常见骗局。                                   |
| **Web3 Builder** | 从概念进入 DApp、智能合约、区块浏览器、Bitcoin RPC、DeFi、L2 和 DAO 工具。           |
| **研究者**       | 系统复习 Bitcoin、Ethereum、DeFi、L2、DAO、跨链桥、稳定币和智能账户。                |
| **AI Agent**     | 通过 `llms.txt`、JSON artifacts 和本地 MCP server 搜索、读取、引用和组合课程上下文。 |
| **赞助商**       | 支持开源 Web3 教育，并在学习者选择默认工具前建立可信触达。                           |

## 项目边界

本仓库首先是课程内容平台和 AI-readable 知识层。后续会增加少量现代 Web3 实验，但这些实验用于教学，不是生产级 DApp 脚手架。

本项目不提供投资建议、代币推广、交易所导流或虚拟货币业务服务。钱包、SIWE、x402、链上证书、赞助和付费工具相关内容，必须在真实上线并验证前明确标注为 demo、metadata、draft 或 future plan。

## 当前内容资产

| 项目           | 当前状态                                               |
| -------------- | ------------------------------------------------------ |
| 课程模块       | 11 个                                                  |
| React 课程地图 | 62 讲                                                  |
| AI-native 索引 | 124 条双语课程索引记录                                 |
| 术语表         | 63 个 Web3 术语                                        |
| 语言           | 中文优先，英文持续补齐                                 |
| App 功能       | AI Tutor、搜索、测验、徽章、XP、深浅色模式、PWA/离线   |
| Agent 入口     | `llms.txt`、AI manifest、内容索引、本地只读 MCP server |
| 变现基础       | 捐赠、联盟链接披露、赞助包、未来 x402 付费工具元数据   |

## 在线入口

在线学习平台：

**https://beihaili.github.io/Get-Started-with-Web3/**

公开 AI 入口：

- [llms.txt](https://beihaili.github.io/Get-Started-with-Web3/llms.txt)
- [AI manifest](https://beihaili.github.io/Get-Started-with-Web3/ai/manifest.json)
- [AI content index](https://beihaili.github.io/Get-Started-with-Web3/ai/content-index.json)

## 课程地图

| 模块                       | 课程数 | 重点                                                             |
| -------------------------- | -----: | ---------------------------------------------------------------- |
| Web3 快速入门              |      7 | 钱包、第一笔交易、DApp、常用工具、发币、安全、交易所基础         |
| 比特币技术：密码学与数据层 |      8 | 哈希、签名、交易结构、多签、SegWit、Taproot、数据结构            |
| 比特币技术：网络与共识层   |      6 | Bitcoin Core、P2P、网络安全、PoW、难度调整、分叉和 BIP           |
| 比特币技术：应用层         |      7 | 钱包、RPC、低费率广播、Bitcoin Script、治理、Ordinals、跨链 DeFi |
| Web3 深度思考              |      3 | 基本原则、主权、区块链必要性、比特币文化彩蛋                     |
| Web3 生态与工具            |      6 | DeFi、Ethereum、Layer 2、新兴公链、AI x Web3、实用工具           |
| Web3 Builder 实战          |      6 | ERC-20 部署、第一个 DApp、区块浏览器、合约安全、钱包和 SIWE 实验 |
| DeFi 深度解析              |      5 | DeFi 架构、AMM、借贷、稳定币、风险                               |
| 跨链与 Layer 2             |      6 | 扩容、Rollup、L2 生态、跨链桥、风险模拟、L2 实操                  |
| DAO 与去中心化治理         |      5 | DAO 基础、治理机制、DAO 工具、案例、挑战                         |
| 以太坊与智能账户           |      3 | Pectra/Fusaka 后的以太坊、账户抽象、UserOperation 模拟器、智能钱包 |

## 快速开始

```bash
git clone https://github.com/beihaili/Get-Started-with-Web3.git
cd Get-Started-with-Web3
npm install
npm run dev
```

开发服务器会运行在 `http://localhost:5173/Get-Started-with-Web3/`。

常用命令：

```bash
npm run build      # 生产构建、OG 图片、sitemap、预渲染
npm test           # Vitest 测试
npm run lint       # ESLint 检查
npm run ai:verify  # 验证公开 AI 入口和 x402 元数据
```

## AI Agent 与 MCP

本仓库提供面向 AI Agent 的机器可读内容层：

```bash
npm run ai:index   # 重新生成 ai/manifest.json、ai/content-index.json、ai/llms.txt
npm run ai:publish # 复制 AI artifacts 到 public/
npm run ai:verify  # 检查公开 AI 入口和 x402 元数据
npm run mcp:web3   # 启动本地只读 stdio MCP server
```

Agent 使用方式：

```bash
npm run mcp:web3
```

如果你的 MCP client 支持 `mcpServers` JSON 配置，可以复制下面的配置，并把 `cwd` 替换成本仓库的本地绝对路径：

```json
{
  "mcpServers": {
    "get-started-with-web3": {
      "command": "npm",
      "args": ["run", "mcp:web3"],
      "cwd": "/absolute/path/to/Get-Started-with-Web3"
    }
  }
}
```

然后在 MCP client 中调用：

- `search_web3_content`: 搜索课程和术语。
- `read_web3_lesson`: 读取带引用的课程内容。
- `get_learning_path`: 获取新手、Builder、研究者或投资者学习路径。
- `lookup_web3_glossary`: 查询 Web3 术语。
- `compose_web3_context`: 组合带引用的上下文包。
- `list_monetizable_tools`: 查看未来 x402-ready 付费工具元数据。

本地 MCP 工具保持只读，不执行支付验证、链上签名或链上操作。x402 字段只是为未来远程付费工具预留的元数据。

AI artifacts 通过 `artifactContract.version` 作为稳定 v1 公开接口维护；详见 [AI-native v1 稳定层与变现决策](docs/strategy/2026-06-26-ai-native-v1-stability-and-monetization.md)。

## 技术栈

- **Frontend:** React 19 + Vite + Tailwind CSS
- **State:** Zustand
- **Routing:** React Router
- **Content:** `zh/` 与 `en/` 下的 Markdown
- **Rendering:** react-markdown + remark-gfm + rehype-raw
- **AI Tutor:** Gemini，使用用户自带 API key
- **Agent layer:** `@modelcontextprotocol/sdk`、生成的 JSON artifacts、`llms.txt`
- **SEO:** sitemap、OG 图片生成、预渲染
- **Testing:** Vitest + happy-dom + Testing Library
- **CI/CD:** GitHub Actions 到 GitHub Pages

## 参与贡献

适合新贡献者的方向：

- 修正过时或不清楚的课程内容。
- 校对英文翻译。
- 添加 quiz 或 glossary 条目。
- 改善可访问性、移动端体验或测试。
- 补充案例、图表和代码示例。

入口：

- [贡献指南](CONTRIBUTING.md)
- [贡献者成长路径](docs/community/contributor-ladder.md)
- [贡献者 Spotlight 模板](docs/community/contributor-spotlight-template.md)
- [贡献者 Spotlights](docs/community/spotlights/README.md)
- [Good first issues 清单](docs/community/good-first-issues.md)
- [good first issues](https://github.com/beihaili/Get-Started-with-Web3/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
- [所有 issues](https://github.com/beihaili/Get-Started-with-Web3/issues)

## 支持和赞助

项目会保持核心学习内容免费。你的支持会用于维护、翻译、新课程和 AI-native 工具。

- **GitHub Sponsors:** [github.com/sponsors/beihaili](https://github.com/sponsors/beihaili)
- **Buy Me a Coffee:** [buymeacoffee.com/beihaili](https://buymeacoffee.com/beihaili)
- **赞助包:** [docs/strategy/2026-05-14-sponsor-kit.md](docs/strategy/2026-05-14-sponsor-kit.md)
- **披露审查:** [docs/strategy/2026-05-18-donation-affiliate-disclosure-review.md](docs/strategy/2026-05-18-donation-affiliate-disclosure-review.md)
- **ETH / EVM:** `0xb7Cd29C78B97cdf0A6e6FFC9268d43eDc3eCa649`
- **BTC:** `1GihPqLkjJNK2fzCMSicc9mLapKeGy3Vv1`
- **Binance:** [注册链接](https://www.bsmkweb.cc/register?ref=39797374)（20% 手续费返佣）

部分外链可能是联盟或赞助链接，会在使用处披露。

## 社区

- **Twitter/X:** [@bhbtc1337](https://twitter.com/bhbtc1337)
- **微信交流群:** [填表加入](https://forms.gle/QMBwL6LwZyQew1tX8)
- **GitHub Issues:** [提问与反馈](https://github.com/beihaili/Get-Started-with-Web3/issues)

## 贡献者

<a href="https://github.com/beihaili/Get-Started-with-Web3/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=beihaili/Get-Started-with-Web3" />
</a>

## License

[MIT License](LICENSE) — 自由使用、修改和分发。

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=beihaili/Get-Started-with-Web3&type=Date)](https://star-history.com/#beihaili/Get-Started-with-Web3&Date)
