koishi-plugin-kkk 1.0.0

package/src/richtext/types.ts

@@ -0,0 +1,320 @@
+/**
+ * 富文本节点联合类型。
+ *
+ * 后端只需要生产这些纯 JSON 节点，前端可以再按 React、HTML、Canvas 等不同目标渲染。
+ */
+export type RichTextNode = RichTextInlineNode | RichTextBlockNode
+
+/** 行内节点。 */
+export type RichTextInlineNode =
+  | RichTextTextNode
+  | RichTextEmojiNode
+  | RichTextMentionNode
+  | RichTextSearchKeywordNode
+  | RichTextLineBreakNode
+  | RichTextTopicNode
+  | RichTextAtNode
+  | RichTextLotteryNode
+  | RichTextWebLinkNode
+  | RichTextOpusLinkNode
+  | RichTextVoteNode
+  | RichTextViewPictureNode
+  | RichTextHashtagNode
+
+/** 块级节点。 */
+export type RichTextBlockNode =
+  | RichTextHeadingNode
+  | RichTextParagraphNode
+  | RichTextImageNode
+  | RichTextBlockquoteNode
+  | RichTextListNode
+  | RichTextListItemNode
+  | RichTextCodeBlockNode
+  | RichTextLinkCardNode
+  | RichTextHorizontalRuleNode
+
+/**
+ * 富文本文档。
+ *
+ * `version` 用来给后续节点协议升级留空间；`platform` 用来标记来源平台，方便后续按平台做兼容。
+ */
+export interface RichTextDocument {
+  version: 1
+  platform?: string
+  nodes: RichTextNode[]
+}
+
+/** 行内文本样式。 */
+export interface RichTextInlineStyle {
+  /** 粗体 */
+  bold?: boolean
+  /** 斜体 */
+  italic?: boolean
+  /** 删除线 */
+  strike?: boolean
+  /** 文字颜色（CSS color 值） */
+  color?: string
+  /** 超链接地址 */
+  link?: string
+  /** 字体大小（CSS font-size 值） */
+  fontSize?: string
+}
+
+/** 普通文本节点。文本永远作为文本渲染，不会当成 HTML 执行。 */
+export interface RichTextTextNode {
+  type: 'text'
+  /** 文本内容 */
+  text: string
+  /** 可选的行内样式 */
+  style?: RichTextInlineStyle
+}
+
+/** 行内表情节点。用于评论文本中夹杂的平台表情图片。 */
+export interface RichTextEmojiNode {
+  type: 'emoji'
+  /** 表情包名称 */
+  name: string
+  /** 表情包链接 */
+  src: string
+  /** 缩放倍率。默认 1，某些平台的大表情可以传 3。 */
+  scale?: number
+}
+
+/** @ 用户节点。`userId` 可选，因为有些平台只给历史昵称，不给稳定 ID。 */
+export interface RichTextMentionNode {
+  type: 'mention'
+  /** @ 用户的文本 */
+  text: string
+  /** UID */
+  userId?: string
+}
+
+/**
+ * 搜索词高亮节点。
+ *
+ * 某些平台会把"评论里的高亮搜索词"独立放在元数据里，而不是单独拼进 HTML。
+ * 这里把它提升成独立节点，方便 template 渲染成高亮文本和上标搜索图标。
+ */
+export interface RichTextSearchKeywordNode {
+  type: 'searchKeyword'
+  /** 搜索词 */
+  text: string
+  /** 搜索ID */
+  queryId?: string
+}
+
+/** 换行节点。前端渲染成 `<br />`，避免后端直接拼 HTML。 */
+export interface RichTextLineBreakNode {
+  type: 'lineBreak'
+}
+
+/** 话题节点。B站动态中以 #话题名称# 形式呈现，带彩色文字。 */
+export interface RichTextTopicNode {
+  type: 'topic'
+  /** 话题名称（不含#号） */
+  text: string
+}
+
+/** @用户节点。用于动态描述中的@提及。 */
+export interface RichTextAtNode {
+  type: 'at'
+  /** @用户的显示文本 */
+  text: string
+  /** 用户ID（可选） */
+  userId?: string
+}
+
+/** 抽奖节点。带SVG图标，显示抽奖信息。 */
+export interface RichTextLotteryNode {
+  type: 'lottery'
+  /** 显示文本 */
+  text: string
+}
+
+/** 网页链接节点。带SVG图标，显示链接的标题。 */
+export interface RichTextWebLinkNode {
+  type: 'webLink'
+  /** 显示文本（如网页标题） */
+  text: string
+  /** 跳转链接 */
+  jumpUrl: string
+}
+
+/**
+ * 站内图文链接节点。带SVG图标，显示图文标题。
+ *
+ * 对应 B站 opus 正文里的高亮链接（官方页面上的 `opus-text-rich-hl`）。
+ * 模板渲染不需要交互，所以只渲染图标和文本；`url` 留给纯文本场景（如合并转发）拼出链接。
+ */
+export interface RichTextOpusLinkNode {
+  type: 'opusLink'
+  /** 显示文本（如图文标题） */
+  text: string
+  /** 跳转链接 */
+  url: string
+}
+
+/** 投票节点。带SVG图标，显示投票标题。 */
+export interface RichTextVoteNode {
+  type: 'vote'
+  /** 投票标题 */
+  text: string
+}
+
+/** 查看图片节点。带SVG图标，提示用户点击查看图片。 */
+export interface RichTextViewPictureNode {
+  type: 'viewPicture'
+  /** 显示文本 */
+  text: string
+}
+
+/**
+ * Hashtag 话题节点。
+ *
+ * 纯文本高亮，不带任何图标。用于抖音等平台的 #话题# 标签展示。
+ * 与 topic 节点的区别：topic 带有 B站风格的 # 图标，hashtag 只做纯文字高亮。
+ */
+export interface RichTextHashtagNode {
+  type: 'hashtag'
+  /** 话题文本（包含 # 号） */
+  text: string
+}
+
+/** 标题节点。 */
+export interface RichTextHeadingNode {
+  type: 'heading'
+  /** 标题级别 1-6 */
+  level: 1 | 2 | 3 | 4 | 5 | 6
+  /** 子节点 */
+  nodes: RichTextNode[]
+}
+
+/** 段落节点。 */
+export interface RichTextParagraphNode {
+  type: 'paragraph'
+  /** 子节点 */
+  nodes: RichTextNode[]
+}
+
+/** 图片节点。 */
+export interface RichTextImageNode {
+  type: 'image'
+  /** 图片地址 */
+  src: string
+  /** 替代文本 */
+  alt?: string
+  /** 图片下方注释/说明文字 */
+  caption?: string
+}
+
+/** 水平分隔线节点。 */
+export interface RichTextHorizontalRuleNode {
+  type: 'horizontalRule'
+}
+
+/** 引用块节点。 */
+export interface RichTextBlockquoteNode {
+  type: 'blockquote'
+  /** 子节点 */
+  nodes: RichTextNode[]
+}
+
+/** 列表节点。 */
+export interface RichTextListNode {
+  type: 'list'
+  /** 是否为有序列表 */
+  ordered: boolean
+  /** 列表项 */
+  items: RichTextListItemNode[]
+}
+
+/** 列表项节点。 */
+export interface RichTextListItemNode {
+  type: 'listItem'
+  /** 子节点 */
+  nodes: RichTextNode[]
+}
+
+/** 代码块节点。 */
+export interface RichTextCodeBlockNode {
+  type: 'codeBlock'
+  /** 代码语言 */
+  language?: string
+  /** 代码内容 */
+  content: string
+}
+
+/** 链接卡片节点。 */
+export interface RichTextLinkCardNode {
+  type: 'linkCard'
+  /** 卡片标题/显示文本 */
+  title: string
+  /** 跳转链接 */
+  url: string
+  /** 卡片类型标识 */
+  cardType?: string
+  /** 额外元数据 */
+  meta?: Record<string, any>
+}
+
+/** 平台表情定义，通常由 core 从平台表情接口转换得到。 */
+export interface RichTextEmojiDefinition {
+  name: string
+  url: string
+  /** 缩放倍率。默认 1。 */
+  scale?: number
+}
+
+/**
+ * 单个富文本节点的样式配置。
+ *
+ * 平台模板传入它们想要的 className，渲染器直接应用。
+ * 只允许 className，不允许 style 对象——视觉样式全部由 Tailwind 接管。
+ */
+export interface RichTextNodeStyleConfig {
+  /** Tailwind className，控制该节点的视觉样式 */
+  className?: string
+}
+
+/**
+ * 搜索关键词节点需要额外的图标 className（普通节点不需要）。
+ */
+export interface RichTextSearchKeywordStyleConfig extends RichTextNodeStyleConfig {
+  /** 搜索图标的额外 className */
+  iconClassName?: string
+}
+
+/**
+ * HTML 渲染器配置。React 渲染器复用这些 className 约定。
+ *
+ * 传入的 className 会覆盖渲染器内部对这些节点的默认样式。
+ * 视觉样式全部由 Tailwind className 表达，渲染器只负责结构。
+ */
+export interface RichTextRenderOptions {
+  /** @提及节点 */
+  mention?: RichTextNodeStyleConfig
+  /** 搜索关键词节点（高亮词） */
+  searchKeyword?: RichTextSearchKeywordStyleConfig
+  /** 话题节点 */
+  topic?: RichTextNodeStyleConfig
+  /** @用户节点 */
+  at?: RichTextNodeStyleConfig
+  /** 抽奖节点 */
+  lottery?: RichTextNodeStyleConfig
+  /** 网页链接节点 */
+  webLink?: RichTextNodeStyleConfig
+  /** 站内图文链接节点 */
+  opusLink?: RichTextNodeStyleConfig
+  /** 投票节点 */
+  vote?: RichTextNodeStyleConfig
+  /** 查看图片节点 */
+  viewPicture?: RichTextNodeStyleConfig
+  /** 代码块节点 */
+  codeBlock?: RichTextNodeStyleConfig
+  /** 链接卡片节点 */
+  linkCard?: RichTextNodeStyleConfig
+  /** hashtag 话题节点 */
+  hashtag?: RichTextNodeStyleConfig
+  /** 图标缩放比例，默认 1。用于在不同字体大小下保持图标比例一致。 */
+  iconScale?: number
+}

package/src/schema.ts

@@ -0,0 +1,372 @@
+/**
+ * 把插件自己的配置（上游的 config.json）映射成 Koishi 的控制台表单。
+ *
+ * 上游 Karin 版把这些配置放在 \`config/config.json\`（amagi / app / douyin / bilibili / kuaishou /
+ * xiaohongshu / pushlist 七个模块），由它的 WebUI 编辑。Koishi 侧如果只声明集成选项，
+ * 控制台的「插件配置」里就看不到清晰度这类选项 —— 所以这里**按默认配置的形状动态生成 Schema**：
+ *   - 结构、键名与上游完全一致，升级上游默认配置后表单会自动跟着变；
+ *   - 描述取自上游 \`config/default_config/*.yaml\` 里每个字段上方的中文注释（Karin 版的字段说明）；
+ *   - **默认值取自同一份默认配置**：所有字段在控制台里都显示真实取值，而不是一片空白；
+ *   - **枚举型字段渲染成下拉框**：取值直接从注释里解析（「可选值：'info'(视频信息)…」、
+ *     \`- 6: 240P 极速\` 这类列表、\`all为所有人\` 这类权限说明），选项文案用注释里的中文说明。
+ *
+ * ⚠️ 默认值带来的副作用（已在 configBridge 里处理）：Koishi 会把默认值填进配置对象，
+ * 于是「没填」和「填了默认值」不再靠有没有值来区分，改为**与上游默认值相等即视为没填**，
+ * 这样用户直接改 config.json 的内容不会在下次启动时被表单里的默认值覆盖。
+ * 代价：在控制台里把某项改回默认值，不会写回 config.json（想强制改回请用 /kkk 面板或直接改文件）。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { Schema } from 'koishi'
+
+/** 递归深度上限，避免异常配置把 Schema 撑爆 */
+const MAX_DEPTH = 6
+
+/** \`douyin.videoQuality\` -> 「视频画质偏好设置…」 */
+export type DescriptionMap = Record<string, string>
+
+/** 一个下拉选项 */
+export interface EnumOption {
+  value: string | number
+  label: string
+}
+
+/** 一个字段的注释信息 */
+export interface FieldMeta {
+  /** 注释正文（拼成一段） */
+  text: string
+  /** 从注释里解析出来的候选值；没有就是普通输入框 */
+  options?: EnumOption[]
+}
+
+export type MetaMap = Record<string, FieldMeta>
+
+/**
+ * 补充说明：上游 YAML 里没有（字段是后加的）或只作为模块容器出现的字段，
+ * 按 \`src/karin/types/config/*.ts\` 的 JSDoc 与实际用途补上。YAML 里已有的说明优先。
+ */
+const SUPPLEMENT: DescriptionMap = {
+  amagi: 'amagi 解析库配置：请求超时、UA、代理、各平台 Cookie、内置 API Server',
+  'amagi.proxy.switch': '是否启用代理',
+  'amagi.cookies': '各平台 Cookie，扫码登录成功后会自动写入这里',
+  'amagi.cookies.bilibili': 'B站 Cookie（SESSDATA 等），配置后才能拿高画质与动态推送',
+  'amagi.cookies.douyin': '抖音 Cookie，配置后才能解析作品与推送',
+  'amagi.cookies.kuaishou': '快手 Cookie',
+  'amagi.cookies.xiaohongshu': '小红书 Cookie',
+  app: '全局通用设置：解析总开关、渲染、缓存、错误上报等',
+  'app.ambientCover': '封面氛围背景参数：控制封面图对模板背景氛围的贡献度，取值 0~1',
+  'app.ambientCover.coverOpacity': '模糊封面层不透明度：封面色强度总闸，越大整体越浓',
+  'app.ambientCover.overlayEdgeOpacity': '主题色压色罩两端（顶/底）不透明度',
+  'app.ambientCover.overlayMiddleOpacity': '主题色压色罩中间带不透明度，越小封面色越透',
+  douyin: '抖音解析与推送设置',
+  bilibili: 'B站解析与推送设置',
+  kuaishou: '快手解析设置',
+  xiaohongshu: '小红书解析设置',
+  pushlist: '推送订阅列表：每一项是「关注对象 + 群号:机器人账号」，可加过滤词/标签',
+  'xiaohongshu.watermark': '小红书图片是否加水印（上游保留项）'
+}
+
+/**
+ * 注释里解析不出来的枚举，手工补。
+ * 只补「取值域封闭、写错就跑不起来」的字段；普通数值/文本**不要**往这里加，
+ * 否则控制台会把人限制在几个选项里。
+ */
+const SUPPLEMENT_ENUMS: Record<string, EnumOption[]> = {
+  'app.Theme': [
+    { value: 0, label: '自动（06:00-18:00 浅色，其余深色）' },
+    { value: 1, label: '浅色' },
+    { value: 2, label: '深色' },
+    { value: 3, label: '智能场景（按封面判断深浅）' }
+  ],
+  'douyin.push.shareType': [
+    { value: 'web', label: '跳转到抖音网页' },
+    { value: 'download', label: '视频下载直链' }
+  ]
+}
+
+/** 权限类字段：值就是 all / admin / master / group.owner / group.admin */
+const PERMISSION_VALUES: EnumOption[] = [
+  { value: 'all', label: '所有人' },
+  { value: 'admin', label: '管理员' },
+  { value: 'master', label: '主人' },
+  { value: 'group.owner', label: '群主' },
+  { value: 'group.admin', label: '群管理员' }
+]
+
+/** 字段名命中权限域 */
+const isPermissionField = (name: string): boolean => /^(loginPerm|permission)$/i.test(name)
+
+/** 剥掉列表项的 \`[]\` 后缀，用于回查字段名 */
+const shortName = (fieldPath: string): string => fieldPath.split('.').pop()!.replace(/\[\]$/, '')
+
+/**
+ * 从注释行里抽枚举候选。
+ *
+ * 支持的三种写法（都是上游 YAML 里真实存在的）：
+ * 1. \`可选值：'info'(视频信息)、'comment'(评论图片)\` —— 引号里的值 + 紧跟的中文说明；
+ * 2. 列表项 \`- 6: 240P 极速\` / \`- 'off': 关闭\` / \`- 'google' - Google Motion Photo\`；
+ * 3. \`all为所有人，admin为管理员…\` —— 权限字段常见写法。
+ * @param lines 该字段的注释行
+ * @param name 字段名（判断是不是权限域）
+ */
+function extractOptions (lines: string[], name: string): EnumOption[] | undefined {
+  const found = new Map<string, string>()
+  const add = (rawValue: string, label: string) => {
+    const value = String(rawValue ?? '').trim().replace(/^['"]|['"]$/g, '')
+    const text = String(label ?? '').replace(/^[\s:：\-—]+/, '').replace(/[，,。；;]+$/, '').trim()
+    if (!value || found.has(value)) return
+    found.set(value, text)
+  }
+
+  for (const line of lines) {
+    const bullet = line.match(/^\s*[-*·]\s+(.+)$/)
+    if (bullet) {
+      const item = bullet[1].match(/^['"]?([^'"\s:：]+)['"]?\s*(?:[:：\-—]\s*)?(.*)$/)
+      if (item) add(item[1], item[2])
+      continue
+    }
+
+    if (/可选值|可选：/.test(line)) {
+      const quoted = /['"]([^'"]+)['"]/g
+      let matched: RegExpExecArray | null
+      while ((matched = quoted.exec(line)) !== null) {
+        const rest = line.slice(quoted.lastIndex)
+        /**
+         * 候选值后面必须紧跟「说明括号 / 顿号 / 逗号 / 句号 / 结束」。
+         * 这条约束是为了滤掉解释性文字里的引号 —— 例如
+         * 「'master'（除'console'外的第一个主人）」里的 'console' 后面是「外」，
+         * 不加约束就会多出一个叫 console 的假选项。
+         */
+        if (!/^\s*([（(、，,。;；]|$)/.test(rest)) continue
+        const label = rest.match(/^\s*[（(]([^）)]*)[）)]/)
+        add(matched[1], label ? label[1] : '')
+      }
+      continue
+    }
+
+    if (isPermissionField(name)) {
+      const words = /([a-zA-Z][\w.]*)为/g
+      let matched: RegExpExecArray | null
+      while ((matched = words.exec(line)) !== null) add(matched[1], '')
+    }
+  }
+
+  // 「0为自动，1为浅色，2为深色」这类数字枚举：至少 3 个才算，避免把「0-100」这种区间误判成枚举
+  const numeric = new Map<string, string>()
+  for (const line of lines) {
+    const numbers = /(\d+(?:\.\d+)?)\s*为/g
+    let matched: RegExpExecArray | null
+    while ((matched = numbers.exec(line)) !== null) {
+      if (!numeric.has(matched[1])) numeric.set(matched[1], '')
+    }
+  }
+  if (numeric.size >= 3) for (const [value, label] of numeric) add(value, label)
+
+  return found.size >= 2 ? [...found].map(([value, label]) => ({ value, label })) : undefined
+}
+
+/**
+ * 解析 \`config/default_config/*.yaml\` 里的字段注释。
+ *
+ * 形如：
+ * \`\`\`yaml
+ * # 视频体积上限，自适应画质模式下可接受的最大视频大小（单位：MB）
+ * maxAutoVideoSize: 50
+ * \`\`\`
+ * 注释写在字段上方、连续若干行，用缩进判断层级。
+ * @param pluginRoot 插件根目录
+ */
+export function parseConfigMeta (pluginRoot: string): MetaMap {
+  const dir = path.join(pluginRoot, 'config', 'default_config')
+  const result: MetaMap = {}
+  let files: string[] = []
+  try {
+    files = fs.readdirSync(dir).filter((item) => item.endsWith('.yaml'))
+  } catch {
+    return result
+  }
+
+  for (const file of files) {
+    const mod = file.replace(/\.yaml$/, '')
+    let content = ''
+    try {
+      content = fs.readFileSync(path.join(dir, file), 'utf8')
+    } catch {
+      continue
+    }
+    const stack: Array<{ indent: number; key: string }> = []
+    let comments: string[] = []
+
+    for (const rawLine of content.split(/\r?\n/)) {
+      const trimmed = rawLine.trim()
+      if (!trimmed) {
+        comments = []
+        continue
+      }
+      if (trimmed.startsWith('#')) {
+        comments.push(trimmed.replace(/^#\s?/, '').trimEnd())
+        continue
+      }
+      const matched = rawLine.match(/^(\s*)([^\s:#][^:#]*?)\s*:/)
+      if (!matched) {
+        // 数组项、缩进文本等
+        comments = []
+        continue
+      }
+      const indent = matched[1].length
+      const key = matched[2].trim().replace(/^['"]|['"]$/g, '')
+      while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop()
+      stack.push({ indent, key })
+
+      const fullPath = [mod, ...stack.map((item) => item.key)].join('.')
+      const text = comments.join(' ').replace(/\s+/g, ' ').trim()
+      if (text && !result[fullPath]) {
+        result[fullPath] = { text, options: extractOptions(comments, key) }
+      }
+      comments = []
+    }
+  }
+
+  // 上游把若干旧 YAML 合并进了 config.json 的模块（例如 amagi 里混着 request/cookies 的字段），
+  // 这些字段的完整路径对不上，补一张「唯一短名 → 描述」的表兜底。
+  const flatCount: Record<string, number> = {}
+  const flat: MetaMap = {}
+  for (const [key, value] of Object.entries(result)) {
+    const name = key.split('.').pop()!
+    flatCount[name] = (flatCount[name] ?? 0) + 1
+    flat[name] = value
+  }
+  for (const [name, count] of Object.entries(flatCount)) {
+    if (count === 1) result['#' + name] = flat[name]
+  }
+  return result
+}
+
+/** 只取描述文本（对外保留的旧接口） */
+export function parseConfigDescriptions (pluginRoot: string): DescriptionMap {
+  const meta = parseConfigMeta(pluginRoot)
+  const result: DescriptionMap = {}
+  for (const [key, value] of Object.entries(meta)) result[key] = value.text
+  return result
+}
+
+/**
+ * 取某个字段路径的注释信息：完整路径 → 去掉 \`[]\` 的路径 → 唯一短名兜底。
+ *
+ * 中间那一跳是为数组元素准备的：枚举解析时用的是 \`xxx[]\`，
+ * 而注释是按 \`xxx\` 登记的；同名短名（douyin/bilibili 都有 displayContent）又轮不到兜底表，
+ * 少这一跳数组字段就永远拿不到下拉选项。
+ */
+function metaOf (meta: MetaMap, fieldPath: string): FieldMeta | undefined {
+  return meta[fieldPath]
+    ?? meta[fieldPath.replace(/\[\]$/, '')]
+    ?? meta['#' + shortName(fieldPath)]
+}
+
+/** 取某个字段路径的描述：YAML 说明 → 唯一的短名兜底 → 手工补充 */
+function describe (meta: MetaMap, fieldPath: string): string | undefined {
+  return metaOf(meta, fieldPath)?.text ?? SUPPLEMENT[fieldPath]
+}
+
+/**
+ * 把候选值对齐到字段的类型上。
+ * @param options 候选值
+ * @param sample 该字段的默认值（决定类型）
+ * @returns 可用的下拉选项；类型对不上或不足 2 个时返回 undefined
+ */
+function coerceOptions (options: EnumOption[] | undefined, sample: unknown): EnumOption[] | undefined {
+  if (!options || options.length < 2) return undefined
+  const seen = new Set<string | number>()
+  const result: EnumOption[] = []
+  for (const option of options) {
+    let value: string | number
+    if (typeof sample === 'number') {
+      value = Number(option.value)
+      if (!Number.isFinite(value)) continue
+    } else if (typeof sample === 'string') {
+      value = String(option.value)
+    } else {
+      return undefined
+    }
+    if (seen.has(value)) continue
+    seen.add(value)
+    result.push({ value, label: option.label })
+  }
+  return result.length >= 2 ? result : undefined
+}
+
+/** 生成叶子字段（枚举 → 下拉；否则按类型给输入框），并带上默认值与说明 */
+function leafSchema (sample: unknown, fieldPath: string, meta: MetaMap, ensure: unknown[] = []): Schema {
+  const withDesc = (schema: Schema): Schema => {
+    const text = describe(meta, fieldPath)
+    return text ? schema.description(text) : schema
+  }
+
+  // 手工枚举优先（选项文案更清楚），没有就用注释里解析出来的
+  const options = coerceOptions(SUPPLEMENT_ENUMS[fieldPath] ?? metaOf(meta, fieldPath)?.options, sample)
+  if (options) {
+    const list = [...options]
+    /**
+     * 默认值必须出现在选项里。
+     * 对数组字段这不是理论问题：上游注释里 \`douyin.displayContent\` 就漏写了 \`desc\`，
+     * 而默认值里有它 —— 不补进去，控制台一保存就会写出一个 Schema 校验不过的值。
+     */
+    for (const value of [sample, ...ensure]) {
+      if (typeof value !== 'string' && typeof value !== 'number') continue
+      if (list.some((option) => option.value === value)) continue
+      list.unshift({ value, label: String(value) + '（默认值，注释里未列出）' })
+    }
+    const union = Schema.union(
+      list.map((option) => Schema.const(option.value as never).description(option.label || String(option.value)))
+    )
+    return withDesc(union.default(sample as never))
+  }
+
+  if (typeof sample === 'boolean') return withDesc(Schema.boolean().default(sample))
+  if (typeof sample === 'number') return withDesc(Schema.number().default(sample))
+  if (typeof sample === 'string') return withDesc(Schema.string().default(sample))
+  return withDesc(Schema.any())
+}
+
+function toSchema (value: unknown, fieldPath: string, meta: MetaMap, depth = 0): Schema {
+  if (depth > MAX_DEPTH) return Schema.any()
+
+  if (Array.isArray(value)) {
+    const sample = value.find((item) => item !== null && item !== undefined)
+    const inner = sample === undefined ? Schema.any() : leafSchema(sample, fieldPath + '[]', meta, value)
+    const text = describe(meta, fieldPath)
+    const schema = Schema.array(inner).default(value as never)
+    return text ? schema.description(text) : schema
+  }
+
+  if (value && typeof value === 'object') {
+    const dict: Record<string, Schema> = {}
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      dict[key] = toSchema(item, fieldPath + '.' + key, meta, depth + 1)
+    }
+    const text = describe(meta, fieldPath)
+    const schema = Schema.object(dict)
+    return text ? schema.description(text) : schema
+  }
+
+  return leafSchema(value, fieldPath, meta)
+}
+
+/** 读取插件的默认配置，生成对应的 Koishi Schema（读不到时给个空对象，不影响启动） */
+export function buildUpstreamSchema (pluginRoot: string): Schema {
+  try {
+    const file = path.join(pluginRoot, 'config', 'default_config', 'config.json')
+    const defaults = JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>
+    const meta = parseConfigMeta(pluginRoot)
+    const dict: Record<string, Schema> = {}
+    for (const [key, value] of Object.entries(defaults)) {
+      dict[key] = toSchema(value, key, meta)
+    }
+    return Schema.object(dict)
+  } catch {
+    return Schema.object({})
+  }
+}
+
+export default buildUpstreamSchema