OpenCode 学习笔记 00：项目搭建

学习一个复杂项目最好的方式，不是看文档，而是自己动手实现一个简化版。

系列目录

本系列共 16 篇，分为 5 个阶段，每篇都有可运行的代码产出：

Phase 1: 基础架构 (00-01) ✅

Phase 2: 核心工具 - "AI 如何操作代码" ✅

Phase 3: 会话与记忆 - "AI 如何记住" ✅

Phase 4: 高级功能 ✅

Phase 5: 扩展与生产 ✅

Phase 6: 深入探索 📖

---

专题索引

快速找到你感兴趣的功能：

AI 如何操作代码？

AI 如何记住？

Agent 核心机制

系统高级功能

---

学习目标

本篇完成：

• 了解 OpenCode 的整体架构
• 创建 tiny-agent 项目结构
• 配置 TypeScript + Bun 环境
• 运行第一个 "Hello World"

一、OpenCode 是什么？

OpenCode 是一个开源的 AI coding agent，类似 Claude Code，核心特点：

• 100% 开源：完全开放的代码库
• 多 Provider 支持：Claude、OpenAI、Gemini、本地模型...
• 客户端-服务器架构：TUI 只是前端之一，可以有 Web、移动端等
• LSP 集成：内置语言服务器协议支持
• MCP 支持：Model Context Protocol 扩展能力

二、OpenCode 项目结构

opencode/
├── packages/
│   ├── opencode/          # 🎯 核心包（我们主要学习对象）
│   │   └── src/
│   │       ├── agent/     # Agent 定义（build, plan, explore）
│   │       ├── tool/      # 工具实现（read, write, bash, grep...）
│   │       ├── session/   # 会话管理、消息历史
│   │       ├── provider/  # LLM Provider 抽象
│   │       ├── server/    # HTTP API 服务
│   │       ├── cli/       # TUI 界面
│   │       └── ...
│   ├── console/           # Web 控制台
│   ├── desktop/           # 桌面应用（Tauri）
│   ├── sdk/               # SDK 包
│   └── ui/                # 共享 UI 组件
└── ...

核心模块说明

三、tiny-agent 设计

我们不需要实现完整的 OpenCode，而是提取核心概念，构建一个可运行的最小版本：

tiny-agent/
├── src/
│   ├── index.ts      # 入口
│   ├── tool/         # 工具系统（学习重点 1）
│   ├── agent/        # Agent 定义（学习重点 2）
│   ├── session/      # 会话管理（学习重点 3）
│   ├── provider/     # LLM 调用（学习重点 4）
│   └── tui/          # 简单界面（学习重点 5）
├── package.json
└── tsconfig.json

技术选型

四、项目搭建

4.1 创建目录结构

mkdir -p external/tiny-agent/src/{tool,agent,session,provider,tui}

4.2 package.json

{
  "name": "tiny-agent",
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "bun run src/index.ts"
  },
  "dependencies": {
    "ai": "^4.0.0",
    "zod": "^3.24.0",
    "@anthropic-ai/sdk": "^0.30.0",
    "openai": "^4.70.0"
  },
  "devDependencies": {
    "@types/bun": "latest",
    "typescript": "^5.0.0"
  }
}

4.3 tsconfig.json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

4.4 入口文件 src/index.ts

console.log("🤖 tiny-agent v0.1.0")
console.log("A minimal AI coding agent for learning purposes")

五、运行验证

cd external/tiny-agent
bun install
bun dev

输出：

🤖 tiny-agent v0.1.0
A minimal AI coding agent for learning purposes

项目搭建完成！

六、与 OpenCode 的对照

让我们看看 OpenCode 的入口文件 packages/opencode/src/index.ts：

// OpenCode 使用 yargs 处理命令行参数
const cli = yargs(hideBin(process.argv))
  .scriptName("opencode")
  .command(RunCommand)      // 主运行命令
  .command(ServeCommand)    // 启动服务器
  .command(AuthCommand)     // 认证
  // ... 更多命令

关键观察：

1. OpenCode 是一个 CLI 工具，使用 yargs 处理命令
2. 有多个子命令：run、serve、auth、models...
3. 我们的 tiny-agent 会简化这些，专注于核心逻辑

七、下一步预告

第01篇：Tool 抽象设计

我们将学习 OpenCode 最核心的设计模式之一：Tool 系统。

// 目标：实现这样的 API
const readTool = Tool.define("read", {
  description: "读取文件内容",
  parameters: z.object({
    path: z.string().describe("文件路径"),
  }),
  execute: async (args) => {
    // 实现逻辑
  },
})

将分析的 OpenCode 源码：

• packages/opencode/src/tool/tool.ts - Tool 抽象定义
• packages/opencode/src/tool/read.ts - read 工具实现

---

总结

代码仓库：external/tiny-agent/

下一篇：OpenCode 学习笔记 01：Tool 系统设计