From a9b4251158b8e49596f7ebe09a198f8b3057d10e Mon Sep 17 00:00:00 2001 From: opencode-sync Date: Tue, 13 Oct 2026 12:38:52 +0800 Subject: [PATCH] sync: import skills/, plugins/, memory/ and shared files from origin/main --- skills/find-skills/SKILL.md | 142 ++++ skills/mmx/SKILL.md | 637 ++++++++++++++++++ skills/opencode-config/SKILL.md | 93 +++ .../opencode-config/references/01-agents.md | 163 +++++ .../opencode-config/references/02-skills.md | 199 ++++++ .../references/03-mcp-servers.md | 200 ++++++ .../references/04-custom-tools.md | 156 +++++ skills/opencode-config/references/05-tools.md | 123 ++++ 8 files changed, 1713 insertions(+) create mode 100644 skills/find-skills/SKILL.md create mode 100644 skills/mmx/SKILL.md create mode 100644 skills/opencode-config/SKILL.md create mode 100644 skills/opencode-config/references/01-agents.md create mode 100644 skills/opencode-config/references/02-skills.md create mode 100644 skills/opencode-config/references/03-mcp-servers.md create mode 100644 skills/opencode-config/references/04-custom-tools.md create mode 100644 skills/opencode-config/references/05-tools.md diff --git a/skills/find-skills/SKILL.md b/skills/find-skills/SKILL.md new file mode 100644 index 0000000..114c663 --- /dev/null +++ b/skills/find-skills/SKILL.md @@ -0,0 +1,142 @@ +--- +name: find-skills +description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill. +--- + +# Find Skills + +This skill helps you discover and install skills from the open agent skills ecosystem. + +## When to Use This Skill + +Use this skill when the user: + +- Asks "how do I do X" where X might be a common task with an existing skill +- Says "find a skill for X" or "is there a skill for X" +- Asks "can you do X" where X is a specialized capability +- Expresses interest in extending agent capabilities +- Wants to search for tools, templates, or workflows +- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.) + +## What is the Skills CLI? + +The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools. + +**Key commands:** + +- `npx skills find [query]` - Search for skills interactively or by keyword +- `npx skills add ` - Install a skill from GitHub or other sources +- `npx skills check` - Check for skill updates +- `npx skills update` - Update all installed skills + +**Browse skills at:** https://skills.sh/ + +## How to Help Users Find Skills + +### Step 1: Understand What They Need + +When a user asks for help with something, identify: + +1. The domain (e.g., React, testing, design, deployment) +2. The specific task (e.g., writing tests, creating animations, reviewing PRs) +3. Whether this is a common enough task that a skill likely exists + +### Step 2: Check the Leaderboard First + +Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options. + +For example, top skills for web development include: +- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each) +- `anthropics/skills` — Frontend design, document processing (100K+ installs) + +### Step 3: Search for Skills + +If the leaderboard doesn't cover the user's need, run the find command: + +```bash +npx skills find [query] +``` + +For example: + +- User asks "how do I make my React app faster?" → `npx skills find react performance` +- User asks "can you help me with PR reviews?" → `npx skills find pr review` +- User asks "I need to create a changelog" → `npx skills find changelog` + +### Step 4: Verify Quality Before Recommending + +**Do not recommend a skill based solely on search results.** Always verify: + +1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100. +2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors. +3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism. + +### Step 5: Present Options to the User + +When you find relevant skills, present them to the user with: + +1. The skill name and what it does +2. The install count and source +3. The install command they can run +4. A link to learn more at skills.sh + +Example response: + +``` +I found a skill that might help! The "react-best-practices" skill provides +React and Next.js performance optimization guidelines from Vercel Engineering. +(185K installs) + +To install it: +npx skills add vercel-labs/agent-skills@react-best-practices + +Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices +``` + +### Step 6: Offer to Install + +If the user wants to proceed, you can install the skill for them: + +```bash +npx skills add -g -y +``` + +The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts. + +## Common Skill Categories + +When searching, consider these common categories: + +| Category | Example Queries | +| --------------- | ---------------------------------------- | +| Web Development | react, nextjs, typescript, css, tailwind | +| Testing | testing, jest, playwright, e2e | +| DevOps | deploy, docker, kubernetes, ci-cd | +| Documentation | docs, readme, changelog, api-docs | +| Code Quality | review, lint, refactor, best-practices | +| Design | ui, ux, design-system, accessibility | +| Productivity | workflow, automation, git | + +## Tips for Effective Searches + +1. **Use specific keywords**: "react testing" is better than just "testing" +2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd" +3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills` + +## When No Skills Are Found + +If no relevant skills exist: + +1. Acknowledge that no existing skill was found +2. Offer to help with the task directly using your general capabilities +3. Suggest the user could create their own skill with `npx skills init` + +Example: + +``` +I searched for skills related to "xyz" but didn't find any matches. +I can still help you with this task directly! Would you like me to proceed? + +If this is something you do often, you could create your own skill: +npx skills init my-xyz-skill +``` diff --git a/skills/mmx/SKILL.md b/skills/mmx/SKILL.md new file mode 100644 index 0000000..2baf777 --- /dev/null +++ b/skills/mmx/SKILL.md @@ -0,0 +1,637 @@ +--- +name: mmx +description: MiniMax CLI (mmx) 技能索引。提供文本生成、语音合成、图像生成、视频生成、音乐生成、网络搜索、视觉理解等 AI 能力的命令行接口。当任务涉及 MiniMax API 调用、内容生成、或需要 AI 多模态能力时使用此技能。 +--- + +# MiniMax CLI (mmx) Skill + +MiniMax AI 多模态命令行工具，整合了 Text Generation、Speech Synthesis、Image Generation、Video Generation、Music Generation、Web Search、Vision 等能力。 + +## Global Flags + +| Flag | 说明 | +|------|------| +| `--api-key ` | API Key (覆盖其他认证方式) | +| `--region ` | API 区域: `global` (默认) / `cn` | +| `--base-url ` | API Base URL (覆盖 region) | +| `--output ` | 输出格式: `text` / `json` | +| `--quiet` | 抑制非必要输出 | +| `--verbose` | 打印 HTTP 请求/响应详情 | +| `--timeout ` | 请求超时 (默认: 300) | +| `--no-color` | 禁用 ANSI 颜色和动画 | +| `--dry-run` | 显示将要执行的操作但不实际执行 | +| `--non-interactive` | 禁用交互式提示 (CI/agent 模式) | + +## Resource Index + +### 1. auth - 认证 + +| Command | 说明 | +|---------|------| +| `auth login` | 通过 OAuth 或 API Key 认证 | +| `auth status` | 显示当前认证状态和配额快照 | +| `auth refresh` | 手动刷新 OAuth Token | +| `auth logout` | 撤销 Token 并清除存储的凭据 | + +#### auth login + +``` +mmx auth login [--api-key ] [--recommend] [--region=global|cn] +``` + +- `--api-key ` 直接保存 API Key +- `--recommend` 直接进入 OAuth (可配合 `--region=` 跳过区域选择) + +#### auth status + +``` +mmx auth status +``` + +#### auth refresh + +``` +mmx auth refresh +``` + +#### auth logout + +``` +mmx auth logout [--yes] [--dry-run] +``` + +- `--yes` 跳过确认提示 + +--- + +### 2. text - 文本生成 + +| Command | 说明 | +|---------|------| +| `text chat` | 发送聊天补全 (MiniMax Messages API) | +| `text repl` | 启动交互式多轮对话会话 | + +#### text chat + +``` +mmx text chat --message [flags] +``` + +| Flag | 说明 | 默认值 | +|------|------|--------| +| `--model ` | 模型 ID | `MiniMax-M2.7` | +| `--message ` | 消息文本 (可重复, 前缀 `role:` 设置角色) | - | +| `--messages-file ` | JSON 文件包含消息数组 (`-` 表示 stdin) | - | +| `--system ` | 系统提示词 | - | +| `--max-tokens ` | 最大生成 Token 数 | 4096 | +| `--temperature ` | 采样温度 (0.0, 1.0] | - | +| `--top-p ` | 核采样阈值 | - | +| `--stream` | 流式响应 (TTY 中默认开启) | - | +| `--tool ` | 工具定义 (可重复) | - | + +**Examples:** + +```bash +mmx text chat --message "What is MiniMax?" +mmx text chat --model MiniMax-M2.7-highspeed --system "You are a coding assistant." --message "Write fizzbuzz in Python" +cat conversation.json | mmx text chat --messages-file - --stream +``` + +#### text repl + +``` +mmx text repl [flags] +``` + +| Flag | 说明 | 默认值 | +|------|------|--------| +| `--model ` | 模型 ID | `MiniMax-M2.7` | +| `--system ` | 系统提示词 | - | +| `--max-tokens ` | 每响应最大 Token 数 | 4096 | +| `--temperature ` | 采样温度 (0.0, 1.0] | - | +| `--top-p ` | 核采样阈值 | - | + +**Examples:** + +```bash +mmx text repl +mmx text repl --model MiniMax-M2.7-highspeed --system "You are a coding assistant." +``` + +--- + +### 3. speech - 语音合成 + +| Command | 说明 | +|---------|------| +| `speech synthesize` | 同步 TTS, 最多 10k 字符 (speech-2.8-hd / 2.6 / 02) | +| `speech generate` | synthesize 的别名 | +| `speech voices` | 列出可用的系统声音 | + +#### speech synthesize + +``` +mmx speech synthesize --text [--out ] [flags] +``` + +| Flag | 说明 | 默认值 | +|------|------|--------| +| `--model ` | 模型 ID | `speech-2.8-hd` | +| `--text ` | 要合成的文本 | - | +| `--text-file ` | 从文件读取文本 (`-` 表示 stdin) | - | +| `--voice ` | 声音 ID | `English_expressive_narrator` | +| `--speed ` | 语速倍数 | - | +| `--volume ` | 音量 | - | +| `--pitch ` | 音调调整 | - | +| `--format ` | 音频格式: `mp3`, `pcm`, `flac`, `wav`, `pcmu_raw`, `pcmu_wav`, `opus` | `mp3` | +| `--sample-rate ` | 采样率 | `32000` | +| `--bitrate ` | 比特率 | `128000` | +| `--channels ` | 声道数 | `1` | +| `--language ` | 语言增强 | - | +| `--subtitles` | 包含字幕时间数据 | - | +| `--pronunciation ` | 自定义发音 (可重复) | - | +| `--out ` | 保存音频到文件 | - | +| `--stream` | 流式输出原始音频到 stdout | - | + +**Examples:** + +```bash +mmx speech synthesize --text "Hello, world!" +mmx speech synthesize --text "Hello, world!" --out hello.mp3 +echo "Breaking news." | mmx speech synthesize --text-file - --out news.mp3 +mmx speech synthesize --text "Stream" --stream | mpv --no-terminal - +``` + +#### speech voices + +``` +mmx speech voices [--language ] +``` + +| Flag | 说明 | +|------|------| +| `--language ` | 按语言过滤声音 (如 `english`, `korean`, `japanese`) | + +**Examples:** + +```bash +mmx speech voices +mmx speech voices --language english +mmx speech voices --output json +``` + +--- + +### 4. image - 图像生成 + +| Command | 说明 | +|---------|------| +| `image generate` | 生成图像 (image-01 / image-01-live) | + +#### image generate + +``` +mmx image generate --prompt [flags] +``` + +| Flag | 说明 | 默认值 | +|------|------|--------| +| `--prompt ` | 图像描述 | - | +| `--aspect-ratio ` | 宽高比 (如 `16:9`, `1:1`) | - | +| `--n ` | 生成图像数量 | `1` | +| `--seed ` | 随机种子 (相同 seed + prompt = 相同输出) | - | +| `--width ` | 自定义宽度 [512, 2048], 必须是 8 的倍数 | - | +| `--height ` | 自定义高度 [512, 2048], 必须是 8 的倍数 | - | +| `--prompt-optimizer` | 自动优化提示词 | - | +| `--aigc-watermark` | 在输出图像中嵌入 AI 生成内容水印 | - | +| `--subject-ref ` | 主体参考 (角色一致性): `type=character,image=path-or-url` | - | +| `--out ` | 保存图像到指定路径 (仅单张) | - | +| `--response-format ` | 响应格式: `url` (下载), `base64` (嵌入) | `url` | +| `--out-dir ` | 下载图像到目录 | - | +| `--out-prefix ` | 文件名前缀 | `image` | + +**Examples:** + +```bash +mmx image generate --prompt "A cat in a spacesuit on Mars" --aspect-ratio 16:9 +mmx image generate --prompt "Logo design" --n 3 --out-dir ./generated/ +mmx image generate --prompt "Mountain landscape" --quiet +mmx image generate --prompt "A castle" --seed 42 +mmx image generate --prompt "Wide landscape" --width 1920 --height 1080 +mmx image generate --prompt "sunset" --prompt-optimizer --aigc-watermark +mmx image generate --prompt "A cat" --out /tmp/cat.jpg +mmx image generate --prompt "A cat" --response-format base64 +``` + +--- + +### 5. video - 视频生成 + +| Command | 说明 | +|---------|------| +| `video generate` | 生成视频 (T2V/I2V/SEF/S2V) | +| `video task get` | 查询视频任务状态 | +| `video download` | 通过 File ID 下载完成的视频 | + +#### video generate + +``` +mmx video generate --prompt [flags] +``` + +| Flag | 说明 | +|------|------| +| `--model ` | 模型: T2V 用 `MiniMax-Hailuo-2.3`; I2V 用 `MiniMax-Hailuo-2.3` (默认) 或 `MiniMax-Hailuo-2.3-Fast` (需要 `--first-frame`); 有 `--last-frame` 切换到 `Hailuo-02`; 有 `--subject-image` 切换到 `S2V-01` | +| `--prompt ` | 视频描述 | +| `--first-frame ` | 首帧图像 (本地路径或 URL) | +| `--last-frame ` | 末帧图像 (需要 `--first-frame`, 启用 SEF 模式) | +| `--subject-image ` | 主体参考图像 (角色一致性) | +| `--callback-url ` | 完成通知的 Webhook URL | +| `--download ` | 完成后保存视频到文件 | +| `--no-wait` / `--async` | 立即返回任务 ID，不等待 | +| `--poll-interval ` | 轮询间隔 (默认: 5) | + +**Video Modes:** + +| Mode | 说明 | 模型 | +|------|------|------| +| T2V | 文本转视频 | Hailuo-2.3 | +| I2V | 图像转视频 | Hailuo-2.3 (默认) / Hailuo-2.3-Fast | +| SEF | 首尾帧插值 | Hailuo-02 | +| S2V | 主体一致性视频 | S2V-01 | + +**Examples:** + +```bash +mmx video generate --prompt "A man reads a book. Static shot." +mmx video generate --prompt "Ocean waves at sunset." --download sunset.mp4 +mmx video generate --prompt "A robot painting." --async --quiet +mmx video generate --prompt "Walk forward" --first-frame start.jpg --last-frame end.jpg +mmx video generate --prompt "A detective walking" --subject-image character.jpg +``` + +#### video task get + +``` +mmx video task get --task-id +``` + +| Flag | 说明 | +|------|------| +| `--task-id ` | 视频生成任务 ID | + +**Examples:** + +```bash +mmx video task get --task-id 106916112212032 +mmx video task get --task-id 106916112212032 --output json +``` + +#### video download + +``` +mmx video download --file-id --out +``` + +| Flag | 说明 | +|------|------| +| `--file-id ` | 要下载的文件 ID | +| `--out ` | 输出文件路径 | + +**Examples:** + +```bash +mmx video download --file-id 176844028768320 --out video.mp4 +``` + +--- + +### 6. music - 音乐生成 + +| Command | 说明 | +|---------|------| +| `music generate` | 生成歌曲 (music-2.6 / music-2.5+ / music-2.5) | +| `music cover` | 基于参考音频生成歌曲的翻唱版本 (music-cover) | + +#### music generate + +``` +mmx music generate --prompt (--lyrics | --instrumental | --lyrics-optimizer) [--out ] [flags] +``` + +| Flag | 说明 | 默认值 | +|------|------|--------| +| `--prompt ` | 音乐风格描述 (最多 2000 字符) | - | +| `--lyrics ` | 带结构标签的歌词 | - | +| `--lyrics-file ` | 从文件读取歌词 (`-` 表示 stdin) | - | +| `--lyrics-optimizer` | 从 prompt 自动生成歌词 (不能与 `--lyrics` 或 `--instrumental` 共用) | - | +| `--instrumental` | 生成器乐音乐 | - | +| `--vocals ` | 人声风格, 如 "warm male baritone" | - | +| `--genre ` | 音乐流派, 如 folk, pop, jazz, electronic | - | +| `--mood ` | 情绪, 如 warm, melancholic, uplifting | - | +| `--instruments ` | 要突出的乐器 | - | +| `--tempo ` | 节奏描述, 如 fast, slow, moderate | - | +| `--bpm ` | 精确 BPM | - | +| `--key ` | 调性, 如 C major, A minor | - | +| `--avoid ` | 要避免的元素 | - | +| `--use-case ` | 使用场景, 如 "background music for video" | - | +| `--structure ` | 歌曲结构 | - | +| `--references ` | 参考曲目或艺术家 | - | +| `--extra ` | 额外细化需求 | - | +| `--model ` | 模型: `music-2.6` (默认), `music-2.5+`, `music-2.5` | `music-2.6` | +| `--output-format ` | 返回格式: `hex` (默认, 保存到文件) 或 `url` (24h 过期) | `hex` | +| `--aigc-watermark` | 嵌入 AI 生成内容水印 | - | +| `--format ` | 音频格式: `mp3`, `wav`, `pcm` | `mp3` | +| `--sample-rate ` | 采样率 | `44100` | +| `--bitrate ` | 比特率 | `256000` | +| `--stream` | 流式输出原始音频到 stdout | - | +| `--out ` | 保存音频到文件 | - | + +**Lyrics 结构标签:** + +`[Intro]`, `[Verse]`, `[Pre Chorus]`, `[Chorus]`, `[Interlude]`, `[Bridge]`, `[Outro]`, `[Post Chorus]`, `[Transition]`, `[Break]`, `[Hook]`, `[Build Up]`, `[Inst]`, `[Solo]` + +**Examples:** + +```bash +mmx music generate --prompt "Upbeat pop" --lyrics "La la la..." --out summer.mp3 +mmx music generate --prompt "Indie folk, melancholic" --lyrics-file song.txt --out my_song.mp3 +mmx music generate --prompt "Upbeat pop about summer" --lyrics-optimizer --out summer.mp3 +mmx music generate --prompt "Cinematic orchestral, building tension" --instrumental --out bgm.mp3 +mmx music generate --prompt "Upbeat pop" --lyrics "La la la..." --output-format url +mmx music generate --prompt "Warm morning folk" --vocals "male and female duet, harmonies in chorus" --instruments "acoustic guitar, piano" --bpm 95 --out duet.mp3 +``` + +#### music cover + +``` +mmx music cover --prompt (--audio | --audio-file ) [--lyrics ] [--out ] [flags] +``` + +| Flag | 说明 | 默认值 | +|------|------|--------| +| `--model ` | 模型: `music-cover` (默认) | `music-cover` | +| `--prompt ` | 目标翻唱风格, 如 "Indie folk, acoustic guitar, warm male vocal" | - | +| `--audio ` | 参考音频 URL (mp3/wav/flac, 6s-6min, 最大 50MB) | - | +| `--audio-file ` | 本地参考音频文件 (自动 Base64 编码) | - | +| `--lyrics ` | 翻唱歌词 (省略则通过 ASR 从参考音频提取) | - | +| `--lyrics-file ` | 从文件读取歌词 (`-` 表示 stdin) | - | +| `--seed ` | 随机种子 0-1000000 | - | +| `--format ` | 音频格式: `mp3`, `wav`, `pcm` | `mp3` | +| `--sample-rate ` | 采样率 | `44100` | +| `--bitrate ` | 比特率 | `256000` | +| `--channel ` | 声道: `1` (单声道) / `2` (立体声, 默认) | `2` | +| `--stream` | 流式输出原始音频到 stdout | - | +| `--out ` | 保存音频到文件 | - | + +**Examples:** + +```bash +mmx music cover --prompt "Indie folk, acoustic guitar, warm male vocal" --audio https://example.com/song.mp3 --out cover.mp3 +mmx music cover --prompt "Jazz, piano, slow" --audio-file original.mp3 --lyrics-file lyrics.txt --out jazz_cover.mp3 +mmx music cover --prompt "Pop, upbeat" --audio https://example.com/ref.mp3 --seed 42 --out reproducible.mp3 +``` + +--- + +### 7. search - 网络搜索 + +| Command | 说明 | +|---------|------| +| `search query` | 通过 MiniMax 搜索网页 | +| `search web` | `search query` 的别名 | + +#### search query + +``` +mmx search query --q +``` + +| Flag | 说明 | +|------|------| +| `--q ` | 搜索查询字符串 | + +**Examples:** + +```bash +mmx search query --q "MiniMax AI" +mmx search query --q "latest news" --output json +``` + +--- + +### 8. vision - 视觉理解 + +| Command | 说明 | +|---------|------| +| `vision describe` | 使用 MiniMax VLM 描述图像 | + +#### vision describe + +``` +mmx vision describe (--image | --file-id ) [--prompt ] +``` + +| Flag | 说明 | 默认值 | +|------|------|--------| +| `--image ` | 本地图像路径或 URL (自动 Base64 编码) | - | +| `--file-id ` | 预上传的文件 ID (跳过 Base64 转换) | - | +| `--prompt ` | 关于图像的问题 | `"Describe the image."` | + +**Examples:** + +```bash +mmx vision describe --image photo.jpg +mmx vision describe --image https://example.com/photo.jpg --prompt "What breed is this dog?" +mmx vision describe --file-id file-123456789 --prompt "Extract the text" +``` + +--- + +### 9. quota - 使用配额 + +| Command | 说明 | +|---------|------| +| `quota show` | 显示 Token Plan 使用情况和剩余配额 | + +#### quota show + +``` +mmx quota show +``` + +**Examples:** + +```bash +mmx quota show +mmx quota show --output json +``` + +--- + +### 10. config - CLI 配置 + +| Command | 说明 | +|---------|------| +| `config show` | 显示当前配置 | +| `config set` | 设置配置值 | +| `config export-schema` | 导出 CLI 命令为 Anthropic/OpenAI 兼容的 JSON 工具模式 | + +#### config show + +``` +mmx config show +``` + +**Examples:** + +```bash +mmx config show +mmx config show --output json +``` + +#### config set + +``` +mmx config set --key --value +``` + +| Flag | 说明 | +|------|------| +| `--key ` | 配置键: `region`, `base_url`, `output`, `timeout`, `api_key`, `proxy`, `default_text_model`, `default_speech_model`, `default_video_model`, `default_music_model` | +| `--value ` | 要设置的值 | + +**Examples:** + +```bash +mmx config set --key output --value json +mmx config set --key timeout --value 600 +mmx config set --key proxy --value http://127.0.0.1:7890 +mmx config set --key base_url --value https://api-uw.minimax.io +``` + +#### config export-schema + +``` +mmx config export-schema [--command ""] +``` + +| Flag | 说明 | +|------|------| +| `--command ` | 仅导出特定命令的模式 (如 `video generate`) | + +**Examples:** + +```bash +mmx config export-schema +mmx config export-schema --command "video generate" +``` + +--- + +### 11. file - 文件存储 + +| Command | 说明 | +|---------|------| +| `file upload` | 上传文件到 MiniMax 存储 | +| `file list` | 列出已上传的文件 | +| `file delete` | 删除已上传的文件 | + +#### file upload + +``` +mmx file upload --file [--purpose ] +``` + +| Flag | 说明 | 默认值 | +|------|------|--------| +| `--file ` | 文件的本地路径 | - | +| `--purpose ` | 文件用途 (默认: `retrieval`) | `retrieval` | + +**Examples:** + +```bash +mmx file upload --file doc.pdf +mmx file upload --file image.png --purpose vision +``` + +#### file list + +``` +mmx file list +``` + +**Examples:** + +```bash +mmx file list +mmx file list --output json +``` + +#### file delete + +``` +mmx file delete --file-id +``` + +| Flag | 说明 | +|------|------| +| `--file-id ` | 要删除的文件 ID | + +**Examples:** + +```bash +mmx file delete --file-id 123456789 +``` + +--- + +### 12. update - 更新 + +``` +mmx update +``` + +更新 mmx 到最新版本。 + +--- + +## Quick Reference + +```bash +# 认证 +mmx auth login --api-key sk-cp-xxxxx +mmx auth status + +# 文本生成 +mmx text chat --message "Hello" + +# 语音合成 +mmx speech synthesize --text "Hello" --out hello.mp3 + +# 图像生成 +mmx image generate --prompt "A sunset" --aspect-ratio 16:9 + +# 视频生成 +mmx video generate --prompt "A man walking" --async --quiet + +# 音乐生成 +mmx music generate --prompt "Upbeat pop" --lyrics "La la" --out song.mp3 + +# 网络搜索 +mmx search query --q "MiniMax" + +# 视觉理解 +mmx vision describe --image photo.jpg + +# 查看配额 +mmx quota show +``` + +## API Reference + +- Text: https://platform.minimaxi.com/docs/api-reference/text-post +- Speech: https://platform.minimaxi.com/docs/api-reference/speech-t2a-http +- Image: https://platform.minimaxi.com/docs/api-reference/image-generation-t2i +- Video: https://platform.minimaxi.com/docs/api-reference/video-generation +- Music: https://platform.minimaxi.com/docs/api-reference/music-generation \ No newline at end of file diff --git a/skills/opencode-config/SKILL.md b/skills/opencode-config/SKILL.md new file mode 100644 index 0000000..f9685cf --- /dev/null +++ b/skills/opencode-config/SKILL.md @@ -0,0 +1,93 @@ +--- +name: opencode-config +description: 配置 opencode 自身 (agents / skills / MCP servers / custom tools / 内置工具权限) 的工作流与速查。基于 opencode 官方中文文档 (agents、skills、mcp-servers、custom-tools、tools 五篇)。Use ONLY when 用户要创建/修改 opencode.json、子代理文件、SKILL.md、MCP server 配置、.opencode/tools/ 自定义工具、或调整工具权限策略;不用于改业务代码或运行应用。 +license: MIT +compatibility: opencode +metadata: + audience: opencode maintainers + scope: opencode-self-config + source: https://opencode.ai/docs/zh-cn/ +--- + +# opencode-config + +opencode 自身配置的**导航 + 摘要** skill。详细字段/示例/边界场景放 `references/`,按需加载,避免主文件膨胀。 + +## 何时加载我 + +- 用户说"加个子代理 / 改 opencode.json / 配置 MCP / 写个自定义工具 / 调权限" +- 用户要求排查"skill 没显示 / MCP 连不上 / 自定义工具不生效" +- 用户给 opencode 官方文档链接,要求落地 + +> 反向场景 (不要加载): 改 RuoYi 业务、跑 `mvn install`、查 MySQL、调小程序 — 这些走 `ruoyi-cs-platform` / `dba` 子代理。 + +## 文件位置约定 (本仓库) + +| 类别 | 路径 | 备注 | +|---|---|---| +| 主配置 | `opencode.json` 或 `opencode.jsonc` | 必须含 `"$schema": "https://opencode.ai/config.json"` | +| 子代理 (文件) | `.opencode/agent/.md` 或 `.opencode/agents/.md` | 文件名即 agent 名 | +| 技能 | `.opencode/skill//SKILL.md` | frontmatter `name` 与目录名一致 | +| 技能 (外部) | `.agents/skills//SKILL.md` | 兼容 Claude 风格 | +| MCP | 写在 `opencode.json` 的 `mcp.` | 不用单独文件 | +| 自定义工具 | `.opencode/tools/.ts` | 文件名即工具名,`@opencode-ai/plugin` 的 `tool()` | +| 插件 | `.opencode/plugin/*.ts` 或 `opencode.json` 的 `plugin` 数组 | TS 文件自动发现 | + +> 配置**只读一次**,改完任何 opencode 配置文件都需告诉用户**退出并重启 opencode** 才生效。 + +## 5 篇官方文档 → 5 个子文件 (按需 `read` 加载) + +| 子文件 | 对应官方页 | 涵盖内容 | +|---|---|---| +| `references/01-agents.md` | [agents](https://opencode.ai/docs/zh-cn/agents/) | 主/子代理、内置代理 (build/plan/general/explore/scout)、JSON vs Markdown 配置、description/temperature/steps/prompt/model/tools/permission/mode/hidden/task/color/top_p、文档/安全审计样例 | +| `references/02-skills.md` | [skills](https://opencode.ai/docs/zh-cn/skills/) | SKILL.md frontmatter (`name`/`description` 必填)、name 正则 `^[a-z0-9]+(-[a-z0-9]+)*$`、description 1-1024 字符、发现路径、glob 通配符权限、agent 级 skill 权限覆盖、禁用 skill 工具、加载问题排查 | +| `references/03-mcp-servers.md` | [mcp-servers](https://opencode.ai/docs/zh-cn/mcp-servers/) | `mcp` 段结构、local (`type:"local"`, `command` 数组, `environment`) / remote (`type:"remote"`, `url`, `headers`) / OAuth (auto/preregister/manual)、`enabled: false` 临时禁用、按 agent 控制 MCP 工具 (`mymcp_*` glob)、Context7/Sentry/gh_grep 示例 | +| `references/04-custom-tools.md` | [custom-tools](https://opencode.ai/docs/zh-cn/custom-tools/) | `.opencode/tools/*.ts`、`tool()` 辅助函数 + Zod (`tool.schema`)、多导出命名 `_`、context (agent/sessionID/messageID/directory/worktree)、与内置工具同名时覆盖、Python 等非 TS 实现 | +| `references/05-tools.md` | [tools](https://opencode.ai/docs/zh-cn/tools/) | 12 个内置工具清单:bash/edit/write/read/grep/glob/lsp/patch/skill/todowrite/webfetch/websearch/question,以及 `permission` 字段 (`allow`/`ask`/`deny`)、glob 通配符、`.ignore` 文件覆盖 `.gitignore` | + +> 加载方式: 用 `read` 工具读 `references/0X-xxx.md` 的完整内容。主文件只保留"我要做 X,先读哪个引用"的导航。 + +## 速查决策树 + +``` +用户想… +├─ 加子代理 ──────────→ references/01-agents.md §"Markdown 形式" +│ 落地: .opencode/agent/.md (frontmatter + prompt) +├─ 改 opencode.json ──→ 对应类别的 references/ + 校验 $schema +├─ 加 skill ──────────→ references/02-skills.md §"编写 frontmatter" +│ 落地: .opencode/skill//SKILL.md (主文件) + 视情况 references/ scripts/ templates/ +├─ 加 MCP server ─────→ references/03-mcp-servers.md §"本地/远程/OAuth" +│ 落地: opencode.json 的 mcp. +├─ 写自定义工具 ─────→ references/04-custom-tools.md §"结构/参数/上下文" +│ 落地: .opencode/tools/.ts (import { tool } from "@opencode-ai/plugin") +├─ 调工具权限 ───────→ references/05-tools.md §"配置" + references/01 §"权限" +│ 落地: opencode.json 的 permission 段 +└─ 排查加载问题 ─────→ references/02 §"排查加载问题" / references/03 §"OAuth 调试" / references/05 §"忽略模式" +``` + +## 硬约束 (违反 opencode 拒启 / 静默失败) + +1. **JSON Schema**: `opencode.json` 顶部必须 `"$schema": "https://opencode.ai/config.json"`,未知顶层键 `ConfigInvalidError`。 +2. **SKILL.md frontmatter**: `name` 必填 + 1-64 字符 + 小写连字符正则;`description` 必填 + 1-1024 字符。无 description 的 skill **从模型视野过滤掉**,不报错也不出现。 +3. **MCP `command`** 是字符串数组,不是单个字符串;`type: local|remote` 必填。 +4. **`mcp[name].disabled` 静默**: 想要临时关 → `enabled: false`;彻底删 → 从 `mcp` 段移除。 +5. **Skill 权限拒绝后**: 代理在 `` 里**看不到**该 skill,会安静地以为不存在。 +6. **MCP 工具 glob**: 禁用某 server 全部工具用 `"_*": false`,因为工具注册时带 server 前缀。 +7. **`todowrite` 默认对子代理禁用**: 要用就 `agent..tools.todowrite: true`。 +8. **LSP 工具**: 需 `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` (或 `OPENCODE_EXPERIMENTAL=true`)。 +9. **websearch 工具**: 需 OpenCode 提供商,或 `OPENCODE_ENABLE_EXA=1|true`。 +10. **配置热重载**: 不支持 — 改完**必须**告诉用户退出重启 opencode。 + +## 写配置的标准动作 + +1. **读对应 references/ 子文件** 拿到字段/示例/边界。 +2. **校验字段** — 不确定就 `webfetch https://opencode.ai/config.json` 看 schema。 +3. **保留用户原有字段** — 只动用户明确指出的部分,别顺手改 model/username/keys。 +4. **加 `$schema`** — 帮编辑器即时校验。 +5. **写完后** — 输出"修改清单 + 提醒用户退出重启 opencode"。 + +## 相关 skill (本仓库已存在) + +- `ruoyi-cs-platform` — 业务入口 skill,改 RuoYi 代码前必读 +- `customize-opencode` (内置) — opencode 自身配置速查,与本 skill 互补但**本 skill 更细、含子文件分页** +- `.qwen/skills/*` — 历史 Qwen 风格 skill,与 `.opencode/skill/*` 并存,迁移时按需搬运 diff --git a/skills/opencode-config/references/01-agents.md b/skills/opencode-config/references/01-agents.md new file mode 100644 index 0000000..c4519f3 --- /dev/null +++ b/skills/opencode-config/references/01-agents.md @@ -0,0 +1,163 @@ +# 01 — Agents (代理) + +> 源: +> 适用: 创建/修改 opencode 子代理 (`.opencode/agent/*.md`) 或 `opencode.json` 的 `agent` 段 + +## 类型 + +- **主代理 (primary)**: 用户直接交互,Tab 切换;默认 Build (全工具) + Plan (只读/ask) +- **子代理 (subagent)**: 主代理自动调用,或用户 `@` 提及 + +## 内置代理清单 + +| 名称 | 模式 | 用途 | 工具 | +|---|---|---|---| +| `build` | primary | 默认开发 | 全开 | +| `plan` | primary | 规划/分析 (不写) | edit/bash = ask | +| `general` | subagent | 通用多步任务 | 几乎全开 (无 todowrite) | +| `explore` | subagent | 代码库搜索 | **只读** | +| `scout` | subagent | 外部库/upstream 对比 | 只读 + 克隆到缓存 | +| `compaction` / `title` / `summary` | primary (隐藏) | 系统内部 | — | + +> 自定义代理可覆盖内置:`agent: { build: { ... } }` 或 `agent/build.md`。 + +## 两种配置形式 + +**JSON 形式** (`opencode.json`): + +```json +{ + "$schema": "https://opencode.ai/config.json", + "agent": { + "review": { + "description": "Reviews code for best practices", + "mode": "subagent", + "model": "anthropic/claude-sonnet-4-6", + "tools": { "write": false, "edit": false, "bash": false }, + "prompt": "{file:./prompts/review.txt}" + } + } +} +``` + +**Markdown 形式** (推荐,本仓库使用) — `.opencode/agent/.md` 或 `.opencode/agents/.md`: + +```markdown +--- +description: Reviews code for quality and best practices +mode: subagent +model: anthropic/claude-sonnet-4-6 +temperature: 0.1 +tools: + write: false + edit: false + bash: false +--- +You are in code review mode. Focus on: +- Code quality and best practices +- Potential bugs and edge cases +- Performance implications +- Security considerations +``` + +> **文件名即代理名**: `review.md` → `review`。`prompt` 写在 frontmatter 还是 body 选一个,别两处都写。 + +## Frontmatter 全字段 + +| 字段 | 必填 | 类型 | 说明 | +|---|---|---|---| +| `name` | 是 (内联必填,文件可选) | string | 代理名 | +| `description` | 是 | string | **必需**,决定自动调用时机 | +| `mode` | 否 | `primary` \| `subagent` \| `all` | 默认 `all` | +| `model` | 否 | `provider/model-id` | 子代理默认继承主代理模型 | +| `prompt` | 否 | string / `{file:...}` | 系统提示词;路径相对**配置文件**所在目录 | +| `temperature` | 否 | 0.0-1.0 | 0=确定, 0.55=Qwen 默认, 0.7=创意 | +| `top_p` | 否 | 0.0-1.0 | 温度的替代 | +| `steps` | 否 | int | 最大迭代步数 (旧 `maxSteps` 弃用) | +| `tools` | 否 | object | `{ "": bool }` 或 glob `"mymcp_*": false` | +| `permission` | 否 | object | 覆盖全局权限 (见 02-skills / 05-tools) | +| `mode` | 否 | string | — | +| `hidden` | 否 | bool | `true` 时从 `@` 补全菜单隐藏 (仅 subagent) | +| `color` | 否 | `#RRGGBB` \| 主题色 | UI 颜色: `primary`/`secondary`/`accent`/`success`/`warning`/`error`/`info` | +| `disable` | 否 | bool | `true` 禁用 | +| `steps` | 否 | int | — | +| `options` | 否 | object | 其他键进 options,透传到模型 (如 `reasoningEffort: "high"`) | +| `variant` | 否 | string | — | + +> 未知 top-level 字段 → 静默进 `options` (透传模型)。**不是**抛错。 + +## 权限 (重点) + +支持值: `"allow"` / `"ask"` / `"deny"`。 + +**Glob 规则 — 最后匹配优先**: + +```yaml +permission: + bash: + "*": ask # 兜底 + "git status *": allow # 放行具体 +``` + +**`permission.task` 控制子代理能调谁**: + +```yaml +permission: + task: + "*": deny + "orchestrator-*": allow + "code-reviewer": ask +``` + +> `deny` 时,该子代理**从 Task 工具描述中完全移除**,模型看不到它。用户**仍能**用 `@` 直接调。 + +## 创建代理的官方命令 + +```bash +opencode agent create # 交互式: 位置/描述/工具/生成 +``` + +## 实战示例 (照搬官方) + +**文档代理** (`~/.config/opencode/agents/docs-writer.md`): + +```markdown +--- +description: Writes and maintains project documentation +mode: subagent +tools: + bash: false +--- +You are a technical writer. Create clear, comprehensive documentation. +``` + +**安全审计代理** (`~/.config/opencode/agents/security-auditor.md`): + +```markdown +--- +description: Performs security audits and identifies vulnerabilities +mode: subagent +tools: + write: false + edit: false +--- +You are a security expert. Focus on: +- Input validation vulnerabilities +- Authentication and authorization flaws +- Data exposure risks +- Dependency vulnerabilities +- Configuration security issues +``` + +## 本仓库现状 + +- `.opencode/agents/dba.md` — 已存在的 DBA 子代理 (本项目自定义) +- `~/.config/opencode/agent/*` — 全局子代理位置 + +## 验证清单 (改完跑一遍) + +1. frontmatter `description` 非空,`mode` 正确。 +2. 工具权限: 不需要的都 `false`,尤其 `bash` / `edit` / `write`。 +3. 全局权限 vs 代理权限: 子代理用 `permission:` 块覆盖。 +4. **退出并重启 opencode**。 +5. 在 UI 用 `@` 试调,或主代理根据 description 自动触发。 diff --git a/skills/opencode-config/references/02-skills.md b/skills/opencode-config/references/02-skills.md new file mode 100644 index 0000000..6f96ed0 --- /dev/null +++ b/skills/opencode-config/references/02-skills.md @@ -0,0 +1,199 @@ +# 02 — Skills (代理技能) + +> 源: +> 适用: 创建/修改 `SKILL.md` (`.opencode/skill//SKILL.md`) + +## 放置文件 (发现路径) + +OpenCode 递归扫描以下位置找 `**/SKILL.md`: + +| 范围 | 路径 | +|---|---| +| 项目 opencode | `.opencode/skills//SKILL.md` | +| 全局 opencode | `~/.config/opencode/skills//SKILL.md` | +| 项目 Claude 兼容 | `.claude/skills//SKILL.md` | +| 全局 Claude 兼容 | `~/.claude/skills//SKILL.md` | +| 项目 agents 兼容 | `.agents/skills//SKILL.md` | +| 全局 agents 兼容 | `~/.agents/skills//SKILL.md` | + +> 项目本地路径: opencode 从当前工作目录**向上**遍历到 git worktree 根,沿途全加载。 + +> 本仓库主要用 `.opencode/skill/` (opencode 风格),同时保留 `.qwen/skills/` / `.agents/skills/` (历史) — 三者并存不冲突。 + +## Frontmatter 字段 + +**只识别**以下字段,其它一律忽略: + +| 字段 | 必填 | 说明 | +|---|---|---| +| `name` | ✅ | 1-64 字符,正则 `^[a-z0-9]+(-[a-z0-9]+)*$`,**必须与目录名一致** | +| `description` | ✅ | 1-1024 字符,**决定何时被加载** | +| `license` | ❌ | 字符串 | +| `compatibility` | ❌ | 字符串 | +| `metadata` | ❌ | string→string 映射 | + +> 缺 `description` → **静默过滤掉**,不会报错也不会出现在 ``。 + +## Name 验证规则 (硬) + +``` +^[a-z0-9]+(-[a-z0-9]+)*$ +``` + +- 1-64 字符 +- 仅小写字母和数字,单个连字符分隔 +- 不以 `-` 开头或结尾 +- 不含连续 `--` +- **与目录名一致** + +## Description 写法 (触发匹配关键) + +- 第三人称 "Use when..." / "Use ONLY when..." +- **前置** 关键词/文件名 (用户原话里常出现的字) +- 1-1024 字符,具体到能区分相邻话题 +- "Use ONLY when..." 收窄误触 + +**正面**: + +```yaml +description: Configures opencode itself (agents/skills/MCP/custom tools/permissions). Use ONLY when user creates/modifies opencode.json, agent files, SKILL.md, MCP server config, .opencode/tools/, or tool permission policies. +``` + +**反面** (太泛): + +```yaml +description: Helps with development +``` + +## 工具描述 (模型看到什么) + +`` 列出每个 skill 的 `name` + `description`: + +```xml + + + git-release + Create consistent releases and changelogs + + +``` + +模型用 `skill({ name: "git-release" })` 加载。 + +## 权限配置 + +**全局** (`opencode.json`): + +```json +{ + "permission": { + "skill": { + "*": "allow", + "pr-review": "allow", + "internal-*": "deny", + "experimental-*": "ask" + } + } +} +``` + +| 行为 | 效果 | +|---|---| +| `allow` | 立即加载 | +| `deny` | 对代理**隐藏**,拒绝访问 (模型看不到) | +| `ask` | 加载前弹确认 | + +**按代理覆盖**: + +```yaml +# 自定义代理 frontmatter +--- +permission: + skill: + "documents-*": allow +--- +``` + +```json +// 内置代理 opencode.json +{ + "agent": { + "plan": { + "permission": { "skill": { "internal-*": "allow" } } + } + } +} +``` + +**禁用 skill 工具** (代理完全用不了): + +```yaml +# 自定义代理 +--- +tools: + skill: false +--- +``` + +```json +// 内置代理 +{ "agent": { "plan": { "tools": { "skill": false } } } } +``` + +## 排查加载问题 (按顺序) + +1. 文件名**全大写** `SKILL.md` (不是 `skill.md` / `SKILL.MD`) +2. frontmatter 含 `name` + `description` +3. `name` 在**所有路径里唯一** (项目 + 全局) +4. 权限: 被 `deny` 会静默消失 +5. 退出并重启 opencode (配置不热重载) + +## 文件组织 (大内容用子文件) + +> 本 skill 的约定: 主 SKILL.md 保持导航/速查,详细文档放 `references/`/`scripts/`/`templates/`。 + +``` +.opencode/skill/ +└── my-skill/ + ├── SKILL.md # 必填, 主体 (导航+摘要) + ├── references/ # 可选, 详细文档 + │ ├── 01-xxx.md + │ └── 02-xxx.md + ├── scripts/ # 可选, 工具脚本 + └── templates/ # 可选, 模板 +``` + +> 加载方式: 主 SKILL.md 里用一句话导航,如"详细见 `references/01-xxx.md`",模型用 `read` 工具按需取。 + +## 官方示例 (照搬) + +`.opencode/skills/git-release/SKILL.md`: + +```markdown +--- +name: git-release +description: Create consistent releases and changelogs +license: MIT +compatibility: opencode +metadata: + audience: maintainers + workflow: github +--- +## What I do +- Draft release notes from merged PRs +- Propose a version bump +- Provide a copy-pasteable `gh release create` command + +## When to use me +Use this when you are preparing a tagged release. +Ask clarifying questions if the target versioning scheme is unclear. +``` + +## 验证清单 (改完跑一遍) + +1. `name` 与目录名一致,通过正则。 +2. `description` 1-1024 字符,前置关键词。 +3. 文件名 `SKILL.md` 全大写。 +4. 退出重启 opencode。 +5. 主代理在 UI 输入与 description 相关的请求,看 `` 是否列出。 +6. 主代理调 `skill({ name: "..." })` 验证内容能加载。 diff --git a/skills/opencode-config/references/03-mcp-servers.md b/skills/opencode-config/references/03-mcp-servers.md new file mode 100644 index 0000000..b12dd4c --- /dev/null +++ b/skills/opencode-config/references/03-mcp-servers.md @@ -0,0 +1,200 @@ +# 03 — MCP Servers (Model Context Protocol) + +> 源: +> 适用: 在 `opencode.json` 的 `mcp` 段加本地/远程 MCP server,加 OAuth 配置,按代理管控 + +## 顶层结构 + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "": { + "type": "local" | "remote", + "enabled": true, + // local 还需 command + 可选 environment + // remote 还需 url + 可选 headers/oauth + "timeout": 5000 + } + } +} +``` + +> `enabled: false` 临时禁用 (配置保留)。彻底删 → 从 `mcp` 段移除。 + +> **上下文成本警告**: MCP 工具进 LLM 上下文,大量启用易爆上下文。Sentry / GitHub MCP 特别吃 token。 + +## 本地 (`type: "local"`) + +```json +{ + "mcp": { + "playwright": { + "type": "local", + "command": ["npx", "-y", "@playwright/mcp"], + "enabled": true, + "environment": { "BROWSER": "chromium" } + } + } +} +``` + +| 字段 | 必填 | 说明 | +|---|---|---| +| `type` | ✅ | 必须 `"local"` | +| `command` | ✅ | **字符串数组**,不是单个字符串 | +| `environment` | ❌ | object, 启动时设置环境变量 | +| `enabled` | ❌ | 启动时启用/禁用 | +| `timeout` | ❌ | ms, 默认 5000 | + +## 远程 (`type: "remote"`) + +```json +{ + "mcp": { + "my-remote-mcp": { + "type": "remote", + "url": "https://my-mcp-server.com", + "enabled": true, + "headers": { "Authorization": "Bearer MY_API_KEY" } + } + } +} +``` + +| 字段 | 必填 | 说明 | +|---|---|---| +| `type` | ✅ | 必须 `"remote"` | +| `url` | ✅ | 远程 MCP server 地址 | +| `enabled` | ❌ | — | +| `headers` | ❌ | object, 随请求发 | +| `oauth` | ❌ | object \| `false` | +| `timeout` | ❌ | ms, 默认 5000 | + +## OAuth + +**自动**: 远程 server 触发 401 → opencode 自动走 OAuth 流程 (支持 RFC 7591 动态注册)。Token 存 `~/.local/share/opencode/mcp-auth.json`。 + +**预注册** (已有 client 凭据): + +```json +{ + "mcp": { + "my-oauth-server": { + "type": "remote", + "url": "https://mcp.example.com/mcp", + "oauth": { + "clientId": "{env:MY_MCP_CLIENT_ID}", + "clientSecret": "{env:MY_MCP_CLIENT_SECRET}", + "scope": "tools:read tools:execute" + } + } + } +} +``` + +**禁用自动 OAuth** (用 API key 替代): + +```json +{ + "mcp": { + "my-api-key-server": { + "type": "remote", + "url": "https://mcp.example.com/mcp", + "oauth": false, + "headers": { "Authorization": "Bearer {env:MY_API_KEY}" } + } + } +} +``` + +**手动命令**: + +```bash +opencode mcp auth # 触发 OAuth (开浏览器) +opencode mcp auth list # 列出所有支持 OAuth 的状态 +opencode mcp list # 列出所有 MCP server + 状态 +opencode mcp logout # 删凭据 +opencode mcp debug # 调试: 状态/HTTP/OAuth 发现 +``` + +## 按代理管控 (MCP 工具) + +MCP 工具注册时**带 server 前缀** (`_`)。要用 `tools._*` glob: + +**全局禁用,只在特定代理开**: + +```json +{ + "mcp": { + "my-mcp": { + "type": "local", + "command": ["bun", "x", "my-mcp-command"], + "enabled": true + } + }, + "tools": { "my-mcp*": false }, + "agent": { + "my-agent": { "tools": { "my-mcp*": true } } + } +} +``` + +**Glob 规则**: `*` 零或多字符,`?` 恰好一个字符,其它字面值。 + +## 覆盖组织远程默认 + +组织可在 `.well-known/opencode` 端点发默认 MCP server,可能默认禁用。启用方法: 在本地配置**加同名字段** + `enabled: true`。 + +## 官方示例 (照搬) + +**Sentry**: + +```json +{ "mcp": { "sentry": { "type": "remote", "url": "https://mcp.sentry.dev/mcp", "oauth": {} } } } +``` + +→ `opencode mcp auth sentry` → 浏览器 OAuth。 + +**Context7** (查文档): + +```json +{ "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp" } } } +``` + +带 API key 提高速率: + +```json +{ + "mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" } + } + } +} +``` + +提示: `use context7` 让代理用。也可在 AGENTS.md 写: + +```markdown +When you need to search docs, use `context7` tools. +``` + +**Grep by Vercel** (搜 GitHub 代码): + +```json +{ "mcp": { "gh_grep": { "type": "remote", "url": "https://mcp.grep.app" } } } +``` + +→ 提示: `use the gh_grep tool`。 + +## 验证清单 + +1. `type: local|remote` 必填,`command` 是数组。 +2. 远程 URL 正确,headers/oauth 字段拼写。 +3. 退出重启 opencode。 +4. `opencode mcp list` 看 server 状态。 +5. 在 prompt 里 `use ` 试调,或用 `mcp debug ` 诊断。 +6. 上下文吃紧 → 全局 `tools.*: false`,按代理开。 diff --git a/skills/opencode-config/references/04-custom-tools.md b/skills/opencode-config/references/04-custom-tools.md new file mode 100644 index 0000000..30dca4d --- /dev/null +++ b/skills/opencode-config/references/04-custom-tools.md @@ -0,0 +1,156 @@ +# 04 — Custom Tools (自定义工具) + +> 源: +> 适用: 在 `.opencode/tools/*.ts` 创建 LLM 可调用的工具 + +## 位置 + +- 项目级: `.opencode/tools/.ts` (本仓库用) +- 全局: `~/.config/opencode/tools/.ts` + +> 文件名**即工具名**。`database.ts` → `database` 工具。 + +## 最小结构 (用 `tool()` 辅助) + +`.opencode/tools/database.ts`: + +```ts +import { tool } from "@opencode-ai/plugin" + +export default tool({ + description: "Query the project database", + args: { + query: tool.schema.string().describe("SQL query to execute"), + }, + async execute(args) { + return `Executed query: ${args.query}` + }, +}) +``` + +## 参数 (Zod) + +`tool.schema` 即 Zod 命名导出: + +```ts +args: { + query: tool.schema.string().describe("SQL query to execute"), + limit: tool.schema.number().int().min(1).default(20).describe("Max rows"), + filter: tool.schema.enum(["all", "active"]).describe("Status filter"), +} +``` + +或直接 import: + +```ts +import { z } from "zod" + +export default { + description: "...", + args: { param: z.string().describe("...") }, + async execute(args, context) { ... } +} +``` + +## Context (工具能拿到的会话上下文) + +```ts +async execute(args, context) { + const { agent, sessionID, messageID, directory, worktree } = context + return JSON.stringify({ agent, sessionID, messageID, directory, worktree }) +} +``` + +| 字段 | 含义 | +|---|---| +| `agent` | 当前代理名 | +| `sessionID` | 会话 ID | +| `messageID` | 消息 ID | +| `directory` | 会话工作目录 | +| `worktree` | git worktree 根 | + +## 单文件多导出 + +`.opencode/tools/math.ts`: + +```ts +import { tool } from "@opencode-ai/plugin" + +export const add = tool({ + description: "Add two numbers", + args: { + a: tool.schema.number().describe("First number"), + b: tool.schema.number().describe("Second number"), + }, + async execute(args) { return args.a + args.b } +}) + +export const multiply = tool({ + description: "Multiply two numbers", + args: { + a: tool.schema.number().describe("First number"), + b: tool.schema.number().describe("Second number"), + }, + async execute(args) { return args.a * args.b } +}) +``` + +→ 工具名 `math_add` / `math_multiply` (`_`)。 + +## 与内置工具同名 → 覆盖 + +`.opencode/tools/bash.ts` 取代内置 `bash`: + +```ts +import { tool } from "@opencode-ai/plugin" +export default tool({ + description: "Restricted bash wrapper", + args: { command: tool.schema.string() }, + async execute(args) { return `blocked: ${args.command}` } +}) +``` + +> 想禁用内置**不**覆盖,改用 `permission.bash: "deny"`。 + +## 非 TS 实现 (Python 等) + +工具定义用 TS,**实现**可调任意语言。 + +`add.py`: + +```python +import sys +a = int(sys.argv[1]) +b = int(sys.argv[2]) +print(a + b) +``` + +`python-add.ts`: + +```ts +import { tool } from "@opencode-ai/plugin" +import path from "path" + +export default tool({ + description: "Add two numbers using Python", + args: { + a: tool.schema.number().describe("First number"), + b: tool.schema.number().describe("Second number"), + }, + async execute(args, context) { + const script = path.join(context.worktree, ".opencode/tools/add.py") + const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text() + return result.trim() + }, +}) +``` + +## 验证清单 + +1. 文件名 `*.ts` (不是 `.js`/`.mjs`,虽然支持)。 +2. 默认导出用 `tool()` 或返回 `{ description, args, execute }` 对象。 +3. Zod schema 全部字段都 `.describe()` (LLM 用作工具描述)。 +4. 多导出文件名 `` + 导出名 `` 形成工具名 `_`。 +5. **退出重启 opencode**。 +6. 在 prompt 看 `` 是否列出新工具。 +7. 调一次验证参数/返回/错误处理。 diff --git a/skills/opencode-config/references/05-tools.md b/skills/opencode-config/references/05-tools.md new file mode 100644 index 0000000..a8de5f7 --- /dev/null +++ b/skills/opencode-config/references/05-tools.md @@ -0,0 +1,123 @@ +# 05 — Tools (内置工具 + 权限) + +> 源: +> 适用: 调整 `opencode.json` 的 `permission` 段,管控 LLM 能用什么工具 + +## 全局 permission + +```json +{ + "$schema": "https://opencode.ai/config.json", + "permission": { + "edit": "deny", + "bash": "ask", + "webfetch": "allow" + } +} +``` + +值: `"allow"` / `"ask"` / `"deny"`。 + +**Glob 通配符** (针对所有工具): + +```json +{ "permission": { "mymcp_*": "ask" } } // 某 MCP server 全部工具需审批 +{ "permission": { "mymcp*": false } } // (在 tools 段) 全局禁用 +``` + +> `tools` 段控制**可用性** (true/false),`permission` 段控制**行为** (allow/ask/deny)。两者可叠加。 + +## 12 个内置工具 + +| 工具 | 用途 | 关键说明 | +|---|---|---| +| `bash` | 执行 shell 命令 | — | +| `edit` | 精确字符串替换 | — | +| `write` | 创建/覆盖文件 | 由 `edit` 权限控制 (含 edit/write/patch) | +| `read` | 读文件 (支持行范围) | — | +| `grep` | ripgrep 内容搜索 | 遵循 `.gitignore` | +| `glob` | 文件模式匹配 (按 mtime 排序) | 遵循 `.gitignore` | +| `lsp` | 跳转/引用/悬停/调用层次 | **需** `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` 或 `OPENCODE_EXPERIMENTAL=true` | +| `patch` | 应用补丁 | 由 `edit` 权限控制 | +| `skill` | 加载 SKILL.md | 见 02-skills | +| `todowrite` | 任务列表 | **默认对子代理禁用**,要开 `agent..tools.todowrite: true` | +| `webfetch` | 取网页 | — | +| `websearch` | 网络搜索 (Exa) | **需** OpenCode 提供商,或 `OPENCODE_ENABLE_EXA=1\|true` | +| `question` | 交互提问 | — | + +## 特殊权限 (只接受 flat action, 不接受 per-pattern object) + +- `todowrite` +- `question` +- `webfetch` (在某些版本) +- `websearch` (在某些版本) +- `doom_loop` + +→ 只能 `"allow"` / `"ask"` / `"deny"`,不能 `{"git *": "allow", ...}`。 + +## `.ignore` 覆盖 `.gitignore` + +`grep` / `glob` 默认遵守 `.gitignore`。要强制搜 `node_modules/` 等被忽略目录,加项目根 `.ignore`: + +```gitignore +!node_modules/ +!dist/ +!build/ +``` + +## 实战组合 + +**Plan 代理只读**: + +```json +{ + "permission": { "edit": "deny", "bash": "ask", "webfetch": "deny" }, + "agent": { + "plan": { + "permission": { "edit": "ask", "bash": "ask" } + } + } +} +``` + +**全局禁 MCP,只给 review 代理开**: + +```json +{ + "mcp": { "playwright": { "type": "local", "command": ["npx", "-y", "@playwright/mcp"] } }, + "tools": { "playwright_*": false }, + "agent": { "code-reviewer": { "tools": { "playwright_*": true } } } +} +``` + +**让某代理能调指定子代理** (Task 权限): + +```json +{ + "agent": { + "orchestrator": { + "permission": { + "task": { "*": "deny", "orchestrator-*": "allow", "code-reviewer": "ask" } + } + } + } +} +``` + +> 规则**最后匹配优先**。`orchestrator-planner` 同时匹配 `*`(deny) 和 `orchestrator-*`(allow) → 第二个胜出 → allow。 +> 用户**始终能**用 `@` 调任何子代理,即使被 task 权限拒绝。 + +## 内部机制 + +- `grep` / `glob` 用 ripgrep,默认遵守 `.gitignore`。 +- MCP 工具以 `_` 命名,glob 模式 `mymcp_*`。 +- 权限 JSON 中对象型值,插入顺序敏感 — opencode 取**最后匹配**的规则,先放宽后放严。 + +## 验证清单 + +1. permission 值: `allow` / `ask` / `deny`,不是 `true`/`false`。 +2. tools 段用 `true`/`false`,`permission` 段用三态字符串。 +3. glob 模式放宽松规则**前**,具体规则**后** (最后匹配优先)。 +4. 特殊权限 (todowrite/question/websearch) 不传对象。 +5. **退出重启 opencode**。 +6. 实测: 启用规则下,代理能正常调;ask 时弹确认;deny 时直接拒绝。