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 环境支持（可选）

安装

# 克隆或下载 OpenCode 项目
cd ~/.config/opencode

# 验证安装
opencode --version

📚 核心组件使用指南

1. Commands（命令系统）

命令是 OpenCode 最直接的使用方式，使用 / 前缀调用。

Git 命令

/git-status - 查看仓库状态

/git-status
# 输出：当前分支、暂存区文件、未暂存修改、未跟踪文件

/git-add - 智能暂存文件（自动过滤敏感文件）

/git-add
# 选项：
# - y/yes        仅暂存已修改文件
# - all/u        暂存所有安全文件（推荐）
# - force        强制暂存所有文件（包括敏感文件，谨慎）
# - no/cancel    取消操作

/git-commit - 自动生成提交信息并提交

/git-commit
# 功能：
# - 自动分析文件变更
# - 按 Conventional Commits 生成提交信息
# - 自动更新版本号（如需要）
# - 创建版本标签

/git-push - 提交、创建标签、推送到远程（一键完成）

/git-push
# 执行流程：
# 1. 分析暂存的变更
# 2. 生成提交信息
# 3. 创建版本标签（如需要）
# 4. 推送提交到远程
# 5. 推送标签到远程

/git-pull - 拉取远程最新变更

/git-pull
# 功能：
# - 获取远程更新
# - 自动合并变更
# - 处理合并冲突（需要时）

/git-push-tags - 推送所有标签到远程

/git-push-tags
# 用于推送忘记推送的标签或批量推送多个标签

Gitea 集成命令

/gitea-config - 查看当前 Gitea 配置

/gitea-config
# 显示：Gitea URL、默认组织、Token 状态、Runner 信息

/gitea-create-repo - 在 Gitea 创建新仓库

/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

/gitea-create-runner [runner-name]
# 功能：
# - 自动安装 act_runner（如果未安装）
# - 自动检测系统环境和架构
# - 生成合适的 labels
# - 注册并启动 runner

/gitea-list-runners - 列出所有已配置的 Runners

/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 操作和最佳实践

快速查看：

# 查看 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 - 项目级配置

{
  "dependencies": {
    "@opencode-ai/plugin": "1.1.15"
  }
}

AGENTS.md - 全局开发规范

语言偏好（中文）
代码风格
Git 提交规范
任务管理指南

Gitea 配置

首次使用 Gitea 相关命令时需要配置：

/gitea-reset
# 按提示输入：
# - Gitea 服务器 URL
# - API Token
# - 默认组织（可选）

配置存储在：~/.config/gitea/config.env

💡 工作流程示例

示例 1：完整的开发流程

# 1. 查看当前状态
/git-status

# 2. 智能暂存文件（自动过滤敏感文件）
/git-add
# 选择 "all" 暂存所有安全文件

# 3. 推送到远程（包括提交、标签、推送）
/git-push
# 一键完成：生成提交信息 → 创建版本标签 → 推送到远程

示例 2：创建 Gitea 仓库并配置 Runner

# 1. 初始化 Gitea 配置
/gitea-reset

# 2. 创建新仓库
/gitea-create-repo ai/my-project

# 3. 创建 Actions Runner
/gitea-create-runner

# 4. 验证配置
/gitea-config

示例 3：处理合并冲突

# 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 规范。

提交类型

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 中：

# 列出所有可用命令
ctrl+p

# 查看特定命令帮助
/command-name --help

# 获取反馈和问题报告
# https://github.com/anomalyco/opencode

📝 相关文档

📄 许可证

OpenCode 项目遵循相关许可证。详见项目根目录的 LICENSE 文件。

提示： 使用 OpenCode 时，遵循项目的规范和最佳实践，可以显著提高开发效率和代码质量！

README.md Unescape Escape

OpenCode

🌟 核心特性

📋 目录结构