astrbot_plugin_onesync

语言 / Language: 中文 | English

OneSync 是一个面向 AstrBot 的通用可扩展软件更新器插件。

• 支持定时检查、自动更新、手动触发。
• 支持多目标扩展（不仅是 zeroclaw）。
• 支持镜像/多远端回退（提高更新稳定性）。
• 支持更新前自动探测远端质量（连通性与延迟）并择优使用。
• 支持状态持久化与事件日志，便于排障与审计。
• 设置页支持“软件与版本总览（自动生成滚动列表）”，便于用户快速查看。
• 支持内置 WebUI 管理端（无需改 AstrBot Dashboard 源码），提供“立即更新（当前筛选）/立即全部更新”并带确认弹窗。
• WebUI 现已支持读取与修改插件配置（含 Human/Developer 双模式目标编辑与 targets_json 互相同步）。
• 原生支持 system_package 策略：apt_get/yum/dnf/pacman/zypper/choco/winget/brew。

配置模式（重要）

OneSync 支持两种配置模式：

• human（默认）：面向用户的简洁配置，只保留常用基础项。
• developer：直接编辑 targets_json 的高级模式（镜像、超时、正则等）。

通过配置项 target_config_mode 切换。

软件总览（运维视图）

software_overview 是插件自动生成的软件版本总览，只读展示，不支持手动编辑。

为适配大规模运维场景，配置界面提供了多种切换能力：

1. 视图模式切换：
   • 表格：适合高密度、多列对比（带粘性表头和滚动区）。
   • 卡片：适合快速浏览单个软件状态。
   • 紧凑列表：适合一次查看更多目标。
2. 主题模式切换：
   • 跟随系统
   • 浅色
   • 深色柔和
   • 深色蓝灰
   • 海军蓝
   • 暖灰夜
   • 高对比
3. 密度模式切换：
   • 舒适
   • 紧凑
   • 极限紧凑
4. 运维筛选能力：
   • 支持按关键字搜索（软件名/版本/策略）。
   • 支持按状态筛选（已最新/可更新/待检查/已停用）。

以上偏好会在浏览器本地保存，下次打开配置页会自动恢复。

内置 WebUI（推荐）

当你希望不修改 AstrBot Dashboard 源码但仍获得完整前端交互时，可启用 OneSync 内置 WebUI。

1. 在插件配置中打开 web_admin.enabled=true。
2. 设定 web_admin.host 与 web_admin.port（默认 127.0.0.1:8099）。
3. （可选）设置 web_admin.password 开启 API 登录保护。
4. 重启/热重载插件后，查看配置项 web_admin_url，浏览器打开即可。

WebUI 关键能力：

• 按关键字和状态筛选软件。
• 立即更新（当前筛选）：只更新当前筛选结果中的启用目标。
• 立即全部更新（全部纳管）：更新所有启用目标。
• 配置中心：在 WebUI 内直接修改插件配置、目标模式、软件列表与目标参数。
• AI 配置助手：在 WebUI 内生成可直接发送给 AI 的 Prompt（初始化/增量新增/诊断/完整套件）。
• 使用指引：内置用户流程与开发者流程，并提供文档直达链接。
• 两个操作均有确认弹窗，防止误触。
• 内置 Debug 日志面板：支持多标签视图（运行/目标/调度/系统）、实时滚动、级别筛选、关键字过滤与一键清空。
• 内置 i18n：WebUI 支持中英文切换（界面文案、按钮、筛选项、日志面板标签同步切换）。

WebUI 内嵌 AI 助手与使用指引

入口方式：

• 顶部按钮：AI 配置助手、使用指引
• 快捷键：
  • Alt+A 打开 AI 助手
  • Alt+H 打开使用指引
  • Esc 关闭当前最上层弹窗（AI/指引/配置中心）

用户流程（推荐）：

1. 点击 AI 配置助手，先点 用户预设。
2. 如已有配置，先点 从当前配置自动填充，自动回填模式、轮询参数和一个软件目标字段。
3. 可选：打开 自动生成: 开 开关，让“自动填充”完成后直接生成 Prompt。
4. 选择场景（初始化/增量新增/诊断/完整套件）并补齐必要参数。
5. 点击 生成 Prompt，再点击 复制输出 发送给 AI。
6. 拿到 AI 返回的 JSON/脚本后，在 配置中心 或 API 下发。
7. 在 最近执行任务 与 Debug 日志 中验证执行结果。

开发者流程（推荐）：

1. 打开 AI 配置助手，点击 开发者预设。
2. 选择 完整套件 生成多场景 Prompt（初始化 + 增量 + 诊断）。
3. 将输出给 AI 生成 targets_json 或 API 一键脚本。
4. 在配置中心切到 developer 模式，粘贴配置后保存。
5. 执行 /updater env、/updater check 做环境与策略验收。

WebUI 常见问题：加载配置失败（404）

如果看到 加载配置失败: 404 Not Found，通常是运行中的插件实例还在使用旧版本前端/后端路由。

建议按以下顺序处理：

1. 重启 AstrBot 服务： systemctl restart astrbot.service
2. 确认访问的是 OneSync web_admin_url（默认 http://127.0.0.1:8099），而不是 AstrBot Dashboard 地址。
3. 浏览器强制刷新页面（Ctrl+F5）。
4. 在主机上验证接口：
   • curl -i http://127.0.0.1:8099/api/config
   • curl -s http://127.0.0.1:8099/openapi.json | jq -r '.paths | keys[]'

AI 一键配置 Prompt（复制即用）

如果你不想手动填大段参数，先用内置生成器自动产出 Prompt：

# 交互式：按提示回答少量问题（推荐）
python3 scripts/onesync_prompt_builder.py --interactive --lang zh --scenario suite --output /tmp/onesync_prompt_zh.txt

# 非交互：直接按参数生成（示例：Ubuntu + system_package）
python3 scripts/onesync_prompt_builder.py \
  --lang zh \
  --scenario suite \
  --os-profile ubuntu \
  --software-name curl \
  --strategy system_package \
  --output /tmp/onesync_prompt_zh.txt

然后把 /tmp/onesync_prompt_zh.txt 内容整体发给 AI，即可得到可执行配置结果。

下面这段 Prompt 可以直接发给 AI（ChatGPT/Codex/Claude 等），用于“一次生成 + 一次下发 + 一次验证” OneSync 配置。

你是 OneSync（astrbot_plugin_onesync）配置执行助手。目标：为我生成可直接提交到 OneSync WebUI API 的配置，并给出一键执行命令。

请严格执行：
1) 先根据我的输入，生成一个合法 JSON 文件内容，格式必须是：
   {
     "config": {
       ...OneSync 配置...
     }
   }
2) 再输出一段 bash 命令，完成：
   - 写入 onesync_config.json
   - （可选）如果 WEBUI_PASSWORD 非空，先 POST /api/login 获取 token
   - POST /api/config 下发配置
   - GET /api/config 与 /api/overview 做结果验证
3) 若有缺失字段，请使用稳妥默认值并在“假设说明”里列出。
4) 输出必须包含且仅包含以下 3 个部分：
   - `JSON_PAYLOAD`
   - `BASH_ONE_CLICK`
   - `ASSUMPTIONS`
5) 任何 JSON 不允许注释、尾逗号、伪代码。

我的输入如下（请按此生成）：
WEBUI_URL=http://127.0.0.1:8099
WEBUI_PASSWORD=
TARGET_CONFIG_MODE=human
POLL_INTERVAL_MINUTES=10
DEFAULT_CHECK_INTERVAL_HOURS=12
AUTO_UPDATE_ON_SCHEDULE=true
NOTIFY_ADMIN_ON_SCHEDULE=true
NOTIFY_ON_SCHEDULE_NOOP=false
ADMIN_SID_LIST=
TARGETS_YAML:
- name: zeroclaw
  strategy: cargo_path_git
  enabled: true
  check_interval_hours: 12
  repo_path: /home/jacob/zeroclaw
  binary_path: /root/.cargo/bin/zeroclaw
  upstream_repo: https://github.com/zeroclaw-labs/zeroclaw.git
  build_commands:
    - cargo install --path {repo_path}
  verify_cmd: "{binary_path} --version"
- name: curl
  strategy: system_package
  enabled: true
  check_interval_hours: 24
  manager: apt_get
  package_name: curl
  require_sudo: true

完整 Prompt 套件（初始化、增量新增、诊断修复）见安装配置手册：

• 安装与配置手册（中文）
• Installation & Config Guide (English)

快速设置同步时间（最短路径）

同步节奏由两个参数共同决定：

• poll_interval_minutes：后台轮询周期（分钟）。
• check_interval_hours：每个软件目标自己的检查周期（小时，可用小数）。

推荐设置：

1. 把 poll_interval_minutes 设为 5（或 10）。
2. 在目标配置里把 check_interval_hours 设为期望频率（例如 6 表示每 6 小时）。
3. 保存后重启 AstrBot（修改 poll_interval_minutes 后建议重启）。
4. 发送 /updater status 验证。
5. 发送 /updater env <name> 做依赖环境检测（命令可用性与版本）。

新增软件配置指南（人类方案）

适用场景：运维/普通用户在 WebUI 手工配置。

1. 在插件配置页把 target_config_mode 设为 human。
2. 进入 软件目标列表（human_targets）。
3. 点击“添加条目”，选择模板：
   • Cargo/Git 软件
   • 命令型软件
4. 填写条目参数：
   • 必填：name（唯一名称）。
   • 调度：check_interval_hours。
   • 基础：仓库/二进制路径或版本命令/更新命令。
5. 保存配置后，执行 /updater check <name> 验证目标可用。

说明：

• 条目数量不受固定槽位限制，可持续新增。
• 已存在目标会在列表里直接显示，可逐条修改或删除。
• 首次切换到 human 模式时，插件会自动把已有 targets_json 目标迁移到 human_targets 以便可视化管理。
• 镜像策略、超时、正则等高级项请切换 developer 模式配置。

新增软件配置指南（AI/开发者方案）

适用场景：让 AI 生成配置、或你批量维护多目标。

1. 把 target_config_mode 设为 developer。
2. 在 targets_json 中粘贴完整 JSON。
3. 保存后执行 /updater check 或 /updater run 验证。

安装

推荐安装路径：<ASTRBOT_ROOT>/data/plugins/astrbot_plugin_onesync

cd <ASTRBOT_ROOT>/data/plugins
git clone https://github.com/Jacobinwwey/astrbot_plugin_onesync.git

如果 AstrBot 以服务方式运行：

systemctl restart astrbot.service

验证：

• 管理员发送 /updater status。
• 出现 Software Updater Status 且目标列表正常，即插件加载成功。

管理命令

• /updater status：查看插件状态和目标状态（含最近一次 best_remote）。
• /updater check [target]：立即检查版本，不执行更新。
• /updater run [target]：立即检查并在有新版本时更新。
• /updater force [target]：强制执行更新命令（忽略版本比较）。
• /updater env [target]：检测目标依赖环境，显示命令路径与版本信息。

target 可省略；省略时对所有已配置目标执行。

文档导航

• 安装与配置手册（中文）
• Installation & Config Guide (English)
• 操作与同步手册（中文）
• Operations and Sync Manual (English)