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

2026-10-13 12:38:52 +08:00
parent 33155181a1
commit a9b4251158
8 changed files with 1713 additions and 0 deletions
@@ -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 时直接拒绝。