OpenCode 团队协作指南：用配置共享与 Git 管理实现 AI 编程助手的标准化落地

OpenCode 团队协作指南：用配置共享与 Git 管理实现 AI 编程助手的标准化落地

引言

当个人开发者尝到 OpenCode 带来的效率提升后，很自然会想把它推广到整个团队。然而，每个人的模型配置不同、规则偏好不同、自定义命令也不同，如果没有统一的管理方式，团队的 AI 编程体验就会碎片化：张三用 GPT-4 写出来的代码风格是一种，李四用 Claude 生成的又是另一种，代码评审时各说各话。本文将围绕「标准化」和「可共享」两个核心，讲解如何通过 Git 仓库管理和 OpenCode 自身的配置机制，在团队中高效落地 AI 编程助手的统一配置。

一、配置文件的 Git 化管理

OpenCode 的核心配置集中在项目根目录的 opencode.json 文件中。要实现团队共享，第一步就是将它纳入 Git 版本控制。

1.1 项目级配置 vs 全局配置

首先要区分两种配置作用域：

| 配置层级 | 配置文件路径 | 适用范围 |
|---------|-------------|---------|
| 项目级 | 项目根目录/opencode.json | 团队共享，纳入 Git |
| 用户级 | ~/.config/opencode/opencode.json | 个人偏好，不纳入 Git |
| 混合 | 项目级 + ~/.config/opencode/config.json | 两者合并，用户级覆盖项目级 |

推荐的做法是：将模型提供商、API Key、个性化快捷键等敏感或个人偏好的配置放在用户级，将规则、自定义命令、工具配置、MCP 服务器等团队通用的配置放在项目级。

1.2 示例：团队级 opencode.json

{
  "name": "my-project",
  "description": "团队统一配置",
  "rules": [
    "遵循 PSR-12 编码规范",
    "所有新增代码必须包含单元测试",
    "注释使用中文，代码中的标识符使用英文",
    "不允许引入新的全局函数"
  ],
  "commands": {
    "test": {
      "description": "运行测试并生成覆盖率报告",
      "command": "php artisan test --coverage"
    },
    "lint": {
      "description": "运行代码风格检查",
      "command": "vendor/bin/pint --test"
    },
    "review": {
      "description": "对当前文件进行代码审查",
      "command": "opencode review"
    }
  },
  "formatters": {
    "php": "vendor/bin/pint",
    "javascript": "npx prettier --write"
  }
}

团队成员只需 git pull 拉取最新配置，即可获得一致的规则和命令。

二、AGENTS.md：团队的 AI 行为规范书

AGENTS.md 是 OpenCode 中最重要的规则文件之一，它告诉 AI 助手「在这个项目中应该怎么做」。对于团队协作来说，这份文件相当于一份正式的开发约定。

2.1 团队级 AGENTS.md 模板

# 项目开发规范

## 代码风格
- PHP 代码使用 PSR-12 标准
- JavaScript/TypeScript 使用 Prettier 默认配置
- 缩进使用 4 个空格，不使用 TAB

## 提交规范
- 提交信息遵循 Conventional Commits 格式
- feat: 新功能
- fix: 修复 Bug
- refactor: 重构
- test: 测试相关
- docs: 文档变更

## 测试要求
- 所有新功能必须有对应的单元测试
- 测试覆盖率不得低于 80%
- 使用 Pest PHP 作为测试框架

## 数据库规范
- 所有表必须有 created_at 和 updated_at 字段
- 软删除使用 Laravel 内置的 SoftDeletes trait
- 索引命名：idx_表名_列名

2.2 按模块拆分子 Agent

对于大型项目，可以为不同模块编写独立的规则文件：

.opencode/
├── agents/
│   ├── api-agent.md       # API 开发规范
│   ├── frontend-agent.md  # 前端开发规范
│   └── database-agent.md  # 数据库迁移规范
├── skills/
│   └── code-review.md     # 代码审查技能
├── auto_article.md
└── auto_prompt.md

然后在 opencode.json 中按需引用：

{
  "agents": {
    "api": {
      "description": "API 开发助手",
      "instructions": ".opencode/agents/api-agent.md"
    },
    "frontend": {
      "description": "前端开发助手",
      "instructions": ".opencode/agents/frontend-agent.md"
    }
  }
}

三、Skill 系统的团队复用

Skill 是 OpenCode 中最具复用价值的功能模块。团队可以将常用的开发流程封装成 Skill，通过 Git 仓库统一分发。

3.1 创建团队共享 Skill

在项目目录下创建 .opencode/skills/ 文件夹，编写通用的开发流程技能。

示例：代码审查 Skill（.opencode/skills/code-review.md）

# Code Review Skill

当你被要求进行代码审查时，执行以下步骤：

1. **安全性检查**
   - 是否存在 SQL 注入风险（使用 Eloquent ORM 而非 raw queries）
   - API Key 和密码是否硬编码
   - 是否存在 XSS 漏洞（所有输出是否经过转义）

2. **性能检查**
   - 是否存在 N+1 查询问题
   - 是否有未加索引的查询字段
   - 是否有不必要的循环嵌套

3. **代码质量**
   - 函数是否过长（超过 50 行应拆分为小函数）
   - 命名是否清晰表达意图
   - 是否有重复代码可抽取

4. **测试覆盖**
   - 新逻辑是否有对应测试
   - 异常路径是否被覆盖

团队成员在任何项目的代码审查中，只需输入 /skill code-review 即可调用这套标准的审查流程。

3.2 通过 Git Submodule 共享 Skill 库

当团队拥有多个项目时，可以将 Skill 抽离为一个独立仓库，通过 Git Submodule 统一引用：

git submodule add https://github.com/team/opencode-skills.git .opencode/skills

这样所有项目共享同一套技能库，更新技能时只需 git submodule update --remote。

四、MCP 服务器的统一管理

MCP（Model Context Protocol）服务器为 OpenCode 拓展了访问数据库、文件系统、API 等外部能力。团队可以共建和共享 MCP 服务器配置。

4.1 共享的 MCP 配置

在项目级 opencode.json 中配置团队通用的 MCP 服务器：

{
  "mcpServers": {
    "database": {
      "description": "数据库查询服务",
      "command": "npx",
      "args": ["@team/mcp-database-server"],
      "env": {
        "DB_HOST": "${DB_HOST}",
        "DB_PORT": "${DB_PORT}",
        "DB_DATABASE": "${DB_DATABASE}",
        "DB_USERNAME": "${DB_USERNAME}"
      }
    },
    "gitlab": {
      "description": "GitLab API 集成",
      "command": "npx",
      "args": ["@team/mcp-gitlab-server"],
      "env": {
        "GITLAB_TOKEN": "${GITLAB_TOKEN}"
      }
    }
  }
}

敏感信息通过环境变量注入，不写入配置文件本身。可以在 .env.example 中列出所需变量，让团队成员自行设置。

4.2 权限规则的统一管理

OpenCode 的权限规则可以细粒度控制 AI 能访问的文件和执行的操作。团队可以在 .opencode/permissions.json 中定义统一的权限策略：

{
  "allow": [
    "read:src/**/*.php",
    "read:resources/**/*.blade.php",
    "write:tests/**/*.php",
    "run:composer *",
    "run:php artisan *",
    "run:npm *"
  ],
  "deny": [
    "write:.env",
    "write:config/**/*.php",
    "run:rm -rf",
    "run:drop *"
  ],
  "allowedDomains": [
    "packagist.org",
    "registry.npmjs.org",
    "github.com"
  ]
}

既保障了开发效率，又防止了 AI 操作敏感文件或执行危险命令。

五、跨项目 References 共享

OpenCode 的 References 系统允许在一个项目中引用另一个项目的代码。团队场景下，这特别适合共享公共库和基础包。

5.1 配置跨项目引用

{
  "references": {
    "core": {
      "description": "公共核心库",
      "url": "git@github.com:team/core-library.git",
      "path": "../core-library"
    },
    "packages": {
      "description": "内部 Composer 包",
      "path": "../satis"
    }
  }
}

当 AI 需要理解某个内部包的用法时，OpenCode 会自动搜索引用项目中的相关代码，给出更准确的建议。

六、新人 onboarding 的最佳实践

当新成员加入团队时，标准化的 OpenCode 配置可以大幅降低上手成本：

拉取项目代码：git clone git@github.com:team/project.git

配置用户级 API Key：编辑 ~/.config/opencode/opencode.json 填入模型和密钥

安装 MCP 依赖：npm install -g @team/mcp-servers

启动 OpenCode：在项目目录运行 opencode，所有团队配置自动生效

整个过程不超过 10 分钟，新人就能拥有与资深成员一致的 AI 编程环境。

七、配置的版本管理与变更通知

团队协作中，配置变更是常见需求。推荐遵循以下流程：

• 将配置文件的变更纳入常规 Code Review 流程
• 使用 Conventional Commits 标注变更类型：feat(opencode): 新增 MCP Redis 服务器配置
• 在 CHANGELOG 中记录破坏性变更
• 通过 CI 检查 opencode.json 和 AGENTS.md 的合法性

CI 检查示例

# .github/workflows/opencode-config.yml
name: Validate OpenCode Config

on:
  pull_request:
    paths:
      - 'opencode.json'
      - '.opencode/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate JSON
        run: jq empty opencode.json
      - name: Check required fields
        run: |
          jq -e '.rules' opencode.json || exit 1
          jq -e '.commands' opencode.json || exit 1

总结

团队级 OpenCode 配置管理的核心在于三个原则：

可共享 — 通过 Git 管理项目级配置，让所有成员获得一致的 AI 编程环境

可分层 — 项目级配置覆盖通用设置，用户级配置保留个人偏好，两者互不干扰

可扩展 — Skill、MCP、Agents 等模块化机制让团队可以持续积累和复用 AI 工作流资产

将 AI 编程助手从个人玩具升级为团队工程效率武器，关键在于标准化的配置管理。希望本文的实践方案能为你在团队中落地 OpenCode 提供清晰的路径参考。