WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

2026-09-22 16:19:06 +08:00
commit f7fc992f57
3929 changed files with 1006607 additions and 0 deletions
@@ -0,0 +1,42 @@
+# MCP 工具人工审核（危险调用）
+
+对应需求：智能体调用 MCP 工具前可中断，待人工确认后再执行（GitHub #1173）。
+
+## 行为说明
+
+1. 在 **设置 → MCP** 中连接测试成功后，在工具列表上打开 **「需人工审核」** 开关，即可为该工具打标。
+2. Agent 运行时若即将调用已打标的工具，会推送 `tool_approval_required` 事件，对话界面展示审批卡片（可编辑 JSON 参数）。
+3. 用户 **通过** 或 **拒绝** 后，后端恢复执行；拒绝时工具返回错误信息给模型，不会调用远端 MCP。
+4. 若超时未处理（默认 10 分钟，可通过配置 `agent.tool_approval_timeout_seconds` 调整），视为拒绝。
+
+## 配置示例
+
+任选一种：
+
+**1. config.yaml**
+
+```yaml
+agent:
+  tool_approval_timeout_seconds: 600  # 可选，默认 600（秒）
+```
+
+**2. 环境变量**（优先级高于 yaml）
+
+```bash
+# 支持纯秒数或 Go duration（30s / 5m / 1h）
+WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT=600
+```
+
+## API
+
+- `GET /api/v1/mcp-services/:id/tool-approvals` — 列出已保存的审核配置  
+- `PUT /api/v1/mcp-services/:id/tool-approvals/:tool_name` — 设置某工具是否需审核（`{"require_approval": true}`）  
+- `POST /api/v1/agent/tool-approvals/:pending_id` — 在审批卡片中提交结果  
+  - body: `{"decision":"approve"|"reject","modified_args":{...}可选,"reason":"..."可选}`
+
+## 部署与限制
+
+- **审批等待状态保存在进程内存** 中：`pending_id` 仅对当前实例有效；进程重启后进行中的等待会失败（表现为拒绝/取消）。
+- **多副本部署**：当配置了 `REDIS_ADDR` 时，`Resolve` 会通过 Redis Pub/Sub（频道 `weknora:mcp_approval:resolve`）跨实例转发，因此 SSE 与提交审批的 HTTP 请求落到不同实例也能正确唤醒等待者；未配置 Redis 时退化为单机模式，需要使用会话粘滞（sticky session）。
+- **审批等待不会被工具默认 60s 超时取消**：审批阶段使用 round 级别的 ctx（不带 `defaultToolExecTimeout`），仅受 `agent.tool_approval_timeout_seconds` 与请求级取消控制。
+- 安全边界：审核通过后的参数仍由当前登录空间提交；请仅在可信环境下授予「通过」权限。