Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions all-in-one-book/00-前言/01-本书简介与阅读指南.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# 本书简介与阅读指南

> 📌 一本从零到精通的 OpenCode 中文技术书籍,采用"地图→路线→细节"三级认知结构。

## 本书的目标读者

本书面向以下读者:

| 角色 | 你会获得什么 |
|------|-------------|
| **AI 工具用户** | 学会高效使用 OpenCode 完成日常编码任务 |
| **全栈开发者** | 理解 Coding Agent 的架构设计,学习 TypeScript/Bun/Effect-TS 实践 |
| **开源贡献者** | 掌握源码结构,快速定位并修改代码 |
| **架构师** | 理解 Agent 系统的设计模式和技术选型 |
| **AI 产品经理** | 理解 AI Coding Agent 的能力边界和扩展方式 |

## 本书的认知结构

我们采用 **"地图→路线→细节"** 三级认知结构:

```
第一级(全景地图): 花 30 分钟建立完整心智模型
↓ 知道"所有部件在哪、怎么连、怎么跑"
第二级(路线导航): 沿着数据流/执行流走通关键路径
↓ 知道"一个请求从输入到输出经历了什么"
第三级(细节深入): 对每个模块进行源码级解析
↓ 知道"每个零件内部怎么工作"
```

### 推荐阅读路线

**路线 A:快速了解(1 小时)**
1. 01-全景视野/01-一图看懂OpenCode
2. 01-全景视野/04-一次对话的完整旅程
3. 02-快速上手/02-五分钟体验OpenCode

**路线 B:深入架构(半天)**
1. 01-全景视野(全部 11 节)
2. 03-关键路径详解(全部 5 节)

**路线 C:扩展开发(按需)**
1. 01-全景视野/09-扩展点全景图
2. 06-扩展与集成(选择你需要的扩展类型)
3. 10-实战案例(动手练习)

**路线 D:完整精读(一周)**
按目录顺序从头到尾读完。

## 约定说明

- 技术术语首次出现时使用 `中文(English)` 格式,例如:`会话(Session)`
- 源码引用标注文件路径,如 `// 文件: packages/opencode/src/agent/agent.ts`
- 所有架构图使用 Mermaid 语法
- 💡 标记表示关键设计决策
- 📍 标记表示"你在全景图中的位置"
- ⚠️ 标记表示需要特别注意的地方

## 前置知识

阅读本书的不同章节需要不同程度的前置知识:

| 章节 | 需要了解 |
|------|---------|
| 00-前言、01-全景视野 | 基本编程概念 |
| 02-快速上手 | 命令行基础操作 |
| 03-关键路径、04-核心引擎 | TypeScript 基础、async/await |
| 05-用户界面 | 前端框架基本概念 |
| 09-周边知识 | 无(本章就是帮你补前置知识的) |
56 changes: 56 additions & 0 deletions all-in-one-book/00-前言/02-OpenCode是什么.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# OpenCode 是什么

> 📌 OpenCode 是一个开源的 AI 编程代理(Coding Agent),让你在终端中与 AI 结对编程。

## 一句话定义

**OpenCode 是一个运行在终端里的 AI 编程助手**,它能理解你的代码库,帮你读代码、写代码、改代码、运行命令,就像一个坐在你旁边的资深程序员搭档。

## 核心特性

| 特性 | 说明 |
|------|------|
| 🤖 **多模型支持** | 支持 Claude、GPT、Gemini、Mistral 等 20+ 种 LLM |
| 🔧 **内置工具** | 文件读写、代码搜索、Shell 执行、Git 操作等 |
| 🔌 **MCP 协议** | 通过 Model Context Protocol 无限扩展工具能力 |
| 🖥️ **多端体验** | TUI 终端界面、Web 应用、桌面客户端 |
| 📂 **项目感知** | 自动理解项目结构、Git 状态、文件关系 |
| 🔒 **权限控制** | 精细的权限模型,控制 AI 可以做什么 |
| 🧩 **可扩展** | 自定义 Agent、Tool、Command、Plugin |
| 💾 **会话持久化** | 对话历史保存在本地 SQLite 数据库 |

## 与同类工具对比

| 特性 | OpenCode | GitHub Copilot CLI | Cursor | Aider |
|------|----------|-------------------|--------|-------|
| 开源 | ✅ MIT | ❌ | ❌ | ✅ |
| 多 LLM 支持 | ✅ 20+ | ❌ 仅 GPT | ❌ 有限 | ✅ |
| MCP 协议 | ✅ | ❌ | ✅ | ❌ |
| TUI 界面 | ✅ | ✅ | ❌ | ✅ |
| Web 界面 | ✅ | ❌ | ✅ | ❌ |
| 桌面客户端 | ✅ | ❌ | ✅ | ❌ |
| 插件系统 | ✅ | ❌ | ❌ | ❌ |
| 自定义 Agent | ✅ | ❌ | ❌ | ❌ |

## 项目背景

OpenCode 最初由 [anomalyco](https://github.com/anomalyco) 团队开发,本书基于 `propress/opencode` 仓库的 `dev` 分支编写。项目采用 MIT 许可证,欢迎社区贡献。

- **官网**: https://opencode.ai
- **GitHub**: https://github.com/anomalyco/opencode
- **技术栈**: TypeScript + Bun + Effect-TS + Vercel AI SDK + SolidJS + Tauri + Drizzle ORM

## OpenCode 能做什么?

```
你:帮我把 src/utils.ts 里的所有 forEach 改成 for...of 循环

OpenCode:
1. 🔍 搜索 src/utils.ts 中的 forEach 用法
2. 📖 读取文件内容,理解上下文
3. ✏️ 逐个替换为 for...of,保持语义一致
4. ✅ 展示修改 diff,等你确认
5. 💾 保存文件,创建 Git 快照
```

这就是 OpenCode 的核心工作方式:**理解意图 → 分析代码 → 选择工具 → 执行操作 → 确认结果**。
Loading