源码快照 @ 2026-09-02 (source-only, 剔除非源码素材)
This commit is contained in:
commit
04bac1f6e2
2200 files changed
+489415
No files matched your search
@@ -0,0 +1,301 @@
|
||||
import { z } from "zod"
|
||||
|
||||
export interface ToolSchemaBase {
|
||||
readonly description?: string
|
||||
}
|
||||
|
||||
export type ToolSchemaNode =
|
||||
| (ToolSchemaBase & {
|
||||
readonly type: "string"
|
||||
readonly enum?: readonly string[]
|
||||
readonly minLength?: number
|
||||
readonly maxLength?: number
|
||||
})
|
||||
| (ToolSchemaBase & {
|
||||
readonly type: "number" | "integer"
|
||||
readonly minimum?: number
|
||||
readonly maximum?: number
|
||||
})
|
||||
| (ToolSchemaBase & { readonly type: "boolean" | "null" })
|
||||
| (ToolSchemaBase & {
|
||||
readonly type: "array"
|
||||
readonly items: ToolSchemaNode
|
||||
readonly minItems?: number
|
||||
readonly maxItems?: number
|
||||
})
|
||||
| (ToolSchemaBase & {
|
||||
readonly type: "object"
|
||||
readonly properties: Readonly<Record<string, ToolSchemaNode>>
|
||||
readonly required: readonly string[]
|
||||
readonly additionalProperties: boolean | ToolSchemaNode
|
||||
})
|
||||
| (ToolSchemaBase & { readonly oneOf: readonly ToolSchemaNode[] })
|
||||
| (ToolSchemaBase & { readonly anyOf: readonly ToolSchemaNode[] })
|
||||
|
||||
export type ToolProperty = ToolSchemaNode
|
||||
export type ToolInputSchema = Extract<ToolSchemaNode, { readonly type: "object" }>
|
||||
|
||||
const maximumSchemaDepth = 10
|
||||
const maximumSchemaNodes = 512
|
||||
const maximumSchemaBytes = 64 * 1024
|
||||
const maximumProperties = 128
|
||||
const maximumCompositionBranches = 8
|
||||
const maximumDescriptionLength = 2_000
|
||||
const maximumArgumentDepth = 20
|
||||
const maximumArgumentNodes = 20_000
|
||||
const maximumArgumentIssues = 25
|
||||
|
||||
const commonKeys = new Set(["description"])
|
||||
const keysByType: Readonly<Record<string, ReadonlySet<string>>> = {
|
||||
string: new Set(["type", "description", "enum", "minLength", "maxLength"]),
|
||||
number: new Set(["type", "description", "minimum", "maximum"]),
|
||||
integer: new Set(["type", "description", "minimum", "maximum"]),
|
||||
boolean: new Set(["type", "description"]),
|
||||
null: new Set(["type", "description"]),
|
||||
array: new Set(["type", "description", "items", "minItems", "maxItems"]),
|
||||
object: new Set(["type", "description", "properties", "required", "additionalProperties"]),
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value)
|
||||
}
|
||||
|
||||
function integerInRange(value: unknown, minimum: number, maximum: number): value is number {
|
||||
return typeof value === "number" && Number.isInteger(value) && value >= minimum && value <= maximum
|
||||
}
|
||||
|
||||
function finiteNumber(value: unknown): value is number {
|
||||
return typeof value === "number" && Number.isFinite(value)
|
||||
}
|
||||
|
||||
function pushUnknownKeyIssues(value: Record<string, unknown>, allowed: ReadonlySet<string>, path: string, issues: string[]): void {
|
||||
for (const key of Object.keys(value)) {
|
||||
if (!allowed.has(key)) issues.push(`${path} uses unsupported JSON Schema keyword '${key}'`)
|
||||
}
|
||||
}
|
||||
|
||||
function schemaDefinitionIssues(value: unknown): string[] {
|
||||
const issues: string[] = []
|
||||
let remainingNodes = maximumSchemaNodes
|
||||
const ancestors = new Set<object>()
|
||||
|
||||
try {
|
||||
if (Buffer.byteLength(JSON.stringify(value), "utf8") > maximumSchemaBytes) {
|
||||
issues.push(`Tool schema exceeds ${maximumSchemaBytes} bytes`)
|
||||
return issues
|
||||
}
|
||||
} catch {
|
||||
issues.push("Tool schema must be acyclic JSON data")
|
||||
return issues
|
||||
}
|
||||
|
||||
const visit = (node: unknown, depth: number, path: string): void => {
|
||||
if (issues.length >= maximumArgumentIssues) return
|
||||
if (!isRecord(node)) {
|
||||
issues.push(`${path} must be a JSON Schema object`)
|
||||
return
|
||||
}
|
||||
if (depth > maximumSchemaDepth) {
|
||||
issues.push(`${path} exceeds maximum schema depth ${maximumSchemaDepth}`)
|
||||
return
|
||||
}
|
||||
remainingNodes -= 1
|
||||
if (remainingNodes < 0) {
|
||||
issues.push(`Tool schema exceeds ${maximumSchemaNodes} nodes`)
|
||||
return
|
||||
}
|
||||
if (ancestors.has(node)) {
|
||||
issues.push(`${path} contains a cycle`)
|
||||
return
|
||||
}
|
||||
ancestors.add(node)
|
||||
|
||||
if (node.description !== undefined && (typeof node.description !== "string" || node.description.length === 0 || node.description.length > maximumDescriptionLength)) {
|
||||
issues.push(`${path}.description must contain 1-${maximumDescriptionLength} characters`)
|
||||
}
|
||||
|
||||
const compositionKey = "oneOf" in node ? "oneOf" : "anyOf" in node ? "anyOf" : null
|
||||
if (compositionKey) {
|
||||
pushUnknownKeyIssues(node, new Set([...commonKeys, compositionKey]), path, issues)
|
||||
const branches = node[compositionKey]
|
||||
if (!Array.isArray(branches) || branches.length < 1 || branches.length > maximumCompositionBranches) {
|
||||
issues.push(`${path}.${compositionKey} must contain 1-${maximumCompositionBranches} schemas`)
|
||||
} else {
|
||||
branches.forEach((branch, index) => visit(branch, depth + 1, `${path}.${compositionKey}[${index}]`))
|
||||
}
|
||||
ancestors.delete(node)
|
||||
return
|
||||
}
|
||||
|
||||
const type = node.type
|
||||
if (typeof type !== "string" || !Object.hasOwn(keysByType, type)) {
|
||||
issues.push(`${path}.type must be one supported JSON Schema type`)
|
||||
ancestors.delete(node)
|
||||
return
|
||||
}
|
||||
pushUnknownKeyIssues(node, keysByType[type] ?? commonKeys, path, issues)
|
||||
|
||||
if (type === "string") {
|
||||
if (node.enum !== undefined && (!Array.isArray(node.enum) || node.enum.length < 1 || node.enum.length > 100 || node.enum.some((item) => typeof item !== "string"))) {
|
||||
issues.push(`${path}.enum must contain 1-100 strings`)
|
||||
}
|
||||
if (node.minLength !== undefined && !integerInRange(node.minLength, 0, 1_048_576)) issues.push(`${path}.minLength is invalid`)
|
||||
if (node.maxLength !== undefined && !integerInRange(node.maxLength, 1, 1_048_576)) issues.push(`${path}.maxLength is invalid`)
|
||||
if (finiteNumber(node.minLength) && finiteNumber(node.maxLength) && node.minLength > node.maxLength) issues.push(`${path} has minLength greater than maxLength`)
|
||||
} else if (type === "number" || type === "integer") {
|
||||
if (node.minimum !== undefined && !finiteNumber(node.minimum)) issues.push(`${path}.minimum must be finite`)
|
||||
if (node.maximum !== undefined && !finiteNumber(node.maximum)) issues.push(`${path}.maximum must be finite`)
|
||||
if (finiteNumber(node.minimum) && finiteNumber(node.maximum) && node.minimum > node.maximum) issues.push(`${path} has minimum greater than maximum`)
|
||||
} else if (type === "array") {
|
||||
if (!("items" in node)) issues.push(`${path}.items is required`)
|
||||
else visit(node.items, depth + 1, `${path}.items`)
|
||||
if (node.minItems !== undefined && !integerInRange(node.minItems, 0, 10_000)) issues.push(`${path}.minItems is invalid`)
|
||||
if (node.maxItems !== undefined && !integerInRange(node.maxItems, 1, 10_000)) issues.push(`${path}.maxItems is invalid`)
|
||||
if (finiteNumber(node.minItems) && finiteNumber(node.maxItems) && node.minItems > node.maxItems) issues.push(`${path} has minItems greater than maxItems`)
|
||||
} else if (type === "object") {
|
||||
if (!isRecord(node.properties) || Object.keys(node.properties).length > maximumProperties) {
|
||||
issues.push(`${path}.properties must be an object with at most ${maximumProperties} entries`)
|
||||
} else {
|
||||
for (const [name, property] of Object.entries(node.properties)) {
|
||||
if (!name || name.length > 128) issues.push(`${path}.properties contains an invalid property name`)
|
||||
visit(property, depth + 1, `${path}.properties.${name}`)
|
||||
}
|
||||
}
|
||||
if (!Array.isArray(node.required) || node.required.some((name) => typeof name !== "string" || !name)) {
|
||||
issues.push(`${path}.required must be an array of property names`)
|
||||
} else {
|
||||
const unique = new Set(node.required)
|
||||
if (unique.size !== node.required.length) issues.push(`${path}.required contains duplicates`)
|
||||
for (const name of unique) {
|
||||
if (!isRecord(node.properties) || !Object.hasOwn(node.properties, name)) issues.push(`${path}.required references undeclared property '${name}'`)
|
||||
}
|
||||
}
|
||||
if (typeof node.additionalProperties !== "boolean") {
|
||||
if (!("additionalProperties" in node)) issues.push(`${path}.additionalProperties is required`)
|
||||
else visit(node.additionalProperties, depth + 1, `${path}.additionalProperties`)
|
||||
}
|
||||
}
|
||||
ancestors.delete(node)
|
||||
}
|
||||
|
||||
visit(value, 0, "$schema")
|
||||
return issues
|
||||
}
|
||||
|
||||
function schemaContract<Output extends ToolSchemaNode>(rootMustBeObject: boolean): z.ZodType<Output> {
|
||||
return z
|
||||
.unknown()
|
||||
.superRefine((value, context) => {
|
||||
for (const message of schemaDefinitionIssues(value)) context.addIssue({ code: "custom", message })
|
||||
if (rootMustBeObject && (!isRecord(value) || value.type !== "object")) {
|
||||
context.addIssue({ code: "custom", message: "A tool input schema root must have type 'object'" })
|
||||
}
|
||||
})
|
||||
.transform((value) => value as Output)
|
||||
}
|
||||
|
||||
export const toolPropertySchema = schemaContract<ToolSchemaNode>(false)
|
||||
export const toolInputSchemaSchema = schemaContract<ToolInputSchema>(true)
|
||||
|
||||
export const mockToolSchema = z.object({
|
||||
name: z.string().min(1).max(128).regex(/^[A-Za-z0-9_.-]+$/),
|
||||
title: z.string().min(1).max(200),
|
||||
description: z.string().min(1).max(2_000),
|
||||
kind: z.enum(["read", "mutation"]),
|
||||
inputSchema: toolInputSchemaSchema,
|
||||
})
|
||||
|
||||
export type MockTool = z.infer<typeof mockToolSchema>
|
||||
|
||||
export type ArgumentValidationResult =
|
||||
| { readonly success: true; readonly value: Readonly<Record<string, unknown>> }
|
||||
| { readonly success: false; readonly issues: readonly string[] }
|
||||
|
||||
interface ArgumentContext {
|
||||
remainingNodes: number
|
||||
readonly issues: string[]
|
||||
}
|
||||
|
||||
function validateNode(schema: ToolSchemaNode, value: unknown, path: string, depth: number, context: ArgumentContext): void {
|
||||
if (context.issues.length >= maximumArgumentIssues) return
|
||||
context.remainingNodes -= 1
|
||||
if (context.remainingNodes < 0) {
|
||||
context.issues.push(`Arguments exceed ${maximumArgumentNodes} values`)
|
||||
return
|
||||
}
|
||||
if (depth > maximumArgumentDepth) {
|
||||
context.issues.push(`${path} exceeds maximum argument depth ${maximumArgumentDepth}`)
|
||||
return
|
||||
}
|
||||
|
||||
if ("oneOf" in schema || "anyOf" in schema) {
|
||||
const branches = "oneOf" in schema ? schema.oneOf : schema.anyOf
|
||||
const validBranches = branches.filter((branch) => {
|
||||
const branchContext: ArgumentContext = { remainingNodes: context.remainingNodes, issues: [] }
|
||||
validateNode(branch, value, path, depth + 1, branchContext)
|
||||
return branchContext.issues.length === 0
|
||||
}).length
|
||||
const valid = "oneOf" in schema ? validBranches === 1 : validBranches >= 1
|
||||
if (!valid) context.issues.push(`${path} does not match the declared schema alternatives`)
|
||||
return
|
||||
}
|
||||
|
||||
if (schema.type === "string") {
|
||||
if (typeof value !== "string") context.issues.push(`${path} must be a string`)
|
||||
else if (schema.enum && !schema.enum.includes(value)) context.issues.push(`${path} must be one of ${schema.enum.join(", ")}`)
|
||||
else if (schema.minLength !== undefined && value.length < schema.minLength) context.issues.push(`${path} is shorter than ${schema.minLength}`)
|
||||
else if (schema.maxLength !== undefined && value.length > schema.maxLength) context.issues.push(`${path} is longer than ${schema.maxLength}`)
|
||||
return
|
||||
}
|
||||
if (schema.type === "number" || schema.type === "integer") {
|
||||
if (typeof value !== "number" || !Number.isFinite(value)) context.issues.push(`${path} must be a finite number`)
|
||||
else if (schema.type === "integer" && !Number.isInteger(value)) context.issues.push(`${path} must be an integer`)
|
||||
else if (schema.minimum !== undefined && value < schema.minimum) context.issues.push(`${path} must be at least ${schema.minimum}`)
|
||||
else if (schema.maximum !== undefined && value > schema.maximum) context.issues.push(`${path} must be at most ${schema.maximum}`)
|
||||
return
|
||||
}
|
||||
if (schema.type === "boolean") {
|
||||
if (typeof value !== "boolean") context.issues.push(`${path} must be a boolean`)
|
||||
return
|
||||
}
|
||||
if (schema.type === "null") {
|
||||
if (value !== null) context.issues.push(`${path} must be null`)
|
||||
return
|
||||
}
|
||||
if (schema.type === "array") {
|
||||
if (!Array.isArray(value)) {
|
||||
context.issues.push(`${path} must be an array`)
|
||||
return
|
||||
}
|
||||
if (schema.minItems !== undefined && value.length < schema.minItems) context.issues.push(`${path} requires at least ${schema.minItems} items`)
|
||||
if (schema.maxItems !== undefined && value.length > schema.maxItems) context.issues.push(`${path} accepts at most ${schema.maxItems} items`)
|
||||
value.forEach((item, index) => validateNode(schema.items, item, `${path}[${index}]`, depth + 1, context))
|
||||
return
|
||||
}
|
||||
|
||||
if (schema.type !== "object") {
|
||||
context.issues.push(`${path} uses an unsupported schema branch`)
|
||||
return
|
||||
}
|
||||
|
||||
if (!isRecord(value)) {
|
||||
context.issues.push(`${path} must be an object`)
|
||||
return
|
||||
}
|
||||
for (const requiredName of schema.required) {
|
||||
if (!Object.hasOwn(value, requiredName)) context.issues.push(`${path} is missing required property '${requiredName}'`)
|
||||
}
|
||||
for (const [name, propertyValue] of Object.entries(value)) {
|
||||
const property = Object.hasOwn(schema.properties, name) ? schema.properties[name] : undefined
|
||||
if (property) validateNode(property, propertyValue, `${path}.${name}`, depth + 1, context)
|
||||
else if (schema.additionalProperties === false) context.issues.push(`${path} contains unknown property '${name}'`)
|
||||
else if (schema.additionalProperties !== true) validateNode(schema.additionalProperties, propertyValue, `${path}.${name}`, depth + 1, context)
|
||||
}
|
||||
}
|
||||
|
||||
export function validateToolArguments(schema: ToolInputSchema, value: unknown): ArgumentValidationResult {
|
||||
if (!isRecord(value)) return { success: false, issues: ["Arguments must be an object"] }
|
||||
const context: ArgumentContext = { remainingNodes: maximumArgumentNodes, issues: [] }
|
||||
validateNode(schema, value, "$arguments", 0, context)
|
||||
return context.issues.length === 0 ? { success: true, value } : { success: false, issues: context.issues }
|
||||
}
|
||||
Reference in new issue
Block a user