# Agent 工具执行权限控制设计

## 背景

当前 Agent 工具框架中，所有 `enabled = 1` 的工具对任何登录用户都可见可调用。某些敏感工具（如 `fetch`，可发起外部 HTTP 请求）应限制为仅管理员可在 LLM 对话中调用，普通用户不应感知到这些工具的存在。

## 目标

- 在工具级别增加「仅管理员可用」开关
- 普通用户对话时，admin-only 工具完全隐藏（不出现在工具列表中，LLM 不知道其存在）
- 管理员对话时，所有 enabled 工具正常可用
- 管理后台显示权限标记，支持快速切换

## 设计

### 数据库变更

在 `agent_tools` 表新增 `admin_only` 字段：

```typescript
adminOnly: integer("admin_only").default(0).notNull()
```

- `0`：所有登录用户可用（默认）
- `1`：仅管理员可在 LLM 对话中调用

需执行 `db:generate` + `db:migrate` 生成并应用迁移。

### Service 层变更（`server/service/agent-tool/index.ts`）

1. **接口扩展**：`CreateAgentToolInput` 和 `UpdateAgentToolInput` 新增 `adminOnly?: boolean` 字段

2. **CRUD 函数**：`createAgentTool` 和 `updateAgentTool` 处理 `adminOnly` 字段（`boolean → 0/1`）

3. **`getEnabledToolsForLlm(userId, userRole)`**：
   - 新增 `userRole: UserRole | null` 参数
   - 查询 enabled=1 的工具后，若 `userRole !== "admin"`，过滤掉 `adminOnly = 1` 的工具
   - 过滤在内存中进行（数据量小，无需额外 DB 条件）

4. **`getEnabledToolInfos(userRole)`**：
   - 新增 `userRole: UserRole | null` 参数
   - 同理过滤 admin-only 工具

### API 层变更

1. **`server/api/llm/chat/index.post.ts`**：
   - `getEnabledToolsForLlm(user.id)` → `getEnabledToolsForLlm(user.id, user.role)`

2. **`server/api/llm/chat/tools.get.ts`**：
   - 获取当前用户，`getEnabledToolInfos()` → `getEnabledToolInfos(user?.role ?? null)`

3. **`server/api/agent-tools/index.post.ts`** 和 **`[id].put.ts`**：
   - 请求体新增 `adminOnly` 字段透传到 service 层

### 前端变更

1. **`app/pages/admin/agent-tools/index.vue`**：
   - `AgentToolRow` 接口新增 `adminOnly: number`
   - 表格新增「权限」列，显示「仅管理员」或「所有人」标签
   - 新增 `handleToggleAdminOnly` 函数，快速切换 admin_only 状态

2. **`app/components/AgentToolFormModal.vue`**：
   - `form` 新增 `adminOnly` 字段
   - 新增「仅管理员可用」复选框
   - 保存时 body 新增 `adminOnly` 字段

### 数据流

```
管理员后台:  创建/编辑工具 → 勾选「仅管理员可用」→ adminOnly=1 存入 DB

普通用户对话: /api/llm/chat → getEnabledToolsForLlm(userId, "user")
              → 查询 enabled=1 → 过滤 adminOnly=1 → 普通用户不可见

管理员对话:   /api/llm/chat → getEnabledToolsForLlm(userId, "admin")
              → 查询 enabled=1 → 不过滤 → 管理员可用全部工具
```

### 不改动的部分

- 工具 CRUD 管理 API 仍然是 admin-only（已有 `requireAdmin`）
- `executeAgentTool` 独立执行函数不加权限检查（仅在 admin 调试 API 中使用）
- `ToolContext` 不变（不需要传 role 到执行器层）
- `needsApproval` 审批机制不变（与 admin_only 正交：admin_only 控制可见性，needsApproval 控制执行确认）

## 涉及文件清单

| 文件 | 变更类型 |
|------|----------|
| `packages/drizzle-pkg/lib/schema/agent-tool.ts` | 新增字段 |
| `server/service/agent-tool/index.ts` | 接口+函数扩展 |
| `server/api/llm/chat/index.post.ts` | 传参变更 |
| `server/api/llm/chat/tools.get.ts` | 传参变更 |
| `server/api/agent-tools/index.post.ts` | 透传字段 |
| `server/api/agent-tools/[id].put.ts` | 透传字段 |
| `app/pages/admin/agent-tools/index.vue` | 表格+切换 |
| `app/components/AgentToolFormModal.vue` | 表单字段 |
| 迁移文件（自动生成） | 新增 |