397 lines
9.2 KiB
Markdown
397 lines
9.2 KiB
Markdown
# 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 环境支持（可选）
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
# 克隆或下载 OpenCode 项目
|
||
cd ~/.config/opencode
|
||
|
||
# 验证安装
|
||
opencode --version
|
||
```
|
||
|
||
## 📚 核心组件使用指南
|
||
|
||
### 1. Commands（命令系统）
|
||
|
||
命令是 OpenCode 最直接的使用方式，使用 `/` 前缀调用。
|
||
|
||
#### Git 命令
|
||
|
||
**`/git-status`** - 查看仓库状态
|
||
```bash
|
||
/git-status
|
||
# 输出：当前分支、暂存区文件、未暂存修改、未跟踪文件
|
||
```
|
||
|
||
**`/git-add`** - 智能暂存文件（自动过滤敏感文件）
|
||
```bash
|
||
/git-add
|
||
# 选项：
|
||
# - y/yes 仅暂存已修改文件
|
||
# - all/u 暂存所有安全文件（推荐）
|
||
# - force 强制暂存所有文件（包括敏感文件，谨慎）
|
||
# - no/cancel 取消操作
|
||
```
|
||
|
||
**`/git-commit`** - 自动生成提交信息并提交
|
||
```bash
|
||
/git-commit
|
||
# 功能：
|
||
# - 自动分析文件变更
|
||
# - 按 Conventional Commits 生成提交信息
|
||
# - 自动更新版本号（如需要）
|
||
# - 创建版本标签
|
||
```
|
||
|
||
**`/git-push`** - 提交、创建标签、推送到远程（一键完成）
|
||
```bash
|
||
/git-push
|
||
# 执行流程：
|
||
# 1. 分析暂存的变更
|
||
# 2. 生成提交信息
|
||
# 3. 创建版本标签（如需要）
|
||
# 4. 推送提交到远程
|
||
# 5. 推送标签到远程
|
||
```
|
||
|
||
**`/git-pull`** - 拉取远程最新变更
|
||
```bash
|
||
/git-pull
|
||
# 功能：
|
||
# - 获取远程更新
|
||
# - 自动合并变更
|
||
# - 处理合并冲突（需要时）
|
||
```
|
||
|
||
**`/git-push-tags`** - 推送所有标签到远程
|
||
```bash
|
||
/git-push-tags
|
||
# 用于推送忘记推送的标签或批量推送多个标签
|
||
```
|
||
|
||
#### Gitea 集成命令
|
||
|
||
**`/gitea-config`** - 查看当前 Gitea 配置
|
||
```bash
|
||
/gitea-config
|
||
# 显示：Gitea URL、默认组织、Token 状态、Runner 信息
|
||
```
|
||
|
||
**`/gitea-create-repo`** - 在 Gitea 创建新仓库
|
||
```bash
|
||
/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
|
||
```bash
|
||
/gitea-create-runner [runner-name]
|
||
# 功能：
|
||
# - 自动安装 act_runner（如果未安装）
|
||
# - 自动检测系统环境和架构
|
||
# - 生成合适的 labels
|
||
# - 注册并启动 runner
|
||
```
|
||
|
||
**`/gitea-list-runners`** - 列出所有已配置的 Runners
|
||
```bash
|
||
/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 操作和最佳实践
|
||
|
||
快速查看：
|
||
```bash
|
||
# 查看 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`** - 项目级配置
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"@opencode-ai/plugin": "1.1.15"
|
||
}
|
||
}
|
||
```
|
||
|
||
**`AGENTS.md`** - 全局开发规范
|
||
- 语言偏好（中文）
|
||
- 代码风格
|
||
- Git 提交规范
|
||
- 任务管理指南
|
||
|
||
### Gitea 配置
|
||
|
||
首次使用 Gitea 相关命令时需要配置：
|
||
|
||
```bash
|
||
/gitea-reset
|
||
# 按提示输入：
|
||
# - Gitea 服务器 URL
|
||
# - API Token
|
||
# - 默认组织（可选）
|
||
```
|
||
|
||
配置存储在：`~/.config/gitea/config.env`
|
||
|
||
## 💡 工作流程示例
|
||
|
||
### 示例 1：完整的开发流程
|
||
|
||
```bash
|
||
# 1. 查看当前状态
|
||
/git-status
|
||
|
||
# 2. 智能暂存文件（自动过滤敏感文件）
|
||
/git-add
|
||
# 选择 "all" 暂存所有安全文件
|
||
|
||
# 3. 推送到远程（包括提交、标签、推送）
|
||
/git-push
|
||
# 一键完成：生成提交信息 → 创建版本标签 → 推送到远程
|
||
```
|
||
|
||
### 示例 2：创建 Gitea 仓库并配置 Runner
|
||
|
||
```bash
|
||
# 1. 初始化 Gitea 配置
|
||
/gitea-reset
|
||
|
||
# 2. 创建新仓库
|
||
/gitea-create-repo ai/my-project
|
||
|
||
# 3. 创建 Actions Runner
|
||
/gitea-create-runner
|
||
|
||
# 4. 验证配置
|
||
/gitea-config
|
||
```
|
||
|
||
### 示例 3：处理合并冲突
|
||
|
||
```bash
|
||
# 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](https://www.conventionalcommits.org/) 规范。
|
||
|
||
### 提交类型
|
||
|
||
- `feat` - 新功能
|
||
- `fix` - 修复 bug
|
||
- `docs` - 文档更新
|
||
- `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 中：
|
||
|
||
```bash
|
||
# 列出所有可用命令
|
||
ctrl+p
|
||
|
||
# 查看特定命令帮助
|
||
/command-name --help
|
||
|
||
# 获取反馈和问题报告
|
||
# https://github.com/anomalyco/opencode
|
||
```
|
||
|
||
## 📝 相关文档
|
||
|
||
- [Git 工作流程指南](./skill/git/SKILL.md)
|
||
- [全局开发规范](./AGENTS.md)
|
||
- [命令参考](./command/)
|
||
- [技能库](./skill/)
|
||
|
||
## 📄 许可证
|
||
|
||
OpenCode 项目遵循相关许可证。详见项目根目录的 LICENSE 文件。
|
||
|
||
---
|
||
|
||
**提示：** 使用 OpenCode 时，遵循项目的规范和最佳实践，可以显著提高开发效率和代码质量！
|