From c14f82830f8ff1393f8af3aec9cb4f228ef3c6bc Mon Sep 17 00:00:00 2001 From: opencode-sync Date: Tue, 13 Oct 2026 12:40:06 +0800 Subject: [PATCH] skills: remove obsolete opencode-config (replaced by opencode-plugins) --- 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 ----------- 6 files changed, 934 deletions(-) delete mode 100644 skills/opencode-config/SKILL.md delete mode 100644 skills/opencode-config/references/01-agents.md delete mode 100644 skills/opencode-config/references/02-skills.md delete mode 100644 skills/opencode-config/references/03-mcp-servers.md delete mode 100644 skills/opencode-config/references/04-custom-tools.md delete mode 100644 skills/opencode-config/references/05-tools.md diff --git a/skills/opencode-config/SKILL.md b/skills/opencode-config/SKILL.md deleted file mode 100644 index f9685cf..0000000 --- a/skills/opencode-config/SKILL.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -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 deleted file mode 100644 index c4519f3..0000000 --- a/skills/opencode-config/references/01-agents.md +++ /dev/null @@ -1,163 +0,0 @@ -# 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 deleted file mode 100644 index 6f96ed0..0000000 --- a/skills/opencode-config/references/02-skills.md +++ /dev/null @@ -1,199 +0,0 @@ -# 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 deleted file mode 100644 index b12dd4c..0000000 --- a/skills/opencode-config/references/03-mcp-servers.md +++ /dev/null @@ -1,200 +0,0 @@ -# 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 deleted file mode 100644 index 30dca4d..0000000 --- a/skills/opencode-config/references/04-custom-tools.md +++ /dev/null @@ -1,156 +0,0 @@ -# 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 deleted file mode 100644 index a8de5f7..0000000 --- a/skills/opencode-config/references/05-tools.md +++ /dev/null @@ -1,123 +0,0 @@ -# 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 时直接拒绝。