docs: 添加 README 文档，介绍 OpenCode 使用指南和快速开始
This commit is contained in:
396
README.md
Normal file
396
README.md
Normal file
@@ -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 <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 时，遵循项目的规范和最佳实践，可以显著提高开发效率和代码质量！
|
||||
Reference in New Issue
Block a user