From 1af6c39d258693c2b8399ef80f032717d0a24ea1 Mon Sep 17 00:00:00 2001 From: voson Date: Tue, 13 Jan 2026 10:29:10 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20README=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E4=BB=8B=E7=BB=8D=20OpenCode=20=E4=BD=BF?= =?UTF-8?q?=E7=94=A8=E6=8C=87=E5=8D=97=E5=92=8C=E5=BF=AB=E9=80=9F=E5=BC=80?= =?UTF-8?q?=E5=A7=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 396 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 396 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..dcb3770 --- /dev/null +++ b/README.md @@ -0,0 +1,396 @@ +# 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 / [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` - 构建系统 + +### 提交消息格式 + +``` +(): + + +