{ "openapi": "3.1.0", "info": { "title": "昔枢 CyreneAPI", "version": "0.1.0", "description": "只读公共事实 API：时间、天气、语录与本地小工具；无状态、无账号、不保存任何个人数据，所有工具类接口都在服务端本地计算。", "license": { "name": "GPL-3.0-only", "identifier": "GPL-3.0-only" } }, "servers": [ { "url": "/" } ], "paths": { "/v1/health": { "get": { "tags": [ "misc" ], "operationId": "health", "summary": "服务健康状态", "responses": { "200": { "description": "服务身份与实际模块状态", "headers": { "X-Xishu-Module": { "schema": { "const": "health" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Health" } } } } }, "description": "返回服务名称、版本、当前时间与各模块开关状态；不计入限流，响应不缓存。" } }, "/v1/time": { "get": { "tags": [ "time" ], "operationId": "time", "summary": "当前时间", "parameters": [ { "name": "tz", "in": "query", "schema": { "type": "string", "default": "Asia/Shanghai" }, "example": "Asia/Shanghai", "description": "IANA 时区名，例如 Asia/Shanghai；缺省使用服务端 default_tz。" } ], "responses": { "200": { "description": "当前时间", "headers": { "X-Xishu-Module": { "schema": { "const": "time" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Time" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "$ref": "#/components/responses/Disabled" }, "500": { "$ref": "#/components/responses/Internal" } }, "description": "按 IANA 时区返回当前时间，含 Unix 秒与毫秒、ISO 8601、UTC 偏移和 ISO 周；不传 tz 时用服务端默认时区。" } }, "/v1/weather": { "get": { "tags": [ "weather" ], "operationId": "weather", "summary": "查询天气", "parameters": [ { "name": "place", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "example": "nanan", "description": "地名、别名、全拼或首字母，例如南岸区、nanan、长生桥。" }, { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 15, "default": 5 }, "description": "预报天数，取值 1–15，缺省 5。" }, { "name": "raw", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "传 1 时附带小米上游原始片段；0 或缺省不返回。" } ], "responses": { "200": { "description": "结构化天气；缓存键 location_key:days；缺失可选观测为 null", "headers": { "X-Xishu-Module": { "schema": { "const": "weather" } }, "Cache-Control": { "schema": { "const": "public, max-age=300" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Weather" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "$ref": "#/components/responses/Disabled" }, "502": { "$ref": "#/components/responses/Upstream" }, "500": { "$ref": "#/components/responses/Internal" } }, "description": "先用本地索引解析中国大陆地名，再取小米天气；days 控制预报天数，raw=1 才附带上游原始片段。" } }, "/v1/quote": { "get": { "tags": [ "quote" ], "operationId": "quote", "summary": "随机语录", "parameters": [ { "name": "category", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "分类名，可重复传入，多个分类取并集；缺省表示全库，也兼容逗号分隔。" }, { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, "description": "返回条数，取值 1–10，缺省 1；1 返回对象，大于 1 返回数组。" }, { "name": "daily", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "传 1 时按「客户端 IP + 请求时区的当天日期」生成每日固定的 daily_uuid 与句子；0 或缺省为随机。" }, { "name": "tz", "in": "query", "schema": { "type": "string", "default": "Asia/Shanghai" }, "description": "daily=1 计算日期所用的 IANA 时区，缺省使用服务端 default_tz；非 daily 时忽略。", "example": "Asia/Shanghai" } ], "responses": { "200": { "description": "随机语录；count=1 返回对象，count>1 返回数组。非 daily 是随机句，`Cache-Control: no-store`（任何中间层缓存都会让所有人拿到同一句）；daily=1 时每个对象额外带 daily_uuid，且只能私有缓存。", "headers": { "X-Xishu-Module": { "schema": { "const": "quote" } }, "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store", "private, max-age=600" ] } } }, "content": { "application/json; charset=utf-8": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Quote" }, { "type": "array", "minItems": 2, "maxItems": 10, "items": { "$ref": "#/components/schemas/Quote" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "$ref": "#/components/responses/Disabled" }, "500": { "$ref": "#/components/responses/Internal" } }, "description": "从语录库随机抽取；daily=1 时按「客户端 IP + 请求时区的当天日期」用 HMAC-SHA256 生成固定的 daily_uuid，并据此取句，同一天同一 IP 结果不变；count=1 返回对象，count>1 返回数组。" } }, "/v1/almanac": { "get": { "tags": [ "almanac" ], "operationId": "almanac", "summary": "农历黄历", "description": "按公历日期给出农历日期、干支、生肖、当前节气、节日与当日宜忌；日期缺省为配置时区的今天。宜忌一天不变，响应按 public, max-age=3600 缓存。", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "公历日期 YYYY-MM-DD，缺省为配置时区的当天；只支持 1900-01-01 到 2100-12-31。", "example": "2026-10-30" }, { "name": "tz", "in": "query", "schema": { "type": "string" }, "description": "IANA 时区名，只用来确定缺省 date 是哪一天，缺省取配置里的 default_tz。", "example": "Asia/Shanghai" } ], "responses": { "200": { "description": "该日的农历黄历数据", "headers": { "X-Xishu-Module": { "schema": { "const": "almanac" } }, "Cache-Control": { "schema": { "const": "public, max-age=3600" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Almanac" } } } }, "501": { "$ref": "#/components/responses/Disabled" }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/openapi.json": { "get": { "tags": [ "misc" ], "operationId": "openapi", "summary": "接口文档", "responses": { "200": { "description": "OpenAPI 3.1 文档", "headers": { "X-Xishu-Module": { "schema": { "const": "openapi" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "返回编译进二进制的手写 OpenAPI 3.1 文档，供文档站渲染接口分组、参数表与响应说明。" } }, "/v1/text/base64": { "get": { "tags": [ "text" ], "operationId": "textBase64", "summary": "Base64 编解码", "description": "把 UTF-8 文本编码为标准 Base64，或把 Base64 解回 UTF-8；解码接受无填充与 URL-safe 变体，非法输入返回 400。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 8192 }, "description": "待处理文本，按 UTF-8 字节计，最多 8192 字节。", "example": "hello" }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "encode", "decode" ], "default": "encode" }, "example": "encode", "description": "encode 表示编码，decode 表示解码；缺省 encode。" } ], "responses": { "200": { "description": "编码/解码结果", "headers": { "X-Xishu-Module": { "schema": { "const": "text" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Base64" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/text/hash": { "get": { "tags": [ "text" ], "operationId": "textHash", "summary": "文本哈希", "description": "计算文本的 MD5、SHA-1 或 SHA-256 摘要，输出小写十六进制；算法缺省 sha256。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 8192 }, "description": "待计算摘要的文本，按 UTF-8 字节计，最多 8192 字节。", "example": "abc" }, { "name": "algo", "in": "query", "schema": { "type": "string", "enum": [ "md5", "sha1", "sha256" ], "default": "sha256" }, "description": "摘要算法，可选 md5、sha1、sha256，大小写不敏感，缺省 sha256。", "example": "sha256" } ], "responses": { "200": { "description": "摘要结果", "headers": { "X-Xishu-Module": { "schema": { "const": "text" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Hash" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/convert/json": { "get": { "tags": [ "convert" ], "operationId": "convertJson", "summary": "JSON 格式化", "description": "校验并格式化 JSON，indent=0 压缩成单行；非法 JSON 只返回行列号与错误类别，不回显原文。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 8192 }, "description": "待处理的 JSON 文本，最多 8192 字节。", "example": "{\"b\":1,\"a\":2}" }, { "name": "indent", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 8, "default": 2 }, "description": "缩进空格数，取值 0–8；0 表示压缩成单行，缺省 2。", "example": 2 } ], "responses": { "200": { "description": "转换结果；键序保留", "headers": { "X-Xishu-Module": { "schema": { "const": "convert" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/JsonConvert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/time/convert": { "get": { "tags": [ "time" ], "operationId": "timeConvert", "summary": "时区换算", "description": "把同一时刻换算到两个 IANA 时区，分别给出 ISO 时间、UTC 偏移与星期；at 可传 RFC3339 或 Unix 秒。", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "default": "Asia/Shanghai" }, "description": "起始 IANA 时区名，缺省使用服务端 default_tz。", "example": "Asia/Shanghai" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "description": "目标 IANA 时区名，例如 America/New_York。", "example": "America/New_York" }, { "name": "at", "in": "query", "schema": { "type": "string" }, "description": "要换算的时刻，可传 RFC3339 或 Unix 秒；缺省取当前时刻。", "example": "2026-10-30T12:00:00+08:00" } ], "responses": { "200": { "description": "两侧的 ISO / 偏移 / 星期", "headers": { "X-Xishu-Module": { "schema": { "const": "time" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/TimeConvert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "$ref": "#/components/responses/Disabled" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/misc/date-diff": { "get": { "tags": [ "misc" ], "operationId": "miscDateDiff", "summary": "日期差计算", "description": "计算两个 YYYY-MM-DD 日期之间的整天数，并按 unit 换算成周或小时；反向查询返回负值。", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "description": "起始日期，格式 YYYY-MM-DD。", "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "description": "结束日期，格式 YYYY-MM-DD。", "example": "2026-10-30" }, { "name": "unit", "in": "query", "schema": { "type": "string", "enum": [ "days", "weeks", "hours" ], "default": "days" }, "description": "差值单位，可选 days、weeks、hours，缺省 days；weeks 按整天数除以 7 截断。", "example": "days" } ], "responses": { "200": { "description": "整数差值与两端是否同日", "headers": { "X-Xishu-Module": { "schema": { "const": "misc" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/DateDiff" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/misc/random": { "get": { "tags": [ "misc" ], "operationId": "miscRandom", "summary": "随机生成", "description": "生成随机整数、字母数字字符串或 UUID v4；属于普通随机数，不适合用于密钥或安全令牌。", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "int", "string", "uuid" ], "default": "int" }, "example": "uuid", "description": "随机类型，可选 int、string、uuid，缺省 int。" }, { "name": "min", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "整数最小值（闭区间），仅 type=int 有效，缺省 1。", "example": 1 }, { "name": "max", "in": "query", "schema": { "type": "integer", "default": 100 }, "description": "整数最大值（闭区间），仅 type=int 有效，缺省 100，且不得小于 min。", "example": 100 }, { "name": "length", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 128, "default": 16 }, "description": "字符串长度，取值 1–128，仅 type=string 有效，缺省 16；字符集为大小写字母和数字。", "example": 16 }, { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 }, "example": 1, "description": "生成个数，取值 1–20，缺省 1；1 返回对象，大于 1 返回数组。" } ], "responses": { "200": { "description": "count=1 返回对象，count>1 返回同形状数组", "headers": { "X-Xishu-Module": { "schema": { "const": "misc" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RandomItem" }, { "type": "array", "minItems": 2, "maxItems": 20, "items": { "$ref": "#/components/schemas/RandomItem" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/image/qrcode": { "get": { "tags": [ "convert" ], "operationId": "imageQrcode", "summary": "二维码生成", "description": "把不超过 512 字节的文本编码成二维码 SVG，带 4 模块静默区；v1 仅支持 SVG，可缓存一小时。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 512 }, "description": "要编码的文本，按 UTF-8 字节计，最多 512 字节。", "example": "hello" }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 512, "maximum": 2048, "default": 512 }, "description": "输出边长（像素），512–2048 的整数，缺省 512。码点尺寸随之变化，越大越容易扫。", "example": 512 }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "svg" ], "default": "svg" }, "description": "输出格式，目前仅支持 svg，缺省 svg。", "example": "svg" }, { "name": "theme", "in": "query", "schema": { "type": "string", "enum": [ "default", "cyrene" ], "default": "default" }, "description": "配色。缺省 default 为白底黑码，输出与旧版一字节不差；cyrene 背景仍是纯白，只把码点（深色方块）换成桃粉 #ff3fc0 → 天蓝 #4a9af0 的两端渐变（不插中间色），两端对白底实测对比度 3.12:1 / 2.93:1。已对部署产物用 rsvg-convert 栅格化、zbarimg 逐张验过 512/768/1024/2048 四种尺寸 × 三段文本，外加五档角度与静默区 1–8。", "example": "cyrene" }, { "name": "angle", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 360, "default": 90 }, "description": "渐变方向，0–360 的整数，缺省 90。90 = 从左到右（渐变色的惯用方向）、0 = 从下到上、180 = 从上到下、45 = 左下到右上；任意角度都支持，只在 theme=cyrene 时生效。", "example": 90 }, { "name": "margin", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 8, "default": 4 }, "description": "静默区宽度，1–8 的整数（模块数），缺省 4，即标准静默区。只在 theme=cyrene 时生效；default 主题忽略它，输出的静默区恒为 4。", "example": 4 } ], "responses": { "200": { "description": "二维码 SVG；theme=cyrene 时码点 path 的 fill 是 url(#cyrene)，背景 rect 仍是纯白。", "headers": { "X-Xishu-Module": { "schema": { "const": "image" } }, "Cache-Control": { "schema": { "const": "public, max-age=3600" } } }, "content": { "image/svg+xml; charset=utf-8": { "schema": { "type": "string", "description": "二维码 SVG 源码，可直接嵌入网页或用 <img> 引用。" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/district": { "get": { "tags": [ "misc" ], "operationId": "district", "summary": "行政区划查询", "description": "只查本地地名索引（精确、拼音、前缀、包含、模糊五级），返回标准名、层级、上级、站点、坐标与别名；认不出返回 404，不请求上游。", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "地名、别名、全拼或首字母，例如南岸、nanan、长生桥。", "example": "南岸" }, { "name": "level", "in": "query", "schema": { "type": "string", "enum": [ "province", "city", "district", "street" ] }, "description": "只在该层级里匹配，可选 province（省级）、city（市级）、district（区县级）、street（街道级）。", "example": "district" } ], "responses": { "200": { "description": "标准名、层级、上级、站点、坐标、别名/拼音/首字母", "headers": { "X-Xishu-Module": { "schema": { "const": "district" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/District" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/almanac": { "get": { "tags": [ "almanac" ], "operationId": "almanacAlias", "summary": "农历黄历", "description": "与 /v1/almanac 等价（同一 handler，非重定向），正文逐字节一致。", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "公历日期 YYYY-MM-DD，缺省为配置时区的当天；只支持 1900-01-01 到 2100-12-31。", "example": "2026-10-30" }, { "name": "tz", "in": "query", "schema": { "type": "string" }, "description": "IANA 时区名，只用来确定缺省 date 是哪一天，缺省取配置里的 default_tz。", "example": "Asia/Shanghai" } ], "responses": { "200": { "description": "该日的农历黄历数据", "headers": { "X-Xishu-Module": { "schema": { "const": "almanac" } }, "Cache-Control": { "schema": { "const": "public, max-age=3600" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Almanac" } } } }, "501": { "$ref": "#/components/responses/Disabled" }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/pinyin": { "get": { "tags": [ "text" ], "operationId": "pinyin", "summary": "汉字转拼音", "description": "把汉字转成拼音：full 给带空格的全拼，initials 给声母，tone 给带声调的写法；非汉字原样保留。字典随二进制发布，纯本地计算。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string" }, "description": "待转写文本，按 UTF-8 字节计，最多 1024 字节。", "example": "南岸区" }, { "name": "style", "in": "query", "schema": { "type": "string", "enum": [ "full", "initials", "tone" ], "default": "full" }, "description": "拼音风格：full 全拼（缺省）、initials 声母、tone 带声调。", "example": "full" } ], "responses": { "200": { "description": "拼音转换结果", "headers": { "X-Xishu-Module": { "schema": { "const": "text" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Pinyin" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/pinyin": { "get": { "tags": [ "text" ], "operationId": "pinyinAlias", "summary": "汉字转拼音", "description": "与 /v1/pinyin 等价（同一 handler，非重定向），正文逐字节一致。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string" }, "description": "待转写文本，按 UTF-8 字节计，最多 1024 字节。", "example": "南岸区" }, { "name": "style", "in": "query", "schema": { "type": "string", "enum": [ "full", "initials", "tone" ], "default": "full" }, "description": "拼音风格：full 全拼（缺省）、initials 声母、tone 带声调。", "example": "full" } ], "responses": { "200": { "description": "拼音转换结果", "headers": { "X-Xishu-Module": { "schema": { "const": "text" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Pinyin" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/text/count": { "get": { "tags": [ "text" ], "operationId": "textCount", "summary": "字数统计", "description": "统计汉字数、英文字母数、数字、单词数、总字符数、非空白字符数，并按中文 300 字/分钟、英文 200 词/分钟估算阅读时长。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string" }, "description": "待统计文本，按 UTF-8 字节计，最多 8192 字节。", "example": "南岸区 hello 2026" } ], "responses": { "200": { "description": "各类字符的计数与阅读时长", "headers": { "X-Xishu-Module": { "schema": { "const": "text" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/TextCount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/text/count": { "get": { "tags": [ "text" ], "operationId": "textCountAlias", "summary": "字数统计", "description": "与 /v1/text/count 等价（同一 handler，非重定向），正文逐字节一致。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string" }, "description": "待统计文本，按 UTF-8 字节计，最多 8192 字节。", "example": "南岸区 hello 2026" } ], "responses": { "200": { "description": "各类字符的计数与阅读时长", "headers": { "X-Xishu-Module": { "schema": { "const": "text" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/TextCount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/convert/units": { "get": { "tags": [ "convert" ], "operationId": "unitConvert", "summary": "单位换算", "description": "在长度、重量、温度、面积、体积、数据、速度七类单位之间换算。单位不认识时返回 400，并在 hint 里列出该类别支持的全部单位。", "parameters": [ { "name": "value", "in": "query", "required": true, "schema": { "type": "string" }, "description": "要换算的数值，可带小数与负号。", "example": "1" }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string" }, "description": "源单位，如 km、miles、kg、米；大小写不敏感，也认常见别名。", "example": "km" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "description": "目标单位，如 mile、磅、m2。", "example": "mile" }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "length", "weight", "temperature", "area", "volume", "data", "speed" ], "default": "length" }, "description": "换算类别：length 长度（缺省）、weight 重量、temperature 温度、area 面积、volume 体积、data 数据（1024 进位）、speed 速度。", "example": "length" } ], "responses": { "200": { "description": "换算结果", "headers": { "X-Xishu-Module": { "schema": { "const": "convert" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/UnitConvert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/convert/units": { "get": { "tags": [ "convert" ], "operationId": "unitConvertAlias", "summary": "单位换算", "description": "与 /v1/convert/units 等价（同一 handler，非重定向），正文逐字节一致。", "parameters": [ { "name": "value", "in": "query", "required": true, "schema": { "type": "string" }, "description": "要换算的数值，可带小数与负号。", "example": "1" }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string" }, "description": "源单位，如 km、miles、kg、米；大小写不敏感，也认常见别名。", "example": "km" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "description": "目标单位，如 mile、磅、m2。", "example": "mile" }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "length", "weight", "temperature", "area", "volume", "data", "speed" ], "default": "length" }, "description": "换算类别：length 长度（缺省）、weight 重量、temperature 温度、area 面积、volume 体积、data 数据（1024 进位）、speed 速度。", "example": "length" } ], "responses": { "200": { "description": "换算结果", "headers": { "X-Xishu-Module": { "schema": { "const": "convert" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/UnitConvert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/color": { "get": { "tags": [ "convert" ], "operationId": "colorConvert", "summary": "颜色格式转换", "description": "接受十六进制、rgb()、hsl()、hsv() 与常见色名，输出 hex/rgb/hsl/hsv 四份，另给相对亮度、感知亮度与 is_dark，方便挑文字颜色。", "parameters": [ { "name": "value", "in": "query", "required": true, "schema": { "type": "string" }, "description": "颜色输入：#ff6ad9、rgb(255,106,217)、hsl(315,100%,71%)、hsv(315,58%,100%) 或常见中英文色名（如 red、红）。", "example": "#ff6ad9" }, { "name": "to", "in": "query", "schema": { "type": "string", "enum": [ "hex", "rgb", "hsl", "hsv" ], "default": "hex" }, "description": "主输出格式：hex（缺省）、rgb、hsl、hsv；无论取值如何，响应里都会同时给出四份。", "example": "hex" } ], "responses": { "200": { "description": "四种写法与亮度信息", "headers": { "X-Xishu-Module": { "schema": { "const": "convert" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Color" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/color": { "get": { "tags": [ "convert" ], "operationId": "colorConvertAlias", "summary": "颜色格式转换", "description": "与 /v1/color 等价（同一 handler，非重定向），正文逐字节一致。", "parameters": [ { "name": "value", "in": "query", "required": true, "schema": { "type": "string" }, "description": "颜色输入：#ff6ad9、rgb(255,106,217)、hsl(315,100%,71%)、hsv(315,58%,100%) 或常见中英文色名（如 red、红）。", "example": "#ff6ad9" }, { "name": "to", "in": "query", "schema": { "type": "string", "enum": [ "hex", "rgb", "hsl", "hsv" ], "default": "hex" }, "description": "主输出格式：hex（缺省）、rgb、hsl、hsv；无论取值如何，响应里都会同时给出四份。", "example": "hex" } ], "responses": { "200": { "description": "四种写法与亮度信息", "headers": { "X-Xishu-Module": { "schema": { "const": "convert" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Color" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/time": { "get": { "tags": [ "time" ], "operationId": "time", "summary": "当前时间", "parameters": [ { "name": "tz", "in": "query", "schema": { "type": "string", "default": "Asia/Shanghai" }, "example": "Asia/Shanghai", "description": "IANA 时区名，例如 Asia/Shanghai；缺省使用服务端 default_tz。" } ], "responses": { "200": { "description": "当前时间", "headers": { "X-Xishu-Module": { "schema": { "const": "time" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Time" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "$ref": "#/components/responses/Disabled" }, "500": { "$ref": "#/components/responses/Internal" } }, "description": "与 /v1/time 等价，供老客户端使用。按 IANA 时区返回当前时间，含 Unix 秒与毫秒、ISO 8601、UTC 偏移和 ISO 周；不传 tz 时用服务端默认时区。" } }, "/api/v1/weather": { "get": { "tags": [ "weather" ], "operationId": "weather", "summary": "查询天气", "parameters": [ { "name": "place", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "example": "nanan", "description": "地名、别名、全拼或首字母，例如南岸区、nanan、长生桥。" }, { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 15, "default": 5 }, "description": "预报天数，取值 1–15，缺省 5。" }, { "name": "raw", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "传 1 时附带小米上游原始片段；0 或缺省不返回。" } ], "responses": { "200": { "description": "结构化天气；缓存键 location_key:days；缺失可选观测为 null", "headers": { "X-Xishu-Module": { "schema": { "const": "weather" } }, "Cache-Control": { "schema": { "const": "public, max-age=300" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Weather" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "$ref": "#/components/responses/Disabled" }, "502": { "$ref": "#/components/responses/Upstream" }, "500": { "$ref": "#/components/responses/Internal" } }, "description": "与 /v1/weather 等价，供老客户端使用。先用本地索引解析中国大陆地名，再取小米天气；days 控制预报天数，raw=1 才附带上游原始片段。" } }, "/api/v1/quote": { "get": { "tags": [ "quote" ], "operationId": "quote", "summary": "随机语录", "parameters": [ { "name": "category", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "分类名，可重复传入，多个分类取并集；缺省表示全库，也兼容逗号分隔。" }, { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, "description": "返回条数，取值 1–10，缺省 1；1 返回对象，大于 1 返回数组。" }, { "name": "daily", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "传 1 时按「客户端 IP + 请求时区的当天日期」生成每日固定的 daily_uuid 与句子；0 或缺省为随机。" }, { "name": "tz", "in": "query", "schema": { "type": "string", "default": "Asia/Shanghai" }, "description": "daily=1 计算日期所用的 IANA 时区，缺省使用服务端 default_tz；非 daily 时忽略。", "example": "Asia/Shanghai" } ], "responses": { "200": { "description": "随机语录；count=1 返回对象，count>1 返回数组。非 daily 是随机句，`Cache-Control: no-store`（任何中间层缓存都会让所有人拿到同一句）；daily=1 时每个对象额外带 daily_uuid，且只能私有缓存。", "headers": { "X-Xishu-Module": { "schema": { "const": "quote" } }, "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store", "private, max-age=600" ] } } }, "content": { "application/json; charset=utf-8": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Quote" }, { "type": "array", "minItems": 2, "maxItems": 10, "items": { "$ref": "#/components/schemas/Quote" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "$ref": "#/components/responses/Disabled" }, "500": { "$ref": "#/components/responses/Internal" } }, "description": "与 /v1/quote 等价，供老客户端使用。从语录库随机抽取；daily=1 时按「客户端 IP + 请求时区的当天日期」用 HMAC-SHA256 生成固定的 daily_uuid，并据此取句，同一天同一 IP 结果不变；count=1 返回对象，count>1 返回数组。" } }, "/api/v1/text/base64": { "get": { "tags": [ "text" ], "operationId": "textBase64", "summary": "Base64 编解码", "description": "与 /v1/text/base64 等价，供老客户端使用。把 UTF-8 文本编码为标准 Base64，或把 Base64 解回 UTF-8；解码接受无填充与 URL-safe 变体，非法输入返回 400。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 8192 }, "description": "待处理文本，按 UTF-8 字节计，最多 8192 字节。", "example": "hello" }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "encode", "decode" ], "default": "encode" }, "example": "encode", "description": "encode 表示编码，decode 表示解码；缺省 encode。" } ], "responses": { "200": { "description": "编码/解码结果", "headers": { "X-Xishu-Module": { "schema": { "const": "text" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Base64" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/text/hash": { "get": { "tags": [ "text" ], "operationId": "textHash", "summary": "文本哈希", "description": "与 /v1/text/hash 等价，供老客户端使用。计算文本的 MD5、SHA-1 或 SHA-256 摘要，输出小写十六进制；算法缺省 sha256。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 8192 }, "description": "待计算摘要的文本，按 UTF-8 字节计，最多 8192 字节。", "example": "abc" }, { "name": "algo", "in": "query", "schema": { "type": "string", "enum": [ "md5", "sha1", "sha256" ], "default": "sha256" }, "description": "摘要算法，可选 md5、sha1、sha256，大小写不敏感，缺省 sha256。", "example": "sha256" } ], "responses": { "200": { "description": "摘要结果", "headers": { "X-Xishu-Module": { "schema": { "const": "text" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Hash" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/convert/json": { "get": { "tags": [ "convert" ], "operationId": "convertJson", "summary": "JSON 格式化", "description": "与 /v1/convert/json 等价，供老客户端使用。校验并格式化 JSON，indent=0 压缩成单行；非法 JSON 只返回行列号与错误类别，不回显原文。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 8192 }, "description": "待处理的 JSON 文本，最多 8192 字节。", "example": "{\"b\":1,\"a\":2}" }, { "name": "indent", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 8, "default": 2 }, "description": "缩进空格数，取值 0–8；0 表示压缩成单行，缺省 2。", "example": 2 } ], "responses": { "200": { "description": "转换结果；键序保留", "headers": { "X-Xishu-Module": { "schema": { "const": "convert" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/JsonConvert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/time/convert": { "get": { "tags": [ "time" ], "operationId": "timeConvert", "summary": "时区换算", "description": "与 /v1/time/convert 等价，供老客户端使用。把同一时刻换算到两个 IANA 时区，分别给出 ISO 时间、UTC 偏移与星期；at 可传 RFC3339 或 Unix 秒。", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "default": "Asia/Shanghai" }, "description": "起始 IANA 时区名，缺省使用服务端 default_tz。", "example": "Asia/Shanghai" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "description": "目标 IANA 时区名，例如 America/New_York。", "example": "America/New_York" }, { "name": "at", "in": "query", "schema": { "type": "string" }, "description": "要换算的时刻，可传 RFC3339 或 Unix 秒；缺省取当前时刻。", "example": "2026-10-30T12:00:00+08:00" } ], "responses": { "200": { "description": "两侧的 ISO / 偏移 / 星期", "headers": { "X-Xishu-Module": { "schema": { "const": "time" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/TimeConvert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "$ref": "#/components/responses/Disabled" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/misc/date-diff": { "get": { "tags": [ "misc" ], "operationId": "miscDateDiff", "summary": "日期差计算", "description": "与 /v1/misc/date-diff 等价，供老客户端使用。计算两个 YYYY-MM-DD 日期之间的整天数，并按 unit 换算成周或小时；反向查询返回负值。", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "description": "起始日期，格式 YYYY-MM-DD。", "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "description": "结束日期，格式 YYYY-MM-DD。", "example": "2026-10-30" }, { "name": "unit", "in": "query", "schema": { "type": "string", "enum": [ "days", "weeks", "hours" ], "default": "days" }, "description": "差值单位，可选 days、weeks、hours，缺省 days；weeks 按整天数除以 7 截断。", "example": "days" } ], "responses": { "200": { "description": "整数差值与两端是否同日", "headers": { "X-Xishu-Module": { "schema": { "const": "misc" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/DateDiff" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/misc/random": { "get": { "tags": [ "misc" ], "operationId": "miscRandom", "summary": "随机生成", "description": "与 /v1/misc/random 等价，供老客户端使用。生成随机整数、字母数字字符串或 UUID v4；属于普通随机数，不适合用于密钥或安全令牌。", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "int", "string", "uuid" ], "default": "int" }, "example": "uuid", "description": "随机类型，可选 int、string、uuid，缺省 int。" }, { "name": "min", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "整数最小值（闭区间），仅 type=int 有效，缺省 1。", "example": 1 }, { "name": "max", "in": "query", "schema": { "type": "integer", "default": 100 }, "description": "整数最大值（闭区间），仅 type=int 有效，缺省 100，且不得小于 min。", "example": 100 }, { "name": "length", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 128, "default": 16 }, "description": "字符串长度，取值 1–128，仅 type=string 有效，缺省 16；字符集为大小写字母和数字。", "example": 16 }, { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 }, "example": 1, "description": "生成个数，取值 1–20，缺省 1；1 返回对象，大于 1 返回数组。" } ], "responses": { "200": { "description": "count=1 返回对象，count>1 返回同形状数组", "headers": { "X-Xishu-Module": { "schema": { "const": "misc" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RandomItem" }, { "type": "array", "minItems": 2, "maxItems": 20, "items": { "$ref": "#/components/schemas/RandomItem" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/image/qrcode": { "get": { "tags": [ "convert" ], "operationId": "imageQrcode", "summary": "二维码生成", "description": "与 /v1/image/qrcode 等价，供老客户端使用。把不超过 512 字节的文本编码成二维码 SVG，带 4 模块静默区；v1 仅支持 SVG，可缓存一小时。", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 512 }, "description": "要编码的文本，按 UTF-8 字节计，最多 512 字节。", "example": "hello" }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 512, "maximum": 2048, "default": 512 }, "description": "输出边长（像素），512–2048 的整数，缺省 512。码点尺寸随之变化，越大越容易扫。", "example": 512 }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "svg" ], "default": "svg" }, "description": "输出格式，目前仅支持 svg，缺省 svg。", "example": "svg" }, { "name": "theme", "in": "query", "schema": { "type": "string", "enum": [ "default", "cyrene" ], "default": "default" }, "description": "配色。缺省 default 为白底黑码，输出与旧版一字节不差；cyrene 背景仍是纯白，只把码点（深色方块）换成桃粉 #ff3fc0 → 天蓝 #4a9af0 的两端渐变（不插中间色），两端对白底实测对比度 3.12:1 / 2.93:1。已对部署产物用 rsvg-convert 栅格化、zbarimg 逐张验过 512/768/1024/2048 四种尺寸 × 三段文本，外加五档角度与静默区 1–8。", "example": "cyrene" }, { "name": "angle", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 360, "default": 90 }, "description": "渐变方向，0–360 的整数，缺省 90。90 = 从左到右（渐变色的惯用方向）、0 = 从下到上、180 = 从上到下、45 = 左下到右上；任意角度都支持，只在 theme=cyrene 时生效。", "example": 90 }, { "name": "margin", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 8, "default": 4 }, "description": "静默区宽度，1–8 的整数（模块数），缺省 4，即标准静默区。只在 theme=cyrene 时生效；default 主题忽略它，输出的静默区恒为 4。", "example": 4 } ], "responses": { "200": { "description": "二维码 SVG；theme=cyrene 时码点 path 的 fill 是 url(#cyrene)，背景 rect 仍是纯白。", "headers": { "X-Xishu-Module": { "schema": { "const": "image" } }, "Cache-Control": { "schema": { "const": "public, max-age=3600" } } }, "content": { "image/svg+xml; charset=utf-8": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/api/v1/district": { "get": { "tags": [ "misc" ], "operationId": "district", "summary": "行政区划查询", "description": "与 /v1/district 等价，供老客户端使用。只查本地地名索引（精确、拼音、前缀、包含、模糊五级），返回标准名、层级、上级、站点、坐标与别名；认不出返回 404，不请求上游。", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "地名、别名、全拼或首字母，例如南岸、nanan、长生桥。", "example": "南岸" }, { "name": "level", "in": "query", "schema": { "type": "string", "enum": [ "province", "city", "district", "street" ] }, "description": "只在该层级里匹配，可选 province（省级）、city（市级）、district（区县级）、street（街道级）。", "example": "district" } ], "responses": { "200": { "description": "标准名、层级、上级、站点、坐标、别名/拼音/首字母", "headers": { "X-Xishu-Module": { "schema": { "const": "district" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/District" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } } }, "components": { "headers": { "Module": { "description": "响应所属模块", "schema": { "type": "string", "enum": [ "health", "time", "weather", "quote", "almanac", "openapi", "text", "convert", "misc", "image", "district", "unknown" ] } }, "NoStore": { "schema": { "const": "no-store" } }, "RetryAfter": { "description": "补足一个令牌所需的整数秒", "schema": { "type": "integer", "minimum": 1 } } }, "responses": { "BadRequest": { "description": "400 bad_request", "headers": { "X-Xishu-Module": { "$ref": "#/components/headers/Module" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "404 not_found，包括范围外地区", "headers": { "X-Xishu-Module": { "$ref": "#/components/headers/Module" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "429 rate_limited", "headers": { "X-Xishu-Module": { "$ref": "#/components/headers/Module" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Disabled": { "description": "501 module_disabled", "headers": { "X-Xishu-Module": { "$ref": "#/components/headers/Module" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Upstream": { "description": "502 upstream_error；不暴露上游 URL 或用户自由文本", "headers": { "X-Xishu-Module": { "$ref": "#/components/headers/Module" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Internal": { "description": "500 internal", "headers": { "X-Xishu-Module": { "$ref": "#/components/headers/Module" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message", "hint" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "bad_request", "not_found", "rate_limited", "upstream_error", "module_disabled", "internal" ], "description": "错误码，取值见枚举。" }, "message": { "type": "string", "description": "中文错误说明，不回显调用方原文。" }, "hint": { "type": "string", "description": "中文处理建议。" } }, "description": "统一错误体。" } } }, "Modules": { "type": "object", "required": [ "time", "weather", "quote", "almanac" ], "additionalProperties": false, "properties": { "time": { "type": "boolean", "description": "time 模块是否启用。" }, "weather": { "type": "boolean", "description": "weather 模块是否启用。" }, "quote": { "type": "boolean", "description": "quote 模块是否启用。" }, "almanac": { "const": false, "description": "almanac 模块是否启用；v1 恒为 false。" } } }, "Health": { "type": "object", "required": [ "name", "name_en", "version", "time", "modules" ], "additionalProperties": false, "properties": { "name": { "const": "昔枢", "description": "服务中文名。" }, "name_en": { "const": "CyreneAPI", "description": "服务英文名。" }, "version": { "const": "0.1.0", "description": "语义化版本号。" }, "time": { "type": "string", "format": "date-time", "description": "当前时间，带 UTC 偏移的 RFC3339。" }, "modules": { "$ref": "#/components/schemas/Modules", "description": "各模块开关状态。" } } }, "Time": { "type": "object", "required": [ "timestamp", "timestamp_ms", "iso", "timezone", "utc_offset_seconds", "week", "day_of_year", "is_weekend" ], "additionalProperties": false, "properties": { "timestamp": { "type": "integer", "description": "Unix 时间戳（秒）。" }, "timestamp_ms": { "type": "integer", "description": "Unix 时间戳（毫秒）。" }, "iso": { "type": "string", "format": "date-time", "description": "ISO 8601 时间，带 UTC 偏移。" }, "timezone": { "type": "string", "description": "本次使用的 IANA 时区名。" }, "utc_offset_seconds": { "type": "integer", "description": "当前 UTC 偏移，单位秒。" }, "week": { "type": "integer", "minimum": 1, "maximum": 53, "description": "ISO 周数，取值 1–53。" }, "day_of_year": { "type": "integer", "minimum": 1, "maximum": 366, "description": "年内第几天，取值 1–366。" }, "is_weekend": { "type": "boolean", "description": "当天是否周末。" } } }, "Place": { "type": "object", "required": [ "query", "standard_name", "location_key", "matched_by", "confidence", "latitude", "longitude" ], "additionalProperties": false, "properties": { "query": { "type": "string", "description": "调用方传入的原始地名。" }, "standard_name": { "type": "string", "description": "标准名，上级与自身用空格分隔。" }, "location_key": { "type": "string", "pattern": "^weathercn:[0-9]+$", "description": "小米天气站点编号，形如 weathercn:101044000。" }, "matched_by": { "type": "string", "enum": [ "exact", "pinyin", "prefix", "contains", "fuzzy", "upstream" ], "description": "命中方式：exact 精确、pinyin 拼音或首字母、prefix 前缀、contains 包含、fuzzy 模糊、upstream 上游兜底。" }, "confidence": { "type": "number", "enum": [ 1.0, 0.95, 0.85, 0.7, 0.6, 0.5 ], "description": "匹配置信度，1.0 最高、0.5 为上游兜底。" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "纬度，单位度。" }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "经度，单位度。" } } }, "Current": { "type": "object", "required": [ "temperature", "feels_like", "humidity", "pressure", "weather_code", "weather_text", "wind_direction", "wind_speed", "uv_index", "pub_time" ], "additionalProperties": false, "properties": { "temperature": { "type": "number", "description": "当前气温，摄氏度。" }, "feels_like": { "type": [ "number", "null" ], "description": "体感温度，摄氏度；上游缺失为 null。" }, "humidity": { "type": [ "number", "null" ], "description": "相对湿度，百分比；上游缺失为 null。" }, "pressure": { "type": [ "number", "null" ], "description": "气压，百帕；上游缺失为 null。" }, "weather_code": { "type": "string", "description": "上游天气码字符串。" }, "weather_text": { "type": "string", "description": "天气码对应的中文文本，未知码为「未知」。" }, "wind_direction": { "type": [ "number", "null" ], "description": "风向，单位度；上游缺失为 null。" }, "wind_speed": { "type": [ "number", "null" ], "description": "风速，单位千米每小时；上游缺失为 null。" }, "uv_index": { "type": [ "string", "null" ], "description": "紫外线指数，保留上游字符串；缺失为 null。" }, "pub_time": { "type": "string", "format": "date-time", "description": "上游发布时间，带偏移的 RFC3339。" } } }, "Daily": { "type": "object", "required": [ "date", "temp_high", "temp_low", "sunrise", "sunset", "precip_probability", "aqi" ], "additionalProperties": false, "properties": { "date": { "type": "string", "format": "date", "description": "预报日期，格式 YYYY-MM-DD。" }, "temp_high": { "type": [ "number", "null" ], "description": "最高气温，摄氏度；缺失为 null。" }, "temp_low": { "type": [ "number", "null" ], "description": "最低气温，摄氏度；缺失为 null。" }, "sunrise": { "type": [ "string", "null" ], "format": "date-time", "description": "日出时间，带偏移的 RFC3339；缺失为 null。" }, "sunset": { "type": [ "string", "null" ], "format": "date-time", "description": "日落时间，带偏移的 RFC3339；缺失为 null。" }, "precip_probability": { "type": [ "number", "null" ], "description": "降水概率，百分比；缺失为 null。" }, "aqi": { "type": [ "number", "null" ], "description": "空气质量指数；缺失为 null。" } } }, "Weather": { "type": "object", "required": [ "place", "current", "daily", "fetched_at", "cached" ], "additionalProperties": false, "properties": { "place": { "$ref": "#/components/schemas/Place", "description": "地名解析结果。" }, "current": { "$ref": "#/components/schemas/Current", "description": "当前实况。" }, "daily": { "type": "array", "minItems": 1, "maxItems": 15, "items": { "$ref": "#/components/schemas/Daily" }, "description": "逐日预报，条数等于请求的 days。" }, "fetched_at": { "type": "string", "format": "date-time", "description": "本份数据从上游取得的时刻，带偏移。" }, "cached": { "type": "boolean", "description": "是否命中进程内缓存。" }, "raw": { "type": "object", "required": [ "current", "forecastDaily", "aqi" ], "properties": { "current": { "type": "object" }, "forecastDaily": { "type": "object" }, "aqi": { "type": [ "object", "null" ] } }, "description": "上游原始片段；仅 raw=1 时返回。" } } }, "Quote": { "type": "object", "required": [ "value", "from", "author", "category", "source" ], "additionalProperties": false, "properties": { "value": { "type": "string", "minLength": 1, "description": "语录正文。" }, "from": { "type": "string", "description": "出处，可能为空字符串。" }, "author": { "type": "string", "description": "作者，可能为空字符串。" }, "category": { "type": "array", "items": { "type": "string" }, "description": "本次参与抽取的分类列表。" }, "source": { "const": "CyreneAPI", "description": "数据来源标识，固定 CyreneAPI。" }, "daily_uuid": { "type": "string", "description": "仅 daily=1 时返回的逐日标识：对「客户端 IP + 时区日期」做 HMAC-SHA256 得到，同一 IP 同一天恒定。" } } }, "Base64": { "type": "object", "required": [ "mode", "input_bytes", "output_bytes", "text" ], "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "encode", "decode" ], "description": "本次操作：encode 编码或 decode 解码。" }, "input_bytes": { "type": "integer", "minimum": 0, "description": "输入文本的字节数。" }, "output_bytes": { "type": "integer", "minimum": 0, "description": "输出文本的字节数。" }, "text": { "type": "string", "description": "encode 时是 Base64 串，decode 时是 UTF-8 原文。" } } }, "Hash": { "type": "object", "required": [ "algo", "hex", "input_bytes" ], "additionalProperties": false, "properties": { "algo": { "type": "string", "enum": [ "md5", "sha1", "sha256" ], "description": "实际使用的算法：md5、sha1 或 sha256。" }, "hex": { "type": "string", "pattern": "^[0-9a-f]+$", "description": "小写十六进制摘要。" }, "input_bytes": { "type": "integer", "minimum": 0, "description": "参与计算的字节数。" } } }, "JsonConvert": { "type": "object", "required": [ "indent", "input_bytes", "output_bytes", "json" ], "additionalProperties": false, "properties": { "indent": { "type": "integer", "minimum": 0, "maximum": 8, "description": "实际使用的缩进空格数，0 表示已压缩。" }, "input_bytes": { "type": "integer", "minimum": 0, "description": "输入 JSON 的字节数。" }, "output_bytes": { "type": "integer", "minimum": 0, "description": "输出 JSON 的字节数。" }, "json": { "type": "string", "description": "格式化或压缩后的 JSON 文本，键序保留。" } } }, "TimeSide": { "type": "object", "required": [ "timezone", "iso", "offset", "utc_offset_seconds", "weekday", "weekday_zh", "date", "local_time" ], "additionalProperties": false, "properties": { "timezone": { "type": "string", "description": "该侧的 IANA 时区名。" }, "iso": { "type": "string", "format": "date-time", "description": "该侧的本地时间，带 UTC 偏移的 RFC3339。" }, "offset": { "type": "string", "pattern": "^[+-][0-9]{2}:[0-9]{2}$", "description": "UTC 偏移，形如 +08:00。" }, "utc_offset_seconds": { "type": "integer", "description": "UTC 偏移的秒数。" }, "weekday": { "type": "string", "enum": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ], "description": "英文星期名。" }, "weekday_zh": { "type": "string", "description": "中文星期名。" }, "date": { "type": "string", "format": "date", "description": "当地日期，格式 YYYY-MM-DD。" }, "local_time": { "type": "string", "pattern": "^[0-9]{2}:[0-9]{2}:[0-9]{2}$", "description": "当地时刻，格式 HH:MM:SS。" } } }, "TimeConvert": { "type": "object", "required": [ "timestamp", "from", "to", "same_offset" ], "additionalProperties": false, "properties": { "timestamp": { "type": "integer", "description": "换算时刻的 Unix 秒。" }, "from": { "$ref": "#/components/schemas/TimeSide", "description": "起始时区一侧的本地时间。" }, "to": { "$ref": "#/components/schemas/TimeSide", "description": "目标时区一侧的本地时间。" }, "same_offset": { "type": "boolean", "description": "两侧当前 UTC 偏移是否相同。" } } }, "DateDiff": { "type": "object", "required": [ "from", "to", "unit", "value", "days", "same_day", "weekday_from", "weekday_to" ], "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date", "description": "起始日期。" }, "to": { "type": "string", "format": "date", "description": "结束日期。" }, "unit": { "type": "string", "enum": [ "days", "weeks", "hours" ], "description": "实际使用的差值单位。" }, "value": { "type": "integer", "description": "按 unit 换算后的整数差；weeks 为整天数除以 7 截断，可为负。" }, "days": { "type": "integer", "description": "始终返回整天数，可为负。" }, "same_day": { "type": "boolean", "description": "两端是否同一天。" }, "weekday_from": { "type": "string", "description": "起始日期的英文星期名。" }, "weekday_to": { "type": "string", "description": "结束日期的英文星期名。" } } }, "RandomItem": { "type": "object", "required": [ "type", "value" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "int", "string", "uuid" ], "description": "随机类型：int 整数、string 字符串、uuid UUID v4。" }, "value": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "随机结果；type=int 时为整数，其余为字符串。" } } }, "District": { "type": "object", "required": [ "query", "standard_name", "level", "parent", "location_key", "latitude", "longitude", "aliases", "pinyin", "initials", "matched_by", "confidence" ], "additionalProperties": false, "properties": { "query": { "type": "string", "description": "调用方传入的原始地名。" }, "standard_name": { "type": "string", "description": "标准名，层级之间用空格分隔。" }, "level": { "type": "string", "enum": [ "country", "province", "city", "district", "street" ], "description": "层级：country 国家、province 省级、city 市级、district 区县级、street 街道级。" }, "parent": { "type": "string", "description": "上级行政区名称。" }, "location_key": { "type": "string", "pattern": "^weathercn:[0-9]+$", "description": "对应的天气站点编号。" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "纬度，单位度。" }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "经度，单位度。" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "可命中的别名列表。" }, "pinyin": { "type": "array", "items": { "type": "string" }, "description": "全拼列表。" }, "initials": { "type": "array", "items": { "type": "string" }, "description": "拼音首字母列表。" }, "matched_by": { "type": "string", "enum": [ "exact", "pinyin", "prefix", "contains", "fuzzy" ], "description": "命中方式：exact 精确、pinyin 拼音或首字母、prefix 前缀、contains 包含、fuzzy 模糊。" }, "confidence": { "type": "number", "enum": [ 1.0, 0.95, 0.85, 0.7, 0.6 ], "description": "匹配置信度，1.0 最高、0.6 最低。" } } }, "AlmanacLunar": { "type": "object", "required": [ "year", "month", "day", "text" ], "additionalProperties": false, "properties": { "year": { "type": "string", "description": "农历年的干支，如丙午。" }, "month": { "type": "string", "description": "农历月，如九月；闰月会写成闰六月。" }, "day": { "type": "string", "description": "农历日，如廿一。" }, "text": { "type": "string", "description": "连起来的中文农历日期，如丙午年九月廿一。" } } }, "AlmanacGanzhi": { "type": "object", "required": [ "year", "month", "day" ], "additionalProperties": false, "properties": { "year": { "type": "string", "description": "年柱干支，以正月初一为界，如丙午。" }, "month": { "type": "string", "description": "月柱干支，以节气为界，如戊戌。" }, "day": { "type": "string", "description": "日柱干支，如丁丑。" } } }, "Almanac": { "type": "object", "required": [ "date", "lunar", "zodiac", "ganzhi", "solar_term", "jieqi_today", "festivals", "yi", "ji", "weekday_zh", "timezone", "source" ], "additionalProperties": false, "properties": { "date": { "type": "string", "description": "公历日期 YYYY-MM-DD，来自 date 参数或当天。" }, "lunar": { "allOf": [ { "$ref": "#/components/schemas/AlmanacLunar" } ], "description": "农历日期：年月日的中文写法与整句。" }, "zodiac": { "type": "string", "description": "农历年对应的生肖，如马。" }, "ganzhi": { "allOf": [ { "$ref": "#/components/schemas/AlmanacGanzhi" } ], "description": "年、月、日三柱干支。" }, "solar_term": { "type": [ "string", "null" ], "description": "当前所处的节气名（如霜降），即最近一次节气；极少数情况下算不出时为 null。" }, "jieqi_today": { "type": "boolean", "description": "今天是否恰好是节气当日。" }, "festivals": { "type": "array", "items": { "type": "string" }, "description": "当天的节日，农历与阳历一起给；没有节日时是空数组。" }, "yi": { "type": "array", "items": { "type": "string" }, "description": "宜做的事（黄历建除与神煞表）；算不出时为空数组，绝不编造。" }, "ji": { "type": "array", "items": { "type": "string" }, "description": "忌做的事；算不出时为空数组。" }, "weekday_zh": { "type": "string", "description": "中文星期，如星期五。" }, "timezone": { "type": "string", "description": "用来确定「今天」的时区，IANA 名，如 Asia/Shanghai。" }, "source": { "type": "string", "description": "农历算法来源，固定为 lunar-rs（寿星天文历）。" } } }, "Pinyin": { "type": "object", "required": [ "text", "style", "pinyin", "syllables" ], "additionalProperties": false, "properties": { "text": { "type": "string", "description": "原样回显的输入文本。" }, "style": { "type": "string", "enum": [ "full", "initials", "tone" ], "description": "使用的拼音风格：full 全拼、initials 声母、tone 带声调。" }, "pinyin": { "type": "string", "description": "转换结果；非汉字原样保留，initials 风格把相邻汉字声母连写。" }, "syllables": { "type": "array", "items": { "type": "string" }, "description": "每个汉字的全拼音节（不带声调），非汉字不计入。" } } }, "TextCount": { "type": "object", "required": [ "chars", "chars_no_space", "hanzi", "letters", "digits", "words", "reading_seconds", "reading_minutes" ], "additionalProperties": false, "properties": { "chars": { "type": "integer", "minimum": 0, "description": "总字符数，按 Unicode 字符计。" }, "chars_no_space": { "type": "integer", "minimum": 0, "description": "去掉空白字符后的字符数。" }, "hanzi": { "type": "integer", "minimum": 0, "description": "汉字个数，含 CJK 扩展区。" }, "letters": { "type": "integer", "minimum": 0, "description": "英文字母个数，按 ASCII 字母计。" }, "digits": { "type": "integer", "minimum": 0, "description": "阿拉伯数字个数，按 0-9 计。" }, "words": { "type": "integer", "minimum": 0, "description": "单词数：英文按连续字母数字串计 1 个，汉字按字计。" }, "reading_seconds": { "type": "integer", "minimum": 0, "description": "大致阅读时长（秒），中文按 300 字/分钟、英文按 200 词/分钟估算。" }, "reading_minutes": { "type": "number", "description": "大致阅读时长（分钟），reading_seconds 换算后保留两位小数。" } } }, "UnitConvert": { "type": "object", "required": [ "kind", "value", "from", "from_name", "to", "to_name", "result" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "description": "换算类别：length、weight、temperature、area、volume、data、speed。" }, "value": { "type": "number", "description": "输入的数值，原样回显。" }, "from": { "type": "string", "description": "源单位的规范写法，如 km；别名会被归一化到它。" }, "from_name": { "type": "string", "description": "源单位的中文名，如公里。" }, "to": { "type": "string", "description": "目标单位的规范写法，如 mile。" }, "to_name": { "type": "string", "description": "目标单位的中文名，如英里。" }, "result": { "type": "number", "description": "换算结果，保留约 12 位有效数字；温度走摄氏度换算，数据量按 1024 进位。" } } }, "Rgb": { "type": "object", "required": [ "r", "g", "b" ], "additionalProperties": false, "properties": { "r": { "type": "integer", "minimum": 0, "description": "红色分量 0–255。" }, "g": { "type": "integer", "minimum": 0, "description": "绿色分量 0–255。" }, "b": { "type": "integer", "minimum": 0, "description": "蓝色分量 0–255。" } } }, "Hsl": { "type": "object", "required": [ "h", "s", "l" ], "additionalProperties": false, "properties": { "h": { "type": "number", "description": "色相 0–360 度。" }, "s": { "type": "number", "description": "饱和度 0–100%。" }, "l": { "type": "number", "description": "明度 0–100%。" } } }, "Hsv": { "type": "object", "required": [ "h", "s", "v" ], "additionalProperties": false, "properties": { "h": { "type": "number", "description": "色相 0–360 度。" }, "s": { "type": "number", "description": "饱和度 0–100%。" }, "v": { "type": "number", "description": "明度 0–100%。" } } }, "Color": { "type": "object", "required": [ "input", "name", "hex", "rgb", "rgb_text", "hsl", "hsl_text", "hsv", "hsv_text", "luminance", "brightness", "is_dark", "to", "text" ], "additionalProperties": false, "properties": { "input": { "type": "string", "description": "原样回显的输入文本。" }, "name": { "type": [ "string", "null" ], "description": "匹配到的色名（英文规范名，如 red）；输入是十六进制或函数写法时为 null。" }, "hex": { "type": "string", "description": "十六进制写法，如 #ff6ad9。" }, "rgb": { "allOf": [ { "$ref": "#/components/schemas/Rgb" } ], "description": "rgb 数值写法，三个分量 0–255。" }, "rgb_text": { "type": "string", "description": "rgb() 写法，如 rgb(255, 106, 217)。" }, "hsl": { "allOf": [ { "$ref": "#/components/schemas/Hsl" } ], "description": "hsl 数值写法：色相、饱和度、明度。" }, "hsl_text": { "type": "string", "description": "hsl() 写法，如 hsl(315.3, 100%, 70.8%)。" }, "hsv": { "allOf": [ { "$ref": "#/components/schemas/Hsv" } ], "description": "hsv 数值写法：色相、饱和度、明度。" }, "hsv_text": { "type": "string", "description": "hsv() 写法，如 hsv(315.3, 58.4%, 100%)。" }, "luminance": { "type": "number", "description": "WCAG 相对亮度 0–1，用来算对比度。" }, "brightness": { "type": "integer", "minimum": 0, "description": "感知亮度 0–255（YIQ 加权）。" }, "is_dark": { "type": "boolean", "description": "是否算深色底：感知亮度低于 128 即 true，用来挑文字颜色。" }, "to": { "type": "string", "enum": [ "hex", "rgb", "hsl", "hsv" ], "description": "主输出格式，来自 to 参数，缺省 hex。" }, "text": { "type": "string", "description": "按 to 格式给出的字符串，直接可用。" } } } } }, "tags": [ { "name": "time", "description": "时间与时区：当前时间、时区换算" }, { "name": "weather", "description": "天气：中国大陆城市天气与地名解析" }, { "name": "quote", "description": "语录：随机语录与每日固定语录" }, { "name": "almanac", "description": "农历：黄历宜忌、节气与干支" }, { "name": "text", "description": "文本工具：Base64 编解码、MD5/SHA 摘要、字数统计、拼音" }, { "name": "convert", "description": "转换：JSON 格式化压缩、单位换算、颜色格式、文本转二维码" }, { "name": "misc", "description": "杂项数据：日期差、随机数、行政区划、服务状态" }, { "name": "network", "description": "网络工具（v1 预留，暂无接口）" } ] }