ai/opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 在 README 中添加项目统计和核心特性，完善目录结构说明

Browse Source
This commit is contained in:
voson
2026-01-13 10:43:51 +08:00
parent 1af6c39d25
commit b4fd0df70a
1 changed files with 86 additions and 378 deletions
Download Patch File Download Diff File Expand all files Collapse all files

464
README.md
View File

@@ -2,6 +2,13 @@
OpenCode 是一个强大的交互式 CLI 工具，帮助开发者高效地完成软件工程任务。它提供智能化的命令、可复用的技能以及扩展插件，支持自动化工作流程。
## 📊 项目统计
- **15 个 CLI 命令** - 涵盖 Git 和 Gitea 操作
- **7 个开发领域技能库** - Android、iOS、Go、Electron、MQTT 等
- **4 套 CI/CD 工作流模板** - 适配多种项目类型
- **50+ 文档文件** - 完整的指南和参考资料
## 🌟 核心特性
- **智能命令系统** - 自动生成提交信息、管理版本标签、安全地暂存文件
@@ -10,387 +17,88 @@ OpenCode 是一个强大的交互式 CLI 工具，帮助开发者高效地完成
- **安全优先** - 自动过滤敏感文件，防止意外泄露凭证
- **中文友好** - 完整的中文支持和交互提示
## 📋 目录结构
## 📋 完整目录结构
```
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 # 开发规范和指南
├── command/ # CLI 命令定义
│ ├── git-add.md # 智能暂存文件（自动过滤敏感文件）
│ ├── git-commit.md # 自动生成提交信息并提交
│ ├── git-pull.md # 拉取远程最新变更
│ ├── git-push.md # 提交+创建标签+推送（一键完成）
│ ├── git-push-tags.md # 推送所有标签到远程
│ ├── git-status.md # 查看仓库状态
│ ├── gitea-config.md # 查看 Gitea 配置和 Runner 状态
│ ├── gitea-create-repo.md # 在 Gitea 创建新仓库
│ ├── gitea-create-runner.md # 创建并启动 Gitea Actions Runner
│ ├── gitea-delete-runner.md # 删除已配置的 Runner
│ ├── gitea-list-runners.md # 列出所有已配置的 Runners
│ ├── gitea-reset.md # 重置 Gitea 配置
│ ├── gitea-switch-org.md # 切换默认组织
│ └── review.md # 代码审查命令
│
├── skill/ # 可复用技能库和指南
│ ├── git/ # Git 工作流程和版本管理
│ │ ├── SKILL.md # 完整的 Git 工作流程指南
│ │ └── quick-reference.md # Git 快速参考
│ │
│ ├── gitea/ # Gitea 平台集成
│ │ ├── SKILL.md # Gitea 完整指南
│ │ ├── setup-guide.md # 初始化和配置指南
│ │ ├── repository-operations.md # 仓库操作指南
│ │ ├── runner-management.md # Runner 管理指南
│ │ ├── api-reference.md # Gitea API 参考
│ │ ├── troubleshooting.md # 常见问题和解决方案
│ │ ├── workflow-generator.md # Workflow 自动生成工具
│ │ └── workflow-templates/ # CI/CD Workflow 模板库
│ │ ├── android-app.md # Android App 构建 Workflow
│ │ ├── go-backend.md # Go 后端服务 Workflow
│ │ ├── nodejs-frontend.md # Node.js 前端 Workflow
│ │ └── wechat-miniprogram.md # 微信小程序 Workflow
│ │
│ ├── android-developer/ # Android 开发指南
│ │ └── SKILL.md # Android 项目开发规范
│ │
│ ├── ios-developer/ # iOS 开发指南
│ │ └── SKILL.md # iOS 项目开发规范
│ │
│ ├── go-developer/ # Go 后端开发指南
│ │ └── SKILL.md # Go 项目开发规范
│ │
│ ├── electron-developer/ # Electron 桌面应用指南
│ │ └── SKILL.md # Electron 项目开发规范
│ │
│ └── mqtts-developer/ # MQTT over TLS/SSL 开发指南
│ ├── SKILL.md # MQTT 完整指南
│ ├── README.md # MQTT 项目说明
│ ├── setup-mqtts-acme.md # ACME 证书配置
│ ├── mqtts-client-config.md # 客户端配置
│ ├── mqtts-quick-reference.md # 快速参考
│ └── USAGE_EXAMPLES.md # 使用示例
│
├── plugin/ # 插件扩展系统
│ └── notification.ts # 通知插件（邮件、Slack、钉钉等）
│
├── README.md # 项目说明文档（当前文件）
├── AGENTS.md # 全局开发规范和指南
├── opencode.json # 项目配置文件
├── package.json # Node.js 依赖配置
└── .gitignore # Git 忽略文件配置
```
## 🚀 快速开始
### 目录说明
| 目录 | 用途 | 说明 |
|------|------|------|
| `command/` | CLI 命令 | 15 个内置命令，支持 Git、Gitea 等操作 |
| `skill/` | 开发指南 | 7 个开发领域的完整工作流程和最佳实践 |
| `skill/git/` | Git 工作流 | 提交规范、版本管理、Tag 规范等 |
| `skill/gitea/` | Gitea 集成 | 仓库、Runner、API、CI/CD Workflow 管理 |
| `skill/gitea/workflow-templates/` | 工作流模板 | 4 套预定义的 CI/CD Workflow 模板 |
| `skill/android-developer/` | Android 开发 | Kotlin、Jetpack Compose、MVVM 架构规范 |
| `skill/ios-developer/` | iOS 开发 | Swift、SwiftUI、iOS 26+ 最佳实践 |
| `skill/go-developer/` | Go 开发 | 后端开发规范、测试标准、质量工具 |
| `skill/electron-developer/` | Electron 开发 | TypeScript、Lit Web Components、跨平台实践 |
| `skill/mqtts-developer/` | MQTT 开发 | MQTT over TLS/SSL 协议、安全通信 |
| `plugin/` | 插件系统 | 扩展功能，支持自定义开发 |
### 前置条件
- **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 时，遵循项目的规范和最佳实践，可以显著提高开发效率和代码质量！