OpenCode 项目协作与工作流集成指南

OpenCode 不仅能独立工作，还能深度融入你的团队协作工具和开发工作流。从 GitHub/GitLab 集成到 LSP 服务器，从 References 引用系统到上下文管理，从会话分享到团队标准化——本文将覆盖所有协作相关功能。

一、GitHub / GitLab 集成

GitHub 集成

OpenCode 可以直接在 GitHub Issues 和 Pull Requests 中工作：

# 处理 Issue
opencode -p "查看 GitHub issue #42 的描述，实现其中要求的功能"

# 审查 PR
opencode -p "审查 PR #128 的代码变更，关注安全性和性能"

通过 GitHub MCP 服务器可以获得更完整的 GitHub 集成：

{
  "mcp": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

配置后可以：

帮我创建 Issue：「用户登录页面需要支持 OAuth 2.0」
帮我把当前分支推送到 origin 并创建一个 Draft PR
查看 repo 中所有标记为 bug 且 assignee 是我的 Issue

GitHub App 集成

安装 OpenCode GitHub App 后，可以在 Issue 中通过 /opencode 命令触发 AI 操作：

<!-- 在 GitHub Issue 评论中 -->
/opencode 帮我实现这个功能

/opencode review

GitLab 集成

{
  "mcp": {
    "gitlab": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_TOKEN}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Git Worktree 隔离工作

OpenCode 内置了 Git Worktree 支持，可以在隔离的工作副本中执行实验性修改：

@using-git-worktrees 创建一个 worktree 来实验新的认证方案

二、LSP 服务器集成

通过接入 LSP（Language Server Protocol），OpenCode 可以获得编辑器级别的代码理解能力。

配置 LSP 服务器

{
  "lsp": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "rust": {
      "command": "rust-analyzer",
      "args": []
    },
    "go": {
      "command": "gopls"
    },
    "python": {
      "command": "pyright-langserver",
      "args": ["--stdio"]
    },
    "lua": {
      "command": "lua-language-server"
    },
    "svelte": {
      "command": "svelte-language-server",
      "args": ["--stdio"]
    },
    "vue": {
      "command": "vue-language-server",
      "args": ["--stdio"]
    }
  }
}

LSP 提供的能力

接入 LSP 后，OpenCode 可以：

  • 类型推断：精确了解变量类型，生成类型安全的代码
  • 引用查找：找到所有调用某函数的地方
  • 诊断信息：获取编译器的警告和错误
  • 代码补全：更精准的智能补全
  • 定义跳转：理解代码间的引用关系
  • 重命名：安全地重构标识符

实战示例

启用 TypeScript LSP 后：

帮我重构 UserService 类，把直接的数据库调用改成 Repository 模式。
注意：需要更新所有引用 UserService 的地方。

OpenCode 会通过 LSP 找到所有引用点，确保重构的完整性。

三、References 引用系统

References 让 OpenCode 可以跨项目引用代码和知识。

引用方式

在对话中使用 @ 符号引用：

@path/to/file.ts           # 引用当前项目的文件
@/absolute/path/file.rs    # 引用绝对路径文件
@../other-project/src/     # 引用其他项目的目录
@https://example.com/doc   # 引用网页内容
@file:src/utils.ts:42-58   # 引用文件的特定行范围

引用配置

{
  "references": {
    "enabled": true,
    "maxReferencedFiles": 10,
    "followSymlinks": true,
    "sharedKnowledge": [
      "~/dev/shared-docs/",
      "~/dev/company-standards/"
    ]
  }
}

跨项目知识共享

@~/dev/shared-docs/api-standards.md 参考这个文档，检查当前项目的 API 是否合规

四、上下文管理

合理管理上下文窗口是使用 LLM 高效工作的关键。

上下文配置

{
  "session": {
    "maxContextTokens": 180000,
    "autoSummarize": true,
    "summarizeThreshold": 0.75
  },
  "context": {
    "indexOnStart": false,
    "maxFiles": 40,
    "maxFileSize": 100000,
    "exclude": [
      "node_modules",
      "dist",
      ".git",
      "vendor",
      "*.lock",
      "*.min.js",
      "*.map",
      "*.generated.*"
    ],
    "includeExtensions": [
      ".ts", ".tsx", ".js", ".jsx",
      ".rs", ".go", ".py",
      ".json", ".yaml", ".yml",
      ".md"
    ]
  }
}

上下文智能总结

当上下文接近上限时，OpenCode 会自动总结历史对话：

[自动总结] 本次会话已进行了 15 轮对话，以下是要点摘要：
- 完成了用户认证模块的重构
- 添加了 JWT token 刷新机制
- 修复了登录页面的 XSS 漏洞
- 正在进行：API 速率限制功能

你也可以手动触发总结：

/compact

上下文窗口策略

| 策略 | 适用场景 |
|------|----------|
| 保持完整历史 | 同一功能开发，需要连贯上下文 |
| 定期总结 | 长时间开发，涉及多个模块 |
| 新会话开始 | 切换到完全不同的任务 |

五、会话分享

OpenCode 支持将当前会话导出为可分享的链接：

/share

生成一个临时链接，团队成员可以通过浏览器查看你的对话：

  • 只读模式：查看者只能看到对话内容
  • 临期链接：默认 24 小时后过期
  • 可撤销：随时可以撤销分享

配置会话分享：

{
  "sharing": {
    "enabled": true,
    "defaultExpiry": "24h",
    "maxExpiry": "7d",
    "requireAuth": false,
    "allowFork": true
  }
}

当 allowFork 为 true 时，其他人可以从你的分享链接创建自己的会话副本继续工作。

六、团队协作配置

团队标准化配置

将项目配置提交到 Git，确保团队统一的工作方式：

// .opencode/opencode.json（提交到 Git）
{
  "agent": "build",
  "agents": {
    "build": {
      "permissions": {
        "allow": ["src/**", "tests/**"],
        "deny": [".env", "**/secrets/**"]
      }
    }
  },
  "formatters": {
    "prettier": {
      "command": "npx",
      "args": ["prettier", "--write"],
      "extensions": [".ts", ".tsx", ".json", ".md"]
    }
  },
  "formatOnSave": true,
  "context": {
    "exclude": ["node_modules", "dist", ".git"]
  }
}

团队共享的 Commands

.opencode/commands/
├── pr.md         # 创建 PR 的标准流程
├── test.md       # 运行测试的标准流程
├── review.md     # Code Review 标准流程
└── deploy.md     # 部署标准流程

团队共享的 Skills

.opencode/skills/
├── api-design/
│   └── SKILL.md        # API 设计规范
├── code-style/
│   └── SKILL.md        # 编码风格规范
└── database/
    └── SKILL.md        # 数据库操作规范

团队知识库

通过 AGENTS.md 建立团队知识库：

# 团队知识库

## 项目架构决策 (ADR)

1. **为什么使用 NestJS**：团队熟悉 TypeScript，需要企业级架构
2. **为什么使用 PostgreSQL 而非 MongoDB**：需要复杂的事务和关系查询
3. **微服务还是单体**：当前阶段使用模块化单体，未来按需拆分

## 常见问题

### Q：如何添加新的 API 端点？

1. 在对应 Module 的 controllers 中定义路由
2. 使用 class-validator 添加参数验证
3. 在 Swagger 装饰器中添加文档
4. 运行 `npm run test:e2e` 验证

### Q：如何添加数据库迁移？

1. 创建迁移文件：`npm run db:migrate:create -- --name=description`
2. 编写迁移 SQL
3. 运行迁移：`npm run db:migrate`

七、Code Review 集成

PR Review 工作流

<!-- .opencode/commands/review-pr.md -->
请作为 Code Reviewer 审查当前分支相对于 main 的所有变更：

## 审查维度

### 必须通过
- [ ] 代码逻辑是否正确，无明显的 bug
- [ ] 安全漏洞检查（SQL注入、XSS、敏感信息泄露）
- [ ] 数据库查询是否有 N+1 问题

### 应该检查
- [ ] 测试覆盖率是否充分
- [ ] 代码风格是否与项目一致
- [ ] 是否有重复代码可以抽取

### 建议检查
- [ ] 命名是否清晰易懂
- [ ] 注释是否必要且准确
- [ ] 是否有性能优化空间

请按严重程度列出所有发现的问题。

自动化 Code Review

{
  "agents": {
    "reviewer": {
      "description": "自动代码审查 Agent",
      "tools": ["read", "bash", "glob", "grep"],
      "permissions": {
        "edit": false,
        "bash": true,
        "network": false
      },
      "instructions": "你是一个严格的代码审查员。始终从安全性、正确性、性能和可维护性四个维度审查代码。"
    }
  }
}

使用方式：

/agent reviewer
请审查我刚才编写的认证模块代码

八、开发工作流最佳实践

典型的一天工作流

1. 启动 OpenCode
   ↓
2. Plan 模式 → 分析今天要做的任务
   /agent plan
   分析 issues #42 和 #45，确定实现方案
   ↓
3. Build 模式 → 实现功能
   /agent build
   按照计划实现功能
   ↓
4. Reviewer Agent → 自查代码
   /agent reviewer
   审查今天的所有修改
   ↓
5. 创建 PR
   /pr

TDD 工作流

1. 先写测试
   帮我为 UserService.createUser 写测试用例

2. 让 AI 运行测试，确认失败
   运行新写的测试，确认它们如预期地失败

3. 实现代码让测试通过
   实现 UserService.createUser 让所有测试通过

4. 重构
   在不改变测试的前提下优化实现

探索不熟悉代码

/agent plan

分析这个项目的整体架构：
1. 入口文件在哪里
2. 核心模块有哪些
3. 数据流是怎样的
4. 配置是如何管理的

小结

OpenCode 的协作与工作流集成使其从一个「个人工具」升级为「团队平台」。GitHub 集成让 AI 融入代码评审流程，LSP 集成让 AI 获得语言级的代码理解，References 系统打通了跨项目知识共享，会话分享让协作无处不在。

下一篇我们将深入 OpenCode 的调试、网络与故障排除，解决使用过程中可能遇到的所有问题。

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客