@jsbot-tellus/core 2.9.1 → 2.10.0

package/dist/core/plugin/params/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/plugin/params/types.ts"],"names":[],"mappings":"AAsBA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAChC,KAAK,CAAQ;IAEtB,YAAY,OAAe,EAAE,KAAa;QACtC,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;QAChC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACtB,CAAC;CACJ;AAsBD,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC5C,OAAO,IAAI,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;AACzC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/plugin/params/types.ts"],"names":[],"mappings":"AAsBA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAChC,KAAK,CAAQ;IAEtB,YAAY,OAAe,EAAE,KAAa;QACtC,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;QAChC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACtB,CAAC;CACJ;AAkCD,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC5C,OAAO,IAAI,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;AACzC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,SAAyB;IACpD,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK;aAC1B,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;aACtB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QAEzB,OAAO,IAAI,OAAO,GAAG,CAAA;IACzB,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAA;IAE/B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC,IAAI,CAAA;IACzB,CAAC;IAED,OAAO,GAAG,SAAS,CAAC,IAAI,IAAI,MAAM,CAAC,GAAG,IAAI,EAAE,KAAK,MAAM,CAAC,GAAG,IAAI,EAAE,GAAG,CAAA;AACxE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAC/B,UAAqC;IAErC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;IAE7C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IAElC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAE/C,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;IAE5C,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAA;AACvD,CAAC"}

package/docs/plugin-api.md

@@ -250,6 +250,8 @@ ctx.commands.register(
 | `<arg:type>`          | 指定类型的必填参数                       |
 | `[arg:type=default]`  | 可选参数及默认值                         |
 | `<arg:string(2..10)>` | 带长度限制的字符串参数                   |
+| `<arg:type1\|type2>`  | 联合类型，按声明顺序尝试                 |
+| `<arg:'a'\|'b'>`      | 字面量联合，输入必须匹配其中一个值       |
 | `<arg:text>`          | 文本参数，消费全部剩余输入，必须放在最后 |
 | `[...rest]`           | 变长参数，每个剩余 token 作为一个字符串  |
 
@@ -277,20 +279,38 @@ params: '<message:text(2..200)> [nickname:string(..16)]'
 - 只能用于 `string` / `text`；其他类型和 `[...rest]` 会报声明错误。
 - 默认值也会在注册时校验；usage 不会显示长度限制。
 
+联合类型：
+
+`|` 可以把多个内置类型或字面量组合成一个参数，解析时按声明顺序尝试，第一个成功的候选生效：
+
+```ts
+params: "<value:string|integer> [mode:'fast'|'slow'='fast']"
+```
+
+- 内置类型联合：`<value:string|integer>`，handler 推导为 `string | number`。
+- 字面量联合：`<mode:'fast'|'slow'>`，输入必须精确等于其中一个值，区分大小写；handler 推导为 `'fast' | 'slow'`。字面量必须用单引号或双引号包裹，支持空格、`|`、`=`、`:` 和转义引号。
+- 顺序很重要：`<value:string|integer>` 会把 `123` 解析为字符串 `'123'`；需要数字时写成 `<value:integer|string>`。
+- `string` 候选可以带长度限制，例如 `<name:string(2..10)|integer>`。
+- `text` 和 `reply` 不能用于联合类型；`[...rest]` 仍然只收集字符串。
+- 默认值也按顺序尝试，例如 `[mode:'fast'|'slow'='fast']`。`at` 候选不支持默认值，会被跳过；如果所有候选都无法解析默认值，注册时抛错。
+- 重复的候选会被去重。
+- 可选字面量联合 `[mode:'fast'|'slow']` 推导为 `'fast' | 'slow' | undefined`；`CommandParamArgs<"<mode:'fast'|'slow'>">` 推导为 `['fast' | 'slow']`。
+
 固定参数可以用双引号或单引号包裹，例如 `/ask "hello world" 2` 会把 `hello world` 作为一个 token；引号内的反斜杠用于转义。
 
 解析规则：
 
 - `match.args` 和 `match.rest` 保持原始内容，不会被参数解析结果替换。
 - 声明槽位填完后，多余 token 会被忽略并记录 debug 日志，不会报错。`text` 和 `rest` 会消费全部剩余输入，因此不存在多余 token。
-- 必填参数缺失、已声明槽位类型错误、长度不符合限制或引号未闭合时，Router 会自动回复错误和用法，handler 不会执行。
+- 必填参数缺失、已声明槽位类型错误、联合类型的所有候选都不匹配、长度不符合限制或引号未闭合时，Router 会自动回复错误和用法，handler 不会执行。
 - usage 会自动生成，并显示在 `/help` 和指令组根命令的用法提示中。
 - 必填参数不能出现在可选参数之后；参数名不能重复；`text` 和变长参数必须放在最后；必填参数不能声明默认值；长度限制只能用于 `string` / `text`，上下限必须是非负整数且下限不能大于上限。
-- 当 `params` 是字符串字面量时，handler 从第四个参数开始的位置参数类型会自动推导。例如 `<question:string> [count:integer=1]` 会推导为 `(question: string, count: number)`，`[name:string]` 会推导为 `string | undefined`，`[...rest]` 会推导为 `...string[]`。
+- 联合类型的候选不能为空；`text` 和 `reply` 不能参与联合类型；字面量必须使用单引号或双引号包裹。
+- 当 `params` 是字符串字面量时，handler 从第四个参数开始的位置参数类型会自动推导。例如 `<question:string> [count:integer=1]` 会推导为 `(question: string, count: number)`，`[name:string]` 会推导为 `string | undefined`，`[...rest]` 会推导为 `...string[]`。联合类型会推导为 TypeScript 联合，例如 `<value:string|integer>` 推导为 `string | number`，`<mode:'fast'|'slow'>` 推导为 `'fast' | 'slow'`。
 - 需要在类型位置复用推导结果时，可以使用导出的 `CommandParamArgs<'<question:string>'>`。
 - 也可以继续手写 handler 参数注解；注解与声明不一致时会在编译期报错。
 - 自动推导只对字面量生效：运行时拼接的字符串，或显式声明为 `string` 的变量会回退为 `any[]`。需要保留字面量类型时，使用 `const` 变量或 `as const`。
-- 类型层解析覆盖上面的声明语法；如果默认值包含 `]` 等会干扰声明边界的字符，可能回退为 `any[]`，但不影响运行时解析。非法声明仍然在注册时抛错，而不是变成类型错误。
+- 类型层解析覆盖上面的声明语法，包括联合类型和引号字面量；如果字面量或默认值包含 `>`、`]` 等会干扰声明边界的字符，可能回退为 `any[]`，但不影响运行时解析。非法声明仍然在注册时抛错，而不是变成类型错误。
 
 参数错误示例：
 
@@ -298,6 +318,10 @@ params: '<message:text(2..200)> [nickname:string(..16)]'
 /ask hello abc
 -> 参数 count 需要是整数
 -> 用法：/ask <question> [count]
+
+/mode medium
+-> 参数 mode 需要是 'fast' 或 'slow'
+-> 用法：/mode <mode>
 ```
 
 ### 指令组

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jsbot-tellus/core",
-    "version": "2.9.1",
+    "version": "2.10.0",
     "engines": {
         "node": "^24.22.1 || >=26.12.1"
     },

package/src/core/plugin/params/declaration.ts

@@ -1,8 +1,12 @@
 import {
+    candidateLabel,
     declarationError,
+    joinCandidateLabels,
     type CommandParamType,
+    type ParamCandidate,
     type ParamLength,
     type ParamSpec,
+    type ParamTypeCandidate,
 } from './types.js'
 import {
     measureLength,
@@ -30,11 +34,6 @@ export function parseType(value: string): CommandParamType {
     }
 }
 
-interface ParsedType {
-    type: CommandParamType
-    length?: ParamLength | undefined
-}
-
 function parseLengthNumber(raw: string, token: string): number {
     const value = Number(raw)
 
@@ -70,12 +69,34 @@ function parseLength(raw: string, token: string): ParamLength {
     return { min, max }
 }
 
-function parseTypeDeclaration(raw: string, token: string): ParsedType {
-    const value = raw.trim()
+function isQuoted(value: string): boolean {
+    const quote = value[0]
+
+    return quote === '"' || quote === "'"
+}
+
+function parseLiteral(value: string, token: string): string {
+    const quote = value[0]
+
+    if (
+        (quote !== '"' && quote !== "'") ||
+        value.length < 2 ||
+        value[value.length - 1] !== quote
+    ) {
+        throw declarationError(`非法的字面量 "${value}"：${token}`)
+    }
+
+    return unquote(value)
+}
+
+function parseBuiltinCandidate(
+    value: string,
+    token: string
+): ParamTypeCandidate {
     const open = value.indexOf('(')
 
     if (open < 0) {
-        return { type: parseType(value) }
+        return { kind: 'type', type: parseType(value) }
     }
 
     if (!value.endsWith(')')) {
@@ -89,7 +110,112 @@ function parseTypeDeclaration(raw: string, token: string): ParsedType {
         throw declarationError(`只有 string/text 参数支持长度限制：${token}`)
     }
 
-    return { type, length }
+    return { kind: 'type', type, length }
+}
+
+function candidateKey(candidate: ParamCandidate): string {
+    if (candidate.kind === 'literal') {
+        return `literal:${candidate.value}`
+    }
+
+    const length = candidate.length
+    const range =
+        length === undefined ? '' : `${length.min ?? ''}..${length.max ?? ''}`
+
+    return `type:${candidate.type}:${range}`
+}
+
+function splitUnion(raw: string, token: string): string[] {
+    const parts: string[] = []
+    let current = ''
+    let quote: string | null = null
+
+    for (let index = 0; index < raw.length; index += 1) {
+        const char = raw[index]
+
+        if (char === undefined) break
+
+        if (quote !== null) {
+            current += char
+
+            if (char === '\\') {
+                const next = raw[index + 1]
+
+                if (next !== undefined) {
+                    current += next
+                    index += 1
+                }
+
+                continue
+            }
+
+            if (char === quote) {
+                quote = null
+            }
+
+            continue
+        }
+
+        if (char === '"' || char === "'") {
+            quote = char
+            current += char
+            continue
+        }
+
+        if (char === '|') {
+            parts.push(current)
+            current = ''
+            continue
+        }
+
+        current += char
+    }
+
+    if (quote !== null) {
+        throw declarationError(`参数 "${token}" 的引号未闭合`)
+    }
+
+    parts.push(current)
+
+    return parts
+}
+
+function parseCandidates(raw: string, token: string): ParamCandidate[] {
+    const candidates: ParamCandidate[] = []
+    const seen = new Set<string>()
+
+    for (const part of splitUnion(raw, token)) {
+        const value = part.trim()
+
+        if (!value) {
+            throw declarationError(`联合类型中存在空的类型：${token}`)
+        }
+
+        const candidate = isQuoted(value)
+            ? { kind: 'literal' as const, value: parseLiteral(value, token) }
+            : parseBuiltinCandidate(value, token)
+        const key = candidateKey(candidate)
+
+        if (seen.has(key)) continue
+
+        seen.add(key)
+        candidates.push(candidate)
+    }
+
+    if (candidates.length > 1) {
+        for (const candidate of candidates) {
+            if (
+                candidate.kind === 'type' &&
+                (candidate.type === 'text' || candidate.type === 'reply')
+            ) {
+                throw declarationError(
+                    `${candidate.type} 不能用于联合类型：${token}`
+                )
+            }
+        }
+    }
+
+    return candidates
 }
 
 function validateDefaultLength(
@@ -187,6 +313,84 @@ export function splitDeclaration(input: string): string[] {
     return parts
 }
 
+function hasUnquotedEllipsis(value: string): boolean {
+    let quote: string | null = null
+
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index]
+
+        if (char === undefined) break
+
+        if (quote !== null) {
+            if (char === '\\') {
+                index += 1
+                continue
+            }
+
+            if (char === quote) {
+                quote = null
+            }
+
+            continue
+        }
+
+        if (char === '"' || char === "'") {
+            quote = char
+            continue
+        }
+
+        if (value.startsWith('...', index)) {
+            return true
+        }
+    }
+
+    return false
+}
+
+function splitDefault(
+    inner: string,
+    token: string
+): { head: string; defaultRaw?: string | undefined } {
+    let quote: string | null = null
+
+    for (let index = 0; index < inner.length; index += 1) {
+        const char = inner[index]
+
+        if (char === undefined) break
+
+        if (quote !== null) {
+            if (char === '\\') {
+                index += 1
+                continue
+            }
+
+            if (char === quote) {
+                quote = null
+            }
+
+            continue
+        }
+
+        if (char === '"' || char === "'") {
+            quote = char
+            continue
+        }
+
+        if (char === '=') {
+            return {
+                head: inner.slice(0, index).trim(),
+                defaultRaw: inner.slice(index + 1).trim(),
+            }
+        }
+    }
+
+    if (quote !== null) {
+        throw declarationError(`参数 "${token}" 的引号未闭合`)
+    }
+
+    return { head: inner.trim() }
+}
+
 export function parseToken(token: string): ParamSpec {
     const open = token[0]
     const close = token[token.length - 1]
@@ -221,23 +425,22 @@ export function parseToken(token: string): ParamSpec {
 
         return {
             name,
-            type: 'string',
+            candidates: [{ kind: 'type', type: 'string' }],
             required: false,
             rest: true,
             hasDefault: false,
         }
     }
 
-    if (inner.includes('...')) {
+    const { head, defaultRaw } = splitDefault(inner, token)
+
+    if (hasUnquotedEllipsis(head)) {
         throw declarationError(`非法的参数声明 "${token}"`)
     }
 
-    const equals = inner.indexOf('=')
-    const head = equals >= 0 ? inner.slice(0, equals).trim() : inner.trim()
-    const defaultRaw = equals >= 0 ? inner.slice(equals + 1).trim() : undefined
     const colon = head.indexOf(':')
     const name = validateName(colon >= 0 ? head.slice(0, colon) : head)
-    const { type, length } = parseTypeDeclaration(
+    const candidates = parseCandidates(
         colon >= 0 ? head.slice(colon + 1) : 'string',
         token
     )
@@ -247,33 +450,33 @@ export function parseToken(token: string): ParamSpec {
     }
 
     if (defaultRaw !== undefined) {
-        const defaultValue = parseDefaultValue(type, defaultRaw, name)
-
-        if (typeof defaultValue === 'string') {
-            validateDefaultLength(name, defaultValue, length)
-        }
+        const defaultValue = parseDefaultValue(candidates, defaultRaw, name)
 
         return {
             name,
-            type,
+            candidates,
             required,
             rest: false,
             hasDefault: true,
             defaultValue,
-            length,
         }
     }
 
     return {
         name,
-        type,
+        candidates,
         required,
         rest: false,
         hasDefault: false,
-        length,
     }
 }
 
+function hasTextCandidate(spec: ParamSpec): boolean {
+    return spec.candidates.some(
+        (candidate) => candidate.kind === 'type' && candidate.type === 'text'
+    )
+}
+
 export function validateSpecs(specs: ParamSpec[]): void {
     const names = new Set<string>()
     let seenOptional = false
@@ -308,7 +511,7 @@ export function validateSpecs(specs: ParamSpec[]): void {
             continue
         }
 
-        if (spec.type === 'text') {
+        if (hasTextCandidate(spec)) {
             if (index !== specs.length - 1) {
                 throw declarationError('文本参数必须放在最后')
             }
@@ -333,23 +536,32 @@ export function usageOf(specs: ParamSpec[]): string {
                 return `[...${spec.name}]`
             }
 
-            const name = spec.type === 'text' ? `${spec.name}...` : spec.name
+            const name = hasTextCandidate(spec) ? `${spec.name}...` : spec.name
 
             return spec.required ? `<${name}>` : `[${name}]`
         })
         .join(' ')
 }
 
-export function parseDefaultValue(
-    type: CommandParamType,
-    raw: string,
+function parseDefaultCandidate(
+    candidate: ParamCandidate,
+    value: string,
     name: string
 ): unknown {
-    const value = unquote(raw)
+    if (candidate.kind === 'literal') {
+        if (value === candidate.value) {
+            return value
+        }
+
+        throw declarationError(
+            `参数 ${name} 的默认值需要是 ${candidateLabel(candidate)}`
+        )
+    }
 
-    switch (type) {
+    switch (candidate.type) {
         case 'string':
         case 'text':
+            validateDefaultLength(name, value, candidate.length)
             return value
         case 'number': {
             const number = value.trim() === '' ? Number.NaN : Number(value)
@@ -392,3 +604,29 @@ export function parseDefaultValue(
         }
     }
 }
+
+export function parseDefaultValue(
+    candidates: ParamCandidate[],
+    raw: string,
+    name: string
+): unknown {
+    const value = unquote(raw)
+
+    if (candidates.length === 1) {
+        return parseDefaultCandidate(candidates[0]!, value, name)
+    }
+
+    for (const candidate of candidates) {
+        try {
+            return parseDefaultCandidate(candidate, value, name)
+        } catch (error) {
+            if (!(error instanceof Error)) {
+                throw error
+            }
+        }
+    }
+
+    throw declarationError(
+        `参数 ${name} 的默认值需要是 ${joinCandidateLabels(candidates)}`
+    )
+}

package/src/core/plugin/params/input.ts

@@ -1,6 +1,10 @@
 import {
+    candidateLabel,
     CommandParamsError,
+    joinCandidateLabels,
     type InputToken,
+    type ParamCandidate,
+    type ParamLength,
     type ParamSpec,
     type ParsedCommandParams,
 } from './types.js'
@@ -101,9 +105,12 @@ export function tokenizeInput(input: string, usage: string): InputToken[] {
     return tokens
 }
 
-function enforceLength(spec: ParamSpec, value: string, usage: string): string {
-    const length = spec.length
-
+function enforceLength(
+    name: string,
+    length: ParamLength | undefined,
+    value: string,
+    usage: string
+): string {
     if (length === undefined) {
         return value
     }
@@ -112,14 +119,14 @@ function enforceLength(spec: ParamSpec, value: string, usage: string): string {
 
     if (length.min !== undefined && measured < length.min) {
         throw new CommandParamsError(
-            `参数 ${spec.name} 至少需要 ${length.min} 个字符`,
+            `参数 ${name} 至少需要 ${length.min} 个字符`,
             usage
         )
     }
 
     if (length.max !== undefined && measured > length.max) {
         throw new CommandParamsError(
-            `参数 ${spec.name} 不能超过 ${length.max} 个字符`,
+            `参数 ${name} 不能超过 ${length.max} 个字符`,
             usage
         )
     }
@@ -127,16 +134,27 @@ function enforceLength(spec: ParamSpec, value: string, usage: string): string {
     return value
 }
 
-export function parseValue(
+function parseCandidate(
+    candidate: ParamCandidate,
     spec: ParamSpec,
     raw: string,
     usage: string
 ): unknown {
-    switch (spec.type) {
+    if (candidate.kind === 'literal') {
+        if (raw === candidate.value) {
+            return raw
+        }
+
+        throw new CommandParamsError(
+            `参数 ${spec.name} 需要是 ${candidateLabel(candidate)}`,
+            usage
+        )
+    }
+
+    switch (candidate.type) {
         case 'string':
-            return enforceLength(spec, raw, usage)
         case 'text':
-            return raw
+            return enforceLength(spec.name, candidate.length, raw, usage)
         case 'number': {
             const value = raw.trim() === '' ? Number.NaN : Number(raw)
 
@@ -175,11 +193,41 @@ export function parseValue(
         }
         case 'at':
             return parseAt(raw, spec.name, usage)
+        case 'reply':
+            throw new CommandParamsError(
+                `参数 ${spec.name} 需要引用一条消息`,
+                usage
+            )
         case 'time':
             return parseTime(raw, spec.name, usage)
     }
 }
 
+export function parseValue(
+    spec: ParamSpec,
+    raw: string,
+    usage: string
+): unknown {
+    if (spec.candidates.length === 1) {
+        return parseCandidate(spec.candidates[0]!, spec, raw, usage)
+    }
+
+    for (const candidate of spec.candidates) {
+        try {
+            return parseCandidate(candidate, spec, raw, usage)
+        } catch (error) {
+            if (!(error instanceof CommandParamsError)) {
+                throw error
+            }
+        }
+    }
+
+    throw new CommandParamsError(
+        `参数 ${spec.name} 需要是 ${joinCandidateLabels(spec.candidates)}`,
+        usage
+    )
+}
+
 export function parseInput(
     specs: ParamSpec[],
     input: string,
@@ -191,7 +239,10 @@ export function parseInput(
     let index = 0
 
     for (const spec of specs) {
-        if (spec.type === 'reply') {
+        const sole =
+            spec.candidates.length === 1 ? spec.candidates[0] : undefined
+
+        if (sole?.kind === 'type' && sole.type === 'reply') {
             if (quoteId !== undefined) {
                 args.push(quoteId)
             } else if (spec.required) {
@@ -223,7 +274,7 @@ export function parseInput(
             continue
         }
 
-        if (spec.type === 'text') {
+        if (sole?.kind === 'type' && sole.type === 'text') {
             const token = tokens[index]
 
             if (!token) {
@@ -245,7 +296,7 @@ export function parseInput(
             const value =
                 remaining === 1 ? token.value : input.slice(token.start).trim()
 
-            args.push(enforceLength(spec, value, usage))
+            args.push(enforceLength(spec.name, sole.length, value, usage))
             index = tokens.length
             continue
         }