🚀 OpenCode 工程化实战指南：从零构建工业级 AI 开发体系（上）

本教程完全基于免费开源生态，仅需大模型 API 付费。目标：让 OpenCode 产出接近 Claude 级别的代码质量，Bug 率降低 75%+，架构清晰可维护。由于教程过长，将拆分为两篇博文，烦请知悉。

---

🌐 一、双平台环境初始化（15 分钟）

🖥️ 1.1 Mac 环境配置

1.1.1 基础工具链

# 安装 Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装核心工具
brew install node git python@3.12 openjdk@21
brew install --cask visual-studio-code

# 安装 OpenCode CLI
curl -fsSL https://opencode.ai/install.sh | bash

# 验证安装
opencode --version

1.1.2 配置环境变量

# 编辑 ~/.zshrc 或 ~/.bash_profile
echo 'export DEEPSEEK_API_KEY="sk-你的密钥"' >> ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

1.1.3 创建 OpenCode 配置目录

mkdir -p ~/.config/opencode
mkdir -p ~/.opencode

---

💻 1.2 Windows 环境配置

1.2.1 安装 WSL2（推荐）

# 管理员权限运行
wsl --install -d Ubuntu-22.04
# 重启后完成初始化

1.2.2 在 WSL2 中配置环境

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install -y curl git python3 python3-pip openjdk-21-jdk nodejs npm

# 安装 OpenCode
curl -fsSL https://opencode.ai/install.sh | bash

# 配置环境变量
echo 'export DEEPSEEK_API_KEY="sk-你的密钥"' >> ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

1.2.3 验证安装

opencode --version
# 应输出类似：opencode 1.14.41

---

⚙️ 二、OpenCode 配置文件详解（关键！）

2.1 官方 Schema 兼容配置模板

创建 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "deepseek/deepseek-v4-pro",
  "small_model": "deepseek/deepseek-v4-flash",
  "provider": {
    "deepseek": {
      "options": {
        "apiKey": "{env:DEEPSEEK_API_KEY}",
        "baseURL": "https://api.deepseek.com/v1",
        "setCacheKey": true
      }
    }
  },
  "agent": {
    "build": {
      "temperature": 0.1,
      "top_p": 0.75,
      "steps": 50,
      "prompt": "你是专业软件架构师，每次任务必须按顺序输出：1. 架构规划 2. 测试用例 3. 实现代码 4. 验证命令。所有代码必须符合工程规范，禁止魔法数字/字符串，单函数≤40行，嵌套≤3层，必须加类型注解。输出格式严格按【规划】【测试】【实现】【验证】四段输出。"
    }
  },
  "instructions": [
    "~/.opencode/rules.md"
  ],
  "compaction": {
    "auto": true,
    "prune": true,
    "threshold": 0.6,
    "reserved": 20000
  },
  "permission": {
    "read": "allow",
    "edit": "allow",
    "bash": "ask",
    "websearch": "allow"
  },
  "tool_output": {
    "max_lines": 1000,
    "max_bytes": 25600
  },
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-filesystem", "."],
      "enabled": true
    },
    "github": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-github"],
      "enabled": true
    }
  },
  "autoupdate": "notify"
}

🔑 关键字段说明

字段	作用	推荐值
model	主模型标识	deepseek/deepseek-v4-pro
agent.build.prompt	系统提示词位置（非顶级system）	四段式约束模板
instructions	自动加载外部规则文件	["~/.opencode/rules.md"]
compaction	上下文自动压缩，防溢出	threshold: 0.6
tool_output	工具输出截断，防上下文爆炸	max_lines: 1000
permission.bash	执行命令前确认，防误操作	"ask"
mcp	连接外部工具的标准协议	按需启用
autoupdate	自动更新策略	"notify"

⚠️ 重要：所有自动化脚本中必须使用 opencode run "prompt"，绝对不能使用 TUI 模式，否则会触发 30KB 长度限制导致卡死。

---

📜 三、规则文件增强（~/.opencode/rules.md）

# 工程约束（AI 必须遵守）

## 语言规范
- 语言：Java 17+ / Python 3.10+ / TypeScript 5.x
- 风格：Google Java Style / PEP8 / ESLint Airbnb
- 结构：单函数 ≤40 行，嵌套 ≤3 层，必须加类型注解

## 测试要求
- 核心函数覆盖率 ≥80%，先写测试再生成实现
- 所有函数必须包含异常处理
- 所有外部调用必须添加超时机制（默认 30 秒）
- 禁止使用 eval、exec、__import__ 等危险函数

## 安全规范
- 密钥走环境变量，禁止硬编码
- 所有 SQL 语句必须使用参数化查询
- 所有用户输入必须进行验证和转义
- 禁止在日志中打印敏感信息

## 输出格式
- 严格按【规划】【测试】【实现】【验证命令】四段输出
- 【规划】必须包含模块划分图（mermaid 格式）
- 【测试】必须包含正常/边界/异常三类用例
- 【实现】必须包含类型注解和关键注释
- 【验证命令】必须是可复制执行的单行命令

## 禁止行为
- 不生成占位符（如 "TODO"、"pass"）
- 不省略错误处理（必须 try-catch 或返回 Result）
- 不虚构库函数（只能使用标准库或已声明依赖）
- 不跳过断言（测试必须包含 assert）

---

🧩 四、项目结构设计（让架构清晰可维护）

4.1 通用项目结构模板

my-project/
├── .opencode/            # AI 规则配置（项目级覆盖）
│   └── rules.md
├── .github/
│   └── workflows/        # CI/CD 流水线
├── docs/                 # 架构文档（自动生成）
│   ├── architecture.md   # Mermaid 架构图
│   └── api.yaml          # OpenAPI 3.0 规范
├── src/
│   ├── main/
│   │   ├── java/         # Java 源码（包结构）
│   │   ├── python/       # Python 源码（模块结构）
│   │   └── web/          # Web 前端（Vue/React）
│   └── test/
│       ├── java/         # Java 测试（JUnit）
│       ├── python/       # Python 测试（pytest）
│       └── web/          # Web 测试（Playwright）
├── config/               # 配置文件（数据库、环境变量）
├── scripts/              # 自动化脚本
│   ├── ai-fix.sh         # AI 自愈脚本
│   ├── check_coverage.sh # 覆盖率检查
│   └── generate_docs.sh  # 文档生成
├── .gitignore
├── pom.xml / pyproject.toml / package.json
└── README.md

4.2 配置文件示例（Java/Python 双模）

pom.xml (Java)

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>my-project</artifactId>
  <version>0.1.0</version>
  
  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  
  <dependencies>
    <!-- 测试依赖 -->
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.13.2</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.assertj</groupId>
      <artifactId>assertj-core</artifactId>
      <version>3.24.2</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  
  <build>
    <plugins>
      <plugin>
        <groupId>org.jacoco</groupId>
        <artifactId>jacoco-maven-plugin</artifactId>
        <version>0.8.11</version>
        <executions>
          <execution>
            <goals><goal>prepare-agent</goal></goals>
          </execution>
          <execution>
            <id>report</id>
            <phase>test</phase>
            <goals><goal>report</goal></goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

pyproject.toml (Python)

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "AI-Engineered Project"
authors = ["Your Name <you@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.10"
fastapi = "^0.109.0"
uvicorn = "^0.27.0"
sqlalchemy = "^2.0.25"
pytest = "^7.4.0"
hypothesis = "^6.96.0"

[tool.poetry.group.dev.dependencies]
ruff = "^0.8.0"
mypy = "^1.8.0"
pre-commit = "^3.6.0"

[tool.ruff]
line-length = 88
target-version = "py310"
select = ["E", "F", "W", "I", "PL", "PT"]
ignore = ["F401", "W292"]

[tool.ruff.per-file-ignores]
"__init__.py" = ["F401"]
"tests/*" = ["PLR2004"]

[tool.mypy]
python_version = "3.10"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

[tool.pytest.ini_options]
addopts = "--cov=src --cov-report=term-missing"
testpaths = ["tests"]

---

🧪 五、自动化测试架构（工业级实践）

5.1 测试金字塔结构

        ┌─────────────────┐
        │   E2E 测试 5%    │  ← Playwright / Cypress
        ├─────────────────┤
        │  集成测试 15%    │  ← API 契约测试
        ├─────────────────┤
        │  单元测试 80%    │  ← pytest / JUnit + Hypothesis
        └─────────────────┘

5.2 单元测试配置

5.2.1 Python 单元测试 + 属性测试

# tests/python/auth/test_auth.py
import pytest
from src.python.auth import register_user
from hypothesis import given, strategies as st, settings

class TestRegisterUser:
    """用户注册测试套件"""
    
    @given(
        name=st.text(min_size=3, max_size=20, alphabet=st.characters(min_codepoint=97, max_codepoint=122)),
        email=st.emails()
    )
    @settings(max_examples=100)
    def test_valid_registration(self, name: str, email: str):
        """属性测试：任意合法输入都应成功"""
        result = register_user(name, email)
        assert result["success"] is True
        assert "user_id" in result
        assert isinstance(result["user_id"], str)
    
    @pytest.mark.parametrize("invalid_name", ["", "a", "ab", "a"*21])
    def test_invalid_name_length(self, invalid_name: str):
        """边界值：名称长度校验"""
        result = register_user(invalid_name, "valid@example.com")
        assert result["success"] is False
        assert "name" in result["error"].lower()
    
    def test_duplicate_email(self):
        """业务逻辑：邮箱唯一性"""
        email = "test@example.com"
        register_user("user1", email)
        result = register_user("user2", email)
        assert result["success"] is False
        assert "email" in result["error"].lower()

5.2.2 Java 单元测试（JUnit 5）

// src/test/java/com/example/auth/AuthServiceTest.java
package com.example.auth;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;

class AuthServiceTest {
    
    private AuthService authService;
    
    @BeforeEach
    void setUp() {
        authService = new AuthService(new InMemoryUserStorage());
    }
    
    @Test
    void testValidRegistration() {
        RegistrationResult result = authService.register("valid_user", "valid@example.com");
        
        assertThat(result.isSuccess()).isTrue();
        assertThat(result.getUserId()).isNotNull();
        assertThat(result.getUserId()).matches("^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$");
    }
    
    @ParameterizedTest
    @ValueSource(strings = {"", "a", "ab"})
    void testInvalidNameLength(String invalidName) {
        RegistrationResult result = authService.register(invalidName, "valid@example.com");
        
        assertThat(result.isSuccess()).isFalse();
        assertThat(result.getError()).containsIgnoringCase("name");
    }
    
    @Test
    void testDuplicateEmail() {
        String email = "test@example.com";
        authService.register("user1", email);
        
        RegistrationResult result = authService.register("user2", email);
        
        assertThat(result.isSuccess()).isFalse();
        assertThat(result.getError()).containsIgnoringCase("email");
 expect
    }
}

5.3 契约测试（API 层）

5.3.1 安装契约测试工具

# Python 项目
pip install schemathesis

# 或全局安装
pipx install schemathesis

5.3.2 运行契约测试

# 基于 OpenAPI 3.0 规范自动生成 200+ 边界测试
schemathesis run docs/api.yaml \
  --hypothesis-phases=explicit,generate \
  --hypothesis-max-examples=50 \
  --base-url=http://localhost:8000 \
  --report=html \
  --output=report.html

✅ Schemathesis 会自动生成：

• 参数边界值（空字符串、超长、特殊字符）
• 必填字段缺失测试
• 类型错误测试（字符串传数字）
• 认证/授权边界测试

---

🔧 六、自动化脚本（关键！）

6.1 测试覆盖率检查脚本

创建 scripts/check_coverage.sh：

#!/bin/bash
set -e  # 遇到错误立即退出

echo "🧪 运行测试并生成覆盖率报告..."

# 运行测试并捕获输出
COVERAGE_OUTPUT=$(pytest --cov=src --cov-report=term-missing 2>&1)
echo "$COVERAGE_OUTPUT"

# 精确提取 TOTAL 行的覆盖率百分比
COVERAGE=$(echo "$COVERAGE_OUTPUT" | grep "TOTAL" | awk '{print $NF}' | tr -d '%')

# 验证提取结果
if ! [[ "$COVERAGE" =~ ^[0-9]+$ ]]; then
    echo "❌ 无法解析覆盖率: $COVERAGE"
    exit 1
fi

echo "📊 测试覆盖率: ${COVERAGE}%"

# 门禁检查
if [ "$COVERAGE" -lt 80 ]; then
    echo "❌ 测试覆盖率 ${COVERAGE}% < 80%，拒绝提交"
    echo "💡 建议：运行 'pytest --cov=src --cov-report=html' 查看缺失覆盖的代码"
    exit 1
else
    echo "✅ 测试覆盖率 ${COVERAGE}% ≥ 80%，通过门禁"
    exit 0
fi

6.2 AI 自愈脚本

创建 scripts/ai-fix.sh：

#!/bin/bash
set -e

MAX_RETRIES=3
RETRY=0
LOG_FILE="test_$(date +%Y%m%d_%H%M%S).log"

echo "🔄 AI 自愈循环启动 (最大重试: $MAX_RETRIES)"

while [ $RETRY -lt $MAX_RETRIES ]; do
    echo ""
    echo "▶ 第 $((RETRY+1))/$MAX_RETRIES 次测试..."
    
    # 运行测试并记录日志
    if pytest tests/ --tb=short -q 2>&1 | tee "$LOG_FILE"; then
        echo "✅ 所有测试通过!"
        rm -f "$LOG_FILE"
        exit 0
    fi
    
    echo "❌ 测试失败，收集错误日志..."
    
    # 提取失败摘要（前 50 行 + 最后 20 行）
    FAIL_SUMMARY=$(head -n 50 "$LOG_FILE"; echo "..."; tail -n 20 "$LOG_FILE")
    
    echo "🤖 请求 AI 分析并修复..."
    
    # 使用 opencode run（非 TUI）请求修复
    FIX_RESPONSE=$(opencode run "分析以下测试失败日志，仅输出修复后的代码和测试用例。
保持原有逻辑不变，严格按【测试】【实现】格式输出，不要包含其他解释：

$FAIL_SUMMARY" --model deepseek/deepseek-v4-pro 2>/dev/null)
    
    # 使用 sed 精确提取段落（避免固定行数截断）
    echo "$FIX_RESPONSE" | sed -n '/【测试】/,/【实现】/p' | sed '$d' > temp_test.py
    echo "$FIX_RESPONSE" | sed -n '/【实现】/,/^【/p' | sed '/^【/d' > temp_impl.py
    
    # 验证提取结果
    if [ ! -s temp_impl.py ]; then
        echo "⚠️  AI 未输出有效修复代码，跳过本次重试"
        RETRY=$((RETRY+1))
        continue
    fi
    
    # 备份原文件并应用修复
    cp src/python/auth/auth.py src/python/auth/auth.py.bak
    cp tests/python/auth/test_auth.py tests/python/auth/test_auth.py.bak
    cp temp_impl.py src/python/auth/auth.py
    cp temp_test.py tests/python/auth/test_auth.py
    
    echo "🔧 已应用 AI 修复，重新运行测试..."
    RETRY=$((RETRY+1))
done

echo ""
echo "🛑 达到最大重试次数 ($MAX_RETRIES)，需人工干预"
echo "📋 查看日志: $LOG_FILE"
echo "💡 建议步骤:"
echo "  1. 手动运行: pytest tests/ -v"
echo "  2. 检查修复文件: git diff src/ tests/"
echo "  3. 必要时回滚: git checkout -- src/ tests/"

# 清理临时文件
rm -f temp_test.py temp_impl.py "$LOG_FILE"
exit 1

6.3 文档生成脚本

创建 scripts/generate_docs.sh：

#!/bin/bash
set -e

echo "📚 生成项目文档..."

# 生成架构图（Mermaid 格式）
echo "🔷 生成架构图..."
opencode run "分析当前项目代码结构，生成项目架构图（mermaid 格式），包含：
- 模块划分
- 模块间调用关系
- 数据流向
- 外部依赖
- 扩展点标注" --model deepseek/deepseek-v4-pro > docs/architecture.md

# 生成 API 文档（OpenAPI 3.0）
echo "🔷 生成 API 文档..."
opencode run "根据项目代码生成 OpenAPI 3.0 规范文档，包含：
- 所有端点路径和方法
- 请求/响应示例（JSON）
- 参数说明和约束
- 错误码定义
- 认证方式说明" --model deepseek/deepseek-v4-pro > docs/api.yaml

# 生成模块关系图
echo "🔷 生成模块依赖图..."
opencode run "分析项目代码，生成模块间调用关系图（mermaid 格式），标注：
- 强依赖（必须存在）
- 弱依赖（可选）
- 循环依赖（需警告）" --model deepseek/deepseek-v4-pro > docs/module-dependency.md

echo "✅ 文档生成完成: docs/"

---

上半部分结束，请移步下半部分，谢谢。