配置

配置

Lingchu Bot 将轻量级运行时设置存储在插件专属的 JSON5 配置文件中，同时复用 NoneBot2 的全局配置解析器。

首次启动时，插件会创建 config.json5。其路径由 nonebot-plugin-localstore 提供，属于插件配置目录，而非数据或缓存目录。

运行时设置

config.json5 示例：

{
  superuser_key: "123456789abcdef",
  message_store_enabled: true,
  message_store_retention_days: 30,
  message_store_summary_limit: 500,
  message_store_record_api_calls: true,
  message_store_cleanup_enabled: true,
  recall_message_default_count: 10,
  permission_platform_runtime_passthrough: true,
  command_trigger_overrides: {
    member_mute: {
      chinese: "禁言",
      chinese_aliases: ["禁言用户", "禁"],
      english: "mute",
      english_aliases: ["ban"],
    },
  },
  menu_page_trigger_overrides: {
    "member-management": {
      chinese: "成员管理",
      english: "member-management",
    },
  },
  protected_subject_feature_keys: ["kick_member", "member_mute", "recall_message", "block_member"],
  lingchu_adapter: "~onebot.v11",
  lingchu_superusers: null,
}

NoneBot 全局配置仍可覆盖 JSON5：

LINGCHUAdapter = "~onebot.v11"

或在 .env 文件中：

LINGCHUAdapter=~onebot.v11

如果同一键同时出现在操作系统环境变量、dotenv 和 config.json5 中，操作系统环境变量优先。

menu.json5

Lingchu Bot 也会在插件配置目录创建 menu.json5。这个文件只控制菜单展示。

可编辑字段：

• 页面 title
• 功能 summary 和 usage
• 页面、子页面和条目的顺序

代码拥有的字段不能通过 JSON5 编辑。command_key 集合、菜单页 command、platform_capability 和实现级 availability 保留在代码中，避免菜单宣称不存在的命令或适配器能力。如需修改菜单页触发词，请使用 config.json5 中的 menu_page_trigger_overrides。如果 menu.json5 引用了未知 command_key，Lingchu 会拒绝该文件并保留代码默认菜单。未知页面 id 会记录警告并跳过。

权限和触发词自定义

permission_platform_runtime_passthrough 控制 QQ 群主、管理员、成员等平台侧运行时角色是否可以通过运行时身份组满足 Lingchu 授权。设为 false 会要求显式 Lingchu 成员关系，也可以使用 { qq: false } 这样的对象做平台级控制。

command_trigger_overrides 和 menu_page_trigger_overrides 会在 matcher 注册前加载。因此主触发词变更需要重启生效。覆盖加载器会拒绝跨命令重复的触发词。

白名单保护通过 subject policy API 和 protected_subject_feature_keys 配置。当受保护用户是列表中副作用命令的目标时，Lingchu 会拦截该命令；受保护用户本人仍可执行其有权限执行的命令。

核心路径设置

core_version、data_dir、config_dir、cache_dir 和系统平台辅助信息仍由核心 Config 提供。路径来自 nonebot-plugin-localstore：

群公告图片路径桥接

关于 NapCat Docker 公告图片路径桥接，参见 NapCat Docker。

国际化设置

运行时翻译按以下顺序读取 NoneBot 配置键：

1. lingchu_locale
2. lc_locale
3. locale

推荐的 .env 项目专用键：

LINGCHU_LOCALE=zh_CN

当前可用目录包括 zh_CN 和 en_US。locale 名称在使用前会进行规范化，因此 en-US 和 en_US.UTF-8 都会变为 en_US。当设置缺失、为空或 NoneBot 尚未初始化时，默认 locale 为 zh_CN。

容器环境标志

in_containers 来自 NoneBot 全局配置。必须为布尔值。

IN_CONTAINERS=true

本地运行路径

仓库根目录当前不包含已提交的本地 bot.py。项目级 localstore 路径由 NoneBot 配置控制；参见 .env.example：

LOCALSTORE_USE_CWD=true

这意味着 localstore 相关目录优先使用当前工作目录，便于本地开发和调试。

Handle级配置文件

Lingchu Bot 支持每个 handle 的独立配置文件，实现对单个命令行为的精细控制。每个 handle（命令）都可以有自己的 JSON5 配置文件，覆盖代码默认值。

文件命名与位置

Handle 配置文件遵循 <command_key>.json5 的命名规范，存储在由 nonebot-plugin-localstore 管理的插件配置目录中。例如：

• recall_message.json5 — 消息撤回命令的配置
• member_mute.json5 — 成员禁言命令的配置
• kick_member.json5 — 成员踢出命令的配置

标准字段

所有 handle 配置文件共享由 handle_config.schema.json5 验证的通用结构：

defaults 对象可以包含 handle 专用字段。例如，recall_message.json5 可能定义 default_count 字段，设置用户省略数量参数时的默认撤回条数。

配置管理器

HandleConfigManager 类提供对 handle 配置的集中访问：

• get_config(command_key) — 读取特定 handle 的配置
• update_config(command_key, updates) — 用部分变更更新配置
• get_all_configs() — 获取所有已注册 handle 的配置
• ensure_config_files() — 用默认值创建缺失的配置文件

管理器会自动：

• 缓存已加载的配置以提升性能
• 文件缺失或无效时回退到已注册的默认值
• 持久化更新前根据 JSON Schema 验证配置

模块独立原则

每个 handle 模块必须在 handle_config_defaults/ 中使用 register_handle_defaults() 注册其默认配置。这确保了：

1. Handle 有规范的默认配置
2. HandleConfigManager 能验证 command_key
3. 缺失的配置文件能回退到已知默认值

配置文件示例

{
  "$schema": "handle_config.schema.json5",
  enabled: true,
  defaults: {
    default_count: 10,
  },
  policies: {},
}

此示例展示了 recall_message.json5 文件的标准结构。defaults.default_count 字段覆盖了撤回命令的代码定义默认值。

相关页面

• 环境变量 — .env 变量参考
• 适配器选择 — LINGCHUAdapter 配置
• 超级用户身份 — LINGCHU_SUPERUSERS 设置