@xisui-pa/chatserver 0.0.0-stage → 1.0.0

package/schemas/config.schema.json

@@ -0,0 +1,355 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ChatServer configuration",
+  "description": "config.json for the built-in chat pipelines. Custom registered adapters and tools require extending this schema.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Location of this JSON schema for editor validation and completion."
+    },
+    "chats": {
+      "type": "array",
+      "description": "Chat pipelines served by this process. An empty array runs no adapters.",
+      "default": [],
+      "items": {
+        "$ref": "#/definitions/chat"
+      }
+    }
+  },
+  "definitions": {
+    "localToolName": {
+      "type": "string",
+      "enum": ["web_search", "read_url", "calculate", "current_time", "read_image"]
+    },
+    "apiToolType": {
+      "type": "string",
+      "pattern": "^\\S+$",
+      "not": { "enum": ["function", "custom"] }
+    },
+    "nonEmptyString": {
+      "type": "string",
+      "pattern": "\\S"
+    },
+    "modelReference": {
+      "type": "string",
+      "pattern": "^[^\\s/](?:[^/]*[^\\s/])?/\\S(?:[\\s\\S]*\\S)?$",
+      "description": "<provider>/<model id>, using the provider name and model ID from models.json. Model IDs may contain additional slashes.",
+      "examples": [
+        "my-provider/my-model-id"
+      ]
+    },
+    "duration": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "chat": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "messager"
+      ],
+      "properties": {
+        "messager": {
+          "$ref": "#/definitions/messager"
+        },
+        "stt": {
+          "$ref": "#/definitions/stt"
+        },
+        "tts": {
+          "$ref": "#/definitions/tts"
+        },
+        "filters": {
+          "type": "array",
+          "description": "Filters evaluated in order. Omit or use [] to delegate to the reply model without running filters.",
+          "default": [],
+          "items": {
+            "$ref": "#/definitions/filter"
+          }
+        }
+      }
+    },
+    "tts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "model"],
+      "description": "Optional voice replies through an OpenAI-compatible audio/speech endpoint returning PCM/float WAV audio. Omit to use text replies only.",
+      "properties": {
+        "type": { "const": "model" },
+        "model": { "$ref": "#/definitions/modelReference" },
+        "options": {
+          "type": "object",
+          "description": "Provider speech fields such as voice, speed, instructions, or language. ChatServer controls model, input, response_format=wav, and stream_format=audio.",
+          "propertyNames": { "not": { "enum": ["model", "input", "response_format", "stream_format"] } },
+          "examples": [{ "voice": "alloy", "speed": 1 }]
+        }
+      }
+    },
+    "stt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "model"],
+      "description": "Optional speech-to-text settings. Omit the entire object to ignore voice input.",
+      "properties": {
+        "type": { "const": "model" },
+        "model": {
+          "description": "Required <provider>/<model id> for audio/transcriptions. There is no fallback to messager.replier.",
+          "allOf": [{ "$ref": "#/definitions/modelReference" }]
+        },
+        "audioConversionCmd": {
+          "type": "string",
+          "pattern": "^(?=[\\s\\S]*\\{input\\})(?=[\\s\\S]*\\{output\\})[\\s\\S]+$",
+          "description": "Optional shell command converting {input} to {output} as WAV. Runs in an isolated temporary directory; converter must be installed on the ChatServer machine. Without it, original audio is uploaded.",
+          "examples": ["ffmpeg -nostdin -y -i {input} -ar 16000 -ac 1 -c:a pcm_s16le {output}"]
+        }
+      }
+    },
+    "messager": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "replier"
+      ],
+      "properties": {
+        "name": {
+          "const": "wechat",
+          "description": "Registered transport. WeChat is the built-in implementation."
+        },
+        "replier": {
+          "$ref": "#/definitions/modelReference"
+        },
+        "memoryTokenLimit": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 16000,
+          "default": 1000,
+          "description": "Per-conversation token budget for this pipeline's memory notes and confirmed replies, including their compact JSON metadata. Oldest entries are removed first; three-day retention still applies."
+        },
+        "persona": {
+          "description": "Optional replier identity, tone, and style as a nonempty string with one or more sentences; newlines are preserved. Omit for the default helpful assistant. Applies only to the replier; output-format and reply-length requirements still apply.",
+          "allOf": [{ "$ref": "#/definitions/nonEmptyString" }],
+          "examples": ["You are a warm, lightly humorous friend. Give practical photography advice. Keep your tone relaxed."]
+        },
+        "mainAccount": {
+          "description": "Exact sender ID authorized to use /status in a direct chat; usually wxid_..., not a display name.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/nonEmptyString"
+            }
+          ]
+        },
+        "localTools": {
+          "type": "array",
+          "description": "Application-managed tools, selected by name strings or objects containing only type. Omit to enable all built-ins; [] disables local tools. read_image enables conversation image caching and lookup for replies and model filters. Duplicate types are deduplicated.",
+          "default": [
+            "web_search",
+            "read_url",
+            "calculate",
+            "current_time",
+            "read_image"
+          ],
+          "items": {
+            "oneOf": [
+              { "$ref": "#/definitions/localToolName" },
+              {
+                "type": "object",
+                "required": ["type"],
+                "properties": {
+                  "type": { "$ref": "#/definitions/localToolName" }
+                },
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "apiTools": {
+          "type": "array",
+          "description": "Provider-hosted Responses API tools as type strings or definition objects with provider-specific options. Strings expand to objects with type. Omitted or [] enables none. The selected provider/model must support them; client-executed tools are not supported here.",
+          "default": [],
+          "items": {
+            "oneOf": [
+              { "$ref": "#/definitions/apiToolType" },
+              {
+                "type": "object",
+                "required": ["type"],
+                "properties": {
+                  "type": { "$ref": "#/definitions/apiToolType" }
+                },
+                "additionalProperties": true
+              }
+            ]
+          }
+        },
+        "imageGeneration": {
+          "type": "boolean",
+          "description": "Enable provider-hosted image generation. Omit to enable when apiTools includes image_generation. True adds the hosted tool if missing; false removes it. Requires support from the replier's provider/model."
+        },
+        "imageWidthLimit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 16384,
+          "default": 1024,
+          "description": "Maximum generated image width in pixels. Combined with imageHeightLimit as the requested hosted-tool size unless a smaller concrete size is set in apiTools. The provider must support the requested dimensions. PNG output is required."
+        },
+        "imageHeightLimit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 16384,
+          "default": 1024,
+          "description": "Maximum generated image height in pixels. Combined with imageWidthLimit as the requested hosted-tool size unless a smaller concrete size is set in apiTools. The provider must support the requested dimensions. PNG output is required."
+        },
+        "dailyImageGenLimit": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "default": 10,
+          "description": "Daily image generation allowance shared by this messager's conversations. Zero disables generation. Usage is kept only in memory and resets on server restart or at server-local midnight; ambiguous provider failures consume quota."
+        },
+        "options": {
+          "$ref": "#/definitions/wechatOptions"
+        }
+      }
+    },
+    "wechatOptions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "baseUrl": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https?://[^/?#@\\s]+(?:/[^?#\\s]*)?$",
+          "description": "agent-wechat HTTP(S) server root, without credentials, query, or fragment.",
+          "default": "http://127.0.0.1:6174"
+        },
+        "tokenEnv": {
+          "description": "Environment variable containing the bearer token; takes precedence over tokenFile.",
+          "default": "AGENT_WECHAT_TOKEN",
+          "allOf": [
+            {
+              "$ref": "#/definitions/nonEmptyString"
+            }
+          ]
+        },
+        "tokenFile": {
+          "description": "Fallback bearer-token file. Relative paths resolve against the config directory; expand ~ yourself.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/nonEmptyString"
+            }
+          ]
+        },
+        "chatIds": {
+          "type": "array",
+          "description": "Chat IDs to monitor. Omit to monitor all chats; mainAccount is always included when configured.",
+          "items": {
+            "$ref": "#/definitions/nonEmptyString"
+          }
+        },
+        "pollIntervalMs": {
+          "description": "Delay after a completed poll, in milliseconds. Failed polls use exponential backoff.",
+          "default": 30000,
+          "allOf": [
+            {
+              "$ref": "#/definitions/duration"
+            }
+          ]
+        },
+        "timeoutMs": {
+          "description": "Timeout for each WeChat REST request in milliseconds; independent of model timeouts.",
+          "default": 30000,
+          "allOf": [
+            {
+              "$ref": "#/definitions/duration"
+            }
+          ]
+        },
+        "bundleGapMs": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "description": "Maximum timestamp gap between adjacent messages from the same sender, in milliseconds. Zero disables bundling.",
+          "default": 10000
+        }
+      }
+    },
+    "filter": {
+      "oneOf": [
+        {
+          "enum": [
+            "ignore",
+            "ignore-sender"
+          ],
+          "description": "Shorthand ignore filter using the default <messager>_ignore file."
+        },
+        {
+          "$ref": "#/definitions/ignoreFilter"
+        },
+        {
+          "$ref": "#/definitions/modelFilter"
+        }
+      ]
+    },
+    "ignoreFilter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "type": {
+          "enum": [
+            "ignore",
+            "ignore-sender"
+          ]
+        },
+        "options": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "file": {
+              "type": "string",
+              "description": "Ignore-list file; defaults to <messager>_ignore in the config directory. Relative paths resolve against that directory."
+            },
+            "senderIds": {
+              "type": "array",
+              "description": "Inline sender IDs combined with the file's IDs. Ignored messages are excluded before buffering and model processing.",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "modelFilter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "model"
+      ],
+      "properties": {
+        "type": {
+          "const": "model"
+        },
+        "model": {
+          "$ref": "#/definitions/modelReference"
+        },
+        "options": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "instructions": {
+              "type": "string",
+              "description": "Decision criteria for the filter model. Thinking is disabled for filter calls.",
+              "default": "Allow messages that would benefit from an assistant response. Otherwise abstain."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/models.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ChatServer model providers",
+  "description": "Non-secret provider and model settings in models.json. API keys belong in the OS credential manager or an environment override.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "providers"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Location of this JSON schema for editor validation and completion."
+    },
+    "version": {
+      "const": 1,
+      "description": "File format version. Defaults to 1 when omitted.",
+      "default": 1
+    },
+    "providers": {
+      "type": "array",
+      "description": "Provider names must be unique. The application checks name uniqueness and config.json model references at runtime.",
+      "items": {
+        "$ref": "#/definitions/provider"
+      }
+    }
+  },
+  "definitions": {
+    "nonEmptyString": {
+      "type": "string",
+      "pattern": "\\S"
+    },
+    "provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "provider",
+        "baseUrl",
+        "models"
+      ],
+      "properties": {
+        "provider": {
+          "description": "Provider name, also used as its credential-manager account and the prefix of <provider>/<model id> references.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/nonEmptyString"
+            }
+          ]
+        },
+        "baseUrl": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https?://",
+          "description": "Required API base URL: Responses-compatible for chat models, audio/transcriptions-compatible for STT models. Omit endpoint suffixes such as /responses. There is no default."
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 2147483647,
+          "description": "Timeout in milliseconds for this provider's model requests. For repliers with tools, also caps the complete model/tool cycle.",
+          "default": 180000
+        },
+        "models": {
+          "type": "array",
+          "description": "Models offered by this provider. Model names must be unique within the provider.",
+          "items": {
+            "$ref": "#/definitions/model"
+          }
+        }
+      }
+    },
+    "model": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "description": "Model ID sent to the API and used after the first slash in config.json model references.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/nonEmptyString"
+            }
+          ]
+        },
+        "supportsImageToolResults": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether this model endpoint accepts native image content arrays in function_call_output. When true and read_image is available, chat images are referenced by ID and retrieved through that tool instead of attached to the initial prompt. If lookup is unavailable, direct attachments are used."
+        },
+        "name": {
+          "description": "CLI display/lookup name. Defaults to id when omitted.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/nonEmptyString"
+            }
+          ]
+        }
+      }
+    }
+  }
+}