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

🔁 七、Pre-commit 门禁配置

7.1 正确的 .pre-commit-config.yaml

# .pre-commit-config.yaml
repos:
  # Python 代码检查与格式化
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff-check
        args: [--fix, --exit-non-zero-on-fix]
        types_or: [python, pyi]
      - id: ruff-format
        types_or: [python, pyi]
  
  # Python 类型检查
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.13.0
    hooks:
      - id: mypy
        additional_dependencies: 
          - types-requests
          - types-PyYAML
        args: [--ignore-missing-imports]
  
  # Java 代码检查（可选）
  - repo: local
    hooks:
      - id: checkstyle-java
        name: CheckStyle Java
        entry: mvn checkstyle:check
        language: system
        types: [java]
        pass_filenames: false
  
  # 测试覆盖率门禁
  - repo: local
    hooks:
      - id: test-coverage
        name: "Test Coverage Check (≥80%)"
        entry: bash scripts/check_coverage.sh
        language: system
        pass_filenames: false
        always_run: true
        stages: [commit]
  
  # 文档生成（可选，在 push 前运行）
  - repo: local
    hooks:
      - id: generate-docs
        name: "Generate Architecture Docs"
        entry: bash scripts/generate_docs.sh
        language: system
        pass_filenames: false
        always_run: false
        stages: [push]

7.2 安装并启用 Pre-commit

# 安装 pre-commit
pip install pre-commit  # 或 pipx install pre-commit

# 在项目根目录初始化
pre-commit install

# 验证安装
pre-commit run --all-files

7.3 Git 提交工作流

# 日常开发流程
git add .
git commit -m "feat: 实现用户注册模块"
# ✅ 自动触发：格式化 → 类型检查 → 测试 → 覆盖率门禁

# 推送前生成文档（可选）
git push
# ✅ 自动触发：生成架构图 + API 文档

🌐 八、CI/CD 流水线配置（GitHub Actions）

8.1 完整工作流 .github/workflows/ci.yml

name: AI-Engineered CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  PYTHON_VERSION: '3.10'
  JAVA_VERSION: '17'
  NODE_VERSION: '20'

jobs:
  # 1. 代码质量检查
  lint:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        language: [python, java]
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        if: matrix.language == 'python'
        uses: actions/setup-python@v5
        with: { python-version: ${{ env.PYTHON_VERSION }} }
      
      - name: Set up Java
        if: matrix.language == 'java'
        uses: actions/setup-java@v4
        with: { distribution: 'temurin', java-version: ${{ env.JAVA_VERSION }} }
      
      - name: Install dependencies
        run: |
          if [ "${{ matrix.language }}" = "python" ]; then
            pip install ruff mypy pytest hypothesis
          else
            mvn dependency:resolve
          fi
      
      - name: Run linter
        run: |
          if [ "${{ matrix.language }}" = "python" ]; then
            ruff check src/ --exit-non-zero-on-fix
            mypy src/ --ignore-missing-imports
          else
            mvn checkstyle:check
          fi

  # 2. 测试执行 + AI 自愈
  test:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with: { python-version: ${{ env.PYTHON_VERSION }} }
      
      - name: Install dependencies
        run: |
          pip install pytest hypothesis ruff mypy pre-commit playwright
          playwright install chromium
      
      # 🔑 关键：安装 OpenCode
      - name: Install OpenCode
        run: |
          curl -fsSL https://opencode.ai/install.sh | bash
          echo "$HOME/.local/bin" >> $GITHUB_PATH
      
      - name: Run pre-commit checks
        run: |
          pre-commit install
          pre-commit run --all-files
      
      - name: Run tests with AI auto-fix
        env:
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
        run: |
          # 运行测试 + AI 自愈循环
          bash scripts/ai-fix.sh
      
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        if: always()
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          files: ./coverage.xml
          fail_ci_if_error: false

  # 3. 文档生成（仅在 main 分支）
  docs:
    runs-on: ubuntu-latest
    needs: test
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      
      - name: Install OpenCode
        run: |
          curl -fsSL https://opencode.ai/install.sh | bash
          echo "$HOME/.local/bin" >> $GITHUB_PATH
      
      - name: Generate documentation
        env:
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
        run: |
          opencode run "生成项目架构图（mermaid 格式）" > docs/architecture.md
          opencode run "生成 API 文档（OpenAPI 3.0 格式）" > docs/api.yaml
      
      - name: Commit docs
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add docs/
          git diff --quiet && git diff --staged --quiet || git commit -m "docs: auto-generate architecture docs [skip ci]"
          git push

8.2 GitHub Secrets 配置

在仓库 → Settings → Secrets and variables → Actions 中添加：

Secret Name Value 说明
DEEPSEEK_API_KEY sk-xxx DeepSeek API 密钥
CODECOV_TOKEN xxx Codecov 上传令牌（可选）

8.3 分支保护规则（GitHub Settings）

Settings → Branches → main → Add rule:
✅ Require a pull request before merging
✅ Require approvals: 1
✅ Require status checks to pass before merging
  → Select: lint (python), lint (java), test
✅ Include administrators
✅ Do not allow bypassing the above settings

🧠 九、模块解耦与扩展性实践

9.1 依赖倒置原则（DIP）实战

❌ 问题代码（紧耦合）
# src/python/auth/auth.py
class AuthService:
    def __init__(self):
        # 直接依赖具体实现
        self.db = SQLiteDatabase("./data/users.db")
    
    def register(self, name: str, email: str) -> dict:
        if not self._validate(name, email):
            return {"success": False, "error": "Invalid input"}
        
        # 直接调用具体方法
        user_id = self.db.insert_user(name, email)
        return {"success": True, "user_id": user_id}
✅ 解耦代码（接口 + 配置注入）
# src/python/auth/interfaces.py
from abc import ABC, abstractmethod
from typing import Optional

class UserStorage(ABC):
    """用户存储接口（依赖倒置）"""
    
    @abstractmethod
    def save_user(self, name: str, email: str) -> Optional[str]:
        """保存用户，返回 user_id"""
        pass
    
    @abstractmethod
    def find_by_email(self, email: str) -> Optional[dict]:
        """按邮箱查询用户"""
        pass

# src/python/auth/sqlite_impl.py
class SQLiteDatabase(UserStorage):
    """SQLite 实现（可替换）"""
    
    def __init__(self, db_path: str):
        self.db_path = db_path
        self._init_db()
    
    def save_user(self, name: str, email: str) -> Optional[str]:
        # 参数化查询防 SQL 注入
        user_id = self._execute(
            "INSERT INTO users (name, email) VALUES (?, ?)",
            (name, email)
        )
        return str(user_id) if user_id else None
    
    # ... 其他实现

# src/python/auth/auth.py
class AuthService:
    """业务逻辑（不依赖具体存储）"""
    
    def __init__(self, storage: UserStorage):
        self.storage = storage  # 依赖接口
    
    def register(self, name: str, email: str) -> dict:
        if not self._validate(name, email):
            return {"success": False, "error": "Invalid input"}
        
        # 通过接口调用，不关心底层实现
        user_id = self.storage.save_user(name, email)
        return {"success": user_id is not None, "user_id": user_id}

9.2 配置文件驱动切换（SQLite → MySQL）

config/database.yaml
development:
  driver: sqlite
  path: "./data/dev.db"

production:
  driver: mysql
  host: ${DB_HOST}
  port: ${DB_PORT:-3306}
  database: ${DB_NAME}
  username: ${DB_USER}
  password: ${DB_PASSWORD}
  pool_size: 10
  timeout: 30  # 外部调用超时（规则要求）
工厂模式创建存储实例
# src/python/config/db_factory.py
import yaml
import os
from typing import Dict, Any

class DatabaseFactory:
    @staticmethod
    def create_storage(env: str = "development") -> UserStorage:
        with open("config/database.yaml") as f:
            config = yaml.safe_load(f)[env]
        
        if config["driver"] == "sqlite":
            from src.python.auth.sqlite_impl import SQLiteDatabase
            return SQLiteDatabase(config["path"])
        
        elif config["driver"] == "mysql":
            from src.python.auth.mysql_impl import MySQLDatabase
            return MySQLDatabase(
                host=os.getenv("DB_HOST", config["host"]),
                port=int(os.getenv("DB_PORT", config["port"])),
                database=os.getenv("DB_NAME"),
                username=os.getenv("DB_USER"),
                password=os.getenv("DB_PASSWORD"),
                pool_size=config.get("pool_size", 10),
                timeout=config.get("timeout", 30)  # 规则：外部调用必须超时
            )
        
        raise ValueError(f"Unsupported driver: {config['driver']}")

📊 十、质量监控与持续改进

10.1 质量指标看板

指标 目标值 检查方式 工具
测试覆盖率 ≥ 80% pytest --cov pytest-cov
代码复杂度 ≤ 15 ruff --select=PL Ruff (PLR, PLC)
重复代码率 ≤ 5% radon cc Radon
CI 通过率 ≥ 95% GitHub Actions GitHub
AI 修复成功率 ≥ 70% 日志统计 自定义脚本

10.2 每日质量报告脚本

创建 scripts/generate_quality_report.sh：

#!/bin/bash
echo "# 📊 每日质量报告 $(date '+%Y-%m-%d')"
echo ""

echo "## 1️⃣ 测试覆盖率"
pytest --cov=src --cov-report=term-missing 2>&1 | grep -A 3 "TOTAL"
echo ""

echo "## 2️⃣ 代码复杂度（>15 的函数）"
ruff check src/ --select=PLR091 --output-format=concise | head -n 10
echo ""

echo "## 3️⃣ 重复代码检测"
radon cc src/ -a -nb 2>&1 | grep -E "^[A-Z]" | head -n 10
echo ""

echo "## 4️⃣ 最近提交统计"
git log --since="24 hours ago" --oneline --no-merges | wc -l | xargs echo "提交数:"
echo ""

echo "## 5️⃣ AI 修复记录"
if [ -f "ai_fix.log" ]; then
    tail -n 20 ai_fix.log
else
    echo "📭 无 AI 修复记录"
fi

10.3 AI 改进闭环

生产环境错误

收集错误日志

AI 根因分析

生成修复方案

更新 rules.md

更新 agent.build.prompt

下一版本防御
自动更新 rules.md 示例
# scripts/update_rules_from_errors.sh
#!/bin/bash
ERROR_LOG="$1"

if [ -z "$ERROR_LOG" ]; then
    echo "Usage: $0 <error_log_file>"
    exit 1
fi

# 请求 AI 分析错误并生成规则建议
RULE_SUGGESTION=$(opencode run "分析以下生产错误日志，生成 1-3 条可添加到 rules.md 的工程约束规则，
要求：具体、可执行、能预防同类错误。输出格式：
- [规则类别] 规则描述

错误日志：
$(cat $ERROR_LOG)" --model deepseek/deepseek-v4-pro)

# 追加到 rules.md
echo "" >> ~/.opencode/rules.md
echo "# Auto-generated on $(date)" >> ~/.opencode/rules.md
echo "$RULE_SUGGESTION" >> ~/.opencode/rules.md

echo "✅ 已更新 rules.md，建议人工审核后提交"

🚀 十一、终极行动清单（今日即可开始）

🌟 第 1 天：环境搭建（30 分钟）

  • Mac/WSL2 安装 OpenCode + 验证版本
  • 创建 ~/.config/opencode/opencode.json
  • 创建 ~/.opencode/rules.md
  • 配置 DEEPSEEK_API_KEY 环境变量
  • 验证：opencode run "Hello" --model deepseek/deepseek-v4-pro

🌟 第 2-3 天：项目初始化（2 小时）

  • 创建新项目并应用结构模板
  • 配置 pyproject.toml / pom.xml（含测试依赖）
  • 编写第一个模块 + 测试（遵循四段式输出）
  • 配置 .pre-commit-config.yaml
  • 运行 pre-commit install 并验证门禁

🌟 第 4-5 天：自动化工作流（2 小时）

  • 部署 scripts/ai-fix.sh
  • 部署 scripts/check_coverage.sh（精确覆盖率提取）
  • 测试 git commit 触发完整门禁流程
  • 配置 scripts/generate_docs.sh 生成架构图

🌟 第 6-7 天：CI/CD 集成（1 小时）

  • 创建 .github/workflows/ci.yml（含 OpenCode 安装步骤）
  • 在 GitHub Secrets 添加 DEEPSEEK_API_KEY
  • 配置分支保护规则（要求状态检查）
  • 推送代码验证 CI 流水线

🆘 遇到问题？精准排查指南

问题 1：OpenCode 配置不生效

# 诊断命令
opencode debug config

# 检查项：
# 1. ~/.config/opencode/opencode.json 语法（用 jq 验证）
jq . ~/.config/opencode/opencode.json

# 2. 环境变量是否加载
echo $DEEPSEEK_API_KEY

# 3. rules.md 路径是否正确
ls -la ~/.opencode/rules.md

问题 2：Pre-commit 运行失败

# 手动运行排查
pre-commit run ruff-check --all-files
pre-commit run mypy --all-files

# 常见修复：
# - Ruff 报错：添加 # noqa: XXX 或调整 .ruff.toml
# - MyPy 报错：添加 # type: ignore 或完善类型注解

问题 3：AI 修复脚本提取失败

# 检查 fix.log 格式
cat fix.log | grep -A 5 "【测试】"

# 调试 sed 提取
echo "【测试】" | sed -n '/【测试】/,/【实现】/p'

# 备选方案：改用 Python 解析
python3 -c "
import re
with open('fix.log') as f:
    content = f.read()
test_part = re.search(r'【测试】(.*?)【实现】', content, re.DOTALL)
if test_part:
    with open('temp_test.py', 'w') as out:
        out.write(test_part.group(1).strip())
"

问题 4：CI/CD 中 OpenCode 命令失败

# 调试步骤：
- name: Debug OpenCode
  run: |
    which opencode
    opencode --version
    opencode run "test" --model deepseek/deepseek-v4-pro
  env:
    DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}

💡 核心认知：为什么这套方案能显著降低 Bug 率？

传统 AI 开发痛点 本方案解决策略
仅生成代码，无测试约束 测试先行 + 覆盖率门禁，从源头拦截
无结构约束，代码混乱 四段式输出 + rules.md，强制工程规范
人工验证，效率低下 Pre-commit + CI 门禁，自动化拦截烂代码
架构不清晰，难以维护 自动生成架构图 + 模块关系，可视化依赖
扩展困难，耦合高 依赖倒置 + 配置驱动，换实现零代码修改
上下文溢出，生成截断 compaction + tool_output，智能压缩防崩溃
工具输出过长，分析困难 max_lines/max_bytes，截断关键信息保留

✅ 终极价值：通过工程化约束 + 自动化门禁 + AI 自愈，把 AI 从"写代码工具"升级为"质量保障体系"。不是让 AI 写得更好，而是让系统设计让 AI 无法写出烂代码。

📌 最后提醒：本教程所有工具均为免费开源（仅需 DeepSeek API 付费），按此路径执行，2 周内即可构建工业级 AI 开发体系。

# 人工智能 # elasticsearch
Logo
北京朝阳AI社区

更多推荐

cover

76、【Agent】【OpenCode】用户对话提示词（addtionalProperties 属性）

avatar 北京朝阳AI社区
cover

AI Agent构建秘籍：从ReAct到CodeAct，手把手教你打造智能体！

avatar 北京朝阳AI社区
cover

75、【Agent】【OpenCode】用户对话提示词（question 工具）

avatar 北京朝阳AI社区