OpenCode 与 OpenSkills 集成 API 文档

icodebase 5小时前 AI基础 opencodeopenskills 收藏

0 / 5

概述

OpenCode 是一个支持代理技能的 AI 编辑器，而 OpenSkills 是一个跨编辑器 AI 技能管理工具。通过两者的集成，开发者可以：

统一管理技能：使用 OpenSkills 安装和管理技能
跨编辑器复用：在 OpenCode 中无缝使用 OpenSkills 管理的技能
简化配置：避免为不同编辑器重复配置技能

架构关系

OpenSkills (技能管理器)
    ├── 技能安装
    ├── 技能同步
    ├── 路径管理
    └── 跨编辑器适配
        │
        └── OpenCode (AI 编辑器)
            ├── 技能发现
            ├── 技能加载
            ├── 权限控制
            └── 工具集成

集成方案

方案一：使用 OpenSkills 作为技能源

1. 安装 OpenSkills

# 全局安装 OpenSkills
npm install -g openskills

# 验证安装
openskills --version

2. 配置 OpenCode 使用 OpenSkills 管理的技能

方法 A：直接使用 OpenSkills 安装路径

OpenCode 原生支持以下路径，与 OpenSkills 的安装路径兼容：

# 使用 OpenSkills 安装技能到 OpenCode 兼容路径
openskills install anthropics/skills/pdf --project  # 安装到 .claude/skills
openskills install anthropics/skills/xlsx --global  # 安装到 ~/.claude/skills

方法 B：使用符号链接（推荐）

# 1. 使用 OpenSkills 安装技能到通用目录
openskills install anthropics/skills/pdf --universal

# 2. 创建符号链接到 OpenCode 目录
# Linux/macOS
ln -s $(pwd)/.agent/skills/pdf .opencode/skills/pdf

# Windows (PowerShell)
New-Item -ItemType SymbolicLink -Path ".opencode\skills\pdf" -Target ".agent\skills\pdf"

3. 同步技能信息

# 生成 AGENTS.md（OpenSkills 格式）
openskills sync

# 将 AGENTS.md 转换为 OpenCode 可用的格式
cat AGENTS.md | grep -A2 "<skill>" | sed 's/<name>//g; s/<\/name>//g; s/<description>//g; s/<\/description>//g' > .opencode/skills-list.md

方案二：使用 OpenSkills 作为技能代理

1. 创建 OpenCode 技能包装器

创建 .opencode/skills/openskills-proxy/SKILL.md：

---
name: openskills-proxy
description: 通过 OpenSkills 管理系统加载和管理技能
license: MIT
compatibility: opencode
metadata:
  type: skill-manager
  manager: openskills
---

## 功能描述

此技能作为 OpenSkills 的代理，允许 OpenCode 通过 OpenSkills 系统：
1. 列出所有可用的技能
2. 动态加载技能内容
3. 管理技能权限

## 使用方法

### 列出可用技能
```bash
openskills list

加载特定技能

openskills read <skill-name>

安装新技能

openskills install <source> [--project|--global|--universal]

集成示例

当需要特定技能时，我会：

检查技能是否已安装
如果未安装，提示安装命令
加载技能内容供使用

#### 2. 配置 OpenCode 权限

在 `opencode.json` 中配置：

```json
{
  "permission": {
    "skill": {
      "openskills-proxy": "allow",
      "pdf": "allow",
      "xlsx": "allow",
      "*": "ask"
    }
  },
  "agent": {
    "default": {
      "tools": {
        "skill": true
      }
    }
  }
}

API 接口映射

OpenSkills 命令 → OpenCode 集成

OpenSkills 命令	OpenCode 集成方式	说明
`openskills install`	自动安装到兼容路径	技能立即可用
`openskills sync`	生成技能清单	更新可用技能列表
`openskills read`	动态技能加载	按需加载技能内容
`openskills list`	技能发现	显示所有可用技能

OpenCode 技能发现 → OpenSkills 路径

OpenCode 按以下顺序搜索技能，与 OpenSkills 安装路径对应：

项目级技能：
- .opencode/skills/ ← OpenSkills --project 安装（通过符号链接）
- .claude/skills/ ← OpenSkills --project 安装（原生兼容）
全局级技能：
- ~/.config/opencode/skills/ ← OpenSkills --global 安装（通过符号链接）
- ~/.claude/skills/ ← OpenSkills --global 安装（原生兼容）
通用技能：
- .agent/skills/ ← OpenSkills --universal 安装（推荐集成路径）

配置示例

完整的集成配置

1. 初始化脚本 `setup-opencode-skills.sh`

#!/bin/bash
# setup-opencode-skills.sh

echo "=== OpenCode + OpenSkills 集成配置 ==="

# 1. 安装 OpenSkills
if ! command -v openskills &> /dev/null; then
    echo "安装 OpenSkills..."
    npm install -g openskills
else
    echo "OpenSkills 已安装"
fi

# 2. 创建目录结构
mkdir -p .opencode/skills
mkdir -p .agent/skills

# 3. 安装常用技能
echo "安装常用技能..."
openskills install anthropics/skills/pdf --universal
openskills install anthropics/skills/xlsx --universal
openskills install anthropics/skills/frontend-design --universal

# 4. 创建符号链接
echo "创建符号链接..."
for skill in .agent/skills/*; do
    if [ -d "$skill" ]; then
        skill_name=$(basename "$skill")
        ln -sfn "../../.agent/skills/$skill_name" ".opencode/skills/$skill_name"
        echo "  ✓ 链接: $skill_name"
    fi
done

# 5. 生成技能清单
echo "生成技能清单..."
openskills sync

# 6. 创建 OpenCode 配置文件
cat > opencode.json << EOF
{
  "version": "1.0",
  "permission": {
    "skill": {
      "pdf": "allow",
      "xlsx": "allow",
      "frontend-design": "allow",
      "openskills-proxy": "allow",
      "*": "ask"
    }
  },
  "agent": {
    "default": {
      "tools": {
        "skill": true
      }
    }
  }
}
EOF

echo "=== 配置完成 ==="
echo "可用技能:"
openskills list

2. Windows PowerShell 配置脚本 `Setup-OpenCodeSkills.ps1`

# Setup-OpenCodeSkills.ps1

Write-Host "=== OpenCode + OpenSkills 集成配置 ===" -ForegroundColor Cyan

# 1. 检查并安装 OpenSkills
if (-not (Get-Command openskills -ErrorAction SilentlyContinue)) {
    Write-Host "安装 OpenSkills..." -ForegroundColor Yellow
    npm install -g openskills
} else {
    Write-Host "OpenSkills 已安装" -ForegroundColor Green
}

# 2. 创建目录结构
New-Item -ItemType Directory -Force -Path ".opencode\skills"
New-Item -ItemType Directory -Force -Path ".agent\skills"

# 3. 安装常用技能
Write-Host "安装常用技能..." -ForegroundColor Yellow
openskills install anthropics/skills/pdf --universal
openskills install anthropics/skills/xlsx --universal
openskills install anthropics/skills/frontend-design --universal

# 4. 创建符号链接
Write-Host "创建符号链接..." -ForegroundColor Yellow
Get-ChildItem ".agent\skills" -Directory | ForEach-Object {
    $skillName = $_.Name
    $target = "..\..\.agent\skills\$skillName"
    $link = ".opencode\skills\$skillName"
    
    if (Test-Path $link) {
        Remove-Item $link -Force
    }
    
    New-Item -ItemType SymbolicLink -Path $link -Target $target
    Write-Host "  ✓ 链接: $skillName" -ForegroundColor Green
}

# 5. 生成技能清单
Write-Host "生成技能清单..." -ForegroundColor Yellow
openskills sync

# 6. 创建 OpenCode 配置文件
@'
{
  "version": "1.0",
  "permission": {
    "skill": {
      "pdf": "allow",
      "xlsx": "allow",
      "frontend-design": "allow",
      "openskills-proxy": "allow",
      "*": "ask"
    }
  },
  "agent": {
    "default": {
      "tools": {
        "skill": true
      }
    }
  }
}
'@ | Out-File -FilePath "opencode.json" -Encoding UTF8

Write-Host "=== 配置完成 ===" -ForegroundColor Cyan
Write-Host "可用技能:" -ForegroundColor Yellow
openskills list

使用流程

1. 初始化配置

# 运行配置脚本
chmod +x setup-opencode-skills.sh
./setup-opencode-skills.sh

2. 日常使用

添加新技能

# 通过 OpenSkills 安装
openskills install anthropics/skills/git-release --universal

# 创建符号链接
ln -sfn "../../.agent/skills/git-release" ".opencode/skills/git-release"

# 更新权限配置
# 在 opencode.json 中添加：
# "git-release": "allow"

更新技能

# 重新安装技能
openskills install anthropics/skills/pdf --universal --force

# 同步技能信息
openskills sync

列出可用技能

# 通过 OpenSkills
openskills list

# 通过 OpenCode（在编辑器中）
# 代理会看到 <available_skills> 列表

权限管理集成

基于 OpenSkills 的权限控制

创建 .opencode/skills/permission-manager/SKILL.md：

---
name: permission-manager
description: 管理 OpenCode 技能权限，与 OpenSkills 集成
license: MIT
compatibility: opencode
metadata:
  type: permission-system
  integration: openskills
---

## 权限映射规则

将 OpenSkills 的安装路径映射到 OpenCode 权限：

### 路径 → 权限级别
1. `.agent/skills/` (--universal) → 通用权限
2. `.claude/skills/` (--project/--global) → 项目/用户权限
3. `.opencode/skills/` (符号链接) → 集成权限

### 自动权限建议
基于技能来源建议权限：
- `anthropics/skills/*` → "allow" (官方技能)
- `community/*` → "ask" (社区技能)
- `internal/*` → "deny" (内部技能，除非明确允许)

故障排除

常见问题及解决方案

Q1: 技能在 OpenCode 中不显示

检查步骤：

验证符号链接：
```
ls -la .opencode/skills/
```
检查技能格式：
```
openskills read <skill-name>
```

验证权限配置：

cat opencode.json | grep -A5 "permission"

Q2: 技能加载失败

解决方案：

重新创建符号链接：

rm .opencode/skills/<skill-name>
ln -sfn "../../.agent/skills/<skill-name>" ".opencode/skills/<skill-name>"

重新安装技能：

openskills install <source> --universal --force

Q3: 权限冲突