MoviePilot/docs/refactor/agent-tool-refactor-plan.md

MoviePilot Agent 工具体系重构计划

状态：COMPLETE — L1-L10 全部 VERIFIED，正式方案已提交推送并通过远端 CI

建立日期：2026-08-31

当前基线：v3@91e33277f3a05dc10b8984a2e612d8a32441c987

关联目标：本线程已建立的 Agent 工具体系重构 Goal

1. 战略目标

在不削弱 MoviePilot Agent 智能化、权限安全、会话交互、后台任务和失败恢复能力的前提下， 重构当前过大的 Agent 工具目录：

• 用受控、结构化的 MoviePilot API 网关承载稳定业务能力
• 用按领域 Skill 提供调用流程、参数语义和 API 操作范围
• 用受控 Skill 脚本直接承载下载器、媒体服务器的低层第三方 API 操作
• 迁移可以由 REST API 完整表达的业务工具，删除重复的 Agent Tool Schema
• 补齐搜索会话、规则校验、安全设置和插件数据等 API parity
• 保留依赖当前会话、渠道、宿主或流式状态的原生能力
• 保持原有权限、确认、幂等、审计、结果裁剪和可恢复语义

最终目标不是建立一个可执行任意 URL 的万能 curl 工具，而是建立一个由操作白名单、身份透传、 策略分类和结果投影共同约束的 API 能力面。

下载器和媒体服务器采用混合边界：设备级查询、诊断和任务控制可以由 Skill 的受控脚本 读取本机配置后调用第三方自身 API；涉及 MoviePilot 媒体身份、路径映射、下载历史、订阅、 转移和跨服务器聚合的高层用例继续由 MoviePilot Application/API 承担。

2. 基线与当前实现事实

项目	初始基线	当前实现
工厂固定工具元组	82 个	12 个原生工具；默认再追加 send_local_file 与 moviepilot_api，共 14 个
工具目录默认行为	LLM_MAX_TOOLS=0，默认将完整目录绑定到主模型	默认完整目录已收敛为 14 个；按钮选择和语音发送仅在渠道能力满足时条件注入
默认固定目录体积	工具名称、描述和 JSON Schema 合计约 113 KB	实测 23,865 bytes，约下降 79%
API Skill	skills/moviepilot-api/SKILL.md 通过任意 method/path 调用	moviepilot_api 只接受 203 个固定 operation ID；Skill 与 MCP oneOf 逐 operation 暴露精确英文参数合同
API 身份	API Token 映射为管理员级集成身份，不等于 Agent 当前用户/渠道身份	Web/渠道身份绑定到真实用户；HTTP/MCP 管理入口绑定持久化超级用户，不接受模型注入 Token
下载器/媒体服务器	依赖内置低层 Agent 工具或有限 REST operation	downloader-operation 与 mediaserver-operation Skill 通过固定脚本调用已配置 provider API
MCP/HTTP 工具管理	存在旧业务工具与同名 first-wins 选择空间	与主 Agent 共用严格唯一新目录；重名直接以 TOOL_IDENTITY_AMBIGUOUS 失败
退役代码	旧实现仍位于 app/agent/tools/impl	77 个退役文件已直接删除，其中 72 个工具模块、5 个辅助模块
架构图	982 个宿主模块、8,430 条内部依赖边	919 个宿主模块、7,690 条内部依赖边，Application/Chain 具体 Adapter 直连仍为 0
工作区状态	基线提交 871632af，与 origin/v3 对齐，初始工作区干净	L1-L10 已完成并通过远端 CI；2026-09-01 继续修复集合总数在大结果截断预览中不可见的问题

3. 目标工具分层

3.1 第一批迁移：现有 API 基本覆盖的 48 个工具

领域	工具
媒体	search_media, search_person, search_person_credits, recognize_media, scrape_metadata, query_episode_schedule, query_media_detail
订阅	add_subscribe, update_subscribe, search_subscribe, query_subscribes, query_subscribe_shares, query_popular_subscribes, query_subscribe_history, delete_subscribe
下载/历史	add_download_tasks, query_download_tasks, delete_download_tasks, delete_download_history, delete_transfer_history, query_downloaders
站点	query_sites, update_site, query_site_userdata, test_site, update_site_cookie
推荐/媒体库/存储	get_recommendations, query_library_exists, query_library_latest, query_directory_settings, list_directory, query_transfer_history, transfer_file
调度/工作流	query_schedulers, run_scheduler, query_workflows, run_workflow
插件	query_installed_plugins, query_market_plugins, query_plugin_capabilities, query_plugin_config, update_plugin_config, reload_plugin, install_plugin, uninstall_plugin
命令/配置	list_slash_commands, query_custom_identifiers, update_custom_identifiers

3.2 第二批迁移：补齐 API parity 后的 16 个工具

• 搜索会话：search_torrents, get_search_results
• 下载器高级修改：update_download_tasks
• 过滤规则和规则组：9 个查询、增加、更新、删除工具
• 插件持久化数据：query_plugin_data
• 安全系统设置：query_system_settings, update_system_settings
• 斜杠命令执行：run_slash_command

3.3 原生能力最终保留

• 外部能力：search_web, recognize_captcha, browse_webpage
• 当前渠道消息：send_message, send_local_file；ask_user_choice 与 send_voice_message 按渠道能力条件注入
• Agent 会话任务：agent_task 单工具 action=create/list/update/run/delete
• Agent 人格状态：persona 单工具 action=list/switch/update
• 宿主能力：execute_command, edit_file, apply_patch, write_file, read_file
• 诊断能力：query_doctor_report

此外，渠道工具、Skill 工具、统一记忆（含活动记录）、子 Agent 和插件/MCP 动态工具继续按运行时条件注入；活动记录不再维护独立的活动日志中间件。

3.4 最终目录规模

• 工厂固定工具元组由 82 个降为 12 个原生工具。
• 默认运行目录再追加 send_local_file 与单一 moviepilot_api 网关，共 14 个固定工具。
• 其中 13 个是原生能力，1 个是 203-operation 结构化 API 网关。
• ask_user_choice、send_voice_message、Skill、渠道、子 Agent、插件和外部 MCP 工具仍按运行时条件注入，不计入 14 个默认固定工具。
• 77 个退役实现/辅助文件直接删除，不保留 Agent 或 MCP 兼容副本。

3.5 下载器与媒体服务器第三方 API Skill

评估结论：可行，纳入正式目标，但采用“低层直连、高层保留”的边界。

能力	最终承载方式	原因
下载器实例发现、连接诊断、任务列表和详情	downloader-operation Skill + 受控脚本	属于 qBittorrent、Transmission、rTorrent 自身能力，适合按 provider 扩展
下载器暂停、恢复、限速、标签、分类、Tracker 和删除	downloader-operation Skill + 受控脚本	参数差异可在脚本适配层显式归一；删除文件仍需明确确认
媒体服务器实例、用户、媒体库、条目、最近入库和扫描诊断	mediaserver-operation Skill + 受控脚本	属于 Emby、Jellyfin、Plex 等服务自身查询面
媒体库刷新/扫描	mediaserver-operation Skill + 受控脚本	允许按 provider 能力执行，属于外部副作用并要求确认
下载提交、种子与站点 Cookie、保存目录选择	MoviePilot API	必须保留站点、下载选择、路径映射、历史和失败恢复语义
library.exists 精确去重	MoviePilot API	必须保留 canonical media_source/media_id、音乐匹配和多服务器聚合
下载/转移历史、订阅状态、自动转移	MoviePilot API	属于 MoviePilot 持久化与业务编排，不是第三方设备 API

Skill 脚本必须满足：

• 从 MoviePilot 本机配置读取连接参数，模型参数中不得出现服务器 URL、用户名、密码或 Token
• 只允许脚本声明的 provider、实例名和 action，禁止任意 URL、任意 HTTP method 和任意请求头
• 优先复用现有 provider client/SDK 和配置解析，不复制 MoviePilot 高层 Chain 业务规则
• 输出统一 JSON、默认分页和字段投影，错误中不得回显凭据
• 只在新 Skill 和离线测试就绪后，从 moviepilot-api operation 目录移除重复低层操作
• 不删除供前端和其它宿主调用的 REST 端点；删除的是 Agent operation 暴露和旧 Agent Tool 代码

能力面不局限于替换现有 operation。每个脚本都提供 capabilities 动作，按当前已配置实例和 provider 动态返回 namespaced action、参数约束、副作用等级及是否支持批量调用；Agent 只在加载 对应 Skill 后看到这部分领域知识。首批扩展目标包括：

• 下载器：任务属性/文件/Tracker/Peer、队列与优先级、暂停/恢复、重校验、重新汇报、 限速、分类、标签、保存位置、顺序下载、会话统计、剩余空间和批量任务控制
• 媒体服务器：服务器/用户/媒体库/条目查询、最近入库、搜索与详情、播放会话、观看状态、 媒体库扫描、单项元数据刷新，以及 provider 已稳定实现的合集/播放列表等扩展能力
• provider 专属能力通过扩展注册表增加；禁止退化为任意对象方法调用、任意 URL 或任意 HTTP 请求

4. 阶段、叶子和依赖

执行规则：任何时刻只允许一个叶子处于 ACTIVE；每个叶子必须可独立验证、交付和回滚。

阶段/叶子	状态	依赖	退出条件
L1 基线与契约设计	VERIFIED	无	工具替代矩阵、调用路径、权限事实、输出合同、回归指标和排除项冻结
L2 受控 API 网关	VERIFIED	L1	moviepilot_api 结构化工具、固定 API 路由、身份/策略透传、结果裁剪和统一新目录完成；不设置运行时切换开关
L3 API parity	VERIFIED	L2	搜索会话、下载高级修改、过滤规则、插件数据、系统设置和斜杠命令均有 typed API 与离线测试
L4 第一批迁移	VERIFIED	L2	第一批工具从 Agent、MCP 和 HTTP 工具管理目录移除，能力统一由 API 网关提供
L5 第二批迁移	VERIFIED	L3	parity 工具迁移完成，确认、脱敏、幂等和恢复语义进入统一策略
L6 原生工具收敛	VERIFIED	L4,L5	Agent 任务和人格工具合并为 action 工具；宿主/会话/渠道原生能力边界固定
L7 第三方服务 Skill 化	VERIFIED	L5	下载器和媒体服务器能力发现、受控脚本、Skill、策略和离线测试完成；重复低层 Agent API operation 已删除
L8 收口与交付	VERIFIED	L6,L7	旧代码、文档与架构基线已收口；静态检查和锁定全量测试已完成
L9 全 API 面审计与最终交付	VERIFIED	L8	375 个 OpenAPI 操作逐路由归属、203 个网关合同与 72 个退出工具映射均由测试锁定；全量测试、80% 覆盖率门禁、提交推送和远端 CI 终态均已完成
L10 查询 API 显式分页与数据库下推	VERIFIED	L9	列表端点显式声明分页输入；数据库筛选在 LIMIT/OFFSET 前完成并使用同条件精确 COUNT；省略新增参数保持旧返回语义；响应 data 列表结构不变；外部原生分页未提供总数时不伪造；OpenAPI、MCP、Skill、审计、80% 覆盖率和远端 CI 同步完成

5. L2 受控 API 网关约束

5.1 模型可见合同

模型只看到一个结构化工具：moviepilot_api(operation_id, path_params, query, body)。

operation_id 来自审核过的操作注册表，模型不能传入任意 host、URL、认证头或 API Token。

5.2 身份和权限

• 从当前 Agent 的 ToolPolicyContext 继承用户、会话、渠道、来源、后台/子 Agent 身份
• API 网关不能把全局 API_TOKEN 当作当前用户身份
• 策略按 operation_id 加参数分类，而不是只按工具名 moviepilot_api 分类
• 读取、敏感读取、可恢复写入、破坏性写入和外部副作用分别处理
• 保持现有确认、管理员门禁、敏感值脱敏、幂等和恢复模式

5.3 Skill 合同

Skill 负责判断何时使用某个领域能力、提供业务流程和参数示例、声明允许访问的 allowed-api-operations。宿主必须实际执行该操作范围；只在提示词里显示 allowed-tools 不算权限控制。

5.4 输出和失败合同

• 统一 JSON envelope、分页、字段投影和长度上限
• 结果进入模型前做敏感字段裁剪和错误归一化
• 写操作带幂等键或版本前置条件
• 超时和取消后明确外部状态未知，不能直接报告为已停止
• API 网关不得复制业务规则；业务 owner 仍是现有 Application/Chain/API 能力

第三方服务 Skill 的脚本不属于 API 网关，也不得成为任意网络出口。脚本只消费审核过的 action，并使用 MoviePilot 已配置的具体服务实例访问其自身 API。

6. 验收指标

功能

• 媒体搜索、识别、订阅、下载、站点管理、媒体库、插件和工作流任务成功率不低于基线
• 搜索结果短引用、分页、筛选项和下载任务关联不回退
• API 网关和 provider Skill 的替代路径保持原业务结果、错误、确认与恢复语义

安全

• 普通用户、频道管理员、系统管理员、后台任务和子 Agent 权限边界保持一致
• 未经确认不能执行敏感读取、删除、覆盖、安装和外部副作用
• API Token、Cookie、密码和插件私有数据不进入 prompt、日志或错误摘要
• 不允许模型通过参数绕过 operation allowlist、host 限制或身份绑定
• 第三方服务 Skill 不接受连接地址或凭据参数，删除文件和媒体库扫描按外部副作用处理

运行质量

• 主模型工具 Schema 体积显著下降
• 工具选择误选率、平均调用次数、上下文 token、端到端延迟不劣于基线，优先取得改善
• API 网关失败可观测、可重试、可对账；取消/超时场景可恢复
• 所有测试零真实外部网络；相关测试使用边界 mock 或录制回放

7. 明确排除项

• 不把 execute_command 当作 MoviePilot API 网关；仅允许领域 Skill 调用仓库内受控、可审计的固定脚本
• 不暴露任意 REST path、任意 HTTP method 或任意外部 host
• 不把浏览器、验证码、文件编辑、终端命令和渠道回调强行 API 化
• MCP、HTTP 工具管理器和主 Agent 全部使用新 API 工具目录，不保留旧业务工具兼容入口
• 不修改 app/plugins/** 运行时副本
• 旧工具不作为回滚机制；回滚依赖 Git 版本和提交边界，正式运行时不保留兼容实现
• 不用第三方直连替代下载提交、订阅、转移、历史和 canonical 媒体存在性等 MoviePilot 高层用例

8. 阶段更新日志

2026-08-31：建立计划

• 创建 Codex Goal，目标为 Agent 工具体系的 API 化重构和安全收口
• 基线同步到 v3@6ee47795629f
• 确认 82 个固定工具、48 个第一批迁移候选、16 个 parity 候选和 18 个原生保留工具
• 当前活动叶子为 L1；尚未修改生产代码

2026-08-31：L1 基线验证与 L2 启动

• 已核对最新 v3 基线、工具工厂、Agent 编排、Skill 中间件、MCP 入口、API Token 鉴权和策略注册表
• 已确认第一批 48 个 API 候选、第二批 16 个 parity 候选和原生保留边界；后续实测更正默认固定目录终态为 14 个
• 已冻结 API 网关必须透传 ToolPolicyContext、禁止任意 URL、保留确认/幂等/恢复和结果裁剪的设计约束
• 当前唯一活动叶子切换为 L2；下一步直接实现正式结构化 API 网关，不增加运行时切换

2026-08-31：L2.1 网关骨架完成

• 新增 app/agent/policy/api.py，冻结第一批 48 个和 parity 16 个 operation ID、固定 API 路由与策略元数据
• 新增 app/agent/tools/impl/api.py，提供 moviepilot_api(operation_id, path_params, query, body) 结构化合同
• 工具工厂已切换为统一新目录：默认移除替代业务工具并注入单一网关，不新增运行时开关
• 主 Agent、子 Agent、MCP 和 HTTP 工具管理器均走同一新目录；不保留旧业务工具对外或内部兼容入口
• 策略注册表已按 operation ID 分类未知、敏感、可恢复写入、破坏性写入和外部副作用
• 网关已从旧工具 owner 转发改为 operation ID 到固定 HTTP 方法/路径的 API 执行器，模型不能注入 URL、认证头或方法
• 已删除临时 app/agent/tools/legacy.py，并移除 MCP 同名工具 first-wins 兼容选择；重复名称由严格目录冲突机制处理
• Skill operation 范围改为默认拒绝：未加载声明 allowed-api-operations 的 Skill 时不能调用 moviepilot_api
• 敏感系统设置确认入口已迁移到 config.system.get operation，策略回执对 SECRET 结果整体脱敏
• 当前未完成：补齐 parity API 的真实业务端点、完成渠道用户到 API 用户身份映射、删除 64 个退出工具文件并迁移关联测试/Skill
• 验证：网关、Skill、策略、数据端口与 MCP 专项 63 passed；新增代码 compileall 通过

2026-08-31：最终目录决策确认

• 不增加 AGENT_API_GATEWAY_ENABLED、AGENT_COMPACT_TOOL_CATALOG_ENABLED 或其它运行时切换
• 不考虑 MCP 旧工具兼容；MCP、HTTP 工具管理器和 Agent 统一采用新 API 目录
• 旧业务工具代码的删除是本目标的必达项：先将行为迁移到 API operation handler，再删除对应 app/agent/tools/impl/* 文件、注册、测试和文档
• 网关不得实例化旧工具类；临时 legacy owner 文件已经删除，后续不再恢复

2026-08-31：L2 完成并进入 L3

• Web/WebAgent 数字用户 ID 才允许直接作为 API 身份；外部消息渠道即使用户 ID 为数字，也必须通过渠道绑定解析为有效 MoviePilot 用户
• API 执行器使用宿主签发的当前用户令牌，并通过模型不可控请求头透传会话、渠道和来源；不读取全局 API_TOKEN
• 系统设置元数据与脱敏、过滤规则校验与引用处理、插件管理投影已迁出 app/agent/tools/impl，进入对应 Application owner
• 新增 typed API：统一系统设置、自定义识别词、下载任务高级修改、过滤规则/规则组 CRUD、插件运行能力/持久化数据、斜杠命令执行
• parity operation 已切换到真实固定路由，不再使用 system/ruletest、插件页面或环境变量接口作为占位映射
• L2 状态更新为 VERIFIED，当前唯一活动叶子为 L3；下一步补齐推荐、目录配置等剩余语义差异并开始删除 64 个退出工具文件
• 验证：uv run --locked --no-sync python -m compileall -q app/agent app/application app/api/endpoints app/schemas 通过；Agent 网关/Skill/策略/数据端口/MCP 专项 63 passed

2026-08-31：纳入下载器与媒体服务器第三方 API Skill

• 对照 database-operation Skill、下载器 provider client、媒体服务器 provider client 和现有 API operation 完成边界评估
• 决定新增 downloader-operation 与 mediaserver-operation 两个领域 Skill，通过固定脚本读取本机配置并调用已配置第三方服务自身 API
• 两个 Skill 不仅替代既有低层 operation，还提供动态 capabilities 清单和 provider 扩展注册表，使 Agent 可按需使用任务文件/Tracker/Peer/队列、播放会话、观看状态、扫描和元数据刷新等高级能力
• 计划在 Skill 通过离线测试后移除 download.list、download.update、download.delete、downloaders.list 和 library.latest 等重复低层 Agent operation
• 保留 download.add、library.exists、下载/转移历史和订阅等 MoviePilot 高层 operation，避免削弱媒体身份、路径映射、持久化和恢复能力
• 不保留旧工具或 MCP 兼容入口；前端仍需使用的 REST 端点不在删除范围
• 当前活动叶子仍为 L6 原生工具收敛；L7 已加入 Goal，待 action 工具收口后实施

2026-08-31：L3 至 L6 完成

• 完成 59 个正式 operation：第一批 44 个、parity 15 个；模型不能注入 URL、method、认证头或 Token
• 将过滤规则、系统设置、插件管理/数据、音乐投影、下载任务和命令执行迁入对应 Application owner
• agent_task 合并 create/list/update/run/delete，persona 合并 list/switch/update；旧独立工具实现全部删除
• 主 Agent、子 Agent、CLI、MCP 和 HTTP 工具管理器统一消费同一严格目录，不再注册旧工具名
• 删除 77 个 app/agent/tools/impl 退役文件，其中 72 个工具模块和 5 个辅助模块
• 阶段验证：网关、策略、原生 action、流式活动和关联回归 218 passed

2026-08-31：L7 第三方服务 Skill 化完成

• 新增 downloader-operation Skill 与 mp-downloader.py 固定脚本，覆盖 qBittorrent、Transmission、rTorrent 的实例、能力发现、任务/文件/Tracker/Peer、队列、限速、标签、分类、位置和会话统计等动作
• 新增 mediaserver-operation Skill 与 mp-mediaserver.py 固定脚本，覆盖 Emby、Jellyfin、Plex、ZSpace、Ugreen、TrimeMedia、Navidrome 的实例、媒体库、条目、活动、播放会话、扫描和元数据刷新等动作
• 两个脚本只读取 MoviePilot 已配置实例，拒绝任意 URL/method/header/凭据参数，统一递归裁剪密码、Token、Cookie、API Key 和会话字段
• 从 Agent operation 目录删除 download.list、download.update、download.delete、downloaders.list 和 library.latest；保留前端 REST 端点与 MoviePilot 高层 download.add、library.exists、订阅和历史能力
• 阶段验证：provider Skill、网关移除项和内置 Skill 边界 33 passed

2026-08-31：L8 收口完成

• CLI scheduler list/run 已改用 scheduler.list 与 scheduler.run operation，不再调用已删除工具名
• 工具目录构造、Agent 图、HTTP/MCP direct 调用均强制唯一身份；同名插件/MCP 工具直接失败，不采用 first-wins
• docs/mcp-api.md、docs/cli.md、命令规则、内置 Skill 文档和 Schema 导出清单已同步新合同
• 宿主架构基线在 L8 首次更新为 917 个模块、7,671 条内部依赖边；L9 新增固定 API MCP 合同与外部服务工具 owner 后为 919 个模块、7,680 条内部依赖边，未新增 Application/Chain 到具体 Adapter 的直连
• 受影响 Python 文件通过 Ruff、compileall 和 Pylint --errors-only；Schema 导出、架构基线与 git diff --check 均通过
• 最终架构/OpenAPI/i18n/事件/package-root 回归 84 passed；Agent/MCP/CLI/Skill/架构大回归 1066 passed、插件与架构边界专项 124 passed、provider/gateway 专项 33 passed
• 完整锁定测试 uv run --locked --no-sync python tests/run.py 完成：7554 passed、9 skipped、2 failed
• 两个失败仅为 test_release_supply_chain.py::test_release_promotes_latest_only_after_both_versioned_images 与 test_resource_v3.py::test_v3_release_workflows_use_main_wiki_and_isolated_images；均已在未改动的 v3@6ee47795629f 干净 detached worktree 复现，属于本次重构前已有的发布工作流基线问题
• Agent 工具重构范围内没有遗留失败；L1-L8 全部退出，正式方案不保留旧工具、MCP 兼容或运行时切换开关
• 当前变更尚未提交或推送

2026-08-31：Skill/MCP 自描述合同与系统设置收口

• 下载器 24 个 provider action 加 instances.list / capabilities.list 两个发现 action、媒体服务器 17 个 provider action 加同样两个发现 action、MoviePilot API 203 个 operation 均从运行时合同生成完整英文参数说明；外部 MCP tools/list 保留相同 oneOf、必填、类型、默认值、枚举和跨字段约束
• 新增 admin-only database_operation MCP 工具，暴露 tables、schema、query、write 四个 action；内置 Agent 仍按需加载 database-operation Skill，不增加常驻业务工具
• 数据库 Skill 已覆盖 27 张 ORM 表、alembic_version 和全部字段基线；每张表均说明用途、适合查询的场景和写入边界，运行时仍以 tables / schema 实际结果为准
• Skill 文档生成器会对数据库说明与 ORM 元数据做双向缺项校验；新增、删除或改名表但未同步说明时生成直接失败，避免文档再次出现漏表或只有字段没有语义的问题
• 系统设置继续由 config.system.get/update 统一承载，不恢复旧配置工具；Skill 不再复制易漂移的 Settings / SystemConfigKey 全量清单，而是要求先动态发现 definition（声明类型、当前形状、敏感性、允许操作、列表匹配字段和持久化位置），再按精确键更新
• Settings 更新执行类型转换并持久化到 app.env；SystemConfigKey 通过配置服务写入数据库，保留插件 mutation 门禁、敏感值脱敏和配置变更事件
• app/agent/policy/resources/api_mcp_schema.json 明确为 OpenAPI + 固定 operation 合同生成的 MCP tools/list 制品，禁止手工维护；所有 operation、模型和字段必须具备具体英文说明，抽象占位文本或中文说明会由测试拒绝
• API 权限保持双层硬门禁：moviepilot_api 按 operation 的 required_role 在发起 HTTP 前拒绝非管理员，最终 FastAPI 端点继续用真实当前用户令牌执行 superuser/manage/user 级鉴权；下载器、媒体服务器、数据库外部工具整体为 admin-only
• 异步边界复核：内置 Skill 脚本经 asyncio subprocess 执行；外部服务/数据库 MCP 工具把同步脚本放入 downloader、mediaserver、db 分域线程池；moviepilot_api 使用异步 HTTP，不阻塞 Agent event loop
• 当前阶段进入最终验证：聚焦 Agent/Skill/MCP 回归、全量锁定测试、80% 固定覆盖率 CI、提交推送与远端终态确认

2026-08-31 至 2026-09-01：L9 全 API 面审计与真实调用验证

• 从当前 FastAPI OpenAPI 生成 375 个 HTTP 操作的完整清单；每个路由明确归类为 gateway、provider-skill、consolidated、alternate-auth-duplicate、transport_or_identity、stream_or_binary 或 ui_presentation，生成器对任何未归类端点直接失败
• moviepilot_api 扩展为 203 个稳定 operation，除 10 个音乐识别、探索、专辑、艺术家和缓存操作外，继续覆盖仪表盘、媒体发现与识别、站点全生命周期、订阅协作、存储维护、整理队列、工作流、种子缓存、数据库备份、规则与网络测试、插件运行管理、当前用户公开配置和使用统计；音乐支持艺术家到作品、作品到艺术家的双向浏览
• 新增 tests/test_agent_api_surface_audit.py，逐项校验 OpenAPI 清单、固定路由、生成审计文档、MCP oneOf、英文字段说明和 Skill operation 章节完全一致
• 将历史删除提交中的 72 个业务工具冻结为替代映射测试，逐项证明其 owner 是 203-operation API、下载器/媒体服务器 action 或统一 agent_task / persona 原生工具，并确认旧模块物理文件不存在
• 实际执行数据库脚本 tables / schema / SELECT 1、下载器与媒体服务器 instances / capabilities，并直接运行三个结构化 service tool；本机未配置 provider 实例时返回空实例而不是配置读取错误
• 通过临时本地 HTTP 服务实际执行 MoviePilotApiTool -> MoviePilotApiExecutor -> GET /api/v1/site/agent 完整链路，验证返回成功且普通用户投影不包含 cookie、API key、token 或 RSS 等认证字段
• 新增内置 Agent 私有 read_skill 工具，绕过普通工具 64 KiB 结果裁剪并单独限制 SKILL.md 主体为 512 KiB；工具同时返回全部辅助文件相对路径，超过上限时明确标记截断，真实内置 Skill 加载测试确认 203 个 operation 均可见且 truncated=false
• Skill 生成器同步 YAML allowed-api-operations 与正文目录，避免“文档有参数但运行时未授权”的双事实源漂移；MCP schema、Skill front matter、正文和注册表数量及集合完全一致
• 为站点优先级、插件目录和工作流路径 ID 等原先不精确的输入补充类型模型或端点约束；固定路由占位符与 path schema 名称、required 状态由测试逐项校验
• 受影响 Agent/Skill/MCP/OpenAPI/音乐/架构回归 247 passed；修复全量发现的工作流管理员门禁、插件分页默认值、模块命名治理、服务工具标签和 Schema 导出清单后，专项回归 40 passed
• 完整锁定测试最终通过：7,614 passed、9 skipped；覆盖率按 CI 相同的 8 分片采集并合并，Application 81.88%、Domain 81.01%，通过固定 80% 门禁
• 首次推送 6d4d7331d 的远端 Pylint 成功；Architecture Contract Gate 在 complexity v2 发现 plugin.py 从 999 行增长到 1007 行，合并三个短 import 后恢复到 999 行，本地两套复杂度门禁及 49 项相关回归均通过
• 第二次推送 28298c485 的远端 Pylint 成功；Architecture Contract Gate 识别出两处 Ruff 导入排序债务下降尚未固化，以及新增 service tool/Agent 投影端点未显式处理 mypy 既有基础设施告警
• 已对新增 Pydantic/ResponseAPIRouter 边界使用精确错误码抑制，补齐 service tool 的 ClassVar 与可选 selector 类型；未通过覆盖基线隐藏任何新增 mypy 错误
• Ruff 低水位由 576 降至 574，mypy 低水位由 9,606 降至 9,605；mypy、复杂度 v1/v2、并发、异步阻塞、TaskRegistry owner、服务定位和启动性能全部本地通过
• API/Skill/MCP/provider 专项 86 passed，架构与质量门禁专项 127 passed；生成器重建后工作区合同无额外差异
• 第三次推送 e5722ed98 的远端 Pylint 成功；Unit Tests 的功能分片与覆盖率分片均通过，但 Architecture Contract Gate 在文档合同测试中发现优化清单仍写着旧的 9,606 / 576 量化指标
• 已将 docs/refactor/optimization-checklist.md 同步为 9,605 / 574，本地 test_architecture_contract_baseline.py 与 test_architecture_baseline_cli.py 共 45 项通过，并确认 baseline.py --check-host 成功
• 当前活动叶子保持 L9；下一步提交文档指标修复，等待所有远端工作流终态成功后更新为 COMPLETE

2026-08-31：最终提交与远端门禁完成

• 文档合同修复提交 3106984dfc586aa171bbe9bd52307d19c6ef14f3 已推送到 origin/v3，本地 HEAD 与远端一致，工作区无未提交变更
• Unit Tests 工作流 33421990027 已终态成功：Architecture Contract Gate、4 个功能分片、8 个覆盖率分片和 Coverage Report 全部通过
• Pylint 工作流 33421989865 已终态成功；架构质量门禁、Ruff/mypy ratchet、复杂度、异步阻塞、Task owner、服务定位和启动性能检查均成功
• 全量 Agent API 面审计、Skill/MCP 参数合同、下载器/媒体服务器/数据库真实只读调用、音乐双向浏览能力和固定 80% 覆盖率要求均已完成
• 本次重构正式完成：旧 Agent 工具代码、旧 MCP 兼容路径和运行时切换开关均不保留；后续新增 API 必须同步注册表、Skill、MCP schema、审计清单和测试

2026-09-01：L10 查询 API 兼容分页与总数合同

• 重新开启父目标并进入 L10；当前基线 91e33277f 与 origin/v3 对齐，初始工作区干净
• 查询 API 按结果语义分为完整列表、原生分页或限量列表、结构化分页对象、统计或聚合对象；只有列表结果进入统一数量合同，统计、映射和时序对象不为形式统一而错误分页
• 原完整列表新增的 page / count 必须都是可选参数；两者都省略时不切片，继续返回端点原先的完整列表。显式传入任一参数才启用分页，缺失的 page 按 1、缺失的 count 按 50 解释
• REST 响应继续保持 Response.data 为原列表，禁止改成 {items,total} 等对象；总数和分页信息使用响应头及 Agent 网关附加元数据表达，避免破坏外部插件和既有客户端
• 对完整列表可报告切片前精确总数；对已经由第三方来源原生分页或限量、且上游没有提供总数的结果，只报告当前返回数量，不强制增加总数，也禁止把当前页数量伪装成全局总数
• 第一版由统一响应路由隐式注入分页参数并在序列化后切片；复核后确认这种实现虽然能生成查询参数，但端点签名不自描述，而且数据库列表仍会全量读取，因此不作为最终方案
• 当前正式方案由每个列表端点显式声明 page / count；框架 Response 仅用于写响应头，不会出现在 OpenAPI、MCP 或 Skill 输入中。已有第三方原生 page、count、limit 或 max_results 的接口保留其显式参数语义；当原生限量参数默认值为 None 时，省略所有窗口参数继续返回完整列表
• 用户、PassKey、活动订阅、Workflow、Site、站点用户数据和站点统计的筛选、稳定排序、LIMIT/OFFSET 与精确 COUNT 已下推到异步 SQLAlchemy 查询；状态、用户名、名称、触发类型、站点启用状态、站点 ID/域名和日期筛选均在分页前执行，避免空页和错误总数
• 纯内存、配置、缓存、文件系统或运行时目录仍可在响应边界按显式 page/count 切片；第三方原生分页且不返回总数的接口只报告当前页数量，不伪造总数
• REST 保持 data 原列表；X-Result-Count 报告本次返回数量，精确可知时增加 X-Total-Count，Agent 网关把这些响应头映射到附加 collection 对象。下载历史、订阅历史和插件目录已增加本地精确计数；外部媒体、音乐、推荐和搜索来源未提供总数时不输出 total_count
• OpenAPI 与 api_mcp_schema.json 已重新生成，英文 skills/moviepilot-api/SKILL.md 已同步显式参数；生成器会识别插件目录的既有 max_results，不会错误声称其默认返回全量
• 完整锁定测试已通过：4 个分片分别为 1620 passed, 3 skipped、1860 passed, 4 skipped、1917 passed、2248 passed, 2 skipped，合计 7645 passed, 9 skipped
• 覆盖率按 CI 相同的 8 分片采集并合并，Application 81.72%、Domain 81.01%，通过固定 80% 门禁；Ruff/mypy ratchet、严格 mypy、复杂度 v1/v2、并发、异步阻塞、TaskRegistry owner、服务定位、事件策略和启动性能门禁均通过
• 数据库 Oper 复用 literal_contains 新增 4 条内部依赖边，宿主快照从 7,684 更新为 7,688；没有新增 Application/Chain 到具体 Adapter 的直连或跨层依赖
• 生成器幂等校验通过，api_mcp_schema.json 与 skills/moviepilot-api/SKILL.md 重建前后哈希一致；受影响 Python 文件 Pylint 10.00/10，关键回归 207 passed

2026-09-01：L10 提交推送与远端门禁完成

• 实现提交 d512f528be351dabba0cf344c2e9d890bb93ea6f 已推送到 origin/v3，本地与远端提交一致
• Unit Tests 工作流 33457912749 已终态成功：Architecture Contract Gate、4 个功能分片、8 个覆盖率分片和 Coverage Report 全部通过
• Pylint 工作流 33457912735 已终态成功；变更文件质量检查与完整建议报告均成功
• L10 正式完成：集合端点显式声明 page/count，数据库查询在 SQL 层完成筛选、稳定排序、分页与同条件精确计数；不传新增参数继续返回旧全量列表，外部来源没有总数时不伪造
• MoviePilot Agent 工具体系重构父目标至此全部完成，后续查询端点必须继续维护 REST、OpenAPI、MCP、Skill 和数据库查询合同的一致性

2026-09-01：集合总数截断可见性修复

• Web Agent 实际调用 subscription.list 时未传分页，完整订阅列表超过通用工具结果 64KB 上限；此前网关把 collection 追加在 data 之后，截断预览只保留开头条目，导致 Agent 看不到已经由 API 返回的精确 collection.total_count，继而错误回退到数据库统计
• 网关现将 collection 放在 data 前面，使 X-Total-Count 投影的精确总数在大结果预览中仍优先可见；列表响应和 REST data 结构均未改变
• 核心提示、MCP oneOf、moviepilot-api Skill 和文档统一要求：数量或摘要查询使用最小分页窗口；兼容分页传 page=1,count=1 并读取 collection.total_count，不得因为条目或工具预览截断而改查数据库
• moviepilot-api Skill 版本提升到 24；新增超大订阅结果回归，验证截断预览中总数早于 data 出现
• 完整锁定测试已通过：4 个分片分别为 1620 passed, 3 skipped、1860 passed, 4 skipped、1917 passed、2250 passed, 2 skipped，合计 7647 passed, 9 skipped；变更文件 Pylint 为 10.00/10，Ruff、生成物幂等与 git diff --check 均通过
• 当前未托管后端使用的 API 身份与工作区 CLI 配置不一致，真实 CLI 调用被既有 API key 校验拒绝；本轮未擅自重启正在运行的服务，运行进程需在代码部署并重载后再做在线会话复验

2026-09-01：啰嗦模式 API 主要参数展示修复

• 旧领域工具各自通过 get_tool_message() 展示目标和主要参数；收敛为 moviepilot_api 后，该方法只展示 operation_id，导致 Web Agent 与通知渠道在啰嗦模式下失去 path_params、query 和 body 的调用上下文
• moviepilot_api 现按路径、查询、请求体顺序生成最多 320 字符的主要参数摘要；空参数桶不展示，工具执行与 API 输入结构保持不变
• 参数摘要统一复用宿主递归脱敏器，设置凭据、密码、Cookie、Token 与 API key 等仅显示 ***，避免为了恢复可观察性而泄露敏感输入
• 复用脱敏器新增 1 条 Agent 同域内部依赖边，宿主架构快照由 7,688 更新为 7,689；模块总数和跨层边界均未变化
• 后续将 Skill、子 Agent 和活动记录等中间件统一接入运行时啰嗦模式判断，新增 app.agent.callback -> app.runtime.settings 依赖，宿主架构快照由 7,689 更新为 7,690；该方向符合 Agent 到 Runtime 的既定边界
• 中间件 import 排序修复同时消除了 2 条 Ruff I001 历史诊断，低水位由 571 降至 569，并已同步质量指标文档
• 新增 Web Agent 实际流式回调回归和设置凭据脱敏回归；扩展 Agent/API/流式专项 487 passed，完整锁定测试 4 个分片分别为 1620 passed, 3 skipped、1860 passed, 4 skipped、1917 passed、2253 passed, 2 skipped，合计 7650 passed, 9 skipped；Ruff、Pylint 10.00/10 和全量 mypy ratchet 均通过

本文件作为本次重构的持续记录，保留阶段状态、实际变更、验证结果、提交状态与已知基线边界。