权限

权限配置指南

本指南介绍如何为探索模式配置自定义权限规则。

概述

探索模式是一种只读模式，会阻止潜在的破坏性操作。自定义权限规则允许你放行原本会被阻止的特定操作。

权限文件位置：

工作区级别：~/.tentarc/workspaces/{slug}/permissions.json
数据源级别：~/.tentarc/workspaces/{slug}/sources/{source}/permissions.json

数据源权限的自动作用域限定

重要说明： 数据源 permissions.json 中的 MCP 模式会自动限定在该数据源范围内。

当你编写：

{ "pattern": "list", "comment": "Allow list operations" }

系统会在内部将其转换为 mcp__<sourceSlug>__.*list。这意味着：

像 list 这样的简单模式只会影响来自该数据源的工具
不会意外放行其他数据源的 list 工具
工作区级别的模式仍然全局生效（用于有意的跨数据源规则）

permissions.json 结构

{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "Allow list operations" },
    { "pattern": "get", "comment": "Allow get operations" },
    { "pattern": "search", "comment": "Allow search operations" }
  ],
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "All GET requests" },
    { "method": "POST", "path": "^/search", "comment": "Search POST" }
  ],
  "allowedBashPatterns": [
    { "pattern": "^ls\\s", "comment": "Allow ls commands" }
  ],
  "blockedTools": [
    "dangerous_tool"
  ],
  "allowedWritePaths": [
    "/tmp/**",
    "~/.tentarc/**"
  ]
}

规则类型

allowedMcpPatterns

用于匹配探索模式中允许的 MCP 工具名称的正则表达式模式。

对于数据源级别的 permissions.json，使用简单模式（自动限定作用域）：

{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "All list operations for this source" },
    { "pattern": "get", "comment": "All get operations for this source" },
    { "pattern": "search", "comment": "All search operations for this source" }
  ]
}

对于工作区级别的 permissions.json（全局规则），使用完整模式：

{
  "allowedMcpPatterns": [
    { "pattern": "^mcp__.*__list", "comment": "List operations across all sources" }
  ]
}

allowedApiEndpoints

API 数据源请求的细粒度规则。

{
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "All GET requests" },
    { "method": "POST", "path": "^/search", "comment": "Search POST" },
    { "method": "POST", "path": "^/v1/query$", "comment": "Query endpoint" }
  ]
}

allowedBashPatterns

允许的 bash 命令的正则表达式模式。

{
  "allowedBashPatterns": [
    { "pattern": "^ls\\s", "comment": "ls commands" },
    { "pattern": "^git\\s+status", "comment": "git status" },
    { "pattern": "^pwd$", "comment": "pwd command" }
  ]
}

blockedTools

需要额外阻止的工具（很少需要使用）。

{
  "blockedTools": ["risky_tool_name"]
}

allowedWritePaths

允许写入的目录的 glob 模式。

{
  "allowedWritePaths": [
    "/tmp/**",
    "~/.tentarc/**",
    "/path/to/project/output/**"
  ]
}

探索模式的默认行为

默认阻止：

Bash 命令（下方列出的只读命令除外）
Write、Edit、MultiEdit 工具
具有写入语义的 MCP 工具（create、update、delete）
API POST/PUT/DELETE 请求

默认允许：

Read、Glob、Grep
WebFetch、WebSearch
TodoWrite
具有读取语义的 MCP 工具（list、get、search）
计划文件夹写入（仅限会话计划）

只读 Bash 命令

以下命令在探索模式中无需自定义配置即可使用：

类别	命令
文件浏览	`ls`, `tree`, `cat`, `head`, `tail`, `file`, `stat`, `wc`, `du`, `df`
搜索	`find`, `grep`, `rg`, `ag`, `fd`, `locate`, `which`
Git（只读）	`git status`, `git log`, `git diff`, `git show`, `git branch`, `git blame`, `git reflog`
GitHub CLI	`gh pr view/list`, `gh issue view/list`, `gh repo view`
包管理器	`npm ls/list/outdated`, `yarn list`, `pip list`, `cargo tree`
系统信息	`pwd`, `whoami`, `env`, `ps`, `uname`, `hostname`, `date`
文本处理	`jq`, `yq`, `sort`, `uniq`, `cut`, `column`
网络诊断	`ping`, `dig`, `nslookup`, `netstat`
版本检查	`node --version`, `python --version` 等

复合命令

当所有部分都是安全的时，使用 &&、|| 和 | 的复合命令是允许的：

构造	示例	行为
逻辑与	`git status && git log`	如果两个命令都安全则允许
逻辑或	`git status \|\| echo "failed"`	如果两个命令都安全则允许
管道	`git log \| head`	如果所有命令都安全则允许

每个命令会独立验证。如果任何命令不在允许列表中，整个复合命令都会被阻止。

被阻止的 Shell 构造

以下构造始终被阻止，即使基础命令是允许的：

构造	示例	阻止原因
后台执行	`&`	异步运行，可能隐藏活动
重定向	`>`, `>>`	可能覆盖文件
命令替换	`$()`、反引号、`<()`、`>()`	执行嵌入的命令
控制字符	换行符、回车符	充当命令分隔符

示例：git status > file.txt 会被阻止，因为 > 可能覆盖文件。

规则级联

规则从工作区 → 数据源 → 代理依次级联：

工作区规则全局生效
数据源规则为该数据源扩展工作区规则
代理规则为该代理会话扩展前两者

规则是累加的——只能允许更多操作，不能进一步限制。

最佳实践

精确指定模式 - 使用锚点（^、$）避免过度匹配
添加注释 - 解释每条规则存在的原因
测试模式 - 验证正则表达式匹配预期的工具名称
最小权限 - 只允许必需的操作

示例

只读 Linear 访问：

{
  "allowedMcpPatterns": [
    { "pattern": "^mcp__linear__(list|get|search)", "comment": "Read operations" }
  ]
}

仅搜索的 API：

{
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*" },
    { "method": "POST", "path": "^/search" }
  ]
}

安全的 git 命令：

{
  "allowedBashPatterns": [
    { "pattern": "^git\\s+(status|log|diff|branch)", "comment": "Read-only git" }
  ]
}

探索模式中的计划

在探索模式中，你可以创建实施计划，用户可以接受该计划以过渡到执行阶段。

何时创建计划

在以下情况下创建计划：

任务包含多个复杂步骤
你希望在进行更改之前获得用户批准
你已收集足够的上下文并准备好实施

创建计划

将计划写入会话计划文件夹中的 markdown 文件
使用文件路径调用 SubmitPlan
用户会看到一个格式化的计划和"接受计划"按钮
点击"接受计划"将退出探索模式并开始实施

计划格式

# 计划标题

## 摘要
简要描述此计划要完成的内容。

## 步骤
1. **步骤描述** - 详情和方法
2. **另一个步骤** - 更多详情
3. ...

探索 → 实施工作流

推荐的工作流：

探索 - 读取文件、搜索代码、理解代码库
计划 - 将结构化计划写入计划文件夹
提交 - 调用 SubmitPlan 向用户展示
接受 - 用户点击"接受计划"退出探索模式
执行 - 以完整权限实施计划

这提供了从探索到实施的平滑过渡，同时保持用户监督。