⚙️ 配置说明

在 Web 界面左侧打开 「配置管理」，即可在浏览器里完成本页列出的全部设置。修改后请点击页面下方的 「保存配置」 才会生效（个别项保存后需要重启程序，页面上会有说明）。

本页按配置页的卡片顺序介绍每一项设置。每项都会给出它在配置文件 config.ini 里对应的名字（灰色代码），方便你对照排查；普通用户不需要手改配置文件。

少数功能有独立文档

下面这些卡片的内容较多，已单独成篇，本页只做指引：

• Bangumi Archive → 🗄️ Bangumi Archive 离线查询层
• Bangumi Replay → 🔄 Bangumi Replay 待同步队列补发
• 通知配置 → 🔔 通知系统配置
• ECH 进阶用法 → 🛠️ 自建 ECH DoH（进阶）
• AI 追番总结的记忆功能 → 🧠 AI 追番总结 · 记忆功能
• Trakt 同步 → Trakt.tv 定时同步（Trakt 有自己的配置页面）

---

同步配置

这一组决定「什么样的观看记录会被同步、怎么记」。对应 [sync] 段。

• 启用 Webhook 认证（webhook_auth_enabled）：打开后，媒体服务器通知本程序的地址里需要带上密钥，更安全，适合能从外网访问到本程序的情况；关闭则不要求密钥，仅适合完全内网、你信任当前网络环境时使用。
• Webhook 认证密钥（webhook_key）：开启认证后用来拼在通知地址里的一串字符；可复制，也可刷新为新密钥（刷新后记得在 Plex / Emby / Jellyfin 里把 Webhook 地址改成新的）。页面下方会给出各媒体软件地址的填写示例。
• 模糊匹配置信度阈值（match_confidence_threshold）：程序把媒体库里的片名和 Bangumi 条目对上时，如果最像的那个也只有这点相似度，就不直接同步，而是放进「候选确认」页等你人工确认，避免认错番剧还打了格子。默认 0.6。调高（如 0.85）更保守、更少认错；调低（如 0.4）更激进。填 0 表示关闭这道兜底，全部直接同步。你自己做的自定义映射和本地数据匹配不受它影响。
• 剧场版播放开始时将条目标为在看（movie_playback_start_mark_watching）：仅对剧场版动画生效。开启后开始播放剧场版，会自动把该条目在 Bangumi 上标为「在看」；关闭则不标。
• 剧场版同步后自动将条目也标为看过（movie_mark_subject_completed）：仅对剧场版动画生效，且要在本篇的格子已经打上之后。开启则顺便把整个条目的收藏状态设为「看过」；关闭则只更新观看进度。（如果你想自己写影评，建议关闭此项。）
• TV系列同步后自动将整部番标为看过（anime_mark_subject_completed）：仅对 TV 动画生效。当你看完该番剧下的所有正片格子时，自动把整个条目标为「看过」。默认关闭。
• 启用三次元（日剧/电影）支持（enable_real_action）：默认关闭，程序只认 Bangumi 的动画条目。开启后，动画找不到时会继续尝试三次元条目（日剧、真人版、真人电影等）。默认关闭。
• 测试同步跳过用户名校验（test_skip_permission_check）：开启后，「测试同步」这类调试接口不再检查媒体服务器用户名，方便你还没配好用户名时先验证匹配效果。只对测试接口生效，正常同步不受影响。

单人用还是多人用

程序按「Bangumi 账号」卡片里的账号数量自动判断：只有一个账号就是单人模式；添加了多个账号，就会按各自填写的媒体服务器用户名把记录分给对应账号。不需要手动切换模式。

屏蔽关键词

独立卡片，用于跳过不想同步的番剧。标题包含这里关键词的番剧将不同步（不区分大小写）。

• 点击卡片右上角 「添加关键词」，输入框中填入关键词后回车或点击「添加」即可加入列表。
• 每个关键词以红色标签展示，点击标签右侧的垃圾桶图标可删除。
• 添加和删除即时生效，无需手动点击页面下方的「保存配置」。
• 在「同步记录」页，失败或已忽略的记录旁也有一个盾牌按钮，可一键将该番剧标题加入屏蔽列表。
• 在「待确认」页拒绝某条候选时，相关标题会自动加入此列表（标签上会标注「拒绝时记录」）。

自定义映射优先

如果某个番剧既命中了屏蔽关键词、又设置了自定义映射，程序会按自定义映射同步——自定义映射代表你明确指定「我就要同步这一部」，优先级高于屏蔽规则。

关于存储位置

屏蔽关键词保存在数据库中，通过网页界面管理，不在配置文件里。 如果你的旧配置 config.ini 的 [sync] 段还写着 blocked_keywords，程序首次启动时会自动把这些关键词导入数据库（仅导入一次，之后以网页界面为准）。

Bangumi 账号配置

所有 Bangumi 账号统一在此卡片管理。账号通过 OAuth 授权 或 手动添加 两种方式添加，保存后即时生效。

• 仅一个账号时为单用户模式：只同步该账号对应的媒体服务器用户名的观看记录。
• 多个账号时按媒体服务器用户名自动路由：每个账号配置自己的媒体服务器用户名，谁看的就记到谁的 Bangumi。
• 点击账号条目的 「设为首选」 可切换默认账号，用于无法确定归属时的兜底（如放送日历、API 探测等场景）。
• 点击账号条目的 「停用」 可让该账号暂不参与同步：停用后条目仍保留在列表中并标记为「已停用」，点击 「启用」 即可恢复。

添加账号

• OAuth 授权（推荐）：点击卡片右上角 「OAuth 授权」 按钮，会跳转到 Bangumi 网站登录并授权，完成后自动回到本页并添加账号。授权过程中会自动获取你的用户名、昵称、头像与访问令牌，无需手动填写。回调地址由系统按当前访问地址自动派生，无需额外配置。
• 手动添加：点击 「手动添加」 按钮，自行填写用户名与访问令牌（适合已有令牌或无法使用 OAuth 的场景）。访问令牌可在 Bangumi 令牌生成页 获取。

账号字段说明

• Bangumi 用户名：你在 Bangumi 网站上的用户名。OAuth 授权时自动填充；手动添加时填个人主页 @ 后面的那串字符。
• 访问令牌：用于调用 Bangumi API 的凭证。OAuth 授权时自动获取并定期刷新；手动添加时需自行填写。令牌加密存储在数据库中。
• 媒体服务器用户名：你在 Plex / Emby / Jellyfin 等媒体服务器中的用户名，必须与媒体服务器里显示的一致，这样「谁看的」才能对上「记到谁的 Bangumi」。多个用户名可用英文逗号分隔。
• 观看记录仅自己可见：打开后，同步到 Bangumi 的观看记录仅自己可见，关闭则按 Bangumi 上公开的观看记录处理。
• 启用 / 停用：停用后该账号不参与任务同步，但仍保留在账号列表中，可随时重新启用；用于临时跳过某个账号的同步。
• 令牌过期时间 / 下次刷新：OAuth 授权的账号会展示令牌过期时间，系统会在临近过期时自动刷新，无需干预。
• 断开 OAuth：OAuth 授权的账号可点击「断开」回退为手动模式，保留已填写的访问令牌继续同步，但不再自动刷新。

媒体服务器用户名是必须的

媒体服务器用户名是同步与否的关键依据，请不要忘记设置，这关系到是否会触发同步动作。 fongmi 的用户名比较特殊，为设备名，在日志里可以看到相关信息。

账号存在哪里

账号信息（用户名、访问令牌、OAuth 令牌）保存在数据库 data/sync_records.db 里，不写在配置文件中，且令牌是加密存储的，数据库文件泄露也不会暴露明文令牌。

配置文件里的 [bangumi] 段（username / access_token / private / media_server_username）是老版本的遗留写法，仅用于升级时把旧配置迁移进数据库。新装用户不必理会；已升级的用户可以在 Web 界面确认账号无误后忽略它。

Bangumi OAuth 应用凭证

OAuth 授权所需的应用凭证（Client ID / Client Secret）已内置，开箱即用，普通用户无需关注本卡片。

如需使用自定义应用（例如自己创建的 Bangumi 应用），可在 bgm.tv/dev/app 创建后填写此处覆盖（对应 [bangumi-oauth] 段的 client_id / client_secret），或通过环境变量 BANGUMI_OAUTH_CLIENT_ID / BANGUMI_OAUTH_CLIENT_SECRET 注入。回调地址由系统自动按当前访问地址派生，无需配置。

Web 认证配置

对应 [auth] 段。这一组保护你的管理页面不被别人打开。

• 启用 Web 认证（enabled）：建议能从外网打开管理页时务必开启；关闭后任何人知道地址都能进管理页，仅适合纯内网且你完全信任当前环境。
• 管理员用户名（username） / 管理员密码（password）：登录管理页用的账号密码。密码框留空再保存表示不修改当前密码，要改密码时输入新密码并保存即可。密码会自动加密保存。
• 会话超时时间（session_timeout）：登录后多久无操作会自动退出，单位是秒，默认 3600（1 小时）。
• 启用 HTTPS 安全 Cookie（https_only）：只有当你用 https:// 访问管理页时才建议打开，避免登录状态被不当传输。
• 最大登录尝试次数（max_login_attempts） / 锁定时间（秒）（lockout_duration）：同一网络下连续输错密码达到次数后，暂时禁止该来源继续尝试登录，减轻被试密码的风险。默认 5 次、锁定 900 秒（15 分钟）。
• 会话密钥（secret_key）：程序自动生成、用于加密会话，一般无需修改。手动清空它会导致所有登录状态失效。

高级配置

这一部分大多是网络相关设置，对应 [web] 与 [dev] 段。大多数情况下保持默认就能正常使用，只有网络访问 Bangumi 不顺畅（打不开、很慢、频繁失败）时才需要调整。

访问地址

• Web 对外路径前缀（子路径反代）（[web] 段的 base_path）：只有把程序挂在网址的子路径下（如 http://nas:8000/bangumi）时才需要填，且要与网关或反向代理里设置的路径一致，让网页链接自动带上子路径。默认留空即可。修改此项后需要重启程序才会完全生效。

网络代理

• HTTP 代理（script_proxy）：需要翻墙或公司网络走代理时填写，程序访问外网（Bangumi、GitHub 等）都从它走；留空则直连。Docker 里要注意写法：bridge 模式用 http://172.17.0.1:端口 或 http://host.docker.internal:端口，host 模式用 http://127.0.0.1:端口。
• Bangumi API 反向代理（bgm_api_proxy）：程序连 api.bgm.tv 打不开或很慢时，换成你自行搭建或第三方提供的加速地址（用于替代 https://api.bgm.tv）；留空则使用默认地址。
• Bangumi Next 反向代理（bgm_next_proxy）：点击「授权登录」跳转的授权页打不开时，换成加速地址（用于替代 https://next.bgm.tv）；留空则使用默认地址。
• Bangumi 图片反向代理（bgm_image_proxy）：首页封面图显示不出来时，把封面图地址换成能打开的加速地址（用于替代 https://lain.bgm.tv）；留空则使用官方图片地址。
• SSL 证书验证（ssl_verify）：一般保持开启。仅当使用代理后出现证书报错、且你确认环境可信时，再考虑关闭（会降低连接校验强度）。

ECH（加密访问，推荐开启）

• ECH 模式（ech_mode）：off 关闭；doh 自动从 DoH 获取 ECH 配置（推荐）；manual 手动粘贴 ECH 配置。
• DoH 端点（ech_doh_url）：获取 ECH 配置使用的 DoH 服务地址。默认 https://dns.alidns.com/resolve（阿里公共 DNS，国内直连稳定、实测可正常返回 ECH 配置）；备选方案：海外网络可改 https://dns.google/resolve（Google 公共 DNS）；也可填自建 DoH（自建教程，有一定门槛，非必需）。仅 doh 模式时使用。
• DoH 走代理（ech_doh_use_proxy）：DoH 查询是否走上方「HTTP 代理」。默认关闭（直连隐私性更好）；若直连 DoH 不可达可开启。
• ECH 目标域名（ech_hosts）：启用 ECH 的域名，逗号分隔、后缀匹配（bgm.tv 同时覆盖 api.bgm.tv 等子域）。默认覆盖 Bangumi 全系域名，一般无需修改。
• 手动 ECH 配置（ech_ech_config）：manual 模式下粘贴 base64 编码的 ECHConfigList（可从 https://tls-ech.dev/ 获取）。仅 manual 模式时使用。

为什么推荐开启：正常访问网站时，TLS 握手会明文暴露你访问的域名（SNI），网络中间人（运营商、防火墙等）可以据此看到你在访问 Bangumi，甚至对这类连接做针对性探测/干扰（表现就是"直连经常失败、时好时坏"）。ECH 把握手过程中的域名信息加密隐藏，防探测、防针对性封锁。开启后无需任何维护（doh 模式自动获取配置），即使失败也会自动降级、不影响使用——收益大、零负担，所以推荐开启。

降级路径（任一环节失败自动回退普通 TLS，同步不受影响，日志会有 [ECH] ... 降级为普通 TLS 提示）：

• doh 模式：先向 DoH 端点查 ECH 配置（DNS over HTTPS JSON），失败再尝试二进制格式查询；两种都失败 → 降级普通 TLS；
• manual 模式：未填写配置或内容不是合法 base64 → 降级普通 TLS；
• 环境不支持（缺少 utls 依赖）或构建加密上下文失败 → 降级普通 TLS；
• 配置获取成功后缓存 20 分钟，配置变更自动重新获取。
• 首次启动（进程内第一次查询）会等待一次完整 DoH 查询（最长约 10 秒），确保从启动起就能用上 ECH；运行中缓存过期刷新最多等待约 1.5 秒，超时本次先降级普通 TLS（不阻塞同步），查询继续在后台完成并缓存——之后新建立的连接自动改用 ECH，无需重启。同一时刻只会发起一次 DoH 查询（并发请求共享同一结果）。

日志与排查

• 调试模式（debug）：打开后会打出更多运行细节，方便排查问题；日常使用建议关闭。
• 日志级别（log_level）：控制输出到控制台与日志文件的日志程度，可选 DEBUG / INFO / WARNING / ERROR，默认 INFO（也可通过 LOG_LEVEL 环境变量覆盖）。低于该级别的日志不会写入控制台/日志文件；开启「调试模式」时始终按 DEBUG 级别输出。同步基本过程（开始、结束、失败原因）属于 INFO，其余细节多属于 DEBUG。
• 日志文件路径（log_file）：日志写到哪里，默认 ./log.txt，可填绝对路径；留空则不写文件（仅控制台输出）。
• 日志轮转：日志文件超过 20MB 时自动轮转，保留最近 2 份备份（log.txt.1、log.txt.2），避免单个文件无限增长。
• 请求与批次关联：每条日志行会附带 [run:...]（单次同步）、[req:...]（HTTP 请求，取值于或自动生成的 X-Request-ID 请求头）、[batch:...]（一轮批量补发）标签，便于在日志页/同步记录中串起一次完整调用链。
• 同步记录保留天数（sync_records_retention_days）：程序每次启动时会自动清理超过指定天数的同步记录，控制数据库体积。默认 0 表示永不清理（保留全部历史记录）；调试环境可设为 7–14，生产环境建议 30–90。清理后仪表板的热力图缓存会自动失效并重新加载。

封面图是怎么来的（了解即可）：程序先看你的「在看」列表一次性拿全部封面，没在看的再逐个查；拿到地址后由你的浏览器直接加载图片，配了图片反代就用反代地址，没配就用官方地址。每个封面会记住 24 小时，不用反复查。

出问题会自动兜底：ECH 用不了会自动退回普通方式；封面批量取失败会改为一个个查；本地 Archive 没存到会去查线上。任何一项失效都不会影响同步，日志里会有提示，不用你手动处理。

Bangumi-data 配置

对应 [bangumi-data] 段。Bangumi-data 是一份公开的番剧资料库，用来帮助把媒体库里的片名对上 Bangumi 条目，对上之后记格更稳，也能减少查询次数。

• 使用 Bangumi-data 匹配（enabled）：是否启用它来帮忙匹配，默认开启。
• 使用本地缓存（use_cache）：是否把下载的数据存到本机，下次启动优先读本地，加快启动、少占带宽，默认开启。
• 缓存有效期（天）（cache_ttl_days）：本地缓存用多久后认为需要更新，默认 7 天；填 0 表示每次启动都尝试更新。
• 数据源 URL（data_url）：数据文件的下载地址，一般保持默认即可；若默认地址在你网络下打不开，可换成镜像说明里提供的地址。
• 本地缓存路径（local_cache_path）：缓存文件保存在哪个路径，默认 ./bangumi_data_cache.json，一般保持默认即可。
• 请求代理（http_proxy）：下载这份数据时用的代理，留空则自动沿用「高级配置」里的 HTTP 代理。

匹配裁决层

对应 [matching] 段。这一层决定「搜索到的一堆候选里，到底采用哪一个、够不够格自动采用」。

默认关闭。关闭时只用一个标准判断：相似度够高就直接采用（也就是上面「同步配置」里的模糊匹配置信度阈值），行为与以前完全一致。

开启后改为两个标准：既看分数够不够，也看它比第二名高出多少。两个都不满足的条目会放进「候选确认」页等你确认，而不是直接打格子。

• 启用裁决层（arbiter_enabled）：总开关，默认关闭。
• 最低加权分（min_score）：低于这个分数就判定为「没找到」，默认 0.85。
• 最低领先幅度（min_margin）：第一名和第二名的分差小于这个值，说明是「险胜」，默认 0.10，同样放进待确认。
• 歧义阈值（ambiguous_margin）：分差小于这个值，说明条目本身就有歧义（比如同名不同年份），除了放进待确认，还会额外发一条「匹配有歧义」的提醒，默认 0.05。
• 各来源权重（weight_custom_mapping / weight_bangumi_data / weight_archive / weight_api_search）：同一条目可能被多个来源同时命中（你自定义的映射、本地资料库、本地归档、在线搜索）。程序取「权重 × 分数」里的最高值，让最可信的来源说了算，而不是把各来源的分数平均。默认都是 1.0；把某个来源调低，等于降低它的发言权。

该不该开启

实测下来，开启后认错的条目从 9 条降到 2 条，但代价是自动同步的数量减少（一部分本来正确的匹配会变成需要你人工确认）。

• 如果你更受不了「悄悄标错」（标到了错误的番剧，看起来一切正常）→ 建议开启
• 如果你更受不了「少标」（宁可先自动标上，错了再改）→ 保持关闭

裁决层不会改变「选了哪一季」

季度、媒体类型、关联条目的自动改选属于剧情逻辑（例如搜索命中了第二季但实际应该标第一季），不是分数高低的问题，裁决层不会推翻这些结果。

今日放送提醒

依赖 Bangumi Archive 的放送日期数据，每日定时查询当天放送的番剧章节并通过通知系统推送。仅在 Archive 启用且已导入数据时生效。对应 [notify-airing-today] 段。

• 启用（enabled）：总开关，默认开启，但仍需 Archive 启用才会真正执行。
• 定时 Cron（cron）：默认 0 9 * * *（每日 09:00）。保存配置后定时任务会热更新，无需重启。
• 仅我在追（only_watching）：开启后只统计你在 Bangumi 上「在看」的番剧（动画 + 三次元），需配置 Bangumi 账号；获取失败时自动降级为全部放送。

通知订阅

这个事件默认不会发到任何渠道，需要在「通知配置」里订阅（在「调度任务」分类下勾选「今日放送提醒」）。

此外，仪表板有番剧放送日历卡片（仅在 Archive 启用时显示），可查看未来 7/14/30 天的放送日程，支持「仅我在追」筛选。

飞牛影视

从飞牛的播放记录同步到 Bangumi（仅在使用飞牛并需要此功能时关注）。对应 [feiniu] 段。接入步骤见 飞牛定时同步。

• 启用飞牛同步（enabled）：关闭时完全不读飞牛数据。首次打开并保存后，只会处理保存之后在飞牛里有更新的观看记录，不会把很久以前的老记录一次性全部推到 Bangumi；关闭并保存会清除这一起点设置。
• 数据库路径（db_path）：飞牛库里的 trimmedia.db 在本程序能读到的位置（按你安装方式可能是本机路径或容器里的路径），按安装说明挂载或填写即可。
• 视为看完的最低进度 (%)（min_percent）：播到百分之多少就算「看完了」可以记格，默认 85%，飞牛里已标记看完的会当作 100%。
• 飞牛用户（user_filter）：通常填 all 表示不区分飞牛账号；若只想同步某一个飞牛用户，需要其专用标识，可在 「调试工具」 中按页面说明查看后再填。
• 时间范围（time_range）：在启用同步的前提下，可再限制「只关心最近多久内有更新的记录」，减少无关条目。默认 all。
• 定时扫描间隔（sync_interval）：隔多久自动检查一次飞牛上的观看进度，默认每 15 分钟，不熟悉可保持不动。
• 单次扫描最大条数（limit）：每次最多处理多少条候选记录，默认 100，数字越大单次负担越重。

fongmi 局域网同步

从局域网内 fongmi 播放器的实时播放状态同步到 Bangumi（仅在使用 fongmi 及其 fork 并需要此功能时关注）。对应 [fongmi] 段。接入步骤见 fongmi 局域网同步。

• 启用 fongmi 同步（enabled）：关闭时完全不轮询 fongmi 设备。开启后会按设定频率访问设备的 /media 端点，检测播放进度达标的剧集并提交到 Bangumi。仅支持 fongmi 及其 fork（TV-K、OK影视、WebHomeTV 等），原版 TVBoxOSC 不支持。
• 设备列表（devices）：手动指定 fongmi 设备 IP，多个用英文逗号分隔，可带端口号，例如 192.168.1.100 或 192.168.1.100:9979。使用非标端口的设备必须在此填写；留空则依赖下方的自动扫描。
• 自动扫描网段（auto_scan）：开启后会扫描下方网段的默认端口 9978，自动发现 fongmi 设备。只有一台设备时建议关闭此项并直接填写设备 IP，更快也更稳定。
• 网段（subnet）：自动扫描的局域网网段前三段，默认 192.168.1（会扫描 192.168.1.1–192.168.1.254）。Docker 部署需使用 host 网络模式，否则容器无法发现局域网设备。
• 视为看完的最低进度 (%)（min_percent）：播放进度达到该百分比即视为看完并参与同步，默认 80%。直播流不参与判定。
• 定时 Cron（sync_interval）：隔多久自动轮询一次 fongmi 设备，默认每 3 分钟 */3 * * * *。保存配置后定时任务会热更新，无需重启。
• 与 Bangumi 账号的对应关系：单用户或多用户模式下，上文「媒体服务器用户名」需填写 fongmi 设备名称（来自 /device 的 name 字段，不是 IP），可在 「调试工具」 的 fongmi 扫描结果或同步日志中查看。

Trakt 同步

Trakt 有自己的配置页面（左侧菜单「Trakt 同步」），不在「配置管理」页里。对应 [trakt] 段，接入步骤见 Trakt.tv 定时同步。

• Client ID（client_id） / Client Secret（client_secret）：在 Trakt 网站创建应用后获得的应用凭证。
• 回调地址（redirect_uri）：必须与 Trakt 应用设置里填的回调 URL 一致。
• 默认同步间隔（default_sync_interval）：新建 Trakt 同步任务时使用的默认周期，默认每 6 小时。
• 默认启用（default_enabled）：新建 Trakt 同步任务时是否默认开启。

LLM 全局配置

LLM 连接是独立模块，追番总结和调试工具共用。在「配置管理」页面顶部的 LLM 卡片中修改，对应 [llm] 段。

• 提供商（provider）：LLM 服务提供商。可选值：openai_compat（默认，兼容 OpenAI / DeepSeek / Ollama 等 OpenAI 接口格式的服务）、anthropic_compat（兼容 Anthropic Messages API，官方 API 或遵循 /v1/messages 规范的代理/网关均可）。
• API 地址（api_base）：LLM 服务商的 API 端点，需兼容所选 provider 的接口格式。openai_compat 默认 https://api.openai.com/v1，OpenAI 兼容接口请以 /v1 结尾填写完整地址；anthropic_compat 默认 https://api.anthropic.com/v1，使用第三方兼容网关时按其文档填写。
• API 密钥（api_key）：服务商提供的 API Key。加密存储，页面回显为掩码。
• 模型（model）：要调用的模型名称，默认 gpt-4o-mini。openai_compat 请确认模型支持 Chat Completions 接口；anthropic_compat 请填写 Claude 模型（如 claude-sonnet-4-6、claude-opus-4-6 等）。
• 最大 Token（max_tokens）：单次请求最大输出 token 数，默认 2000。根据模型上下文窗口和总结长度调整。Anthropic Messages API 的 max_tokens 为必填字段，请保持不小于所需输出长度。开启思考强度时该值会被自动抬升到不低于 budget_tokens + 1024（Anthropic 约束：思考 token 计入 max_tokens 上限，budget_tokens 必须小于 max_tokens），无需手动调大。
• 温度（temperature）：生成随机性，0~2 之间，默认 0.7。越低越确定/保守，越高越有创意。注意开启思考后该值会被强制为 1（Anthropic 与 OpenAI o 系列均要求）。
• 思考强度（thinking_level）：可选 off / low / medium / high，默认 off 不启用思考。anthropic_compat 开启后映射为 Anthropic extended thinking 的 budget_tokens（依次为 2048 / 4096 / 8192），low 适合日常总结，高质量总结可试 high；claude-haiku 系列等不支持 extended thinking 的模型会自动降级为 off（日志有提示）。openai_compat 开启后映射为 OpenAI reasoning_effort（low / medium / high），仅 o 系列推理模型（o1/o3/o4-mini 等）生效，其余模型自动忽略（debug 日志有提示）。
• 超时时间（timeout）：请求超时秒数，默认 60。遇到超时错误可适当调大。
• 调用记录保留（retention_days）：LLM 调用记录（Token 用量、延迟等）在数据库中保留天数，默认 365 天。

配置后可点击「测试连接」按钮验证 LLM 是否可达。

---

AI 追番总结

前提：需要先完成 LLM 全局配置，追番总结依赖 LLM 来生成摘要。

在「配置管理」→「AI 追番总结」卡片中创建和管理总结任务。每个任务在配置文件里对应一个 [summary-任务名] 段，但全部在 Web 界面操作，无需手动编辑配置文件。

追番总结任务

在「配置管理」→「AI 追番总结」卡片中操作：

• 任务名称（name）：唯一标识，也用作配置段后缀。通过 Web 界面创建时自动生成（例：追番总结 1）。

• 启用（enabled）：是否开启该定时任务。

• 定时 Cron（cron）：五段式 Cron 表达式，默认 0 21 * * *（每晚 9 点执行）。保存后定时任务会热更新，无需重启。

  常用示例（直接复制 Cron 表达式，配合对应回溯天数）：

  场景	Cron	lookback_days
  每日总结（默认）	0 21 * * *	1
  每周总结（周日 21:00）	0 21 * * 0	7
  每月总结（1 号 21:00）	0 21 1 * *	31
  每季度总结	0 21 1 1,4,7,10 *	92
  年度总结	0 21 1 1 *	365

  季度总结的 92 天回溯已覆盖季番和半年番。如需每次总结半年内容，Cron 保持不变、回溯天数改为 183 即可。

  支持同时创建多个任务（如每日 + 年度），各自独立运行、互不影响。

• 回溯天数（lookback_days）：每次执行时回顾最近几天的观看记录，默认 1 天。调整为与 Cron 周期匹配（如季度总结设为 92）。

• 限定用户（user_name）：只总结特定用户的记录，留空则包含所有用户。

• 自定义提示词（system_prompt）：控制总结的语气、格式、长度等。默认为轻松聊天风格的中文提示词，可根据需要改写。

• 最大记录数（max_records）：每次发送给 LLM 的最大观影记录条数，默认 -1（不限制）。季度/年度总结保持 -1 即可，日常总结可设为 200 控制上下文长度。

📋 推荐 Prompt 模板（点击展开，直接复制）

数据洞察型 — 统计观看数据，发掘规律：

你是一个追番数据分析师。用户会给你一段观影记录，请生成一份数据洞察报告：

1. 按观看次数降序排列番剧，标记 TOP 3 热门
2. 统计各用户的观看活跃度（总集数、番剧数）
3. 从记录时间戳推断观看高峰时段（如工作日晚上、周末下午）
4. 从番剧标题推断类型分布（热血/日常/恋爱/奇幻 等），按占比排名
5. 语气轻松但有数据感，控制在 400 字以内

偏好分析型 — 根据片单推断口味，给出推荐：

你是一个懂二次元的追番顾问。用户会给你一段观影记录，请分析用户的口味偏好：

1. 根据番剧名称和风格，归纳用户的观看偏好（如"偏爱战斗番""喜欢治愈日常"）
2. 如果涉及多用户，对比不同用户的喜好差异
3. 根据当前片单，推荐 1-2 部风格相近的番剧（仅推荐，无需查数据）
4. 语气像朋友聊天，控制在 350 字以内

简洁播报型 — 极简进度表，适合高频推送：

你是一个极简追番播报员。用户会给你一段观影记录，请生成一个超简总结：

1. 按番剧分组，只列名称和进度（如"《芙莉莲》S1E10"）
2. 多用户场景下标注每条记录属于谁
3. 总字数不超过 150 字
4. 最后加一句不超过 15 字的俏皮评论

吐槽评论型 — 轻松吐槽风，比默认更活泼：

你是一个毒舌但可爱的追番伙伴。用户会给你一段观影记录，请用吐槽风格生成总结：

1. 按番剧分组描述进度，并对每部番剧加一句简短吐槽（如"终于开始补这部了，全网都在等你"）
2. 如果进度太慢（同部番剧集数增长很少），善意调侃
3. 如果开了很多新坑，提醒"注意肝度"
4. 语气轻松毒舌但不冒犯，控制在 300 字以内

记忆与同剧关联

追番总结可以「记住」之前总结过的内容，让每次总结有连贯性。这两个选项对应任务配置里的 memory_limit 与 related_limit，默认都是 0（关闭）。详见 🧠 AI 追番总结 · 记忆功能。

创建任务后，可在「调试工具」页面手动触发测试。总结结果会通过通知系统发送，对应的通知类型为 watching_summary_{任务名称}，可在 Webhook/邮件配置中勾选。

调度器

对应 [scheduler] 段。这一组控制程序内部「定时任务」的运行方式，默认值适合绝大多数场景，一般无需修改。目前没有对应的配置页卡片，需要时请手动编辑 config.ini 后重启程序。

• 时区（timezone）：定时任务按哪个时区计算时间，默认 Asia/Shanghai。用 IANA 名称填写（如 Asia/Shanghai、America/New_York、UTC）。留空时会依次回退到环境变量 TZ、最后回到默认值。Docker 部署也可以用 TZ 环境变量指定。
• 启动延迟（startup_delay）：程序启动后等待多少秒才开始运行定时任务，默认 30 秒。留出这段时间让网络、数据库就绪，避免开机瞬间集中失败。
• 最大并发同步数（max_concurrent_syncs）：同时最多处理几个同步任务，默认 3。机器性能较弱或媒体服务器较慢时可调低。
• 单个任务超时（job_timeout）：单个定时任务最长允许运行多少秒，默认 300（5 分钟），超时会被中断并记为失败。数据量大、网络慢时可调大。
• 最大重试次数（max_retries）：任务失败后重试几次，默认 3。
• 重试间隔（retry_delay）：两次重试之间等待多少秒，默认 60。

---

配置文件在哪

Web 界面背后对应一个 config.ini 文件（INI 格式），首次运行时会从 config.example.ini 自动复制一份。程序按以下顺序查找：

1. CONFIG_FILE 环境变量
2. /app/config/config.ini（Docker 挂载）
3. config.dev.ini（开发）
4. config.ini（默认）

不要和 Web 界面同时改

推荐通过 Web 界面修改。若你手动编辑了 config.ini，需要重启程序才生效；并且编辑期间不要在 Web 界面点保存，否则会把手改的内容覆盖掉。

接下来

配置完成后，按你的播放端接入媒体源：

• Plex：Tautulli / 原生 Webhook
• Emby 通知 / Jellyfin Webhook
• 自定义 Webhook
• Trakt.tv 定时同步 / 飞牛定时同步 / fongmi 局域网同步

标题对不上 Bangumi 条目时，可使用 自定义映射 手动指定。