AI 小助手

每个页面右下角有一个 AI 小助手（快捷键 ⌘ / Ctrl + J）：用自然语言提问，它会查找系统接口、读取数据回答你；需要修改数据时，它会把要执行的操作列出来，你点「允许执行」之后才会执行。它始终以你的身份操作，你没有权限的事它也做不了。

打开

小助手默认关闭。先在「系统管理 → 系统配置 → 系统设置 → AI」里配置好模型（见 配置项 → AI 模型），再打开同一页签里的「启用 AI 小助手」（ai.assistant_enabled）。模型配置好之前这个开关不能打开：需要 API Key 和模型名，OpenAI 兼容类服务还需要接口地址。

打开后，所有登录用户的页面右下角都会出现小助手按钮（其他已打开页面的用户刷新后可见）；关闭后按钮随之消失，接口立即返回 403。

能做什么

• 回答问题：系统怎么用、某个页面能做什么。小助手知道你当前所在的页面
• 查询数据：「系统里有多少个启用的用户？」「列出技术部的成员」「最近 10 条操作日志」
• 修改数据：「把部门「测试部」改名为「质量部」」「给张伟发一条通知」。每次写操作都会显示一张确认卡片：一句说明、请求方法和路径、要提交的数据，点「允许执行」才执行，点「拒绝」则什么都不做

对话保存在当前浏览器标签页里，最多保留最近 40 条消息（刷新页面不丢失，关闭标签页后清空），点面板顶部的「新对话」可以清空。

安全边界

• 以你的身份调用接口：小助手的每次调用都经过和页面相同的接口，带着你的登录状态，所以权限、数据权限、演示模式的限制、限流都照常生效，写操作照常记入操作日志（用户为你本人，User-Agent 为 castor-kit-assistant）
• 写操作逐条确认：新增、修改、删除都要你在确认卡片上点「允许执行」。确认请求由服务端签名（密钥由 SECRET_KEY 派生），浏览器里伪造的「已允许」会被拒绝
• 不开放的接口：你自己的账号安全（个人资料与密码、两步验证、登录会话、API Token）、修改系统设置、新建 / 修改 / 删除 Webhook 以及查看其密钥、导入导出、文件上传下载、其他 AI 接口以及小助手自己。这些请在页面上操作
• 受保护的对象：超级管理员账号（不能修改、停用、删除）、超级管理员角色、授予超级管理员角色，以及你自己的账号。这类请求小助手会直接说明做不了，不会弹出确认卡片；即使后端接口本身允许（例如超级管理员操作另一个超级管理员），也要在页面上操作
• 管理其他用户照常可以：有用户管理权限时，可以让它新建用户（含初始密码）、重置密码、分配角色，同样要在确认卡片上允许。密码只用你给出的，强度按系统的密码规则校验。注意：写在对话里的密码会发给模型服务，也会留在这个标签页的对话记录里；确认卡片和操作日志中不显示明文。介意的话请在页面上设置密码
• 接口返回的内容只当数据：记录里出现的「忽略之前的规则」之类的文字不会被当作指令；结果太大时（超过 8000 个字符）会按结构精简：长文本截短、记录里嵌套的列表只留几项、放不下时只保留前面的记录，并告诉模型哪些被省略了
• 数据会发给模型服务：小助手查询到的数据会作为上下文发送给你配置的 AI 服务，请按你的数据合规要求选择模型服务
• API Token 不能调用小助手接口；演示模式下它计入 AI 调用额度，每条消息最多调用 4 轮工具（平时 8 轮）

让自己的模块也能被小助手用上

小助手从两处了解系统的接口：

1. 服务启动时实际注册的 /api/admin/... 路由
2. docs/apifox-full.openapi.json 里对这些路由的说明（summary、description、查询参数、请求体字段）

pnpm scaffold 生成模块时已经写好了它的接口文档，summary 是「设备台账列表」这样的中文。你手动新增或修改的路由，运行 pnpm openapi:generate 补出骨架条目，再按 AGENTS.md「OpenAPI writing rules」补全（见 AI 驱动开发）。没有文档的路由小助手也能调用，只是很难被它找到。

如果某些接口不应该让小助手调用，把路径规则加到 apps/api/src/modules/admin/assistant/catalog.ts 的 ASSISTANT_DENIED。