# 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 时，遵循项目的规范和最佳实践，可以显著提高开发效率和代码质量！