diff --git a/README.md b/README.md index dcb3770..ef6bcb3 100644 --- a/README.md +++ b/README.md @@ -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 / [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 - -# 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` - 构建系统 - -### 提交消息格式 - -``` -(): - - -