{ "openapi": "3.1.0", "info": { "title": "LinkfoxAI Documentation API", "version": "1.0.0", "summary": "LinkfoxAI 面向 AI Agent 和开发者的机器可读文档接口", "description": "LinkfoxAI Wiki 当前只公开无需认证的文档发现接口。业务侧能力需要在 LinkfoxAI 产品中使用已授权账户，Agent 不应猜测未出现在本规范中的接口。公开接口采用 URL 路径版本控制；弃用版本会至少提前 180 天公告，并使用 Deprecation、Sunset 和 Link 响应标头提供时间与迁移目标。", "contact": { "name": "LinkfoxAI Documentation", "url": "https://wiki.linkfox.com/llms.txt" } }, "servers": [ { "url": "https://wiki.linkfox.com/api/v1", "description": "LinkfoxAI Documentation API v1" } ], "tags": [ { "name": "Discovery", "description": "供 Agent 确认文档 API 版本和可用状态的只读入口" } ], "paths": { "/status": { "get": { "operationId": "getDocumentationApiStatus", "summary": "获取 LinkfoxAI 文档 API 版本状态", "description": "返回当前稳定版本、弃用状态、开发者文档和 OpenAPI 地址。该端点无需认证。", "tags": ["Discovery"], "security": [], "responses": { "200": { "description": "当前文档 API 状态", "headers": { "X-API-Version": { "description": "当前 URL 路径版本对应的主版本号", "schema": { "type": "string", "const": "1" } }, "Deprecation": { "description": "仅在版本进入弃用期后发送，值遵循 Deprecation HTTP response header field 规范", "schema": { "type": "string" } }, "Sunset": { "description": "仅在确定停止支持日期后发送，值为 HTTP-date", "schema": { "type": "string" } }, "Link": { "description": "指向机器可读发现资源、弃用策略或后续版本迁移说明", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "当前配额策略，使用 IETF RateLimit header fields 草案定义的 Structured Field 格式", "schema": { "type": "string", "examples": ["\"wiki-status\";q=60;w=60"] } }, "RateLimit": { "description": "当前策略的剩余配额与有效窗口秒数", "schema": { "type": "string", "examples": ["\"wiki-status\";r=59;t=60"] } }, "X-RateLimit-Limit": { "description": "兼容字段：当前窗口的请求上限", "schema": { "type": "integer", "examples": [60] } }, "X-RateLimit-Remaining": { "description": "兼容字段：当前窗口的剩余请求数", "schema": { "type": "integer", "minimum": 0, "examples": [59] } }, "X-RateLimit-Reset": { "description": "兼容字段：距离窗口重置的秒数", "schema": { "type": "integer", "minimum": 1, "examples": [60] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiStatus" }, "examples": { "active": { "value": { "name": "LinkfoxAI documentation API", "version": "v1", "status": "active", "deprecated": false, "documentation": "https://wiki.linkfox.com/llms.txt", "openapi": "https://wiki.linkfox.com/openapi.json", "rateLimit": { "policy": "wiki-status", "quota": 60, "windowSeconds": 60, "scope": "source-ip" } } } } } } }, "404": { "description": "接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "来源 IP 在当前窗口内超过文档 API 请求配额", "headers": { "Retry-After": { "description": "再次请求前至少等待的秒数；优先级高于 RateLimit 中的窗口提示", "schema": { "type": "integer", "minimum": 1, "examples": [1] } }, "RateLimit-Policy": { "description": "触发限流的配额策略", "schema": { "type": "string", "examples": ["\"wiki-status\";q=60;w=60"] } }, "RateLimit": { "description": "剩余配额为 0 及下一有效窗口", "schema": { "type": "string", "examples": ["\"wiki-status\";r=0;t=1"] } }, "X-RateLimit-Limit": { "description": "兼容字段：当前窗口的请求上限", "schema": { "type": "integer", "examples": [60] } }, "X-RateLimit-Remaining": { "description": "兼容字段：触发限流时为 0", "schema": { "type": "integer", "const": 0 } }, "X-RateLimit-Reset": { "description": "兼容字段：距离窗口重置的秒数", "schema": { "type": "integer", "minimum": 1, "examples": [1] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "quotaExceeded": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The documentation API request quota has been exhausted.", "resolution": "Retry after the number of seconds in Retry-After and reduce request frequency." } } } } } } } } } } }, "webhooks": {}, "components": { "schemas": { "ApiStatus": { "type": "object", "required": ["name", "version", "status", "deprecated", "documentation", "openapi", "rateLimit"], "properties": { "name": { "type": "string" }, "version": { "type": "string", "const": "v1" }, "status": { "type": "string", "enum": ["active", "deprecated", "sunset"] }, "deprecated": { "type": "boolean" }, "documentation": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "rateLimit": { "type": "object", "required": ["policy", "quota", "windowSeconds", "scope"], "properties": { "policy": { "type": "string", "const": "wiki-status" }, "quota": { "type": "integer", "const": 60 }, "windowSeconds": { "type": "integer", "const": 60 }, "scope": { "type": "string", "const": "source-ip" } } } } }, "ApiError": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "resolution"], "properties": { "code": { "type": "string", "examples": ["NOT_FOUND"] }, "message": { "type": "string" }, "resolution": { "type": "string" } } } } } } }, "x-versioning-policy": { "strategy": "URL path versioning", "currentVersion": "v1", "breakingChanges": "Breaking changes are published under a new major path such as /api/v2.", "compatibleChanges": "Optional response fields may be added within the current major version.", "deprecationNoticeDays": 180, "deprecationHeaders": ["Deprecation", "Sunset", "Link"] }, "x-rate-limit-policy": { "name": "wiki-status", "scope": "source IP", "quota": 60, "windowSeconds": 60, "responseHeaders": ["RateLimit-Policy", "RateLimit", "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset"], "throttledStatus": 429, "retryHeader": "Retry-After", "specification": "https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/" }, "externalDocs": { "description": "LinkfoxAI 文档索引与 Agent 使用说明", "url": "https://wiki.linkfox.com/llms.txt" } }