9.2 KiB
OpenCode
OpenCode 是一个强大的交互式 CLI 工具，帮助开发者高效地完成软件工程任务。它提供智能化的命令、可复用的技能以及扩展插件，支持自动化工作流程。
🌟 核心特性
- 智能命令系统 - 自动生成提交信息、管理版本标签、安全地暂存文件
- 可复用技能 - 预定义的开发工作流，如 Git 工作流、Android 开发等
- 插件扩展 - 支持自定义插件来扩展功能
- 安全优先 - 自动过滤敏感文件，防止意外泄露凭证
- 中文友好 - 完整的中文支持和交互提示
📋 目录结构
opencode/
├── command/ # CLI 命令定义
│ ├── git-*.md # Git 相关命令
│ ├── gitea-*.md # Gitea 集成命令
│ └── review.md # 代码审查命令
├── skill/ # 可复用技能库
│ ├── git/ # Git 工作流程指南
│ ├── android/ # Android 开发指南
│ ├── ios/ # iOS 开发指南
│ └── ...
├── plugin/ # 插件扩展
│ └── notification.ts # 通知插件
├── opencode.json # 项目配置
└── AGENTS.md # 开发规范和指南
🚀 快速开始
前置条件
- Git (2.0+) - 用于版本控制
- Node.js (14+) - 运行时环境
- Bash - 命令行环境（macOS/Linux）
- PowerShell - Windows 环境支持（可选）
安装
# 克隆或下载 OpenCode 项目
cd ~/.config/opencode
# 验证安装
opencode --version
📚 核心组件使用指南
1. Commands（命令系统）
命令是 OpenCode 最直接的使用方式，使用 / 前缀调用。
Git 命令
/git-status - 查看仓库状态
/git-status
# 输出：当前分支、暂存区文件、未暂存修改、未跟踪文件
/git-add - 智能暂存文件（自动过滤敏感文件）
/git-add
# 选项：
# - y/yes 仅暂存已修改文件
# - all/u 暂存所有安全文件（推荐）
# - force 强制暂存所有文件（包括敏感文件，谨慎）
# - no/cancel 取消操作
/git-commit - 自动生成提交信息并提交
/git-commit
# 功能：
# - 自动分析文件变更
# - 按 Conventional Commits 生成提交信息
# - 自动更新版本号（如需要）
# - 创建版本标签
/git-push - 提交、创建标签、推送到远程（一键完成）
/git-push
# 执行流程：
# 1. 分析暂存的变更
# 2. 生成提交信息
# 3. 创建版本标签（如需要）
# 4. 推送提交到远程
# 5. 推送标签到远程
/git-pull - 拉取远程最新变更
/git-pull
# 功能：
# - 获取远程更新
# - 自动合并变更
# - 处理合并冲突（需要时）
/git-push-tags - 推送所有标签到远程
/git-push-tags
# 用于推送忘记推送的标签或批量推送多个标签
Gitea 集成命令
/gitea-config - 查看当前 Gitea 配置
/gitea-config
# 显示：Gitea URL、默认组织、Token 状态、Runner 信息
/gitea-create-repo - 在 Gitea 创建新仓库
/gitea-create-repo <owner>/<repo> [private|public]
# 示例：
# /gitea-create-repo ai/my-project # 创建私有仓库
# /gitea-create-repo ai/my-project public # 创建公开仓库
/gitea-create-runner - 创建并启动 Gitea Actions Runner
/gitea-create-runner [runner-name]
# 功能：
# - 自动安装 act_runner（如果未安装）
# - 自动检测系统环境和架构
# - 生成合适的 labels
# - 注册并启动 runner
/gitea-list-runners - 列出所有已配置的 Runners
/gitea-list-runners
# 显示：Runner 名称、状态（运行中/已停止）
其他 Gitea 命令：
/gitea-reset- 重置 Gitea 配置/gitea-switch-org- 切换默认组织/gitea-delete-runner- 删除已配置的 Runner
2. Skills（技能库）
技能是预定义的开发工作流程指南，包含详细的步骤和最佳实践。
Git 技能 (skill/git/)
完整的 Git 工作流程指南
包含内容：
- Conventional Commits 提交规范
- 版本管理和 Semantic Versioning
- Tag 命名规范
- Polyrepo vs Monorepo 差异
- 常见 Git 操作和最佳实践
快速查看：
# 查看 Git 技能文档
cat skill/git/SKILL.md
Android 开发技能 (skill/android/)
Android 项目开发规范和最佳实践
iOS 开发技能 (skill/ios/)
iOS 项目开发规范和最佳实践
其他技能
skill/go-developer/- Go 后端开发指南skill/electron-developer/- Electron 桌面应用指南
3. Plugins（插件扩展）
插件用于扩展 OpenCode 的功能。
通知插件 (plugin/notification.ts)
用于发送开发相关的通知（邮件、Slack、钉钉等）
使用场景：
- 构建完成时通知
- 测试失败时告警
- 部署成功时提醒
🔑 配置和环境
配置文件位置
- macOS/Linux:
~/.config/opencode/ - Windows:
%USERPROFILE%\.config\opencode\
主要配置文件
opencode.json - 项目级配置
{
"dependencies": {
"@opencode-ai/plugin": "1.1.15"
}
}
AGENTS.md - 全局开发规范
- 语言偏好（中文）
- 代码风格
- Git 提交规范
- 任务管理指南
Gitea 配置
首次使用 Gitea 相关命令时需要配置：
/gitea-reset
# 按提示输入：
# - Gitea 服务器 URL
# - API Token
# - 默认组织（可选）
配置存储在：~/.config/gitea/config.env
💡 工作流程示例
示例 1：完整的开发流程
# 1. 查看当前状态
/git-status
# 2. 智能暂存文件（自动过滤敏感文件）
/git-add
# 选择 "all" 暂存所有安全文件
# 3. 推送到远程（包括提交、标签、推送）
/git-push
# 一键完成：生成提交信息 → 创建版本标签 → 推送到远程
示例 2：创建 Gitea 仓库并配置 Runner
# 1. 初始化 Gitea 配置
/gitea-reset
# 2. 创建新仓库
/gitea-create-repo ai/my-project
# 3. 创建 Actions Runner
/gitea-create-runner
# 4. 验证配置
/gitea-config
示例 3：处理合并冲突
# 1. 拉取远程更新
/git-pull
# 如果有冲突，按提示解决
# 2. 手动解决文件中的冲突标记（<<<<<<< / ======= / >>>>>>>）
# 3. 暂存解决后的文件
git add <conflict-file>
# 4. 完成合并
git commit
⚠️ 安全特性
OpenCode 优先考虑安全，自动过滤敏感文件：
自动排除的文件模式
.env*- 环境变量文件*.key,*.pem,*.p8- 私钥文件credentials.json,secrets.json- 凭证文件.aws/*,.gcloud/*,.ssh/*- 云服务和 SSH 密钥node_modules/,vendor/,.venv/- 依赖目录dist/,build/,.next/- 构建产物.DS_Store,Thumbs.db- 系统文件
暂存选项
- 默认 (y) - 仅暂存已跟踪的修改文件
- 推荐 (all/u) - 暂存所有安全文件（包括未跟踪）
- 谨慎 (force) - 强制暂存所有文件（包括敏感文件）
📖 提交信息规范
OpenCode 遵循 Conventional Commits 规范。
提交类型
feat- 新功能fix- 修复 bugdocs- 文档更新style- 代码风格（不影响功能）refactor- 代码重构perf- 性能优化test- 测试相关chore- 维护任务ci- CI/CD 配置build- 构建系统
提交消息格式
<type>(<scope>): <subject>
<body>
<footer>
示例：
feat(android): 添加用户认证功能
- 实现 OAuth2 支持
- 集成 JWT Token 验证
- 添加用户会话管理
Closes #123
🔄 版本管理
OpenCode 采用 Semantic Versioning (MAJOR.MINOR.PATCH)
自动版本更新规则
feat类型 → MINOR 版本 +1 (1.2.0 → 1.3.0)fix/perf类型 → PATCH 版本 +1 (1.2.3 → 1.2.4)- Breaking Change → MAJOR 版本 +1 (1.2.3 → 2.0.0)
注意： 仅文档更新、测试、重构等不会更新版本号。
🆘 常见问题
Q: 暂存区为空时如何提交？
A: 先使用 /git-add 暂存文件，然后使用 /git-commit 或 /git-push 提交。
Q: 如何跳过版本标签创建？
A: 在 /git-commit 或 /git-push 时，输入 "skip tag" 或 "skip" 选项。
Q: 如何强制暂存敏感文件？
A: 在 /git-add 时选择 "force" 选项，然后输入 "confirm" 确认。
Q: Gitea 配置丢失怎么办？
A: 运行 /gitea-reset 重新初始化配置。
Q: 如何推送仅有的标签而不推送提交？
A: 使用 /git-push-tags 命令。
📞 获取帮助
在 OpenCode CLI 中：
# 列出所有可用命令
ctrl+p
# 查看特定命令帮助
/command-name --help
# 获取反馈和问题报告
# https://github.com/anomalyco/opencode
📝 相关文档
📄 许可证
OpenCode 项目遵循相关许可证。详见项目根目录的 LICENSE 文件。
提示： 使用 OpenCode 时，遵循项目的规范和最佳实践，可以显著提高开发效率和代码质量！