权限 - 完整API参考

管理命令执行审批、工具访问策略和安全控制。

---

聊天命令

查看权限

/permissions                                查看当前权限
/permissions list                           列出所有规则
/permissions pending                        查看待审批
/permissions history                        查看审批历史

批准/拒绝

/approve                                   批准待处理命令
/approve <id>                               批准特定请求
/reject                                     拒绝待处理命令
/reject <id> "reason"                       拒绝并说明理由

允许/阻止规则

/permissions allow "npm install"            允许模式
/permissions allow "git *"                  允许使用通配符
/permissions block "rm -rf"                 阻止危险命令
/permissions remove <rule-id>               移除规则

安全模式

/permissions mode                           检查当前模式
/permissions mode allowlist                 只允许允许的命令
/permissions mode blocklist                 阻止特定命令
/permissions mode full                      允许全部（危险）

---

TypeScript API参考

创建权限管理器

import { createPermissionsManager } from 'clodds/permissions';

const perms = createPermissionsManager({
  // 安全模式
  mode: 'allowlist',  // 'deny' | 'allowlist' | 'blocklist' | 'full'

  // 默认规则
  defaultAllow: [
    'ls *',
    'cat *',
    'git status',
    'git diff',
    'npm run *',
  ],

  defaultBlock: [
    'rm -rf *',
    'sudo *',
    'chmod 777 *',
  ],

  // 审批设置
  requireApproval: true,
  approvalTimeoutMs: 60000,

  // 存储
  storage: 'sqlite',
  dbPath: './permissions.db',
});

检查权限

// 检查命令是否被允许
const result = await perms.check({
  command: 'npm install lodash',
  userId: 'user-123',
  context: '安装依赖',
});

if (result.allowed) {
  console.log('命令被允许');
} else if (result.needsApproval) {
  console.log(`等待审批：${result.requestId}`);
} else {
  console.log(`被阻止：${result.reason}`);
}

请求审批

// 请求命令审批
const request = await perms.requestApproval({
  command: 'docker build -t myapp .',
  userId: 'user-123',
  reason: '构建应用容器',
});

console.log(`请求ID：${request.id}`);
console.log(`状态：${request.status}`);

// 等待审批
const approved = await perms.waitForApproval(request.id, {
  timeoutMs: 60000,
});

if (approved) {
  console.log('已批准！执行中...');
}

批准/拒绝

// 批准请求
await perms.approve({
  requestId: 'req-123',
  approvedBy: 'admin-user',
  note: '看起来安全',
});

// 拒绝请求
await perms.reject({
  requestId: 'req-123',
  rejectedBy: 'admin-user',
  reason: '命令太宽泛',
});

列出待审批

// 获取待审批
const pending = await perms.listPending();

for (const req of pending) {
  console.log(`[${req.id}] ${req.command}`);
  console.log(`  用户：${req.userId}`);
  console.log(`  理由：${req.reason}`);
  console.log(`  请求时间：${req.createdAt}`);
}

添加规则

// 添加允许规则
await perms.addRule({
  type: 'allow',
  pattern: 'npm run *',
  description: '允许npm脚本',
  createdBy: 'admin',
});

// 添加阻止规则
await perms.addRule({
  type: 'block',
  pattern: 'rm -rf /',
  description: '防止根目录删除',
  createdBy: 'admin',
});

// 列出规则
const rules = await perms.listRules();

for (const rule of rules) {
  console.log(`${rule.type}: ${rule.pattern}`);
}

// 移除规则
await perms.removeRule('rule-id');

工具策略

// 为代理设置工具策略
await perms.setToolPolicy({
  agentId: 'trading',
  allow: ['execute', 'portfolio', 'markets'],
  deny: ['browser', 'docker', 'exec'],
});

// 检查工具访问权限
const canUse = perms.isToolAllowed('trading', 'execute');

// 获取代理允许的工具
const tools = perms.getAllowedTools('trading');

---

安全模式

模式	行为
deny	阻止所有执行命令
allowlist	只允许明确允许的命令
blocklist	阻止特定模式，允许其余
full	允许全部（危险！）

---

模式语法

模式	匹配
npm install	精确命令
npm *	npm带任意参数
git status	精确命令
* --version	带有–version的任意命令

---

内置安全规则

无论模式如何，总是被阻止：

• rm -rf /
• sudo rm -rf
• chmod 777 /
• :(){ :|:& };: （fork bomb）
• 带有shell注入模式的命令

---

CLI命令

# 列出权限规则
clodds permissions list

# 添加允许模式
clodds permissions allow "npm run *"

# 查看待审批
clodds permissions pending

# 批准请求
clodds permissions approve req-123

---

最佳实践

1. 使用允许列表模式 — 最安全，明确权限
2. 定期审查待审批 — 不要让请求堆积
3. 具体模式 — npm install lodash 优于 npm *
4. 审计历史 — 审查已批准的内容
5. 工具策略 — 限制代理工具访问