API 参考：Agent、MCP 与技能
管理智能体、MCP 服务及其凭据、技能和资源收藏。智能体的工具范围与调用审批配置通过本组接口维护。
Agent（/api/v1/agents）
读：Viewer+（API key read_agents/manage_agents/chat/full）；写：创建者 OR Admin+（API key manage_agents/full）；内置 Agent（is_builtin=true）始终 Admin+。
GET /api/v1/agents/placeholders
用途：提示词占位符定义（须先于 /:id 注册）。权限：Viewer+。
响应：200 {"success":true,"data":{"all":{...},"system_prompt":{...},"agent_system_prompt":{...},"context_template":{...},"rewrite_system_prompt":{...},"rewrite_prompt":{...},"fallback_prompt":{...}}}
curl $BASE/api/v1/agents/placeholders -H "Authorization: Bearer $TOKEN"GET /api/v1/agents/type-presets
用途：智能推理 Agent 类型预设（rag-qa / wiki-qa / hybrid / custom 等）。权限：Viewer+。
响应：200 {"success":true,"data":[{type,system_prompt,allowed_tools,kb_compatibility}]}
curl $BASE/api/v1/agents/type-presets -H "Authorization: Bearer $TOKEN"POST /api/v1/agents
用途：创建自定义 Agent。权限：Contributor+。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是（binding:"required"） | 名称 |
description | string | 否 | 描述 |
avatar | string | 否 | 头像/emoji |
config | object | 否 | Agent 配置（types.CustomAgentConfig，见下） |
config 主要字段：agent_mode（quick-answer/smart-reasoning）、agent_type（rag-qa/wiki-qa/hybrid-rag-wiki/data-analysis/custom）、system_prompt、model_id、temperature（0-2，非法返回 code 2103）、max_iterations（1-20，非法返回 code 2102）、allowed_tools（智能推理必填至少一个，code 2101）、mcp_selection_mode/mcp_services、skills_selection_mode、kb_selection_mode/knowledge_bases、web_search_enabled、question_suggestions 等（完整定义见 internal/types/custom_agent.go）。
响应：201 {"success":true,"data":{id,name,description,avatar,is_builtin,created_by,config,creator_name,...}}
curl -X POST $BASE/api/v1/agents -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"售后助手","config":{"agent_mode":"quick-answer","kb_selection_mode":"selected","knowledge_bases":["kb-1"]}}'GET /api/v1/agents
用途：Agent 列表（含内置）。权限：Viewer+。查询参数：creator（mine/others，可选）。
响应：200 {"success":true,"data":[Agent],"disabled_own_agent_ids":[...]}
curl $BASE/api/v1/agents -H "X-API-Key: $API_KEY"GET /api/v1/agents/:id
用途：Agent 详情。权限：Viewer+。
响应：200 {"success":true,"data":{Agent}}
curl $BASE/api/v1/agents/agent-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/agents/:id
用途：更新 Agent。权限：创建者 OR Admin+。请求体：name/description/avatar/config（均可选）。
响应：200 {"success":true,"data":{Agent}}
curl -X PUT $BASE/api/v1/agents/agent-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"description":"更新描述"}'DELETE /api/v1/agents/:id
用途：删除 Agent。权限：创建者 OR Admin+。
响应：200 {"success":true,"message":"Agent deleted successfully"}
curl -X DELETE $BASE/api/v1/agents/agent-1 -H "Authorization: Bearer $TOKEN"POST /api/v1/agents/:id/copy
用途：复制 Agent（副本归调用者）。权限：Contributor+。无请求体。
响应：201 {"success":true,"data":{新 Agent}}
curl -X POST $BASE/api/v1/agents/agent-1/copy -H "Authorization: Bearer $TOKEN"GET /api/v1/agents/:id/suggested-questions
用途：Agent 起始建议问题（注册在组外以避免与 /agents/:id/shares 冲突）。权限：Viewer+；API key read_agents/manage_agents/chat/full。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
knowledge_base_ids | string | 否 | 逗号分隔 KB |
knowledge_ids | string | 否 | 逗号分隔知识 ID |
tag_scopes | string | 否 | JSON 数组的标签范围 |
limit | int | 否 | 上限 30 |
响应：200 {"success":true,"data":{"questions":[{question,source,knowledge_base_id}]}}
curl "$BASE/api/v1/agents/agent-1/suggested-questions?limit=6" -H "X-API-Key: $API_KEY"MCP 服务（/api/v1/mcp-services）
空间级外部工具服务集成。读：Viewer+；写/测试/审批策略：Admin+。API key：manage_mcp_services/full。Handler: internal/handler/mcp_service.go
POST /api/v1/mcp-services
用途：创建 MCP 服务。权限：Admin+。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 名称 |
description | string | 否 | 旧版描述，兼容保留；管理界面统一编辑 usage_instructions |
usage_instructions | string | 配置完成时必填 | 服务用途、适用场景和关键约束；第一步仅保存连接时可省略 |
enabled | bool | 否 | 启用 |
transport_type | string | 是 | sse / http-streamable / stdio |
url | *string | 否 | 服务 URL（SSE/HTTP） |
headers | map[string]string | 否 | HTTP 头 |
auth_config | object | 否 | auth_type(api_key/bearer/oauth)、api_key_header、custom_headers、scopes、auth_server_metadata_url（密钥走 credentials 子资源） |
advanced_config | object | 否 | 超时/重试 |
stdio_config | object | 否 | stdio 命令与参数 |
env_vars | map[string]string | 否 | 环境变量 |
响应：200 {"success":true,"data":{MCPServiceResponse}}（含 credentials:{api_key:{configured},token:{configured}}）
curl -X POST $BASE/api/v1/mcp-services -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"github","transport_type":"sse","url":"https://mcp.example.com/sse"}'GET /api/v1/mcp-services
用途：MCP 服务列表。权限：Viewer+。响应：200 {"success":true,"data":[MCPServiceResponse]}
curl $BASE/api/v1/mcp-services -H "Authorization: Bearer $TOKEN"GET /api/v1/mcp-services/:id
用途：详情。权限：Viewer+。响应：200 {"success":true,"data":{MCPServiceResponse}}
curl $BASE/api/v1/mcp-services/mcp-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/mcp-services/:id
用途：部分更新（map 语义；auth_config 中不可携带 api_key/token）。权限：Admin+。字段同创建（均可选）。
提交 usage_instructions 时必须为去除首尾空白后非空的字符串，最长 16000 字符。仅修改连接或启用状态时可省略该字段，原值保持不变。
响应：200 {"success":true,"data":{MCPServiceResponse}}
curl -X PUT $BASE/api/v1/mcp-services/mcp-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"enabled":false}'POST /api/v1/mcp-services/:id/usage-instructions/generate
用途：根据已同步、未过期的 MCP 工具目录生成精简使用说明。权限：Admin+；API key 需要 manage_mcp_services 或 full。
请求：{"language":"zh-CN"}。支持 zh-CN、en-US、ja-JP、ko-KR、ru-RU，默认中文。
优先使用空间默认的可用对话模型，否则使用首个可用对话模型。输入包括服务名称、服务端说明和已启用工具的名称、描述；OAuth 目录沿用当前用户的授权范围。不会连接 MCP、调用工具或自动保存生成结果。
响应：200 {"success":true,"data":{"usage_instructions":"按模块和时间范围查询远程日志；已有查询 ID 时读取对应日志。"}}。生成目标为 2–3 句简短说明，最多 500 字符；用户可编辑后通过 PUT 保存。目录未同步、过期、无启用工具或无可用对话模型时返回 400。
DELETE /api/v1/mcp-services/:id
用途：删除。权限：Admin+。响应：200 {"success":true,"message":"MCP service deleted successfully"}
curl -X DELETE $BASE/api/v1/mcp-services/mcp-1 -H "Authorization: Bearer $TOKEN"POST /api/v1/mcp-services/:id/test
用途：连接测试（探测外部服务）。权限：Admin+。响应：200 {"success":true,"data":{"success","message","oauth_required","tools":[...],"resources":[...]}}
curl -X POST $BASE/api/v1/mcp-services/mcp-1/test -H "Authorization: Bearer $TOKEN"GET /api/v1/mcp-services/:id/tools
用途：工具列表。权限：Viewer+。响应：200 {"success":true,"data":[{name,description,inputSchema,require_approval}]}
curl $BASE/api/v1/mcp-services/mcp-1/tools -H "Authorization: Bearer $TOKEN"GET /api/v1/mcp-services/:id/resources
用途：资源列表。权限：Viewer+。响应：200 {"success":true,"data":[{uri,name,description,mimeType}]}
curl $BASE/api/v1/mcp-services/mcp-1/resources -H "Authorization: Bearer $TOKEN"PUT /api/v1/mcp-services/:id/credentials
用途：设置密钥（api_key/token，指针字段，省略保留）。权限：Admin+。Handler: internal/handler/mcp_credentials.go
响应：200 {"success":true,"data":{"fields":{"api_key":{"configured"},"token":{"configured"}}}}
curl -X PUT $BASE/api/v1/mcp-services/mcp-1/credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"token":"ghp_..."}'DELETE /api/v1/mcp-services/:id/credentials/:field
用途：删除凭证字段（api_key 或 token）。权限：Admin+。响应：204。
curl -X DELETE $BASE/api/v1/mcp-services/mcp-1/credentials/token -H "Authorization: Bearer $TOKEN"GET /api/v1/mcp-services/:id/tool-approvals
用途：工具启停与人工审批策略列表。权限：Viewer+。响应：200 {"success":true,"data":[{service_id,tool_name,require_approval,enabled,...}]}
curl $BASE/api/v1/mcp-services/mcp-1/tool-approvals -H "Authorization: Bearer $TOKEN"PUT /api/v1/mcp-services/:id/tool-approvals/:tool_name
用途：更新某工具的 enabled（启停）和 require_approval（人工审批）。权限：Admin+。两者至少提供一个，省略的字段保持原值；无记录默认启用且不要求审批。
响应：200 {"success":true}
curl -X PUT $BASE/api/v1/mcp-services/mcp-1/tool-approvals/create_issue \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"require_approval":true}'MCP OAuth
Handler: internal/handler/mcp_oauth.go
GET /api/v1/mcp-oauth/callback
用途：第三方 OAuth 授权回调（免认证，靠单次 state 参数认证；注册在 /mcp-services 组之外）。查询参数：code、state、error。
响应：302 重定向到前端（成功 #mcp_oauth_result=success，失败 #mcp_oauth_error=<code>）。
curl -i "$BASE/api/v1/mcp-oauth/callback?code=xxx&state=yyy"POST /api/v1/mcp-services/:id/oauth/authorize-url
用途：生成用户级授权 URL。权限：Viewer+。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
redirect_uri | string | 是 | 后端回调 URL（绝对地址） |
frontend_redirect | string | 否 | 回调后前端跳转（默认 /） |
响应：200 {"success":true,"data":{"authorization_url","authorization_attempt"}}
curl -X POST $BASE/api/v1/mcp-services/mcp-1/oauth/authorize-url -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"redirect_uri":"'$BASE'/api/v1/mcp-oauth/callback"}'GET /api/v1/mcp-services/:id/oauth/status
用途：查询本人授权状态。权限：Viewer+。查询参数：authorization_attempt（可选）。
响应：200 {"success":true,"data":{"authorized","state":"authorized|pending","refresh_available","expires_at"}}
curl $BASE/api/v1/mcp-services/mcp-1/oauth/status -H "Authorization: Bearer $TOKEN"DELETE /api/v1/mcp-services/:id/oauth/token
用途：吊销本人 OAuth token。权限：Viewer+。响应：204。
curl -X DELETE $BASE/api/v1/mcp-services/mcp-1/oauth/token -H "Authorization: Bearer $TOKEN"Agent 运行时交互（/api/v1/agent）
对话中的人工审批与 OAuth 恢复；权限均 Viewer+（发起会话的人才有上下文），API key 默认拒绝。
POST /api/v1/agent/tool-approvals/:pending_id
用途：裁决待审批的工具调用。Handler: internal/handler/mcp_service.go 的 ResolveToolApproval。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
decision | string | 是（binding:"required"） | approve / reject |
modified_args | JSON | 否 | 修改后的工具参数 |
reason | string | 否 | 理由 |
响应：200 {"success":true}
curl -X POST $BASE/api/v1/agent/tool-approvals/p-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"decision":"approve"}'POST /api/v1/agent/mcp-oauth-resolutions/:pending_id
用途：恢复因 MCP OAuth 暂停的 Agent 运行。Handler: internal/handler/mcp_oauth.go
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
service_id | string | 是（binding:"required"） | MCP 服务 ID |
decision | string | 否 | authorize（默认）/ cancel |
响应：200 {"success":true}
curl -X POST $BASE/api/v1/agent/mcp-oauth-resolutions/p-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"service_id":"mcp-1"}'POST /api/v1/agent/mcp-oauth-resolutions/:pending_id/cancel
用途：取消暂停中的 OAuth 流程。无请求体。
响应：200 {"success":true}
curl -X POST $BASE/api/v1/agent/mcp-oauth-resolutions/p-1/cancel -H "Authorization: Bearer $TOKEN"技能、沙箱与个人变量
GET /api/v1/skills?sandbox_config_id=... 返回指定配置下可用技能的名称/说明及 skills_available。目录收录、安装、模板、进度、文件与个人变量的完整接口见沙箱与技能 API。
智能体 config 增加 sandbox_config_id；与 skills_selection_mode、selected_skills 一起决定可用技能。shell/文件工具按后端能力注册，旧 read_skill / execute_skill_script 不再注册。
长期记忆
智能体 config 的 memory_enabled 为 nil 时继承空间，false 禁用本智能体的记忆读写。个人管理、主题/文档偏好、导出与立即整理见长期记忆 API，使用步骤见跨会话长期记忆。
用户收藏（/api/v1/user/favorites）
按用户维度存储（非资源创建者维度）；权限均 Viewer+，仅 JWT（API key 默认拒绝）。Handler: internal/handler/user_resource_favorite.go
GET /api/v1/user/favorites
用途：收藏列表。查询参数：type（必填，kb 或 agent）。
响应：200 {"success":true,"data":[{type,id,created_at}]}
curl "$BASE/api/v1/user/favorites?type=kb" -H "Authorization: Bearer $TOKEN"POST /api/v1/user/favorites
用途：添加收藏。请求体：{"type":"kb|agent","id":"<资源ID>"}（均必填）。
响应：200 {"success":true}
curl -X POST $BASE/api/v1/user/favorites -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"type":"kb","id":"kb-1"}'DELETE /api/v1/user/favorites/:type/:id
用途：取消收藏。路径参数：type、id。
响应：200 {"success":true}
curl -X DELETE $BASE/api/v1/user/favorites/kb/kb-1 -H "Authorization: Bearer $TOKEN"实现参考
路由注册：internal/router/router.go 的 RegisterCustomAgentRoutes、RegisterMCPServiceRoutes、RegisterSkillRoutes、RegisterUserFavoriteRoutes。Handler：internal/handler/custom_agent.go、internal/handler/mcp_service.go、internal/handler/mcp_credentials.go、internal/handler/mcp_oauth.go、internal/handler/skill_handler.go、internal/handler/user_resource_favorite.go。