sync: import skills/, plugins/, memory/ and shared files from origin/main

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 <package>` - 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 <owner/repo@skill> -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
+```

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 <key>` | API Key (覆盖其他认证方式) |
+| `--region <region>` | API 区域: `global` (默认) / `cn` |
+| `--base-url <url>` | API Base URL (覆盖 region) |
+| `--output <format>` | 输出格式: `text` / `json` |
+| `--quiet` | 抑制非必要输出 |
+| `--verbose` | 打印 HTTP 请求/响应详情 |
+| `--timeout <seconds>` | 请求超时 (默认: 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 <key>] [--recommend] [--region=global|cn]
+```
+
+- `--api-key <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 <text> [flags]
+```
+
+| Flag | 说明 | 默认值 |
+|------|------|--------|
+| `--model <model>` | 模型 ID | `MiniMax-M2.7` |
+| `--message <text>` | 消息文本 (可重复, 前缀 `role:` 设置角色) | - |
+| `--messages-file <path>` | JSON 文件包含消息数组 (`-` 表示 stdin) | - |
+| `--system <text>` | 系统提示词 | - |
+| `--max-tokens <n>` | 最大生成 Token 数 | 4096 |
+| `--temperature <n>` | 采样温度 (0.0, 1.0] | - |
+| `--top-p <n>` | 核采样阈值 | - |
+| `--stream` | 流式响应 (TTY 中默认开启) | - |
+| `--tool <json-or-path>` | 工具定义 (可重复) | - |
+
+**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 <model>` | 模型 ID | `MiniMax-M2.7` |
+| `--system <text>` | 系统提示词 | - |
+| `--max-tokens <n>` | 每响应最大 Token 数 | 4096 |
+| `--temperature <n>` | 采样温度 (0.0, 1.0] | - |
+| `--top-p <n>` | 核采样阈值 | - |
+
+**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 <text> [--out <path>] [flags]
+```
+
+| Flag | 说明 | 默认值 |
+|------|------|--------|
+| `--model <model>` | 模型 ID | `speech-2.8-hd` |
+| `--text <text>` | 要合成的文本 | - |
+| `--text-file <path>` | 从文件读取文本 (`-` 表示 stdin) | - |
+| `--voice <id>` | 声音 ID | `English_expressive_narrator` |
+| `--speed <n>` | 语速倍数 | - |
+| `--volume <n>` | 音量 | - |
+| `--pitch <n>` | 音调调整 | - |
+| `--format <fmt>` | 音频格式: `mp3`, `pcm`, `flac`, `wav`, `pcmu_raw`, `pcmu_wav`, `opus` | `mp3` |
+| `--sample-rate <hz>` | 采样率 | `32000` |
+| `--bitrate <bps>` | 比特率 | `128000` |
+| `--channels <n>` | 声道数 | `1` |
+| `--language <code>` | 语言增强 | - |
+| `--subtitles` | 包含字幕时间数据 | - |
+| `--pronunciation <from/to>` | 自定义发音 (可重复) | - |
+| `--out <path>` | 保存音频到文件 | - |
+| `--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 <lang>]
+```
+
+| Flag | 说明 |
+|------|------|
+| `--language <lang>` | 按语言过滤声音 (如 `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 <text> [flags]
+```
+
+| Flag | 说明 | 默认值 |
+|------|------|--------|
+| `--prompt <text>` | 图像描述 | - |
+| `--aspect-ratio <ratio>` | 宽高比 (如 `16:9`, `1:1`) | - |
+| `--n <count>` | 生成图像数量 | `1` |
+| `--seed <n>` | 随机种子 (相同 seed + prompt = 相同输出) | - |
+| `--width <px>` | 自定义宽度 [512, 2048], 必须是 8 的倍数 | - |
+| `--height <px>` | 自定义高度 [512, 2048], 必须是 8 的倍数 | - |
+| `--prompt-optimizer` | 自动优化提示词 | - |
+| `--aigc-watermark` | 在输出图像中嵌入 AI 生成内容水印 | - |
+| `--subject-ref <params>` | 主体参考 (角色一致性): `type=character,image=path-or-url` | - |
+| `--out <path>` | 保存图像到指定路径 (仅单张) | - |
+| `--response-format <format>` | 响应格式: `url` (下载), `base64` (嵌入) | `url` |
+| `--out-dir <dir>` | 下载图像到目录 | - |
+| `--out-prefix <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 <text> [flags]
+```
+
+| Flag | 说明 |
+|------|------|
+| `--model <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 <text>` | 视频描述 |
+| `--first-frame <path-or-url>` | 首帧图像 (本地路径或 URL) |
+| `--last-frame <path-or-url>` | 末帧图像 (需要 `--first-frame`, 启用 SEF 模式) |
+| `--subject-image <path-or-url>` | 主体参考图像 (角色一致性) |
+| `--callback-url <url>` | 完成通知的 Webhook URL |
+| `--download <path>` | 完成后保存视频到文件 |
+| `--no-wait` / `--async` | 立即返回任务 ID，不等待 |
+| `--poll-interval <seconds>` | 轮询间隔 (默认: 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 <id>
+```
+
+| Flag | 说明 |
+|------|------|
+| `--task-id <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 <id> --out <path>
+```
+
+| Flag | 说明 |
+|------|------|
+| `--file-id <id>` | 要下载的文件 ID |
+| `--out <path>` | 输出文件路径 |
+
+**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 <text> (--lyrics <text> | --instrumental | --lyrics-optimizer) [--out <path>] [flags]
+```
+
+| Flag | 说明 | 默认值 |
+|------|------|--------|
+| `--prompt <text>` | 音乐风格描述 (最多 2000 字符) | - |
+| `--lyrics <text>` | 带结构标签的歌词 | - |
+| `--lyrics-file <path>` | 从文件读取歌词 (`-` 表示 stdin) | - |
+| `--lyrics-optimizer` | 从 prompt 自动生成歌词 (不能与 `--lyrics` 或 `--instrumental` 共用) | - |
+| `--instrumental` | 生成器乐音乐 | - |
+| `--vocals <text>` | 人声风格, 如 "warm male baritone" | - |
+| `--genre <text>` | 音乐流派, 如 folk, pop, jazz, electronic | - |
+| `--mood <text>` | 情绪, 如 warm, melancholic, uplifting | - |
+| `--instruments <text>` | 要突出的乐器 | - |
+| `--tempo <text>` | 节奏描述, 如 fast, slow, moderate | - |
+| `--bpm <number>` | 精确 BPM | - |
+| `--key <text>` | 调性, 如 C major, A minor | - |
+| `--avoid <text>` | 要避免的元素 | - |
+| `--use-case <text>` | 使用场景, 如 "background music for video" | - |
+| `--structure <text>` | 歌曲结构 | - |
+| `--references <text>` | 参考曲目或艺术家 | - |
+| `--extra <text>` | 额外细化需求 | - |
+| `--model <model>` | 模型: `music-2.6` (默认), `music-2.5+`, `music-2.5` | `music-2.6` |
+| `--output-format <fmt>` | 返回格式: `hex` (默认, 保存到文件) 或 `url` (24h 过期) | `hex` |
+| `--aigc-watermark` | 嵌入 AI 生成内容水印 | - |
+| `--format <fmt>` | 音频格式: `mp3`, `wav`, `pcm` | `mp3` |
+| `--sample-rate <hz>` | 采样率 | `44100` |
+| `--bitrate <bps>` | 比特率 | `256000` |
+| `--stream` | 流式输出原始音频到 stdout | - |
+| `--out <path>` | 保存音频到文件 | - |
+
+**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 <text> (--audio <url> | --audio-file <path>) [--lyrics <text>] [--out <path>] [flags]
+```
+
+| Flag | 说明 | 默认值 |
+|------|------|--------|
+| `--model <model>` | 模型: `music-cover` (默认) | `music-cover` |
+| `--prompt <text>` | 目标翻唱风格, 如 "Indie folk, acoustic guitar, warm male vocal" | - |
+| `--audio <url>` | 参考音频 URL (mp3/wav/flac, 6s-6min, 最大 50MB) | - |
+| `--audio-file <path>` | 本地参考音频文件 (自动 Base64 编码) | - |
+| `--lyrics <text>` | 翻唱歌词 (省略则通过 ASR 从参考音频提取) | - |
+| `--lyrics-file <path>` | 从文件读取歌词 (`-` 表示 stdin) | - |
+| `--seed <number>` | 随机种子 0-1000000 | - |
+| `--format <fmt>` | 音频格式: `mp3`, `wav`, `pcm` | `mp3` |
+| `--sample-rate <hz>` | 采样率 | `44100` |
+| `--bitrate <bps>` | 比特率 | `256000` |
+| `--channel <n>` | 声道: `1` (单声道) / `2` (立体声, 默认) | `2` |
+| `--stream` | 流式输出原始音频到 stdout | - |
+| `--out <path>` | 保存音频到文件 | - |
+
+**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 <query>
+```
+
+| Flag | 说明 |
+|------|------|
+| `--q <query>` | 搜索查询字符串 |
+
+**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 <path-or-url> | --file-id <id>) [--prompt <text>]
+```
+
+| Flag | 说明 | 默认值 |
+|------|------|--------|
+| `--image <path-or-url>` | 本地图像路径或 URL (自动 Base64 编码) | - |
+| `--file-id <id>` | 预上传的文件 ID (跳过 Base64 转换) | - |
+| `--prompt <text>` | 关于图像的问题 | `"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 <key> --value <value>
+```
+
+| Flag | 说明 |
+|------|------|
+| `--key <key>` | 配置键: `region`, `base_url`, `output`, `timeout`, `api_key`, `proxy`, `default_text_model`, `default_speech_model`, `default_video_model`, `default_music_model` |
+| `--value <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 "<name>"]
+```
+
+| Flag | 说明 |
+|------|------|
+| `--command <name>` | 仅导出特定命令的模式 (如 `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 <path> [--purpose <purpose>]
+```
+
+| Flag | 说明 | 默认值 |
+|------|------|--------|
+| `--file <path>` | 文件的本地路径 | - |
+| `--purpose <string>` | 文件用途 (默认: `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 <id>
+```
+
+| Flag | 说明 |
+|------|------|
+| `--file-id <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

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/<name>.md` 或 `.opencode/agents/<name>.md` | 文件名即 agent 名 |
+| 技能 | `.opencode/skill/<name>/SKILL.md` | frontmatter `name` 与目录名一致 |
+| 技能 (外部) | `.agents/skills/<name>/SKILL.md` | 兼容 Claude 风格 |
+| MCP | 写在 `opencode.json` 的 `mcp.<server>` | 不用单独文件 |
+| 自定义工具 | `.opencode/tools/<name>.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`)、多导出命名 `<file>_<export>`、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/<name>.md (frontmatter + prompt)
+├─ 改 opencode.json ──→ 对应类别的 references/ + 校验 $schema
+├─ 加 skill ──────────→ references/02-skills.md §"编写 frontmatter"
+│                         落地: .opencode/skill/<name>/SKILL.md (主文件) + 视情况 references/ scripts/ templates/
+├─ 加 MCP server ─────→ references/03-mcp-servers.md §"本地/远程/OAuth"
+│                         落地: opencode.json 的 mcp.<name>
+├─ 写自定义工具 ─────→ references/04-custom-tools.md §"结构/参数/上下文"
+│                         落地: .opencode/tools/<name>.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 权限拒绝后**: 代理在 `<available_skills>` 里**看不到**该 skill,会安静地以为不存在。
+6. **MCP 工具 glob**: 禁用某 server 全部工具用 `"<server>_*": false`,因为工具注册时带 server 前缀。
+7. **`todowrite` 默认对子代理禁用**: 要用就 `agent.<name>.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/*` 并存,迁移时按需搬运

skills/opencode-config/references/01-agents.md

@@ -0,0 +1,163 @@
+# 01 — Agents (代理)
+
+> 源: <https://opencode.ai/docs/zh-cn/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/<name>.md` 或 `.opencode/agents/<name>.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 | `{ "<name>": 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 用 `@<agent-name>` 试调,或主代理根据 description 自动触发。

skills/opencode-config/references/02-skills.md

@@ -0,0 +1,199 @@
+# 02 — Skills (代理技能)
+
+> 源: <https://opencode.ai/docs/zh-cn/skills/>
+> 适用: 创建/修改 `SKILL.md` (`.opencode/skill/<name>/SKILL.md`)
+
+## 放置文件 (发现路径)
+
+OpenCode 递归扫描以下位置找 `**/SKILL.md`:
+
+| 范围 | 路径 |
+|---|---|
+| 项目 opencode | `.opencode/skills/<name>/SKILL.md` |
+| 全局 opencode | `~/.config/opencode/skills/<name>/SKILL.md` |
+| 项目 Claude 兼容 | `.claude/skills/<name>/SKILL.md` |
+| 全局 Claude 兼容 | `~/.claude/skills/<name>/SKILL.md` |
+| 项目 agents 兼容 | `.agents/skills/<name>/SKILL.md` |
+| 全局 agents 兼容 | `~/.agents/skills/<name>/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` → **静默过滤掉**,不会报错也不会出现在 `<available_skills>`。
+
+## 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
+```
+
+## 工具描述 (模型看到什么)
+
+`<available_skills>` 列出每个 skill 的 `name` + `description`:
+
+```xml
+<available_skills>
+  <skill>
+    <name>git-release</name>
+    <description>Create consistent releases and changelogs</description>
+  </skill>
+</available_skills>
+```
+
+模型用 `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 相关的请求,看 `<available_skills>` 是否列出。
+6. 主代理调 `skill({ name: "..." })` 验证内容能加载。

skills/opencode-config/references/03-mcp-servers.md

@@ -0,0 +1,200 @@
+# 03 — MCP Servers (Model Context Protocol)
+
+> 源: <https://opencode.ai/docs/zh-cn/mcp-servers/>
+> 适用: 在 `opencode.json` 的 `mcp` 段加本地/远程 MCP server,加 OAuth 配置,按代理管控
+
+## 顶层结构
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "<server-name>": {
+      "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 <server>          # 触发 OAuth (开浏览器)
+opencode mcp auth list              # 列出所有支持 OAuth 的状态
+opencode mcp list                   # 列出所有 MCP server + 状态
+opencode mcp logout <server>        # 删凭据
+opencode mcp debug <server>         # 调试: 状态/HTTP/OAuth 发现
+```
+
+## 按代理管控 (MCP 工具)
+
+MCP 工具注册时**带 server 前缀** (`<server>_<tool>`)。要用 `tools.<server>_*` 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 <server>` 试调,或用 `mcp debug <server>` 诊断。
+6. 上下文吃紧 → 全局 `tools.<server>*: false`,按代理开。

skills/opencode-config/references/04-custom-tools.md

@@ -0,0 +1,156 @@
+# 04 — Custom Tools (自定义工具)
+
+> 源: <https://opencode.ai/docs/zh-cn/custom-tools/>
+> 适用: 在 `.opencode/tools/*.ts` 创建 LLM 可调用的工具
+
+## 位置
+
+- 项目级: `.opencode/tools/<name>.ts` (本仓库用)
+- 全局: `~/.config/opencode/tools/<name>.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` (`<filename>_<export>`)。
+
+## 与内置工具同名 → 覆盖
+
+`.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. 多导出文件名 `<file>` + 导出名 `<export>` 形成工具名 `<file>_<export>`。
+5. **退出重启 opencode**。
+6. 在 prompt 看 `<available_tools>` 是否列出新工具。
+7. 调一次验证参数/返回/错误处理。

skills/opencode-config/references/05-tools.md

@@ -0,0 +1,123 @@
+# 05 — Tools (内置工具 + 权限)
+
+> 源: <https://opencode.ai/docs/zh-cn/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.<name>.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 工具以 `<server>_<tool>` 命名,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 时直接拒绝。