{ "openapi": "3.1.0", "info": { "title": "AI 知识宇宙（K-World）API", "version": "0.1.0", "description": "用于人工和 AI 审计的完整 API 目录。读取公开，写入需要编辑会话。" }, "servers": [ { "url": "https://world.yuanxuntech.com" } ], "tags": [ { "name": "system" }, { "name": "model" }, { "name": "security" }, { "name": "accounts" }, { "name": "audit" }, { "name": "admin" }, { "name": "credits" }, { "name": "settings" }, { "name": "billing" }, { "name": "organizations" }, { "name": "teams" }, { "name": "enterprise" }, { "name": "api-keys" }, { "name": "destructive" }, { "name": "webhook" }, { "name": "research" }, { "name": "collaboration" }, { "name": "approval" }, { "name": "agents" }, { "name": "sources" }, { "name": "search" }, { "name": "universes" }, { "name": "build" }, { "name": "chat" }, { "name": "study" }, { "name": "evidence" }, { "name": "entities" }, { "name": "write" }, { "name": "permissions" }, { "name": "fact-checking" }, { "name": "credibility" }, { "name": "review" }, { "name": "resolution" }, { "name": "incremental" }, { "name": "reports" }, { "name": "community" }, { "name": "market" }, { "name": "personalization" }, { "name": "jobs" } ], "paths": { "/api/health": { "get": { "operationId": "getHealth", "summary": "读取服务健康状态、运行时间和模型公开配置。", "tags": [ "system" ], "security": [], "parameters": [], "responses": { "200": { "description": "服务可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "always" } }, "/api/model/status": { "get": { "operationId": "getModelStatus", "summary": "检查模型提供方、模式和缺少的配置项，不返回 API Key。", "tags": [ "system", "model" ], "security": [], "parameters": [], "responses": { "200": { "description": "模型公开状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelStatus" } } } } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "always" } }, "/api/editor/session": { "get": { "operationId": "getEditorSession", "summary": "检查写操作是否启用以及当前浏览器是否拥有编辑会话。", "tags": [ "security" ], "security": [], "parameters": [], "responses": { "200": { "description": "编辑模式状态。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "always" } }, "/api/accounts/session": { "get": { "operationId": "getAccountSession", "summary": "读取当前账号、套餐、额度和注册开关。", "tags": [ "accounts" ], "security": [], "parameters": [], "responses": { "200": { "description": "账号会话与套餐信息。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "always" } }, "/api/accounts/register": { "post": { "operationId": "registerAccount", "summary": "注册商业账号并创建免费套餐会话。", "tags": [ "accounts" ], "security": [], "parameters": [], "responses": { "201": { "description": "账号已创建。公开注册只接受邮箱，提交的 username 会被忽略。" }, "403": { "description": "注册已关闭（REGISTRATION_CLOSED）。" }, "409": { "description": "邮箱已注册。" } }, "x-k-world-risk": "auth", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "name": "研究用户", "email": "user@example.com", "password": "strong-password" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/accounts/login": { "post": { "operationId": "loginAccount", "summary": "登录账号并创建 30 天 HttpOnly 会话。identifier 可填邮箱或用户名，username 字段仅作兼容。", "tags": [ "accounts" ], "security": [], "parameters": [], "responses": { "200": { "description": "登录成功。" }, "401": { "description": "凭据错误。" }, "403": { "description": "账号已被停用（ACCOUNT_DISABLED）。" } }, "x-k-world-risk": "auth", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "identifier": "user@example.com 或 admin", "password": "strong-password" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/accounts/password": { "post": { "operationId": "changeOwnPassword", "summary": "修改自己的密码：必须提供当前密码，成功后吊销该账号的其它会话，保留当前会话。", "tags": [ "accounts", "security" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "密码已更新，返回 revokedSessions 数量。" }, "400": { "description": "新密码过短、过长或与当前密码相同。" }, "401": { "description": "未登录，或当前密码不正确。" }, "429": { "description": "尝试次数过多。" } }, "x-k-world-risk": "auth", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "currentPassword": "old-password", "newPassword": "new-password" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/accounts/me": { "get": { "operationId": "getAccountProfile", "summary": "读取当前账号、套餐和本月用量。", "tags": [ "accounts" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "账号资料。" }, "401": { "description": "需要登录。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in" }, "patch": { "operationId": "updateAccountProfile", "summary": "更新账号显示名称。修改密码请用 POST /api/accounts/password（必须提供当前密码）。", "tags": [ "accounts" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "账号已更新。" }, "401": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "name": "新的名称" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/audit/events": { "get": { "operationId": "listAuditEvents", "summary": "读取当前账号自己的操作审计记录。", "tags": [ "accounts", "audit" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "审计事件列表。" }, "401": { "description": "需要登录。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in" } }, "/api/admin/session": { "get": { "operationId": "adminSession", "summary": "查询当前访问者是否具备后台管理权限，以及权限来自编辑模式还是账号角色。", "tags": [ "admin" ], "security": [], "parameters": [], "responses": { "200": { "description": "isAdmin、operator、source 和 editorEnabled。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "always" } }, "/api/admin/overview": { "get": { "operationId": "adminOverview", "summary": "后台总览：账号统计、套餐目录、知识宇宙总数和任务队列状态。", "tags": [ "admin" ], "security": [], "parameters": [], "responses": { "200": { "description": "账号统计与套餐目录。" }, "403": { "description": "需要管理员权限。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/admin/users": { "get": { "operationId": "adminListUsers", "summary": "后台用户列表：支持按名称、邮箱、套餐或角色搜索，并返回用量、积分和额度。", "tags": [ "admin", "accounts" ], "security": [], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "搜索关键词。", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "返回条数上限。", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "分页偏移。", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "账号列表与目录统计。" }, "403": { "description": "需要管理员权限。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" }, "post": { "operationId": "adminCreateUser", "summary": "后台新建用户，可直接指定角色、套餐、状态、初始积分和单独的额度覆盖。", "tags": [ "admin", "accounts" ], "security": [ { "editorCookie": [] } ], "parameters": [], "responses": { "201": { "description": "账号已创建。" }, "401": { "description": "" }, "403": { "description": "需要管理员权限。" }, "409": { "description": "邮箱已被占用。" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "name": "张三", "email": "zhangsan@example.com", "username": "zhangsan", "password": "strong-password", "role": "user", "plan": "pro", "credits": 500, "limitsOverride": { "monthlyAiRequests": 20 } }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/admin/users/{userId}": { "patch": { "operationId": "adminUpdateUser", "summary": "后台修改用户：名称、用户名、邮箱、密码、角色、套餐、启用状态和额度覆盖。用户名留空即清除；停用会立即注销其会话。", "tags": [ "admin", "accounts" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "账号 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "账号已更新。" }, "401": { "description": "" }, "403": { "description": "需要管理员权限。" }, "409": { "description": "邮箱冲突，或触发了最后一个管理员的保护规则。" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "role": "admin", "plan": "team", "status": "active", "limitsOverride": { "monthlyAiRequests": "unlimited" } }, "schema": { "type": "object", "additionalProperties": true } } } } }, "delete": { "operationId": "adminDeleteUser", "summary": "后台删除用户，同时删除其知识宇宙与研究项目、移交其组织所有权并注销其全部会话。", "tags": [ "admin", "accounts" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "账号 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "账号及其数据已删除。" }, "400": { "description": "试图删除当前登录的管理员账号。" }, "401": { "description": "" }, "403": { "description": "需要管理员权限。" }, "409": { "description": "最后一个可用管理员不可删除。" }, "503": { "description": "" } }, "x-k-world-risk": "destructive", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/admin/users/{userId}/credits": { "post": { "operationId": "adminAdjustCredits", "summary": "增减用户积分，正数增加、负数扣减，余额不足会被拒绝；每次变动写入流水。", "tags": [ "admin", "credits" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "账号 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "积分已调整，返回新余额与本次流水。amount 为差值模式，setTo 为直接设为指定值。" }, "400": { "description": "数量非整数、目标为负、与当前值相同或余额不足。" }, "401": { "description": "" }, "403": { "description": "需要管理员权限。" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "amount": 500, "reason": "开通赠送" }, "schema": { "type": "object", "additionalProperties": true } } } } }, "get": { "operationId": "adminCreditLedger", "summary": "读取某用户的积分余额与最近的积分流水。", "tags": [ "admin", "credits" ], "security": [], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "账号 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "余额与流水列表。" }, "403": { "description": "需要管理员权限。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/admin/settings": { "get": { "operationId": "adminSiteSettings", "summary": "读取站点开关（注册开放状态、是否需要登录），并说明取值来自后台设置还是服务器环境。", "tags": [ "admin", "settings" ], "security": [], "parameters": [], "responses": { "200": { "description": "registrationOpen、requireLogin 及其来源与环境默认值。" }, "403": { "description": "需要管理员权限。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" }, "patch": { "operationId": "adminUpdateSiteSettings", "summary": "后台一键开关公开注册与「需要登录」门禁；传 env 可恢复为跟随服务器环境变量。", "tags": [ "admin", "settings" ], "security": [ { "editorCookie": [] } ], "parameters": [], "responses": { "200": { "description": "设置已保存并返回生效值。requireLogin 开启时，未登录访客访问内容接口会收到 401 LOGIN_REQUIRED。" }, "401": { "description": "" }, "403": { "description": "需要管理员权限。" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "registrationOpen": false, "requireLogin": true }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/admin/audit": { "get": { "operationId": "adminAuditEvents", "summary": "读取后台管理员操作审计（admin.* 事件）。", "tags": [ "admin", "audit" ], "security": [], "parameters": [], "responses": { "200": { "description": "管理员操作事件列表。" }, "403": { "description": "需要管理员权限。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/billing/status": { "get": { "operationId": "getBillingStatus", "summary": "读取当前账号的套餐、订阅状态、可用升级项目和支付配置状态。", "tags": [ "billing", "accounts" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "计费状态。" }, "401": { "description": "" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in" } }, "/api/organizations": { "get": { "operationId": "listOrganizations", "summary": "列出当前账号加入的组织 Workspace 和成员。", "tags": [ "organizations", "accounts" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "组织列表。" }, "401": { "description": "" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in" }, "post": { "operationId": "createOrganization", "summary": "创建组织 Workspace；默认要求 Team 或 Enterprise 套餐。", "tags": [ "organizations", "accounts" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "201": { "description": "组织已创建。" }, "401": { "description": "" }, "403": { "description": "套餐不支持组织。" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "name": "AI 产业研究团队" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/organizations/{organizationId}": { "get": { "operationId": "getOrganization", "summary": "读取组织详情和成员。", "tags": [ "organizations" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "组织 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "组织详情。" }, "401": { "description": "" }, "404": { "description": "组织不存在或无权访问。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" }, "patch": { "operationId": "updateOrganization", "summary": "组织 owner 或 admin 更新组织名称和 slug。", "tags": [ "organizations" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "组织 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "组织已更新。" }, "401": { "description": "" }, "403": { "description": "需要管理员权限。" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "name": "新的组织名称" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/organizations/{organizationId}/members": { "post": { "operationId": "upsertOrganizationMember", "summary": "组织 owner 或 admin 邀请账号并设置 admin、editor 或 viewer 角色。", "tags": [ "organizations", "teams" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "组织 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "组织成员已更新。" }, "401": { "description": "" }, "403": { "description": "需要管理员权限。" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "email": "member@example.com", "role": "editor" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/organizations/{organizationId}/members/{userId}": { "delete": { "operationId": "removeOrganizationMember", "summary": "组织 owner 或 admin 移除成员；不能移除组织所有者。", "tags": [ "organizations", "teams" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "组织 ID。", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "成员账号 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成员已移除。" }, "400": { "description": "不能移除所有者。" }, "401": { "description": "" } }, "x-k-world-risk": "destructive", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/organizations/{organizationId}/audit": { "get": { "operationId": "exportOrganizationAudit", "summary": "组织 owner 或 admin 导出组织审计记录，支持 JSON 或 CSV，最多 2000 条。", "tags": [ "organizations", "audit", "enterprise" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "组织 ID。", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "csv 时返回可下载 CSV。", "schema": { "type": "string", "enum": [ "json", "csv" ] } } ], "responses": { "200": { "description": "审计事件 JSON 或 CSV。" }, "401": { "description": "" }, "403": { "description": "需要组织管理员权限。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" } }, "/api/organizations/{organizationId}/api-keys": { "get": { "operationId": "listOrganizationApiKeys", "summary": "组织 owner/admin 查看 API Key 元数据；不返回明文 Token 或哈希。", "tags": [ "organizations", "api-keys", "enterprise" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "组织 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "API Key 元数据列表。" }, "401": { "description": "" }, "403": { "description": "需要管理员权限。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" }, "post": { "operationId": "createOrganizationApiKey", "summary": "生成组织级 Enterprise API Key；明文 Token 只在创建响应中返回一次。", "tags": [ "organizations", "api-keys", "enterprise" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "组织 ID。", "schema": { "type": "string" } } ], "responses": { "201": { "description": "返回一次性 Token 和 Key 元数据。" }, "401": { "description": "" }, "403": { "description": "需要管理员权限。" } }, "x-k-world-risk": "auth", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "name": "内部数据平台", "scopes": [ "read", "write" ] }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/organizations/{organizationId}/api-keys/{keyId}": { "delete": { "operationId": "revokeOrganizationApiKey", "summary": "吊销组织 API Key；之后使用该 Key 的请求返回 401。", "tags": [ "organizations", "api-keys", "destructive" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "组织 ID。", "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "description": "API Key ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Key 已吊销。" }, "401": { "description": "" }, "404": { "description": "Key 不存在。" } }, "x-k-world-risk": "destructive", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/billing/checkout": { "post": { "operationId": "createBillingCheckout", "summary": "为 Pro 或 Team 套餐创建 Stripe Subscription Checkout 会话。", "tags": [ "billing", "accounts" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "201": { "description": "返回 Stripe Checkout URL。" }, "401": { "description": "" }, "503": { "description": "支付未配置。" } }, "x-k-world-risk": "external", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "plan": "pro" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/billing/webhook": { "post": { "operationId": "stripeBillingWebhook", "summary": "接收签名验证后的 Stripe Checkout 和 Subscription Webhook，更新账号套餐状态。", "tags": [ "billing", "webhook" ], "security": [], "parameters": [], "responses": { "200": { "description": "Webhook 已处理。" }, "400": { "description": "签名或 JSON 无效。" }, "503": { "description": "Webhook 未配置。" } }, "x-k-world-risk": "external", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "id": "evt_...", "type": "checkout.session.completed", "data": { "object": {} } }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/research-projects": { "get": { "operationId": "listResearchProjects", "summary": "列出当前账号的云端研究项目。", "tags": [ "research", "accounts" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "研究项目列表。" }, "401": { "description": "需要登录。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in" }, "post": { "operationId": "createResearchProjectStored", "summary": "创建持久化云端研究项目，保存实体、来源和研究笔记。", "tags": [ "research", "accounts" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "201": { "description": "项目已创建。" }, "401": { "description": "" }, "429": { "description": "项目数量达到套餐上限。" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "title": "研究项目", "question": "待研究问题", "workspace": { "entities": [], "sources": [], "notes": [] } }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/research-projects/{projectId}": { "get": { "operationId": "getResearchProjectStored", "summary": "读取一个云端研究项目。", "tags": [ "research", "accounts" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "研究项目 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "研究项目。" }, "401": { "description": "" }, "404": { "description": "项目不存在。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" }, "patch": { "operationId": "updateResearchProjectStored", "summary": "更新研究项目状态、问题、宇宙关联或工作台内容。", "tags": [ "research", "accounts" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "研究项目 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "项目已更新。" }, "401": { "description": "" }, "404": { "description": "项目不存在。" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "status": "completed", "workspace": { "entities": [], "sources": [], "notes": [] } }, "schema": { "type": "object", "additionalProperties": true } } } } }, "delete": { "operationId": "deleteResearchProjectStored", "summary": "永久删除当前账号的一个研究项目。", "tags": [ "research", "destructive" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "研究项目 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "项目已删除。" }, "401": { "description": "" }, "404": { "description": "项目不存在。" } }, "x-k-world-risk": "destructive", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/research-projects/{projectId}/collaboration": { "get": { "operationId": "getProjectCollaboration", "summary": "读取研究项目评论、活动、审批状态和当前成员权限。", "tags": [ "collaboration", "research" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "研究项目 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "协作状态。" }, "401": { "description": "" }, "404": { "description": "项目不存在或无权访问。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" } }, "/api/research-projects/{projectId}/comments": { "post": { "operationId": "createProjectComment", "summary": "在研究项目中发表评论，可附带实体、来源或章节锚点。", "tags": [ "collaboration" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "研究项目 ID。", "schema": { "type": "string" } } ], "responses": { "201": { "description": "评论已创建。" }, "401": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "body": "这个结论需要第二个来源。", "anchor": { "type": "entity", "id": "p-zhugeliang" } }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/research-projects/{projectId}/comments/{commentId}": { "patch": { "operationId": "updateProjectComment", "summary": "修改评论正文或把评论标记为已解决。", "tags": [ "collaboration" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "研究项目 ID。", "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "required": true, "description": "评论 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "评论已更新。" }, "401": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "status": "resolved" }, "schema": { "type": "object", "additionalProperties": true } } } } }, "delete": { "operationId": "deleteProjectComment", "summary": "作者删除自己的评论，组织管理员可以删除任意评论。", "tags": [ "collaboration", "destructive" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "研究项目 ID。", "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "required": true, "description": "评论 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "评论已删除。" }, "401": { "description": "" } }, "x-k-world-risk": "destructive", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/research-projects/{projectId}/review/submit": { "post": { "operationId": "submitProjectReview", "summary": "editor、admin 或 owner 把研究项目提交给组织管理员审阅。", "tags": [ "collaboration", "approval" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "研究项目 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "项目已进入审阅状态。" }, "401": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "note": "证据和结论已整理完成。" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/research-projects/{projectId}/review/decision": { "post": { "operationId": "decideProjectReview", "summary": "组织 owner 或 admin 批准或退回研究项目。", "tags": [ "collaboration", "approval" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "研究项目 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "项目审批已记录。" }, "401": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "decision": "approved", "note": "通过审核。" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/research/runs": { "get": { "operationId": "listResearchRuns", "summary": "列出当前账号的多 Agent 研究任务及六个阶段的定义。", "tags": [ "research", "agents" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "研究任务列表和阶段定义。" }, "401": { "description": "" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in" }, "post": { "operationId": "createResearchRun", "summary": "启动持久化多 Agent 研究流水线：Research、Search、Extraction、Graph、Evidence、Writer。可指定 sourceScope 复用已有知识宇宙的资料池。", "tags": [ "research", "agents" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "202": { "description": "研究任务已创建并在后台运行。" }, "400": { "description": "缺少资料池宇宙（MISSING_SOURCE_UNIVERSE）或资料池为空（SOURCE_POOL_EMPTY）。" }, "401": { "description": "" }, "429": { "description": "套餐额度不足。" } }, "x-k-world-risk": "external", "x-k-world-cost": "model+search+build", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "projectId": "prj_...", "question": "研究生成式 AI 的商业机会", "sourceScope": "hybrid", "universeId": "universe-..." }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/research/runs/{runId}": { "get": { "operationId": "getResearchRun", "summary": "读取多 Agent 研究任务的当前阶段、进度、来源、错误和关键结果。", "tags": [ "research", "agents" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "研究任务 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "研究任务状态。" }, "401": { "description": "" }, "404": { "description": "任务不存在或不属于当前账号。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" } }, "/api/research/runs/{runId}/retry": { "post": { "operationId": "retryResearchRun", "summary": "重新启动失败或中断的多 Agent 研究流水线。", "tags": [ "research", "agents" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "研究任务 ID。", "schema": { "type": "string" } } ], "responses": { "202": { "description": "研究任务已重新启动。" }, "401": { "description": "" }, "404": { "description": "任务不存在。" } }, "x-k-world-risk": "external", "x-k-world-cost": "model+search+build", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/editor/login": { "post": { "operationId": "loginEditor", "summary": "验证编辑密码并创建 HttpOnly 编辑会话。公共读取不需要调用。", "tags": [ "security" ], "security": [], "parameters": [], "responses": { "200": { "description": "编辑会话创建成功。" }, "401": { "description": "编辑凭据错误。" }, "429": { "description": "失败次数过多。" }, "503": { "description": "服务器未启用编辑模式。" } }, "x-k-world-risk": "auth", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "username": "editor", "password": "editor-password" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/editor/logout": { "post": { "operationId": "logoutEditor", "summary": "销毁当前编辑会话。", "tags": [ "security" ], "security": [], "parameters": [], "responses": { "200": { "description": "编辑会话已清除。" } }, "x-k-world-risk": "auth", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": {}, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/model/test": { "post": { "operationId": "testModel", "summary": "向已配置模型发送一次连通性测试，会产生外部请求和模型费用。", "tags": [ "model" ], "security": [], "parameters": [], "responses": { "200": { "description": "模型连接正常。" }, "503": { "description": "模型未配置。" } }, "x-k-world-risk": "external", "x-k-world-cost": "model", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in", "requestBody": { "required": false, "content": { "application/json": { "example": {}, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/documents/parse": { "post": { "operationId": "parseDocument", "summary": "解析 Base64 文档并返回文本，支持 PDF、Word、Markdown、TXT、HTML 和电子书。", "tags": [ "sources" ], "security": [], "parameters": [], "responses": { "200": { "description": "返回解析后的文档正文。" }, "400": { "description": "格式不支持或正文为空。" }, "413": { "description": "文件过大。" } }, "x-k-world-risk": "cpu", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in", "requestBody": { "required": false, "content": { "application/json": { "example": { "name": "example.md", "mimeType": "text/markdown", "dataBase64": "SGVsbG8=" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/sources/fetch": { "post": { "operationId": "fetchSourceUrl", "summary": "抓取公开 HTTP(S) 网页并提取正文，内网、元数据地址和本机地址会被拒绝。", "tags": [ "sources" ], "security": [], "parameters": [], "responses": { "200": { "description": "返回网页标题、正文和来源信息。" }, "400": { "description": "URL 不合法或指向受限地址。" }, "502": { "description": "网页无法访问或正文过少。" } }, "x-k-world-risk": "external", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in", "requestBody": { "required": false, "content": { "application/json": { "example": { "url": "https://example.com" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/research/collect": { "post": { "operationId": "collectResearchSources", "summary": "通过 Tavily、Brave、Serper 或自定义搜索提供商收集多个网页，抓取正文并整理为研究资料。", "tags": [ "research", "search" ], "security": [], "parameters": [], "responses": { "200": { "description": "返回搜索结果、成功抓取的来源、正文、失败项和检索时间。" }, "429": { "description": "账号网页抓取额度不足。" }, "503": { "description": "未配置搜索提供商。" } }, "x-k-world-risk": "external", "x-k-world-cost": "search+fetch", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in", "requestBody": { "required": false, "content": { "application/json": { "example": { "query": "生成式人工智能产业链 2026", "maxResults": 6, "maxPages": 4 }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/universes": { "get": { "operationId": "listUniverses", "summary": "列出全部知识宇宙及其统计信息。", "tags": [ "universes" ], "security": [], "parameters": [], "responses": { "200": { "description": "知识宇宙摘要列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniverseList" } } } } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "always" }, "post": { "operationId": "createUniverse", "summary": "创建知识宇宙并异步启动解析、抽取和图谱生成。", "tags": [ "universes", "build" ], "security": [ { "editorCookie": [] } ], "parameters": [], "responses": { "202": { "description": "已创建并启动后台构建任务。" }, "401": { "description": "" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "model", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "name": "AI 审计临时知识宇宙", "description": "用于审计，请在隔离环境中创建并删除。", "sourceTitles": [ "example.md" ], "sourceText": "用于测试的短文本。", "mode": "research" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/search": { "get": { "operationId": "searchUniverse", "summary": "在一个知识宇宙中按关键词和实体类型搜索。", "tags": [ "search" ], "security": [], "parameters": [ { "name": "universeId", "in": "query", "required": false, "description": "知识宇宙 ID；省略时使用默认宇宙。", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": true, "description": "搜索词。", "schema": { "type": "string" }, "example": "曹操" }, { "name": "type", "in": "query", "required": false, "description": "实体类型筛选。", "schema": { "type": "string" }, "example": "person" } ], "responses": { "200": { "description": "匹配实体列表。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "always" } }, "/api/chat": { "post": { "operationId": "chatWithUniverse", "summary": "基于指定知识宇宙和当前实体进行带证据的 AI 问答。", "tags": [ "chat", "model" ], "security": [], "parameters": [], "responses": { "200": { "description": "包含 answer、sections、evidence 和 actions 的回答。" } }, "x-k-world-risk": "external", "x-k-world-cost": "model", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "universeId": "three-kingdoms", "entityId": "p-caocao", "question": "曹操和诸葛亮之间有哪些关键关系？" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/universes/{universeId}/retry": { "post": { "operationId": "retryUniverseBuild", "summary": "重新启动失败或中断的知识宇宙构建任务。", "tags": [ "build" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "202": { "description": "已重新启动后台构建。" }, "401": { "description": "" }, "404": { "description": "知识宇宙不存在。" }, "409": { "description": "当前状态下不能重试。" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "model", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": {}, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/universes/{universeId}/study-guide": { "get": { "operationId": "getStudyGuide", "summary": "读取学习指南；首次生成或 force=1 时可能调用模型并持久化结果。", "tags": [ "study", "model" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } }, { "name": "force", "in": "query", "required": false, "description": "设为 1 时强制重新生成。", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "返回学习指南。" }, "202": { "description": "知识宇宙仍在构建。" }, "401": { "description": "" }, "503": { "description": "" } }, "x-k-world-risk": "conditional-write", "x-k-world-cost": "conditional-model", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "skip-default" } }, "/api/universes/{universeId}/research-report": { "get": { "operationId": "getResearchReport", "summary": "把当前知识宇宙整理为执行摘要、关键实体、发展时间线、关系、证据、结论和限制。", "tags": [ "research" ], "security": [], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "结构化研究报告。" }, "202": { "description": "知识宇宙仍在构建。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" } }, "/api/universes/{universeId}/evidence-verification": { "get": { "operationId": "getEvidenceVerification", "summary": "核验关系来源数量、来源类型、平均可信度、弱来源、无来源实体和无来源时间事件。", "tags": [ "evidence", "research" ], "security": [], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "证据核验分数、摘要、关系状态和问题列表。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" } }, "/api/universes/{universeId}/entities": { "post": { "operationId": "addManualEntity", "summary": "向一个知识宇宙手动添加实体，并可创建一条关系。", "tags": [ "entities", "write" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "201": { "description": "返回新增实体和可选关系。" }, "401": { "description": "" }, "404": { "description": "知识宇宙不存在。" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "name": "审计临时实体", "type": "concept", "summary": "仅用于隔离环境中的审计。", "relatedEntityId": "p-caocao", "relationLabel": "测试关系" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/universes/{universeId}": { "delete": { "operationId": "deleteUniverse", "summary": "永久删除知识宇宙及其持久化文件。", "tags": [ "universes", "destructive" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "删除完成。" }, "401": { "description": "" }, "404": { "description": "知识宇宙不存在。" }, "503": { "description": "" } }, "x-k-world-risk": "destructive", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" }, "patch": { "operationId": "updateUniverse", "summary": "知识宇宙所有者更新名称、说明或公开读取状态。", "tags": [ "universes", "permissions" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "知识宇宙已更新。" }, "401": { "description": "" }, "403": { "description": "只有所有者可以更新。" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "visibility": "private", "name": "新的名称" }, "schema": { "type": "object", "additionalProperties": true } } } } }, "get": { "operationId": "getUniverse", "summary": "读取一个知识宇宙的完整实体、关系、时间线、来源和学习指南。", "tags": [ "universes" ], "security": [], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "完整知识宇宙对象。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Universe" } } } }, "404": { "description": "知识宇宙不存在。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "always" } }, "/api/universes/{universeId}/members": { "post": { "operationId": "upsertUniverseMember", "summary": "所有者邀请已注册账号并设置 viewer 或 editor 角色。", "tags": [ "permissions", "teams" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成员权限已设置。" }, "401": { "description": "" }, "404": { "description": "邮箱未注册。" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "email": "member@example.com", "role": "viewer" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/universes/{universeId}/members/{userId}": { "delete": { "operationId": "removeUniverseMember", "summary": "所有者移除知识宇宙成员。", "tags": [ "permissions", "teams" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "成员账号 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成员已移除。" }, "400": { "description": "不能移除所有者。" }, "401": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/universes/{universeId}/entities/{entityId}": { "get": { "operationId": "getEntity", "summary": "读取单个实体及其关联证据。", "tags": [ "entities" ], "security": [], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } }, { "name": "entityId", "in": "path", "required": true, "description": "实体 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "实体及其证据。" }, "404": { "description": "实体不存在。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" } }, "/api/universes/{universeId}/fact-check": { "post": { "operationId": "runFactCheck", "summary": "使用 Wikidata 对知识宇宙实体做外部事实核查，并把冲突加入人工复核。", "tags": [ "evidence", "fact-checking" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "事实核查和复核入队结果。" }, "401": { "description": "" }, "503": { "description": "" } }, "x-k-world-risk": "external", "x-k-world-cost": "external-free-api", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "maxEntities": 20, "concurrency": 3 }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/universes/{universeId}/sources/verify": { "post": { "operationId": "verifySourceMetadata", "summary": "通过 DOI 或 ISBN 核验来源元数据。", "tags": [ "evidence", "sources" ], "security": [], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "来源核验结果。" } }, "x-k-world-risk": "external", "x-k-world-cost": "external-free-api", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "doi": "10.1000/example" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/source-verification/check": { "post": { "operationId": "sourceVerificationCheck", "summary": "按 URL、发布方、作者、日期和外部数据库信号计算来源可信度。", "tags": [ "evidence", "credibility" ], "security": [], "parameters": [], "responses": { "200": { "description": "可信度评分和特征。" } }, "x-k-world-risk": "external", "x-k-world-cost": "external-free-api", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "source": { "title": "Demo", "url": "https://example.com", "publisher": "Example" } }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/source-verification/feedback": { "post": { "operationId": "trainCredibilityModel", "summary": "用人工标注反馈训练并持久化来源可信度权重。", "tags": [ "evidence", "credibility" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "更新后的模型。" }, "401": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "label": true, "features": { "https": 1, "knownPublisher": 1, "hasAuthor": 1 } }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/review-queue": { "get": { "operationId": "listReviewQueue", "summary": "读取知识宇宙的人工证据复核队列。", "tags": [ "evidence", "review" ], "security": [], "parameters": [ { "name": "universeId", "in": "query", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "复核事项和统计。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" } }, "/api/review-queue/{itemId}": { "patch": { "operationId": "updateReviewItem", "summary": "认领、确认、忽略或要求补充证据。", "tags": [ "evidence", "review" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "description": "复核事项 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "更新后的复核事项。" }, "401": { "description": "" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "decision": "accepted", "note": "已人工确认" }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/universes/{universeId}/entity-resolution/run": { "post": { "operationId": "runEntityResolution", "summary": "跨来源识别重复实体，自动合并高置信度项，并把冲突保留为人工候选。", "tags": [ "entities", "resolution" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "实体合并结果。" }, "401": { "description": "" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "threshold": 0.9, "reviewThreshold": 0.62 }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/universes/{universeId}/sources/incremental": { "post": { "operationId": "incrementalSourceUpdate", "summary": "往已建好的知识宇宙补充资料：按来源指纹去重，重新用模型解析新增内容，只合并新增实体、关系、事件并标记受影响部分。", "tags": [ "sources", "incremental" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "资料与已收录内容指纹一致，没有新增知识。" }, "202": { "description": "增量分析任务已排队，返回任务与 incrementalUpdate 进度。" }, "400": { "description": "单批资料数量超限。" }, "401": { "description": "" }, "409": { "description": "该知识宇宙已有增量任务在执行。" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "model", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "sources": [ { "title": "2026 更新报告", "text": "新增正文", "url": "https://example.com/report" }, { "title": "补充访谈", "text": "另一份新增正文" } ] }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/universes/{universeId}/research-report/export": { "get": { "operationId": "exportResearchReport", "summary": "导出带引用的 Markdown、可编辑 Word 或 PDF 研究报告。", "tags": [ "research", "reports" ], "security": [], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "markdown、docx 或 pdf。", "schema": { "type": "string", "enum": [ "markdown", "docx", "pdf" ] } } ], "responses": { "200": { "description": "报告文件。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "dynamic-read" } }, "/api/market": { "get": { "operationId": "listMarket", "summary": "公开搜索已发布知识宇宙市场。", "tags": [ "community", "market" ], "security": [], "parameters": [], "responses": { "200": { "description": "公开市场列表。" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "always" } }, "/api/market/{listingId}/fork": { "post": { "operationId": "forkMarketUniverse", "summary": "把公开知识宇宙复制到当前账号的私有空间。", "tags": [ "community", "market" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "listingId", "in": "path", "required": true, "description": "市场条目 ID。", "schema": { "type": "string" } } ], "responses": { "201": { "description": "已创建私有副本。" }, "401": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } }, "/api/universes/{universeId}/publish": { "post": { "operationId": "publishUniverse", "summary": "知识宇宙所有者把知识宇宙发布到公开市场。", "tags": [ "community", "market" ], "security": [ { "editorCookie": [] } ], "parameters": [ { "name": "universeId", "in": "path", "required": true, "description": "知识宇宙 ID。", "schema": { "type": "string" } } ], "responses": { "201": { "description": "市场条目。" }, "401": { "description": "" }, "503": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never", "requestBody": { "required": false, "content": { "application/json": { "example": { "title": "公开知识宇宙", "tags": [ "AI" ] }, "schema": { "type": "object", "additionalProperties": true } } } } } }, "/api/personalization": { "get": { "operationId": "listPersonalization", "summary": "读取当前账号的个性化偏好。", "tags": [ "personalization" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "个性化配置。" }, "401": { "description": "" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in" } }, "/api/jobs": { "get": { "operationId": "listJobs", "summary": "读取持久化任务队列、优先级、预算、重试和状态统计。", "tags": [ "jobs" ], "security": [ { "accountCookie": [] } ], "parameters": [], "responses": { "200": { "description": "任务列表和统计。" }, "401": { "description": "" } }, "x-k-world-risk": "read", "x-k-world-cost": "none", "x-k-world-mutation": false, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "opt-in" } }, "/api/jobs/{jobId}/cancel": { "post": { "operationId": "cancelJob", "summary": "取消排队或运行中的长任务。", "tags": [ "jobs" ], "security": [ { "accountCookie": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "任务 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "取消后的任务。" }, "401": { "description": "" } }, "x-k-world-risk": "write", "x-k-world-cost": "none", "x-k-world-mutation": true, "x-k-world-source": "server.mjs#handleApi", "x-k-world-probe": "never" } } }, "components": { "schemas": { "Health": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" }, "now": { "type": "string", "format": "date-time" }, "model": { "$ref": "#/components/schemas/ModelStatus" } }, "required": [ "ok", "service", "now", "model" ] }, "ModelStatus": { "type": "object", "properties": { "configured": { "type": "boolean" }, "engine": { "type": "string" }, "providerHost": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "apiMode": { "type": "string" }, "hasApiKey": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } } } }, "UniverseList": { "type": "object", "properties": { "universes": { "type": "array", "items": { "$ref": "#/components/schemas/UniverseSummary" } } } }, "UniverseSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "stats": { "type": "object", "additionalProperties": true }, "updatedAt": { "type": "string" } } }, "Universe": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "entities": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "relationships": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "timeline": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "studyGuide": { "type": [ "object", "null" ], "additionalProperties": true } } } }, "securitySchemes": { "accountCookie": { "type": "apiKey", "in": "cookie", "name": "kworld_account", "description": "通过 /api/accounts/login 或注册创建账号会话。" }, "editorCookie": { "type": "apiKey", "in": "cookie", "name": "kworld_editor", "description": "通过 /api/editor/login 创建 HttpOnly 编辑会话。公共读取接口不需要该会话。" } } }, "x-k-world-audit": { "manifest": "https://world.yuanxuntech.com/api/ai/manifest", "llmsText": "https://world.yuanxuntech.com/llms.txt", "readOnlyCrawler": "npm run audit:ai -- --base-url ", "warning": "DELETE、POST 和可能生成内容的学习指南接口会改变数据或产生模型费用。" } }