权限

xiantong Agent 如何处理敏感操作

xiantong 可以代表你执行强大操作——读取文件、运行命令、修改文档。为了让你始终掌控，应用程序提供了三种权限模式，用于确定 Agent 具有多大的自主权。

以对话为主的自定义： 你可以让 Agent 为你自定义权限。试试“在探索模式下允许 npm build”或“让我在不提示的情况下运行 pytest”，Agent 就会自动更新你的配置。

权限模式#

xiantong 提供三种不同的权限模式。使用 SHIFT+TAB 循环切换它们：

探索模式（安全模式）#

探索模式是一种只读安全模式，适用于研究与调查。Agent 可以收集信息，但不能进行任何修改。允许的操作：

• Read - 读取文件内容
• Glob - 按模式查找文件
• Grep - 搜索文件内容
• WebSearch、WebFetch - 网络搜索与内容抓取
• Task、TaskOutput - 子 Agent 任务
• TodoWrite、SubmitPlan - 计划操作
• LSP - 语言服务器查询（悬浮、定义等）
• 只读 bash 命令（见下文安全命令）

禁止的操作：

• Write - 创建或覆盖文件
• Edit、MultiEdit - 修改文件内容
• NotebookEdit - 修改 Jupyter 笔记本
• Bash 变更命令（如 rm、mv、mkdir 等）
• MCP 工具变更（创建、更新、删除操作）
• API 变更（POST、PUT、DELETE 请求）

在你希望 Agent 进行研究与分析而不会发生意外更改时，请使用探索模式。

询问后编辑模式（默认）#

询问后编辑是默认模式。它采用三级权限系统：

当 Agent 需要运行非安全命令时，你会看到权限提示：

Agent 想运行： npm install lodash

允许吗？[y]es / [n]o / [a]lways allow

你的选项：

• y（是） - 允许此特定操作
• n（否） - 拒绝请求
• a（总是） - 在本次会话中允许该命令（危险命令不可用）

执行模式（全允许模式）#

执行模式赋予 Agent 完全的自主执行能力。操作无需提示即可运行，从而实现快速、不中断的工作流程。

执行模式绕过权限提示。只在你完全信任正在执行的操作（例如受控自动化场景）时使用。

切换模式#

按 SHIFT+TAB 循环切换权限模式：

探索 → 询问后编辑 → 执行 → 探索 → ...

界面始终显示当前模式，方便你了解 Agent 拥有什么级别的自主权。

危险命令#

危险命令是非安全命令的一个子集，需要额外谨慎。与常规命令的关键区别：

• 常规命令： 可在会话中用“总是允许”自动允许
• 危险命令： 每次都必须单独批准（“总是允许”会被静默忽略）
• curl/wget 特殊情况： “总是允许”会将域名加入白名单，而不是命令本身

在执行模式中，包括危险命令在内的所有命令都会自动运行。

rm, rmdir # 文件/目录删除
mv, cp # 文件移动/复制（可能覆盖）
sudo, su # 提权
chmod, chown, chgrp # 权限更改
dd, mkfs, fdisk, parted # 磁盘操作
kill, killall, pkill # 进程终止
reboot, shutdown, halt, poweroff # 系统控制
curl, wget # 网络下载（可能抓取恶意内容）
ssh, scp, rsync # 远程访问/传输
git push # 推送到远程仓库
git reset # 重置 git 状态
git rebase # 重写 git 历史
git checkout # 可能丢弃更改

安全命令#

探索模式允许一套全面的只读命令。任何模式下这些命令都无需提示：文件探索：

ls, ll, la, tree # 目录列表
cat, head, tail, less, more # 查看文件
file, stat, du, df, wc # 文件信息
bat # 具有语法高亮的现代替代

搜索工具：

find, locate, which, whereis, type
grep, rg, ag, ack, fd, fzf

Git（只读）：

git status, git log, git diff, git show
git branch, git tag, git remote
git stash list, git blame, git reflog

GitHub CLI（只读）：

gh pr view/list, gh issue view/list
gh repo view, gh release list
gh api（仅限 GET 请求）

包管理工具（只读）：

npm ls/list/view/outdated/audit
yarn list/info/why/outdated
pnpm list/ls/why/outdated
pip list/show/freeze
cargo tree/metadata
go list/mod graph

Docker 与 Kubernetes（只读）：

docker ps, images, logs, inspect, stats
kubectl get, describe, logs, top, explain

系统信息：

pwd, whoami, id, uname, hostname
date, uptime, env, ps, free

文本处理：

jq, yq, xq, xmllint # 结构化数据处理器
sort, uniq, cut, tr, column
sed -n（仅打印模式）

网络诊断：

ping, traceroute, dig, nslookup
netstat, ss, ip addr/link/route

版本检查：

node --version, python --version
npm --version, cargo --version
（以及其他运行时版本命令）

自定义探索模式#

只需告诉你的 Agent。 自定义探索模式最简单的方法就是告诉 Agent 你需要什么：

• “在探索模式下允许 npm build”
• “让安全模式支持 Linear 评论”
• “在允许命令中添加 bun run test”

Agent 会自动处理配置文件。

如果你更习惯手动配置，探索模式权限高度可定制。你可以扩展允许列表以适应你的工作流——添加特定的 bash 命令、MCP 工具模式、API 端点，甚至文件写入路径。

权限配置#

权限通过多个层级的 permissions.json 文件配置：

~/.xiantong/permissions/default.json # 应用范围默认
~/.xiantong/workspaces/{id}/permissions.json # 工作区特定
~/.xiantong/workspaces/{id}/sources/{slug}/permissions.json # 来源特定

更具体的配置会扩展（而非替换）通用配置。来源级模式会自动限定在该来源的工具上。

配置模式#

{
"allowedBashPatterns": [
{ "pattern": "^npm run build\\b", "comment": "允许 npm build" },
{ "pattern": "^make\\s+test\\b", "comment": "允许 make test" }
],
"allowedMcpPatterns": [
{ "pattern": "create_draft", "comment": "允许创建草稿" }
],
"allowedApiEndpoints": [
{ "method": "POST", "path": "/api/drafts", "comment": "创建草稿" }
],
"allowedWritePaths": [
"tmp/**",
"*.draft.md"
]
}

模式类型#

allowedBashPatterns - 用于 bash 命令的正则模式：

{ "pattern": "^npm run (build|test|lint)\\b", "comment": "npm 脚本" }

allowedMcpPatterns - 匹配 MCP 工具名称的模式：

{ "pattern": "linear_create_comment", "comment": "允许 Linear 评论" }

来源级的模式会自动加上作用域。在来源的 permissions.json 中写 create_comment，它会在内部变成 mcp__linear__.*create_comment——.* 表示模式可以匹配工具名称后缀中的任意位置。allowedApiEndpoints - HTTP 方法 + 路径组合：

{ "method": "POST", "path": "/api/comments", "comment": "创建评论" }

方法必须是以下之一：GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS。路径是一个正则表达式。allowedWritePaths - 探索模式下可写入的文件路径的 glob 模式：

["plans/**", "drafts/**", "*.tmp"]

示例：在探索模式下允许 npm 脚本#

创建 ~/.xiantong/permissions/default.json：

{
"allowedBashPatterns": [
{ "pattern": "^npm run\\b", "comment": "所有 npm 脚本" },
{ "pattern": "^yarn\\b", "comment": "所有 yarn 命令" },
{ "pattern": "^bun run\\b", "comment": "所有 bun 脚本" }
]
}

示例：在探索模式下允许 Linear 评论#

创建 ~/.xiantong/workspaces/{id}/sources/linear/permissions.json：

{
"allowedMcpPatterns": [
{ "pattern": "create_comment", "comment": "允许发布评论" }
]
}

限制的 Shell 构造#

即使是允许的命令，当它们包含潜在危险的 Shell 构造时也会被阻止：命令链 - 可能链到危险命令：

&& || ; | & |&

重定向 - 可能覆盖文件：

> >> >&

替换 - 可能执行嵌入命令：

$() `backticks` <() >()

控制字符 - 作为命令分隔符：

换行、回车

对于所有部分都安全的复合命令（如 git status && git log），系统会使用 AST 解析分别验证每一部分。

即使是安全命令，只要结合了 shell 构造也会被阻止。例如，由于管道可能用于链向危险命令，ls | grep foo 在探索模式下会被阻止。请单独运行安全命令，避免使用管道或重定向。

API 与 MCP 凭证#

外部服务的凭证会被安全处理：

• 存储在 ~/.xiantong/credentials.enc 中并加密
• 录入后不会以明文显示
• 按工作区与来源进行作用域划分
• 你可以控制每个 Agent 可访问哪些服务

当 Agent 需要使用新的 API 时，会提示你提供凭证。凭证随后会安全存储以供后续使用。

最佳实践#

从探索模式开始

在调查不熟悉的代码或系统时，先使用探索模式，安全地进行研究再进行更改。

在常规工作中使用询问后编辑

默认的询问后编辑模式为大多数任务提供了生产率与控制力的良好平衡。

将执行模式留给受信任的工作流

仅在任务明确、可重复且你信任 Agent 操作时使用执行模式。

为你的工作流自定义探索模式

将常用的构建命令、测试运行器和安全的 MCP 操作添加到 permissions.json，以便它们在探索模式下可用。

在批准前先复查

在询问后编辑模式下，批准之前花点时间阅读即将发生的更改，特别是对于不熟悉的操作。