nuxt-app/docs/superpowers/specs/2026-08-06-agent-tool-admin-only-design.md

Agent 工具执行权限控制设计

背景

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

目标

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

设计

数据库变更

在 agent_tools 表新增 admin_only 字段：

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	表单字段
迁移文件（自动生成）	新增