Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 43e138b19e | |||
| 75462f3412 | |||
| 5d9efea7ab |
21
README.md
21
README.md
@@ -1,30 +1,14 @@
|
|||||||
# OpenCode
|
# OpenCode
|
||||||
|
|
||||||
|
|
||||||
## 📊 项目统计
|
|
||||||
|
|
||||||
- **15 个 CLI 命令** - 涵盖 Git 和 Gitea 操作
|
|
||||||
- **7 个开发领域技能库** - Android、iOS、Go、Electron、MQTT 等
|
|
||||||
- **4 套 CI/CD 工作流模板** - 适配多种项目类型
|
|
||||||
|
|
||||||
## 🌟 核心特性
|
|
||||||
|
|
||||||
- **智能命令系统** - 自动生成提交信息、管理版本标签、安全地暂存文件
|
|
||||||
- **可复用技能** - 预定义的开发工作流，如 Git 工作流、Android 开发等
|
|
||||||
- **安全优先** - 自动过滤敏感文件，防止意外泄露凭证
|
|
||||||
- **中文友好** - 完整的中文支持和交互提示
|
|
||||||
|
|
||||||
## 目录
|
## 目录
|
||||||
|
|
||||||
```
|
```
|
||||||
opencode/
|
opencode/
|
||||||
├── command/ # CLI 命令定义
|
├── command/ # CLI 命令定义
|
||||||
│ ├── git-add.md # 智能暂存文件（自动过滤敏感文件）
|
|
||||||
│ ├── git-commit.md # 自动生成提交信息并提交
|
│ ├── git-commit.md # 自动生成提交信息并提交
|
||||||
│ ├── git-pull.md # 拉取远程最新变更
|
│ ├── git-pull.md # 拉取远程最新变更
|
||||||
│ ├── git-push.md # 提交+创建标签+推送（一键完成）
|
│ ├── git-push.md # 提交+创建标签+推送（一键完成）
|
||||||
│ ├── git-push-tags.md # 推送所有标签到远程
|
│ ├── git-push-tags.md # 推送所有标签到远程
|
||||||
│ ├── git-status.md # 查看仓库状态
|
|
||||||
│ ├── gitea-config.md # 查看 Gitea 配置和 Runner 状态
|
│ ├── gitea-config.md # 查看 Gitea 配置和 Runner 状态
|
||||||
│ ├── gitea-create-repo.md # 在 Gitea 创建新仓库
|
│ ├── gitea-create-repo.md # 在 Gitea 创建新仓库
|
||||||
│ ├── gitea-create-runner.md # 创建并启动 Gitea Actions Runner
|
│ ├── gitea-create-runner.md # 创建并启动 Gitea Actions Runner
|
||||||
@@ -73,13 +57,8 @@ opencode/
|
|||||||
│ ├── mqtts-quick-reference.md # 快速参考
|
│ ├── mqtts-quick-reference.md # 快速参考
|
||||||
│ └── USAGE_EXAMPLES.md # 使用示例
|
│ └── USAGE_EXAMPLES.md # 使用示例
|
||||||
│
|
│
|
||||||
├── plugin/ # 插件扩展系统
|
|
||||||
│ └── notification.ts # 通知插件（邮件、Slack、钉钉等）
|
|
||||||
│
|
|
||||||
├── README.md # 项目说明文档（当前文件）
|
├── README.md # 项目说明文档（当前文件）
|
||||||
├── AGENTS.md # 全局开发规范和指南
|
├── AGENTS.md # 全局开发规范和指南
|
||||||
├── opencode.json # 项目配置文件
|
├── opencode.json # 项目配置文件
|
||||||
├── package.json # Node.js 依赖配置
|
|
||||||
└── .gitignore # Git 忽略文件配置
|
└── .gitignore # Git 忽略文件配置
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
@@ -1,71 +0,0 @@
|
|||||||
---
|
|
||||||
description: Stage changes with automatic filtering of sensitive files
|
|
||||||
---
|
|
||||||
|
|
||||||
Intelligently stage changes while automatically filtering security-sensitive files.
|
|
||||||
|
|
||||||
Please perform the following:
|
|
||||||
|
|
||||||
1. **Detect all unstaged changes:**
|
|
||||||
- Modified files (M)
|
|
||||||
- Deleted files (D)
|
|
||||||
- Untracked files (??) - **重要：第一次就显示并提供选项**
|
|
||||||
|
|
||||||
2. **Filter sensitive files** - Automatically exclude:
|
|
||||||
- `.env*` - Environment files
|
|
||||||
- `*.key`, `*.pem`, `*.p8` - Private keys
|
|
||||||
- `.aws/*`, `.gcloud/*`, `.ssh/*` - Cloud/SSH credentials
|
|
||||||
- `credentials.json`, `secrets.json` - Credential files
|
|
||||||
- `node_modules/`, `vendor/`, `.venv/` - Dependencies
|
|
||||||
- `dist/`, `build/`, `.next/` - Build artifacts
|
|
||||||
- `.DS_Store`, `Thumbs.db` - System files
|
|
||||||
|
|
||||||
3. **Categorize files:**
|
|
||||||
- **已跟踪的修改/删除** (tracked modified/deleted)
|
|
||||||
- **未跟踪的安全文件** (untracked safe files)
|
|
||||||
- **敏感文件** (sensitive files - filtered)
|
|
||||||
|
|
||||||
4. **Display preview in Chinese:**
|
|
||||||
```
|
|
||||||
=== 将要暂存的文件 (N) ===
|
|
||||||
M [tracked modified files]
|
|
||||||
D [tracked deleted files]
|
|
||||||
|
|
||||||
=== 未跟踪的文件 (N) ===
|
|
||||||
?? [untracked safe files]
|
|
||||||
|
|
||||||
=== 敏感文件已过滤 (N) ===
|
|
||||||
⚠ [sensitive files with reasons]
|
|
||||||
|
|
||||||
=== 操作选项 ===
|
|
||||||
- 输入 "y" 或 "yes" 暂存已修改/已删除的文件（不包括未跟踪文件）
|
|
||||||
- 输入 "all" 或 "u" 暂存所有安全文件（包括未跟踪文件）✓ 推荐
|
|
||||||
- 输入 "force" 强制暂存所有文件（包括敏感文件）⚠️ 谨慎使用
|
|
||||||
- 输入 "no" 或 "cancel" 取消操作
|
|
||||||
- 输入文件路径 暂存特定文件
|
|
||||||
```
|
|
||||||
|
|
||||||
5. **Wait for user confirmation**
|
|
||||||
|
|
||||||
6. **Execute staging based on user choice:**
|
|
||||||
- `y/yes`: Stage tracked modified/deleted only
|
|
||||||
- `all/u`: Stage all safe files (including untracked)
|
|
||||||
- `force`: Show warning, require "confirm" input, then stage everything
|
|
||||||
- `no/cancel`: Abort
|
|
||||||
- File path: Stage specific file(s)
|
|
||||||
|
|
||||||
7. **Display result in Chinese:**
|
|
||||||
```
|
|
||||||
✓ 暂存成功
|
|
||||||
|
|
||||||
已暂存 N 个文件：
|
|
||||||
[列出已暂存的文件]
|
|
||||||
|
|
||||||
敏感文件已过滤并排除，保护了你的凭证信息。
|
|
||||||
|
|
||||||
下一步：
|
|
||||||
- 运行 /git-commit 生成提交信息并提交
|
|
||||||
- 运行 /git-status 查看暂存区状态
|
|
||||||
```
|
|
||||||
|
|
||||||
**重要：第一次运行就显示所有选项，包括未跟踪文件的处理方式，不需要用户多次运行命令。**
|
|
||||||
@@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
description: Commit staged files with auto-generated message and create version tag
|
description: 提交暂存文件，自动生成提交信息并创建版本标签
|
||||||
---
|
---
|
||||||
|
|
||||||
Auto-generate a commit message for staged files, commit to the local repository, and create a version tag following semantic versioning.
|
Auto-generate a commit message for staged files, commit to the local repository, and create a version tag following semantic versioning.
|
||||||
|
|||||||
@@ -1,23 +0,0 @@
|
|||||||
---
|
|
||||||
description: Pull latest changes from remote repository
|
|
||||||
---
|
|
||||||
|
|
||||||
Pull the latest changes from the remote repository for the current branch.
|
|
||||||
|
|
||||||
Please perform the following tasks:
|
|
||||||
|
|
||||||
1. **Run `git pull`** to fetch and merge remote changes
|
|
||||||
2. **Handle merge conflicts if they occur:**
|
|
||||||
- Check conflict files with `git status`
|
|
||||||
- Guide me through conflict resolution
|
|
||||||
- Help stage resolved files with `git add <file>`
|
|
||||||
- Complete the merge with `git commit`
|
|
||||||
3. **Show the result** with branch status and changes summary
|
|
||||||
|
|
||||||
If there are any errors or conflicts, explain them clearly in Chinese and provide step-by-step guidance for resolution.
|
|
||||||
|
|
||||||
Present the final result showing:
|
|
||||||
- Branch name
|
|
||||||
- Number of commits pulled
|
|
||||||
- Files changed
|
|
||||||
- Any conflicts that need attention
|
|
||||||
@@ -1,55 +0,0 @@
|
|||||||
---
|
|
||||||
description: Push all local tags to remote repository
|
|
||||||
---
|
|
||||||
|
|
||||||
Push all local tags to the remote repository.
|
|
||||||
|
|
||||||
Please perform the following:
|
|
||||||
|
|
||||||
1. **List local tags:**
|
|
||||||
```bash
|
|
||||||
git tag --list | sort -V
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Check remote tags:**
|
|
||||||
```bash
|
|
||||||
git ls-remote --tags origin
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Identify unpushed tags** - Compare local and remote to find tags that need to be pushed
|
|
||||||
|
|
||||||
4. **Display summary in Chinese:**
|
|
||||||
```
|
|
||||||
本地标签总数：N 个
|
|
||||||
远程标签总数：M 个
|
|
||||||
待推送标签：K 个
|
|
||||||
- [list of unpushed tags]
|
|
||||||
|
|
||||||
确认推送所有标签到 origin？
|
|
||||||
```
|
|
||||||
|
|
||||||
5. **Wait for user confirmation** (or proceed if no confirmation needed)
|
|
||||||
|
|
||||||
6. **Push all tags:**
|
|
||||||
```bash
|
|
||||||
git push --tags
|
|
||||||
```
|
|
||||||
|
|
||||||
7. **Verify and display result in Chinese:**
|
|
||||||
```
|
|
||||||
✓ 已成功推送所有标签到 origin
|
|
||||||
|
|
||||||
最近 5 个远程标签：
|
|
||||||
- [list of recent tags]
|
|
||||||
```
|
|
||||||
|
|
||||||
**Use cases:**
|
|
||||||
- After creating multiple local tags
|
|
||||||
- Sync tags with remote repository
|
|
||||||
- Before triggering CI/CD release workflows
|
|
||||||
- Share version tags with team
|
|
||||||
|
|
||||||
**Notes:**
|
|
||||||
- Pushes ALL local tags, not just one
|
|
||||||
- To push a specific tag: `git push origin <tag-name>`
|
|
||||||
- Safe operation: won't overwrite existing tags (no force push)
|
|
||||||
@@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
description: Commit staged files, create version tag, and push to remote repository
|
description: 提交暂存文件，创建版本标签并推送到远程仓库
|
||||||
---
|
---
|
||||||
|
|
||||||
Complete workflow: auto-generate commit message, create version tag, commit, and push everything to remote repository.
|
Complete workflow: auto-generate commit message, create version tag, commit, and push everything to remote repository.
|
||||||
|
|||||||
@@ -1,29 +0,0 @@
|
|||||||
---
|
|
||||||
description: Check git working directory status and file changes
|
|
||||||
---
|
|
||||||
|
|
||||||
Check the current git repository status and display file changes in a clear, organized format.
|
|
||||||
|
|
||||||
Please perform the following tasks:
|
|
||||||
|
|
||||||
1. **Run `git status`** to show the current state of the working tree
|
|
||||||
2. **Display current branch** using `git branch --show-current`
|
|
||||||
3. **List unstaged changes** with `git diff --name-only`
|
|
||||||
4. **List staged changes** with `git diff --cached --name-only`
|
|
||||||
|
|
||||||
Present the information in Chinese with the following structure:
|
|
||||||
|
|
||||||
```
|
|
||||||
当前分支: [branch_name]
|
|
||||||
|
|
||||||
暂存区文件 ([count]):
|
|
||||||
[列出已暂存的文件]
|
|
||||||
|
|
||||||
未暂存的修改 ([count]):
|
|
||||||
[列出未暂存的修改文件]
|
|
||||||
|
|
||||||
未跟踪的文件 ([count]):
|
|
||||||
[列出未跟踪的文件]
|
|
||||||
```
|
|
||||||
|
|
||||||
Use clear formatting and emoji indicators (✓, ⚠️, etc.) to make the output easy to read.
|
|
||||||
@@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
description: View current Gitea configuration and runner status
|
description: 查看当前 Gitea 配置和 Runner 状态
|
||||||
---
|
---
|
||||||
|
|
||||||
Display the current Gitea configuration and runner status.
|
Display the current Gitea configuration and runner status.
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
description: Create a new Git repository on Gitea
|
description: 在 Gitea 上创建新的 Git 仓库
|
||||||
---
|
---
|
||||||
|
|
||||||
Create a new Git repository on Gitea via API.
|
Create a new Git repository on Gitea via API.
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
description: Create and start a Gitea Actions runner (default host mode)
|
description: 创建并启动 Gitea Actions Runner（默认使用 host 模式）
|
||||||
agent: general
|
agent: general
|
||||||
subtask: true
|
subtask: true
|
||||||
---
|
---
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
description: Delete a Gitea runner configuration (interactive)
|
description: 删除 Gitea Runner 配置（交互式）
|
||||||
agent: general
|
agent: general
|
||||||
subtask: true
|
subtask: true
|
||||||
---
|
---
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
description: List all global runners on Gitea server
|
description: 列出 Gitea 服务器上的所有全局 Runner
|
||||||
---
|
---
|
||||||
|
|
||||||
List all global runners registered on the Gitea server.
|
List all global runners registered on the Gitea server.
|
||||||
|
|||||||
@@ -1,132 +0,0 @@
|
|||||||
---
|
|
||||||
description: Reset Gitea configuration with interactive setup wizard
|
|
||||||
agent: general
|
|
||||||
subtask: true
|
|
||||||
---
|
|
||||||
|
|
||||||
Launch an interactive configuration wizard to set up or reset Gitea configuration.
|
|
||||||
|
|
||||||
## 工作目录
|
|
||||||
|
|
||||||
**macOS / Linux:**
|
|
||||||
```
|
|
||||||
~/.config/gitea/
|
|
||||||
```
|
|
||||||
|
|
||||||
**Windows:**
|
|
||||||
```
|
|
||||||
%USERPROFILE%\.config\gitea\
|
|
||||||
```
|
|
||||||
|
|
||||||
配置文件和 Runner 目录都将存储在此位置。
|
|
||||||
|
|
||||||
Please perform the following:
|
|
||||||
|
|
||||||
1. **Create configuration directory:**
|
|
||||||
|
|
||||||
**macOS / Linux:**
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.config/gitea/runners
|
|
||||||
```
|
|
||||||
|
|
||||||
**Windows PowerShell:**
|
|
||||||
```powershell
|
|
||||||
New-Item -Path "$env:USERPROFILE\.config\gitea\runners" -ItemType Directory -Force
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Interactive input - Gitea URL:**
|
|
||||||
- Prompt: "请输入 Gitea 实例地址 (例如: https://git.digitevents.com):"
|
|
||||||
- Validate: Must start with http:// or https://
|
|
||||||
- Remove trailing slash
|
|
||||||
|
|
||||||
3. **Interactive input - Personal Access Token:**
|
|
||||||
- Prompt: "请输入 Personal Access Token:"
|
|
||||||
- Before input, show help:
|
|
||||||
```
|
|
||||||
提示：获取 Personal Access Token 的步骤：
|
|
||||||
1. 登录 Gitea
|
|
||||||
2. 右上角头像 → 设置 → 应用 → 访问令牌
|
|
||||||
3. 点击 "生成新令牌"
|
|
||||||
4. 设置令牌名称（如 opencode-cli）
|
|
||||||
5. 选择权限：repo, admin:org, write:runner（推荐）
|
|
||||||
6. 点击 "生成令牌"
|
|
||||||
7. 复制生成的 Token
|
|
||||||
```
|
|
||||||
- Validate: Not empty
|
|
||||||
- Use `read -sp` for secure input (password style)
|
|
||||||
|
|
||||||
4. **Test connection:**
|
|
||||||
- API: `GET ${GITEA_URL}/api/v1/user`
|
|
||||||
- If fails: Show error and possible reasons
|
|
||||||
- If success: Show username
|
|
||||||
|
|
||||||
5. **Validate token permissions:**
|
|
||||||
- Check `repo`: `GET /api/v1/user/repos` (required)
|
|
||||||
- Check `admin:org`: `GET /api/v1/user/orgs` (optional, for org runners)
|
|
||||||
- Check `write:runner`: Try to get registration token (optional, for runners)
|
|
||||||
- Warn if missing required permissions
|
|
||||||
|
|
||||||
6. **Input default organization (optional):**
|
|
||||||
- Prompt: "请输入默认组织名称 (回车跳过):"
|
|
||||||
- If provided, validate it exists: `GET /api/v1/orgs/${org_name}`
|
|
||||||
|
|
||||||
7. **Save configuration:**
|
|
||||||
|
|
||||||
**macOS / Linux** - Save to `~/.config/gitea/config.env`:
|
|
||||||
```bash
|
|
||||||
GITEA_URL=...
|
|
||||||
GITEA_TOKEN=...
|
|
||||||
GITEA_DEFAULT_ORG=... (if set)
|
|
||||||
GITEA_RUNNER_CAPACITY=2
|
|
||||||
GITEA_RUNNER_TIMEOUT=3h
|
|
||||||
```
|
|
||||||
- Set permissions: `chmod 600 ~/.config/gitea/config.env`
|
|
||||||
- Create `.gitignore` to exclude sensitive files
|
|
||||||
|
|
||||||
**Windows** - Save to `%USERPROFILE%\.config\gitea\config.env`:
|
|
||||||
```bash
|
|
||||||
GITEA_URL=...
|
|
||||||
GITEA_TOKEN=...
|
|
||||||
GITEA_DEFAULT_ORG=... (if set)
|
|
||||||
GITEA_RUNNER_CAPACITY=2
|
|
||||||
GITEA_RUNNER_TIMEOUT=3h
|
|
||||||
```
|
|
||||||
- Set file permissions to restrict access (see setup-guide.md for PowerShell script)
|
|
||||||
- Create `.gitignore` to exclude sensitive files
|
|
||||||
|
|
||||||
8. **Display completion summary in Chinese:**
|
|
||||||
|
|
||||||
**macOS / Linux:**
|
|
||||||
```
|
|
||||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
||||||
配置完成
|
|
||||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
||||||
|
|
||||||
配置文件: ~/.config/gitea/config.env
|
|
||||||
Runner 目录: ~/.config/gitea/runners
|
|
||||||
|
|
||||||
下一步：
|
|
||||||
- 查看配置: /gitea-config
|
|
||||||
- 创建 Runner: 告诉 AI '创建一个 runner'
|
|
||||||
- 创建仓库: /create-gitea-repo <repo-name>
|
|
||||||
```
|
|
||||||
|
|
||||||
**Windows:**
|
|
||||||
```
|
|
||||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
||||||
配置完成
|
|
||||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
||||||
|
|
||||||
配置文件: %USERPROFILE%\.config\gitea\config.env
|
|
||||||
Runner 目录: %USERPROFILE%\.config\gitea\runners
|
|
||||||
|
|
||||||
下一步：
|
|
||||||
- 查看配置: /gitea-config
|
|
||||||
- 创建 Runner: 告诉 AI '创建一个 runner'
|
|
||||||
- 创建仓库: /create-gitea-repo <repo-name>
|
|
||||||
```
|
|
||||||
|
|
||||||
**Security notes:**
|
|
||||||
- Config file permissions: 600 (owner read/write only)
|
|
||||||
- Token is never displayed after initial input
|
|
||||||
- Sensitive files excluded in .gitignore
|
|
||||||
@@ -1,82 +0,0 @@
|
|||||||
---
|
|
||||||
description: Switch default Gitea organization
|
|
||||||
---
|
|
||||||
|
|
||||||
Switch the default Gitea organization in configuration.
|
|
||||||
|
|
||||||
## 工作目录
|
|
||||||
|
|
||||||
**macOS / Linux:**
|
|
||||||
```
|
|
||||||
~/.config/gitea/
|
|
||||||
```
|
|
||||||
|
|
||||||
**Windows:**
|
|
||||||
```
|
|
||||||
%USERPROFILE%\.config\gitea\
|
|
||||||
```
|
|
||||||
|
|
||||||
**User input format:** `$ARGUMENTS` = organization name
|
|
||||||
|
|
||||||
**Example usage:**
|
|
||||||
```
|
|
||||||
/gitea-switch-org ai
|
|
||||||
/gitea-switch-org my-team
|
|
||||||
```
|
|
||||||
|
|
||||||
Please perform the following:
|
|
||||||
|
|
||||||
1. **Check configuration exists:**
|
|
||||||
- Config file:
|
|
||||||
- macOS/Linux: `~/.config/gitea/config.env`
|
|
||||||
- Windows: `%USERPROFILE%\.config\gitea\config.env`
|
|
||||||
- If not exists: prompt user to run `/gitea-reset`
|
|
||||||
|
|
||||||
2. **Load configuration:**
|
|
||||||
|
|
||||||
**macOS / Linux:**
|
|
||||||
```bash
|
|
||||||
source ~/.config/gitea/config.env
|
|
||||||
```
|
|
||||||
|
|
||||||
**Windows PowerShell:**
|
|
||||||
```powershell
|
|
||||||
Get-Content "$env:USERPROFILE\.config\gitea\config.env" | ForEach-Object {
|
|
||||||
if ($_ -match '^([^=]+)=(.*)$') {
|
|
||||||
[Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process')
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Parse user input:**
|
|
||||||
- Organization name from `$ARGUMENTS`
|
|
||||||
- If empty: show usage and examples
|
|
||||||
|
|
||||||
4. **Validate organization exists:**
|
|
||||||
- API: `GET ${GITEA_URL}/api/v1/orgs/${org_name}`
|
|
||||||
- Header: `Authorization: token ${GITEA_TOKEN}`
|
|
||||||
- If 404: Show error and list available organizations:
|
|
||||||
```bash
|
|
||||||
curl -s -H "Authorization: token $GITEA_TOKEN" \
|
|
||||||
"${GITEA_URL}/api/v1/user/orgs" | jq -r '.[].username'
|
|
||||||
```
|
|
||||||
|
|
||||||
5. **Update configuration file:**
|
|
||||||
- If `GITEA_DEFAULT_ORG` exists: update the line
|
|
||||||
- If not exists: add after `GITEA_TOKEN`
|
|
||||||
- Handle macOS (sed -i '') and Linux (sed -i) differences
|
|
||||||
|
|
||||||
6. **Display result in Chinese:**
|
|
||||||
```
|
|
||||||
✓ 默认组织已切换到: [org_name]
|
|
||||||
|
|
||||||
现在可以：
|
|
||||||
- 创建仓库: /create-gitea-repo my-project
|
|
||||||
（将创建到 [org_name]/my-project）
|
|
||||||
- 查看配置: /gitea-config
|
|
||||||
```
|
|
||||||
|
|
||||||
**Notes:**
|
|
||||||
- Switching organization doesn't affect existing repositories or runners
|
|
||||||
- Only affects default owner for future repository creation
|
|
||||||
- Can switch anytime
|
|
||||||
@@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
description: Review code or documentation and provide suggestions
|
description: 审查代码或文档并提供建议
|
||||||
agent: plan
|
agent: plan
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
84
command/summarize-conversation.md
Normal file
84
command/summarize-conversation.md
Normal file
@@ -0,0 +1,84 @@
|
|||||||
|
---
|
||||||
|
description: 归纳总结当前对话中有价值的内容，生成 Markdown 文件以便后续参考
|
||||||
|
agent: general
|
||||||
|
---
|
||||||
|
|
||||||
|
# 对话内容总结
|
||||||
|
|
||||||
|
你的任务是归纳总结当前对话中有价值的内容，生成一个结构化的 Markdown 文件，方便后续与 AI 对话时快速回顾，避免重复查询。
|
||||||
|
|
||||||
|
## 总结内容
|
||||||
|
|
||||||
|
请从对话历史中提取以下信息：
|
||||||
|
|
||||||
|
1. **对话主题** - 用户的主要需求和目标
|
||||||
|
2. **关键决策** - 用户做出的重要选择、确定的技术方案
|
||||||
|
3. **代码更改** - 创建、修改或删除的代码文件及核心逻辑
|
||||||
|
4. **配置更新** - 环境变量、配置文件、依赖项变更
|
||||||
|
5. **待办事项** - 用户明确提到的未来任务或计划
|
||||||
|
6. **下一步行动** - 建议的后续步骤
|
||||||
|
7. **重要注意事项** - 需要特别记住的细节、限制条件
|
||||||
|
8. **相关文件路径** - 涉及的重要文件位置（格式：`文件路径:行号`）
|
||||||
|
|
||||||
|
## 生成文件
|
||||||
|
|
||||||
|
1. **默认文件名**：`conversation-summary.md`
|
||||||
|
2. **文件位置**：当前工作目录
|
||||||
|
3. **文件格式**：使用 Markdown 语法，包含清晰的标题和列表
|
||||||
|
4. **时间戳**：在文件开头添加生成时间（格式：YYYY-MM-DD HH:MM:SS）
|
||||||
|
5. **对话上下文**：简要描述对话的背景和目的
|
||||||
|
|
||||||
|
## 执行步骤
|
||||||
|
|
||||||
|
1. **分析对话** - 回顾完整的对话历史，识别有价值的信息点
|
||||||
|
2. **提取内容** - 按照上述分类整理信息，确保准确性和完整性
|
||||||
|
3. **生成总结** - 创建结构化的 Markdown 内容，使用中文描述
|
||||||
|
4. **保存文件** - 将总结写入 `conversation-summary.md` 文件
|
||||||
|
5. **验证内容** - 检查文件是否包含所有关键信息
|
||||||
|
6. **通知用户** - 告知用户文件已生成，并提供文件路径
|
||||||
|
|
||||||
|
## 注意事项
|
||||||
|
|
||||||
|
- 只总结**有价值**的内容，忽略闲聊和无关信息
|
||||||
|
- 保持总结简洁明了，便于快速查阅
|
||||||
|
- 涉及代码时，提供文件路径和关键行号引用
|
||||||
|
- 如果有未完成的任务，明确标注状态（待处理/进行中/已完成）
|
||||||
|
- 如果对话中涉及敏感信息（如密码、密钥），**不要**包含在总结中
|
||||||
|
|
||||||
|
## 输出示例
|
||||||
|
|
||||||
|
```
|
||||||
|
# 对话总结
|
||||||
|
|
||||||
|
**生成时间**: 2025-01-15 14:30:00
|
||||||
|
**对话主题**: 创建 OpenCode 命令用于总结对话内容
|
||||||
|
|
||||||
|
## 关键决策
|
||||||
|
- 命令名称: `summarize-conversation`
|
||||||
|
- 文件位置: 全局命令目录 (`~/.config/opencode/command/`)
|
||||||
|
- 代理类型: general
|
||||||
|
|
||||||
|
## 代码更改
|
||||||
|
- 创建命令文件: `command/summarize-conversation.md`
|
||||||
|
|
||||||
|
## 配置更新
|
||||||
|
- 无
|
||||||
|
|
||||||
|
## 待办事项
|
||||||
|
- 测试命令功能：运行 `/summarize-conversation`
|
||||||
|
- 考虑添加文件命名参数支持
|
||||||
|
|
||||||
|
## 下一步行动
|
||||||
|
1. 使用 `/summarize-conversation` 测试命令效果
|
||||||
|
2. 根据使用反馈优化总结模板
|
||||||
|
|
||||||
|
## 重要注意事项
|
||||||
|
- 总结文件保存在当前工作目录的 `conversation-summary.md`
|
||||||
|
- 每次运行会覆盖之前的总结文件
|
||||||
|
- 建议定期备份重要总结
|
||||||
|
|
||||||
|
## 相关文件
|
||||||
|
- `command/summarize-conversation.md`
|
||||||
|
```
|
||||||
|
|
||||||
|
**完成标准**：成功生成包含上述所有部分的 Markdown 文件，并通知用户文件位置。
|
||||||
@@ -1,5 +1,8 @@
|
|||||||
{
|
{
|
||||||
"$schema": "https://opencode.ai/config.json",
|
"$schema": "https://opencode.ai/config.json",
|
||||||
|
"mcp": {},
|
||||||
|
"permission": "allow",
|
||||||
|
"plugin": ["@mohak34/opencode-notifier@latest"],
|
||||||
"provider": {
|
"provider": {
|
||||||
"opencode": {
|
"opencode": {
|
||||||
"models": {
|
"models": {
|
||||||
@@ -10,19 +13,15 @@
|
|||||||
"budgetTokens": 16000
|
"budgetTokens": 16000
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
},
|
},
|
||||||
"claude-sonnet-4-5": {
|
"zhipuai-coding-plan": {
|
||||||
"options": {
|
"options": {
|
||||||
"thinking": {
|
"apiKey": "0f76aea86295476dbfa98724013b0fe8.o2EaJVqcl4Cf7WLP"
|
||||||
"type": "enabled",
|
|
||||||
"budgetTokens": 16000
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"mcp": {
|
"model": "deepseek/deepseek-resoner",
|
||||||
},
|
"small_model": "deepseek/deepseek-resoner"
|
||||||
"permission": "allow"
|
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,72 +0,0 @@
|
|||||||
import type { Plugin } from "@opencode-ai/plugin"
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 通知 Plugin
|
|
||||||
* 在会话完成或发生错误时发送系统通知
|
|
||||||
*/
|
|
||||||
export const NotificationPlugin: Plugin = async ({ project, client, $ }) => {
|
|
||||||
// 检测操作系统
|
|
||||||
const platform = process.platform
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 发送系统通知
|
|
||||||
* @param title 通知标题
|
|
||||||
* @param message 通知内容
|
|
||||||
* @param isError 是否为错误通知
|
|
||||||
*/
|
|
||||||
const sendNotification = async (title: string, message: string, isError: boolean = false) => {
|
|
||||||
try {
|
|
||||||
if (platform === "darwin") {
|
|
||||||
// macOS - 使用 osascript
|
|
||||||
const sound = isError ? ' sound name "Basso"' : ''
|
|
||||||
await $`osascript -e 'display notification "${message}" with title "${title}"${sound}'`
|
|
||||||
} else if (platform === "linux") {
|
|
||||||
// Linux - 使用 notify-send
|
|
||||||
const urgency = isError ? "-u critical" : ""
|
|
||||||
await $`notify-send "${title}" "${message}" ${urgency}`
|
|
||||||
} else if (platform === "win32") {
|
|
||||||
// Windows - 使用 PowerShell
|
|
||||||
const script = `Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('${message}', '${title}')`
|
|
||||||
await $`powershell -Command "& {${script}}"`
|
|
||||||
}
|
|
||||||
|
|
||||||
// 记录日志
|
|
||||||
await client.app.log({
|
|
||||||
service: "notification",
|
|
||||||
level: "info",
|
|
||||||
message: `已发送通知: ${title} - ${message}`,
|
|
||||||
})
|
|
||||||
} catch (error) {
|
|
||||||
// 如果通知发送失败，记录错误但不中断流程
|
|
||||||
await client.app.log({
|
|
||||||
service: "notification",
|
|
||||||
level: "error",
|
|
||||||
message: `发送通知失败: ${error}`,
|
|
||||||
})
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
event: async ({ event }) => {
|
|
||||||
const projectName = project?.name || "OpenCode"
|
|
||||||
|
|
||||||
// 会话完成时发送通知
|
|
||||||
if (event.type === "session.idle") {
|
|
||||||
await sendNotification(
|
|
||||||
projectName,
|
|
||||||
"会话已完成！",
|
|
||||||
false
|
|
||||||
)
|
|
||||||
}
|
|
||||||
|
|
||||||
// 会话错误时发送通知
|
|
||||||
if (event.type === "session.error") {
|
|
||||||
await sendNotification(
|
|
||||||
projectName,
|
|
||||||
"会话发生错误！",
|
|
||||||
true
|
|
||||||
)
|
|
||||||
}
|
|
||||||
},
|
|
||||||
}
|
|
||||||
}
|
|
||||||
442
skill/agent-browser/SKILL.md
Normal file
442
skill/agent-browser/SKILL.md
Normal file
@@ -0,0 +1,442 @@
|
|||||||
|
---
|
||||||
|
name: ab
|
||||||
|
description: 浏览器自动化工具，用于网页测试、表单填写、截图、数据提取等
|
||||||
|
---
|
||||||
|
|
||||||
|
# 浏览器自动化工具 agent-browser
|
||||||
|
|
||||||
|
ab是 agent-browser 的缩写，它是一个为 AI 代理设计的无头浏览器自动化 CLI 工具，基于 Rust 和 Playwright 构建。支持快速导航、元素交互、页面截图、数据提取等功能。
|
||||||
|
|
||||||
|
注意：必须使用 agent-browser 全称作为命令关键字。
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 安装检查
|
||||||
|
agent-browser 默认已安装。如果遇到 "command not found" 错误，请运行以下命令安装：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 全局安装
|
||||||
|
npm install -g agent-browser
|
||||||
|
|
||||||
|
# 下载 Chromium 浏览器
|
||||||
|
agent-browser install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 核心工作流程（4步法）
|
||||||
|
```bash
|
||||||
|
# 使用 agent-browser
|
||||||
|
1. agent-browser open <url>
|
||||||
|
2. agent-browser snapshot -i
|
||||||
|
3. agent-browser click @e1
|
||||||
|
4. agent-browser fill @e2 "文本"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 核心工作流程详解
|
||||||
|
|
||||||
|
### 1. 导航到页面
|
||||||
|
```bash
|
||||||
|
agent-browser open https://example.com
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 获取页面快照（推荐使用交互模式）
|
||||||
|
```bash
|
||||||
|
agent-browser snapshot -i # 仅显示交互元素（按钮、输入框、链接）
|
||||||
|
```
|
||||||
|
|
||||||
|
**输出示例：**
|
||||||
|
```
|
||||||
|
- link "Learn more" [ref=e1]
|
||||||
|
- textbox "Email" [ref=e2]
|
||||||
|
- button "Submit" [ref=e3]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 使用 Refs 进行交互
|
||||||
|
快照中的 `[ref=e1]`、`[ref=e2]` 等是元素的唯一引用标识，**推荐使用 refs 而非 CSS 选择器**：
|
||||||
|
- **确定性**：ref 指向快照中的确切元素
|
||||||
|
- **快速**：无需重新查询 DOM
|
||||||
|
- **AI 友好**：适合 LLM 处理
|
||||||
|
|
||||||
|
### 4. 页面变化后重新快照
|
||||||
|
页面发生重大变化（导航、表单提交等）后，需要重新获取快照：
|
||||||
|
```bash
|
||||||
|
agent-browser snapshot -i # 重新获取新的 refs
|
||||||
|
```
|
||||||
|
|
||||||
|
## 命令参考
|
||||||
|
|
||||||
|
### 导航命令
|
||||||
|
```bash
|
||||||
|
agent-browser open <url> # 导航到 URL（或：ab open <url>）
|
||||||
|
agent-browser back # 后退（或：ab back）
|
||||||
|
agent-browser forward # 前进（或：ab forward）
|
||||||
|
agent-browser reload # 重新加载页面（或：ab reload）
|
||||||
|
agent-browser close # 关闭浏览器（或：ab close）
|
||||||
|
```
|
||||||
|
|
||||||
|
### 快照命令（页面分析）
|
||||||
|
```bash
|
||||||
|
agent-browser snapshot # 完整可访问性树（或：ab snapshot）
|
||||||
|
agent-browser snapshot -i # 仅交互元素（推荐）（或：ab snapshot -i）
|
||||||
|
agent-browser snapshot -c # 紧凑输出（移除空结构元素）（或：ab snapshot -c）
|
||||||
|
agent-browser snapshot -d 3 # 限制深度为 3 级（或：ab snapshot -d 3）
|
||||||
|
agent-browser snapshot -s "#main" # 限定到 CSS 选择器范围（或：ab snapshot -s "#main"）
|
||||||
|
```
|
||||||
|
|
||||||
|
### 交互命令（使用 @refs）
|
||||||
|
```bash
|
||||||
|
# 基础交互
|
||||||
|
agent-browser click @e1 # 单击
|
||||||
|
agent-browser dblclick @e1 # 双击
|
||||||
|
agent-browser fill @e2 "文本" # 清空并填写
|
||||||
|
agent-browser type @e2 "文本" # 不清空直接输入
|
||||||
|
agent-browser press Enter # 按键（支持组合键 Control+a）
|
||||||
|
agent-browser hover @e1 # 悬停
|
||||||
|
agent-browser focus @e1 # 聚焦
|
||||||
|
|
||||||
|
# 表单操作
|
||||||
|
agent-browser check @e1 # 勾选复选框
|
||||||
|
agent-browser uncheck @e1 # 取消勾选
|
||||||
|
agent-browser select @e1 "值" # 选择下拉选项
|
||||||
|
agent-browser upload @e1 file1.jpg # 上传文件
|
||||||
|
|
||||||
|
# 滚动
|
||||||
|
agent-browser scroll down 500 # 向下滚动 500px
|
||||||
|
agent-browser scrollintoview @e1 # 滚动元素到可见区域
|
||||||
|
```
|
||||||
|
|
||||||
|
### 获取信息
|
||||||
|
```bash
|
||||||
|
agent-browser get text @e1 # 获取元素文本
|
||||||
|
agent-browser get value @e1 # 获取输入框值
|
||||||
|
agent-browser get html @e1 # 获取 innerHTML
|
||||||
|
agent-browser get attr @e1 id # 获取属性
|
||||||
|
agent-browser get title # 获取页面标题
|
||||||
|
agent-browser get url # 获取当前 URL
|
||||||
|
agent-browser get count ".item" # 计数匹配元素
|
||||||
|
agent-browser get box @e1 # 获取边界框
|
||||||
|
```
|
||||||
|
|
||||||
|
### 检查状态
|
||||||
|
```bash
|
||||||
|
agent-browser is visible @e1 # 检查是否可见
|
||||||
|
agent-browser is enabled @e1 # 检查是否启用
|
||||||
|
agent-browser is checked @e1 # 检查是否勾选
|
||||||
|
```
|
||||||
|
|
||||||
|
### 截图命令
|
||||||
|
```bash
|
||||||
|
agent-browser screenshot # 截图到标准输出
|
||||||
|
agent-browser screenshot page.png # 保存到文件
|
||||||
|
agent-browser screenshot --full # 完整页面截图
|
||||||
|
```
|
||||||
|
|
||||||
|
### 等待命令
|
||||||
|
```bash
|
||||||
|
agent-browser wait @e1 # 等待元素可见
|
||||||
|
agent-browser wait 2000 # 等待毫秒数
|
||||||
|
agent-browser wait --text "成功" # 等待文本出现
|
||||||
|
agent-browser wait --url "*/dashboard" # 等待 URL 模式匹配
|
||||||
|
agent-browser wait --load networkidle # 等待网络空闲
|
||||||
|
|
||||||
|
# 加载状态选项：load, domcontentloaded, networkidle
|
||||||
|
```
|
||||||
|
|
||||||
|
### 语义化定位器（替代 refs）
|
||||||
|
```bash
|
||||||
|
agent-browser find role button click --name "提交"
|
||||||
|
agent-browser find text "登录" click
|
||||||
|
agent-browser find label "邮箱" fill "user@test.com"
|
||||||
|
agent-browser find placeholder "请输入" fill "内容"
|
||||||
|
agent-browser find first ".item" click
|
||||||
|
agent-browser find nth 2 "a" text
|
||||||
|
```
|
||||||
|
|
||||||
|
## 认证与状态管理
|
||||||
|
|
||||||
|
### 方法1：手动登录流程（推荐用于首次）
|
||||||
|
```bash
|
||||||
|
# 导航到登录页面
|
||||||
|
agent-browser open https://example.com/login
|
||||||
|
|
||||||
|
# 填写表单
|
||||||
|
agent-browser snapshot -i
|
||||||
|
# 输出显示：textbox "邮箱" [ref=e1], textbox "密码" [ref=e2], button "登录" [ref=e3]
|
||||||
|
|
||||||
|
agent-browser fill @e1 "user@example.com"
|
||||||
|
agent-browser fill @e2 "password123"
|
||||||
|
agent-browser click @e3
|
||||||
|
|
||||||
|
# 等待登录成功
|
||||||
|
agent-browser wait --url "*/dashboard"
|
||||||
|
|
||||||
|
# 保存认证状态（重要！）
|
||||||
|
agent-browser state save auth.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### 方法2：加载已保存状态（后续使用）
|
||||||
|
```bash
|
||||||
|
# 加载保存的认证状态
|
||||||
|
agent-browser state load auth.json
|
||||||
|
|
||||||
|
# 直接访问受保护页面
|
||||||
|
agent-browser open https://example.com/dashboard
|
||||||
|
```
|
||||||
|
|
||||||
|
### 方法3：HTTP Headers 认证（跳过登录界面）
|
||||||
|
```bash
|
||||||
|
# 为特定域名设置认证头
|
||||||
|
agent-browser open https://api.example.com --headers '{"Authorization": "Bearer <token>"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 方法4：Cookies 管理
|
||||||
|
```bash
|
||||||
|
# 设置 cookie
|
||||||
|
agent-browser cookies set session_id "abc123"
|
||||||
|
|
||||||
|
# 查看所有 cookies
|
||||||
|
agent-browser cookies
|
||||||
|
```
|
||||||
|
|
||||||
|
## 高级功能
|
||||||
|
|
||||||
|
### 无头/有头模式
|
||||||
|
```bash
|
||||||
|
# 默认：无头模式（无界面）
|
||||||
|
agent-browser open example.com
|
||||||
|
|
||||||
|
# 有头模式：显示浏览器窗口（适合调试）
|
||||||
|
agent-browser --headed open example.com
|
||||||
|
```
|
||||||
|
|
||||||
|
**无头模式特点**：
|
||||||
|
- 后台运行 Chromium
|
||||||
|
- 不占用屏幕空间
|
||||||
|
- 更快的执行速度
|
||||||
|
- 适合自动化测试和 AI Agent 使用
|
||||||
|
|
||||||
|
### 会话隔离
|
||||||
|
```bash
|
||||||
|
# 创建独立会话
|
||||||
|
agent-browser --session user1 open site-a.com
|
||||||
|
agent-browser --session user2 open site-b.com
|
||||||
|
|
||||||
|
# 查看活动会话
|
||||||
|
agent-browser session list
|
||||||
|
|
||||||
|
# 每个会话独立：
|
||||||
|
# - 浏览器实例
|
||||||
|
# - Cookies 和存储
|
||||||
|
# - 导航历史
|
||||||
|
# - 认证状态
|
||||||
|
```
|
||||||
|
|
||||||
|
### JSON 输出（适合机器解析）
|
||||||
|
```bash
|
||||||
|
agent-browser snapshot -i --json
|
||||||
|
agent-browser get text @e1 --json
|
||||||
|
agent-browser is visible @e2 --json
|
||||||
|
```
|
||||||
|
|
||||||
|
### 自定义浏览器可执行文件
|
||||||
|
```bash
|
||||||
|
# 使用自定义 Chromium 路径
|
||||||
|
agent-browser --executable-path /path/to/chromium open example.com
|
||||||
|
|
||||||
|
# 环境变量方式
|
||||||
|
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com
|
||||||
|
```
|
||||||
|
|
||||||
|
### CDP 模式（连接现有浏览器）
|
||||||
|
```bash
|
||||||
|
# 连接通过 Chrome DevTools Protocol 运行的浏览器
|
||||||
|
agent-browser --cdp 9222 snapshot
|
||||||
|
|
||||||
|
# 可控制：Electron 应用、启用远程调试的 Chrome、WebView2 等
|
||||||
|
```
|
||||||
|
|
||||||
|
### 调试工具
|
||||||
|
```bash
|
||||||
|
agent-browser console # 查看控制台消息
|
||||||
|
agent-browser errors # 查看页面错误
|
||||||
|
agent-browser console --clear # 清空控制台
|
||||||
|
agent-browser errors --clear # 清空错误
|
||||||
|
agent-browser highlight @e1 # 高亮显示元素
|
||||||
|
```
|
||||||
|
|
||||||
|
## 示例场景
|
||||||
|
|
||||||
|
### 示例1：表单提交
|
||||||
|
```bash
|
||||||
|
# 1. 导航到表单页面
|
||||||
|
agent-browser open https://example.com/form
|
||||||
|
|
||||||
|
# 2. 获取交互元素快照
|
||||||
|
agent-browser snapshot -i
|
||||||
|
# 输出：textbox "邮箱" [ref=e1], textbox "密码" [ref=e2], button "提交" [ref=e3]
|
||||||
|
|
||||||
|
# 3. 填写并提交表单
|
||||||
|
agent-browser fill @e1 "user@example.com"
|
||||||
|
agent-browser fill @e2 "password123"
|
||||||
|
agent-browser click @e3
|
||||||
|
|
||||||
|
# 4. 等待结果并验证
|
||||||
|
agent-browser wait --load networkidle
|
||||||
|
agent-browser snapshot -i # 检查结果
|
||||||
|
```
|
||||||
|
|
||||||
|
### 示例2：带认证的完整流程
|
||||||
|
```bash
|
||||||
|
# 首次：登录并保存状态
|
||||||
|
agent-browser open https://app.example.com/login
|
||||||
|
agent-browser fill "#email" "username"
|
||||||
|
agent-browser fill "#password" "password123"
|
||||||
|
agent-browser click "#submit"
|
||||||
|
agent-browser wait --url "**/dashboard"
|
||||||
|
agent-browser state save app-auth.json
|
||||||
|
|
||||||
|
# 后续使用：加载状态
|
||||||
|
agent-browser state load app-auth.json
|
||||||
|
agent-browser open https://app.example.com/dashboard
|
||||||
|
|
||||||
|
# 执行操作
|
||||||
|
agent-browser snapshot -i
|
||||||
|
agent-browser click @e1
|
||||||
|
```
|
||||||
|
|
||||||
|
### 示例3：数据提取
|
||||||
|
```bash
|
||||||
|
# 提取列表数据
|
||||||
|
agent-browser open https://example.com/products
|
||||||
|
agent-browser wait --load networkidle
|
||||||
|
|
||||||
|
# 获取所有产品标题
|
||||||
|
for i in $(seq 1 10); do
|
||||||
|
agent-browser get text "@e$i" --json
|
||||||
|
done
|
||||||
|
|
||||||
|
# 或使用 CSS 选择器
|
||||||
|
agent-browser get text ".product-title"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 示例4：并行测试
|
||||||
|
```bash
|
||||||
|
# 会话1：用户A
|
||||||
|
agent-browser --session userA open site.com
|
||||||
|
agent-browser --session userA fill "#email" "userA@test.com"
|
||||||
|
agent-browser --session userA fill "#password" "passA123"
|
||||||
|
|
||||||
|
# 会话2：用户B（同时运行）
|
||||||
|
agent-browser --session userB open site.com
|
||||||
|
agent-browser --session userB fill "#email" "userB@test.com"
|
||||||
|
agent-browser --session userB fill "#password" "passB123"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 最佳实践
|
||||||
|
|
||||||
|
### 1. 优先使用 Refs
|
||||||
|
- 从 `snapshot -i` 获取 refs
|
||||||
|
- 使用 `@e1`、`@e2` 而非 CSS 选择器
|
||||||
|
- 页面变化后重新快照获取新 refs
|
||||||
|
|
||||||
|
### 2. 合理使用等待
|
||||||
|
- 页面加载：`wait --load networkidle`
|
||||||
|
- 元素出现：`wait @e1`
|
||||||
|
- 文本出现：`wait --text "成功"`
|
||||||
|
- 避免硬编码 sleep，使用条件等待
|
||||||
|
|
||||||
|
### 3. 状态管理策略
|
||||||
|
- 首次登录后使用 `state save`
|
||||||
|
- 后续使用 `state load` 避免重复登录
|
||||||
|
- 敏感操作使用 `--session` 隔离
|
||||||
|
|
||||||
|
### 4. 错误处理
|
||||||
|
- 检查元素是否存在：`is visible @e1`
|
||||||
|
- 查看控制台日志：`console`
|
||||||
|
- 调试时使用 `--headed` 模式
|
||||||
|
|
||||||
|
### 5. 性能优化
|
||||||
|
- 使用 `-i` 参数限制快照输出
|
||||||
|
- 批量操作使用循环
|
||||||
|
- 合理使用等待避免超时
|
||||||
|
|
||||||
|
## 故障排除
|
||||||
|
|
||||||
|
### 常见问题
|
||||||
|
|
||||||
|
**1. "command not found: agent-browser" 错误**
|
||||||
|
```bash
|
||||||
|
# 错误原因：agent-browser 未安装
|
||||||
|
# 解决方案：运行安装命令
|
||||||
|
npm install -g agent-browser
|
||||||
|
agent-browser install
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. "Unsupported token @e1" 错误**
|
||||||
|
```bash
|
||||||
|
# 错误原因：快照后页面已刷新，refs 失效
|
||||||
|
# 解决方案：重新获取快照
|
||||||
|
agent-browser snapshot -i
|
||||||
|
agent-browser click @e1 # 使用新的 ref
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. 元素找不到**
|
||||||
|
```bash
|
||||||
|
# 检查元素是否存在
|
||||||
|
agent-browser is visible @e1
|
||||||
|
|
||||||
|
# 等待元素出现
|
||||||
|
agent-browser wait @e1
|
||||||
|
|
||||||
|
# 使用语义化查找
|
||||||
|
agent-browser find role button click --name "提交"
|
||||||
|
```
|
||||||
|
|
||||||
|
**4. 登录状态丢失**
|
||||||
|
```bash
|
||||||
|
# 重新登录并保存状态
|
||||||
|
agent-browser state save auth.json
|
||||||
|
|
||||||
|
# 或设置 cookies
|
||||||
|
agent-browser cookies set session_id "value"
|
||||||
|
```
|
||||||
|
|
||||||
|
**5. 页面加载缓慢**
|
||||||
|
```bash
|
||||||
|
# 增加等待时间
|
||||||
|
agent-browser wait --load networkidle
|
||||||
|
agent-browser wait 5000
|
||||||
|
|
||||||
|
# 或设置超时
|
||||||
|
agent-browser set timeout 30000
|
||||||
|
```
|
||||||
|
|
||||||
|
## 平台支持
|
||||||
|
|
||||||
|
| 平台 | 原生二进制 | 回退方案 |
|
||||||
|
|------|-----------|----------|
|
||||||
|
| macOS ARM64 | ✓ | Node.js |
|
||||||
|
| macOS x64 | ✓ | Node.js |
|
||||||
|
| Linux ARM64 | ✓ | Node.js |
|
||||||
|
| Linux x64 | ✓ | Node.js |
|
||||||
|
| Windows x64 | ✓ | Node.js |
|
||||||
|
|
||||||
|
## 技术架构
|
||||||
|
|
||||||
|
agent-browser 采用客户端-守护进程架构：
|
||||||
|
1. **Rust CLI**（原生二进制）- 解析命令，与守护进程通信
|
||||||
|
2. **Node.js 守护进程** - 管理 Playwright 浏览器实例
|
||||||
|
3. **回退方案** - 如果原生二进制不可用，直接使用 Node.js
|
||||||
|
|
||||||
|
守护进程在首次命令时自动启动，并在命令间持久化以实现快速后续操作。
|
||||||
|
|
||||||
|
**浏览器引擎**：默认使用 Chromium。守护进程也支持通过 Playwright 协议使用 Firefox 和 WebKit。
|
||||||
|
|
||||||
|
## 相关资源
|
||||||
|
|
||||||
|
- 官方仓库：https://github.com/vercel-labs/agent-browser
|
||||||
|
- 官方文档：https://agent-browser.dev
|
||||||
|
- npm 包：https://www.npmjs.com/package/agent-browser
|
||||||
|
|
||||||
|
## 许可证
|
||||||
|
|
||||||
|
Apache-2.0
|
||||||
151
skill/opencode/SKILL.md
Normal file
151
skill/opencode/SKILL.md
Normal file
@@ -0,0 +1,151 @@
|
|||||||
|
---
|
||||||
|
name: opencode
|
||||||
|
description: Create and manage OpenCode commands and skills with templates and best practices. Use this skill when users ask to create commands or skills.
|
||||||
|
---
|
||||||
|
|
||||||
|
# OpenCode Command and Skill Management
|
||||||
|
|
||||||
|
You are an expert in OpenCode configuration and extension development. This skill serves as the entry point for creating and managing OpenCode commands and skills.
|
||||||
|
|
||||||
|
**Trigger Phrases**: When users mention any of the following, automatically use this skill:
|
||||||
|
- "创建command", "创建命令", "make command", "create command"
|
||||||
|
- "创建skill", "创建技能", "make skill", "create skill"
|
||||||
|
- "添加command", "添加命令", "add command"
|
||||||
|
- "添加skill", "添加技能", "add skill"
|
||||||
|
- "opcode command", "opencode skill"
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
OpenCode extensions are organized into two main types:
|
||||||
|
- **Commands**: User-invoked prompts for repetitive tasks, defined in `command/` directory
|
||||||
|
- **Skills**: Reusable behavior definitions for agents, defined in `skill/<name>/SKILL.md`
|
||||||
|
|
||||||
|
## Detailed Guides
|
||||||
|
|
||||||
|
This skill folder contains comprehensive guides for command and skill creation:
|
||||||
|
|
||||||
|
### Command Creation
|
||||||
|
For detailed command creation guidelines, refer to:
|
||||||
|
- `skill/opencode/command-creation.md` - Complete guide to creating OpenCode commands
|
||||||
|
- Includes: file structure, templates, best practices, troubleshooting
|
||||||
|
|
||||||
|
### Skill Creation
|
||||||
|
For detailed skill creation guidelines, refer to:
|
||||||
|
- `skill/opencode/skill-creation.md` - Complete guide to creating OpenCode skills
|
||||||
|
- Includes: directory structure, naming rules, templates, testing
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### To Create a Command
|
||||||
|
1. Determine command name (kebab-case, descriptive)
|
||||||
|
2. **Default location**: global (`~/.config/opencode/command/`)
|
||||||
|
3. Create file: `<command-name>.md`
|
||||||
|
4. Add frontmatter with `description`
|
||||||
|
5. Write template with `$ARGUMENTS` support
|
||||||
|
|
||||||
|
### To Create a Skill
|
||||||
|
1. Validate skill name (lowercase, hyphens, alphanumeric)
|
||||||
|
2. **Default location**: global (`~/.config/opencode/skill/<skill-name>/`)
|
||||||
|
3. Create directory: `skill/<skill-name>/`
|
||||||
|
4. Create `SKILL.md` with required frontmatter
|
||||||
|
5. Add structured content: Purpose, Usage, Examples, Troubleshooting
|
||||||
|
|
||||||
|
## Automatic Name Generation
|
||||||
|
|
||||||
|
When users request command or skill creation, names are automatically generated based on the description to provide a seamless experience.
|
||||||
|
|
||||||
|
### For Commands:
|
||||||
|
1. **Keyword Extraction**: Identify action verbs and target nouns from the description
|
||||||
|
2. **English Conversion**: Convert Chinese keywords to English equivalents (e.g., "创建" → "create", "总结" → "summarize")
|
||||||
|
3. **Kebab-case Format**: Combine words with hyphens, all lowercase (e.g., "create-summary")
|
||||||
|
4. **Conflict Resolution**: Check if name exists in `command/` directory, append numeric suffix if needed
|
||||||
|
|
||||||
|
### For Skills:
|
||||||
|
1. **Function Extraction**: Identify core functionality from the description
|
||||||
|
2. **Simplified Naming**: Use lowercase, hyphen-separated words describing the skill's purpose
|
||||||
|
3. **Validation**: Ensure name follows `[a-z0-9-]+` pattern
|
||||||
|
4. **Conflict Check**: Verify uniqueness in `skill/` directory
|
||||||
|
|
||||||
|
### Examples:
|
||||||
|
- "创建command，用于归纳总结当前对话中有价值的内容" → `summarize-conversation`
|
||||||
|
- "创建skill，用于管理git工作流" → `git-workflow`
|
||||||
|
- "添加命令来处理图片压缩" → `compress-images`
|
||||||
|
- "创建技能用于代码审查" → `code-review`
|
||||||
|
|
||||||
|
### User Override:
|
||||||
|
If users explicitly provide a name in their request, use the provided name instead of auto-generation.
|
||||||
|
|
||||||
|
## Response Guide for Creation Requests
|
||||||
|
|
||||||
|
When users ask to create commands or skills, follow this structured approach:
|
||||||
|
|
||||||
|
### For "创建command" or "创建命令" requests:
|
||||||
|
1. **自动生成名称**: 基于用户描述自动生成 kebab-case 命令名称
|
||||||
|
- 从描述中提取关键词（动词+名词）
|
||||||
|
- 转换为英文 kebab-case 格式
|
||||||
|
- 如果名称已存在，添加数字后缀（如 `-2`, `-3`）
|
||||||
|
2. **验证名称**: 确保名称符合 kebab-case 规范
|
||||||
|
3. **默认位置**: 全局 (`~/.config/opencode/command/`)
|
||||||
|
4. **创建模板**:
|
||||||
|
- 生成包含 `description` 的 frontmatter
|
||||||
|
- 创建支持 `$ARGUMENTS` 的模板
|
||||||
|
- 包含使用示例
|
||||||
|
5. **写入文件**: 在默认位置创建命令文件
|
||||||
|
6. **测试**: 验证文件存在且格式正确
|
||||||
|
|
||||||
|
### For "创建skill" or "创建技能" requests:
|
||||||
|
1. **自动生成名称**: 基于用户描述自动生成 skill 名称
|
||||||
|
- 从描述中提取核心功能关键词
|
||||||
|
- 转换为小写字母、连字符格式
|
||||||
|
- 如果名称已存在，添加数字后缀
|
||||||
|
2. **验证名称**: 确保名称符合命名规则（小写字母、连字符、字母数字）
|
||||||
|
3. **默认位置**: 全局 (`~/.config/opencode/skill/<name>/`)
|
||||||
|
4. **创建目录**: `skill/<name>/`
|
||||||
|
5. **创建 SKILL.md**:
|
||||||
|
- 包含 `name` 和 `description` 的 frontmatter
|
||||||
|
- 结构化内容：Purpose, Usage, Examples, Best Practices, Troubleshooting
|
||||||
|
6. **写入文件**: 在默认位置创建完整的 SKILL.md 文件
|
||||||
|
7. **测试**: 验证技能可正常加载 `skill({ name: "<skill-name>" })`
|
||||||
|
|
||||||
|
### Sample Response Format:
|
||||||
|
```
|
||||||
|
我将帮你创建 [command/skill]。
|
||||||
|
|
||||||
|
基于您的描述，自动生成名称：[generated-name]
|
||||||
|
|
||||||
|
**自动命名规则**:
|
||||||
|
- 从描述中提取关键词（动词+名词）
|
||||||
|
- 转换为 kebab-case 格式（小写字母、连字符）
|
||||||
|
- 检查名称冲突，自动添加数字后缀
|
||||||
|
|
||||||
|
**文件详情**:
|
||||||
|
- 名称: [generated-name]
|
||||||
|
- 用途: [brief-description]
|
||||||
|
- 位置: 全局 (~/.config/opencode/[command|skill]/)
|
||||||
|
|
||||||
|
已创建 [file-path]：
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
[complete file content]
|
||||||
|
```
|
||||||
|
|
||||||
|
要测试，请运行：[/command-name] 或 skill({ name: "skill-name" })
|
||||||
|
```
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
- [OpenCode Skills Documentation](https://opencode.ai/docs/skills)
|
||||||
|
- [OpenCode Commands Documentation](https://opencode.ai/docs/commands)
|
||||||
|
- [OpenCode Configuration Guide](https://opencode.ai/docs/config)
|
||||||
|
- [GitHub Repository](https://github.com/anomalyco/opencode)
|
||||||
|
|
||||||
|
## Updates and Maintenance
|
||||||
|
|
||||||
|
1. **Regular Review**: Periodically review and update commands/skills
|
||||||
|
2. **Version Tracking**: Use Git to track changes
|
||||||
|
3. **Community Sharing**: Share useful commands/skills with community
|
||||||
|
4. **Feedback Integration**: Incorporate user feedback for improvements
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Last updated: 2026-01-15*
|
||||||
201
skill/opencode/command-creation.md
Normal file
201
skill/opencode/command-creation.md
Normal file
@@ -0,0 +1,201 @@
|
|||||||
|
# Command Creation Guide
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
OpenCode commands are user-invoked prompts for repetitive tasks, defined in the `command/` directory.
|
||||||
|
|
||||||
|
## File Location
|
||||||
|
- **Default location (Global)**: `~/.config/opencode/command/<name>.md`
|
||||||
|
- **Project-specific**: `.opencode/command/<name>.md` (when needed)
|
||||||
|
|
||||||
|
## Command Structure
|
||||||
|
Each command file must contain YAML frontmatter followed by the prompt template.
|
||||||
|
|
||||||
|
### Required Frontmatter Fields
|
||||||
|
- `description`: Brief description shown in TUI (1-2 sentences)
|
||||||
|
|
||||||
|
### Optional Frontmatter Fields
|
||||||
|
- `agent`: Specific agent to execute this command
|
||||||
|
- `model`: Override default model
|
||||||
|
- `subtask`: Boolean to force subagent invocation
|
||||||
|
|
||||||
|
## Template Features
|
||||||
|
The command template supports several placeholders:
|
||||||
|
|
||||||
|
- `$ARGUMENTS`: All arguments passed to the command
|
||||||
|
- `$1`, `$2`, `$3`: Individual positional arguments
|
||||||
|
- `!``command``: Execute bash command and inject output
|
||||||
|
- `@filename`: Include file content in prompt
|
||||||
|
|
||||||
|
## Example Command
|
||||||
|
Create `~/.config/opencode/command/new-skill.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
description: Create a new OpenCode skill with proper structure
|
||||||
|
---
|
||||||
|
|
||||||
|
Create a new OpenCode skill named "$ARGUMENTS" with comprehensive documentation.
|
||||||
|
|
||||||
|
**Skill Requirements:**
|
||||||
|
1. Directory: `skill/$ARGUMENTS/SKILL.md`
|
||||||
|
2. Frontmatter with `name` and `description`
|
||||||
|
3. Clear sections for usage, examples, best practices
|
||||||
|
4. Follow naming conventions: lowercase, hyphens, alphanumeric
|
||||||
|
|
||||||
|
**Steps:**
|
||||||
|
1. Create directory structure
|
||||||
|
2. Write SKILL.md with frontmatter
|
||||||
|
3. Include practical examples
|
||||||
|
4. Add troubleshooting section
|
||||||
|
|
||||||
|
Output the complete SKILL.md content for review.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Command Design
|
||||||
|
1. **Clear Purpose**: Each command should have a single, focused purpose
|
||||||
|
2. **Descriptive Names**: Use verbs that describe the action (e.g., `create-`, `review-`, `analyze-`)
|
||||||
|
3. **Argument Handling**: Use `$ARGUMENTS` or `$1`, `$2` for flexible input
|
||||||
|
4. **Error Handling**: Include validation in prompts
|
||||||
|
5. **Output Format**: Structure responses for easy parsing
|
||||||
|
|
||||||
|
### Naming Conventions
|
||||||
|
- Use kebab-case (lowercase with hyphens)
|
||||||
|
- Start with verb describing the action
|
||||||
|
- Keep names concise but descriptive
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
### Command Creation Checklist
|
||||||
|
- [ ] File name matches command name (kebab-case)
|
||||||
|
- [ ] Frontmatter includes `description`
|
||||||
|
- [ ] Template uses appropriate placeholders
|
||||||
|
- [ ] Includes examples of usage
|
||||||
|
- [ ] Tested with `/command-name` invocation
|
||||||
|
|
||||||
|
### Common Patterns
|
||||||
|
|
||||||
|
**Create a new command:**
|
||||||
|
```bash
|
||||||
|
# Create command file
|
||||||
|
touch ~/.config/opencode/command/my-command.md
|
||||||
|
|
||||||
|
# Edit with template
|
||||||
|
cat > ~/.config/opencode/command/my-command.md << 'EOF'
|
||||||
|
---
|
||||||
|
description: Description of my command
|
||||||
|
---
|
||||||
|
|
||||||
|
Command template with $ARGUMENTS support.
|
||||||
|
|
||||||
|
Example: /my-command argument1 argument2
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing and Validation
|
||||||
|
|
||||||
|
### Test Command Loading
|
||||||
|
```bash
|
||||||
|
# Check if command appears in TUI
|
||||||
|
# Type "/" in OpenCode TUI and search for your command
|
||||||
|
```
|
||||||
|
|
||||||
|
### Verify Syntax
|
||||||
|
```bash
|
||||||
|
# Check YAML frontmatter
|
||||||
|
head -20 command/my-command.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Command Not Appearing
|
||||||
|
1. **Check file location**: Ensure command is in correct `command/` directory
|
||||||
|
2. **Verify frontmatter**: Must have `description` field
|
||||||
|
3. **Check permissions**: No restrictive permissions blocking command
|
||||||
|
4. **Restart OpenCode**: Some changes require restart
|
||||||
|
|
||||||
|
### Common Errors
|
||||||
|
- **"Command not found"**: File not in correct location or missing `.md` extension
|
||||||
|
- **"Invalid frontmatter"**: Missing required fields or YAML syntax error
|
||||||
|
|
||||||
|
## Integration with OpenCode Config
|
||||||
|
|
||||||
|
### Permissions Configuration
|
||||||
|
Add to `opencode.json`:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"permission": {
|
||||||
|
"skill": {
|
||||||
|
"*": "allow",
|
||||||
|
"experimental-*": "ask",
|
||||||
|
"internal-*": "deny"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Agent-Specific Settings
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agent": {
|
||||||
|
"plan": {
|
||||||
|
"permission": {
|
||||||
|
"skill": {
|
||||||
|
"analysis-*": "allow"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Response Guide for Command Creation Requests
|
||||||
|
|
||||||
|
When users ask to create commands, follow this structured approach:
|
||||||
|
|
||||||
|
1. **自动生成名称**: 基于用户描述自动生成 kebab-case 命令名称
|
||||||
|
- 从描述中提取关键词（动词+名词）
|
||||||
|
- 转换为英文 kebab-case 格式
|
||||||
|
- 如果名称已存在，添加数字后缀（如 `-2`, `-3`）
|
||||||
|
2. **验证名称**: 确保名称符合 kebab-case 规范
|
||||||
|
3. **默认位置**: 全局 (`~/.config/opencode/command/`) - commands are created here by default
|
||||||
|
4. **创建模板**:
|
||||||
|
- 生成包含 `description` 的 frontmatter
|
||||||
|
- 创建支持 `$ARGUMENTS` 的模板
|
||||||
|
- 包含使用示例
|
||||||
|
5. **写入文件**: 创建命令文件并写入内容
|
||||||
|
6. **测试**: 验证文件存在且格式正确
|
||||||
|
|
||||||
|
### Sample Response Format:
|
||||||
|
```
|
||||||
|
我将帮你创建命令。
|
||||||
|
|
||||||
|
基于您的描述，自动生成名称：[generated-name]
|
||||||
|
|
||||||
|
**自动命名规则**:
|
||||||
|
- 从描述中提取关键词（动词+名词）
|
||||||
|
- 转换为 kebab-case 格式（小写字母、连字符）
|
||||||
|
- 检查名称冲突，自动添加数字后缀
|
||||||
|
|
||||||
|
**文件详情**:
|
||||||
|
- 名称: [generated-name]
|
||||||
|
- 用途: [brief-description]
|
||||||
|
- 位置: 全局 (~/.config/opencode/command/)
|
||||||
|
|
||||||
|
已创建 [file-path]：
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
[complete file content]
|
||||||
|
```
|
||||||
|
|
||||||
|
要测试，请运行：[/command-name]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
- [OpenCode Commands Documentation](https://opencode.ai/docs/commands)
|
||||||
|
- [OpenCode Configuration Guide](https://opencode.ai/docs/config)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Last updated: 2026-01-15*
|
||||||
251
skill/opencode/skill-creation.md
Normal file
251
skill/opencode/skill-creation.md
Normal file
@@ -0,0 +1,251 @@
|
|||||||
|
# Skill Creation Guide
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
OpenCode skills are reusable behavior definitions for agents, defined in `skill/<name>/SKILL.md` files.
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
**Default location (Global):**
|
||||||
|
```
|
||||||
|
~/.config/opencode/skill/
|
||||||
|
└── <skill-name>/
|
||||||
|
└── SKILL.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Project-specific location (when needed):**
|
||||||
|
```
|
||||||
|
.opencode/skill/
|
||||||
|
└── <skill-name>/
|
||||||
|
└── SKILL.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Skill File Requirements
|
||||||
|
|
||||||
|
### Frontmatter (Required)
|
||||||
|
- `name`: Skill name (must match directory name)
|
||||||
|
- `description`: Concise description (1-1024 characters)
|
||||||
|
|
||||||
|
### Frontmatter (Optional)
|
||||||
|
- `license`: License identifier
|
||||||
|
- `compatibility`: Compatibility constraints
|
||||||
|
- `metadata`: Key-value pairs for additional context
|
||||||
|
|
||||||
|
## Naming Rules
|
||||||
|
Skill names must:
|
||||||
|
- Be 1-64 characters
|
||||||
|
- Use lowercase alphanumeric with single hyphens
|
||||||
|
- Not start or end with hyphen
|
||||||
|
- Not contain consecutive hyphens
|
||||||
|
- Match regex: `^[a-z0-9]+(-[a-z0-9]+)*$`
|
||||||
|
|
||||||
|
## Skill Content Structure
|
||||||
|
A well-structured skill should include:
|
||||||
|
|
||||||
|
1. **Introduction**: Purpose and scope
|
||||||
|
2. **Usage Instructions**: When and how to use the skill
|
||||||
|
3. **Examples**: Practical implementation examples
|
||||||
|
4. **Best Practices**: Recommended approaches
|
||||||
|
5. **Troubleshooting**: Common issues and solutions
|
||||||
|
6. **References**: Related documentation
|
||||||
|
|
||||||
|
## Example Skill Template
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
name: example-skill
|
||||||
|
description: Brief description of what this skill does
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill Title
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
Explain what this skill helps achieve and when to use it.
|
||||||
|
|
||||||
|
## Core Concepts
|
||||||
|
- Key principle 1
|
||||||
|
- Key principle 2
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
Step-by-step instructions for using this skill.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
### Basic Example
|
||||||
|
```bash
|
||||||
|
# Example code or commands
|
||||||
|
```
|
||||||
|
|
||||||
|
### Advanced Example
|
||||||
|
Detailed example with explanation.
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
1. Recommended approach 1
|
||||||
|
2. Recommended approach 2
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
| Issue | Solution |
|
||||||
|
|-------|----------|
|
||||||
|
| Common problem | How to fix it |
|
||||||
|
|
||||||
|
## References
|
||||||
|
- [Documentation link](https://opencode.ai/docs)
|
||||||
|
- Related skills or commands
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Skill Development
|
||||||
|
1. **Modular Design**: Keep skills focused on specific domains
|
||||||
|
2. **Comprehensive Documentation**: Include examples and edge cases
|
||||||
|
3. **Consistent Formatting**: Follow existing skill patterns
|
||||||
|
4. **Testing**: Verify skill loads correctly with `skill({ name: "skill-name" })`
|
||||||
|
5. **Version Control**: Track skill changes in Git
|
||||||
|
|
||||||
|
### Organization
|
||||||
|
1. **Default location**: Global (`~/.config/opencode/skill/`) - skills are created here by default for reuse across projects
|
||||||
|
2. **Naming Conventions**: Use kebab-case for all skill names
|
||||||
|
3. **Documentation**: Maintain README or index of available skills
|
||||||
|
4. **Permissions**: Configure access controls in `opencode.json`
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
### Skill Creation Checklist
|
||||||
|
- [ ] Directory name matches skill name
|
||||||
|
- [ ] SKILL.md contains required frontmatter
|
||||||
|
- [ ] Description is 1-1024 characters
|
||||||
|
- [ ] Name follows naming rules
|
||||||
|
- [ ] Content includes usage and examples
|
||||||
|
- [ ] Skill loads without errors
|
||||||
|
|
||||||
|
### Common Patterns
|
||||||
|
|
||||||
|
**Create a new skill:**
|
||||||
|
```bash
|
||||||
|
# Create skill directory
|
||||||
|
mkdir -p ~/.config/opencode/skill/my-skill
|
||||||
|
|
||||||
|
# Create SKILL.md
|
||||||
|
cat > ~/.config/opencode/skill/my-skill/SKILL.md << 'EOF'
|
||||||
|
---
|
||||||
|
name: my-skill
|
||||||
|
description: Description of my skill
|
||||||
|
---
|
||||||
|
|
||||||
|
# My Skill
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
Instructions here.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
Example content.
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing and Validation
|
||||||
|
|
||||||
|
### Test Skill Loading
|
||||||
|
```bash
|
||||||
|
# In OpenCode session
|
||||||
|
skill({ name: "my-skill" })
|
||||||
|
```
|
||||||
|
|
||||||
|
### Verify Syntax
|
||||||
|
```bash
|
||||||
|
# Check YAML frontmatter
|
||||||
|
head -20 skill/my-skill/SKILL.md
|
||||||
|
|
||||||
|
# Validate naming
|
||||||
|
echo "skill-name" | grep -E '^[a-z0-9]+(-[a-z0-9]+)*$'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Skill Not Loading
|
||||||
|
1. **Directory name**: Must match skill name in frontmatter
|
||||||
|
2. **File name**: Must be `SKILL.md` (all caps)
|
||||||
|
3. **Frontmatter**: Requires `name` and `description`
|
||||||
|
4. **Naming rules**: Verify name follows conventions
|
||||||
|
5. **Permissions**: Check `opencode.json` permissions
|
||||||
|
|
||||||
|
### Common Errors
|
||||||
|
- **"Skill not found"**: Directory name mismatch or missing SKILL.md
|
||||||
|
- **"Invalid frontmatter"**: Missing required fields or YAML syntax error
|
||||||
|
- **"Permission denied"**: Skill blocked by permission configuration
|
||||||
|
|
||||||
|
## Integration with OpenCode Config
|
||||||
|
|
||||||
|
### Permissions Configuration
|
||||||
|
Add to `opencode.json`:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"permission": {
|
||||||
|
"skill": {
|
||||||
|
"*": "allow",
|
||||||
|
"experimental-*": "ask",
|
||||||
|
"internal-*": "deny"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Agent-Specific Settings
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agent": {
|
||||||
|
"plan": {
|
||||||
|
"permission": {
|
||||||
|
"skill": {
|
||||||
|
"analysis-*": "allow"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Response Guide for Skill Creation Requests
|
||||||
|
|
||||||
|
When users ask to create skills, follow this structured approach:
|
||||||
|
|
||||||
|
1. **自动生成名称**: 基于用户描述自动生成 skill 名称
|
||||||
|
- 从描述中提取核心功能关键词
|
||||||
|
- 转换为小写字母、连字符格式
|
||||||
|
- 如果名称已存在，添加数字后缀
|
||||||
|
2. **验证名称**: 确保名称符合命名规则（小写字母、连字符、字母数字）
|
||||||
|
3. **默认位置**: 全局 (`~/.config/opencode/skill/<name>/`) - skills are created here by default
|
||||||
|
4. **创建 SKILL.md**:
|
||||||
|
- 包含 `name` 和 `description` 的 frontmatter
|
||||||
|
- 结构化内容：Purpose, Usage, Examples, Best Practices, Troubleshooting
|
||||||
|
5. **写入文件**: 创建完整的 SKILL.md 文件
|
||||||
|
6. **测试**: 验证技能可正常加载 `skill({ name: "<skill-name>" })`
|
||||||
|
|
||||||
|
### Sample Response Format:
|
||||||
|
```
|
||||||
|
我将帮你创建技能。
|
||||||
|
|
||||||
|
基于您的描述，自动生成名称：[generated-name]
|
||||||
|
|
||||||
|
**自动命名规则**:
|
||||||
|
- 从描述中提取核心功能关键词
|
||||||
|
- 转换为小写字母、连字符格式
|
||||||
|
- 检查名称冲突，自动添加数字后缀
|
||||||
|
|
||||||
|
**文件详情**:
|
||||||
|
- 名称: [generated-name]
|
||||||
|
- 主要功能: [brief-description]
|
||||||
|
- 位置: 全局 (~/.config/opencode/skill/)
|
||||||
|
|
||||||
|
已创建 [file-path]：
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
[complete file content]
|
||||||
|
```
|
||||||
|
|
||||||
|
要测试，请运行：skill({ name: "skill-name" })
|
||||||
|
```
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
- [OpenCode Skills Documentation](https://opencode.ai/docs/skills)
|
||||||
|
- [OpenCode Configuration Guide](https://opencode.ai/docs/config)
|
||||||
|
- [GitHub Repository](https://github.com/anomalyco/opencode)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Last updated: 2026-01-15*
|
||||||
Reference in New Issue
Block a user