opencode-sync
124 lines
3.6 KiB
Markdown
124 lines
3.6 KiB
Markdown
# 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 时直接拒绝。
|