版本：v1.0
日期：2026-11-01
状态：建议基线
EasyBot 是连接 Minecraft 服务器与 QQ 等社交平台的机器人管理工具。新版本以 Go 提供单体后端服务，以 Vue 3 管理界面完成配置和运维，支持 SQLite、MySQL、PostgreSQL。目标是在保留原产品核心使用场景的同时，形成可扩展的平台适配、服务器桥接、命令与插件能力。
规划依据是 EasyBot 介绍文档：文档将消息同步、绑定、自定义命令、AI、图片模板、占位符、插件和高级管理列为核心能力，平台支持覆盖 Bukkit/Mod/MCDR/Velocity 等形态。本文将这些能力映射为重建阶段，不假设当前脚手架已经实现它们。
- Minecraft 服务器服主及管理团队：配置消息互通、玩家绑定、命令、白黑名单和服务器状态。
- 同时管理多个服务器或社交群的运维者：在一个控制台查看连接、在线状态、日志和告警。
- 扩展开发者：通过有版本约束和权限边界的扩展接口补充命令、事件处理和集成。
- EasyBot 主程序负责配置、适配器生命周期、消息路由、数据持久化、管理 API 和 Web 控制台。
- Minecraft 插件/模组/外部桥接端负责在游戏侧采集事件、执行命令、读取玩家状态和占位符，并与主程序通信。
- 社交平台适配器负责平台协议、鉴权、收发消息和平台事件规范化。
- AI、图片模板、脚本扩展依赖明确的接口和资源限制，作为消息链路稳定后的增量能力。
- 不以微服务作为首版目标；单机部署和可观测运维优先。
首个可用版本应满足以下验收条件：
- 用户可完成首次启动、管理员安全配置、数据库初始化和备份恢复。
- 至少一个社交平台适配器与一个 Minecraft 桥接端可以持续连接、重连并报告健康状态。
- Minecraft 与社交群之间可配置双向或单向消息同步，消息来源标记清晰且不会无限循环。
- 玩家可通过一次性验证码完成账号绑定；管理员可查询、解除和审计绑定关系。
- 管理员可以使用白名单/黑名单、命令权限和基础自定义命令进行常规管理。
- Web 控制台能管理服务器、适配器、群、绑定、命令和设置，并实时查看运行日志及错误。
- SQLite、MySQL、PostgreSQL 使用同一迁移和存储契约通过集成测试。
- 核心路径有自动化测试、部署文档、升级与回滚说明；关键操作有权限检查和审计记录。
- 明确配置格式、环境变量覆盖规则、数据目录、日志格式和版本策略。
- 建立 Go 模块边界：配置、存储、HTTP API、运行时、适配器、Minecraft 网关、消息路由、日志与安全。
- 建立数据库迁移机制、健康检查、优雅关闭、结构化日志、API 错误格式和分页规范。
- 完成原版式 Token 登录、凭据安全存储、会话/令牌策略、CSRF/CORS/来源约束及敏感配置脱敏。
- 交付：可启动的单体服务、Vue 管理壳、安装文档、SQLite 默认配置和三种数据库的 CI 测试。
- 适配器注册表、创建/编辑/启动/停止/重连、状态和能力描述。
- 首批社交平台适配器按原产品用户需求排序；先定义统一事件与消息接口，再逐个平台落地。当前脚手架登记了 OneBot 11、Milky、Telegram、OpenQQ 类型，但尚无协议运行时。
- Minecraft 桥接协议和首个服务端插件/模组：连接认证、心跳、服务器标识、聊天事件、命令下发、断线重连。
- 消息路由规则：服务器、群、方向、过滤、格式模板、来源标记、去重与循环抑制。
- 控制台页面：总览、服务器、适配器、群与同步规则、运行日志、基础设置。
- 交付验收：从群发言到游戏聊天、从游戏聊天到群消息均可端到端测试；异常断线后能自动恢复，重复消息不形成回环。
- QQ/社交账号与 Minecraft UUID 的绑定、跨平台绑定、验证码过期与重试限制。
- 命令注册、参数校验、别名、权限身份、执行审计和平台侧命令反馈。
- 白名单/黑名单及其管理命令；平台用户、群、游戏玩家和管理员权限模型。
- 玩家与服务器状态查询、在线列表和基础 PlaceholderAPI 变量。
- 交付验收：绑定关系唯一性规则明确，越权命令被拒绝且留痕；解绑和封禁状态对所有入口一致生效。
- 自定义命令和可复用变量/占位符管线，含转义、默认值、超时和错误处理。
- 图片模板渲染与预览，模板资源管理、字体/图片校验和渲染资源上限。
- JS 插件/扩展系统：插件清单、API 版本、事件订阅、权限声明、生命周期、依赖和故障隔离。
- 导入/导出配置、模板复用、命令帮助生成和操作审计查询。
- 交付验收：插件可单独启停和定位异常；模板与扩展输入有大小、时间及文件访问限制。
- 可配置 AI 提供方、模型、密钥、上下文长度、超时、并发和费用/频率限制。
- AI 触发规则、群/用户白名单、会话清理、内容拒答和错误降级。
- 完善跨平台绑定、更多社交适配器和 Bukkit/Mod/MCDR/Velocity 桥接形态。
- 物品、背包、末影箱和潜影盒预览等较高复杂度能力按兼容性与资源预算单独立项。
- 交付验收：AI 不阻塞消息主链路；达到限额、超时或上游异常时快速失败并给出可理解反馈。
- 指标、健康探针、运行告警、诊断包、配置校验和数据维护工具。
- 扩展/模板分发和版本兼容流程；签名或可信来源策略在开放生态前确定。
- 大数据量压测、升级迁移演练、崩溃恢复和多系统部署文档。
- 根据真实用户反馈评估多实例部署；若进入该阶段，需先定义适配器单实例所有权和消息投递语义。
- 使用 Go 标准库
net/http作为 HTTP 基础；路由、配置、校验等第三方库保持精简，选择需在实现阶段结合维护状态和许可证评估。 - 以模块化单体组织代码，按领域拆分接口和实现，不按微服务拆分部署单元。
- 运行时组件使用显式生命周期：创建、启动、健康检查、停止；适配器不得绕过运行时直接写业务数据。
- 消息入口经规范化事件模型进入路由器；出站动作带 trace/message ID、来源信息、幂等键和超时。
- API 使用
/api/v1版本前缀；统一分页、过滤、错误码、认证和 OpenAPI 文档。 - 管理实时状态优先使用 SSE；只有需要双向低延迟交互的场景再采用 WebSocket。
- Vue 3 Composition API、TypeScript 严格模式、Vite 构建、Tailwind CSS v4。
- 按业务域组织页面和 API client；定义可复用表格、表单、确认、空状态和错误展示模式。
- 通过 OpenAPI 类型或明确的共享契约保持前后端 DTO 一致；密钥字段只提供写入/轮换，不回显明文。
- 首期页面优先服务运维任务：总览、连接管理、同步规则、玩家/绑定、命令、日志、系统设置。
- 列表需支持搜索、分页、加载/错误/空状态；高风险操作须二次确认并显示操作结果。
- 三种数据库使用同一领域存储接口和版本化 SQL 迁移；不在业务层分支拼 SQL。
- SQLite 为默认单机部署选项；明确 WAL、忙等待、备份一致性和单实例写入约束。
- MySQL/PostgreSQL 面向已有数据库运维或更高并发部署；连接池、TLS、超时及凭据通过配置注入。
- 表结构采用显式主键、时间戳、必要唯一约束和外键策略；索引由查询需求驱动。
- JSON 配置按可迁移、可检索字段决定存储方式；核心关系（服务器、适配器、账号、绑定、规则、命令）采用明确数据模型，避免长期堆入通用
records表。 - 数据迁移必须支持启动前检查、版本记录、失败中止和备份恢复；禁止自动破坏性降级。
User/Role/Session：控制台管理员及权限。Adapter/AdapterCredential：平台类型、配置、运行状态；凭据加密或仅通过安全配置引用。Server/BridgeConnection：Minecraft 实例、平台类型、协议版本与连接状态。SocialGroup/SyncRoute：平台群与服务器之间的消息方向、过滤、格式和启停规则。Player/SocialAccount/BindingChallenge：UUID、平台账号、绑定状态与一次性挑战。Command/PermissionRule：命令定义、参数和允许的角色/来源。AccessEntry：白名单、黑名单及原因、操作者和有效期。Plugin/Template/AIProvider：阶段性扩展配置及版本信息。AuditEvent/RuntimeLog：管理操作审计与运行诊断，生命周期和保留策略分开。
Vue 管理台 --HTTP/SSE--> Go API 与认证
|
配置/领域服务/审计
|
平台适配器 --> 规范化事件 --> 消息路由 --> 平台适配器
|
Minecraft 网关
|
服务端插件/模组桥接
|
SQLite / MySQL / PostgreSQL
消息处理主链路应与 AI、图片渲染和第三方慢请求解耦。对每个外部入口实施超时、并发上限、重试退避和消息大小限制；只对可安全重试的操作重试。运行时状态与持久化配置分离，进程重启后按启用配置恢复适配器。
- 首次安装不暴露未认证管理面；默认仅绑定回环地址，公网访问必须显式配置监听地址和认证。
- 密钥不写普通日志、不在 API 响应中回显；备份和导出需说明敏感字段处理方式。
- 所有管理 API 执行认证、权限校验、输入限制和审计；速率限制覆盖登录、绑定码和高成本功能。
- 插件脚本按不可信代码处理：默认关闭或受限运行，不允许隐式任意文件/进程/网络访问；能力白名单和隔离方案未确认前不纳入首期。
- 运行日志有大小/时间保留策略；诊断信息隐藏令牌、密码、机器人密钥和个人敏感数据。
- 备份恢复覆盖数据库、配置和模板文件，并提供版本兼容及校验步骤。
- 日志、指标和健康状态能区分配置错误、认证失败、外部平台不可达、桥接端离线和数据库异常。
- Go 单元测试覆盖路由规则、绑定状态、权限判定、迁移和消息循环抑制。
- 适配器使用协议模拟器或录制样例测试鉴权、收发、限流、重连及错误映射。
- 数据库集成测试在 SQLite、MySQL、PostgreSQL 上运行同一套存储契约测试。
- API 合约测试覆盖认证、权限、分页、输入错误和并发更新；前端构建与类型检查纳入 CI。
- 端到端测试覆盖首次配置、建立连接、双向同步、绑定、断线恢复、日志检索和备份恢复。
- 发布物提供版本、支持平台、迁移说明、校验和及回滚步骤；发布验证区分本地构建、CI 与实际下载产物。
| 风险/决策 | 影响 | 建议处理 |
|---|---|---|
| 原有插件和协议行为未完全掌握 | 兼容性返工 | 按实际使用场景维护兼容清单和样例服务器，先固定桥接协议契约 |
| 各社交平台 API 与政策差异 | 接入成本、限流与封禁风险 | 每种适配器独立评估认证、限流、消息能力和维护成本 |
| SQLite 并发与备份限制 | 单机规模边界 | 明确 SQLite 部署假设，并为外部数据库提供同一迁移测试 |
| JS 插件安全隔离 | 任意代码执行风险 | 不在 MVP 开放；先完成能力模型、超时和沙箱方案评估 |
| 图片/物品渲染资源消耗 | CPU、内存和磁盘压力 | 限制并发、尺寸、缓存和输入资源，作为独立阶段交付 |
| AI 费用与数据外发 | 费用及隐私风险 | 默认关闭、明确数据提示、设置频率/费用上限与群级策略 |
| 通用记录表扩展 | 查询、约束和迁移困难 | 脚手架仅用于早期原型，领域模型稳定后拆分正式表和迁移 |
截至 2026-11-07，dev/ 已有 Go HTTP 主机、SQLite/MySQL/PostgreSQL 驱动、版本化迁移、基础 CRUD、OneBot 11 正向 WebSocket 适配器、有界内存与持久化运行日志、仪表盘汇总接口，以及 Vue 3/TypeScript/Tailwind v4 管理台。当前迁移版本为 v4。回环监听且访问来源、Host/Origin 均为本机时免登录；非回环监听统一使用 Token 登录，无需用户名或独立 API Key，支持 HTTP 和可选 HTTPS。token.txt 沿用原版 SHA-256 原始 32 字节格式，缺失时首次生成 12 位 Token 并在控制台显示一次。会话只保存 SHA-256 摘要，浏览器使用 HttpOnly、SameSite=Strict Cookie，7 天过期；更换 Token 后重启会清除旧会话，登录按远端 IP 限流。前端提供 Token 登录、退出和受保护控制台入口，服务支持优雅退出。
这些交付只完成了管理底座的一部分，不代表规划功能已完成：目前使用单 Token 认证，没有角色/多用户、CSRF Token、权限矩阵和持久审计；适配器/服务器/群组/玩家/命令等业务数据仍使用通用 records 表；MySQL/PostgreSQL 尚未完成本机集成迁移验证；OneBot 11 已有模拟器验证，真实账号尚未验证，其他平台适配器和 Minecraft Bridge 运行时未实现；跨平台消息路由投递、玩家绑定、命令执行、持久化统计、备份恢复和扩展能力均未形成端到端功能。概览不能把配置存在推断成连接在线或消息成功。
建议按以下次序继续实施：
- 补充单 Token 认证的 CSRF 策略和操作审计；将通用
records逐步拆为正式领域模型，并验证 SQLite/MySQL/PostgreSQL 同一迁移契约。 - 冻结平台事件、消息、路由规则和 Minecraft 桥接协议的数据契约。
- 选定一个目标社交适配器和一种服务器桥接端，完成最小端到端消息闭环，并以真实健康状态驱动概览。
- 将账号绑定、访问控制和命令纳入该闭环，再开展 AI、图片模板和脚本扩展。
具体人力与日历工期需基于团队人数、目标社交平台优先级、兼容版本范围和桥接端开发边界另行估算；本规划不伪造这些未确认参数。
- 程序读取配置文件，叠加环境变量，校验监听地址、数据库 DSN、数据目录和密钥引用。
- 建立数据库连接，读取迁移版本；执行向前迁移。迁移失败时停止启动并输出可诊断错误，不启动半初始化服务。
- 回环监听时允许本机直接进入管理台；非回环监听时读取原版格式的
token.txt，缺失则自动生成 12 位 Token，明文仅在首次启动控制台显示。 - 非本地模式在网页输入 Token 登录，获得 7 天会话；忘记 Token 时停止程序并删除
token.txt，重启生成新 Token 并清除旧会话。 - 进入控制台后按引导顺序配置社交适配器、服务器桥接端和同步规则。
验收点：非本地模式不能绕过 Token 访问管理 API；重启沿用 Token，替换 Token 后旧会话失效；除首次控制台提示外，不在运行日志或 API JSON 响应中暴露凭据。
- 适配器或 Minecraft 桥接端接收原始事件，校验连接身份、载荷大小和协议版本。
- 转换为内部
MessageEvent，分配唯一事件 ID，记录平台、群/服务器、发送者、内容、时间、来源链和附件元数据。 - 路由器按启用规则筛选目标，检查方向、群/服务器范围、发言者权限、关键词过滤和来源链。
- 格式化器解析受限变量（如玩家名、服务器名、时间），拒绝未知或递归变量；内容经过目标平台长度和格式限制。
- 出站队列按目标平台限流发送。可重试错误采用有上限的指数退避；永久错误直接记失败，不无限重试。
- 记录投递结果、耗时和错误类别；管理台可查看事件关联 ID 和失败原因，避免记录不必要的消息隐私内容。
循环抑制至少组合使用来源标记、内部事件 ID 去重缓存、平台回显过滤以及可配置的机器人自身消息过滤。去重窗口和最大跳数均须可配置并有合理默认值。
- 用户在任一已连接入口请求绑定，系统生成密码学安全的一次性随机码，关联发起的平台账号并设置短时有效期。
- 用户在游戏内执行绑定命令；桥接端提交玩家 UUID 和挑战码，后端校验有效期、尝试次数、来源和唯一性约束。
- 成功后，在同一数据库事务中消费挑战并建立绑定关系，生成审计事件并通知两端。
- 重复绑定、码过期、输错过多、已有账号占用等情况返回不同但不泄漏他人身份信息的错误。
- 解绑需校验本人或管理员权限；管理员操作必须填写原因并可在审计页追溯。
数据约束：挑战码只存哈希；挑战码单次使用；同一平台账号和同一 UUID 的绑定唯一；跨平台绑定通过一个玩家主体关联多条外部身份，不在单字段拼接多个账号。
- 入口解析命令和参数，不通过字符串拼接执行任意 shell 命令。
- 命令注册表校验命令存在、参数类型、来源范围和速率限制。
- 授权模块根据发起者身份、平台群、游戏权限和命令策略作出允许/拒绝决定。
- 命令处理器调用领域服务；如需在游戏端执行，使用桥接端的结构化命令请求，并设置截止时间和请求 ID。
- 统一格式化结果并发回原入口；超时显示明确状态，不将内部堆栈或密钥泄漏给用户。
- 记录操作者、命令标识、目标、判定结果、耗时和原因。敏感参数按命令声明脱敏。
下表为逻辑模型草案，最终列类型应由迁移实现针对三种数据库统一映射。ID 建议使用 UUID 字符串或 16 字节形式；时间统一存 UTC。关系型核心实体不使用通用 JSON 记录代替。
| 表 | 关键字段与约束 | 用途 |
|---|---|---|
schema_migrations |
version 主键、applied_at |
迁移版本记录 |
users |
id、username 唯一、password_hash、status、时间戳 |
控制台用户 |
roles / user_roles |
角色键唯一；用户和角色复合唯一 | 管理权限分配 |
sessions |
token_hash 唯一、user_id、过期时间、撤销时间 |
管理台会话，不存明文令牌 |
adapters |
id、type、name、enabled、config_json、配置版本 |
社交平台连接配置 |
servers |
id、name、platform_type、enabled、config_json |
Minecraft 服务实例 |
bridge_connections |
server_id、protocol_version、status、last_seen_at |
瞬时连接信息；重启后重建 |
social_groups |
adapter_id、external_group_id、显示名；二者复合唯一 |
社交群/频道 |
sync_routes |
源、目标、方向、过滤 JSON、格式模板、启用状态 | 消息路由配置 |
players |
uuid 唯一、最近游戏名、首次/最近出现时间 |
Minecraft 玩家主体 |
social_accounts |
adapter_id、外部账号 ID、显示名；复合唯一 |
社交平台身份 |
player_social_accounts |
玩家与社交账号复合唯一、绑定时间、操作者 | 跨平台绑定关系 |
binding_challenges |
挑战哈希唯一、目标身份、到期时间、尝试次数、消费时间 | 一次性绑定流程 |
commands |
命令键唯一、定义 JSON、启用状态、版本 | 内置和自定义命令元数据 |
access_entries |
主体类型/ID、名单类型、原因、有效期、操作者 | 白名单/黑名单 |
audit_events |
操作者、动作、目标、结果、请求 ID、时间 | 管理操作追踪 |
message_deliveries |
事件 ID、目标 ID、状态、尝试次数、错误类别、时间 | 可选的持久投递/排障记录 |
plugins / templates / ai_providers |
各自独立领域字段和版本 | 后续阶段能力配置 |
实现约束：
- 所有外部 ID 需保留原始字符串，避免不同平台的数字/字母 ID 被误转成整数。
config_json仅用于适配器特有、带版本的配置；可查询和约束的核心字段应独立列出。- 软删除只用于有恢复价值的实体；连接、挑战和消息诊断数据按保留策略清理。
- 唯一性和外键错误映射为稳定 API 错误码，不能依赖数据库原始错误文本。
- PostgreSQL JSONB、MySQL JSON、SQLite TEXT 的差异应封装在迁移和仓储层；通用查询不依赖特定数据库 JSON 操作。
所有管理端点使用 /api/v1 前缀。JSON 时间使用 RFC 3339 UTC。列表端点统一返回 {items, nextCursor} 或采用一致的页码分页，首版选定一种后不得按模块混用。写请求应校验内容类型和最大载荷；破坏性操作要求 CSRF 防护、权限检查和审计。
| 资源 | 建议端点 | 说明 |
|---|---|---|
| 健康与版本 | GET /health/live、GET /health/ready、GET /api/v1/app/info |
存活与依赖就绪分开 |
| 初始化/会话 | GET /api/v1/setup/status、POST /api/v1/setup/admin、POST /api/v1/auth/login、POST /api/v1/auth/logout |
初始化仅限本机且单次；登录有限流 |
| 总览 | GET /api/v1/dashboard |
数量、连接健康、近期错误摘要 |
| 适配器 | GET/POST /api/v1/adapters、GET/PATCH/DELETE /api/v1/adapters/{id}、`POST .../{id}/start |
stop |
| 服务器 | GET/POST /api/v1/servers、GET/PATCH/DELETE /api/v1/servers/{id} |
游戏实例和桥接状态分离 |
| 群与路由 | /api/v1/groups、/api/v1/routes |
群发现和同步规则管理 |
| 绑定 | GET /api/v1/bindings、POST /api/v1/bindings/{id}/revoke |
查询和管理员解绑 |
| 访问控制 | /api/v1/access-entries |
筛选名单、到期和原因 |
| 命令 | /api/v1/commands、POST /api/v1/commands/{id}/test |
测试运行需标记为非生产或安全沙箱 |
| 日志与事件 | GET /api/v1/logs、GET /api/v1/audit-events、GET /api/v1/events/stream |
SSE 事件流须支持断线重连和权限过滤 |
| 系统 | /api/v1/settings、POST /api/v1/backup、POST /api/v1/restore/validate |
恢复执行应有额外确认和维护模式 |
错误响应建议统一为 {code, message, requestId, details?}。message 面向用户，code 稳定供前端处理，details 不包含内部密钥或堆栈。创建返回 201；删除成功返回 204；冲突返回 409；无效输入返回 400 或 422，全项目统一选择。
| 导航区 | 页面 | 主要任务 |
|---|---|---|
| 概览 | 仪表盘 | 快速识别离线适配器、离线服务器、最近错误和消息量 |
| 接入 | 平台适配器、Minecraft 服务器 | 新建配置、连接测试、启停、查看能力和诊断 |
| 消息 | 群组、同步规则 | 选择源与目标、设置方向/格式/过滤、发送测试消息 |
| 玩家 | 玩家、账号绑定、白黑名单 | 搜索玩家、核对绑定、封禁/解封和查看操作来源 |
| 自动化 | 命令、占位符、插件 | 管理命令和扩展能力；按阶段显示未启用功能状态 |
| 内容 | 图片模板、AI 提供方 | 配置、预览、限额；未实现前不展示假可用控件 |
| 运维 | 实时日志、审计、备份、系统设置 | 排错、追溯高风险操作和数据维护 |
通用交互：保存前做字段级校验；连接测试需显示进行中、成功和失败原因；长任务显示任务状态而非假定同步完成；删除/解绑/恢复需展示明确对象及影响范围；敏感凭据保存后只显示已配置状态和轮换入口。页面支持窄屏基础操作，但复杂配置优先为桌面运维场景设计。
配置优先级建议为：内置默认值 < 配置文件 < 环境变量 < 明确的命令行参数。启动时输出最终配置摘要，但对密码、Token、DSN 凭据和密钥统一脱敏。
server:
listen: 127.0.0.1:5001
public_url: ""
database:
driver: sqlite
dsn: appdata/easybot.db
security:
session_secret_file: appdata/secrets/session.key
trusted_proxies: []
logging:
level: info
retention_days: 14
runtime:
adapter_shutdown_timeout: 10s
event_queue_size: 1000上例是配置形状建议，字段名称需在实现时与环境变量映射一起冻结。SQLite 部署需将数据库、密钥和模板目录放在持久卷并纳入备份；容器关闭时给予适配器和 HTTP 服务有限的优雅退出时间。外部数据库 DSN 生产环境必须启用 TLS（本机开发除外），并建议使用最小权限账号。
交付包应包含可执行程序、内嵌或同版本静态前端、默认配置模板、迁移说明、许可证与第三方组件清单。升级先做兼容性备份，再执行迁移；若迁移失败，恢复步骤必须清晰，不能通过旧程序直接写入新版本数据库。
日历估算尚缺开发人数、每周投入、平台优先级和服务端桥接形式，故这里以交付批次拆分，不承诺虚假日期。每批按可演示结果验收，功能完成不等于代码合并。
| 批次 | 主要交付 | 进入下一批的条件 |
|---|---|---|
| A. 契约定稿 | 事件模型、桥接协议、数据库迁移方案、认证模型、部署配置 | 所有外部边界有版本、错误和身份校验约定 |
| B. 管理底座 | 初始化、登录、领域表、日志/审计、Vue 导航和基础 CRUD | 三种数据库迁移通过，未认证请求无法访问管理 API |
| C. 首个连接器 | 一个真实社交适配器、适配器生命周期、连接状态 | 模拟测试与真实测试账号收发稳定，重连和限流可观察 |
| D. 游戏桥接 | 一个目标平台桥接端、认证、心跳、聊天和命令 | 不匹配密钥和过期协议拒绝连接，断线状态可恢复 |
| E. 同步 MVP | 路由、格式、过滤、去重、双向投递和日志关联 | 端到端测试验证无循环、限流、重试和目标故障降级 |
| F. 身份治理 | 绑定、命令权限、访问名单、审计 | 单次挑战和并发绑定规则通过集成测试 |
| G. 扩展能力 | 模板、AI、脚本或更多适配器按价值单独排期 | 资源隔离、权限声明、关闭路径和故障测试完善 |
每个批次完成定义（DoD）：需求和边界有文档；错误与空状态可见；API 权限和输入校验完成；新增迁移在三数据库验证；关键逻辑有单元/集成测试；前端类型检查和生产构建通过；日志不泄密；升级/回滚及用户文档同步更新；未完成能力不得以成功状态展示。
以下是初始验收目标，正式值需在目标硬件和消息平台限流条件下校准：
- 管理 API（不含外部调用）本机部署 p95 响应时间不高于 300 ms；列表接口有硬分页上限。
- 消息事件进入路由队列后，内部决策 p95 不高于 100 ms；外部平台发送耗时单独统计。
- 单个适配器故障不得阻塞其他适配器、控制台 API 或健康检查。
- 每个外部连接有心跳/超时判断、有限重连退避和可人工立即重启的操作。
- 队列达到上限时执行明确背压策略（拒绝、丢弃低优先级或持久排队），并计数告警；不得无限占用内存。
- 默认日志保留和消息诊断保留分开配置；诊断消息正文默认不持久化或提供显式脱敏配置。
- 关键服务指标至少包括连接状态、队列深度、事件处理数、投递成功/失败数、重试数、耗时分位数和数据库错误数。
- 发布前完成连续运行、断网恢复、数据库重启、磁盘空间不足和迁移失败演练。
这些决策会显著影响首版范围，规划阶段先保留为开放项：
- 首发社交平台和优先级：OneBot 11、Milky、Telegram、OpenQQ 中先交付哪一个，是否有官方 API/账号限制。
- 首发 Minecraft 桥接方式：Bukkit/Paper 插件、Velocity 插件、Mod 模组、MCDR 插件，或协议兼容的外部连接器。
- 部署目标：Windows/Linux 单机、Docker，还是需要同时维护服务端 GUI 安装包。
- 管理台用户模型：仅单管理员，还是首版就需要多用户、角色和远程访问。
- 消息留存策略：是否保存正文、保存多久、是否需要管理员检索历史消息。
- 插件系统兼容：继续支持 JS/ClearScript 行为，还是设计新的受限扩展 API。
- 对旧版本的迁移范围：需要导入哪些配置、绑定和模板；是否要求自动迁移旧数据库。
在这些项确定前，首期实现应保持接口可扩展但避免提前实现多平台、多角色或任意脚本执行造成的额外复杂度。
管理台采用桌面优先的运维控制台布局，视觉重点放在状态、列表和操作反馈，不采用营销型首页结构。
- 左侧主导航：概览、接入、消息、玩家、自动化、内容、运维。窄屏时折叠为图标导航或抽屉，当前栏目保持明确选中态。
- 顶部栏：当前页面标题/面包屑、全局连接健康摘要、主题切换、当前管理员菜单。全局健康摘要可展开查看各适配器和服务器状态。
- 内容区：页面标题、主要动作、过滤工具、数据表或详情内容。标题区域不堆叠说明文案；帮助信息放入文档链接或字段级提示。
- 通知区：短暂成功提示用于确认操作结果；持久错误显示在相关表单或连接详情旁，提供可执行的重试/诊断动作。
- 状态约定：连接状态统一使用“运行中、连接中、已停止、异常、未配置”等词，并配合图标/颜色和最后更新时间，不能仅依赖颜色区分。
桌面基准建议为 1440×900，兼容 1280px 宽度；窄屏重点保证列表查看、搜索、详情和常用启停操作可用。复杂编辑表单可在窄屏使用全屏抽屉或独立页面。
目的：管理员登录后快速判断消息链路是否可用，以及下一步应该处理什么。
布局与内容：
- 页面标题“概览”，右侧提供刷新按钮和最近数据更新时间。
- 第一行显示运行概况：在线服务器数、运行中适配器数、启用同步规则数、近 24 小时投递失败数。每项是紧凑统计，不以大面积装饰卡片占据首屏。
- 主内容分为“连接状态”和“最近异常”两栏。连接状态列出服务器/适配器名称、平台类型、状态、最后心跳和快捷查看入口；异常列表显示时间、模块、错误摘要、关联对象和查看日志入口。
- 下方显示近期消息投递趋势或成功/失败计数；未实现持久消息统计前不显示虚构图表，改为展示可用的连接和错误信息。
- 初次安装时显示明确的配置待办顺序：创建适配器、连接服务器、发现群、创建同步规则。每项点击后直达对应配置界面。
交互与状态：点击离线对象打开详情；刷新显示加载中，失败时保留已有数据并提示刷新失败。空状态区分“尚未配置”和“已配置但暂无事件”。仪表盘数据轮询间隔可配置或使用 SSE 增量刷新，页面离开后停止无用轮询。
列表页：顶部有“添加适配器”主操作；过滤项包括平台类型、运行状态和关键字。表格建议列为名称、平台、状态、最近连接、关联群数、最近错误、操作。行操作提供查看、编辑、启动/停止；删除放入更多菜单并要求确认。
添加/编辑流程：
- 选择平台类型，展示该平台支持的连接方式与所需凭据。
- 填写名称、连接地址、鉴权配置和高级参数；密钥输入框默认遮蔽，已保存密钥显示“已配置”并提供替换/清除操作。
- 点击“测试连接”，在当前表单显示连接中、成功（含机器人身份/能力）或可读错误及建议动作。
- 保存后进入适配器详情，可查看运行状态、能力、群列表、连接事件和脱敏后的配置摘要。
安全交互：启动/停止是可逆操作，完成后更新状态并保留操作结果；删除前显示适配器名称及受影响的群和同步规则数量。若仍有规则引用，默认阻止删除并提供先停用或迁移规则的入口。
列表页展示名称、服务端平台/版本、桥接状态、在线玩家数（若桥接协议提供）、最后心跳、绑定适配器/路由数和操作。支持按平台和连接状态筛选。
新增服务器表单包含显示名称、桥接类型、服务器标识、连接地址/连接方向、认证密钥、协议版本策略和可选标签。选择桥接类型后只展示对应字段；认证密钥只在创建/轮换时输入。提供“生成连接密钥”快捷操作，但不会自动把密钥写入远端服务器。
详情页采用页签组织：
- 状态：连接状态、最近心跳、桥接版本、在线人数和最近事件。
- 消息路由：引用该服务器的同步规则及其启停状态。
- 玩家：在线玩家和最近活动玩家，可跳转到玩家详情。
- 命令/变量：展示桥接端声明支持的命令和变量能力；无能力时解释需安装/升级桥接端。
- 诊断：协议协商、认证、心跳和重连事件，密钥及玩家敏感数据脱敏。
群组页以适配器为筛选维度，显示外部群 ID、群名、机器人是否可发言、最近事件和已关联服务器。群列表由适配器发现或按平台能力手工录入；刷新群列表时显示发现时间与新增数量。
同步规则列表显示规则名称、来源、目标、方向、过滤摘要、启用状态和最近投递结果。主要操作为新建规则、启停、编辑和复制。列表应醒目区分单向与双向规则，便于检查重复路由。
规则编辑界面按步骤组织：
- 选择来源类型和来源实例（社交群或 Minecraft 服务器）。
- 选择目标类型和目标实例；双向同步通过“方向”分段选项表达，不要求用户重复创建两条规则。
- 设置消息模板，提供可插入变量清单和实时预览；预览使用样例数据，不向真实群发送。
- 设置过滤条件：忽略机器人、忽略命令、关键词/正则（若支持需限制执行成本）、允许/拒绝身份。
- 使用测试消息验证渲染长度和目标能力，确认后启用。
保存前显示路由摘要，如“群 A ↔ 生存服”，并检测相同源目标的重复规则。检测到可能的循环/冲突时指出具体规则和处理建议；允许保存的情况必须明确解释覆盖或优先级。
玩家列表支持 UUID/游戏名/社交账号搜索，列为游戏名、UUID、绑定平台账号数、最近在线、访问状态和最近绑定时间。账号信息按权限展示，默认不暴露不必要的个人资料。
玩家详情显示当前绑定关系、绑定时间、关联平台、访问名单状态、最近在线信息和审计事件。管理员可解绑或调整访问名单；高风险操作要求输入原因。跨平台身份以独立行展示，不能将多个账号压缩进一个难以辨认的文本字段。
绑定挑战页用于排查待处理挑战，显示发起平台、创建时间、剩余有效期、尝试次数和状态；挑战码只显示给发起用户一次，后台列表仅显示脱敏标识或哈希摘要。页面提供撤销挑战操作，不提供恢复明文挑战码功能。
白名单和黑名单可通过分段标签切换，避免将两种相反动作混在同一张难辨表格中。列表列包括主体、主体类型、原因、创建者、创建时间、到期时间和状态。支持批量导入前预览校验结果，显示新增、重复、无效条目数量；实际导入需二次确认并生成批次审计记录。
添加条目时，主体类型选择玩家 UUID、游戏名或平台身份，并提示哪些标识会随玩家改名变化。到期时间提供永久/指定日期选择。解除条目需要确认对象和原因，并可在审计页追踪。
命令列表显示命令名称、触发前缀、允许来源、授权范围、启用状态和最近执行结果。内置命令与自定义命令应有明确标识。
命令编辑器包括名称/别名、帮助文本、参数定义、允许平台和群、权限身份、频率限制、处理类型与执行超时。初版自定义命令建议只组合受控动作和变量，不提供任意 shell 执行。对会修改服务器状态的动作显示风险级别与确认设置。
命令详情提供最近执行记录：请求者、来源、目标、授权结果、耗时和脱敏后的结果摘要。提供“模拟解析”测试区，输入样例命令后展示参数解析和权限判定，不应误触发真实游戏动作。
实时日志提供级别、模块、适配器/服务器、时间范围和关键词过滤；默认展示最新记录，暂停滚动后允许选中复制。每条记录显示时间、级别、模块、消息、关联 request/event ID。长堆栈折叠，敏感字段脱敏。提供清空过滤、暂停/继续和下载当前筛选结果。
审计日志与运行日志分开呈现，默认只读。筛选项包括操作者、动作、目标类型、结果和时间范围。详情抽屉展示前后字段差异，但凭据字段只显示“已修改”，不保存或展示旧值/新值。
日志断流时保留已加载记录并显示断连状态；重连后从最近游标续传，若有遗漏则提示时间区间并允许重新查询。空状态明确区分“无匹配记录”和“日志服务不可用”。
AI 页面分为“提供方”和“触发策略”两个页签。提供方表格显示名称、厂商/协议、模型、连接测试状态和启用状态，密钥仅支持新增或轮换。测试连接只发出明确标注的测试请求，并说明可能产生的上游费用。
策略编辑项包括触发方式、允许群/用户、上下文轮数、最大回复长度、超时、每用户/每群频率上限、每日额度和数据发送提示。提供对话清理策略和禁用开关。上游超时或额度耗尽时展示降级消息，不阻塞普通消息同步。
模板列表显示名称、用途、版本、更新时间和启用状态；支持新建、复制、导入和导出。模板编辑区采用左侧属性/图层列表、中间预览画布、右侧选中元素属性的工作区结构；窄屏切换为分步编辑。
预览使用固定样例玩家/物品数据，提供刷新和不同尺寸预览。渲染任务显示排队/渲染失败状态及可理解原因。上传字体和图片前校验格式、尺寸和文件大小；不支持的资源不得静默替换。模板发布前可保存草稿和恢复上一个已发布版本。
插件列表显示名称、版本、作者、兼容 API 版本、启用状态、权限摘要和最近错误。详情页展示声明的权限（文件、网络、事件、命令等）、依赖、版本变更和日志。安装来源与校验结果需清晰展示。
启用前呈现权限差异并要求确认；升级失败可恢复先前版本或停用插件。插件崩溃应显示隔离状态和重启动作，不导致主进程或消息路由整体停止。未实现安全隔离能力前，界面应标记插件功能不可用，不能只做看似可操作的空壳。
系统设置按常规设置、网络、安全、数据库、日志与高级选项分组。修改监听地址、认证策略、数据库连接等关键设置时显示需要重启的提示，并明确当前值和保存后生效时间。环境变量覆盖的字段标记为只读或提示需修改部署配置。
备份页显示上次备份时间、备份内容、文件大小和校验状态；允许立即创建备份和下载。备份应包含恢复所需配置和数据库，不应在页面上直接暴露密钥明文。
恢复流程分为上传/选择文件、校验版本与完整性、查看将覆盖的数据摘要、进入维护模式执行恢复、重启并验证。最终确认前展示不可逆影响；失败时保留原数据并给出恢复到执行前快照的操作说明。
- 登录页仅提供账号、密码和登录按钮；显示错误但不区分用户名是否存在。连续失败触发短暂限流反馈。
- 首次配置页依次完成管理员、数据库状态、适配器、服务器和路由初始设置；用户可跳过非必需步骤，稍后从仪表盘待办继续。
- 无权限页说明当前账号缺少的权限标识（不泄漏可访问资源），提供返回概览入口。
- 服务不可用页区分后端未就绪、数据库不可达和会话过期；可重试的场景提供重试操作，不无限自动刷新。
- 版本升级提示只在数据迁移或配置调整需要管理员处理时显示，带备份建议、变更摘要和完成状态。
每个页面进入实现验收前至少满足：
- 明确主要任务和唯一主操作，页面标题与导航位置一致。
- 覆盖加载、空结果、部分数据、错误、无权限和窄屏状态。
- 所有写操作显示成功/失败结果；破坏性操作能确认具体目标。
- 表单错误定位到字段；离开页面时未保存修改会提示。
- 连接和后台任务状态能刷新或订阅更新，离线状态不会伪装成加载中。
- 键盘可操作主要表单、弹窗和表格动作；图标按钮有可访问名称。
- UI 不显示尚未接通后端的成功状态或示例统计；演示数据须明确隔离于生产数据。
- 关键视图在 1440×900、1280×800 和 390×844 视口完成检查，确保表格、对话框、长名称和错误文本不溢出或互相遮挡。
本章从服主和群管理员实际操作出发，定义配置向导、用户入口、系统处理规则和可见结果。文档直接确认的能力按“文档能力”描述；为使新系统可实现、可测试而增加的交互与策略按“本项目建议”描述，最终需要结合原产品行为和首发平台确认。
目标：新安装用户不需要先理解内部架构，按引导完成一条可验证的群服消息链路。
进入条件：管理员首次登录或当前尚无已启用适配器、服务器和同步规则。用户可从向导中退出，进度自动保存为待办。
步骤 A：选择社交平台接入方式
- 显示已实现的平台卡片，包括平台名称、连接模式、需要准备的凭据、当前产品支持的消息能力和文档链接。未实现的平台显示“尚未支持”，不能进入可提交状态。
- 用户选择平台后填写适配器名称、连接模式、连接地址/令牌等该平台实际需要的字段。字段旁解释从哪里获取，密码类输入使用遮罩。
- 用户点击“测试连接”。系统执行 DNS/网络连通、协议握手和鉴权测试；反馈成功身份、可收发能力、缺少权限，或错误类别及排查建议。
- 测试成功后用户点击“保存并连接”。连接是后台任务，按钮进入处理中；成功后出现在线状态和下一步“获取群列表”。
步骤 B：创建 Minecraft 服务器
- 用户选择桥接端类型（如 Paper/Bukkit、Velocity、Mod、MCDR；首版只允许选择实际已实现的类型）。
- 表单展示连接方式、服务器名称、服务器唯一标识、协议版本、共享密钥和可选服务器地址。系统生成随机共享密钥，提供复制按钮及密钥轮换操作。
- 页面提供对应桥接端的安装步骤和配置片段，片段包含连接地址、服务器 ID、密钥占位内容和版本号。密钥仅在创建/轮换流程展示一次，用户需自行复制到游戏服配置。
- 保存后等待桥接心跳。超时后状态仍为“等待连接”，并显示最近握手/认证错误及“重新生成密钥”“复制配置”“查看日志”操作。
步骤 C：选择群和服务器并建立同步规则
- 用户从适配器发现的群列表中勾选一个或多个目标群，从已连接服务器中选择游戏端。
- 选择同步方向：群到服务器、服务器到群、双向。对于多群，界面明确呈现一群多服或多群一服的关系。
- 选择消息格式预设，初始格式可为“[群名] 用户名：消息”和“[服务器名] 玩家名：消息”；允许预览，但预设变量必须来自白名单。
- 点击“发送测试消息”。测试消息显著标记为测试，不触发真实命令或玩家身份处理；用户确认实际目标收到后启用规则。
- 仪表盘显示适配器在线、服务器在线和规则启用三项状态。若任何一项失败，提供跳转到对应配置页的动作。
完成状态：向导不以“保存成功”作为链路验收，只有测试消息成功到达已选目标后才标记消息同步配置完成。允许用户跳过测试，但系统必须标记为“未验证”。
配置入口：消息 > 同步规则 > 新建规则。用户无需编辑 JSON 或配置文件即可完成常见同步；高级 JSON 编辑仅作为管理员调试入口，且须校验 schema。
新建规则表单：
| 区块 | 控件 | 用户输入/选择 | 保存后的作用 |
|---|---|---|---|
| 基本信息 | 文本输入 | 规则名称、备注 | 便于服主识别和审计 |
| 来源 | 类型下拉 + 搜索选择器 | 社交适配器及群，或 Minecraft 服务器 | 确定事件监听范围 |
| 目标 | 多选选择器 | 一个或多个群/服务器 | 确定消息投递位置 |
| 方向 | 三段切换 | 群→服、服→群、双向 | 生成一个或两个方向的路由 |
| 内容 | 格式预设下拉 + 模板输入 | 消息格式及允许变量 | 规范名称、来源和正文显示 |
| 忽略条件 | 开关/多选 | 忽略机器人、命令、空消息、附件类型 | 在转发前过滤不需要的消息 |
| 限制 | 数值输入 | 单用户频率、最大正文长度、目标冷却 | 避免刷屏和不兼容消息 |
| 故障策略 | 选择项 | 暂存有限队列/失败即停止 | 目标离线时确定消息处理方式 |
| 生效 | 开关 | 创建后启用或保持停用 | 控制规则是否参与路由 |
消息模板建议：群到游戏默认 [群名] {sender_name}: {content}；游戏到群默认 [{server_name}] {player_name}: {content}。插入变量通过变量菜单选择，不要求用户记忆变量语法。系统对群名、玩家名和正文中的格式控制字符做转义，避免伪造前缀或注入目标命令。
运行时规则：用户发消息后，系统先判断消息是否由机器人产生、是否命中忽略条件、是否超过长度/频率限制，再查找启用路由。每个投递目标独立记录结果；一个群发送失败不应取消其他目标的成功投递。队列满时按规则显示“拒绝新消息”或“丢弃旧消息”策略，不静默丢失。
用户侧反馈：普通聊天转发不应额外刷系统回执；配置测试、被频率限制或目标不可达时，管理员在控制台看到关联事件 ID、目标、失败类别和重试状态。日志默认显示内容摘要而非完整正文。
编辑与冲突：编辑已启用规则时，保存后立即应用新版本并记录规则版本号。相同来源和目标存在重复方向时，保存前显示冲突规则名称及重叠方向；用户必须选择合并、停用旧规则或确认并行转发。
文档定义两种绑定模式，本项目将它们作为同一“绑定策略”中的互斥模式配置。一个实例首版建议只启用一种主流程，避免用户遇到不一致操作。
管理员配置：玩家 > 绑定设置 > 绑定模式选择“双向验证”；设置验证码有效分钟数、最大尝试次数、每账号/每 IP 的冷却时间、绑定唯一性策略及允许绑定的服务器范围。建议默认验证码有效 5 分钟、最多错误 5 次，最终值应可配置。
玩家操作：
- 玩家在游戏内执行配置好的绑定命令（例如
/easybot bind），服务器返回一次性验证码和过期时间。 - 玩家在指定社交群发送机器人绑定关键词（例如
绑定 123456），机器人识别当前平台账号和群。 - 后端同时校验验证码、未过期、未消费、玩家和社交账号尚未冲突、该群/服务器允许绑定。
- 成功后游戏内和群内分别回执绑定的游戏名/账号；验证码立即作废。若失败则提示对应的可恢复原因，如已过期、次数过多或账号已绑定。
管理员配置：绑定模式选择“社交平台信任”；明确列出可信平台和可信群；配置可绑定服务器、游戏名校验方式（是否要求玩家在线、是否区分大小写）及重名/改名处理策略。由于该模式以社交平台身份作为信任依据，系统需显示风险提示，不应默认对所有群开放。
玩家操作：用户在可信群使用关键词加游戏名（例如 绑定 Steve）。机器人检查来源群、群成员身份和游戏名，再创建绑定关系；如果游戏名可能对应多个 UUID，要求用户在线验证或选择 UUID，不允许猜测绑定。
管理员在绑定设置的“强制绑定”列表中勾选服务器。对选中的服务器，桥接端在玩家进入时查询绑定状态：未绑定玩家按策略拒绝进入或踢出，并显示配置的原因和可操作指引。解绑成功事件应通知桥接端执行强制规则；若桥接端暂时离线，应在重连后重新同步绑定状态。
设置项包括：启用服务器多选、未绑定时动作（拒绝登录/踢出）、提示文本、是否允许管理员豁免、豁免有效期。提示文本支持 {bind_command} 和 {group_name} 等已审核变量。踢出行为需经兼容服务器测试，不得在桥接端离线时假定玩家已被踢出。
- 允许解绑开关决定用户是否可自行解绑；关闭后仅管理员可解除。
- “成员退群时自动解绑”按适配器成员退群事件配置，可对每个群单独启停。执行解绑前记录平台账号和受影响玩家，生成审计事件。
- 群名片策略提供“绑定成功后改为游戏 ID”“用户发言时检查并修正”“关闭”三项。第二项会增加每次发言的查询和平台 API 调用，界面须显示性能与平台限流提示。
- 群名片包含多个游戏 ID 时按平台字符限制截断，明确使用省略标记，不得静默丢失数据库中的绑定关系。
普通用户如何使用：用户在受支持的群内按命令前缀和关键词触发命令，例如 !在线。界面帮助页展示每个命令的别名、参数、权限要求和示例；自定义前缀从命令设置读取。
管理员如何创建命令：自动化 > 命令 > 新建。表单按“触发方式、权限、操作、回复”分步配置。
| 配置项 | 控件形式 | 说明/建议默认值 |
|---|---|---|
| 命令名称 | 文本输入 | 稳定内部键，创建后修改需提示影响 |
| 关键词/别名 | 可增删标签 | 可配置多个触发词；避免与内置关键词冲突 |
| 匹配方式 | 单选 | 精确匹配为默认；正则需管理员权限并做复杂度限制 |
| 允许入口 | 多选 | 指定平台、群和游戏服务器 |
| 权限 | 单选 | 全员、管理、绑定、群主、自定义身份 |
| 作用服务器 | 多选 | 对需要读取服务器数据的命令指定目标；可选择多个并汇总结果 |
| 操作类型 | 单选 | 文本回复、服务器命令、PAPI 查询；后续可扩展受控动作 |
| 操作参数 | 按类型显示表单 | 命令执行填写目标命令和允许参数；PAPI 填写变量与服务器；文本填写模板 |
| 回复形式 | 单选 | 纯文本或图片模式（渲染器可用时） |
| 频率限制 | 数值/时间单位 | 每用户和每群独立配置；默认启用基础限制 |
| 启用状态 | 开关 | 新建默认停用，测试通过后启用 |
权限含义：全员表示规则允许的入口内所有用户；管理表示平台群主/管理员；绑定表示完成账号绑定者；群主仅群主；自定义表示命令身份配置中显式授予的身份。平台不提供可靠角色信息时，管理/群主权限不可默认为真，应禁用并说明平台能力限制。
命令执行安全：命令类型中的“服务器命令”只允许发送到用户选定的 Minecraft 服务器控制端，禁止调用主机 shell。对高风险服务器命令可配置管理员权限、确认口令或只允许控制台执行。模板中的用户参数必须作为独立参数传递和转义，不能直接拼接可执行语句。
图片模式：管理员开启前选择模板、最大宽高和无模板时的退化方式（转纯文本或失败）。如果渲染服务未安装，配置页面显示依赖状态和资源要求，不提供可保存的伪配置。
测试与运行记录：保存前使用模拟用户、模拟群和模拟参数预览命中关键词、权限判定、目标服务器与输出模板。正式执行记录显示发起人、入口、授权结果、目标、执行时间和错误类别；秘密参数脱敏。对于服务器修改命令，测试模式只解析不执行。
配置前置条件：Minecraft 桥接端已连接；目标服务器安装并启用了所需 PlaceholderAPI 扩展（若该服务端模式支持）。
管理员操作：命令或模板的操作类型选择“PAPI 查询”；选择作用服务器；输入或从服务器上报的变量列表中选择变量；设置查询玩家（触发者绑定玩家、指定玩家或不需要玩家）；设置超时和无数据时的提示文案。保存前点击“测试查询”，使用当前在线玩家或显式样例玩家执行只读测试。
执行方式：机器人命令入口解析请求用户，若变量需要玩家则先查绑定；调用指定桥接端查询；超时、玩家离线、扩展未安装分别映射为不同错误。多个作用服务器的结果按服务器名称分段回复，单个服务器失败不影响其余结果。
用户界面：在线玩家页展示数据更新时间和来源服务器；变量页显示变量名、依赖插件、示例值、查询耗时和最近错误。查询结果需缓存时由管理员设置 TTL；默认短缓存，避免每条消息都打到 Minecraft 主线程。
文档确认支持 OpenAI 格式 LLM 接口。本项目建议将“兼容接口”作为首版配置标准，不默认依赖免费公共中转服务。
添加提供方流程：内容 > AI 提供方 > 添加。用户填写显示名称、API Base URL、API Key、模型名、请求超时、最大并发和默认最大输出 Token。系统用密钥遮罩输入；点击测试时向指定模型发最小测试请求，并展示响应时间、模型返回和错误类别。密钥仅保存，不回显。
触发策略：选择明确触发方式（命令触发、@机器人、关键词之一）；选择允许群和用户；设置系统提示词、上下文轮数、最大输入/输出长度、每用户冷却、每群并发、每日调用上限、超时以及是否保留对话。新增群默认关闭 AI，管理员显式启用。
用户使用流程：用户按启用的触发形式发送问题；系统检查群/用户白名单和频率；构造上下文后调用提供方；将回复按平台长度拆分或拒绝超长内容；失败时返回“AI 暂时不可用”类短提示并记录 request ID。普通聊天消息同步不等待 AI 完成。
数据和费用提示：保存前显示发送到第三方的数据类别（触发消息、上下文、昵称等）；对话记录默认关闭持久化，若开启则配置保留天数和清理任务。控制台展示调用数、失败数、Token（若上游返回）和估算费用（仅在提供可靠费率配置时展示）。达到上限时停止调用并说明限额，不静默切换到未知免费节点。
文档定义图片模板为基于浏览器渲染的自定义模板，可用于服务器状态、玩家数据、PAPI 查询等复杂图像。本项目建议使用受限 HTML/CSS 模板或可视化图层编辑器；具体采用哪一种需在原型验证中确定，不允许在运行时执行任意不受控网页脚本。
服主使用流程：
- 内容 > 图片模板 > 新建，选择用途（服务器状态、玩家信息、命令结果等）和画布尺寸预设。
- 选择“可视化编辑”或“导入模板包”。导入时预检模板版本、文件路径、资源类型和大小；拒绝外链脚本、任意文件访问和不支持资源。
- 在编辑器中添加文本、图片、矩形、头像/皮肤等受支持元素；通过变量面板插入玩家名称、在线数、服务器名称或获准的 PAPI 结果。
- 右侧属性编辑位置、尺寸、字体、颜色、对齐、边距和数据绑定；中央画布用样例数据实时预览。
- 点击“测试渲染”，显示耗时、内存上限、变量取值和渲染错误；通过后保存草稿并发布版本。
- 在命令或消息规则里选择已发布模板；可以回滚到上一个版本。
资源与部署提示：使用浏览器渲染器会增加内存和启动成本。启用前检查主机内存、并发渲染上限、单任务超时、图片尺寸上限和缓存空间；资源不足时提示维持文本模式。平台介绍提及 FULL 镜像至少建议 2 GB 内存，本项目应将其作为上游建议值展示，并通过压测确定自己的最低配置。
使用目标：插件为标准命令、路由和模板不能覆盖的事件处理提供扩展。由于任意脚本风险高，首版默认关闭插件加载；用户安装插件前必须确认来源和权限。
管理流程：扩展 > 插件 > 安装文件/目录；系统解析插件清单并展示名称、作者、版本、兼容 API、依赖和权限申请。管理员逐项授予或拒绝权限后才能启用。权限至少拆分为订阅事件、注册命令、访问玩家数据、调用外部网络、读写插件私有目录等，不提供默认全权。
生命周期操作：插件状态包括未安装、待授权、已停用、启动中、运行中、故障隔离。插件错误显示最近错误、关联事件和重启/停用入口。升级需显示版本差异和权限变化；权限增加需重新授权。卸载前说明其命令、事件订阅和配置将如何处理。
实现前置条件：脚本超时、中止、内存限制、主机 API 白名单和主进程隔离方案通过安全评估。若无法提供可靠隔离，扩展应作为独立进程协议运行，而不是在主服务中执行任意脚本。
- 群组页允许选择适配器、刷新群信息、设定默认群和为群添加标签。刷新只拉取当前机器人可见群，不绕过平台权限。
- 命令身份页允许管理员创建身份名称并分配平台群/用户或游戏权限条件；命令配置选择身份时展示其实际授权范围。
- 玩家查询通过 UUID、游戏名或社交账号搜索；搜索无结果时区分“玩家未出现”和“账号未绑定”。
- 仪表盘每个错误项提供“查看详情”“复制诊断 ID”；诊断包导出前允许选择时间范围，并自动脱敏密钥和个人信息。
- 备份页面支持创建本地备份、下载备份和验证文件；恢复操作先校验版本、数据库类型、文件完整性及目标数据摘要，再进入维护模式执行。
本节给出产品配置界面应该提供什么控件，不代表所有默认值已获产品确认。所有安全、平台和性能参数必须在帮助提示中说明单位、影响和限制。
| 配置页 | 用户可配置的关键项 | 建议初始值/策略 | 配置错误如何反馈 |
|---|---|---|---|
| 社交适配器 | 类型、连接模式、地址、凭据、心跳/超时、限速 | 使用适配器安全默认值；凭据必填与否按平台能力 | 测试连接逐项显示 DNS、握手、鉴权和能力发现结果 |
| Minecraft 服务器 | 桥接类型、服务器 ID、协议版本、共享密钥、心跳超时 | 自动生成唯一 ID 和随机密钥；只允许支持的协议版本 | 显示最后握手阶段、版本不匹配和认证失败原因 |
| 消息规则 | 来源、目标、方向、模板、过滤、频率、离线队列 | 单向/双向由用户明确选择；长度遵从目标平台限制 | 保存前列出冲突，测试发送检查模板与目标能力 |
| 绑定策略 | 模式、验证码时间/次数、可信群、唯一性、强制服 | 默认双向验证；信任模式不默认启用 | 字段错误和服务器兼容性分开提示 |
| 命令 | 关键词、匹配方式、作用域、权限、动作、冷却 | 精确匹配；危险动作需更高权限；新命令默认停用 | 模拟执行报告命中、授权、参数、目标和预期回复 |
| PAPI/玩家状态 | 变量、服务器、玩家上下文、超时、缓存 TTL | 只读；短 TTL；超时快速返回 | 测试展示桥接端、插件依赖、变量值和耗时 |
| AI | Base URL、Key、模型、触发范围、上下文、额度 | 默认关闭；仅 OpenAI 兼容接口；新群默认不允许 | 测试请求显示 HTTP 状态、模型错误和 request ID，屏蔽密钥 |
| 图片模板 | 画布尺寸、渲染并发/超时、最大资源、模板版本 | 限制尺寸和并发；无渲染器时不允许绑定图片命令 | 测试渲染报告失败元素和资源限制 |
| 插件 | 来源、版本、API 兼容、权限、启动状态 | 默认不执行未授权脚本 | 显示清单校验、权限差异和隔离状态 |
| 系统安全 | 监听地址、登录策略、会话时长、代理信任 | 监听回环；登录限流；代理默认不信任 | 提示哪些设置需要重启及公网暴露影响 |
| 数据库 | SQLite 路径或外部 DSN、TLS、连接池、备份 | 默认 SQLite；生产外部 DSN 凭据不写配置样例 | 保存前连通测试；迁移前备份并显示目标版本 |
配置表单统一支持“恢复默认”“取消未保存更改”和“保存”操作；只对确实有默认值的字段显示恢复。高级配置可折叠，但不得把必须安全设置藏在用户无法发现的位置。
服主创建一个社交适配器并验证机器人可收发；创建 Paper 服务器条目并将生成的 ID/共享密钥写入桥接端配置；等待在线后发现群；创建“官方群 ↔ 生存服”双向规则；选择默认格式和忽略机器人开关；发送双向测试消息；启用规则。玩家随后在群里发普通文本，游戏端显示带群来源和昵称的消息；游戏玩家聊天会在群内带服务器名和游戏名。命令、机器人回执和系统错误按规则过滤，日志以同一个事件 ID 关联两个投递方向。
管理员选“双向验证”并设置验证码过期和目标服务器；玩家在游戏端申请验证码，在官方群提交；机器人验证后确认绑定。管理员创建“在线状态”命令，关键词设置为“在线”，权限设为全员，动作选择查询服务器状态，作用服务器选大厅和生存服；测试区确认输出格式后启用。已绑定玩家可触发依赖个人身份的变量查询，未绑定用户收到绑定指引而非内部错误。
管理员在强制绑定列表中勾选正式服，设置未绑定拒绝进入和踢出消息，填入群名及绑定指令变量；在测试服模拟未绑定和已绑定玩家，分别验证限制和放行。正式启用后，桥接端在玩家登录事件检查绑定状态；解绑或群退事件触发后同步到服务器。若桥接端状态未知，管理台显示“强制策略无法确认已执行”，并进入告警，而不是显示成功。
管理员确认主机满足渲染资源要求，创建服务器状态模板，绑定服务器名、在线人数和状态变量，使用样例数据预览后测试真实渲染；创建命令“状态”，权限为全员，作用服务器选择目标服，回复形式选择图片并关联模板。执行命令时若图片渲染失败，按命令配置退化为文本摘要；日志显示渲染失败元素和 request ID。
管理员添加可信的 OpenAI 兼容提供方，填 API 地址、密钥和模型并测试；建立仅限测试群启用的触发策略，选择 @机器人，上下文轮数和每日额度设为有限值，关闭对话持久化；测试群中验证可用后再逐群开放。用户提问时收到 AI 回答，普通消息转发并行执行；达到限额后返回限额提示且不切换到未配置提供方。
| 优先级 | 首版范围 | 明确验收结果 |
|---|---|---|
| P0 | 初始化、认证、数据库迁移、适配器/服务器配置、状态、日志 | 安全启动，能发现连接故障 |
| P0 | 一种社交平台 + 一种 Minecraft 桥接端 + 群服消息规则 | 完成可重复的双向消息端到端演示 |
| P1 | 双向验证码绑定、强制绑定、查询绑定、基础访问控制 | 账号关联规则可靠，越权和失效挑战正确处理 |
| P1 | 文本/服务器命令/PAPI 查询及五类权限 | 命令模拟和真实执行权限符合配置 |
| P2 | AI 提供方和触发策略 | 限额、超时、数据范围可控，不影响主链路 |
| P2 | 浏览器渲染图片模板 | 在资源限制下完成预览、测试、发布和降级 |
| P3 | JS 插件生态、更多社交平台和多类桥接端、物品预览 | 各能力需单独通过兼容、安全和资源评估 |
首版排除：多租户 SaaS 计费、跨实例集群调度、任意主机 shell、未经授权的自动加群、无限量消息历史、未经安全评估的任意远程插件安装。此排除用于控制首发风险，不限制后续在明确安全与运营需求后立项。
以下是本策划书为了可执行而采用的暂定决策，需产品负责人确认后冻结：
- 默认绑定模式暂定“双向验证”，信任绑定必须由管理员显式开启并限定可信群。
- 默认数据库暂定 SQLite，MySQL/PostgreSQL 为同产品部署选项；三种数据库不代表支持多实例并发运行同一套适配器。
- 首版命令动作限定为文本、服务器命令代理和只读 PAPI 查询，不开放主机 shell。
- AI 默认关闭，配置 OpenAI 兼容 API；公共免费节点不作为默认提供方。
- 图片模板采用资源受限的浏览器渲染服务，需实测 CPU/内存后确定并发默认值。
- JS 扩展需先证明隔离、权限控制和超时可行；否则延期或改为独立扩展进程。
- 消息正文默认不长期入库；运营排障以脱敏摘要、ID 和投递状态为主，历史查询需求需另行确认。
这些建议的理由是把安全、数据范围和外部平台限制显式纳入产品体验。任何改动应同步更新配置说明、用户流程和验收用例，而不只修改后端默认值。