feat(api): Tool Invoke API + Naga Scoped Token 鉴权系统

config.toml.example

@@ -733,6 +733,24 @@ auth_key = "changeme"
 # zh: 是否暴露 OpenAPI 文档（/openapi.json）。
 # en: Expose OpenAPI document (/openapi.json).
 openapi_enabled = true
+# zh: 是否启用工具调用 API（POST /api/v1/tools/invoke）。
+# en: Enable tool invocation API (POST /api/v1/tools/invoke).
+tool_invoke_enabled = false
+# zh: 暴露的工具范围。可选 "tools"、"toolsets"、"tools+toolsets"、"agents"、"all"。
+# en: Tool exposure scope. Options: "tools", "toolsets", "tools+toolsets", "agents", "all".
+tool_invoke_expose = "tools+toolsets"
+# zh: 工具白名单（非空时覆盖 expose 规则）。
+# en: Tool allowlist (overrides expose when non-empty).
+tool_invoke_allowlist = []
+# zh: 工具黑名单（始终优先于白名单和 expose）。
+# en: Tool denylist (always takes priority).
+tool_invoke_denylist = []
+# zh: 单次工具调用超时（秒）。
+# en: Per-invocation timeout in seconds.
+tool_invoke_timeout = 120
+# zh: 回调请求超时（秒）。
+# en: Callback request timeout in seconds.
+tool_invoke_callback_timeout = 10
 
 # zh: 认知记忆系统配置。启用后需配置 [models.embedding]，其余参数均有合理默认值。
 # en: Cognitive memory system. Requires [models.embedding] when enabled. All other params have sensible defaults.
@@ -837,3 +855,33 @@ failed_cleanup_interval = 100
 # zh: 单个任务最大自动重试次数（超过后移入 failed，0=不重试）。
 # en: Max auto-retries per job before moving to failed (0=no retry).
 job_max_retries = 3
+
+# zh: Naga 外部网关集成配置。
+# zh: 开关分层：
+# zh:   - [features].nagaagent_mode_enabled — 总开关，控制 AI 侧行为（提示词切换、工具暴露）
+# zh:   - [naga].enabled — 子开关，控制外部网关集成（回调 API、/naga 命令、绑定管理）
+# zh: 仅当两者均为 true 时，外部网关集成才生效。
+# zh: 若只需 NagaAgent 解答能力而不需要外部回调联动，可只开启 nagaagent_mode_enabled。
+# zh: ⚠️ 此功能面向与 NagaAgent 对接的高级场景，普通用户不建议开启。
+# en: Naga external gateway integration settings.
+# en: Switch hierarchy:
+# en:   - [features].nagaagent_mode_enabled — master switch for AI behavior (prompt, tool exposure)
+# en:   - [naga].enabled — sub-switch for external gateway (callback API, /naga command, bindings)
+# en: Both must be true for external gateway integration to work.
+# en: To get NagaAgent answering without external callbacks, only enable nagaagent_mode_enabled.
+# en: ⚠️ Advanced feature for NagaAgent integration. Not recommended for regular users.
+[naga]
+# zh: 是否启用外部网关集成（回调 API、/naga 命令、绑定管理）。
+# zh: 需同时开启 [features].nagaagent_mode_enabled 才生效。
+# en: Enable external gateway integration (callback API, /naga command, bindings).
+# en: Requires [features].nagaagent_mode_enabled = true to take effect.
+enabled = false
+# zh: Naga 服务器 API 地址。
+# en: Naga server API URL.
+api_url = ""
+# zh: 双方共享密钥（Undefined ↔ Naga 身份验证）。
+# en: Shared secret key for authentication between Undefined and Naga.
+api_key = ""
+# zh: Naga 服务群聊名单：绑定/回调群发仅限这些群。
+# en: Allowed groups for Naga binding and group callback delivery.
+allowed_groups = []

docs/configuration.md

@@ -635,6 +635,43 @@ model_name = "gpt-4o-mini"
 
 ---
 
+### 4.25 `[naga]` Naga 外部网关集成
+
+> **⚠️ 此功能面向与 NagaAgent 对接的高级场景，普通用户不建议开启。**
+
+启用后允许 NagaAgent 通过绑定审批机制向 QQ 群/用户发送回调消息。鉴权采用双层模型：共享密钥 `api_key` 验证服务器身份 + 每个绑定独立的 scoped token 验证调用权限。
+
+**开关分层**：
+
+| 开关 | 控制范围 | 默认值 |
+|------|---------|--------|
+| `[features].nagaagent_mode_enabled` | 总开关：AI 侧行为（提示词切换、工具暴露） | `false` |
+| `[naga].enabled` | 子开关：外部网关集成（回调 API、`/naga` 命令、绑定管理） | `false` |
+
+- 仅当两者均为 `true` 时，外部网关集成生效（API 端点注册、`/naga` 命令可用）
+- 若只需 NagaAgent 解答能力而不需要外部回调联动，可只开启 `nagaagent_mode_enabled`
+- `nagaagent_mode_enabled = false` 时强制关闭所有 Naga 功能，无论 `naga.enabled` 值
+
+| 字段 | 默认值 | 说明 | 约束/回退 |
+|---|---:|---|---|
+| `enabled` | `false` | 是否启用外部网关集成 | 需同时开启 `nagaagent_mode_enabled` |
+| `api_url` | `""` | Naga 服务器 API 地址 | 为空时 token 同步/删除操作跳过 |
+| `api_key` | `""` | Undefined ↔ Naga 共享密钥 | 回调端点通过 `Authorization: Bearer` 校验 |
+| `allowed_groups` | `[]` | Naga 服务群聊名单 | 绑定命令和回调群发仅限名单内的群 |
+
+**作用域规则**：
+- 群聊场景下，所有 `/naga` 子命令仅在 `allowed_groups` 内的群可用
+- 私聊场景不受 `allowed_groups` 限制
+- 回调群发仅发到绑定时的群（该群须仍在 `allowed_groups` 内）
+- 回调私聊只需开关开启，不受 `allowed_groups` 限制
+- `/api/v1/naga/*` 端点仅在两个开关均开启时注册
+
+**数据存储**：绑定数据持久化在 `data/naga_bindings.json`，Unix 下自动 `chmod 600`。
+
+`naga.*` 变更需要重启进程才能生效。
+
+---
+
 ## 5. 热更新与重启边界
 
 ### 5.1 热更新监听对象
@@ -655,6 +692,7 @@ model_name = "gpt-4o-mini"
 - `webui.port`
 - `webui.password`
 - `api.*`（`enabled/host/port/auth_key/openapi_enabled`）
+- `naga.*`（`enabled/api_url/api_key/allowed_groups`）
 
 ### 5.3 明确“会执行热应用”的字段
 - 模型发车间隔 / 模型名 / 模型池变更（队列间隔刷新）